diff --git a/.env.example b/.env.example
index 06d43070c..e0a07236e 100644
--- a/.env.example
+++ b/.env.example
@@ -5,16 +5,17 @@
 # ANTHROPIC_API_KEY=sk-ant-xxx
 # OPENAI_API_KEY=sk-xxx
 # GEMINI_API_KEY=xxx
-# CEREBRAS_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/workflows/nightly.yml b/.github/workflows/nightly.yml
new file mode 100644
index 000000000..321e35ccd
--- /dev/null
+++ b/.github/workflows/nightly.yml
@@ -0,0 +1,204 @@
+name: Nightly Build
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  create-tag:
+    name: Create Git Tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
+      changelog: ${{ steps.version.outputs.changelog }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Generate and push tag
+        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
+            TAG="v0.0.0-nightly.${DATE}.${SHA}"
+          else
+            TAG="${BASE_VERSION}-nightly.${DATE}.${SHA}"
+          fi
+          VERSION=$TAG
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "Tag $TAG already exists, reusing existing tag"
+          else
+            git tag -a "$TAG" -m "Nightly build $VERSION"
+          fi
+          git push origin "$TAG"
+          
+          COMPARE_URL="https://github.com/${{ github.repository }}/commits/${TAG}"
+          if [ -n "$BASE_VERSION" ] && [ "$BASE_VERSION" != "v0.0.0" ]; then
+            COMPARE_URL="https://github.com/${{ github.repository }}/compare/${BASE_VERSION}...${TAG}"
+          fi
+          echo "changelog=**Full Changelog**: $COMPARE_URL" >> "$GITHUB_OUTPUT"
+          
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
+  release:
+    name: GoReleaser Release
+    needs: create-tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - name: Checkout tag
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.create-tag.outputs.tag }}
+
+      - 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@v4
+        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
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        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 }}
+          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 }}
+
+  update-rolling:
+    name: Update Rolling Nightly
+    needs: [create-tag, release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Update nightly release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ needs.create-tag.outputs.tag }}
+          TITLE: ${{ needs.create-tag.outputs.version }}
+        run: |
+          CHANGELOG='${{ needs.create-tag.outputs.changelog }}'
+          NOTES=$(cat <<EOF
+          Nightly build for **${TITLE}**
+          
+          This is an automated build and may be unstable. Use with caution.
+          
+          ${CHANGELOG}
+          EOF
+          )
+          
+          # Download assets from the newly created release if it exists,
+          # otherwise fall back to using locally built dist/ artifacts.
+          mkdir -p build
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Downloading assets from GitHub release for $TAG..."
+            gh release download "$TAG" --dir build
+          else
+            echo "GitHub release for $TAG not found; falling back to local dist/ artifacts..."
+            if [ -d "dist" ]; then
+              cp -R dist/* build/
+            else
+              echo "Error: no GitHub release for $TAG and no local dist/ directory found." >&2
+              exit 1
+            fi
+          fi
+          
+          # Delete existing nightly release and tag to avoid conflicts
+          echo "Deleting existing nightly release and tag..."
+          gh release delete nightly --cleanup-tag -y || true
+          git push origin :refs/tags/nightly || true
+          
+          gh release create nightly \
+            --title "Nightly Build" \
+            --notes "$NOTES" \
+            --target "${{ github.sha }}" \
+            --prerelease \
+            build/*
+
+          echo "Cleaning up old nightly releases (keeping only the most recent)..."
+          gh release list --limit 100 --json tagName -q '.[].tagName | select(contains("-nightly."))' | tail -n +2 | while read -r old_tag; do
+            if [ -n "$old_tag" ] && [ "$old_tag" != "$TAG" ]; then
+              echo "Deleting old nightly release: $old_tag"
+              gh release delete "$old_tag" --cleanup-tag -y || true
+            fi
+          done
+          
+          echo "Cleaning up old 'vX.X.X-nightly...' Docker images on GHCR..."
+          OWNER="${{ github.repository_owner }}"
+          PACKAGE_NAME="${{ github.event.repository.name }}"
+          
+          # Check if owner is an organization or user
+          ORG_TEST=$(gh api -H "Accept: application/vnd.github+json" /orgs/$OWNER 2>/dev/null || true)
+          if echo "$ORG_TEST" | grep -q '"login"'; then
+            ACCOUNT_TYPE="orgs"
+          else
+            ACCOUNT_TYPE="users"
+          fi
+          
+          PACKAGE_URL="/${ACCOUNT_TYPE}/${OWNER}/packages/container/${PACKAGE_NAME}/versions"
+          OLD_NIGHTLY_VERSIONS=$(gh api --paginate -H "Accept: application/vnd.github+json" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            "$PACKAGE_URL" \
+            --jq ". | map(select(any(.metadata.container.tags[]; contains(\"-nightly.\") and (. != \"nightly\") and (. != \"$TAG\")))) | .[].id" 2>/dev/null || true)
+            
+          for version_id in $OLD_NIGHTLY_VERSIONS; do
+            if [ -n "$version_id" ]; then
+              echo "Deleting Docker image version ID: $version_id"
+              gh api -X DELETE -H "Accept: application/vnd.github+json" \
+                -H "X-GitHub-Api-Version: 2022-11-28" \
+                "/${ACCOUNT_TYPE}/${OWNER}/packages/container/${PACKAGE_NAME}/versions/$version_id" || true
+            fi
+          done
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index be1c10c52..1e9a7919a 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -24,6 +24,25 @@ jobs:
         with:
           version: v2.10.1
 
+  vuln_check:
+    name: Security Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Run Govulncheck
+        uses: golang/govulncheck-action@v1
+        with:
+          go-package: ./...
+
   test:
     name: Tests
     runs-on: ubuntu-latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 786c893ef..4a584773d 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,6 +65,14 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        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
 
@@ -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 ce30d749e..61fe494ca 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,7 +10,7 @@ build/
 *.out
 /picoclaw
 /picoclaw-test
-cmd/picoclaw/workspace
+cmd/**/workspace
 
 # Picoclaw specific
 
@@ -38,9 +38,21 @@ ralph/
 .ralph/
 tasks/
 
+# Plans
+docs/plans/
+
 # Editors
 .vscode/
 .idea/
 
 # Added by goreleaser init:
 dist/
+*.vite/
+
+# Windows Application Icon/Resource
+*.syso
+
+# Keep embedded backend dist directory placeholder in VCS
+!web/backend/dist/
+web/backend/dist/*
+!web/backend/dist/.gitkeep
diff --git a/.golangci.yaml b/.golangci.yaml
index d45d69e67..ea3107ec8 100644
--- a/.golangci.yaml
+++ b/.golangci.yaml
@@ -7,7 +7,6 @@ linters:
     - containedctx
     - cyclop
     - depguard
-    - dupl
     - dupword
     - err113
     - exhaustruct
@@ -28,9 +27,7 @@ linters:
     - wsl_v5
 
     # TODO: Disabled, because they are failing at the moment, we should fix them and enable (step by step)
-    - bodyclose
     - contextcheck
-    - dogsled
     - embeddedstructfieldcheck
     - errcheck
     - errchkjson
@@ -45,32 +42,24 @@ linters:
     - gocritic
     - gocyclo
     - godox
-    - goprintffuncname
     - gosec
     - ineffassign
     - lll
     - maintidx
-    - misspell
     - mnd
     - modernize
-    - nakedret
     - nestif
     - nilnil
     - paralleltest
     - perfsprint
-    - prealloc
-    - predeclared
     - revive
     - staticcheck
     - tagalign
     - testifylint
     - thelper
     - unparam
-    - unused
     - usestdlibvars
     - usetesting
-    - wastedassign
-    - whitespace
   settings:
     errcheck:
       check-type-assertions: true
@@ -152,6 +141,9 @@ linters:
           - gocognit
           - gocyclo
         path: _test\.go$
+      - linters:
+          - nolintlint
+        path: 'pkg/tools/(i2c\.go|spi\.go)$'
 
 issues:
   max-issues-per-linter: 0
diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index 2c47f7d86..654ad6ae6 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -5,7 +5,10 @@ version: 2
 before:
   hooks:
     - go mod tidy
-    - go generate ./cmd/picoclaw
+    - 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 web/backend/winres/winres.json --out web/backend/rsrc --product-version={{ .Version }} --file-version={{ .Version }}
 
 builds:
   - id: picoclaw
@@ -15,10 +18,10 @@ builds:
       - stdjson
     ldflags:
       - -s -w
-      - -X main.version={{ .Version }}
-      - -X main.gitCommit={{ .ShortCommit }}
-      - -X main.buildTime={{ .Date }}
-      - -X main.goVersion={{ .Env.GOVERSION }}
+      - -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 }}
     goos:
       - linux
       - windows
@@ -28,30 +31,117 @@ builds:
       - amd64
       - arm64
       - riscv64
-      - s390x
-      - mips64
+      - loong64
       - arm
+      - s390x
+      - mipsle
+    goarm:
+      - "6"
+      - "7"
+    gomips:
+      - softfloat
     main: ./cmd/picoclaw
     ignore:
       - goos: windows
         goarch: arm
 
+  - id: picoclaw-launcher
+    binary: picoclaw-launcher
+    env:
+      - CGO_ENABLED=0
+    tags:
+      - stdjson
+    ldflags:
+      - -s -w
+    goos:
+      - linux
+      - windows
+      - darwin
+      - freebsd
+    goarch:
+      - amd64
+      - arm64
+      - riscv64
+      - loong64
+      - arm
+      - s390x
+      - mipsle
+    goarm:
+      - "6"
+      - "7"
+    gomips:
+      - softfloat
+    main: ./web/backend
+    ignore:
+      - goos: windows
+        goarch: arm
+
+  - id: picoclaw-launcher-tui
+    binary: picoclaw-launcher-tui
+    env:
+      - CGO_ENABLED=0
+    tags:
+      - stdjson
+    ldflags:
+      - -s -w
+    goos:
+      - linux
+      - windows
+      - darwin
+      - freebsd
+    goarch:
+      - amd64
+      - arm64
+      - riscv64
+      - loong64
+      - arm
+      - s390x
+      - mipsle
+    goarm:
+      - "6"
+      - "7"
+    gomips:
+      - softfloat
+    main: ./cmd/picoclaw-launcher-tui
+    ignore:
+      - goos: windows
+        goarch: arm
+
 dockers_v2:
   - id: picoclaw
-    dockerfile: Dockerfile.goreleaser
+    dockerfile: docker/Dockerfile.goreleaser
+    extra_files:
+      - docker/entrypoint.sh
     ids:
       - picoclaw
     images:
       - "ghcr.io/{{ .Env.GITHUB_REPOSITORY_OWNER }}/picoclaw"
-      - "docker.io/{{ .Env.DOCKERHUB_IMAGE_NAME }}"
+      - '{{ if not (isEnvSet "NIGHTLY_BUILD") }}docker.io/{{ .Env.DOCKERHUB_IMAGE_NAME }}{{ end }}'
     tags:
       - "{{ .Tag }}"
-      - "latest"
+      - '{{ if isEnvSet "NIGHTLY_BUILD" }}nightly{{ else }}latest{{ 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`.
@@ -67,6 +157,34 @@ archives:
       - goos: windows
         formats: [zip]
 
+nfpms:
+  - id: picoclaw
+    ids:
+      - picoclaw
+      - picoclaw-launcher
+      - picoclaw-launcher-tui
+    package_name: picoclaw
+    file_name_template: >-
+      {{ .PackageName }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "arm64" }}aarch64
+      {{- else if eq .Arch "arm" }}armv{{ .Arm }}
+      {{- else }}{{ .Arch }}{{ end }}
+    vendor: picoclaw
+    homepage: https://github.com/{{ .Env.GITHUB_REPOSITORY_OWNER }}/picoclaw
+    maintainer: picoclaw contributors
+    description: picoclaw - a tool for managing and running tasks
+    license: MIT
+    formats:
+      - 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
   filters:
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 29e2fc964..955c1c966 100644
--- a/Makefile
+++ b/Makefile
@@ -11,12 +11,35 @@ 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}')
-LDFLAGS=-ldflags "-X main.version=$(VERSION) -X main.gitCommit=$(GIT_COMMIT) -X main.buildTime=$(BUILD_TIME) -X main.goVersion=$(GO_VERSION) -s -w"
+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"
 
 # Go variables
-GO?=go
+GO?=CGO_ENABLED=0 go
 GOFLAGS?=-v -tags stdjson
 
+# 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
 
@@ -43,10 +66,14 @@ ifeq ($(UNAME_S),Linux)
 		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
@@ -84,14 +111,74 @@ build: generate
 	@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
+	@$(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=linux GOARCH=mipsle GOMIPS=softfloat $(GO) build -tags whatsapp_native $(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 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)
+	@echo "Build complete"
+##	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)
+
+## build-linux-arm: Build for Linux ARMv7 (e.g. Raspberry Pi Zero 2 W 32-bit)
+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)
+	@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)
+	@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 $(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)"
+
 ## build-all: Build picoclaw for all platforms
 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=mipsle GOMIPS=softfloat $(GO) build $(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 $(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)
 	@echo "All builds complete"
@@ -129,11 +216,11 @@ clean:
 	@echo "Clean complete"
 
 ## vet: Run go vet for static analysis
-vet:
+vet: generate
 	@$(GO) vet ./...
 
 ## test: Test Go code
-test:
+test: generate
 	@$(GO) test ./...
 
 ## fmt: Format Go code
@@ -144,6 +231,10 @@ fmt:
 lint:
 	@$(GOLANGCI_LINT) run
 
+## fix: Fix linting issues
+fix:
+	@$(GOLANGCI_LINT) run --fix
+
 ## deps: Download dependencies
 deps:
 	@$(GO) mod download
@@ -161,6 +252,44 @@ 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
+
 ## help: Show this help message
 help:
 	@echo "picoclaw Makefile"
@@ -169,13 +298,15 @@ help:
 	@echo "  make [target]"
 	@echo ""
 	@echo "Targets:"
-	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/## /  /'
+	@grep -E '^## ' $(MAKEFILE_LIST) | sort | awk -F': ' '{printf "  %-16s %s\n", substr($$1, 4), $$2}'
 	@echo ""
 	@echo "Examples:"
 	@echo "  make build              # Build for current platform"
 	@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 d09276c27..08a1926b6 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -7,7 +7,7 @@
 
   <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/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V-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>
@@ -65,7 +65,7 @@
 
 ⚡️ **Démarrage Éclair** : Temps de démarrage 400X plus rapide, boot en 1 seconde même sur un cœur unique à 0,6 GHz.
 
-🌍 **Véritable Portabilité** : Un seul binaire autonome pour RISC-V, ARM et x86. Un clic et c'est parti !
+🌍 **Véritable Portabilité** : Un seul binaire autonome pour RISC-V, ARM, MIPS et x86. Un clic et c'est parti !
 
 🤖 **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.
 
@@ -164,39 +164,43 @@ Vous pouvez également exécuter PicoClaw avec Docker Compose sans rien installe
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Configurez vos clés API
-cp config/config.example.json config/config.json
-vim config/config.json      # Configurez DISCORD_BOT_TOKEN, clés API, etc.
+# 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.
 
-# 3. Compiler & Démarrer
-docker compose --profile gateway up -d
+# 3. Configurez vos clés API
+vim docker/data/config.json   # Clés API du fournisseur, tokens de bot, 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 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`.
 
+```bash
+# 5. Voir les logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. Voir les logs
-docker compose logs -f picoclaw-gateway
-
-# 5. Arrêter
-docker compose --profile gateway down
+# 6. Arrêter
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Mode Agent (exécution unique)
 
 ```bash
 # Poser une question
-docker compose run --rm picoclaw-agent -m "Combien font 2+2 ?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Combien font 2+2 ?"
 
 # Mode interactif
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Recompiler
+### Mettre à jour
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Démarrage Rapide
@@ -221,12 +225,13 @@ picoclaw onboard
       "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": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "channels": {
@@ -252,6 +257,9 @@ picoclaw onboard
 }
 ```
 
+> **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)
@@ -280,7 +288,7 @@ Discutez avec votre PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom
 | **QQ**       | Facile (AppID + AppSecret)             |
 | **DingTalk** | Moyen (identifiants de l'application)  |
 | **LINE**     | Moyen (identifiants + URL de webhook)  |
-| **WeCom**    | Moyen (CorpID + configuration webhook) |
+| **WeCom AI Bot** | Moyen (Token + clé AES)            |
 
 <details>
 <summary><b>Telegram</b> (Recommandé)</summary>
@@ -448,8 +456,6 @@ picoclaw gateway
       "enabled": true,
       "channel_secret": "VOTRE_CHANNEL_SECRET",
       "channel_access_token": "VOTRE_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
       "webhook_path": "/webhook/line",
       "allow_from": []
     }
@@ -462,12 +468,14 @@ picoclaw gateway
 LINE exige HTTPS pour les webhooks. Utilisez un reverse proxy ou un tunnel :
 
 ```bash
-# Exemple avec ngrok
-ngrok http 18791
+# 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
@@ -476,19 +484,20 @@ 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** : Ajoutez `ports: ["18791:18791"]` au service `picoclaw-gateway` pour exposer le port du webhook.
+> **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 :
+PicoClaw prend en charge trois 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
+**Option 1 : WeCom Bot (Robot)** - 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 Intelligent)** - Bot IA officiel, réponses en streaming, prend en charge groupe et privé
 
-Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour des instructions détaillées.
+Voir le [Guide de Configuration WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) pour des instructions détaillées.
 
 **Configuration Rapide - WeCom Bot :**
 
@@ -507,8 +516,6 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
       "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_host": "0.0.0.0",
-      "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": []
     }
@@ -527,7 +534,7 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
 **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:18792/webhook/wecom-app`
+* Définissez l'URL sur `http://your-server:18790/webhook/wecom-app`
 * Générez le **Token** et l'**EncodingAESKey**
 
 **3. Configurer**
@@ -542,8 +549,6 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
       "agent_id": 1000002,
       "token": "YOUR_TOKEN",
       "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": []
     }
@@ -557,7 +562,40 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
 picoclaw gateway
 ```
 
-> **Note** : WeCom App nécessite l'ouverture du port 18792 pour les callbacks webhook. Utilisez un proxy inverse pour HTTPS en production.
+> **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.
+
+**Configuration Rapide - WeCom AI Bot :**
+
+**1. Créer un AI Bot**
+
+* Accédez à la Console d'Administration WeCom → Gestion des Applications → AI Bot
+* Configurez l'URL de callback : `http://your-server:18791/webhook/wecom-aibot`
+* Copiez le **Token** et générez l'**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": "Bonjour ! Comment puis-je vous aider ?"
+    }
+  }
+}
+```
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+> **Note** : WeCom AI Bot utilise le protocole pull en streaming — pas de problème de timeout. Les tâches longues (>5,5 min) basculent automatiquement vers la livraison via `response_url`.
 
 </details>
 
@@ -571,6 +609,31 @@ Connectez PicoClaw au Réseau Social d'Agents simplement en envoyant un seul mes
 
 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`) :
@@ -764,7 +827,7 @@ Le sous-agent a accès aux outils (message, web_search, etc.) et peut communique
 ### Fournisseurs
 
 > [!NOTE]
-> Groq fournit la transcription vocale gratuite via Whisper. Si configuré, les messages vocaux Telegram seront automatiquement transcrits.
+> 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.
 
 | Fournisseur              | Utilisation                              | Obtenir une Clé API                                    |
 | ------------------------ | ---------------------------------------- | ------------------------------------------------------ |
@@ -979,6 +1042,17 @@ Cette conception permet également le **support multi-agent** avec une sélectio
 ```
 > 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 :
diff --git a/README.ja.md b/README.ja.md
index 67eccddc2..c4c5b27a0 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -8,7 +8,7 @@
 
 <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/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V-blue" alt="Hardware">
 <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
 </p>
 
@@ -49,7 +49,7 @@
 
 ⚡️ **超高速**: 起動時間 400 倍高速、0.6GHz シングルコアでも 1 秒で起動。
 
-🌍 **真のポータビリティ**: RISC-V、ARM、x86 対応の単一バイナリ。ワンクリックで Go！
+🌍 **真のポータビリティ**: RISC-V、ARM、MIPS、x86 対応の単一バイナリ。ワンクリックで Go！
 
 🤖 **AI ブートストラップ**: 自律的な Go ネイティブ実装 — コアの 95% が AI 生成、人間によるレビュー付き。
 
@@ -126,39 +126,43 @@ Docker Compose を使えば、ローカルにインストールせずに PicoCla
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. API キーを設定
-cp config/config.example.json config/config.json
-vim config/config.json      # DISCORD_BOT_TOKEN, プロバイダーの API キーを設定
+# 2. 初回起動 — docker/data/config.json を自動生成して終了
+docker compose -f docker/docker-compose.yml --profile gateway up
+# コンテナが "First-run setup complete." を表示して停止します。
 
-# 3. ビルドと起動
-docker compose --profile gateway up -d
+# 3. API キーを設定
+vim docker/data/config.json   # プロバイダー API キー、Bot トークンなどを設定
+
+# 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
 
-# 4. ログ確認
-docker compose logs -f picoclaw-gateway
-
-# 5. 停止
-docker compose --profile gateway down
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Agent モード（ワンショット）
 
 ```bash
 # 質問を投げる
-docker compose run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
 
 # インタラクティブモード
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### リビルド
+### アップデート
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 クイックスタート（ネイティブ）
@@ -183,12 +187,13 @@ picoclaw onboard
       "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": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "channels": {
@@ -221,6 +226,9 @@ picoclaw onboard
 }
 ```
 
+> **新機能**: `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)
@@ -249,7 +257,7 @@ Telegram、Discord、QQ、DingTalk、LINE、WeCom で PicoClaw と会話でき
 | **QQ** | 簡単（AppID + AppSecret） |
 | **DingTalk** | 普通（アプリ認証情報） |
 | **LINE** | 普通（認証情報 + Webhook URL） |
-| **WeCom** | 普通（CorpID + Webhook設定） |
+| **WeCom AI Bot** | 普通（Token + AES キー） |
 
 <details>
 <summary><b>Telegram</b>（推奨）</summary>
@@ -413,8 +421,6 @@ picoclaw gateway
       "enabled": true,
       "channel_secret": "YOUR_CHANNEL_SECRET",
       "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
       "webhook_path": "/webhook/line",
       "allow_from": []
     }
@@ -428,11 +434,13 @@ LINE の Webhook には HTTPS が必要です。リバースプロキシまた
 
 ```bash
 # ngrok の例
-ngrok http 18791
+ngrok http 18790
 ```
 
 LINE Developers Console で Webhook URL を `https://あなたのドメイン/webhook/line` に設定し、**Webhook の利用** を有効にしてください。
 
+> **注意**: LINE の Webhook は共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は Gateway のポートを公開するか、リバースプロキシを設定してください。
+
 **4. 起動**
 
 ```bash
@@ -441,19 +449,20 @@ picoclaw gateway
 
 > グループチャットでは @メンション時のみ応答します。返信は元メッセージを引用する形式です。
 
-> **Docker Compose**: `picoclaw-gateway` サービスに `ports: ["18791:18791"]` を追加して Webhook ポートを公開してください。
+> **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 統合をサポートしています：
+PicoClaw は3種類の WeCom 統合をサポートしています：
 
-**オプション1: WeCom Bot (智能ロボット)** - 簡単な設定、グループチャット対応
-**オプション2: WeCom App (自作アプリ)** - より多機能、アクティブメッセージング対応
+**オプション1: WeCom Bot (ロボット)** - 簡単な設定、グループチャット対応
+**オプション2: WeCom App (カスタムアプリ)** - より多機能、アクティブメッセージング対応、プライベートチャットのみ
+**オプション3: WeCom AI Bot (スマートボット)** - 公式 AI Bot、ストリーミング返信、グループ・プライベート両対応
 
-詳細な設定手順は [WeCom App Configuration Guide](docs/wecom-app-configuration.md) を参照してください。
+詳細な設定手順は [WeCom AI Bot Configuration Guide](docs/channels/wecom/wecom_aibot/README.zh.md) を参照してください。
 
 **クイックセットアップ - WeCom Bot:**
 
@@ -472,13 +481,13 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
       "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_host": "0.0.0.0",
-      "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": []
     }
   }
 }
+
+> **注意**: WeCom Bot の Webhook 受信は共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は Gateway のポートを公開するか、HTTPS 用のリバースプロキシを設定してください。
 ```
 
 **クイックセットアップ - WeCom App:**
@@ -492,7 +501,7 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
 **2. メッセージ受信を設定**
 
 * アプリ詳細で "メッセージを受信" → "APIを設定" をクリック
-* URL を `http://your-server:18792/webhook/wecom-app` に設定
+* URL を `http://your-server:18790/webhook/wecom-app` に設定
 * **Token** と **EncodingAESKey** を生成
 
 **3. 設定**
@@ -507,8 +516,6 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
       "agent_id": 1000002,
       "token": "YOUR_TOKEN",
       "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": []
     }
@@ -522,7 +529,40 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
 picoclaw gateway
 ```
 
-> **注意**: WeCom App は Webhook コールバック用にポート 18792 を開放する必要があります。本番環境では HTTPS 用のリバースプロキシを使用してください。
+> **注意**: WeCom App の Webhook コールバックは共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は HTTPS 用のリバースプロキシを設定してください。
+
+**クイックセットアップ - WeCom AI Bot:**
+
+**1. AI Bot を作成**
+
+* WeCom 管理コンソール → アプリ管理 → AI Bot
+* コールバック URL を設定: `http://your-server:18791/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": "こんにちは！何かお手伝いできますか？"
+    }
+  }
+}
+```
+
+**3. 起動**
+
+```bash
+picoclaw gateway
+```
+
+> **注意**: WeCom AI Bot はストリーミングプルプロトコルを使用 — 返信タイムアウトの心配なし。長時間タスク（>30秒）は自動的に `response_url` によるプッシュ配信に切り替わります。
 
 </details>
 
@@ -530,6 +570,31 @@ picoclaw gateway
 
 設定ファイル: `~/.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`）にデータを保存します：
@@ -720,7 +785,7 @@ HEARTBEAT_OK 応答         ユーザーが直接結果を受け取る
 ### プロバイダー
 
 > [!NOTE]
-> Groq は Whisper による無料の音声文字起こしを提供しています。設定すると、Telegram の音声メッセージが自動的に文字起こしされます。
+> Groq は Whisper による無料の音声文字起こしを提供しています。設定すると、あらゆるチャンネルからの音声メッセージがエージェントレベルで自動的に文字起こしされます。
 
 | プロバイダー | 用途 | API キー取得先 |
 | --- | --- | --- |
@@ -918,6 +983,17 @@ HEARTBEAT_OK 応答         ユーザーが直接結果を受け取る
 ```
 > 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 が自動的にラウンドロビンで分散します：
diff --git a/README.md b/README.md
index 84d92115b..5cf9f6143 100644
--- a/README.md
+++ b/README.md
@@ -7,11 +7,14 @@
 
   <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/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V-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>
+    <br>
+    <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**
@@ -51,7 +54,7 @@
 
 ## 📢 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-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](ROADMAP.md) —we can’t wait to have you on board!
 
 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.
@@ -66,7 +69,7 @@
 
 ⚡️ **Lightning Fast**: 400X Faster startup time, boot in 1 second even in 0.6GHz single core.
 
-🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, and x86, One-click to Go!
+🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, MIPS, and x86, One-click to Go!
 
 🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.
 
@@ -151,10 +154,15 @@ make build
 # 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
 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.
+
 ## 🐳 Docker Compose
 
 You can also run PicoClaw using Docker Compose without installing anything locally.
@@ -164,39 +172,43 @@ You can also run PicoClaw using Docker Compose without installing anything local
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Set your API keys
-cp config/config.example.json config/config.json
-vim config/config.json      # Set DISCORD_BOT_TOKEN, API keys, etc.
+# 2. First run — auto-generates docker/data/config.json then exits
+docker compose -f docker/docker-compose.yml --profile gateway up
+# The container prints "First-run setup complete." and stops.
 
-# 3. Build & Start
-docker compose --profile gateway up -d
+# 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
 
-# 4. Check logs
-docker compose logs -f picoclaw-gateway
-
-# 5. Stop
-docker compose --profile gateway down
+# 6. Stop
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Agent Mode (One-shot)
 
 ```bash
 # Ask a question
-docker compose run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
 
 # Interactive mode
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Rebuild
+### Update
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Quick Start
@@ -204,7 +216,7 @@ docker compose --profile gateway up -d
 > [!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.
+> Web Search is **optional** - get free [Tavily API](https://tavily.com) (1000 free queries/month), [SearXNG](https://github.com/searxng/searxng) (free, self-hosted) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month) or use built-in auto fallback.
 
 **1. Initialize**
 
@@ -219,7 +231,7 @@ picoclaw onboard
   "agents": {
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
-      "model": "gpt4",
+      "model_name": "gpt4",
       "max_tokens": 8192,
       "temperature": 0.7,
       "max_tool_iterations": 20
@@ -229,7 +241,8 @@ picoclaw onboard
     {
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
-      "api_key": "your-api-key"
+      "api_key": "your-api-key",
+      "request_timeout": 300
     },
     {
       "model_name": "claude-sonnet-4.6",
@@ -252,6 +265,16 @@ picoclaw onboard
       "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
       }
     }
   }
@@ -259,11 +282,17 @@ picoclaw onboard
 ```
 
 > **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)
+* **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.
 
@@ -279,16 +308,20 @@ That's it! You have a working AI assistant in 2 minutes.
 
 ## 💬 Chat Apps
 
-Talk to your picoclaw through Telegram, Discord, DingTalk, LINE, or WeCom
+Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, 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) |
+| **Matrix**   | Medium (homeserver + bot access token) |
 | **QQ**       | Easy (AppID + AppSecret)           |
 | **DingTalk** | Medium (app credentials)           |
 | **LINE**     | Medium (credentials + webhook URL) |
-| **WeCom**    | Medium (CorpID + webhook setup)    |
+| **WeCom AI Bot** | Medium (Token + AES key)       |
 
 <details>
 <summary><b>Telegram</b> (Recommended)</summary>
@@ -321,6 +354,13 @@ Talk to your picoclaw through Telegram, Discord, DingTalk, LINE, or WeCom
 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`) 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.
+
 </details>
 
 <details>
@@ -349,8 +389,7 @@ picoclaw gateway
     "discord": {
       "enabled": true,
       "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"],
-      "mention_only": false
+      "allow_from": ["YOUR_USER_ID"]
     }
   }
 }
@@ -363,9 +402,31 @@ picoclaw gateway
 * Bot Permissions: `Send Messages`, `Read Message History`
 * Open the generated invite URL and add the bot to your server
 
-**Optional: Mention-only mode**
+**Optional: Group trigger mode**
 
-Set `"mention_only": true` to make the bot respond only when @-mentioned. Useful for shared servers where you want the bot to respond only when explicitly called.
+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**
 
@@ -375,6 +436,33 @@ 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>
 
@@ -441,6 +529,40 @@ picoclaw gateway
 ```
 </details>
 
+<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](docs/channels/matrix/README.md).
+
+</details>
+
 <details>
 <summary><b>LINE</b></summary>
 
@@ -459,8 +581,6 @@ picoclaw gateway
       "enabled": true,
       "channel_secret": "YOUR_CHANNEL_SECRET",
       "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
       "webhook_path": "/webhook/line",
       "allow_from": []
     }
@@ -468,13 +588,15 @@ picoclaw gateway
 }
 ```
 
+> 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
-ngrok http 18791
+# 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**.
@@ -487,19 +609,18 @@ picoclaw gateway
 
 > In group chats, the bot responds only when @mentioned. Replies quote the original message.
 
-> **Docker Compose**: Add `ports: ["18791:18791"]` to the `picoclaw-gateway` service to expose the webhook port.
-
 </details>
 
 <details>
 <summary><b>WeCom (企业微信)</b></summary>
 
-PicoClaw supports two types of WeCom integration:
+PicoClaw supports three types of WeCom integration:
 
-**Option 1: WeCom Bot (智能机器人)** - Easier setup, supports group chats
-**Option 2: WeCom App (自建应用)** - More features, proactive messaging
+**Option 1: WeCom Bot (Bot)** - Easier setup, supports group chats
+**Option 2: WeCom App (Custom App)** - More features, proactive messaging, private chat only
+**Option 3: WeCom AI Bot (AI Bot)** - Official AI Bot, streaming replies, supports group & private chat
 
-See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detailed setup instructions.
+See [WeCom AI Bot Configuration Guide](docs/channels/wecom/wecom_aibot/README.zh.md) for detailed setup instructions.
 
 **Quick Setup - WeCom Bot:**
 
@@ -518,8 +639,6 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
       "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_host": "0.0.0.0",
-      "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": []
     }
@@ -527,6 +646,8 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
 }
 ```
 
+> 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**
@@ -534,10 +655,11 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
 * 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:18792/webhook/wecom-app`
+* Set URL to `http://your-server:18790/webhook/wecom-app`
 * Generate **Token** and **EncodingAESKey**
 
 **3. Configure**
@@ -552,8 +674,6 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
       "agent_id": 1000002,
       "token": "YOUR_TOKEN",
       "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": []
     }
@@ -567,7 +687,40 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
 picoclaw gateway
 ```
 
-> **Note**: WeCom App requires opening port 18792 for webhook callbacks. Use a reverse proxy for HTTPS.
+> **Note**: WeCom webhook callbacks are served on the Gateway port (default 18790). Use a reverse proxy for HTTPS.
+
+**Quick Setup - WeCom AI Bot:**
+
+**1. Create an AI Bot**
+
+* Go to WeCom Admin Console → App Management → AI Bot
+* In the AI Bot settings, configure callback URL: `http://your-server:18791/webhook/wecom-aibot`
+* Copy **Token** and click "Random Generate" for **EncodingAESKey**
+
+**2. Configure**
+
+```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. Run**
+
+```bash
+picoclaw gateway
+```
+
+> **Note**: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to `response_url` push delivery.
 
 </details>
 
@@ -581,6 +734,31 @@ Connect Picoclaw to the Agent Social Network simply by sending a single message
 
 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`):
@@ -600,6 +778,26 @@ PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspa
 └── USER.md           # User preferences
 ```
 
+### Skill Sources
+
+By default, skills are loaded from:
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (global)
+3. `<current-working-directory>/skills` (builtin)
+
+For advanced/test setups, you can override the builtin skills root with:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### 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.
 ### 🔒 Security Sandbox
 
 PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
@@ -776,7 +974,7 @@ The subagent has access to tools (message, web_search, etc.) and can communicate
 ### Providers
 
 > [!NOTE]
-> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
+> 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                                                          |
 | -------------------------- | --------------------------------------- | -------------------------------------------------------------------- |
@@ -789,6 +987,7 @@ The subagent has access to tools (message, web_search, etc.) and can communicate
 | `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)
 
@@ -804,7 +1003,7 @@ This design also enables **multi-agent support** with flexible provider selectio
 #### 📋 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) |
@@ -816,10 +1015,12 @@ This design also enables **multi-agent support** with flexible provider selectio
 | **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/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://console.volcengine.com)                        |
 | **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
+| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
 | **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
 | **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
 
@@ -912,10 +1113,24 @@ This design also enables **multi-agent support** with flexible provider selectio
   "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:
@@ -1040,6 +1255,10 @@ picoclaw agent -m "Hello"
       "model": "anthropic/claude-opus-4-5"
     }
   },
+  "session": {
+    "dm_scope": "per-channel-peer",
+    "backlog_limit": 20
+  },
   "providers": {
     "openrouter": {
       "api_key": "sk-or-v1-xxx"
@@ -1060,7 +1279,11 @@ picoclaw agent -m "Hello"
       "allow_from": [""]
     },
     "whatsapp": {
-      "enabled": false
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
     },
     "feishu": {
       "enabled": false,
@@ -1087,6 +1310,16 @@ picoclaw agent -m "Hello"
       "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": {
@@ -1140,14 +1373,73 @@ discord: <https://discord.gg/V4sAZ9XWpN>
 
 ## 🐛 Troubleshooting
 
-### Web search says "API 配置问题"
+### 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:
+#### Search Provider Priority
 
-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).
+PicoClaw automatically selects the best available search provider in this order:
+1. **Perplexity** (if enabled and API key configured) - AI-powered search with citations
+2. **Brave Search** (if enabled and API key configured) - Privacy-focused paid API ($5/1000 queries)
+3. **SearXNG** (if enabled and base_url configured) - Self-hosted metasearch aggregating 70+ engines (free)
+4. **DuckDuckGo** (if enabled, default fallback) - No API key required (free)
+
+#### Web Search Configuration Options
+
+**Option 1 (Best Results)**: Perplexity AI Search
+```json
+{
+  "tools": {
+    "web": {
+      "perplexity": {
+        "enabled": true,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+**Option 2 (Paid API)**: Get an API key at [https://brave.com/search/api](https://brave.com/search/api) ($5/1000 queries, ~$5-6/month)
+```json
+{
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": true,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+**Option 3 (Self-Hosted)**: Deploy your own [SearXNG](https://github.com/searxng/searxng) instance
+```json
+{
+  "tools": {
+    "web": {
+      "searxng": {
+        "enabled": true,
+        "base_url": "http://your-server:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+Benefits of SearXNG:
+- **Zero cost**: No API fees or rate limits
+- **Privacy-focused**: Self-hosted, no tracking
+- **Aggregate results**: Queries 70+ search engines simultaneously
+- **Perfect for cloud VMs**: Solves datacenter IP blocking issues (Oracle Cloud, GCP, AWS, Azure)
+- **No API key needed**: Just deploy and configure the base URL
+
+**Option 4 (No Setup Required)**: DuckDuckGo is enabled by default as fallback (no API key needed)
 
 Add the key to `~/.picoclaw/config.json` if using Brave:
 
@@ -1163,6 +1455,16 @@ Add the key to `~/.picoclaw/config.json` if using Brave:
       "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
       }
     }
   }
@@ -1181,10 +1483,11 @@ This happens when another instance of the bot is running. Make sure only one `pi
 
 ## 📝 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.)    |
+| 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** | Paid ($5/1000 queries)   | Web search functionality              |
+| **SearXNG**      | Unlimited (self-hosted)  | Privacy-focused metasearch (70+ engines) |
+| **Groq**         | Free tier available      | Fast inference (Llama, Mixtral)       |
+| **Cerebras**     | Free tier available      | Fast inference (Llama, Qwen, etc.)    |
diff --git a/README.pt-br.md b/README.pt-br.md
index 8d87333bc..5f37ba457 100644
--- a/README.pt-br.md
+++ b/README.pt-br.md
@@ -7,7 +7,7 @@
 
   <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/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V-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>
@@ -66,7 +66,7 @@
 
 ⚡️ **Inicialização Relámpago**: Tempo de inicialização 400X mais rápido, boot em 1 segundo mesmo em CPU single-core de 0.6GHz.
 
-🌍 **Portabilidade Real**: Um único binário auto-contido para RISC-V, ARM e x86. Um clique e já era!
+🌍 **Portabilidade Real**: Um único binário auto-contido para RISC-V, ARM, MIPS e x86. Um clique e já era!
 
 🤖 **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.
 
@@ -165,39 +165,43 @@ Você tambêm pode rodar o PicoClaw usando Docker Compose sem instalar nada loca
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Configure suas API keys
-cp config/config.example.json config/config.json
-vim config/config.json      # Configure DISCORD_BOT_TOKEN, API keys, etc.
+# 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.
 
-# 3. Build & Iniciar
-docker compose --profile gateway up -d
+# 3. Configure suas API keys
+vim docker/data/config.json   # Chaves de API do provedor, tokens de bot, etc.
+
+# 4. Iniciar
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!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`.
 
+```bash
+# 5. Ver logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. Ver logs
-docker compose logs -f picoclaw-gateway
-
-# 5. Parar
-docker compose --profile gateway down
+# 6. Parar
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Modo Agente (Execução única)
 
 ```bash
 # Fazer uma pergunta
-docker compose run --rm picoclaw-agent -m "Quanto e 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Quanto e 2+2?"
 
 # Modo interativo
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Rebuild
+### Atualizar
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Início Rápido
@@ -222,12 +226,13 @@ picoclaw onboard
       "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": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "tools": {
@@ -246,6 +251,9 @@ picoclaw onboard
 }
 ```
 
+> **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)
@@ -274,7 +282,7 @@ Converse com seu PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom.
 | **QQ** | Fácil (AppID + AppSecret) |
 | **DingTalk** | Médio (credenciais do app) |
 | **LINE** | Médio (credenciais + webhook URL) |
-| **WeCom** | Médio (CorpID + configuração webhook) |
+| **WeCom AI Bot** | Médio (Token + chave AES) |
 
 <details>
 <summary><b>Telegram</b> (Recomendado)</summary>
@@ -442,8 +450,6 @@ picoclaw gateway
       "enabled": true,
       "channel_secret": "YOUR_CHANNEL_SECRET",
       "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
       "webhook_path": "/webhook/line",
       "allow_from": []
     }
@@ -457,11 +463,13 @@ O LINE requer HTTPS para webhooks. Use um reverse proxy ou tunnel:
 
 ```bash
 # Exemplo com ngrok
-ngrok http 18791
+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
@@ -470,19 +478,20 @@ picoclaw gateway
 
 > Em chats de grupo, o bot responde apenas quando mencionado com @. As respostas citam a mensagem original.
 
-> **Docker Compose**: Adicione `ports: ["18791:18791"]` ao serviço `picoclaw-gateway` para expor a porta do webhook.
+> **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:
+O PicoClaw suporta três 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
+**Opção 1: WeCom Bot (Robô)** - Configuração mais fácil, suporta chats em grupo
+**Opção 2: WeCom App (Aplicativo Personalizado)** - Mais recursos, mensagens proativas, somente chat privado
+**Opção 3: WeCom AI Bot (Robô Inteligente)** - Bot IA oficial, respostas em streaming, suporta grupo e privado
 
-Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para instruções detalhadas.
+Veja o [Guia de Configuração WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) para instruções detalhadas.
 
 **Configuração Rápida - WeCom Bot:**
 
@@ -501,8 +510,6 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
       "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_host": "0.0.0.0",
-      "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": []
     }
@@ -510,6 +517,8 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
 }
 ```
 
+> **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**
@@ -521,7 +530,7 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
 **2. Configurar recebimento de mensagens**
 
 * Nos detalhes do aplicativo, clique em "Receber Mensagens" → "Configurar API"
-* Defina a URL como `http://your-server:18792/webhook/wecom-app`
+* Defina a URL como `http://your-server:18790/webhook/wecom-app`
 * Gere o **Token** e o **EncodingAESKey**
 
 **3. Configurar**
@@ -536,8 +545,6 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
       "agent_id": 1000002,
       "token": "YOUR_TOKEN",
       "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": []
     }
@@ -551,7 +558,40 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
 picoclaw gateway
 ```
 
-> **Nota**: O WeCom App requer a abertura da porta 18792 para callbacks de webhook. Use um proxy reverso para HTTPS em produção.
+> **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.
+
+**Configuração Rápida - WeCom AI Bot:**
+
+**1. Criar um AI Bot**
+
+* Acesse o Console de Administração WeCom → Gerenciamento de Aplicativos → AI Bot
+* Configure a URL de callback: `http://your-server:18791/webhook/wecom-aibot`
+* Copie o **Token** e gere 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": "Olá! Como posso ajudá-lo?"
+    }
+  }
+}
+```
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+> **Nota**: O WeCom AI Bot usa protocolo de pull em streaming — sem preocupações com timeout de resposta. Tarefas longas (>5,5 min) alternam automaticamente para entrega via `response_url`.
 
 </details>
 
@@ -565,6 +605,31 @@ Conecte o PicoClaw a Rede Social de Agentes simplesmente enviando uma única men
 
 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`):
@@ -758,7 +823,7 @@ O subagente tem acesso às ferramentas (message, web_search, etc.) e pode se com
 ### Provedores
 
 > [!NOTE]
-> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de voz do Telegram serão automaticamente transcritas.
+> 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.
 
 | Provedor | Finalidade | Obter API Key |
 | --- | --- | --- |
@@ -973,6 +1038,17 @@ Este design também possibilita o **suporte multi-agent** com seleção flexíve
 ```
 > 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:
diff --git a/README.vi.md b/README.vi.md
index 1be58d9f6..92c6ecbae 100644
--- a/README.vi.md
+++ b/README.vi.md
@@ -3,11 +3,11 @@
 
 <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 · 皮皮虾，我们走！</h3>
+<h3>Phần cứng $10 · RAM 10MB · Khởi động 1 giây · Nào, xuất phát!</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/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V-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>
@@ -65,7 +65,7 @@
 
 ⚡️ **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.
 
-🌍 **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!
+🌍 **Di động thực sự**: Một file binary duy nhất chạy trên RISC-V, ARM, MIPS và x86. Một click là chạy!
 
 🤖 **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.
 
@@ -145,39 +145,43 @@ Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cà
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Thiết lập API Key
-cp config/config.example.json config/config.json
-vim config/config.json      # Thiết lập DISCORD_BOT_TOKEN, API keys, v.v.
+# 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.
 
-# 3. Build & Khởi động
-docker compose --profile gateway up -d
+# 3. Thiết lập API Key
+vim docker/data/config.json   # API key của provider, bot token, v.v.
+
+# 4. Khởi động
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!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`.
 
+```bash
+# 5. Xem logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. Xem logs
-docker compose logs -f picoclaw-gateway
-
-# 5. Dừng
-docker compose --profile gateway down
+# 6. Dừng
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Chế độ Agent (chạy một lần)
 
 ```bash
 # Đặt câu hỏi
-docker compose run --rm picoclaw-agent -m "2+2 bằng mấy?"
+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 run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Build lại
+### Cập nhật
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Bắt đầu nhanh
@@ -202,12 +206,13 @@ picoclaw onboard
       "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": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "channels": {
@@ -220,6 +225,9 @@ picoclaw onboard
 }
 ```
 
+> **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)
@@ -248,7 +256,7 @@ Trò chuyện với PicoClaw qua Telegram, Discord, DingTalk, LINE hoặc WeCom.
 | **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) |
+| **WeCom AI Bot** | Trung bình (Token + khóa AES) |
 
 <details>
 <summary><b>Telegram</b> (Khuyên dùng)</summary>
@@ -416,8 +424,6 @@ picoclaw gateway
       "enabled": true,
       "channel_secret": "YOUR_CHANNEL_SECRET",
       "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
       "webhook_path": "/webhook/line",
       "allow_from": []
     }
@@ -431,7 +437,7 @@ LINE yêu cầu HTTPS cho webhook. Sử dụng reverse proxy hoặc tunnel:
 
 ```bash
 # Ví dụ với ngrok
-ngrok http 18791
+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**.
@@ -444,19 +450,20 @@ 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**: Thêm `ports: ["18791:18791"]` vào service `picoclaw-gateway` để mở port webhook.
+> **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:
+PicoClaw hỗ trợ ba 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
+**Tùy chọn 1: WeCom Bot (Robot)** - 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ùy chỉnh)** - Nhiều tính năng hơn, nhắn tin chủ động, chỉ chat riêng tư
+**Tùy chọn 3: WeCom AI Bot (Bot Thông Minh)** - Bot AI chính thức, phản hồi streaming, hỗ trợ nhóm và riêng tư
 
-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.
+Xem [Hướng dẫn Cấu hình WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) để biết hướng dẫn chi tiết.
 
 **Thiết lập Nhanh - WeCom Bot:**
 
@@ -475,8 +482,6 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
       "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_host": "0.0.0.0",
-      "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": []
     }
@@ -484,6 +489,8 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
 }
 ```
 
+> **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**
@@ -495,7 +502,7 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
 **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:18792/webhook/wecom-app`
+* Đặt URL thành `http://your-server:18790/webhook/wecom-app`
 * Tạo **Token** và **EncodingAESKey**
 
 **3. Cấu hình**
@@ -510,8 +517,6 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
       "agent_id": 1000002,
       "token": "YOUR_TOKEN",
       "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": []
     }
@@ -525,7 +530,40 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
 picoclaw gateway
 ```
 
-> **Lưu ý**: WeCom App yêu cầu mở cổng 18792 cho callback webhook. Sử dụng proxy ngược cho HTTPS trong môi trường sản xuất.
+> **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.
+
+**Thiết lập Nhanh - WeCom AI Bot:**
+
+**1. Tạo AI Bot**
+
+* Truy cập Bảng điều khiển Quản trị WeCom → Quản lý Ứng dụng → AI Bot
+* Cấu hình URL callback: `http://your-server:18791/webhook/wecom-aibot`
+* Sao chép **Token** và tạo **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": "Xin chào! Tôi có thể giúp gì cho bạn?"
+    }
+  }
+}
+```
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+> **Lưu ý**: WeCom AI Bot sử dụng giao thức pull streaming — không lo timeout phản hồi. Tác vụ dài (>5,5 phút) tự động chuyển sang gửi qua `response_url`.
 
 </details>
 
@@ -539,6 +577,31 @@ Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi mộ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`):
@@ -732,7 +795,7 @@ Subagent có quyền truy cập các công cụ (message, web_search, v.v.) và
 ### 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.
+> 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 âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển thành văn bản ở cấp độ agent.
 
 | Nhà cung cấp | Mục đích | Lấy API Key |
 | --- | --- | --- |
@@ -944,6 +1007,17 @@ Thiết kế này cũng cho phép **hỗ trợ đa tác nhân** với lựa ch
 ```
 > 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:
diff --git a/README.zh.md b/README.zh.md
index 74760b3b1..c744e0d20 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -7,7 +7,7 @@
 
   <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/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V-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>
@@ -67,7 +67,7 @@
 
 ⚡️ **闪电启动**: 启动速度快 400 倍，即使在 0.6GHz 单核处理器上也能在 1 秒内启动。
 
-🌍 **真正可移植**: 跨 RISC-V、ARM 和 x86 架构的单二进制文件，一键运行！
+🌍 **真正可移植**: 跨 RISC-V、ARM、MIPS 和 x86 架构的单二进制文件，一键运行！
 
 🤖 **AI 自举**: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由“人机回环 (Human-in-the-loop)”微调。
 
@@ -166,41 +166,43 @@ make install
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. 设置 API Key
-cp config/config.example.json config/config.json
-vim config/config.json      # 设置 DISCORD_BOT_TOKEN, API keys 等
+# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
+docker compose -f docker/docker-compose.yml --profile gateway up
+# 容器打印 "First-run setup complete." 后自动停止
 
-# 3. 构建并启动
-docker compose --profile gateway up -d
+# 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`。
+> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
 
-# 4. 查看日志
-docker compose logs -f picoclaw-gateway
-
-# 5. 停止
-docker compose --profile gateway down
+```bash
+# 5. 查看日志
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Agent 模式 (一次性运行)
 
 ```bash
 # 提问
-docker compose run --rm picoclaw-agent -m "2+2 等于几？"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
 
 # 交互模式
-docker compose run --rm picoclaw-agent
-
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### 重新构建
+### 更新镜像
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
-
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 快速开始
@@ -224,7 +226,7 @@ picoclaw onboard
   "agents": {
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
-      "model": "gpt4",
+      "model_name": "gpt4",
       "max_tokens": 8192,
       "temperature": 0.7,
       "max_tool_iterations": 20
@@ -234,7 +236,8 @@ picoclaw onboard
     {
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
-      "api_key": "your-api-key"
+      "api_key": "your-api-key",
+      "request_timeout": 300
     },
     {
       "model_name": "claude-sonnet-4.6",
@@ -263,6 +266,7 @@ picoclaw onboard
 ```
 
 > **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。
+> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
 
 **3. 获取 API Key**
 
@@ -286,6 +290,8 @@ picoclaw agent -m "2+2 等于几？"
 
 PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
 
+> **注意**: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。注意：飞书（Feishu）使用 WebSocket/SDK 模式，不通过该共享 HTTP webhook 服务器接收消息。
+
 ### 核心渠道
 
 | 渠道                 | 设置难度    | 特性说明                                  | 文档链接                                                                                                        |
@@ -293,14 +299,22 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
 | **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)                                                                    |
+| **Matrix**           | ⭐⭐ 中等   | 联邦协议，支持自建 homeserver 与公开服务器 | [查看文档](docs/channels/matrix/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) |
+| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)、自建应用(API)和智能机器人(AI Bot) | [Bot 文档](docs/channels/wecom/wecom_bot/README.zh.md) / [App 文档](docs/channels/wecom/wecom_app/README.zh.md) / [AI Bot 文档](docs/channels/wecom/wecom_aibot/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)                                                                  |
 
+### Telegram 命令注册（启动时自动同步）
+
+PicoClaw 现在使用统一的命令定义来源。启动时会自动将 Telegram 支持的命令（例如 `/start`、`/help`、`/show`、`/list`）注册到 Bot 命令菜单，确保菜单展示与实际行为一致。
+Telegram 侧保留的是命令菜单注册能力；通用命令的实际执行统一走 Agent Loop 中的 commands executor。
+
+如果注册因网络或 API 短暂异常失败，不会阻塞 channel 启动；系统会在后台自动重试。
+
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> 加入 Agent 社交网络
 
 只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
@@ -311,6 +325,31 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
 
 配置文件路径: `~/.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`）：
@@ -331,6 +370,26 @@ PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/work
 
 ```
 
+### 技能来源 (Skill Sources)
+
+默认情况下，技能会按以下顺序加载：
+
+1. `~/.picoclaw/workspace/skills`（工作区）
+2. `~/.picoclaw/skills`（全局）
+3. `<current-working-directory>/skills`（内置）
+
+在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### 统一命令执行策略
+
+- 通用斜杠命令通过 `pkg/agent/loop.go` 中的 `commands.Executor` 统一执行。
+- Channel 适配器不再在本地消费通用命令；它们只负责把入站文本转发到 bus/agent 路径。Telegram 仍会在启动时自动注册其支持的命令菜单。
+- 未注册的斜杠命令（例如 `/foo`）会透传给 LLM 按普通输入处理。
+- 已注册但当前 channel 不支持的命令（例如 WhatsApp 上的 `/show`）会返回明确的用户可见错误，并停止后续处理。
 ### 心跳 / 周期性任务 (Heartbeat)
 
 PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：
@@ -414,7 +473,7 @@ Agent 读取 HEARTBEAT.md
 ### 提供商 (Providers)
 
 > [!NOTE]
-> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，Telegram 语音消息将被自动转录为文字。
+> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，任意渠道的音频消息都将在 Agent 层面自动转录为文字。
 
 | 提供商               | 用途                         | 获取 API Key                                                         |
 | -------------------- | ---------------------------- | -------------------------------------------------------------------- |
@@ -550,7 +609,8 @@ Agent 读取 HEARTBEAT.md
   "model_name": "my-custom-model",
   "model": "openai/custom-model",
   "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-..."
+  "api_key": "sk-...",
+  "request_timeout": 300
 }
 ```
 
@@ -669,6 +729,10 @@ picoclaw agent -m "你好"
       "model": "anthropic/claude-opus-4-5"
     }
   },
+  "session": {
+    "dm_scope": "per-channel-peer",
+    "backlog_limit": 20
+  },
   "providers": {
     "openrouter": {
       "api_key": "sk-or-v1-xxx"
diff --git a/assets/picoclaw_detect_person.mp4 b/assets/picoclaw_detect_person.mp4
deleted file mode 100644
index b56999689..000000000
Binary files a/assets/picoclaw_detect_person.mp4 and /dev/null differ
diff --git a/assets/wechat.png b/assets/wechat.png
index a34217c33..4442ef2c7 100644
Binary files a/assets/wechat.png and b/assets/wechat.png differ
diff --git a/cmd/picoclaw-launcher-tui/internal/config/store.go b/cmd/picoclaw-launcher-tui/internal/config/store.go
new file mode 100644
index 000000000..0236de19f
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/config/store.go
@@ -0,0 +1,49 @@
+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
new file mode 100644
index 000000000..a2ccddf70
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/app.go
@@ -0,0 +1,522 @@
+package ui
+
+import (
+	"fmt"
+	"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)
+	root.AddItem(footerView(), 1, 0, false)
+
+	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("Menu", nil)
+	refreshMainMenu(menu, s)
+	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		switch event.Key() {
+		case tcell.KeyEsc:
+			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 (s *appState) countChannels() (enabled int, total int) {
+	c := s.config.Channels
+	entries := []bool{
+		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.Matrix.Enabled,
+		c.LINE.Enabled,
+		c.OneBot.Enabled,
+		c.WeCom.Enabled,
+		c.WeComApp.Enabled,
+	}
+	total = len(entries)
+	for _, v := range entries {
+		if v {
+			enabled++
+		}
+	}
+	return enabled, total
+}
+
+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()
+	enabledCount, totalChannels := s.countChannels()
+	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(),
+			Action: func() {
+				s.push("model", s.modelMenu())
+			},
+			MainColor: func() *tcell.Color {
+				if modelReady {
+					return nil
+				}
+				color := tcell.ColorGray
+				return &color
+			}(),
+		},
+		{
+			Label:       rootChannelLabel(channelReady),
+			Description: fmt.Sprintf("%d/%d enabled", enabledCount, totalChannels),
+			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 (None)"
+	}
+	return "Model (" + selected + ")"
+}
+
+func rootModelDescription() string {
+	return "Using SPACE to choose your model"
+}
+
+func rootChannelLabel(valid bool) string {
+	if !valid {
+		return "Channel (no channel enabled)"
+	}
+	return "Channel"
+}
+
+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.Matrix.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
new file mode 100644
index 000000000..2f28af123
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/channel.go
@@ -0,0 +1,433 @@
+package ui
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func (s *appState) buildChannelMenuItems() []MenuItem {
+	return []MenuItem{
+		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(
+			"Matrix",
+			"Matrix bot settings",
+			s.config.Channels.Matrix.Enabled,
+			func() { s.push("channel-matrix", s.matrixForm()) },
+		),
+		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()) },
+		),
+	}
+}
+
+func (s *appState) channelMenu() tview.Primitive {
+	menu := NewMenu("Channels", s.buildChannelMenuItems())
+	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			s.pop()
+			return nil
+		}
+		return event
+	})
+	return menu
+}
+
+func refreshChannelMenuFromState(menu *Menu, s *appState) {
+	menu.applyItems(s.buildChannelMenuItems())
+}
+
+func (s *appState) telegramForm() tview.Primitive {
+	cfg := &s.config.Channels.Telegram
+	form := baseChannelForm("Telegram", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) discordForm() tview.Primitive {
+	cfg := &s.config.Channels.Discord
+	form := baseChannelForm("Discord", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) qqForm() tview.Primitive {
+	cfg := &s.config.Channels.QQ
+	form := baseChannelForm("QQ", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) maixcamForm() tview.Primitive {
+	cfg := &s.config.Channels.MaixCam
+	form := baseChannelForm("MaixCam", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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 })
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) whatsappForm() tview.Primitive {
+	cfg := &s.config.Channels.WhatsApp
+	form := baseChannelForm("WhatsApp", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	form.AddInputField("Bridge URL", cfg.BridgeURL, 128, nil, func(text string) {
+		cfg.BridgeURL = strings.TrimSpace(text)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) feishuForm() tview.Primitive {
+	cfg := &s.config.Channels.Feishu
+	form := baseChannelForm("Feishu", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) dingtalkForm() tview.Primitive {
+	cfg := &s.config.Channels.DingTalk
+	form := baseChannelForm("DingTalk", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) slackForm() tview.Primitive {
+	cfg := &s.config.Channels.Slack
+	form := baseChannelForm("Slack", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) lineForm() tview.Primitive {
+	cfg := &s.config.Channels.LINE
+	form := baseChannelForm("LINE", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) matrixForm() tview.Primitive {
+	cfg := &s.config.Channels.Matrix
+	form := baseChannelForm("Matrix", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	form.AddInputField("Homeserver", cfg.Homeserver, 128, nil, func(text string) {
+		cfg.Homeserver = strings.TrimSpace(text)
+	})
+	form.AddInputField("User ID", cfg.UserID, 128, nil, func(text string) {
+		cfg.UserID = strings.TrimSpace(text)
+	})
+	form.AddInputField("Access Token", cfg.AccessToken, 128, nil, func(text string) {
+		cfg.AccessToken = strings.TrimSpace(text)
+	})
+	form.AddInputField("Device ID", cfg.DeviceID, 128, nil, func(text string) {
+		cfg.DeviceID = strings.TrimSpace(text)
+	})
+	form.AddCheckbox("Join On Invite", cfg.JoinOnInvite, func(checked bool) {
+		cfg.JoinOnInvite = checked
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) onebotForm() tview.Primitive {
+	cfg := &s.config.Channels.OneBot
+	form := baseChannelForm("OneBot", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+		},
+	)
+	addAllowFromField(form, &cfg.AllowFrom)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) wecomForm() tview.Primitive {
+	cfg := &s.config.Channels.WeCom
+	form := baseChannelForm("WeCom", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	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, s.makeChannelOnEnabled(&cfg.Enabled))
+	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)
+	})
+	addAllowFromField(form, &cfg.AllowFrom)
+	addIntField(
+		form,
+		"Reply Timeout",
+		cfg.ReplyTimeout,
+		func(value int) { cfg.ReplyTimeout = value },
+	)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) makeChannelOnEnabled(enabledPtr *bool) func(bool) {
+	return func(v bool) {
+		*enabledPtr = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	}
+}
+
+func addAllowFromField(form *tview.Form, allowFrom *picoclawconfig.FlexibleStringSlice) {
+	form.AddInputField("Allow From", strings.Join(*allowFrom, ","), 128, nil, func(text string) {
+		*allowFrom = splitCSV(text)
+	})
+}
+
+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
new file mode 100644
index 000000000..bc874f7f2
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go
@@ -0,0 +1,16 @@
+//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
new file mode 100644
index 000000000..7067a5c13
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go
@@ -0,0 +1,16 @@
+//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
new file mode 100644
index 000000000..9f2132c5a
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/menu.go
@@ -0,0 +1,72 @@
+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
new file mode 100644
index 000000000..47ca5a355
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/model.go
@@ -0,0 +1,399 @@
+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, 1+len(s.config.ModelList))
+	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))
+			},
+		})
+	}
+	// Add model entry appended at the end so the models map to rows 1..N
+	items = append(items,
+		MenuItem{
+			Label:       "**Add model**",
+			Description: "Append a new model entry",
+			Action: func() {
+				newName := s.nextAvailableModelName("new-model")
+				s.addModel(
+					picoclawconfig.ModelConfig{ModelName: newName, Model: "openai/gpt-5.2"},
+				)
+				s.push(
+					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
+					s.modelForm(len(s.config.ModelList)-1),
+				)
+			},
+		},
+	)
+
+	menu := NewMenu("Models", items)
+	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			s.pop()
+			return nil
+		}
+
+		if event.Rune() == ' ' {
+			row, _ := menu.GetSelection()
+			if row >= 0 && row < len(s.config.ModelList) {
+				model := s.config.ModelList[row]
+				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))
+
+	addInput(form, "Model Name", model.ModelName, func(value string) {
+		if value == "" {
+			s.showMessage("Invalid model name", "Model Name cannot be empty")
+			return
+		}
+		if s.modelNameExists(value, index) {
+			s.showMessage("Duplicate model name", fmt.Sprintf("Model Name '%s' already exists", value))
+			return
+		}
+		oldName := model.ModelName
+		model.ModelName = value
+		if s.config.Agents.Defaults.Model == oldName {
+			s.config.Agents.Defaults.Model = value
+		}
+		s.dirty = true
+		form.SetTitle(fmt.Sprintf("Model: %s", model.ModelName))
+		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() {
+		pageName := "confirm-delete-model"
+		if s.pages.HasPage(pageName) {
+			return
+		}
+		modal := tview.NewModal().
+			SetText("Are you sure you want to delete this model?").
+			AddButtons([]string{"Cancel", "Delete"}).
+			SetDoneFunc(func(buttonIndex int, buttonLabel string) {
+				s.pages.RemovePage(pageName)
+				if buttonLabel == "Delete" {
+					s.deleteModel(index)
+				}
+			})
+		modal.SetTitle("Confirm Delete").SetBorder(true)
+		s.pages.AddPage(pageName, modal, true, true)
+	})
+	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
+		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, 1+len(s.config.ModelList))
+	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))
+			},
+		})
+	}
+	items = append(items,
+		MenuItem{
+			Label:       "**Add Model**",
+			Description: "Append a new model entry",
+			Action: func() {
+				newName := s.nextAvailableModelName("new-model")
+				s.addModel(
+					picoclawconfig.ModelConfig{ModelName: newName, Model: "openai/gpt-5.2"},
+				)
+				s.push(fmt.Sprintf("model-%d", len(s.config.ModelList)-1), s.modelForm(len(s.config.ModelList)-1))
+			},
+		},
+	)
+	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) modelNameExists(name string, excludeIndex int) bool {
+	target := strings.TrimSpace(name)
+	if target == "" {
+		return false
+	}
+	for i := range s.config.ModelList {
+		if i == excludeIndex {
+			continue
+		}
+		if strings.TrimSpace(s.config.ModelList[i].ModelName) == target {
+			return true
+		}
+	}
+	return false
+}
+
+func (s *appState) nextAvailableModelName(base string) string {
+	name := strings.TrimSpace(base)
+	if name == "" {
+		name = "new-model"
+	}
+	if !s.modelNameExists(name, -1) {
+		return name
+	}
+	for i := 2; ; i++ {
+		candidate := fmt.Sprintf("%s-%d", name, i)
+		if !s.modelNameExists(candidate, -1) {
+			return candidate
+		}
+	}
+}
+
+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, err := io.ReadAll(io.LimitReader(resp.Body, 2048))
+	if err != nil {
+		s.showMessage("Test failed", fmt.Sprintf("failed to read response: %v", err))
+		return
+	}
+	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
new file mode 100644
index 000000000..da3c3526d
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/style.go
@@ -0,0 +1,55 @@
+package ui
+
+import (
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+)
+
+const (
+	colorBlue = "[#3e5db9]"
+	colorRed  = "[#d54646]"
+	banner    = "\r\n[::b]" +
+		colorBlue + "██████╗ ██╗ ██████╗ ██████╗ " + colorRed + " ██████╗██╗      █████╗ ██╗    ██╗\n" +
+		colorBlue + "██╔══██╗██║██╔════╝██╔═══██╗" + colorRed + "██╔════╝██║     ██╔══██╗██║    ██║\n" +
+		colorBlue + "██████╔╝██║██║     ██║   ██║" + colorRed + "██║     ██║     ███████║██║ █╗ ██║\n" +
+		colorBlue + "██╔═══╝ ██║██║     ██║   ██║" + colorRed + "██║     ██║     ██╔══██║██║███╗██║\n" +
+		colorBlue + "██║     ██║╚██████╗╚██████╔╝" + colorRed + "╚██████╗███████╗██║  ██║╚███╔███╔╝\n" +
+		colorBlue + "╚═╝     ╚═╝ ╚═════╝ ╚═════╝ " + colorRed + " ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝\n " +
+		"[:]"
+)
+
+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(banner)
+	text.SetBorder(false)
+	return text
+}
+
+const footerText = "Esc: Back/Exit | Enter: Enter | ←↓↑→ : Move | Space: Select | Tab/Shift+Tab: Switch"
+
+func footerView() *tview.TextView {
+	text := tview.NewTextView()
+	text.SetTextAlign(tview.AlignCenter)
+	text.SetText(footerText)
+	text.SetBackgroundColor(tview.Styles.MoreContrastBackgroundColor)
+	text.SetTextColor(tview.Styles.PrimaryTextColor)
+	text.SetBorder(false)
+	return text
+}
diff --git a/cmd/picoclaw-launcher-tui/main.go b/cmd/picoclaw-launcher-tui/main.go
new file mode 100644
index 000000000..0e8cce415
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/main.go
@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/ui"
+)
+
+func main() {
+	if err := ui.Run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
diff --git a/cmd/picoclaw/cmd_cron.go b/cmd/picoclaw/cmd_cron.go
deleted file mode 100644
index 8c42bde06..000000000
--- a/cmd/picoclaw/cmd_cron.go
+++ /dev/null
@@ -1,227 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
-
-import (
-	"fmt"
-	"os"
-	"path/filepath"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/cron"
-)
-
-func cronCmd() {
-	if len(os.Args) < 3 {
-		cronHelp()
-		return
-	}
-
-	subcommand := os.Args[2]
-
-	// Load config to get workspace path
-	cfg, err := loadConfig()
-	if err != nil {
-		fmt.Printf("Error loading config: %v\n", err)
-		return
-	}
-
-	cronStorePath := filepath.Join(cfg.WorkspacePath(), "cron", "jobs.json")
-
-	switch subcommand {
-	case "list":
-		cronListCmd(cronStorePath)
-	case "add":
-		cronAddCmd(cronStorePath)
-	case "remove":
-		if len(os.Args) < 4 {
-			fmt.Println("Usage: picoclaw cron remove <job_id>")
-			return
-		}
-		cronRemoveCmd(cronStorePath, os.Args[3])
-	case "enable":
-		cronEnableCmd(cronStorePath, false)
-	case "disable":
-		cronEnableCmd(cronStorePath, true)
-	default:
-		fmt.Printf("Unknown cron command: %s\n", subcommand)
-		cronHelp()
-	}
-}
-
-func cronHelp() {
-	fmt.Println("\nCron commands:")
-	fmt.Println("  list              List all scheduled jobs")
-	fmt.Println("  add              Add a new scheduled job")
-	fmt.Println("  remove <id>       Remove a job by ID")
-	fmt.Println("  enable <id>      Enable a job")
-	fmt.Println("  disable <id>     Disable a job")
-	fmt.Println()
-	fmt.Println("Add options:")
-	fmt.Println("  -n, --name       Job name")
-	fmt.Println("  -m, --message    Message for agent")
-	fmt.Println("  -e, --every      Run every N seconds")
-	fmt.Println("  -c, --cron       Cron expression (e.g. '0 9 * * *')")
-	fmt.Println("  -d, --deliver     Deliver response to channel")
-	fmt.Println("  --to             Recipient for delivery")
-	fmt.Println("  --channel        Channel for delivery")
-}
-
-func cronListCmd(storePath string) {
-	cs := cron.NewCronService(storePath, nil)
-	jobs := cs.ListJobs(true) // Show all jobs, including disabled
-
-	if len(jobs) == 0 {
-		fmt.Println("No scheduled jobs.")
-		return
-	}
-
-	fmt.Println("\nScheduled Jobs:")
-	fmt.Println("----------------")
-	for _, job := range jobs {
-		var schedule string
-		if job.Schedule.Kind == "every" && job.Schedule.EveryMS != nil {
-			schedule = fmt.Sprintf("every %ds", *job.Schedule.EveryMS/1000)
-		} else if job.Schedule.Kind == "cron" {
-			schedule = job.Schedule.Expr
-		} else {
-			schedule = "one-time"
-		}
-
-		nextRun := "scheduled"
-		if job.State.NextRunAtMS != nil {
-			nextTime := time.UnixMilli(*job.State.NextRunAtMS)
-			nextRun = nextTime.Format("2006-01-02 15:04")
-		}
-
-		status := "enabled"
-		if !job.Enabled {
-			status = "disabled"
-		}
-
-		fmt.Printf("  %s (%s)\n", job.Name, job.ID)
-		fmt.Printf("    Schedule: %s\n", schedule)
-		fmt.Printf("    Status: %s\n", status)
-		fmt.Printf("    Next run: %s\n", nextRun)
-	}
-}
-
-func cronAddCmd(storePath string) {
-	name := ""
-	message := ""
-	var everySec *int64
-	cronExpr := ""
-	deliver := false
-	channel := ""
-	to := ""
-
-	args := os.Args[3:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "-n", "--name":
-			if i+1 < len(args) {
-				name = args[i+1]
-				i++
-			}
-		case "-m", "--message":
-			if i+1 < len(args) {
-				message = args[i+1]
-				i++
-			}
-		case "-e", "--every":
-			if i+1 < len(args) {
-				var sec int64
-				fmt.Sscanf(args[i+1], "%d", &sec)
-				everySec = &sec
-				i++
-			}
-		case "-c", "--cron":
-			if i+1 < len(args) {
-				cronExpr = args[i+1]
-				i++
-			}
-		case "-d", "--deliver":
-			deliver = true
-		case "--to":
-			if i+1 < len(args) {
-				to = args[i+1]
-				i++
-			}
-		case "--channel":
-			if i+1 < len(args) {
-				channel = args[i+1]
-				i++
-			}
-		}
-	}
-
-	if name == "" {
-		fmt.Println("Error: --name is required")
-		return
-	}
-
-	if message == "" {
-		fmt.Println("Error: --message is required")
-		return
-	}
-
-	if everySec == nil && cronExpr == "" {
-		fmt.Println("Error: Either --every or --cron must be specified")
-		return
-	}
-
-	var schedule cron.CronSchedule
-	if everySec != nil {
-		everyMS := *everySec * 1000
-		schedule = cron.CronSchedule{
-			Kind:    "every",
-			EveryMS: &everyMS,
-		}
-	} else {
-		schedule = cron.CronSchedule{
-			Kind: "cron",
-			Expr: cronExpr,
-		}
-	}
-
-	cs := cron.NewCronService(storePath, nil)
-	job, err := cs.AddJob(name, schedule, message, deliver, channel, to)
-	if err != nil {
-		fmt.Printf("Error adding job: %v\n", err)
-		return
-	}
-
-	fmt.Printf("✓ Added job '%s' (%s)\n", job.Name, job.ID)
-}
-
-func cronRemoveCmd(storePath, jobID string) {
-	cs := cron.NewCronService(storePath, nil)
-	if cs.RemoveJob(jobID) {
-		fmt.Printf("✓ Removed job %s\n", jobID)
-	} else {
-		fmt.Printf("✗ Job %s not found\n", jobID)
-	}
-}
-
-func cronEnableCmd(storePath string, disable bool) {
-	if len(os.Args) < 4 {
-		fmt.Println("Usage: picoclaw cron enable/disable <job_id>")
-		return
-	}
-
-	jobID := os.Args[3]
-	cs := cron.NewCronService(storePath, nil)
-	enabled := !disable
-
-	job := cs.EnableJob(jobID, enabled)
-	if job != nil {
-		status := "enabled"
-		if disable {
-			status = "disabled"
-		}
-		fmt.Printf("✓ Job '%s' %s\n", job.Name, status)
-	} else {
-		fmt.Printf("✗ Job %s not found\n", jobID)
-	}
-}
diff --git a/cmd/picoclaw/cmd_migrate.go b/cmd/picoclaw/cmd_migrate.go
deleted file mode 100644
index 86d4903ef..000000000
--- a/cmd/picoclaw/cmd_migrate.go
+++ /dev/null
@@ -1,81 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/sipeed/picoclaw/pkg/migrate"
-)
-
-func migrateCmd() {
-	if len(os.Args) > 2 && (os.Args[2] == "--help" || os.Args[2] == "-h") {
-		migrateHelp()
-		return
-	}
-
-	opts := migrate.Options{}
-
-	args := os.Args[2:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--dry-run":
-			opts.DryRun = true
-		case "--config-only":
-			opts.ConfigOnly = true
-		case "--workspace-only":
-			opts.WorkspaceOnly = true
-		case "--force":
-			opts.Force = true
-		case "--refresh":
-			opts.Refresh = true
-		case "--openclaw-home":
-			if i+1 < len(args) {
-				opts.OpenClawHome = args[i+1]
-				i++
-			}
-		case "--picoclaw-home":
-			if i+1 < len(args) {
-				opts.PicoClawHome = args[i+1]
-				i++
-			}
-		default:
-			fmt.Printf("Unknown flag: %s\n", args[i])
-			migrateHelp()
-			os.Exit(1)
-		}
-	}
-
-	result, err := migrate.Run(opts)
-	if err != nil {
-		fmt.Printf("Error: %v\n", err)
-		os.Exit(1)
-	}
-
-	if !opts.DryRun {
-		migrate.PrintSummary(result)
-	}
-}
-
-func migrateHelp() {
-	fmt.Println("\nMigrate from OpenClaw to PicoClaw")
-	fmt.Println()
-	fmt.Println("Usage: picoclaw migrate [options]")
-	fmt.Println()
-	fmt.Println("Options:")
-	fmt.Println("  --dry-run          Show what would be migrated without making changes")
-	fmt.Println("  --refresh          Re-sync workspace files from OpenClaw (repeatable)")
-	fmt.Println("  --config-only      Only migrate config, skip workspace files")
-	fmt.Println("  --workspace-only   Only migrate workspace files, skip config")
-	fmt.Println("  --force            Skip confirmation prompts")
-	fmt.Println("  --openclaw-home    Override OpenClaw home directory (default: ~/.openclaw)")
-	fmt.Println("  --picoclaw-home    Override PicoClaw home directory (default: ~/.picoclaw)")
-	fmt.Println()
-	fmt.Println("Examples:")
-	fmt.Println("  picoclaw migrate              Detect and migrate from OpenClaw")
-	fmt.Println("  picoclaw migrate --dry-run    Show what would be migrated")
-	fmt.Println("  picoclaw migrate --refresh    Re-sync workspace files")
-	fmt.Println("  picoclaw migrate --force      Migrate without confirmation")
-}
diff --git a/cmd/picoclaw/internal/agent/command.go b/cmd/picoclaw/internal/agent/command.go
new file mode 100644
index 000000000..47262fc85
--- /dev/null
+++ b/cmd/picoclaw/internal/agent/command.go
@@ -0,0 +1,30 @@
+package agent
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewAgentCommand() *cobra.Command {
+	var (
+		message    string
+		sessionKey string
+		model      string
+		debug      bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "agent",
+		Short: "Interact with the agent directly",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return agentCmd(message, sessionKey, model, debug)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&debug, "debug", "d", false, "Enable debug logging")
+	cmd.Flags().StringVarP(&message, "message", "m", "", "Send a single message (non-interactive mode)")
+	cmd.Flags().StringVarP(&sessionKey, "session", "s", "cli:default", "Session key")
+	cmd.Flags().StringVarP(&model, "model", "", "", "Model to use")
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/agent/command_test.go b/cmd/picoclaw/internal/agent/command_test.go
new file mode 100644
index 000000000..1457d6a49
--- /dev/null
+++ b/cmd/picoclaw/internal/agent/command_test.go
@@ -0,0 +1,33 @@
+package agent
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewAgentCommand(t *testing.T) {
+	cmd := NewAgentCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "agent", cmd.Use)
+	assert.Equal(t, "Interact with the agent directly", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("debug"))
+	assert.NotNil(t, cmd.Flags().Lookup("message"))
+	assert.NotNil(t, cmd.Flags().Lookup("session"))
+	assert.NotNil(t, cmd.Flags().Lookup("model"))
+}
diff --git a/cmd/picoclaw/cmd_agent.go b/cmd/picoclaw/internal/agent/helpers.go
similarity index 69%
rename from cmd/picoclaw/cmd_agent.go
rename to cmd/picoclaw/internal/agent/helpers.go
index 8658c9d32..f754abc65 100644
--- a/cmd/picoclaw/cmd_agent.go
+++ b/cmd/picoclaw/internal/agent/helpers.go
@@ -1,7 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package agent
 
 import (
 	"bufio"
@@ -14,62 +11,44 @@ import (
 
 	"github.com/chzyer/readline"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/agent"
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
-func agentCmd() {
-	message := ""
-	sessionKey := "cli:default"
-	modelOverride := ""
-
-	args := os.Args[2:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--debug", "-d":
-			logger.SetLevel(logger.DEBUG)
-			fmt.Println("🔍 Debug mode enabled")
-		case "-m", "--message":
-			if i+1 < len(args) {
-				message = args[i+1]
-				i++
-			}
-		case "-s", "--session":
-			if i+1 < len(args) {
-				sessionKey = args[i+1]
-				i++
-			}
-		case "--model", "-model":
-			if i+1 < len(args) {
-				modelOverride = args[i+1]
-				i++
-			}
-		}
+func agentCmd(message, sessionKey, model string, debug bool) error {
+	if sessionKey == "" {
+		sessionKey = "cli:default"
 	}
 
-	cfg, err := loadConfig()
+	if debug {
+		logger.SetLevel(logger.DEBUG)
+		fmt.Println("🔍 Debug mode enabled")
+	}
+
+	cfg, err := internal.LoadConfig()
 	if err != nil {
-		fmt.Printf("Error loading config: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error loading config: %w", err)
 	}
 
-	if modelOverride != "" {
-		cfg.Agents.Defaults.Model = modelOverride
+	if model != "" {
+		cfg.Agents.Defaults.ModelName = model
 	}
 
 	provider, modelID, err := providers.CreateProvider(cfg)
 	if err != nil {
-		fmt.Printf("Error creating provider: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error creating provider: %w", err)
 	}
+
 	// Use the resolved model ID from provider creation
 	if modelID != "" {
-		cfg.Agents.Defaults.Model = modelID
+		cfg.Agents.Defaults.ModelName = modelID
 	}
 
 	msgBus := bus.NewMessageBus()
+	defer msgBus.Close()
 	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
 
 	// Print agent startup info (only for interactive mode)
@@ -85,18 +64,20 @@ func agentCmd() {
 		ctx := context.Background()
 		response, err := agentLoop.ProcessDirect(ctx, message, sessionKey)
 		if err != nil {
-			fmt.Printf("Error: %v\n", err)
-			os.Exit(1)
+			return fmt.Errorf("error processing message: %w", err)
 		}
-		fmt.Printf("\n%s %s\n", logo, response)
-	} else {
-		fmt.Printf("%s Interactive mode (Ctrl+C to exit)\n\n", logo)
-		interactiveMode(agentLoop, sessionKey)
+		fmt.Printf("\n%s %s\n", internal.Logo, response)
+		return nil
 	}
+
+	fmt.Printf("%s Interactive mode (Ctrl+C to exit)\n\n", internal.Logo)
+	interactiveMode(agentLoop, sessionKey)
+
+	return nil
 }
 
 func interactiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
-	prompt := fmt.Sprintf("%s You: ", logo)
+	prompt := fmt.Sprintf("%s You: ", internal.Logo)
 
 	rl, err := readline.NewEx(&readline.Config{
 		Prompt:          prompt,
@@ -141,14 +122,14 @@ func interactiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
 			continue
 		}
 
-		fmt.Printf("\n%s %s\n\n", logo, response)
+		fmt.Printf("\n%s %s\n\n", internal.Logo, response)
 	}
 }
 
 func simpleInteractiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
 	reader := bufio.NewReader(os.Stdin)
 	for {
-		fmt.Printf("%s You: ", logo)
+		fmt.Print(fmt.Sprintf("%s You: ", internal.Logo))
 		line, err := reader.ReadString('\n')
 		if err != nil {
 			if err == io.EOF {
@@ -176,6 +157,6 @@ func simpleInteractiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
 			continue
 		}
 
-		fmt.Printf("\n%s %s\n\n", logo, response)
+		fmt.Printf("\n%s %s\n\n", internal.Logo, response)
 	}
 }
diff --git a/cmd/picoclaw/internal/auth/command.go b/cmd/picoclaw/internal/auth/command.go
new file mode 100644
index 000000000..12a0a3a8c
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/command.go
@@ -0,0 +1,22 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func NewAuthCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "auth",
+		Short: "Manage authentication (login, logout, status)",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	cmd.AddCommand(
+		newLoginCommand(),
+		newLogoutCommand(),
+		newStatusCommand(),
+		newModelsCommand(),
+	)
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/auth/command_test.go b/cmd/picoclaw/internal/auth/command_test.go
new file mode 100644
index 000000000..48dc704dd
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/command_test.go
@@ -0,0 +1,55 @@
+package auth
+
+import (
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewAuthCommand(t *testing.T) {
+	cmd := NewAuthCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "auth", cmd.Use)
+	assert.Equal(t, "Manage authentication (login, logout, status)", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.False(t, cmd.HasFlags())
+	assert.True(t, cmd.HasSubCommands())
+
+	allowedCommands := []string{
+		"login",
+		"logout",
+		"status",
+		"models",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+
+		assert.Len(t, subcmd.Aliases, 0)
+		assert.False(t, subcmd.Hidden)
+
+		assert.False(t, subcmd.HasSubCommands())
+
+		assert.Nil(t, subcmd.Run)
+		assert.NotNil(t, subcmd.RunE)
+
+		assert.Nil(t, subcmd.PersistentPreRun)
+		assert.Nil(t, subcmd.PersistentPostRun)
+	}
+}
diff --git a/cmd/picoclaw/cmd_auth.go b/cmd/picoclaw/internal/auth/helpers.go
similarity index 61%
rename from cmd/picoclaw/cmd_auth.go
rename to cmd/picoclaw/internal/auth/helpers.go
index 729c56177..a0a229167 100644
--- a/cmd/picoclaw/cmd_auth.go
+++ b/cmd/picoclaw/internal/auth/helpers.go
@@ -1,9 +1,7 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package auth
 
 import (
+	"bufio"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -12,92 +10,31 @@ import (
 	"strings"
 	"time"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/auth"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
-const supportedProvidersMsg = "Supported providers: openai, anthropic, google-antigravity"
-
-func authCmd() {
-	if len(os.Args) < 3 {
-		authHelp()
-		return
-	}
-
-	switch os.Args[2] {
-	case "login":
-		authLoginCmd()
-	case "logout":
-		authLogoutCmd()
-	case "status":
-		authStatusCmd()
-	case "models":
-		authModelsCmd()
-	default:
-		fmt.Printf("Unknown auth command: %s\n", os.Args[2])
-		authHelp()
-	}
-}
-
-func authHelp() {
-	fmt.Println("\nAuth commands:")
-	fmt.Println("  login       Login via OAuth or paste token")
-	fmt.Println("  logout      Remove stored credentials")
-	fmt.Println("  status      Show current auth status")
-	fmt.Println("  models      List available Antigravity models")
-	fmt.Println()
-	fmt.Println("Login options:")
-	fmt.Println("  --provider <name>    Provider to login with (openai, anthropic, google-antigravity)")
-	fmt.Println("  --device-code        Use device code flow (for headless environments)")
-	fmt.Println()
-	fmt.Println("Examples:")
-	fmt.Println("  picoclaw auth login --provider openai")
-	fmt.Println("  picoclaw auth login --provider openai --device-code")
-	fmt.Println("  picoclaw auth login --provider anthropic")
-	fmt.Println("  picoclaw auth login --provider google-antigravity")
-	fmt.Println("  picoclaw auth models")
-	fmt.Println("  picoclaw auth logout --provider openai")
-	fmt.Println("  picoclaw auth status")
-}
-
-func authLoginCmd() {
-	provider := ""
-	useDeviceCode := false
-
-	args := os.Args[3:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--provider", "-p":
-			if i+1 < len(args) {
-				provider = args[i+1]
-				i++
-			}
-		case "--device-code":
-			useDeviceCode = true
-		}
-	}
-
-	if provider == "" {
-		fmt.Println("Error: --provider is required")
-		fmt.Println(supportedProvidersMsg)
-		return
-	}
+const (
+	supportedProvidersMsg = "supported providers: openai, anthropic, google-antigravity"
+	defaultAnthropicModel = "claude-sonnet-4.6"
+)
 
+func authLoginCmd(provider string, useDeviceCode bool, useOauth bool) error {
 	switch provider {
 	case "openai":
-		authLoginOpenAI(useDeviceCode)
+		return authLoginOpenAI(useDeviceCode)
 	case "anthropic":
-		authLoginPasteToken(provider)
+		return authLoginAnthropic(useOauth)
 	case "google-antigravity", "antigravity":
-		authLoginGoogleAntigravity()
+		return authLoginGoogleAntigravity()
 	default:
-		fmt.Printf("Unsupported provider: %s\n", provider)
-		fmt.Println(supportedProvidersMsg)
+		return fmt.Errorf("unsupported provider: %s (%s)", provider, supportedProvidersMsg)
 	}
 }
 
-func authLoginOpenAI(useDeviceCode bool) {
+func authLoginOpenAI(useDeviceCode bool) error {
 	cfg := auth.OpenAIOAuthConfig()
 
 	var cred *auth.AuthCredential
@@ -110,16 +47,14 @@ func authLoginOpenAI(useDeviceCode bool) {
 	}
 
 	if err != nil {
-		fmt.Printf("Login failed: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("login failed: %w", err)
 	}
 
 	if err = auth.SetCredential("openai", cred); err != nil {
-		fmt.Printf("Failed to save credentials: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to save credentials: %w", err)
 	}
 
-	appCfg, err := loadConfig()
+	appCfg, err := internal.LoadConfig()
 	if err == nil {
 		// Update Providers (legacy format)
 		appCfg.Providers.OpenAI.AuthMethod = "oauth"
@@ -144,10 +79,10 @@ func authLoginOpenAI(useDeviceCode bool) {
 		}
 
 		// Update default model to use OpenAI
-		appCfg.Agents.Defaults.Model = "gpt-5.2"
+		appCfg.Agents.Defaults.ModelName = "gpt-5.2"
 
-		if err := config.SaveConfig(getConfigPath(), appCfg); err != nil {
-			fmt.Printf("Warning: could not update config: %v\n", err)
+		if err = config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
+			return fmt.Errorf("could not update config: %w", err)
 		}
 	}
 
@@ -156,15 +91,16 @@ func authLoginOpenAI(useDeviceCode bool) {
 		fmt.Printf("Account: %s\n", cred.AccountID)
 	}
 	fmt.Println("Default model set to: gpt-5.2")
+
+	return nil
 }
 
-func authLoginGoogleAntigravity() {
+func authLoginGoogleAntigravity() error {
 	cfg := auth.GoogleAntigravityOAuthConfig()
 
 	cred, err := auth.LoginBrowser(cfg)
 	if err != nil {
-		fmt.Printf("Login failed: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("login failed: %w", err)
 	}
 
 	cred.Provider = "google-antigravity"
@@ -189,11 +125,10 @@ func authLoginGoogleAntigravity() {
 	}
 
 	if err = auth.SetCredential("google-antigravity", cred); err != nil {
-		fmt.Printf("Failed to save credentials: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to save credentials: %w", err)
 	}
 
-	appCfg, err := loadConfig()
+	appCfg, err := internal.LoadConfig()
 	if err == nil {
 		// Update Providers (legacy format, for backward compatibility)
 		appCfg.Providers.Antigravity.AuthMethod = "oauth"
@@ -218,9 +153,9 @@ func authLoginGoogleAntigravity() {
 		}
 
 		// Update default model
-		appCfg.Agents.Defaults.Model = "gemini-flash"
+		appCfg.Agents.Defaults.ModelName = "gemini-flash"
 
-		if err := config.SaveConfig(getConfigPath(), appCfg); err != nil {
+		if err := config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
 			fmt.Printf("Warning: could not update config: %v\n", err)
 		}
 	}
@@ -228,6 +163,83 @@ func authLoginGoogleAntigravity() {
 	fmt.Println("\n✓ Google Antigravity login successful!")
 	fmt.Println("Default model set to: gemini-flash")
 	fmt.Println("Try it: picoclaw agent -m \"Hello world\"")
+
+	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 {
+		appCfg.Providers.Anthropic.AuthMethod = "oauth"
+
+		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) {
@@ -244,7 +256,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))
 	}
@@ -258,19 +273,17 @@ func fetchGoogleUserEmail(accessToken string) (string, error) {
 	return userInfo.Email, nil
 }
 
-func authLoginPasteToken(provider string) {
+func authLoginPasteToken(provider string) error {
 	cred, err := auth.LoginPasteToken(provider, os.Stdin)
 	if err != nil {
-		fmt.Printf("Login failed: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("login failed: %w", err)
 	}
 
 	if err = auth.SetCredential(provider, cred); err != nil {
-		fmt.Printf("Failed to save credentials: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to save credentials: %w", err)
 	}
 
-	appCfg, err := loadConfig()
+	appCfg, err := internal.LoadConfig()
 	if err == nil {
 		switch provider {
 		case "anthropic":
@@ -286,13 +299,12 @@ func authLoginPasteToken(provider string) {
 			}
 			if !found {
 				appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
-					ModelName:  "claude-sonnet-4.6",
-					Model:      "anthropic/claude-sonnet-4.6",
+					ModelName:  defaultAnthropicModel,
+					Model:      "anthropic/" + defaultAnthropicModel,
 					AuthMethod: "token",
 				})
+				appCfg.Agents.Defaults.ModelName = defaultAnthropicModel
 			}
-			// Update default model
-			appCfg.Agents.Defaults.Model = "claude-sonnet-4.6"
 		case "openai":
 			appCfg.Providers.OpenAI.AuthMethod = "token"
 			// Update ModelList
@@ -312,38 +324,29 @@ func authLoginPasteToken(provider string) {
 				})
 			}
 			// Update default model
-			appCfg.Agents.Defaults.Model = "gpt-5.2"
+			appCfg.Agents.Defaults.ModelName = "gpt-5.2"
 		}
-		if err := config.SaveConfig(getConfigPath(), appCfg); err != nil {
-			fmt.Printf("Warning: could not update config: %v\n", err)
+		if err := config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
+			return fmt.Errorf("could not update config: %w", err)
 		}
 	}
 
 	fmt.Printf("Token saved for %s!\n", provider)
-	fmt.Printf("Default model set to: %s\n", appCfg.Agents.Defaults.Model)
-}
 
-func authLogoutCmd() {
-	provider := ""
-
-	args := os.Args[3:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--provider", "-p":
-			if i+1 < len(args) {
-				provider = args[i+1]
-				i++
-			}
-		}
+	if appCfg != nil {
+		fmt.Printf("Default model set to: %s\n", appCfg.Agents.Defaults.GetModelName())
 	}
 
+	return nil
+}
+
+func authLogoutCmd(provider string) error {
 	if provider != "" {
 		if err := auth.DeleteCredential(provider); err != nil {
-			fmt.Printf("Failed to remove credentials: %v\n", err)
-			os.Exit(1)
+			return fmt.Errorf("failed to remove credentials: %w", err)
 		}
 
-		appCfg, err := loadConfig()
+		appCfg, err := internal.LoadConfig()
 		if err == nil {
 			// Clear AuthMethod in ModelList
 			for i := range appCfg.ModelList {
@@ -371,44 +374,46 @@ func authLogoutCmd() {
 			case "google-antigravity", "antigravity":
 				appCfg.Providers.Antigravity.AuthMethod = ""
 			}
-			config.SaveConfig(getConfigPath(), appCfg)
+			config.SaveConfig(internal.GetConfigPath(), appCfg)
 		}
 
 		fmt.Printf("Logged out from %s\n", provider)
-	} else {
-		if err := auth.DeleteAllCredentials(); err != nil {
-			fmt.Printf("Failed to remove credentials: %v\n", err)
-			os.Exit(1)
-		}
 
-		appCfg, err := loadConfig()
-		if err == nil {
-			// Clear all AuthMethods in ModelList
-			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(getConfigPath(), appCfg)
-		}
-
-		fmt.Println("Logged out from all providers")
+		return nil
 	}
+
+	if err := auth.DeleteAllCredentials(); err != nil {
+		return fmt.Errorf("failed to remove credentials: %w", err)
+	}
+
+	appCfg, err := internal.LoadConfig()
+	if err == nil {
+		// Clear all AuthMethods in ModelList
+		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)
+	}
+
+	fmt.Println("Logged out from all providers")
+
+	return nil
 }
 
-func authStatusCmd() {
+func authStatusCmd() error {
 	store, err := auth.LoadStore()
 	if err != nil {
-		fmt.Printf("Error loading auth store: %v\n", err)
-		return
+		return fmt.Errorf("failed to load auth store: %w", err)
 	}
 
 	if len(store.Credentials) == 0 {
 		fmt.Println("No authenticated providers.")
 		fmt.Println("Run: picoclaw auth login --provider <name>")
-		return
+		return nil
 	}
 
 	fmt.Println("\nAuthenticated Providers:")
@@ -436,15 +441,27 @@ func authStatusCmd() {
 		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
 }
 
-func authModelsCmd() {
+func authModelsCmd() error {
 	cred, err := auth.GetCredential("google-antigravity")
 	if err != nil || cred == nil {
-		fmt.Println("Not logged in to Google Antigravity.")
-		fmt.Println("Run: picoclaw auth login --provider google-antigravity")
-		return
+		return fmt.Errorf(
+			"not logged in to Google Antigravity.\nrun: picoclaw auth login --provider google-antigravity",
+		)
 	}
 
 	// Refresh token if needed
@@ -459,21 +476,18 @@ func authModelsCmd() {
 
 	projectID := cred.ProjectID
 	if projectID == "" {
-		fmt.Println("No project ID stored. Try logging in again.")
-		return
+		return fmt.Errorf("no project id stored. Try logging in again")
 	}
 
 	fmt.Printf("Fetching models for project: %s\n\n", projectID)
 
 	models, err := providers.FetchAntigravityModels(cred.AccessToken, projectID)
 	if err != nil {
-		fmt.Printf("Error fetching models: %v\n", err)
-		return
+		return fmt.Errorf("error fetching models: %w", err)
 	}
 
 	if len(models) == 0 {
-		fmt.Println("No models available.")
-		return
+		return fmt.Errorf("no models available")
 	}
 
 	fmt.Println("Available Antigravity Models:")
@@ -489,6 +503,8 @@ func authModelsCmd() {
 		}
 		fmt.Printf("  %s %s\n", status, name)
 	}
+
+	return nil
 }
 
 // isAntigravityModel checks if a model string belongs to antigravity provider
diff --git a/cmd/picoclaw/internal/auth/login.go b/cmd/picoclaw/internal/auth/login.go
new file mode 100644
index 000000000..afbe098aa
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/login.go
@@ -0,0 +1,30 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newLoginCommand() *cobra.Command {
+	var (
+		provider      string
+		useDeviceCode bool
+		useOauth      bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Login via OAuth or paste token",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			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/login_test.go b/cmd/picoclaw/internal/auth/login_test.go
new file mode 100644
index 000000000..d6a03c25b
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/login_test.go
@@ -0,0 +1,29 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewLoginSubCommand(t *testing.T) {
+	cmd := newLoginCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Login via OAuth or paste token", cmd.Short)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("device-code"))
+
+	providerFlag := cmd.Flags().Lookup("provider")
+	require.NotNil(t, providerFlag)
+
+	val, found := providerFlag.Annotations[cobra.BashCompOneRequiredFlag]
+	require.True(t, found)
+	require.NotEmpty(t, val)
+	assert.Equal(t, "true", val[0])
+}
diff --git a/cmd/picoclaw/internal/auth/logout.go b/cmd/picoclaw/internal/auth/logout.go
new file mode 100644
index 000000000..384667524
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/logout.go
@@ -0,0 +1,20 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newLogoutCommand() *cobra.Command {
+	var provider string
+
+	cmd := &cobra.Command{
+		Use:   "logout",
+		Short: "Remove stored credentials",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authLogoutCmd(provider)
+		},
+	}
+
+	cmd.Flags().StringVarP(&provider, "provider", "p", "", "Provider to logout from (openai, anthropic); empty = all")
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/auth/logout_test.go b/cmd/picoclaw/internal/auth/logout_test.go
new file mode 100644
index 000000000..c0f3a5e92
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/logout_test.go
@@ -0,0 +1,20 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewLogoutSubcommand(t *testing.T) {
+	cmd := newLogoutCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Remove stored credentials", cmd.Short)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("provider"))
+}
diff --git a/cmd/picoclaw/internal/auth/models.go b/cmd/picoclaw/internal/auth/models.go
new file mode 100644
index 000000000..cabe6822c
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/models.go
@@ -0,0 +1,15 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newModelsCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "models",
+		Short: "Show available models",
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return authModelsCmd()
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/auth/models_test.go b/cmd/picoclaw/internal/auth/models_test.go
new file mode 100644
index 000000000..26ca67787
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/models_test.go
@@ -0,0 +1,19 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewModelsCommand(t *testing.T) {
+	cmd := newModelsCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "models", cmd.Use)
+	assert.Equal(t, "Show available models", cmd.Short)
+
+	assert.False(t, cmd.HasFlags())
+}
diff --git a/cmd/picoclaw/internal/auth/status.go b/cmd/picoclaw/internal/auth/status.go
new file mode 100644
index 000000000..ca3007d12
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/status.go
@@ -0,0 +1,16 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newStatusCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "status",
+		Short: "Show current auth status",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authStatusCmd()
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/auth/status_test.go b/cmd/picoclaw/internal/auth/status_test.go
new file mode 100644
index 000000000..7748ba502
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/status_test.go
@@ -0,0 +1,18 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewStatusSubcommand(t *testing.T) {
+	cmd := newStatusCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Show current auth status", cmd.Short)
+
+	assert.False(t, cmd.HasFlags())
+}
diff --git a/cmd/picoclaw/internal/cron/add.go b/cmd/picoclaw/internal/cron/add.go
new file mode 100644
index 000000000..947557d5a
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/add.go
@@ -0,0 +1,64 @@
+package cron
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/cron"
+)
+
+func newAddCommand(storePath func() string) *cobra.Command {
+	var (
+		name    string
+		message string
+		every   int64
+		cronExp string
+		deliver bool
+		channel string
+		to      string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "add",
+		Short: "Add a new scheduled job",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if every <= 0 && cronExp == "" {
+				return fmt.Errorf("either --every or --cron must be specified")
+			}
+
+			var schedule cron.CronSchedule
+			if every > 0 {
+				everyMS := every * 1000
+				schedule = cron.CronSchedule{Kind: "every", EveryMS: &everyMS}
+			} else {
+				schedule = cron.CronSchedule{Kind: "cron", Expr: cronExp}
+			}
+
+			cs := cron.NewCronService(storePath(), nil)
+			job, err := cs.AddJob(name, schedule, message, deliver, channel, to)
+			if err != nil {
+				return fmt.Errorf("error adding job: %w", err)
+			}
+
+			fmt.Printf("✓ Added job '%s' (%s)\n", job.Name, job.ID)
+
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVarP(&name, "name", "n", "", "Job name")
+	cmd.Flags().StringVarP(&message, "message", "m", "", "Message for agent")
+	cmd.Flags().Int64VarP(&every, "every", "e", 0, "Run every N seconds")
+	cmd.Flags().StringVarP(&cronExp, "cron", "c", "", "Cron expression (e.g. '0 9 * * *')")
+	cmd.Flags().BoolVarP(&deliver, "deliver", "d", false, "Deliver response to channel")
+	cmd.Flags().StringVar(&to, "to", "", "Recipient for delivery")
+	cmd.Flags().StringVar(&channel, "channel", "", "Channel for delivery")
+
+	_ = cmd.MarkFlagRequired("name")
+	_ = cmd.MarkFlagRequired("message")
+	cmd.MarkFlagsMutuallyExclusive("every", "cron")
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/cron/add_test.go b/cmd/picoclaw/internal/cron/add_test.go
new file mode 100644
index 000000000..09701fab5
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/add_test.go
@@ -0,0 +1,57 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewAddSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newAddCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "add", cmd.Use)
+	assert.Equal(t, "Add a new scheduled job", cmd.Short)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("every"))
+	assert.NotNil(t, cmd.Flags().Lookup("cron"))
+	assert.NotNil(t, cmd.Flags().Lookup("deliver"))
+	assert.NotNil(t, cmd.Flags().Lookup("to"))
+	assert.NotNil(t, cmd.Flags().Lookup("channel"))
+
+	nameFlag := cmd.Flags().Lookup("name")
+	require.NotNil(t, nameFlag)
+
+	messageFlag := cmd.Flags().Lookup("message")
+	require.NotNil(t, messageFlag)
+
+	val, found := nameFlag.Annotations[cobra.BashCompOneRequiredFlag]
+	require.True(t, found)
+	require.NotEmpty(t, val)
+	assert.Equal(t, "true", val[0])
+
+	val, found = messageFlag.Annotations[cobra.BashCompOneRequiredFlag]
+	require.True(t, found)
+	require.NotEmpty(t, val)
+	assert.Equal(t, "true", val[0])
+}
+
+func TestNewAddCommandEveryAndCronMutuallyExclusive(t *testing.T) {
+	cmd := newAddCommand(func() string { return "testing" })
+
+	cmd.SetArgs([]string{
+		"--name", "job",
+		"--message", "hello",
+		"--every", "10",
+		"--cron", "0 9 * * *",
+	})
+
+	err := cmd.Execute()
+	require.Error(t, err)
+}
diff --git a/cmd/picoclaw/internal/cron/command.go b/cmd/picoclaw/internal/cron/command.go
new file mode 100644
index 000000000..39f8ccf28
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/command.go
@@ -0,0 +1,44 @@
+package cron
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func NewCronCommand() *cobra.Command {
+	var storePath string
+
+	cmd := &cobra.Command{
+		Use:     "cron",
+		Aliases: []string{"c"},
+		Short:   "Manage scheduled tasks",
+		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+		// Resolve storePath at execution time so it reflects the current config
+		// and is shared across all subcommands.
+		PersistentPreRunE: func(_ *cobra.Command, _ []string) error {
+			cfg, err := internal.LoadConfig()
+			if err != nil {
+				return fmt.Errorf("error loading config: %w", err)
+			}
+			storePath = filepath.Join(cfg.WorkspacePath(), "cron", "jobs.json")
+			return nil
+		},
+	}
+
+	cmd.AddCommand(
+		newListCommand(func() string { return storePath }),
+		newAddCommand(func() string { return storePath }),
+		newRemoveCommand(func() string { return storePath }),
+		newEnableCommand(func() string { return storePath }),
+		newDisableCommand(func() string { return storePath }),
+	)
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/cron/command_test.go b/cmd/picoclaw/internal/cron/command_test.go
new file mode 100644
index 000000000..af2ac83ae
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/command_test.go
@@ -0,0 +1,58 @@
+package cron
+
+import (
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewCronCommand(t *testing.T) {
+	cmd := NewCronCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Manage scheduled tasks", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("c"))
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.NotNil(t, cmd.PersistentPreRunE)
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.True(t, cmd.HasSubCommands())
+
+	allowedCommands := []string{
+		"list",
+		"add",
+		"remove",
+		"enable",
+		"disable",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+
+		assert.Len(t, subcmd.Aliases, 0)
+		assert.False(t, subcmd.Hidden)
+
+		assert.False(t, subcmd.HasSubCommands())
+
+		assert.Nil(t, subcmd.Run)
+		assert.NotNil(t, subcmd.RunE)
+
+		assert.Nil(t, subcmd.PersistentPreRun)
+		assert.Nil(t, subcmd.PersistentPostRun)
+	}
+}
diff --git a/cmd/picoclaw/internal/cron/disable.go b/cmd/picoclaw/internal/cron/disable.go
new file mode 100644
index 000000000..a3670fd50
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/disable.go
@@ -0,0 +1,16 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newDisableCommand(storePath func() string) *cobra.Command {
+	return &cobra.Command{
+		Use:     "disable",
+		Short:   "Disable a job",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw cron disable 1`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronSetJobEnabled(storePath(), args[0], false)
+			return nil
+		},
+	}
+}
diff --git a/cmd/picoclaw/internal/cron/disable_test.go b/cmd/picoclaw/internal/cron/disable_test.go
new file mode 100644
index 000000000..e5d2ff844
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/disable_test.go
@@ -0,0 +1,20 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDisableSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newDisableCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "disable", cmd.Use)
+	assert.Equal(t, "Disable a job", cmd.Short)
+
+	assert.True(t, cmd.HasExample())
+}
diff --git a/cmd/picoclaw/internal/cron/enable.go b/cmd/picoclaw/internal/cron/enable.go
new file mode 100644
index 000000000..7f8b05233
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/enable.go
@@ -0,0 +1,16 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newEnableCommand(storePath func() string) *cobra.Command {
+	return &cobra.Command{
+		Use:     "enable",
+		Short:   "Enable a job",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw cron enable 1`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronSetJobEnabled(storePath(), args[0], true)
+			return nil
+		},
+	}
+}
diff --git a/cmd/picoclaw/internal/cron/enable_test.go b/cmd/picoclaw/internal/cron/enable_test.go
new file mode 100644
index 000000000..85a2e01aa
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/enable_test.go
@@ -0,0 +1,20 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEnableSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newEnableCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "enable", cmd.Use)
+	assert.Equal(t, "Enable a job", cmd.Short)
+
+	assert.True(t, cmd.HasExample())
+}
diff --git a/cmd/picoclaw/internal/cron/helpers.go b/cmd/picoclaw/internal/cron/helpers.go
new file mode 100644
index 000000000..88bdf1bf7
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/helpers.go
@@ -0,0 +1,66 @@
+package cron
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/cron"
+)
+
+func cronListCmd(storePath string) {
+	cs := cron.NewCronService(storePath, nil)
+	jobs := cs.ListJobs(true) // Show all jobs, including disabled
+
+	if len(jobs) == 0 {
+		fmt.Println("No scheduled jobs.")
+		return
+	}
+
+	fmt.Println("\nScheduled Jobs:")
+	fmt.Println("----------------")
+	for _, job := range jobs {
+		var schedule string
+		if job.Schedule.Kind == "every" && job.Schedule.EveryMS != nil {
+			schedule = fmt.Sprintf("every %ds", *job.Schedule.EveryMS/1000)
+		} else if job.Schedule.Kind == "cron" {
+			schedule = job.Schedule.Expr
+		} else {
+			schedule = "one-time"
+		}
+
+		nextRun := "scheduled"
+		if job.State.NextRunAtMS != nil {
+			nextTime := time.UnixMilli(*job.State.NextRunAtMS)
+			nextRun = nextTime.Format("2006-01-02 15:04")
+		}
+
+		status := "enabled"
+		if !job.Enabled {
+			status = "disabled"
+		}
+
+		fmt.Printf("  %s (%s)\n", job.Name, job.ID)
+		fmt.Printf("    Schedule: %s\n", schedule)
+		fmt.Printf("    Status: %s\n", status)
+		fmt.Printf("    Next run: %s\n", nextRun)
+	}
+}
+
+func cronRemoveCmd(storePath, jobID string) {
+	cs := cron.NewCronService(storePath, nil)
+	if cs.RemoveJob(jobID) {
+		fmt.Printf("✓ Removed job %s\n", jobID)
+	} else {
+		fmt.Printf("✗ Job %s not found\n", jobID)
+	}
+}
+
+func cronSetJobEnabled(storePath, jobID string, enabled bool) {
+	cs := cron.NewCronService(storePath, nil)
+	job := cs.EnableJob(jobID, enabled)
+	if job != nil {
+		fmt.Printf("✓ Job '%s' enabled\n", job.Name)
+	} else {
+		fmt.Printf("✗ Job %s not found\n", jobID)
+	}
+}
diff --git a/cmd/picoclaw/internal/cron/list.go b/cmd/picoclaw/internal/cron/list.go
new file mode 100644
index 000000000..854eb1a44
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/list.go
@@ -0,0 +1,17 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newListCommand(storePath func() string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List all scheduled jobs",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			cronListCmd(storePath())
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/cron/list_test.go b/cmd/picoclaw/internal/cron/list_test.go
new file mode 100644
index 000000000..0b9d1bd59
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/list_test.go
@@ -0,0 +1,17 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewListSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newListCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "List all scheduled jobs", cmd.Short)
+}
diff --git a/cmd/picoclaw/internal/cron/remove.go b/cmd/picoclaw/internal/cron/remove.go
new file mode 100644
index 000000000..5f1d1a04b
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/remove.go
@@ -0,0 +1,18 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newRemoveCommand(storePath func() string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "remove",
+		Short:   "Remove a job by ID",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw cron remove 1`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronRemoveCmd(storePath(), args[0])
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/cron/remove_test.go b/cmd/picoclaw/internal/cron/remove_test.go
new file mode 100644
index 000000000..36121f370
--- /dev/null
+++ b/cmd/picoclaw/internal/cron/remove_test.go
@@ -0,0 +1,19 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewRemoveSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newRemoveCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Remove a job by ID", cmd.Short)
+
+	assert.True(t, cmd.HasExample())
+}
diff --git a/cmd/picoclaw/internal/gateway/command.go b/cmd/picoclaw/internal/gateway/command.go
new file mode 100644
index 000000000..66a56f9ce
--- /dev/null
+++ b/cmd/picoclaw/internal/gateway/command.go
@@ -0,0 +1,23 @@
+package gateway
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewGatewayCommand() *cobra.Command {
+	var debug bool
+
+	cmd := &cobra.Command{
+		Use:     "gateway",
+		Aliases: []string{"g"},
+		Short:   "Start picoclaw gateway",
+		Args:    cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return gatewayCmd(debug)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&debug, "debug", "d", false, "Enable debug logging")
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/gateway/command_test.go b/cmd/picoclaw/internal/gateway/command_test.go
new file mode 100644
index 000000000..4d591ea67
--- /dev/null
+++ b/cmd/picoclaw/internal/gateway/command_test.go
@@ -0,0 +1,31 @@
+package gateway
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewGatewayCommand(t *testing.T) {
+	cmd := NewGatewayCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "gateway", cmd.Use)
+	assert.Equal(t, "Start picoclaw gateway", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("g"))
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.True(t, cmd.HasFlags())
+	assert.NotNil(t, cmd.Flags().Lookup("debug"))
+}
diff --git a/cmd/picoclaw/cmd_gateway.go b/cmd/picoclaw/internal/gateway/helpers.go
similarity index 59%
rename from cmd/picoclaw/cmd_gateway.go
rename to cmd/picoclaw/internal/gateway/helpers.go
index 28ef76ad3..4f93b858a 100644
--- a/cmd/picoclaw/cmd_gateway.go
+++ b/cmd/picoclaw/internal/gateway/helpers.go
@@ -1,58 +1,65 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package gateway
 
 import (
 	"context"
 	"fmt"
-	"net/http"
+	"log"
 	"os"
 	"os/signal"
 	"path/filepath"
-	"strings"
 	"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/irc"
+	_ "github.com/sipeed/picoclaw/pkg/channels/line"
+	_ "github.com/sipeed/picoclaw/pkg/channels/maixcam"
+	_ "github.com/sipeed/picoclaw/pkg/channels/matrix"
+	_ "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"
 	"github.com/sipeed/picoclaw/pkg/voice"
 )
 
-func gatewayCmd() {
-	// Check for --debug flag
-	args := os.Args[2:]
-	for _, arg := range args {
-		if arg == "--debug" || arg == "-d" {
-			logger.SetLevel(logger.DEBUG)
-			fmt.Println("🔍 Debug mode enabled")
-			break
-		}
+func gatewayCmd(debug bool) error {
+	if debug {
+		logger.SetLevel(logger.DEBUG)
+		fmt.Println("🔍 Debug mode enabled")
 	}
 
-	cfg, err := loadConfig()
+	cfg, err := internal.LoadConfig()
 	if err != nil {
-		fmt.Printf("Error loading config: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error loading config: %w", err)
 	}
 
 	provider, modelID, err := providers.CreateProvider(cfg)
 	if err != nil {
-		fmt.Printf("Error creating provider: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error creating provider: %w", err)
 	}
+
 	// Use the resolved model ID from provider creation
 	if modelID != "" {
-		cfg.Agents.Defaults.Model = modelID
+		cfg.Agents.Defaults.ModelName = modelID
 	}
 
 	msgBus := bus.NewMessageBus()
@@ -112,49 +119,28 @@ func gatewayCmd() {
 		return tools.SilentResult(response)
 	})
 
-	channelManager, err := channels.NewManager(cfg, msgBus)
+	// 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 {
-		fmt.Printf("Error creating channel manager: %v\n", err)
-		os.Exit(1)
+		mediaStore.Stop()
+		return fmt.Errorf("error creating channel manager: %w", err)
 	}
 
-	// Inject channel manager into agent loop for command handling
+	// Inject channel manager and media store into agent loop
 	agentLoop.SetChannelManager(channelManager)
+	agentLoop.SetMediaStore(mediaStore)
 
-	var transcriber *voice.GroqTranscriber
-	groqAPIKey := cfg.Providers.Groq.APIKey
-	if groqAPIKey == "" {
-		for _, mc := range cfg.ModelList {
-			if strings.HasPrefix(mc.Model, "groq/") && mc.APIKey != "" {
-				groqAPIKey = mc.APIKey
-				break
-			}
-		}
-	}
-	if groqAPIKey != "" {
-		transcriber = voice.NewGroqTranscriber(groqAPIKey)
-		logger.InfoC("voice", "Groq voice transcription enabled")
-	}
-
-	if transcriber != nil {
-		if telegramChannel, ok := channelManager.GetChannel("telegram"); ok {
-			if tc, ok := telegramChannel.(*channels.TelegramChannel); ok {
-				tc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Telegram channel")
-			}
-		}
-		if discordChannel, ok := channelManager.GetChannel("discord"); ok {
-			if dc, ok := discordChannel.(*channels.DiscordChannel); ok {
-				dc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Discord channel")
-			}
-		}
-		if slackChannel, ok := channelManager.GetChannel("slack"); ok {
-			if sc, ok := slackChannel.(*channels.SlackChannel); ok {
-				sc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Slack channel")
-			}
-		}
+	// Wire up voice transcription if a supported provider is configured.
+	if transcriber := voice.DetectTranscriber(cfg); transcriber != nil {
+		agentLoop.SetTranscriber(transcriber)
+		logger.InfoCF("voice", "Transcription enabled (agent-level)", map[string]any{"provider": transcriber.Name()})
 	}
 
 	enabledChannels := channelManager.GetEnabledChannels()
@@ -192,16 +178,16 @@ func gatewayCmd() {
 		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
 	}
 
-	healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
-	go func() {
-		if err := healthServer.Start(); err != nil && err != http.ErrServerClosed {
-			logger.ErrorCF("health", "Health server error", map[string]any{"error": err.Error()})
-		}
-	}()
 	fmt.Printf("✓ Health endpoints available at http://%s:%d/health and /ready\n", cfg.Gateway.Host, cfg.Gateway.Port)
 
 	go agentLoop.Run(ctx)
@@ -211,14 +197,26 @@ func gatewayCmd() {
 	<-sigChan
 
 	fmt.Println("\nShutting down...")
+	if cp, ok := provider.(providers.StatefulProvider); ok {
+		cp.Close()
+	}
 	cancel()
-	healthServer.Stop(context.Background())
+	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()
-	channelManager.StopAll(ctx)
 	fmt.Println("✓ Gateway stopped")
+
+	return nil
 }
 
 func setupCronTool(
@@ -234,15 +232,25 @@ func setupCronTool(
 	// Create cron service
 	cronService := cron.NewCronService(cronStorePath, nil)
 
-	// Create and register CronTool
-	cronTool := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, cfg)
-	agentLoop.RegisterTool(cronTool)
+	// Create and register CronTool if enabled
+	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 {
+			log.Fatalf("Critical error during CronTool initialization: %v", err)
+		}
 
-	// Set the onJob handler
-	cronService.SetOnJob(func(job *cron.CronJob) (string, error) {
-		result := cronTool.ExecuteJob(context.Background(), job)
-		return result, nil
-	})
+		agentLoop.RegisterTool(cronTool)
+	}
+
+	// Set onJob handler
+	if cronTool != nil {
+		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
new file mode 100644
index 000000000..f81d7013d
--- /dev/null
+++ b/cmd/picoclaw/internal/helpers.go
@@ -0,0 +1,64 @@
+package internal
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const Logo = "🦞"
+
+var (
+	version   = "dev"
+	gitCommit string
+	buildTime string
+	goVersion string
+)
+
+// GetPicoclawHome returns the picoclaw home directory.
+// Priority: $PICOCLAW_HOME > ~/.picoclaw
+func GetPicoclawHome() string {
+	if home := os.Getenv("PICOCLAW_HOME"); home != "" {
+		return home
+	}
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".picoclaw")
+}
+
+func GetConfigPath() string {
+	if configPath := os.Getenv("PICOCLAW_CONFIG"); configPath != "" {
+		return configPath
+	}
+	return filepath.Join(GetPicoclawHome(), "config.json")
+}
+
+func LoadConfig() (*config.Config, error) {
+	return config.LoadConfig(GetConfigPath())
+}
+
+// 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/cmd/picoclaw/internal/helpers_test.go b/cmd/picoclaw/internal/helpers_test.go
new file mode 100644
index 000000000..646be1ba1
--- /dev/null
+++ b/cmd/picoclaw/internal/helpers_test.go
@@ -0,0 +1,128 @@
+package internal
+
+import (
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetConfigPath(t *testing.T) {
+	t.Setenv("HOME", "/tmp/home")
+
+	got := GetConfigPath()
+	want := filepath.Join("/tmp/home", ".picoclaw", "config.json")
+
+	assert.Equal(t, want, got)
+}
+
+func TestGetConfigPath_WithPICOCLAW_HOME(t *testing.T) {
+	t.Setenv("PICOCLAW_HOME", "/custom/picoclaw")
+	t.Setenv("HOME", "/tmp/home")
+
+	got := GetConfigPath()
+	want := filepath.Join("/custom/picoclaw", "config.json")
+
+	assert.Equal(t, want, got)
+}
+
+func TestGetConfigPath_WithPICOCLAW_CONFIG(t *testing.T) {
+	t.Setenv("PICOCLAW_CONFIG", "/custom/config.json")
+	t.Setenv("PICOCLAW_HOME", "/custom/picoclaw")
+	t.Setenv("HOME", "/tmp/home")
+
+	got := GetConfigPath()
+	want := "/custom/config.json"
+
+	assert.Equal(t, want, got)
+}
+
+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 TestGetConfigPath_Windows(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("windows-specific HOME behavior varies; run on windows")
+	}
+
+	testUserProfilePath := `C:\Users\Test`
+	t.Setenv("USERPROFILE", testUserProfilePath)
+
+	got := GetConfigPath()
+	want := filepath.Join(testUserProfilePath, ".picoclaw", "config.json")
+
+	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/migrate/command.go b/cmd/picoclaw/internal/migrate/command.go
new file mode 100644
index 000000000..76352c9db
--- /dev/null
+++ b/cmd/picoclaw/internal/migrate/command.go
@@ -0,0 +1,52 @@
+package migrate
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/migrate"
+)
+
+func NewMigrateCommand() *cobra.Command {
+	var opts migrate.Options
+
+	cmd := &cobra.Command{
+		Use:   "migrate",
+		Short: "Migrate from xxxclaw(openclaw, etc.) to picoclaw",
+		Args:  cobra.NoArgs,
+		Example: `  picoclaw migrate
+  picoclaw migrate --from openclaw
+  picoclaw migrate --dry-run
+  picoclaw migrate --refresh
+  picoclaw migrate --force`,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			m := migrate.NewMigrateInstance(opts)
+			result, err := m.Run(opts)
+			if err != nil {
+				return err
+			}
+			if !opts.DryRun {
+				m.PrintSummary(result)
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false,
+		"Show what would be migrated without making changes")
+	cmd.Flags().StringVar(&opts.Source, "from", "openclaw",
+		"Source to migrate from (e.g., openclaw)")
+	cmd.Flags().BoolVar(&opts.Refresh, "refresh", false,
+		"Re-sync workspace files from OpenClaw (repeatable)")
+	cmd.Flags().BoolVar(&opts.ConfigOnly, "config-only", false,
+		"Only migrate config, skip workspace files")
+	cmd.Flags().BoolVar(&opts.WorkspaceOnly, "workspace-only", false,
+		"Only migrate workspace files, skip config")
+	cmd.Flags().BoolVar(&opts.Force, "force", false,
+		"Skip confirmation prompts")
+	cmd.Flags().StringVar(&opts.SourceHome, "source-home", "",
+		"Override source home directory (default: ~/.openclaw)")
+	cmd.Flags().StringVar(&opts.TargetHome, "target-home", "",
+		"Override target home directory (default: ~/.picoclaw)")
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/migrate/command_test.go b/cmd/picoclaw/internal/migrate/command_test.go
new file mode 100644
index 000000000..5110249a2
--- /dev/null
+++ b/cmd/picoclaw/internal/migrate/command_test.go
@@ -0,0 +1,38 @@
+package migrate
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewMigrateCommand(t *testing.T) {
+	cmd := NewMigrateCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "migrate", cmd.Use)
+	assert.Equal(t, "Migrate from xxxclaw(openclaw, etc.) to picoclaw", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("dry-run"))
+	assert.NotNil(t, cmd.Flags().Lookup("refresh"))
+	assert.NotNil(t, cmd.Flags().Lookup("config-only"))
+	assert.NotNil(t, cmd.Flags().Lookup("workspace-only"))
+	assert.NotNil(t, cmd.Flags().Lookup("force"))
+	assert.NotNil(t, cmd.Flags().Lookup("source-home"))
+	assert.NotNil(t, cmd.Flags().Lookup("target-home"))
+}
diff --git a/cmd/picoclaw/internal/onboard/command.go b/cmd/picoclaw/internal/onboard/command.go
new file mode 100644
index 000000000..ec1012959
--- /dev/null
+++ b/cmd/picoclaw/internal/onboard/command.go
@@ -0,0 +1,24 @@
+package onboard
+
+import (
+	"embed"
+
+	"github.com/spf13/cobra"
+)
+
+//go:generate cp -r ../../../../workspace .
+//go:embed workspace
+var embeddedFiles embed.FS
+
+func NewOnboardCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "onboard",
+		Aliases: []string{"o"},
+		Short:   "Initialize picoclaw configuration and workspace",
+		Run: func(cmd *cobra.Command, args []string) {
+			onboard()
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/onboard/command_test.go b/cmd/picoclaw/internal/onboard/command_test.go
new file mode 100644
index 000000000..bc799a079
--- /dev/null
+++ b/cmd/picoclaw/internal/onboard/command_test.go
@@ -0,0 +1,29 @@
+package onboard
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewOnboardCommand(t *testing.T) {
+	cmd := NewOnboardCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "onboard", cmd.Use)
+	assert.Equal(t, "Initialize picoclaw configuration and workspace", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("o"))
+
+	assert.NotNil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.False(t, cmd.HasFlags())
+	assert.False(t, cmd.HasSubCommands())
+}
diff --git a/cmd/picoclaw/cmd_onboard.go b/cmd/picoclaw/internal/onboard/helpers.go
similarity index 90%
rename from cmd/picoclaw/cmd_onboard.go
rename to cmd/picoclaw/internal/onboard/helpers.go
index 1a9ebad61..4db8bdc8b 100644
--- a/cmd/picoclaw/cmd_onboard.go
+++ b/cmd/picoclaw/internal/onboard/helpers.go
@@ -1,24 +1,17 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package onboard
 
 import (
-	"embed"
 	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/config"
 )
 
-//go:generate cp -r ../../workspace .
-//go:embed workspace
-var embeddedFiles embed.FS
-
 func onboard() {
-	configPath := getConfigPath()
+	configPath := internal.GetConfigPath()
 
 	if _, err := os.Stat(configPath); err == nil {
 		fmt.Printf("Config already exists at %s\n", configPath)
@@ -40,7 +33,7 @@ func onboard() {
 	workspace := cfg.WorkspacePath()
 	createWorkspaceTemplates(workspace)
 
-	fmt.Printf("%s picoclaw is ready!\n", logo)
+	fmt.Printf("%s picoclaw is ready!\n", internal.Logo)
 	fmt.Println("\nNext steps:")
 	fmt.Println("  1. Add your API key to", configPath)
 	fmt.Println("")
@@ -53,6 +46,13 @@ func onboard() {
 	fmt.Println("  2. Chat: picoclaw agent -m \"Hello!\"")
 }
 
+func createWorkspaceTemplates(workspace string) {
+	err := copyEmbeddedToTarget(workspace)
+	if err != nil {
+		fmt.Printf("Error copying workspace templates: %v\n", err)
+	}
+}
+
 func copyEmbeddedToTarget(targetDir string) error {
 	// Ensure target directory exists
 	if err := os.MkdirAll(targetDir, 0o755); err != nil {
@@ -99,10 +99,3 @@ func copyEmbeddedToTarget(targetDir string) error {
 
 	return err
 }
-
-func createWorkspaceTemplates(workspace string) {
-	err := copyEmbeddedToTarget(workspace)
-	if err != nil {
-		fmt.Printf("Error copying workspace templates: %v\n", err)
-	}
-}
diff --git a/cmd/picoclaw/internal/onboard/helpers_test.go b/cmd/picoclaw/internal/onboard/helpers_test.go
new file mode 100644
index 000000000..f3e0c92e0
--- /dev/null
+++ b/cmd/picoclaw/internal/onboard/helpers_test.go
@@ -0,0 +1,25 @@
+package onboard
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestCopyEmbeddedToTargetUsesAgentsMarkdown(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)
+	}
+
+	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)
+	}
+}
diff --git a/cmd/picoclaw/internal/skills/command.go b/cmd/picoclaw/internal/skills/command.go
new file mode 100644
index 000000000..65eb127b9
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/command.go
@@ -0,0 +1,79 @@
+package skills
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+type deps struct {
+	workspace    string
+	installer    *skills.SkillInstaller
+	skillsLoader *skills.SkillsLoader
+}
+
+func NewSkillsCommand() *cobra.Command {
+	var d deps
+
+	cmd := &cobra.Command{
+		Use:   "skills",
+		Short: "Manage skills",
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := internal.LoadConfig()
+			if err != nil {
+				return fmt.Errorf("error loading config: %w", err)
+			}
+
+			d.workspace = cfg.WorkspacePath()
+			d.installer = skills.NewSkillInstaller(d.workspace)
+
+			// get global config directory and builtin skills directory
+			globalDir := filepath.Dir(internal.GetConfigPath())
+			globalSkillsDir := filepath.Join(globalDir, "skills")
+			builtinSkillsDir := filepath.Join(globalDir, "picoclaw", "skills")
+			d.skillsLoader = skills.NewSkillsLoader(d.workspace, globalSkillsDir, builtinSkillsDir)
+
+			return nil
+		},
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	installerFn := func() (*skills.SkillInstaller, error) {
+		if d.installer == nil {
+			return nil, fmt.Errorf("skills installer is not initialized")
+		}
+		return d.installer, nil
+	}
+
+	loaderFn := func() (*skills.SkillsLoader, error) {
+		if d.skillsLoader == nil {
+			return nil, fmt.Errorf("skills loader is not initialized")
+		}
+		return d.skillsLoader, nil
+	}
+
+	workspaceFn := func() (string, error) {
+		if d.workspace == "" {
+			return "", fmt.Errorf("workspace is not initialized")
+		}
+		return d.workspace, nil
+	}
+
+	cmd.AddCommand(
+		newListCommand(loaderFn),
+		newInstallCommand(installerFn),
+		newInstallBuiltinCommand(workspaceFn),
+		newListBuiltinCommand(),
+		newRemoveCommand(installerFn),
+		newSearchCommand(),
+		newShowCommand(loaderFn),
+	)
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/command_test.go b/cmd/picoclaw/internal/skills/command_test.go
new file mode 100644
index 000000000..0917d1384
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/command_test.go
@@ -0,0 +1,28 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewSkillsCommand(t *testing.T) {
+	cmd := NewSkillsCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "skills", cmd.Use)
+	assert.Equal(t, "Manage skills", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.NotNil(t, cmd.PersistentPreRunE)
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+}
diff --git a/cmd/picoclaw/cmd_skills.go b/cmd/picoclaw/internal/skills/helpers.go
similarity index 66%
rename from cmd/picoclaw/cmd_skills.go
rename to cmd/picoclaw/internal/skills/helpers.go
index 0814494b3..a59a2013a 100644
--- a/cmd/picoclaw/cmd_skills.go
+++ b/cmd/picoclaw/internal/skills/helpers.go
@@ -1,39 +1,21 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package skills
 
 import (
 	"context"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/skills"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
-func skillsHelp() {
-	fmt.Println("\nSkills commands:")
-	fmt.Println("  list                    List installed skills")
-	fmt.Println("  install <repo>          Install skill from GitHub")
-	fmt.Println("  install-builtin         Install all builtin skills to workspace")
-	fmt.Println("  list-builtin            List available builtin skills")
-	fmt.Println("  remove <name>           Remove installed skill")
-	fmt.Println("  search                  Search available skills")
-	fmt.Println("  show <name>             Show skill details")
-	fmt.Println()
-	fmt.Println("Examples:")
-	fmt.Println("  picoclaw skills list")
-	fmt.Println("  picoclaw skills install sipeed/picoclaw-skills/weather")
-	fmt.Println("  picoclaw skills install-builtin")
-	fmt.Println("  picoclaw skills list-builtin")
-	fmt.Println("  picoclaw skills remove weather")
-	fmt.Println("  picoclaw skills install --registry clawhub github")
-}
+const skillsSearchMaxResults = 20
 
 func skillsListCmd(loader *skills.SkillsLoader) {
 	allSkills := loader.ListSkills()
@@ -53,53 +35,31 @@ func skillsListCmd(loader *skills.SkillsLoader) {
 	}
 }
 
-func skillsInstallCmd(installer *skills.SkillInstaller, cfg *config.Config) {
-	if len(os.Args) < 4 {
-		fmt.Println("Usage: picoclaw skills install <github-repo>")
-		fmt.Println("       picoclaw skills install --registry <name> <slug>")
-		return
-	}
-
-	// Check for --registry flag.
-	if os.Args[3] == "--registry" {
-		if len(os.Args) < 6 {
-			fmt.Println("Usage: picoclaw skills install --registry <name> <slug>")
-			fmt.Println("Example: picoclaw skills install --registry clawhub github")
-			return
-		}
-		registryName := os.Args[4]
-		slug := os.Args[5]
-		skillsInstallFromRegistry(cfg, registryName, slug)
-		return
-	}
-
-	// Default: install from GitHub (backward compatible).
-	repo := os.Args[3]
+func skillsInstallCmd(installer *skills.SkillInstaller, repo string) error {
 	fmt.Printf("Installing skill from %s...\n", repo)
 
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 
 	if err := installer.InstallFromGitHub(ctx, repo); err != nil {
-		fmt.Printf("\u2717 Failed to install skill: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to install skill: %w", err)
 	}
 
 	fmt.Printf("\u2713 Skill '%s' installed successfully!\n", filepath.Base(repo))
+
+	return nil
 }
 
 // skillsInstallFromRegistry installs a skill from a named registry (e.g. clawhub).
-func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
+func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) error {
 	err := utils.ValidateSkillIdentifier(registryName)
 	if err != nil {
-		fmt.Printf("\u2717 Invalid registry name: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("✗  invalid registry name: %w", err)
 	}
 
 	err = utils.ValidateSkillIdentifier(slug)
 	if err != nil {
-		fmt.Printf("\u2717 Invalid slug: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("✗  invalid slug: %w", err)
 	}
 
 	fmt.Printf("Installing skill '%s' from %s registry...\n", slug, registryName)
@@ -111,24 +71,21 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 
 	registry := registryMgr.GetRegistry(registryName)
 	if registry == nil {
-		fmt.Printf("\u2717 Registry '%s' not found or not enabled. Check your config.json.\n", registryName)
-		os.Exit(1)
+		return fmt.Errorf("✗  registry '%s' not found or not enabled. check your config.json.", registryName)
 	}
 
 	workspace := cfg.WorkspacePath()
 	targetDir := filepath.Join(workspace, "skills", slug)
 
 	if _, err = os.Stat(targetDir); err == nil {
-		fmt.Printf("\u2717 Skill '%s' already installed at %s\n", slug, targetDir)
-		os.Exit(1)
+		return fmt.Errorf("\u2717 skill '%s' already installed at %s", slug, targetDir)
 	}
 
 	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
 	defer cancel()
 
 	if err = os.MkdirAll(filepath.Join(workspace, "skills"), 0o755); err != nil {
-		fmt.Printf("\u2717 Failed to create skills directory: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("\u2717 failed to create skills directory: %v", err)
 	}
 
 	result, err := registry.DownloadAndInstall(ctx, slug, "", targetDir)
@@ -137,8 +94,7 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 		if rmErr != nil {
 			fmt.Printf("\u2717 Failed to remove partial install: %v\n", rmErr)
 		}
-		fmt.Printf("\u2717 Failed to install skill: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("✗ failed to install skill: %w", err)
 	}
 
 	if result.IsMalwareBlocked {
@@ -146,8 +102,8 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 		if rmErr != nil {
 			fmt.Printf("\u2717 Failed to remove partial install: %v\n", rmErr)
 		}
-		fmt.Printf("\u2717 Skill '%s' is flagged as malicious and cannot be installed.\n", slug)
-		os.Exit(1)
+
+		return fmt.Errorf("\u2717 Skill '%s' is flagged as malicious and cannot be installed.\n", slug)
 	}
 
 	if result.IsSuspicious {
@@ -158,6 +114,8 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 	if result.Summary != "" {
 		fmt.Printf("  %s\n", result.Summary)
 	}
+
+	return nil
 }
 
 func skillsRemoveCmd(installer *skills.SkillInstaller, skillName string) {
@@ -208,7 +166,7 @@ func skillsInstallBuiltinCmd(workspace string) {
 }
 
 func skillsListBuiltinCmd() {
-	cfg, err := loadConfig()
+	cfg, err := internal.LoadConfig()
 	if err != nil {
 		fmt.Printf("Error loading config: %v\n", err)
 		return
@@ -259,34 +217,43 @@ func skillsListBuiltinCmd() {
 	}
 }
 
-func skillsSearchCmd(installer *skills.SkillInstaller) {
+func skillsSearchCmd(query string) {
 	fmt.Println("Searching for available skills...")
 
+	cfg, err := internal.LoadConfig()
+	if err != nil {
+		fmt.Printf("✗ Failed to load config: %v\n", err)
+		return
+	}
+
+	registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
+		MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
+		ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+	})
+
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 
-	availableSkills, err := installer.ListAvailableSkills(ctx)
+	results, err := registryMgr.SearchAll(ctx, query, skillsSearchMaxResults)
 	if err != nil {
 		fmt.Printf("✗ Failed to fetch skills list: %v\n", err)
 		return
 	}
 
-	if len(availableSkills) == 0 {
+	if len(results) == 0 {
 		fmt.Println("No skills available.")
 		return
 	}
 
-	fmt.Printf("\nAvailable Skills (%d):\n", len(availableSkills))
+	fmt.Printf("\nAvailable Skills (%d):\n", len(results))
 	fmt.Println("--------------------")
-	for _, skill := range availableSkills {
-		fmt.Printf("  📦 %s\n", skill.Name)
-		fmt.Printf("     %s\n", skill.Description)
-		fmt.Printf("     Repo: %s\n", skill.Repository)
-		if skill.Author != "" {
-			fmt.Printf("     Author: %s\n", skill.Author)
-		}
-		if len(skill.Tags) > 0 {
-			fmt.Printf("     Tags: %v\n", skill.Tags)
+	for _, result := range results {
+		fmt.Printf("  📦 %s\n", result.DisplayName)
+		fmt.Printf("     %s\n", result.Summary)
+		fmt.Printf("     Slug: %s\n", result.Slug)
+		fmt.Printf("     Registry: %s\n", result.RegistryName)
+		if result.Version != "" {
+			fmt.Printf("     Version: %s\n", result.Version)
 		}
 		fmt.Println()
 	}
@@ -303,3 +270,37 @@ func skillsShowCmd(loader *skills.SkillsLoader, skillName string) {
 	fmt.Println("----------------------")
 	fmt.Println(content)
 }
+
+func copyDirectory(src, dst string) error {
+	return filepath.Walk(src, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		relPath, err := filepath.Rel(src, path)
+		if err != nil {
+			return err
+		}
+
+		dstPath := filepath.Join(dst, relPath)
+
+		if info.IsDir() {
+			return os.MkdirAll(dstPath, info.Mode())
+		}
+
+		srcFile, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		defer srcFile.Close()
+
+		dstFile, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
+		if err != nil {
+			return err
+		}
+		defer dstFile.Close()
+
+		_, err = io.Copy(dstFile, srcFile)
+		return err
+	})
+}
diff --git a/cmd/picoclaw/internal/skills/install.go b/cmd/picoclaw/internal/skills/install.go
new file mode 100644
index 000000000..78bc421db
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/install.go
@@ -0,0 +1,58 @@
+package skills
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newInstallCommand(installerFn func() (*skills.SkillInstaller, error)) *cobra.Command {
+	var registry string
+
+	cmd := &cobra.Command{
+		Use:   "install",
+		Short: "Install skill from GitHub",
+		Example: `
+picoclaw skills install sipeed/picoclaw-skills/weather
+picoclaw skills install --registry clawhub github
+`,
+		Args: func(cmd *cobra.Command, args []string) error {
+			if registry != "" {
+				if len(args) != 1 {
+					return fmt.Errorf("when --registry is set, exactly 1 argument is required: <slug>")
+				}
+				return nil
+			}
+
+			if len(args) != 1 {
+				return fmt.Errorf("exactly 1 argument is required: <github>")
+			}
+
+			return nil
+		},
+		RunE: func(_ *cobra.Command, args []string) error {
+			installer, err := installerFn()
+			if err != nil {
+				return err
+			}
+
+			if registry != "" {
+				cfg, err := internal.LoadConfig()
+				if err != nil {
+					return err
+				}
+
+				return skillsInstallFromRegistry(cfg, registry, args[0])
+			}
+
+			return skillsInstallCmd(installer, args[0])
+		},
+	}
+
+	cmd.Flags().StringVar(&registry, "registry", "", "Install from registry: --registry <name> <slug>")
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/install_test.go b/cmd/picoclaw/internal/skills/install_test.go
new file mode 100644
index 000000000..6b362822d
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/install_test.go
@@ -0,0 +1,97 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewInstallSubcommand(t *testing.T) {
+	cmd := newInstallCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "install", cmd.Use)
+	assert.Equal(t, "Install skill from GitHub", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.True(t, cmd.HasFlags())
+	assert.NotNil(t, cmd.Flags().Lookup("registry"))
+
+	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/skills/installbuiltin.go b/cmd/picoclaw/internal/skills/installbuiltin.go
new file mode 100644
index 000000000..d4b7c6a9f
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/installbuiltin.go
@@ -0,0 +1,21 @@
+package skills
+
+import "github.com/spf13/cobra"
+
+func newInstallBuiltinCommand(workspaceFn func() (string, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "install-builtin",
+		Short:   "Install all builtin skills to workspace",
+		Example: `picoclaw skills install-builtin`,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			workspace, err := workspaceFn()
+			if err != nil {
+				return err
+			}
+			skillsInstallBuiltinCmd(workspace)
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/installbuiltin_test.go b/cmd/picoclaw/internal/skills/installbuiltin_test.go
new file mode 100644
index 000000000..ea65907e3
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/installbuiltin_test.go
@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewInstallbuiltinSubcommand(t *testing.T) {
+	cmd := newInstallBuiltinCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "install-builtin", cmd.Use)
+	assert.Equal(t, "Install all builtin skills to workspace", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}
diff --git a/cmd/picoclaw/internal/skills/list.go b/cmd/picoclaw/internal/skills/list.go
new file mode 100644
index 000000000..7d89ff8ed
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/list.go
@@ -0,0 +1,25 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newListCommand(loaderFn func() (*skills.SkillsLoader, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "list",
+		Short:   "List installed skills",
+		Example: `picoclaw skills list`,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			loader, err := loaderFn()
+			if err != nil {
+				return err
+			}
+			skillsListCmd(loader)
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/list_test.go b/cmd/picoclaw/internal/skills/list_test.go
new file mode 100644
index 000000000..9947ce7aa
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/list_test.go
@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewListSubcommand(t *testing.T) {
+	cmd := newListCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "list", cmd.Use)
+	assert.Equal(t, "List installed skills", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}
diff --git a/cmd/picoclaw/internal/skills/listbuiltin.go b/cmd/picoclaw/internal/skills/listbuiltin.go
new file mode 100644
index 000000000..a3efb8d83
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/listbuiltin.go
@@ -0,0 +1,16 @@
+package skills
+
+import "github.com/spf13/cobra"
+
+func newListBuiltinCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "list-builtin",
+		Short:   "List available builtin skills",
+		Example: `picoclaw skills list-builtin`,
+		Run: func(_ *cobra.Command, _ []string) {
+			skillsListBuiltinCmd()
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/listbuiltin_test.go b/cmd/picoclaw/internal/skills/listbuiltin_test.go
new file mode 100644
index 000000000..d4f45a436
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/listbuiltin_test.go
@@ -0,0 +1,26 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewListbuiltinSubcommand(t *testing.T) {
+	cmd := newListBuiltinCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "list-builtin", cmd.Use)
+	assert.Equal(t, "List available builtin skills", cmd.Short)
+
+	assert.NotNil(t, cmd.Run)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}
diff --git a/cmd/picoclaw/internal/skills/remove.go b/cmd/picoclaw/internal/skills/remove.go
new file mode 100644
index 000000000..cd7d3a8b4
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/remove.go
@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newRemoveCommand(installerFn func() (*skills.SkillInstaller, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "remove",
+		Aliases: []string{"rm", "uninstall"},
+		Short:   "Remove installed skill",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw skills remove weather`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			installer, err := installerFn()
+			if err != nil {
+				return err
+			}
+			skillsRemoveCmd(installer, args[0])
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/remove_test.go b/cmd/picoclaw/internal/skills/remove_test.go
new file mode 100644
index 000000000..b4c79760c
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/remove_test.go
@@ -0,0 +1,29 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewRemoveSubcommand(t *testing.T) {
+	cmd := newRemoveCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "remove", cmd.Use)
+	assert.Equal(t, "Remove installed skill", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 2)
+	assert.True(t, cmd.HasAlias("rm"))
+	assert.True(t, cmd.HasAlias("uninstall"))
+}
diff --git a/cmd/picoclaw/internal/skills/search.go b/cmd/picoclaw/internal/skills/search.go
new file mode 100644
index 000000000..54f72259f
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/search.go
@@ -0,0 +1,23 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func newSearchCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "search [query]",
+		Short: "Search available skills",
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			query := ""
+			if len(args) == 1 {
+				query = args[0]
+			}
+			skillsSearchCmd(query)
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/search_test.go b/cmd/picoclaw/internal/skills/search_test.go
new file mode 100644
index 000000000..ed92e25cc
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/search_test.go
@@ -0,0 +1,25 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewSearchSubcommand(t *testing.T) {
+	cmd := newSearchCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "search [query]", cmd.Use)
+	assert.Equal(t, "Search available skills", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.False(t, cmd.HasSubCommands())
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}
diff --git a/cmd/picoclaw/internal/skills/show.go b/cmd/picoclaw/internal/skills/show.go
new file mode 100644
index 000000000..e484f3f28
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/show.go
@@ -0,0 +1,26 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newShowCommand(loaderFn func() (*skills.SkillsLoader, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "show",
+		Short:   "Show skill details",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw skills show weather`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			loader, err := loaderFn()
+			if err != nil {
+				return err
+			}
+			skillsShowCmd(loader, args[0])
+			return nil
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/skills/show_test.go b/cmd/picoclaw/internal/skills/show_test.go
new file mode 100644
index 000000000..5858d2790
--- /dev/null
+++ b/cmd/picoclaw/internal/skills/show_test.go
@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewShowSubcommand(t *testing.T) {
+	cmd := newShowCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "show", cmd.Use)
+	assert.Equal(t, "Show skill details", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}
diff --git a/cmd/picoclaw/internal/status/command.go b/cmd/picoclaw/internal/status/command.go
new file mode 100644
index 000000000..9303ae2ec
--- /dev/null
+++ b/cmd/picoclaw/internal/status/command.go
@@ -0,0 +1,18 @@
+package status
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewStatusCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "status",
+		Aliases: []string{"s"},
+		Short:   "Show picoclaw status",
+		Run: func(cmd *cobra.Command, args []string) {
+			statusCmd()
+		},
+	}
+
+	return cmd
+}
diff --git a/cmd/picoclaw/internal/status/command_test.go b/cmd/picoclaw/internal/status/command_test.go
new file mode 100644
index 000000000..974b4ea3d
--- /dev/null
+++ b/cmd/picoclaw/internal/status/command_test.go
@@ -0,0 +1,29 @@
+package status
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewStatusCommand(t *testing.T) {
+	cmd := NewStatusCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "status", cmd.Use)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("s"))
+
+	assert.Equal(t, "Show picoclaw status", cmd.Short)
+
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.NotNil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+}
diff --git a/cmd/picoclaw/cmd_status.go b/cmd/picoclaw/internal/status/helpers.go
similarity index 88%
rename from cmd/picoclaw/cmd_status.go
rename to cmd/picoclaw/internal/status/helpers.go
index 07296784e..ab28f4885 100644
--- a/cmd/picoclaw/cmd_status.go
+++ b/cmd/picoclaw/internal/status/helpers.go
@@ -1,27 +1,25 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package status
 
 import (
 	"fmt"
 	"os"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/auth"
 )
 
 func statusCmd() {
-	cfg, err := loadConfig()
+	cfg, err := internal.LoadConfig()
 	if err != nil {
 		fmt.Printf("Error loading config: %v\n", err)
 		return
 	}
 
-	configPath := getConfigPath()
+	configPath := internal.GetConfigPath()
 
-	fmt.Printf("%s picoclaw Status\n", logo)
-	fmt.Printf("Version: %s\n", formatVersion())
-	build, _ := formatBuildInfo()
+	fmt.Printf("%s picoclaw Status\n", internal.Logo)
+	fmt.Printf("Version: %s\n", internal.FormatVersion())
+	build, _ := internal.FormatBuildInfo()
 	if build != "" {
 		fmt.Printf("Build: %s\n", build)
 	}
@@ -41,7 +39,7 @@ func statusCmd() {
 	}
 
 	if _, err := os.Stat(configPath); err == nil {
-		fmt.Printf("Model: %s\n", cfg.Agents.Defaults.Model)
+		fmt.Printf("Model: %s\n", cfg.Agents.Defaults.GetModelName())
 
 		hasOpenRouter := cfg.Providers.OpenRouter.APIKey != ""
 		hasAnthropic := cfg.Providers.Anthropic.APIKey != ""
diff --git a/cmd/picoclaw/internal/version/command.go b/cmd/picoclaw/internal/version/command.go
new file mode 100644
index 000000000..1cf686671
--- /dev/null
+++ b/cmd/picoclaw/internal/version/command.go
@@ -0,0 +1,33 @@
+package version
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func NewVersionCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "version",
+		Aliases: []string{"v"},
+		Short:   "Show version information",
+		Run: func(_ *cobra.Command, _ []string) {
+			printVersion()
+		},
+	}
+
+	return cmd
+}
+
+func printVersion() {
+	fmt.Printf("%s picoclaw %s\n", internal.Logo, internal.FormatVersion())
+	build, goVer := internal.FormatBuildInfo()
+	if build != "" {
+		fmt.Printf("  Build: %s\n", build)
+	}
+	if goVer != "" {
+		fmt.Printf("  Go: %s\n", goVer)
+	}
+}
diff --git a/cmd/picoclaw/internal/version/command_test.go b/cmd/picoclaw/internal/version/command_test.go
new file mode 100644
index 000000000..f08a4d1ea
--- /dev/null
+++ b/cmd/picoclaw/internal/version/command_test.go
@@ -0,0 +1,31 @@
+package version
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewVersionCommand(t *testing.T) {
+	cmd := NewVersionCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "version", cmd.Use)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("v"))
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Equal(t, "Show version information", cmd.Short)
+
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.NotNil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+}
diff --git a/cmd/picoclaw/main.go b/cmd/picoclaw/main.go
index 25ad701ca..fe4de8ecc 100644
--- a/cmd/picoclaw/main.go
+++ b/cmd/picoclaw/main.go
@@ -8,192 +8,63 @@ package main
 
 import (
 	"fmt"
-	"io"
 	"os"
-	"path/filepath"
-	"runtime"
 
-	"github.com/sipeed/picoclaw/pkg/config"
-	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/agent"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/auth"
+	"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/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"
 )
 
-var (
-	version   = "dev"
-	gitCommit string
-	buildTime string
-	goVersion string
+func NewPicoclawCommand() *cobra.Command {
+	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, internal.GetVersion())
+
+	cmd := &cobra.Command{
+		Use:     "picoclaw",
+		Short:   short,
+		Example: "picoclaw version",
+	}
+
+	cmd.AddCommand(
+		onboard.NewOnboardCommand(),
+		agent.NewAgentCommand(),
+		auth.NewAuthCommand(),
+		gateway.NewGatewayCommand(),
+		status.NewStatusCommand(),
+		cron.NewCronCommand(),
+		migrate.NewMigrateCommand(),
+		skills.NewSkillsCommand(),
+		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"
 )
 
-const logo = "🦞"
-
-// 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() (build string, goVer string) {
-	if buildTime != "" {
-		build = buildTime
-	}
-	goVer = goVersion
-	if goVer == "" {
-		goVer = runtime.Version()
-	}
-	return
-}
-
-func printVersion() {
-	fmt.Printf("%s picoclaw %s\n", logo, formatVersion())
-	build, goVer := formatBuildInfo()
-	if build != "" {
-		fmt.Printf("  Build: %s\n", build)
-	}
-	if goVer != "" {
-		fmt.Printf("  Go: %s\n", goVer)
-	}
-}
-
-func copyDirectory(src, dst string) error {
-	return filepath.Walk(src, func(path string, info os.FileInfo, err error) error {
-		if err != nil {
-			return err
-		}
-
-		relPath, err := filepath.Rel(src, path)
-		if err != nil {
-			return err
-		}
-
-		dstPath := filepath.Join(dst, relPath)
-
-		if info.IsDir() {
-			return os.MkdirAll(dstPath, info.Mode())
-		}
-
-		srcFile, err := os.Open(path)
-		if err != nil {
-			return err
-		}
-		defer srcFile.Close()
-
-		dstFile, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
-		if err != nil {
-			return err
-		}
-		defer dstFile.Close()
-
-		_, err = io.Copy(dstFile, srcFile)
-		return err
-	})
-}
-
 func main() {
-	if len(os.Args) < 2 {
-		printHelp()
-		os.Exit(1)
-	}
-
-	command := os.Args[1]
-
-	switch command {
-	case "onboard":
-		onboard()
-	case "agent":
-		agentCmd()
-	case "gateway":
-		gatewayCmd()
-	case "status":
-		statusCmd()
-	case "migrate":
-		migrateCmd()
-	case "auth":
-		authCmd()
-	case "cron":
-		cronCmd()
-	case "skills":
-		if len(os.Args) < 3 {
-			skillsHelp()
-			return
-		}
-
-		subcommand := os.Args[2]
-
-		cfg, err := loadConfig()
-		if err != nil {
-			fmt.Printf("Error loading config: %v\n", err)
-			os.Exit(1)
-		}
-
-		workspace := cfg.WorkspacePath()
-		installer := skills.NewSkillInstaller(workspace)
-		// get global config directory and builtin skills directory
-		globalDir := filepath.Dir(getConfigPath())
-		globalSkillsDir := filepath.Join(globalDir, "skills")
-		builtinSkillsDir := filepath.Join(globalDir, "picoclaw", "skills")
-		skillsLoader := skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir)
-
-		switch subcommand {
-		case "list":
-			skillsListCmd(skillsLoader)
-		case "install":
-			skillsInstallCmd(installer, cfg)
-		case "remove", "uninstall":
-			if len(os.Args) < 4 {
-				fmt.Println("Usage: picoclaw skills remove <skill-name>")
-				return
-			}
-			skillsRemoveCmd(installer, os.Args[3])
-		case "install-builtin":
-			skillsInstallBuiltinCmd(workspace)
-		case "list-builtin":
-			skillsListBuiltinCmd()
-		case "search":
-			skillsSearchCmd(installer)
-		case "show":
-			if len(os.Args) < 4 {
-				fmt.Println("Usage: picoclaw skills show <skill-name>")
-				return
-			}
-			skillsShowCmd(skillsLoader, os.Args[3])
-		default:
-			fmt.Printf("Unknown skills command: %s\n", subcommand)
-			skillsHelp()
-		}
-	case "version", "--version", "-v":
-		printVersion()
-	default:
-		fmt.Printf("Unknown command: %s\n", command)
-		printHelp()
+	fmt.Printf("%s", banner)
+	cmd := NewPicoclawCommand()
+	if err := cmd.Execute(); err != nil {
 		os.Exit(1)
 	}
 }
-
-func printHelp() {
-	fmt.Printf("%s picoclaw - Personal AI Assistant v%s\n\n", logo, version)
-	fmt.Println("Usage: picoclaw <command>")
-	fmt.Println()
-	fmt.Println("Commands:")
-	fmt.Println("  onboard     Initialize picoclaw configuration and workspace")
-	fmt.Println("  agent       Interact with the agent directly")
-	fmt.Println("  auth        Manage authentication (login, logout, status)")
-	fmt.Println("  gateway     Start picoclaw gateway")
-	fmt.Println("  status      Show picoclaw status")
-	fmt.Println("  cron        Manage scheduled tasks")
-	fmt.Println("  migrate     Migrate from OpenClaw to PicoClaw")
-	fmt.Println("  skills      Manage skills (install, list, remove)")
-	fmt.Println("  version     Show version information")
-}
-
-func getConfigPath() string {
-	home, _ := os.UserHomeDir()
-	return filepath.Join(home, ".picoclaw", "config.json")
-}
-
-func loadConfig() (*config.Config, error) {
-	return config.LoadConfig(getConfigPath())
-}
diff --git a/cmd/picoclaw/main_test.go b/cmd/picoclaw/main_test.go
new file mode 100644
index 000000000..3740ba358
--- /dev/null
+++ b/cmd/picoclaw/main_test.go
@@ -0,0 +1,56 @@
+package main
+
+import (
+	"fmt"
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func TestNewPicoclawCommand(t *testing.T) {
+	cmd := NewPicoclawCommand()
+
+	require.NotNil(t, cmd)
+
+	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, internal.GetVersion())
+
+	assert.Equal(t, "picoclaw", cmd.Use)
+	assert.Equal(t, short, cmd.Short)
+
+	assert.True(t, cmd.HasSubCommands())
+	assert.True(t, cmd.HasAvailableSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Nil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	allowedCommands := []string{
+		"agent",
+		"auth",
+		"cron",
+		"gateway",
+		"migrate",
+		"onboard",
+		"skills",
+		"status",
+		"version",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+
+		assert.False(t, subcmd.Hidden)
+	}
+}
diff --git a/config/config.example.json b/config/config.example.json
index 555509732..3a33b3caf 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -3,10 +3,12 @@
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
       "restrict_to_workspace": true,
-      "model": "gpt4",
+      "model_name": "gpt4",
       "max_tokens": 8192,
       "temperature": 0.7,
-      "max_tool_iterations": 20
+      "max_tool_iterations": 20,
+      "summarize_message_threshold": 20,
+      "summarize_token_percent": 75
     }
   },
   "model_list": [
@@ -20,7 +22,8 @@
       "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"
     },
     {
       "model_name": "gemini",
@@ -49,33 +52,44 @@
     "telegram": {
       "enabled": false,
       "token": "YOUR_TELEGRAM_BOT_TOKEN",
+      "base_url": "",
       "proxy": "",
       "allow_from": [
         "YOUR_USER_ID"
-      ]
+      ],
+      "reasoning_channel_id": ""
     },
     "discord": {
       "enabled": false,
       "token": "YOUR_DISCORD_BOT_TOKEN",
+      "proxy": "",
       "allow_from": [],
-      "mention_only": false
+      "group_trigger": {
+        "mention_only": false
+      },
+      "reasoning_channel_id": ""
     },
     "qq": {
       "enabled": false,
       "app_id": "YOUR_QQ_APP_ID",
       "app_secret": "YOUR_QQ_APP_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "maixcam": {
       "enabled": false,
       "host": "0.0.0.0",
       "port": 18790,
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "whatsapp": {
       "enabled": false,
       "bridge_url": "ws://localhost:3001",
-      "allow_from": []
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "feishu": {
       "enabled": false,
@@ -83,28 +97,48 @@
       "app_secret": "",
       "encrypt_key": "",
       "verification_token": "",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": "",
+      "random_reaction_emoji": []
     },
     "dingtalk": {
       "enabled": false,
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "slack": {
       "enabled": false,
       "bot_token": "xoxb-YOUR-BOT-TOKEN",
       "app_token": "xapp-YOUR-APP-TOKEN",
-      "allow_from": []
+      "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": ""
     },
     "line": {
       "enabled": false,
       "channel_secret": "YOUR_LINE_CHANNEL_SECRET",
       "channel_access_token": "YOUR_LINE_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
       "webhook_path": "/webhook/line",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "onebot": {
       "enabled": false,
@@ -112,33 +146,69 @@
       "access_token": "",
       "reconnect_interval": 5,
       "group_trigger_prefix": [],
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "wecom": {
-      "_comment": "WeCom Bot (智能机器人) - Easier setup, supports group chats",
+      "_comment": "WeCom Bot - Easier setup, supports group chats",
       "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_host": "0.0.0.0",
-      "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": [],
-      "reply_timeout": 5
+      "reply_timeout": 5,
+      "reasoning_channel_id": ""
     },
     "wecom_app": {
-      "_comment": "WeCom App (自建应用) - More features, proactive messaging, private chat only. See docs/wecom-app-configuration.md",
+      "_comment": "WeCom App (自建应用) - More features, proactive messaging, private chat only.",
       "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_host": "0.0.0.0",
-      "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": [],
-      "reply_timeout": 5
+      "reply_timeout": 5,
+      "reasoning_channel_id": ""
+    },
+    "wecom_aibot": {
+      "_comment": "WeCom AI Bot (智能机器人) - Official WeCom AI Bot integration, supports proactive messaging and private chats.",
+      "enabled": false,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "max_steps": 10,
+      "welcome_message": "Hello! I'm your AI assistant. How can I help you today?",
+      "reasoning_channel_id": ""
+    },
+    "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": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "typing": {
+        "enabled": false
+      },
+      "reasoning_channel_id": ""
     }
   },
   "providers": {
@@ -200,42 +270,197 @@
     "mistral": {
       "api_key": "",
       "api_base": "https://api.mistral.ai/v1"
+    },
+    "avian": {
+      "api_key": "",
+      "api_base": "https://api.avian.io/v1"
     }
   },
   "tools": {
+    "allow_read_paths": null,
+    "allow_write_paths": null,
     "web": {
+      "enabled": true,
       "brave": {
         "enabled": false,
         "api_key": "YOUR_BRAVE_API_KEY",
         "max_results": 5
       },
+      "tavily": {
+        "enabled": false,
+        "api_key": "",
+        "base_url": "",
+        "max_results": 0
+      },
       "duckduckgo": {
         "enabled": true,
         "max_results": 5
       },
       "perplexity": {
         "enabled": false,
-        "api_key": "pplx-xxx",
+        "api_key": "",
         "max_results": 5
-      }
+      },
+      "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
     },
     "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
         }
+      },
+      "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": {
diff --git a/Dockerfile b/docker/Dockerfile
similarity index 100%
rename from Dockerfile
rename to docker/Dockerfile
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/Dockerfile.goreleaser b/docker/Dockerfile.goreleaser
similarity index 58%
rename from Dockerfile.goreleaser
rename to docker/Dockerfile.goreleaser
index 0cdc8c6bd..68a02aae8 100644
--- a/Dockerfile.goreleaser
+++ b/docker/Dockerfile.goreleaser
@@ -5,6 +5,8 @@ ARG TARGETPLATFORM
 RUN apk add --no-cache ca-certificates tzdata
 
 COPY $TARGETPLATFORM/picoclaw /usr/local/bin/picoclaw
+COPY docker/entrypoint.sh /entrypoint.sh
 
-ENTRYPOINT ["picoclaw"]
-CMD ["gateway"]
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
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-compose.yml b/docker/docker-compose.yml
similarity index 64%
rename from docker-compose.yml
rename to docker/docker-compose.yml
index c268b01cd..9ec71abab 100644
--- a/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -1,12 +1,10 @@
 services:
   # ─────────────────────────────────────────────
   # PicoClaw Agent (one-shot query)
-  #   docker compose run --rm picoclaw-agent -m "Hello"
+  #   docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Hello"
   # ─────────────────────────────────────────────
   picoclaw-agent:
-    build:
-      context: .
-      dockerfile: Dockerfile
+    image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-agent
     profiles:
       - agent
@@ -14,33 +12,23 @@ services:
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
-      - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
+      - ./data:/root/.picoclaw
     entrypoint: ["picoclaw", "agent"]
     stdin_open: true
     tty: true
 
   # ─────────────────────────────────────────────
   # PicoClaw Gateway (Long-running Bot)
-  #   docker compose up picoclaw-gateway
+  #   docker compose -f docker/docker-compose.yml up picoclaw-gateway
   # ─────────────────────────────────────────────
   picoclaw-gateway:
-    build:
-      context: .
-      dockerfile: Dockerfile
+    image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-gateway
-    restart: unless-stopped
+    restart: on-failure
     profiles:
       - gateway
     # Uncomment to access host network; leave commented unless needed.
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      # Configuration file
-      - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
-      # Persistent workspace (sessions, memory, logs)
-      - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
-    command: ["gateway"]
-
-volumes:
-  picoclaw-workspace:
+      - ./data:/root/.picoclaw
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
new file mode 100644
index 000000000..b6fc724b5
--- /dev/null
+++ b/docker/entrypoint.sh
@@ -0,0 +1,15 @@
+#!/bin/sh
+set -e
+
+# First-run: neither config nor workspace exists.
+# If config.json is already mounted but workspace is missing we skip onboard to
+# avoid the interactive "Overwrite? (y/n)" prompt hanging in a non-TTY container.
+if [ ! -d "${HOME}/.picoclaw/workspace" ] && [ ! -f "${HOME}/.picoclaw/config.json" ]; then
+    picoclaw onboard
+    echo ""
+    echo "First-run setup complete."
+    echo "Edit ${HOME}/.picoclaw/config.json (add your API key, etc.) then restart the container."
+    exit 0
+fi
+
+exec picoclaw gateway "$@"
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/channels/discord/README.zh.md b/docs/channels/discord/README.zh.md
index 5b597eced..6d3c502cf 100644
--- a/docs/channels/discord/README.zh.md
+++ b/docs/channels/discord/README.zh.md
@@ -11,7 +11,9 @@ Discord 是一个专为社区设计的免费语音、视频和文本聊天应用
       "enabled": true,
       "token": "YOUR_BOT_TOKEN",
       "allow_from": ["YOUR_USER_ID"],
-      "mention_only": false
+      "group_trigger": {
+        "mention_only": false
+      }
     }
   }
 }
@@ -22,7 +24,7 @@ Discord 是一个专为社区设计的免费语音、视频和文本聊天应用
 | enabled      | bool   | 是   | 是否启用 Discord 频道            |
 | token        | string | 是   | Discord 机器人 Token             |
 | allow_from   | array  | 否   | 用户ID白名单，空表示允许所有用户 |
-| mention_only | bool   | 否   | 是否仅响应提及机器人的消息       |
+| group_trigger | object | 否   | 群组触发设置（示例: { "mention_only": false }） |
 
 ## 设置流程
 
diff --git a/docs/channels/feishu/README.zh.md b/docs/channels/feishu/README.zh.md
index 310827723..3fafffb7d 100644
--- a/docs/channels/feishu/README.zh.md
+++ b/docs/channels/feishu/README.zh.md
@@ -26,7 +26,8 @@
 | app_secret         | string | 是   | 飞书应用的 App Secret            |
 | encrypt_key        | string | 否   | 事件回调加密密钥                 |
 | verification_token | string | 否   | 用于Webhook事件验证的Token       |
-| allow_from         | array  | 否   | 用户ID白名单，空表示允许所有用户 |
+| allow_from         | array  | 否   | 用户ID白名单，空表示所有用户   |
+| random_reaction_emoji | array | 否   | 随机添加的表情列表，空则使用默认 "Pin" |
 
 ## 设置流程
 
@@ -35,3 +36,4 @@
 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))
diff --git a/docs/channels/line/README.zh.md b/docs/channels/line/README.zh.md
index fd3aa80da..a36f622c2 100644
--- a/docs/channels/line/README.zh.md
+++ b/docs/channels/line/README.zh.md
@@ -11,8 +11,6 @@ PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的
       "enabled": true,
       "channel_secret": "YOUR_CHANNEL_SECRET",
       "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
       "webhook_path": "/webhook/line",
       "allow_from": []
     }
@@ -25,9 +23,7 @@ PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的
 | enabled              | bool   | 是   | 是否启用 LINE Channel                      |
 | channel_secret       | string | 是   | LINE Messaging API 的 Channel Secret       |
 | channel_access_token | string | 是   | LINE Messaging API 的 Channel Access Token |
-| webhook_host         | string | 是   | Webhook 监听的主机地址 (通常为 0.0.0.0)    |
-| webhook_port         | int    | 是   | Webhook 监听的端口 (默认为 18791)          |
-| webhook_path         | string | 是   | Webhook 的路径 (默认为 /webhook/line)      |
+| webhook_path         | string | 否   | Webhook 的路径 (默认为 /webhook/line)      |
 | allow_from           | array  | 否   | 用户ID白名单，空表示允许所有用户           |
 
 ## 设置流程
@@ -35,7 +31,8 @@ PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的
 1. 前往 [LINE Developers Console](https://developers.line.biz/console/) 创建一个服务提供商和一个 Messaging API Channel
 2. 获取 Channel Secret 和 Channel Access Token
 3. 配置Webhook:
-   - Line要求Webhook必须使用HTTPS协议，因此需要部署一个支持HTTPS的服务器，或者使用反向代理工具如ngrok将本地服务器暴露到公网
-   - 将 Webhook URL 设置为 `https://your-domain.com/webhook/line`
+   - 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/matrix/README.md b/docs/channels/matrix/README.md
new file mode 100644
index 000000000..c213aa80b
--- /dev/null
+++ b/docs/channels/matrix/README.md
@@ -0,0 +1,59 @@
+# 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": ""
+    }
+  }
+}
+```
+
+## 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 |
+
+## 3. Currently Supported
+
+- Text message send/receive
+- 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)
+
+## 4. TODO
+
+- Rich media metadata improvements (for example image/video size and thumbnails)
diff --git a/docs/channels/matrix/README.zh.md b/docs/channels/matrix/README.zh.md
new file mode 100644
index 000000000..efbc13093
--- /dev/null
+++ b/docs/channels/matrix/README.zh.md
@@ -0,0 +1,59 @@
+# 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": ""
+    }
+  }
+}
+```
+
+## 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   | 否   | 思维链输出目标通道 |
+
+## 3. 当前支持
+
+- 文本消息收发
+- 图片/音频/视频/文件消息入站下载（写入 MediaStore / 本地路径回退）
+- 音频消息按统一标记进入现有转写流程（`[audio: ...]`）
+- 图片/音频/视频/文件消息出站发送（上传到 Matrix 媒体库后发送）
+- 群聊触发规则（支持仅 @ 提及时响应）
+- Typing 状态（`m.typing`）
+- 占位消息（`Thinking... 💭`）+ 最终回复替换
+- 自动加入邀请房间（可关闭）
+
+## 4. TODO
+
+- 富媒体细节增强（如 image/video 的尺寸、缩略图等 metadata）
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..d210528af
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.zh.md
@@ -0,0 +1,116 @@
+# 企业微信智能机器人 (AI Bot)
+
+企业微信智能机器人（AI Bot）是企业微信官方提供的 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 Bot 管理页面配置               |
+| encoding_aes_key | string | 是   | 43 字符 AES 密钥，在 AI Bot 管理页面随机生成       |
+| webhook_path     | string | 否   | Webhook 路径（默认：/webhook/wecom-aibot）         |
+| allow_from       | array  | 否   | 用户 ID 白名单，空数组表示允许所有用户             |
+| welcome_message  | string | 否   | 用户进入聊天时发送的欢迎语，留空则不发送           |
+| reply_timeout    | int    | 否   | 回复超时时间（秒，默认：5）                        |
+| max_steps        | int    | 否   | Agent 最大执行步骤数（默认：10）                   |
+
+## 设置流程
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
+2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
+3. 在 AI Bot 配置页面，填写"消息接收"信息：
+   - **URL**：`http://<your-server-ip>:18791/webhook/wecom-aibot`
+   - **Token**：随机生成或自定义
+   - **EncodingAESKey**：点击"随机生成"，得到 43 字符密钥
+4. 将 Token 和 EncodingAESKey 填入 PicoClaw 配置文件，启动服务后回到管理后台保存（企业微信会发送验证请求）
+
+> [!TIP]
+> 服务器需要能被企业微信服务器访问。如在内网/本地开发，可使用 [ngrok](https://ngrok.com) 或 frp 做内网穿透。
+
+## 流式响应协议
+
+WeCom AI Bot 使用"流式拉取"协议，区别于普通 Webhook 的一次性回复：
+
+```
+用户发消息
+  │
+  ▼
+PicoClaw 立即返回 {finish: false}（Agent 开始处理）
+  │
+  ▼
+企业微信每隔约 1 秒拉取一次 {msgtype: "stream", stream: {id: "..."}}
+  │
+  ├─ Agent 未完成 → 返回 {finish: false}（继续等待）
+  │
+  └─ Agent 完成 → 返回 {finish: true, content: "回答内容"}
+```
+
+**超时处理**（任务超过 30 秒）：
+
+若 Agent 处理时间超过约 30 秒（企业微信最大轮询窗口为 6 分钟），PicoClaw 会：
+
+1. 立即关闭流，向用户显示「⏳ 正在处理中，请稍候，结果将稍后发送。」
+2. Agent 继续在后台运行
+3. Agent 完成后，通过消息中携带的 `response_url` 将最终回复主动推送给用户
+
+> `response_url` 由企业微信颁发，有效期 1 小时，只可使用一次，无需加密，直接 POST markdown 消息体即可。
+
+## 欢迎语
+
+配置 `welcome_message` 后，当用户打开与 AI Bot 的聊天窗口时（`enter_chat` 事件），PicoClaw 会自动回复该欢迎语。留空则静默忽略。
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## 常见问题
+
+### 回调 URL 验证失败
+
+- 确认服务器防火墙已开放对应端口（默认 18791）
+- 确认 `token` 与 `encoding_aes_key` 填写正确
+- 检查 PicoClaw 日志是否收到了来自企业微信的 GET 请求
+
+### 消息没有回复
+
+- 检查 `allow_from` 是否意外限制了发送者
+- 查看日志中是否出现 `context canceled` 或 Agent 错误
+- 确认 Agent 配置（`model_name` 等）正确
+
+### 超长任务没有收到最终推送
+
+- 确认消息回调中携带了 `response_url`（仅企业微信新版 AI Bot 支持）
+- 确认服务器能主动访问外网（需向 `response_url` POST 请求）
+- 查看日志关键词 `response_url mode` 和 `Sending reply via response_url`
+
+## 参考文档
+
+- [企业微信 AI Bot 接入文档](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_app/README.zh.md b/docs/channels/wecom/wecom_app/README.zh.md
index 1e6a0e2b3..0a9858107 100644
--- a/docs/channels/wecom/wecom_app/README.zh.md
+++ b/docs/channels/wecom/wecom_app/README.zh.md
@@ -14,8 +14,6 @@
       "agent_id": 1000002,
       "token": "YOUR_TOKEN",
       "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": [],
       "reply_timeout": 5
@@ -31,8 +29,6 @@
 | agent_id         | int    | 是   | 应用程序代理 ID                          |
 | token            | string | 是   | 回调验证令牌                             |
 | encoding_aes_key | string | 是   | 43 字符 AES 密钥                         |
-| webhook_host     | string | 否   | HTTP 服务器绑定地址                      |
-| webhook_port     | int    | 否   | HTTP 服务器端口（默认：18792）           |
 | webhook_path     | string | 否   | Webhook 路径（默认：/webhook/wecom-app） |
 | allow_from       | array  | 否   | 用户 ID 白名单                           |
 | reply_timeout    | int    | 否   | 回复超时时间（秒）                       |
@@ -45,3 +41,5 @@
 4. 在应用设置中配置“接收消息”，获取 Token 和 EncodingAESKey
 5. 设置回调 URL 为 `http://<your-server-ip>:<port>/webhook/wecom-app`
 6. 将 CorpID, Secret, AgentID 等信息填入配置文件
+
+   注意: PicoClaw 现在使用共享的 Gateway HTTP 服务器来接收所有渠道的 webhook 回调，默认监听地址为 127.0.0.1:18790。如需从公网接收回调，请把外部域名反向代理到 Gateway（默认端口 18790）。
diff --git a/docs/channels/wecom/wecom_bot/README.zh.md b/docs/channels/wecom/wecom_bot/README.zh.md
index c4bb1c87e..63d9b84d6 100644
--- a/docs/channels/wecom/wecom_bot/README.zh.md
+++ b/docs/channels/wecom/wecom_bot/README.zh.md
@@ -12,8 +12,6 @@
       "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_host": "0.0.0.0",
-      "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": [],
       "reply_timeout": 5
@@ -27,8 +25,6 @@
 | token            | string | 是   | 签名验证代币                                 |
 | encoding_aes_key | string | 是   | 用于解密的 43 字符 AES 密钥                  |
 | webhook_url      | string | 是   | 用于发送回复的企业微信群聊机器人 Webhook URL |
-| webhook_host     | string | 否   | HTTP 服务器绑定地址（默认：0.0.0.0）         |
-| webhook_port     | int    | 否   | HTTP 服务器端口（默认：18793）               |
 | webhook_path     | string | 否   | Webhook 端点路径（默认：/webhook/wecom）     |
 | allow_from       | array  | 否   | 用户 ID 白名单（空值 = 允许所有用户）        |
 | reply_timeout    | int    | 否   | 回复超时时间（单位：秒，默认值：5）          |
@@ -39,3 +35,5 @@
 2. 获取 Webhook URL
 3. (如需接收消息) 在机器人配置页面设置接收消息的 API 地址（回调地址）以及 Token 和 EncodingAESKey
 4. 将相关信息填入配置文件
+
+   注意: PicoClaw 现在使用共享的 Gateway HTTP 服务器来接收所有渠道的 webhook 回调，默认监听地址为 127.0.0.1:18790。如需从公网接收回调，请把外部域名反向代理到 Gateway（默认端口 18790）。
diff --git a/docs/design/issue-783-investigation-and-fix-plan.zh.md b/docs/design/issue-783-investigation-and-fix-plan.zh.md
new file mode 100644
index 000000000..1c9fc1e70
--- /dev/null
+++ b/docs/design/issue-783-investigation-and-fix-plan.zh.md
@@ -0,0 +1,61 @@
+# Issue #783 调研与修复执行文档
+
+## 1. 问题澄清（已确认）
+
+- 现象：当 `agents.*.model.primary/fallbacks` 使用 `model_name` 别名（如 `step-3.5-flash`）时，fallback 链路将别名当作真实 `provider/model` 解析，导致 `provider` 可能为空、`model` 可能错误。
+- 根因：`ResolveCandidates` 仅对字符串做 `ParseModelRef`，未先通过 `model_list` 将别名映射到真实 `model` 字段。
+- 影响：
+  - fallback 执行可能把别名直接发给 OpenAI-compatible provider，触发 `Unknown Model`。
+  - `defaults.provider` 为空时，日志出现 `provider=` 空值。
+
+## 2. 本次目标
+
+- 修复 fallback 候选解析：优先通过 `model_list` 解析别名。
+- 兼容旧行为：若未命中 `model_list`，继续走原有 `ParseModelRef` 兜底。
+- 补充测试：覆盖别名、嵌套路径模型（如 `openrouter/stepfun/...`）、空默认 provider。
+- 验证代码风格：与当前仓库风格保持一致（命名、错误处理、测试结构）。
+
+## 3. 联网最佳实践调研结论（已完成）
+
+- [x] 查阅 OpenAI-compatible 网关（如 OpenRouter）对 `model` 字段的推荐处理。
+- [x] 查阅多 provider/fallback 设计最佳实践（候选解析、日志可观测性）。
+- [x] 将外部建议映射为本仓库可执行约束。
+
+外部参考要点（来自 OpenRouter/LiteLLM/Cloudflare AI Gateway 等官方文档）：
+
+- 优先显式配置，不依赖字符串切分推断 provider。
+- 对网关模型标识应保留完整路径语义，避免截断导致 Unknown Model。
+- fallback 与 primary 应复用同一解析策略，避免“主路径正确、降级路径错误”。
+
+参考链接：
+
+- OpenRouter Provider Routing: https://openrouter.ai/docs/guides/routing/provider-selection
+- OpenRouter Model Fallbacks: https://openrouter.ai/docs/guides/routing/model-fallbacks
+- OpenRouter Chat Completion API: https://openrouter.ai/docs/api-reference/chat-completion
+- LiteLLM Router Architecture: https://docs.litellm.ai/docs/router_architecture
+- Cloudflare AI Gateway Chat Completion: https://developers.cloudflare.com/ai-gateway/usage/chat-completion/
+
+与本仓库对应的可执行约束：
+
+- 在 fallback candidate 构建阶段先做 `model_name -> model_list.model` 映射。
+- 未命中映射时保留旧解析行为，保证兼容性。
+- 用新增测试锁定“别名 + 嵌套模型路径 + 空默认 provider”场景。
+
+## 4. 实施步骤（顺序执行）
+
+- [x] Step 1: 对齐现有代码模式，定位最小改动点（`pkg/agent` + `pkg/providers`）。
+- [x] Step 2: 实现“基于 model_list 的 fallback 候选解析”。
+- [x] Step 3: 增加/更新单元测试，覆盖 issue 场景。
+- [x] Step 4: 代码风格一致性复核（与现有文件风格对照）。
+- [x] Step 5: 运行质量门禁（LSP + `make check`）。
+
+## 5. 执行记录
+
+- 状态：已完成
+- 已完成改动：
+  - `pkg/providers/fallback.go`：新增 `ResolveCandidatesWithLookup`，并保持 `ResolveCandidates` 向后兼容。
+  - `pkg/agent/instance.go`：在构建 fallback candidates 前，优先通过 `model_list` 解析别名，并对无协议模型补齐默认 `openai/` 前缀后再解析。
+  - `pkg/providers/fallback_test.go`：新增别名解析与去重测试。
+  - `pkg/agent/instance_test.go`：新增 agent 侧别名解析到嵌套模型路径、无协议模型解析测试。
+- 风格对齐检查（完成）：与 `pkg/providers/fallback_test.go`、`pkg/providers/model_ref_test.go` 现有模式一致。
+- 质量验证（完成）：先 `make generate`，后 `make check` 全量通过。
diff --git a/docs/migration/model-list-migration.md b/docs/migration/model-list-migration.md
index 589dfc043..0d4af719c 100644
--- a/docs/migration/model-list-migration.md
+++ b/docs/migration/model-list-migration.md
@@ -117,6 +117,7 @@ The `model` field uses a protocol prefix format: `[protocol/]model-identifier`
 | `connect_mode` | No | Connection mode for CLI providers: `stdio`, `grpc` |
 | `rpm` | No | Requests per minute limit |
 | `max_tokens_field` | No | Field name for max tokens |
+| `request_timeout` | No | HTTP request timeout in seconds; `<=0` uses default `120s` |
 
 *`api_key` is required for HTTP-based protocols unless `api_base` points to a local server.
 
diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md
index 8aba1aa91..8c8eb31f0 100644
--- a/docs/tools_configuration.md
+++ b/docs/tools_configuration.md
@@ -7,10 +7,21 @@ PicoClaw's tools configuration is located in the `tools` field of `config.json`.
 ```json
 {
   "tools": {
-    "web": { ... },
-    "exec": { ... },
-    "cron": { ... },
-    "skills": { ... }
+    "web": {
+      ...
+    },
+    "mcp": {
+      ...
+    },
+    "exec": {
+      ...
+    },
+    "cron": {
+      ...
+    },
+    "skills": {
+      ...
+    }
   }
 }
 ```
@@ -21,35 +32,35 @@ Web tools are used for web search and fetching.
 
 ### 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      |
+| `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 |
 
 ### 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        |
+| `max_results` | int    | 5       | Maximum number of results |
 
 ## 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                                |
+|------------------------|-------|---------|--------------------------------------------|
+| `enable_deny_patterns` | bool  | true    | Enable default dangerous command blocking  |
+| `custom_deny_patterns` | array | []      | Custom deny patterns (regular expressions) |
 
 ### Functionality
 
@@ -93,9 +104,167 @@ 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 |
+
+## 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   | If true, MCP tools are hidden and loaded on-demand via search. If false, all tools are loaded                                     |
+| `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                     |
+| `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"
+          }
+        }
+      }
+    }
+  }
+}
+```
 
 ## Skills Tool
 
@@ -103,13 +272,14 @@ 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 | `/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                            |
 
 ### Configuration Example
 
@@ -121,6 +291,7 @@ The skills tool configures skill discovery and installation via registries like
         "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"
@@ -136,8 +307,11 @@ 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_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
new file mode 100644
index 000000000..219d2c6e3
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,43 @@
+# Troubleshooting
+
+## "model ... not found in model_list" or OpenRouter "free is not a valid model ID"
+
+**Symptom:** You see either:
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter returns 400: `"free is not a valid model ID"`
+
+**Cause:** The `model` field in your `model_list` entry is what gets sent to the API. For OpenRouter you must use the **full** model ID, not a shorthand.
+
+- **Wrong:** `"model": "free"` → OpenRouter receives `free` and rejects it.
+- **Right:** `"model": "openrouter/free"` → OpenRouter receives `openrouter/free` (auto free-tier routing).
+
+**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"`).
+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"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+Example snippet:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "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"
+    }
+  ]
+}
+```
+
+Get your key at [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 3b17d37a7..000000000
--- a/docs/wecom-app-configuration.md
+++ /dev/null
@@ -1,117 +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:18792/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_host": "0.0.0.0",
-      "webhook_port": 18792,
-      "webhook_path": "/webhook/wecom-app",
-      "allow_from": [],
-      "reply_timeout": 5
-    }
-  }
-}
-```
-
-## 常见问题
-
-### 1. 回调URL验证失败
-
-**症状**: 企业微信保存API接收消息时提示验证失败
-
-**检查项**:
-- 确认服务器防火墙已开放 18792 端口
-- 确认 `corp_id`、`token`、`encoding_aes_key` 配置正确
-- 查看 PicoClaw 日志是否有请求到达
-
-### 2. 中文消息解密失败
-
-**症状**: 发送中文消息时出现 `invalid padding size` 错误
-
-**原因**: 企业微信使用非标准的 PKCS7 填充（32字节块大小）
-
-**解决**: 确保使用最新版本的 PicoClaw，已修复此问题。
-
-### 3. 端口冲突
-
-**症状**: 启动时提示端口已被占用
-
-**解决**: 修改 `webhook_port` 为其他端口，如 18794
-
-## 技术细节
-
-### 加密算法
-
-- **算法**: 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/go.mod b/go.mod
index 1f88639c8..f60be046f 100644
--- a/go.mod
+++ b/go.mod
@@ -8,22 +8,62 @@ require (
 	github.com/bwmarrin/discordgo v0.29.0
 	github.com/caarlos0/env/v11 v11.3.1
 	github.com/chzyer/readline v1.5.1
+	github.com/ergochat/irc-go v0.5.0
+	github.com/gdamore/tcell/v2 v2.13.8
 	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/mdp/qrterminal/v3 v3.2.1
+	github.com/modelcontextprotocol/go-sdk v1.3.1
 	github.com/mymmrac/telego v1.6.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/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/whatsmeow v0.0.0-20260219150138-7ae702b1eed4
 	golang.org/x/oauth2 v0.35.0
+	golang.org/x/time v0.14.0
+	google.golang.org/protobuf v1.36.11
+	maunium.net/go/mautrix v0.26.3
+	modernc.org/sqlite v1.46.1
 )
 
 require (
+	filippo.io/edwards25519 v1.1.1 // 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/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/pmezard/go-difflib v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // 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.3 // 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
+	modernc.org/libc v1.67.6 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	rsc.io/qr v0.2.0 // indirect
 )
 
 require (
@@ -47,9 +87,10 @@ require (
 	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/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/net v0.51.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.41.0 // indirect
 )
diff --git a/go.sum b/go.sum
index 0e95bf5cd..4060997f8 100644
--- a/go.sum
+++ b/go.sum
@@ -1,10 +1,20 @@
 cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
+filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw=
+filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+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=
 github.com/adhocore/gronx v1.19.6/go.mod h1:7oUY1WAU8rEJWmAxXR2DN0JaO4gi9khSgKjiRypqteg=
+github.com/agnivade/levenshtein v1.2.1 h1:EHBY3UOn1gwdy/VbFwgo4cxecRznFk7fKWN1KOX7eoM=
+github.com/agnivade/levenshtein v1.2.1/go.mod h1:QVVI16kDrtSuwcpd0p1+xMC6Z/VfhtCyDIjcwga4/DU=
+github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883 h1:bvNMNQO63//z+xNgfBlViaCIJKLlCJ6/fmUseuG0wVQ=
+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/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=
 github.com/bwmarrin/discordgo v0.29.0/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
 github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
@@ -25,13 +35,27 @@ 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=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
+github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 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/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.5.0 h1:woQ1RS9YbfgqPgSpPBBQeczXGIGzR0aC7dEgk469fTw=
+github.com/ergochat/irc-go v0.5.0/go.mod h1:2vi7KNpIPWnReB5hmLpl92eMywQvuIeIIGdt/FQCph0=
 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/go-redis/redis/v8 v8.11.4/go.mod h1:2Z2wHZXdQpCDXEGzqMockDpNyYvi2l4Pxt6RJr792+w=
@@ -41,8 +65,11 @@ github.com/go-resty/resty/v2 v2.17.1/go.mod h1:kCKZ3wWmwJaNc7S29BRtUhJwy7iqmn+2m
 github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE=
 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/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.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
+github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 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=
@@ -62,6 +89,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
 github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
 github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
@@ -71,7 +100,13 @@ 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=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
 github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
 github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
@@ -88,8 +123,25 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/larksuite/oapi-sdk-go/v3 v3.5.3 h1:xvf8Dv29kBXC5/DNDCLhHkAFW8l/0LlQJimO5Zn+JUk=
 github.com/larksuite/oapi-sdk-go/v3 v3.5.3/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
+github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp6Zk=
+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/modelcontextprotocol/go-sdk v1.3.1 h1:TfqtNKOIWN4Z1oqmPAiWDC2Jq7K9OdJaooe0teoXASI=
+github.com/modelcontextprotocol/go-sdk v1.3.1/go.mod h1:DgVX498dMD8UJlseK1S5i1T4tFz2fkBk4xogC3D15nw=
 github.com/mymmrac/telego v1.6.0 h1:Zc8rgyHozvd/7ZgyrigyHdAF9koHYMfilYfyB6wlFC0=
 github.com/mymmrac/telego v1.6.0/go.mod h1:xt6ZWA8zi8KmuzryE1ImEdl9JSwjHNpM4yhC7D8hU4Y=
+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=
 github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
@@ -102,14 +154,38 @@ 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/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=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/rivo/tview v0.42.0 h1:b/ftp+RxtDsHSaynXTbJb+/n/BxDEi+W3UfF5jILK6c=
+github.com/rivo/tview v0.42.0/go.mod h1:cSfIYfhpSGCjp3r/ECJb+GKS7cGJnqV8vfjQPwoXyfY=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+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.3 h1:OjMgICtcSFuNvQCdwqMCv9Tg7lEOXGwm1J5RPQccx6w=
+github.com/segmentio/encoding v0.5.3/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=
 github.com/slack-go/slack v0.17.3/go.mod h1:X+UqOufi3LYQHDnMG1vxf0J8asC6+WllXrVrhl8/Prk=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
@@ -144,13 +220,24 @@ github.com/valyala/fasthttp v1.69.0 h1:fNLLESD2SooWeh2cidsuFtOcrEi4uB4m1mPrkJMZy
 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/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/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=
 go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/arch v0.24.0 h1:qlJ3M9upxvFfwRM51tTg3Yl+8CP9vCC1E7vlFpgv99Y=
 golang.org/x/arch v0.24.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -161,10 +248,14 @@ golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5y
 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/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/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=
@@ -180,6 +271,8 @@ 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.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
+golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
 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=
@@ -207,8 +300,11 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
 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=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+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=
@@ -217,6 +313,8 @@ golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuX
 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/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=
@@ -224,8 +322,10 @@ 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/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
-golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+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/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=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
@@ -233,6 +333,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/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=
@@ -245,6 +347,8 @@ google.golang.org/protobuf v1.21.0/go.mod h1:47Nbq4nVaFHyn7ilMalzfO3qCViNmqZ2kzi
 google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
@@ -259,3 +363,35 @@ 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.3 h1:tWZih6Vjw0qGTWuPmg9JUrQPzViTNDPGQLVc5UXC4nk=
+maunium.net/go/mautrix v0.26.3/go.mod h1:v5ZdDoCwUpNqEj5OrhEoUa3L1kEddKPaAya9TgGXN38=
+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=
+modernc.org/ccgo/v4 v4.30.1/go.mod h1:bIOeI1JL54Utlxn+LwrFyjCx2n2RDiYEaJVSrgdrRfM=
+modernc.org/fileutil v1.3.40 h1:ZGMswMNc9JOCrcrakF1HrvmergNLAmxOPjizirpfqBA=
+modernc.org/fileutil v1.3.40/go.mod h1:HxmghZSZVAz/LXcMNwZPA/DRrQZEVP9VX0V4LQGQFOc=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.1 h1:k8T3gkXWY9sEiytKhcgyiZ2L0DTyCQ/nvX+LoCljoRE=
+modernc.org/gc/v3 v3.1.1/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.67.6 h1:eVOQvpModVLKOdT+LvBPjdQqfrZq+pC39BygcT+E7OI=
+modernc.org/libc v1.67.6/go.mod h1:JAhxUVlolfYDErnwiqaLvUqc8nfb2r6S6slAgZOnaiE=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
+modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.46.1 h1:eFJ2ShBLIEnUWlLy12raN0Z1plqmFX9Qe3rjQTKt6sU=
+modernc.org/sqlite v1.46.1/go.mod h1:CzbrU2lSB1DKUusvwGz7rqEKIq+NUd8GWuBBZDs9/nA=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=
+rsc.io/qr v0.2.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=
diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index a9db5afdd..92663a32d 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -1,27 +1,58 @@
 package agent
 
 import (
+	"errors"
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/skills"
-	"github.com/sipeed/picoclaw/pkg/tools"
 )
 
 type ContextBuilder struct {
-	workspace    string
-	skillsLoader *skills.SkillsLoader
-	memory       *MemoryStore
-	tools        *tools.ToolRegistry // Direct reference to tool registry
+	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.
+	// The cache auto-invalidates when workspace source files change (mtime check).
+	systemPromptMutex  sync.RWMutex
+	cachedSystemPrompt string
+	cachedAt           time.Time // max observed mtime across tracked paths at cache build time
+
+	// existedAtCache tracks which source file paths existed the last time the
+	// cache was built. This lets sourceFilesChanged detect files that are newly
+	// 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("PICOCLAW_HOME"); home != "" {
+		return home
+	}
 	home, err := os.UserHomeDir()
 	if err != nil {
 		return ""
@@ -32,8 +63,11 @@ func getGlobalConfigDir() string {
 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("PICOCLAW_BUILTIN_SKILLS"))
+	if builtinSkillsDir == "" {
+		wd, _ := os.Getwd()
+		builtinSkillsDir = filepath.Join(wd, "skills")
+	}
 	globalSkillsDir := filepath.Join(getGlobalConfigDir(), "skills")
 
 	return &ContextBuilder{
@@ -43,69 +77,51 @@ func NewContextBuilder(workspace string) *ContextBuilder {
 	}
 }
 
-// SetToolsRegistry sets the tools registry for dynamic tool summary generation.
-func (cb *ContextBuilder) SetToolsRegistry(registry *tools.ToolRegistry) {
-	cb.tools = registry
-}
-
 func (cb *ContextBuilder) getIdentity() string {
-	now := time.Now().Format("2006-01-02 15:04 (Monday)")
 	workspacePath, _ := filepath.Abs(filepath.Join(cb.workspace))
-	runtime := fmt.Sprintf("%s %s, Go %s", runtime.GOOS, runtime.GOARCH, runtime.Version())
-
-	// Build tools section dynamically
-	toolsSection := cb.buildToolsSection()
+	toolDiscovery := cb.getDiscoveryRule()
 
 	return fmt.Sprintf(`# picoclaw 🦞
 
 You are picoclaw, a helpful AI assistant.
 
-## Current Time
-%s
-
-## Runtime
-%s
-
 ## Workspace
 Your workspace is at: %s
 - Memory: %s/memory/MEMORY.md
 - Daily Notes: %s/memory/YYYYMM/YYYYMMDD.md
 - Skills: %s/skills/{skill-name}/SKILL.md
 
-%s
-
 ## Important Rules
 
 1. **ALWAYS use tools** - When you need to perform an action (schedule reminders, send messages, execute commands, etc.), you MUST call the appropriate tool. Do NOT just say you'll do it or pretend to do it.
 
 2. **Be helpful and accurate** - When using tools, briefly explain what you're doing.
 
-3. **Memory** - When interacting with me if something seems memorable, update %s/memory/MEMORY.md`,
-		now, runtime, workspacePath, workspacePath, workspacePath, workspacePath, toolsSection, workspacePath)
+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.
+
+%s`,
+		workspacePath, workspacePath, workspacePath, workspacePath, workspacePath, toolDiscovery)
 }
 
-func (cb *ContextBuilder) buildToolsSection() string {
-	if cb.tools == nil {
+func (cb *ContextBuilder) getDiscoveryRule() string {
+	if !cb.toolDiscoveryBM25 && !cb.toolDiscoveryRegex {
 		return ""
 	}
 
-	summaries := cb.tools.GetSummaries()
-	if len(summaries) == 0 {
-		return ""
+	var toolNames []string
+	if cb.toolDiscoveryBM25 {
+		toolNames = append(toolNames, `"tool_search_tool_bm25"`)
+	}
+	if cb.toolDiscoveryRegex {
+		toolNames = append(toolNames, `"tool_search_tool_regex"`)
 	}
 
-	var sb strings.Builder
-	sb.WriteString("## Available Tools\n\n")
-	sb.WriteString(
-		"**CRITICAL**: You MUST use tools to perform actions. Do NOT pretend to execute commands or schedule tasks.\n\n",
+	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 "),
 	)
-	sb.WriteString("You have access to the following tools:\n\n")
-	for _, s := range summaries {
-		sb.WriteString(s)
-		sb.WriteString("\n")
-	}
-
-	return sb.String()
 }
 
 func (cb *ContextBuilder) BuildSystemPrompt() string {
@@ -140,6 +156,277 @@ The following skills extend your capabilities. To use a skill, read its SKILL.md
 	return strings.Join(parts, "\n\n---\n\n")
 }
 
+// BuildSystemPromptWithCache returns the cached system prompt if available
+// and source files haven't changed, otherwise builds and caches it.
+// Source file changes are detected via mtime checks (cheap stat calls).
+func (cb *ContextBuilder) BuildSystemPromptWithCache() string {
+	// Try read lock first — fast path when cache is valid
+	cb.systemPromptMutex.RLock()
+	if cb.cachedSystemPrompt != "" && !cb.sourceFilesChangedLocked() {
+		result := cb.cachedSystemPrompt
+		cb.systemPromptMutex.RUnlock()
+		return result
+	}
+	cb.systemPromptMutex.RUnlock()
+
+	// Acquire write lock for building
+	cb.systemPromptMutex.Lock()
+	defer cb.systemPromptMutex.Unlock()
+
+	// Double-check: another goroutine may have rebuilt while we waited
+	if cb.cachedSystemPrompt != "" && !cb.sourceFilesChangedLocked() {
+		return cb.cachedSystemPrompt
+	}
+
+	// Snapshot the baseline (existence + max mtime) BEFORE building the prompt.
+	// This way cachedAt reflects the pre-build state: if a file is modified
+	// during BuildSystemPrompt, its new mtime will be > baseline.maxMtime,
+	// so the next sourceFilesChangedLocked check will correctly trigger a
+	// rebuild. The alternative (baseline after build) risks caching stale
+	// content with a too-new baseline, making the staleness invisible.
+	baseline := cb.buildCacheBaseline()
+	prompt := cb.BuildSystemPrompt()
+	cb.cachedSystemPrompt = prompt
+	cb.cachedAt = baseline.maxMtime
+	cb.existedAtCache = baseline.existed
+	cb.skillFilesAtCache = baseline.skillFiles
+
+	logger.DebugCF("agent", "System prompt cached",
+		map[string]any{
+			"length": len(prompt),
+		})
+
+	return prompt
+}
+
+// InvalidateCache clears the cached system prompt.
+// Normally not needed because the cache auto-invalidates via mtime checks,
+// but this is useful for tests or explicit reload commands.
+func (cb *ContextBuilder) InvalidateCache() {
+	cb.systemPromptMutex.Lock()
+	defer cb.systemPromptMutex.Unlock()
+
+	cb.cachedSystemPrompt = ""
+	cb.cachedAt = time.Time{}
+	cb.existedAtCache = nil
+	cb.skillFilesAtCache = nil
+
+	logger.DebugCF("agent", "System prompt cache invalidated", nil)
+}
+
+// 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"),
+	}
+}
+
+// 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
+	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 {
+	skillRoots := cb.skillRoots()
+
+	// 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 {
+		info, err := os.Stat(p)
+		existed[p] = err == nil
+		if 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
+		})
+	}
+
+	// If no tracked files exist yet (empty workspace), maxMtime is zero.
+	// Use a very old non-zero time so that:
+	// 1. cachedAt.IsZero() won't trigger perpetual rebuilds.
+	// 2. Any real file created afterwards has mtime > cachedAt, so it
+	//    will be detected by fileChangedSince (unlike time.Now() which
+	//    could race with a file whose mtime <= Now).
+	if maxMtime.IsZero() {
+		maxMtime = time.Unix(1, 0)
+	}
+
+	return cacheBaseline{existed: existed, skillFiles: skillFiles, maxMtime: maxMtime}
+}
+
+// sourceFilesChangedLocked checks whether any workspace source file has been
+// modified, created, or deleted since the cache was last built.
+//
+// IMPORTANT: The caller MUST hold at least a read lock on systemPromptMutex.
+// Go's sync.RWMutex is not reentrant, so this function must NOT acquire the
+// lock itself (it would deadlock when called from BuildSystemPromptWithCache
+// which already holds RLock or Lock).
+func (cb *ContextBuilder) sourceFilesChangedLocked() bool {
+	if cb.cachedAt.IsZero() {
+		return true
+	}
+
+	// Check tracked source files (bootstrap + memory).
+	if slices.ContainsFunc(cb.sourcePaths(), cb.fileChangedSince) {
+		return true
+	}
+
+	// --- Skill roots (workspace/global/builtin) ---
+	//
+	// 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
+		}
+	}
+	if skillFilesChangedSince(cb.skillRoots(), cb.skillFilesAtCache) {
+		return true
+	}
+
+	return false
+}
+
+// fileChangedSince returns true if a tracked source file has been modified,
+// newly created, or deleted since the cache was built.
+//
+// Four cases:
+//   - existed at cache time, exists now -> check mtime
+//   - existed at cache time, gone now   -> changed (deleted)
+//   - absent at cache time,  exists now -> changed (created)
+//   - absent at cache time,  gone now   -> no change
+func (cb *ContextBuilder) fileChangedSince(path string) bool {
+	// Defensive: if existedAtCache was never initialized, treat as changed
+	// so the cache rebuilds rather than silently serving stale data.
+	if cb.existedAtCache == nil {
+		return true
+	}
+
+	existedBefore := cb.existedAtCache[path]
+	info, err := os.Stat(path)
+	existsNow := err == nil
+
+	if existedBefore != existsNow {
+		return true // file was created or deleted
+	}
+	if !existsNow {
+		return false // didn't exist before, doesn't exist now
+	}
+	return info.ModTime().After(cb.cachedAt)
+}
+
+// errWalkStop is a sentinel error used to stop filepath.WalkDir early.
+// Using a dedicated error (instead of fs.SkipAll) makes the early-exit
+// intent explicit and avoids the nilerr linter warning that would fire
+// if the callback returned nil when its err parameter is non-nil.
+var errWalkStop = errors.New("walk stop")
+
+// 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
+	}
+
+	// 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",
@@ -159,6 +446,28 @@ func (cb *ContextBuilder) LoadBootstrapFiles() string {
 	return sb.String()
 }
 
+// buildDynamicContext returns a short dynamic context string with per-request info.
+// This changes every request (time, session) so it is NOT part of the cached prompt.
+// LLM-side KV cache reuse is achieved by each provider adapter's native mechanism:
+//   - Anthropic: per-block cache_control (ephemeral) on the static SystemParts block
+//   - OpenAI / Codex: prompt_cache_key for prefix-based caching
+//
+// 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 {
+	now := time.Now().Format("2006-01-02 15:04 (Monday)")
+	rt := fmt.Sprintf("%s %s, Go %s", runtime.GOOS, runtime.GOARCH, runtime.Version())
+
+	var sb strings.Builder
+	fmt.Fprintf(&sb, "## Current Time\n%s\n\n## Runtime\n%s", now, rt)
+
+	if channel != "" && chatID != "" {
+		fmt.Fprintf(&sb, "\n\n## Current Session\nChannel: %s\nChat ID: %s", channel, chatID)
+	}
+
+	return sb.String()
+}
+
 func (cb *ContextBuilder) BuildMessages(
 	history []providers.Message,
 	summary string,
@@ -168,23 +477,65 @@ func (cb *ContextBuilder) BuildMessages(
 ) []providers.Message {
 	messages := []providers.Message{}
 
-	systemPrompt := cb.BuildSystemPrompt()
+	// The static part (identity, bootstrap, skills, memory) is cached locally to
+	// avoid repeated file I/O and string building on every call (fixes issue #607).
+	// Dynamic parts (time, session, summary) are appended per request.
+	// Everything is sent as a single system message for provider compatibility:
+	// - Anthropic adapter extracts messages[0] (Role=="system") and maps its content
+	//   to the top-level "system" parameter in the Messages API request. A single
+	//   contiguous system block makes this extraction straightforward.
+	// - Codex maps only the first system message to its instructions field.
+	// - OpenAI-compat passes messages through as-is.
+	staticPrompt := cb.BuildSystemPromptWithCache()
 
-	// Add Current Session info if provided
-	if channel != "" && chatID != "" {
-		systemPrompt += fmt.Sprintf("\n\n## Current Session\nChannel: %s\nChat ID: %s", channel, chatID)
+	// Build short dynamic context (time, runtime, session) — changes per request
+	dynamicCtx := cb.buildDynamicContext(channel, chatID)
+
+	// Compose a single system message: static (cached) + dynamic + optional summary.
+	// Keeping all system content in one message ensures every provider adapter can
+	// extract it correctly (Anthropic adapter -> top-level system param,
+	// Codex -> instructions field).
+	//
+	// SystemParts carries the same content as structured blocks so that
+	// cache-aware adapters (Anthropic) can set per-block cache_control.
+	// The static block is marked "ephemeral" — its prefix hash is stable
+	// across requests, enabling LLM-side KV cache reuse.
+	stringParts := []string{staticPrompt, dynamicCtx}
+
+	contentBlocks := []providers.ContentBlock{
+		{Type: "text", Text: staticPrompt, CacheControl: &providers.CacheControl{Type: "ephemeral"}},
+		{Type: "text", Text: dynamicCtx},
 	}
 
-	// Log system prompt summary for debugging (debug mode only)
+	if summary != "" {
+		summaryText := fmt.Sprintf(
+			"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
+				"for reference only. It may be incomplete or outdated — always defer to explicit instructions.\n\n%s",
+			summary)
+		stringParts = append(stringParts, summaryText)
+		contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: summaryText})
+	}
+
+	fullSystemPrompt := strings.Join(stringParts, "\n\n---\n\n")
+
+	// Log system prompt summary for debugging (debug mode only).
+	// Read cachedSystemPrompt under lock to avoid a data race with
+	// concurrent InvalidateCache / BuildSystemPromptWithCache writes.
+	cb.systemPromptMutex.RLock()
+	isCached := cb.cachedSystemPrompt != ""
+	cb.systemPromptMutex.RUnlock()
+
 	logger.DebugCF("agent", "System prompt built",
 		map[string]any{
-			"total_chars":   len(systemPrompt),
-			"total_lines":   strings.Count(systemPrompt, "\n") + 1,
-			"section_count": strings.Count(systemPrompt, "\n\n---\n\n") + 1,
+			"static_chars":  len(staticPrompt),
+			"dynamic_chars": len(dynamicCtx),
+			"total_chars":   len(fullSystemPrompt),
+			"has_summary":   summary != "",
+			"cached":        isCached,
 		})
 
 	// Log preview of system prompt (avoid logging huge content)
-	preview := systemPrompt
+	preview := fullSystemPrompt
 	if len(preview) > 500 {
 		preview = preview[:500] + "... (truncated)"
 	}
@@ -193,24 +544,30 @@ func (cb *ContextBuilder) BuildMessages(
 			"preview": preview,
 		})
 
-	if summary != "" {
-		systemPrompt += "\n\n## Summary of Previous Conversation\n\n" + summary
-	}
-
 	history = sanitizeHistoryForProvider(history)
 
+	// Single system message containing all context — compatible with all providers.
+	// SystemParts enables cache-aware adapters to set per-block cache_control;
+	// Content is the concatenated fallback for adapters that don't read SystemParts.
 	messages = append(messages, providers.Message{
-		Role:    "system",
-		Content: systemPrompt,
+		Role:        "system",
+		Content:     fullSystemPrompt,
+		SystemParts: contentBlocks,
 	})
 
+	// Add conversation history
 	messages = append(messages, history...)
 
+	// 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
@@ -224,13 +581,32 @@ func sanitizeHistoryForProvider(history []providers.Message) []providers.Message
 	sanitized := make([]providers.Message, 0, len(history))
 	for _, msg := range history {
 		switch msg.Role {
+		case "system":
+			// Drop system messages from history. BuildMessages always
+			// constructs its own single system message (static + dynamic +
+			// summary); extra system messages would break providers that
+			// only accept one (Anthropic, Codex).
+			logger.DebugCF("agent", "Dropping system message from history", map[string]any{})
+			continue
+
 		case "tool":
 			if len(sanitized) == 0 {
 				logger.DebugCF("agent", "Dropping orphaned leading tool message", map[string]any{})
 				continue
 			}
-			last := sanitized[len(sanitized)-1]
-			if last.Role != "assistant" || len(last.ToolCalls) == 0 {
+			// Walk backwards to find the nearest assistant message,
+			// skipping over any preceding tool messages (multi-tool-call case).
+			foundAssistant := false
+			for i := len(sanitized) - 1; i >= 0; i-- {
+				if sanitized[i].Role == "tool" {
+					continue
+				}
+				if sanitized[i].Role == "assistant" && len(sanitized[i].ToolCalls) > 0 {
+					foundAssistant = true
+				}
+				break
+			}
+			if !foundAssistant {
 				logger.DebugCF("agent", "Dropping orphaned tool message", map[string]any{})
 				continue
 			}
@@ -259,7 +635,60 @@ 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))
+	for i := 0; i < len(sanitized); i++ {
+		msg := sanitized[i]
+		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(
@@ -288,25 +717,6 @@ func (cb *ContextBuilder) AddAssistantMessage(
 	return messages
 }
 
-func (cb *ContextBuilder) loadSkills() string {
-	allSkills := cb.skillsLoader.ListSkills()
-	if len(allSkills) == 0 {
-		return ""
-	}
-
-	var skillNames []string
-	for _, s := range allSkills {
-		skillNames = append(skillNames, s.Name)
-	}
-
-	content := cb.skillsLoader.LoadSkillsForContext(skillNames)
-	if content == "" {
-		return ""
-	}
-
-	return "# Skill Definitions\n\n" + content
-}
-
 // GetSkillsInfo returns information about loaded skills.
 func (cb *ContextBuilder) GetSkillsInfo() map[string]any {
 	allSkills := cb.skillsLoader.ListSkills()
diff --git a/pkg/agent/context_cache_test.go b/pkg/agent/context_cache_test.go
new file mode 100644
index 000000000..707510820
--- /dev/null
+++ b/pkg/agent/context_cache_test.go
@@ -0,0 +1,669 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// setupWorkspace creates a temporary workspace with standard directories and optional files.
+// Returns the tmpDir path; caller should defer os.RemoveAll(tmpDir).
+func setupWorkspace(t *testing.T, files map[string]string) string {
+	t.Helper()
+	tmpDir, err := os.MkdirTemp("", "picoclaw-test-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.MkdirAll(filepath.Join(tmpDir, "memory"), 0o755)
+	os.MkdirAll(filepath.Join(tmpDir, "skills"), 0o755)
+	for name, content := range files {
+		dir := filepath.Dir(filepath.Join(tmpDir, name))
+		os.MkdirAll(dir, 0o755)
+		if err := os.WriteFile(filepath.Join(tmpDir, name), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return tmpDir
+}
+
+// TestSingleSystemMessage verifies that BuildMessages always produces exactly one
+// system message regardless of summary/history variations.
+// Fix: multiple system messages break Anthropic (top-level system param) and
+// Codex (only reads last system message as instructions).
+func TestSingleSystemMessage(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
+		history []providers.Message
+		summary string
+		message string
+	}{
+		{
+			name:    "no summary, no history",
+			summary: "",
+			message: "hello",
+		},
+		{
+			name:    "with summary",
+			summary: "Previous conversation discussed X",
+			message: "hello",
+		},
+		{
+			name: "with history and summary",
+			history: []providers.Message{
+				{Role: "user", Content: "hi"},
+				{Role: "assistant", Content: "hello"},
+			},
+			summary: strings.Repeat("Long summary text. ", 50),
+			message: "new message",
+		},
+		{
+			name: "system message in history is filtered",
+			history: []providers.Message{
+				{Role: "system", Content: "stale system prompt from previous session"},
+				{Role: "user", Content: "hi"},
+				{Role: "assistant", Content: "hello"},
+			},
+			summary: "",
+			message: "new message",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			msgs := cb.BuildMessages(tt.history, tt.summary, tt.message, nil, "test", "chat1")
+
+			systemCount := 0
+			for _, m := range msgs {
+				if m.Role == "system" {
+					systemCount++
+				}
+			}
+			if systemCount != 1 {
+				t.Errorf("expected exactly 1 system message, got %d", systemCount)
+			}
+			if msgs[0].Role != "system" {
+				t.Errorf("first message should be system, got %s", msgs[0].Role)
+			}
+			if msgs[len(msgs)-1].Role != "user" {
+				t.Errorf("last message should be user, got %s", msgs[len(msgs)-1].Role)
+			}
+
+			// System message must contain identity (static) and time (dynamic)
+			sys := msgs[0].Content
+			if !strings.Contains(sys, "picoclaw") {
+				t.Error("system message missing identity")
+			}
+			if !strings.Contains(sys, "Current Time") {
+				t.Error("system message missing dynamic time context")
+			}
+
+			// Summary handling
+			if tt.summary != "" {
+				if !strings.Contains(sys, "CONTEXT_SUMMARY:") {
+					t.Error("summary present but CONTEXT_SUMMARY prefix missing")
+				}
+				if !strings.Contains(sys, tt.summary[:20]) {
+					t.Error("summary content not found in system message")
+				}
+			} else {
+				if strings.Contains(sys, "CONTEXT_SUMMARY:") {
+					t.Error("CONTEXT_SUMMARY should not appear without summary")
+				}
+			}
+		})
+	}
+}
+
+// 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,
+// memory, or skills were invisible until process restart.
+func TestMtimeAutoInvalidation(t *testing.T) {
+	tests := []struct {
+		name       string
+		file       string // relative path inside workspace
+		contentV1  string
+		contentV2  string
+		checkField string // substring to verify in rebuilt prompt
+	}{
+		{
+			name:       "bootstrap file change",
+			file:       "IDENTITY.md",
+			contentV1:  "# Original Identity",
+			contentV2:  "# Updated Identity",
+			checkField: "Updated Identity",
+		},
+		{
+			name:       "memory file change",
+			file:       "memory/MEMORY.md",
+			contentV1:  "# Memory\nUser likes Go.",
+			contentV2:  "# Memory\nUser likes Rust.",
+			checkField: "User likes Rust",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir := setupWorkspace(t, map[string]string{tt.file: tt.contentV1})
+			defer os.RemoveAll(tmpDir)
+
+			cb := NewContextBuilder(tmpDir)
+
+			sp1 := cb.BuildSystemPromptWithCache()
+
+			// Overwrite file and set future mtime to ensure detection.
+			// Use 2s offset for filesystem mtime resolution safety (some FS
+			// have 1s or coarser granularity, especially in CI containers).
+			fullPath := filepath.Join(tmpDir, tt.file)
+			os.WriteFile(fullPath, []byte(tt.contentV2), 0o644)
+			future := time.Now().Add(2 * time.Second)
+			os.Chtimes(fullPath, future, future)
+
+			// Verify sourceFilesChangedLocked detects the mtime change
+			cb.systemPromptMutex.RLock()
+			changed := cb.sourceFilesChangedLocked()
+			cb.systemPromptMutex.RUnlock()
+			if !changed {
+				t.Fatalf("sourceFilesChangedLocked() should detect %s change", tt.file)
+			}
+
+			// Should auto-rebuild without explicit InvalidateCache()
+			sp2 := cb.BuildSystemPromptWithCache()
+			if sp1 == sp2 {
+				t.Errorf("cache not rebuilt after %s change", tt.file)
+			}
+			if !strings.Contains(sp2, tt.checkField) {
+				t.Errorf("rebuilt prompt missing expected content %q", tt.checkField)
+			}
+		})
+	}
+
+	// Skills directory mtime change
+	t.Run("skills dir change", func(t *testing.T) {
+		tmpDir := setupWorkspace(t, nil)
+		defer os.RemoveAll(tmpDir)
+
+		cb := NewContextBuilder(tmpDir)
+		_ = cb.BuildSystemPromptWithCache() // populate cache
+
+		// Touch skills directory (simulate new skill installed)
+		skillsDir := filepath.Join(tmpDir, "skills")
+		future := time.Now().Add(2 * time.Second)
+		os.Chtimes(skillsDir, future, future)
+
+		// Verify sourceFilesChangedLocked detects it (cache is rebuilt)
+		// We confirm by checking internal state: a second call should rebuild.
+		cb.systemPromptMutex.RLock()
+		changed := cb.sourceFilesChangedLocked()
+		cb.systemPromptMutex.RUnlock()
+		if !changed {
+			t.Error("sourceFilesChangedLocked() should detect skills dir mtime change")
+		}
+	})
+}
+
+// TestExplicitInvalidateCache verifies that InvalidateCache() forces a rebuild
+// 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",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	sp1 := cb.BuildSystemPromptWithCache()
+	cb.InvalidateCache()
+	sp2 := cb.BuildSystemPromptWithCache()
+
+	if sp1 != sp2 {
+		t.Error("prompt should be identical after invalidate+rebuild when files unchanged")
+	}
+
+	// Verify cachedAt was reset
+	cb.InvalidateCache()
+	cb.systemPromptMutex.RLock()
+	if !cb.cachedAt.IsZero() {
+		t.Error("cachedAt should be zero after InvalidateCache()")
+	}
+	cb.systemPromptMutex.RUnlock()
+}
+
+// TestCacheStability verifies that the static prompt is stable across repeated calls
+// 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",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	results := make([]string, 5)
+	for i := range results {
+		results[i] = cb.BuildSystemPromptWithCache()
+	}
+	for i := 1; i < len(results); i++ {
+		if results[i] != results[0] {
+			t.Errorf("cached prompt changed between call 0 and %d", i)
+		}
+	}
+
+	// Static prompt must NOT contain per-request data
+	if strings.Contains(results[0], "Current Time") {
+		t.Error("static cached prompt should not contain time (added dynamically)")
+	}
+}
+
+// TestNewFileCreationInvalidatesCache verifies that creating a source file that
+// did not exist when the cache was built triggers a cache rebuild.
+// This catches the "from nothing to something" edge case that the old
+// modifiedSince (return false on stat error) would miss.
+func TestNewFileCreationInvalidatesCache(t *testing.T) {
+	tests := []struct {
+		name       string
+		file       string // relative path inside workspace
+		content    string
+		checkField string // substring to verify in rebuilt prompt
+	}{
+		{
+			name:       "new bootstrap file",
+			file:       "SOUL.md",
+			content:    "# Soul\nBe kind and helpful.",
+			checkField: "Be kind and helpful",
+		},
+		{
+			name:       "new memory file",
+			file:       "memory/MEMORY.md",
+			content:    "# Memory\nUser prefers dark mode.",
+			checkField: "User prefers dark mode",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Start with an empty workspace (no bootstrap/memory files)
+			tmpDir := setupWorkspace(t, nil)
+			defer os.RemoveAll(tmpDir)
+
+			cb := NewContextBuilder(tmpDir)
+
+			// Populate cache — file does not exist yet
+			sp1 := cb.BuildSystemPromptWithCache()
+			if strings.Contains(sp1, tt.checkField) {
+				t.Fatalf("prompt should not contain %q before file is created", tt.checkField)
+			}
+
+			// Create the file after cache was built
+			fullPath := filepath.Join(tmpDir, tt.file)
+			os.MkdirAll(filepath.Dir(fullPath), 0o755)
+			if err := os.WriteFile(fullPath, []byte(tt.content), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			// Set future mtime to guarantee detection
+			future := time.Now().Add(2 * time.Second)
+			os.Chtimes(fullPath, future, future)
+
+			// Cache should auto-invalidate because file went from absent -> present
+			sp2 := cb.BuildSystemPromptWithCache()
+			if !strings.Contains(sp2, tt.checkField) {
+				t.Errorf("cache not invalidated on new file creation: expected %q in prompt", tt.checkField)
+			}
+		})
+	}
+}
+
+// TestSkillFileContentChange verifies that modifying a skill file's content
+// (not just the directory structure) invalidates the cache.
+// This is the scenario where directory mtime alone is insufficient — on most
+// filesystems, editing a file inside a directory does NOT update the parent
+// directory's mtime.
+func TestSkillFileContentChange(t *testing.T) {
+	skillMD := `---
+name: test-skill
+description: "A test skill"
+---
+# Test Skill v1
+Original content.`
+
+	tmpDir := setupWorkspace(t, map[string]string{
+		"skills/test-skill/SKILL.md": skillMD,
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	// Populate cache
+	sp1 := cb.BuildSystemPromptWithCache()
+	_ = sp1 // cache is warm
+
+	// Modify the skill file content (without touching the skills/ directory)
+	updatedSkillMD := `---
+name: test-skill
+description: "An updated test skill"
+---
+# Test Skill v2
+Updated content.`
+
+	skillPath := filepath.Join(tmpDir, "skills", "test-skill", "SKILL.md")
+	if err := os.WriteFile(skillPath, []byte(updatedSkillMD), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Set future mtime on the skill file only (NOT the directory)
+	future := time.Now().Add(2 * time.Second)
+	os.Chtimes(skillPath, future, future)
+
+	// Verify that sourceFilesChangedLocked detects the content change
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Error("sourceFilesChangedLocked() should detect skill file content change")
+	}
+
+	// Verify cache is actually rebuilt with new content
+	sp2 := cb.BuildSystemPromptWithCache()
+	if sp1 == sp2 && strings.Contains(sp1, "test-skill") {
+		// If the skill appeared in the prompt and the prompt didn't change,
+		// the cache was not invalidated.
+		t.Error("cache should be invalidated when skill file content changes")
+	}
+}
+
+// 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.",
+		"SOUL.md":              "# Soul\nBe helpful.",
+		"memory/MEMORY.md":     "# Memory\nUser prefers Go.",
+		"skills/demo/SKILL.md": "---\nname: demo\ndescription: \"demo skill\"\n---\n# Demo",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	const goroutines = 20
+	const iterations = 50
+
+	var wg sync.WaitGroup
+	errs := make(chan string, goroutines*iterations)
+
+	for g := range goroutines {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for i := range iterations {
+				result := cb.BuildSystemPromptWithCache()
+				if result == "" {
+					errs <- "empty prompt returned"
+					return
+				}
+				if !strings.Contains(result, "picoclaw") {
+					errs <- "prompt missing identity"
+					return
+				}
+
+				// Also exercise BuildMessages concurrently
+				msgs := cb.BuildMessages(nil, "", "hello", nil, "test", "chat")
+				if len(msgs) < 2 {
+					errs <- "BuildMessages returned fewer than 2 messages"
+					return
+				}
+				if msgs[0].Role != "system" {
+					errs <- "first message not system"
+					return
+				}
+
+				// Occasionally invalidate to exercise the write path
+				if i%10 == 0 {
+					cb.InvalidateCache()
+				}
+			}
+		}(g)
+	}
+
+	wg.Wait()
+	close(errs)
+
+	for errMsg := range errs {
+		t.Errorf("concurrent access error: %s", errMsg)
+	}
+}
+
+// BenchmarkBuildMessagesWithCache measures caching performance.
+
+// TestEmptyWorkspaceBaselineDetectsNewFiles verifies that when the cache is
+// built on an empty workspace (no tracked files exist), creating a file
+// afterwards still triggers cache invalidation. This validates the
+// time.Unix(1, 0) fallback for maxMtime: any real file's mtime is after epoch,
+// so fileChangedSince correctly detects the absent -> present transition AND
+// the mtime comparison succeeds even without artificially inflated Chtimes.
+func TestEmptyWorkspaceBaselineDetectsNewFiles(t *testing.T) {
+	// Empty workspace: no bootstrap files, no memory, no skills content.
+	tmpDir := setupWorkspace(t, nil)
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	// Build cache — all tracked files are absent, maxMtime falls back to epoch.
+	sp1 := cb.BuildSystemPromptWithCache()
+
+	// Create a bootstrap file with natural mtime (no Chtimes manipulation).
+	// The file's mtime should be the current wall-clock time, which is
+	// strictly after time.Unix(1, 0).
+	soulPath := filepath.Join(tmpDir, "SOUL.md")
+	if err := os.WriteFile(soulPath, []byte("# Soul\nNewly created."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Cache should detect the new file via existedAtCache (absent -> present).
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Fatal("sourceFilesChangedLocked should detect newly created file on empty workspace")
+	}
+
+	sp2 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(sp2, "Newly created") {
+		t.Error("rebuilt prompt should contain new file content")
+	}
+	if sp1 == sp2 {
+		t.Error("cache should have been invalidated after file creation")
+	}
+}
+
+// BenchmarkBuildMessagesWithCache measures caching performance.
+func BenchmarkBuildMessagesWithCache(b *testing.B) {
+	tmpDir, _ := os.MkdirTemp("", "picoclaw-bench-*")
+	defer os.RemoveAll(tmpDir)
+
+	os.MkdirAll(filepath.Join(tmpDir, "memory"), 0o755)
+	os.MkdirAll(filepath.Join(tmpDir, "skills"), 0o755)
+	for _, name := range []string{"IDENTITY.md", "SOUL.md", "USER.md"} {
+		os.WriteFile(filepath.Join(tmpDir, name), []byte(strings.Repeat("Content.\n", 10)), 0o644)
+	}
+
+	cb := NewContextBuilder(tmpDir)
+	history := []providers.Message{
+		{Role: "user", Content: "previous message"},
+		{Role: "assistant", Content: "previous response"},
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = cb.BuildMessages(history, "summary", "new message", nil, "cli", "test")
+	}
+}
diff --git a/pkg/agent/context_test.go b/pkg/agent/context_test.go
new file mode 100644
index 000000000..5756ed911
--- /dev/null
+++ b/pkg/agent/context_test.go
@@ -0,0 +1,283 @@
+package agent
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func msg(role, content string) providers.Message {
+	return providers.Message{Role: role, Content: content}
+}
+
+func assistantWithTools(toolIDs ...string) providers.Message {
+	calls := make([]providers.ToolCall, len(toolIDs))
+	for i, id := range toolIDs {
+		calls[i] = providers.ToolCall{ID: id, Type: "function"}
+	}
+	return providers.Message{Role: "assistant", ToolCalls: calls}
+}
+
+func toolResult(id string) providers.Message {
+	return providers.Message{Role: "tool", Content: "result", ToolCallID: id}
+}
+
+func TestSanitizeHistoryForProvider_EmptyHistory(t *testing.T) {
+	result := sanitizeHistoryForProvider(nil)
+	if len(result) != 0 {
+		t.Fatalf("expected empty, got %d messages", len(result))
+	}
+
+	result = sanitizeHistoryForProvider([]providers.Message{})
+	if len(result) != 0 {
+		t.Fatalf("expected empty, got %d messages", len(result))
+	}
+}
+
+func TestSanitizeHistoryForProvider_SingleToolCall(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		assistantWithTools("A"),
+		toolResult("A"),
+		msg("assistant", "done"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 4 {
+		t.Fatalf("expected 4 messages, got %d", len(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_MultiToolCalls(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "do two things"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		toolResult("B"),
+		msg("assistant", "both 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")
+}
+
+func TestSanitizeHistoryForProvider_AssistantToolCallAfterPlainAssistant(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hi"),
+		msg("assistant", "thinking"),
+		assistantWithTools("A"),
+		toolResult("A"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 2 {
+		t.Fatalf("expected 2 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_OrphanedLeadingTool(t *testing.T) {
+	history := []providers.Message{
+		toolResult("A"),
+		msg("user", "hello"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 message, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user")
+}
+
+func TestSanitizeHistoryForProvider_ToolAfterUserDropped(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		toolResult("A"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 message, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user")
+}
+
+func TestSanitizeHistoryForProvider_ToolAfterAssistantNoToolCalls(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		msg("assistant", "hi"),
+		toolResult("A"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 2 {
+		t.Fatalf("expected 2 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_AssistantToolCallAtStart(t *testing.T) {
+	history := []providers.Message{
+		assistantWithTools("A"),
+		toolResult("A"),
+		msg("user", "hello"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 message, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user")
+}
+
+func TestSanitizeHistoryForProvider_MultiToolCallsThenNewRound(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "do two things"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		toolResult("B"),
+		msg("assistant", "done"),
+		msg("user", "hi"),
+		assistantWithTools("C"),
+		toolResult("C"),
+		msg("assistant", "done again"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 9 {
+		t.Fatalf("expected 9 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "tool", "assistant", "user", "assistant", "tool", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_ConsecutiveMultiToolRounds(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "start"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		toolResult("B"),
+		assistantWithTools("C", "D"),
+		toolResult("C"),
+		toolResult("D"),
+		msg("assistant", "all done"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 8 {
+		t.Fatalf("expected 8 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "tool", "assistant", "tool", "tool", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_PlainConversation(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		msg("assistant", "hi"),
+		msg("user", "how are you"),
+		msg("assistant", "fine"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 4 {
+		t.Fatalf("expected 4 messages, got %d", len(result))
+	}
+	assertRoles(t, result, "user", "assistant", "user", "assistant")
+}
+
+func roles(msgs []providers.Message) []string {
+	r := make([]string, len(msgs))
+	for i, m := range msgs {
+		r[i] = m.Role
+	}
+	return r
+}
+
+func assertRoles(t *testing.T, msgs []providers.Message, expected ...string) {
+	t.Helper()
+	if len(msgs) != len(expected) {
+		t.Fatalf("role count mismatch: got %v, want %v", roles(msgs), expected)
+	}
+	for i, exp := range expected {
+		if msgs[i].Role != exp {
+			t.Errorf("message[%d]: got role %q, want %q", i, msgs[i].Role, exp)
+		}
+	}
+}
+
+// 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/instance.go b/pkg/agent/instance.go
index dfbef9fbc..b60818875 100644
--- a/pkg/agent/instance.go
+++ b/pkg/agent/instance.go
@@ -1,8 +1,11 @@
 package agent
 
 import (
+	"fmt"
+	"log"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 
 	"github.com/sipeed/picoclaw/pkg/config"
@@ -15,22 +18,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.SessionManager
+	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.
@@ -47,19 +61,47 @@ func NewAgentInstance(
 	fallbacks := resolveAgentFallbacks(agentCfg, defaults)
 
 	restrict := defaults.RestrictToWorkspace
+	readRestrict := restrict && !defaults.AllowReadOutsideWorkspace
+
+	// Compile path whitelist patterns from config.
+	allowReadPaths := compilePatterns(cfg.Tools.AllowReadPaths)
+	allowWritePaths := compilePatterns(cfg.Tools.AllowWritePaths)
+
 	toolsRegistry := tools.NewToolRegistry()
-	toolsRegistry.Register(tools.NewReadFileTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewListDirTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewExecToolWithConfig(workspace, restrict, cfg))
-	toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict))
+
+	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)
+		if err != nil {
+			log.Fatalf("Critical error: unable to initialize exec tool: %v", err)
+		}
+		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)
 
-	contextBuilder := NewContextBuilder(workspace)
-	contextBuilder.SetToolsRegistry(toolsRegistry)
+	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 := ""
@@ -88,30 +130,110 @@ func NewAgentInstance(
 		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 := providers.ResolveCandidates(modelCfg, defaults.Provider)
+	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)
+
+	// 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 != "" {
+		lightModelCfg := providers.ModelConfig{Primary: rc.LightModel}
+		resolved := providers.ResolveCandidatesWithLookup(lightModelCfg, defaults.Provider, resolveFromModelList)
+		if len(resolved) > 0 {
+			router = routing.New(routing.RouterConfig{
+				LightModel: rc.LightModel,
+				Threshold:  rc.Threshold,
+			})
+			lightCandidates = resolved
+		} else {
+			log.Printf("routing: light_model %q not found in model_list — routing disabled for agent %q",
+				rc.LightModel, agentID)
+		}
+	}
 
 	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:             maxTokens,
+		SummarizeMessageThreshold: summarizeMessageThreshold,
+		SummarizeTokenPercent:     summarizeTokenPercent,
+		Provider:                  provider,
+		Sessions:                  sessionsManager,
+		ContextBuilder:            contextBuilder,
+		Tools:                     toolsRegistry,
+		Subagents:                 subagents,
+		SkillsFilter:              skillsFilter,
+		Candidates:                candidates,
+		Router:                    router,
+		LightCandidates:           lightCandidates,
 	}
 }
 
@@ -120,12 +242,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.
@@ -133,7 +256,7 @@ func resolveAgentModel(agentCfg *config.AgentConfig, defaults *config.AgentDefau
 	if agentCfg != nil && agentCfg.Model != nil && strings.TrimSpace(agentCfg.Model.Primary) != "" {
 		return strings.TrimSpace(agentCfg.Model.Primary)
 	}
-	return defaults.Model
+	return defaults.GetModelName()
 }
 
 // resolveAgentFallbacks resolves the fallback models for an agent.
@@ -144,6 +267,19 @@ func resolveAgentFallbacks(agentCfg *config.AgentConfig, defaults *config.AgentD
 	return defaults.ModelFallbacks
 }
 
+func compilePatterns(patterns []string) []*regexp.Regexp {
+	compiled := make([]*regexp.Regexp, 0, len(patterns))
+	for _, p := range patterns {
+		re, err := regexp.Compile(p)
+		if err != nil {
+			fmt.Printf("Warning: invalid path pattern %q: %v\n", p, err)
+			continue
+		}
+		compiled = append(compiled, re)
+	}
+	return compiled
+}
+
 func expandHome(path string) string {
 	if path == "" {
 		return path
diff --git a/pkg/agent/instance_test.go b/pkg/agent/instance_test.go
index fcc8e9bea..4f41ecd1c 100644
--- a/pkg/agent/instance_test.go
+++ b/pkg/agent/instance_test.go
@@ -93,3 +93,70 @@ func TestNewAgentInstance_DefaultsTemperatureWhenUnset(t *testing.T) {
 		t.Fatalf("Temperature = %f, want %f", agent.Temperature, 0.7)
 	}
 }
+
+func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
+	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",
+		},
+	}
+
+	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,
+						Model:     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)
+			}
+		})
+	}
+}
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index 2cfb77845..56a620094 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -9,7 +9,10 @@ package agent
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"path/filepath"
+	"regexp"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -17,15 +20,19 @@ import (
 
 	"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"
+	"github.com/sipeed/picoclaw/pkg/mcp"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/routing"
 	"github.com/sipeed/picoclaw/pkg/skills"
 	"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 {
@@ -37,6 +44,9 @@ type AgentLoop struct {
 	summarizing    sync.Map
 	fallback       *providers.FallbackChain
 	channelManager *channels.Manager
+	mediaStore     media.MediaStore
+	transcriber    voice.Transcriber
+	cmdRegistry    *commands.Registry
 
 	// Extracted components for better separation of concerns
 	compressor *ContextCompressor
@@ -50,17 +60,32 @@ type AgentLoop struct {
 
 // 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
+	UserMessage     string   // User message content (may include prefix)
+	Media           []string // media:// refs from inbound message
+	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)
 }
 
-func NewAgentLoop(cfg *config.Config, msgBus *bus.MessageBus, provider providers.LLMProvider) *AgentLoop {
+const (
+	defaultResponse           = "I've completed processing but have no response to give. Increase `max_tool_iterations` in config.json."
+	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
@@ -85,17 +110,21 @@ func NewAgentLoop(cfg *config.Config, msgBus *bus.MessageBus, provider providers
 	// Create cancellation context for graceful shutdown
 	cancelCtx, cancelFunc := context.WithCancel(context.Background())
 
-	return &AgentLoop{
-		bus:        msgBus,
-		cfg:        cfg,
-		registry:   registry,
-		state:      stateManager,
-		fallback:   fallbackChain,
-		compressor: compressor,
-		toolExec:   toolExec,
-		cancelCtx:  cancelCtx,
-		cancelFunc: cancelFunc,
+	al := &AgentLoop{
+		bus:         msgBus,
+		cfg:         cfg,
+		registry:    registry,
+		state:       stateManager,
+		summarizing: sync.Map{},
+		fallback:    fallbackChain,
+		cmdRegistry: commands.NewRegistry(commands.BuiltinDefinitions()),
+		compressor:  compressor,
+		toolExec:    toolExec,
+		cancelCtx:   cancelCtx,
+		cancelFunc:  cancelFunc,
 	}
+
+	return al
 }
 
 // registerSharedTools registers tools that are shared across all agents (web, message, spawn).
@@ -112,70 +141,237 @@ func registerSharedTools(
 		}
 
 		// Web tools
-		if searchTool := 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,
-		}); searchTool != nil {
-			agent.Tools.Register(searchTool)
+		if cfg.Tools.IsToolEnabled("web") {
+			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,
+				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,
+				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_fetch") {
+			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)
+			}
 		}
-		agent.Tools.Register(tools.NewWebFetchTool(50000))
 
 		// 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 {
-			msgBus.PublishOutbound(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,
+				})
 			})
-			return nil
-		})
-		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,
+			)
+			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) {
+			registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
+				MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
+				ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+			})
+
+			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 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)
-
-		// Update context builder with the complete tools registry
-		agent.ContextBuilder.SetToolsRegistry(agent.Tools)
+		if cfg.Tools.IsToolEnabled("spawn") {
+			if cfg.Tools.IsToolEnabled("subagent") {
+				subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace)
+				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)
+			} else {
+				logger.WarnCF("agent", "spawn tool requires subagent to be enabled", nil)
+			}
+		}
 	}
 }
 
 func (al *AgentLoop) Run(ctx context.Context) error {
 	al.running.Store(true)
 
+	// Initialize MCP servers for all agents
+	if al.cfg.Tools.IsToolEnabled("mcp") {
+		mcpManager := mcp.NewManager()
+		// Ensure MCP connections are cleaned up on exit, regardless of initialization success
+		// This fixes resource leak when LoadFromMCPConfig partially succeeds then fails
+		defer func() {
+			if err := mcpManager.Close(); err != nil {
+				logger.ErrorCF("agent", "Failed to close MCP manager",
+					map[string]any{
+						"error": err.Error(),
+					})
+			}
+		}()
+
+		defaultAgent := al.registry.GetDefaultAgent()
+		var workspacePath string
+		if defaultAgent != nil && defaultAgent.Workspace != "" {
+			workspacePath = defaultAgent.Workspace
+		} else {
+			workspacePath = al.cfg.WorkspacePath()
+		}
+
+		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(),
+				})
+		} else {
+			// 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)
+				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 al.cfg.Tools.MCP.Discovery.Enabled {
+							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(),
+							})
+					}
+				}
+			}
+			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 {
+					return fmt.Errorf(
+						"tool discovery is enabled but neither 'use_bm25' nor 'use_regex' is set to true in the configuration",
+					)
+				}
+
+				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))
+					}
+				}
+			}
+		}
+	}
+
 	for al.running.Load() {
 		select {
 		case <-ctx.Done():
@@ -186,33 +382,61 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 				continue
 			}
 
-			response, err := al.processMessage(ctx, msg)
-			if err != nil {
-				response = fmt.Sprintf("Error processing message: %v", err)
-			}
+			// Process message
+			func() {
+				// 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() {
+				// 	if al.mediaStore != nil && msg.MediaScope != "" {
+				// 		if releaseErr := al.mediaStore.ReleaseAll(msg.MediaScope); releaseErr != nil {
+				// 			logger.WarnCF("agent", "Failed to release media", map[string]any{
+				// 				"scope": msg.MediaScope,
+				// 				"error": releaseErr.Error(),
+				// 			})
+				// 		}
+				// 	}
+				// }()
 
-			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()
+				response, err := al.processMessage(ctx, msg)
+				if err != nil {
+					response = fmt.Sprintf("Error processing message: %v", err)
+				}
+
+				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(bus.OutboundMessage{
-						Channel: msg.Channel,
-						ChatID:  msg.ChatID,
-						Content: response,
-					})
+					if !alreadySent {
+						al.bus.PublishOutbound(ctx, bus.OutboundMessage{
+							Channel: msg.Channel,
+							ChatID:  msg.ChatID,
+							Content: response,
+						})
+						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},
+						)
+					}
 				}
-			}
+			}()
 		}
 	}
 
@@ -239,6 +463,106 @@ func (al *AgentLoop) SetChannelManager(cm *channels.Manager) {
 	al.channelManager = cm
 }
 
+// SetMediaStore injects a MediaStore for media lifecycle management.
+func (al *AgentLoop) SetMediaStore(s media.MediaStore) {
+	al.mediaStore = s
+
+	// Propagate store to send_file tools in all agents.
+	al.registry.ForEachTool("send_file", func(t tools.Tool) {
+		if sf, ok := t.(*tools.SendFileTool); ok {
+			sf.SetMediaStore(s)
+		}
+	})
+}
+
+// SetTranscriber injects a voice transcriber for agent-level audio transcription.
+func (al *AgentLoop) SetTranscriber(t voice.Transcriber) {
+	al.transcriber = t
+}
+
+var audioAnnotationRe = regexp.MustCompile(`\[(voice|audio)(?::[^\]]*)?\]`)
+
+// transcribeAudioInMessage resolves audio media refs, transcribes them, and
+// replaces audio annotations in msg.Content with the transcribed text.
+func (al *AgentLoop) transcribeAudioInMessage(ctx context.Context, msg bus.InboundMessage) bus.InboundMessage {
+	if al.transcriber == nil || al.mediaStore == nil || len(msg.Media) == 0 {
+		return msg
+	}
+
+	// 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
+	}
+
+	// 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
+}
+
+// inferMediaType determines the media type ("image", "audio", "video", "file")
+// from a filename and MIME content type.
+func inferMediaType(filename, contentType string) string {
+	ct := strings.ToLower(contentType)
+	fn := strings.ToLower(filename)
+
+	if strings.HasPrefix(ct, "image/") {
+		return "image"
+	}
+	if strings.HasPrefix(ct, "audio/") || ct == "application/ogg" {
+		return "audio"
+	}
+	if strings.HasPrefix(ct, "video/") {
+		return "video"
+	}
+
+	// Fallback: infer from extension
+	ext := filepath.Ext(fn)
+	switch ext {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg":
+		return "image"
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma", ".opus":
+		return "audio"
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return "video"
+	}
+
+	return "file"
+}
+
 // RecordLastChannel records the last active channel for this workspace.
 // This uses the atomic state save mechanism to prevent data loss on crash.
 func (al *AgentLoop) RecordLastChannel(channel string) error {
@@ -257,7 +581,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")
 }
 
@@ -278,14 +605,20 @@ 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) {
+func (al *AgentLoop) ProcessHeartbeat(
+	ctx context.Context,
+	content, channel, chatID string,
+) (string, error) {
 	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for heartbeat")
+	}
 	return al.runAgentLoop(ctx, agent, processOptions{
 		SessionKey:      "heartbeat",
 		Channel:         channel,
 		ChatID:          chatID,
 		UserMessage:     content,
-		DefaultResponse: "I've completed processing but have no response to give.",
+		DefaultResponse: defaultResponse,
 		EnableSummary:   false,
 		SendResponse:    false,
 		NoHistory:       true, // Don't load session history for heartbeat
@@ -300,66 +633,107 @@ 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,
-		})
+		},
+	)
+
+	msg = al.transcribeAudioInMessage(ctx, msg)
 
 	// 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 {
+	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 resetter, ok := tool.(interface{ ResetSentInRound() }); ok {
+			resetter.ResetSentInRound()
+		}
+	}
+
+	// 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,
+			"scope_key":     scopeKey,
+			"session_key":   sessionKey,
+			"matched_by":    route.MatchedBy,
+			"route_agent":   route.AgentID,
+			"route_channel": route.Channel,
+		})
+
+	opts := processOptions{
+		SessionKey:      sessionKey,
+		Channel:         msg.Channel,
+		ChatID:          msg.ChatID,
+		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
 	}
 
-	// Route to determine agent and session key
+	return al.runAgentLoop(ctx, agent, opts)
+}
+
+func (al *AgentLoop) resolveMessageRoute(msg bus.InboundMessage) (routing.ResolvedRoute, *AgentInstance, error) {
 	route := al.registry.ResolveRoute(routing.RouteInput{
 		Channel:    msg.Channel,
-		AccountID:  msg.Metadata["account_id"],
+		AccountID:  inboundMetadata(msg, metadataKeyAccountID),
 		Peer:       extractPeer(msg),
 		ParentPeer: extractParentPeer(msg),
-		GuildID:    msg.Metadata["guild_id"],
-		TeamID:     msg.Metadata["team_id"],
+		GuildID:    inboundMetadata(msg, metadataKeyGuildID),
+		TeamID:     inboundMetadata(msg, metadataKeyTeamID),
 	})
 
 	agent, ok := al.registry.GetAgent(route.AgentID)
 	if !ok {
 		agent = al.registry.GetDefaultAgent()
 	}
-
-	// 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
+	if agent == nil {
+		return routing.ResolvedRoute{}, nil, fmt.Errorf("no agent available for route (agent_id=%s)", route.AgentID)
 	}
 
-	logger.InfoCF("agent", "Routed message",
-		map[string]any{
-			"agent_id":    agent.ID,
-			"session_key": sessionKey,
-			"matched_by":  route.MatchedBy,
-		})
-
-	return al.runAgentLoop(ctx, agent, processOptions{
-		SessionKey:      sessionKey,
-		Channel:         msg.Channel,
-		ChatID:          msg.ChatID,
-		UserMessage:     msg.Content,
-		DefaultResponse: "I've completed processing but have no response to give.",
-		EnableSummary:   true,
-		SendResponse:    false,
-	})
+	return route, agent, nil
 }
 
-func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMessage) (string, error) {
+func resolveScopeKey(route routing.ResolvedRoute, msgSessionKey string) string {
+	if msgSessionKey != "" && strings.HasPrefix(msgSessionKey, sessionKeyAgentPrefix) {
+		return msgSessionKey
+	}
+	return route.SessionKey
+}
+
+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",
@@ -398,6 +772,9 @@ func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMe
 
 	// Use default agent for system messages
 	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for system message")
+	}
 
 	// Use the origin session for context
 	sessionKey := routing.BuildAgentMainSessionKey(agent.ID)
@@ -414,14 +791,21 @@ 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)
+func (al *AgentLoop) runAgentLoop(
+	ctx context.Context,
+	agent *AgentInstance,
+	opts processOptions,
+) (string, error) {
+	// 0. Record last channel for heartbeat notifications (skip internal channels and cli)
 	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()})
+				logger.WarnCF(
+					"agent",
+					"Failed to record last channel",
+					map[string]any{"error": err.Error()},
+				)
 			}
 		}
 	}
@@ -440,15 +824,19 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 		history,
 		summary,
 		opts.UserMessage,
-		nil,
+		opts.Media,
 		opts.Channel,
 		opts.ChatID,
 	)
 
-	// 3. Save user message to session
+	// Resolve media:// refs to base64 data URLs (streaming)
+	maxMediaSize := al.cfg.Agents.Defaults.GetMaxMediaSize()
+	messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize)
+
+	// 2. Save user message to session
 	agent.Sessions.AddMessage(opts.SessionKey, "user", opts.UserMessage)
 
-	// 4. Run LLM iteration loop
+	// 3. Run LLM iteration loop
 	finalContent, iteration, err := al.runLLMIteration(ctx, agent, messages, opts)
 	if err != nil {
 		return "", err
@@ -457,30 +845,30 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 	// 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
+	// 4. Handle empty response
 	if finalContent == "" {
 		finalContent = opts.DefaultResponse
 	}
 
-	// 6. Save final assistant message to session
+	// 5. Save final assistant message to session
 	agent.Sessions.AddMessage(opts.SessionKey, "assistant", finalContent)
 	agent.Sessions.Save(opts.SessionKey)
 
-	// 7. Optional: summarization
+	// 6. Optional: summarization
 	if opts.EnableSummary {
 		al.compressor.MaybeSummarize(agent, opts.SessionKey, opts.Channel, opts.ChatID)
 	}
 
-	// 8. Optional: send response via bus
+	// 7. Optional: send response via bus
 	if opts.SendResponse {
-		al.bus.PublishOutbound(bus.OutboundMessage{
+		al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 			Channel: opts.Channel,
 			ChatID:  opts.ChatID,
 			Content: finalContent,
 		})
 	}
 
-	// 9. Log response
+	// 8. Log response
 	responsePreview := utils.Truncate(finalContent, 120)
 	logger.InfoCF("agent", fmt.Sprintf("Response: %s", responsePreview),
 		map[string]any{
@@ -493,6 +881,62 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 	return finalContent, nil
 }
 
+func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string) {
+	if al.channelManager == nil {
+		return ""
+	}
+	if ch, ok := al.channelManager.GetChannel(channelName); ok {
+		return ch.ReasoningChannelID()
+	}
+	return ""
+}
+
+func (al *AgentLoop) handleReasoning(
+	ctx context.Context,
+	reasoningContent, channelName, channelID string,
+) {
+	if reasoningContent == "" || channelName == "" || channelID == "" {
+		return
+	}
+
+	// Check context cancellation before attempting to publish,
+	// since PublishOutbound's select may race between send and ctx.Done().
+	if ctx.Err() != nil {
+		return
+	}
+
+	// Use a short timeout so the goroutine does not block indefinitely when
+	// the outbound bus is full.  Reasoning output is best-effort; dropping it
+	// is acceptable to avoid goroutine accumulation.
+	pubCtx, pubCancel := context.WithTimeout(ctx, 5*time.Second)
+	defer pubCancel()
+
+	if err := al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{
+		Channel: channelName,
+		ChatID:  channelID,
+		Content: reasoningContent,
+	}); err != nil {
+		// Treat context.DeadlineExceeded / context.Canceled as expected
+		// (bus full under load, or parent canceled).  Check the error
+		// itself rather than ctx.Err(), because pubCtx may time out
+		// (5 s) while the parent ctx is still active.
+		// Also treat ErrBusClosed as expected — it occurs during normal
+		// shutdown when the bus is closed before all goroutines finish.
+		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) ||
+			errors.Is(err, bus.ErrBusClosed) {
+			logger.DebugCF("agent", "Reasoning publish skipped (timeout/cancel)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		} else {
+			logger.WarnCF("agent", "Failed to publish reasoning (best-effort)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		}
+	}
+}
+
 // runLLMIteration executes the LLM call loop with tool handling.
 func (al *AgentLoop) runLLMIteration(
 	ctx context.Context,
@@ -503,6 +947,12 @@ func (al *AgentLoop) runLLMIteration(
 	iteration := 0
 	var finalContent string
 
+	// Determine effective model tier for this conversation turn.
+	// selectCandidates evaluates routing once and the decision is sticky for
+	// all tool-follow-up iterations within the same turn so that a multi-step
+	// tool chain doesn't switch models mid-way through.
+	activeCandidates, activeModel := al.selectCandidates(agent, opts.UserMessage, messages)
+
 	for iteration < agent.MaxIterations {
 		iteration++
 
@@ -521,7 +971,7 @@ func (al *AgentLoop) runLLMIteration(
 			map[string]any{
 				"agent_id":          agent.ID,
 				"iteration":         iteration,
-				"model":             agent.Model,
+				"model":             activeModel,
 				"messages_count":    len(messages),
 				"tools_count":       len(providerToolDefs),
 				"max_tokens":        agent.MaxTokens,
@@ -537,34 +987,49 @@ func (al *AgentLoop) runLLMIteration(
 				"tools_json":    formatToolsForLog(providerToolDefs),
 			})
 
-		// Call LLM with fallback chain if candidates are configured.
+		// Call LLM with fallback chain if multiple candidates are configured.
 		var response *providers.LLMResponse
 		var err error
 
+		llmOpts := map[string]any{
+			"max_tokens":       agent.MaxTokens,
+			"temperature":      agent.Temperature,
+			"prompt_cache_key": agent.ID,
+		}
+		// parseThinkingLevel guarantees ThinkingOff for empty/unknown values,
+		// so checking != ThinkingOff is sufficient.
+		if agent.ThinkingLevel != ThinkingOff {
+			if tc, ok := agent.Provider.(providers.ThinkingCapable); ok && tc.SupportsThinking() {
+				llmOpts["thinking_level"] = string(agent.ThinkingLevel)
+			} else {
+				logger.WarnCF("agent", "thinking_level is set but current provider does not support it, ignoring",
+					map[string]any{"agent_id": agent.ID, "thinking_level": string(agent.ThinkingLevel)})
+			}
+		}
+
 		callLLM := func() (*providers.LLMResponse, error) {
-			if len(agent.Candidates) > 1 && al.fallback != nil {
-				fbResult, fbErr := al.fallback.Execute(ctx, agent.Candidates,
+			if len(activeCandidates) > 1 && al.fallback != nil {
+				fbResult, fbErr := al.fallback.Execute(
+					ctx,
+					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,
-						})
+						return agent.Provider.Chat(ctx, messages, providerToolDefs, 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": 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,
-			})
+			return agent.Provider.Chat(ctx, messages, providerToolDefs, activeModel, llmOpts)
 		}
 
 		// Retry loop for context/token errors
@@ -575,16 +1040,41 @@ func (al *AgentLoop) runLLMIteration(
 				break
 			}
 
-			isContextError := providers.IsContextWindowError(err)
+			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 && providers.IsContextWindowError(err)
+
+			if isTimeoutError && retry < maxRetries {
+				backoff := time.Duration(retry+1) * 5 * time.Second
+				logger.WarnCF("agent", "Timeout error, retrying after backoff", map[string]any{
+					"error":   err.Error(),
+					"retry":   retry,
+					"backoff": backoff.String(),
+				})
+				time.Sleep(backoff)
+				continue
+			}
 
 			if isContextError && retry < maxRetries {
-				logger.WarnCF("agent", "Context window error detected, attempting compression", map[string]any{
-					"error": err.Error(),
-					"retry": retry,
-				})
+				logger.WarnCF(
+					"agent",
+					"Context window error detected, attempting compression",
+					map[string]any{
+						"error": err.Error(),
+						"retry": retry,
+					},
+				)
 
 				if retry == 0 && !constants.IsInternalChannel(opts.Channel) {
-					al.bus.PublishOutbound(bus.OutboundMessage{
+					al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 						Channel: opts.Channel,
 						ChatID:  opts.ChatID,
 						Content: "Context window exceeded. Compressing history and retrying...",
@@ -613,9 +1103,29 @@ func (al *AgentLoop) runLLMIteration(
 			return "", iteration, fmt.Errorf("LLM call failed after retries: %w", err)
 		}
 
-		// Check if no tool calls - we're done
+		go al.handleReasoning(
+			ctx,
+			response.Reasoning,
+			opts.Channel,
+			al.targetReasoningChannelID(opts.Channel),
+		)
+
+		logger.DebugCF("agent", "LLM response",
+			map[string]any{
+				"agent_id":       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,
+			})
+		// Check if no tool calls - then check reasoning content if any
 		if len(response.ToolCalls) == 0 {
 			finalContent = response.Content
+			if finalContent == "" && response.ReasoningContent != "" {
+				finalContent = response.ReasoningContent
+			}
 			logger.InfoCF("agent", "LLM response without tool calls (direct answer)",
 				map[string]any{
 					"agent_id":      agent.ID,
@@ -645,8 +1155,9 @@ func (al *AgentLoop) runLLMIteration(
 
 		// Build assistant message with tool calls
 		assistantMsg := providers.Message{
-			Role:    "assistant",
-			Content: response.Content,
+			Role:             "assistant",
+			Content:          response.Content,
+			ReasoningContent: response.ReasoningContent,
 		}
 		for _, tc := range normalizedToolCalls {
 			argumentsJSON, _ := json.Marshal(tc.Arguments)
@@ -675,17 +1186,195 @@ func (al *AgentLoop) runLLMIteration(
 		// Save assistant message with tool calls to session
 		agent.Sessions.AddFullMessage(opts.SessionKey, assistantMsg)
 
-		// Execute tool calls via the ToolExecutor component
-		toolResultMsgs := al.toolExec.ExecuteToolCalls(ctx, agent, normalizedToolCalls, opts)
-		for _, resultMsg := range toolResultMsgs {
-			messages = append(messages, resultMsg)
-			agent.Sessions.AddFullMessage(opts.SessionKey, resultMsg)
+		// Execute tool calls in parallel
+		type indexedAgentResult struct {
+			result *tools.ToolResult
+			tc     providers.ToolCall
 		}
+
+		agentResults := make([]indexedAgentResult, len(normalizedToolCalls))
+		var wg sync.WaitGroup
+
+		for i, tc := range normalizedToolCalls {
+			agentResults[i].tc = tc
+
+			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("agent", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview),
+					map[string]any{
+						"agent_id":  agent.ID,
+						"tool":      tc.Name,
+						"iteration": iteration,
+					})
+
+				// Create async callback for tools that implement AsyncExecutor.
+				// When the background work completes, this publishes the result
+				// as an inbound system message so processSystemMessage routes it
+				// back to the user via the normal agent loop.
+				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: opts.Channel,
+							ChatID:  opts.ChatID,
+							Content: result.ForUser,
+						})
+					}
+
+					// Determine content for the agent loop (ForLLM or error).
+					content := result.ForLLM
+					if content == "" && result.Err != nil {
+						content = result.Err.Error()
+					}
+					if content == "" {
+						return
+					}
+
+					logger.InfoCF("agent", "Async tool completed, publishing result",
+						map[string]any{
+							"tool":        tc.Name,
+							"content_len": len(content),
+							"channel":     opts.Channel,
+						})
+
+					pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+					defer pubCancel()
+					_ = al.bus.PublishInbound(pubCtx, bus.InboundMessage{
+						Channel:  "system",
+						SenderID: fmt.Sprintf("async:%s", tc.Name),
+						ChatID:   fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID),
+						Content:  content,
+					})
+				}
+
+				toolResult := agent.Tools.ExecuteWithContext(
+					ctx,
+					tc.Name,
+					tc.Arguments,
+					opts.Channel,
+					opts.ChatID,
+					asyncCallback,
+				)
+				agentResults[idx].result = toolResult
+			}(i, tc)
+		}
+		wg.Wait()
+
+		// Process results in original order (send to user, save to session)
+		for _, r := range agentResults {
+			// Send ForUser content to user immediately if not Silent
+			if !r.result.Silent && r.result.ForUser != "" && opts.SendResponse {
+				al.bus.PublishOutbound(ctx, bus.OutboundMessage{
+					Channel: opts.Channel,
+					ChatID:  opts.ChatID,
+					Content: r.result.ForUser,
+				})
+				logger.DebugCF("agent", "Sent tool result to user",
+					map[string]any{
+						"tool":        r.tc.Name,
+						"content_len": len(r.result.ForUser),
+					})
+			}
+
+			// If tool returned media refs, publish them as outbound media
+			if len(r.result.Media) > 0 {
+				parts := make([]bus.MediaPart, 0, len(r.result.Media))
+				for _, ref := range r.result.Media {
+					part := bus.MediaPart{Ref: ref}
+					if al.mediaStore != nil {
+						if _, meta, err := al.mediaStore.ResolveWithMeta(ref); err == nil {
+							part.Filename = meta.Filename
+							part.ContentType = meta.ContentType
+							part.Type = inferMediaType(meta.Filename, meta.ContentType)
+						}
+					}
+					parts = append(parts, part)
+				}
+				al.bus.PublishOutboundMedia(ctx, bus.OutboundMediaMessage{
+					Channel: opts.Channel,
+					ChatID:  opts.ChatID,
+					Parts:   parts,
+				})
+			}
+
+			// Determine content for LLM based on tool result
+			contentForLLM := r.result.ForLLM
+			if contentForLLM == "" && r.result.Err != nil {
+				contentForLLM = r.result.Err.Error()
+			}
+
+			toolResultMsg := providers.Message{
+				Role:       "tool",
+				Content:    contentForLLM,
+				ToolCallID: r.tc.ID,
+			}
+			messages = append(messages, toolResultMsg)
+
+			// Save tool result message to session
+			agent.Sessions.AddFullMessage(opts.SessionKey, toolResultMsg)
+		}
+
+		// Tick down TTL of discovered tools after processing tool results.
+		// Only reached when tool calls were made (the loop continues);
+		// the break on no-tool-call responses skips this.
+		// NOTE: This is safe because processMessage is sequential per agent.
+		// If per-agent concurrency is added, TTL consistency between
+		// ToProviderDefs and Get must be re-evaluated.
+		agent.Tools.TickTTL()
+		logger.DebugCF("agent", "TTL tick after tool execution", map[string]any{
+			"agent_id": agent.ID, "iteration": iteration,
+		})
 	}
 
 	return finalContent, iteration, nil
 }
 
+// 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, 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, 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, agent.Router.LightModel()
+}
+
+
 // GetStartupInfo returns information about loaded tools and skills for logging.
 func (al *AgentLoop) GetStartupInfo() map[string]any {
 	info := make(map[string]any)
@@ -729,7 +1418,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),
+					)
 				}
 			}
 		}
@@ -758,124 +1451,142 @@ 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("]")
 	return sb.String()
 }
 
-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 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
-		}
-		switch args[0] {
-		case "model":
-			defaultAgent := al.registry.GetDefaultAgent()
-			if defaultAgent == nil {
-				return "No default agent configured", true
-			}
-			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
-		}
+	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
+		},
+	})
 
-	case "/list":
-		if len(args) < 1 {
-			return "Usage: /list [models|channels|agents]", true
+	switch result.Outcome {
+	case commands.OutcomeHandled:
+		if result.Err != nil {
+			return mapCommandError(result), true
 		}
-		switch args[0] {
-		case "models":
-			return "Available models: configured in config.json per agent", true
-		case "channels":
-			if al.channelManager == nil {
-				return "Channel manager not initialized", true
-			}
-			channels := al.channelManager.GetEnabledChannels()
-			if len(channels) == 0 {
-				return "No channels enabled", true
-			}
-			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":
-			if al.channelManager == nil {
-				return "Channel manager not initialized", true
-			}
-			if _, exists := al.channelManager.GetChannel(value); !exists && value != "cli" {
-				return fmt.Sprintf("Channel '%s' not found or not enabled", value), true
-			}
-			return fmt.Sprintf("Switched target channel to %s", value), true
-		default:
-			return fmt.Sprintf("Unknown switch target: %s", target), true
+		if commandReply != "" {
+			return commandReply, true
 		}
+		return "", true
+	default: // OutcomePassthrough — let the message fall through to LLM
+		return "", false
 	}
-
-	return "", false
 }
 
-// extractPeer extracts the routing peer from inbound message metadata.
+func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOptions) *commands.Runtime {
+	rt := &commands.Runtime{
+		Config:          al.cfg,
+		ListAgentIDs:    al.registry.ListAgentIDs,
+		ListDefinitions: al.cmdRegistry.Definitions,
+		GetEnabledChannels: func() []string {
+			if al.channelManager == nil {
+				return nil
+			}
+			return al.channelManager.GetEnabledChannels()
+		},
+		SwitchChannel: func(value string) error {
+			if al.channelManager == nil {
+				return fmt.Errorf("channel manager not initialized")
+			}
+			if _, exists := al.channelManager.GetChannel(value); !exists && value != "cli" {
+				return fmt.Errorf("channel '%s' not found or not enabled", value)
+			}
+			return nil
+		},
+	}
+	if agent != nil {
+		rt.GetModelInfo = func() (string, string) {
+			return agent.Model, al.cfg.Agents.Defaults.Provider
+		}
+		rt.SwitchModel = func(value string) (string, error) {
+			oldModel := agent.Model
+			agent.Model = value
+			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
+}
+
+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.
 func extractPeer(msg bus.InboundMessage) *routing.RoutePeer {
-	peerKind := msg.Metadata["peer_kind"]
-	if peerKind == "" {
+	if msg.Peer.Kind == "" {
 		return nil
 	}
-	peerID := msg.Metadata["peer_id"]
+	peerID := msg.Peer.ID
 	if peerID == "" {
-		if peerKind == "direct" {
+		if msg.Peer.Kind == "direct" {
 			peerID = msg.SenderID
 		} else {
 			peerID = msg.ChatID
 		}
 	}
-	return &routing.RoutePeer{Kind: peerKind, ID: peerID}
+	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
 	}
diff --git a/pkg/agent/loop_media.go b/pkg/agent/loop_media.go
new file mode 100644
index 000000000..82547a008
--- /dev/null
+++ b/pkg/agent/loop_media.go
@@ -0,0 +1,122 @@
+// 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 replaces media:// refs in message Media fields with base64 data URLs.
+// Uses streaming base64 encoding (file handle → encoder → buffer) to avoid holding
+// both raw bytes and encoded string in memory simultaneously.
+// 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))
+		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
+			}
+			if info.Size() > int64(maxSize) {
+				logger.WarnCF("agent", "Media file too large, skipping", map[string]any{
+					"path":     localPath,
+					"size":     info.Size(),
+					"max_size": maxSize,
+				})
+				continue
+			}
+
+			// Determine MIME type: prefer metadata, fallback to magic-bytes detection
+			mime := meta.ContentType
+			if mime == "" {
+				kind, ftErr := filetype.MatchFile(localPath)
+				if ftErr != nil || kind == filetype.Unknown {
+					logger.WarnCF("agent", "Unknown media type, skipping", map[string]any{
+						"path": localPath,
+					})
+					continue
+				}
+				mime = kind.MIME.Value
+			}
+
+			// Streaming base64: open file → base64 encoder → buffer
+			// Peak memory: ~1.33x file size (buffer only, no raw bytes copy)
+			f, err := os.Open(localPath)
+			if err != nil {
+				logger.WarnCF("agent", "Failed to open media file", map[string]any{
+					"path":  localPath,
+					"error": err.Error(),
+				})
+				continue
+			}
+
+			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 {
+				f.Close()
+				logger.WarnCF("agent", "Failed to encode media file", map[string]any{
+					"path":  localPath,
+					"error": err.Error(),
+				})
+				continue
+			}
+			encoder.Close()
+			f.Close()
+
+			resolved = append(resolved, buf.String())
+		}
+
+		result[i].Media = resolved
+	}
+
+	return result
+}
diff --git a/pkg/agent/loop_test.go b/pkg/agent/loop_test.go
index 4414398b1..2e456fa60 100644
--- a/pkg/agent/loop_test.go
+++ b/pkg/agent/loop_test.go
@@ -5,25 +5,40 @@ import (
 	"fmt"
 	"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"
 )
 
-func TestRecordLastChannel(t *testing.T) {
-	// Create temp workspace
+type fakeChannel struct{ id string }
+
+func (f *fakeChannel) Name() string                                            { return "fake" }
+func (f *fakeChannel) Start(ctx context.Context) error                         { return nil }
+func (f *fakeChannel) Stop(ctx context.Context) error                          { return nil }
+func (f *fakeChannel) Send(ctx context.Context, msg bus.OutboundMessage) error { return nil }
+func (f *fakeChannel) IsRunning() bool                                         { return true }
+func (f *fakeChannel) IsAllowed(string) bool                                   { return true }
+func (f *fakeChannel) IsAllowedSender(sender bus.SenderInfo) bool              { return true }
+func (f *fakeChannel) ReasoningChannelID() string                              { return f.id }
+
+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)
 	}
-	defer os.RemoveAll(tmpDir)
-
-	// Create test config
-	cfg := &config.Config{
+	cfg = &config.Config{
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
@@ -33,74 +48,43 @@ func TestRecordLastChannel(t *testing.T) {
 			},
 		},
 	}
+	msgBus = bus.NewMessageBus()
+	provider = &mockProvider{}
+	al = NewAgentLoop(cfg, msgBus, provider)
+	return al, cfg, msgBus, provider, func() { os.RemoveAll(tmpDir) }
+}
 
-	// Create agent loop
-	msgBus := bus.NewMessageBus()
-	provider := &mockProvider{}
-	al := NewAgentLoop(cfg, msgBus, provider)
+func TestRecordLastChannel(t *testing.T) {
+	al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+	defer cleanup()
 
-	// Test RecordLastChannel
 	testChannel := "test-channel"
-	err = al.RecordLastChannel(testChannel)
-	if err != nil {
+	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)
 	}
 }
 
@@ -175,47 +159,27 @@ func TestToolRegistry_ToolRegistration(t *testing.T) {
 	toolsList := toolsInfo["names"].([]string)
 
 	// Check that our custom tool name is in the list
-	found := false
-	for _, name := range toolsList {
-		if name == "mock_custom" {
-			found = true
-			break
-		}
-	}
+	found := slices.Contains(toolsList, "mock_custom")
 	if !found {
 		t.Error("Expected custom tool to be registered")
 	}
 }
 
-// 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
@@ -250,13 +214,7 @@ func TestToolRegistry_GetDefinitions(t *testing.T) {
 	toolsList := toolsInfo["names"].([]string)
 
 	// Check that our custom tool name is in the list
-	found := false
-	for _, name := range toolsList {
-		if name == "mock_custom" {
-			found = true
-			break
-		}
-	}
+	found := slices.Contains(toolsList, "mock_custom")
 	if !found {
 		t.Error("Expected custom tool to be registered")
 	}
@@ -270,16 +228,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.Model = "test-model"
+	cfg.Agents.Defaults.MaxTokens = 4096
+	cfg.Agents.Defaults.MaxToolIterations = 10
 
 	msgBus := bus.NewMessageBus()
 	provider := &mockProvider{}
@@ -366,6 +319,29 @@ func (m *simpleMockProvider) GetDefaultModel() string {
 	return "mock-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"
+}
+
 // mockCustomTool is a simple mock tool for registration testing
 type mockCustomTool struct{}
 
@@ -388,36 +364,6 @@ 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
-}
-
-func (m *mockContextualTool) Name() string {
-	return "mock_contextual"
-}
-
-func (m *mockContextualTool) Description() string {
-	return "Mock contextual tool"
-}
-
-func (m *mockContextualTool) 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 *mockContextualTool) SetContext(channel, chatID string) {
-	m.lastChannel = channel
-	m.lastChatID = chatID
-}
-
 // testHelper executes a message and returns the response
 type testHelper struct {
 	al *AgentLoop
@@ -437,6 +383,198 @@ 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,
+				Model:             "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,
+				Model:             "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",
+				Model:             "before-switch",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	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 after-switch",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if !strings.Contains(switchResp, "Switched model from before-switch to after-switch") {
+		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: after-switch (Provider: openai)") {
+		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)
+	}
+}
+
 // TestToolResult_SilentToolDoesNotSendUserMessage verifies silent tools don't trigger outbound
 func TestToolResult_SilentToolDoesNotSendUserMessage(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "agent-test-*")
@@ -631,3 +769,350 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
 		t.Errorf("Expected history to be compressed (len < 8), got %d", len(finalHistory))
 	}
 }
+
+func TestTargetReasoningChannelID_AllChannels(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,
+				Model:             "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	al := NewAgentLoop(cfg, bus.NewMessageBus(), &mockProvider{})
+	chManager, err := channels.NewManager(&config.Config{}, bus.NewMessageBus(), nil)
+	if err != nil {
+		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",
+	} {
+		chManager.RegisterChannel(name, &fakeChannel{id: id})
+	}
+	al.SetChannelManager(chManager)
+	tests := []struct {
+		channel string
+		wantID  string
+	}{
+		{channel: "whatsapp", wantID: "rid-whatsapp"},
+		{channel: "telegram", wantID: "rid-telegram"},
+		{channel: "feishu", wantID: "rid-feishu"},
+		{channel: "discord", wantID: "rid-discord"},
+		{channel: "maixcam", wantID: "rid-maixcam"},
+		{channel: "qq", wantID: "rid-qq"},
+		{channel: "dingtalk", wantID: "rid-dingtalk"},
+		{channel: "slack", wantID: "rid-slack"},
+		{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: ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.channel, func(t *testing.T) {
+			got := al.targetReasoningChannelID(tt.channel)
+			if got != tt.wantID {
+				t.Fatalf("targetReasoningChannelID(%q) = %q, want %q", tt.channel, got, tt.wantID)
+			}
+		})
+	}
+}
+
+func TestHandleReasoning(t *testing.T) {
+	newLoop := func(t *testing.T) (*AgentLoop, *bus.MessageBus) {
+		t.Helper()
+		tmpDir, err := os.MkdirTemp("", "agent-test-*")
+		if err != nil {
+			t.Fatalf("Failed to create temp dir: %v", err)
+		}
+		t.Cleanup(func() { _ = os.RemoveAll(tmpDir) })
+		cfg := &config.Config{
+			Agents: config.AgentsConfig{
+				Defaults: config.AgentDefaults{
+					Workspace:         tmpDir,
+					Model:             "test-model",
+					MaxTokens:         4096,
+					MaxToolIterations: 10,
+				},
+			},
+		}
+		msgBus := bus.NewMessageBus()
+		return NewAgentLoop(cfg, msgBus, &mockProvider{}), msgBus
+	}
+
+	t.Run("skips when any required field is empty", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		al.handleReasoning(context.Background(), "reasoning", "telegram", "")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+		defer cancel()
+		if msg, ok := msgBus.SubscribeOutbound(ctx); ok {
+			t.Fatalf("expected no outbound message, got %+v", msg)
+		}
+	})
+
+	t.Run("publishes one message for non telegram", func(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)
+		if !ok {
+			t.Fatal("expected an outbound message")
+		}
+		if msg.Channel != "slack" || msg.ChatID != "channel-1" || msg.Content != "hello reasoning" {
+			t.Fatalf("unexpected outbound message: %+v", msg)
+		}
+	})
+
+	t.Run("publishes one message for telegram", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		reasoning := "hello telegram reasoning"
+		al.handleReasoning(context.Background(), reasoning, "telegram", "tg-chat")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+		msg, ok := msgBus.SubscribeOutbound(ctx)
+		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)
+		}
+	})
+	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)
+		}
+	})
+
+	t.Run("returns promptly when bus is full", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+
+		// Fill the outbound bus buffer until a publish would block.
+		// Use a short timeout to detect when the buffer is full,
+		// rather than hardcoding the buffer size.
+		for i := 0; ; i++ {
+			fillCtx, fillCancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+			err := msgBus.PublishOutbound(fillCtx, bus.OutboundMessage{
+				Channel: "filler",
+				ChatID:  "filler",
+				Content: fmt.Sprintf("filler-%d", i),
+			})
+			fillCancel()
+			if err != nil {
+				// Buffer is full (timed out trying to send).
+				break
+			}
+		}
+
+		// Use a short-deadline parent context to bound the test.
+		ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+		defer cancel()
+
+		start := time.Now()
+		al.handleReasoning(ctx, "should timeout", "slack", "channel-full")
+		elapsed := time.Since(start)
+
+		// handleReasoning uses a 5s internal timeout, but the parent ctx
+		// expires in 500ms. It should return within ~500ms, not 5s.
+		if elapsed > 2*time.Second {
+			t.Fatalf("handleReasoning blocked too long (%v); expected prompt return", elapsed)
+		}
+
+		// 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
+		for {
+			msg, ok := msgBus.SubscribeOutbound(drainCtx)
+			if !ok {
+				break
+			}
+			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 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_SkipsUnknownType(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 (unknown type), got %d", len(result[0].Media))
+	}
+}
+
+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])
+	}
+}
diff --git a/pkg/agent/memory.go b/pkg/agent/memory.go
index dd5f4441c..01e682f3b 100644
--- a/pkg/agent/memory.go
+++ b/pkg/agent/memory.go
@@ -12,6 +12,8 @@ import (
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
 // MemoryStore manages persistent memory for the agent.
@@ -58,7 +60,9 @@ func (ms *MemoryStore) ReadLongTerm() string {
 
 // WriteLongTerm writes content to the long-term memory file (MEMORY.md).
 func (ms *MemoryStore) WriteLongTerm(content string) error {
-	return os.WriteFile(ms.memoryFile, []byte(content), 0o644)
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	// Using 0o600 (owner read/write only) for secure default permissions.
+	return fileutil.WriteFileAtomic(ms.memoryFile, []byte(content), 0o600)
 }
 
 // ReadToday reads today's daily note.
@@ -78,7 +82,9 @@ func (ms *MemoryStore) AppendToday(content string) error {
 
 	// Ensure month directory exists
 	monthDir := filepath.Dir(todayFile)
-	os.MkdirAll(monthDir, 0o755)
+	if err := os.MkdirAll(monthDir, 0o755); err != nil {
+		return err
+	}
 
 	var existingContent string
 	if data, err := os.ReadFile(todayFile); err == nil {
@@ -95,7 +101,8 @@ func (ms *MemoryStore) AppendToday(content string) error {
 		newContent = existingContent + "\n" + content
 	}
 
-	return os.WriteFile(todayFile, []byte(newContent), 0o644)
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	return fileutil.WriteFileAtomic(todayFile, []byte(newContent), 0o600)
 }
 
 // GetRecentDailyNotes returns daily notes from the last N days.
@@ -104,7 +111,7 @@ func (ms *MemoryStore) GetRecentDailyNotes(days int) string {
 	var sb strings.Builder
 	first := true
 
-	for i := 0; i < days; i++ {
+	for i := range days {
 		date := time.Now().AddDate(0, 0, -i)
 		dateStr := date.Format("20060102") // YYYYMMDD
 		monthDir := dateStr[:6]            // YYYYMM
diff --git a/pkg/agent/registry.go b/pkg/agent/registry.go
index 77b846832..0e7973dc3 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,19 @@ 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)
+		}
+	}
+}
+
 // GetDefaultAgent returns the default agent instance.
 func (r *AgentRegistry) GetDefaultAgent() *AgentInstance {
 	r.mu.RLock()
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/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 cf8c1c9c4..4667e3d81 100644
--- a/pkg/auth/oauth.go
+++ b/pkg/auth/oauth.go
@@ -66,7 +66,8 @@ func decodeBase64(s string) string {
 	return string(data)
 }
 
-func generateState() (string, error) {
+// GenerateState generates a random state string for OAuth CSRF protection.
+func GenerateState() (string, error) {
 	buf := make([]byte, 32)
 	if _, err := rand.Read(buf); err != nil {
 		return "", err
@@ -80,7 +81,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 		return nil, fmt.Errorf("generating PKCE: %w", err)
 	}
 
-	state, err := generateState()
+	state, err := GenerateState()
 	if err != nil {
 		return nil, fmt.Errorf("generating state: %w", err)
 	}
@@ -127,7 +128,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 
 	fmt.Printf("Open this URL to authenticate:\n\n%s\n\n", authURL)
 
-	if err := openBrowser(authURL); err != nil {
+	if err := OpenBrowser(authURL); err != nil {
 		fmt.Printf("Could not open browser automatically.\nPlease open this URL manually:\n\n%s\n\n", authURL)
 	}
 
@@ -153,10 +154,10 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 		if result.err != nil {
 			return nil, result.err
 		}
-		return exchangeCodeForTokens(cfg, result.code, pkce.CodeVerifier, redirectURI)
+		return ExchangeCodeForTokens(cfg, result.code, pkce.CodeVerifier, redirectURI)
 	case manualInput := <-manualCh:
 		if manualInput == "" {
-			return nil, fmt.Errorf("manual input cancelled")
+			return nil, fmt.Errorf("manual input canceled")
 		}
 		// Extract code from URL if it's a full URL
 		code := manualInput
@@ -169,7 +170,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 		if code == "" {
 			return nil, fmt.Errorf("could not find authorization code in input")
 		}
-		return exchangeCodeForTokens(cfg, code, pkce.CodeVerifier, redirectURI)
+		return ExchangeCodeForTokens(cfg, code, pkce.CodeVerifier, redirectURI)
 	case <-time.After(5 * time.Minute):
 		return nil, fmt.Errorf("authentication timed out after 5 minutes")
 	}
@@ -186,6 +187,62 @@ type deviceCodeResponse struct {
 	Interval     int
 }
 
+// DeviceCodeInfo holds the device code information returned by the OAuth provider.
+type DeviceCodeInfo struct {
+	DeviceAuthID string `json:"device_auth_id"`
+	UserCode     string `json:"user_code"`
+	VerifyURL    string `json:"verify_url"`
+	Interval     int    `json:"interval"`
+}
+
+// RequestDeviceCode requests a device code from the OAuth provider.
+// Returns the info needed for the user to authenticate in a browser.
+func RequestDeviceCode(cfg OAuthProviderConfig) (*DeviceCodeInfo, error) {
+	reqBody, _ := json.Marshal(map[string]string{
+		"client_id": cfg.ClientID,
+	})
+
+	resp, err := http.Post(
+		cfg.Issuer+"/api/accounts/deviceauth/usercode",
+		"application/json",
+		strings.NewReader(string(reqBody)),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("requesting device code: %w", err)
+	}
+	defer resp.Body.Close()
+
+	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))
+	}
+
+	deviceResp, err := parseDeviceCodeResponse(body)
+	if err != nil {
+		return nil, fmt.Errorf("parsing device code response: %w", err)
+	}
+
+	if deviceResp.Interval < 1 {
+		deviceResp.Interval = 5
+	}
+
+	return &DeviceCodeInfo{
+		DeviceAuthID: deviceResp.DeviceAuthID,
+		UserCode:     deviceResp.UserCode,
+		VerifyURL:    cfg.Issuer + "/codex/device",
+		Interval:     deviceResp.Interval,
+	}, nil
+}
+
+// PollDeviceCodeOnce makes a single poll attempt to check if the user has authenticated.
+// Returns (credential, nil) on success, (nil, nil) if still pending, or (nil, err) on failure.
+func PollDeviceCodeOnce(cfg OAuthProviderConfig, deviceAuthID, userCode string) (*AuthCredential, error) {
+	return pollDeviceCode(cfg, deviceAuthID, userCode)
+}
+
 func parseDeviceCodeResponse(body []byte) (deviceCodeResponse, error) {
 	var raw struct {
 		DeviceAuthID string          `json:"device_auth_id"`
@@ -246,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))
 	}
@@ -306,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"`
@@ -318,7 +381,7 @@ func pollDeviceCode(cfg OAuthProviderConfig, deviceAuthID, userCode string) (*Au
 	}
 
 	redirectURI := cfg.Issuer + "/deviceauth/callback"
-	return exchangeCodeForTokens(cfg, tokenResp.AuthorizationCode, tokenResp.CodeVerifier, redirectURI)
+	return ExchangeCodeForTokens(cfg, tokenResp.AuthorizationCode, tokenResp.CodeVerifier, redirectURI)
 }
 
 func RefreshAccessToken(cred *AuthCredential, cfg OAuthProviderConfig) (*AuthCredential, error) {
@@ -347,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))
 	}
@@ -410,7 +476,8 @@ func buildAuthorizeURL(cfg OAuthProviderConfig, pkce PKCECodes, state, redirectU
 	return cfg.Issuer + "/oauth/authorize?" + params.Encode()
 }
 
-func exchangeCodeForTokens(cfg OAuthProviderConfig, code, codeVerifier, redirectURI string) (*AuthCredential, error) {
+// ExchangeCodeForTokens exchanges an authorization code for tokens.
+func ExchangeCodeForTokens(cfg OAuthProviderConfig, code, codeVerifier, redirectURI string) (*AuthCredential, error) {
 	data := url.Values{
 		"grant_type":    {"authorization_code"},
 		"code":          {code},
@@ -439,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))
 	}
@@ -552,7 +622,8 @@ func base64URLDecode(s string) ([]byte, error) {
 	return base64.StdEncoding.DecodeString(s)
 }
 
-func openBrowser(url string) error {
+// OpenBrowser opens the given URL in the user's default browser.
+func OpenBrowser(url string) error {
 	switch runtime.GOOS {
 	case "darwin":
 		return exec.Command("open", url).Start()
diff --git a/pkg/auth/oauth_test.go b/pkg/auth/oauth_test.go
index 0cb589069..230ac7c2a 100644
--- a/pkg/auth/oauth_test.go
+++ b/pkg/auth/oauth_test.go
@@ -219,9 +219,9 @@ func TestExchangeCodeForTokens(t *testing.T) {
 		Port:     1455,
 	}
 
-	cred, err := exchangeCodeForTokens(cfg, "test-code", "test-verifier", "http://localhost:1455/auth/callback")
+	cred, err := ExchangeCodeForTokens(cfg, "test-code", "test-verifier", "http://localhost:1455/auth/callback")
 	if err != nil {
-		t.Fatalf("exchangeCodeForTokens() error: %v", err)
+		t.Fatalf("ExchangeCodeForTokens() error: %v", err)
 	}
 
 	if cred.AccessToken != "mock-access-token" {
diff --git a/pkg/auth/store.go b/pkg/auth/store.go
index 64708421b..2e55d4877 100644
--- a/pkg/auth/store.go
+++ b/pkg/auth/store.go
@@ -5,6 +5,8 @@ import (
 	"os"
 	"path/filepath"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
 type AuthCredential struct {
@@ -37,6 +39,9 @@ func (c *AuthCredential) NeedsRefresh() bool {
 }
 
 func authFilePath() string {
+	if home := os.Getenv("PICOCLAW_HOME"); home != "" {
+		return filepath.Join(home, "auth.json")
+	}
 	home, _ := os.UserHomeDir()
 	return filepath.Join(home, ".picoclaw", "auth.json")
 }
@@ -63,16 +68,13 @@ func LoadStore() (*AuthStore, error) {
 
 func SaveStore(store *AuthStore) error {
 	path := authFilePath()
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return err
-	}
-
 	data, err := json.MarshalIndent(store, "", "  ")
 	if err != nil {
 		return err
 	}
-	return os.WriteFile(path, data, 0o600)
+
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	return fileutil.WriteFileAtomic(path, data, 0o600)
 }
 
 func GetCredential(provider string) (*AuthCredential, 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 58c0a25d5..f5ff9587d 100644
--- a/pkg/bus/bus.go
+++ b/pkg/bus/bus.go
@@ -2,81 +2,156 @@ package bus
 
 import (
 	"context"
-	"sync"
+	"errors"
+	"sync/atomic"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
+// ErrBusClosed is returned when publishing to a closed MessageBus.
+var ErrBusClosed = errors.New("message bus closed")
+
+const defaultBusBufferSize = 64
+
 type MessageBus struct {
-	inbound  chan InboundMessage
-	outbound chan OutboundMessage
-	handlers map[string]MessageHandler
-	closed   bool
-	mu       sync.RWMutex
+	inbound       chan InboundMessage
+	outbound      chan OutboundMessage
+	outboundMedia chan OutboundMediaMessage
+	done          chan struct{}
+	closed        atomic.Bool
 }
 
 func NewMessageBus() *MessageBus {
 	return &MessageBus{
-		inbound:  make(chan InboundMessage, 100),
-		outbound: make(chan OutboundMessage, 100),
-		handlers: make(map[string]MessageHandler),
+		inbound:       make(chan InboundMessage, defaultBusBufferSize),
+		outbound:      make(chan OutboundMessage, defaultBusBufferSize),
+		outboundMedia: make(chan OutboundMediaMessage, defaultBusBufferSize),
+		done:          make(chan struct{}),
 	}
 }
 
-func (mb *MessageBus) PublishInbound(msg InboundMessage) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	if mb.closed {
-		return
+func (mb *MessageBus) PublishInbound(ctx context.Context, msg InboundMessage) error {
+	if mb.closed.Load() {
+		return ErrBusClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case mb.inbound <- msg:
+		return nil
+	case <-mb.done:
+		return ErrBusClosed
+	case <-ctx.Done():
+		return ctx.Err()
 	}
-	mb.inbound <- msg
 }
 
 func (mb *MessageBus) ConsumeInbound(ctx context.Context) (InboundMessage, bool) {
 	select {
-	case msg := <-mb.inbound:
-		return msg, true
+	case msg, ok := <-mb.inbound:
+		return msg, ok
+	case <-mb.done:
+		return InboundMessage{}, false
 	case <-ctx.Done():
 		return InboundMessage{}, false
 	}
 }
 
-func (mb *MessageBus) PublishOutbound(msg OutboundMessage) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	if mb.closed {
-		return
+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()
 	}
-	mb.outbound <- msg
 }
 
 func (mb *MessageBus) SubscribeOutbound(ctx context.Context) (OutboundMessage, bool) {
 	select {
-	case msg := <-mb.outbound:
-		return msg, true
+	case msg, ok := <-mb.outbound:
+		return msg, ok
+	case <-mb.done:
+		return OutboundMessage{}, false
 	case <-ctx.Done():
 		return OutboundMessage{}, false
 	}
 }
 
-func (mb *MessageBus) RegisterHandler(channel string, handler MessageHandler) {
-	mb.mu.Lock()
-	defer mb.mu.Unlock()
-	mb.handlers[channel] = handler
+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()
+	}
 }
 
-func (mb *MessageBus) GetHandler(channel string) (MessageHandler, bool) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	handler, ok := mb.handlers[channel]
-	return handler, ok
+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) Close() {
-	mb.mu.Lock()
-	defer mb.mu.Unlock()
-	if mb.closed {
-		return
+	if mb.closed.CompareAndSwap(false, true) {
+		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.
+		drained := 0
+		for {
+			select {
+			case <-mb.inbound:
+				drained++
+			default:
+				goto doneInbound
+			}
+		}
+	doneInbound:
+		for {
+			select {
+			case <-mb.outbound:
+				drained++
+			default:
+				goto doneOutbound
+			}
+		}
+	doneOutbound:
+		for {
+			select {
+			case <-mb.outboundMedia:
+				drained++
+			default:
+				goto doneMedia
+			}
+		}
+	doneMedia:
+		if drained > 0 {
+			logger.DebugCF("bus", "Drained buffered messages during close", map[string]any{
+				"count": drained,
+			})
+		}
 	}
-	mb.closed = true
-	close(mb.inbound)
-	close(mb.outbound)
 }
diff --git a/pkg/bus/bus_test.go b/pkg/bus/bus_test.go
new file mode 100644
index 000000000..e07b8c7fe
--- /dev/null
+++ b/pkg/bus/bus_test.go
@@ -0,0 +1,229 @@
+package bus
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestPublishConsume(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	msg := InboundMessage{
+		Channel:  "test",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello",
+	}
+
+	if err := mb.PublishInbound(ctx, msg); err != nil {
+		t.Fatalf("PublishInbound failed: %v", err)
+	}
+
+	got, ok := mb.ConsumeInbound(ctx)
+	if !ok {
+		t.Fatal("ConsumeInbound returned ok=false")
+	}
+	if got.Content != "hello" {
+		t.Fatalf("expected content 'hello', got %q", got.Content)
+	}
+	if got.Channel != "test" {
+		t.Fatalf("expected channel 'test', got %q", got.Channel)
+	}
+}
+
+func TestPublishOutboundSubscribe(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	msg := OutboundMessage{
+		Channel: "telegram",
+		ChatID:  "123",
+		Content: "world",
+	}
+
+	if err := mb.PublishOutbound(ctx, msg); err != nil {
+		t.Fatalf("PublishOutbound failed: %v", err)
+	}
+
+	got, ok := mb.SubscribeOutbound(ctx)
+	if !ok {
+		t.Fatal("SubscribeOutbound returned ok=false")
+	}
+	if got.Content != "world" {
+		t.Fatalf("expected content 'world', got %q", got.Content)
+	}
+}
+
+func TestPublishInbound_ContextCancel(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	// Fill the buffer
+	ctx := context.Background()
+	for i := range defaultBusBufferSize {
+		if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil {
+			t.Fatalf("fill failed at %d: %v", i, err)
+		}
+	}
+
+	// Now buffer is full; publish with a canceled context
+	cancelCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := mb.PublishInbound(cancelCtx, InboundMessage{Content: "overflow"})
+	if err == nil {
+		t.Fatal("expected error from canceled context, got nil")
+	}
+	if err != context.Canceled {
+		t.Fatalf("expected context.Canceled, got %v", err)
+	}
+}
+
+func TestPublishInbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed, got %v", err)
+	}
+}
+
+func TestPublishOutbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	err := mb.PublishOutbound(context.Background(), OutboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed, got %v", err)
+	}
+}
+
+func TestConsumeInbound_ContextCancel(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, ok := mb.ConsumeInbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when context is canceled")
+	}
+}
+
+func TestConsumeInbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	_, ok := mb.ConsumeInbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when bus is closed")
+	}
+}
+
+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)
+	if ok {
+		t.Fatal("expected ok=false when bus is closed")
+	}
+}
+
+func TestConcurrentPublishClose(t *testing.T) {
+	mb := NewMessageBus()
+	ctx := context.Background()
+
+	const numGoroutines = 100
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines + 1)
+
+	// Spawn many goroutines trying to publish
+	for range numGoroutines {
+		go func() {
+			defer wg.Done()
+			// Use a short timeout context so we don't block forever after close
+			publishCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
+			defer cancel()
+			// Errors are expected; we just must not panic or deadlock
+			_ = mb.PublishInbound(publishCtx, InboundMessage{Content: "concurrent"})
+		}()
+	}
+
+	// Close from another goroutine
+	go func() {
+		defer wg.Done()
+		time.Sleep(5 * time.Millisecond)
+		mb.Close()
+	}()
+
+	// Must complete without deadlock
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// success
+	case <-time.After(5 * time.Second):
+		t.Fatal("test timed out - possible deadlock")
+	}
+}
+
+func TestPublishInbound_FullBuffer(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	// Fill the buffer
+	for i := range defaultBusBufferSize {
+		if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil {
+			t.Fatalf("fill failed at %d: %v", i, err)
+		}
+	}
+
+	// Buffer is full; publish with short timeout
+	timeoutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
+	defer cancel()
+
+	err := mb.PublishInbound(timeoutCtx, InboundMessage{Content: "overflow"})
+	if err == nil {
+		t.Fatal("expected error when buffer is full and context times out")
+	}
+	if err != context.DeadlineExceeded {
+		t.Fatalf("expected context.DeadlineExceeded, got %v", err)
+	}
+}
+
+func TestCloseIdempotent(t *testing.T) {
+	mb := NewMessageBus()
+
+	// Multiple Close calls must not panic
+	mb.Close()
+	mb.Close()
+	mb.Close()
+
+	// After close, publish should return ErrBusClosed
+	err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed after multiple closes, got %v", err)
+	}
+}
diff --git a/pkg/bus/types.go b/pkg/bus/types.go
index 44f9181a5..7ad8f0417 100644
--- a/pkg/bus/types.go
+++ b/pkg/bus/types.go
@@ -1,11 +1,30 @@
 package bus
 
+// Peer identifies the routing peer for a message (direct, group, channel, etc.)
+type Peer struct {
+	Kind string `json:"kind"` // "direct" | "group" | "channel" | ""
+	ID   string `json:"id"`
+}
+
+// SenderInfo provides structured sender identity information.
+type SenderInfo struct {
+	Platform    string `json:"platform,omitempty"`     // "telegram", "discord", "slack", ...
+	PlatformID  string `json:"platform_id,omitempty"`  // raw platform ID, e.g. "123456"
+	CanonicalID string `json:"canonical_id,omitempty"` // "platform:id" format
+	Username    string `json:"username,omitempty"`     // username (e.g. @alice)
+	DisplayName string `json:"display_name,omitempty"` // display name
+}
+
 type InboundMessage struct {
 	Channel    string            `json:"channel"`
 	SenderID   string            `json:"sender_id"`
+	Sender     SenderInfo        `json:"sender"`
 	ChatID     string            `json:"chat_id"`
 	Content    string            `json:"content"`
 	Media      []string          `json:"media,omitempty"`
+	Peer       Peer              `json:"peer"`                  // routing peer
+	MessageID  string            `json:"message_id,omitempty"`  // platform message ID
+	MediaScope string            `json:"media_scope,omitempty"` // media lifecycle scope
 	SessionKey string            `json:"session_key"`
 	Metadata   map[string]string `json:"metadata,omitempty"`
 }
@@ -16,4 +35,18 @@ type OutboundMessage struct {
 	Content string `json:"content"`
 }
 
-type MessageHandler func(InboundMessage) error
+// MediaPart describes a single media attachment to send.
+type MediaPart struct {
+	Type        string `json:"type"`                   // "image" | "audio" | "video" | "file"
+	Ref         string `json:"ref"`                    // media store ref, e.g. "media://abc123"
+	Caption     string `json:"caption,omitempty"`      // optional caption text
+	Filename    string `json:"filename,omitempty"`     // original filename hint
+	ContentType string `json:"content_type,omitempty"` // MIME type hint
+}
+
+// OutboundMediaMessage carries media attachments from Agent to channels via the bus.
+type OutboundMediaMessage struct {
+	Channel string      `json:"channel"`
+	ChatID  string      `json:"chat_id"`
+	Parts   []MediaPart `json:"parts"`
+}
diff --git a/pkg/channels/README.md b/pkg/channels/README.md
new file mode 100644
index 000000000..b7c56660b
--- /dev/null
+++ b/pkg/channels/README.md
@@ -0,0 +1,1384 @@
+# PicoClaw Channel System: Complete Development Guide
+
+> **Scope**: `pkg/channels/`, `pkg/bus/`, `pkg/media/`, `pkg/identity/`, `cmd/picoclaw/internal/gateway/`
+
+---
+
+## Table of Contents
+
+- [Part 1: Architecture Overview](#part-1-architecture-overview)
+- [Part 2: Migration Guide — From main Branch to Refactored Branch](#part-2-migration-guide--from-main-branch-to-refactored-branch)
+- [Part 3: New Channel Development Guide — Implementing a Channel from Scratch](#part-3-new-channel-development-guide--implementing-a-channel-from-scratch)
+- [Part 4: Core Subsystem Details](#part-4-core-subsystem-details)
+- [Part 5: Key Design Decisions and Conventions](#part-5-key-design-decisions-and-conventions)
+- [Appendix: Complete File Listing and Interface Quick Reference](#appendix-complete-file-listing-and-interface-quick-reference)
+
+---
+
+## Part 1: Architecture Overview
+
+### 1.1 Before and After Comparison
+
+**Before Refactor (main branch)**:
+
+```
+pkg/channels/
+├── telegram.go          # Each channel directly in the channels package
+├── discord.go
+├── slack.go
+├── manager.go           # Manager directly references each channel type
+├── ...
+```
+
+- All channel implementations lived at the top level of `pkg/channels/`
+- Manager constructed each channel via `switch` or `if-else` chains
+- Routing info like Peer and MessageID was buried in `Metadata map[string]string`
+- No rate limiting or retry on message sending
+- No unified media file lifecycle management
+- Each channel ran its own HTTP server
+- Group chat trigger filtering logic was scattered across channels
+
+**After Refactor (refactor/channel-system branch)**:
+
+```
+pkg/channels/
+├── base.go              # BaseChannel shared abstraction layer
+├── interfaces.go        # Optional capability interfaces (TypingCapable, MessageEditor, ReactionCapable, PlaceholderCapable, PlaceholderRecorder)
+├── README.md            # English documentation
+├── README.zh.md         # Chinese documentation
+├── media.go             # MediaSender optional interface
+├── webhook.go           # WebhookHandler, HealthChecker optional interfaces
+├── errors.go            # Sentinel errors (ErrNotRunning, ErrRateLimit, ErrTemporary, ErrSendFailed)
+├── errutil.go           # Error classification helpers
+├── registry.go          # Factory registry (RegisterFactory / getFactory)
+├── manager.go           # Unified orchestration: Worker queues, rate limiting, retries, Typing/Placeholder, shared HTTP
+├── split.go             # Smart long-message splitting (preserves code block integrity)
+├── telegram/            # Each channel in its own sub-package
+│   ├── init.go          # Factory registration
+│   ├── telegram.go      # Implementation
+│   └── telegram_commands.go
+├── discord/
+│   ├── init.go
+│   └── discord.go
+├── slack/ line/ onebot/ dingtalk/ feishu/ wecom/ qq/ whatsapp/ whatsapp_native/ maixcam/ pico/
+│   └── ...
+
+pkg/bus/
+├── bus.go               # MessageBus (buffer 64, safe close + drain)
+├── types.go             # Structured message types (Peer, SenderInfo, MediaPart, InboundMessage, OutboundMessage, OutboundMediaMessage)
+
+pkg/media/
+├── store.go             # MediaStore interface + FileMediaStore implementation (two-phase release, TTL cleanup)
+
+pkg/identity/
+├── identity.go          # Unified user identity: canonical "platform:id" format + backward-compatible matching
+```
+
+### 1.2 Message Flow Overview
+
+```
+┌────────────┐      InboundMessage       ┌───────────┐      LLM + Tools      ┌────────────┐
+│  Telegram   │──┐                        │           │                        │            │
+│  Discord    │──┤   PublishInbound()     │           │   PublishOutbound()   │            │
+│  Slack      │──┼──────────────────────▶ │ MessageBus │ ◀─────────────────── │ AgentLoop  │
+│  LINE       │──┤   (buffered chan, 64)  │           │   (buffered chan, 64) │            │
+│  ...        │──┘                        │           │                        │            │
+└────────────┘                            └─────┬─────┘                        └────────────┘
+                                                │
+                            SubscribeOutbound() │  SubscribeOutboundMedia()
+                                                ▼
+                                    ┌───────────────────┐
+                                    │   Manager          │
+                                    │   ├── dispatchOutbound()    Route to Worker queues
+                                    │   ├── dispatchOutboundMedia()
+                                    │   ├── runWorker()           Message split + sendWithRetry()
+                                    │   ├── runMediaWorker()      sendMediaWithRetry()
+                                    │   ├── preSend()             Stop Typing + Undo Reaction + Edit Placeholder
+                                    │   └── runTTLJanitor()       Clean up expired Typing/Placeholder
+                                    └────────┬──────────┘
+                                             │
+                                   channel.Send() / SendMedia()
+                                             │
+                                             ▼
+                                    ┌────────────────┐
+                                    │ Platform APIs   │
+                                    └────────────────┘
+```
+
+### 1.3 Key Design Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Sub-package Isolation** | Each channel is a standalone Go sub-package, depending on `BaseChannel` and interfaces from the `channels` parent package |
+| **Factory Registration** | Sub-packages self-register via `init()`, Manager looks up factories by name, eliminating import coupling |
+| **Capability Discovery** | Optional capabilities are declared via interfaces (`MediaSender`, `TypingCapable`, `ReactionCapable`, `PlaceholderCapable`, `MessageEditor`, `WebhookHandler`, `HealthChecker`), discovered by Manager via runtime type assertions |
+| **Structured Messages** | Peer, MessageID, and SenderInfo promoted from Metadata to first-class fields on InboundMessage |
+| **Error Classification** | Channels return sentinel errors (`ErrRateLimit`, `ErrTemporary`, etc.), Manager uses these to determine retry strategy |
+| **Centralized Orchestration** | Rate limiting, message splitting, retries, and Typing/Reaction/Placeholder management are all handled by Manager and BaseChannel; channels only need to implement Send |
+
+---
+
+## Part 2: Migration Guide — From main Branch to Refactored Branch
+
+### 2.1 If You Have Unmerged Channel Changes
+
+#### Step 1: Identify which files you modified
+
+On the main branch, channel files were directly in `pkg/channels/` top level, e.g.:
+- `pkg/channels/telegram.go`
+- `pkg/channels/discord.go`
+
+After refactoring, these files have been removed and code moved to corresponding sub-packages:
+- `pkg/channels/telegram/telegram.go`
+- `pkg/channels/discord/discord.go`
+
+#### Step 2: Understand the structural change mapping
+
+| main branch file | Refactored branch location | Changes |
+|---|---|---|
+| `pkg/channels/telegram.go` | `pkg/channels/telegram/telegram.go` + `init.go` | Package name changed from `channels` to `telegram` |
+| `pkg/channels/discord.go` | `pkg/channels/discord/discord.go` + `init.go` | Same as above |
+| `pkg/channels/manager.go` | `pkg/channels/manager.go` | Extensively rewritten |
+| _(did not exist)_ | `pkg/channels/base.go` | New shared abstraction layer |
+| _(did not exist)_ | `pkg/channels/registry.go` | New factory registry |
+| _(did not exist)_ | `pkg/channels/errors.go` + `errutil.go` | New error classification system |
+| _(did not exist)_ | `pkg/channels/interfaces.go` | New optional capability interfaces |
+| _(did not exist)_ | `pkg/channels/media.go` | New MediaSender interface |
+| _(did not exist)_ | `pkg/channels/webhook.go` | New WebhookHandler/HealthChecker |
+| _(did not exist)_ | `pkg/channels/whatsapp_native/` | New WhatsApp native mode (whatsmeow) |
+| _(did not exist)_ | `pkg/channels/split.go` | New message splitting (migrated from utils) |
+| _(did not exist)_ | `pkg/bus/types.go` | New structured message types |
+| _(did not exist)_ | `pkg/media/store.go` | New media file lifecycle management |
+| _(did not exist)_ | `pkg/identity/identity.go` | New unified user identity |
+
+#### Step 3: Migrate your channel code
+
+Using Telegram as an example, the main changes are:
+
+**3a. Package declaration and imports**
+
+```go
+// Old code (main branch)
+package channels
+
+import (
+    "github.com/sipeed/picoclaw/pkg/bus"
+    "github.com/sipeed/picoclaw/pkg/config"
+)
+
+// New code (refactored branch)
+package telegram
+
+import (
+    "github.com/sipeed/picoclaw/pkg/bus"
+    "github.com/sipeed/picoclaw/pkg/channels"     // Reference parent package
+    "github.com/sipeed/picoclaw/pkg/config"
+    "github.com/sipeed/picoclaw/pkg/identity"      // New
+    "github.com/sipeed/picoclaw/pkg/media"          // New (if media support needed)
+)
+```
+
+**3b. Struct embeds BaseChannel**
+
+```go
+// Old code: directly held bus, config, etc. fields
+type TelegramChannel struct {
+    bus       *bus.MessageBus
+    config    *config.Config
+    running   bool
+    allowList []string
+    // ...
+}
+
+// New code: embed BaseChannel, which provides bus, running, allowList, etc.
+type TelegramChannel struct {
+    *channels.BaseChannel          // Embed shared abstraction
+    bot    *telego.Bot
+    config *config.Config
+    // ... only channel-specific fields
+}
+```
+
+**3c. Constructor**
+
+```go
+// Old code: direct assignment
+func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
+    return &TelegramChannel{
+        bus:       bus,
+        config:    cfg,
+        allowList: cfg.Channels.Telegram.AllowFrom,
+        // ...
+    }, nil
+}
+
+// New code: use NewBaseChannel + functional options
+func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
+    base := channels.NewBaseChannel(
+        "telegram",                    // Name
+        cfg.Channels.Telegram,         // Raw config (any type)
+        bus,                           // Message bus
+        cfg.Channels.Telegram.AllowFrom, // Allow list
+        channels.WithMaxMessageLength(4096),                     // Platform message length limit
+        channels.WithGroupTrigger(cfg.Channels.Telegram.GroupTrigger), // Group trigger config
+        channels.WithReasoningChannelID(cfg.Channels.Telegram.ReasoningChannelID), // Reasoning chain routing
+    )
+    return &TelegramChannel{
+        BaseChannel: base,
+        bot:         bot,
+        config:      cfg,
+    }, nil
+}
+```
+
+**3d. Start/Stop lifecycle**
+
+```go
+// New code: use SetRunning atomic operation
+func (c *TelegramChannel) Start(ctx context.Context) error {
+    // ... initialize bot, webhook, etc.
+    c.SetRunning(true)    // Must be called after ready
+    go bh.Start()
+    return nil
+}
+
+func (c *TelegramChannel) Stop(ctx context.Context) error {
+    c.SetRunning(false)   // Must be called before cleanup
+    // ... stop bot handler, cancel context
+    return nil
+}
+```
+
+**3e. Send method error returns**
+
+```go
+// Old code: returns plain error
+func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+    if !c.running { return fmt.Errorf("not running") }
+    // ...
+    if err != nil { return err }
+}
+
+// New code: must return sentinel errors for Manager to determine retry strategy
+func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+    if !c.IsRunning() {
+        return channels.ErrNotRunning    // ← Manager will not retry
+    }
+    // ...
+    if err != nil {
+        // Use ClassifySendError to wrap error based on HTTP status code
+        return channels.ClassifySendError(statusCode, err)
+        // Or manually wrap:
+        // return fmt.Errorf("%w: %v", channels.ErrTemporary, err)
+        // return fmt.Errorf("%w: %v", channels.ErrRateLimit, err)
+        // return fmt.Errorf("%w: %v", channels.ErrSendFailed, err)
+    }
+    return nil
+}
+```
+
+**3f. Message reception (Inbound)**
+
+```go
+// Old code: directly construct InboundMessage and publish
+msg := bus.InboundMessage{
+    Channel:  "telegram",
+    SenderID: senderID,
+    ChatID:   chatID,
+    Content:  content,
+    Metadata: map[string]string{
+        "peer_kind": "group",     // Routing info buried in metadata
+        "peer_id":   chatID,
+        "message_id": msgID,
+    },
+}
+c.bus.PublishInbound(ctx, msg)
+
+// New code: use BaseChannel.HandleMessage with structured fields
+sender := bus.SenderInfo{
+    Platform:    "telegram",
+    PlatformID:  strconv.FormatInt(from.ID, 10),
+    CanonicalID: identity.BuildCanonicalID("telegram", strconv.FormatInt(from.ID, 10)),
+    Username:    from.Username,
+    DisplayName: from.FirstName,
+}
+
+peer := bus.Peer{
+    Kind: "group",    // or "direct"
+    ID:   chatID,
+}
+
+// HandleMessage internally calls IsAllowedSender for permission checks, builds MediaScope, and publishes to bus
+c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, mediaRefs, metadata, sender)
+```
+
+**3g. Add factory registration (required)**
+
+Create `init.go` for your channel:
+
+```go
+// pkg/channels/telegram/init.go
+package telegram
+
+import (
+    "github.com/sipeed/picoclaw/pkg/bus"
+    "github.com/sipeed/picoclaw/pkg/channels"
+    "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+    channels.RegisterFactory("telegram", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+        return NewTelegramChannel(cfg, b)
+    })
+}
+```
+
+**3h. Import sub-package in Gateway**
+
+```go
+// cmd/picoclaw/internal/gateway/helpers.go
+import (
+    _ "github.com/sipeed/picoclaw/pkg/channels/telegram"   // Triggers init() registration
+    _ "github.com/sipeed/picoclaw/pkg/channels/discord"
+    _ "github.com/sipeed/picoclaw/pkg/channels/your_new_channel"  // New addition
+)
+```
+
+#### Step 4: Migrate bus message usage
+
+If your code directly reads routing fields from `InboundMessage.Metadata`:
+
+```go
+// Old code
+peerKind := msg.Metadata["peer_kind"]
+peerID   := msg.Metadata["peer_id"]
+msgID    := msg.Metadata["message_id"]
+
+// New code
+peerKind := msg.Peer.Kind      // First-class field
+peerID   := msg.Peer.ID        // First-class field
+msgID    := msg.MessageID       // First-class field
+sender   := msg.Sender          // bus.SenderInfo struct
+scope    := msg.MediaScope       // Media lifecycle scope
+```
+
+#### Step 5: Migrate allow-list checks
+
+```go
+// Old code
+if !c.isAllowed(senderID) { return }
+
+// New code: prefer structured check
+if !c.IsAllowedSender(sender) { return }
+// Or fall back to string check:
+if !c.IsAllowed(senderID) { return }
+```
+
+`BaseChannel.HandleMessage` already handles this logic internally — no need to duplicate the check in your channel.
+
+### 2.2 If You Have Manager Modifications
+
+The Manager has been completely rewritten. Your modifications will need to account for the new architecture:
+
+| Old Manager Responsibility | New Manager Responsibility |
+|---|---|
+| Directly construct channels (switch/if-else) | Look up and construct via factory registry |
+| Directly call channel.Send | Per-channel Worker queues + rate limiting + retries |
+| No message splitting | Automatic splitting based on MaxMessageLength |
+| Each channel runs its own HTTP server | Unified shared HTTP server |
+| No Typing/Placeholder management | Unified preSend handles Typing stop + Reaction undo + Placeholder edit; inbound-side BaseChannel.HandleMessage auto-orchestrates Typing/Reaction/Placeholder |
+| No TTL cleanup | runTTLJanitor periodically cleans up expired Typing/Reaction/Placeholder entries |
+
+### 2.3 If You Have Agent Loop Modifications
+
+Main changes to the Agent Loop:
+
+1. **MediaStore injection**: `agentLoop.SetMediaStore(mediaStore)` — Agent resolves media references produced by tools via MediaStore
+2. **ChannelManager injection**: `agentLoop.SetChannelManager(channelManager)` — Agent can query channel state
+3. **OutboundMediaMessage**: Agent now sends media messages via `bus.PublishOutboundMedia()` instead of embedding them in text replies
+4. **extractPeer**: Routing uses `msg.Peer` structured fields instead of Metadata lookups
+
+---
+
+## Part 3: New Channel Development Guide — Implementing a Channel from Scratch
+
+### 3.1 Minimum Implementation Checklist
+
+To add a new chat platform (e.g., `matrix`), you need to:
+
+1. ✅ Create sub-package directory `pkg/channels/matrix/`
+2. ✅ Create `init.go` — factory registration
+3. ✅ Create `matrix.go` — channel implementation
+4. ✅ Add blank import in Gateway helpers
+5. ✅ Add config check in Manager.initChannels()
+6. ✅ Add config struct in `pkg/config/`
+
+### 3.2 Complete Template
+
+#### `pkg/channels/matrix/init.go`
+
+```go
+package matrix
+
+import (
+    "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) {
+        return NewMatrixChannel(cfg, b)
+    })
+}
+```
+
+#### `pkg/channels/matrix/matrix.go`
+
+```go
+package matrix
+
+import (
+    "context"
+    "fmt"
+
+    "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"
+)
+
+// MatrixChannel implements channels.Channel for the Matrix protocol.
+type MatrixChannel struct {
+    *channels.BaseChannel            // Must embed
+    config *config.Config
+    ctx    context.Context
+    cancel context.CancelFunc
+    // ... Matrix SDK client, etc.
+}
+
+func NewMatrixChannel(cfg *config.Config, msgBus *bus.MessageBus) (*MatrixChannel, error) {
+    matrixCfg := cfg.Channels.Matrix // Assumes this field exists in config
+
+    base := channels.NewBaseChannel(
+        "matrix",                           // Channel name (globally unique)
+        matrixCfg,                          // Raw config
+        msgBus,                             // Message bus
+        matrixCfg.AllowFrom,                // Allow list
+        channels.WithMaxMessageLength(65536), // Matrix message length limit
+        channels.WithGroupTrigger(matrixCfg.GroupTrigger),
+        channels.WithReasoningChannelID(matrixCfg.ReasoningChannelID), // Reasoning chain routing (optional)
+    )
+
+    return &MatrixChannel{
+        BaseChannel: base,
+        config:      cfg,
+    }, nil
+}
+
+// ========== Required Channel Interface Methods ==========
+
+func (c *MatrixChannel) Start(ctx context.Context) error {
+    c.ctx, c.cancel = context.WithCancel(ctx)
+
+    // 1. Initialize Matrix client
+    // 2. Start listening for messages
+    // 3. Mark as running
+    c.SetRunning(true)
+
+    logger.InfoC("matrix", "Matrix channel started")
+    return nil
+}
+
+func (c *MatrixChannel) Stop(ctx context.Context) error {
+    c.SetRunning(false)
+
+    if c.cancel != nil {
+        c.cancel()
+    }
+
+    logger.InfoC("matrix", "Matrix channel stopped")
+    return nil
+}
+
+func (c *MatrixChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+    // 1. Check running state
+    if !c.IsRunning() {
+        return channels.ErrNotRunning
+    }
+
+    // 2. Send message to Matrix
+    err := c.sendToMatrix(ctx, msg.ChatID, msg.Content)
+    if err != nil {
+        // 3. Must use error classification wrapping
+        //    If you have an HTTP status code:
+        //    return channels.ClassifySendError(statusCode, err)
+        //    If it's a network error:
+        //    return channels.ClassifyNetError(err)
+        //    If manual classification is needed:
+        return fmt.Errorf("%w: %v", channels.ErrTemporary, err)
+    }
+
+    return nil
+}
+
+// ========== Incoming Message Handling ==========
+
+func (c *MatrixChannel) handleIncoming(roomID, senderID, displayName, content string, msgID string) {
+    // 1. Construct structured sender identity
+    sender := bus.SenderInfo{
+        Platform:    "matrix",
+        PlatformID:  senderID,
+        CanonicalID: identity.BuildCanonicalID("matrix", senderID),
+        Username:    senderID,
+        DisplayName: displayName,
+    }
+
+    // 2. Determine Peer type (direct vs group)
+    peer := bus.Peer{
+        Kind: "group",    // or "direct"
+        ID:   roomID,
+    }
+
+    // 3. Group chat filtering (if applicable)
+    isGroup := peer.Kind == "group"
+    if isGroup {
+        isMentioned := false // Detect @mentions based on platform specifics
+        shouldRespond, cleanContent := c.ShouldRespondInGroup(isMentioned, content)
+        if !shouldRespond {
+            return
+        }
+        content = cleanContent
+    }
+
+    // 4. Handle media attachments (if any)
+    var mediaRefs []string
+    store := c.GetMediaStore()
+    if store != nil {
+        // Download attachment locally → store.Store() → get ref
+        // mediaRefs = append(mediaRefs, ref)
+    }
+
+    // 5. Call HandleMessage to publish to bus
+    //    HandleMessage internally will:
+    //    - Check IsAllowedSender/IsAllowed
+    //    - Build MediaScope
+    //    - Publish InboundMessage
+    c.HandleMessage(
+        c.ctx,
+        peer,
+        msgID,                   // Platform message ID
+        senderID,                // Raw sender ID
+        roomID,                  // Chat/room ID
+        content,                 // Message content
+        mediaRefs,               // Media reference list
+        nil,                     // Extra metadata (usually nil)
+        sender,                  // SenderInfo (variadic parameter)
+    )
+}
+
+// ========== Internal Methods ==========
+
+func (c *MatrixChannel) sendToMatrix(ctx context.Context, roomID, content string) error {
+    // Actual Matrix SDK call
+    return nil
+}
+```
+
+### 3.3 Optional Capability Interfaces
+
+Depending on platform capabilities, your channel can optionally implement the following interfaces:
+
+#### MediaSender — Send Media Attachments
+
+```go
+// If the platform supports sending images/files/audio/video
+func (c *MatrixChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+    if !c.IsRunning() {
+        return channels.ErrNotRunning
+    }
+
+    store := c.GetMediaStore()
+    if store == nil {
+        return fmt.Errorf("no media store: %w", channels.ErrSendFailed)
+    }
+
+    for _, part := range msg.Parts {
+        localPath, err := store.Resolve(part.Ref)
+        if err != nil {
+            logger.ErrorCF("matrix", "Failed to resolve media", map[string]any{
+                "ref": part.Ref, "error": err.Error(),
+            })
+            continue
+        }
+
+        // Call the appropriate API based on part.Type ("image"|"audio"|"video"|"file")
+        switch part.Type {
+        case "image":
+            // Upload image to Matrix
+        default:
+            // Upload file to Matrix
+        }
+    }
+    return nil
+}
+```
+
+#### TypingCapable — Typing Indicator
+
+```go
+// If the platform supports "typing..." indicators
+func (c *MatrixChannel) StartTyping(ctx context.Context, chatID string) (stop func(), err error) {
+    // Call Matrix API to send typing indicator
+    // The returned stop function must be idempotent
+    stopped := false
+    return func() {
+        if !stopped {
+            stopped = true
+            // Call Matrix API to stop typing
+        }
+    }, nil
+}
+```
+
+#### ReactionCapable — Message Reaction Indicator
+
+```go
+// If the platform supports adding emoji reactions to inbound messages (e.g., Slack's 👀, OneBot's emoji 289)
+func (c *MatrixChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (undo func(), err error) {
+    // Call Matrix API to add reaction to message
+    // The returned undo function removes the reaction, must be idempotent
+    err = c.addReaction(chatID, messageID, "eyes")
+    if err != nil {
+        return func() {}, err
+    }
+    return func() {
+        c.removeReaction(chatID, messageID, "eyes")
+    }, nil
+}
+```
+
+#### MessageEditor — Message Editing
+
+```go
+// If the platform supports editing sent messages (used for Placeholder replacement)
+func (c *MatrixChannel) EditMessage(ctx context.Context, chatID, messageID, content string) error {
+    // Call Matrix API to edit message
+    return nil
+}
+```
+
+#### PlaceholderCapable — Placeholder Messages
+
+```go
+// If the platform supports sending placeholder messages (e.g. "Thinking... 💭"),
+// and the channel also implements MessageEditor, then Manager's preSend will
+// automatically edit the placeholder into the final response on outbound.
+// SendPlaceholder checks PlaceholderConfig.Enabled internally;
+// returning ("", nil) means skip.
+func (c *MatrixChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+    cfg := c.config.Channels.Matrix.Placeholder
+    if !cfg.Enabled {
+        return "", nil
+    }
+    text := cfg.Text
+    if text == "" {
+        text = "Thinking... 💭"
+    }
+    // Call Matrix API to send placeholder message
+    msg, err := c.sendText(ctx, chatID, text)
+    if err != nil {
+        return "", err
+    }
+    return msg.ID, nil
+}
+```
+
+#### WebhookHandler — HTTP Webhook Reception
+
+```go
+// If the channel receives messages via webhook (rather than long-polling/WebSocket)
+func (c *MatrixChannel) WebhookPath() string {
+    return "/webhook/matrix"   // Path will be registered on the shared HTTP server
+}
+
+func (c *MatrixChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+    // Handle webhook request
+}
+```
+
+#### HealthChecker — Health Check Endpoint
+
+```go
+func (c *MatrixChannel) HealthPath() string {
+    return "/health/matrix"
+}
+
+func (c *MatrixChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
+    if c.IsRunning() {
+        w.WriteHeader(http.StatusOK)
+        w.Write([]byte("OK"))
+    } else {
+        w.WriteHeader(http.StatusServiceUnavailable)
+    }
+}
+```
+
+### 3.4 Inbound-side Typing/Reaction/Placeholder Auto-orchestration
+
+`BaseChannel.HandleMessage` automatically detects whether the channel implements `TypingCapable`, `ReactionCapable`, and/or `PlaceholderCapable` **before** publishing the inbound message, and triggers the corresponding indicators. The three pipelines are completely independent and do not interfere with each other:
+
+```go
+// Automatically executed inside BaseChannel.HandleMessage (no manual calls needed):
+if c.owner != nil && c.placeholderRecorder != nil {
+    // Typing — independent pipeline
+    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
+    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)
+        }
+    }
+}
+```
+
+**This means**:
+- Channels implementing `TypingCapable` (Telegram, Discord, LINE, Pico) do not need to manually call `StartTyping` + `RecordTypingStop` in `handleMessage`
+- Channels implementing `ReactionCapable` (Slack, OneBot) do not need to manually call `AddReaction` + `RecordTypingStop` in `handleMessage`
+- Channels implementing `PlaceholderCapable` (Telegram, Discord, Pico) do not need to manually send placeholder messages and call `RecordPlaceholder` in `handleMessage`
+- Channels only need to implement the corresponding interface; `HandleMessage` handles orchestration automatically
+- Channels that don't implement these interfaces are unaffected (type assertions will fail and be skipped)
+- `PlaceholderCapable`'s `SendPlaceholder` method internally decides whether to send based on the configured `PlaceholderConfig.Enabled`; returning `("", nil)` skips registration
+
+**Owner Injection**: Manager automatically calls `SetOwner(ch)` in `initChannel` to inject the concrete channel into BaseChannel — no manual setup required from developers.
+
+When the Agent finishes processing a message, Manager's `preSend` automatically:
+1. Calls the recorded `stop()` to stop Typing
+2. Calls the recorded `undo()` to undo Reaction
+3. If there is a Placeholder and the channel implements `MessageEditor`, attempts to edit the Placeholder with the final reply (skipping Send)
+
+### 3.5 Register Configuration and Gateway Integration
+
+#### Add configuration in `pkg/config/config.go`
+
+```go
+type ChannelsConfig struct {
+    // ... existing channels
+    Matrix  MatrixChannelConfig  `json:"matrix"`
+}
+
+type MatrixChannelConfig struct {
+    Enabled    bool     `json:"enabled"`
+    HomeServer string   `json:"home_server"`
+    Token      string   `json:"token"`
+    AllowFrom  []string `json:"allow_from"`
+    GroupTrigger GroupTriggerConfig `json:"group_trigger"`
+    Placeholder  PlaceholderConfig  `json:"placeholder"`
+    ReasoningChannelID string `json:"reasoning_channel_id"`
+}
+```
+
+#### Add entry in Manager.initChannels()
+
+```go
+// In the initChannels() method of pkg/channels/manager.go
+if m.config.Channels.Matrix.Enabled && m.config.Channels.Matrix.Token != "" {
+    m.initChannel("matrix", "Matrix")
+}
+```
+
+> **Note**: If your channel has multiple modes (like WhatsApp Bridge vs Native), branch in initChannels based on config:
+> ```go
+> if cfg.UseNative {
+>     m.initChannel("whatsapp_native", "WhatsApp Native")
+> } else {
+>     m.initChannel("whatsapp", "WhatsApp")
+> }
+> ```
+
+#### Add blank import in Gateway
+
+```go
+// cmd/picoclaw/internal/gateway/helpers.go
+import (
+    _ "github.com/sipeed/picoclaw/pkg/channels/matrix"
+)
+```
+
+---
+
+## Part 4: Core Subsystem Details
+
+### 4.1 MessageBus
+
+**Files**: `pkg/bus/bus.go`, `pkg/bus/types.go`
+
+```go
+type MessageBus struct {
+    inbound       chan InboundMessage       // buffer = 64
+    outbound      chan OutboundMessage      // buffer = 64
+    outboundMedia chan OutboundMediaMessage  // buffer = 64
+    done          chan struct{}             // Close signal
+    closed        atomic.Bool              // Prevents double-close
+}
+```
+
+**Key Behaviors**:
+
+| Method | Behavior |
+|--------|----------|
+| `PublishInbound(ctx, msg)` | Check closed → send to inbound channel → block/timeout/close |
+| `ConsumeInbound(ctx)` | Read from inbound → block/close/cancel |
+| `PublishOutbound(ctx, msg)` | Send to outbound channel |
+| `SubscribeOutbound(ctx)` | Read from outbound (called by Manager dispatcher) |
+| `PublishOutboundMedia(ctx, msg)` | Send to outboundMedia channel |
+| `SubscribeOutboundMedia(ctx)` | Read from outboundMedia (called by Manager media dispatcher) |
+| `Close()` | CAS close → close(done) → drain all channels (**does not close the channels themselves** to avoid concurrent send-on-closed panic) |
+
+**Design Notes**:
+- Buffer size increased from 16 to 64 to reduce blocking under burst load
+- `Close()` does not close the underlying channels (only closes the `done` signal channel), because there may be concurrent `Publish` goroutines
+- Drain loop ensures buffered messages are not silently dropped
+
+### 4.2 Structured Message Types
+
+**File**: `pkg/bus/types.go`
+
+```go
+// Routing peer
+type Peer struct {
+    Kind string `json:"kind"`  // "direct" | "group" | "channel" | ""
+    ID   string `json:"id"`
+}
+
+// Sender identity information
+type SenderInfo struct {
+    Platform    string `json:"platform,omitempty"`     // "telegram", "discord", ...
+    PlatformID  string `json:"platform_id,omitempty"`  // Platform-native ID
+    CanonicalID string `json:"canonical_id,omitempty"` // "platform:id" canonical format
+    Username    string `json:"username,omitempty"`
+    DisplayName string `json:"display_name,omitempty"`
+}
+
+// Inbound message
+type InboundMessage struct {
+    Channel    string            // Source channel name
+    SenderID   string            // Sender ID (prefer CanonicalID)
+    Sender     SenderInfo        // Structured sender info
+    ChatID     string            // Chat/room ID
+    Content    string            // Message text
+    Media      []string          // Media reference list (media://...)
+    Peer       Peer              // Routing peer (first-class field)
+    MessageID  string            // Platform message ID (first-class field)
+    MediaScope string            // Media lifecycle scope
+    SessionKey string            // Session key
+    Metadata   map[string]string // Only for channel-specific extensions
+}
+
+// Outbound text message
+type OutboundMessage struct {
+    Channel string
+    ChatID  string
+    Content string
+}
+
+// Outbound media message
+type OutboundMediaMessage struct {
+    Channel string
+    ChatID  string
+    Parts   []MediaPart
+}
+
+// Media part
+type MediaPart struct {
+    Type        string // "image" | "audio" | "video" | "file"
+    Ref         string // "media://uuid"
+    Caption     string
+    Filename    string
+    ContentType string
+}
+```
+
+### 4.3 BaseChannel
+
+**File**: `pkg/channels/base.go`
+
+BaseChannel is the shared abstraction layer for all channels, providing the following capabilities:
+
+| Method/Feature | Description |
+|---|---|
+| `Name() string` | Channel name |
+| `IsRunning() bool` | Atomically read running state |
+| `SetRunning(bool)` | Atomically set running state |
+| `MaxMessageLength() int` | Message length limit (rune count), 0 = unlimited |
+| `ReasoningChannelID() string` | Reasoning chain routing target channel ID (empty = no routing) |
+| `IsAllowed(senderID string) bool` | Legacy allow-list check (supports `"id\|username"` and `"@username"` formats) |
+| `IsAllowedSender(sender SenderInfo) bool` | New allow-list check (delegates to `identity.MatchAllowed`) |
+| `ShouldRespondInGroup(isMentioned, content) (bool, string)` | Unified group chat trigger filtering logic |
+| `HandleMessage(...)` | Unified inbound message handling: permission check → build MediaScope → auto-trigger Typing/Reaction/Placeholder → publish to Bus |
+| `SetMediaStore(s) / GetMediaStore()` | MediaStore injected by Manager |
+| `SetPlaceholderRecorder(r) / GetPlaceholderRecorder()` | PlaceholderRecorder injected by Manager |
+| `SetOwner(ch)` | Concrete channel reference injected by Manager (used for Typing/Reaction/Placeholder type assertions in HandleMessage) |
+
+**Functional Options**:
+
+```go
+channels.WithMaxMessageLength(4096)        // Set platform message length limit
+channels.WithGroupTrigger(groupTriggerCfg) // Set group trigger configuration
+channels.WithReasoningChannelID(id)        // Set reasoning chain routing target channel
+```
+
+### 4.4 Factory Registry
+
+**File**: `pkg/channels/registry.go`
+
+```go
+type ChannelFactory func(cfg *config.Config, bus *bus.MessageBus) (Channel, error)
+
+func RegisterFactory(name string, f ChannelFactory)   // Called in sub-package init()
+func getFactory(name string) (ChannelFactory, bool)    // Called internally by Manager
+```
+
+The factory registry is protected by `sync.RWMutex` and registrations occur during `init()` phase (completed at process startup). Manager looks up factories by name in `initChannel()` and calls them.
+
+### 4.5 Error Classification and Retries
+
+**Files**: `pkg/channels/errors.go`, `pkg/channels/errutil.go`
+
+#### Sentinel Errors
+
+```go
+var (
+    ErrNotRunning = errors.New("channel not running")   // Permanent: do not retry
+    ErrRateLimit  = errors.New("rate limited")           // Fixed delay: retry after 1s
+    ErrTemporary  = errors.New("temporary failure")      // Exponential backoff: 500ms * 2^attempt, max 8s
+    ErrSendFailed = errors.New("send failed")            // Permanent: do not retry
+)
+```
+
+#### Error Classification Helpers
+
+```go
+// Automatically classify based on HTTP status code
+func ClassifySendError(statusCode int, rawErr error) error {
+    // 429 → ErrRateLimit
+    // 5xx → ErrTemporary
+    // 4xx → ErrSendFailed
+}
+
+// Wrap network errors as temporary
+func ClassifyNetError(err error) error {
+    // → ErrTemporary
+}
+```
+
+#### Manager Retry Strategy (`sendWithRetry`)
+
+```
+Max retries:      3
+Rate limit delay:  1 second
+Base backoff:      500 milliseconds
+Max backoff:       8 seconds
+
+Retry logic:
+  ErrNotRunning → Fail immediately, no retry
+  ErrSendFailed → Fail immediately, no retry
+  ErrRateLimit  → Wait 1s → retry
+  ErrTemporary  → Wait 500ms * 2^attempt (max 8s) → retry
+  Other unknown → Wait 500ms * 2^attempt (max 8s) → retry
+```
+
+### 4.6 Manager Orchestration
+
+**File**: `pkg/channels/manager.go`
+
+#### Per-channel Worker Architecture
+
+```go
+type channelWorker struct {
+    ch         Channel                      // Channel instance
+    queue      chan bus.OutboundMessage      // Outbound text queue (buffered 16)
+    mediaQueue chan bus.OutboundMediaMessage // Outbound media queue (buffered 16)
+    done       chan struct{}                // Text worker completion signal
+    mediaDone  chan struct{}                // Media worker completion signal
+    limiter    *rate.Limiter                // Per-channel rate limiter
+}
+```
+
+#### Per-channel Rate Limit Configuration
+
+```go
+var channelRateConfig = map[string]float64{
+    "telegram": 20,   // 20 msg/s
+    "discord":  1,    // 1 msg/s
+    "slack":    1,    // 1 msg/s
+    "line":     10,   // 10 msg/s
+}
+// Default: 10 msg/s
+// burst = max(1, ceil(rate/2))
+```
+
+#### Lifecycle Management
+
+```
+StartAll:
+  1. Iterate registered channels → channel.Start(ctx)
+  2. Create channelWorker for each successfully started channel
+  3. Start goroutines:
+     - runWorker (per-channel outbound text)
+     - runMediaWorker (per-channel outbound media)
+     - dispatchOutbound (route from bus to worker queues)
+     - dispatchOutboundMedia (route from bus to media worker queues)
+     - runTTLJanitor (every 10s clean up expired typing/reaction/placeholder)
+  4. Start shared HTTP server (if configured)
+
+StopAll:
+  1. Shut down shared HTTP server (5s timeout)
+  2. Cancel dispatcher context
+  3. Close text worker queues → wait for drain to complete
+  4. Close media worker queues → wait for drain to complete
+  5. Stop each channel (channel.Stop)
+```
+
+#### Typing/Reaction/Placeholder Management
+
+```go
+// Manager implements PlaceholderRecorder interface
+func (m *Manager) RecordPlaceholder(channel, chatID, placeholderID string)
+func (m *Manager) RecordTypingStop(channel, chatID string, stop func())
+func (m *Manager) RecordReactionUndo(channel, chatID string, undo func())
+
+// Inbound side: BaseChannel.HandleMessage auto-orchestrates
+// BaseChannel.HandleMessage, before PublishInbound, auto-triggers via owner type assertions:
+//   - TypingCapable.StartTyping       → RecordTypingStop
+//   - ReactionCapable.ReactToMessage  → RecordReactionUndo
+//   - PlaceholderCapable.SendPlaceholder → RecordPlaceholder
+// All three are independent and do not interfere with each other. Channels don't need to call these manually.
+
+// Outbound side: pre-send processing
+func (m *Manager) preSend(ctx, name, msg, ch) bool {
+    key := name + ":" + msg.ChatID
+    // 1. Stop Typing (call stored stop function)
+    // 2. Undo Reaction (call stored undo function)
+    // 3. Attempt to edit Placeholder (if channel implements MessageEditor)
+    //    Success → return true (skip Send)
+    //    Failure → return false (proceed with Send)
+}
+```
+
+Manager storage is fully separated; three pipelines do not interfere:
+
+```go
+Manager {
+    typingStops   sync.Map  // "channel:chatID" → typingEntry    ← manages TypingCapable
+    reactionUndos sync.Map  // "channel:chatID" → reactionEntry  ← manages ReactionCapable
+    placeholders  sync.Map  // "channel:chatID" → placeholderEntry
+}
+```
+
+TTL Cleanup:
+- Typing stop functions: 5-minute TTL (auto-calls stop and deletes on expiry)
+- Reaction undo functions: 5-minute TTL (auto-calls undo and deletes on expiry)
+- Placeholder IDs: 10-minute TTL (deletes on expiry)
+- Cleanup interval: 10 seconds
+
+### 4.7 Message Splitting
+
+**File**: `pkg/channels/split.go`
+
+`SplitMessage(content string, maxLen int) []string`
+
+Smart splitting strategy:
+1. Calculate effective split point = maxLen - 10% buffer (to reserve space for code block closure)
+2. Prefer splitting at newlines
+3. Otherwise split at spaces/tabs
+4. Detect unclosed code blocks (` ``` `)
+5. If a code block is unclosed:
+   - Attempt to extend to maxLen to include the closing fence
+   - If the code block is too long, inject close/reopen fences (`\n```\n` + header)
+   - Last resort: split before the code block starts
+
+### 4.8 MediaStore
+
+**File**: `pkg/media/store.go`
+
+```go
+type MediaStore interface {
+    Store(localPath string, meta MediaMeta, scope string) (ref string, err error)
+    Resolve(ref string) (localPath string, err error)
+    ResolveWithMeta(ref string) (localPath string, meta MediaMeta, err error)
+    ReleaseAll(scope string) error
+}
+```
+
+**FileMediaStore Implementation**:
+- Pure in-memory mapping, no file copy/move
+- Reference format: `media://<uuid>`
+- Scope format: `channel:chatID:messageID` (generated by `BuildMediaScope`)
+- **Two-phase operation**:
+  - Phase 1 (holding lock): collect and delete entries from map
+  - Phase 2 (no lock): delete files from disk
+  - Purpose: minimize lock contention
+- **TTL Cleanup**: `NewFileMediaStoreWithCleanup` → `Start()` launches background cleanup goroutine
+- Cleanup interval and max TTL are controlled by configuration
+
+### 4.9 Identity
+
+**File**: `pkg/identity/identity.go`
+
+```go
+// Build canonical ID
+func BuildCanonicalID(platform, platformID string) string
+// → "telegram:123456"
+
+// Parse canonical ID
+func ParseCanonicalID(canonical string) (platform, id string, ok bool)
+
+// Match against allow list (backward-compatible)
+func MatchAllowed(sender bus.SenderInfo, allowed string) bool
+```
+
+`MatchAllowed` supported allow-list formats:
+| Format | Matching |
+|--------|----------|
+| `"123456"` | Matches `sender.PlatformID` |
+| `"@alice"` | Matches `sender.Username` |
+| `"123456\|alice"` | Matches PlatformID or Username (legacy format compatibility) |
+| `"telegram:123456"` | Exact match on `sender.CanonicalID` (new format) |
+
+### 4.10 Shared HTTP Server
+
+**File**: `pkg/channels/manager.go`'s `SetupHTTPServer`
+
+Manager creates a single `http.Server` and auto-discovers and registers:
+- Channels implementing `WebhookHandler` → mounted at `wh.WebhookPath()`
+- Channels implementing `HealthChecker` → mounted at `hc.HealthPath()`
+- Global health endpoint registered by `health.Server.RegisterOnMux`
+
+Timeout configuration: ReadTimeout = 30s, WriteTimeout = 30s
+
+---
+
+## Part 5: Key Design Decisions and Conventions
+
+### 5.1 Mandatory Conventions
+
+1. **Error classification is a contract**: A channel's `Send` method **must** return sentinel errors (or wrap them). Manager's retry strategy relies entirely on `errors.Is` checks. Returning unclassified errors will cause Manager to treat them as "unknown errors" (exponential backoff retry).
+
+2. **SetRunning is a lifecycle signal**: **Must** call `c.SetRunning(true)` after successful `Start`, and **must** call `c.SetRunning(false)` at the beginning of `Stop`. **Must** check `c.IsRunning()` in `Send` and return `ErrNotRunning`.
+
+3. **HandleMessage includes permission checks**: Do not perform your own permission checks before calling `HandleMessage` (unless you need platform-specific preprocessing before the check). `HandleMessage` already calls `IsAllowedSender`/`IsAllowed` internally.
+
+4. **Message splitting is handled by Manager**: A channel's `Send` method does not need to handle long message splitting. Manager automatically splits based on `MaxMessageLength()` before calling `Send`. Channels only need to declare the limit via `WithMaxMessageLength`.
+
+5. **Typing/Reaction/Placeholder is handled by BaseChannel + Manager automatically**: A channel's `Send` method does not need to manage Typing stop, Reaction undo, or Placeholder editing. `BaseChannel.HandleMessage` auto-triggers `TypingCapable`, `ReactionCapable`, and `PlaceholderCapable` on the inbound side (via `owner` type assertions); Manager's `preSend` auto-stops Typing, undoes Reaction, and edits Placeholder on the outbound side. Channels only need to implement the corresponding interfaces.
+
+6. **Factory registration belongs in init()**: Each sub-package must have an `init.go` file calling `channels.RegisterFactory`. Gateway must trigger registration via blank imports (`_ "pkg/channels/xxx"`).
+
+### 5.2 Metadata Field Usage Conventions
+
+**Do NOT put the following information in Metadata anymore**:
+- `peer_kind` / `peer_id` → Use `InboundMessage.Peer`
+- `message_id` → Use `InboundMessage.MessageID`
+- `sender_platform` / `sender_username` → Use `InboundMessage.Sender`
+
+**Metadata should only be used for**:
+- Channel-specific extension information (e.g., Telegram's `reply_to_message_id`)
+- Temporary information that doesn't fit into structured fields
+
+### 5.3 Concurrency Safety Conventions
+
+- `BaseChannel.running`: Uses `atomic.Bool`, thread-safe
+- `Manager.channels` / `Manager.workers`: Protected by `sync.RWMutex`
+- `Manager.placeholders` / `Manager.typingStops` / `Manager.reactionUndos`: Uses `sync.Map`
+- `MessageBus.closed`: Uses `atomic.Bool`
+- `FileMediaStore`: Uses `sync.RWMutex`, two-phase operation to minimize lock-hold time
+- Channel Worker queue: Go channel, inherently concurrent-safe
+
+### 5.4 Testing Conventions
+
+Existing test files:
+- `pkg/channels/base_test.go` — BaseChannel unit tests
+- `pkg/channels/manager_test.go` — Manager unit tests
+- `pkg/channels/split_test.go` — Message splitting tests
+- `pkg/channels/errors_test.go` — Error type tests
+- `pkg/channels/errutil_test.go` — Error classification tests
+
+To add tests for a new channel:
+```bash
+go test ./pkg/channels/matrix/ -v              # Sub-package tests
+go test ./pkg/channels/ -run TestSpecific -v    # Framework tests
+make test                                       # Full test suite
+```
+
+---
+
+## Appendix: Complete File Listing and Interface Quick Reference
+
+### A.1 Framework Layer Files
+
+| File | Responsibility |
+|------|---------------|
+| `pkg/channels/base.go` | BaseChannel struct, Channel interface, MessageLengthProvider, BaseChannelOption, HandleMessage |
+| `pkg/channels/interfaces.go` | TypingCapable, MessageEditor, ReactionCapable, PlaceholderCapable, PlaceholderRecorder interfaces |
+| `pkg/channels/media.go` | MediaSender interface |
+| `pkg/channels/webhook.go` | WebhookHandler, HealthChecker interfaces |
+| `pkg/channels/errors.go` | ErrNotRunning, ErrRateLimit, ErrTemporary, ErrSendFailed sentinels |
+| `pkg/channels/errutil.go` | ClassifySendError, ClassifyNetError helpers |
+| `pkg/channels/registry.go` | RegisterFactory, getFactory factory registry |
+| `pkg/channels/manager.go` | Manager: Worker queues, rate limiting, retries, preSend, shared HTTP, TTL janitor |
+| `pkg/channels/split.go` | SplitMessage long-message splitting |
+| `pkg/bus/bus.go` | MessageBus implementation |
+| `pkg/bus/types.go` | Peer, SenderInfo, InboundMessage, OutboundMessage, OutboundMediaMessage, MediaPart |
+| `pkg/media/store.go` | MediaStore interface, FileMediaStore implementation |
+| `pkg/identity/identity.go` | BuildCanonicalID, ParseCanonicalID, MatchAllowed |
+
+### A.2 Channel Sub-packages
+
+| Sub-package | Registered Name | Optional Interfaces |
+|-------------|----------------|-------------------|
+| `pkg/channels/telegram/` | `"telegram"` | TypingCapable, PlaceholderCapable, MessageEditor, MediaSender |
+| `pkg/channels/discord/` | `"discord"` | TypingCapable, PlaceholderCapable, MessageEditor, MediaSender |
+| `pkg/channels/slack/` | `"slack"` | ReactionCapable, MediaSender |
+| `pkg/channels/line/` | `"line"` | TypingCapable, MediaSender, WebhookHandler |
+| `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/qq/` | `"qq"` | — |
+| `pkg/channels/whatsapp/` | `"whatsapp"` | — (Bridge mode) |
+| `pkg/channels/whatsapp_native/` | `"whatsapp_native"` | — (Native whatsmeow mode) |
+| `pkg/channels/maixcam/` | `"maixcam"` | — |
+| `pkg/channels/pico/` | `"pico"` | TypingCapable, PlaceholderCapable, MessageEditor, WebhookHandler |
+
+### A.3 Interface Quick Reference
+
+```go
+// ===== Required =====
+type Channel interface {
+    Name() string
+    Start(ctx context.Context) error
+    Stop(ctx context.Context) error
+    Send(ctx context.Context, msg bus.OutboundMessage) error
+    IsRunning() bool
+    IsAllowed(senderID string) bool
+    IsAllowedSender(sender bus.SenderInfo) bool
+    ReasoningChannelID() string
+}
+
+// ===== Optional =====
+type MediaSender interface {
+    SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error
+}
+
+type TypingCapable interface {
+    StartTyping(ctx context.Context, chatID string) (stop func(), err error)
+}
+
+type ReactionCapable interface {
+    ReactToMessage(ctx context.Context, chatID, messageID string) (undo func(), err error)
+}
+
+type PlaceholderCapable interface {
+    SendPlaceholder(ctx context.Context, chatID string) (messageID string, err error)
+}
+
+type MessageEditor interface {
+    EditMessage(ctx context.Context, chatID, messageID, content string) error
+}
+
+type WebhookHandler interface {
+    WebhookPath() string
+    http.Handler
+}
+
+type HealthChecker interface {
+    HealthPath() string
+    HealthHandler(w http.ResponseWriter, r *http.Request)
+}
+
+type MessageLengthProvider interface {
+    MaxMessageLength() int
+}
+
+// ===== Injected by Manager =====
+type PlaceholderRecorder interface {
+    RecordPlaceholder(channel, chatID, placeholderID string)
+    RecordTypingStop(channel, chatID string, stop func())
+    RecordReactionUndo(channel, chatID string, undo func())
+}
+```
+
+### A.4 Gateway Startup Sequence (Complete Bootstrap Flow)
+
+```go
+// 1. Create core components
+msgBus     := bus.NewMessageBus()
+provider   := providers.CreateProvider(cfg)
+agentLoop  := agent.NewAgentLoop(cfg, msgBus, provider)
+
+// 2. Create media store (with TTL cleanup)
+mediaStore := media.NewFileMediaStoreWithCleanup(cleanerConfig)
+mediaStore.Start()
+
+// 3. Create Channel Manager (triggers initChannels → factory lookup → construct → inject MediaStore/PlaceholderRecorder/Owner)
+channelManager := channels.NewManager(cfg, msgBus, mediaStore)
+
+// 4. Inject references
+agentLoop.SetChannelManager(channelManager)
+agentLoop.SetMediaStore(mediaStore)
+
+// 5. Configure shared HTTP server
+channelManager.SetupHTTPServer(addr, healthServer)
+
+// 6. Start
+channelManager.StartAll(ctx)  // Start channels + workers + dispatchers + HTTP server
+go agentLoop.Run(ctx)          // Start Agent message loop
+
+// 7. Shutdown (signal-triggered)
+cancel()                       // Cancel context
+msgBus.Close()                 // Signal close + drain
+channelManager.StopAll(shutdownCtx)  // Stop HTTP + workers + channels
+mediaStore.Stop()              // Stop TTL cleanup
+agentLoop.Stop()               // Stop Agent
+```
+
+### A.5 Per-channel Rate Limit Reference
+
+| Channel | Rate (msg/s) | Burst |
+|---------|-------------|-------|
+| telegram | 20 | 10 |
+| discord | 1 | 1 |
+| slack | 1 | 1 |
+| line | 10 | 5 |
+| _others_ | 10 (default) | 5 |
+
+### A.6 Known Limitations and Caveats
+
+1. **Media cleanup temporarily disabled**: The `ReleaseAll` call in the Agent loop is commented out (`refactor(loop): disable media cleanup to prevent premature file deletion`) because session boundaries are not yet clearly defined. TTL cleanup remains active.
+
+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`.
+
+4. **Pico Protocol**: `pkg/channels/pico/` implements a custom PicoClaw native protocol channel that receives messages via WebSocket webhook (`/pico/ws`).
+
+5. **WhatsApp has two modes**: `"whatsapp"` (Bridge mode, communicates via external bridge URL) and `"whatsapp_native"` (native whatsmeow mode, connects directly to WhatsApp). Manager selects which to initialize based on `WhatsAppConfig.UseNative`.
+
+6. **DingTalk uses Stream mode**: DingTalk uses the SDK's Stream/WebSocket mode (not HTTP webhook), so it does not implement `WebhookHandler`.
+
+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
diff --git a/pkg/channels/README.zh.md b/pkg/channels/README.zh.md
new file mode 100644
index 000000000..2c5e7356e
--- /dev/null
+++ b/pkg/channels/README.zh.md
@@ -0,0 +1,1383 @@
+# PicoClaw Channel System：完整开发指南
+
+> **影响范围**: `pkg/channels/`, `pkg/bus/`, `pkg/media/`, `pkg/identity/`, `cmd/picoclaw/internal/gateway/`
+
+---
+
+## 目录
+
+- [第一部分：架构总览](#第一部分架构总览)
+- [第二部分：迁移指南——从 main 分支迁移到重构分支](#第二部分迁移指南从-main-分支迁移到重构分支)
+- [第三部分：新 Channel 开发指南——从零实现一个新 Channel](#第三部分新-channel-开发指南从零实现一个新-channel)
+- [第四部分：核心子系统详解](#第四部分核心子系统详解)
+- [第五部分：关键设计决策与约定](#第五部分关键设计决策与约定)
+- [附录：完整文件清单与接口速查表](#附录完整文件清单与接口速查表)
+
+---
+
+## 第一部分：架构总览
+
+### 1.1 重构前后对比
+
+**重构前（main 分支）**：
+
+```
+pkg/channels/
+├── telegram.go          # 每个 channel 直接放在 channels 包内
+├── discord.go
+├── slack.go
+├── manager.go           # Manager 直接引用各 channel 类型
+├── ...
+```
+
+- Channel 实现全部在 `pkg/channels/` 包的顶层
+- Manager 通过 `switch` 或 `if-else` 链条直接构造各 channel
+- Peer、MessageID 等路由信息埋在 `Metadata map[string]string` 中
+- 消息发送没有速率限制和重试
+- 没有统一的媒体文件生命周期管理
+- 各 channel 各自启动 HTTP 服务器
+- 群聊触发过滤逻辑分散在各 channel 中
+
+**重构后（refactor/channel-system 分支）**：
+
+```
+pkg/channels/
+├── base.go              # BaseChannel 共享抽象层
+├── interfaces.go        # 可选能力接口（TypingCapable, MessageEditor, ReactionCapable, PlaceholderCapable, PlaceholderRecorder）
+├── README.md            # 英文文档
+├── README.zh.md         # 中文文档
+├── media.go             # MediaSender 可选接口
+├── webhook.go           # WebhookHandler, HealthChecker 可选接口
+├── errors.go            # 错误哨兵值（ErrNotRunning, ErrRateLimit, ErrTemporary, ErrSendFailed）
+├── errutil.go           # 错误分类帮助函数
+├── registry.go          # 工厂注册表（RegisterFactory / getFactory）
+├── manager.go           # 统一编排：Worker 队列、速率限制、重试、Typing/Placeholder、共享 HTTP
+├── split.go             # 长消息智能分割（保留代码块完整性）
+├── telegram/            # 每个 channel 独立子包
+│   ├── init.go          # 工厂注册
+│   ├── telegram.go      # 实现
+│   └── telegram_commands.go
+├── discord/
+│   ├── init.go
+│   └── discord.go
+├── slack/ line/ onebot/ dingtalk/ feishu/ wecom/ qq/ whatsapp/ whatsapp_native/ maixcam/ pico/
+│   └── ...
+
+pkg/bus/
+├── bus.go               # MessageBus（缓冲区 64，安全关闭+排水）
+├── types.go             # 结构化消息类型（Peer, SenderInfo, MediaPart, InboundMessage, OutboundMessage, OutboundMediaMessage）
+
+pkg/media/
+├── store.go             # MediaStore 接口 + FileMediaStore 实现（两阶段释放，TTL 清理）
+
+pkg/identity/
+├── identity.go          # 统一用户身份：规范 "platform:id" 格式 + 向后兼容匹配
+```
+
+### 1.2 消息流转全景图
+
+```
+┌────────────┐      InboundMessage       ┌───────────┐      LLM + Tools      ┌────────────┐
+│  Telegram   │──┐                        │           │                        │            │
+│  Discord    │──┤   PublishInbound()     │           │   PublishOutbound()   │            │
+│  Slack      │──┼──────────────────────▶ │ MessageBus │ ◀─────────────────── │ AgentLoop  │
+│  LINE       │──┤   (buffered chan, 64)  │           │   (buffered chan, 64) │            │
+│  ...        │──┘                        │           │                        │            │
+└────────────┘                            └─────┬─────┘                        └────────────┘
+                                                │
+                            SubscribeOutbound() │  SubscribeOutboundMedia()
+                                                ▼
+                                    ┌───────────────────┐
+                                    │   Manager          │
+                                    │   ├── dispatchOutbound()    路由到 Worker 队列
+                                    │   ├── dispatchOutboundMedia()
+                                    │   ├── runWorker()           消息分割 + sendWithRetry()
+                                    │   ├── runMediaWorker()      sendMediaWithRetry()
+                                    │   ├── preSend()             停止 Typing + 撤销 Reaction + 编辑 Placeholder
+                                    │   └── runTTLJanitor()       清理过期 Typing/Placeholder
+                                    └────────┬──────────┘
+                                             │
+                                   channel.Send() / SendMedia()
+                                             │
+                                             ▼
+                                    ┌────────────────┐
+                                    │ 各平台 API/SDK  │
+                                    └────────────────┘
+```
+
+### 1.3 关键设计原则
+
+| 原则 | 说明 |
+|------|------|
+| **子包隔离** | 每个 channel 一个独立 Go 子包，依赖 `channels` 父包提供的 `BaseChannel` 和接口 |
+| **工厂注册** | 各子包通过 `init()` 自注册，Manager 通过名字查找工厂，消除 import 耦合 |
+| **能力发现** | 可选能力通过接口（`MediaSender`, `TypingCapable`, `ReactionCapable`, `PlaceholderCapable`, `MessageEditor`, `WebhookHandler`, `HealthChecker`）声明，Manager 运行时类型断言发现 |
+| **结构化消息** | Peer、MessageID、SenderInfo 从 Metadata 提升为 InboundMessage 的一等字段 |
+| **错误分类** | Channel 返回哨兵错误（`ErrRateLimit`, `ErrTemporary` 等），Manager 据此决定重试策略 |
+| **集中编排** | 速率限制、消息分割、重试、Typing/Reaction/Placeholder 全部由 Manager 和 BaseChannel 统一处理，Channel 只负责 Send |
+
+---
+
+## 第二部分：迁移指南——从 main 分支迁移到重构分支
+
+### 2.1 如果你有未合并的 Channel 修改
+
+#### 步骤 1：确认你修改了哪些文件
+
+在 main 分支上，Channel 文件直接位于 `pkg/channels/` 顶层，例如：
+- `pkg/channels/telegram.go`
+- `pkg/channels/discord.go`
+
+重构后，这些文件已被删除，代码移动到了对应子包：
+- `pkg/channels/telegram/telegram.go`
+- `pkg/channels/discord/discord.go`
+
+#### 步骤 2：理解结构变化映射
+
+| main 分支文件 | 重构分支位置 | 变化 |
+|---|---|---|
+| `pkg/channels/telegram.go` | `pkg/channels/telegram/telegram.go` + `init.go` | 包名从 `channels` 变为 `telegram` |
+| `pkg/channels/discord.go` | `pkg/channels/discord/discord.go` + `init.go` | 同上 |
+| `pkg/channels/manager.go` | `pkg/channels/manager.go` | 大幅重写 |
+| _(不存在)_ | `pkg/channels/base.go` | 新增共享抽象层 |
+| _(不存在)_ | `pkg/channels/registry.go` | 新增工厂注册表 |
+| _(不存在)_ | `pkg/channels/errors.go` + `errutil.go` | 新增错误分类体系 |
+| _(不存在)_ | `pkg/channels/interfaces.go` | 新增可选能力接口 |
+| _(不存在)_ | `pkg/channels/media.go` | 新增 MediaSender 接口 |
+| _(不存在)_ | `pkg/channels/webhook.go` | 新增 WebhookHandler/HealthChecker |
+| _(不存在)_ | `pkg/channels/whatsapp_native/` | 新增 WhatsApp 原生模式（whatsmeow） |
+| _(不存在)_ | `pkg/channels/split.go` | 新增消息分割（从 utils 迁入） |
+| _(不存在)_ | `pkg/bus/types.go` | 新增结构化消息类型 |
+| _(不存在)_ | `pkg/media/store.go` | 新增媒体文件生命周期管理 |
+| _(不存在)_ | `pkg/identity/identity.go` | 新增统一用户身份 |
+
+#### 步骤 3：迁移你的 Channel 代码
+
+以 Telegram 为例，主要改动项：
+
+**3a. 包声明和导入**
+
+```go
+// 旧代码（main 分支）
+package channels
+
+import (
+    "github.com/sipeed/picoclaw/pkg/bus"
+    "github.com/sipeed/picoclaw/pkg/config"
+)
+
+// 新代码（重构分支）
+package telegram
+
+import (
+    "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/media"          // 新增（如需媒体）
+)
+```
+
+**3b. 结构体嵌入 BaseChannel**
+
+```go
+// 旧代码：直接持有 bus、config 等字段
+type TelegramChannel struct {
+    bus       *bus.MessageBus
+    config    *config.Config
+    running   bool
+    allowList []string
+    // ...
+}
+
+// 新代码：嵌入 BaseChannel，它提供 bus、running、allowList 等
+type TelegramChannel struct {
+    *channels.BaseChannel          // 嵌入共享抽象
+    bot    *telego.Bot
+    config *config.Config
+    // ... 只保留 channel 特有字段
+}
+```
+
+**3c. 构造函数**
+
+```go
+// 旧代码：直接赋值
+func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
+    return &TelegramChannel{
+        bus:       bus,
+        config:    cfg,
+        allowList: cfg.Channels.Telegram.AllowFrom,
+        // ...
+    }, nil
+}
+
+// 新代码：使用 NewBaseChannel + 功能选项
+func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
+    base := channels.NewBaseChannel(
+        "telegram",                    // 名称
+        cfg.Channels.Telegram,         // 原始配置（any 类型）
+        bus,                           // 消息总线
+        cfg.Channels.Telegram.AllowFrom, // 允许列表
+        channels.WithMaxMessageLength(4096),                     // 平台消息长度上限
+        channels.WithGroupTrigger(cfg.Channels.Telegram.GroupTrigger), // 群聊触发配置
+        channels.WithReasoningChannelID(cfg.Channels.Telegram.ReasoningChannelID), // 思维链路由
+    )
+    return &TelegramChannel{
+        BaseChannel: base,
+        bot:         bot,
+        config:      cfg,
+    }, nil
+}
+```
+
+**3d. Start/Stop 生命周期**
+
+```go
+// 新代码：使用 SetRunning 原子操作
+func (c *TelegramChannel) Start(ctx context.Context) error {
+    // ... 初始化 bot、webhook 等
+    c.SetRunning(true)    // 必须在就绪后调用
+    go bh.Start()
+    return nil
+}
+
+func (c *TelegramChannel) Stop(ctx context.Context) error {
+    c.SetRunning(false)   // 必须在清理前调用
+    // ... 停止 bot handler、取消 context
+    return nil
+}
+```
+
+**3e. Send 方法的错误返回**
+
+```go
+// 旧代码：返回普通 error
+func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+    if !c.running { return fmt.Errorf("not running") }
+    // ...
+    if err != nil { return err }
+}
+
+// 新代码：必须返回哨兵错误，供 Manager 判断重试策略
+func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+    if !c.IsRunning() {
+        return channels.ErrNotRunning    // ← Manager 不会重试
+    }
+    // ...
+    if err != nil {
+        // 使用 ClassifySendError 根据 HTTP 状态码包装错误
+        return channels.ClassifySendError(statusCode, err)
+        // 或手动包装：
+        // return fmt.Errorf("%w: %v", channels.ErrTemporary, err)
+        // return fmt.Errorf("%w: %v", channels.ErrRateLimit, err)
+        // return fmt.Errorf("%w: %v", channels.ErrSendFailed, err)
+    }
+    return nil
+}
+```
+
+**3f. 消息接收（Inbound）**
+
+```go
+// 旧代码：直接构造 InboundMessage 并发布
+msg := bus.InboundMessage{
+    Channel:  "telegram",
+    SenderID: senderID,
+    ChatID:   chatID,
+    Content:  content,
+    Metadata: map[string]string{
+        "peer_kind": "group",     // 路由信息埋在 metadata
+        "peer_id":   chatID,
+        "message_id": msgID,
+    },
+}
+c.bus.PublishInbound(ctx, msg)
+
+// 新代码：使用 BaseChannel.HandleMessage，传入结构化字段
+sender := bus.SenderInfo{
+    Platform:    "telegram",
+    PlatformID:  strconv.FormatInt(from.ID, 10),
+    CanonicalID: identity.BuildCanonicalID("telegram", strconv.FormatInt(from.ID, 10)),
+    Username:    from.Username,
+    DisplayName: from.FirstName,
+}
+
+peer := bus.Peer{
+    Kind: "group",    // 或 "direct"
+    ID:   chatID,
+}
+
+// HandleMessage 内部调用 IsAllowedSender 检查权限，构建 MediaScope，发布到 bus
+c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, mediaRefs, metadata, sender)
+```
+
+**3g. 添加工厂注册（必需）**
+
+为你的 channel 创建 `init.go`：
+
+```go
+// pkg/channels/telegram/init.go
+package telegram
+
+import (
+    "github.com/sipeed/picoclaw/pkg/bus"
+    "github.com/sipeed/picoclaw/pkg/channels"
+    "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+    channels.RegisterFactory("telegram", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+        return NewTelegramChannel(cfg, b)
+    })
+}
+```
+
+**3h. 在 Gateway 中导入子包**
+
+```go
+// cmd/picoclaw/internal/gateway/helpers.go
+import (
+    _ "github.com/sipeed/picoclaw/pkg/channels/telegram"   // 触发 init() 注册
+    _ "github.com/sipeed/picoclaw/pkg/channels/discord"
+    _ "github.com/sipeed/picoclaw/pkg/channels/your_new_channel"  // 新增
+)
+```
+
+#### 步骤 4：迁移 Bus 消息使用方式
+
+如果你的代码直接读取 `InboundMessage.Metadata` 中的路由字段：
+
+```go
+// 旧代码
+peerKind := msg.Metadata["peer_kind"]
+peerID   := msg.Metadata["peer_id"]
+msgID    := msg.Metadata["message_id"]
+
+// 新代码
+peerKind := msg.Peer.Kind      // 一等字段
+peerID   := msg.Peer.ID        // 一等字段
+msgID    := msg.MessageID       // 一等字段
+sender   := msg.Sender          // bus.SenderInfo 结构体
+scope    := msg.MediaScope       // 媒体生命周期作用域
+```
+
+#### 步骤 5：迁移允许列表检查
+
+```go
+// 旧代码
+if !c.isAllowed(senderID) { return }
+
+// 新代码：优先使用结构化检查
+if !c.IsAllowedSender(sender) { return }
+// 或回退到字符串检查：
+if !c.IsAllowed(senderID) { return }
+```
+
+`BaseChannel.HandleMessage` 方法内部已经处理了这个逻辑，无需在 channel 中重复检查。
+
+### 2.2 如果你有 Manager 的修改
+
+Manager 已被完全重写。你的修改需要理解新架构：
+
+| 旧 Manager 职责 | 新 Manager 职责 |
+|---|---|
+| 直接构造 channel（switch/if-else） | 通过工厂注册表查找并构造 |
+| 直接调用 channel.Send | 通过 per-channel Worker 队列 + 速率限制 + 重试 |
+| 无消息分割 | 自动根据 MaxMessageLength 分割长消息 |
+| 各 channel 自建 HTTP 服务器 | 统一共享 HTTP 服务器 |
+| 无 Typing/Placeholder 管理 | 统一 preSend 处理 Typing 停止 + Reaction 撤销 + Placeholder 编辑；入站侧 BaseChannel.HandleMessage 自动编排 Typing/Reaction/Placeholder |
+| 无 TTL 清理 | runTTLJanitor 定期清理过期 Typing/Reaction/Placeholder 条目 |
+
+### 2.3 如果你有 Agent Loop 的修改
+
+Agent Loop 的主要变化：
+
+1. **MediaStore 注入**：`agentLoop.SetMediaStore(mediaStore)` — Agent 通过 MediaStore 解析工具产生的媒体引用
+2. **ChannelManager 注入**：`agentLoop.SetChannelManager(channelManager)` — Agent 可查询 channel 状态
+3. **OutboundMediaMessage**：Agent 现在通过 `bus.PublishOutboundMedia()` 发送媒体消息，而非嵌入文本回复
+4. **extractPeer**：路由使用 `msg.Peer` 结构化字段而非 Metadata 查找
+
+---
+
+## 第三部分：新 Channel 开发指南——从零实现一个新 Channel
+
+### 3.1 最小实现清单
+
+要添加一个新的聊天平台（例如 `matrix`），你需要：
+
+1. ✅ 创建子包目录 `pkg/channels/matrix/`
+2. ✅ 创建 `init.go` — 工厂注册
+3. ✅ 创建 `matrix.go` — Channel 实现
+4. ✅ 在 Gateway helpers 中添加 blank import
+5. ✅ 在 Manager.initChannels() 中添加配置检查
+6. ✅ 在 `pkg/config/` 中添加配置结构体
+
+### 3.2 完整模板
+
+#### `pkg/channels/matrix/init.go`
+
+```go
+package matrix
+
+import (
+    "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) {
+        return NewMatrixChannel(cfg, b)
+    })
+}
+```
+
+#### `pkg/channels/matrix/matrix.go`
+
+```go
+package matrix
+
+import (
+    "context"
+    "fmt"
+
+    "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"
+)
+
+// MatrixChannel implements channels.Channel for the Matrix protocol.
+type MatrixChannel struct {
+    *channels.BaseChannel            // 必须嵌入
+    config *config.Config
+    ctx    context.Context
+    cancel context.CancelFunc
+    // ... Matrix SDK 客户端等
+}
+
+func NewMatrixChannel(cfg *config.Config, msgBus *bus.MessageBus) (*MatrixChannel, error) {
+    matrixCfg := cfg.Channels.Matrix // 假设配置中有此字段
+
+    base := channels.NewBaseChannel(
+        "matrix",                           // channel 名称（全局唯一）
+        matrixCfg,                          // 原始配置
+        msgBus,                             // 消息总线
+        matrixCfg.AllowFrom,                // 允许列表
+        channels.WithMaxMessageLength(65536), // Matrix 消息长度限制
+        channels.WithGroupTrigger(matrixCfg.GroupTrigger),
+        channels.WithReasoningChannelID(matrixCfg.ReasoningChannelID), // 思维链路由（可选）
+    )
+
+    return &MatrixChannel{
+        BaseChannel: base,
+        config:      cfg,
+    }, nil
+}
+
+// ========== 必须实现的 Channel 接口方法 ==========
+
+func (c *MatrixChannel) Start(ctx context.Context) error {
+    c.ctx, c.cancel = context.WithCancel(ctx)
+
+    // 1. 初始化 Matrix 客户端
+    // 2. 开始监听消息
+    // 3. 标记为运行中
+    c.SetRunning(true)
+
+    logger.InfoC("matrix", "Matrix channel started")
+    return nil
+}
+
+func (c *MatrixChannel) Stop(ctx context.Context) error {
+    c.SetRunning(false)
+
+    if c.cancel != nil {
+        c.cancel()
+    }
+
+    logger.InfoC("matrix", "Matrix channel stopped")
+    return nil
+}
+
+func (c *MatrixChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+    // 1. 检查运行状态
+    if !c.IsRunning() {
+        return channels.ErrNotRunning
+    }
+
+    // 2. 发送消息到 Matrix
+    err := c.sendToMatrix(ctx, msg.ChatID, msg.Content)
+    if err != nil {
+        // 3. 必须使用错误分类包装
+        //    如果你有 HTTP 状态码：
+        //    return channels.ClassifySendError(statusCode, err)
+        //    如果是网络错误：
+        //    return channels.ClassifyNetError(err)
+        //    如果需要手动分类：
+        return fmt.Errorf("%w: %v", channels.ErrTemporary, err)
+    }
+
+    return nil
+}
+
+// ========== 消息接收处理 ==========
+
+func (c *MatrixChannel) handleIncoming(roomID, senderID, displayName, content string, msgID string) {
+    // 1. 构造结构化发送者身份
+    sender := bus.SenderInfo{
+        Platform:    "matrix",
+        PlatformID:  senderID,
+        CanonicalID: identity.BuildCanonicalID("matrix", senderID),
+        Username:    senderID,
+        DisplayName: displayName,
+    }
+
+    // 2. 确定 Peer 类型（直聊 vs 群聊）
+    peer := bus.Peer{
+        Kind: "group",    // 或 "direct"
+        ID:   roomID,
+    }
+
+    // 3. 群聊过滤（如适用）
+    isGroup := peer.Kind == "group"
+    if isGroup {
+        isMentioned := false // 根据平台特性检测 @提及
+        shouldRespond, cleanContent := c.ShouldRespondInGroup(isMentioned, content)
+        if !shouldRespond {
+            return
+        }
+        content = cleanContent
+    }
+
+    // 4. 处理媒体附件（如有）
+    var mediaRefs []string
+    store := c.GetMediaStore()
+    if store != nil {
+        // 下载附件到本地 → store.Store() → 获取 ref
+        // mediaRefs = append(mediaRefs, ref)
+    }
+
+    // 5. 调用 HandleMessage 发布到 bus
+    //    HandleMessage 内部会：
+    //    - 检查 IsAllowedSender/IsAllowed
+    //    - 构建 MediaScope
+    //    - 发布 InboundMessage
+    c.HandleMessage(
+        c.ctx,
+        peer,
+        msgID,                   // 平台消息 ID
+        senderID,                // 原始发送者 ID
+        roomID,                  // 聊天/房间 ID
+        content,                 // 消息内容
+        mediaRefs,               // 媒体引用列表
+        nil,                     // 额外 metadata（通常 nil）
+        sender,                  // SenderInfo（variadic 参数）
+    )
+}
+
+// ========== 内部方法 ==========
+
+func (c *MatrixChannel) sendToMatrix(ctx context.Context, roomID, content string) error {
+    // 实际的 Matrix SDK 调用
+    return nil
+}
+```
+
+### 3.3 可选能力接口
+
+根据平台能力，你的 Channel 可以选择性实现以下接口：
+
+#### MediaSender — 发送媒体附件
+
+```go
+// 如果平台支持发送图片/文件/音频/视频
+func (c *MatrixChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+    if !c.IsRunning() {
+        return channels.ErrNotRunning
+    }
+
+    store := c.GetMediaStore()
+    if store == nil {
+        return fmt.Errorf("no media store: %w", channels.ErrSendFailed)
+    }
+
+    for _, part := range msg.Parts {
+        localPath, err := store.Resolve(part.Ref)
+        if err != nil {
+            logger.ErrorCF("matrix", "Failed to resolve media", map[string]any{
+                "ref": part.Ref, "error": err.Error(),
+            })
+            continue
+        }
+
+        // 根据 part.Type ("image"|"audio"|"video"|"file") 调用对应 API
+        switch part.Type {
+        case "image":
+            // 上传图片到 Matrix
+        default:
+            // 上传文件到 Matrix
+        }
+    }
+    return nil
+}
+```
+
+#### TypingCapable — Typing 指示器
+
+```go
+// 如果平台支持 "正在输入..." 提示
+func (c *MatrixChannel) StartTyping(ctx context.Context, chatID string) (stop func(), err error) {
+    // 调用 Matrix API 发送 typing 指示器
+    // 返回的 stop 函数必须是幂等的
+    stopped := false
+    return func() {
+        if !stopped {
+            stopped = true
+            // 调用 Matrix API 停止 typing
+        }
+    }, nil
+}
+```
+
+#### ReactionCapable — 消息反应指示器
+
+```go
+// 如果平台支持对入站消息添加 emoji 反应（如 Slack 的 👀、OneBot 的表情 289）
+func (c *MatrixChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (undo func(), err error) {
+    // 调用 Matrix API 添加反应到消息
+    // 返回的 undo 函数移除反应，必须是幂等的
+    err = c.addReaction(chatID, messageID, "eyes")
+    if err != nil {
+        return func() {}, err
+    }
+    return func() {
+        c.removeReaction(chatID, messageID, "eyes")
+    }, nil
+}
+```
+
+#### MessageEditor — 消息编辑
+
+```go
+// 如果平台支持编辑已发送的消息（用于 Placeholder 替换）
+func (c *MatrixChannel) EditMessage(ctx context.Context, chatID, messageID, content string) error {
+    // 调用 Matrix API 编辑消息
+    return nil
+}
+```
+
+#### PlaceholderCapable — 占位消息
+
+```go
+// 如果平台支持发送占位消息（如 "Thinking... 💭"），并且实现了 MessageEditor，
+// 则 Manager 的 preSend 会在出站时自动将占位消息编辑为最终回复。
+// SendPlaceholder 内部根据 PlaceholderConfig.Enabled 决定是否发送；
+// 返回 ("", nil) 表示跳过。
+func (c *MatrixChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+    cfg := c.config.Channels.Matrix.Placeholder
+    if !cfg.Enabled {
+        return "", nil
+    }
+    text := cfg.Text
+    if text == "" {
+        text = "Thinking... 💭"
+    }
+    // 调用 Matrix API 发送占位消息
+    msg, err := c.sendText(ctx, chatID, text)
+    if err != nil {
+        return "", err
+    }
+    return msg.ID, nil
+}
+```
+
+#### WebhookHandler — HTTP Webhook 接收
+
+```go
+// 如果 channel 通过 webhook 接收消息（而非长轮询/WebSocket）
+func (c *MatrixChannel) WebhookPath() string {
+    return "/webhook/matrix"   // 路径会被注册到共享 HTTP 服务器
+}
+
+func (c *MatrixChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+    // 处理 webhook 请求
+}
+```
+
+#### HealthChecker — 健康检查端点
+
+```go
+func (c *MatrixChannel) HealthPath() string {
+    return "/health/matrix"
+}
+
+func (c *MatrixChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
+    if c.IsRunning() {
+        w.WriteHeader(http.StatusOK)
+        w.Write([]byte("OK"))
+    } else {
+        w.WriteHeader(http.StatusServiceUnavailable)
+    }
+}
+```
+
+### 3.4 入站侧 Typing/Reaction/Placeholder 自动编排
+
+`BaseChannel.HandleMessage` 在发布入站消息**之前**，自动检测 channel 是否实现了 `TypingCapable`、`ReactionCapable` 和/或 `PlaceholderCapable`，并触发相应的指示器。三条管道完全独立，互不干扰：
+
+```go
+// BaseChannel.HandleMessage 内部自动执行（无需 channel 手动调用）：
+if c.owner != nil && c.placeholderRecorder != nil {
+    // 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 — 独立管道
+    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 — 独立管道
+    if pc, ok := c.owner.(PlaceholderCapable); ok {
+        if phID, err := pc.SendPlaceholder(ctx, chatID); err == nil && phID != "" {
+            c.placeholderRecorder.RecordPlaceholder(c.name, chatID, phID)
+        }
+    }
+}
+```
+
+**这意味着**：
+- 实现 `TypingCapable` 的 channel（Telegram、Discord、LINE、Pico）无需在 `handleMessage` 中手动调用 `StartTyping` + `RecordTypingStop`
+- 实现 `ReactionCapable` 的 channel（Slack、OneBot）无需在 `handleMessage` 中手动调用 `AddReaction` + `RecordTypingStop`
+- 实现 `PlaceholderCapable` 的 channel（Telegram、Discord、Pico）无需在 `handleMessage` 中手动发送占位消息并调用 `RecordPlaceholder`
+- Channel 只需实现对应接口，`HandleMessage` 会自动完成编排
+- 不实现这些接口的 channel 不受影响（类型断言会失败，跳过）
+- `PlaceholderCapable` 的 `SendPlaceholder` 方法内部根据配置的 `PlaceholderConfig.Enabled` 决定是否发送；返回 `("", nil)` 时跳过注册
+
+**Owner 注入**：Manager 在 `initChannel` 中自动调用 `SetOwner(ch)` 将具体 channel 注入 BaseChannel，无需开发者手动设置。
+
+当 Agent 处理完消息后，Manager 的 `preSend` 会自动：
+1. 调用已记录的 `stop()` 停止 Typing
+2. 调用已记录的 `undo()` 撤销 Reaction
+3. 如果有 Placeholder，且 channel 实现了 `MessageEditor`，尝试编辑 Placeholder 为最终回复（跳过 Send）
+
+### 3.5 注册配置和 Gateway 接入
+
+#### 在 `pkg/config/config.go` 中添加配置
+
+```go
+type ChannelsConfig struct {
+    // ... 现有 channels
+    Matrix  MatrixChannelConfig  `json:"matrix"`
+}
+
+type MatrixChannelConfig struct {
+    Enabled    bool     `json:"enabled"`
+    HomeServer string   `json:"home_server"`
+    Token      string   `json:"token"`
+    AllowFrom  []string `json:"allow_from"`
+    GroupTrigger GroupTriggerConfig `json:"group_trigger"`
+    Placeholder  PlaceholderConfig  `json:"placeholder"`
+    ReasoningChannelID string `json:"reasoning_channel_id"`
+}
+```
+
+#### 在 Manager.initChannels() 中添加入口
+
+```go
+// pkg/channels/manager.go 的 initChannels() 方法中
+if m.config.Channels.Matrix.Enabled && m.config.Channels.Matrix.Token != "" {
+    m.initChannel("matrix", "Matrix")
+}
+```
+
+> **注意**：如果你的 channel 有多种模式（如 WhatsApp Bridge vs Native），需要在 initChannels 中根据配置分支：
+> ```go
+> if cfg.UseNative {
+>     m.initChannel("whatsapp_native", "WhatsApp Native")
+> } else {
+>     m.initChannel("whatsapp", "WhatsApp")
+> }
+> ```
+
+#### 在 Gateway 中添加 blank import
+
+```go
+// cmd/picoclaw/internal/gateway/helpers.go
+import (
+    _ "github.com/sipeed/picoclaw/pkg/channels/matrix"
+)
+```
+
+---
+
+## 第四部分：核心子系统详解
+
+### 4.1 MessageBus
+
+**文件**：`pkg/bus/bus.go`、`pkg/bus/types.go`
+
+```go
+type MessageBus struct {
+    inbound       chan InboundMessage       // 缓冲区 = 64
+    outbound      chan OutboundMessage      // 缓冲区 = 64
+    outboundMedia chan OutboundMediaMessage  // 缓冲区 = 64
+    done          chan struct{}             // 关闭信号
+    closed        atomic.Bool              // 防止重复关闭
+}
+```
+
+**关键行为**：
+
+| 方法 | 行为 |
+|------|------|
+| `PublishInbound(ctx, msg)` | 检查 closed → 发送到 inbound channel → 阻塞/超时/关闭 |
+| `ConsumeInbound(ctx)` | 从 inbound 读取 → 阻塞/关闭/取消 |
+| `PublishOutbound(ctx, msg)` | 发送到 outbound channel |
+| `SubscribeOutbound(ctx)` | 从 outbound 读取（Manager dispatcher 调用） |
+| `PublishOutboundMedia(ctx, msg)` | 发送到 outboundMedia channel |
+| `SubscribeOutboundMedia(ctx)` | 从 outboundMedia 读取（Manager media dispatcher 调用） |
+| `Close()` | CAS 关闭 → close(done) → 排水所有 channel（**不关闭 channel 本身**，避免并发 send-on-closed panic） |
+
+**设计要点**：
+- 缓冲区从 16 增至 64，减少突发负载下的阻塞
+- `Close()` 不关闭底层 channel（只关闭 `done` 信号通道），因为可能有正在并发 `Publish` 的 goroutine
+- 排水循环确保 buffered 消息不被静默丢弃
+
+### 4.2 结构化消息类型
+
+**文件**：`pkg/bus/types.go`
+
+```go
+// 路由对等体
+type Peer struct {
+    Kind string `json:"kind"`  // "direct" | "group" | "channel" | ""
+    ID   string `json:"id"`
+}
+
+// 发送者身份信息
+type SenderInfo struct {
+    Platform    string `json:"platform,omitempty"`     // "telegram", "discord", ...
+    PlatformID  string `json:"platform_id,omitempty"`  // 平台原始 ID
+    CanonicalID string `json:"canonical_id,omitempty"` // "platform:id" 规范格式
+    Username    string `json:"username,omitempty"`
+    DisplayName string `json:"display_name,omitempty"`
+}
+
+// 入站消息
+type InboundMessage struct {
+    Channel    string            // 来源 channel 名称
+    SenderID   string            // 发送者 ID（优先使用 CanonicalID）
+    Sender     SenderInfo        // 结构化发送者信息
+    ChatID     string            // 聊天/房间 ID
+    Content    string            // 消息文本
+    Media      []string          // 媒体引用列表（media://...）
+    Peer       Peer              // 路由对等体（一等字段）
+    MessageID  string            // 平台消息 ID（一等字段）
+    MediaScope string            // 媒体生命周期作用域
+    SessionKey string            // 会话键
+    Metadata   map[string]string // 仅用于 channel 特有扩展
+}
+
+// 出站文本消息
+type OutboundMessage struct {
+    Channel string
+    ChatID  string
+    Content string
+}
+
+// 出站媒体消息
+type OutboundMediaMessage struct {
+    Channel string
+    ChatID  string
+    Parts   []MediaPart
+}
+
+// 媒体片段
+type MediaPart struct {
+    Type        string // "image" | "audio" | "video" | "file"
+    Ref         string // "media://uuid"
+    Caption     string
+    Filename    string
+    ContentType string
+}
+```
+
+### 4.3 BaseChannel
+
+**文件**：`pkg/channels/base.go`
+
+BaseChannel 是所有 channel 的共享抽象层，提供以下能力：
+
+| 方法/特性 | 说明 |
+|---|---|
+| `Name() string` | Channel 名称 |
+| `IsRunning() bool` | 原子读取运行状态 |
+| `SetRunning(bool)` | 原子设置运行状态 |
+| `MaxMessageLength() int` | 消息长度限制（rune 计数），0 = 无限制 |
+| `ReasoningChannelID() string` | 思维链路由目标 channel ID（空 = 不路由） |
+| `IsAllowed(senderID string) bool` | 旧格式允许列表检查（支持 `"id\|username"` 和 `"@username"` 格式） |
+| `IsAllowedSender(sender SenderInfo) bool` | 新格式允许列表检查（委托给 `identity.MatchAllowed`） |
+| `ShouldRespondInGroup(isMentioned, content) (bool, string)` | 统一群聊触发过滤逻辑 |
+| `HandleMessage(...)` | 统一入站消息处理：权限检查 → 构建 MediaScope → 自动触发 Typing/Reaction/Placeholder → 发布到 Bus |
+| `SetMediaStore(s) / GetMediaStore()` | Manager 注入的媒体存储 |
+| `SetPlaceholderRecorder(r) / GetPlaceholderRecorder()` | Manager 注入的占位符记录器 |
+| `SetOwner(ch) ` | Manager 注入的具体 channel 引用（用于 HandleMessage 内部的 Typing/Reaction/Placeholder 类型断言） |
+
+**功能选项**：
+
+```go
+channels.WithMaxMessageLength(4096)        // 设置平台消息长度限制
+channels.WithGroupTrigger(groupTriggerCfg) // 设置群聊触发配置
+channels.WithReasoningChannelID(id)        // 设置思维链路由目标 channel
+```
+
+### 4.4 工厂注册表
+
+**文件**：`pkg/channels/registry.go`
+
+```go
+type ChannelFactory func(cfg *config.Config, bus *bus.MessageBus) (Channel, error)
+
+func RegisterFactory(name string, f ChannelFactory)   // 子包 init() 中调用
+func getFactory(name string) (ChannelFactory, bool)    // Manager 内部调用
+```
+
+工厂注册表使用 `sync.RWMutex` 保护，在 `init()` 阶段注册（进程启动时完成）。Manager 在 `initChannel()` 中通过名字查找工厂并调用它。
+
+### 4.5 错误分类与重试
+
+**文件**：`pkg/channels/errors.go`、`pkg/channels/errutil.go`
+
+#### 哨兵错误
+
+```go
+var (
+    ErrNotRunning = errors.New("channel not running")   // 永久：不重试
+    ErrRateLimit  = errors.New("rate limited")           // 固定延迟：1s 后重试
+    ErrTemporary  = errors.New("temporary failure")      // 指数退避：500ms * 2^attempt，最大 8s
+    ErrSendFailed = errors.New("send failed")            // 永久：不重试
+)
+```
+
+#### 错误分类帮助函数
+
+```go
+// 根据 HTTP 状态码自动分类
+func ClassifySendError(statusCode int, rawErr error) error {
+    // 429 → ErrRateLimit
+    // 5xx → ErrTemporary
+    // 4xx → ErrSendFailed
+}
+
+// 网络错误统一包装为临时错误
+func ClassifyNetError(err error) error {
+    // → ErrTemporary
+}
+```
+
+#### Manager 重试策略（`sendWithRetry`）
+
+```
+最大重试次数: 3
+速率限制延迟: 1 秒
+基础退避:     500 毫秒
+最大退避:     8 秒
+
+重试逻辑:
+  ErrNotRunning → 立即失败，不重试
+  ErrSendFailed → 立即失败，不重试
+  ErrRateLimit  → 等待 1s → 重试
+  ErrTemporary  → 等待 500ms * 2^attempt（最大 8s） → 重试
+  其他未知错误  → 等待 500ms * 2^attempt（最大 8s） → 重试
+```
+
+### 4.6 Manager 编排
+
+**文件**：`pkg/channels/manager.go`
+
+#### Per-channel Worker 架构
+
+```go
+type channelWorker struct {
+    ch         Channel                      // channel 实例
+    queue      chan bus.OutboundMessage      // 出站文本队列（缓冲 16）
+    mediaQueue chan bus.OutboundMediaMessage // 出站媒体队列（缓冲 16）
+    done       chan struct{}                // 文本 worker 完成信号
+    mediaDone  chan struct{}                // 媒体 worker 完成信号
+    limiter    *rate.Limiter                // per-channel 速率限制器
+}
+```
+
+#### Per-channel 速率限制配置
+
+```go
+var channelRateConfig = map[string]float64{
+    "telegram": 20,   // 20 msg/s
+    "discord":  1,    // 1 msg/s
+    "slack":    1,    // 1 msg/s
+    "line":     10,   // 10 msg/s
+}
+// 默认: 10 msg/s
+// burst = max(1, ceil(rate/2))
+```
+
+#### 生命周期管理
+
+```
+StartAll:
+  1. 遍历已注册 channels → channel.Start(ctx)
+  2. 为每个启动成功的 channel 创建 channelWorker
+  3. 启动 goroutines:
+     - runWorker (per-channel 出站文本)
+     - runMediaWorker (per-channel 出站媒体)
+     - dispatchOutbound (从 bus 路由到 worker 队列)
+     - dispatchOutboundMedia (从 bus 路由到 media worker 队列)
+     - runTTLJanitor (每 10s 清理过期 typing/reaction/placeholder)
+  4. 启动共享 HTTP 服务器（如已配置）
+
+StopAll:
+  1. 关闭共享 HTTP 服务器（5s 超时）
+  2. 取消 dispatcher context
+  3. 关闭 text worker 队列 → 等待排水完成
+  4. 关闭 media worker 队列 → 等待排水完成
+  5. 停止每个 channel（channel.Stop）
+```
+
+#### Typing/Reaction/Placeholder 管理
+
+```go
+// Manager 实现 PlaceholderRecorder 接口
+func (m *Manager) RecordPlaceholder(channel, chatID, placeholderID string)
+func (m *Manager) RecordTypingStop(channel, chatID string, stop func())
+func (m *Manager) RecordReactionUndo(channel, chatID string, undo func())
+
+// 入站侧：BaseChannel.HandleMessage 自动编排
+// BaseChannel.HandleMessage 在 PublishInbound 之前，通过 owner 类型断言自动触发：
+//   - TypingCapable.StartTyping       → RecordTypingStop
+//   - ReactionCapable.ReactToMessage  → RecordReactionUndo
+//   - PlaceholderCapable.SendPlaceholder → RecordPlaceholder
+// 三者独立，互不干扰。Channel 无需手动调用。
+
+// 出站侧：发送前处理
+func (m *Manager) preSend(ctx, name, msg, ch) bool {
+    key := name + ":" + msg.ChatID
+    // 1. 停止 Typing（调用存储的 stop 函数）
+    // 2. 撤销 Reaction（调用存储的 undo 函数）
+    // 3. 尝试编辑 Placeholder（如果 channel 实现了 MessageEditor）
+    //    成功 → return true（跳过 Send）
+    //    失败 → return false（继续 Send）
+}
+```
+
+Manager 存储完全分离，三条管道互不干扰：
+
+```go
+Manager {
+    typingStops   sync.Map  // "channel:chatID" → typingEntry    ← 管 TypingCapable
+    reactionUndos sync.Map  // "channel:chatID" → reactionEntry  ← 管 ReactionCapable
+    placeholders  sync.Map  // "channel:chatID" → placeholderEntry
+}
+```
+
+TTL 清理：
+- Typing 停止函数：5 分钟 TTL（到期后自动调用 stop 并删除）
+- Reaction 撤销函数：5 分钟 TTL（到期后自动调用 undo 并删除）
+- Placeholder ID：10 分钟 TTL（到期后删除）
+- 清理间隔：10 秒
+
+### 4.7 消息分割
+
+**文件**：`pkg/channels/split.go`
+
+`SplitMessage(content string, maxLen int) []string`
+
+智能分割策略：
+1. 计算有效分割点 = maxLen - 10% 缓冲区（为代码块闭合留空间）
+2. 优先在换行符处分割
+3. 其次在空格/制表符处分割
+4. 检测未闭合的代码块（` ``` `）
+5. 如果代码块未闭合：
+   - 尝试扩展到 maxLen 以包含闭合围栏
+   - 如果代码块太长，注入闭合/重开围栏（`\n```\n` + header）
+   - 最后手段：在代码块开始前分割
+
+### 4.8 MediaStore
+
+**文件**：`pkg/media/store.go`
+
+```go
+type MediaStore interface {
+    Store(localPath string, meta MediaMeta, scope string) (ref string, err error)
+    Resolve(ref string) (localPath string, err error)
+    ResolveWithMeta(ref string) (localPath string, meta MediaMeta, err error)
+    ReleaseAll(scope string) error
+}
+```
+
+**FileMediaStore 实现**：
+- 纯内存映射，不复制/移动文件
+- 引用格式：`media://<uuid>`
+- Scope 格式：`channel:chatID:messageID`（由 `BuildMediaScope` 生成）
+- **两阶段操作**：
+  - Phase 1（持锁）：从 map 中收集并删除条目
+  - Phase 2（无锁）：从磁盘删除文件
+  - 目的：最小化锁争用
+- **TTL 清理**：`NewFileMediaStoreWithCleanup` → `Start()` 启动后台清理协程
+- 清理间隔和最大存活时间由配置控制
+
+### 4.9 Identity
+
+**文件**：`pkg/identity/identity.go`
+
+```go
+// 构建规范 ID
+func BuildCanonicalID(platform, platformID string) string
+// → "telegram:123456"
+
+// 解析规范 ID
+func ParseCanonicalID(canonical string) (platform, id string, ok bool)
+
+// 匹配允许列表（向后兼容）
+func MatchAllowed(sender bus.SenderInfo, allowed string) bool
+```
+
+`MatchAllowed` 支持的允许列表格式：
+| 格式 | 匹配方式 |
+|------|----------|
+| `"123456"` | 匹配 `sender.PlatformID` |
+| `"@alice"` | 匹配 `sender.Username` |
+| `"123456\|alice"` | 匹配 PlatformID 或 Username（旧格式兼容） |
+| `"telegram:123456"` | 精确匹配 `sender.CanonicalID`（新格式） |
+
+### 4.10 共享 HTTP 服务器
+
+**文件**：`pkg/channels/manager.go` 的 `SetupHTTPServer`
+
+Manager 创建单一 `http.Server`，自动发现和注册：
+- 实现 `WebhookHandler` 的 channel → 挂载到 `wh.WebhookPath()`
+- 实现 `HealthChecker` 的 channel → 挂载到 `hc.HealthPath()`
+- Health 全局端点由 `health.Server.RegisterOnMux` 注册
+
+超时配置：ReadTimeout = 30s, WriteTimeout = 30s
+
+---
+
+## 第五部分：关键设计决策与约定
+
+### 5.1 必须遵守的约定
+
+1. **错误分类是合约**：Channel 的 `Send` 方法**必须**返回哨兵错误（或包装它们）。Manager 的重试策略完全依赖 `errors.Is` 检查。如果返回未分类的错误，Manager 会按"未知错误"处理（指数退避重试）。
+
+2. **SetRunning 是生命周期信号**：`Start` 成功后**必须**调用 `c.SetRunning(true)`，`Stop` 开始时**必须**调用 `c.SetRunning(false)`。`Send` 中**必须**检查 `c.IsRunning()` 并返回 `ErrNotRunning`。
+
+3. **HandleMessage 包含权限检查**：不要在调用 `HandleMessage` 之前自行进行权限检查（除非你需要在检查前做平台特定的预处理）。`HandleMessage` 内部已经调用 `IsAllowedSender`/`IsAllowed`。
+
+4. **消息分割由 Manager 处理**：Channel 的 `Send` 方法不需要处理长消息分割。Manager 会在调用 `Send` 之前根据 `MaxMessageLength()` 自动分割。Channel 只需通过 `WithMaxMessageLength` 声明限制。
+
+5. **Typing/Reaction/Placeholder 由 BaseChannel + Manager 自动处理**：Channel 的 `Send` 方法不需要管理 Typing 停止、Reaction 撤销或 Placeholder 编辑。`BaseChannel.HandleMessage` 在入站侧自动触发 `TypingCapable`、`ReactionCapable` 和 `PlaceholderCapable`（通过 `owner` 类型断言）；Manager 的 `preSend` 在出站侧自动停止 Typing、撤销 Reaction、编辑 Placeholder。Channel 只需实现对应接口即可。
+
+6. **工厂注册在 init() 中**：每个子包必须有 `init.go` 文件调用 `channels.RegisterFactory`。Gateway 必须通过 blank import（`_ "pkg/channels/xxx"`）触发注册。
+
+### 5.2 Metadata 字段使用约定
+
+**不要再把以下信息放入 Metadata**：
+- `peer_kind` / `peer_id` → 使用 `InboundMessage.Peer`
+- `message_id` → 使用 `InboundMessage.MessageID`
+- `sender_platform` / `sender_username` → 使用 `InboundMessage.Sender`
+
+**Metadata 仅用于**：
+- Channel 特有的扩展信息（如 Telegram 的 `reply_to_message_id`）
+- 不适合放入结构化字段的临时信息
+
+### 5.3 并发安全约定
+
+- `BaseChannel.running`：使用 `atomic.Bool`，线程安全
+- `Manager.channels` / `Manager.workers`：使用 `sync.RWMutex` 保护
+- `Manager.placeholders` / `Manager.typingStops` / `Manager.reactionUndos`：使用 `sync.Map`
+- `MessageBus.closed`：使用 `atomic.Bool`
+- `FileMediaStore`：使用 `sync.RWMutex`，两阶段操作减少持锁时间
+- Channel Worker queue：Go channel，天然并发安全
+
+### 5.4 测试约定
+
+已有测试文件：
+- `pkg/channels/base_test.go` — BaseChannel 单元测试
+- `pkg/channels/manager_test.go` — Manager 单元测试
+- `pkg/channels/split_test.go` — 消息分割测试
+- `pkg/channels/errors_test.go` — 错误类型测试
+- `pkg/channels/errutil_test.go` — 错误分类测试
+
+为新 channel 添加测试时：
+```bash
+go test ./pkg/channels/matrix/ -v              # 子包测试
+go test ./pkg/channels/ -run TestSpecific -v    # 框架测试
+make test                                       # 全量测试
+```
+
+---
+
+## 附录：完整文件清单与接口速查表
+
+### A.1 框架层文件
+
+| 文件 | 职责 |
+|------|------|
+| `pkg/channels/base.go` | BaseChannel 结构体、Channel 接口、MessageLengthProvider、BaseChannelOption、HandleMessage |
+| `pkg/channels/interfaces.go` | TypingCapable、MessageEditor、ReactionCapable、PlaceholderCapable、PlaceholderRecorder 接口 |
+| `pkg/channels/media.go` | MediaSender 接口 |
+| `pkg/channels/webhook.go` | WebhookHandler、HealthChecker 接口 |
+| `pkg/channels/errors.go` | ErrNotRunning、ErrRateLimit、ErrTemporary、ErrSendFailed 哨兵 |
+| `pkg/channels/errutil.go` | ClassifySendError、ClassifyNetError 帮助函数 |
+| `pkg/channels/registry.go` | RegisterFactory、getFactory 工厂注册表 |
+| `pkg/channels/manager.go` | Manager：Worker 队列、速率限制、重试、preSend、共享 HTTP、TTL janitor |
+| `pkg/channels/split.go` | SplitMessage 长消息分割 |
+| `pkg/bus/bus.go` | MessageBus 实现 |
+| `pkg/bus/types.go` | Peer、SenderInfo、InboundMessage、OutboundMessage、OutboundMediaMessage、MediaPart |
+| `pkg/media/store.go` | MediaStore 接口、FileMediaStore 实现 |
+| `pkg/identity/identity.go` | BuildCanonicalID、ParseCanonicalID、MatchAllowed |
+
+### A.2 Channel 子包
+
+| 子包 | 注册名 | 可选接口 |
+|------|--------|----------|
+| `pkg/channels/telegram/` | `"telegram"` | TypingCapable, PlaceholderCapable, MessageEditor, MediaSender |
+| `pkg/channels/discord/` | `"discord"` | TypingCapable, PlaceholderCapable, MessageEditor, MediaSender |
+| `pkg/channels/slack/` | `"slack"` | ReactionCapable, MediaSender |
+| `pkg/channels/line/` | `"line"` | TypingCapable, MediaSender, WebhookHandler |
+| `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/qq/` | `"qq"` | — |
+| `pkg/channels/whatsapp/` | `"whatsapp"` | — (Bridge 模式) |
+| `pkg/channels/whatsapp_native/` | `"whatsapp_native"` | — (原生 whatsmeow 模式) |
+| `pkg/channels/maixcam/` | `"maixcam"` | — |
+| `pkg/channels/pico/` | `"pico"` | TypingCapable, PlaceholderCapable, MessageEditor, WebhookHandler |
+
+### A.3 接口速查表
+
+```go
+// ===== 必须实现 =====
+type Channel interface {
+    Name() string
+    Start(ctx context.Context) error
+    Stop(ctx context.Context) error
+    Send(ctx context.Context, msg bus.OutboundMessage) error
+    IsRunning() bool
+    IsAllowed(senderID string) bool
+    IsAllowedSender(sender bus.SenderInfo) bool
+    ReasoningChannelID() string
+}
+
+// ===== 可选实现 =====
+type MediaSender interface {
+    SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error
+}
+
+type TypingCapable interface {
+    StartTyping(ctx context.Context, chatID string) (stop func(), err error)
+}
+
+type ReactionCapable interface {
+    ReactToMessage(ctx context.Context, chatID, messageID string) (undo func(), err error)
+}
+
+type PlaceholderCapable interface {
+    SendPlaceholder(ctx context.Context, chatID string) (messageID string, err error)
+}
+
+type MessageEditor interface {
+    EditMessage(ctx context.Context, chatID, messageID, content string) error
+}
+
+type WebhookHandler interface {
+    WebhookPath() string
+    http.Handler
+}
+
+type HealthChecker interface {
+    HealthPath() string
+    HealthHandler(w http.ResponseWriter, r *http.Request)
+}
+
+type MessageLengthProvider interface {
+    MaxMessageLength() int
+}
+
+// ===== 由 Manager 注入 =====
+type PlaceholderRecorder interface {
+    RecordPlaceholder(channel, chatID, placeholderID string)
+    RecordTypingStop(channel, chatID string, stop func())
+    RecordReactionUndo(channel, chatID string, undo func())
+}
+```
+
+### A.4 Gateway 启动序列（完整引导流程）
+
+```go
+// 1. 创建核心组件
+msgBus     := bus.NewMessageBus()
+provider   := providers.CreateProvider(cfg)
+agentLoop  := agent.NewAgentLoop(cfg, msgBus, provider)
+
+// 2. 创建媒体存储（带 TTL 清理）
+mediaStore := media.NewFileMediaStoreWithCleanup(cleanerConfig)
+mediaStore.Start()
+
+// 3. 创建 Channel Manager（触发 initChannels → 工厂查找 → 构造 → 注入 MediaStore/PlaceholderRecorder/Owner）
+channelManager := channels.NewManager(cfg, msgBus, mediaStore)
+
+// 4. 注入引用
+agentLoop.SetChannelManager(channelManager)
+agentLoop.SetMediaStore(mediaStore)
+
+// 5. 配置共享 HTTP 服务器
+channelManager.SetupHTTPServer(addr, healthServer)
+
+// 6. 启动
+channelManager.StartAll(ctx)  // 启动 channels + workers + dispatchers + HTTP server
+go agentLoop.Run(ctx)          // 启动 Agent 消息循环
+
+// 7. 关闭（信号触发）
+cancel()                       // 取消 context
+msgBus.Close()                 // 信号关闭 + 排水
+channelManager.StopAll(shutdownCtx)  // 停止 HTTP + workers + channels
+mediaStore.Stop()              // 停止 TTL 清理
+agentLoop.Stop()               // 停止 Agent
+```
+
+### A.5 Per-channel 速率限制参考
+
+| Channel | 速率 (msg/s) | Burst |
+|---------|-------------|-------|
+| telegram | 20 | 10 |
+| discord | 1 | 1 |
+| slack | 1 | 1 |
+| line | 10 | 5 |
+| _其他_ | 10 (默认) | 5 |
+
+### A.6 已知限制和注意事项
+
+1. **媒体清理暂时禁用**：Agent loop 中的 `ReleaseAll` 调用被注释掉了（`refactor(loop): disable media cleanup to prevent premature file deletion`），因为会话边界尚未明确定义。TTL 清理仍然有效。
+
+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`。
+
+4. **Pico Protocol**：`pkg/channels/pico/` 实现了一个自定义的 PicoClaw 原生协议 channel，通过 WebSocket webhook (`/pico/ws`) 接收消息。
+
+5. **WhatsApp 有两种模式**：`"whatsapp"`（Bridge 模式，通过外部 bridge URL 通信）和 `"whatsapp_native"`（原生 whatsmeow 模式，直接连接 WhatsApp）。Manager 根据 `WhatsAppConfig.UseNative` 决定初始化哪个。
+
+6. **DingTalk 使用 Stream 模式**：DingTalk 使用 SDK 的 Stream/WebSocket 模式（非 HTTP webhook），因此不实现 `WebhookHandler`。
+
+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
diff --git a/pkg/channels/base.go b/pkg/channels/base.go
index cd6419ebb..063a66523 100644
--- a/pkg/channels/base.go
+++ b/pkg/channels/base.go
@@ -2,11 +2,44 @@ package channels
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/binary"
+	"encoding/hex"
+	"strconv"
 	"strings"
+	"sync/atomic"
+	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/identity"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 )
 
+var (
+	uniqueIDCounter uint64
+	uniqueIDPrefix  string
+)
+
+func init() {
+	// One-time read from crypto/rand for a unique prefix (single syscall).
+	var b [8]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		// fallback to time-based prefix
+		binary.BigEndian.PutUint64(b[:], uint64(time.Now().UnixNano()))
+	}
+	uniqueIDPrefix = hex.EncodeToString(b[:])
+}
+
+// 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.
+func uniqueID() string {
+	n := atomic.AddUint64(&uniqueIDCounter, 1)
+	return uniqueIDPrefix + strconv.FormatUint(n, 16)
+}
+
 type Channel interface {
 	Name() string
 	Start(ctx context.Context) error
@@ -14,32 +47,126 @@ type Channel interface {
 	Send(ctx context.Context, msg bus.OutboundMessage) error
 	IsRunning() bool
 	IsAllowed(senderID string) bool
+	IsAllowedSender(sender bus.SenderInfo) bool
+	ReasoningChannelID() string
+}
+
+// BaseChannelOption is a functional option for configuring a BaseChannel.
+type BaseChannelOption func(*BaseChannel)
+
+// WithMaxMessageLength sets the maximum message length (in runes) for a channel.
+// Messages exceeding this limit will be automatically split by the Manager.
+// A value of 0 means no limit.
+func WithMaxMessageLength(n int) BaseChannelOption {
+	return func(c *BaseChannel) { c.maxMessageLength = n }
+}
+
+// WithGroupTrigger sets the group trigger configuration for a channel.
+func WithGroupTrigger(gt config.GroupTriggerConfig) BaseChannelOption {
+	return func(c *BaseChannel) { c.groupTrigger = gt }
+}
+
+// WithReasoningChannelID sets the reasoning channel ID where thoughts should be sent.
+func WithReasoningChannelID(id string) BaseChannelOption {
+	return func(c *BaseChannel) { c.reasoningChannelID = id }
+}
+
+// MessageLengthProvider is an opt-in interface that channels implement
+// to advertise their maximum message length. The Manager uses this via
+// type assertion to decide whether to split outbound messages.
+type MessageLengthProvider interface {
+	MaxMessageLength() int
 }
 
 type BaseChannel struct {
-	config    any
-	bus       *bus.MessageBus
-	running   bool
-	name      string
-	allowList []string
+	config              any
+	bus                 *bus.MessageBus
+	running             atomic.Bool
+	name                string
+	allowList           []string
+	maxMessageLength    int
+	groupTrigger        config.GroupTriggerConfig
+	mediaStore          media.MediaStore
+	placeholderRecorder PlaceholderRecorder
+	owner               Channel // the concrete channel that embeds this BaseChannel
+	reasoningChannelID  string
 }
 
-func NewBaseChannel(name string, config any, bus *bus.MessageBus, allowList []string) *BaseChannel {
-	return &BaseChannel{
+func NewBaseChannel(
+	name string,
+	config any,
+	bus *bus.MessageBus,
+	allowList []string,
+	opts ...BaseChannelOption,
+) *BaseChannel {
+	bc := &BaseChannel{
 		config:    config,
 		bus:       bus,
 		name:      name,
 		allowList: allowList,
-		running:   false,
 	}
+	for _, opt := range opts {
+		opt(bc)
+	}
+	return bc
+}
+
+// MaxMessageLength returns the maximum message length (in runes) for this channel.
+// A value of 0 means no limit.
+func (c *BaseChannel) MaxMessageLength() int {
+	return c.maxMessageLength
+}
+
+// ShouldRespondInGroup determines whether the bot should respond in a group chat.
+// Each channel is responsible for:
+//  1. Detecting isMentioned (platform-specific)
+//  2. Stripping bot mention from content (platform-specific)
+//  3. Calling this method to get the group response decision
+//
+// Logic:
+//   - If isMentioned → always respond
+//   - If mention_only configured and not mentioned → ignore
+//   - If prefixes configured → respond if content starts with any prefix (strip it)
+//   - If prefixes configured but no match and not mentioned → ignore
+//   - Otherwise (no group_trigger configured) → respond to all (permissive default)
+func (c *BaseChannel) ShouldRespondInGroup(isMentioned bool, content string) (bool, string) {
+	gt := c.groupTrigger
+
+	// Mentioned → always respond
+	if isMentioned {
+		return true, strings.TrimSpace(content)
+	}
+
+	// mention_only → require mention
+	if gt.MentionOnly {
+		return false, content
+	}
+
+	// Prefix matching
+	if len(gt.Prefixes) > 0 {
+		for _, prefix := range gt.Prefixes {
+			if prefix != "" && strings.HasPrefix(content, prefix) {
+				return true, strings.TrimSpace(strings.TrimPrefix(content, prefix))
+			}
+		}
+		// Prefixes configured but none matched and not mentioned → ignore
+		return false, content
+	}
+
+	// No group_trigger configured → permissive (respond to all)
+	return true, strings.TrimSpace(content)
 }
 
 func (c *BaseChannel) Name() string {
 	return c.name
 }
 
+func (c *BaseChannel) ReasoningChannelID() string {
+	return c.reasoningChannelID
+}
+
 func (c *BaseChannel) IsRunning() bool {
-	return c.running
+	return c.running.Load()
 }
 
 func (c *BaseChannel) IsAllowed(senderID string) bool {
@@ -81,23 +208,130 @@ func (c *BaseChannel) IsAllowed(senderID string) bool {
 	return false
 }
 
-func (c *BaseChannel) HandleMessage(senderID, chatID, content string, media []string, metadata map[string]string) {
-	if !c.IsAllowed(senderID) {
-		return
+// IsAllowedSender checks whether a structured SenderInfo is permitted by the allow-list.
+// It delegates to identity.MatchAllowed for each entry, providing unified matching
+// across all legacy formats and the new canonical "platform:id" format.
+func (c *BaseChannel) IsAllowedSender(sender bus.SenderInfo) bool {
+	if len(c.allowList) == 0 {
+		return true
 	}
 
+	for _, allowed := range c.allowList {
+		if identity.MatchAllowed(sender, allowed) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func (c *BaseChannel) HandleMessage(
+	ctx context.Context,
+	peer bus.Peer,
+	messageID, senderID, chatID, content string,
+	media []string,
+	metadata map[string]string,
+	senderOpts ...bus.SenderInfo,
+) {
+	// Use SenderInfo-based allow check when available, else fall back to string
+	var sender bus.SenderInfo
+	if len(senderOpts) > 0 {
+		sender = senderOpts[0]
+	}
+	if sender.CanonicalID != "" || sender.PlatformID != "" {
+		if !c.IsAllowedSender(sender) {
+			return
+		}
+	} else {
+		if !c.IsAllowed(senderID) {
+			return
+		}
+	}
+
+	// Set SenderID to canonical if available, otherwise keep the raw senderID
+	resolvedSenderID := senderID
+	if sender.CanonicalID != "" {
+		resolvedSenderID = sender.CanonicalID
+	}
+
+	scope := BuildMediaScope(c.name, chatID, messageID)
+
 	msg := bus.InboundMessage{
-		Channel:  c.name,
-		SenderID: senderID,
-		ChatID:   chatID,
-		Content:  content,
-		Media:    media,
-		Metadata: metadata,
+		Channel:    c.name,
+		SenderID:   resolvedSenderID,
+		Sender:     sender,
+		ChatID:     chatID,
+		Content:    content,
+		Media:      media,
+		Peer:       peer,
+		MessageID:  messageID,
+		MediaScope: scope,
+		Metadata:   metadata,
 	}
 
-	c.bus.PublishInbound(msg)
+	// Auto-trigger typing indicator, message reaction, and placeholder before publishing.
+	// Each capability is independent — all three may fire for the same message.
+	if c.owner != nil && c.placeholderRecorder != nil {
+		// Typing — independent pipeline
+		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
+		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)
+			}
+		}
+	}
+
+	if err := c.bus.PublishInbound(ctx, msg); err != nil {
+		logger.ErrorCF("channels", "Failed to publish inbound message", map[string]any{
+			"channel": c.name,
+			"chat_id": chatID,
+			"error":   err.Error(),
+		})
+	}
 }
 
-func (c *BaseChannel) setRunning(running bool) {
-	c.running = running
+func (c *BaseChannel) SetRunning(running bool) {
+	c.running.Store(running)
+}
+
+// SetMediaStore injects a MediaStore into the channel.
+func (c *BaseChannel) SetMediaStore(s media.MediaStore) { c.mediaStore = s }
+
+// GetMediaStore returns the injected MediaStore (may be nil).
+func (c *BaseChannel) GetMediaStore() media.MediaStore { return c.mediaStore }
+
+// SetPlaceholderRecorder injects a PlaceholderRecorder into the channel.
+func (c *BaseChannel) SetPlaceholderRecorder(r PlaceholderRecorder) {
+	c.placeholderRecorder = r
+}
+
+// GetPlaceholderRecorder returns the injected PlaceholderRecorder (may be nil).
+func (c *BaseChannel) GetPlaceholderRecorder() PlaceholderRecorder {
+	return c.placeholderRecorder
+}
+
+// SetOwner injects the concrete channel that embeds this BaseChannel.
+// This allows HandleMessage to auto-trigger TypingCapable / ReactionCapable / PlaceholderCapable.
+func (c *BaseChannel) SetOwner(ch Channel) {
+	c.owner = ch
+}
+
+// BuildMediaScope constructs a scope key for media lifecycle tracking.
+func BuildMediaScope(channel, chatID, messageID string) string {
+	id := messageID
+	if id == "" {
+		id = uniqueID()
+	}
+	return channel + ":" + chatID + ":" + id
 }
diff --git a/pkg/channels/base_test.go b/pkg/channels/base_test.go
index 78c6d1d66..6132b8bf9 100644
--- a/pkg/channels/base_test.go
+++ b/pkg/channels/base_test.go
@@ -1,6 +1,11 @@
 package channels
 
-import "testing"
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
 
 func TestBaseChannelIsAllowed(t *testing.T) {
 	tests := []struct {
@@ -50,3 +55,211 @@ func TestBaseChannelIsAllowed(t *testing.T) {
 		})
 	}
 }
+
+func TestShouldRespondInGroup(t *testing.T) {
+	tests := []struct {
+		name        string
+		gt          config.GroupTriggerConfig
+		isMentioned bool
+		content     string
+		wantRespond bool
+		wantContent string
+	}{
+		{
+			name:        "no config - permissive default",
+			gt:          config.GroupTriggerConfig{},
+			isMentioned: false,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "no config - mentioned",
+			gt:          config.GroupTriggerConfig{},
+			isMentioned: true,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "mention_only - not mentioned",
+			gt:          config.GroupTriggerConfig{MentionOnly: true},
+			isMentioned: false,
+			content:     "hello world",
+			wantRespond: false,
+			wantContent: "hello world",
+		},
+		{
+			name:        "mention_only - mentioned",
+			gt:          config.GroupTriggerConfig{MentionOnly: true},
+			isMentioned: true,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "prefix match",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask"}},
+			isMentioned: false,
+			content:     "/ask hello",
+			wantRespond: true,
+			wantContent: "hello",
+		},
+		{
+			name:        "prefix no match - not mentioned",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask"}},
+			isMentioned: false,
+			content:     "hello world",
+			wantRespond: false,
+			wantContent: "hello world",
+		},
+		{
+			name:        "prefix no match - but mentioned",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask"}},
+			isMentioned: true,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "multiple prefixes - second matches",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask", "/bot"}},
+			isMentioned: false,
+			content:     "/bot help me",
+			wantRespond: true,
+			wantContent: "help me",
+		},
+		{
+			name:        "mention_only with prefixes - mentioned overrides",
+			gt:          config.GroupTriggerConfig{MentionOnly: true, Prefixes: []string{"/ask"}},
+			isMentioned: true,
+			content:     "hello",
+			wantRespond: true,
+			wantContent: "hello",
+		},
+		{
+			name:        "mention_only with prefixes - not mentioned, no prefix",
+			gt:          config.GroupTriggerConfig{MentionOnly: true, Prefixes: []string{"/ask"}},
+			isMentioned: false,
+			content:     "hello",
+			wantRespond: false,
+			wantContent: "hello",
+		},
+		{
+			name:        "empty prefix in list is skipped",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"", "/ask"}},
+			isMentioned: false,
+			content:     "/ask test",
+			wantRespond: true,
+			wantContent: "test",
+		},
+		{
+			name:        "prefix strips leading whitespace after prefix",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask "}},
+			isMentioned: false,
+			content:     "/ask hello",
+			wantRespond: true,
+			wantContent: "hello",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ch := NewBaseChannel("test", nil, nil, nil, WithGroupTrigger(tt.gt))
+			gotRespond, gotContent := ch.ShouldRespondInGroup(tt.isMentioned, tt.content)
+			if gotRespond != tt.wantRespond {
+				t.Errorf("ShouldRespondInGroup() respond = %v, want %v", gotRespond, tt.wantRespond)
+			}
+			if gotContent != tt.wantContent {
+				t.Errorf("ShouldRespondInGroup() content = %q, want %q", gotContent, tt.wantContent)
+			}
+		})
+	}
+}
+
+func TestIsAllowedSender(t *testing.T) {
+	tests := []struct {
+		name      string
+		allowList []string
+		sender    bus.SenderInfo
+		want      bool
+	}{
+		{
+			name:      "empty allowlist allows all",
+			allowList: nil,
+			sender:    bus.SenderInfo{PlatformID: "anyone"},
+			want:      true,
+		},
+		{
+			name:      "numeric ID matches PlatformID",
+			allowList: []string{"123456"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: true,
+		},
+		{
+			name:      "canonical format matches",
+			allowList: []string{"telegram:123456"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: true,
+		},
+		{
+			name:      "canonical format wrong platform",
+			allowList: []string{"discord:123456"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: false,
+		},
+		{
+			name:      "@username matches",
+			allowList: []string{"@alice"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+				Username:    "alice",
+			},
+			want: true,
+		},
+		{
+			name:      "compound id|username matches by ID",
+			allowList: []string{"123456|alice"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+				Username:    "alice",
+			},
+			want: true,
+		},
+		{
+			name:      "non matching sender denied",
+			allowList: []string{"654321"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ch := NewBaseChannel("test", nil, nil, tt.allowList)
+			if got := ch.IsAllowedSender(tt.sender); got != tt.want {
+				t.Fatalf("IsAllowedSender(%+v) = %v, want %v", tt.sender, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/pkg/channels/dingtalk.go b/pkg/channels/dingtalk/dingtalk.go
similarity index 83%
rename from pkg/channels/dingtalk.go
rename to pkg/channels/dingtalk/dingtalk.go
index 662fba3b7..8642ad362 100644
--- a/pkg/channels/dingtalk.go
+++ b/pkg/channels/dingtalk/dingtalk.go
@@ -1,7 +1,7 @@
 // PicoClaw - Ultra-lightweight personal AI agent
 // DingTalk channel implementation using Stream Mode
 
-package channels
+package dingtalk
 
 import (
 	"context"
@@ -12,7 +12,9 @@ import (
 	"github.com/open-dingtalk/dingtalk-stream-sdk-go/client"
 
 	"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"
 )
@@ -20,7 +22,7 @@ import (
 // DingTalkChannel implements the Channel interface for DingTalk (钉钉)
 // It uses WebSocket for receiving messages via stream mode and API for sending
 type DingTalkChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config       config.DingTalkConfig
 	clientID     string
 	clientSecret string
@@ -37,7 +39,11 @@ func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) (
 		return nil, fmt.Errorf("dingtalk client_id and client_secret are required")
 	}
 
-	base := NewBaseChannel("dingtalk", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("dingtalk", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(20000),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
 
 	return &DingTalkChannel{
 		BaseChannel:  base,
@@ -70,7 +76,7 @@ func (c *DingTalkChannel) Start(ctx context.Context) error {
 		return fmt.Errorf("failed to start stream client: %w", err)
 	}
 
-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("dingtalk", "DingTalk channel started (Stream Mode)")
 	return nil
 }
@@ -87,7 +93,7 @@ func (c *DingTalkChannel) Stop(ctx context.Context) error {
 		c.streamClient.Close()
 	}
 
-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("dingtalk", "DingTalk channel stopped")
 	return nil
 }
@@ -95,7 +101,7 @@ func (c *DingTalkChannel) Stop(ctx context.Context) error {
 // Send sends a message to DingTalk via the chatbot reply API
 func (c *DingTalkChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("dingtalk channel not running")
+		return channels.ErrNotRunning
 	}
 
 	// Get session webhook from storage
@@ -159,12 +165,17 @@ func (c *DingTalkChannel) onChatBotMessageReceived(
 		"session_webhook":   data.SessionWebhook,
 	}
 
+	var peer bus.Peer
 	if data.ConversationType == "1" {
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}
 	} else {
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = data.ConversationId
+		peer = bus.Peer{Kind: "group", ID: data.ConversationId}
+		// In group chats, apply unified group trigger filtering
+		respond, cleaned := c.ShouldRespondInGroup(false, content)
+		if !respond {
+			return nil, nil
+		}
+		content = cleaned
 	}
 
 	logger.DebugCF("dingtalk", "Received message", map[string]any{
@@ -173,8 +184,20 @@ func (c *DingTalkChannel) onChatBotMessageReceived(
 		"preview":     utils.Truncate(content, 50),
 	})
 
+	// Build sender info
+	sender := bus.SenderInfo{
+		Platform:    "dingtalk",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("dingtalk", senderID),
+		DisplayName: senderNick,
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return nil, nil
+	}
+
 	// Handle the message through the base channel
-	c.HandleMessage(senderID, chatID, content, nil, metadata)
+	c.HandleMessage(ctx, peer, "", senderID, chatID, content, nil, metadata, sender)
 
 	// Return nil to indicate we've handled the message asynchronously
 	// The response will be sent through the message bus
@@ -197,7 +220,7 @@ func (c *DingTalkChannel) SendDirectReply(ctx context.Context, sessionWebhook, c
 		contentBytes,
 	)
 	if err != nil {
-		return fmt.Errorf("failed to send reply: %w", err)
+		return fmt.Errorf("dingtalk send: %w", channels.ErrTemporary)
 	}
 
 	return nil
diff --git a/pkg/channels/dingtalk/init.go b/pkg/channels/dingtalk/init.go
new file mode 100644
index 000000000..5f49bce8c
--- /dev/null
+++ b/pkg/channels/dingtalk/init.go
@@ -0,0 +1,13 @@
+package dingtalk
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("dingtalk", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewDingTalkChannel(cfg.Channels.DingTalk, b)
+	})
+}
diff --git a/pkg/channels/discord.go b/pkg/channels/discord.go
deleted file mode 100644
index 20f3b267c..000000000
--- a/pkg/channels/discord.go
+++ /dev/null
@@ -1,373 +0,0 @@
-package channels
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/bwmarrin/discordgo"
-
-	"github.com/sipeed/picoclaw/pkg/bus"
-	"github.com/sipeed/picoclaw/pkg/config"
-	"github.com/sipeed/picoclaw/pkg/logger"
-	"github.com/sipeed/picoclaw/pkg/utils"
-	"github.com/sipeed/picoclaw/pkg/voice"
-)
-
-const (
-	transcriptionTimeout = 30 * time.Second
-	sendTimeout          = 10 * time.Second
-)
-
-type DiscordChannel struct {
-	*BaseChannel
-	session     *discordgo.Session
-	config      config.DiscordConfig
-	transcriber *voice.GroqTranscriber
-	ctx         context.Context
-	typingMu    sync.Mutex
-	typingStop  map[string]chan struct{} // chatID → stop signal
-	botUserID   string                   // stored for mention checking
-}
-
-func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordChannel, error) {
-	session, err := discordgo.New("Bot " + cfg.Token)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create discord session: %w", err)
-	}
-
-	base := NewBaseChannel("discord", cfg, bus, cfg.AllowFrom)
-
-	return &DiscordChannel{
-		BaseChannel: base,
-		session:     session,
-		config:      cfg,
-		transcriber: nil,
-		ctx:         context.Background(),
-		typingStop:  make(map[string]chan struct{}),
-	}, nil
-}
-
-func (c *DiscordChannel) SetTranscriber(transcriber *voice.GroqTranscriber) {
-	c.transcriber = transcriber
-}
-
-func (c *DiscordChannel) getContext() context.Context {
-	if c.ctx == nil {
-		return context.Background()
-	}
-	return c.ctx
-}
-
-func (c *DiscordChannel) Start(ctx context.Context) error {
-	logger.InfoC("discord", "Starting Discord bot")
-
-	c.ctx = ctx
-
-	// Get bot user ID before opening session to avoid race condition
-	botUser, err := c.session.User("@me")
-	if err != nil {
-		return fmt.Errorf("failed to get bot user: %w", err)
-	}
-	c.botUserID = botUser.ID
-
-	c.session.AddHandler(c.handleMessage)
-
-	if err := c.session.Open(); err != nil {
-		return fmt.Errorf("failed to open discord session: %w", err)
-	}
-
-	c.setRunning(true)
-
-	logger.InfoCF("discord", "Discord bot connected", map[string]any{
-		"username": botUser.Username,
-		"user_id":  botUser.ID,
-	})
-
-	return nil
-}
-
-func (c *DiscordChannel) Stop(ctx context.Context) error {
-	logger.InfoC("discord", "Stopping Discord bot")
-	c.setRunning(false)
-
-	// Stop all typing goroutines before closing session
-	c.typingMu.Lock()
-	for chatID, stop := range c.typingStop {
-		close(stop)
-		delete(c.typingStop, chatID)
-	}
-	c.typingMu.Unlock()
-
-	if err := c.session.Close(); err != nil {
-		return fmt.Errorf("failed to close discord session: %w", err)
-	}
-
-	return nil
-}
-
-func (c *DiscordChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
-	c.stopTyping(msg.ChatID)
-
-	if !c.IsRunning() {
-		return fmt.Errorf("discord bot not running")
-	}
-
-	channelID := msg.ChatID
-	if channelID == "" {
-		return fmt.Errorf("channel ID is empty")
-	}
-
-	runes := []rune(msg.Content)
-	if len(runes) == 0 {
-		return nil
-	}
-
-	chunks := utils.SplitMessage(msg.Content, 2000) // Split messages into chunks, Discord length limit: 2000 chars
-
-	for _, chunk := range chunks {
-		if err := c.sendChunk(ctx, channelID, chunk); err != nil {
-			return err
-		}
-	}
-
-	return nil
-}
-
-func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content 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)
-		done <- err
-	}()
-
-	select {
-	case err := <-done:
-		if err != nil {
-			return fmt.Errorf("failed to send discord message: %w", err)
-		}
-		return nil
-	case <-sendCtx.Done():
-		return fmt.Errorf("send message timeout: %w", sendCtx.Err())
-	}
-}
-
-// appendContent safely appends content to existing text
-func appendContent(content, suffix string) string {
-	if content == "" {
-		return suffix
-	}
-	return content + "\n" + suffix
-}
-
-func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.MessageCreate) {
-	if m == nil || m.Author == nil {
-		return
-	}
-
-	if m.Author.ID == s.State.User.ID {
-		return
-	}
-
-	// Check allowlist first to avoid downloading attachments and transcribing for rejected users
-	if !c.IsAllowed(m.Author.ID) {
-		logger.DebugCF("discord", "Message rejected by allowlist", map[string]any{
-			"user_id": m.Author.ID,
-		})
-		return
-	}
-
-	// If configured to only respond to mentions, check if bot is mentioned
-	// Skip this check for DMs (GuildID is empty) - DMs should always be responded to
-	if c.config.MentionOnly && m.GuildID != "" {
-		isMentioned := false
-		for _, mention := range m.Mentions {
-			if mention.ID == c.botUserID {
-				isMentioned = true
-				break
-			}
-		}
-		if !isMentioned {
-			logger.DebugCF("discord", "Message ignored - bot not mentioned", map[string]any{
-				"user_id": m.Author.ID,
-			})
-			return
-		}
-	}
-
-	senderID := m.Author.ID
-	senderName := m.Author.Username
-	if m.Author.Discriminator != "" && m.Author.Discriminator != "0" {
-		senderName += "#" + m.Author.Discriminator
-	}
-
-	content := m.Content
-	content = c.stripBotMention(content)
-	mediaPaths := make([]string, 0, len(m.Attachments))
-	localFiles := make([]string, 0, len(m.Attachments))
-
-	// Ensure temp files are cleaned up when function returns
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("discord", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
-			}
-		}
-	}()
-
-	for _, attachment := range m.Attachments {
-		isAudio := utils.IsAudioFile(attachment.Filename, attachment.ContentType)
-
-		if isAudio {
-			localPath := c.downloadAttachment(attachment.URL, attachment.Filename)
-			if localPath != "" {
-				localFiles = append(localFiles, localPath)
-
-				transcribedText := ""
-				if c.transcriber != nil && c.transcriber.IsAvailable() {
-					ctx, cancel := context.WithTimeout(c.getContext(), transcriptionTimeout)
-					result, err := c.transcriber.Transcribe(ctx, localPath)
-					cancel() // Release context resources immediately to avoid leaks in for loop
-
-					if err != nil {
-						logger.ErrorCF("discord", "Voice transcription failed", map[string]any{
-							"error": err.Error(),
-						})
-						transcribedText = fmt.Sprintf("[audio: %s (transcription failed)]", attachment.Filename)
-					} else {
-						transcribedText = fmt.Sprintf("[audio transcription: %s]", result.Text)
-						logger.DebugCF("discord", "Audio transcribed successfully", map[string]any{
-							"text": result.Text,
-						})
-					}
-				} else {
-					transcribedText = fmt.Sprintf("[audio: %s]", attachment.Filename)
-				}
-
-				content = appendContent(content, transcribedText)
-			} else {
-				logger.WarnCF("discord", "Failed to download audio attachment", map[string]any{
-					"url":      attachment.URL,
-					"filename": attachment.Filename,
-				})
-				mediaPaths = append(mediaPaths, attachment.URL)
-				content = appendContent(content, fmt.Sprintf("[attachment: %s]", attachment.URL))
-			}
-		} else {
-			mediaPaths = append(mediaPaths, attachment.URL)
-			content = appendContent(content, fmt.Sprintf("[attachment: %s]", attachment.URL))
-		}
-	}
-
-	if content == "" && len(mediaPaths) == 0 {
-		return
-	}
-
-	if content == "" {
-		content = "[media only]"
-	}
-
-	// Start typing after all early returns — guaranteed to have a matching Send()
-	c.startTyping(m.ChannelID)
-
-	logger.DebugCF("discord", "Received message", map[string]any{
-		"sender_name": senderName,
-		"sender_id":   senderID,
-		"preview":     utils.Truncate(content, 50),
-	})
-
-	peerKind := "channel"
-	peerID := m.ChannelID
-	if m.GuildID == "" {
-		peerKind = "direct"
-		peerID = senderID
-	}
-
-	metadata := map[string]string{
-		"message_id":   m.ID,
-		"user_id":      senderID,
-		"username":     m.Author.Username,
-		"display_name": senderName,
-		"guild_id":     m.GuildID,
-		"channel_id":   m.ChannelID,
-		"is_dm":        fmt.Sprintf("%t", m.GuildID == ""),
-		"peer_kind":    peerKind,
-		"peer_id":      peerID,
-	}
-
-	c.HandleMessage(senderID, m.ChannelID, content, mediaPaths, metadata)
-}
-
-// startTyping starts a continuous typing indicator loop for the given chatID.
-// It stops any existing typing loop for that chatID before starting a new one.
-func (c *DiscordChannel) startTyping(chatID string) {
-	c.typingMu.Lock()
-	// Stop existing loop for this chatID if any
-	if stop, ok := c.typingStop[chatID]; ok {
-		close(stop)
-	}
-	stop := make(chan struct{})
-	c.typingStop[chatID] = stop
-	c.typingMu.Unlock()
-
-	go func() {
-		if err := c.session.ChannelTyping(chatID); err != nil {
-			logger.DebugCF("discord", "ChannelTyping error", map[string]any{"chatID": chatID, "err": err})
-		}
-		ticker := time.NewTicker(8 * time.Second)
-		defer ticker.Stop()
-		timeout := time.After(5 * time.Minute)
-		for {
-			select {
-			case <-stop:
-				return
-			case <-timeout:
-				return
-			case <-c.ctx.Done():
-				return
-			case <-ticker.C:
-				if err := c.session.ChannelTyping(chatID); err != nil {
-					logger.DebugCF("discord", "ChannelTyping error", map[string]any{"chatID": chatID, "err": err})
-				}
-			}
-		}
-	}()
-}
-
-// stopTyping stops the typing indicator loop for the given chatID.
-func (c *DiscordChannel) stopTyping(chatID string) {
-	c.typingMu.Lock()
-	defer c.typingMu.Unlock()
-	if stop, ok := c.typingStop[chatID]; ok {
-		close(stop)
-		delete(c.typingStop, chatID)
-	}
-}
-
-func (c *DiscordChannel) downloadAttachment(url, filename string) string {
-	return utils.DownloadFile(url, filename, utils.DownloadOptions{
-		LoggerPrefix: "discord",
-	})
-}
-
-// 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 {
-	if c.botUserID == "" {
-		return text
-	}
-	// Remove both regular mention <@USER_ID> and nickname mention <@!USER_ID>
-	text = strings.ReplaceAll(text, fmt.Sprintf("<@%s>", c.botUserID), "")
-	text = strings.ReplaceAll(text, fmt.Sprintf("<@!%s>", c.botUserID), "")
-	return strings.TrimSpace(text)
-}
diff --git a/pkg/channels/discord/discord.go b/pkg/channels/discord/discord.go
new file mode 100644
index 000000000..c3bcbff8d
--- /dev/null
+++ b/pkg/channels/discord/discord.go
@@ -0,0 +1,591 @@
+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"
+	"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 (
+	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
+	config     config.DiscordConfig
+	ctx        context.Context
+	cancel     context.CancelFunc
+	typingMu   sync.Mutex
+	typingStop map[string]chan struct{} // chatID → stop signal
+	botUserID  string                   // stored for mention checking
+}
+
+func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordChannel, error) {
+	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),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
+
+	return &DiscordChannel{
+		BaseChannel: base,
+		session:     session,
+		config:      cfg,
+		ctx:         context.Background(),
+		typingStop:  make(map[string]chan struct{}),
+	}, nil
+}
+
+func (c *DiscordChannel) Start(ctx context.Context) error {
+	logger.InfoC("discord", "Starting Discord bot")
+
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
+	// Get bot user ID before opening session to avoid race condition
+	botUser, err := c.session.User("@me")
+	if err != nil {
+		return fmt.Errorf("failed to get bot user: %w", err)
+	}
+	c.botUserID = botUser.ID
+
+	c.session.AddHandler(c.handleMessage)
+
+	if err := c.session.Open(); err != nil {
+		return fmt.Errorf("failed to open discord session: %w", err)
+	}
+
+	c.SetRunning(true)
+
+	logger.InfoCF("discord", "Discord bot connected", map[string]any{
+		"username": botUser.Username,
+		"user_id":  botUser.ID,
+	})
+
+	return nil
+}
+
+func (c *DiscordChannel) Stop(ctx context.Context) error {
+	logger.InfoC("discord", "Stopping Discord bot")
+	c.SetRunning(false)
+
+	// Stop all typing goroutines before closing session
+	c.typingMu.Lock()
+	for chatID, stop := range c.typingStop {
+		close(stop)
+		delete(c.typingStop, chatID)
+	}
+	c.typingMu.Unlock()
+
+	// Cancel our context so typing goroutines using c.ctx.Done() exit
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	if err := c.session.Close(); err != nil {
+		return fmt.Errorf("failed to close discord session: %w", err)
+	}
+
+	return nil
+}
+
+func (c *DiscordChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	channelID := msg.ChatID
+	if channelID == "" {
+		return fmt.Errorf("channel ID is empty")
+	}
+
+	if len([]rune(msg.Content)) == 0 {
+		return nil
+	}
+
+	return c.sendChunk(ctx, channelID, msg.Content)
+}
+
+// SendMedia implements the channels.MediaSender interface.
+func (c *DiscordChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	channelID := msg.ChatID
+	if channelID == "" {
+		return fmt.Errorf("channel ID is empty")
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	// Collect all files into a single ChannelMessageSendComplex call
+	files := make([]*discordgo.File, 0, len(msg.Parts))
+	var caption string
+
+	for _, part := range msg.Parts {
+		localPath, err := store.Resolve(part.Ref)
+		if err != nil {
+			logger.ErrorCF("discord", "Failed to resolve media ref", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		file, err := os.Open(localPath)
+		if err != nil {
+			logger.ErrorCF("discord", "Failed to open media file", map[string]any{
+				"path":  localPath,
+				"error": err.Error(),
+			})
+			continue
+		}
+		// Note: discordgo reads from the Reader and we can't close it before send
+
+		filename := part.Filename
+		if filename == "" {
+			filename = "file"
+		}
+
+		files = append(files, &discordgo.File{
+			Name:        filename,
+			ContentType: part.ContentType,
+			Reader:      file,
+		})
+
+		if part.Caption != "" && caption == "" {
+			caption = part.Caption
+		}
+	}
+
+	if len(files) == 0 {
+		return nil
+	}
+
+	sendCtx, cancel := context.WithTimeout(ctx, sendTimeout)
+	defer cancel()
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := c.session.ChannelMessageSendComplex(channelID, &discordgo.MessageSend{
+			Content: caption,
+			Files:   files,
+		})
+		done <- err
+	}()
+
+	select {
+	case err := <-done:
+		// Close all file readers
+		for _, f := range files {
+			if closer, ok := f.Reader.(*os.File); ok {
+				closer.Close()
+			}
+		}
+		if err != nil {
+			return fmt.Errorf("discord send media: %w", channels.ErrTemporary)
+		}
+		return nil
+	case <-sendCtx.Done():
+		// Close all file readers
+		for _, f := range files {
+			if closer, ok := f.Reader.(*os.File); ok {
+				closer.Close()
+			}
+		}
+		return sendCtx.Err()
+	}
+}
+
+// EditMessage implements channels.MessageEditor.
+func (c *DiscordChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
+	_, err := c.session.ChannelMessageEdit(chatID, messageID, content)
+	return err
+}
+
+// SendPlaceholder implements channels.PlaceholderCapable.
+// It sends a placeholder message that will later be edited to the actual
+// response via EditMessage (channels.MessageEditor).
+func (c *DiscordChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	if !c.config.Placeholder.Enabled {
+		return "", nil
+	}
+
+	text := c.config.Placeholder.Text
+	if text == "" {
+		text = "Thinking... 💭"
+	}
+
+	msg, err := c.session.ChannelMessageSend(chatID, text)
+	if err != nil {
+		return "", err
+	}
+
+	return msg.ID, nil
+}
+
+func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content 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)
+		done <- err
+	}()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			return fmt.Errorf("discord send: %w", channels.ErrTemporary)
+		}
+		return nil
+	case <-sendCtx.Done():
+		return sendCtx.Err()
+	}
+}
+
+// appendContent safely appends content to existing text
+func appendContent(content, suffix string) string {
+	if content == "" {
+		return suffix
+	}
+	return content + "\n" + suffix
+}
+
+func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.MessageCreate) {
+	if m == nil || m.Author == nil {
+		return
+	}
+
+	if m.Author.ID == s.State.User.ID {
+		return
+	}
+
+	// Check allowlist first to avoid downloading attachments for rejected users
+	sender := bus.SenderInfo{
+		Platform:    "discord",
+		PlatformID:  m.Author.ID,
+		CanonicalID: identity.BuildCanonicalID("discord", m.Author.ID),
+		Username:    m.Author.Username,
+	}
+	// Build display name
+	displayName := m.Author.Username
+	if m.Author.Discriminator != "" && m.Author.Discriminator != "0" {
+		displayName += "#" + m.Author.Discriminator
+	}
+	sender.DisplayName = displayName
+
+	if !c.IsAllowedSender(sender) {
+		logger.DebugCF("discord", "Message rejected by allowlist", map[string]any{
+			"user_id": m.Author.ID,
+		})
+		return
+	}
+
+	content := m.Content
+
+	// In guild (group) channels, apply unified group trigger filtering
+	// DMs (GuildID is empty) always get a response
+	if m.GuildID != "" {
+		isMentioned := false
+		for _, mention := range m.Mentions {
+			if mention.ID == c.botUserID {
+				isMentioned = true
+				break
+			}
+		}
+		content = c.stripBotMention(content)
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+		if !respond {
+			logger.DebugCF("discord", "Group message ignored by group trigger", map[string]any{
+				"user_id": m.Author.ID,
+			})
+			return
+		}
+		content = cleaned
+	} else {
+		// DMs: just strip bot mention without filtering
+		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))
+
+	scope := channels.BuildMediaScope("discord", m.ChannelID, m.ID)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "discord",
+			}, scope)
+			if err == nil {
+				return ref
+			}
+		}
+		return localPath // fallback
+	}
+
+	for _, attachment := range m.Attachments {
+		isAudio := utils.IsAudioFile(attachment.Filename, attachment.ContentType)
+
+		if isAudio {
+			localPath := c.downloadAttachment(attachment.URL, attachment.Filename)
+			if localPath != "" {
+				mediaPaths = append(mediaPaths, storeMedia(localPath, attachment.Filename))
+				content = appendContent(content, fmt.Sprintf("[audio: %s]", attachment.Filename))
+			} else {
+				logger.WarnCF("discord", "Failed to download audio attachment", map[string]any{
+					"url":      attachment.URL,
+					"filename": attachment.Filename,
+				})
+				mediaPaths = append(mediaPaths, attachment.URL)
+				content = appendContent(content, fmt.Sprintf("[attachment: %s]", attachment.URL))
+			}
+		} else {
+			mediaPaths = append(mediaPaths, attachment.URL)
+			content = appendContent(content, fmt.Sprintf("[attachment: %s]", attachment.URL))
+		}
+	}
+
+	if content == "" && len(mediaPaths) == 0 {
+		return
+	}
+
+	if content == "" {
+		content = "[media only]"
+	}
+
+	logger.DebugCF("discord", "Received message", map[string]any{
+		"sender_name": sender.DisplayName,
+		"sender_id":   senderID,
+		"preview":     utils.Truncate(content, 50),
+	})
+
+	peerKind := "channel"
+	peerID := m.ChannelID
+	if m.GuildID == "" {
+		peerKind = "direct"
+		peerID = senderID
+	}
+
+	peer := bus.Peer{Kind: peerKind, ID: peerID}
+
+	metadata := map[string]string{
+		"user_id":      senderID,
+		"username":     m.Author.Username,
+		"display_name": sender.DisplayName,
+		"guild_id":     m.GuildID,
+		"channel_id":   m.ChannelID,
+		"is_dm":        fmt.Sprintf("%t", m.GuildID == ""),
+	}
+
+	c.HandleMessage(c.ctx, peer, m.ID, senderID, m.ChannelID, content, mediaPaths, metadata, sender)
+}
+
+// startTyping starts a continuous typing indicator loop for the given chatID.
+// It stops any existing typing loop for that chatID before starting a new one.
+func (c *DiscordChannel) startTyping(chatID string) {
+	c.typingMu.Lock()
+	// Stop existing loop for this chatID if any
+	if stop, ok := c.typingStop[chatID]; ok {
+		close(stop)
+	}
+	stop := make(chan struct{})
+	c.typingStop[chatID] = stop
+	c.typingMu.Unlock()
+
+	go func() {
+		if err := c.session.ChannelTyping(chatID); err != nil {
+			logger.DebugCF("discord", "ChannelTyping error", map[string]any{"chatID": chatID, "err": err})
+		}
+		ticker := time.NewTicker(8 * time.Second)
+		defer ticker.Stop()
+		timeout := time.After(5 * time.Minute)
+		for {
+			select {
+			case <-stop:
+				return
+			case <-timeout:
+				return
+			case <-c.ctx.Done():
+				return
+			case <-ticker.C:
+				if err := c.session.ChannelTyping(chatID); err != nil {
+					logger.DebugCF("discord", "ChannelTyping error", map[string]any{"chatID": chatID, "err": err})
+				}
+			}
+		}
+	}()
+}
+
+// stopTyping stops the typing indicator loop for the given chatID.
+func (c *DiscordChannel) stopTyping(chatID string) {
+	c.typingMu.Lock()
+	defer c.typingMu.Unlock()
+	if stop, ok := c.typingStop[chatID]; ok {
+		close(stop)
+		delete(c.typingStop, chatID)
+	}
+}
+
+// StartTyping implements channels.TypingCapable.
+// It starts a continuous typing indicator and returns an idempotent stop function.
+func (c *DiscordChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	c.startTyping(chatID)
+	return func() { c.stopTyping(chatID) }, nil
+}
+
+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 {
+	if c.botUserID == "" {
+		return text
+	}
+	// Remove both regular mention <@USER_ID> and nickname mention <@!USER_ID>
+	text = strings.ReplaceAll(text, fmt.Sprintf("<@%s>", c.botUserID), "")
+	text = strings.ReplaceAll(text, fmt.Sprintf("<@!%s>", c.botUserID), "")
+	return strings.TrimSpace(text)
+}
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/discord/init.go b/pkg/channels/discord/init.go
new file mode 100644
index 000000000..15a539804
--- /dev/null
+++ b/pkg/channels/discord/init.go
@@ -0,0 +1,13 @@
+package discord
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("discord", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewDiscordChannel(cfg.Channels.Discord, b)
+	})
+}
diff --git a/pkg/channels/errors.go b/pkg/channels/errors.go
new file mode 100644
index 000000000..09ee88b3f
--- /dev/null
+++ b/pkg/channels/errors.go
@@ -0,0 +1,21 @@
+package channels
+
+import "errors"
+
+var (
+	// ErrNotRunning indicates the channel is not running.
+	// Manager will not retry.
+	ErrNotRunning = errors.New("channel not running")
+
+	// ErrRateLimit indicates the platform returned a rate-limit response (e.g. HTTP 429).
+	// Manager will wait a fixed delay and retry.
+	ErrRateLimit = errors.New("rate limited")
+
+	// ErrTemporary indicates a transient failure (e.g. network timeout, 5xx).
+	// Manager will use exponential backoff and retry.
+	ErrTemporary = errors.New("temporary failure")
+
+	// ErrSendFailed indicates a permanent failure (e.g. invalid chat ID, 4xx non-429).
+	// Manager will not retry.
+	ErrSendFailed = errors.New("send failed")
+)
diff --git a/pkg/channels/errors_test.go b/pkg/channels/errors_test.go
new file mode 100644
index 000000000..e5592345a
--- /dev/null
+++ b/pkg/channels/errors_test.go
@@ -0,0 +1,56 @@
+package channels
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestErrorsIs(t *testing.T) {
+	wrapped := fmt.Errorf("telegram API: %w", ErrRateLimit)
+	if !errors.Is(wrapped, ErrRateLimit) {
+		t.Error("wrapped ErrRateLimit should match")
+	}
+	if errors.Is(wrapped, ErrTemporary) {
+		t.Error("wrapped ErrRateLimit should not match ErrTemporary")
+	}
+}
+
+func TestErrorsIsAllTypes(t *testing.T) {
+	sentinels := []error{ErrNotRunning, ErrRateLimit, ErrTemporary, ErrSendFailed}
+
+	for _, sentinel := range sentinels {
+		wrapped := fmt.Errorf("context: %w", sentinel)
+		if !errors.Is(wrapped, sentinel) {
+			t.Errorf("wrapped %v should match itself", sentinel)
+		}
+
+		// Verify it doesn't match other sentinel errors
+		for _, other := range sentinels {
+			if other == sentinel {
+				continue
+			}
+			if errors.Is(wrapped, other) {
+				t.Errorf("wrapped %v should not match %v", sentinel, other)
+			}
+		}
+	}
+}
+
+func TestErrorMessages(t *testing.T) {
+	tests := []struct {
+		err  error
+		want string
+	}{
+		{ErrNotRunning, "channel not running"},
+		{ErrRateLimit, "rate limited"},
+		{ErrTemporary, "temporary failure"},
+		{ErrSendFailed, "send failed"},
+	}
+
+	for _, tt := range tests {
+		if got := tt.err.Error(); got != tt.want {
+			t.Errorf("error message = %q, want %q", got, tt.want)
+		}
+	}
+}
diff --git a/pkg/channels/errutil.go b/pkg/channels/errutil.go
new file mode 100644
index 000000000..319e3c980
--- /dev/null
+++ b/pkg/channels/errutil.go
@@ -0,0 +1,30 @@
+package channels
+
+import (
+	"fmt"
+	"net/http"
+)
+
+// ClassifySendError wraps a raw error with the appropriate sentinel based on
+// an HTTP status code. Channels that perform HTTP API calls should use this
+// in their Send path.
+func ClassifySendError(statusCode int, rawErr error) error {
+	switch {
+	case statusCode == http.StatusTooManyRequests:
+		return fmt.Errorf("%w: %v", ErrRateLimit, rawErr)
+	case statusCode >= 500:
+		return fmt.Errorf("%w: %v", ErrTemporary, rawErr)
+	case statusCode >= 400:
+		return fmt.Errorf("%w: %v", ErrSendFailed, rawErr)
+	default:
+		return rawErr
+	}
+}
+
+// ClassifyNetError wraps a network/timeout error as ErrTemporary.
+func ClassifyNetError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("%w: %v", ErrTemporary, err)
+}
diff --git a/pkg/channels/errutil_test.go b/pkg/channels/errutil_test.go
new file mode 100644
index 000000000..e3d35f65b
--- /dev/null
+++ b/pkg/channels/errutil_test.go
@@ -0,0 +1,97 @@
+package channels
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestClassifySendError(t *testing.T) {
+	raw := fmt.Errorf("some API error")
+
+	tests := []struct {
+		name       string
+		statusCode int
+		wantIs     error
+		wantNil    bool
+	}{
+		{"429 -> ErrRateLimit", 429, ErrRateLimit, false},
+		{"500 -> ErrTemporary", 500, ErrTemporary, false},
+		{"502 -> ErrTemporary", 502, ErrTemporary, false},
+		{"503 -> ErrTemporary", 503, ErrTemporary, false},
+		{"400 -> ErrSendFailed", 400, ErrSendFailed, false},
+		{"403 -> ErrSendFailed", 403, ErrSendFailed, false},
+		{"404 -> ErrSendFailed", 404, ErrSendFailed, false},
+		{"200 -> raw error", 200, nil, false},
+		{"201 -> raw error", 201, nil, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ClassifySendError(tt.statusCode, raw)
+			if err == nil {
+				t.Fatal("expected non-nil error")
+			}
+			if tt.wantIs != nil {
+				if !errors.Is(err, tt.wantIs) {
+					t.Errorf("errors.Is(err, %v) = false, want true; err = %v", tt.wantIs, err)
+				}
+			} else {
+				// Should return the raw error unchanged
+				if err != raw {
+					t.Errorf("expected raw error to be returned unchanged for status %d, got %v", tt.statusCode, err)
+				}
+			}
+		})
+	}
+}
+
+func TestClassifySendErrorNoFalsePositive(t *testing.T) {
+	raw := fmt.Errorf("some error")
+
+	// 429 should NOT match ErrTemporary or ErrSendFailed
+	err := ClassifySendError(429, raw)
+	if errors.Is(err, ErrTemporary) {
+		t.Error("429 should not match ErrTemporary")
+	}
+	if errors.Is(err, ErrSendFailed) {
+		t.Error("429 should not match ErrSendFailed")
+	}
+
+	// 500 should NOT match ErrRateLimit or ErrSendFailed
+	err = ClassifySendError(500, raw)
+	if errors.Is(err, ErrRateLimit) {
+		t.Error("500 should not match ErrRateLimit")
+	}
+	if errors.Is(err, ErrSendFailed) {
+		t.Error("500 should not match ErrSendFailed")
+	}
+
+	// 400 should NOT match ErrRateLimit or ErrTemporary
+	err = ClassifySendError(400, raw)
+	if errors.Is(err, ErrRateLimit) {
+		t.Error("400 should not match ErrRateLimit")
+	}
+	if errors.Is(err, ErrTemporary) {
+		t.Error("400 should not match ErrTemporary")
+	}
+}
+
+func TestClassifyNetError(t *testing.T) {
+	t.Run("nil error returns nil", func(t *testing.T) {
+		if err := ClassifyNetError(nil); err != nil {
+			t.Errorf("expected nil, got %v", err)
+		}
+	})
+
+	t.Run("non-nil error wraps as ErrTemporary", func(t *testing.T) {
+		raw := fmt.Errorf("connection refused")
+		err := ClassifyNetError(raw)
+		if err == nil {
+			t.Fatal("expected non-nil error")
+		}
+		if !errors.Is(err, ErrTemporary) {
+			t.Errorf("errors.Is(err, ErrTemporary) = false, want true; err = %v", err)
+		}
+	})
+}
diff --git a/pkg/channels/feishu/common.go b/pkg/channels/feishu/common.go
new file mode 100644
index 000000000..fbe085b73
--- /dev/null
+++ b/pkg/channels/feishu/common.go
@@ -0,0 +1,86 @@
+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 {
+		return ""
+	}
+	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)
+}
diff --git a/pkg/channels/feishu/common_test.go b/pkg/channels/feishu/common_test.go
new file mode 100644
index 000000000..fefc9f7c1
--- /dev/null
+++ b/pkg/channels/feishu/common_test.go
@@ -0,0 +1,292 @@
+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)
+			}
+		})
+	}
+}
diff --git a/pkg/channels/feishu_32.go b/pkg/channels/feishu/feishu_32.go
similarity index 50%
rename from pkg/channels/feishu_32.go
rename to pkg/channels/feishu/feishu_32.go
index 5109b8195..f5e3aa224 100644
--- a/pkg/channels/feishu_32.go
+++ b/pkg/channels/feishu/feishu_32.go
@@ -1,20 +1,23 @@
 //go:build !amd64 && !arm64 && !riscv64 && !mips64 && !ppc64
 
-package channels
+package feishu
 
 import (
 	"context"
 	"errors"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 // FeishuChannel is a stub implementation for 32-bit architectures
 type FeishuChannel struct {
-	*BaseChannel
+	*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(
@@ -24,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
new file mode 100644
index 000000000..5dbbcf0af
--- /dev/null
+++ b/pkg/channels/feishu/feishu_64.go
@@ -0,0 +1,832 @@
+//go:build amd64 || arm64 || riscv64 || mips64 || ppc64
+
+package feishu
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/rand"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sync"
+	"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"
+
+	"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"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+type FeishuChannel struct {
+	*channels.BaseChannel
+	config   config.FeishuConfig
+	client   *lark.Client
+	wsClient *larkws.Client
+
+	botOpenID atomic.Value // stores string; populated lazily for @mention detection
+
+	mu     sync.Mutex
+	cancel context.CancelFunc
+}
+
+func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChannel, error) {
+	base := channels.NewBaseChannel("feishu", cfg, bus, cfg.AllowFrom,
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
+
+	ch := &FeishuChannel{
+		BaseChannel: base,
+		config:      cfg,
+		client:      lark.NewClient(cfg.AppID, cfg.AppSecret),
+	}
+	ch.SetOwner(ch)
+	return ch, nil
+}
+
+func (c *FeishuChannel) Start(ctx context.Context) error {
+	if c.config.AppID == "" || c.config.AppSecret == "" {
+		return fmt.Errorf("feishu app_id or app_secret is empty")
+	}
+
+	// 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
+	c.wsClient = larkws.NewClient(
+		c.config.AppID,
+		c.config.AppSecret,
+		larkws.WithEventHandler(dispatcher),
+	)
+	wsClient := c.wsClient
+	c.mu.Unlock()
+
+	c.SetRunning(true)
+	logger.InfoC("feishu", "Feishu channel started (websocket mode)")
+
+	go func() {
+		if err := wsClient.Start(runCtx); err != nil {
+			logger.ErrorCF("feishu", "Feishu websocket stopped with error", map[string]any{
+				"error": err.Error(),
+			})
+		}
+	}()
+
+	return nil
+}
+
+func (c *FeishuChannel) Stop(ctx context.Context) error {
+	c.mu.Lock()
+	if c.cancel != nil {
+		c.cancel()
+		c.cancel = nil
+	}
+	c.wsClient = nil
+	c.mu.Unlock()
+
+	c.SetRunning(false)
+	logger.InfoC("feishu", "Feishu channel stopped")
+	return nil
+}
+
+// Send sends a message using Interactive Card format for markdown rendering.
+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: %w", channels.ErrSendFailed)
+	}
+
+	// Build interactive card with markdown content
+	cardContent, err := buildMarkdownCard(msg.Content)
+	if err != nil {
+		return fmt.Errorf("feishu send: card build failed: %w", err)
+	}
+	return c.sendCard(ctx, msg.ChatID, cardContent)
+}
+
+// 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() {
+		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(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 placeholder send: %w", err)
+	}
+	if !resp.Success() {
+		return "", fmt.Errorf("feishu placeholder api error (code=%d msg=%s)", resp.Code, resp.Msg)
+	}
+
+	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() {
+		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
+	}
+
+	message := event.Event.Message
+	sender := event.Event.Sender
+
+	chatID := stringValue(message.ChatId)
+	if chatID == "" {
+		return nil
+	}
+
+	senderID := extractFeishuSenderID(sender)
+	if senderID == "" {
+		senderID = "unknown"
+	}
+
+	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)
+	}
+
+	// Append media tags to content (like Telegram does)
+	content = appendMediaTags(content, messageType, mediaRefs)
+
+	if content == "" {
+		content = "[empty message]"
+	}
+
+	metadata := map[string]string{}
+	if messageID != "" {
+		metadata["message_id"] = messageID
+	}
+	if messageType != "" {
+		metadata["message_type"] = messageType
+	}
+	chatType := stringValue(message.ChatType)
+	if chatType != "" {
+		metadata["chat_type"] = chatType
+	}
+	if sender != nil && sender.TenantKey != nil {
+		metadata["tenant_key"] = *sender.TenantKey
+	}
+
+	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(isMentioned, content)
+		if !respond {
+			return nil
+		}
+		content = cleaned
+	}
+
+	logger.InfoCF("feishu", "Feishu message received", map[string]any{
+		"sender_id":  senderID,
+		"chat_id":    chatID,
+		"message_id": messageID,
+		"preview":    utils.Truncate(content, 80),
+	})
+
+	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)
+	}
+
+	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 {
+		return fmt.Errorf("bot info api error (code=%d)", result.Code)
+	}
+	if result.Bot.OpenID == "" {
+		return fmt.Errorf("bot info: empty open_id")
+	}
+
+	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.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.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() {
+		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 := filepath.Join(os.TempDir(), "picoclaw_media")
+	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",
+	}, 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]").
+func appendMediaTags(content, messageType string, mediaRefs []string) string {
+	if len(mediaRefs) == 0 {
+		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() {
+		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
+}
+
+// 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() {
+		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() {
+		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() {
+		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() {
+		return fmt.Errorf("feishu file send api error (code=%d msg=%s)", resp.Code, resp.Msg)
+	}
+	return nil
+}
+
+func extractFeishuSenderID(sender *larkim.EventSender) string {
+	if sender == nil || sender.SenderId == nil {
+		return ""
+	}
+
+	if sender.SenderId.UserId != nil && *sender.SenderId.UserId != "" {
+		return *sender.SenderId.UserId
+	}
+	if sender.SenderId.OpenId != nil && *sender.SenderId.OpenId != "" {
+		return *sender.SenderId.OpenId
+	}
+	if sender.SenderId.UnionId != nil && *sender.SenderId.UnionId != "" {
+		return *sender.SenderId.UnionId
+	}
+
+	return ""
+}
diff --git a/pkg/channels/feishu/feishu_64_test.go b/pkg/channels/feishu/feishu_64_test.go
new file mode 100644
index 000000000..dc3eab2e7
--- /dev/null
+++ b/pkg/channels/feishu/feishu_64_test.go
@@ -0,0 +1,256 @@
+//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:        "",
+		},
+	}
+
+	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]",
+		},
+	}
+
+	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/init.go b/pkg/channels/feishu/init.go
new file mode 100644
index 000000000..7e5a62dae
--- /dev/null
+++ b/pkg/channels/feishu/init.go
@@ -0,0 +1,13 @@
+package feishu
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("feishu", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewFeishuChannel(cfg.Channels.Feishu, b)
+	})
+}
diff --git a/pkg/channels/feishu_64.go b/pkg/channels/feishu_64.go
deleted file mode 100644
index 42e74980f..000000000
--- a/pkg/channels/feishu_64.go
+++ /dev/null
@@ -1,227 +0,0 @@
-//go:build amd64 || arm64 || riscv64 || mips64 || ppc64
-
-package channels
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"sync"
-	"time"
-
-	lark "github.com/larksuite/oapi-sdk-go/v3"
-	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"
-
-	"github.com/sipeed/picoclaw/pkg/bus"
-	"github.com/sipeed/picoclaw/pkg/config"
-	"github.com/sipeed/picoclaw/pkg/logger"
-	"github.com/sipeed/picoclaw/pkg/utils"
-)
-
-type FeishuChannel struct {
-	*BaseChannel
-	config   config.FeishuConfig
-	client   *lark.Client
-	wsClient *larkws.Client
-
-	mu     sync.Mutex
-	cancel context.CancelFunc
-}
-
-func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChannel, error) {
-	base := NewBaseChannel("feishu", cfg, bus, cfg.AllowFrom)
-
-	return &FeishuChannel{
-		BaseChannel: base,
-		config:      cfg,
-		client:      lark.NewClient(cfg.AppID, cfg.AppSecret),
-	}, nil
-}
-
-func (c *FeishuChannel) Start(ctx context.Context) error {
-	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).
-		OnP2MessageReceiveV1(c.handleMessageReceive)
-
-	runCtx, cancel := context.WithCancel(ctx)
-
-	c.mu.Lock()
-	c.cancel = cancel
-	c.wsClient = larkws.NewClient(
-		c.config.AppID,
-		c.config.AppSecret,
-		larkws.WithEventHandler(dispatcher),
-	)
-	wsClient := c.wsClient
-	c.mu.Unlock()
-
-	c.setRunning(true)
-	logger.InfoC("feishu", "Feishu channel started (websocket mode)")
-
-	go func() {
-		if err := wsClient.Start(runCtx); err != nil {
-			logger.ErrorCF("feishu", "Feishu websocket stopped with error", map[string]any{
-				"error": err.Error(),
-			})
-		}
-	}()
-
-	return nil
-}
-
-func (c *FeishuChannel) Stop(ctx context.Context) error {
-	c.mu.Lock()
-	if c.cancel != nil {
-		c.cancel()
-		c.cancel = nil
-	}
-	c.wsClient = nil
-	c.mu.Unlock()
-
-	c.setRunning(false)
-	logger.InfoC("feishu", "Feishu channel stopped")
-	return nil
-}
-
-func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
-	if !c.IsRunning() {
-		return fmt.Errorf("feishu channel not running")
-	}
-
-	if msg.ChatID == "" {
-		return fmt.Errorf("chat ID is empty")
-	}
-
-	payload, err := json.Marshal(map[string]string{"text": msg.Content})
-	if err != nil {
-		return fmt.Errorf("failed to marshal feishu content: %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())).
-			Build()).
-		Build()
-
-	resp, err := c.client.Im.V1.Message.Create(ctx, req)
-	if err != nil {
-		return fmt.Errorf("failed to send feishu message: %w", err)
-	}
-
-	if !resp.Success() {
-		return fmt.Errorf("feishu api error: code=%d msg=%s", resp.Code, resp.Msg)
-	}
-
-	logger.DebugCF("feishu", "Feishu message sent", map[string]any{
-		"chat_id": msg.ChatID,
-	})
-
-	return nil
-}
-
-func (c *FeishuChannel) handleMessageReceive(_ context.Context, event *larkim.P2MessageReceiveV1) error {
-	if event == nil || event.Event == nil || event.Event.Message == nil {
-		return nil
-	}
-
-	message := event.Event.Message
-	sender := event.Event.Sender
-
-	chatID := stringValue(message.ChatId)
-	if chatID == "" {
-		return nil
-	}
-
-	senderID := extractFeishuSenderID(sender)
-	if senderID == "" {
-		senderID = "unknown"
-	}
-
-	content := extractFeishuMessageContent(message)
-	if content == "" {
-		content = "[empty message]"
-	}
-
-	metadata := map[string]string{}
-	if messageID := stringValue(message.MessageId); messageID != "" {
-		metadata["message_id"] = messageID
-	}
-	if messageType := stringValue(message.MessageType); messageType != "" {
-		metadata["message_type"] = messageType
-	}
-	if chatType := stringValue(message.ChatType); chatType != "" {
-		metadata["chat_type"] = chatType
-	}
-	if sender != nil && sender.TenantKey != nil {
-		metadata["tenant_key"] = *sender.TenantKey
-	}
-
-	chatType := stringValue(message.ChatType)
-	if chatType == "p2p" {
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
-	} else {
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = chatID
-	}
-
-	logger.InfoCF("feishu", "Feishu message received", map[string]any{
-		"sender_id": senderID,
-		"chat_id":   chatID,
-		"preview":   utils.Truncate(content, 80),
-	})
-
-	c.HandleMessage(senderID, chatID, content, nil, metadata)
-	return nil
-}
-
-func extractFeishuSenderID(sender *larkim.EventSender) string {
-	if sender == nil || sender.SenderId == nil {
-		return ""
-	}
-
-	if sender.SenderId.UserId != nil && *sender.SenderId.UserId != "" {
-		return *sender.SenderId.UserId
-	}
-	if sender.SenderId.OpenId != nil && *sender.SenderId.OpenId != "" {
-		return *sender.SenderId.OpenId
-	}
-	if sender.SenderId.UnionId != nil && *sender.SenderId.UnionId != "" {
-		return *sender.SenderId.UnionId
-	}
-
-	return ""
-}
-
-func extractFeishuMessageContent(message *larkim.EventMessage) string {
-	if message == nil || message.Content == nil || *message.Content == "" {
-		return ""
-	}
-
-	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
-}
-
-func stringValue(v *string) string {
-	if v == nil {
-		return ""
-	}
-	return *v
-}
diff --git a/pkg/channels/interfaces.go b/pkg/channels/interfaces.go
new file mode 100644
index 000000000..b3a493761
--- /dev/null
+++ b/pkg/channels/interfaces.go
@@ -0,0 +1,52 @@
+package channels
+
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/commands"
+)
+
+// TypingCapable — channels that can show a typing/thinking indicator.
+// StartTyping begins the indicator and returns a stop function.
+// The stop function MUST be idempotent and safe to call multiple times.
+type TypingCapable interface {
+	StartTyping(ctx context.Context, chatID string) (stop func(), err error)
+}
+
+// MessageEditor — channels that can edit an existing message.
+// messageID is always string; channels convert platform-specific types internally.
+type MessageEditor interface {
+	EditMessage(ctx context.Context, chatID string, messageID string, content 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.
+type ReactionCapable interface {
+	ReactToMessage(ctx context.Context, chatID, messageID string) (undo func(), err error)
+}
+
+// PlaceholderCapable — channels that can send a placeholder message
+// (e.g. "Thinking... 💭") that will later be edited to the actual response.
+// The channel MUST also implement MessageEditor for the placeholder to be useful.
+// SendPlaceholder returns the platform message ID of the placeholder so that
+// Manager.preSend can later edit it via MessageEditor.EditMessage.
+type PlaceholderCapable interface {
+	SendPlaceholder(ctx context.Context, chatID string) (messageID string, err error)
+}
+
+// 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.
+type PlaceholderRecorder interface {
+	RecordPlaceholder(channel, chatID, placeholderID string)
+	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..aca4ddd11
--- /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..28c59b540
--- /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/init.go b/pkg/channels/line/init.go
new file mode 100644
index 000000000..9265575cc
--- /dev/null
+++ b/pkg/channels/line/init.go
@@ -0,0 +1,13 @@
+package line
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("line", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewLINEChannel(cfg.Channels.LINE, b)
+	})
+}
diff --git a/pkg/channels/line.go b/pkg/channels/line/line.go
similarity index 71%
rename from pkg/channels/line.go
rename to pkg/channels/line/line.go
index 44134996f..b36350a06 100644
--- a/pkg/channels/line.go
+++ b/pkg/channels/line/line.go
@@ -1,4 +1,4 @@
-package channels
+package line
 
 import (
 	"bytes"
@@ -10,14 +10,16 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"os"
 	"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/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
@@ -41,14 +43,15 @@ type replyTokenEntry struct {
 // using the LINE Messaging API with HTTP webhook for receiving messages
 // and REST API for sending messages.
 type LINEChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config         config.LINEConfig
-	httpServer     *http.Server
-	botUserID      string   // Bot's user ID
-	botBasicID     string   // Bot's basic ID (e.g. @216ru...)
-	botDisplayName string   // Bot's display name for text-based mention detection
-	replyTokens    sync.Map // chatID -> replyTokenEntry
-	quoteTokens    sync.Map // chatID -> quoteToken (string)
+	infoClient     *http.Client // for bot info lookups (short timeout)
+	apiClient      *http.Client // for messaging API calls
+	botUserID      string       // Bot's user ID
+	botBasicID     string       // Bot's basic ID (e.g. @216ru...)
+	botDisplayName string       // Bot's display name for text-based mention detection
+	replyTokens    sync.Map     // chatID -> replyTokenEntry
+	quoteTokens    sync.Map     // chatID -> quoteToken (string)
 	ctx            context.Context
 	cancel         context.CancelFunc
 }
@@ -59,15 +62,21 @@ func NewLINEChannel(cfg config.LINEConfig, messageBus *bus.MessageBus) (*LINECha
 		return nil, fmt.Errorf("line channel_secret and channel_access_token are required")
 	}
 
-	base := NewBaseChannel("line", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("line", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(5000),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
 
 	return &LINEChannel{
 		BaseChannel: base,
 		config:      cfg,
+		infoClient:  &http.Client{Timeout: 10 * time.Second},
+		apiClient:   &http.Client{Timeout: 30 * time.Second},
 	}, nil
 }
 
-// Start launches the HTTP webhook server.
+// Start initializes the LINE channel.
 func (c *LINEChannel) Start(ctx context.Context) error {
 	logger.InfoC("line", "Starting LINE channel (Webhook Mode)")
 
@@ -86,32 +95,7 @@ func (c *LINEChannel) Start(ctx context.Context) error {
 		})
 	}
 
-	mux := http.NewServeMux()
-	path := c.config.WebhookPath
-	if path == "" {
-		path = "/webhook/line"
-	}
-	mux.HandleFunc(path, c.webhookHandler)
-
-	addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
-	c.httpServer = &http.Server{
-		Addr:    addr,
-		Handler: mux,
-	}
-
-	go func() {
-		logger.InfoCF("line", "LINE webhook server listening", map[string]any{
-			"addr": addr,
-			"path": path,
-		})
-		if err := c.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			logger.ErrorCF("line", "Webhook server error", map[string]any{
-				"error": err.Error(),
-			})
-		}
-	}()
-
-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("line", "LINE channel started (Webhook Mode)")
 	return nil
 }
@@ -124,8 +108,7 @@ func (c *LINEChannel) fetchBotInfo() error {
 	}
 	req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken)
 
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := c.infoClient.Do(req)
 	if err != nil {
 		return err
 	}
@@ -150,7 +133,7 @@ func (c *LINEChannel) fetchBotInfo() error {
 	return nil
 }
 
-// Stop gracefully shuts down the HTTP server.
+// Stop gracefully stops the LINE channel.
 func (c *LINEChannel) Stop(ctx context.Context) error {
 	logger.InfoC("line", "Stopping LINE channel")
 
@@ -158,21 +141,24 @@ func (c *LINEChannel) Stop(ctx context.Context) error {
 		c.cancel()
 	}
 
-	if c.httpServer != nil {
-		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
-		defer cancel()
-		if err := c.httpServer.Shutdown(shutdownCtx); err != nil {
-			logger.ErrorCF("line", "Webhook server shutdown error", map[string]any{
-				"error": err.Error(),
-			})
-		}
-	}
-
-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("line", "LINE channel stopped")
 	return nil
 }
 
+// WebhookPath returns the path for registering on the shared HTTP server.
+func (c *LINEChannel) WebhookPath() string {
+	if c.config.WebhookPath != "" {
+		return c.config.WebhookPath
+	}
+	return "/webhook/line"
+}
+
+// ServeHTTP implements http.Handler for the shared HTTP server.
+func (c *LINEChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	c.webhookHandler(w, r)
+}
+
 // webhookHandler handles incoming LINE webhook requests.
 func (c *LINEChannel) webhookHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
@@ -284,14 +270,6 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 		return
 	}
 
-	// In group chats, only respond when the bot is mentioned
-	if isGroup && !c.isBotMentioned(msg) {
-		logger.DebugCF("line", "Ignoring group message without mention", map[string]any{
-			"chat_id": chatID,
-		})
-		return
-	}
-
 	// Store reply token for later use
 	if event.ReplyToken != "" {
 		c.replyTokens.Store(chatID, replyTokenEntry{
@@ -307,18 +285,22 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 
 	var content string
 	var mediaPaths []string
-	localFiles := []string{}
 
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("line", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	scope := channels.BuildMediaScope("line", chatID, msg.ID)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "line",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback
+	}
 
 	switch msg.Type {
 	case "text":
@@ -330,22 +312,19 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 	case "image":
 		localPath := c.downloadContent(msg.ID, "image.jpg")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "image.jpg"))
 			content = "[image]"
 		}
 	case "audio":
 		localPath := c.downloadContent(msg.ID, "audio.m4a")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "audio.m4a"))
 			content = "[audio]"
 		}
 	case "video":
 		localPath := c.downloadContent(msg.ID, "video.mp4")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "video.mp4"))
 			content = "[video]"
 		}
 	case "file":
@@ -360,18 +339,29 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 		return
 	}
 
+	// In group chats, apply unified group trigger filtering
+	if isGroup {
+		isMentioned := c.isBotMentioned(msg)
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+		if !respond {
+			logger.DebugCF("line", "Ignoring group message by group trigger", map[string]any{
+				"chat_id": chatID,
+			})
+			return
+		}
+		content = cleaned
+	}
+
 	metadata := map[string]string{
 		"platform":    "line",
 		"source_type": event.Source.Type,
-		"message_id":  msg.ID,
 	}
 
+	var peer bus.Peer
 	if isGroup {
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = chatID
+		peer = bus.Peer{Kind: "group", ID: chatID}
 	} else {
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}
 	}
 
 	logger.DebugCF("line", "Received message", map[string]any{
@@ -382,10 +372,17 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 		"preview":      utils.Truncate(content, 50),
 	})
 
-	// Show typing/loading indicator (requires user ID, not group ID)
-	c.sendLoading(senderID)
+	sender := bus.SenderInfo{
+		Platform:    "line",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("line", senderID),
+	}
 
-	c.HandleMessage(senderID, chatID, content, mediaPaths, metadata)
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, mediaPaths, metadata, sender)
 }
 
 // isBotMentioned checks if the bot is mentioned in the message.
@@ -491,7 +488,7 @@ func (c *LINEChannel) resolveChatID(source lineSource) string {
 // using a cached reply token, then falls back to the Push API.
 func (c *LINEChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("line channel not running")
+		return channels.ErrNotRunning
 	}
 
 	// Load and consume quote token for this chat
@@ -519,6 +516,36 @@ func (c *LINEChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	return c.sendPush(ctx, msg.ChatID, msg.Content, quoteToken)
 }
 
+// SendMedia implements the channels.MediaSender interface.
+// LINE requires media to be accessible via public URL; since we only have local files,
+// we fall back to sending a text message with the filename/caption.
+// For full support, an external file hosting service would be needed.
+func (c *LINEChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	// LINE Messaging API requires publicly accessible URLs for media messages.
+	// Since we only have local file paths, send caption text as fallback.
+	for _, part := range msg.Parts {
+		caption := part.Caption
+		if caption == "" {
+			caption = fmt.Sprintf("[%s: %s]", part.Type, part.Filename)
+		}
+
+		if err := c.sendPush(ctx, msg.ChatID, caption, ""); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
 // buildTextMessage creates a text message object, optionally with quoteToken.
 func buildTextMessage(content, quoteToken string) map[string]string {
 	msg := map[string]string{
@@ -551,17 +578,58 @@ func (c *LINEChannel) sendPush(ctx context.Context, to, content, quoteToken stri
 	return c.callAPI(ctx, linePushEndpoint, payload)
 }
 
+// StartTyping implements channels.TypingCapable using LINE's loading animation.
+//
+// NOTE: The LINE loading animation API only works for 1:1 chats.
+// Group/room chat IDs (starting with "C" or "R") are detected automatically;
+// for these, a no-op stop function is returned without calling the API.
+func (c *LINEChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	if chatID == "" {
+		return func() {}, nil
+	}
+
+	// Group/room chats: LINE loading animation is 1:1 only.
+	if strings.HasPrefix(chatID, "C") || strings.HasPrefix(chatID, "R") {
+		return func() {}, nil
+	}
+
+	typingCtx, cancel := context.WithCancel(ctx)
+	var once sync.Once
+	stop := func() { once.Do(cancel) }
+
+	// Send immediately, then refresh periodically for long-running tasks.
+	if err := c.sendLoading(typingCtx, chatID); err != nil {
+		stop()
+		return stop, err
+	}
+
+	ticker := time.NewTicker(50 * time.Second)
+	go func() {
+		defer ticker.Stop()
+		for {
+			select {
+			case <-typingCtx.Done():
+				return
+			case <-ticker.C:
+				if err := c.sendLoading(typingCtx, chatID); err != nil {
+					logger.DebugCF("line", "Failed to refresh loading indicator", map[string]any{
+						"error": err.Error(),
+					})
+				}
+			}
+		}
+	}()
+
+	return stop, nil
+}
+
 // sendLoading sends a loading animation indicator to the chat.
-func (c *LINEChannel) sendLoading(chatID string) {
+func (c *LINEChannel) sendLoading(ctx context.Context, chatID string) error {
 	payload := map[string]any{
 		"chatId":         chatID,
 		"loadingSeconds": 60,
 	}
-	if err := c.callAPI(c.ctx, lineLoadingEndpoint, payload); err != nil {
-		logger.DebugCF("line", "Failed to send loading indicator", map[string]any{
-			"error": err.Error(),
-		})
-	}
+	return c.callAPI(ctx, lineLoadingEndpoint, payload)
 }
 
 // callAPI makes an authenticated POST request to the LINE API.
@@ -579,16 +647,18 @@ 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)
 
-	client := &http.Client{Timeout: 30 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := c.apiClient.Do(req)
 	if err != nil {
-		return fmt.Errorf("API request failed: %w", err)
+		return channels.ClassifyNetError(err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode != http.StatusOK {
-		respBody, _ := io.ReadAll(resp.Body)
-		return fmt.Errorf("LINE API error (status %d): %s", resp.StatusCode, string(respBody))
+		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)))
 	}
 
 	return nil
diff --git a/pkg/channels/maixcam/init.go b/pkg/channels/maixcam/init.go
new file mode 100644
index 000000000..5a269b22b
--- /dev/null
+++ b/pkg/channels/maixcam/init.go
@@ -0,0 +1,13 @@
+package maixcam
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("maixcam", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewMaixCamChannel(cfg.Channels.MaixCam, b)
+	})
+}
diff --git a/pkg/channels/maixcam.go b/pkg/channels/maixcam/maixcam.go
similarity index 78%
rename from pkg/channels/maixcam.go
rename to pkg/channels/maixcam/maixcam.go
index 34ce62b20..ff9a3ed1a 100644
--- a/pkg/channels/maixcam.go
+++ b/pkg/channels/maixcam/maixcam.go
@@ -1,4 +1,4 @@
-package channels
+package maixcam
 
 import (
 	"context"
@@ -6,16 +6,21 @@ import (
 	"fmt"
 	"net"
 	"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"
 )
 
 type MaixCamChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config     config.MaixCamConfig
 	listener   net.Listener
+	ctx        context.Context
+	cancel     context.CancelFunc
 	clients    map[net.Conn]bool
 	clientsMux sync.RWMutex
 }
@@ -28,7 +33,13 @@ type MaixCamMessage struct {
 }
 
 func NewMaixCamChannel(cfg config.MaixCamConfig, bus *bus.MessageBus) (*MaixCamChannel, error) {
-	base := NewBaseChannel("maixcam", cfg, bus, cfg.AllowFrom)
+	base := channels.NewBaseChannel(
+		"maixcam",
+		cfg,
+		bus,
+		cfg.AllowFrom,
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
 
 	return &MaixCamChannel{
 		BaseChannel: base,
@@ -40,37 +51,40 @@ func NewMaixCamChannel(cfg config.MaixCamConfig, bus *bus.MessageBus) (*MaixCamC
 func (c *MaixCamChannel) Start(ctx context.Context) error {
 	logger.InfoC("maixcam", "Starting MaixCam channel server")
 
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
 	addr := fmt.Sprintf("%s:%d", c.config.Host, c.config.Port)
 	listener, err := net.Listen("tcp", addr)
 	if err != nil {
+		c.cancel()
 		return fmt.Errorf("failed to listen on %s: %w", addr, err)
 	}
 
 	c.listener = listener
-	c.setRunning(true)
+	c.SetRunning(true)
 
 	logger.InfoCF("maixcam", "MaixCam server listening", map[string]any{
 		"host": c.config.Host,
 		"port": c.config.Port,
 	})
 
-	go c.acceptConnections(ctx)
+	go c.acceptConnections()
 
 	return nil
 }
 
-func (c *MaixCamChannel) acceptConnections(ctx context.Context) {
+func (c *MaixCamChannel) acceptConnections() {
 	logger.DebugC("maixcam", "Starting connection acceptor")
 
 	for {
 		select {
-		case <-ctx.Done():
+		case <-c.ctx.Done():
 			logger.InfoC("maixcam", "Stopping connection acceptor")
 			return
 		default:
 			conn, err := c.listener.Accept()
 			if err != nil {
-				if c.running {
+				if c.IsRunning() {
 					logger.ErrorCF("maixcam", "Failed to accept connection", map[string]any{
 						"error": err.Error(),
 					})
@@ -86,12 +100,12 @@ func (c *MaixCamChannel) acceptConnections(ctx context.Context) {
 			c.clients[conn] = true
 			c.clientsMux.Unlock()
 
-			go c.handleConnection(conn, ctx)
+			go c.handleConnection(conn)
 		}
 	}
 }
 
-func (c *MaixCamChannel) handleConnection(conn net.Conn, ctx context.Context) {
+func (c *MaixCamChannel) handleConnection(conn net.Conn) {
 	logger.DebugC("maixcam", "Handling MaixCam connection")
 
 	defer func() {
@@ -106,7 +120,7 @@ func (c *MaixCamChannel) handleConnection(conn net.Conn, ctx context.Context) {
 
 	for {
 		select {
-		case <-ctx.Done():
+		case <-c.ctx.Done():
 			return
 		default:
 			var msg MaixCamMessage
@@ -170,11 +184,29 @@ func (c *MaixCamChannel) handlePersonDetection(msg MaixCamMessage) {
 		"y":         fmt.Sprintf("%.0f", y),
 		"w":         fmt.Sprintf("%.0f", w),
 		"h":         fmt.Sprintf("%.0f", h),
-		"peer_kind": "channel",
-		"peer_id":   "default",
 	}
 
-	c.HandleMessage(senderID, chatID, content, []string{}, metadata)
+	sender := bus.SenderInfo{
+		Platform:    "maixcam",
+		PlatformID:  "maixcam",
+		CanonicalID: identity.BuildCanonicalID("maixcam", "maixcam"),
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(
+		c.ctx,
+		bus.Peer{Kind: "channel", ID: "default"},
+		"",
+		senderID,
+		chatID,
+		content,
+		[]string{},
+		metadata,
+		sender,
+	)
 }
 
 func (c *MaixCamChannel) handleStatusUpdate(msg MaixCamMessage) {
@@ -185,7 +217,12 @@ func (c *MaixCamChannel) handleStatusUpdate(msg MaixCamMessage) {
 
 func (c *MaixCamChannel) Stop(ctx context.Context) error {
 	logger.InfoC("maixcam", "Stopping MaixCam channel")
-	c.setRunning(false)
+	c.SetRunning(false)
+
+	// Cancel context first to signal goroutines to exit
+	if c.cancel != nil {
+		c.cancel()
+	}
 
 	if c.listener != nil {
 		c.listener.Close()
@@ -205,7 +242,14 @@ func (c *MaixCamChannel) Stop(ctx context.Context) error {
 
 func (c *MaixCamChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("maixcam channel not running")
+		return channels.ErrNotRunning
+	}
+
+	// Check ctx before entering write path
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
 	}
 
 	c.clientsMux.RLock()
@@ -230,13 +274,15 @@ func (c *MaixCamChannel) Send(ctx context.Context, msg bus.OutboundMessage) erro
 
 	var sendErr error
 	for conn := range c.clients {
+		_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
 		if _, err := conn.Write(data); err != nil {
 			logger.ErrorCF("maixcam", "Failed to send to client", map[string]any{
 				"client": conn.RemoteAddr().String(),
 				"error":  err.Error(),
 			})
-			sendErr = err
+			sendErr = fmt.Errorf("maixcam send: %w", channels.ErrTemporary)
 		}
+		_ = conn.SetWriteDeadline(time.Time{})
 	}
 
 	return sendErr
diff --git a/pkg/channels/manager.go b/pkg/channels/manager.go
index 75edaf49e..cdd49538f 100644
--- a/pkg/channels/manager.go
+++ b/pkg/channels/manager.go
@@ -8,32 +8,154 @@ package channels
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"math"
+	"net/http"
 	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/constants"
+	"github.com/sipeed/picoclaw/pkg/health"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 )
 
+const (
+	defaultChannelQueueSize = 16
+	defaultRateLimit        = 10 // default 10 msg/s
+	maxRetries              = 3
+	rateLimitDelay          = 1 * time.Second
+	baseBackoff             = 500 * time.Millisecond
+	maxBackoff              = 8 * time.Second
+
+	janitorInterval = 10 * time.Second
+	typingStopTTL   = 5 * time.Minute
+	placeholderTTL  = 10 * time.Minute
+)
+
+// typingEntry wraps a typing stop function with a creation timestamp for TTL eviction.
+type typingEntry struct {
+	stop      func()
+	createdAt time.Time
+}
+
+// reactionEntry wraps a reaction undo function with a creation timestamp for TTL eviction.
+type reactionEntry struct {
+	undo      func()
+	createdAt time.Time
+}
+
+// placeholderEntry wraps a placeholder ID with a creation timestamp for TTL eviction.
+type placeholderEntry struct {
+	id        string
+	createdAt time.Time
+}
+
+// channelRateConfig maps channel name to per-second rate limit.
+var channelRateConfig = map[string]float64{
+	"telegram": 20,
+	"discord":  1,
+	"slack":    1,
+	"matrix":   2,
+	"line":     10,
+	"irc":      2,
+}
+
+type channelWorker struct {
+	ch         Channel
+	queue      chan bus.OutboundMessage
+	mediaQueue chan bus.OutboundMediaMessage
+	done       chan struct{}
+	mediaDone  chan struct{}
+	limiter    *rate.Limiter
+}
+
 type Manager struct {
-	channels     map[string]Channel
-	bus          *bus.MessageBus
-	config       *config.Config
-	dispatchTask *asyncTask
-	mu           sync.RWMutex
+	channels      map[string]Channel
+	workers       map[string]*channelWorker
+	bus           *bus.MessageBus
+	config        *config.Config
+	mediaStore    media.MediaStore
+	dispatchTask  *asyncTask
+	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
 }
 
 type asyncTask struct {
 	cancel context.CancelFunc
 }
 
-func NewManager(cfg *config.Config, messageBus *bus.MessageBus) (*Manager, error) {
+// RecordPlaceholder registers a placeholder message for later editing.
+// Implements PlaceholderRecorder.
+func (m *Manager) RecordPlaceholder(channel, chatID, placeholderID string) {
+	key := channel + ":" + chatID
+	m.placeholders.Store(key, placeholderEntry{id: placeholderID, createdAt: time.Now()})
+}
+
+// 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()})
+}
+
+// RecordReactionUndo registers a reaction undo function for later invocation.
+// Implements PlaceholderRecorder.
+func (m *Manager) RecordReactionUndo(channel, chatID string, undo func()) {
+	key := channel + ":" + chatID
+	m.reactionUndos.Store(key, reactionEntry{undo: undo, createdAt: time.Now()})
+}
+
+// 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).
+func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMessage, ch Channel) bool {
+	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
+		}
+	}
+
+	// 2. Undo reaction
+	if v, loaded := m.reactionUndos.LoadAndDelete(key); loaded {
+		if entry, ok := v.(reactionEntry); ok {
+			entry.undo() // idempotent, safe
+		}
+	}
+
+	// 3. 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 {
+				if err := editor.EditMessage(ctx, msg.ChatID, entry.id, msg.Content); err == nil {
+					return true // edited successfully, skip Send
+				}
+				// edit failed → fall through to normal Send
+			}
+		}
+	}
+
+	return false
+}
+
+func NewManager(cfg *config.Config, messageBus *bus.MessageBus, store media.MediaStore) (*Manager, error) {
 	m := &Manager{
-		channels: make(map[string]Channel),
-		bus:      messageBus,
-		config:   cfg,
+		channels:   make(map[string]Channel),
+		workers:    make(map[string]*channelWorker),
+		bus:        messageBus,
+		config:     cfg,
+		mediaStore: store,
 	}
 
 	if err := m.initChannels(); err != nil {
@@ -43,163 +165,119 @@ func NewManager(cfg *config.Config, messageBus *bus.MessageBus) (*Manager, error
 	return m, 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)
+	if !ok {
+		logger.WarnCF("channels", "Factory not registered", map[string]any{
+			"channel": displayName,
+		})
+		return
+	}
+	logger.DebugCF("channels", "Attempting to initialize channel", map[string]any{
+		"channel": displayName,
+	})
+	ch, err := f(m.config, m.bus)
+	if err != nil {
+		logger.ErrorCF("channels", "Failed to initialize channel", map[string]any{
+			"channel": displayName,
+			"error":   err.Error(),
+		})
+	} else {
+		// Inject MediaStore if channel supports it
+		if m.mediaStore != nil {
+			if setter, ok := ch.(interface{ SetMediaStore(s media.MediaStore) }); ok {
+				setter.SetMediaStore(m.mediaStore)
+			}
+		}
+		// Inject PlaceholderRecorder if channel supports it
+		if setter, ok := ch.(interface{ SetPlaceholderRecorder(r PlaceholderRecorder) }); ok {
+			setter.SetPlaceholderRecorder(m)
+		}
+		// Inject owner reference so BaseChannel.HandleMessage can auto-trigger typing/reaction
+		if setter, ok := ch.(interface{ SetOwner(ch Channel) }); ok {
+			setter.SetOwner(ch)
+		}
+		m.channels[name] = ch
+		logger.InfoCF("channels", "Channel enabled successfully", map[string]any{
+			"channel": displayName,
+		})
+	}
+}
+
 func (m *Manager) initChannels() error {
 	logger.InfoC("channels", "Initializing channel manager")
 
 	if m.config.Channels.Telegram.Enabled && m.config.Channels.Telegram.Token != "" {
-		logger.DebugC("channels", "Attempting to initialize Telegram channel")
-		telegram, err := NewTelegramChannel(m.config, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Telegram channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["telegram"] = telegram
-			logger.InfoC("channels", "Telegram channel enabled successfully")
-		}
+		m.initChannel("telegram", "Telegram")
 	}
 
-	if m.config.Channels.WhatsApp.Enabled && m.config.Channels.WhatsApp.BridgeURL != "" {
-		logger.DebugC("channels", "Attempting to initialize WhatsApp channel")
-		whatsapp, err := NewWhatsAppChannel(m.config.Channels.WhatsApp, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize WhatsApp channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["whatsapp"] = whatsapp
-			logger.InfoC("channels", "WhatsApp channel enabled successfully")
+	if m.config.Channels.WhatsApp.Enabled {
+		waCfg := m.config.Channels.WhatsApp
+		if waCfg.UseNative {
+			m.initChannel("whatsapp_native", "WhatsApp Native")
+		} else if waCfg.BridgeURL != "" {
+			m.initChannel("whatsapp", "WhatsApp")
 		}
 	}
 
 	if m.config.Channels.Feishu.Enabled {
-		logger.DebugC("channels", "Attempting to initialize Feishu channel")
-		feishu, err := NewFeishuChannel(m.config.Channels.Feishu, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Feishu channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["feishu"] = feishu
-			logger.InfoC("channels", "Feishu channel enabled successfully")
-		}
+		m.initChannel("feishu", "Feishu")
 	}
 
 	if m.config.Channels.Discord.Enabled && m.config.Channels.Discord.Token != "" {
-		logger.DebugC("channels", "Attempting to initialize Discord channel")
-		discord, err := NewDiscordChannel(m.config.Channels.Discord, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Discord channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["discord"] = discord
-			logger.InfoC("channels", "Discord channel enabled successfully")
-		}
+		m.initChannel("discord", "Discord")
 	}
 
 	if m.config.Channels.MaixCam.Enabled {
-		logger.DebugC("channels", "Attempting to initialize MaixCam channel")
-		maixcam, err := NewMaixCamChannel(m.config.Channels.MaixCam, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize MaixCam channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["maixcam"] = maixcam
-			logger.InfoC("channels", "MaixCam channel enabled successfully")
-		}
+		m.initChannel("maixcam", "MaixCam")
 	}
 
 	if m.config.Channels.QQ.Enabled {
-		logger.DebugC("channels", "Attempting to initialize QQ channel")
-		qq, err := NewQQChannel(m.config.Channels.QQ, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize QQ channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["qq"] = qq
-			logger.InfoC("channels", "QQ channel enabled successfully")
-		}
+		m.initChannel("qq", "QQ")
 	}
 
 	if m.config.Channels.DingTalk.Enabled && m.config.Channels.DingTalk.ClientID != "" {
-		logger.DebugC("channels", "Attempting to initialize DingTalk channel")
-		dingtalk, err := NewDingTalkChannel(m.config.Channels.DingTalk, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize DingTalk channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["dingtalk"] = dingtalk
-			logger.InfoC("channels", "DingTalk channel enabled successfully")
-		}
+		m.initChannel("dingtalk", "DingTalk")
 	}
 
 	if m.config.Channels.Slack.Enabled && m.config.Channels.Slack.BotToken != "" {
-		logger.DebugC("channels", "Attempting to initialize Slack channel")
-		slackCh, err := NewSlackChannel(m.config.Channels.Slack, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Slack channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["slack"] = slackCh
-			logger.InfoC("channels", "Slack channel enabled successfully")
-		}
+		m.initChannel("slack", "Slack")
+	}
+
+	if m.config.Channels.Matrix.Enabled &&
+		m.config.Channels.Matrix.Homeserver != "" &&
+		m.config.Channels.Matrix.UserID != "" &&
+		m.config.Channels.Matrix.AccessToken != "" {
+		m.initChannel("matrix", "Matrix")
 	}
 
 	if m.config.Channels.LINE.Enabled && m.config.Channels.LINE.ChannelAccessToken != "" {
-		logger.DebugC("channels", "Attempting to initialize LINE channel")
-		line, err := NewLINEChannel(m.config.Channels.LINE, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize LINE channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["line"] = line
-			logger.InfoC("channels", "LINE channel enabled successfully")
-		}
+		m.initChannel("line", "LINE")
 	}
 
 	if m.config.Channels.OneBot.Enabled && m.config.Channels.OneBot.WSUrl != "" {
-		logger.DebugC("channels", "Attempting to initialize OneBot channel")
-		onebot, err := NewOneBotChannel(m.config.Channels.OneBot, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize OneBot channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["onebot"] = onebot
-			logger.InfoC("channels", "OneBot channel enabled successfully")
-		}
+		m.initChannel("onebot", "OneBot")
 	}
 
 	if m.config.Channels.WeCom.Enabled && m.config.Channels.WeCom.Token != "" {
-		logger.DebugC("channels", "Attempting to initialize WeCom channel")
-		wecom, err := NewWeComBotChannel(m.config.Channels.WeCom, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize WeCom channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["wecom"] = wecom
-			logger.InfoC("channels", "WeCom channel enabled successfully")
-		}
+		m.initChannel("wecom", "WeCom")
+	}
+
+	if m.config.Channels.WeComAIBot.Enabled && m.config.Channels.WeComAIBot.Token != "" {
+		m.initChannel("wecom_aibot", "WeCom AI Bot")
 	}
 
 	if m.config.Channels.WeComApp.Enabled && m.config.Channels.WeComApp.CorpID != "" {
-		logger.DebugC("channels", "Attempting to initialize WeCom App channel")
-		wecomApp, err := NewWeComAppChannel(m.config.Channels.WeComApp, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize WeCom App channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["wecom_app"] = wecomApp
-			logger.InfoC("channels", "WeCom App channel enabled successfully")
-		}
+		m.initChannel("wecom_app", "WeCom App")
+	}
+
+	if m.config.Channels.Pico.Enabled && m.config.Channels.Pico.Token != "" {
+		m.initChannel("pico", "Pico")
+	}
+
+	if m.config.Channels.IRC.Enabled && m.config.Channels.IRC.Server != "" {
+		m.initChannel("irc", "IRC")
 	}
 
 	logger.InfoCF("channels", "Channel initialization completed", map[string]any{
@@ -209,13 +287,50 @@ func (m *Manager) initChannels() error {
 	return nil
 }
 
+// SetupHTTPServer creates a shared HTTP server with the given listen address.
+// It registers health endpoints from the health server and discovers channels
+// that implement WebhookHandler and/or HealthChecker to register their handlers.
+func (m *Manager) SetupHTTPServer(addr string, healthServer *health.Server) {
+	m.mux = http.NewServeMux()
+
+	// Register health endpoints
+	if healthServer != nil {
+		healthServer.RegisterOnMux(m.mux)
+	}
+
+	// Discover and register webhook handlers and health checkers
+	for name, ch := range m.channels {
+		if wh, ok := ch.(WebhookHandler); ok {
+			m.mux.Handle(wh.WebhookPath(), wh)
+			logger.InfoCF("channels", "Webhook handler registered", map[string]any{
+				"channel": name,
+				"path":    wh.WebhookPath(),
+			})
+		}
+		if hc, ok := ch.(HealthChecker); ok {
+			m.mux.HandleFunc(hc.HealthPath(), hc.HealthHandler)
+			logger.InfoCF("channels", "Health endpoint registered", map[string]any{
+				"channel": name,
+				"path":    hc.HealthPath(),
+			})
+		}
+	}
+
+	m.httpServer = &http.Server{
+		Addr:         addr,
+		Handler:      m.mux,
+		ReadTimeout:  30 * time.Second,
+		WriteTimeout: 30 * time.Second,
+	}
+}
+
 func (m *Manager) StartAll(ctx context.Context) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
 	if len(m.channels) == 0 {
 		logger.WarnC("channels", "No channels enabled")
-		return nil
+		return errors.New("no channels enabled")
 	}
 
 	logger.InfoC("channels", "Starting all channels")
@@ -223,8 +338,6 @@ func (m *Manager) StartAll(ctx context.Context) error {
 	dispatchCtx, cancel := context.WithCancel(ctx)
 	m.dispatchTask = &asyncTask{cancel: cancel}
 
-	go m.dispatchOutbound(dispatchCtx)
-
 	for name, channel := range m.channels {
 		logger.InfoCF("channels", "Starting channel", map[string]any{
 			"channel": name,
@@ -234,7 +347,34 @@ func (m *Manager) StartAll(ctx context.Context) error {
 				"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)
+	}
+
+	// Start the dispatcher that reads from the bus and routes to workers
+	go m.dispatchOutbound(dispatchCtx)
+	go m.dispatchOutboundMedia(dispatchCtx)
+
+	// Start the TTL janitor that cleans up stale typing/placeholder entries
+	go m.runTTLJanitor(dispatchCtx)
+
+	// Start shared HTTP server if configured
+	if m.httpServer != nil {
+		go func() {
+			logger.InfoCF("channels", "Shared HTTP server listening", map[string]any{
+				"addr": m.httpServer.Addr,
+			})
+			if err := m.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+				logger.ErrorCF("channels", "Shared HTTP server error", map[string]any{
+					"error": err.Error(),
+				})
+			}
+		}()
 	}
 
 	logger.InfoC("channels", "All channels started")
@@ -247,11 +387,48 @@ func (m *Manager) StopAll(ctx context.Context) error {
 
 	logger.InfoC("channels", "Stopping all channels")
 
+	// Shutdown shared HTTP server first
+	if m.httpServer != nil {
+		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		defer cancel()
+		if err := m.httpServer.Shutdown(shutdownCtx); err != nil {
+			logger.ErrorCF("channels", "Shared HTTP server shutdown error", map[string]any{
+				"error": err.Error(),
+			})
+		}
+		m.httpServer = nil
+	}
+
+	// Cancel dispatcher
 	if m.dispatchTask != nil {
 		m.dispatchTask.cancel()
 		m.dispatchTask = nil
 	}
 
+	// Close all worker queues and wait for them to drain
+	for _, w := range m.workers {
+		if w != nil {
+			close(w.queue)
+		}
+	}
+	for _, w := range m.workers {
+		if w != nil {
+			<-w.done
+		}
+	}
+	// Close all media worker queues and wait for them to drain
+	for _, w := range m.workers {
+		if w != nil {
+			close(w.mediaQueue)
+		}
+	}
+	for _, w := range m.workers {
+		if w != nil {
+			<-w.mediaDone
+		}
+	}
+
+	// Stop all channels
 	for name, channel := range m.channels {
 		logger.InfoCF("channels", "Stopping channel", map[string]any{
 			"channel": name,
@@ -268,42 +445,318 @@ func (m *Manager) StopAll(ctx context.Context) error {
 	return nil
 }
 
+// newChannelWorker creates a channelWorker with a rate limiter configured
+// for the given channel name.
+func newChannelWorker(name string, ch Channel) *channelWorker {
+	rateVal := float64(defaultRateLimit)
+	if r, ok := channelRateConfig[name]; ok {
+		rateVal = r
+	}
+	burst := int(math.Max(1, math.Ceil(rateVal/2)))
+
+	return &channelWorker{
+		ch:         ch,
+		queue:      make(chan bus.OutboundMessage, defaultChannelQueueSize),
+		mediaQueue: make(chan bus.OutboundMediaMessage, defaultChannelQueueSize),
+		done:       make(chan struct{}),
+		mediaDone:  make(chan struct{}),
+		limiter:    rate.NewLimiter(rate.Limit(rateVal), burst),
+	}
+}
+
+// runWorker processes outbound messages for a single channel, splitting
+// messages that exceed the channel's maximum message length.
+func (m *Manager) runWorker(ctx context.Context, name string, w *channelWorker) {
+	defer close(w.done)
+	for {
+		select {
+		case msg, ok := <-w.queue:
+			if !ok {
+				return
+			}
+			maxLen := 0
+			if mlp, ok := w.ch.(MessageLengthProvider); ok {
+				maxLen = mlp.MaxMessageLength()
+			}
+			if maxLen > 0 && len([]rune(msg.Content)) > maxLen {
+				chunks := SplitMessage(msg.Content, maxLen)
+				for _, chunk := range chunks {
+					chunkMsg := msg
+					chunkMsg.Content = chunk
+					m.sendWithRetry(ctx, name, w, chunkMsg)
+				}
+			} else {
+				m.sendWithRetry(ctx, name, w, msg)
+			}
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+// sendWithRetry sends a message through the channel with rate limiting and
+// retry logic. It classifies errors to determine the retry strategy:
+//   - ErrNotRunning / ErrSendFailed: permanent, no retry
+//   - ErrRateLimit: fixed delay retry
+//   - ErrTemporary / unknown: exponential backoff retry
+func (m *Manager) sendWithRetry(ctx context.Context, name string, w *channelWorker, msg bus.OutboundMessage) {
+	// Rate limit: wait for token
+	if err := w.limiter.Wait(ctx); err != nil {
+		// ctx canceled, shutting down
+		return
+	}
+
+	// Pre-send: stop typing and try to edit placeholder
+	if m.preSend(ctx, name, msg, w.ch) {
+		return // placeholder was edited successfully, skip Send
+	}
+
+	var lastErr error
+	for attempt := 0; attempt <= maxRetries; attempt++ {
+		lastErr = w.ch.Send(ctx, msg)
+		if lastErr == nil {
+			return
+		}
+
+		// Permanent failures — don't retry
+		if errors.Is(lastErr, ErrNotRunning) || errors.Is(lastErr, ErrSendFailed) {
+			break
+		}
+
+		// Last attempt exhausted — don't sleep
+		if attempt == maxRetries {
+			break
+		}
+
+		// Rate limit error — fixed delay
+		if errors.Is(lastErr, ErrRateLimit) {
+			select {
+			case <-time.After(rateLimitDelay):
+				continue
+			case <-ctx.Done():
+				return
+			}
+		}
+
+		// ErrTemporary or unknown error — exponential backoff
+		backoff := min(time.Duration(float64(baseBackoff)*math.Pow(2, float64(attempt))), maxBackoff)
+		select {
+		case <-time.After(backoff):
+		case <-ctx.Done():
+			return
+		}
+	}
+
+	// All retries exhausted or permanent failure
+	logger.ErrorCF("channels", "Send failed", map[string]any{
+		"channel": name,
+		"chat_id": msg.ChatID,
+		"error":   lastErr.Error(),
+		"retries": maxRetries,
+	})
+}
+
+func dispatchLoop[M any](
+	ctx context.Context,
+	m *Manager,
+	subscribe func(context.Context) (M, bool),
+	getChannel func(M) string,
+	enqueue func(context.Context, *channelWorker, M) bool,
+	startMsg, stopMsg, unknownMsg, noWorkerMsg string,
+) {
+	logger.InfoC("channels", startMsg)
+
+	for {
+		msg, ok := subscribe(ctx)
+		if !ok {
+			logger.InfoC("channels", stopMsg)
+			return
+		}
+
+		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) {
-	logger.InfoC("channels", "Outbound dispatcher started")
+	dispatchLoop(
+		ctx, m,
+		m.bus.SubscribeOutbound,
+		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) {
+	dispatchLoop(
+		ctx, m,
+		m.bus.SubscribeOutboundMedia,
+		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 false
+			}
+		},
+		"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.
+func (m *Manager) runMediaWorker(ctx context.Context, name string, w *channelWorker) {
+	defer close(w.mediaDone)
+	for {
+		select {
+		case msg, ok := <-w.mediaQueue:
+			if !ok {
+				return
+			}
+			m.sendMediaWithRetry(ctx, name, w, msg)
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+// 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) {
+	ms, ok := w.ch.(MediaSender)
+	if !ok {
+		logger.DebugCF("channels", "Channel does not support MediaSender, skipping media", map[string]any{
+			"channel": name,
+		})
+		return
+	}
+
+	// Rate limit: wait for token
+	if err := w.limiter.Wait(ctx); err != nil {
+		return
+	}
+
+	var lastErr error
+	for attempt := 0; attempt <= maxRetries; attempt++ {
+		lastErr = ms.SendMedia(ctx, msg)
+		if lastErr == nil {
+			return
+		}
+
+		// Permanent failures — don't retry
+		if errors.Is(lastErr, ErrNotRunning) || errors.Is(lastErr, ErrSendFailed) {
+			break
+		}
+
+		// Last attempt exhausted — don't sleep
+		if attempt == maxRetries {
+			break
+		}
+
+		// Rate limit error — fixed delay
+		if errors.Is(lastErr, ErrRateLimit) {
+			select {
+			case <-time.After(rateLimitDelay):
+				continue
+			case <-ctx.Done():
+				return
+			}
+		}
+
+		// ErrTemporary or unknown error — exponential backoff
+		backoff := min(time.Duration(float64(baseBackoff)*math.Pow(2, float64(attempt))), maxBackoff)
+		select {
+		case <-time.After(backoff):
+		case <-ctx.Done():
+			return
+		}
+	}
+
+	// All retries exhausted or permanent failure
+	logger.ErrorCF("channels", "SendMedia failed", map[string]any{
+		"channel": name,
+		"chat_id": msg.ChatID,
+		"error":   lastErr.Error(),
+		"retries": maxRetries,
+	})
+}
+
+// runTTLJanitor periodically scans the typingStops and placeholders maps
+// and evicts entries that have exceeded their TTL. This prevents memory
+// accumulation when outbound paths fail to trigger preSend (e.g. LLM errors).
+func (m *Manager) runTTLJanitor(ctx context.Context) {
+	ticker := time.NewTicker(janitorInterval)
+	defer ticker.Stop()
 
 	for {
 		select {
 		case <-ctx.Done():
-			logger.InfoC("channels", "Outbound dispatcher stopped")
 			return
-		default:
-			msg, ok := m.bus.SubscribeOutbound(ctx)
-			if !ok {
-				continue
-			}
-
-			// Silently skip internal channels
-			if constants.IsInternalChannel(msg.Channel) {
-				continue
-			}
-
-			m.mu.RLock()
-			channel, exists := m.channels[msg.Channel]
-			m.mu.RUnlock()
-
-			if !exists {
-				logger.WarnCF("channels", "Unknown channel for outbound message", map[string]any{
-					"channel": msg.Channel,
-				})
-				continue
-			}
-
-			if err := channel.Send(ctx, msg); err != nil {
-				logger.ErrorCF("channels", "Error sending message to channel", map[string]any{
-					"channel": msg.Channel,
-					"error":   err.Error(),
-				})
-			}
+		case now := <-ticker.C:
+			m.typingStops.Range(func(key, value any) bool {
+				if entry, ok := value.(typingEntry); ok {
+					if now.Sub(entry.createdAt) > typingStopTTL {
+						if _, loaded := m.typingStops.LoadAndDelete(key); loaded {
+							entry.stop() // idempotent, safe
+						}
+					}
+				}
+				return true
+			})
+			m.reactionUndos.Range(func(key, value any) bool {
+				if entry, ok := value.(reactionEntry); ok {
+					if now.Sub(entry.createdAt) > typingStopTTL {
+						if _, loaded := m.reactionUndos.LoadAndDelete(key); loaded {
+							entry.undo() // idempotent, safe
+						}
+					}
+				}
+				return true
+			})
+			m.placeholders.Range(func(key, value any) bool {
+				if entry, ok := value.(placeholderEntry); ok {
+					if now.Sub(entry.createdAt) > placeholderTTL {
+						m.placeholders.Delete(key)
+					}
+				}
+				return true
+			})
 		}
 	}
 }
@@ -349,12 +802,20 @@ func (m *Manager) RegisterChannel(name string, channel Channel) {
 func (m *Manager) UnregisterChannel(name string) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
+	if w, ok := m.workers[name]; ok && w != nil {
+		close(w.queue)
+		<-w.done
+		close(w.mediaQueue)
+		<-w.mediaDone
+	}
+	delete(m.workers, name)
 	delete(m.channels, name)
 }
 
 func (m *Manager) SendToChannel(ctx context.Context, channelName, chatID, content string) error {
 	m.mu.RLock()
-	channel, exists := m.channels[channelName]
+	_, exists := m.channels[channelName]
+	w, wExists := m.workers[channelName]
 	m.mu.RUnlock()
 
 	if !exists {
@@ -367,5 +828,16 @@ func (m *Manager) SendToChannel(ctx context.Context, channelName, chatID, conten
 		Content: content,
 	}
 
+	if wExists && w != nil {
+		select {
+		case w.queue <- msg:
+			return nil
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	// Fallback: direct send (should not happen)
+	channel, _ := m.channels[channelName]
 	return channel.Send(ctx, msg)
 }
diff --git a/pkg/channels/manager_test.go b/pkg/channels/manager_test.go
new file mode 100644
index 000000000..f09ecfe2f
--- /dev/null
+++ b/pkg/channels/manager_test.go
@@ -0,0 +1,862 @@
+package channels
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+)
+
+// 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
+}
+
+func (m *mockChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	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 }
+
+// newTestManager creates a minimal Manager suitable for unit tests.
+func newTestManager() *Manager {
+	return &Manager{
+		channels: make(map[string]Channel),
+		workers:  make(map[string]*channelWorker),
+	}
+}
+
+func TestSendWithRetry_Success(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call, got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_TemporaryThenSuccess(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			if callCount <= 2 {
+				return fmt.Errorf("network error: %w", ErrTemporary)
+			}
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 3 {
+		t.Fatalf("expected 3 Send calls (2 failures + 1 success), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_PermanentFailure(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return fmt.Errorf("bad chat ID: %w", ErrSendFailed)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call (no retry for permanent failure), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_NotRunning(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return ErrNotRunning
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call (no retry for ErrNotRunning), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_RateLimitRetry(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			if callCount == 1 {
+				return fmt.Errorf("429: %w", ErrRateLimit)
+			}
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	start := time.Now()
+	m.sendWithRetry(ctx, "test", w, msg)
+	elapsed := time.Since(start)
+
+	if callCount != 2 {
+		t.Fatalf("expected 2 Send calls (1 rate limit + 1 success), got %d", callCount)
+	}
+	// Should have waited at least rateLimitDelay (1s) but allow some slack
+	if elapsed < 900*time.Millisecond {
+		t.Fatalf("expected at least ~1s delay for rate limit retry, got %v", elapsed)
+	}
+}
+
+func TestSendWithRetry_MaxRetriesExhausted(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return fmt.Errorf("timeout: %w", ErrTemporary)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	expected := maxRetries + 1 // initial attempt + maxRetries retries
+	if callCount != expected {
+		t.Fatalf("expected %d Send calls, got %d", expected, callCount)
+	}
+}
+
+func TestSendWithRetry_UnknownError(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			if callCount == 1 {
+				return errors.New("random unexpected error")
+			}
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 2 {
+		t.Fatalf("expected 2 Send calls (unknown error treated as temporary), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_ContextCancelled(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return fmt.Errorf("timeout: %w", ErrTemporary)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	// Cancel context after first Send attempt returns
+	ch.sendFn = func(_ context.Context, _ bus.OutboundMessage) error {
+		callCount++
+		cancel()
+		return fmt.Errorf("timeout: %w", ErrTemporary)
+	}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	// Should have called Send once, then noticed ctx canceled during backoff
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call before context cancellation, got %d", callCount)
+	}
+}
+
+func TestWorkerRateLimiter(t *testing.T) {
+	m := newTestManager()
+
+	var mu sync.Mutex
+	var sendTimes []time.Time
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			mu.Lock()
+			sendTimes = append(sendTimes, time.Now())
+			mu.Unlock()
+			return nil
+		},
+	}
+
+	// Create a worker with a low rate: 2 msg/s, burst 1
+	w := &channelWorker{
+		ch:      ch,
+		queue:   make(chan bus.OutboundMessage, 10),
+		done:    make(chan struct{}),
+		limiter: rate.NewLimiter(2, 1),
+	}
+
+	ctx := t.Context()
+
+	go m.runWorker(ctx, "test", w)
+
+	// Enqueue 4 messages
+	for i := range 4 {
+		w.queue <- bus.OutboundMessage{Channel: "test", ChatID: "1", Content: fmt.Sprintf("msg%d", i)}
+	}
+
+	// Wait enough time for all messages to be sent (4 msgs at 2/s = ~2s, give extra margin)
+	time.Sleep(3 * time.Second)
+
+	mu.Lock()
+	times := make([]time.Time, len(sendTimes))
+	copy(times, sendTimes)
+	mu.Unlock()
+
+	if len(times) != 4 {
+		t.Fatalf("expected 4 sends, got %d", len(times))
+	}
+
+	// Verify rate limiting: total duration should be at least 1s
+	// (first message immediate, then ~500ms between each subsequent one at 2/s)
+	totalDuration := times[len(times)-1].Sub(times[0])
+	if totalDuration < 1*time.Second {
+		t.Fatalf("expected total duration >= 1s for 4 msgs at 2/s rate, got %v", totalDuration)
+	}
+}
+
+func TestNewChannelWorker_DefaultRate(t *testing.T) {
+	ch := &mockChannel{}
+	w := newChannelWorker("unknown_channel", ch)
+
+	if w.limiter == nil {
+		t.Fatal("expected limiter to be non-nil")
+	}
+	if w.limiter.Limit() != rate.Limit(defaultRateLimit) {
+		t.Fatalf("expected rate limit %v, got %v", rate.Limit(defaultRateLimit), w.limiter.Limit())
+	}
+}
+
+func TestNewChannelWorker_ConfiguredRate(t *testing.T) {
+	ch := &mockChannel{}
+
+	for name, expectedRate := range channelRateConfig {
+		w := newChannelWorker(name, ch)
+		if w.limiter.Limit() != rate.Limit(expectedRate) {
+			t.Fatalf("channel %s: expected rate %v, got %v", name, expectedRate, w.limiter.Limit())
+		}
+	}
+}
+
+func TestRunWorker_MessageSplitting(t *testing.T) {
+	m := newTestManager()
+
+	var mu sync.Mutex
+	var received []string
+
+	ch := &mockChannelWithLength{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, msg bus.OutboundMessage) error {
+				mu.Lock()
+				received = append(received, msg.Content)
+				mu.Unlock()
+				return nil
+			},
+		},
+		maxLen: 5,
+	}
+
+	w := &channelWorker{
+		ch:      ch,
+		queue:   make(chan bus.OutboundMessage, 10),
+		done:    make(chan struct{}),
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := t.Context()
+
+	go m.runWorker(ctx, "test", w)
+
+	// Send a message that should be split
+	w.queue <- bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello world"}
+
+	time.Sleep(100 * time.Millisecond)
+
+	mu.Lock()
+	count := len(received)
+	mu.Unlock()
+
+	if count < 2 {
+		t.Fatalf("expected message to be split into at least 2 chunks, got %d", count)
+	}
+}
+
+// mockChannelWithLength implements MessageLengthProvider.
+type mockChannelWithLength struct {
+	mockChannel
+	maxLen int
+}
+
+func (m *mockChannelWithLength) MaxMessageLength() int {
+	return m.maxLen
+}
+
+func TestSendWithRetry_ExponentialBackoff(t *testing.T) {
+	m := newTestManager()
+
+	var callTimes []time.Time
+	var callCount atomic.Int32
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callTimes = append(callTimes, time.Now())
+			callCount.Add(1)
+			return fmt.Errorf("timeout: %w", ErrTemporary)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	start := time.Now()
+	m.sendWithRetry(ctx, "test", w, msg)
+	totalElapsed := time.Since(start)
+
+	// With maxRetries=3: attempts at 0, ~500ms, ~1.5s, ~3.5s
+	// Total backoff: 500ms + 1s + 2s = 3.5s
+	// Allow some margin
+	if totalElapsed < 3*time.Second {
+		t.Fatalf("expected total elapsed >= 3s for exponential backoff, got %v", totalElapsed)
+	}
+
+	if int(callCount.Load()) != maxRetries+1 {
+		t.Fatalf("expected %d calls, got %d", maxRetries+1, callCount.Load())
+	}
+}
+
+// --- Phase 10: preSend orchestration tests ---
+
+// mockMessageEditor is a channel that supports MessageEditor.
+type mockMessageEditor struct {
+	mockChannel
+	editFn func(ctx context.Context, chatID, messageID, content string) error
+}
+
+func (m *mockMessageEditor) EditMessage(ctx context.Context, chatID, messageID, content string) error {
+	return m.editFn(ctx, chatID, messageID, content)
+}
+
+func TestPreSend_PlaceholderEditSuccess(t *testing.T) {
+	m := newTestManager()
+	var sendCalled bool
+	var editCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				sendCalled = true
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, chatID, messageID, content string) error {
+			editCalled = true
+			if chatID != "123" {
+				t.Fatalf("expected chatID 123, got %s", chatID)
+			}
+			if messageID != "456" {
+				t.Fatalf("expected messageID 456, got %s", messageID)
+			}
+			if content != "hello" {
+				t.Fatalf("expected content 'hello', got %s", content)
+			}
+			return nil
+		},
+	}
+
+	// Register placeholder
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if !edited {
+		t.Fatal("expected preSend to return true (placeholder edited)")
+	}
+	if !editCalled {
+		t.Fatal("expected EditMessage to be called")
+	}
+	if sendCalled {
+		t.Fatal("expected Send to NOT be called when placeholder edited")
+	}
+}
+
+func TestPreSend_PlaceholderEditFails_FallsThrough(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, _, _, _ string) error {
+			return fmt.Errorf("edit failed")
+		},
+	}
+
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if edited {
+		t.Fatal("expected preSend to return false when edit fails")
+	}
+}
+
+func TestPreSend_TypingStopCalled(t *testing.T) {
+	m := newTestManager()
+	var stopCalled bool
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			return nil
+		},
+	}
+
+	m.RecordTypingStop("test", "123", func() {
+		stopCalled = true
+	})
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	m.preSend(context.Background(), "test", msg, ch)
+
+	if !stopCalled {
+		t.Fatal("expected typing stop func to be called")
+	}
+}
+
+func TestPreSend_NoRegisteredState(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			return nil
+		},
+	}
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if edited {
+		t.Fatal("expected preSend to return false with no registered state")
+	}
+}
+
+func TestPreSend_TypingAndPlaceholder(t *testing.T) {
+	m := newTestManager()
+	var stopCalled bool
+	var editCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, _, _, _ string) error {
+			editCalled = true
+			return nil
+		},
+	}
+
+	m.RecordTypingStop("test", "123", func() {
+		stopCalled = true
+	})
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if !stopCalled {
+		t.Fatal("expected typing stop to be called")
+	}
+	if !editCalled {
+		t.Fatal("expected EditMessage to be called")
+	}
+	if !edited {
+		t.Fatal("expected preSend to return true")
+	}
+}
+
+func TestRecordPlaceholder_ConcurrentSafe(t *testing.T) {
+	m := newTestManager()
+
+	var wg sync.WaitGroup
+	for i := range 100 {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			chatID := fmt.Sprintf("chat_%d", i%10)
+			m.RecordPlaceholder("test", chatID, fmt.Sprintf("msg_%d", i))
+		}(i)
+	}
+	wg.Wait()
+}
+
+func TestRecordTypingStop_ConcurrentSafe(t *testing.T) {
+	m := newTestManager()
+
+	var wg sync.WaitGroup
+	for i := range 100 {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			chatID := fmt.Sprintf("chat_%d", i%10)
+			m.RecordTypingStop("test", chatID, func() {})
+		}(i)
+	}
+	wg.Wait()
+}
+
+func TestSendWithRetry_PreSendEditsPlaceholder(t *testing.T) {
+	m := newTestManager()
+	var sendCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				sendCalled = true
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, _, _, _ string) error {
+			return nil // edit succeeds
+		},
+	}
+
+	m.RecordPlaceholder("test", "123", "456")
+
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	m.sendWithRetry(context.Background(), "test", w, msg)
+
+	if sendCalled {
+		t.Fatal("expected Send to NOT be called when placeholder was edited")
+	}
+}
+
+// --- Dispatcher exit tests (Step 1) ---
+
+func TestDispatcherExitsOnCancel(t *testing.T) {
+	mb := bus.NewMessageBus()
+	defer mb.Close()
+
+	m := &Manager{
+		channels: make(map[string]Channel),
+		workers:  make(map[string]*channelWorker),
+		bus:      mb,
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+
+	go func() {
+		m.dispatchOutbound(ctx)
+		close(done)
+	}()
+
+	// Cancel context and verify the dispatcher exits quickly
+	cancel()
+
+	select {
+	case <-done:
+		// success
+	case <-time.After(2 * time.Second):
+		t.Fatal("dispatchOutbound did not exit within 2s after context cancel")
+	}
+}
+
+func TestDispatcherMediaExitsOnCancel(t *testing.T) {
+	mb := bus.NewMessageBus()
+	defer mb.Close()
+
+	m := &Manager{
+		channels: make(map[string]Channel),
+		workers:  make(map[string]*channelWorker),
+		bus:      mb,
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+
+	go func() {
+		m.dispatchOutboundMedia(ctx)
+		close(done)
+	}()
+
+	cancel()
+
+	select {
+	case <-done:
+		// success
+	case <-time.After(2 * time.Second):
+		t.Fatal("dispatchOutboundMedia did not exit within 2s after context cancel")
+	}
+}
+
+// --- TTL Janitor tests (Step 2) ---
+
+func TestTypingStopJanitorEviction(t *testing.T) {
+	m := newTestManager()
+
+	var stopCalled atomic.Bool
+	// Store a typing entry with a creation time far in the past
+	m.typingStops.Store("test:123", typingEntry{
+		stop:      func() { stopCalled.Store(true) },
+		createdAt: time.Now().Add(-10 * time.Minute), // well past typingStopTTL
+	})
+
+	// Run janitor with a short-lived context
+	ctx, cancel := context.WithCancel(context.Background())
+
+	// Manually trigger the janitor logic once by simulating a tick
+	go func() {
+		// Override janitor to run immediately
+		now := time.Now()
+		m.typingStops.Range(func(key, value any) bool {
+			if entry, ok := value.(typingEntry); ok {
+				if now.Sub(entry.createdAt) > typingStopTTL {
+					if _, loaded := m.typingStops.LoadAndDelete(key); loaded {
+						entry.stop()
+					}
+				}
+			}
+			return true
+		})
+		cancel()
+	}()
+
+	<-ctx.Done()
+
+	if !stopCalled.Load() {
+		t.Fatal("expected typing stop function to be called by janitor eviction")
+	}
+
+	// Verify entry was deleted
+	if _, loaded := m.typingStops.Load("test:123"); loaded {
+		t.Fatal("expected typing entry to be deleted after eviction")
+	}
+}
+
+func TestPlaceholderJanitorEviction(t *testing.T) {
+	m := newTestManager()
+
+	// Store a placeholder entry with a creation time far in the past
+	m.placeholders.Store("test:456", placeholderEntry{
+		id:        "msg_old",
+		createdAt: time.Now().Add(-20 * time.Minute), // well past placeholderTTL
+	})
+
+	// Simulate janitor logic
+	now := time.Now()
+	m.placeholders.Range(func(key, value any) bool {
+		if entry, ok := value.(placeholderEntry); ok {
+			if now.Sub(entry.createdAt) > placeholderTTL {
+				m.placeholders.Delete(key)
+			}
+		}
+		return true
+	})
+
+	// Verify entry was deleted
+	if _, loaded := m.placeholders.Load("test:456"); loaded {
+		t.Fatal("expected placeholder entry to be deleted after eviction")
+	}
+}
+
+func TestPreSendStillWorksWithWrappedTypes(t *testing.T) {
+	m := newTestManager()
+	var stopCalled bool
+	var editCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, chatID, messageID, content string) error {
+			editCalled = true
+			if messageID != "ph_id" {
+				t.Fatalf("expected messageID ph_id, got %s", messageID)
+			}
+			return nil
+		},
+	}
+
+	// Use the new wrapped types via the public API
+	m.RecordTypingStop("test", "chat1", func() {
+		stopCalled = true
+	})
+	m.RecordPlaceholder("test", "chat1", "ph_id")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "chat1", Content: "response"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if !stopCalled {
+		t.Fatal("expected typing stop to be called via wrapped type")
+	}
+	if !editCalled {
+		t.Fatal("expected EditMessage to be called via wrapped type")
+	}
+	if !edited {
+		t.Fatal("expected preSend to return true")
+	}
+}
+
+// --- Lazy worker creation tests (Step 6) ---
+
+func TestLazyWorkerCreation(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			return nil
+		},
+	}
+
+	// RegisterChannel should NOT create a worker
+	m.RegisterChannel("lazy", ch)
+
+	m.mu.RLock()
+	_, chExists := m.channels["lazy"]
+	_, wExists := m.workers["lazy"]
+	m.mu.RUnlock()
+
+	if !chExists {
+		t.Fatal("expected channel to be registered")
+	}
+	if wExists {
+		t.Fatal("expected worker to NOT be created by RegisterChannel (lazy creation)")
+	}
+}
+
+// --- FastID uniqueness test (Step 5) ---
+
+func TestBuildMediaScope_FastIDUniqueness(t *testing.T) {
+	seen := make(map[string]bool)
+
+	for range 1000 {
+		scope := BuildMediaScope("test", "chat1", "")
+		if seen[scope] {
+			t.Fatalf("duplicate scope generated: %s", scope)
+		}
+		seen[scope] = true
+	}
+
+	// Verify format: "channel:chatID:id"
+	scope := BuildMediaScope("telegram", "42", "")
+	parts := 0
+	for _, c := range scope {
+		if c == ':' {
+			parts++
+		}
+	}
+	if parts != 2 {
+		t.Fatalf("expected scope to have 2 colons (channel:chatID:id), got: %s", scope)
+	}
+}
+
+func TestBuildMediaScope_WithMessageID(t *testing.T) {
+	scope := BuildMediaScope("discord", "chat99", "msg123")
+	expected := "discord:chat99:msg123"
+	if scope != expected {
+		t.Fatalf("expected %s, got %s", expected, scope)
+	}
+}
diff --git a/pkg/channels/matrix/init.go b/pkg/channels/matrix/init.go
new file mode 100644
index 000000000..6677f855e
--- /dev/null
+++ b/pkg/channels/matrix/init.go
@@ -0,0 +1,13 @@
+package matrix
+
+import (
+	"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) {
+		return NewMatrixChannel(cfg.Channels.Matrix, b)
+	})
+}
diff --git a/pkg/channels/matrix/matrix.go b/pkg/channels/matrix/matrix.go
new file mode 100644
index 000000000..d51eee8fb
--- /dev/null
+++ b/pkg/channels/matrix/matrix.go
@@ -0,0 +1,1115 @@
+package matrix
+
+import (
+	"context"
+	"fmt"
+	"html"
+	"mime"
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"maunium.net/go/mautrix"
+	"maunium.net/go/mautrix/event"
+	"maunium.net/go/mautrix/id"
+
+	"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 (
+	typingRefreshInterval      = 20 * time.Second
+	typingServerTTL            = 30 * time.Second
+	roomKindCacheTTL           = 5 * time.Minute
+	roomKindCacheCleanupPeriod = 1 * time.Minute
+	roomKindCacheMaxEntries    = 2048
+
+	matrixMediaTempDirName = "picoclaw_media"
+)
+
+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
+}
+
+func NewMatrixChannel(cfg config.MatrixConfig, messageBus *bus.MessageBus) (*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{},
+	}, 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()
+
+	c.syncer.OnEventType(event.EventMessage, 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)
+
+	logger.InfoC("matrix", "Matrix channel stopped")
+	return nil
+}
+
+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, &event.MessageEventContent{
+		MsgType: event.MsgText,
+		Body:    content,
+	})
+	if err != nil {
+		return fmt.Errorf("matrix send: %w", channels.ErrTemporary)
+	}
+	return nil
+}
+
+// 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 := &event.MessageEventContent{
+		MsgType: event.MsgText,
+		Body:    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
+	}
+
+	msgEvt := evt.Content.AsMessage()
+	if msgEvt == nil {
+		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,
+	)
+}
+
+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 {
+		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()
+
+	data, err := c.client.DownloadBytes(reqCtx, parsed)
+	if err != nil {
+		return "", err
+	}
+
+	// Encrypted attachments put URL in msgEvt.File and require client-side decryption.
+	if msgEvt != nil && msgEvt.File != nil && msgEvt.URL == "" {
+		err = msgEvt.File.DecryptInPlace(data)
+		if err != nil {
+			return "", fmt.Errorf("decrypt matrix media: %w", err)
+		}
+	}
+
+	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
+	}
+	defer tmp.Close()
+
+	if _, err = tmp.Write(data); err != nil {
+		_ = os.Remove(tmp.Name())
+		return "", err
+	}
+
+	return tmp.Name(), 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 := filepath.Join(os.TempDir(), matrixMediaTempDirName)
+	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..e76db0d3e
--- /dev/null
+++ b/pkg/channels/matrix/matrix_test.go
@@ -0,0 +1,291 @@
+package matrix
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"maunium.net/go/mautrix"
+	"maunium.net/go/mautrix/event"
+	"maunium.net/go/mautrix/id"
+)
+
+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) != matrixMediaTempDirName {
+		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 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)
+	}
+}
diff --git a/pkg/channels/media.go b/pkg/channels/media.go
new file mode 100644
index 000000000..c645a6180
--- /dev/null
+++ b/pkg/channels/media.go
@@ -0,0 +1,15 @@
+package channels
+
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+)
+
+// MediaSender is an optional interface for channels that can send
+// media attachments (images, files, audio, video).
+// Manager discovers channels implementing this interface via type
+// assertion and routes OutboundMediaMessage to them.
+type MediaSender interface {
+	SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error
+}
diff --git a/pkg/channels/onebot/init.go b/pkg/channels/onebot/init.go
new file mode 100644
index 000000000..84c06dfd6
--- /dev/null
+++ b/pkg/channels/onebot/init.go
@@ -0,0 +1,13 @@
+package onebot
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("onebot", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewOneBotChannel(cfg.Channels.OneBot, b)
+	})
+}
diff --git a/pkg/channels/onebot.go b/pkg/channels/onebot/onebot.go
similarity index 74%
rename from pkg/channels/onebot.go
rename to pkg/channels/onebot/onebot.go
index cee8ad9d3..62a9eb34a 100644
--- a/pkg/channels/onebot.go
+++ b/pkg/channels/onebot/onebot.go
@@ -1,10 +1,9 @@
-package channels
+package onebot
 
 import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"os"
 	"strconv"
 	"strings"
 	"sync"
@@ -14,30 +13,30 @@ import (
 	"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"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
-	"github.com/sipeed/picoclaw/pkg/voice"
 )
 
 type OneBotChannel struct {
-	*BaseChannel
-	config          config.OneBotConfig
-	conn            *websocket.Conn
-	ctx             context.Context
-	cancel          context.CancelFunc
-	dedup           map[string]struct{}
-	dedupRing       []string
-	dedupIdx        int
-	mu              sync.Mutex
-	writeMu         sync.Mutex
-	echoCounter     int64
-	selfID          int64
-	pending         map[string]chan json.RawMessage
-	pendingMu       sync.Mutex
-	transcriber     *voice.GroqTranscriber
-	lastMessageID   sync.Map
-	pendingEmojiMsg sync.Map
+	*channels.BaseChannel
+	config        config.OneBotConfig
+	conn          *websocket.Conn
+	ctx           context.Context
+	cancel        context.CancelFunc
+	dedup         map[string]struct{}
+	dedupRing     []string
+	dedupIdx      int
+	mu            sync.Mutex
+	writeMu       sync.Mutex
+	echoCounter   int64
+	selfID        int64
+	pending       map[string]chan json.RawMessage
+	pendingMu     sync.Mutex
+	lastMessageID sync.Map
 }
 
 type oneBotRawEvent struct {
@@ -98,7 +97,10 @@ type oneBotMessageSegment struct {
 }
 
 func NewOneBotChannel(cfg config.OneBotConfig, messageBus *bus.MessageBus) (*OneBotChannel, error) {
-	base := NewBaseChannel("onebot", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("onebot", cfg, messageBus, cfg.AllowFrom,
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
 
 	const dedupSize = 1024
 	return &OneBotChannel{
@@ -111,10 +113,6 @@ func NewOneBotChannel(cfg config.OneBotConfig, messageBus *bus.MessageBus) (*One
 	}, nil
 }
 
-func (c *OneBotChannel) SetTranscriber(transcriber *voice.GroqTranscriber) {
-	c.transcriber = transcriber
-}
-
 func (c *OneBotChannel) setMsgEmojiLike(messageID string, emojiID int, set bool) {
 	go func() {
 		_, err := c.sendAPIRequest("set_msg_emoji_like", map[string]any{
@@ -131,6 +129,22 @@ func (c *OneBotChannel) setMsgEmojiLike(messageID string, emojiID int, set bool)
 	}()
 }
 
+// ReactToMessage implements channels.ReactionCapable.
+// It adds an emoji reaction (ID 289) to group messages and returns an undo function.
+// Private messages return a no-op since reactions are only meaningful in groups.
+func (c *OneBotChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (func(), error) {
+	// Only react in group chats
+	if !strings.HasPrefix(chatID, "group:") {
+		return func() {}, nil
+	}
+
+	c.setMsgEmojiLike(messageID, 289, true)
+
+	return func() {
+		c.setMsgEmojiLike(messageID, 289, false)
+	}, nil
+}
+
 func (c *OneBotChannel) Start(ctx context.Context) error {
 	if c.config.WSUrl == "" {
 		return fmt.Errorf("OneBot ws_url not configured")
@@ -159,7 +173,7 @@ func (c *OneBotChannel) Start(ctx context.Context) error {
 		}
 	}
 
-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("onebot", "OneBot channel started successfully")
 
 	return nil
@@ -174,7 +188,10 @@ func (c *OneBotChannel) connect() error {
 		header["Authorization"] = []string{"Bearer " + c.config.AccessToken}
 	}
 
-	conn, _, err := dialer.Dial(c.config.WSUrl, header)
+	conn, resp, err := dialer.Dial(c.config.WSUrl, header)
+	if resp != nil {
+		resp.Body.Close()
+	}
 	if err != nil {
 		return err
 	}
@@ -297,7 +314,9 @@ func (c *OneBotChannel) sendAPIRequest(action string, params any, timeout time.D
 	}
 
 	c.writeMu.Lock()
+	_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
 	err = conn.WriteMessage(websocket.TextMessage, data)
+	_ = conn.SetWriteDeadline(time.Time{})
 	c.writeMu.Unlock()
 
 	if err != nil {
@@ -306,19 +325,19 @@ func (c *OneBotChannel) sendAPIRequest(action string, params any, timeout time.D
 
 	select {
 	case resp := <-ch:
+		if resp == nil {
+			return nil, fmt.Errorf("API request %s: channel stopped", action)
+		}
 		return resp, nil
 	case <-time.After(timeout):
 		return nil, fmt.Errorf("API request %s timed out after %v", action, timeout)
 	case <-c.ctx.Done():
-		return nil, fmt.Errorf("context cancelled")
+		return nil, fmt.Errorf("context canceled")
 	}
 }
 
 func (c *OneBotChannel) reconnectLoop() {
-	interval := time.Duration(c.config.ReconnectInterval) * time.Second
-	if interval < 5*time.Second {
-		interval = 5 * time.Second
-	}
+	interval := max(time.Duration(c.config.ReconnectInterval)*time.Second, 5*time.Second)
 
 	for {
 		select {
@@ -346,7 +365,7 @@ func (c *OneBotChannel) reconnectLoop() {
 
 func (c *OneBotChannel) Stop(ctx context.Context) error {
 	logger.InfoC("onebot", "Stopping OneBot channel")
-	c.setRunning(false)
+	c.SetRunning(false)
 
 	if c.cancel != nil {
 		c.cancel()
@@ -354,7 +373,10 @@ func (c *OneBotChannel) Stop(ctx context.Context) error {
 
 	c.pendingMu.Lock()
 	for echo, ch := range c.pending {
-		close(ch)
+		select {
+		case ch <- nil: // non-blocking wake for blocked sendAPIRequest goroutines
+		default:
+		}
 		delete(c.pending, echo)
 	}
 	c.pendingMu.Unlock()
@@ -371,7 +393,14 @@ func (c *OneBotChannel) Stop(ctx context.Context) error {
 
 func (c *OneBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("OneBot channel not running")
+		return channels.ErrNotRunning
+	}
+
+	// Check ctx before entering write path
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
 	}
 
 	c.mu.Lock()
@@ -401,20 +430,127 @@ func (c *OneBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
 	}
 
 	c.writeMu.Lock()
+	_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
 	err = conn.WriteMessage(websocket.TextMessage, data)
+	_ = conn.SetWriteDeadline(time.Time{})
 	c.writeMu.Unlock()
 
 	if err != nil {
 		logger.ErrorCF("onebot", "Failed to send message", map[string]any{
 			"error": err.Error(),
 		})
-		return err
+		return fmt.Errorf("onebot send: %w", channels.ErrTemporary)
 	}
 
-	if msgID, ok := c.pendingEmojiMsg.LoadAndDelete(msg.ChatID); ok {
-		if mid, ok := msgID.(string); ok && mid != "" {
-			c.setMsgEmojiLike(mid, 289, false)
+	return nil
+}
+
+// SendMedia implements the channels.MediaSender interface.
+func (c *OneBotChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+	}
+
+	c.mu.Lock()
+	conn := c.conn
+	c.mu.Unlock()
+
+	if conn == nil {
+		return fmt.Errorf("OneBot WebSocket not connected")
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	// Build media segments
+	var segments []oneBotMessageSegment
+	for _, part := range msg.Parts {
+		localPath, err := store.Resolve(part.Ref)
+		if err != nil {
+			logger.ErrorCF("onebot", "Failed to resolve media ref", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			continue
 		}
+
+		var segType string
+		switch part.Type {
+		case "image":
+			segType = "image"
+		case "video":
+			segType = "video"
+		case "audio":
+			segType = "record"
+		default:
+			segType = "file"
+		}
+
+		segments = append(segments, oneBotMessageSegment{
+			Type: segType,
+			Data: map[string]any{"file": "file://" + localPath},
+		})
+
+		if part.Caption != "" {
+			segments = append(segments, oneBotMessageSegment{
+				Type: "text",
+				Data: map[string]any{"text": part.Caption},
+			})
+		}
+	}
+
+	if len(segments) == 0 {
+		return nil
+	}
+
+	chatID := msg.ChatID
+	var action, idKey string
+	var rawID string
+	if rest, ok := strings.CutPrefix(chatID, "group:"); ok {
+		action, idKey, rawID = "send_group_msg", "group_id", rest
+	} else if rest, ok := strings.CutPrefix(chatID, "private:"); ok {
+		action, idKey, rawID = "send_private_msg", "user_id", rest
+	} else {
+		action, idKey, rawID = "send_private_msg", "user_id", chatID
+	}
+
+	id, err := strconv.ParseInt(rawID, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid %s in chatID: %s: %w", idKey, chatID, channels.ErrSendFailed)
+	}
+
+	echo := fmt.Sprintf("send_%d", atomic.AddInt64(&c.echoCounter, 1))
+
+	req := oneBotAPIRequest{
+		Action: action,
+		Params: map[string]any{idKey: id, "message": segments},
+		Echo:   echo,
+	}
+
+	data, err := json.Marshal(req)
+	if err != nil {
+		return fmt.Errorf("failed to marshal OneBot request: %w", err)
+	}
+
+	c.writeMu.Lock()
+	_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
+	err = conn.WriteMessage(websocket.TextMessage, data)
+	_ = conn.SetWriteDeadline(time.Time{})
+	c.writeMu.Unlock()
+
+	if err != nil {
+		logger.ErrorCF("onebot", "Failed to send media message", map[string]any{
+			"error": err.Error(),
+		})
+		return fmt.Errorf("onebot send media: %w", channels.ErrTemporary)
 	}
 
 	return nil
@@ -571,11 +707,15 @@ type parseMessageResult struct {
 	Text           string
 	IsBotMentioned bool
 	Media          []string
-	LocalFiles     []string
 	ReplyTo        string
 }
 
-func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64) parseMessageResult {
+func (c *OneBotChannel) parseMessageSegments(
+	raw json.RawMessage,
+	selfID int64,
+	store media.MediaStore,
+	scope string,
+) parseMessageResult {
 	if len(raw) == 0 {
 		return parseMessageResult{}
 	}
@@ -602,10 +742,23 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 	var textParts []string
 	mentioned := false
 	selfIDStr := strconv.FormatInt(selfID, 10)
-	var media []string
-	var localFiles []string
+	var mediaRefs []string
 	var replyTo string
 
+	// Helper to register a local file with the media store
+	storeFile := func(localPath, filename string) string {
+		if store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "onebot",
+			}, scope)
+			if err == nil {
+				return ref
+			}
+		}
+		return localPath // fallback
+	}
+
 	for _, seg := range segments {
 		segType, _ := seg["type"].(string)
 		data, _ := seg["data"].(map[string]any)
@@ -641,8 +794,7 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 						LoggerPrefix: "onebot",
 					})
 					if localPath != "" {
-						media = append(media, localPath)
-						localFiles = append(localFiles, localPath)
+						mediaRefs = append(mediaRefs, storeFile(localPath, filename))
 						textParts = append(textParts, fmt.Sprintf("[%s]", segType))
 					}
 				}
@@ -656,24 +808,8 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 						LoggerPrefix: "onebot",
 					})
 					if localPath != "" {
-						localFiles = append(localFiles, localPath)
-						if c.transcriber != nil && c.transcriber.IsAvailable() {
-							tctx, tcancel := context.WithTimeout(c.ctx, 30*time.Second)
-							result, err := c.transcriber.Transcribe(tctx, localPath)
-							tcancel()
-							if err != nil {
-								logger.WarnCF("onebot", "Voice transcription failed", map[string]any{
-									"error": err.Error(),
-								})
-								textParts = append(textParts, "[voice (transcription failed)]")
-								media = append(media, localPath)
-							} else {
-								textParts = append(textParts, fmt.Sprintf("[voice transcription: %s]", result.Text))
-							}
-						} else {
-							textParts = append(textParts, "[voice]")
-							media = append(media, localPath)
-						}
+						textParts = append(textParts, "[voice]")
+						mediaRefs = append(mediaRefs, storeFile(localPath, "voice.amr"))
 					}
 				}
 			}
@@ -695,15 +831,13 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 			textParts = append(textParts, "[forward message]")
 
 		default:
-
 		}
 	}
 
 	return parseMessageResult{
 		Text:           strings.TrimSpace(strings.Join(textParts, "")),
 		IsBotMentioned: mentioned,
-		Media:          media,
-		LocalFiles:     localFiles,
+		Media:          mediaRefs,
 		ReplyTo:        replyTo,
 	}
 }
@@ -712,7 +846,13 @@ func (c *OneBotChannel) handleRawEvent(raw *oneBotRawEvent) {
 	switch raw.PostType {
 	case "message":
 		if userID, err := parseJSONInt64(raw.UserID); err == nil && userID > 0 {
-			if !c.IsAllowed(strconv.FormatInt(userID, 10)) {
+			// Build minimal sender for allowlist check
+			sender := bus.SenderInfo{
+				Platform:    "onebot",
+				PlatformID:  strconv.FormatInt(userID, 10),
+				CanonicalID: identity.BuildCanonicalID("onebot", strconv.FormatInt(userID, 10)),
+			}
+			if !c.IsAllowedSender(sender) {
 				logger.DebugCF("onebot", "Message rejected by allowlist", map[string]any{
 					"user_id": userID,
 				})
@@ -795,7 +935,17 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 		selfID = atomic.LoadInt64(&c.selfID)
 	}
 
-	parsed := c.parseMessageSegments(raw.Message, selfID)
+	// Compute scope for media store before parsing (parsing may download files)
+	var chatIDForScope string
+	switch raw.MessageType {
+	case "group":
+		chatIDForScope = "group:" + strconv.FormatInt(groupID, 10)
+	default:
+		chatIDForScope = "private:" + strconv.FormatInt(userID, 10)
+	}
+	scope := channels.BuildMediaScope("onebot", chatIDForScope, messageID)
+
+	parsed := c.parseMessageSegments(raw.Message, selfID, c.GetMediaStore(), scope)
 	isBotMentioned := parsed.IsBotMentioned
 
 	content := raw.RawMessage
@@ -824,20 +974,6 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 		}
 	}
 
-	// Clean up temp files when done
-	if len(parsed.LocalFiles) > 0 {
-		defer func() {
-			for _, f := range parsed.LocalFiles {
-				if err := os.Remove(f); err != nil {
-					logger.DebugCF("onebot", "Failed to remove temp file", map[string]any{
-						"path":  f,
-						"error": err.Error(),
-					})
-				}
-			}
-		}()
-	}
-
 	if c.isDuplicate(messageID) {
 		logger.DebugCF("onebot", "Duplicate message, skipping", map[string]any{
 			"message_id": messageID,
@@ -855,9 +991,9 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 	senderID := strconv.FormatInt(userID, 10)
 	var chatID string
 
-	metadata := map[string]string{
-		"message_id": messageID,
-	}
+	var peer bus.Peer
+
+	metadata := map[string]string{}
 
 	if parsed.ReplyTo != "" {
 		metadata["reply_to_message_id"] = parsed.ReplyTo
@@ -866,14 +1002,12 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 	switch raw.MessageType {
 	case "private":
 		chatID = "private:" + senderID
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}
 
 	case "group":
 		groupIDStr := strconv.FormatInt(groupID, 10)
 		chatID = "group:" + groupIDStr
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = groupIDStr
+		peer = bus.Peer{Kind: "group", ID: groupIDStr}
 		metadata["group_id"] = groupIDStr
 
 		senderUserID, _ := parseJSONInt64(sender.UserID)
@@ -887,8 +1021,8 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 			metadata["sender_name"] = sender.Nickname
 		}
 
-		triggered, strippedContent := c.checkGroupTrigger(content, isBotMentioned)
-		if !triggered {
+		respond, strippedContent := c.ShouldRespondInGroup(isBotMentioned, content)
+		if !respond {
 			logger.DebugCF("onebot", "Group message ignored (no trigger)", map[string]any{
 				"sender":       senderID,
 				"group":        groupIDStr,
@@ -923,12 +1057,21 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 
 	c.lastMessageID.Store(chatID, messageID)
 
-	if raw.MessageType == "group" && messageID != "" && messageID != "0" {
-		c.setMsgEmojiLike(messageID, 289, true)
-		c.pendingEmojiMsg.Store(chatID, messageID)
+	senderInfo := bus.SenderInfo{
+		Platform:    "onebot",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("onebot", senderID),
+		DisplayName: sender.Nickname,
 	}
 
-	c.HandleMessage(senderID, chatID, content, parsed.Media, metadata)
+	if !c.IsAllowedSender(senderInfo) {
+		logger.DebugCF("onebot", "Message rejected by allowlist (senderInfo)", map[string]any{
+			"sender": senderID,
+		})
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, messageID, senderID, chatID, content, parsed.Media, metadata, senderInfo)
 }
 
 func (c *OneBotChannel) isDuplicate(messageID string) bool {
@@ -960,23 +1103,3 @@ func truncate(s string, n int) string {
 	}
 	return string(runes[:n]) + "..."
 }
-
-func (c *OneBotChannel) checkGroupTrigger(
-	content string,
-	isBotMentioned bool,
-) (triggered bool, strippedContent string) {
-	if isBotMentioned {
-		return true, strings.TrimSpace(content)
-	}
-
-	for _, prefix := range c.config.GroupTriggerPrefix {
-		if prefix == "" {
-			continue
-		}
-		if strings.HasPrefix(content, prefix) {
-			return true, strings.TrimSpace(strings.TrimPrefix(content, prefix))
-		}
-	}
-
-	return false, content
-}
diff --git a/pkg/channels/pico/init.go b/pkg/channels/pico/init.go
new file mode 100644
index 000000000..96d764418
--- /dev/null
+++ b/pkg/channels/pico/init.go
@@ -0,0 +1,13 @@
+package pico
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("pico", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewPicoChannel(cfg.Channels.Pico, b)
+	})
+}
diff --git a/pkg/channels/pico/pico.go b/pkg/channels/pico/pico.go
new file mode 100644
index 000000000..8d8b62a67
--- /dev/null
+++ b/pkg/channels/pico/pico.go
@@ -0,0 +1,462 @@
+package pico
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"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"
+)
+
+// picoConn represents a single WebSocket connection.
+type picoConn struct {
+	id        string
+	conn      *websocket.Conn
+	sessionID string
+	writeMu   sync.Mutex
+	closed    atomic.Bool
+}
+
+// writeJSON sends a JSON message to the connection with write locking.
+func (pc *picoConn) writeJSON(v any) error {
+	if pc.closed.Load() {
+		return fmt.Errorf("connection closed")
+	}
+	pc.writeMu.Lock()
+	defer pc.writeMu.Unlock()
+	return pc.conn.WriteJSON(v)
+}
+
+// close closes the connection.
+func (pc *picoConn) close() {
+	if pc.closed.CompareAndSwap(false, true) {
+		pc.conn.Close()
+	}
+}
+
+// PicoChannel implements the native Pico Protocol WebSocket channel.
+// 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
+}
+
+// NewPicoChannel creates a new Pico Protocol channel.
+func NewPicoChannel(cfg config.PicoConfig, messageBus *bus.MessageBus) (*PicoChannel, error) {
+	if cfg.Token == "" {
+		return nil, fmt.Errorf("pico token is required")
+	}
+
+	base := channels.NewBaseChannel("pico", cfg, messageBus, cfg.AllowFrom)
+
+	allowOrigins := cfg.AllowOrigins
+	checkOrigin := func(r *http.Request) bool {
+		if len(allowOrigins) == 0 {
+			return true // allow all if not configured
+		}
+		origin := r.Header.Get("Origin")
+		for _, allowed := range allowOrigins {
+			if allowed == "*" || allowed == origin {
+				return true
+			}
+		}
+		return false
+	}
+
+	return &PicoChannel{
+		BaseChannel: base,
+		config:      cfg,
+		upgrader: websocket.Upgrader{
+			CheckOrigin:     checkOrigin,
+			ReadBufferSize:  1024,
+			WriteBufferSize: 1024,
+		},
+	}, nil
+}
+
+// Start implements Channel.
+func (c *PicoChannel) Start(ctx context.Context) error {
+	logger.InfoC("pico", "Starting Pico Protocol channel")
+	c.ctx, c.cancel = context.WithCancel(ctx)
+	c.SetRunning(true)
+	logger.InfoC("pico", "Pico Protocol channel started")
+	return nil
+}
+
+// Stop implements Channel.
+func (c *PicoChannel) Stop(ctx context.Context) error {
+	logger.InfoC("pico", "Stopping Pico Protocol channel")
+	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
+	})
+
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	logger.InfoC("pico", "Pico Protocol channel stopped")
+	return nil
+}
+
+// WebhookPath implements channels.WebhookHandler.
+func (c *PicoChannel) WebhookPath() string { return "/pico/" }
+
+// ServeHTTP implements http.Handler for the shared HTTP server.
+func (c *PicoChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	path := strings.TrimPrefix(r.URL.Path, "/pico")
+
+	switch {
+	case path == "/ws" || path == "/ws/":
+		c.handleWebSocket(w, r)
+	default:
+		http.NotFound(w, r)
+	}
+}
+
+// Send implements Channel — sends a message to the appropriate WebSocket connection.
+func (c *PicoChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	outMsg := newMessage(TypeMessageCreate, map[string]any{
+		"content": msg.Content,
+	})
+
+	return c.broadcastToSession(msg.ChatID, outMsg)
+}
+
+// EditMessage implements channels.MessageEditor.
+func (c *PicoChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
+	outMsg := newMessage(TypeMessageUpdate, map[string]any{
+		"message_id": messageID,
+		"content":    content,
+	})
+	return c.broadcastToSession(chatID, outMsg)
+}
+
+// StartTyping implements channels.TypingCapable.
+func (c *PicoChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	startMsg := newMessage(TypeTypingStart, nil)
+	if err := c.broadcastToSession(chatID, startMsg); err != nil {
+		return func() {}, err
+	}
+	return func() {
+		stopMsg := newMessage(TypeTypingStop, nil)
+		c.broadcastToSession(chatID, stopMsg)
+	}, nil
+}
+
+// SendPlaceholder implements channels.PlaceholderCapable.
+// It sends a placeholder message via the Pico Protocol that will later be
+// edited to the actual response via EditMessage (channels.MessageEditor).
+func (c *PicoChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	if !c.config.Placeholder.Enabled {
+		return "", nil
+	}
+
+	text := c.config.Placeholder.Text
+	if text == "" {
+		text = "Thinking... 💭"
+	}
+
+	msgID := uuid.New().String()
+	outMsg := newMessage(TypeMessageCreate, map[string]any{
+		"content":    text,
+		"message_id": msgID,
+	})
+
+	if err := c.broadcastToSession(chatID, outMsg); err != nil {
+		return "", err
+	}
+
+	return msgID, nil
+}
+
+// broadcastToSession sends a message to all connections with a matching session.
+func (c *PicoChannel) broadcastToSession(chatID string, msg PicoMessage) error {
+	// chatID format: "pico:<sessionID>"
+	sessionID := strings.TrimPrefix(chatID, "pico:")
+	msg.SessionID = sessionID
+
+	var sent bool
+	c.connections.Range(func(key, value any) bool {
+		pc, ok := value.(*picoConn)
+		if !ok {
+			return 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)
+	}
+	return nil
+}
+
+// handleWebSocket upgrades the HTTP connection and manages the WebSocket lifecycle.
+func (c *PicoChannel) handleWebSocket(w http.ResponseWriter, r *http.Request) {
+	if !c.IsRunning() {
+		http.Error(w, "channel not running", http.StatusServiceUnavailable)
+		return
+	}
+
+	// Authenticate
+	if !c.authenticate(r) {
+		http.Error(w, "unauthorized", http.StatusUnauthorized)
+		return
+	}
+
+	// Check connection limit
+	maxConns := c.config.MaxConnections
+	if maxConns <= 0 {
+		maxConns = 100
+	}
+	if int(c.connCount.Load()) >= maxConns {
+		http.Error(w, "too many connections", http.StatusServiceUnavailable)
+		return
+	}
+
+	conn, err := c.upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		logger.ErrorCF("pico", "WebSocket upgrade failed", map[string]any{
+			"error": err.Error(),
+		})
+		return
+	}
+
+	// Determine session ID from query param or generate one
+	sessionID := r.URL.Query().Get("session_id")
+	if sessionID == "" {
+		sessionID = uuid.New().String()
+	}
+
+	pc := &picoConn{
+		id:        uuid.New().String(),
+		conn:      conn,
+		sessionID: sessionID,
+	}
+
+	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,
+	})
+
+	go c.readLoop(pc)
+}
+
+// authenticate checks the Bearer token from the Authorization header.
+// Query parameter authentication is only allowed when AllowTokenQuery is explicitly enabled.
+func (c *PicoChannel) authenticate(r *http.Request) bool {
+	token := c.config.Token
+	if token == "" {
+		return false
+	}
+
+	// Check Authorization header
+	auth := r.Header.Get("Authorization")
+	if after, ok := strings.CutPrefix(auth, "Bearer "); ok {
+		if after == token {
+			return true
+		}
+	}
+
+	// Check query parameter only when explicitly allowed
+	if c.config.AllowTokenQuery {
+		if r.URL.Query().Get("token") == token {
+			return true
+		}
+	}
+
+	return false
+}
+
+// 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,
+		})
+	}()
+
+	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(appData string) error {
+		_ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+		return nil
+	})
+
+	// Start ping ticker
+	pingInterval := time.Duration(c.config.PingInterval) * time.Second
+	if pingInterval <= 0 {
+		pingInterval = 30 * time.Second
+	}
+	go c.pingLoop(pc, pingInterval)
+
+	for {
+		select {
+		case <-c.ctx.Done():
+			return
+		default:
+		}
+
+		_, rawMsg, err := pc.conn.ReadMessage()
+		if err != nil {
+			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
+				logger.DebugCF("pico", "WebSocket read error", map[string]any{
+					"conn_id": pc.id,
+					"error":   err.Error(),
+				})
+			}
+			return
+		}
+
+		_ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+
+		var msg PicoMessage
+		if err := json.Unmarshal(rawMsg, &msg); err != nil {
+			errMsg := newError("invalid_message", "failed to parse message")
+			pc.writeJSON(errMsg)
+			continue
+		}
+
+		c.handleMessage(pc, msg)
+	}
+}
+
+// pingLoop sends periodic ping frames to keep the connection alive.
+func (c *PicoChannel) pingLoop(pc *picoConn, interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-c.ctx.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
+			}
+		}
+	}
+}
+
+// handleMessage processes an inbound Pico Protocol message.
+func (c *PicoChannel) handleMessage(pc *picoConn, msg PicoMessage) {
+	switch msg.Type {
+	case TypePing:
+		pong := newMessage(TypePong, nil)
+		pong.ID = msg.ID
+		pc.writeJSON(pong)
+
+	case TypeMessageSend:
+		c.handleMessageSend(pc, msg)
+
+	default:
+		errMsg := newError("unknown_type", fmt.Sprintf("unknown message type: %s", msg.Type))
+		pc.writeJSON(errMsg)
+	}
+}
+
+// handleMessageSend processes an inbound message.send from a client.
+func (c *PicoChannel) handleMessageSend(pc *picoConn, msg PicoMessage) {
+	content, _ := msg.Payload["content"].(string)
+	if strings.TrimSpace(content) == "" {
+		errMsg := newError("empty_content", "message content is empty")
+		pc.writeJSON(errMsg)
+		return
+	}
+
+	sessionID := msg.SessionID
+	if sessionID == "" {
+		sessionID = pc.sessionID
+	}
+
+	chatID := "pico:" + sessionID
+	senderID := "pico-user"
+
+	peer := bus.Peer{Kind: "direct", ID: "pico:" + sessionID}
+
+	metadata := map[string]string{
+		"platform":   "pico",
+		"session_id": sessionID,
+		"conn_id":    pc.id,
+	}
+
+	logger.DebugCF("pico", "Received message", map[string]any{
+		"session_id": sessionID,
+		"preview":    truncate(content, 50),
+	})
+
+	sender := bus.SenderInfo{
+		Platform:    "pico",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("pico", senderID),
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, nil, metadata, sender)
+}
+
+// truncate truncates a string to maxLen runes.
+func truncate(s string, maxLen int) string {
+	runes := []rune(s)
+	if len(runes) <= maxLen {
+		return s
+	}
+	return string(runes[:maxLen]) + "..."
+}
diff --git a/pkg/channels/pico/protocol.go b/pkg/channels/pico/protocol.go
new file mode 100644
index 000000000..0a630e193
--- /dev/null
+++ b/pkg/channels/pico/protocol.go
@@ -0,0 +1,46 @@
+package pico
+
+import "time"
+
+// Protocol message types.
+const (
+	// TypeMessageSend is sent from client to server.
+	TypeMessageSend = "message.send"
+	TypeMediaSend   = "media.send"
+	TypePing        = "ping"
+
+	// TypeMessageCreate is sent from server to client.
+	TypeMessageCreate = "message.create"
+	TypeMessageUpdate = "message.update"
+	TypeMediaCreate   = "media.create"
+	TypeTypingStart   = "typing.start"
+	TypeTypingStop    = "typing.stop"
+	TypeError         = "error"
+	TypePong          = "pong"
+)
+
+// PicoMessage is the wire format for all Pico Protocol messages.
+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"`
+}
+
+// newMessage creates a PicoMessage with the given type and payload.
+func newMessage(msgType string, payload map[string]any) PicoMessage {
+	return PicoMessage{
+		Type:      msgType,
+		Timestamp: time.Now().UnixMilli(),
+		Payload:   payload,
+	}
+}
+
+// newError creates an error PicoMessage.
+func newError(code, message string) PicoMessage {
+	return newMessage(TypeError, map[string]any{
+		"code":    code,
+		"message": message,
+	})
+}
diff --git a/pkg/channels/qq/init.go b/pkg/channels/qq/init.go
new file mode 100644
index 000000000..15b955089
--- /dev/null
+++ b/pkg/channels/qq/init.go
@@ -0,0 +1,13 @@
+package qq
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("qq", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewQQChannel(cfg.Channels.QQ, b)
+	})
+}
diff --git a/pkg/channels/qq.go b/pkg/channels/qq/qq.go
similarity index 74%
rename from pkg/channels/qq.go
rename to pkg/channels/qq/qq.go
index b10776db6..112964143 100644
--- a/pkg/channels/qq.go
+++ b/pkg/channels/qq/qq.go
@@ -1,4 +1,4 @@
-package channels
+package qq
 
 import (
 	"context"
@@ -14,12 +14,14 @@ import (
 	"golang.org/x/oauth2"
 
 	"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"
 )
 
 type QQChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config         config.QQConfig
 	api            openapi.OpenAPI
 	tokenSource    oauth2.TokenSource
@@ -31,7 +33,10 @@ type QQChannel struct {
 }
 
 func NewQQChannel(cfg config.QQConfig, messageBus *bus.MessageBus) (*QQChannel, error) {
-	base := NewBaseChannel("qq", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("qq", cfg, messageBus, cfg.AllowFrom,
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
 
 	return &QQChannel{
 		BaseChannel:  base,
@@ -90,11 +95,11 @@ func (c *QQChannel) Start(ctx context.Context) error {
 			logger.ErrorCF("qq", "WebSocket session error", map[string]any{
 				"error": err.Error(),
 			})
-			c.setRunning(false)
+			c.SetRunning(false)
 		}
 	}()
 
-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("qq", "QQ bot started successfully")
 
 	return nil
@@ -102,7 +107,7 @@ func (c *QQChannel) Start(ctx context.Context) error {
 
 func (c *QQChannel) Stop(ctx context.Context) error {
 	logger.InfoC("qq", "Stopping QQ bot")
-	c.setRunning(false)
+	c.SetRunning(false)
 
 	if c.cancel != nil {
 		c.cancel()
@@ -113,7 +118,7 @@ func (c *QQChannel) Stop(ctx context.Context) error {
 
 func (c *QQChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("QQ bot not running")
+		return channels.ErrNotRunning
 	}
 
 	// construct message
@@ -127,7 +132,7 @@ func (c *QQChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 		logger.ErrorCF("qq", "Failed to send C2C message", map[string]any{
 			"error": err.Error(),
 		})
-		return err
+		return fmt.Errorf("qq send: %w", channels.ErrTemporary)
 	}
 
 	return nil
@@ -162,20 +167,35 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 			"length": len(content),
 		})
 
-		// forward to message bus
-		metadata := map[string]string{
-			"message_id": data.ID,
-			"peer_kind":  "direct",
-			"peer_id":    senderID,
+		// 转发到消息总线
+		metadata := map[string]string{}
+
+		sender := bus.SenderInfo{
+			Platform:    "qq",
+			PlatformID:  data.Author.ID,
+			CanonicalID: identity.BuildCanonicalID("qq", data.Author.ID),
 		}
 
-		c.HandleMessage(senderID, senderID, content, []string{}, metadata)
+		if !c.IsAllowedSender(sender) {
+			return nil
+		}
+
+		c.HandleMessage(c.ctx,
+			bus.Peer{Kind: "direct", ID: senderID},
+			data.ID,
+			senderID,
+			senderID,
+			content,
+			[]string{},
+			metadata,
+			sender,
+		)
 
 		return nil
 	}
 }
 
-// handleGroupATMessage handles group @messages
+// handleGroupATMessage handles QQ group @ messages
 func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 	return func(event *dto.WSPayload, data *dto.WSGroupATMessageData) error {
 		// deduplication check
@@ -192,34 +212,57 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 			return nil
 		}
 
-		// extract message content (remove @bot part)
+		// 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),
 		})
 
-		// forward to message bus (use GroupID as ChatID)
+		// 转发到消息总线（使用 GroupID 作为 ChatID）
 		metadata := map[string]string{
-			"message_id": data.ID,
-			"group_id":   data.GroupID,
-			"peer_kind":  "group",
-			"peer_id":    data.GroupID,
+			"group_id": data.GroupID,
 		}
 
-		c.HandleMessage(senderID, data.GroupID, content, []string{}, metadata)
+		sender := bus.SenderInfo{
+			Platform:    "qq",
+			PlatformID:  data.Author.ID,
+			CanonicalID: identity.BuildCanonicalID("qq", data.Author.ID),
+		}
+
+		if !c.IsAllowedSender(sender) {
+			return nil
+		}
+
+		c.HandleMessage(c.ctx,
+			bus.Peer{Kind: "group", ID: data.GroupID},
+			data.ID,
+			senderID,
+			data.GroupID,
+			content,
+			[]string{},
+			metadata,
+			sender,
+		)
 
 		return nil
 	}
 }
 
-// isDuplicate checks if message is duplicate
+// isDuplicate 检查消息是否重复
 func (c *QQChannel) isDuplicate(messageID string) bool {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -230,9 +273,9 @@ func (c *QQChannel) isDuplicate(messageID string) bool {
 
 	c.processedIDs[messageID] = true
 
-	// simple cleanup: limit map size
+	// 简单清理：限制 map 大小
 	if len(c.processedIDs) > 10000 {
-		// clear half
+		// 清空一半
 		count := 0
 		for id := range c.processedIDs {
 			if count >= 5000 {
diff --git a/pkg/channels/registry.go b/pkg/channels/registry.go
new file mode 100644
index 000000000..36a05bf3e
--- /dev/null
+++ b/pkg/channels/registry.go
@@ -0,0 +1,32 @@
+package channels
+
+import (
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// ChannelFactory is a constructor function that creates a Channel from config and message bus.
+// Each channel subpackage registers one or more factories via init().
+type ChannelFactory func(cfg *config.Config, bus *bus.MessageBus) (Channel, error)
+
+var (
+	factoriesMu sync.RWMutex
+	factories   = map[string]ChannelFactory{}
+)
+
+// RegisterFactory registers a named channel factory. Called from subpackage init() functions.
+func RegisterFactory(name string, f ChannelFactory) {
+	factoriesMu.Lock()
+	defer factoriesMu.Unlock()
+	factories[name] = f
+}
+
+// getFactory looks up a channel factory by name.
+func getFactory(name string) (ChannelFactory, bool) {
+	factoriesMu.RLock()
+	defer factoriesMu.RUnlock()
+	f, ok := factories[name]
+	return f, ok
+}
diff --git a/pkg/channels/slack/init.go b/pkg/channels/slack/init.go
new file mode 100644
index 000000000..c131bb291
--- /dev/null
+++ b/pkg/channels/slack/init.go
@@ -0,0 +1,13 @@
+package slack
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("slack", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewSlackChannel(cfg.Channels.Slack, b)
+	})
+}
diff --git a/pkg/channels/slack.go b/pkg/channels/slack/slack.go
similarity index 65%
rename from pkg/channels/slack.go
rename to pkg/channels/slack/slack.go
index f087aa8da..024b1b023 100644
--- a/pkg/channels/slack.go
+++ b/pkg/channels/slack/slack.go
@@ -1,32 +1,31 @@
-package channels
+package slack
 
 import (
 	"context"
 	"fmt"
-	"os"
 	"strings"
 	"sync"
-	"time"
 
 	"github.com/slack-go/slack"
 	"github.com/slack-go/slack/slackevents"
 	"github.com/slack-go/slack/socketmode"
 
 	"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"
 	"github.com/sipeed/picoclaw/pkg/utils"
-	"github.com/sipeed/picoclaw/pkg/voice"
 )
 
 type SlackChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config       config.SlackConfig
 	api          *slack.Client
 	socketClient *socketmode.Client
 	botUserID    string
 	teamID       string
-	transcriber  *voice.GroqTranscriber
 	ctx          context.Context
 	cancel       context.CancelFunc
 	pendingAcks  sync.Map
@@ -49,7 +48,11 @@ func NewSlackChannel(cfg config.SlackConfig, messageBus *bus.MessageBus) (*Slack
 
 	socketClient := socketmode.New(api)
 
-	base := NewBaseChannel("slack", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("slack", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(40000),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
 
 	return &SlackChannel{
 		BaseChannel:  base,
@@ -59,10 +62,6 @@ func NewSlackChannel(cfg config.SlackConfig, messageBus *bus.MessageBus) (*Slack
 	}, nil
 }
 
-func (c *SlackChannel) SetTranscriber(transcriber *voice.GroqTranscriber) {
-	c.transcriber = transcriber
-}
-
 func (c *SlackChannel) Start(ctx context.Context) error {
 	logger.InfoC("slack", "Starting Slack channel (Socket Mode)")
 
@@ -92,7 +91,7 @@ func (c *SlackChannel) Start(ctx context.Context) error {
 		}
 	}()
 
-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("slack", "Slack channel started (Socket Mode)")
 	return nil
 }
@@ -104,14 +103,14 @@ func (c *SlackChannel) Stop(ctx context.Context) error {
 		c.cancel()
 	}
 
-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("slack", "Slack channel stopped")
 	return nil
 }
 
 func (c *SlackChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("slack channel not running")
+		return channels.ErrNotRunning
 	}
 
 	channelID, threadTS := parseSlackChatID(msg.ChatID)
@@ -129,7 +128,7 @@ func (c *SlackChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
 
 	_, _, err := c.api.PostMessageContext(ctx, channelID, opts...)
 	if err != nil {
-		return fmt.Errorf("failed to send slack message: %w", err)
+		return fmt.Errorf("slack send: %w", channels.ErrTemporary)
 	}
 
 	if ref, ok := c.pendingAcks.LoadAndDelete(msg.ChatID); ok {
@@ -148,6 +147,82 @@ func (c *SlackChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
 	return nil
 }
 
+// SendMedia implements the channels.MediaSender interface.
+func (c *SlackChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	channelID, _ := parseSlackChatID(msg.ChatID)
+	if channelID == "" {
+		return fmt.Errorf("invalid slack chat ID: %s", msg.ChatID)
+	}
+
+	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("slack", "Failed to resolve media ref", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		filename := part.Filename
+		if filename == "" {
+			filename = "file"
+		}
+
+		title := part.Caption
+		if title == "" {
+			title = filename
+		}
+
+		_, err = c.api.UploadFileV2Context(ctx, slack.UploadFileV2Parameters{
+			Channel:  channelID,
+			File:     localPath,
+			Filename: filename,
+			Title:    title,
+		})
+		if err != nil {
+			logger.ErrorCF("slack", "Failed to upload media", map[string]any{
+				"filename": filename,
+				"error":    err.Error(),
+			})
+			return fmt.Errorf("slack send media: %w", channels.ErrTemporary)
+		}
+	}
+
+	return nil
+}
+
+// ReactToMessage implements channels.ReactionCapable.
+// It adds an "eyes" (👀) reaction to the inbound message and returns an undo function
+// that removes the reaction.
+func (c *SlackChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (func(), error) {
+	channelID, _ := parseSlackChatID(chatID)
+	if channelID == "" {
+		return func() {}, nil
+	}
+
+	c.api.AddReaction("eyes", slack.ItemRef{
+		Channel:   channelID,
+		Timestamp: messageID,
+	})
+
+	return func() {
+		c.api.RemoveReaction("eyes", slack.ItemRef{
+			Channel:   channelID,
+			Timestamp: messageID,
+		})
+	}, nil
+}
+
 func (c *SlackChannel) eventLoop() {
 	for {
 		select {
@@ -201,7 +276,12 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 	}
 
 	// check allowlist to avoid downloading attachments for rejected users
-	if !c.IsAllowed(ev.User) {
+	sender := bus.SenderInfo{
+		Platform:    "slack",
+		PlatformID:  ev.User,
+		CanonicalID: identity.BuildCanonicalID("slack", ev.User),
+	}
+	if !c.IsAllowedSender(sender) {
 		logger.DebugCF("slack", "Message rejected by allowlist", map[string]any{
 			"user_id": ev.User,
 		})
@@ -218,11 +298,6 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 		chatID = channelID + "/" + threadTS
 	}
 
-	c.api.AddReaction("eyes", slack.ItemRef{
-		Channel:   channelID,
-		Timestamp: messageTS,
-	})
-
 	c.pendingAcks.Store(chatID, slackMessageRef{
 		ChannelID: channelID,
 		Timestamp: messageTS,
@@ -231,20 +306,32 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 	content := ev.Text
 	content = c.stripBotMention(content)
 
-	var mediaPaths []string
-	localFiles := []string{} // track local files that need cleanup
+	// In non-DM channels, apply group trigger filtering
+	if !strings.HasPrefix(channelID, "D") {
+		respond, cleaned := c.ShouldRespondInGroup(false, content)
+		if !respond {
+			return
+		}
+		content = cleaned
+	}
 
-	// ensure temp files are cleaned up when function returns
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("slack", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	var mediaPaths []string
+
+	scope := channels.BuildMediaScope("slack", chatID, messageTS)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "slack",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback
+	}
 
 	if ev.Message != nil && len(ev.Message.Files) > 0 {
 		for _, file := range ev.Message.Files {
@@ -252,23 +339,8 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 			if localPath == "" {
 				continue
 			}
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
-
-			if utils.IsAudioFile(file.Name, file.Mimetype) && c.transcriber != nil && c.transcriber.IsAvailable() {
-				ctx, cancel := context.WithTimeout(c.ctx, 30*time.Second)
-				defer cancel()
-				result, err := c.transcriber.Transcribe(ctx, localPath)
-
-				if err != nil {
-					logger.ErrorCF("slack", "Voice transcription failed", map[string]any{"error": err.Error()})
-					content += fmt.Sprintf("\n[audio: %s (transcription failed)]", file.Name)
-				} else {
-					content += fmt.Sprintf("\n[voice transcription: %s]", result.Text)
-				}
-			} else {
-				content += fmt.Sprintf("\n[file: %s]", file.Name)
-			}
+			mediaPaths = append(mediaPaths, storeMedia(localPath, file.Name))
+			content += fmt.Sprintf("\n[file: %s]", file.Name)
 		}
 	}
 
@@ -283,13 +355,13 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 		peerID = senderID
 	}
 
+	peer := bus.Peer{Kind: peerKind, ID: peerID}
+
 	metadata := map[string]string{
 		"message_ts": messageTS,
 		"channel_id": channelID,
 		"thread_ts":  threadTS,
 		"platform":   "slack",
-		"peer_kind":  peerKind,
-		"peer_id":    peerID,
 		"team_id":    c.teamID,
 	}
 
@@ -300,7 +372,7 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 		"has_thread": threadTS != "",
 	})
 
-	c.HandleMessage(senderID, chatID, content, mediaPaths, metadata)
+	c.HandleMessage(c.ctx, peer, messageTS, senderID, chatID, content, mediaPaths, metadata, sender)
 }
 
 func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) {
@@ -308,7 +380,11 @@ func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) {
 		return
 	}
 
-	if !c.IsAllowed(ev.User) {
+	if !c.IsAllowedSender(bus.SenderInfo{
+		Platform:    "slack",
+		PlatformID:  ev.User,
+		CanonicalID: identity.BuildCanonicalID("slack", ev.User),
+	}) {
 		logger.DebugCF("slack", "Mention rejected by allowlist", map[string]any{
 			"user_id": ev.User,
 		})
@@ -316,6 +392,11 @@ func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) {
 	}
 
 	senderID := ev.User
+	mentionSender := bus.SenderInfo{
+		Platform:    "slack",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("slack", senderID),
+	}
 	channelID := ev.Channel
 	threadTS := ev.ThreadTimeStamp
 	messageTS := ev.TimeStamp
@@ -327,11 +408,6 @@ func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) {
 		chatID = channelID + "/" + messageTS
 	}
 
-	c.api.AddReaction("eyes", slack.ItemRef{
-		Channel:   channelID,
-		Timestamp: messageTS,
-	})
-
 	c.pendingAcks.Store(chatID, slackMessageRef{
 		ChannelID: channelID,
 		Timestamp: messageTS,
@@ -350,18 +426,18 @@ func (c *SlackChannel) handleAppMention(ev *slackevents.AppMentionEvent) {
 		mentionPeerID = senderID
 	}
 
+	mentionPeer := bus.Peer{Kind: mentionPeerKind, ID: mentionPeerID}
+
 	metadata := map[string]string{
 		"message_ts": messageTS,
 		"channel_id": channelID,
 		"thread_ts":  threadTS,
 		"platform":   "slack",
 		"is_mention": "true",
-		"peer_kind":  mentionPeerKind,
-		"peer_id":    mentionPeerID,
 		"team_id":    c.teamID,
 	}
 
-	c.HandleMessage(senderID, chatID, content, nil, metadata)
+	c.HandleMessage(c.ctx, mentionPeer, messageTS, senderID, chatID, content, nil, metadata, mentionSender)
 }
 
 func (c *SlackChannel) handleSlashCommand(event socketmode.Event) {
@@ -374,7 +450,12 @@ func (c *SlackChannel) handleSlashCommand(event socketmode.Event) {
 		c.socketClient.Ack(*event.Request)
 	}
 
-	if !c.IsAllowed(cmd.UserID) {
+	cmdSender := bus.SenderInfo{
+		Platform:    "slack",
+		PlatformID:  cmd.UserID,
+		CanonicalID: identity.BuildCanonicalID("slack", cmd.UserID),
+	}
+	if !c.IsAllowedSender(cmdSender) {
 		logger.DebugCF("slack", "Slash command rejected by allowlist", map[string]any{
 			"user_id": cmd.UserID,
 		})
@@ -395,8 +476,6 @@ func (c *SlackChannel) handleSlashCommand(event socketmode.Event) {
 		"platform":   "slack",
 		"is_command": "true",
 		"trigger_id": cmd.TriggerID,
-		"peer_kind":  "channel",
-		"peer_id":    channelID,
 		"team_id":    c.teamID,
 	}
 
@@ -406,7 +485,17 @@ func (c *SlackChannel) handleSlashCommand(event socketmode.Event) {
 		"text":      utils.Truncate(content, 50),
 	})
 
-	c.HandleMessage(senderID, chatID, content, nil, metadata)
+	c.HandleMessage(
+		c.ctx,
+		bus.Peer{Kind: "channel", ID: channelID},
+		"",
+		senderID,
+		chatID,
+		content,
+		nil,
+		metadata,
+		cmdSender,
+	)
 }
 
 func (c *SlackChannel) downloadSlackFile(file slack.File) string {
@@ -439,5 +528,5 @@ func parseSlackChatID(chatID string) (channelID, threadTS string) {
 	if len(parts) > 1 {
 		threadTS = parts[1]
 	}
-	return
+	return channelID, threadTS
 }
diff --git a/pkg/channels/slack_test.go b/pkg/channels/slack/slack_test.go
similarity index 99%
rename from pkg/channels/slack_test.go
rename to pkg/channels/slack/slack_test.go
index 3707c2703..30e0d2d73 100644
--- a/pkg/channels/slack_test.go
+++ b/pkg/channels/slack/slack_test.go
@@ -1,4 +1,4 @@
-package channels
+package slack
 
 import (
 	"testing"
diff --git a/pkg/channels/split.go b/pkg/channels/split.go
new file mode 100644
index 000000000..bb26c6d8f
--- /dev/null
+++ b/pkg/channels/split.go
@@ -0,0 +1,208 @@
+package channels
+
+import (
+	"strings"
+)
+
+// SplitMessage splits long messages into chunks, preserving code block integrity.
+// The maxLen parameter is measured in runes (Unicode characters), not bytes.
+// The function reserves a buffer (10% of maxLen, min 50) to leave room for closing code blocks,
+// but may extend to maxLen when needed.
+// Call SplitMessage with the full text content and the maximum allowed length of a single message;
+// it returns a slice of message chunks that each respect maxLen and avoid splitting fenced code blocks.
+func SplitMessage(content string, maxLen int) []string {
+	if maxLen <= 0 {
+		if content == "" {
+			return nil
+		}
+		return []string{content}
+	}
+
+	runes := []rune(content)
+	totalLen := len(runes)
+	var messages []string
+
+	// Dynamic buffer: 10% of maxLen, but at least 50 chars if possible
+	codeBlockBuffer := max(maxLen/10, 50)
+	if codeBlockBuffer > maxLen/2 {
+		codeBlockBuffer = maxLen / 2
+	}
+
+	start := 0
+	for start < totalLen {
+		remaining := totalLen - start
+		if remaining <= maxLen {
+			messages = append(messages, string(runes[start:totalLen]))
+			break
+		}
+
+		// Effective split point: maxLen minus buffer, to leave room for code blocks
+		effectiveLimit := max(maxLen-codeBlockBuffer, maxLen/2)
+
+		end := start + effectiveLimit
+
+		// Find natural split point within the effective limit
+		msgEnd := findLastNewlineInRange(runes, start, end, 200)
+		if msgEnd <= start {
+			msgEnd = findLastSpaceInRange(runes, start, end, 100)
+		}
+		if msgEnd <= start {
+			msgEnd = end
+		}
+
+		// Check if this would end with an incomplete code block
+		unclosedIdx := findLastUnclosedCodeBlockInRange(runes, start, msgEnd)
+
+		if unclosedIdx >= 0 {
+			// Message would end with incomplete code block
+			// Try to extend up to maxLen to include the closing ```
+			if totalLen > msgEnd {
+				closingIdx := findNextClosingCodeBlockInRange(runes, msgEnd, totalLen)
+				if closingIdx > 0 && closingIdx-start <= maxLen {
+					// Extend to include the closing ```
+					msgEnd = closingIdx
+				} else {
+					// Code block is too long to fit in one chunk or missing closing fence.
+					// Try to split inside by injecting closing and reopening fences.
+					headerEnd := findNewlineFrom(runes, unclosedIdx)
+					var header string
+					if headerEnd == -1 {
+						header = strings.TrimSpace(string(runes[unclosedIdx : unclosedIdx+3]))
+					} else {
+						header = strings.TrimSpace(string(runes[unclosedIdx:headerEnd]))
+					}
+					headerEndIdx := unclosedIdx + len([]rune(header))
+					if headerEnd != -1 {
+						headerEndIdx = headerEnd
+					}
+
+					// If we have a reasonable amount of content after the header, split inside
+					if msgEnd > headerEndIdx+20 {
+						// Find a better split point closer to maxLen
+						innerLimit := min(
+							// Leave room for "\n```"
+							start+maxLen-5, totalLen)
+						betterEnd := findLastNewlineInRange(runes, start, innerLimit, 200)
+						if betterEnd > headerEndIdx {
+							msgEnd = betterEnd
+						} else {
+							msgEnd = innerLimit
+						}
+						chunk := strings.TrimRight(string(runes[start:msgEnd]), " \t\n\r") + "\n```"
+						messages = append(messages, chunk)
+						remaining := strings.TrimSpace(header + "\n" + string(runes[msgEnd:totalLen]))
+						// Replace the tail of runes with the reconstructed remaining
+						runes = []rune(remaining)
+						totalLen = len(runes)
+						start = 0
+						continue
+					}
+
+					// Otherwise, try to split before the code block starts
+					newEnd := findLastNewlineInRange(runes, start, unclosedIdx, 200)
+					if newEnd <= start {
+						newEnd = findLastSpaceInRange(runes, start, unclosedIdx, 100)
+					}
+					if newEnd > start {
+						msgEnd = newEnd
+					} else {
+						// If we can't split before, we MUST split inside (last resort)
+						if unclosedIdx-start > 20 {
+							msgEnd = unclosedIdx
+						} else {
+							splitAt := min(start+maxLen-5, totalLen)
+							chunk := strings.TrimRight(string(runes[start:splitAt]), " \t\n\r") + "\n```"
+							messages = append(messages, chunk)
+							remaining := strings.TrimSpace(header + "\n" + string(runes[splitAt:totalLen]))
+							runes = []rune(remaining)
+							totalLen = len(runes)
+							start = 0
+							continue
+						}
+					}
+				}
+			}
+		}
+
+		if msgEnd <= start {
+			msgEnd = start + effectiveLimit
+		}
+
+		messages = append(messages, string(runes[start:msgEnd]))
+		// Advance start, skipping leading whitespace of next chunk
+		start = msgEnd
+		for start < totalLen && (runes[start] == ' ' || runes[start] == '\t' || runes[start] == '\n' || runes[start] == '\r') {
+			start++
+		}
+	}
+
+	return messages
+}
+
+// findLastUnclosedCodeBlockInRange finds the last opening ``` that doesn't have a closing ```
+// within runes[start:end]. Returns the absolute rune index or -1.
+func findLastUnclosedCodeBlockInRange(runes []rune, start, end int) int {
+	inCodeBlock := false
+	lastOpenIdx := -1
+
+	for i := start; i < end; i++ {
+		if i+2 < end && runes[i] == '`' && runes[i+1] == '`' && runes[i+2] == '`' {
+			if !inCodeBlock {
+				lastOpenIdx = i
+			}
+			inCodeBlock = !inCodeBlock
+			i += 2
+		}
+	}
+
+	if inCodeBlock {
+		return lastOpenIdx
+	}
+	return -1
+}
+
+// findNextClosingCodeBlockInRange finds the next closing ``` starting from startIdx
+// within runes[startIdx:end]. Returns the absolute index after the closing ``` or -1.
+func findNextClosingCodeBlockInRange(runes []rune, startIdx, end int) int {
+	for i := startIdx; i < end; i++ {
+		if i+2 < end && runes[i] == '`' && runes[i+1] == '`' && runes[i+2] == '`' {
+			return i + 3
+		}
+	}
+	return -1
+}
+
+// findNewlineFrom finds the first newline character starting from the given index.
+// Returns the absolute index or -1 if not found.
+func findNewlineFrom(runes []rune, from int) int {
+	for i := from; i < len(runes); i++ {
+		if runes[i] == '\n' {
+			return i
+		}
+	}
+	return -1
+}
+
+// findLastNewlineInRange finds the last newline within the last searchWindow runes
+// of the range runes[start:end]. Returns the absolute index or start-1 (indicating not found).
+func findLastNewlineInRange(runes []rune, start, end, searchWindow int) int {
+	searchStart := max(end-searchWindow, start)
+	for i := end - 1; i >= searchStart; i-- {
+		if runes[i] == '\n' {
+			return i
+		}
+	}
+	return start - 1
+}
+
+// findLastSpaceInRange finds the last space/tab within the last searchWindow runes
+// of the range runes[start:end]. Returns the absolute index or start-1 (indicating not found).
+func findLastSpaceInRange(runes []rune, start, end, searchWindow int) int {
+	searchStart := max(end-searchWindow, start)
+	for i := end - 1; i >= searchStart; i-- {
+		if runes[i] == ' ' || runes[i] == '\t' {
+			return i
+		}
+	}
+	return start - 1
+}
diff --git a/pkg/channels/split_test.go b/pkg/channels/split_test.go
new file mode 100644
index 000000000..a922f9558
--- /dev/null
+++ b/pkg/channels/split_test.go
@@ -0,0 +1,362 @@
+package channels
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestSplitMessage(t *testing.T) {
+	longText := strings.Repeat("a", 2500)
+	longCode := "```go\n" + strings.Repeat("fmt.Println(\"hello\")\n", 100) + "```" // ~2100 chars
+
+	tests := []struct {
+		name         string
+		content      string
+		maxLen       int
+		expectChunks int                                 // Check number of chunks
+		checkContent func(t *testing.T, chunks []string) // Custom validation
+	}{
+		{
+			name:         "Empty message",
+			content:      "",
+			maxLen:       2000,
+			expectChunks: 0,
+		},
+		{
+			name:         "Short message fits in one chunk",
+			content:      "Hello world",
+			maxLen:       2000,
+			expectChunks: 1,
+		},
+		{
+			name:         "Simple split regular text",
+			content:      longText,
+			maxLen:       2000,
+			expectChunks: 2,
+			checkContent: func(t *testing.T, chunks []string) {
+				if len([]rune(chunks[0])) > 2000 {
+					t.Errorf("Chunk 0 too large: %d runes", len([]rune(chunks[0])))
+				}
+				if len([]rune(chunks[0]))+len([]rune(chunks[1])) != len([]rune(longText)) {
+					t.Errorf(
+						"Total rune length mismatch. Got %d, want %d",
+						len([]rune(chunks[0]))+len([]rune(chunks[1])),
+						len([]rune(longText)),
+					)
+				}
+			},
+		},
+		{
+			name: "Split at newline",
+			// 1750 chars then newline, then more chars.
+			// Dynamic buffer: 2000 / 10 = 200.
+			// Effective limit: 2000 - 200 = 1800.
+			// Split should happen at newline because it's at 1750 (< 1800).
+			// Total length must > 2000 to trigger split. 1750 + 1 + 300 = 2051.
+			content:      strings.Repeat("a", 1750) + "\n" + strings.Repeat("b", 300),
+			maxLen:       2000,
+			expectChunks: 2,
+			checkContent: func(t *testing.T, chunks []string) {
+				if len([]rune(chunks[0])) != 1750 {
+					t.Errorf("Expected chunk 0 to be 1750 runes (split at newline), got %d", len([]rune(chunks[0])))
+				}
+				if chunks[1] != strings.Repeat("b", 300) {
+					t.Errorf("Chunk 1 content mismatch. Len: %d", len([]rune(chunks[1])))
+				}
+			},
+		},
+		{
+			name:         "Long code block split",
+			content:      "Prefix\n" + longCode,
+			maxLen:       2000,
+			expectChunks: 2,
+			checkContent: func(t *testing.T, chunks []string) {
+				// Check that first chunk ends with closing fence
+				if !strings.HasSuffix(chunks[0], "\n```") {
+					t.Error("First chunk should end with injected closing fence")
+				}
+				// Check that second chunk starts with execution header
+				if !strings.HasPrefix(chunks[1], "```go") {
+					t.Error("Second chunk should start with injected code block header")
+				}
+			},
+		},
+		{
+			name:         "Preserve Unicode characters (rune-aware)",
+			content:      strings.Repeat("\u4e16", 2500), // 2500 runes, 7500 bytes
+			maxLen:       2000,
+			expectChunks: 2,
+			checkContent: func(t *testing.T, chunks []string) {
+				// Verify chunks contain valid unicode and don't split mid-rune
+				for i, chunk := range chunks {
+					runeCount := len([]rune(chunk))
+					if runeCount > 2000 {
+						t.Errorf("Chunk %d has %d runes, exceeds maxLen 2000", i, runeCount)
+					}
+					if !strings.Contains(chunk, "\u4e16") {
+						t.Errorf("Chunk %d should contain unicode characters", i)
+					}
+				}
+				// Verify total rune count is preserved
+				totalRunes := 0
+				for _, chunk := range chunks {
+					totalRunes += len([]rune(chunk))
+				}
+				if totalRunes != 2500 {
+					t.Errorf("Total rune count mismatch. Got %d, want 2500", totalRunes)
+				}
+			},
+		},
+		{
+			name:         "Zero maxLen returns single chunk",
+			content:      "Hello world",
+			maxLen:       0,
+			expectChunks: 1,
+			checkContent: func(t *testing.T, chunks []string) {
+				if chunks[0] != "Hello world" {
+					t.Errorf("Expected original content, got %q", chunks[0])
+				}
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := SplitMessage(tc.content, tc.maxLen)
+
+			if tc.expectChunks == 0 {
+				if len(got) != 0 {
+					t.Errorf("Expected 0 chunks, got %d", len(got))
+				}
+				return
+			}
+
+			if len(got) != tc.expectChunks {
+				t.Errorf("Expected %d chunks, got %d", tc.expectChunks, len(got))
+				// Log sizes for debugging
+				for i, c := range got {
+					t.Logf("Chunk %d length: %d", i, len(c))
+				}
+				return // Stop further checks if count assumes specific split
+			}
+
+			if tc.checkContent != nil {
+				tc.checkContent(t, got)
+			}
+		})
+	}
+}
+
+// --- Helper function tests for index-based rune operations ---
+
+func TestFindLastNewlineInRange(t *testing.T) {
+	runes := []rune("aaa\nbbb\nccc")
+	// Indices:        0123 4567 89 10
+
+	tests := []struct {
+		name         string
+		start, end   int
+		searchWindow int
+		want         int
+	}{
+		{"finds last newline in full range", 0, 11, 200, 7},
+		{"finds newline within search window", 0, 11, 4, 7},
+		{"narrow window misses newline outside window", 4, 11, 3, 3}, // returns start-1 (not found)
+		{"no newline in range", 0, 3, 200, -1},                       // start-1 = -1
+		{"range limited to first segment", 0, 4, 200, 3},
+		{"search window of 1 at newline", 0, 8, 1, 7},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := findLastNewlineInRange(runes, tc.start, tc.end, tc.searchWindow)
+			if got != tc.want {
+				t.Errorf("findLastNewlineInRange(runes, %d, %d, %d) = %d, want %d",
+					tc.start, tc.end, tc.searchWindow, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestFindLastSpaceInRange(t *testing.T) {
+	runes := []rune("abc def\tghi")
+	// Indices:        0123 4567 89 10
+
+	tests := []struct {
+		name         string
+		start, end   int
+		searchWindow int
+		want         int
+	}{
+		{"finds tab as last space/tab", 0, 11, 200, 7},
+		{"finds space when tab out of window", 0, 7, 200, 3},
+		{"no space in range", 0, 3, 200, -1},
+		{"narrow window finds tab", 5, 11, 4, 7},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := findLastSpaceInRange(runes, tc.start, tc.end, tc.searchWindow)
+			if got != tc.want {
+				t.Errorf("findLastSpaceInRange(runes, %d, %d, %d) = %d, want %d",
+					tc.start, tc.end, tc.searchWindow, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestFindNewlineFrom(t *testing.T) {
+	runes := []rune("hello\nworld\n")
+
+	tests := []struct {
+		name string
+		from int
+		want int
+	}{
+		{"from start", 0, 5},
+		{"from after first newline", 6, 11},
+		{"from past all newlines", 12, -1},
+		{"from newline itself", 5, 5},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := findNewlineFrom(runes, tc.from)
+			if got != tc.want {
+				t.Errorf("findNewlineFrom(runes, %d) = %d, want %d", tc.from, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestFindLastUnclosedCodeBlockInRange(t *testing.T) {
+	tests := []struct {
+		name       string
+		content    string
+		start, end int
+		want       int
+	}{
+		{
+			name:    "no code blocks",
+			content: "hello world",
+			start:   0, end: 11,
+			want: -1,
+		},
+		{
+			name:    "complete code block",
+			content: "```go\ncode\n```",
+			start:   0, end: 14,
+			want: -1,
+		},
+		{
+			name:    "unclosed code block",
+			content: "text\n```go\ncode here",
+			start:   0, end: 20,
+			want: 5,
+		},
+		{
+			name:    "closed then unclosed",
+			content: "```a\n```\n```b\ncode",
+			start:   0, end: 17,
+			want: 9,
+		},
+		{
+			name:    "search within subrange",
+			content: "```a\n```\n```b\ncode",
+			start:   9, end: 17,
+			want: 9,
+		},
+		{
+			name:    "subrange with no code blocks",
+			content: "```a\n```\nhello",
+			start:   9, end: 14,
+			want: -1,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			runes := []rune(tc.content)
+			got := findLastUnclosedCodeBlockInRange(runes, tc.start, tc.end)
+			if got != tc.want {
+				t.Errorf("findLastUnclosedCodeBlockInRange(%q, %d, %d) = %d, want %d",
+					tc.content, tc.start, tc.end, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestFindNextClosingCodeBlockInRange(t *testing.T) {
+	tests := []struct {
+		name     string
+		content  string
+		startIdx int
+		end      int
+		want     int
+	}{
+		{
+			name:     "finds closing fence",
+			content:  "code\n```\nmore",
+			startIdx: 0, end: 13,
+			want: 8, // position after ```
+		},
+		{
+			name:     "no closing fence",
+			content:  "just code here",
+			startIdx: 0, end: 14,
+			want: -1,
+		},
+		{
+			name:     "fence at start of search",
+			content:  "```end",
+			startIdx: 0, end: 6,
+			want: 3,
+		},
+		{
+			name:     "fence outside range",
+			content:  "code\n```",
+			startIdx: 0, end: 4,
+			want: -1,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			runes := []rune(tc.content)
+			got := findNextClosingCodeBlockInRange(runes, tc.startIdx, tc.end)
+			if got != tc.want {
+				t.Errorf("findNextClosingCodeBlockInRange(%q, %d, %d) = %d, want %d",
+					tc.content, tc.startIdx, tc.end, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestSplitMessage_CodeBlockIntegrity(t *testing.T) {
+	// Focused test for the core requirement: splitting inside a code block preserves syntax highlighting
+
+	// 60 chars total approximately
+	content := "```go\npackage main\n\nfunc main() {\n\tprintln(\"Hello\")\n}\n```"
+	maxLen := 40
+
+	chunks := SplitMessage(content, maxLen)
+
+	if len(chunks) != 2 {
+		t.Fatalf("Expected 2 chunks, got %d: %q", len(chunks), chunks)
+	}
+
+	// First chunk must end with "\n```"
+	if !strings.HasSuffix(chunks[0], "\n```") {
+		t.Errorf("First chunk should end with closing fence. Got: %q", chunks[0])
+	}
+
+	// Second chunk must start with the header "```go"
+	if !strings.HasPrefix(chunks[1], "```go") {
+		t.Errorf("Second chunk should start with code block header. Got: %q", chunks[1])
+	}
+
+	// First chunk should contain meaningful content
+	if len([]rune(chunks[0])) > 40 {
+		t.Errorf("First chunk exceeded maxLen: length %d runes", len([]rune(chunks[0])))
+	}
+}
diff --git a/pkg/channels/telegram.go b/pkg/channels/telegram.go
deleted file mode 100644
index 5cd51e8bc..000000000
--- a/pkg/channels/telegram.go
+++ /dev/null
@@ -1,529 +0,0 @@
-package channels
-
-import (
-	"context"
-	"fmt"
-	"net/http"
-	"net/url"
-	"os"
-	"regexp"
-	"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/config"
-	"github.com/sipeed/picoclaw/pkg/logger"
-	"github.com/sipeed/picoclaw/pkg/utils"
-	"github.com/sipeed/picoclaw/pkg/voice"
-)
-
-type TelegramChannel struct {
-	*BaseChannel
-	bot          *telego.Bot
-	commands     TelegramCommander
-	config       *config.Config
-	chatIDs      map[string]int64
-	transcriber  *voice.GroqTranscriber
-	placeholders sync.Map // chatID -> messageID
-	stopThinking sync.Map // chatID -> thinkingCancel
-}
-
-type thinkingCancel struct {
-	fn context.CancelFunc
-}
-
-func (c *thinkingCancel) Cancel() {
-	if c != nil && c.fn != nil {
-		c.fn()
-	}
-}
-
-func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
-	var opts []telego.BotOption
-	telegramCfg := cfg.Channels.Telegram
-
-	if telegramCfg.Proxy != "" {
-		proxyURL, parseErr := url.Parse(telegramCfg.Proxy)
-		if parseErr != nil {
-			return nil, fmt.Errorf("invalid proxy URL %q: %w", telegramCfg.Proxy, parseErr)
-		}
-		opts = append(opts, telego.WithHTTPClient(&http.Client{
-			Transport: &http.Transport{
-				Proxy: http.ProxyURL(proxyURL),
-			},
-		}))
-	} else if os.Getenv("HTTP_PROXY") != "" || os.Getenv("HTTPS_PROXY") != "" {
-		// Use environment proxy if configured
-		opts = append(opts, telego.WithHTTPClient(&http.Client{
-			Transport: &http.Transport{
-				Proxy: http.ProxyFromEnvironment,
-			},
-		}))
-	}
-
-	bot, err := telego.NewBot(telegramCfg.Token, opts...)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create telegram bot: %w", err)
-	}
-
-	base := NewBaseChannel("telegram", telegramCfg, bus, telegramCfg.AllowFrom)
-
-	return &TelegramChannel{
-		BaseChannel:  base,
-		commands:     NewTelegramCommands(bot, cfg),
-		bot:          bot,
-		config:       cfg,
-		chatIDs:      make(map[string]int64),
-		transcriber:  nil,
-		placeholders: sync.Map{},
-		stopThinking: sync.Map{},
-	}, nil
-}
-
-func (c *TelegramChannel) SetTranscriber(transcriber *voice.GroqTranscriber) {
-	c.transcriber = transcriber
-}
-
-func (c *TelegramChannel) Start(ctx context.Context) error {
-	logger.InfoC("telegram", "Starting Telegram bot (polling mode)...")
-
-	updates, err := c.bot.UpdatesViaLongPolling(ctx, &telego.GetUpdatesParams{
-		Timeout: 30,
-	})
-	if err != nil {
-		return fmt.Errorf("failed to start long polling: %w", err)
-	}
-
-	bh, err := telegohandler.NewBotHandler(c.bot, updates)
-	if err != nil {
-		return fmt.Errorf("failed to create bot handler: %w", err)
-	}
-
-	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())
-
-	c.setRunning(true)
-	logger.InfoCF("telegram", "Telegram bot connected", map[string]any{
-		"username": c.bot.Username(),
-	})
-
-	go bh.Start()
-
-	go func() {
-		<-ctx.Done()
-		bh.Stop()
-	}()
-
-	return nil
-}
-
-func (c *TelegramChannel) Stop(ctx context.Context) error {
-	logger.InfoC("telegram", "Stopping Telegram bot...")
-	c.setRunning(false)
-	return nil
-}
-
-func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
-	if !c.IsRunning() {
-		return fmt.Errorf("telegram bot not running")
-	}
-
-	chatID, err := parseChatID(msg.ChatID)
-	if err != nil {
-		return fmt.Errorf("invalid chat ID: %w", err)
-	}
-
-	// Stop thinking animation
-	if stop, ok := c.stopThinking.Load(msg.ChatID); ok {
-		if cf, ok := stop.(*thinkingCancel); ok && cf != nil {
-			cf.Cancel()
-		}
-		c.stopThinking.Delete(msg.ChatID)
-	}
-
-	htmlContent := markdownToTelegramHTML(msg.Content)
-
-	// Try to edit placeholder
-	if pID, ok := c.placeholders.Load(msg.ChatID); ok {
-		c.placeholders.Delete(msg.ChatID)
-		editMsg := tu.EditMessageText(tu.ID(chatID), pID.(int), htmlContent)
-		editMsg.ParseMode = telego.ModeHTML
-
-		if _, err = c.bot.EditMessageText(ctx, editMsg); err == nil {
-			return nil
-		}
-		// Fallback to new message if edit fails
-	}
-
-	tgMsg := tu.Message(tu.ID(chatID), htmlContent)
-	tgMsg.ParseMode = telego.ModeHTML
-
-	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(),
-		})
-		tgMsg.ParseMode = ""
-		_, err = c.bot.SendMessage(ctx, tgMsg)
-		return err
-	}
-
-	return nil
-}
-
-func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Message) error {
-	if message == nil {
-		return fmt.Errorf("message is nil")
-	}
-
-	user := message.From
-	if user == nil {
-		return fmt.Errorf("message sender (user) is nil")
-	}
-
-	senderID := fmt.Sprintf("%d", user.ID)
-	if user.Username != "" {
-		senderID = fmt.Sprintf("%d|%s", user.ID, user.Username)
-	}
-
-	// check allowlist to avoid downloading attachments for rejected users
-	if !c.IsAllowed(senderID) {
-		logger.DebugCF("telegram", "Message rejected by allowlist", map[string]any{
-			"user_id": senderID,
-		})
-		return nil
-	}
-
-	chatID := message.Chat.ID
-	c.chatIDs[senderID] = chatID
-
-	content := ""
-	mediaPaths := []string{}
-	localFiles := []string{} // track local files that need cleanup
-
-	// ensure temp files are cleaned up when function returns
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("telegram", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
-			}
-		}
-	}()
-
-	if message.Text != "" {
-		content += message.Text
-	}
-
-	if message.Caption != "" {
-		if content != "" {
-			content += "\n"
-		}
-		content += message.Caption
-	}
-
-	if len(message.Photo) > 0 {
-		photo := message.Photo[len(message.Photo)-1]
-		photoPath := c.downloadPhoto(ctx, photo.FileID)
-		if photoPath != "" {
-			localFiles = append(localFiles, photoPath)
-			mediaPaths = append(mediaPaths, photoPath)
-			if content != "" {
-				content += "\n"
-			}
-			content += "[image: photo]"
-		}
-	}
-
-	if message.Voice != nil {
-		voicePath := c.downloadFile(ctx, message.Voice.FileID, ".ogg")
-		if voicePath != "" {
-			localFiles = append(localFiles, voicePath)
-			mediaPaths = append(mediaPaths, voicePath)
-
-			transcribedText := ""
-			if c.transcriber != nil && c.transcriber.IsAvailable() {
-				transcriberCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
-				defer cancel()
-
-				result, err := c.transcriber.Transcribe(transcriberCtx, voicePath)
-				if err != nil {
-					logger.ErrorCF("telegram", "Voice transcription failed", map[string]any{
-						"error": err.Error(),
-						"path":  voicePath,
-					})
-					transcribedText = "[voice (transcription failed)]"
-				} else {
-					transcribedText = fmt.Sprintf("[voice transcription: %s]", result.Text)
-					logger.InfoCF("telegram", "Voice transcribed successfully", map[string]any{
-						"text": result.Text,
-					})
-				}
-			} else {
-				transcribedText = "[voice]"
-			}
-
-			if content != "" {
-				content += "\n"
-			}
-			content += transcribedText
-		}
-	}
-
-	if message.Audio != nil {
-		audioPath := c.downloadFile(ctx, message.Audio.FileID, ".mp3")
-		if audioPath != "" {
-			localFiles = append(localFiles, audioPath)
-			mediaPaths = append(mediaPaths, audioPath)
-			if content != "" {
-				content += "\n"
-			}
-			content += "[audio]"
-		}
-	}
-
-	if message.Document != nil {
-		docPath := c.downloadFile(ctx, message.Document.FileID, "")
-		if docPath != "" {
-			localFiles = append(localFiles, docPath)
-			mediaPaths = append(mediaPaths, docPath)
-			if content != "" {
-				content += "\n"
-			}
-			content += "[file]"
-		}
-	}
-
-	if content == "" {
-		content = "[empty message]"
-	}
-
-	logger.DebugCF("telegram", "Received message", map[string]any{
-		"sender_id": senderID,
-		"chat_id":   fmt.Sprintf("%d", chatID),
-		"preview":   utils.Truncate(content, 50),
-	})
-
-	// Thinking indicator
-	err := c.bot.SendChatAction(ctx, tu.ChatAction(tu.ID(chatID), telego.ChatActionTyping))
-	if err != nil {
-		logger.ErrorCF("telegram", "Failed to send chat action", map[string]any{
-			"error": err.Error(),
-		})
-	}
-
-	// Stop any previous thinking animation
-	chatIDStr := fmt.Sprintf("%d", chatID)
-	if prevStop, ok := c.stopThinking.Load(chatIDStr); ok {
-		if cf, ok := prevStop.(*thinkingCancel); ok && cf != nil {
-			cf.Cancel()
-		}
-	}
-
-	// Create cancel function for thinking state
-	_, thinkCancel := context.WithTimeout(ctx, 5*time.Minute)
-	c.stopThinking.Store(chatIDStr, &thinkingCancel{fn: thinkCancel})
-
-	pMsg, err := c.bot.SendMessage(ctx, tu.Message(tu.ID(chatID), "Thinking... 💭"))
-	if err == nil {
-		pID := pMsg.MessageID
-		c.placeholders.Store(chatIDStr, pID)
-	}
-
-	peerKind := "direct"
-	peerID := fmt.Sprintf("%d", user.ID)
-	if message.Chat.Type != "private" {
-		peerKind = "group"
-		peerID = fmt.Sprintf("%d", chatID)
-	}
-
-	metadata := map[string]string{
-		"message_id": fmt.Sprintf("%d", message.MessageID),
-		"user_id":    fmt.Sprintf("%d", user.ID),
-		"username":   user.Username,
-		"first_name": user.FirstName,
-		"is_group":   fmt.Sprintf("%t", message.Chat.Type != "private"),
-		"peer_kind":  peerKind,
-		"peer_id":    peerID,
-	}
-
-	c.HandleMessage(fmt.Sprintf("%d", user.ID), fmt.Sprintf("%d", chatID), content, mediaPaths, metadata)
-	return nil
-}
-
-func (c *TelegramChannel) downloadPhoto(ctx context.Context, fileID string) string {
-	file, err := c.bot.GetFile(ctx, &telego.GetFileParams{FileID: fileID})
-	if err != nil {
-		logger.ErrorCF("telegram", "Failed to get photo file", map[string]any{
-			"error": err.Error(),
-		})
-		return ""
-	}
-
-	return c.downloadFileWithInfo(file, ".jpg")
-}
-
-func (c *TelegramChannel) downloadFileWithInfo(file *telego.File, ext string) string {
-	if file.FilePath == "" {
-		return ""
-	}
-
-	url := c.bot.FileDownloadURL(file.FilePath)
-	logger.DebugCF("telegram", "File URL", map[string]any{"url": url})
-
-	// Use FilePath as filename for better identification
-	filename := file.FilePath + ext
-	return utils.DownloadFile(url, filename, utils.DownloadOptions{
-		LoggerPrefix: "telegram",
-	})
-}
-
-func (c *TelegramChannel) downloadFile(ctx context.Context, fileID, ext string) string {
-	file, err := c.bot.GetFile(ctx, &telego.GetFileParams{FileID: fileID})
-	if err != nil {
-		logger.ErrorCF("telegram", "Failed to get file", map[string]any{
-			"error": err.Error(),
-		})
-		return ""
-	}
-
-	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 ""
-	}
-
-	codeBlocks := extractCodeBlocks(text)
-	text = codeBlocks.text
-
-	inlineCodes := extractInlineCodes(text)
-	text = inlineCodes.text
-
-	text = regexp.MustCompile(`^#{1,6}\s+(.+)$`).ReplaceAllString(text, "$1")
-
-	text = regexp.MustCompile(`^>\s*(.*)$`).ReplaceAllString(text, "$1")
-
-	text = escapeHTML(text)
-
-	text = regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`).ReplaceAllString(text, `<a href="$2">$1</a>`)
-
-	text = regexp.MustCompile(`\*\*(.+?)\*\*`).ReplaceAllString(text, "<b>$1</b>")
-
-	text = regexp.MustCompile(`__(.+?)__`).ReplaceAllString(text, "<b>$1</b>")
-
-	reItalic := regexp.MustCompile(`_([^_]+)_`)
-	text = reItalic.ReplaceAllStringFunc(text, func(s string) string {
-		match := reItalic.FindStringSubmatch(s)
-		if len(match) < 2 {
-			return s
-		}
-		return "<i>" + match[1] + "</i>"
-	})
-
-	text = regexp.MustCompile(`~~(.+?)~~`).ReplaceAllString(text, "<s>$1</s>")
-
-	text = regexp.MustCompile(`^[-*]\s+`).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 {
-	re := regexp.MustCompile("```[\\w]*\\n?([\\s\\S]*?)```")
-	matches := re.FindAllStringSubmatch(text, -1)
-
-	codes := make([]string, 0, len(matches))
-	for _, match := range matches {
-		codes = append(codes, match[1])
-	}
-
-	i := 0
-	text = re.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 {
-	re := regexp.MustCompile("`([^`]+)`")
-	matches := re.FindAllStringSubmatch(text, -1)
-
-	codes := make([]string, 0, len(matches))
-	for _, match := range matches {
-		codes = append(codes, match[1])
-	}
-
-	i := 0
-	text = re.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/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/init.go b/pkg/channels/telegram/init.go
new file mode 100644
index 000000000..ac87bb805
--- /dev/null
+++ b/pkg/channels/telegram/init.go
@@ -0,0 +1,13 @@
+package telegram
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("telegram", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewTelegramChannel(cfg, b)
+	})
+}
diff --git a/pkg/channels/telegram/telegram.go b/pkg/channels/telegram/telegram.go
new file mode 100644
index 000000000..0a36247a6
--- /dev/null
+++ b/pkg/channels/telegram/telegram.go
@@ -0,0 +1,784 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/mymmrac/telego"
+	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"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+var (
+	reHeading    = regexp.MustCompile(`^#{1,6}\s+(.+)$`)
+	reBlockquote = regexp.MustCompile(`^>\s*(.*)$`)
+	reLink       = regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`)
+	reBoldStar   = regexp.MustCompile(`\*\*(.+?)\*\*`)
+	reBoldUnder  = regexp.MustCompile(`__(.+?)__`)
+	reItalic     = regexp.MustCompile(`_([^_]+)_`)
+	reStrike     = regexp.MustCompile(`~~(.+?)~~`)
+	reListItem   = regexp.MustCompile(`^[-*]\s+`)
+	reCodeBlock  = regexp.MustCompile("```[\\w]*\\n?([\\s\\S]*?)```")
+	reInlineCode = regexp.MustCompile("`([^`]+)`")
+)
+
+type TelegramChannel struct {
+	*channels.BaseChannel
+	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) {
+	var opts []telego.BotOption
+	telegramCfg := cfg.Channels.Telegram
+
+	if telegramCfg.Proxy != "" {
+		proxyURL, parseErr := url.Parse(telegramCfg.Proxy)
+		if parseErr != nil {
+			return nil, fmt.Errorf("invalid proxy URL %q: %w", telegramCfg.Proxy, parseErr)
+		}
+		opts = append(opts, telego.WithHTTPClient(&http.Client{
+			Transport: &http.Transport{
+				Proxy: http.ProxyURL(proxyURL),
+			},
+		}))
+	} else if os.Getenv("HTTP_PROXY") != "" || os.Getenv("HTTPS_PROXY") != "" {
+		// Use environment proxy if configured
+		opts = append(opts, telego.WithHTTPClient(&http.Client{
+			Transport: &http.Transport{
+				Proxy: http.ProxyFromEnvironment,
+			},
+		}))
+	}
+
+	if baseURL := strings.TrimRight(strings.TrimSpace(telegramCfg.BaseURL), "/"); baseURL != "" {
+		opts = append(opts, telego.WithAPIServer(baseURL))
+	}
+
+	bot, err := telego.NewBot(telegramCfg.Token, opts...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create telegram bot: %w", err)
+	}
+
+	base := channels.NewBaseChannel(
+		"telegram",
+		telegramCfg,
+		bus,
+		telegramCfg.AllowFrom,
+		channels.WithMaxMessageLength(4000),
+		channels.WithGroupTrigger(telegramCfg.GroupTrigger),
+		channels.WithReasoningChannelID(telegramCfg.ReasoningChannelID),
+	)
+
+	return &TelegramChannel{
+		BaseChannel: base,
+		bot:         bot,
+		config:      cfg,
+		chatIDs:     make(map[string]int64),
+	}, nil
+}
+
+func (c *TelegramChannel) Start(ctx context.Context) error {
+	logger.InfoC("telegram", "Starting Telegram bot (polling mode)...")
+
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
+	updates, err := c.bot.UpdatesViaLongPolling(c.ctx, &telego.GetUpdatesParams{
+		Timeout: 30,
+	})
+	if err != nil {
+		c.cancel()
+		return fmt.Errorf("failed to start long polling: %w", err)
+	}
+
+	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 {
+		return c.handleMessage(ctx, &message)
+	}, th.AnyMessage())
+
+	c.SetRunning(true)
+	logger.InfoCF("telegram", "Telegram bot connected", map[string]any{
+		"username": c.bot.Username(),
+	})
+
+	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
+}
+
+func (c *TelegramChannel) Stop(ctx context.Context) error {
+	logger.InfoC("telegram", "Stopping Telegram bot...")
+	c.SetRunning(false)
+
+	// Stop the bot handler
+	if c.bh != nil {
+		_ = c.bh.StopWithContext(ctx)
+	}
+
+	// Cancel our context (stops long polling)
+	if c.cancel != nil {
+		c.cancel()
+	}
+	if c.commandRegCancel != nil {
+		c.commandRegCancel()
+	}
+
+	return nil
+}
+
+func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	chatID, err := parseChatID(msg.ChatID)
+	if err != nil {
+		return fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed)
+	}
+
+	if msg.Content == "" {
+		return nil
+	}
+
+	// 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.
+	queue := []string{msg.Content}
+	for len(queue) > 0 {
+		chunk := queue[0]
+		queue = queue[1:]
+
+		htmlContent := markdownToTelegramHTML(chunk)
+
+		if len([]rune(htmlContent)) > 4096 {
+			ratio := float64(len([]rune(chunk))) / float64(len([]rune(htmlContent)))
+			smallerLen := int(float64(4096) * ratio * 0.95) // 5% safety margin
+			if smallerLen < 100 {
+				smallerLen = 100
+			}
+			// Push sub-chunks back to the front of the queue for
+			// re-validation instead of sending them blindly.
+			subChunks := channels.SplitMessage(chunk, smallerLen)
+			queue = append(subChunks, queue...)
+			continue
+		}
+
+		if err := c.sendHTMLChunk(ctx, chatID, htmlContent, chunk); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// sendHTMLChunk sends a single HTML message, falling back to the original
+// markdown as plain text on parse failure so users never see raw HTML tags.
+func (c *TelegramChannel) sendHTMLChunk(ctx context.Context, chatID int64, htmlContent, mdFallback string) error {
+	tgMsg := tu.Message(tu.ID(chatID), htmlContent)
+	tgMsg.ParseMode = telego.ModeHTML
+
+	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(),
+		})
+		tgMsg.Text = mdFallback
+		tgMsg.ParseMode = ""
+		if _, err = c.bot.SendMessage(ctx, tgMsg); err != nil {
+			return fmt.Errorf("telegram send: %w", channels.ErrTemporary)
+		}
+	}
+	return nil
+}
+
+// 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.
+func (c *TelegramChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	cid, err := parseChatID(chatID)
+	if err != nil {
+		return func() {}, err
+	}
+
+	// Send the first typing action immediately
+	_ = c.bot.SendChatAction(ctx, tu.ChatAction(tu.ID(cid), telego.ChatActionTyping))
+
+	typingCtx, cancel := context.WithCancel(ctx)
+	go func() {
+		ticker := time.NewTicker(4 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-typingCtx.Done():
+				return
+			case <-ticker.C:
+				_ = c.bot.SendChatAction(typingCtx, tu.ChatAction(tu.ID(cid), telego.ChatActionTyping))
+			}
+		}
+	}()
+
+	return cancel, nil
+}
+
+// EditMessage implements channels.MessageEditor.
+func (c *TelegramChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
+	cid, err := parseChatID(chatID)
+	if err != nil {
+		return err
+	}
+	mid, err := strconv.Atoi(messageID)
+	if err != nil {
+		return err
+	}
+	htmlContent := markdownToTelegramHTML(content)
+	editMsg := tu.EditMessageText(tu.ID(cid), mid, htmlContent)
+	editMsg.ParseMode = telego.ModeHTML
+	_, err = c.bot.EditMessageText(ctx, editMsg)
+	return err
+}
+
+// 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).
+func (c *TelegramChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	phCfg := c.config.Channels.Telegram.Placeholder
+	if !phCfg.Enabled {
+		return "", nil
+	}
+
+	text := phCfg.Text
+	if text == "" {
+		text = "Thinking... 💭"
+	}
+
+	cid, err := parseChatID(chatID)
+	if err != nil {
+		return "", err
+	}
+
+	pMsg, err := c.bot.SendMessage(ctx, tu.Message(tu.ID(cid), text))
+	if err != nil {
+		return "", err
+	}
+
+	return fmt.Sprintf("%d", pMsg.MessageID), nil
+}
+
+// SendMedia implements the channels.MediaSender interface.
+func (c *TelegramChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	chatID, err := parseChatID(msg.ChatID)
+	if err != nil {
+		return fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed)
+	}
+
+	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("telegram", "Failed to resolve media ref", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		file, err := os.Open(localPath)
+		if err != nil {
+			logger.ErrorCF("telegram", "Failed to open media file", map[string]any{
+				"path":  localPath,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		switch part.Type {
+		case "image":
+			params := &telego.SendPhotoParams{
+				ChatID:  tu.ID(chatID),
+				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,
+			}
+			_, err = c.bot.SendAudio(ctx, params)
+		case "video":
+			params := &telego.SendVideoParams{
+				ChatID:  tu.ID(chatID),
+				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,
+			}
+			_, err = c.bot.SendDocument(ctx, params)
+		}
+
+		file.Close()
+
+		if err != nil {
+			logger.ErrorCF("telegram", "Failed to send media", map[string]any{
+				"type":  part.Type,
+				"error": err.Error(),
+			})
+			return fmt.Errorf("telegram send media: %w", channels.ErrTemporary)
+		}
+	}
+
+	return nil
+}
+
+func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Message) error {
+	if message == nil {
+		return fmt.Errorf("message is nil")
+	}
+
+	user := message.From
+	if user == nil {
+		return fmt.Errorf("message sender (user) is nil")
+	}
+
+	platformID := fmt.Sprintf("%d", user.ID)
+	sender := bus.SenderInfo{
+		Platform:    "telegram",
+		PlatformID:  platformID,
+		CanonicalID: identity.BuildCanonicalID("telegram", platformID),
+		Username:    user.Username,
+		DisplayName: user.FirstName,
+	}
+
+	// check allowlist to avoid downloading attachments for rejected users
+	if !c.IsAllowedSender(sender) {
+		logger.DebugCF("telegram", "Message rejected by allowlist", map[string]any{
+			"user_id": platformID,
+		})
+		return nil
+	}
+
+	chatID := message.Chat.ID
+	c.chatIDs[platformID] = chatID
+
+	content := ""
+	mediaPaths := []string{}
+
+	chatIDStr := fmt.Sprintf("%d", chatID)
+	messageIDStr := fmt.Sprintf("%d", message.MessageID)
+	scope := channels.BuildMediaScope("telegram", chatIDStr, messageIDStr)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "telegram",
+			}, scope)
+			if err == nil {
+				return ref
+			}
+		}
+		return localPath // fallback: use raw path
+	}
+
+	if message.Text != "" {
+		content += message.Text
+	}
+
+	if message.Caption != "" {
+		if content != "" {
+			content += "\n"
+		}
+		content += message.Caption
+	}
+
+	if len(message.Photo) > 0 {
+		photo := message.Photo[len(message.Photo)-1]
+		photoPath := c.downloadPhoto(ctx, photo.FileID)
+		if photoPath != "" {
+			mediaPaths = append(mediaPaths, storeMedia(photoPath, "photo.jpg"))
+			if content != "" {
+				content += "\n"
+			}
+			content += "[image: photo]"
+		}
+	}
+
+	if message.Voice != nil {
+		voicePath := c.downloadFile(ctx, message.Voice.FileID, ".ogg")
+		if voicePath != "" {
+			mediaPaths = append(mediaPaths, storeMedia(voicePath, "voice.ogg"))
+
+			if content != "" {
+				content += "\n"
+			}
+			content += "[voice]"
+		}
+	}
+
+	if message.Audio != nil {
+		audioPath := c.downloadFile(ctx, message.Audio.FileID, ".mp3")
+		if audioPath != "" {
+			mediaPaths = append(mediaPaths, storeMedia(audioPath, "audio.mp3"))
+			if content != "" {
+				content += "\n"
+			}
+			content += "[audio]"
+		}
+	}
+
+	if message.Document != nil {
+		docPath := c.downloadFile(ctx, message.Document.FileID, "")
+		if docPath != "" {
+			mediaPaths = append(mediaPaths, storeMedia(docPath, "document"))
+			if content != "" {
+				content += "\n"
+			}
+			content += "[file]"
+		}
+	}
+
+	if content == "" {
+		content = "[empty message]"
+	}
+
+	// In group chats, apply unified group trigger filtering
+	if message.Chat.Type != "private" {
+		isMentioned := c.isBotMentioned(message)
+		if isMentioned {
+			content = c.stripBotMention(content)
+		}
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+		if !respond {
+			return nil
+		}
+		content = cleaned
+	}
+
+	logger.DebugCF("telegram", "Received message", map[string]any{
+		"sender_id": sender.CanonicalID,
+		"chat_id":   fmt.Sprintf("%d", chatID),
+		"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)
+	}
+
+	peer := bus.Peer{Kind: peerKind, ID: peerID}
+	messageID := fmt.Sprintf("%d", message.MessageID)
+
+	metadata := map[string]string{
+		"user_id":    fmt.Sprintf("%d", user.ID),
+		"username":   user.Username,
+		"first_name": user.FirstName,
+		"is_group":   fmt.Sprintf("%t", message.Chat.Type != "private"),
+	}
+
+	c.HandleMessage(c.ctx,
+		peer,
+		messageID,
+		platformID,
+		fmt.Sprintf("%d", chatID),
+		content,
+		mediaPaths,
+		metadata,
+		sender,
+	)
+	return nil
+}
+
+func (c *TelegramChannel) downloadPhoto(ctx context.Context, fileID string) string {
+	file, err := c.bot.GetFile(ctx, &telego.GetFileParams{FileID: fileID})
+	if err != nil {
+		logger.ErrorCF("telegram", "Failed to get photo file", map[string]any{
+			"error": err.Error(),
+		})
+		return ""
+	}
+
+	return c.downloadFileWithInfo(file, ".jpg")
+}
+
+func (c *TelegramChannel) downloadFileWithInfo(file *telego.File, ext string) string {
+	if file.FilePath == "" {
+		return ""
+	}
+
+	url := c.bot.FileDownloadURL(file.FilePath)
+	logger.DebugCF("telegram", "File URL", map[string]any{"url": url})
+
+	// Use FilePath as filename for better identification
+	filename := file.FilePath + ext
+	return utils.DownloadFile(url, filename, utils.DownloadOptions{
+		LoggerPrefix: "telegram",
+	})
+}
+
+func (c *TelegramChannel) downloadFile(ctx context.Context, fileID, ext string) string {
+	file, err := c.bot.GetFile(ctx, &telego.GetFileParams{FileID: fileID})
+	if err != nil {
+		logger.ErrorCF("telegram", "Failed to get file", map[string]any{
+			"error": err.Error(),
+		})
+		return ""
+	}
+
+	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 ""
+	}
+
+	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
+}
+
+// isBotMentioned checks if the bot is mentioned in the message via entities.
+func (c *TelegramChannel) isBotMentioned(message *telego.Message) bool {
+	text, entities := telegramEntityTextAndList(message)
+	if text == "" || len(entities) == 0 {
+		return false
+	}
+
+	botUsername := ""
+	if c.bot != nil {
+		botUsername = c.bot.Username()
+	}
+	runes := []rune(text)
+
+	for _, entity := range entities {
+		entityText, ok := telegramEntityText(runes, entity)
+		if !ok {
+			continue
+		}
+
+		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
+			}
+		}
+	}
+	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()
+	if botUsername == "" {
+		return content
+	}
+	// Case-insensitive replacement
+	re := regexp.MustCompile(`(?i)@` + regexp.QuoteMeta(botUsername))
+	content = re.ReplaceAllString(content, "")
+	return strings.TrimSpace(content)
+}
diff --git a/pkg/channels/telegram/telegram_dispatch_test.go b/pkg/channels/telegram/telegram_dispatch_test.go
new file mode 100644
index 000000000..1ea4a4824
--- /dev/null
+++ b/pkg/channels/telegram/telegram_dispatch_test.go
@@ -0,0 +1,52 @@
+package telegram
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"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)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	inbound, ok := messageBus.ConsumeInbound(ctx)
+	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..0d5b985fe
--- /dev/null
+++ b/pkg/channels/telegram/telegram_group_command_filter_test.go
@@ -0,0 +1,147 @@
+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(), 150*time.Millisecond)
+			defer cancel()
+
+			inbound, ok := messageBus.ConsumeInbound(ctx)
+			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
+			}
+
+			if ok {
+				t.Fatalf("expected message to be filtered, got content=%q", inbound.Content)
+			}
+		})
+	}
+}
+
+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..3a2f1aa66
--- /dev/null
+++ b/pkg/channels/telegram/telegram_test.go
@@ -0,0 +1,273 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"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"
+)
+
+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{}
+
+func (s *stubConstructor) JSONRequest(parameters any) (*ta.RequestData, error) {
+	return &ta.RequestData{}, nil
+}
+
+func (s *stubConstructor) MultipartRequest(
+	parameters map[string]string,
+	files map[string]ta.NamedReader,
+) (*ta.RequestData, error) {
+	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 {
+	t.Helper()
+
+	bot, err := telego.NewBot(testToken,
+		telego.WithAPICaller(caller),
+		telego.WithRequestConstructor(&stubConstructor{}),
+		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),
+	}
+}
+
+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_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)
+}
diff --git a/pkg/channels/telegram_commands.go b/pkg/channels/telegram_commands.go
deleted file mode 100644
index a084b641b..000000000
--- a/pkg/channels/telegram_commands.go
+++ /dev/null
@@ -1,156 +0,0 @@
-package channels
-
-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.Model,
-			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.yaml",
-			c.config.Agents.Defaults.Model, 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/webhook.go b/pkg/channels/webhook.go
new file mode 100644
index 000000000..3cf27baf6
--- /dev/null
+++ b/pkg/channels/webhook.go
@@ -0,0 +1,20 @@
+package channels
+
+import "net/http"
+
+// WebhookHandler is an optional interface for channels that receive messages
+// via HTTP webhooks. Manager discovers channels implementing this interface
+// and registers them on the shared HTTP server.
+type WebhookHandler interface {
+	// WebhookPath returns the path to mount this handler on the shared server.
+	// Examples: "/webhook/line", "/webhook/wecom"
+	WebhookPath() string
+	http.Handler // ServeHTTP(w http.ResponseWriter, r *http.Request)
+}
+
+// HealthChecker is an optional interface for channels that expose
+// a health check endpoint on the shared HTTP server.
+type HealthChecker interface {
+	HealthPath() string
+	HealthHandler(w http.ResponseWriter, r *http.Request)
+}
diff --git a/pkg/channels/wecom/aibot.go b/pkg/channels/wecom/aibot.go
new file mode 100644
index 000000000..93fe8c36d
--- /dev/null
+++ b/pkg/channels/wecom/aibot.go
@@ -0,0 +1,1017 @@
+package wecom
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/big"
+	"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"
+)
+
+// WeComAIBotChannel implements the Channel interface for WeCom AI Bot (企业微信智能机器人)
+type WeComAIBotChannel struct {
+	*channels.BaseChannel
+	config      config.WeComAIBotConfig
+	ctx         context.Context
+	cancel      context.CancelFunc
+	streamTasks map[string]*streamTask   // streamID -> task (for poll lookups)
+	chatTasks   map[string][]*streamTask // chatID   -> in-flight tasks queue (FIFO)
+	taskMu      sync.RWMutex
+}
+
+// streamTask represents a streaming task for AI Bot.
+//
+// Mutable fields (Finished, StreamClosed, StreamClosedAt) must be read/written
+// while holding WeComAIBotChannel.taskMu. Immutable fields (StreamID, ChatID,
+// ResponseURL, Question, CreatedTime, Deadline, answerCh, ctx, cancel) are set
+// once at creation and never modified, so they are safe to read without a lock.
+type streamTask struct {
+	// immutable after creation
+	StreamID    string
+	ChatID      string // used by Send() to find this task
+	ResponseURL string // temporary URL for proactive reply (valid 1 hour, use once)
+	Question    string
+	CreatedTime time.Time
+	Deadline    time.Time          // ~30s, we close the stream here and switch to response_url
+	answerCh    chan string        // receives agent reply from Send()
+	ctx         context.Context    // canceled when task is removed; used to interrupt the agent goroutine
+	cancel      context.CancelFunc // call on task removal to cancel ctx
+
+	// mutable — guarded by WeComAIBotChannel.taskMu
+	StreamClosed   bool      // stream returned finish:true; waiting for agent to reply via response_url
+	StreamClosedAt time.Time // set when StreamClosed becomes true; used for accelerated cleanup
+	Finished       bool      // fully done
+}
+
+// WeComAIBotMessage represents the decrypted JSON message from WeCom AI Bot
+// Ref: https://developer.work.weixin.qq.com/document/path/100719
+type WeComAIBotMessage struct {
+	MsgID    string `json:"msgid"`
+	AIBotID  string `json:"aibotid"`
+	ChatID   string `json:"chatid"`   // only for group chat
+	ChatType string `json:"chattype"` // "single" or "group"
+	From     struct {
+		UserID string `json:"userid"`
+	} `json:"from"`
+	ResponseURL string `json:"response_url"` // temporary URL for proactive reply
+	MsgType     string `json:"msgtype"`
+	// text message
+	Text *struct {
+		Content string `json:"content"`
+	} `json:"text,omitempty"`
+	// stream polling refresh
+	Stream *struct {
+		ID string `json:"id"`
+	} `json:"stream,omitempty"`
+	// image message
+	Image *struct {
+		URL string `json:"url"`
+	} `json:"image,omitempty"`
+	// mixed message (text + image)
+	Mixed *struct {
+		MsgItem []struct {
+			MsgType string `json:"msgtype"`
+			Text    *struct {
+				Content string `json:"content"`
+			} `json:"text,omitempty"`
+			Image *struct {
+				URL string `json:"url"`
+			} `json:"image,omitempty"`
+		} `json:"msg_item"`
+	} `json:"mixed,omitempty"`
+	// event field
+	Event *struct {
+		EventType string `json:"eventtype"`
+	} `json:"event,omitempty"`
+}
+
+// WeComAIBotMsgItemImage holds the image payload inside a stream message item.
+type WeComAIBotMsgItemImage struct {
+	Base64 string `json:"base64"`
+	MD5    string `json:"md5"`
+}
+
+// WeComAIBotMsgItem is a single item inside a stream's msg_item list.
+type WeComAIBotMsgItem struct {
+	MsgType string                  `json:"msgtype"`
+	Image   *WeComAIBotMsgItemImage `json:"image,omitempty"`
+}
+
+// WeComAIBotStreamInfo represents the detailed stream content in streaming responses.
+type WeComAIBotStreamInfo struct {
+	ID      string              `json:"id"`
+	Finish  bool                `json:"finish"`
+	Content string              `json:"content,omitempty"`
+	MsgItem []WeComAIBotMsgItem `json:"msg_item,omitempty"`
+}
+
+// WeComAIBotStreamResponse represents the streaming response format
+type WeComAIBotStreamResponse struct {
+	MsgType string               `json:"msgtype"`
+	Stream  WeComAIBotStreamInfo `json:"stream"`
+}
+
+// WeComAIBotEncryptedResponse represents the encrypted response wrapper
+// Fields match WXBizJsonMsgCrypt.generate() in Python SDK
+type WeComAIBotEncryptedResponse struct {
+	Encrypt      string `json:"encrypt"`
+	MsgSignature string `json:"msgsignature"`
+	Timestamp    string `json:"timestamp"`
+	Nonce        string `json:"nonce"`
+}
+
+// NewWeComAIBotChannel creates a new WeCom AI Bot channel instance
+func NewWeComAIBotChannel(
+	cfg config.WeComAIBotConfig,
+	messageBus *bus.MessageBus,
+) (*WeComAIBotChannel, error) {
+	if cfg.Token == "" || cfg.EncodingAESKey == "" {
+		return nil, fmt.Errorf("token and encoding_aes_key are required for WeCom AI Bot")
+	}
+
+	base := channels.NewBaseChannel("wecom_aibot", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(2048),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
+
+	return &WeComAIBotChannel{
+		BaseChannel: base,
+		config:      cfg,
+		streamTasks: make(map[string]*streamTask),
+		chatTasks:   make(map[string][]*streamTask),
+	}, nil
+}
+
+// Name returns the channel name
+func (c *WeComAIBotChannel) Name() string {
+	return "wecom_aibot"
+}
+
+// Start initializes the WeCom AI Bot channel
+func (c *WeComAIBotChannel) Start(ctx context.Context) error {
+	logger.InfoC("wecom_aibot", "Starting WeCom AI Bot channel...")
+
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
+	// Start cleanup goroutine for old tasks
+	go c.cleanupLoop()
+
+	c.SetRunning(true)
+	logger.InfoC("wecom_aibot", "WeCom AI Bot channel started")
+
+	return nil
+}
+
+// Stop gracefully stops the WeCom AI Bot channel
+func (c *WeComAIBotChannel) Stop(ctx context.Context) error {
+	logger.InfoC("wecom_aibot", "Stopping WeCom AI Bot channel...")
+
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	c.SetRunning(false)
+	logger.InfoC("wecom_aibot", "WeCom AI Bot channel stopped")
+	return nil
+}
+
+// Send delivers the agent reply into the active streamTask for msg.ChatID.
+// It writes into the earliest unfinished task in the queue (FIFO per chatID).
+// If the stream has already closed (deadline passed), it posts directly to response_url.
+func (c *WeComAIBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+	c.taskMu.Lock()
+	queue := c.chatTasks[msg.ChatID]
+	// Only compact Finished tasks at the head of the queue.
+	// Tasks that are Finished in the middle are NOT removed here: doing a full
+	// scan on every Send() call would be O(n) and is unnecessary given that
+	// removeTask() always splices the task out of the queue immediately.
+	// Any Finished task left stranded in the middle (e.g. due to an unexpected
+	// code path) will be collected by cleanupOldTasks.
+	for len(queue) > 0 && queue[0].Finished {
+		queue = queue[1:]
+	}
+	c.chatTasks[msg.ChatID] = queue
+	var task *streamTask
+	var streamClosed bool
+	var responseURL string
+	if len(queue) > 0 {
+		task = queue[0]
+		// Read mutable fields while holding c.taskMu to avoid data races.
+		streamClosed = task.StreamClosed
+		responseURL = task.ResponseURL
+	}
+	c.taskMu.Unlock()
+
+	if task == nil {
+		logger.DebugCF(
+			"wecom_aibot",
+			"Send: no active task for chat (may have timed out)",
+			map[string]any{
+				"chat_id": msg.ChatID,
+			},
+		)
+		return nil
+	}
+
+	if streamClosed {
+		// Stream already ended with a "please wait" notice; send the real reply via response_url.
+		// Note: task.StreamID and task.ChatID are immutable, safe to read without a lock.
+		logger.InfoCF("wecom_aibot", "Sending reply via response_url", map[string]any{
+			"stream_id": task.StreamID,
+			"chat_id":   msg.ChatID,
+		})
+		if responseURL != "" {
+			if err := c.sendViaResponseURL(responseURL, msg.Content); err != nil {
+				logger.ErrorCF("wecom_aibot", "Failed to send via response_url", map[string]any{
+					"error":     err,
+					"stream_id": task.StreamID,
+				})
+				c.removeTask(task)
+				return fmt.Errorf("response_url delivery failed: %w", channels.ErrSendFailed)
+			}
+		} else {
+			logger.WarnCF("wecom_aibot", "Stream closed but no response_url available", map[string]any{
+				"stream_id": task.StreamID,
+			})
+		}
+		c.removeTask(task)
+		return nil
+	}
+
+	// Stream still open: deliver via answerCh for the next poll response.
+	select {
+	case task.answerCh <- msg.Content:
+	case <-task.ctx.Done():
+		// Task was canceled (cleanup removed it); silently drop the reply.
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+	return nil
+}
+
+// WebhookPath returns the path for registering on the shared HTTP server
+func (c *WeComAIBotChannel) WebhookPath() string {
+	if c.config.WebhookPath == "" {
+		return "/webhook/wecom-aibot"
+	}
+	return c.config.WebhookPath
+}
+
+// ServeHTTP implements http.Handler for the shared HTTP server
+func (c *WeComAIBotChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	c.handleWebhook(w, r)
+}
+
+// HealthPath returns the health check endpoint path
+func (c *WeComAIBotChannel) HealthPath() string {
+	return c.WebhookPath() + "/health"
+}
+
+// HealthHandler handles health check requests
+func (c *WeComAIBotChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
+	c.handleHealth(w, r)
+}
+
+// handleWebhook handles incoming webhook requests from WeCom AI Bot
+func (c *WeComAIBotChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	// Log all incoming requests for debugging
+	logger.DebugCF("wecom_aibot", "Received webhook request", map[string]any{
+		"method": r.Method,
+		"path":   r.URL.Path,
+		"query":  r.URL.RawQuery,
+	})
+
+	switch r.Method {
+	case http.MethodGet:
+		// URL verification
+		c.handleVerification(ctx, w, r)
+	case http.MethodPost:
+		// Message callback
+		c.handleMessageCallback(ctx, w, r)
+	default:
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+	}
+}
+
+// handleVerification handles the URL verification request from WeCom
+func (c *WeComAIBotChannel) handleVerification(
+	ctx context.Context,
+	w http.ResponseWriter,
+	r *http.Request,
+) {
+	msgSignature := r.URL.Query().Get("msg_signature")
+	timestamp := r.URL.Query().Get("timestamp")
+	nonce := r.URL.Query().Get("nonce")
+	echostr := r.URL.Query().Get("echostr")
+
+	logger.DebugCF("wecom_aibot", "URL verification request", map[string]any{
+		"msg_signature": msgSignature,
+		"timestamp":     timestamp,
+		"nonce":         nonce,
+	})
+
+	// Verify signature
+	if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+		logger.ErrorC("wecom_aibot", "Signature verification failed")
+		http.Error(w, "Signature verification failed", http.StatusUnauthorized)
+		return
+	}
+
+	// Decrypt echostr
+	// For WeCom AI Bot (智能机器人), receiveid should be empty string
+	decrypted, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
+	if err != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to decrypt echostr", map[string]any{
+			"error": err,
+		})
+		http.Error(w, "Decryption failed", http.StatusInternalServerError)
+		return
+	}
+
+	// Remove BOM and whitespace as per WeCom documentation
+	decrypted = strings.TrimPrefix(decrypted, "\ufeff")
+	decrypted = strings.TrimSpace(decrypted)
+
+	logger.InfoC("wecom_aibot", "URL verification successful")
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.WriteHeader(http.StatusOK)
+	w.Write([]byte(decrypted))
+}
+
+// handleMessageCallback handles incoming messages from WeCom AI Bot
+func (c *WeComAIBotChannel) handleMessageCallback(
+	ctx context.Context,
+	w http.ResponseWriter,
+	r *http.Request,
+) {
+	msgSignature := r.URL.Query().Get("msg_signature")
+	timestamp := r.URL.Query().Get("timestamp")
+	nonce := r.URL.Query().Get("nonce")
+
+	// Read request body (limit to 4 MB to prevent memory exhaustion)
+	const maxBodySize = 4 << 20 // 4 MB
+	body, err := io.ReadAll(io.LimitReader(r.Body, maxBodySize+1))
+	if err != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to read request body", map[string]any{
+			"error": err,
+		})
+		http.Error(w, "Failed to read body", http.StatusBadRequest)
+		return
+	}
+	if len(body) > maxBodySize {
+		http.Error(w, "Request body too large", http.StatusRequestEntityTooLarge)
+		return
+	}
+
+	// Parse JSON body to get encrypted message
+	// Format: {"encrypt": "base64_encrypted_string"}
+	var encryptedMsg struct {
+		Encrypt string `json:"encrypt"`
+	}
+	if unmarshalErr := json.Unmarshal(body, &encryptedMsg); unmarshalErr != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to parse JSON body", map[string]any{
+			"error": unmarshalErr,
+			"body":  string(body),
+		})
+		http.Error(w, "Failed to parse JSON", http.StatusBadRequest)
+		return
+	}
+
+	// Verify signature
+	if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+		logger.ErrorC("wecom_aibot", "Signature verification failed")
+		http.Error(w, "Signature verification failed", http.StatusUnauthorized)
+		return
+	}
+
+	// Decrypt message
+	// For WeCom AI Bot (智能机器人), receiveid is empty string
+	decrypted, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
+	if err != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to decrypt message", map[string]any{
+			"error": err,
+		})
+		http.Error(w, "Decryption failed", http.StatusInternalServerError)
+		return
+	}
+
+	// Parse decrypted JSON message
+	var msg WeComAIBotMessage
+	if unmarshalErr := json.Unmarshal([]byte(decrypted), &msg); unmarshalErr != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to parse decrypted JSON", map[string]any{
+			"error":     unmarshalErr,
+			"decrypted": decrypted,
+		})
+		http.Error(w, "Failed to parse message", http.StatusInternalServerError)
+		return
+	}
+
+	logger.DebugCF("wecom_aibot", "Decrypted message", map[string]any{
+		"msgtype": msg.MsgType,
+	})
+
+	// Process the message and get streaming response
+	response := c.processMessage(ctx, msg, timestamp, nonce)
+
+	// Check if response is empty (e.g. due to unsupported message type)
+	if response == "" {
+		response = c.encryptEmptyResponse(timestamp, nonce)
+	}
+
+	// Return encrypted JSON response
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(http.StatusOK)
+	w.Write([]byte(response))
+}
+
+// processMessage processes the received message and returns encrypted response
+func (c *WeComAIBotChannel) processMessage(
+	ctx context.Context,
+	msg WeComAIBotMessage,
+	timestamp, nonce string,
+) string {
+	logger.DebugCF("wecom_aibot", "Processing message", map[string]any{
+		"msgtype": msg.MsgType,
+	})
+
+	switch msg.MsgType {
+	case "text":
+		return c.handleTextMessage(ctx, msg, timestamp, nonce)
+	case "stream":
+		return c.handleStreamMessage(ctx, msg, timestamp, nonce)
+	case "image":
+		return c.handleImageMessage(ctx, msg, timestamp, nonce)
+	case "mixed":
+		return c.handleMixedMessage(ctx, msg, timestamp, nonce)
+	case "event":
+		return c.handleEventMessage(ctx, msg, timestamp, nonce)
+	default:
+		logger.WarnCF("wecom_aibot", "Unsupported message type", map[string]any{
+			"msgtype": msg.MsgType,
+		})
+		return c.encryptResponse("", timestamp, nonce, WeComAIBotStreamResponse{
+			MsgType: "stream",
+			Stream: WeComAIBotStreamInfo{
+				ID:      c.generateStreamID(),
+				Finish:  true,
+				Content: "Unsupported message type: " + msg.MsgType,
+			},
+		})
+	}
+}
+
+// handleTextMessage handles text messages by starting a new streaming task
+func (c *WeComAIBotChannel) handleTextMessage(
+	ctx context.Context,
+	msg WeComAIBotMessage,
+	timestamp, nonce string,
+) string {
+	if msg.Text == nil {
+		logger.ErrorC("wecom_aibot", "text message missing text field")
+		return c.encryptEmptyResponse(timestamp, nonce)
+	}
+
+	content := msg.Text.Content
+	userID := msg.From.UserID
+	if userID == "" {
+		userID = "unknown"
+	}
+
+	// chatID: group chat uses chatid, single chat uses userid
+	chatID := msg.ChatID
+	if chatID == "" {
+		chatID = userID
+	}
+
+	streamID := c.generateStreamID()
+
+	// WeCom stops sending stream-refresh callbacks after 6 minutes.
+	// Set a slightly shorter deadline so we can send a timeout notice before it gives up.
+	deadline := time.Now().Add(30 * time.Second)
+
+	// Each task gets its own context derived from the channel lifetime context.
+	// Canceling taskCancel interrupts the agent goroutine when the task is removed.
+	taskCtx, taskCancel := context.WithCancel(c.ctx)
+
+	task := &streamTask{
+		StreamID:    streamID,
+		ChatID:      chatID,
+		ResponseURL: msg.ResponseURL,
+		Question:    content,
+		CreatedTime: time.Now(),
+		Deadline:    deadline,
+		Finished:    false,
+		answerCh:    make(chan string, 1),
+		ctx:         taskCtx,
+		cancel:      taskCancel,
+	}
+
+	c.taskMu.Lock()
+	c.streamTasks[streamID] = task
+	c.chatTasks[chatID] = append(c.chatTasks[chatID], task)
+	c.taskMu.Unlock()
+
+	// Publish to agent asynchronously; agent will call Send() with reply.
+	// Use task.ctx (not c.ctx) so the agent goroutine is canceled when the task is removed.
+	go func() {
+		sender := bus.SenderInfo{
+			Platform:    "wecom_aibot",
+			PlatformID:  userID,
+			CanonicalID: identity.BuildCanonicalID("wecom_aibot", userID),
+			DisplayName: userID,
+		}
+		peerKind := "direct"
+		if msg.ChatType == "group" {
+			peerKind = "group"
+		}
+		peer := bus.Peer{Kind: peerKind, ID: chatID}
+		metadata := map[string]string{
+			"channel":      "wecom_aibot",
+			"chat_type":    msg.ChatType,
+			"msg_type":     "text",
+			"msgid":        msg.MsgID,
+			"aibotid":      msg.AIBotID,
+			"stream_id":    streamID,
+			"response_url": msg.ResponseURL,
+		}
+		c.HandleMessage(task.ctx, peer, msg.MsgID, userID, chatID,
+			content, nil, metadata, sender)
+	}()
+
+	// Return first streaming response immediately (finish=false, content empty)
+	return c.getStreamResponse(task, timestamp, nonce)
+}
+
+// handleStreamMessage handles stream polling requests
+func (c *WeComAIBotChannel) handleStreamMessage(
+	ctx context.Context,
+	msg WeComAIBotMessage,
+	timestamp, nonce string,
+) string {
+	if msg.Stream == nil {
+		logger.ErrorC("wecom_aibot", "Stream message missing stream field")
+		return c.encryptEmptyResponse(timestamp, nonce)
+	}
+
+	streamID := msg.Stream.ID
+
+	c.taskMu.RLock()
+	task, exists := c.streamTasks[streamID]
+	c.taskMu.RUnlock()
+
+	if !exists {
+		logger.DebugCF(
+			"wecom_aibot",
+			"Stream task not found (may be from previous session)",
+			map[string]any{
+				"stream_id": streamID,
+			},
+		)
+		return c.encryptResponse(streamID, timestamp, nonce, WeComAIBotStreamResponse{
+			MsgType: "stream",
+			Stream: WeComAIBotStreamInfo{
+				ID:      streamID,
+				Finish:  true,
+				Content: "Task not found or already finished. Please resend your message to start a new session.",
+			},
+		})
+	}
+
+	// Get next response
+	return c.getStreamResponse(task, timestamp, nonce)
+}
+
+// handleImageMessage handles image messages
+func (c *WeComAIBotChannel) handleImageMessage(
+	ctx context.Context,
+	msg WeComAIBotMessage,
+	timestamp, nonce string,
+) string {
+	logger.WarnC("wecom_aibot", "Image message type not yet fully implemented")
+	if msg.Image == nil {
+		logger.ErrorC("wecom_aibot", "Image message missing image field")
+		return c.encryptEmptyResponse(timestamp, nonce)
+	}
+
+	imageURL := msg.Image.URL
+
+	// For now, just acknowledge receipt without echoing the image
+	return c.encryptResponse("", timestamp, nonce, WeComAIBotStreamResponse{
+		MsgType: "stream",
+		Stream: WeComAIBotStreamInfo{
+			ID:     c.generateStreamID(),
+			Finish: true,
+			Content: fmt.Sprintf(
+				"Image received (URL: %s), but image messages are not yet supported",
+				imageURL,
+			),
+		},
+	})
+}
+
+// handleMixedMessage handles mixed (text + image) messages
+func (c *WeComAIBotChannel) handleMixedMessage(
+	ctx context.Context,
+	msg WeComAIBotMessage,
+	timestamp, nonce string,
+) string {
+	logger.WarnC("wecom_aibot", "Mixed message type not yet fully implemented")
+	return c.encryptResponse("", timestamp, nonce, WeComAIBotStreamResponse{
+		MsgType: "stream",
+		Stream: WeComAIBotStreamInfo{
+			ID:      c.generateStreamID(),
+			Finish:  true,
+			Content: "Mixed message type is not yet supported",
+		},
+	})
+}
+
+// handleEventMessage handles event messages
+func (c *WeComAIBotChannel) handleEventMessage(
+	ctx context.Context,
+	msg WeComAIBotMessage,
+	timestamp, nonce string,
+) string {
+	eventType := ""
+	if msg.Event != nil {
+		eventType = msg.Event.EventType
+	}
+	logger.DebugCF("wecom_aibot", "Received event", map[string]any{
+		"event_type": eventType,
+	})
+
+	// Send welcome message when user opens the chat window
+	if eventType == "enter_chat" && c.config.WelcomeMessage != "" {
+		streamID := c.generateStreamID()
+		return c.encryptResponse(streamID, timestamp, nonce, WeComAIBotStreamResponse{
+			MsgType: "stream",
+			Stream: WeComAIBotStreamInfo{
+				ID:      streamID,
+				Finish:  true,
+				Content: c.config.WelcomeMessage,
+			},
+		})
+	}
+
+	return c.encryptEmptyResponse(timestamp, nonce)
+}
+
+// getStreamResponse gets the next streaming response for a task.
+// - If agent replied: return finish=true with the real answer.
+// - If deadline passed: return finish=true with a "please wait" notice, keep task alive for response_url.
+// - Otherwise: return finish=false (empty), client will poll again.
+func (c *WeComAIBotChannel) getStreamResponse(task *streamTask, timestamp, nonce string) string {
+	var content string
+	var finish bool
+	var closeStreamOnly bool // close stream but do NOT remove task (response_url still pending)
+
+	select {
+	case answer := <-task.answerCh:
+		// Agent replied before deadline — normal finish.
+		content = answer
+		finish = true
+	default:
+		if time.Now().After(task.Deadline) {
+			// Deadline reached: close the stream with a notice, then wait for agent via response_url.
+			content = "⏳ Processing, please wait. The results will be sent shortly."
+			finish = true
+			closeStreamOnly = true
+			logger.InfoCF(
+				"wecom_aibot",
+				"Stream deadline reached, switching to response_url mode",
+				map[string]any{
+					"stream_id":    task.StreamID,
+					"chat_id":      task.ChatID,
+					"response_url": task.ResponseURL != "",
+				},
+			)
+		}
+		// else: still waiting, return finish=false
+	}
+
+	if finish && !closeStreamOnly {
+		// Normal finish: remove from all maps.
+		c.removeTask(task)
+	} else if closeStreamOnly {
+		// Mark stream as closed and remove from streamTasks under a single lock
+		// to keep StreamClosed/StreamClosedAt consistent with map membership.
+		c.taskMu.Lock()
+		task.StreamClosed = true
+		task.StreamClosedAt = time.Now()
+		delete(c.streamTasks, task.StreamID)
+		c.taskMu.Unlock()
+	}
+
+	response := WeComAIBotStreamResponse{
+		MsgType: "stream",
+		Stream: WeComAIBotStreamInfo{
+			ID:      task.StreamID,
+			Finish:  finish,
+			Content: content,
+		},
+	}
+
+	return c.encryptResponse(task.StreamID, timestamp, nonce, response)
+}
+
+// removeTask removes a task from both streamTasks and chatTasks, marks it finished,
+// and cancels its context to interrupt the associated agent goroutine.
+func (c *WeComAIBotChannel) removeTask(task *streamTask) {
+	// Cancel first so the agent goroutine stops as soon as possible,
+	// before we acquire the write lock.
+	task.cancel()
+
+	c.taskMu.Lock()
+	task.Finished = true // written under c.taskMu, consistent with all readers
+	delete(c.streamTasks, task.StreamID)
+	queue := c.chatTasks[task.ChatID]
+	for i, t := range queue {
+		if t == task {
+			c.chatTasks[task.ChatID] = append(queue[:i], queue[i+1:]...)
+			break
+		}
+	}
+	if len(c.chatTasks[task.ChatID]) == 0 {
+		delete(c.chatTasks, task.ChatID)
+	}
+	c.taskMu.Unlock()
+}
+
+// sendViaResponseURL posts a markdown reply to the WeCom response_url.
+// response_url is valid for 1 hour and can only be used once per callback.
+// Returned errors are wrapped with channels.ErrRateLimit, channels.ErrTemporary,
+// or channels.ErrSendFailed so the manager can apply the right retry policy.
+func (c *WeComAIBotChannel) sendViaResponseURL(responseURL, content string) error {
+	payload := map[string]any{
+		"msgtype": "markdown",
+		"markdown": map[string]string{
+			"content": content,
+		},
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("failed to marshal payload: %w", err)
+	}
+
+	ctx, cancel := context.WithTimeout(c.ctx, 15*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, responseURL, bytes.NewBuffer(body))
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json; charset=utf-8")
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("post to response_url failed: %w: %w", channels.ErrTemporary, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == http.StatusOK {
+		return nil
+	}
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("reading response_url body: %w: %w", channels.ErrTemporary, err)
+	}
+	switch {
+	case resp.StatusCode == http.StatusTooManyRequests:
+		return fmt.Errorf("response_url rate limited (%d): %s: %w",
+			resp.StatusCode, respBody, channels.ErrRateLimit)
+	case resp.StatusCode >= 500:
+		return fmt.Errorf("response_url server error (%d): %s: %w",
+			resp.StatusCode, respBody, channels.ErrTemporary)
+	default:
+		return fmt.Errorf("response_url returned %d: %s: %w",
+			resp.StatusCode, respBody, channels.ErrSendFailed)
+	}
+}
+
+// encryptResponse encrypts a streaming response
+func (c *WeComAIBotChannel) encryptResponse(
+	streamID, timestamp, nonce string,
+	response WeComAIBotStreamResponse,
+) string {
+	// Marshal response to JSON
+	plaintext, err := json.Marshal(response)
+	if err != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to marshal response", map[string]any{
+			"error": err,
+		})
+		return ""
+	}
+
+	logger.DebugCF("wecom_aibot", "Encrypting response", map[string]any{
+		"stream_id": streamID,
+		"finish":    response.Stream.Finish,
+		"preview":   utils.Truncate(response.Stream.Content, 100),
+	})
+
+	// Encrypt message
+	encrypted, err := c.encryptMessage(string(plaintext), "")
+	if err != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to encrypt message", map[string]any{
+			"error": err,
+		})
+		return ""
+	}
+
+	// Generate signature
+	signature := computeSignature(c.config.Token, timestamp, nonce, encrypted)
+
+	// Build encrypted response
+	encryptedResp := WeComAIBotEncryptedResponse{
+		Encrypt:      encrypted,
+		MsgSignature: signature,
+		Timestamp:    timestamp,
+		Nonce:        nonce,
+	}
+
+	respJSON, err := json.Marshal(encryptedResp)
+	if err != nil {
+		logger.ErrorCF("wecom_aibot", "Failed to marshal encrypted response", map[string]any{
+			"error": err,
+		})
+		return ""
+	}
+
+	logger.DebugCF("wecom_aibot", "Response encrypted", map[string]any{
+		"stream_id": streamID,
+	})
+
+	return string(respJSON)
+}
+
+// encryptEmptyResponse returns a minimal valid encrypted response
+func (c *WeComAIBotChannel) encryptEmptyResponse(timestamp, nonce string) string {
+	// Construct a zero-value stream response and encrypt it so that
+	// WeCom always receives a syntactically valid encrypted JSON object.
+	emptyResp := WeComAIBotStreamResponse{}
+	return c.encryptResponse("", timestamp, nonce, emptyResp)
+}
+
+// encryptMessage encrypts a plain text message for WeCom AI Bot
+func (c *WeComAIBotChannel) encryptMessage(plaintext, receiveid string) (string, error) {
+	aesKey, err := decodeWeComAESKey(c.config.EncodingAESKey)
+	if err != nil {
+		return "", err
+	}
+
+	frame, err := packWeComFrame(plaintext, receiveid)
+	if err != nil {
+		return "", err
+	}
+
+	// PKCS7 padding then AES-CBC encrypt
+	paddedFrame := pkcs7Pad(frame, blockSize)
+	ciphertext, err := encryptAESCBC(aesKey, paddedFrame)
+	if err != nil {
+		return "", err
+	}
+
+	return base64.StdEncoding.EncodeToString(ciphertext), nil
+}
+
+// generateStreamID generates a random stream ID
+func (c *WeComAIBotChannel) generateStreamID() string {
+	const letters = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	b := make([]byte, 10)
+	for i := range b {
+		n, _ := rand.Int(rand.Reader, big.NewInt(int64(len(letters))))
+		b[i] = letters[n.Int64()]
+	}
+	return string(b)
+}
+
+// cleanupLoop periodically cleans up old streaming tasks
+func (c *WeComAIBotChannel) cleanupLoop() {
+	ticker := time.NewTicker(5 * time.Minute)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			c.cleanupOldTasks()
+		case <-c.ctx.Done():
+			return
+		}
+	}
+}
+
+// cleanupOldTasks removes tasks that have exceeded their expected lifetime:
+//   - Active tasks (in streamTasks): cleaned up after 1 hour (response_url validity window).
+//   - StreamClosed tasks (in chatTasks only): cleaned up after streamClosedGracePeriod.
+//     These tasks are waiting for the agent to call Send() via response_url. If the agent
+//     crashes or times out without calling Send(), we must not let them accumulate indefinitely.
+//     The grace period is generous enough to cover typical LLM latency but far shorter than 1 hour,
+//     preventing chatTasks from filling up when many requests time out in quick succession.
+const (
+	streamClosedGracePeriod = 10 * time.Minute // max wait for agent after stream closes
+	taskMaxLifetime         = 1 * time.Hour    // absolute max (≈ response_url validity)
+)
+
+func (c *WeComAIBotChannel) cleanupOldTasks() {
+	c.taskMu.Lock()
+	defer c.taskMu.Unlock()
+
+	now := time.Now()
+	cutoff := now.Add(-taskMaxLifetime)
+	for id, task := range c.streamTasks {
+		if task.CreatedTime.Before(cutoff) {
+			delete(c.streamTasks, id)
+			task.cancel() // interrupt agent goroutine still waiting for LLM
+			queue := c.chatTasks[task.ChatID]
+			for i, t := range queue {
+				if t == task {
+					c.chatTasks[task.ChatID] = append(queue[:i], queue[i+1:]...)
+					break
+				}
+			}
+			if len(c.chatTasks[task.ChatID]) == 0 {
+				delete(c.chatTasks, task.ChatID)
+			}
+			logger.DebugCF("wecom_aibot", "Cleaned up expired task", map[string]any{
+				"stream_id": id,
+			})
+		}
+	}
+	// Clean up StreamClosed tasks from chatTasks.
+	// Two expiry conditions are checked:
+	//  1. Absolute expiry: task was created more than taskMaxLifetime ago.
+	//  2. Grace expiry: stream closed more than streamClosedGracePeriod ago
+	//     (agent had enough time to reply; it is not coming back).
+	for chatID, queue := range c.chatTasks {
+		filtered := queue[:0]
+		for i, t := range queue {
+			absoluteExpired := t.CreatedTime.Before(cutoff)
+			graceExpired := t.StreamClosed &&
+				!t.StreamClosedAt.IsZero() &&
+				t.StreamClosedAt.Before(now.Add(-streamClosedGracePeriod))
+			if t.Finished {
+				// Finished tasks should have been removed by removeTask().
+				// Finding one here (especially not at position 0) means an
+				// unexpected code path left it stranded, causing the queue to
+				// grow silently. Log a warning so it is visible, then drop it.
+				if i > 0 {
+					logger.WarnCF("wecom_aibot",
+						"Found stranded Finished task in the middle of chatTasks queue; "+
+							"this should not happen — removeTask() should have spliced it out",
+						map[string]any{
+							"chat_id":   chatID,
+							"stream_id": t.StreamID,
+							"position":  i,
+						})
+				}
+				// The task is already finished; its context was already canceled
+				// by removeTask(), so no further action is required.
+				continue
+			} else if !absoluteExpired && !graceExpired {
+				filtered = append(filtered, t)
+			} else {
+				t.cancel() // cancel any lingering agent goroutine
+			}
+		}
+		if len(filtered) == 0 {
+			delete(c.chatTasks, chatID)
+		} else {
+			c.chatTasks[chatID] = filtered
+		}
+	}
+}
+
+// handleHealth handles health check requests
+func (c *WeComAIBotChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
+	status := "ok"
+	if !c.IsRunning() {
+		status = "not running"
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(map[string]string{
+		"status": status,
+	})
+}
diff --git a/pkg/channels/wecom/aibot_test.go b/pkg/channels/wecom/aibot_test.go
new file mode 100644
index 000000000..6f0664187
--- /dev/null
+++ b/pkg/channels/wecom/aibot_test.go
@@ -0,0 +1,210 @@
+package wecom
+
+import (
+	"context"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewWeComAIBotChannel(t *testing.T) {
+	t.Run("success with valid config", func(t *testing.T) {
+		cfg := config.WeComAIBotConfig{
+			Enabled:        true,
+			Token:          "test_token",
+			EncodingAESKey: "testkey1234567890123456789012345678901234567",
+			WebhookPath:    "/webhook/test",
+		}
+
+		messageBus := bus.NewMessageBus()
+		ch, err := NewWeComAIBotChannel(cfg, messageBus)
+		if err != nil {
+			t.Fatalf("Expected no error, got %v", err)
+		}
+
+		if ch == nil {
+			t.Fatal("Expected channel to be created")
+		}
+
+		if ch.Name() != "wecom_aibot" {
+			t.Errorf("Expected name 'wecom_aibot', got '%s'", ch.Name())
+		}
+	})
+
+	t.Run("error with missing token", func(t *testing.T) {
+		cfg := config.WeComAIBotConfig{
+			Enabled:        true,
+			EncodingAESKey: "testkey1234567890123456789012345678901234567",
+		}
+
+		messageBus := bus.NewMessageBus()
+		_, err := NewWeComAIBotChannel(cfg, messageBus)
+
+		if err == nil {
+			t.Fatal("Expected error for missing token, got nil")
+		}
+	})
+
+	t.Run("error with missing encoding key", func(t *testing.T) {
+		cfg := config.WeComAIBotConfig{
+			Enabled: true,
+			Token:   "test_token",
+		}
+
+		messageBus := bus.NewMessageBus()
+		_, err := NewWeComAIBotChannel(cfg, messageBus)
+
+		if err == nil {
+			t.Fatal("Expected error for missing encoding key, got nil")
+		}
+	})
+}
+
+func TestWeComAIBotChannelStartStop(t *testing.T) {
+	cfg := config.WeComAIBotConfig{
+		Enabled:        true,
+		Token:          "test_token",
+		EncodingAESKey: "testkey1234567890123456789012345678901234567",
+	}
+
+	messageBus := bus.NewMessageBus()
+	ch, err := NewWeComAIBotChannel(cfg, messageBus)
+	if err != nil {
+		t.Fatalf("Failed to create channel: %v", err)
+	}
+
+	ctx := context.Background()
+
+	// Test Start
+	if err := ch.Start(ctx); err != nil {
+		t.Fatalf("Failed to start channel: %v", err)
+	}
+
+	if !ch.IsRunning() {
+		t.Error("Expected channel to be running")
+	}
+
+	// Test Stop
+	if err := ch.Stop(ctx); err != nil {
+		t.Fatalf("Failed to stop channel: %v", err)
+	}
+
+	if ch.IsRunning() {
+		t.Error("Expected channel to be stopped")
+	}
+}
+
+func TestWeComAIBotChannelWebhookPath(t *testing.T) {
+	t.Run("default path", func(t *testing.T) {
+		cfg := config.WeComAIBotConfig{
+			Enabled:        true,
+			Token:          "test_token",
+			EncodingAESKey: "testkey1234567890123456789012345678901234567",
+		}
+
+		messageBus := bus.NewMessageBus()
+		ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+		expectedPath := "/webhook/wecom-aibot"
+		if ch.WebhookPath() != expectedPath {
+			t.Errorf("Expected webhook path '%s', got '%s'", expectedPath, ch.WebhookPath())
+		}
+	})
+
+	t.Run("custom path", func(t *testing.T) {
+		customPath := "/custom/webhook"
+		cfg := config.WeComAIBotConfig{
+			Enabled:        true,
+			Token:          "test_token",
+			EncodingAESKey: "testkey1234567890123456789012345678901234567",
+			WebhookPath:    customPath,
+		}
+
+		messageBus := bus.NewMessageBus()
+		ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+		if ch.WebhookPath() != customPath {
+			t.Errorf("Expected webhook path '%s', got '%s'", customPath, ch.WebhookPath())
+		}
+	})
+}
+
+func TestGenerateStreamID(t *testing.T) {
+	cfg := config.WeComAIBotConfig{
+		Enabled:        true,
+		Token:          "test_token",
+		EncodingAESKey: "testkey1234567890123456789012345678901234567",
+	}
+
+	messageBus := bus.NewMessageBus()
+	ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+	// Generate multiple IDs and check they are unique
+	ids := make(map[string]bool)
+	for i := 0; i < 100; i++ {
+		id := ch.generateStreamID()
+
+		if len(id) != 10 {
+			t.Errorf("Expected stream ID length 10, got %d", len(id))
+		}
+
+		if ids[id] {
+			t.Errorf("Duplicate stream ID generated: %s", id)
+		}
+		ids[id] = true
+	}
+}
+
+func TestEncryptDecrypt(t *testing.T) {
+	// Use a valid 43-character base64 key (企业微信标准格式)
+	cfg := config.WeComAIBotConfig{
+		Enabled:        true,
+		Token:          "test_token",
+		EncodingAESKey: "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG", // 43 characters
+	}
+
+	messageBus := bus.NewMessageBus()
+	ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+	plaintext := "Hello, World!"
+	receiveid := ""
+
+	// Encrypt
+	encrypted, err := ch.encryptMessage(plaintext, receiveid)
+	if err != nil {
+		t.Fatalf("Failed to encrypt message: %v", err)
+	}
+
+	if encrypted == "" {
+		t.Fatal("Encrypted message is empty")
+	}
+
+	// Decrypt
+	decrypted, err := decryptMessageWithVerify(encrypted, cfg.EncodingAESKey, receiveid)
+	if err != nil {
+		t.Fatalf("Failed to decrypt message: %v", err)
+	}
+
+	if decrypted != plaintext {
+		t.Errorf("Expected decrypted message '%s', got '%s'", plaintext, decrypted)
+	}
+}
+
+func TestGenerateSignature(t *testing.T) {
+	token := "test_token"
+	timestamp := "1234567890"
+	nonce := "test_nonce"
+	encrypt := "encrypted_msg"
+
+	signature := computeSignature(token, timestamp, nonce, encrypt)
+
+	if signature == "" {
+		t.Error("Generated signature is empty")
+	}
+
+	// Verify signature using verifySignature function
+	if !verifySignature(token, signature, timestamp, nonce, encrypt) {
+		t.Error("Generated signature does not verify correctly")
+	}
+}
diff --git a/pkg/channels/wecom_app.go b/pkg/channels/wecom/app.go
similarity index 65%
rename from pkg/channels/wecom_app.go
rename to pkg/channels/wecom/app.go
index 715c48707..2098fcd4e 100644
--- a/pkg/channels/wecom_app.go
+++ b/pkg/channels/wecom/app.go
@@ -1,8 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom App (企业微信自建应用) channel implementation
-// Supports receiving messages via webhook callback and sending messages proactively
-
-package channels
+package wecom
 
 import (
 	"bytes"
@@ -11,14 +7,19 @@ import (
 	"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"
 )
@@ -29,16 +30,15 @@ const (
 
 // WeComAppChannel implements the Channel interface for WeCom App (企业微信自建应用)
 type WeComAppChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config        config.WeComAppConfig
-	server        *http.Server
+	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
+	processedMsgs *MessageDeduplicator
 }
 
 // WeComXMLMessage represents the XML message structure from WeCom
@@ -123,12 +123,27 @@ func NewWeComAppChannel(cfg config.WeComAppConfig, messageBus *bus.MessageBus) (
 		return nil, fmt.Errorf("wecom_app corp_id, corp_secret and agent_id are required")
 	}
 
-	base := NewBaseChannel("wecom_app", cfg, messageBus, cfg.AllowFrom)
+	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,
-		processedMsgs: make(map[string]bool),
+		client:        &http.Client{Timeout: clientTimeout},
+		ctx:           ctx,
+		cancel:        cancel,
+		processedMsgs: NewMessageDeduplicator(wecomMaxProcessedMessages),
 	}, nil
 }
 
@@ -137,10 +152,14 @@ func (c *WeComAppChannel) Name() string {
 	return "wecom_app"
 }
 
-// Start initializes the WeCom App channel with HTTP webhook server
+// 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
@@ -153,37 +172,8 @@ func (c *WeComAppChannel) Start(ctx context.Context) error {
 	// Start token refresh goroutine
 	go c.tokenRefreshLoop()
 
-	// Setup HTTP server for webhook
-	mux := http.NewServeMux()
-	webhookPath := c.config.WebhookPath
-	if webhookPath == "" {
-		webhookPath = "/webhook/wecom-app"
-	}
-	mux.HandleFunc(webhookPath, c.handleWebhook)
-
-	// Health check endpoint
-	mux.HandleFunc("/health/wecom-app", c.handleHealth)
-
-	addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
-	c.server = &http.Server{
-		Addr:    addr,
-		Handler: mux,
-	}
-
-	c.setRunning(true)
-	logger.InfoCF("wecom_app", "WeCom App channel started", map[string]any{
-		"address": addr,
-		"path":    webhookPath,
-	})
-
-	// Start server in goroutine
-	go func() {
-		if err := c.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			logger.ErrorCF("wecom_app", "HTTP server error", map[string]any{
-				"error": err.Error(),
-			})
-		}
-	}()
+	c.SetRunning(true)
+	logger.InfoC("wecom_app", "WeCom App channel started")
 
 	return nil
 }
@@ -196,13 +186,7 @@ func (c *WeComAppChannel) Stop(ctx context.Context) error {
 		c.cancel()
 	}
 
-	if c.server != nil {
-		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
-		defer cancel()
-		c.server.Shutdown(shutdownCtx)
-	}
-
-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("wecom_app", "WeCom App channel stopped")
 	return nil
 }
@@ -210,7 +194,7 @@ func (c *WeComAppChannel) Stop(ctx context.Context) error {
 // 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 fmt.Errorf("wecom_app channel not running")
+		return channels.ErrNotRunning
 	}
 
 	accessToken := c.getAccessToken()
@@ -226,6 +210,240 @@ func (c *WeComAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
 	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, readErr := io.ReadAll(resp.Body)
+		if readErr != nil {
+			return "", channels.ClassifySendError(
+				resp.StatusCode,
+				fmt.Errorf("reading wecom upload error response: %w", readErr),
+			)
+		}
+		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
+}
+
+// sendWeComMessage marshals payload and POSTs it to the WeCom message API.
+func (c *WeComAppChannel) sendWeComMessage(ctx context.Context, accessToken string, payload any) error {
+	apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
+
+	jsonData, err := json.Marshal(payload)
+	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, readErr := io.ReadAll(resp.Body)
+		if readErr != nil {
+			return channels.ClassifySendError(
+				resp.StatusCode,
+				fmt.Errorf("reading wecom_app error response: %w", readErr),
+			)
+		}
+		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
+}
+
+// sendImageMessage sends an image message using a media_id.
+func (c *WeComAppChannel) sendImageMessage(ctx context.Context, accessToken, userID, mediaID string) error {
+	msg := WeComImageMessage{
+		ToUser:  userID,
+		MsgType: "image",
+		AgentID: c.config.AgentID,
+	}
+	msg.Image.MediaID = mediaID
+	return c.sendWeComMessage(ctx, accessToken, msg)
+}
+
+// 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()
@@ -279,7 +497,7 @@ func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.Respons
 	}
 
 	// Verify signature
-	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+	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,
@@ -298,7 +516,7 @@ func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.Respons
 		"encoding_aes_key": c.config.EncodingAESKey,
 		"corp_id":          c.config.CorpID,
 	})
-	decryptedEchoStr, err := WeComDecryptMessageWithVerify(echostr, c.config.EncodingAESKey, 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(),
@@ -357,7 +575,7 @@ func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.Resp
 	}
 
 	// Verify signature
-	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+	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
@@ -365,7 +583,7 @@ func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.Resp
 
 	// Decrypt message with CorpID verification
 	// For WeCom App (自建应用), receiveid should be corp_id
-	decryptedMsg, err := WeComDecryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, c.config.CorpID)
+	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(),
@@ -384,8 +602,9 @@ func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.Resp
 		return
 	}
 
-	// Process the message with context
-	go c.processMessage(ctx, msg)
+	// 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)
@@ -405,29 +624,21 @@ func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessag
 	// 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()
+	if !c.processedMsgs.MarkMessageProcessed(msgID) {
 		logger.DebugCF("wecom_app", "Skipping duplicate message", map[string]any{
 			"msg_id": msgID,
 		})
 		return
 	}
-	c.processedMsgs[msgID] = true
-	c.msgMu.Unlock()
-
-	// Clean up old messages periodically (keep last 1000)
-	if len(c.processedMsgs) > 1000 {
-		c.msgMu.Lock()
-		c.processedMsgs = make(map[string]bool)
-		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),
@@ -435,8 +646,6 @@ func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessag
 		"platform":    "wecom_app",
 		"media_id":    msg.MediaId,
 		"create_time": fmt.Sprintf("%d", msg.CreateTime),
-		"peer_kind":   "direct",
-		"peer_id":     senderID,
 	}
 
 	content := msg.Content
@@ -447,8 +656,15 @@ func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessag
 		"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(senderID, chatID, content, nil, metadata)
+	c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, nil, metadata, appSender)
 }
 
 // tokenRefreshLoop periodically refreshes the access token
@@ -516,114 +732,15 @@ func (c *WeComAppChannel) getAccessToken() string {
 	return c.accessToken
 }
 
-// sendTextMessage sends a text message to a user
+// 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")
-
-	client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
-	resp, err := client.Do(req)
-	if err != nil {
-		return fmt.Errorf("failed to send message: %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 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
-}
-
-// sendMarkdownMessage sends a markdown message to a user
-func (c *WeComAppChannel) sendMarkdownMessage(ctx context.Context, accessToken, userID, content string) error {
-	apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
-
-	msg := WeComMarkdownMessage{
-		ToUser:  userID,
-		MsgType: "markdown",
-		AgentID: c.config.AgentID,
-	}
-	msg.Markdown.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")
-
-	client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
-	resp, err := client.Do(req)
-	if err != nil {
-		return fmt.Errorf("failed to send message: %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 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
+	return c.sendWeComMessage(ctx, accessToken, msg)
 }
 
 // handleHealth handles health check requests
diff --git a/pkg/channels/wecom_app_test.go b/pkg/channels/wecom/app_test.go
similarity index 92%
rename from pkg/channels/wecom_app_test.go
rename to pkg/channels/wecom/app_test.go
index abf15c52b..7f230494f 100644
--- a/pkg/channels/wecom_app_test.go
+++ b/pkg/channels/wecom/app_test.go
@@ -1,7 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom App (企业微信自建应用) channel tests
-
-package channels
+package wecom
 
 import (
 	"bytes"
@@ -46,7 +43,7 @@ func encryptTestMessageApp(message, aesKey string) (string, error) {
 
 	// Prepare message: random(16) + msg_len(4) + msg + corp_id
 	random := make([]byte, 0, 16)
-	for i := 0; i < 16; i++ {
+	for i := range 16 {
 		random = append(random, byte(i+1))
 	}
 
@@ -197,7 +194,7 @@ func TestWeComAppVerifySignature(t *testing.T) {
 		msgEncrypt := "test_message"
 		expectedSig := generateSignatureApp("test_token", timestamp, nonce, msgEncrypt)
 
-		if !WeComVerifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
+		if !verifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
 			t.Error("valid signature should pass verification")
 		}
 	})
@@ -207,7 +204,7 @@ func TestWeComAppVerifySignature(t *testing.T) {
 		nonce := "test_nonce"
 		msgEncrypt := "test_message"
 
-		if WeComVerifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
+		if verifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
 			t.Error("invalid signature should fail verification")
 		}
 	})
@@ -221,7 +218,7 @@ func TestWeComAppVerifySignature(t *testing.T) {
 		}
 		chEmpty, _ := NewWeComAppChannel(cfgEmpty, msgBus)
 
-		if !WeComVerifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
+		if !verifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
 			t.Error("empty token should skip verification and return true")
 		}
 	})
@@ -243,7 +240,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
 		plainText := "hello world"
 		encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
 
-		result, err := WeComDecryptMessage(encoded, ch.config.EncodingAESKey)
+		result, err := decryptMessage(encoded, ch.config.EncodingAESKey)
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
@@ -268,7 +265,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
 			t.Fatalf("failed to encrypt test message: %v", err)
 		}
 
-		result, err := WeComDecryptMessage(encrypted, ch.config.EncodingAESKey)
+		result, err := decryptMessage(encrypted, ch.config.EncodingAESKey)
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
@@ -286,7 +283,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
 		}
 		ch, _ := NewWeComAppChannel(cfg, msgBus)
 
-		_, err := WeComDecryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
+		_, err := decryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
 		if err == nil {
 			t.Error("expected error for invalid base64, got nil")
 		}
@@ -301,7 +298,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
 		}
 		ch, _ := NewWeComAppChannel(cfg, msgBus)
 
-		_, err := WeComDecryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
+		_, err := decryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
 		if err == nil {
 			t.Error("expected error for invalid AES key, got nil")
 		}
@@ -319,67 +316,13 @@ func TestWeComAppDecryptMessage(t *testing.T) {
 
 		// Encrypt a very short message that results in ciphertext less than block size
 		shortData := make([]byte, 8)
-		_, err := WeComDecryptMessage(base64.StdEncoding.EncodeToString(shortData), ch.config.EncodingAESKey)
+		_, 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 := pkcs7UnpadWeCom(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()
@@ -852,6 +795,28 @@ func TestWeComAppMessageStructures(t *testing.T) {
 		}
 	})
 
+	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,
diff --git a/pkg/channels/wecom.go b/pkg/channels/wecom/bot.go
similarity index 62%
rename from pkg/channels/wecom.go
rename to pkg/channels/wecom/bot.go
index f8daf89de..96d5a961f 100644
--- a/pkg/channels/wecom.go
+++ b/pkg/channels/wecom/bot.go
@@ -1,29 +1,20 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom Bot (企业微信智能机器人) channel implementation
-// Uses webhook callback mode for receiving messages and webhook API for sending replies
-
-package channels
+package wecom
 
 import (
 	"bytes"
 	"context"
-	"crypto/aes"
-	"crypto/cipher"
-	"crypto/sha1"
-	"encoding/base64"
-	"encoding/binary"
 	"encoding/json"
 	"encoding/xml"
 	"fmt"
 	"io"
 	"net/http"
-	"sort"
 	"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"
 )
@@ -31,13 +22,12 @@ import (
 // WeComBotChannel implements the Channel interface for WeCom Bot (企业微信智能机器人)
 // Uses webhook callback mode - simpler than WeCom App but only supports passive replies
 type WeComBotChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config        config.WeComConfig
-	server        *http.Server
+	client        *http.Client
 	ctx           context.Context
 	cancel        context.CancelFunc
-	processedMsgs map[string]bool // Message deduplication: msg_id -> processed
-	msgMu         sync.RWMutex
+	processedMsgs *MessageDeduplicator
 }
 
 // WeComBotMessage represents the JSON message structure from WeCom Bot (AIBOT)
@@ -96,12 +86,27 @@ func NewWeComBotChannel(cfg config.WeComConfig, messageBus *bus.MessageBus) (*We
 		return nil, fmt.Errorf("wecom token and webhook_url are required")
 	}
 
-	base := NewBaseChannel("wecom", cfg, messageBus, cfg.AllowFrom)
+	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,
-		processedMsgs: make(map[string]bool),
+		client:        &http.Client{Timeout: clientTimeout},
+		ctx:           ctx,
+		cancel:        cancel,
+		processedMsgs: NewMessageDeduplicator(wecomMaxProcessedMessages),
 	}, nil
 }
 
@@ -110,43 +115,18 @@ func (c *WeComBotChannel) Name() string {
 	return "wecom"
 }
 
-// Start initializes the WeCom Bot channel with HTTP webhook server
+// 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)
 
-	// Setup HTTP server for webhook
-	mux := http.NewServeMux()
-	webhookPath := c.config.WebhookPath
-	if webhookPath == "" {
-		webhookPath = "/webhook/wecom"
-	}
-	mux.HandleFunc(webhookPath, c.handleWebhook)
-
-	// Health check endpoint
-	mux.HandleFunc("/health/wecom", c.handleHealth)
-
-	addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
-	c.server = &http.Server{
-		Addr:    addr,
-		Handler: mux,
-	}
-
-	c.setRunning(true)
-	logger.InfoCF("wecom", "WeCom Bot channel started", map[string]any{
-		"address": addr,
-		"path":    webhookPath,
-	})
-
-	// Start server in goroutine
-	go func() {
-		if err := c.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			logger.ErrorCF("wecom", "HTTP server error", map[string]any{
-				"error": err.Error(),
-			})
-		}
-	}()
+	c.SetRunning(true)
+	logger.InfoC("wecom", "WeCom Bot channel started")
 
 	return nil
 }
@@ -159,13 +139,7 @@ func (c *WeComBotChannel) Stop(ctx context.Context) error {
 		c.cancel()
 	}
 
-	if c.server != nil {
-		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
-		defer cancel()
-		c.server.Shutdown(shutdownCtx)
-	}
-
-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("wecom", "WeCom Bot channel stopped")
 	return nil
 }
@@ -175,7 +149,7 @@ func (c *WeComBotChannel) Stop(ctx context.Context) error {
 // For delayed responses, we use the webhook URL
 func (c *WeComBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("wecom channel not running")
+		return channels.ErrNotRunning
 	}
 
 	logger.DebugCF("wecom", "Sending message via webhook", map[string]any{
@@ -186,6 +160,29 @@ func (c *WeComBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
 	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()
@@ -219,7 +216,7 @@ func (c *WeComBotChannel) handleVerification(ctx context.Context, w http.Respons
 	}
 
 	// Verify signature
-	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+	if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
 		logger.WarnC("wecom", "Signature verification failed")
 		http.Error(w, "Invalid signature", http.StatusForbidden)
 		return
@@ -228,7 +225,7 @@ func (c *WeComBotChannel) handleVerification(ctx context.Context, w http.Respons
 	// Decrypt echostr
 	// For AIBOT (智能机器人), receiveid should be empty string ""
 	// Reference: https://developer.work.weixin.qq.com/document/path/101033
-	decryptedEchoStr, err := WeComDecryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
+	decryptedEchoStr, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
 	if err != nil {
 		logger.ErrorCF("wecom", "Failed to decrypt echostr", map[string]any{
 			"error": err.Error(),
@@ -281,7 +278,7 @@ func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.Resp
 	}
 
 	// Verify signature
-	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+	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
@@ -290,7 +287,7 @@ func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.Resp
 	// Decrypt message
 	// For AIBOT (智能机器人), receiveid should be empty string ""
 	// Reference: https://developer.work.weixin.qq.com/document/path/101033
-	decryptedMsg, err := WeComDecryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
+	decryptedMsg, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
 	if err != nil {
 		logger.ErrorCF("wecom", "Failed to decrypt message", map[string]any{
 			"error": err.Error(),
@@ -309,8 +306,9 @@ func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.Resp
 		return
 	}
 
-	// Process the message asynchronously with context
-	go c.processMessage(ctx, msg)
+	// 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)
@@ -330,23 +328,12 @@ func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessag
 
 	// Message deduplication: Use msg_id to prevent duplicate processing
 	msgID := msg.MsgID
-	c.msgMu.Lock()
-	if c.processedMsgs[msgID] {
-		c.msgMu.Unlock()
+	if !c.processedMsgs.MarkMessageProcessed(msgID) {
 		logger.DebugCF("wecom", "Skipping duplicate message", map[string]any{
 			"msg_id": msgID,
 		})
 		return
 	}
-	c.processedMsgs[msgID] = true
-	c.msgMu.Unlock()
-
-	// Clean up old messages periodically (keep last 1000)
-	if len(c.processedMsgs) > 1000 {
-		c.msgMu.Lock()
-		c.processedMsgs = make(map[string]bool)
-		c.msgMu.Unlock()
-	}
 
 	senderID := msg.From.UserID
 
@@ -387,12 +374,21 @@ func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessag
 	}
 
 	// 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",
-		"peer_kind":    peerKind,
-		"peer_id":      peerID,
 		"response_url": msg.ResponseURL,
 	}
 	if isGroupChat {
@@ -408,8 +404,19 @@ func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessag
 		"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(senderID, chatID, content, nil, metadata)
+	c.HandleMessage(ctx, peer, msg.MsgID, senderID, chatID, content, nil, metadata, sender)
 }
 
 // sendWebhookReply sends a reply using the webhook URL
@@ -439,13 +446,26 @@ func (c *WeComBotChannel) sendWebhookReply(ctx context.Context, userID, content
 	}
 	req.Header.Set("Content-Type", "application/json")
 
-	client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
-	resp, err := client.Do(req)
+	resp, err := c.client.Do(req)
 	if err != nil {
-		return fmt.Errorf("failed to send webhook reply: %w", err)
+		return channels.ClassifyNetError(err)
 	}
 	defer resp.Body.Close()
 
+	if resp.StatusCode != http.StatusOK {
+		body, readErr := io.ReadAll(resp.Body)
+		if readErr != nil {
+			return channels.ClassifySendError(
+				resp.StatusCode,
+				fmt.Errorf("reading webhook error response: %w", readErr),
+			)
+		}
+		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)
@@ -477,129 +497,3 @@ func (c *WeComBotChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(status)
 }
-
-// WeCom common utilities for both WeCom Bot and WeCom App
-// The following functions were moved from wecom_common.go
-
-// WeComVerifySignature verifies the message signature for WeCom
-// This is a common function used by both WeCom Bot and WeCom App
-func WeComVerifySignature(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
-}
-
-// WeComDecryptMessage decrypts the encrypted message using AES
-// This is a common function used by both WeCom Bot and WeCom App
-// For AIBOT, receiveid should be the aibotid; for other apps, it should be corp_id
-func WeComDecryptMessage(encryptedMsg, encodingAESKey string) (string, error) {
-	return WeComDecryptMessageWithVerify(encryptedMsg, encodingAESKey, "")
-}
-
-// WeComDecryptMessageWithVerify decrypts the encrypted message and optionally verifies receiveid
-// receiveid: for AIBOT use aibotid, for WeCom App use corp_id. If empty, skip verification.
-func WeComDecryptMessageWithVerify(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 = pkcs7UnpadWeCom(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
-}
-
-// pkcs7UnpadWeCom removes PKCS7 padding with validation
-// WeCom uses block size of 32 (not standard AES block size of 16)
-const wecomBlockSize = 32
-
-func pkcs7UnpadWeCom(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 > wecomBlockSize {
-		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 := 0; i < padding; i++ {
-		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_test.go b/pkg/channels/wecom/bot_test.go
similarity index 91%
rename from pkg/channels/wecom_test.go
rename to pkg/channels/wecom/bot_test.go
index 8afa7e8c3..c053578b1 100644
--- a/pkg/channels/wecom_test.go
+++ b/pkg/channels/wecom/bot_test.go
@@ -1,7 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom Bot (企业微信智能机器人) channel tests
-
-package channels
+package wecom
 
 import (
 	"bytes"
@@ -45,7 +42,7 @@ func encryptTestMessage(message, aesKey string) (string, error) {
 
 	// Prepare message: random(16) + msg_len(4) + msg + receiveid
 	random := make([]byte, 0, 16)
-	for i := 0; i < 16; i++ {
+	for i := range 16 {
 		random = append(random, byte(i))
 	}
 
@@ -177,7 +174,7 @@ func TestWeComBotVerifySignature(t *testing.T) {
 		msgEncrypt := "test_message"
 		expectedSig := generateSignature("test_token", timestamp, nonce, msgEncrypt)
 
-		if !WeComVerifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
+		if !verifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
 			t.Error("valid signature should pass verification")
 		}
 	})
@@ -187,7 +184,7 @@ func TestWeComBotVerifySignature(t *testing.T) {
 		nonce := "test_nonce"
 		msgEncrypt := "test_message"
 
-		if WeComVerifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
+		if verifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
 			t.Error("invalid signature should fail verification")
 		}
 	})
@@ -202,7 +199,7 @@ func TestWeComBotVerifySignature(t *testing.T) {
 			config: cfgEmpty,
 		}
 
-		if !WeComVerifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
+		if !verifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
 			t.Error("empty token should skip verification and return true")
 		}
 	})
@@ -223,7 +220,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
 		plainText := "hello world"
 		encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
 
-		result, err := WeComDecryptMessage(encoded, ch.config.EncodingAESKey)
+		result, err := decryptMessage(encoded, ch.config.EncodingAESKey)
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
@@ -247,7 +244,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
 			t.Fatalf("failed to encrypt test message: %v", err)
 		}
 
-		result, err := WeComDecryptMessage(encrypted, ch.config.EncodingAESKey)
+		result, err := decryptMessage(encrypted, ch.config.EncodingAESKey)
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
 		}
@@ -264,7 +261,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
 		}
 		ch, _ := NewWeComBotChannel(cfg, msgBus)
 
-		_, err := WeComDecryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
+		_, err := decryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
 		if err == nil {
 			t.Error("expected error for invalid base64, got nil")
 		}
@@ -278,7 +275,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
 		}
 		ch, _ := NewWeComBotChannel(cfg, msgBus)
 
-		_, err := WeComDecryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
+		_, err := decryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
 		if err == nil {
 			t.Error("expected error for invalid AES key, got nil")
 		}
@@ -320,20 +317,20 @@ func TestWeComBotPKCS7Unpad(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			result, err := pkcs7UnpadWeCom(tt.input)
+			result, err := pkcs7Unpad(tt.input)
 			if tt.expected == nil {
 				// This case should return an error
 				if err == nil {
-					t.Errorf("pkcs7UnpadWeCom() expected error for invalid padding, got result: %v", result)
+					t.Errorf("pkcs7Unpad() expected error for invalid padding, got result: %v", result)
 				}
 				return
 			}
 			if err != nil {
-				t.Errorf("pkcs7UnpadWeCom() unexpected error: %v", err)
+				t.Errorf("pkcs7Unpad() unexpected error: %v", err)
 				return
 			}
 			if !bytes.Equal(result, tt.expected) {
-				t.Errorf("pkcs7UnpadWeCom() = %v, want %v", result, tt.expected)
+				t.Errorf("pkcs7Unpad() = %v, want %v", result, tt.expected)
 			}
 		})
 	}
@@ -415,22 +412,9 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
 	}
 	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
+	runBotMessageCallback := func(t *testing.T, jsonMsg string) *httptest.ResponseRecorder {
+		t.Helper()
 		encrypted, _ := encryptTestMessage(jsonMsg, aesKey)
-
-		// Create encrypted XML wrapper
 		encryptedWrapper := struct {
 			XMLName xml.Name `xml:"xml"`
 			Encrypt string   `xml:"Encrypt"`
@@ -438,20 +422,29 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
 			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)
+		return w
+	}
 
+	t.Run("valid direct message callback", func(t *testing.T) {
+		w := runBotMessageCallback(t, `{
+			"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"}
+		}`)
 		if w.Code != http.StatusOK {
 			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
 		}
@@ -461,8 +454,7 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
 	})
 
 	t.Run("valid group message callback", func(t *testing.T) {
-		// Create JSON message for group chat
-		jsonMsg := `{
+		w := runBotMessageCallback(t, `{
 			"msgid": "test_msg_id_456",
 			"aibotid": "test_aibot_id",
 			"chatid": "group_chat_id_123",
@@ -471,33 +463,7 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
 			"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)
 		}
diff --git a/pkg/channels/wecom/common.go b/pkg/channels/wecom/common.go
new file mode 100644
index 000000000..6510e6f81
--- /dev/null
+++ b/pkg/channels/wecom/common.go
@@ -0,0 +1,199 @@
+package wecom
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/sha1"
+	"encoding/base64"
+	"encoding/binary"
+	"fmt"
+	"math/big"
+	"sort"
+	"strings"
+)
+
+// blockSize is the PKCS7 block size used by WeCom (32)
+const blockSize = 32
+
+// computeSignature computes the WeCom message signature from the given parameters.
+// It sorts [token, timestamp, nonce, encrypt], concatenates them and returns the SHA1 hex digest.
+func computeSignature(token, timestamp, nonce, encrypt string) string {
+	params := []string{token, timestamp, nonce, encrypt}
+	sort.Strings(params)
+	str := strings.Join(params, "")
+	hash := sha1.Sum([]byte(str))
+	return fmt.Sprintf("%x", hash)
+}
+
+// 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
+	}
+	return computeSignature(token, timestamp, nonce, msgEncrypt) == 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
+	}
+
+	aesKey, err := decodeWeComAESKey(encodingAESKey)
+	if err != nil {
+		return "", err
+	}
+
+	cipherText, err := base64.StdEncoding.DecodeString(encryptedMsg)
+	if err != nil {
+		return "", fmt.Errorf("failed to decode message: %w", err)
+	}
+
+	plainText, err := decryptAESCBC(aesKey, cipherText)
+	if err != nil {
+		return "", err
+	}
+
+	return unpackWeComFrame(plainText, receiveid)
+}
+
+// decodeWeComAESKey base64-decodes the 43-character EncodingAESKey (trailing "=" is
+// appended automatically) and validates that the result is exactly 32 bytes.
+// It is the single place that handles this repeated pattern in both encrypt and decrypt paths.
+func decodeWeComAESKey(encodingAESKey string) ([]byte, error) {
+	aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=")
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode AES key: %w", err)
+	}
+	if len(aesKey) != 32 {
+		return nil, fmt.Errorf("invalid AES key length: %d", len(aesKey))
+	}
+	return aesKey, nil
+}
+
+// encryptAESCBC encrypts plaintext using AES-CBC with the given key, mirroring
+// decryptAESCBC. IV = aesKey[:aes.BlockSize]. The caller must PKCS7-pad the
+// plaintext to a multiple of aes.BlockSize before calling.
+func encryptAESCBC(aesKey, plaintext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(aesKey)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create cipher: %w", err)
+	}
+	iv := aesKey[:aes.BlockSize]
+	ciphertext := make([]byte, len(plaintext))
+	cipher.NewCBCEncrypter(block, iv).CryptBlocks(ciphertext, plaintext)
+	return ciphertext, nil
+}
+
+// packWeComFrame builds the WeCom wire format:
+//
+//	random(16 ASCII digits) + msg_len(4, big-endian) + msg + receiveid
+func packWeComFrame(msg, receiveid string) ([]byte, error) {
+	randomBytes := make([]byte, 16)
+	for i := range 16 {
+		n, err := rand.Int(rand.Reader, big.NewInt(10))
+		if err != nil {
+			return nil, fmt.Errorf("failed to generate random: %w", err)
+		}
+		randomBytes[i] = byte('0' + n.Int64())
+	}
+	msgBytes := []byte(msg)
+	msgLenBytes := make([]byte, 4)
+	binary.BigEndian.PutUint32(msgLenBytes, uint32(len(msgBytes)))
+	var buf bytes.Buffer
+	buf.Write(randomBytes)
+	buf.Write(msgLenBytes)
+	buf.Write(msgBytes)
+	buf.WriteString(receiveid)
+	return buf.Bytes(), nil
+}
+
+// unpackWeComFrame parses the WeCom wire format produced by packWeComFrame.
+// If receiveid is non-empty it verifies the frame's trailing receiveid field.
+func unpackWeComFrame(data []byte, receiveid string) (string, error) {
+	if len(data) < 20 {
+		return "", fmt.Errorf("decrypted frame too short: %d bytes", len(data))
+	}
+	msgLen := binary.BigEndian.Uint32(data[16:20])
+	if int(msgLen) > len(data)-20 {
+		return "", fmt.Errorf("invalid message length: %d", msgLen)
+	}
+	msg := data[20 : 20+msgLen]
+	if receiveid != "" && len(data) > 20+int(msgLen) {
+		actualReceiveID := string(data[20+msgLen:])
+		if actualReceiveID != receiveid {
+			return "", fmt.Errorf("receiveid mismatch: expected %s, got %s", receiveid, actualReceiveID)
+		}
+	}
+	return string(msg), nil
+}
+
+// decryptAESCBC decrypts ciphertext using AES-CBC with the given key.
+// IV = aesKey[:aes.BlockSize]. PKCS7 padding is stripped from the returned plaintext.
+func decryptAESCBC(aesKey, 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(aesKey)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create cipher: %w", err)
+	}
+	iv := aesKey[:aes.BlockSize]
+	plaintext := make([]byte, len(ciphertext))
+	cipher.NewCBCDecrypter(block, iv).CryptBlocks(plaintext, ciphertext)
+	plaintext, err = pkcs7Unpad(plaintext)
+	if err != nil {
+		return nil, fmt.Errorf("failed to unpad: %w", err)
+	}
+	return plaintext, nil
+}
+
+// pkcs7Pad adds PKCS7 padding
+func pkcs7Pad(data []byte, blockSize int) []byte {
+	padding := blockSize - (len(data) % blockSize)
+	if padding == 0 {
+		padding = blockSize
+	}
+	padText := bytes.Repeat([]byte{byte(padding)}, padding)
+	return append(data, padText...)
+}
+
+// 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/dedupe.go b/pkg/channels/wecom/dedupe.go
new file mode 100644
index 000000000..865be668e
--- /dev/null
+++ b/pkg/channels/wecom/dedupe.go
@@ -0,0 +1,54 @@
+package wecom
+
+import "sync"
+
+const wecomMaxProcessedMessages = 1000
+
+// MessageDeduplicator provides thread-safe message deduplication using a circular queue (ring buffer)
+// combined with a hash map. This ensures fast O(1) lookups while naturally evicting the oldest
+// messages without causing "amnesia cliffs" when the limit is reached.
+type MessageDeduplicator struct {
+	mu   sync.Mutex
+	msgs map[string]bool
+	ring []string
+	idx  int
+	max  int
+}
+
+// NewMessageDeduplicator creates a new deduplicator with the specified capacity.
+func NewMessageDeduplicator(maxEntries int) *MessageDeduplicator {
+	if maxEntries <= 0 {
+		maxEntries = wecomMaxProcessedMessages
+	}
+	return &MessageDeduplicator{
+		msgs: make(map[string]bool, maxEntries),
+		ring: make([]string, maxEntries),
+		max:  maxEntries,
+	}
+}
+
+// MarkMessageProcessed marks msgID as processed and returns false for duplicates.
+func (d *MessageDeduplicator) MarkMessageProcessed(msgID string) bool {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	// 1. Check for duplicate
+	if d.msgs[msgID] {
+		return false
+	}
+
+	// 2. Evict the oldest message at our current ring position (if any)
+	oldestID := d.ring[d.idx]
+	if oldestID != "" {
+		delete(d.msgs, oldestID)
+	}
+
+	// 3. Store the new message
+	d.msgs[msgID] = true
+	d.ring[d.idx] = msgID
+
+	// 4. Advance the circle queue index
+	d.idx = (d.idx + 1) % d.max
+
+	return true
+}
diff --git a/pkg/channels/wecom/dedupe_test.go b/pkg/channels/wecom/dedupe_test.go
new file mode 100644
index 000000000..10dff4cfe
--- /dev/null
+++ b/pkg/channels/wecom/dedupe_test.go
@@ -0,0 +1,83 @@
+package wecom
+
+import (
+	"sync"
+	"testing"
+)
+
+func TestMessageDeduplicator_DuplicateDetection(t *testing.T) {
+	d := NewMessageDeduplicator(wecomMaxProcessedMessages)
+
+	if ok := d.MarkMessageProcessed("msg-1"); !ok {
+		t.Fatalf("first message should be accepted")
+	}
+
+	if ok := d.MarkMessageProcessed("msg-1"); ok {
+		t.Fatalf("duplicate message should be rejected")
+	}
+}
+
+func TestMessageDeduplicator_ConcurrentSameMessage(t *testing.T) {
+	d := NewMessageDeduplicator(wecomMaxProcessedMessages)
+
+	const goroutines = 64
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+
+	results := make(chan bool, goroutines)
+	for i := 0; i < goroutines; i++ {
+		go func() {
+			defer wg.Done()
+			results <- d.MarkMessageProcessed("msg-concurrent")
+		}()
+	}
+
+	wg.Wait()
+	close(results)
+
+	successes := 0
+	for ok := range results {
+		if ok {
+			successes++
+		}
+	}
+
+	if successes != 1 {
+		t.Fatalf("expected exactly 1 successful mark, got %d", successes)
+	}
+}
+
+func TestMessageDeduplicator_CircularQueueEviction(t *testing.T) {
+	// Create a deduplicator with a very small capacity to test eviction easily.
+	capacity := 3
+	d := NewMessageDeduplicator(capacity)
+
+	// Fill the queue.
+	d.MarkMessageProcessed("msg-1")
+	d.MarkMessageProcessed("msg-2")
+	d.MarkMessageProcessed("msg-3")
+
+	// At this point, the queue is full. msg-1 is the oldest.
+	if len(d.msgs) != 3 {
+		t.Fatalf("expected map size to be 3, got %d", len(d.msgs))
+	}
+
+	// This should evict msg-1 and add msg-4.
+	if ok := d.MarkMessageProcessed("msg-4"); !ok {
+		t.Fatalf("msg-4 should be accepted")
+	}
+
+	if len(d.msgs) != 3 {
+		t.Fatalf("expected map size to remain at max capacity (3), got %d", len(d.msgs))
+	}
+
+	// msg-1 should now be forgotten (evicted).
+	if ok := d.MarkMessageProcessed("msg-1"); !ok {
+		t.Fatalf("msg-1 should be accepted again because it was evicted")
+	}
+
+	// msg-2 should have been evicted when we added msg-1 back.
+	if ok := d.MarkMessageProcessed("msg-2"); !ok {
+		t.Fatalf("msg-2 should be accepted again because it was evicted")
+	}
+}
diff --git a/pkg/channels/wecom/init.go b/pkg/channels/wecom/init.go
new file mode 100644
index 000000000..bc5a70fa3
--- /dev/null
+++ b/pkg/channels/wecom/init.go
@@ -0,0 +1,19 @@
+package wecom
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+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)
+	})
+	channels.RegisterFactory("wecom_aibot", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewWeComAIBotChannel(cfg.Channels.WeComAIBot, b)
+	})
+}
diff --git a/pkg/channels/whatsapp/init.go b/pkg/channels/whatsapp/init.go
new file mode 100644
index 000000000..d9c2669c3
--- /dev/null
+++ b/pkg/channels/whatsapp/init.go
@@ -0,0 +1,13 @@
+package whatsapp
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("whatsapp", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewWhatsAppChannel(cfg.Channels.WhatsApp, b)
+	})
+}
diff --git a/pkg/channels/whatsapp.go b/pkg/channels/whatsapp/whatsapp.go
similarity index 53%
rename from pkg/channels/whatsapp.go
rename to pkg/channels/whatsapp/whatsapp.go
index 958d850bb..70b3e02bf 100644
--- a/pkg/channels/whatsapp.go
+++ b/pkg/channels/whatsapp/whatsapp.go
@@ -1,31 +1,42 @@
-package channels
+package whatsapp
 
 import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"log"
 	"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"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 type WhatsAppChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	conn      *websocket.Conn
 	config    config.WhatsAppConfig
 	url       string
+	ctx       context.Context
+	cancel    context.CancelFunc
 	mu        sync.Mutex
 	connected bool
 }
 
 func NewWhatsAppChannel(cfg config.WhatsAppConfig, bus *bus.MessageBus) (*WhatsAppChannel, error) {
-	base := NewBaseChannel("whatsapp", cfg, bus, cfg.AllowFrom)
+	base := channels.NewBaseChannel(
+		"whatsapp",
+		cfg,
+		bus,
+		cfg.AllowFrom,
+		channels.WithMaxMessageLength(65536),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
 
 	return &WhatsAppChannel{
 		BaseChannel: base,
@@ -36,13 +47,21 @@ func NewWhatsAppChannel(cfg config.WhatsAppConfig, bus *bus.MessageBus) (*WhatsA
 }
 
 func (c *WhatsAppChannel) Start(ctx context.Context) error {
-	log.Printf("Starting WhatsApp channel connecting to %s...", c.url)
+	logger.InfoCF("whatsapp", "Starting WhatsApp channel", map[string]any{
+		"bridge_url": c.url,
+	})
+
+	c.ctx, c.cancel = context.WithCancel(ctx)
 
 	dialer := websocket.DefaultDialer
 	dialer.HandshakeTimeout = 10 * time.Second
 
-	conn, _, err := dialer.Dial(c.url, nil)
+	conn, resp, err := dialer.Dial(c.url, nil)
+	if resp != nil {
+		resp.Body.Close()
+	}
 	if err != nil {
+		c.cancel()
 		return fmt.Errorf("failed to connect to WhatsApp bridge: %w", err)
 	}
 
@@ -51,39 +70,57 @@ func (c *WhatsAppChannel) Start(ctx context.Context) error {
 	c.connected = true
 	c.mu.Unlock()
 
-	c.setRunning(true)
-	log.Println("WhatsApp channel connected")
+	c.SetRunning(true)
+	logger.InfoC("whatsapp", "WhatsApp channel connected")
 
-	go c.listen(ctx)
+	go c.listen()
 
 	return nil
 }
 
 func (c *WhatsAppChannel) Stop(ctx context.Context) error {
-	log.Println("Stopping WhatsApp channel...")
+	logger.InfoC("whatsapp", "Stopping WhatsApp channel...")
+
+	// Cancel context first to signal listen goroutine to exit
+	if c.cancel != nil {
+		c.cancel()
+	}
 
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
 	if c.conn != nil {
 		if err := c.conn.Close(); err != nil {
-			log.Printf("Error closing WhatsApp connection: %v", err)
+			logger.ErrorCF("whatsapp", "Error closing WhatsApp connection", map[string]any{
+				"error": err.Error(),
+			})
 		}
 		c.conn = nil
 	}
 
 	c.connected = false
-	c.setRunning(false)
+	c.SetRunning(false)
 
 	return nil
 }
 
 func (c *WhatsAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	// Check ctx before acquiring lock
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+	}
+
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
 	if c.conn == nil {
-		return fmt.Errorf("whatsapp connection not established")
+		return fmt.Errorf("whatsapp connection not established: %w", channels.ErrTemporary)
 	}
 
 	payload := map[string]any{
@@ -97,17 +134,20 @@ func (c *WhatsAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
 		return fmt.Errorf("failed to marshal message: %w", err)
 	}
 
+	_ = c.conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
 	if err := c.conn.WriteMessage(websocket.TextMessage, data); err != nil {
-		return fmt.Errorf("failed to send message: %w", err)
+		_ = c.conn.SetWriteDeadline(time.Time{})
+		return fmt.Errorf("whatsapp send: %w", channels.ErrTemporary)
 	}
+	_ = c.conn.SetWriteDeadline(time.Time{})
 
 	return nil
 }
 
-func (c *WhatsAppChannel) listen(ctx context.Context) {
+func (c *WhatsAppChannel) listen() {
 	for {
 		select {
-		case <-ctx.Done():
+		case <-c.ctx.Done():
 			return
 		default:
 			c.mu.Lock()
@@ -121,14 +161,18 @@ func (c *WhatsAppChannel) listen(ctx context.Context) {
 
 			_, message, err := conn.ReadMessage()
 			if err != nil {
-				log.Printf("WhatsApp read error: %v", err)
+				logger.ErrorCF("whatsapp", "WhatsApp read error", map[string]any{
+					"error": err.Error(),
+				})
 				time.Sleep(2 * time.Second)
 				continue
 			}
 
 			var msg map[string]any
 			if err := json.Unmarshal(message, &msg); err != nil {
-				log.Printf("Failed to unmarshal WhatsApp message: %v", err)
+				logger.ErrorCF("whatsapp", "Failed to unmarshal WhatsApp message", map[string]any{
+					"error": err.Error(),
+				})
 				continue
 			}
 
@@ -171,22 +215,38 @@ func (c *WhatsAppChannel) handleIncomingMessage(msg map[string]any) {
 	}
 
 	metadata := make(map[string]string)
-	if messageID, ok := msg["id"].(string); ok {
-		metadata["message_id"] = messageID
+	var messageID string
+	if mid, ok := msg["id"].(string); ok {
+		messageID = mid
 	}
 	if userName, ok := msg["from_name"].(string); ok {
 		metadata["user_name"] = userName
 	}
 
+	var peer bus.Peer
 	if chatID == senderID {
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}
 	} else {
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = chatID
+		peer = bus.Peer{Kind: "group", ID: chatID}
 	}
 
-	log.Printf("WhatsApp message from %s: %s...", senderID, utils.Truncate(content, 50))
+	logger.InfoCF("whatsapp", "WhatsApp message received", map[string]any{
+		"sender":  senderID,
+		"preview": utils.Truncate(content, 50),
+	})
 
-	c.HandleMessage(senderID, chatID, content, mediaPaths, metadata)
+	sender := bus.SenderInfo{
+		Platform:    "whatsapp",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("whatsapp", senderID),
+	}
+	if display, ok := metadata["user_name"]; ok {
+		sender.DisplayName = display
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, messageID, senderID, chatID, content, mediaPaths, metadata, sender)
 }
diff --git a/pkg/channels/whatsapp/whatsapp_command_test.go b/pkg/channels/whatsapp/whatsapp_command_test.go
new file mode 100644
index 000000000..ee8aa4a52
--- /dev/null
+++ b/pkg/channels/whatsapp/whatsapp_command_test.go
@@ -0,0 +1,41 @@
+package whatsapp
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"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",
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	inbound, ok := messageBus.ConsumeInbound(ctx)
+	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/init.go b/pkg/channels/whatsapp_native/init.go
new file mode 100644
index 000000000..df13e8539
--- /dev/null
+++ b/pkg/channels/whatsapp_native/init.go
@@ -0,0 +1,20 @@
+package whatsapp
+
+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("whatsapp_native", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		waCfg := cfg.Channels.WhatsApp
+		storePath := waCfg.SessionStorePath
+		if storePath == "" {
+			storePath = filepath.Join(cfg.WorkspacePath(), "whatsapp")
+		}
+		return NewWhatsAppNativeChannel(waCfg, b, storePath)
+	})
+}
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..cc2dcb619
--- /dev/null
+++ b/pkg/channels/whatsapp_native/whatsapp_command_test.go
@@ -0,0 +1,56 @@
+//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()
+
+	inbound, ok := messageBus.ConsumeInbound(ctx)
+	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/channels/whatsapp_native/whatsapp_native.go b/pkg/channels/whatsapp_native/whatsapp_native.go
new file mode 100644
index 000000000..188a7c8fa
--- /dev/null
+++ b/pkg/channels/whatsapp_native/whatsapp_native.go
@@ -0,0 +1,448 @@
+//go:build whatsapp_native
+
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package whatsapp
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/mdp/qrterminal/v3"
+	"go.mau.fi/whatsmeow"
+	"go.mau.fi/whatsmeow/proto/waE2E"
+	"go.mau.fi/whatsmeow/store/sqlstore"
+	"go.mau.fi/whatsmeow/types"
+	"go.mau.fi/whatsmeow/types/events"
+	waLog "go.mau.fi/whatsmeow/util/log"
+	"google.golang.org/protobuf/proto"
+	_ "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/utils"
+)
+
+const (
+	sqliteDriver   = "sqlite"
+	whatsappDBName = "store.db"
+
+	reconnectInitial    = 5 * time.Second
+	reconnectMax        = 5 * time.Minute
+	reconnectMultiplier = 2.0
+)
+
+// WhatsAppNativeChannel implements the WhatsApp channel using whatsmeow (in-process, no external bridge).
+type WhatsAppNativeChannel struct {
+	*channels.BaseChannel
+	config       config.WhatsAppConfig
+	storePath    string
+	client       *whatsmeow.Client
+	container    *sqlstore.Container
+	mu           sync.Mutex
+	runCtx       context.Context
+	runCancel    context.CancelFunc
+	reconnectMu  sync.Mutex
+	reconnecting bool
+	stopping     atomic.Bool    // set once Stop begins; prevents new wg.Add calls
+	wg           sync.WaitGroup // tracks background goroutines (QR handler, reconnect)
+}
+
+// NewWhatsAppNativeChannel creates a WhatsApp channel that uses whatsmeow for connection.
+// storePath is the directory for the SQLite session store (e.g. workspace/whatsapp).
+func NewWhatsAppNativeChannel(
+	cfg config.WhatsAppConfig,
+	bus *bus.MessageBus,
+	storePath string,
+) (channels.Channel, error) {
+	base := channels.NewBaseChannel("whatsapp_native", cfg, bus, cfg.AllowFrom, channels.WithMaxMessageLength(65536))
+	if storePath == "" {
+		storePath = "whatsapp"
+	}
+	c := &WhatsAppNativeChannel{
+		BaseChannel: base,
+		config:      cfg,
+		storePath:   storePath,
+	}
+	return c, nil
+}
+
+func (c *WhatsAppNativeChannel) Start(ctx context.Context) error {
+	logger.InfoCF("whatsapp", "Starting WhatsApp native channel (whatsmeow)", map[string]any{"store": c.storePath})
+
+	// Reset lifecycle state from any previous Stop() so a restarted channel
+	// behaves correctly.  Use reconnectMu to be consistent with eventHandler
+	// and Stop() which coordinate under the same lock.
+	c.reconnectMu.Lock()
+	c.stopping.Store(false)
+	c.reconnecting = false
+	c.reconnectMu.Unlock()
+
+	if err := os.MkdirAll(c.storePath, 0o700); err != nil {
+		return fmt.Errorf("create session store dir: %w", err)
+	}
+
+	dbPath := filepath.Join(c.storePath, whatsappDBName)
+	connStr := "file:" + dbPath + "?_foreign_keys=on"
+
+	db, err := sql.Open(sqliteDriver, connStr)
+	if err != nil {
+		return fmt.Errorf("open whatsapp store: %w", err)
+	}
+	db.SetMaxOpenConns(1)
+	db.SetMaxIdleConns(1)
+	if _, err = db.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
+		_ = db.Close()
+		return fmt.Errorf("enable foreign keys: %w", err)
+	}
+
+	waLogger := waLog.Stdout("WhatsApp", "WARN", true)
+	container := sqlstore.NewWithDB(db, sqliteDriver, waLogger)
+	if err = container.Upgrade(ctx); err != nil {
+		_ = db.Close()
+		return fmt.Errorf("open whatsapp store: %w", err)
+	}
+
+	deviceStore, err := container.GetFirstDevice(ctx)
+	if err != nil {
+		_ = container.Close()
+		return fmt.Errorf("get device store: %w", err)
+	}
+
+	client := whatsmeow.NewClient(deviceStore, waLogger)
+
+	// Create runCtx/runCancel BEFORE registering event handler and starting
+	// goroutines so that Stop() can cancel them at any time, including during
+	// the QR-login flow.
+	c.runCtx, c.runCancel = context.WithCancel(ctx)
+
+	client.AddEventHandler(c.eventHandler)
+
+	c.mu.Lock()
+	c.container = container
+	c.client = client
+	c.mu.Unlock()
+
+	// cleanupOnError clears struct references and releases resources when
+	// Start() fails after fields are already assigned.  This prevents
+	// Stop() from operating on stale references (double-close, disconnect
+	// of a partially-initialized client, or stray event handler callbacks).
+	startOK := false
+	defer func() {
+		if startOK {
+			return
+		}
+		c.runCancel()
+		client.Disconnect()
+		c.mu.Lock()
+		c.client = nil
+		c.container = nil
+		c.mu.Unlock()
+		_ = container.Close()
+	}()
+
+	if client.Store.ID == nil {
+		qrChan, err := client.GetQRChannel(c.runCtx)
+		if err != nil {
+			return fmt.Errorf("get QR channel: %w", err)
+		}
+		if err := client.Connect(); err != nil {
+			return fmt.Errorf("connect: %w", err)
+		}
+		// Handle QR events in a background goroutine so Start() returns
+		// promptly.  The goroutine is tracked via c.wg and respects
+		// c.runCtx for cancellation.
+		// Guard wg.Add with reconnectMu + stopping check (same protocol
+		// as eventHandler) so a concurrent Stop() cannot enter wg.Wait()
+		// while we call wg.Add(1).
+		c.reconnectMu.Lock()
+		if c.stopping.Load() {
+			c.reconnectMu.Unlock()
+			return fmt.Errorf("channel stopped during QR setup")
+		}
+		c.wg.Add(1)
+		c.reconnectMu.Unlock()
+		go func() {
+			defer c.wg.Done()
+			for {
+				select {
+				case <-c.runCtx.Done():
+					return
+				case evt, ok := <-qrChan:
+					if !ok {
+						return
+					}
+					if evt.Event == "code" {
+						logger.InfoCF("whatsapp", "Scan this QR code with WhatsApp (Linked Devices):", nil)
+						qrterminal.GenerateWithConfig(evt.Code, qrterminal.Config{
+							Level:      qrterminal.L,
+							Writer:     os.Stdout,
+							HalfBlocks: true,
+						})
+					} else {
+						logger.InfoCF("whatsapp", "WhatsApp login event", map[string]any{"event": evt.Event})
+					}
+				}
+			}
+		}()
+	} else {
+		if err := client.Connect(); err != nil {
+			return fmt.Errorf("connect: %w", err)
+		}
+	}
+
+	startOK = true
+	c.SetRunning(true)
+	logger.InfoC("whatsapp", "WhatsApp native channel connected")
+	return nil
+}
+
+func (c *WhatsAppNativeChannel) Stop(ctx context.Context) error {
+	logger.InfoC("whatsapp", "Stopping WhatsApp native channel")
+
+	// Mark as stopping under reconnectMu so the flag is visible to
+	// eventHandler atomically with respect to its wg.Add(1) call.
+	// This closes the TOCTOU window where eventHandler could check
+	// stopping (false), then Stop sets it true + enters wg.Wait,
+	// then eventHandler calls wg.Add(1) — causing a panic.
+	c.reconnectMu.Lock()
+	c.stopping.Store(true)
+	c.reconnectMu.Unlock()
+
+	if c.runCancel != nil {
+		c.runCancel()
+	}
+
+	// Disconnect the client first so any blocking Connect()/reconnect loops
+	// can be interrupted before we wait on the goroutines.
+	c.mu.Lock()
+	client := c.client
+	container := c.container
+	c.mu.Unlock()
+
+	if client != nil {
+		client.Disconnect()
+	}
+
+	// Wait for background goroutines (QR handler, reconnect) to finish in a
+	// context-aware way so Stop can be bounded by ctx.
+	done := make(chan struct{})
+	go func() {
+		c.wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// All goroutines have finished.
+	case <-ctx.Done():
+		// Context canceled or timed out; log and proceed with best-effort cleanup.
+		logger.WarnC("whatsapp", fmt.Sprintf("Stop context canceled before all goroutines finished: %v", ctx.Err()))
+	}
+
+	// Now it is safe to clear and close resources.
+	c.mu.Lock()
+	c.client = nil
+	c.container = nil
+	c.mu.Unlock()
+
+	if container != nil {
+		_ = container.Close()
+	}
+	c.SetRunning(false)
+	return nil
+}
+
+func (c *WhatsAppNativeChannel) eventHandler(evt any) {
+	switch evt.(type) {
+	case *events.Message:
+		c.handleIncoming(evt.(*events.Message))
+	case *events.Disconnected:
+		logger.InfoCF("whatsapp", "WhatsApp disconnected, will attempt reconnection", nil)
+		c.reconnectMu.Lock()
+		if c.reconnecting {
+			c.reconnectMu.Unlock()
+			return
+		}
+		// Check stopping while holding the lock so the check and wg.Add
+		// are atomic with respect to Stop() setting the flag + calling
+		// wg.Wait(). This prevents the TOCTOU race.
+		if c.stopping.Load() {
+			c.reconnectMu.Unlock()
+			return
+		}
+		c.reconnecting = true
+		c.wg.Add(1)
+		c.reconnectMu.Unlock()
+		go func() {
+			defer c.wg.Done()
+			c.reconnectWithBackoff()
+		}()
+	}
+}
+
+func (c *WhatsAppNativeChannel) reconnectWithBackoff() {
+	defer func() {
+		c.reconnectMu.Lock()
+		c.reconnecting = false
+		c.reconnectMu.Unlock()
+	}()
+
+	backoff := reconnectInitial
+	for {
+		select {
+		case <-c.runCtx.Done():
+			return
+		default:
+		}
+
+		c.mu.Lock()
+		client := c.client
+		c.mu.Unlock()
+		if client == nil {
+			return
+		}
+
+		logger.InfoCF("whatsapp", "WhatsApp reconnecting", map[string]any{"backoff": backoff.String()})
+		err := client.Connect()
+		if err == nil {
+			logger.InfoC("whatsapp", "WhatsApp reconnected")
+			return
+		}
+
+		logger.WarnCF("whatsapp", "WhatsApp reconnect failed", map[string]any{"error": err.Error()})
+
+		select {
+		case <-c.runCtx.Done():
+			return
+		case <-time.After(backoff):
+			if backoff < reconnectMax {
+				next := time.Duration(float64(backoff) * reconnectMultiplier)
+				if next > reconnectMax {
+					next = reconnectMax
+				}
+				backoff = next
+			}
+		}
+	}
+}
+
+func (c *WhatsAppNativeChannel) handleIncoming(evt *events.Message) {
+	if evt.Message == nil {
+		return
+	}
+	senderID := evt.Info.Sender.String()
+	chatID := evt.Info.Chat.String()
+	content := evt.Message.GetConversation()
+	if content == "" && evt.Message.ExtendedTextMessage != nil {
+		content = evt.Message.ExtendedTextMessage.GetText()
+	}
+	content = utils.SanitizeMessageContent(content)
+
+	if content == "" {
+		return
+	}
+
+	var mediaPaths []string
+
+	metadata := make(map[string]string)
+	metadata["message_id"] = evt.Info.ID
+	if evt.Info.PushName != "" {
+		metadata["user_name"] = evt.Info.PushName
+	}
+	if evt.Info.Chat.Server == types.GroupServer {
+		metadata["peer_kind"] = "group"
+		metadata["peer_id"] = chatID
+	} else {
+		metadata["peer_kind"] = "direct"
+		metadata["peer_id"] = senderID
+	}
+
+	peerKind := "direct"
+	if evt.Info.Chat.Server == types.GroupServer {
+		peerKind = "group"
+	}
+	peer := bus.Peer{Kind: peerKind, ID: chatID}
+	messageID := evt.Info.ID
+	sender := bus.SenderInfo{
+		Platform:    "whatsapp",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("whatsapp", senderID),
+		DisplayName: evt.Info.PushName,
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	logger.DebugCF(
+		"whatsapp",
+		"WhatsApp message received",
+		map[string]any{"sender_id": senderID, "content_preview": utils.Truncate(content, 50)},
+	)
+	c.HandleMessage(c.runCtx, peer, messageID, senderID, chatID, content, mediaPaths, metadata, sender)
+}
+
+func (c *WhatsAppNativeChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+	}
+
+	c.mu.Lock()
+	client := c.client
+	c.mu.Unlock()
+
+	if client == nil || !client.IsConnected() {
+		return fmt.Errorf("whatsapp connection not established: %w", channels.ErrTemporary)
+	}
+
+	// Detect unpaired state: the client is connected (to WhatsApp servers)
+	// but has not completed QR-login yet, so sending would fail.
+	if client.Store.ID == nil {
+		return fmt.Errorf("whatsapp not yet paired (QR login pending): %w", channels.ErrTemporary)
+	}
+
+	to, err := parseJID(msg.ChatID)
+	if err != nil {
+		return fmt.Errorf("invalid chat id %q: %w", msg.ChatID, err)
+	}
+
+	waMsg := &waE2E.Message{
+		Conversation: proto.String(msg.Content),
+	}
+
+	if _, err = client.SendMessage(ctx, to, waMsg); err != nil {
+		return fmt.Errorf("whatsapp send: %w", channels.ErrTemporary)
+	}
+	return nil
+}
+
+// parseJID converts a chat ID (phone number or JID string) to types.JID.
+func parseJID(s string) (types.JID, error) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return types.JID{}, fmt.Errorf("empty chat id")
+	}
+	if strings.Contains(s, "@") {
+		return types.ParseJID(s)
+	}
+	return types.NewJID(s, types.DefaultUserServer), nil
+}
diff --git a/pkg/channels/whatsapp_native/whatsapp_native_stub.go b/pkg/channels/whatsapp_native/whatsapp_native_stub.go
new file mode 100644
index 000000000..984af23e7
--- /dev/null
+++ b/pkg/channels/whatsapp_native/whatsapp_native_stub.go
@@ -0,0 +1,21 @@
+//go:build !whatsapp_native
+
+package whatsapp
+
+import (
+	"fmt"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// NewWhatsAppNativeChannel returns an error when the binary was not built with -tags whatsapp_native.
+// Build with: go build -tags whatsapp_native ./cmd/...
+func NewWhatsAppNativeChannel(
+	cfg config.WhatsAppConfig,
+	bus *bus.MessageBus,
+	storePath string,
+) (channels.Channel, error) {
+	return nil, fmt.Errorf("whatsapp native not compiled in; build with -tags whatsapp_native")
+}
diff --git a/pkg/commands/builtin.go b/pkg/commands/builtin.go
new file mode 100644
index 000000000..aed6a1874
--- /dev/null
+++ b/pkg/commands/builtin.go
@@ -0,0 +1,17 @@
+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(),
+		switchCommand(),
+		checkCommand(),
+		clearCommand(),
+	}
+}
diff --git a/pkg/commands/builtin_test.go b/pkg/commands/builtin_test.go
new file mode 100644
index 000000000..66a84825e
--- /dev/null
+++ b/pkg/commands/builtin_test.go
@@ -0,0 +1,145 @@
+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]") {
+		t.Fatalf("/help reply missing /list 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)
+	}
+}
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..bf47b6e9c
--- /dev/null
+++ b/pkg/commands/cmd_list.go
@@ -0,0 +1,52 @@
+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(),
+			},
+		},
+	}
+}
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_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/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..62ee600f2
--- /dev/null
+++ b/pkg/commands/request.go
@@ -0,0 +1,75 @@
+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
+}
+
+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..037184686
--- /dev/null
+++ b/pkg/commands/runtime.go
@@ -0,0 +1,17 @@
+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
+	GetEnabledChannels func() []string
+	SwitchModel        func(value string) (oldModel string, err error)
+	SwitchChannel      func(value string) error
+	ClearHistory       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..047708f0f
--- /dev/null
+++ b/pkg/commands/show_list_handlers_test.go
@@ -0,0 +1,85 @@
+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"}
+		},
+	}
+	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)
+	}
+}
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 2595398c7..a47ab3091 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -4,10 +4,11 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
-	"path/filepath"
 	"sync/atomic"
 
 	"github.com/caarlos0/env/v11"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
 // rrCounter is a global counter for round-robin load balancing across models.
@@ -166,134 +167,286 @@ 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
+}
+
 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"`
-	Provider            string   `json:"provider"                        env:"PICOCLAW_AGENTS_DEFAULTS_PROVIDER"`
-	Model               string   `json:"model"                           env:"PICOCLAW_AGENTS_DEFAULTS_MODEL"`
-	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,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"`
+}
+
+const DefaultMaxMediaSize = 20 * 1024 * 1024 // 20 MB
+
+func (d *AgentDefaults) GetMaxMediaSize() int {
+	if d.MaxMediaSize > 0 {
+		return d.MaxMediaSize
+	}
+	return DefaultMaxMediaSize
+}
+
+// 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
 }
 
 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"`
+	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"`
+	WeComApp   WeComAppConfig   `json:"wecom_app"`
+	WeComAIBot WeComAIBotConfig `json:"wecom_aibot"`
+	Pico       PicoConfig       `json:"pico"`
+	IRC        IRCConfig        `json:"irc"`
+}
+
+// GroupTriggerConfig controls when the bot responds in group chats.
+type GroupTriggerConfig struct {
+	MentionOnly bool     `json:"mention_only,omitempty"`
+	Prefixes    []string `json:"prefixes,omitempty"`
+}
+
+// TypingConfig controls typing indicator behavior (Phase 10).
+type TypingConfig struct {
+	Enabled bool `json:"enabled,omitempty"`
+}
+
+// PlaceholderConfig controls placeholder message behavior (Phase 10).
+type PlaceholderConfig struct {
+	Enabled bool   `json:"enabled,omitempty"`
+	Text    string `json:"text,omitempty"`
 }
 
 type WhatsAppConfig struct {
-	Enabled   bool                `json:"enabled"    env:"PICOCLAW_CHANNELS_WHATSAPP_ENABLED"`
-	BridgeURL string              `json:"bridge_url" env:"PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL"`
-	AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WHATSAPP_ALLOW_FROM"`
+	Enabled            bool                `json:"enabled"              env:"PICOCLAW_CHANNELS_WHATSAPP_ENABLED"`
+	BridgeURL          string              `json:"bridge_url"           env:"PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL"`
+	UseNative          bool                `json:"use_native"           env:"PICOCLAW_CHANNELS_WHATSAPP_USE_NATIVE"`
+	SessionStorePath   string              `json:"session_store_path"   env:"PICOCLAW_CHANNELS_WHATSAPP_SESSION_STORE_PATH"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"           env:"PICOCLAW_CHANNELS_WHATSAPP_ALLOW_FROM"`
+	ReasoningChannelID string              `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WHATSAPP_REASONING_CHANNEL_ID"`
 }
 
 type TelegramConfig struct {
-	Enabled   bool                `json:"enabled"    env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
-	Token     string              `json:"token"      env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
-	Proxy     string              `json:"proxy"      env:"PICOCLAW_CHANNELS_TELEGRAM_PROXY"`
-	AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_TELEGRAM_ALLOW_FROM"`
+	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"`
 }
 
 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"`
+	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"`
 }
 
 type DiscordConfig struct {
-	Enabled     bool                `json:"enabled"      env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
-	Token       string              `json:"token"        env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
-	AllowFrom   FlexibleStringSlice `json:"allow_from"   env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
-	MentionOnly bool                `json:"mention_only" env:"PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY"`
+	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"`
 }
 
 type MaixCamConfig 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"`
+	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"`
 }
 
 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"`
+	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"`
 }
 
 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"`
-	AllowFrom    FlexibleStringSlice `json:"allow_from"    env:"PICOCLAW_CHANNELS_DINGTALK_ALLOW_FROM"`
+	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"`
 }
 
 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"`
-	AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_SLACK_ALLOW_FROM"`
+	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"`
+}
+
+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              `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"`
+	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"`
 }
 
 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"`
-	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"`
+	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"`
 }
 
 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"`
-	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"`
+	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"`
 }
 
 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"`
+	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"`
 }
 
 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"`
+	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"`
+}
+
+type WeComAIBotConfig struct {
+	Enabled            bool                `json:"enabled"              env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENABLED"`
+	Token              string              `json:"token"                env:"PICOCLAW_CHANNELS_WECOM_AIBOT_TOKEN"`
+	EncodingAESKey     string              `json:"encoding_aes_key"     env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENCODING_AES_KEY"`
+	WebhookPath        string              `json:"webhook_path"         env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WEBHOOK_PATH"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"           env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ALLOW_FROM"`
+	ReplyTimeout       int                 `json:"reply_timeout"        env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REPLY_TIMEOUT"`
+	MaxSteps           int                 `json:"max_steps"            env:"PICOCLAW_CHANNELS_WECOM_AIBOT_MAX_STEPS"`       // Maximum streaming steps
+	WelcomeMessage     string              `json:"welcome_message"      env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WELCOME_MESSAGE"` // Sent on enter_chat event; empty = no welcome
+	ReasoningChannelID string              `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"`
+}
+
+type PicoConfig 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"`
+}
+
+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              `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"`
 }
 
 type HeartbeatConfig struct {
@@ -309,6 +462,7 @@ type DevicesConfig struct {
 type ProvidersConfig struct {
 	Anthropic     ProviderConfig       `json:"anthropic"`
 	OpenAI        OpenAIProviderConfig `json:"openai"`
+	LiteLLM       ProviderConfig       `json:"litellm"`
 	OpenRouter    ProviderConfig       `json:"openrouter"`
 	Groq          ProviderConfig       `json:"groq"`
 	Zhipu         ProviderConfig       `json:"zhipu"`
@@ -320,11 +474,14 @@ type ProvidersConfig struct {
 	ShengSuanYun  ProviderConfig       `json:"shengsuanyun"`
 	DeepSeek      ProviderConfig       `json:"deepseek"`
 	Cerebras      ProviderConfig       `json:"cerebras"`
+	Vivgrid       ProviderConfig       `json:"vivgrid"`
 	VolcEngine    ProviderConfig       `json:"volcengine"`
 	GitHubCopilot ProviderConfig       `json:"github_copilot"`
 	Antigravity   ProviderConfig       `json:"antigravity"`
 	Qwen          ProviderConfig       `json:"qwen"`
 	Mistral       ProviderConfig       `json:"mistral"`
+	Avian         ProviderConfig       `json:"avian"`
+	Minimax       ProviderConfig       `json:"minimax"`
 }
 
 // IsEmpty checks if all provider configs are empty (no API keys or API bases set)
@@ -332,6 +489,7 @@ type ProvidersConfig struct {
 func (p ProvidersConfig) 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 == "" &&
@@ -343,11 +501,14 @@ func (p ProvidersConfig) IsEmpty() bool {
 		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.Mistral.APIKey == "" && p.Mistral.APIBase == "" &&
+		p.Avian.APIKey == "" && p.Avian.APIBase == "" &&
+		p.Minimax.APIKey == "" && p.Minimax.APIBase == ""
 }
 
 // MarshalJSON implements custom JSON marshaling for ProvidersConfig
@@ -361,11 +522,12 @@ func (p ProvidersConfig) MarshalJSON() ([]byte, error) {
 }
 
 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"`
-	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`
+	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 {
@@ -396,6 +558,8 @@ type ModelConfig struct {
 	// 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
 }
 
 // Validate checks if the ModelConfig has all required fields.
@@ -414,6 +578,18 @@ type GatewayConfig struct {
 	Port int    `json:"port" env:"PICOCLAW_GATEWAY_PORT"`
 }
 
+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"`
@@ -438,33 +614,90 @@ type PerplexityConfig struct {
 	MaxResults int    `json:"max_results" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_MAX_RESULTS"`
 }
 
+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 `json:"api_key"  env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"`
+	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"`
+}
+
 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"`
+	// 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"`
 }
 
 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
 }
 
 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"`
-}
-
-type ToolsConfig struct {
-	Web    WebToolsConfig    `json:"web"`
-	Cron   CronToolsConfig   `json:"cron"`
-	Exec   ExecConfig        `json:"exec"`
-	Skills SkillsToolsConfig `json:"skills"`
+	ToolConfig          `         envPrefix:"PICOCLAW_TOOLS_EXEC_"`
+	EnableDenyPatterns  bool     `                                 env:"PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS"  json:"enable_deny_patterns"`
+	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 {
-	Registries            SkillsRegistriesConfig `json:"registries"`
-	MaxConcurrentSearches int                    `json:"max_concurrent_searches" env:"PICOCLAW_SKILLS_MAX_CONCURRENT_SEARCHES"`
-	SearchCache           SearchCacheConfig      `json:"search_cache"`
+	ToolConfig            `                       envPrefix:"PICOCLAW_TOOLS_SKILLS_"`
+	Registries            SkillsRegistriesConfig `                                   json:"registries"`
+	MaxConcurrentSearches int                    `                                   json:"max_concurrent_searches" env:"PICOCLAW_TOOLS_SKILLS_MAX_CONCURRENT_SEARCHES"`
+	SearchCache           SearchCacheConfig      `                                   json:"search_cache"`
+}
+
+type MediaCleanupConfig struct {
+	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"`
+	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_"`
+	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 SearchCacheConfig struct {
@@ -488,6 +721,34 @@ type ClawHubRegistryConfig struct {
 	MaxResponseSize int    `json:"max_response_size" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_MAX_RESPONSE_SIZE"`
 }
 
+// MCPServerConfig defines configuration for a single MCP server
+type MCPServerConfig struct {
+	// Enabled indicates whether this MCP server is active
+	Enabled bool `json:"enabled"`
+	// 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) {
 	cfg := DefaultConfig()
 
@@ -499,6 +760,20 @@ func LoadConfig(path string) (*Config, error) {
 		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
+	}
+	if len(tmp.ModelList) > 0 {
+		cfg.ModelList = nil
+	}
+
 	if err := json.Unmarshal(data, cfg); err != nil {
 		return nil, err
 	}
@@ -507,6 +782,9 @@ func LoadConfig(path string) (*Config, error) {
 		return nil, err
 	}
 
+	// 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)
@@ -520,18 +798,27 @@ func LoadConfig(path string) (*Config, error) {
 	return cfg, nil
 }
 
+func (c *Config) 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 SaveConfig(path string, cfg *Config) error {
 	data, err := json.MarshalIndent(cfg, "", "  ")
 	if err != nil {
 		return err
 	}
 
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return err
-	}
-
-	return os.WriteFile(path, data, 0o600)
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	return fileutil.WriteFileAtomic(path, data, 0o600)
 }
 
 func (c *Config) WorkspacePath() string {
@@ -629,25 +916,7 @@ func (c *Config) findMatches(modelName string) []ModelConfig {
 
 // 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 != ""
+	return !c.Providers.IsEmpty()
 }
 
 // ValidateModelList validates all ModelConfig entries in the model_list.
@@ -661,3 +930,50 @@ func (c *Config) ValidateModelList() error {
 	}
 	return nil
 }
+
+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 "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_test.go b/pkg/config/config_test.go
index f88c0269c..47f79c6f0 100644
--- a/pkg/config/config_test.go
+++ b/pkg/config/config_test.go
@@ -5,6 +5,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"strings"
 	"testing"
 )
 
@@ -210,8 +211,8 @@ func TestDefaultConfig_WorkspacePath(t *testing.T) {
 func TestDefaultConfig_Model(t *testing.T) {
 	cfg := DefaultConfig()
 
-	if cfg.Agents.Defaults.Model == "" {
-		t.Error("Model should not be empty")
+	if cfg.Agents.Defaults.Model != "" {
+		t.Error("Model should be empty")
 	}
 }
 
@@ -282,6 +283,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
@@ -324,6 +328,25 @@ func TestSaveConfig_FilePermissions(t *testing.T) {
 	}
 }
 
+func TestSaveConfig_IncludesEmptyLegacyModelField(t *testing.T) {
+	tmpDir := t.TempDir()
+	path := filepath.Join(tmpDir, "config.json")
+
+	cfg := DefaultConfig()
+	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), `"model": ""`) {
+		t.Fatalf("saved config should include empty legacy model field, got: %s", string(data))
+	}
+}
+
 // TestConfig_Complete verifies all config fields are set
 func TestConfig_Complete(t *testing.T) {
 	cfg := DefaultConfig()
@@ -331,8 +354,8 @@ 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 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")
@@ -392,3 +415,70 @@ func TestLoadConfig_OpenAIWebSearchCanBeDisabled(t *testing.T) {
 		t.Fatal("OpenAI codex web search should be false when disabled in config file")
 	}
 }
+
+func TestLoadConfig_WebToolsProxy(t *testing.T) {
+	tmpDir := t.TempDir()
+	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"}],
+  "tools": {"web":{"proxy":"http://127.0.0.1:7890"}}
+}`
+	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)
+	}
+	if cfg.Tools.Web.Proxy != "http://127.0.0.1:7890" {
+		t.Fatalf("Tools.Web.Proxy = %q, want %q", cfg.Tools.Web.Proxy, "http://127.0.0.1:7890")
+	}
+}
+
+// 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()
+
+	if cfg.Session.DMScope != "per-channel-peer" {
+		t.Errorf("Session.DMScope = %q, want 'per-channel-peer'", cfg.Session.DMScope)
+	}
+}
+
+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")
+
+	cfg := DefaultConfig()
+	want := filepath.Join("/tmp/home", ".picoclaw", "workspace")
+
+	if cfg.Agents.Defaults.Workspace != want {
+		t.Errorf("Default workspace path = %q, want %q", cfg.Agents.Defaults.Workspace, want)
+	}
+}
+
+func TestDefaultConfig_WorkspacePath_WithPicoclawHome(t *testing.T) {
+	t.Setenv("PICOCLAW_HOME", "/custom/picoclaw/home")
+
+	cfg := DefaultConfig()
+	want := "/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)
+	}
+}
diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go
index b96ee4d89..e64baa720 100644
--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@@ -5,34 +5,59 @@
 
 package config
 
+import (
+	"os"
+	"path/filepath"
+)
+
 // DefaultConfig returns the default configuration for PicoClaw.
 func DefaultConfig() *Config {
+	// Determine the base path for the workspace.
+	// Priority: $PICOCLAW_HOME > ~/.picoclaw
+	var homePath string
+	if picoclawHome := os.Getenv("PICOCLAW_HOME"); picoclawHome != "" {
+		homePath = picoclawHome
+	} else {
+		userHome, _ := os.UserHomeDir()
+		homePath = filepath.Join(userHome, ".picoclaw")
+	}
+	workspacePath := filepath.Join(homePath, "workspace")
+
 	return &Config{
 		Agents: AgentsConfig{
 			Defaults: AgentDefaults{
-				Workspace:           "~/.picoclaw/workspace",
-				RestrictToWorkspace: true,
-				Provider:            "",
-				Model:               "glm-4.7",
-				MaxTokens:           8192,
-				Temperature:         nil, // nil means use provider default
-				MaxToolIterations:   20,
+				Workspace:                 workspacePath,
+				RestrictToWorkspace:       true,
+				Provider:                  "",
+				Model:                     "",
+				MaxTokens:                 32768,
+				Temperature:               nil, // nil means use provider default
+				MaxToolIterations:         50,
+				SummarizeMessageThreshold: 20,
+				SummarizeTokenPercent:     75,
 			},
 		},
 		Bindings: []AgentBinding{},
 		Session: SessionConfig{
-			DMScope: "main",
+			DMScope: "per-channel-peer",
 		},
 		Channels: ChannelsConfig{
 			WhatsApp: WhatsAppConfig{
-				Enabled:   false,
-				BridgeURL: "ws://localhost:3001",
-				AllowFrom: FlexibleStringSlice{},
+				Enabled:          false,
+				BridgeURL:        "ws://localhost:3001",
+				UseNative:        false,
+				SessionStorePath: "",
+				AllowFrom:        FlexibleStringSlice{},
 			},
 			Telegram: TelegramConfig{
 				Enabled:   false,
 				Token:     "",
 				AllowFrom: FlexibleStringSlice{},
+				Typing:    TypingConfig{Enabled: true},
+				Placeholder: PlaceholderConfig{
+					Enabled: true,
+					Text:    "Thinking... 💭",
+				},
 			},
 			Feishu: FeishuConfig{
 				Enabled:           false,
@@ -72,6 +97,22 @@ func DefaultConfig() *Config {
 				AppToken:  "",
 				AllowFrom: FlexibleStringSlice{},
 			},
+			Matrix: MatrixConfig{
+				Enabled:      false,
+				Homeserver:   "https://matrix.org",
+				UserID:       "",
+				AccessToken:  "",
+				DeviceID:     "",
+				JoinOnInvite: true,
+				AllowFrom:    FlexibleStringSlice{},
+				GroupTrigger: GroupTriggerConfig{
+					MentionOnly: true,
+				},
+				Placeholder: PlaceholderConfig{
+					Enabled: true,
+					Text:    "Thinking... 💭",
+				},
+			},
 			LINE: LINEConfig{
 				Enabled:            false,
 				ChannelSecret:      "",
@@ -80,6 +121,7 @@ func DefaultConfig() *Config {
 				WebhookPort:        18791,
 				WebhookPath:        "/webhook/line",
 				AllowFrom:          FlexibleStringSlice{},
+				GroupTrigger:       GroupTriggerConfig{MentionOnly: true},
 			},
 			OneBot: OneBotConfig{
 				Enabled:            false,
@@ -113,6 +155,25 @@ func DefaultConfig() *Config {
 				AllowFrom:      FlexibleStringSlice{},
 				ReplyTimeout:   5,
 			},
+			WeComAIBot: WeComAIBotConfig{
+				Enabled:        false,
+				Token:          "",
+				EncodingAESKey: "",
+				WebhookPath:    "/webhook/wecom-aibot",
+				AllowFrom:      FlexibleStringSlice{},
+				ReplyTimeout:   5,
+				MaxSteps:       10,
+				WelcomeMessage: "Hello! I'm your AI assistant. How can I help you today?",
+			},
+			Pico: PicoConfig{
+				Enabled:        false,
+				Token:          "",
+				PingInterval:   30,
+				ReadTimeout:    60,
+				WriteTimeout:   10,
+				MaxConnections: 100,
+				AllowFrom:      FlexibleStringSlice{},
+			},
 		},
 		Providers: ProvidersConfig{
 			OpenAI: OpenAIProviderConfig{WebSearch: true},
@@ -216,6 +277,14 @@ func DefaultConfig() *Config {
 				APIKey:    "",
 			},
 
+			// Vivgrid - https://vivgrid.com
+			{
+				ModelName: "vivgrid-auto",
+				Model:     "vivgrid/auto",
+				APIBase:   "https://api.vivgrid.com/v1",
+				APIKey:    "",
+			},
+
 			// Volcengine (火山引擎) - https://console.volcengine.com/ark
 			{
 				ModelName: "doubao-pro",
@@ -263,6 +332,28 @@ func DefaultConfig() *Config {
 				APIKey:    "",
 			},
 
+			// Avian - https://avian.io
+			{
+				ModelName: "deepseek-v3.2",
+				Model:     "avian/deepseek/deepseek-v3.2",
+				APIBase:   "https://api.avian.io/v1",
+				APIKey:    "",
+			},
+			{
+				ModelName: "kimi-k2.5",
+				Model:     "avian/moonshotai/kimi-k2.5",
+				APIBase:   "https://api.avian.io/v1",
+				APIKey:    "",
+			},
+
+			// Minimax - https://api.minimaxi.com/
+			{
+				ModelName: "MiniMax-M2.5",
+				Model:     "minimax/MiniMax-M2.5",
+				APIBase:   "https://api.minimaxi.com/v1",
+				APIKey:    "",
+			},
+
 			// VLLM (local) - http://localhost:8000
 			{
 				ModelName: "local-model",
@@ -276,7 +367,19 @@ func DefaultConfig() *Config {
 			Port: 18790,
 		},
 		Tools: ToolsConfig{
+			MediaCleanup: MediaCleanupConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
+				MaxAge:   30,
+				Interval: 5,
+			},
 			Web: WebToolsConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
+				Proxy:           "",
+				FetchLimitBytes: 10 * 1024 * 1024, // 10MB by default
 				Brave: BraveConfig{
 					Enabled:    false,
 					APIKey:     "",
@@ -291,14 +394,36 @@ func DefaultConfig() *Config {
 					APIKey:     "",
 					MaxResults: 5,
 				},
+				SearXNG: SearXNGConfig{
+					Enabled:    false,
+					BaseURL:    "",
+					MaxResults: 5,
+				},
+				GLMSearch: GLMSearchConfig{
+					Enabled:      false,
+					APIKey:       "",
+					BaseURL:      "https://open.bigmodel.cn/api/paas/v4/web_search",
+					SearchEngine: "search_std",
+					MaxResults:   5,
+				},
 			},
 			Cron: CronToolsConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
 				ExecTimeoutMinutes: 5,
 			},
 			Exec: ExecConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
 				EnableDenyPatterns: true,
+				TimeoutSeconds:     60,
 			},
 			Skills: SkillsToolsConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
 				Registries: SkillsRegistriesConfig{
 					ClawHub: ClawHubRegistryConfig{
 						Enabled: true,
@@ -311,6 +436,62 @@ 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,
+			},
+			SPI: ToolConfig{
+				Enabled: false, // Hardware tool - Linux only
+			},
+			Subagent: ToolConfig{
+				Enabled: true,
+			},
+			WebFetch: ToolConfig{
+				Enabled: true,
+			},
+			WriteFile: ToolConfig{
+				Enabled: true,
+			},
 		},
 		Heartbeat: HeartbeatConfig{
 			Enabled:  true,
diff --git a/pkg/config/migration.go b/pkg/config/migration.go
index 30eaa7474..51f21e4f4 100644
--- a/pkg/config/migration.go
+++ b/pkg/config/migration.go
@@ -41,7 +41,7 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 
 	// Get user's configured provider and model
 	userProvider := strings.ToLower(cfg.Agents.Defaults.Provider)
-	userModel := cfg.Agents.Defaults.Model
+	userModel := cfg.Agents.Defaults.GetModelName()
 
 	p := cfg.Providers
 
@@ -60,12 +60,13 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName:  "openai",
-					Model:      "openai/gpt-5.2",
-					APIKey:     p.OpenAI.APIKey,
-					APIBase:    p.OpenAI.APIBase,
-					Proxy:      p.OpenAI.Proxy,
-					AuthMethod: p.OpenAI.AuthMethod,
+					ModelName:      "openai",
+					Model:          "openai/gpt-5.2",
+					APIKey:         p.OpenAI.APIKey,
+					APIBase:        p.OpenAI.APIBase,
+					Proxy:          p.OpenAI.Proxy,
+					RequestTimeout: p.OpenAI.RequestTimeout,
+					AuthMethod:     p.OpenAI.AuthMethod,
 				}, true
 			},
 		},
@@ -77,12 +78,30 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName:  "anthropic",
-					Model:      "anthropic/claude-sonnet-4.6",
-					APIKey:     p.Anthropic.APIKey,
-					APIBase:    p.Anthropic.APIBase,
-					Proxy:      p.Anthropic.Proxy,
-					AuthMethod: p.Anthropic.AuthMethod,
+					ModelName:      "anthropic",
+					Model:          "anthropic/claude-sonnet-4.6",
+					APIKey:         p.Anthropic.APIKey,
+					APIBase:        p.Anthropic.APIBase,
+					Proxy:          p.Anthropic.Proxy,
+					RequestTimeout: p.Anthropic.RequestTimeout,
+					AuthMethod:     p.Anthropic.AuthMethod,
+				}, true
+			},
+		},
+		{
+			providerNames: []string{"litellm"},
+			protocol:      "litellm",
+			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+				if p.LiteLLM.APIKey == "" && p.LiteLLM.APIBase == "" {
+					return ModelConfig{}, false
+				}
+				return ModelConfig{
+					ModelName:      "litellm",
+					Model:          "litellm/auto",
+					APIKey:         p.LiteLLM.APIKey,
+					APIBase:        p.LiteLLM.APIBase,
+					Proxy:          p.LiteLLM.Proxy,
+					RequestTimeout: p.LiteLLM.RequestTimeout,
 				}, true
 			},
 		},
@@ -94,11 +113,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "openrouter",
-					Model:     "openrouter/auto",
-					APIKey:    p.OpenRouter.APIKey,
-					APIBase:   p.OpenRouter.APIBase,
-					Proxy:     p.OpenRouter.Proxy,
+					ModelName:      "openrouter",
+					Model:          "openrouter/auto",
+					APIKey:         p.OpenRouter.APIKey,
+					APIBase:        p.OpenRouter.APIBase,
+					Proxy:          p.OpenRouter.Proxy,
+					RequestTimeout: p.OpenRouter.RequestTimeout,
 				}, true
 			},
 		},
@@ -110,11 +130,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "groq",
-					Model:     "groq/llama-3.1-70b-versatile",
-					APIKey:    p.Groq.APIKey,
-					APIBase:   p.Groq.APIBase,
-					Proxy:     p.Groq.Proxy,
+					ModelName:      "groq",
+					Model:          "groq/llama-3.1-70b-versatile",
+					APIKey:         p.Groq.APIKey,
+					APIBase:        p.Groq.APIBase,
+					Proxy:          p.Groq.Proxy,
+					RequestTimeout: p.Groq.RequestTimeout,
 				}, true
 			},
 		},
@@ -126,11 +147,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "zhipu",
-					Model:     "zhipu/glm-4",
-					APIKey:    p.Zhipu.APIKey,
-					APIBase:   p.Zhipu.APIBase,
-					Proxy:     p.Zhipu.Proxy,
+					ModelName:      "zhipu",
+					Model:          "zhipu/glm-4",
+					APIKey:         p.Zhipu.APIKey,
+					APIBase:        p.Zhipu.APIBase,
+					Proxy:          p.Zhipu.Proxy,
+					RequestTimeout: p.Zhipu.RequestTimeout,
 				}, true
 			},
 		},
@@ -142,11 +164,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "vllm",
-					Model:     "vllm/auto",
-					APIKey:    p.VLLM.APIKey,
-					APIBase:   p.VLLM.APIBase,
-					Proxy:     p.VLLM.Proxy,
+					ModelName:      "vllm",
+					Model:          "vllm/auto",
+					APIKey:         p.VLLM.APIKey,
+					APIBase:        p.VLLM.APIBase,
+					Proxy:          p.VLLM.Proxy,
+					RequestTimeout: p.VLLM.RequestTimeout,
 				}, true
 			},
 		},
@@ -158,11 +181,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "gemini",
-					Model:     "gemini/gemini-pro",
-					APIKey:    p.Gemini.APIKey,
-					APIBase:   p.Gemini.APIBase,
-					Proxy:     p.Gemini.Proxy,
+					ModelName:      "gemini",
+					Model:          "gemini/gemini-pro",
+					APIKey:         p.Gemini.APIKey,
+					APIBase:        p.Gemini.APIBase,
+					Proxy:          p.Gemini.Proxy,
+					RequestTimeout: p.Gemini.RequestTimeout,
 				}, true
 			},
 		},
@@ -174,11 +198,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "nvidia",
-					Model:     "nvidia/meta/llama-3.1-8b-instruct",
-					APIKey:    p.Nvidia.APIKey,
-					APIBase:   p.Nvidia.APIBase,
-					Proxy:     p.Nvidia.Proxy,
+					ModelName:      "nvidia",
+					Model:          "nvidia/meta/llama-3.1-8b-instruct",
+					APIKey:         p.Nvidia.APIKey,
+					APIBase:        p.Nvidia.APIBase,
+					Proxy:          p.Nvidia.Proxy,
+					RequestTimeout: p.Nvidia.RequestTimeout,
 				}, true
 			},
 		},
@@ -190,11 +215,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "ollama",
-					Model:     "ollama/llama3",
-					APIKey:    p.Ollama.APIKey,
-					APIBase:   p.Ollama.APIBase,
-					Proxy:     p.Ollama.Proxy,
+					ModelName:      "ollama",
+					Model:          "ollama/llama3",
+					APIKey:         p.Ollama.APIKey,
+					APIBase:        p.Ollama.APIBase,
+					Proxy:          p.Ollama.Proxy,
+					RequestTimeout: p.Ollama.RequestTimeout,
 				}, true
 			},
 		},
@@ -206,11 +232,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "moonshot",
-					Model:     "moonshot/kimi",
-					APIKey:    p.Moonshot.APIKey,
-					APIBase:   p.Moonshot.APIBase,
-					Proxy:     p.Moonshot.Proxy,
+					ModelName:      "moonshot",
+					Model:          "moonshot/kimi",
+					APIKey:         p.Moonshot.APIKey,
+					APIBase:        p.Moonshot.APIBase,
+					Proxy:          p.Moonshot.Proxy,
+					RequestTimeout: p.Moonshot.RequestTimeout,
 				}, true
 			},
 		},
@@ -222,11 +249,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "shengsuanyun",
-					Model:     "shengsuanyun/auto",
-					APIKey:    p.ShengSuanYun.APIKey,
-					APIBase:   p.ShengSuanYun.APIBase,
-					Proxy:     p.ShengSuanYun.Proxy,
+					ModelName:      "shengsuanyun",
+					Model:          "shengsuanyun/auto",
+					APIKey:         p.ShengSuanYun.APIKey,
+					APIBase:        p.ShengSuanYun.APIBase,
+					Proxy:          p.ShengSuanYun.Proxy,
+					RequestTimeout: p.ShengSuanYun.RequestTimeout,
 				}, true
 			},
 		},
@@ -238,11 +266,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "deepseek",
-					Model:     "deepseek/deepseek-chat",
-					APIKey:    p.DeepSeek.APIKey,
-					APIBase:   p.DeepSeek.APIBase,
-					Proxy:     p.DeepSeek.Proxy,
+					ModelName:      "deepseek",
+					Model:          "deepseek/deepseek-chat",
+					APIKey:         p.DeepSeek.APIKey,
+					APIBase:        p.DeepSeek.APIBase,
+					Proxy:          p.DeepSeek.Proxy,
+					RequestTimeout: p.DeepSeek.RequestTimeout,
 				}, true
 			},
 		},
@@ -254,11 +283,29 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "cerebras",
-					Model:     "cerebras/llama-3.3-70b",
-					APIKey:    p.Cerebras.APIKey,
-					APIBase:   p.Cerebras.APIBase,
-					Proxy:     p.Cerebras.Proxy,
+					ModelName:      "cerebras",
+					Model:          "cerebras/llama-3.3-70b",
+					APIKey:         p.Cerebras.APIKey,
+					APIBase:        p.Cerebras.APIBase,
+					Proxy:          p.Cerebras.Proxy,
+					RequestTimeout: p.Cerebras.RequestTimeout,
+				}, true
+			},
+		},
+		{
+			providerNames: []string{"vivgrid"},
+			protocol:      "vivgrid",
+			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+				if p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" {
+					return ModelConfig{}, false
+				}
+				return ModelConfig{
+					ModelName:      "vivgrid",
+					Model:          "vivgrid/auto",
+					APIKey:         p.Vivgrid.APIKey,
+					APIBase:        p.Vivgrid.APIBase,
+					Proxy:          p.Vivgrid.Proxy,
+					RequestTimeout: p.Vivgrid.RequestTimeout,
 				}, true
 			},
 		},
@@ -270,11 +317,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "volcengine",
-					Model:     "volcengine/doubao-pro",
-					APIKey:    p.VolcEngine.APIKey,
-					APIBase:   p.VolcEngine.APIBase,
-					Proxy:     p.VolcEngine.Proxy,
+					ModelName:      "volcengine",
+					Model:          "volcengine/doubao-pro",
+					APIKey:         p.VolcEngine.APIKey,
+					APIBase:        p.VolcEngine.APIBase,
+					Proxy:          p.VolcEngine.Proxy,
+					RequestTimeout: p.VolcEngine.RequestTimeout,
 				}, true
 			},
 		},
@@ -316,11 +364,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "qwen",
-					Model:     "qwen/qwen-max",
-					APIKey:    p.Qwen.APIKey,
-					APIBase:   p.Qwen.APIBase,
-					Proxy:     p.Qwen.Proxy,
+					ModelName:      "qwen",
+					Model:          "qwen/qwen-max",
+					APIKey:         p.Qwen.APIKey,
+					APIBase:        p.Qwen.APIBase,
+					Proxy:          p.Qwen.Proxy,
+					RequestTimeout: p.Qwen.RequestTimeout,
 				}, true
 			},
 		},
@@ -332,11 +381,29 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 					return ModelConfig{}, false
 				}
 				return ModelConfig{
-					ModelName: "mistral",
-					Model:     "mistral/mistral-small-latest",
-					APIKey:    p.Mistral.APIKey,
-					APIBase:   p.Mistral.APIBase,
-					Proxy:     p.Mistral.Proxy,
+					ModelName:      "mistral",
+					Model:          "mistral/mistral-small-latest",
+					APIKey:         p.Mistral.APIKey,
+					APIBase:        p.Mistral.APIBase,
+					Proxy:          p.Mistral.Proxy,
+					RequestTimeout: p.Mistral.RequestTimeout,
+				}, true
+			},
+		},
+		{
+			providerNames: []string{"avian"},
+			protocol:      "avian",
+			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+				if p.Avian.APIKey == "" && p.Avian.APIBase == "" {
+					return ModelConfig{}, false
+				}
+				return ModelConfig{
+					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
 			},
 		},
diff --git a/pkg/config/migration_test.go b/pkg/config/migration_test.go
index 42165cb71..d3019aab0 100644
--- a/pkg/config/migration_test.go
+++ b/pkg/config/migration_test.go
@@ -63,6 +63,33 @@ func TestConvertProvidersToModelList_Anthropic(t *testing.T) {
 	}
 }
 
+func TestConvertProvidersToModelList_LiteLLM(t *testing.T) {
+	cfg := &Config{
+		Providers: ProvidersConfig{
+			LiteLLM: ProviderConfig{
+				APIKey:  "litellm-key",
+				APIBase: "http://localhost:4000/v1",
+			},
+		},
+	}
+
+	result := ConvertProvidersToModelList(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 := &Config{
 		Providers: ProvidersConfig{
@@ -115,6 +142,7 @@ func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
 	cfg := &Config{
 		Providers: ProvidersConfig{
 			OpenAI:        OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "key1"}},
+			LiteLLM:       ProviderConfig{APIKey: "key-litellm", APIBase: "http://localhost:4000/v1"},
 			Anthropic:     ProviderConfig{APIKey: "key2"},
 			OpenRouter:    ProviderConfig{APIKey: "key3"},
 			Groq:          ProviderConfig{APIKey: "key4"},
@@ -127,19 +155,21 @@ func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
 			ShengSuanYun:  ProviderConfig{APIKey: "key11"},
 			DeepSeek:      ProviderConfig{APIKey: "key12"},
 			Cerebras:      ProviderConfig{APIKey: "key13"},
-			VolcEngine:    ProviderConfig{APIKey: "key14"},
+			Vivgrid:       ProviderConfig{APIKey: "key14"},
+			VolcEngine:    ProviderConfig{APIKey: "key15"},
 			GitHubCopilot: ProviderConfig{ConnectMode: "grpc"},
 			Antigravity:   ProviderConfig{AuthMethod: "oauth"},
 			Qwen:          ProviderConfig{APIKey: "key17"},
 			Mistral:       ProviderConfig{APIKey: "key18"},
+			Avian:         ProviderConfig{APIKey: "key19"},
 		},
 	}
 
 	result := ConvertProvidersToModelList(cfg)
 
-	// All 18 providers should be converted
-	if len(result) != 18 {
-		t.Errorf("len(result) = %d, want 18", len(result))
+	// All 21 providers should be converted
+	if len(result) != 21 {
+		t.Errorf("len(result) = %d, want 21", len(result))
 	}
 }
 
@@ -166,6 +196,27 @@ func TestConvertProvidersToModelList_Proxy(t *testing.T) {
 	}
 }
 
+func TestConvertProvidersToModelList_RequestTimeout(t *testing.T) {
+	cfg := &Config{
+		Providers: ProvidersConfig{
+			Ollama: ProviderConfig{
+				APIKey:         "ollama-key",
+				RequestTimeout: 300,
+			},
+		},
+	}
+
+	result := ConvertProvidersToModelList(cfg)
+
+	if len(result) != 1 {
+		t.Fatalf("len(result) = %d, want 1", len(result))
+	}
+
+	if result[0].RequestTimeout != 300 {
+		t.Errorf("RequestTimeout = %d, want %d", result[0].RequestTimeout, 300)
+	}
+}
+
 func TestConvertProvidersToModelList_AuthMethod(t *testing.T) {
 	cfg := &Config{
 		Providers: ProvidersConfig{
diff --git a/pkg/config/model_config_test.go b/pkg/config/model_config_test.go
index 3c411dc0f..da6e506f8 100644
--- a/pkg/config/model_config_test.go
+++ b/pkg/config/model_config_test.go
@@ -6,6 +6,7 @@
 package config
 
 import (
+	"encoding/json"
 	"strings"
 	"sync"
 	"testing"
@@ -63,7 +64,7 @@ func TestGetModelConfig_RoundRobin(t *testing.T) {
 
 	// Test round-robin distribution
 	results := make(map[string]int)
-	for i := 0; i < 30; i++ {
+	for range 30 {
 		result, err := cfg.GetModelConfig("lb-model")
 		if err != nil {
 			t.Fatalf("GetModelConfig() error = %v", err)
@@ -93,17 +94,15 @@ func TestGetModelConfig_Concurrent(t *testing.T) {
 	var wg sync.WaitGroup
 	errors := make(chan error, goroutines*iterations)
 
-	for i := 0; i < goroutines; i++ {
-		wg.Add(1)
-		go func() {
-			defer wg.Done()
-			for j := 0; j < iterations; j++ {
+	for range goroutines {
+		wg.Go(func() {
+			for range iterations {
 				_, err := cfg.GetModelConfig("concurrent-model")
 				if err != nil {
 					errors <- err
 				}
 			}
-		}()
+		})
 	}
 
 	wg.Wait()
@@ -114,6 +113,137 @@ 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) {
+	tests := []struct {
+		name     string
+		json     string
+		wantName string
+	}{
+		{
+			name:     "new model_name field",
+			json:     `{"model_name": "gpt4"}`,
+			wantName: "gpt4",
+		},
+		{
+			name:     "old model field",
+			json:     `{"model": "gpt4"}`,
+			wantName: "gpt4",
+		},
+		{
+			name:     "both fields - model_name wins",
+			json:     `{"model_name": "new", "model": "old"}`,
+			wantName: "new",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var defaults AgentDefaults
+			if err := json.Unmarshal([]byte(tt.json), &defaults); err != nil {
+				t.Fatalf("Unmarshal error: %v", err)
+			}
+			if got := defaults.GetModelName(); got != tt.wantName {
+				t.Errorf("GetModelName() = %q, want %q", got, tt.wantName)
+			}
+		})
+	}
+}
+
+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
@@ -233,3 +363,38 @@ func TestConfig_ValidateModelList(t *testing.T) {
 		})
 	}
 }
+
+func TestModelConfig_RequestTimeoutParsing(t *testing.T) {
+	jsonData := `{
+		"model_name": "slow-local",
+		"model": "openai/local-model",
+		"api_base": "http://localhost:11434/v1",
+		"request_timeout": 300
+	}`
+
+	var cfg ModelConfig
+	if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+
+	if cfg.RequestTimeout != 300 {
+		t.Fatalf("RequestTimeout = %d, want 300", cfg.RequestTimeout)
+	}
+}
+
+func TestModelConfig_RequestTimeoutDefaultZeroValue(t *testing.T) {
+	jsonData := `{
+		"model_name": "default-timeout",
+		"model": "openai/gpt-4o",
+		"api_key": "test-key"
+	}`
+
+	var cfg ModelConfig
+	if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+
+	if cfg.RequestTimeout != 0 {
+		t.Fatalf("RequestTimeout = %d, want 0", cfg.RequestTimeout)
+	}
+}
diff --git a/pkg/cron/service.go b/pkg/cron/service.go
index e699a44b5..04775ac42 100644
--- a/pkg/cron/service.go
+++ b/pkg/cron/service.go
@@ -7,11 +7,12 @@ import (
 	"fmt"
 	"log"
 	"os"
-	"path/filepath"
 	"sync"
 	"time"
 
 	"github.com/adhocore/gronx"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
 type CronSchedule struct {
@@ -189,14 +190,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()
@@ -219,22 +227,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 {
@@ -330,17 +351,13 @@ func (cs *CronService) loadStore() error {
 }
 
 func (cs *CronService) saveStoreUnsafe() error {
-	dir := filepath.Dir(cs.storePath)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return err
-	}
-
 	data, err := json.MarshalIndent(cs.store, "", "  ")
 	if err != nil {
 		return err
 	}
 
-	return os.WriteFile(cs.storePath, data, 0o600)
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	return fileutil.WriteFileAtomic(cs.storePath, data, 0o600)
 }
 
 func (cs *CronService) AddJob(
diff --git a/pkg/devices/service.go b/pkg/devices/service.go
index 1541d3c57..1bafe6085 100644
--- a/pkg/devices/service.go
+++ b/pkg/devices/service.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/constants"
@@ -127,7 +128,9 @@ func (s *Service) sendNotification(ev *events.DeviceEvent) {
 	}
 
 	msg := ev.FormatMessage()
-	msgBus.PublishOutbound(bus.OutboundMessage{
+	pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer pubCancel()
+	msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
 		Channel: platform,
 		ChatID:  userID,
 		Content: msg,
diff --git a/pkg/devices/sources/usb_linux.go b/pkg/devices/sources/usb_linux.go
index be0193cfb..2bb38941f 100644
--- a/pkg/devices/sources/usb_linux.go
+++ b/pkg/devices/sources/usb_linux.go
@@ -35,9 +35,8 @@ var usbClassToCapability = map[string]string{
 }
 
 type USBMonitor struct {
-	cmd    *exec.Cmd
-	cancel context.CancelFunc
-	mu     sync.Mutex
+	cmd *exec.Cmd
+	mu  sync.Mutex
 }
 
 func NewUSBMonitor() *USBMonitor {
diff --git a/pkg/fileutil/file.go b/pkg/fileutil/file.go
new file mode 100644
index 000000000..7ca872374
--- /dev/null
+++ b/pkg/fileutil/file.go
@@ -0,0 +1,119 @@
+// 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 fileutil provides file manipulation utilities.
+package fileutil
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// WriteFileAtomic atomically writes data to a file using a temp file + rename pattern.
+//
+// This guarantees that the target file is either:
+// - Completely written with the new data
+// - Unchanged (if any step fails before rename)
+//
+// The function:
+// 1. Creates a temp file in the same directory (original untouched)
+// 2. Writes data to temp file
+// 3. Syncs data to disk (critical for SD cards/flash storage)
+// 4. Sets file permissions
+// 5. Syncs directory metadata (ensures rename is durable)
+// 6. Atomically renames temp file to target path
+//
+// Safety guarantees:
+// - Original file is NEVER modified until successful rename
+// - Temp file is always cleaned up on error
+// - Data is flushed to physical storage before rename
+// - Directory entry is synced to prevent orphaned inodes
+//
+// Parameters:
+//   - path: Target file path
+//   - data: Data to write
+//   - perm: File permission mode (e.g., 0o600 for secure, 0o644 for readable)
+//
+// Returns:
+//   - Error if any step fails, nil on success
+//
+// Example:
+//
+//	// Secure config file (owner read/write only)
+//	err := utils.WriteFileAtomic("config.json", data, 0o600)
+//
+//	// Public readable file
+//	err := utils.WriteFileAtomic("public.txt", data, 0o644)
+func WriteFileAtomic(path string, data []byte, perm os.FileMode) error {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("failed to create directory: %w", err)
+	}
+
+	// Create temp file in the same directory (ensures atomic rename works)
+	// Using a hidden prefix (.tmp-) to avoid issues with some tools
+	tmpFile, err := os.OpenFile(
+		filepath.Join(dir, fmt.Sprintf(".tmp-%d-%d", os.Getpid(), time.Now().UnixNano())),
+		os.O_WRONLY|os.O_CREATE|os.O_EXCL,
+		perm,
+	)
+	if err != nil {
+		return fmt.Errorf("failed to create temp file: %w", err)
+	}
+
+	tmpPath := tmpFile.Name()
+	cleanup := true
+
+	defer func() {
+		if cleanup {
+			tmpFile.Close()
+			_ = os.Remove(tmpPath)
+		}
+	}()
+
+	// Write data to temp file
+	// Note: Original file is untouched at this point
+	if _, err := tmpFile.Write(data); err != nil {
+		return fmt.Errorf("failed to write temp file: %w", err)
+	}
+
+	// CRITICAL: Force sync to storage medium before any other operations.
+	// This ensures data is physically written to disk, not just cached.
+	// Essential for SD cards, eMMC, and other flash storage on edge devices.
+	if err := tmpFile.Sync(); err != nil {
+		return fmt.Errorf("failed to sync temp file: %w", err)
+	}
+
+	// Set file permissions before closing
+	if err := tmpFile.Chmod(perm); err != nil {
+		return fmt.Errorf("failed to set permissions: %w", err)
+	}
+
+	// Close file before rename (required on Windows)
+	if err := tmpFile.Close(); err != nil {
+		return fmt.Errorf("failed to close temp file: %w", err)
+	}
+
+	// Atomic rename: temp file becomes the target
+	// On POSIX: rename() is atomic
+	// On Windows: Rename() is atomic for files
+	if err := os.Rename(tmpPath, path); err != nil {
+		return fmt.Errorf("failed to rename temp file: %w", err)
+	}
+
+	// Sync directory to ensure rename is durable
+	// This prevents the renamed file from disappearing after a crash
+	if dirFile, err := os.Open(dir); err == nil {
+		_ = dirFile.Sync()
+		dirFile.Close()
+	}
+
+	// Success: skip cleanup (file was renamed, no temp to remove)
+	cleanup = false
+	return nil
+}
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 77b36034d..5609ebdf6 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"maps"
 	"net/http"
 	"sync"
 	"time"
@@ -122,9 +123,7 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
 	s.mu.RLock()
 	ready := s.ready
 	checks := make(map[string]Check)
-	for k, v := range s.checks {
-		checks[k] = v
-	}
+	maps.Copy(checks, s.checks)
 	s.mu.RUnlock()
 
 	if !ready {
@@ -156,6 +155,13 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// RegisterOnMux registers /health and /ready 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)
+}
+
 func statusString(ok bool) string {
 	if ok {
 		return "ok"
diff --git a/pkg/heartbeat/service.go b/pkg/heartbeat/service.go
index 75d6248b9..09c93fc6b 100644
--- a/pkg/heartbeat/service.go
+++ b/pkg/heartbeat/service.go
@@ -7,6 +7,7 @@
 package heartbeat
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -16,6 +17,7 @@ import (
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/constants"
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/state"
 	"github.com/sipeed/picoclaw/pkg/tools"
@@ -166,7 +168,7 @@ func (hs *HeartbeatService) executeHeartbeat() {
 	}
 
 	if handler == nil {
-		hs.logError("Heartbeat handler not configured")
+		hs.logErrorf("Heartbeat handler not configured")
 		return
 	}
 
@@ -175,23 +177,23 @@ func (hs *HeartbeatService) executeHeartbeat() {
 	channel, chatID := hs.parseLastChannel(lastChannel)
 
 	// Debug log for channel resolution
-	hs.logInfo("Resolved channel: %s, chatID: %s (from lastChannel: %s)", channel, chatID, lastChannel)
+	hs.logInfof("Resolved channel: %s, chatID: %s (from lastChannel: %s)", channel, chatID, lastChannel)
 
 	result := handler(prompt, channel, chatID)
 
 	if result == nil {
-		hs.logInfo("Heartbeat handler returned nil result")
+		hs.logInfof("Heartbeat handler returned nil result")
 		return
 	}
 
 	// Handle different result types
 	if result.IsError {
-		hs.logError("Heartbeat error: %s", result.ForLLM)
+		hs.logErrorf("Heartbeat error: %s", result.ForLLM)
 		return
 	}
 
 	if result.Async {
-		hs.logInfo("Async task started: %s", result.ForLLM)
+		hs.logInfof("Async task started: %s", result.ForLLM)
 		logger.InfoCF("heartbeat", "Async heartbeat task started",
 			map[string]any{
 				"message": result.ForLLM,
@@ -201,7 +203,7 @@ func (hs *HeartbeatService) executeHeartbeat() {
 
 	// Check if silent
 	if result.Silent {
-		hs.logInfo("Heartbeat OK - silent")
+		hs.logInfof("Heartbeat OK - silent")
 		return
 	}
 
@@ -212,7 +214,7 @@ func (hs *HeartbeatService) executeHeartbeat() {
 		hs.sendResponse(result.ForLLM)
 	}
 
-	hs.logInfo("Heartbeat completed: %s", result.ForLLM)
+	hs.logInfof("Heartbeat completed: %s", result.ForLLM)
 }
 
 // buildPrompt builds the heartbeat prompt from HEARTBEAT.md
@@ -225,7 +227,7 @@ func (hs *HeartbeatService) buildPrompt() string {
 			hs.createDefaultHeartbeatTemplate()
 			return ""
 		}
-		hs.logError("Error reading HEARTBEAT.md: %v", err)
+		hs.logErrorf("Error reading HEARTBEAT.md: %v", err)
 		return ""
 	}
 
@@ -275,10 +277,10 @@ This file contains tasks for the heartbeat service to check periodically.
 Add your heartbeat tasks below this line:
 `
 
-	if err := os.WriteFile(heartbeatPath, []byte(defaultContent), 0o644); err != nil {
-		hs.logError("Failed to create default HEARTBEAT.md: %v", err)
+	if err := fileutil.WriteFileAtomic(heartbeatPath, []byte(defaultContent), 0o644); err != nil {
+		hs.logErrorf("Failed to create default HEARTBEAT.md: %v", err)
 	} else {
-		hs.logInfo("Created default HEARTBEAT.md template")
+		hs.logInfof("Created default HEARTBEAT.md template")
 	}
 }
 
@@ -289,14 +291,14 @@ func (hs *HeartbeatService) sendResponse(response string) {
 	hs.mu.RUnlock()
 
 	if msgBus == nil {
-		hs.logInfo("No message bus configured, heartbeat result not sent")
+		hs.logInfof("No message bus configured, heartbeat result not sent")
 		return
 	}
 
 	// Get last channel from state
 	lastChannel := hs.state.GetLastChannel()
 	if lastChannel == "" {
-		hs.logInfo("No last channel recorded, heartbeat result not sent")
+		hs.logInfof("No last channel recorded, heartbeat result not sent")
 		return
 	}
 
@@ -307,13 +309,15 @@ func (hs *HeartbeatService) sendResponse(response string) {
 		return
 	}
 
-	msgBus.PublishOutbound(bus.OutboundMessage{
+	pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer pubCancel()
+	msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
 		Channel: platform,
 		ChatID:  userID,
 		Content: response,
 	})
 
-	hs.logInfo("Heartbeat result sent to %s", platform)
+	hs.logInfof("Heartbeat result sent to %s", platform)
 }
 
 // parseLastChannel parses the last channel string into platform and userID.
@@ -326,7 +330,7 @@ func (hs *HeartbeatService) parseLastChannel(lastChannel string) (platform, user
 	// Parse channel format: "platform:user_id" (e.g., "telegram:123456")
 	parts := strings.SplitN(lastChannel, ":", 2)
 	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
-		hs.logError("Invalid last channel format: %s", lastChannel)
+		hs.logErrorf("Invalid last channel format: %s", lastChannel)
 		return "", ""
 	}
 
@@ -334,25 +338,25 @@ func (hs *HeartbeatService) parseLastChannel(lastChannel string) (platform, user
 
 	// Skip internal channels
 	if constants.IsInternalChannel(platform) {
-		hs.logInfo("Skipping internal channel: %s", platform)
+		hs.logInfof("Skipping internal channel: %s", platform)
 		return "", ""
 	}
 
 	return platform, userID
 }
 
-// logInfo logs an informational message to the heartbeat log
-func (hs *HeartbeatService) logInfo(format string, args ...any) {
-	hs.log("INFO", format, args...)
+// logInfof logs an informational message to the heartbeat log
+func (hs *HeartbeatService) logInfof(format string, args ...any) {
+	hs.logf("INFO", format, args...)
 }
 
-// logError logs an error message to the heartbeat log
-func (hs *HeartbeatService) logError(format string, args ...any) {
-	hs.log("ERROR", format, args...)
+// logErrorf logs an error message to the heartbeat log
+func (hs *HeartbeatService) logErrorf(format string, args ...any) {
+	hs.logf("ERROR", format, args...)
 }
 
-// log writes a message to the heartbeat log file
-func (hs *HeartbeatService) log(level, format string, args ...any) {
+// logf writes a message to the heartbeat log file
+func (hs *HeartbeatService) logf(level, format string, args ...any) {
 	logFile := filepath.Join(hs.workspace, "heartbeat.log")
 	f, err := os.OpenFile(logFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
 	if err != nil {
diff --git a/pkg/heartbeat/service_test.go b/pkg/heartbeat/service_test.go
index a4dfa7a72..3b7eeeefb 100644
--- a/pkg/heartbeat/service_test.go
+++ b/pkg/heartbeat/service_test.go
@@ -47,79 +47,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)
+			}
+		})
 	}
 }
 
@@ -191,7 +175,7 @@ func TestLogPath(t *testing.T) {
 	hs := NewHeartbeatService(tmpDir, 30, true)
 
 	// Write a log entry
-	hs.log("INFO", "Test log entry")
+	hs.logf("INFO", "Test log entry")
 
 	// Verify log file exists at workspace root
 	expectedLogPath := filepath.Join(tmpDir, "heartbeat.log")
diff --git a/pkg/identity/identity.go b/pkg/identity/identity.go
new file mode 100644
index 000000000..6bc09c210
--- /dev/null
+++ b/pkg/identity/identity.go
@@ -0,0 +1,107 @@
+// Package identity provides unified user identity utilities for PicoClaw.
+// It introduces a canonical "platform:id" format and matching logic
+// that is backward-compatible with all legacy allow-list formats.
+package identity
+
+import (
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+)
+
+// BuildCanonicalID constructs a canonical "platform:id" identifier.
+// Both platform and platformID are lowercased and trimmed.
+func BuildCanonicalID(platform, platformID string) string {
+	p := strings.ToLower(strings.TrimSpace(platform))
+	id := strings.TrimSpace(platformID)
+	if p == "" || id == "" {
+		return ""
+	}
+	return p + ":" + id
+}
+
+// ParseCanonicalID splits a canonical ID ("platform:id") into its parts.
+// Returns ok=false if the input does not contain a colon separator.
+func ParseCanonicalID(canonical string) (platform, id string, ok bool) {
+	canonical = strings.TrimSpace(canonical)
+	idx := strings.Index(canonical, ":")
+	if idx <= 0 || idx == len(canonical)-1 {
+		return "", "", false
+	}
+	return canonical[:idx], canonical[idx+1:], true
+}
+
+// MatchAllowed checks whether the given sender matches a single allow-list entry.
+// It is backward-compatible with all legacy formats:
+//
+//   - "123456"              → matches sender.PlatformID
+//   - "@alice"              → matches sender.Username
+//   - "123456|alice"        → matches PlatformID or Username
+//   - "telegram:123456"     → exact match on sender.CanonicalID
+func MatchAllowed(sender bus.SenderInfo, allowed string) bool {
+	allowed = strings.TrimSpace(allowed)
+	if allowed == "" {
+		return false
+	}
+
+	// Try canonical match first: "platform:id" format
+	if platform, id, ok := ParseCanonicalID(allowed); ok {
+		// Only treat as canonical if the platform portion looks like a known platform name
+		// (not a pure-numeric string, which could be a compound ID)
+		if !isNumeric(platform) {
+			candidate := BuildCanonicalID(platform, id)
+			if candidate != "" && sender.CanonicalID != "" {
+				return strings.EqualFold(sender.CanonicalID, candidate)
+			}
+			// If sender has no canonical ID, try matching platform + platformID
+			return strings.EqualFold(platform, sender.Platform) &&
+				sender.PlatformID == id
+		}
+	}
+
+	// Strip leading "@" for username matching
+	trimmed := strings.TrimPrefix(allowed, "@")
+
+	// Split compound "id|username" format
+	allowedID := trimmed
+	allowedUser := ""
+	if idx := strings.Index(trimmed, "|"); idx > 0 {
+		allowedID = trimmed[:idx]
+		allowedUser = trimmed[idx+1:]
+	}
+
+	// Match against PlatformID
+	if sender.PlatformID != "" && sender.PlatformID == allowedID {
+		return true
+	}
+
+	// Match against Username
+	if sender.Username != "" {
+		if sender.Username == trimmed || sender.Username == allowedUser {
+			return true
+		}
+	}
+
+	// Match compound sender format against allowed parts
+	if allowedUser != "" && sender.PlatformID != "" && sender.PlatformID == allowedID {
+		return true
+	}
+	if allowedUser != "" && sender.Username != "" && sender.Username == allowedUser {
+		return true
+	}
+
+	return false
+}
+
+// isNumeric returns true if s consists entirely of digits.
+func isNumeric(s string) bool {
+	if s == "" {
+		return false
+	}
+	for _, r := range s {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+	return true
+}
diff --git a/pkg/identity/identity_test.go b/pkg/identity/identity_test.go
new file mode 100644
index 000000000..3d24bd794
--- /dev/null
+++ b/pkg/identity/identity_test.go
@@ -0,0 +1,229 @@
+package identity
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+)
+
+func TestBuildCanonicalID(t *testing.T) {
+	tests := []struct {
+		platform   string
+		platformID string
+		want       string
+	}{
+		{"telegram", "123456", "telegram:123456"},
+		{"Discord", "98765432", "discord:98765432"},
+		{"SLACK", "U123ABC", "slack:U123ABC"},
+		{"", "123", ""},
+		{"telegram", "", ""},
+		{"  telegram  ", "  123  ", "telegram:123"},
+	}
+
+	for _, tt := range tests {
+		got := BuildCanonicalID(tt.platform, tt.platformID)
+		if got != tt.want {
+			t.Errorf("BuildCanonicalID(%q, %q) = %q, want %q",
+				tt.platform, tt.platformID, got, tt.want)
+		}
+	}
+}
+
+func TestParseCanonicalID(t *testing.T) {
+	tests := []struct {
+		input        string
+		wantPlatform string
+		wantID       string
+		wantOk       bool
+	}{
+		{"telegram:123456", "telegram", "123456", true},
+		{"discord:98765432", "discord", "98765432", true},
+		{"slack:U123ABC", "slack", "U123ABC", true},
+		{"nocolon", "", "", false},
+		{"", "", "", false},
+		{":missing", "", "", false},
+		{"missing:", "", "", false},
+	}
+
+	for _, tt := range tests {
+		platform, id, ok := ParseCanonicalID(tt.input)
+		if ok != tt.wantOk || platform != tt.wantPlatform || id != tt.wantID {
+			t.Errorf("ParseCanonicalID(%q) = (%q, %q, %v), want (%q, %q, %v)",
+				tt.input, platform, id, ok,
+				tt.wantPlatform, tt.wantID, tt.wantOk)
+		}
+	}
+}
+
+func TestMatchAllowed(t *testing.T) {
+	telegramSender := bus.SenderInfo{
+		Platform:    "telegram",
+		PlatformID:  "123456",
+		CanonicalID: "telegram:123456",
+		Username:    "alice",
+		DisplayName: "Alice Smith",
+	}
+
+	discordSender := bus.SenderInfo{
+		Platform:    "discord",
+		PlatformID:  "98765432",
+		CanonicalID: "discord:98765432",
+		Username:    "bob",
+		DisplayName: "bob#1234",
+	}
+
+	noCanonicalSender := bus.SenderInfo{
+		Platform:   "telegram",
+		PlatformID: "999",
+		Username:   "carol",
+	}
+
+	tests := []struct {
+		name    string
+		sender  bus.SenderInfo
+		allowed string
+		want    bool
+	}{
+		// Pure numeric ID matching
+		{
+			name:    "numeric ID matches PlatformID",
+			sender:  telegramSender,
+			allowed: "123456",
+			want:    true,
+		},
+		{
+			name:    "numeric ID does not match",
+			sender:  telegramSender,
+			allowed: "654321",
+			want:    false,
+		},
+		// Username matching
+		{
+			name:    "@username matches Username",
+			sender:  telegramSender,
+			allowed: "@alice",
+			want:    true,
+		},
+		{
+			name:    "@username does not match",
+			sender:  telegramSender,
+			allowed: "@bob",
+			want:    false,
+		},
+		// Compound format "id|username"
+		{
+			name:    "compound matches by ID",
+			sender:  telegramSender,
+			allowed: "123456|alice",
+			want:    true,
+		},
+		{
+			name:    "compound matches by username",
+			sender:  telegramSender,
+			allowed: "999|alice",
+			want:    true,
+		},
+		{
+			name:    "compound does not match",
+			sender:  telegramSender,
+			allowed: "654321|bob",
+			want:    false,
+		},
+		// Canonical format "platform:id"
+		{
+			name:    "canonical matches exactly",
+			sender:  telegramSender,
+			allowed: "telegram:123456",
+			want:    true,
+		},
+		{
+			name:    "canonical case-insensitive platform",
+			sender:  telegramSender,
+			allowed: "Telegram:123456",
+			want:    true,
+		},
+		{
+			name:    "canonical wrong platform",
+			sender:  telegramSender,
+			allowed: "discord:123456",
+			want:    false,
+		},
+		{
+			name:    "canonical wrong ID",
+			sender:  telegramSender,
+			allowed: "telegram:654321",
+			want:    false,
+		},
+		// Cross-platform canonical
+		{
+			name:    "discord canonical match",
+			sender:  discordSender,
+			allowed: "discord:98765432",
+			want:    true,
+		},
+		{
+			name:    "telegram canonical does not match discord sender",
+			sender:  discordSender,
+			allowed: "telegram:98765432",
+			want:    false,
+		},
+		// Sender without canonical ID
+		{
+			name:    "canonical match falls back to platform+platformID",
+			sender:  noCanonicalSender,
+			allowed: "telegram:999",
+			want:    true,
+		},
+		{
+			name:    "platform mismatch on fallback",
+			sender:  noCanonicalSender,
+			allowed: "discord:999",
+			want:    false,
+		},
+		// Empty allowed string
+		{
+			name:    "empty allowed never matches",
+			sender:  telegramSender,
+			allowed: "",
+			want:    false,
+		},
+		// Whitespace handling
+		{
+			name:    "trimmed allowed matches",
+			sender:  telegramSender,
+			allowed: "  123456  ",
+			want:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := MatchAllowed(tt.sender, tt.allowed)
+			if got != tt.want {
+				t.Errorf("MatchAllowed(%+v, %q) = %v, want %v",
+					tt.sender, tt.allowed, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsNumeric(t *testing.T) {
+	tests := []struct {
+		input string
+		want  bool
+	}{
+		{"123456", true},
+		{"0", true},
+		{"", false},
+		{"abc", false},
+		{"12a34", false},
+		{"telegram", false},
+	}
+
+	for _, tt := range tests {
+		got := isNumeric(tt.input)
+		if got != tt.want {
+			t.Errorf("isNumeric(%q) = %v, want %v", tt.input, got, tt.want)
+		}
+	}
+}
diff --git a/pkg/logger/logger.go b/pkg/logger/logger.go
index c14fbd464..56dc87a53 100644
--- a/pkg/logger/logger.go
+++ b/pkg/logger/logger.go
@@ -153,7 +153,7 @@ func formatComponent(component string) string {
 }
 
 func formatFields(fields map[string]any) string {
-	var parts []string
+	parts := make([]string, 0, len(fields))
 	for k, v := range fields {
 		parts = append(parts, fmt.Sprintf("%s=%v", k, v))
 	}
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
new file mode 100644
index 000000000..30220986c
--- /dev/null
+++ b/pkg/media/store.go
@@ -0,0 +1,271 @@
+package media
+
+import (
+	"fmt"
+	"os"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// MediaMeta holds metadata about a stored media file.
+type MediaMeta struct {
+	Filename    string
+	ContentType string
+	Source      string // "telegram", "discord", "tool:image-gen", etc.
+}
+
+// MediaStore manages the lifecycle of media files associated with processing scopes.
+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.
+	Store(localPath string, meta MediaMeta, scope string) (ref string, err error)
+
+	// Resolve returns the local file path for a given ref.
+	Resolve(ref string) (localPath string, err error)
+
+	// ResolveWithMeta returns the local file path and metadata for a given ref.
+	ResolveWithMeta(ref string) (localPath string, meta MediaMeta, err error)
+
+	// ReleaseAll deletes all files registered under the given scope
+	// and removes the mapping entries. File-not-exist errors are ignored.
+	ReleaseAll(scope string) error
+}
+
+// mediaEntry holds the path and metadata for a stored media file.
+type mediaEntry struct {
+	path     string
+	meta     MediaMeta
+	storedAt time.Time
+}
+
+// MediaCleanerConfig configures the background TTL cleanup.
+type MediaCleanerConfig struct {
+	Enabled  bool
+	MaxAge   time.Duration
+	Interval time.Duration
+}
+
+// FileMediaStore is a pure in-memory implementation of MediaStore.
+// Files are expected to already exist on disk (e.g. in /tmp/picoclaw_media/).
+type FileMediaStore struct {
+	mu          sync.RWMutex
+	refs        map[string]mediaEntry
+	scopeToRefs map[string]map[string]struct{}
+	refToScope  map[string]string
+
+	cleanerCfg MediaCleanerConfig
+	stop       chan struct{}
+	startOnce  sync.Once
+	stopOnce   sync.Once
+	nowFunc    func() time.Time // for testing
+}
+
+// NewFileMediaStore creates a new FileMediaStore without background cleanup.
+func NewFileMediaStore() *FileMediaStore {
+	return &FileMediaStore{
+		refs:        make(map[string]mediaEntry),
+		scopeToRefs: make(map[string]map[string]struct{}),
+		refToScope:  make(map[string]string),
+		nowFunc:     time.Now,
+	}
+}
+
+// NewFileMediaStoreWithCleanup creates a FileMediaStore with TTL-based background cleanup.
+func NewFileMediaStoreWithCleanup(cfg MediaCleanerConfig) *FileMediaStore {
+	return &FileMediaStore{
+		refs:        make(map[string]mediaEntry),
+		scopeToRefs: make(map[string]map[string]struct{}),
+		refToScope:  make(map[string]string),
+		cleanerCfg:  cfg,
+		stop:        make(chan struct{}),
+		nowFunc:     time.Now,
+	}
+}
+
+// Store registers a local file under the given scope. The file must exist.
+func (s *FileMediaStore) Store(localPath string, meta MediaMeta, scope string) (string, error) {
+	if _, err := os.Stat(localPath); err != nil {
+		return "", fmt.Errorf("media store: %s: %w", localPath, err)
+	}
+
+	ref := "media://" + uuid.New().String()
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.refs[ref] = mediaEntry{path: localPath, meta: meta, storedAt: s.nowFunc()}
+	if s.scopeToRefs[scope] == nil {
+		s.scopeToRefs[scope] = make(map[string]struct{})
+	}
+	s.scopeToRefs[scope][ref] = struct{}{}
+	s.refToScope[ref] = scope
+
+	return ref, nil
+}
+
+// Resolve returns the local path for the given ref.
+func (s *FileMediaStore) Resolve(ref string) (string, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	entry, ok := s.refs[ref]
+	if !ok {
+		return "", fmt.Errorf("media store: unknown ref: %s", ref)
+	}
+	return entry.path, nil
+}
+
+// ResolveWithMeta returns the local path and metadata for the given ref.
+func (s *FileMediaStore) ResolveWithMeta(ref string) (string, MediaMeta, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	entry, ok := s.refs[ref]
+	if !ok {
+		return "", MediaMeta{}, fmt.Errorf("media store: unknown ref: %s", ref)
+	}
+	return entry.path, entry.meta, nil
+}
+
+// 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.
+func (s *FileMediaStore) ReleaseAll(scope string) error {
+	// Phase 1: collect paths and remove from maps under lock
+	var paths []string
+
+	s.mu.Lock()
+	refs, ok := s.scopeToRefs[scope]
+	if !ok {
+		s.mu.Unlock()
+		return nil
+	}
+
+	for ref := range refs {
+		if entry, exists := s.refs[ref]; exists {
+			paths = append(paths, entry.path)
+		}
+		delete(s.refs, ref)
+		delete(s.refToScope, ref)
+	}
+	delete(s.scopeToRefs, scope)
+	s.mu.Unlock()
+
+	// Phase 2: delete files without holding the lock
+	for _, p := range paths {
+		if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+			logger.WarnCF("media", "release: failed to remove file", map[string]any{
+				"path":  p,
+				"error": err.Error(),
+			})
+		}
+	}
+
+	return nil
+}
+
+// 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.
+func (s *FileMediaStore) CleanExpired() int {
+	if s.cleanerCfg.MaxAge <= 0 {
+		return 0
+	}
+
+	// Phase 1: collect expired entries under lock
+	type expiredEntry struct {
+		ref  string
+		path string
+	}
+
+	s.mu.Lock()
+	cutoff := s.nowFunc().Add(-s.cleanerCfg.MaxAge)
+	var expired []expiredEntry
+
+	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)
+					if len(scopeRefs) == 0 {
+						delete(s.scopeToRefs, scope)
+					}
+				}
+			}
+
+			delete(s.refs, ref)
+			delete(s.refToScope, ref)
+		}
+	}
+	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) {
+			logger.WarnCF("media", "cleanup: failed to remove file", map[string]any{
+				"path":  e.path,
+				"error": err.Error(),
+			})
+		}
+	}
+
+	return len(expired)
+}
+
+// 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() {
+	if !s.cleanerCfg.Enabled || s.stop == nil {
+		return
+	}
+	if s.cleanerCfg.Interval <= 0 || s.cleanerCfg.MaxAge <= 0 {
+		logger.WarnCF("media", "cleanup: skipped due to invalid config", map[string]any{
+			"interval": s.cleanerCfg.Interval.String(),
+			"max_age":  s.cleanerCfg.MaxAge.String(),
+		})
+		return
+	}
+
+	s.startOnce.Do(func() {
+		logger.InfoCF("media", "cleanup enabled", map[string]any{
+			"interval": s.cleanerCfg.Interval.String(),
+			"max_age":  s.cleanerCfg.MaxAge.String(),
+		})
+
+		go func() {
+			ticker := time.NewTicker(s.cleanerCfg.Interval)
+			defer ticker.Stop()
+
+			for {
+				select {
+				case <-ticker.C:
+					if n := s.CleanExpired(); n > 0 {
+						logger.InfoCF("media", "cleanup: removed expired entries", map[string]any{
+							"count": n,
+						})
+					}
+				case <-s.stop:
+					return
+				}
+			}
+		}()
+	})
+}
+
+// Stop terminates the background cleanup goroutine.
+// Safe to call multiple times; only the first call closes the channel.
+func (s *FileMediaStore) Stop() {
+	if s.stop == nil {
+		return
+	}
+	s.stopOnce.Do(func() {
+		close(s.stop)
+	})
+}
diff --git a/pkg/media/store_test.go b/pkg/media/store_test.go
new file mode 100644
index 000000000..1dcfdf350
--- /dev/null
+++ b/pkg/media/store_test.go
@@ -0,0 +1,530 @@
+package media
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func createTempFile(t *testing.T, dir, name string) string {
+	t.Helper()
+	path := filepath.Join(dir, name)
+	if err := os.WriteFile(path, []byte("test content"), 0o644); err != nil {
+		t.Fatalf("failed to create temp file: %v", err)
+	}
+	return path
+}
+
+func TestStoreAndResolve(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	path := createTempFile(t, dir, "photo.jpg")
+
+	ref, err := store.Store(path, MediaMeta{Filename: "photo.jpg", Source: "telegram"}, "scope1")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	if !strings.HasPrefix(ref, "media://") {
+		t.Errorf("ref should start with media://, got %q", ref)
+	}
+
+	resolved, err := store.Resolve(ref)
+	if err != nil {
+		t.Fatalf("Resolve failed: %v", err)
+	}
+	if resolved != path {
+		t.Errorf("Resolve returned %q, want %q", resolved, path)
+	}
+}
+
+func TestReleaseAll(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	paths := make([]string, 3)
+	refs := make([]string, 3)
+	for i := range 3 {
+		paths[i] = createTempFile(t, dir, strings.Repeat("a", i+1)+".jpg")
+		var err error
+		refs[i], err = store.Store(paths[i], MediaMeta{Source: "test"}, "scope1")
+		if err != nil {
+			t.Fatalf("Store failed: %v", err)
+		}
+	}
+
+	if err := store.ReleaseAll("scope1"); err != nil {
+		t.Fatalf("ReleaseAll failed: %v", err)
+	}
+
+	// Files should be deleted
+	for _, p := range paths {
+		if _, err := os.Stat(p); !os.IsNotExist(err) {
+			t.Errorf("file %q should have been deleted", p)
+		}
+	}
+
+	// Refs should be unresolvable
+	for _, ref := range refs {
+		if _, err := store.Resolve(ref); err == nil {
+			t.Errorf("Resolve(%q) should fail after ReleaseAll", ref)
+		}
+	}
+}
+
+func TestMultiScopeIsolation(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	pathA := createTempFile(t, dir, "fileA.jpg")
+	pathB := createTempFile(t, dir, "fileB.jpg")
+
+	refA, _ := store.Store(pathA, MediaMeta{Source: "test"}, "scopeA")
+	refB, _ := store.Store(pathB, MediaMeta{Source: "test"}, "scopeB")
+
+	// Release only scopeA
+	if err := store.ReleaseAll("scopeA"); err != nil {
+		t.Fatalf("ReleaseAll(scopeA) failed: %v", err)
+	}
+
+	// scopeA file should be gone
+	if _, err := os.Stat(pathA); !os.IsNotExist(err) {
+		t.Error("file A should have been deleted")
+	}
+	if _, err := store.Resolve(refA); err == nil {
+		t.Error("refA should be unresolvable after release")
+	}
+
+	// scopeB file should still exist
+	if _, err := os.Stat(pathB); err != nil {
+		t.Error("file B should still exist")
+	}
+	resolved, err := store.Resolve(refB)
+	if err != nil {
+		t.Fatalf("refB should still resolve: %v", err)
+	}
+	if resolved != pathB {
+		t.Errorf("resolved %q, want %q", resolved, pathB)
+	}
+}
+
+func TestReleaseAllIdempotent(t *testing.T) {
+	store := NewFileMediaStore()
+
+	// ReleaseAll on non-existent scope should not error
+	if err := store.ReleaseAll("nonexistent"); err != nil {
+		t.Fatalf("ReleaseAll on empty scope should not error: %v", err)
+	}
+
+	// Create and release, then release again
+	dir := t.TempDir()
+	path := createTempFile(t, dir, "file.jpg")
+	_, _ = store.Store(path, MediaMeta{Source: "test"}, "scope1")
+
+	if err := store.ReleaseAll("scope1"); err != nil {
+		t.Fatalf("first ReleaseAll failed: %v", err)
+	}
+	if err := store.ReleaseAll("scope1"); err != nil {
+		t.Fatalf("second ReleaseAll should not error: %v", err)
+	}
+}
+
+func TestReleaseAllCleansMappingsIfRefsMissing(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	path := createTempFile(t, dir, "file.jpg")
+	ref, err := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	// Simulate internal inconsistency: scopeToRefs/refToScope contains ref but refs map doesn't.
+	store.mu.Lock()
+	delete(store.refs, ref)
+	store.mu.Unlock()
+
+	if err := store.ReleaseAll("scope1"); err != nil {
+		t.Fatalf("ReleaseAll failed: %v", err)
+	}
+
+	// ReleaseAll should still clean mappings (even if it can't delete the file without the path).
+	store.mu.RLock()
+	defer store.mu.RUnlock()
+	if _, ok := store.refToScope[ref]; ok {
+		t.Error("refToScope should not contain ref after ReleaseAll")
+	}
+	if _, ok := store.scopeToRefs["scope1"]; ok {
+		t.Error("scopeToRefs should not contain scope1 after ReleaseAll")
+	}
+}
+
+func TestStoreNonexistentFile(t *testing.T) {
+	store := NewFileMediaStore()
+
+	_, err := store.Store("/nonexistent/path/file.jpg", MediaMeta{Source: "test"}, "scope1")
+	if err == nil {
+		t.Error("Store should fail for nonexistent file")
+	}
+	// Error message should include the underlying os error, not just "file does not exist"
+	if !strings.Contains(err.Error(), "no such file or directory") &&
+		!strings.Contains(err.Error(), "cannot find") {
+		t.Errorf("Error should contain OS error detail, got: %v", err)
+	}
+}
+
+func TestResolveWithMeta(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	path := createTempFile(t, dir, "image.png")
+	meta := MediaMeta{
+		Filename:    "image.png",
+		ContentType: "image/png",
+		Source:      "telegram",
+	}
+
+	ref, err := store.Store(path, meta, "scope1")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	resolvedPath, resolvedMeta, err := store.ResolveWithMeta(ref)
+	if err != nil {
+		t.Fatalf("ResolveWithMeta failed: %v", err)
+	}
+	if resolvedPath != path {
+		t.Errorf("ResolveWithMeta path = %q, want %q", resolvedPath, path)
+	}
+	if resolvedMeta.Filename != meta.Filename {
+		t.Errorf("ResolveWithMeta Filename = %q, want %q", resolvedMeta.Filename, meta.Filename)
+	}
+	if resolvedMeta.ContentType != meta.ContentType {
+		t.Errorf("ResolveWithMeta ContentType = %q, want %q", resolvedMeta.ContentType, meta.ContentType)
+	}
+	if resolvedMeta.Source != meta.Source {
+		t.Errorf("ResolveWithMeta Source = %q, want %q", resolvedMeta.Source, meta.Source)
+	}
+
+	// Unknown ref should fail
+	_, _, err = store.ResolveWithMeta("media://nonexistent")
+	if err == nil {
+		t.Error("ResolveWithMeta should fail for unknown ref")
+	}
+}
+
+func TestConcurrentSafety(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	const goroutines = 20
+	const filesPerGoroutine = 5
+
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+
+	for g := range goroutines {
+		go func(gIdx int) {
+			defer wg.Done()
+			scope := strings.Repeat("s", gIdx+1)
+
+			for i := range filesPerGoroutine {
+				path := createTempFile(t, dir, strings.Repeat("f", gIdx*filesPerGoroutine+i+1)+".tmp")
+				ref, err := store.Store(path, MediaMeta{Source: "test"}, scope)
+				if err != nil {
+					t.Errorf("Store failed: %v", err)
+					return
+				}
+
+				if _, err := store.Resolve(ref); err != nil {
+					t.Errorf("Resolve failed: %v", err)
+				}
+			}
+
+			if err := store.ReleaseAll(scope); err != nil {
+				t.Errorf("ReleaseAll failed: %v", err)
+			}
+		}(g)
+	}
+
+	wg.Wait()
+}
+
+// --- TTL cleanup tests ---
+
+func newTestStoreWithCleanup(maxAge time.Duration) *FileMediaStore {
+	s := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+		Enabled:  true,
+		MaxAge:   maxAge,
+		Interval: time.Hour, // won't tick in tests
+	})
+	return s
+}
+
+func TestCleanExpiredRemovesOldEntries(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, "old.jpg")
+	ref, err := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	// Advance clock to present
+	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 ref should be unresolvable")
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Error("expired file should be deleted")
+	}
+}
+
+func TestCleanExpiredKeepsNonExpired(t *testing.T) {
+	dir := t.TempDir()
+	now := time.Now()
+	store := newTestStoreWithCleanup(10 * time.Minute)
+	store.nowFunc = func() time.Time { return now }
+
+	path := createTempFile(t, dir, "fresh.jpg")
+	ref, err := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	removed := store.CleanExpired()
+	if removed != 0 {
+		t.Errorf("expected 0 removed, got %d", removed)
+	}
+
+	if _, err := store.Resolve(ref); err != nil {
+		t.Errorf("fresh ref should still resolve: %v", err)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Error("fresh file should still exist")
+	}
+}
+
+func TestCleanExpiredMixedAges(t *testing.T) {
+	dir := t.TempDir()
+	now := time.Now()
+	store := newTestStoreWithCleanup(10 * time.Minute)
+
+	// Store old entry
+	store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+	oldPath := createTempFile(t, dir, "old.jpg")
+	oldRef, _ := store.Store(oldPath, MediaMeta{Source: "test"}, "scope1")
+
+	// Store fresh entry
+	store.nowFunc = func() time.Time { return now }
+	freshPath := createTempFile(t, dir, "fresh.jpg")
+	freshRef, _ := store.Store(freshPath, MediaMeta{Source: "test"}, "scope1")
+
+	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")
+	}
+	if _, err := store.Resolve(freshRef); err != nil {
+		t.Errorf("fresh ref should still resolve: %v", err)
+	}
+}
+
+func TestCleanExpiredCleansEmptyScopes(t *testing.T) {
+	dir := t.TempDir()
+	now := time.Now()
+	store := newTestStoreWithCleanup(10 * time.Minute)
+
+	// Store old entry as the only one in scope
+	store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+	path := createTempFile(t, dir, "only.jpg")
+	store.Store(path, MediaMeta{Source: "test"}, "lonely_scope")
+
+	store.nowFunc = func() time.Time { return now }
+	store.CleanExpired()
+
+	store.mu.RLock()
+	defer store.mu.RUnlock()
+	if _, ok := store.scopeToRefs["lonely_scope"]; ok {
+		t.Error("empty scope should be cleaned up")
+	}
+}
+
+func TestStartStopLifecycle(t *testing.T) {
+	store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+		Enabled:  true,
+		MaxAge:   time.Minute,
+		Interval: 50 * time.Millisecond,
+	})
+
+	// Start and stop should not panic
+	store.Start()
+	// Double start should not spawn a second goroutine
+	store.Start()
+	time.Sleep(100 * time.Millisecond)
+	store.Stop()
+
+	// Double stop should not panic
+	store.Stop()
+}
+
+func TestCleanExpiredZeroMaxAge(t *testing.T) {
+	store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+		Enabled:  true,
+		MaxAge:   0,
+		Interval: time.Hour,
+	})
+
+	dir := t.TempDir()
+	path := createTempFile(t, dir, "file.jpg")
+	ref, _ := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+
+	// Zero MaxAge should be a no-op
+	removed := store.CleanExpired()
+	if removed != 0 {
+		t.Errorf("expected 0 removed with zero MaxAge, got %d", removed)
+	}
+	if _, err := store.Resolve(ref); err != nil {
+		t.Errorf("ref should still resolve: %v", err)
+	}
+}
+
+func TestStartDisabledIsNoop(t *testing.T) {
+	store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+		Enabled:  false,
+		MaxAge:   time.Minute,
+		Interval: time.Minute,
+	})
+	// Should not start any goroutine or panic
+	store.Start()
+	store.Stop()
+}
+
+func TestStartZeroIntervalNoPanic(t *testing.T) {
+	store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+		Enabled:  true,
+		MaxAge:   time.Minute,
+		Interval: 0,
+	})
+	// Zero interval should not panic (time.NewTicker panics on <= 0)
+	store.Start()
+	store.Stop()
+}
+
+func TestStartZeroMaxAgeNoPanic(t *testing.T) {
+	store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+		Enabled:  true,
+		MaxAge:   0,
+		Interval: time.Minute,
+	})
+	store.Start()
+	store.Stop()
+}
+
+func TestConcurrentCleanupSafety(t *testing.T) {
+	dir := t.TempDir()
+	store := newTestStoreWithCleanup(50 * time.Millisecond)
+	store.nowFunc = time.Now
+
+	const workers = 10
+	const ops = 20
+	var wg sync.WaitGroup
+	wg.Add(workers * 4)
+
+	// Store workers
+	for w := range workers {
+		go func(wIdx int) {
+			defer wg.Done()
+			scope := fmt.Sprintf("scope-%d", wIdx)
+			for i := range ops {
+				p := createTempFile(t, dir, fmt.Sprintf("w%d-f%d.tmp", wIdx, i))
+				store.Store(p, MediaMeta{Source: "test"}, scope)
+			}
+		}(w)
+	}
+
+	// Resolve workers
+	for range workers {
+		go func() {
+			defer wg.Done()
+			for range ops {
+				store.Resolve("media://nonexistent")
+			}
+		}()
+	}
+
+	// ReleaseAll workers
+	for w := range workers {
+		go func(wIdx int) {
+			defer wg.Done()
+			for range ops {
+				store.ReleaseAll(fmt.Sprintf("scope-%d", wIdx))
+			}
+		}(w)
+	}
+
+	// CleanExpired workers
+	for range workers {
+		go func() {
+			defer wg.Done()
+			for range ops {
+				store.CleanExpired()
+			}
+		}()
+	}
+
+	wg.Wait()
+}
+
+func TestRefToScopeConsistency(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	// Store entries in two scopes
+	ref1, _ := store.Store(createTempFile(t, dir, "a.jpg"), MediaMeta{Source: "test"}, "s1")
+	ref2, _ := store.Store(createTempFile(t, dir, "b.jpg"), MediaMeta{Source: "test"}, "s1")
+	ref3, _ := store.Store(createTempFile(t, dir, "c.jpg"), MediaMeta{Source: "test"}, "s2")
+
+	store.mu.RLock()
+	checkRef := func(ref, expectedScope string) {
+		t.Helper()
+		if scope, ok := store.refToScope[ref]; !ok || scope != expectedScope {
+			t.Errorf("refToScope[%s] = %q, want %q", ref, scope, expectedScope)
+		}
+	}
+	checkRef(ref1, "s1")
+	checkRef(ref2, "s1")
+	checkRef(ref3, "s2")
+	store.mu.RUnlock()
+
+	// Release s1 and verify refToScope is cleaned
+	store.ReleaseAll("s1")
+
+	store.mu.RLock()
+	defer store.mu.RUnlock()
+	if _, ok := store.refToScope[ref1]; ok {
+		t.Error("refToScope should not contain ref1 after ReleaseAll")
+	}
+	if _, ok := store.refToScope[ref2]; ok {
+		t.Error("refToScope should not contain ref2 after ReleaseAll")
+	}
+	if _, ok := store.refToScope[ref3]; !ok {
+		t.Error("refToScope should still contain ref3")
+	}
+}
diff --git a/pkg/memory/jsonl.go b/pkg/memory/jsonl.go
new file mode 100644
index 000000000..e12e2c5ab
--- /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.
+//
+// Note: this is a lossy mapping — "telegram:123" and "telegram_123"
+// both produce the same filename. This is an intentional tradeoff:
+// keys with colons (e.g. from channels) are by far the common case,
+// and a bidirectional encoding (like URL-encoding) would complicate
+// file listings and debugging.
+func sanitizeKey(key string) string {
+	return strings.ReplaceAll(key, ":", "_")
+}
+
+// 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..c9d5176ab
--- /dev/null
+++ b/pkg/memory/migration.go
@@ -0,0 +1,108 @@
+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 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..3170758b7
--- /dev/null
+++ b/pkg/memory/migration_test.go
@@ -0,0 +1,384 @@
+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)
+	}
+}
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/config.go b/pkg/migrate/config.go
deleted file mode 100644
index 24ce33e94..000000000
--- a/pkg/migrate/config.go
+++ /dev/null
@@ -1,405 +0,0 @@
-package migrate
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
-	"unicode"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-var supportedProviders = map[string]bool{
-	"anthropic":      true,
-	"openai":         true,
-	"openrouter":     true,
-	"groq":           true,
-	"zhipu":          true,
-	"vllm":           true,
-	"gemini":         true,
-	"qwen":           true,
-	"deepseek":       true,
-	"github_copilot": true,
-	"mistral":        true,
-}
-
-var supportedChannels = map[string]bool{
-	"telegram": true,
-	"discord":  true,
-	"whatsapp": true,
-	"feishu":   true,
-	"qq":       true,
-	"dingtalk": true,
-	"maixcam":  true,
-}
-
-func findOpenClawConfig(openclawHome string) (string, error) {
-	candidates := []string{
-		filepath.Join(openclawHome, "openclaw.json"),
-		filepath.Join(openclawHome, "config.json"),
-	}
-	for _, p := range candidates {
-		if _, err := os.Stat(p); err == nil {
-			return p, nil
-		}
-	}
-	return "", fmt.Errorf("no config file found in %s (tried openclaw.json, config.json)", openclawHome)
-}
-
-func LoadOpenClawConfig(configPath string) (map[string]any, error) {
-	data, err := os.ReadFile(configPath)
-	if err != nil {
-		return nil, fmt.Errorf("reading OpenClaw config: %w", err)
-	}
-
-	var raw map[string]any
-	if err := json.Unmarshal(data, &raw); err != nil {
-		return nil, fmt.Errorf("parsing OpenClaw config: %w", err)
-	}
-
-	converted := convertKeysToSnake(raw)
-	result, ok := converted.(map[string]any)
-	if !ok {
-		return nil, fmt.Errorf("unexpected config format")
-	}
-	return result, nil
-}
-
-func ConvertConfig(data map[string]any) (*config.Config, []string, error) {
-	cfg := config.DefaultConfig()
-	var warnings []string
-
-	if agents, ok := getMap(data, "agents"); ok {
-		if defaults, ok := getMap(agents, "defaults"); ok {
-			if v, ok := getString(defaults, "model"); ok {
-				cfg.Agents.Defaults.Model = v
-			}
-			if v, ok := getFloat(defaults, "max_tokens"); ok {
-				cfg.Agents.Defaults.MaxTokens = int(v)
-			}
-			if v, ok := getFloat(defaults, "temperature"); ok {
-				cfg.Agents.Defaults.Temperature = &v
-			}
-			if v, ok := getFloat(defaults, "max_tool_iterations"); ok {
-				cfg.Agents.Defaults.MaxToolIterations = int(v)
-			}
-			if v, ok := getString(defaults, "workspace"); ok {
-				cfg.Agents.Defaults.Workspace = rewriteWorkspacePath(v)
-			}
-		}
-	}
-
-	if providers, ok := getMap(data, "providers"); ok {
-		for name, val := range providers {
-			pMap, ok := val.(map[string]any)
-			if !ok {
-				continue
-			}
-			apiKey, _ := getString(pMap, "api_key")
-			apiBase, _ := getString(pMap, "api_base")
-
-			if !supportedProviders[name] {
-				if apiKey != "" || apiBase != "" {
-					warnings = append(warnings, fmt.Sprintf("Provider '%s' not supported in PicoClaw, skipping", name))
-				}
-				continue
-			}
-
-			pc := config.ProviderConfig{APIKey: apiKey, APIBase: apiBase}
-			switch name {
-			case "anthropic":
-				cfg.Providers.Anthropic = pc
-			case "openai":
-				cfg.Providers.OpenAI = config.OpenAIProviderConfig{
-					ProviderConfig: pc,
-					WebSearch:      getBoolOrDefault(pMap, "web_search", true),
-				}
-			case "openrouter":
-				cfg.Providers.OpenRouter = pc
-			case "groq":
-				cfg.Providers.Groq = pc
-			case "zhipu":
-				cfg.Providers.Zhipu = pc
-			case "vllm":
-				cfg.Providers.VLLM = pc
-			case "gemini":
-				cfg.Providers.Gemini = pc
-			}
-		}
-	}
-
-	if channels, ok := getMap(data, "channels"); ok {
-		for name, val := range channels {
-			cMap, ok := val.(map[string]any)
-			if !ok {
-				continue
-			}
-			if !supportedChannels[name] {
-				warnings = append(warnings, fmt.Sprintf("Channel '%s' not supported in PicoClaw, skipping", name))
-				continue
-			}
-			enabled, _ := getBool(cMap, "enabled")
-			allowFrom := getStringSlice(cMap, "allow_from")
-
-			switch name {
-			case "telegram":
-				cfg.Channels.Telegram.Enabled = enabled
-				cfg.Channels.Telegram.AllowFrom = allowFrom
-				if v, ok := getString(cMap, "token"); ok {
-					cfg.Channels.Telegram.Token = v
-				}
-			case "discord":
-				cfg.Channels.Discord.Enabled = enabled
-				cfg.Channels.Discord.AllowFrom = allowFrom
-				if v, ok := getString(cMap, "token"); ok {
-					cfg.Channels.Discord.Token = v
-				}
-			case "whatsapp":
-				cfg.Channels.WhatsApp.Enabled = enabled
-				cfg.Channels.WhatsApp.AllowFrom = allowFrom
-				if v, ok := getString(cMap, "bridge_url"); ok {
-					cfg.Channels.WhatsApp.BridgeURL = v
-				}
-			case "feishu":
-				cfg.Channels.Feishu.Enabled = enabled
-				cfg.Channels.Feishu.AllowFrom = allowFrom
-				if v, ok := getString(cMap, "app_id"); ok {
-					cfg.Channels.Feishu.AppID = v
-				}
-				if v, ok := getString(cMap, "app_secret"); ok {
-					cfg.Channels.Feishu.AppSecret = v
-				}
-				if v, ok := getString(cMap, "encrypt_key"); ok {
-					cfg.Channels.Feishu.EncryptKey = v
-				}
-				if v, ok := getString(cMap, "verification_token"); ok {
-					cfg.Channels.Feishu.VerificationToken = v
-				}
-			case "qq":
-				cfg.Channels.QQ.Enabled = enabled
-				cfg.Channels.QQ.AllowFrom = allowFrom
-				if v, ok := getString(cMap, "app_id"); ok {
-					cfg.Channels.QQ.AppID = v
-				}
-				if v, ok := getString(cMap, "app_secret"); ok {
-					cfg.Channels.QQ.AppSecret = v
-				}
-			case "dingtalk":
-				cfg.Channels.DingTalk.Enabled = enabled
-				cfg.Channels.DingTalk.AllowFrom = allowFrom
-				if v, ok := getString(cMap, "client_id"); ok {
-					cfg.Channels.DingTalk.ClientID = v
-				}
-				if v, ok := getString(cMap, "client_secret"); ok {
-					cfg.Channels.DingTalk.ClientSecret = v
-				}
-			case "maixcam":
-				cfg.Channels.MaixCam.Enabled = enabled
-				cfg.Channels.MaixCam.AllowFrom = allowFrom
-				if v, ok := getString(cMap, "host"); ok {
-					cfg.Channels.MaixCam.Host = v
-				}
-				if v, ok := getFloat(cMap, "port"); ok {
-					cfg.Channels.MaixCam.Port = int(v)
-				}
-			}
-		}
-	}
-
-	if gateway, ok := getMap(data, "gateway"); ok {
-		if v, ok := getString(gateway, "host"); ok {
-			cfg.Gateway.Host = v
-		}
-		if v, ok := getFloat(gateway, "port"); ok {
-			cfg.Gateway.Port = int(v)
-		}
-	}
-
-	if tools, ok := getMap(data, "tools"); ok {
-		if web, ok := getMap(tools, "web"); ok {
-			// Migrate old "search" config to "brave" if api_key is present
-			if search, ok := getMap(web, "search"); ok {
-				if v, ok := getString(search, "api_key"); ok {
-					cfg.Tools.Web.Brave.APIKey = v
-					if v != "" {
-						cfg.Tools.Web.Brave.Enabled = true
-					}
-				}
-				if v, ok := getFloat(search, "max_results"); ok {
-					cfg.Tools.Web.Brave.MaxResults = int(v)
-					cfg.Tools.Web.DuckDuckGo.MaxResults = int(v)
-				}
-			}
-		}
-	}
-
-	return cfg, warnings, nil
-}
-
-func MergeConfig(existing, incoming *config.Config) *config.Config {
-	if existing.Providers.Anthropic.APIKey == "" {
-		existing.Providers.Anthropic = incoming.Providers.Anthropic
-	}
-	if existing.Providers.OpenAI.APIKey == "" {
-		existing.Providers.OpenAI = incoming.Providers.OpenAI
-	}
-	if existing.Providers.OpenRouter.APIKey == "" {
-		existing.Providers.OpenRouter = incoming.Providers.OpenRouter
-	}
-	if existing.Providers.Groq.APIKey == "" {
-		existing.Providers.Groq = incoming.Providers.Groq
-	}
-	if existing.Providers.Zhipu.APIKey == "" {
-		existing.Providers.Zhipu = incoming.Providers.Zhipu
-	}
-	if existing.Providers.VLLM.APIKey == "" && existing.Providers.VLLM.APIBase == "" {
-		existing.Providers.VLLM = incoming.Providers.VLLM
-	}
-	if existing.Providers.Gemini.APIKey == "" {
-		existing.Providers.Gemini = incoming.Providers.Gemini
-	}
-	if existing.Providers.DeepSeek.APIKey == "" {
-		existing.Providers.DeepSeek = incoming.Providers.DeepSeek
-	}
-	if existing.Providers.GitHubCopilot.APIBase == "" {
-		existing.Providers.GitHubCopilot = incoming.Providers.GitHubCopilot
-	}
-	if existing.Providers.Qwen.APIKey == "" {
-		existing.Providers.Qwen = incoming.Providers.Qwen
-	}
-
-	if !existing.Channels.Telegram.Enabled && incoming.Channels.Telegram.Enabled {
-		existing.Channels.Telegram = incoming.Channels.Telegram
-	}
-	if !existing.Channels.Discord.Enabled && incoming.Channels.Discord.Enabled {
-		existing.Channels.Discord = incoming.Channels.Discord
-	}
-	if !existing.Channels.WhatsApp.Enabled && incoming.Channels.WhatsApp.Enabled {
-		existing.Channels.WhatsApp = incoming.Channels.WhatsApp
-	}
-	if !existing.Channels.Feishu.Enabled && incoming.Channels.Feishu.Enabled {
-		existing.Channels.Feishu = incoming.Channels.Feishu
-	}
-	if !existing.Channels.QQ.Enabled && incoming.Channels.QQ.Enabled {
-		existing.Channels.QQ = incoming.Channels.QQ
-	}
-	if !existing.Channels.DingTalk.Enabled && incoming.Channels.DingTalk.Enabled {
-		existing.Channels.DingTalk = incoming.Channels.DingTalk
-	}
-	if !existing.Channels.MaixCam.Enabled && incoming.Channels.MaixCam.Enabled {
-		existing.Channels.MaixCam = incoming.Channels.MaixCam
-	}
-
-	if existing.Tools.Web.Brave.APIKey == "" {
-		existing.Tools.Web.Brave = incoming.Tools.Web.Brave
-	}
-
-	return existing
-}
-
-func camelToSnake(s string) string {
-	var result strings.Builder
-	for i, r := range s {
-		if unicode.IsUpper(r) {
-			if i > 0 {
-				prev := rune(s[i-1])
-				if unicode.IsLower(prev) || unicode.IsDigit(prev) {
-					result.WriteRune('_')
-				} else if unicode.IsUpper(prev) && i+1 < len(s) && unicode.IsLower(rune(s[i+1])) {
-					result.WriteRune('_')
-				}
-			}
-			result.WriteRune(unicode.ToLower(r))
-		} else {
-			result.WriteRune(r)
-		}
-	}
-	return result.String()
-}
-
-func convertKeysToSnake(data any) any {
-	switch v := data.(type) {
-	case map[string]any:
-		result := make(map[string]any, len(v))
-		for key, val := range v {
-			result[camelToSnake(key)] = convertKeysToSnake(val)
-		}
-		return result
-	case []any:
-		result := make([]any, len(v))
-		for i, val := range v {
-			result[i] = convertKeysToSnake(val)
-		}
-		return result
-	default:
-		return data
-	}
-}
-
-func rewriteWorkspacePath(path string) string {
-	path = strings.Replace(path, ".openclaw", ".picoclaw", 1)
-	return path
-}
-
-func getMap(data map[string]any, key string) (map[string]any, bool) {
-	v, ok := data[key]
-	if !ok {
-		return nil, false
-	}
-	m, ok := v.(map[string]any)
-	return m, ok
-}
-
-func getString(data map[string]any, key string) (string, bool) {
-	v, ok := data[key]
-	if !ok {
-		return "", false
-	}
-	s, ok := v.(string)
-	return s, ok
-}
-
-func getFloat(data map[string]any, key string) (float64, bool) {
-	v, ok := data[key]
-	if !ok {
-		return 0, false
-	}
-	f, ok := v.(float64)
-	return f, ok
-}
-
-func getBool(data map[string]any, key string) (bool, bool) {
-	v, ok := data[key]
-	if !ok {
-		return false, false
-	}
-	b, ok := v.(bool)
-	return b, ok
-}
-
-func getBoolOrDefault(data map[string]any, key string, defaultVal bool) bool {
-	if v, ok := getBool(data, key); ok {
-		return v
-	}
-	return defaultVal
-}
-
-func getStringSlice(data map[string]any, key string) []string {
-	v, ok := data[key]
-	if !ok {
-		return []string{}
-	}
-	arr, ok := v.([]any)
-	if !ok {
-		return []string{}
-	}
-	result := make([]string, 0, len(arr))
-	for _, item := range arr {
-		if s, ok := item.(string); ok {
-			result = append(result, s)
-		}
-	}
-	return result
-}
diff --git a/pkg/migrate/workspace.go b/pkg/migrate/internal/common.go
similarity index 55%
rename from pkg/migrate/workspace.go
rename to pkg/migrate/internal/common.go
index f45748fac..c77ab9f26 100644
--- a/pkg/migrate/workspace.go
+++ b/pkg/migrate/internal/common.go
@@ -1,24 +1,50 @@
-package migrate
+package internal
 
 import (
+	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 )
 
-var migrateableFiles = []string{
-	"AGENTS.md",
-	"SOUL.md",
-	"USER.md",
-	"TOOLS.md",
-	"HEARTBEAT.md",
+func ResolveTargetHome(override string) (string, error) {
+	if override != "" {
+		return ExpandHome(override), nil
+	}
+	if envHome := os.Getenv("PICOCLAW_HOME"); 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
 }
 
-var migrateableDirs = []string{
-	"memory",
-	"skills",
+func ExpandHome(path string) string {
+	if path == "" {
+		return path
+	}
+	if path[0] == '~' {
+		home, _ := os.UserHomeDir()
+		if len(path) > 1 && path[1] == '/' {
+			return home + path[1:]
+		}
+		return home
+	}
+	return path
 }
 
-func PlanWorkspaceMigration(srcWorkspace, dstWorkspace string, force bool) ([]Action, error) {
+func ResolveWorkspace(homeDir string) string {
+	return filepath.Join(homeDir, "workspace")
+}
+
+func PlanWorkspaceMigration(
+	srcWorkspace, dstWorkspace string,
+	migrateableFiles []string,
+	migrateableDirs []string,
+	force bool,
+) ([]Action, error) {
 	var actions []Action
 
 	for _, filename := range migrateableFiles {
@@ -50,7 +76,7 @@ func planFileCopy(src, dst string, force bool) Action {
 		return Action{
 			Type:        ActionSkip,
 			Source:      src,
-			Destination: dst,
+			Target:      dst,
 			Description: "source file not found",
 		}
 	}
@@ -60,7 +86,7 @@ func planFileCopy(src, dst string, force bool) Action {
 		return Action{
 			Type:        ActionBackup,
 			Source:      src,
-			Destination: dst,
+			Target:      dst,
 			Description: "destination exists, will backup and overwrite",
 		}
 	}
@@ -68,7 +94,7 @@ func planFileCopy(src, dst string, force bool) Action {
 	return Action{
 		Type:        ActionCopy,
 		Source:      src,
-		Destination: dst,
+		Target:      dst,
 		Description: "copy file",
 	}
 }
@@ -91,7 +117,7 @@ func planDirCopy(srcDir, dstDir string, force bool) ([]Action, error) {
 		if info.IsDir() {
 			actions = append(actions, Action{
 				Type:        ActionCreateDir,
-				Destination: dst,
+				Target:      dst,
 				Description: "create directory",
 			})
 			return nil
@@ -104,3 +130,33 @@ func planDirCopy(srcDir, dstDir string, force bool) ([]Action, error) {
 
 	return actions, err
 }
+
+func RelPath(path, base string) string {
+	rel, err := filepath.Rel(base, path)
+	if err != nil {
+		return filepath.Base(path)
+	}
+	return rel
+}
+
+func CopyFile(src, dst string) error {
+	srcFile, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer srcFile.Close()
+
+	info, err := srcFile.Stat()
+	if err != nil {
+		return err
+	}
+
+	dstFile, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
+	if err != nil {
+		return err
+	}
+	defer dstFile.Close()
+
+	_, err = io.Copy(dstFile, srcFile)
+	return err
+}
diff --git a/pkg/migrate/internal/common_test.go b/pkg/migrate/internal/common_test.go
new file mode 100644
index 000000000..a67293c19
--- /dev/null
+++ b/pkg/migrate/internal/common_test.go
@@ -0,0 +1,186 @@
+package internal
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestExpandHome(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected string
+	}{
+		{"", ""},
+		{"/absolute/path", "/absolute/path"},
+		{"relative/path", "relative/path"},
+	}
+
+	for _, tt := range tests {
+		result := ExpandHome(tt.input)
+		assert.Equal(t, tt.expected, result)
+	}
+}
+
+func TestExpandHomeWithTilde(t *testing.T) {
+	home, err := os.UserHomeDir()
+	require.NoError(t, err)
+
+	result := ExpandHome("~/path")
+	assert.Equal(t, home+"/path", result)
+
+	result = ExpandHome("~")
+	assert.Equal(t, home, result)
+}
+
+func TestResolveWorkspace(t *testing.T) {
+	result := ResolveWorkspace("/home/user/.picoclaw")
+	assert.Equal(t, "/home/user/.picoclaw/workspace", result)
+}
+
+func TestRelPath(t *testing.T) {
+	result := RelPath("/home/user/.picoclaw/workspace/file.txt", "/home/user/.picoclaw")
+	assert.Equal(t, "workspace/file.txt", result)
+}
+
+func TestRelPathError(t *testing.T) {
+	result := RelPath("relative/path", "/different/base")
+	assert.Equal(t, "path", result)
+}
+
+func TestResolveTargetHome(t *testing.T) {
+	home, err := os.UserHomeDir()
+	require.NoError(t, err)
+
+	result, err := ResolveTargetHome("")
+	require.NoError(t, err)
+	assert.Equal(t, filepath.Join(home, ".picoclaw"), result)
+}
+
+func TestResolveTargetHomeWithOverride(t *testing.T) {
+	result, err := ResolveTargetHome("/custom/path")
+	require.NoError(t, err)
+	assert.Equal(t, "/custom/path", result)
+}
+
+func TestCopyFile(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	sourceFile := filepath.Join(tmpDir, "source.txt")
+	err := os.WriteFile(sourceFile, []byte("test content"), 0o644)
+	require.NoError(t, err)
+
+	dstFile := filepath.Join(tmpDir, "dest.txt")
+	err = CopyFile(sourceFile, dstFile)
+	require.NoError(t, err)
+
+	content, err := os.ReadFile(dstFile)
+	require.NoError(t, err)
+	assert.Equal(t, "test content", string(content))
+}
+
+func TestCopyFileSourceNotFound(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	err := CopyFile(filepath.Join(tmpDir, "nonexistent.txt"), filepath.Join(tmpDir, "dest.txt"))
+	require.Error(t, err)
+}
+
+func TestPlanWorkspaceMigration(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.WriteFile(filepath.Join(srcWorkspace, "file1.txt"), []byte("content"), 0o644)
+	require.NoError(t, err)
+
+	err = os.MkdirAll(filepath.Join(srcWorkspace, "subdir"), 0o755)
+	require.NoError(t, err)
+
+	err = os.WriteFile(filepath.Join(srcWorkspace, "subdir", "file2.txt"), []byte("content"), 0o644)
+	require.NoError(t, err)
+
+	actions, err := PlanWorkspaceMigration(
+		srcWorkspace,
+		dstWorkspace,
+		[]string{"file1.txt"},
+		[]string{"subdir"},
+		false,
+	)
+	require.NoError(t, err)
+
+	assert.GreaterOrEqual(t, len(actions), 1)
+}
+
+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,
+		},
+	}
+
+	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(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{},
+				tt.force,
+			)
+			require.NoError(t, err)
+
+			require.GreaterOrEqual(t, len(actions), 1)
+			assert.Equal(t, tt.wantActionType, actions[0].Type)
+		})
+	}
+}
+
+func TestPlanWorkspaceMigrationNonExistentSource(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	actions, err := PlanWorkspaceMigration(
+		filepath.Join(tmpDir, "nonexistent"),
+		filepath.Join(tmpDir, "dst", "workspace"),
+		[]string{"file1.txt"},
+		[]string{},
+		false,
+	)
+	require.NoError(t, err)
+	require.Len(t, actions, 1)
+	assert.Equal(t, ActionSkip, actions[0].Type)
+	assert.Contains(t, actions[0].Description, "source file not found")
+}
diff --git a/pkg/migrate/internal/types.go b/pkg/migrate/internal/types.go
new file mode 100644
index 000000000..e86a4dea1
--- /dev/null
+++ b/pkg/migrate/internal/types.go
@@ -0,0 +1,52 @@
+package internal
+
+type Options struct {
+	DryRun        bool
+	ConfigOnly    bool
+	WorkspaceOnly bool
+	Force         bool
+	Refresh       bool
+	Source        string
+	SourceHome    string
+	TargetHome    string
+}
+
+type Operation interface {
+	GetSourceName() string
+	GetSourceHome() (string, error)
+	GetSourceWorkspace() (string, error)
+	GetSourceConfigFile() (string, error)
+	ExecuteConfigMigration(srcConfigPath, dstConfigPath string) error
+	GetMigrateableFiles() []string
+	GetMigrateableDirs() []string
+}
+
+type HandlerFactory func(opts Options) Operation
+
+type ActionType int
+
+const (
+	ActionCopy ActionType = iota
+	ActionSkip
+	ActionBackup
+	ActionConvertConfig
+	ActionCreateDir
+	ActionMergeConfig
+)
+
+type Action struct {
+	Type        ActionType
+	Source      string
+	Target      string
+	Description string
+}
+
+type Result struct {
+	FilesCopied    int
+	FilesSkipped   int
+	BackupsCreated int
+	ConfigMigrated bool
+	DirsCreated    int
+	Warnings       []string
+	Errors         []error
+}
diff --git a/pkg/migrate/migrate.go b/pkg/migrate/migrate.go
index cfa82b7d7..51fecf438 100644
--- a/pkg/migrate/migrate.go
+++ b/pkg/migrate/migrate.go
@@ -2,53 +2,73 @@ package migrate
 
 import (
 	"fmt"
-	"io"
 	"os"
 	"path/filepath"
 	"strings"
 
-	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/migrate/internal"
+	"github.com/sipeed/picoclaw/pkg/migrate/sources/openclaw"
 )
 
-type ActionType int
+type (
+	Options        = internal.Options
+	Operation      = internal.Operation
+	ActionType     = internal.ActionType
+	Action         = internal.Action
+	Result         = internal.Result
+	HandlerFactory = internal.HandlerFactory
+)
 
 const (
-	ActionCopy ActionType = iota
-	ActionSkip
-	ActionBackup
-	ActionConvertConfig
-	ActionCreateDir
-	ActionMergeConfig
+	ActionCopy          = internal.ActionCopy
+	ActionSkip          = internal.ActionSkip
+	ActionBackup        = internal.ActionBackup
+	ActionConvertConfig = internal.ActionConvertConfig
+	ActionCreateDir     = internal.ActionCreateDir
+	ActionMergeConfig   = internal.ActionMergeConfig
 )
 
-type Options struct {
-	DryRun        bool
-	ConfigOnly    bool
-	WorkspaceOnly bool
-	Force         bool
-	Refresh       bool
-	OpenClawHome  string
-	PicoClawHome  string
+type MigrateInstance struct {
+	options  Options
+	handlers map[string]Operation
 }
 
-type Action struct {
-	Type        ActionType
-	Source      string
-	Destination string
-	Description string
+func NewMigrateInstance(opts Options) *MigrateInstance {
+	instance := &MigrateInstance{
+		options:  opts,
+		handlers: make(map[string]Operation),
+	}
+
+	openclaw_handler, err := openclaw.NewOpenclawHandler(opts)
+	if err == nil {
+		instance.Register(openclaw_handler.GetSourceName(), openclaw_handler)
+	}
+
+	return instance
 }
 
-type Result struct {
-	FilesCopied    int
-	FilesSkipped   int
-	BackupsCreated int
-	ConfigMigrated bool
-	DirsCreated    int
-	Warnings       []string
-	Errors         []error
+func (m *MigrateInstance) Register(moduleName string, module Operation) {
+	m.handlers[moduleName] = module
 }
 
-func Run(opts Options) (*Result, error) {
+func (m *MigrateInstance) getCurrentHandler() (Operation, error) {
+	source := m.options.Source
+	if source == "" {
+		source = "openclaw"
+	}
+	handler, ok := m.handlers[source]
+	if !ok {
+		return nil, fmt.Errorf("Source '%s' not found", source)
+	}
+	return handler, nil
+}
+
+func (m *MigrateInstance) Run(opts Options) (*Result, error) {
+	handler, err := m.getCurrentHandler()
+	if err != nil {
+		return nil, err
+	}
+
 	if opts.ConfigOnly && opts.WorkspaceOnly {
 		return nil, fmt.Errorf("--config-only and --workspace-only are mutually exclusive")
 	}
@@ -57,28 +77,28 @@ func Run(opts Options) (*Result, error) {
 		opts.WorkspaceOnly = true
 	}
 
-	openclawHome, err := resolveOpenClawHome(opts.OpenClawHome)
+	sourceHome, err := handler.GetSourceHome()
 	if err != nil {
 		return nil, err
 	}
 
-	picoClawHome, err := resolvePicoClawHome(opts.PicoClawHome)
+	targetHome, err := internal.ResolveTargetHome(opts.TargetHome)
 	if err != nil {
 		return nil, err
 	}
 
-	if _, err = os.Stat(openclawHome); os.IsNotExist(err) {
-		return nil, fmt.Errorf("OpenClaw installation not found at %s", openclawHome)
+	if _, err = os.Stat(sourceHome); os.IsNotExist(err) {
+		return nil, fmt.Errorf("Source installation not found at %s", sourceHome)
 	}
 
-	actions, warnings, err := Plan(opts, openclawHome, picoClawHome)
+	actions, warnings, err := m.Plan(opts, sourceHome, targetHome)
 	if err != nil {
 		return nil, err
 	}
 
-	fmt.Println("Migrating from OpenClaw to PicoClaw")
-	fmt.Printf("  Source:      %s\n", openclawHome)
-	fmt.Printf("  Destination: %s\n", picoClawHome)
+	fmt.Println("Migrating from Source to PicoClaw")
+	fmt.Printf("  Source:      %s\n", sourceHome)
+	fmt.Printf("  Target: %s\n", targetHome)
 	fmt.Println()
 
 	if opts.DryRun {
@@ -95,19 +115,23 @@ func Run(opts Options) (*Result, error) {
 		fmt.Println()
 	}
 
-	result := Execute(actions, openclawHome, picoClawHome)
+	result := m.Execute(actions, sourceHome, targetHome)
 	result.Warnings = warnings
 	return result, nil
 }
 
-func Plan(opts Options, openclawHome, picoClawHome string) ([]Action, []string, error) {
+func (m *MigrateInstance) Plan(opts Options, sourceHome, targetHome string) ([]Action, []string, error) {
 	var actions []Action
 	var warnings []string
+	handler, err := m.getCurrentHandler()
+	if err != nil {
+		return nil, nil, err
+	}
 
 	force := opts.Force || opts.Refresh
 
 	if !opts.WorkspaceOnly {
-		configPath, err := findOpenClawConfig(openclawHome)
+		configPath, err := handler.GetSourceConfigFile()
 		if err != nil {
 			if opts.ConfigOnly {
 				return nil, nil, err
@@ -117,91 +141,95 @@ func Plan(opts Options, openclawHome, picoClawHome string) ([]Action, []string,
 			actions = append(actions, Action{
 				Type:        ActionConvertConfig,
 				Source:      configPath,
-				Destination: filepath.Join(picoClawHome, "config.json"),
-				Description: "convert OpenClaw config to PicoClaw format",
+				Target:      filepath.Join(targetHome, "config.json"),
+				Description: "convert Source config to PicoClaw format",
 			})
-
-			data, err := LoadOpenClawConfig(configPath)
-			if err == nil {
-				_, configWarnings, _ := ConvertConfig(data)
-				warnings = append(warnings, configWarnings...)
-			}
 		}
 	}
 
 	if !opts.ConfigOnly {
-		srcWorkspace := resolveWorkspace(openclawHome)
-		dstWorkspace := resolveWorkspace(picoClawHome)
+		srcWorkspace, err := handler.GetSourceWorkspace()
+		if err != nil {
+			return nil, nil, fmt.Errorf("getting source workspace: %w", err)
+		}
+		dstWorkspace := internal.ResolveWorkspace(targetHome)
 
 		if _, err := os.Stat(srcWorkspace); err == nil {
-			wsActions, err := PlanWorkspaceMigration(srcWorkspace, dstWorkspace, force)
+			wsActions, err := internal.PlanWorkspaceMigration(srcWorkspace, dstWorkspace,
+				handler.GetMigrateableFiles(),
+				handler.GetMigrateableDirs(),
+				force)
 			if err != nil {
 				return nil, nil, fmt.Errorf("planning workspace migration: %w", err)
 			}
 			actions = append(actions, wsActions...)
 		} else {
-			warnings = append(warnings, "OpenClaw workspace directory not found, skipping workspace migration")
+			warnings = append(warnings, "Source workspace directory not found, skipping workspace migration")
 		}
 	}
 
 	return actions, warnings, nil
 }
 
-func Execute(actions []Action, openclawHome, picoClawHome string) *Result {
+func (m *MigrateInstance) Execute(actions []Action, sourceHome, targetHome string) *Result {
 	result := &Result{}
+	handler, err := m.getCurrentHandler()
+	if err != nil {
+		return result
+	}
 
 	for _, action := range actions {
 		switch action.Type {
 		case ActionConvertConfig:
-			if err := executeConfigMigration(action.Source, action.Destination, picoClawHome); err != nil {
+			if err := handler.ExecuteConfigMigration(action.Source, action.Target); err != nil {
 				result.Errors = append(result.Errors, fmt.Errorf("config migration: %w", err))
 				fmt.Printf("  ✗ Config migration failed: %v\n", err)
 			} else {
 				result.ConfigMigrated = true
-				fmt.Printf("  ✓ Converted config: %s\n", action.Destination)
+				fmt.Printf("  ✓ Converted config: %s\n", action.Target)
 			}
 		case ActionCreateDir:
-			if err := os.MkdirAll(action.Destination, 0o755); err != nil {
+			if err := os.MkdirAll(action.Target, 0o755); err != nil {
 				result.Errors = append(result.Errors, err)
 			} else {
 				result.DirsCreated++
 			}
 		case ActionBackup:
-			bakPath := action.Destination + ".bak"
-			if err := copyFile(action.Destination, bakPath); err != nil {
-				result.Errors = append(result.Errors, fmt.Errorf("backup %s: %w", action.Destination, err))
-				fmt.Printf("  ✗ Backup failed: %s\n", action.Destination)
+			bakPath := action.Target + ".bak"
+			if err := internal.CopyFile(action.Target, bakPath); err != nil {
+				result.Errors = append(result.Errors, fmt.Errorf("backup %s: %w", action.Target, err))
+				fmt.Printf("  ✗ Backup failed: %s\n", action.Target)
 				continue
 			}
 			result.BackupsCreated++
 			fmt.Printf(
 				"  ✓ Backed up %s -> %s.bak\n",
-				filepath.Base(action.Destination),
-				filepath.Base(action.Destination),
+				filepath.Base(action.Target),
+				filepath.Base(action.Target),
 			)
 
-			if err := os.MkdirAll(filepath.Dir(action.Destination), 0o755); err != nil {
+			if err := os.MkdirAll(filepath.Dir(action.Target), 0o755); err != nil {
 				result.Errors = append(result.Errors, err)
 				continue
 			}
-			if err := copyFile(action.Source, action.Destination); err != nil {
+			if err := internal.CopyFile(action.Source, action.Target); err != nil {
 				result.Errors = append(result.Errors, fmt.Errorf("copy %s: %w", action.Source, err))
 				fmt.Printf("  ✗ Copy failed: %s\n", action.Source)
 			} else {
 				result.FilesCopied++
-				fmt.Printf("  ✓ Copied %s\n", relPath(action.Source, openclawHome))
+				fmt.Printf("  ✓ Copied %s\n", internal.RelPath(action.Source, sourceHome))
 			}
 		case ActionCopy:
-			if err := os.MkdirAll(filepath.Dir(action.Destination), 0o755); err != nil {
+			if err := os.MkdirAll(filepath.Dir(action.Target), 0o755); err != nil {
 				result.Errors = append(result.Errors, err)
 				continue
 			}
-			if err := copyFile(action.Source, action.Destination); err != nil {
+			if err := internal.CopyFile(action.Source, action.Target); err != nil {
 				result.Errors = append(result.Errors, fmt.Errorf("copy %s: %w", action.Source, err))
 				fmt.Printf("  ✗ Copy failed: %s\n", action.Source)
 			} else {
 				result.FilesCopied++
-				fmt.Printf("  ✓ Copied %s\n", relPath(action.Source, openclawHome))
+				fmt.Printf("  ✓ Copied %s\n", internal.RelPath(action.Source, sourceHome))
 			}
 		case ActionSkip:
 			result.FilesSkipped++
@@ -211,31 +239,6 @@ func Execute(actions []Action, openclawHome, picoClawHome string) *Result {
 	return result
 }
 
-func executeConfigMigration(srcConfigPath, dstConfigPath, picoClawHome string) error {
-	data, err := LoadOpenClawConfig(srcConfigPath)
-	if err != nil {
-		return err
-	}
-
-	incoming, _, err := ConvertConfig(data)
-	if err != nil {
-		return err
-	}
-
-	if _, err := os.Stat(dstConfigPath); err == nil {
-		existing, err := config.LoadConfig(dstConfigPath)
-		if err != nil {
-			return fmt.Errorf("loading existing PicoClaw config: %w", err)
-		}
-		incoming = MergeConfig(existing, incoming)
-	}
-
-	if err := os.MkdirAll(filepath.Dir(dstConfigPath), 0o755); err != nil {
-		return err
-	}
-	return config.SaveConfig(dstConfigPath, incoming)
-}
-
 func Confirm() bool {
 	fmt.Print("Proceed with migration? (y/n): ")
 	var response string
@@ -243,49 +246,7 @@ func Confirm() bool {
 	return strings.ToLower(strings.TrimSpace(response)) == "y"
 }
 
-func PrintPlan(actions []Action, warnings []string) {
-	fmt.Println("Planned actions:")
-	copies := 0
-	skips := 0
-	backups := 0
-	configCount := 0
-
-	for _, action := range actions {
-		switch action.Type {
-		case ActionConvertConfig:
-			fmt.Printf("  [config]  %s -> %s\n", action.Source, action.Destination)
-			configCount++
-		case ActionCopy:
-			fmt.Printf("  [copy]    %s\n", filepath.Base(action.Source))
-			copies++
-		case ActionBackup:
-			fmt.Printf("  [backup]  %s (exists, will backup and overwrite)\n", filepath.Base(action.Destination))
-			backups++
-			copies++
-		case ActionSkip:
-			if action.Description != "" {
-				fmt.Printf("  [skip]    %s (%s)\n", filepath.Base(action.Source), action.Description)
-			}
-			skips++
-		case ActionCreateDir:
-			fmt.Printf("  [mkdir]   %s\n", action.Destination)
-		}
-	}
-
-	if len(warnings) > 0 {
-		fmt.Println()
-		fmt.Println("Warnings:")
-		for _, w := range warnings {
-			fmt.Printf("  - %s\n", w)
-		}
-	}
-
-	fmt.Println()
-	fmt.Printf("%d files to copy, %d configs to convert, %d backups needed, %d skipped\n",
-		copies, configCount, backups, skips)
-}
-
-func PrintSummary(result *Result) {
+func (m *MigrateInstance) PrintSummary(result *Result) {
 	fmt.Println()
 	parts := []string{}
 	if result.FilesCopied > 0 {
@@ -316,83 +277,44 @@ func PrintSummary(result *Result) {
 	}
 }
 
-func resolveOpenClawHome(override string) (string, error) {
-	if override != "" {
-		return expandHome(override), nil
-	}
-	if envHome := os.Getenv("OPENCLAW_HOME"); envHome != "" {
-		return expandHome(envHome), nil
-	}
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "", fmt.Errorf("resolving home directory: %w", err)
-	}
-	return filepath.Join(home, ".openclaw"), nil
-}
+func PrintPlan(actions []Action, warnings []string) {
+	fmt.Println("Planned actions:")
+	copies := 0
+	skips := 0
+	backups := 0
+	configCount := 0
 
-func resolvePicoClawHome(override string) (string, error) {
-	if override != "" {
-		return expandHome(override), nil
-	}
-	if envHome := os.Getenv("PICOCLAW_HOME"); 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
-}
-
-func resolveWorkspace(homeDir string) string {
-	return filepath.Join(homeDir, "workspace")
-}
-
-func expandHome(path string) string {
-	if path == "" {
-		return path
-	}
-	if path[0] == '~' {
-		home, _ := os.UserHomeDir()
-		if len(path) > 1 && path[1] == '/' {
-			return home + path[1:]
+	for _, action := range actions {
+		switch action.Type {
+		case ActionConvertConfig:
+			fmt.Printf("  [config]  %s -> %s\n", action.Source, action.Target)
+			configCount++
+		case ActionCopy:
+			fmt.Printf("  [copy]    %s\n", filepath.Base(action.Source))
+			copies++
+		case ActionBackup:
+			fmt.Printf("  [backup]  %s (exists, will backup and overwrite)\n", filepath.Base(action.Target))
+			backups++
+			copies++
+		case ActionSkip:
+			if action.Description != "" {
+				fmt.Printf("  [skip]    %s (%s)\n", filepath.Base(action.Source), action.Description)
+			}
+			skips++
+		case ActionCreateDir:
+			fmt.Printf("  [mkdir]   %s\n", action.Target)
 		}
-		return home
 	}
-	return path
-}
-
-func backupFile(path string) error {
-	bakPath := path + ".bak"
-	return copyFile(path, bakPath)
-}
-
-func copyFile(src, dst string) error {
-	srcFile, err := os.Open(src)
-	if err != nil {
-		return err
-	}
-	defer srcFile.Close()
-
-	info, err := srcFile.Stat()
-	if err != nil {
-		return err
-	}
-
-	dstFile, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
-	if err != nil {
-		return err
-	}
-	defer dstFile.Close()
-
-	_, err = io.Copy(dstFile, srcFile)
-	return err
-}
-
-func relPath(path, base string) string {
-	rel, err := filepath.Rel(base, path)
-	if err != nil {
-		return filepath.Base(path)
-	}
-	return rel
+
+	if len(warnings) > 0 {
+		fmt.Println()
+		fmt.Println("Warnings:")
+		for _, w := range warnings {
+			fmt.Printf("  - %s\n", w)
+		}
+	}
+
+	fmt.Println()
+	fmt.Printf("%d files to copy, %d configs to convert, %d backups needed, %d skipped\n",
+		copies, configCount, backups, skips)
 }
diff --git a/pkg/migrate/migrate_test.go b/pkg/migrate/migrate_test.go
index b6b3d70aa..fc9c2c3a7 100644
--- a/pkg/migrate/migrate_test.go
+++ b/pkg/migrate/migrate_test.go
@@ -1,875 +1,411 @@
 package migrate
 
 import (
-	"encoding/json"
 	"os"
 	"path/filepath"
 	"testing"
 
-	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
-func TestCamelToSnake(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{"simple", "apiKey", "api_key"},
-		{"two words", "apiBase", "api_base"},
-		{"three words", "maxToolIterations", "max_tool_iterations"},
-		{"already snake", "api_key", "api_key"},
-		{"single word", "enabled", "enabled"},
-		{"all lower", "model", "model"},
-		{"consecutive caps", "apiURL", "api_url"},
-		{"starts upper", "Model", "model"},
-		{"bridge url", "bridgeUrl", "bridge_url"},
-		{"client id", "clientId", "client_id"},
-		{"app secret", "appSecret", "app_secret"},
-		{"verification token", "verificationToken", "verification_token"},
-		{"allow from", "allowFrom", "allow_from"},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := camelToSnake(tt.input)
-			if got != tt.want {
-				t.Errorf("camelToSnake(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
+func TestNewMigrateInstance(t *testing.T) {
+	opts := Options{
+		Source: "openclaw",
 	}
+	instance := NewMigrateInstance(opts)
+	require.NotNil(t, instance)
+	assert.Equal(t, "openclaw", instance.options.Source)
 }
 
-func TestConvertKeysToSnake(t *testing.T) {
-	input := map[string]any{
-		"apiKey":  "test-key",
-		"apiBase": "https://example.com",
-		"nested": map[string]any{
-			"maxTokens": float64(8192),
-			"allowFrom": []any{"user1", "user2"},
-			"deeperLevel": map[string]any{
-				"clientId": "abc",
-			},
-		},
-	}
+func TestMigrateInstanceRegister(t *testing.T) {
+	instance := NewMigrateInstance(Options{})
+	require.NotNil(t, instance)
 
-	result := convertKeysToSnake(input)
-	m, ok := result.(map[string]any)
-	if !ok {
-		t.Fatal("expected map[string]interface{}")
-	}
+	mockHandler := &mockOperation{}
+	instance.Register("test-source", mockHandler)
 
-	if _, ok = m["api_key"]; !ok {
-		t.Error("expected key 'api_key' after conversion")
-	}
-	if _, ok = m["api_base"]; !ok {
-		t.Error("expected key 'api_base' after conversion")
-	}
-
-	nested, ok := m["nested"].(map[string]any)
-	if !ok {
-		t.Fatal("expected nested map")
-	}
-	if _, ok = nested["max_tokens"]; !ok {
-		t.Error("expected key 'max_tokens' in nested map")
-	}
-	if _, ok = nested["allow_from"]; !ok {
-		t.Error("expected key 'allow_from' in nested map")
-	}
-
-	deeper, ok := nested["deeper_level"].(map[string]any)
-	if !ok {
-		t.Fatal("expected deeper_level map")
-	}
-	if _, ok := deeper["client_id"]; !ok {
-		t.Error("expected key 'client_id' in deeper level")
-	}
+	handler, ok := instance.handlers["test-source"]
+	require.True(t, ok)
+	assert.Equal(t, mockHandler, handler)
 }
 
-func TestLoadOpenClawConfig(t *testing.T) {
+func TestMigrateInstanceGetCurrentHandler(t *testing.T) {
 	tmpDir := t.TempDir()
 	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
 
-	openclawConfig := map[string]any{
-		"providers": map[string]any{
-			"anthropic": map[string]any{
-				"apiKey":  "sk-ant-test123",
-				"apiBase": "https://api.anthropic.com",
-			},
-		},
-		"agents": map[string]any{
-			"defaults": map[string]any{
-				"maxTokens": float64(4096),
-				"model":     "claude-3-opus",
-			},
-		},
-	}
+	instance := NewMigrateInstance(Options{SourceHome: tmpDir})
+	require.NotNil(t, instance)
 
-	data, err := json.Marshal(openclawConfig)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err = os.WriteFile(configPath, data, 0o644); err != nil {
-		t.Fatal(err)
-	}
-
-	result, err := LoadOpenClawConfig(configPath)
-	if err != nil {
-		t.Fatalf("LoadOpenClawConfig: %v", err)
-	}
-
-	providers, ok := result["providers"].(map[string]any)
-	if !ok {
-		t.Fatal("expected providers map")
-	}
-	anthropic, ok := providers["anthropic"].(map[string]any)
-	if !ok {
-		t.Fatal("expected anthropic map")
-	}
-	if anthropic["api_key"] != "sk-ant-test123" {
-		t.Errorf("api_key = %v, want sk-ant-test123", anthropic["api_key"])
-	}
-
-	agents, ok := result["agents"].(map[string]any)
-	if !ok {
-		t.Fatal("expected agents map")
-	}
-	defaults, ok := agents["defaults"].(map[string]any)
-	if !ok {
-		t.Fatal("expected defaults map")
-	}
-	if defaults["max_tokens"] != float64(4096) {
-		t.Errorf("max_tokens = %v, want 4096", defaults["max_tokens"])
-	}
+	handler, err := instance.getCurrentHandler()
+	require.NoError(t, err)
+	require.NotNil(t, handler)
+	assert.Equal(t, "openclaw", handler.GetSourceName())
 }
 
-func TestConvertConfig(t *testing.T) {
-	t.Run("providers mapping", func(t *testing.T) {
-		data := map[string]any{
-			"providers": map[string]any{
-				"anthropic": map[string]any{
-					"api_key":  "sk-ant-test",
-					"api_base": "https://api.anthropic.com",
-				},
-				"openrouter": map[string]any{
-					"api_key": "sk-or-test",
-				},
-				"groq": map[string]any{
-					"api_key": "gsk-test",
-				},
-			},
-		}
-
-		cfg, warnings, err := ConvertConfig(data)
-		if err != nil {
-			t.Fatalf("ConvertConfig: %v", err)
-		}
-		if len(warnings) != 0 {
-			t.Errorf("expected no warnings, got %v", warnings)
-		}
-		if cfg.Providers.Anthropic.APIKey != "sk-ant-test" {
-			t.Errorf("Anthropic.APIKey = %q, want %q", cfg.Providers.Anthropic.APIKey, "sk-ant-test")
-		}
-		if cfg.Providers.OpenRouter.APIKey != "sk-or-test" {
-			t.Errorf("OpenRouter.APIKey = %q, want %q", cfg.Providers.OpenRouter.APIKey, "sk-or-test")
-		}
-		if cfg.Providers.Groq.APIKey != "gsk-test" {
-			t.Errorf("Groq.APIKey = %q, want %q", cfg.Providers.Groq.APIKey, "gsk-test")
-		}
-	})
-
-	t.Run("unsupported provider warning", func(t *testing.T) {
-		data := map[string]any{
-			"providers": map[string]any{
-				"unknown_provider": map[string]any{
-					"api_key": "sk-test",
-				},
-			},
-		}
-
-		_, warnings, err := ConvertConfig(data)
-		if err != nil {
-			t.Fatalf("ConvertConfig: %v", err)
-		}
-		if len(warnings) != 1 {
-			t.Fatalf("expected 1 warning, got %d", len(warnings))
-		}
-		if warnings[0] != "Provider 'unknown_provider' not supported in PicoClaw, skipping" {
-			t.Errorf("unexpected warning: %s", warnings[0])
-		}
-	})
-
-	t.Run("channels mapping", func(t *testing.T) {
-		data := map[string]any{
-			"channels": map[string]any{
-				"telegram": map[string]any{
-					"enabled":    true,
-					"token":      "tg-token-123",
-					"allow_from": []any{"user1"},
-				},
-				"discord": map[string]any{
-					"enabled": true,
-					"token":   "disc-token-456",
-				},
-			},
-		}
-
-		cfg, _, err := ConvertConfig(data)
-		if err != nil {
-			t.Fatalf("ConvertConfig: %v", err)
-		}
-		if !cfg.Channels.Telegram.Enabled {
-			t.Error("Telegram should be enabled")
-		}
-		if cfg.Channels.Telegram.Token != "tg-token-123" {
-			t.Errorf("Telegram.Token = %q, want %q", cfg.Channels.Telegram.Token, "tg-token-123")
-		}
-		if len(cfg.Channels.Telegram.AllowFrom) != 1 || cfg.Channels.Telegram.AllowFrom[0] != "user1" {
-			t.Errorf("Telegram.AllowFrom = %v, want [user1]", cfg.Channels.Telegram.AllowFrom)
-		}
-		if !cfg.Channels.Discord.Enabled {
-			t.Error("Discord should be enabled")
-		}
-	})
-
-	t.Run("unsupported channel warning", func(t *testing.T) {
-		data := map[string]any{
-			"channels": map[string]any{
-				"email": map[string]any{
-					"enabled": true,
-				},
-			},
-		}
-
-		_, warnings, err := ConvertConfig(data)
-		if err != nil {
-			t.Fatalf("ConvertConfig: %v", err)
-		}
-		if len(warnings) != 1 {
-			t.Fatalf("expected 1 warning, got %d", len(warnings))
-		}
-		if warnings[0] != "Channel 'email' not supported in PicoClaw, skipping" {
-			t.Errorf("unexpected warning: %s", warnings[0])
-		}
-	})
-
-	t.Run("agent defaults", func(t *testing.T) {
-		data := map[string]any{
-			"agents": map[string]any{
-				"defaults": map[string]any{
-					"model":               "claude-3-opus",
-					"max_tokens":          float64(4096),
-					"temperature":         0.5,
-					"max_tool_iterations": float64(10),
-					"workspace":           "~/.openclaw/workspace",
-				},
-			},
-		}
-
-		cfg, _, err := ConvertConfig(data)
-		if err != nil {
-			t.Fatalf("ConvertConfig: %v", err)
-		}
-		if cfg.Agents.Defaults.Model != "claude-3-opus" {
-			t.Errorf("Model = %q, want %q", cfg.Agents.Defaults.Model, "claude-3-opus")
-		}
-		if cfg.Agents.Defaults.MaxTokens != 4096 {
-			t.Errorf("MaxTokens = %d, want %d", cfg.Agents.Defaults.MaxTokens, 4096)
-		}
-		if cfg.Agents.Defaults.Temperature == nil {
-			t.Fatalf("Temperature is nil, want %f", 0.5)
-		}
-		if *cfg.Agents.Defaults.Temperature != 0.5 {
-			t.Errorf("Temperature = %f, want %f", *cfg.Agents.Defaults.Temperature, 0.5)
-		}
-		if cfg.Agents.Defaults.Workspace != "~/.picoclaw/workspace" {
-			t.Errorf("Workspace = %q, want %q", cfg.Agents.Defaults.Workspace, "~/.picoclaw/workspace")
-		}
-	})
-
-	t.Run("empty config", func(t *testing.T) {
-		data := map[string]any{}
-
-		cfg, warnings, err := ConvertConfig(data)
-		if err != nil {
-			t.Fatalf("ConvertConfig: %v", err)
-		}
-		if len(warnings) != 0 {
-			t.Errorf("expected no warnings, got %v", warnings)
-		}
-		if cfg.Agents.Defaults.Model != "glm-4.7" {
-			t.Errorf("default model should be glm-4.7, got %q", cfg.Agents.Defaults.Model)
-		}
-	})
-}
-
-func TestSupportedProvidersCompatibility(t *testing.T) {
-	expected := []string{
-		"anthropic",
-		"openai",
-		"openrouter",
-		"groq",
-		"zhipu",
-		"vllm",
-		"gemini",
-	}
-
-	for _, provider := range expected {
-		if !supportedProviders[provider] {
-			t.Fatalf("supportedProviders missing expected key %q", provider)
-		}
-	}
-}
-
-func TestMergeConfig(t *testing.T) {
-	t.Run("fills empty fields", func(t *testing.T) {
-		existing := config.DefaultConfig()
-		incoming := config.DefaultConfig()
-		incoming.Providers.Anthropic.APIKey = "sk-ant-incoming"
-		incoming.Providers.OpenRouter.APIKey = "sk-or-incoming"
-
-		result := MergeConfig(existing, incoming)
-		if result.Providers.Anthropic.APIKey != "sk-ant-incoming" {
-			t.Errorf("Anthropic.APIKey = %q, want %q", result.Providers.Anthropic.APIKey, "sk-ant-incoming")
-		}
-		if result.Providers.OpenRouter.APIKey != "sk-or-incoming" {
-			t.Errorf("OpenRouter.APIKey = %q, want %q", result.Providers.OpenRouter.APIKey, "sk-or-incoming")
-		}
-	})
-
-	t.Run("preserves existing non-empty fields", func(t *testing.T) {
-		existing := config.DefaultConfig()
-		existing.Providers.Anthropic.APIKey = "sk-ant-existing"
-
-		incoming := config.DefaultConfig()
-		incoming.Providers.Anthropic.APIKey = "sk-ant-incoming"
-		incoming.Providers.OpenAI.APIKey = "sk-oai-incoming"
-
-		result := MergeConfig(existing, incoming)
-		if result.Providers.Anthropic.APIKey != "sk-ant-existing" {
-			t.Errorf("Anthropic.APIKey should be preserved, got %q", result.Providers.Anthropic.APIKey)
-		}
-		if result.Providers.OpenAI.APIKey != "sk-oai-incoming" {
-			t.Errorf("OpenAI.APIKey should be filled, got %q", result.Providers.OpenAI.APIKey)
-		}
-	})
-
-	t.Run("merges enabled channels", func(t *testing.T) {
-		existing := config.DefaultConfig()
-		incoming := config.DefaultConfig()
-		incoming.Channels.Telegram.Enabled = true
-		incoming.Channels.Telegram.Token = "tg-token"
-
-		result := MergeConfig(existing, incoming)
-		if !result.Channels.Telegram.Enabled {
-			t.Error("Telegram should be enabled after merge")
-		}
-		if result.Channels.Telegram.Token != "tg-token" {
-			t.Errorf("Telegram.Token = %q, want %q", result.Channels.Telegram.Token, "tg-token")
-		}
-	})
-
-	t.Run("preserves existing enabled channels", func(t *testing.T) {
-		existing := config.DefaultConfig()
-		existing.Channels.Telegram.Enabled = true
-		existing.Channels.Telegram.Token = "existing-token"
-
-		incoming := config.DefaultConfig()
-		incoming.Channels.Telegram.Enabled = true
-		incoming.Channels.Telegram.Token = "incoming-token"
-
-		result := MergeConfig(existing, incoming)
-		if result.Channels.Telegram.Token != "existing-token" {
-			t.Errorf("Telegram.Token should be preserved, got %q", result.Channels.Telegram.Token)
-		}
-	})
-}
-
-func TestPlanWorkspaceMigration(t *testing.T) {
-	t.Run("copies available files", func(t *testing.T) {
-		srcDir := t.TempDir()
-		dstDir := t.TempDir()
-
-		os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents"), 0o644)
-		os.WriteFile(filepath.Join(srcDir, "SOUL.md"), []byte("# Soul"), 0o644)
-		os.WriteFile(filepath.Join(srcDir, "USER.md"), []byte("# User"), 0o644)
-
-		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
-		if err != nil {
-			t.Fatalf("PlanWorkspaceMigration: %v", err)
-		}
-
-		copyCount := 0
-		skipCount := 0
-		for _, a := range actions {
-			if a.Type == ActionCopy {
-				copyCount++
-			}
-			if a.Type == ActionSkip {
-				skipCount++
-			}
-		}
-		if copyCount != 3 {
-			t.Errorf("expected 3 copies, got %d", copyCount)
-		}
-		if skipCount != 2 {
-			t.Errorf("expected 2 skips (TOOLS.md, HEARTBEAT.md), got %d", skipCount)
-		}
-	})
-
-	t.Run("plans backup for existing destination files", func(t *testing.T) {
-		srcDir := t.TempDir()
-		dstDir := t.TempDir()
-
-		os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents from OpenClaw"), 0o644)
-		os.WriteFile(filepath.Join(dstDir, "AGENTS.md"), []byte("# Existing Agents"), 0o644)
-
-		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
-		if err != nil {
-			t.Fatalf("PlanWorkspaceMigration: %v", err)
-		}
-
-		backupCount := 0
-		for _, a := range actions {
-			if a.Type == ActionBackup && filepath.Base(a.Destination) == "AGENTS.md" {
-				backupCount++
-			}
-		}
-		if backupCount != 1 {
-			t.Errorf("expected 1 backup action for AGENTS.md, got %d", backupCount)
-		}
-	})
-
-	t.Run("force skips backup", func(t *testing.T) {
-		srcDir := t.TempDir()
-		dstDir := t.TempDir()
-
-		os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents"), 0o644)
-		os.WriteFile(filepath.Join(dstDir, "AGENTS.md"), []byte("# Existing"), 0o644)
-
-		actions, err := PlanWorkspaceMigration(srcDir, dstDir, true)
-		if err != nil {
-			t.Fatalf("PlanWorkspaceMigration: %v", err)
-		}
-
-		for _, a := range actions {
-			if a.Type == ActionBackup {
-				t.Error("expected no backup actions with force=true")
-			}
-		}
-	})
-
-	t.Run("handles memory directory", func(t *testing.T) {
-		srcDir := t.TempDir()
-		dstDir := t.TempDir()
-
-		memDir := filepath.Join(srcDir, "memory")
-		os.MkdirAll(memDir, 0o755)
-		os.WriteFile(filepath.Join(memDir, "MEMORY.md"), []byte("# Memory"), 0o644)
-
-		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
-		if err != nil {
-			t.Fatalf("PlanWorkspaceMigration: %v", err)
-		}
-
-		hasCopy := false
-		hasDir := false
-		for _, a := range actions {
-			if a.Type == ActionCopy && filepath.Base(a.Source) == "MEMORY.md" {
-				hasCopy = true
-			}
-			if a.Type == ActionCreateDir {
-				hasDir = true
-			}
-		}
-		if !hasCopy {
-			t.Error("expected copy action for memory/MEMORY.md")
-		}
-		if !hasDir {
-			t.Error("expected create dir action for memory/")
-		}
-	})
-
-	t.Run("handles skills directory", func(t *testing.T) {
-		srcDir := t.TempDir()
-		dstDir := t.TempDir()
-
-		skillDir := filepath.Join(srcDir, "skills", "weather")
-		os.MkdirAll(skillDir, 0o755)
-		os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("# Weather"), 0o644)
-
-		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
-		if err != nil {
-			t.Fatalf("PlanWorkspaceMigration: %v", err)
-		}
-
-		hasCopy := false
-		for _, a := range actions {
-			if a.Type == ActionCopy && filepath.Base(a.Source) == "SKILL.md" {
-				hasCopy = true
-			}
-		}
-		if !hasCopy {
-			t.Error("expected copy action for skills/weather/SKILL.md")
-		}
-	})
-}
-
-func TestFindOpenClawConfig(t *testing.T) {
-	t.Run("finds openclaw.json", func(t *testing.T) {
-		tmpDir := t.TempDir()
-		configPath := filepath.Join(tmpDir, "openclaw.json")
-		os.WriteFile(configPath, []byte("{}"), 0o644)
-
-		found, err := findOpenClawConfig(tmpDir)
-		if err != nil {
-			t.Fatalf("findOpenClawConfig: %v", err)
-		}
-		if found != configPath {
-			t.Errorf("found %q, want %q", found, configPath)
-		}
-	})
-
-	t.Run("falls back to config.json", func(t *testing.T) {
-		tmpDir := t.TempDir()
-		configPath := filepath.Join(tmpDir, "config.json")
-		os.WriteFile(configPath, []byte("{}"), 0o644)
-
-		found, err := findOpenClawConfig(tmpDir)
-		if err != nil {
-			t.Fatalf("findOpenClawConfig: %v", err)
-		}
-		if found != configPath {
-			t.Errorf("found %q, want %q", found, configPath)
-		}
-	})
-
-	t.Run("prefers openclaw.json over config.json", func(t *testing.T) {
-		tmpDir := t.TempDir()
-		openclawPath := filepath.Join(tmpDir, "openclaw.json")
-		os.WriteFile(openclawPath, []byte("{}"), 0o644)
-		os.WriteFile(filepath.Join(tmpDir, "config.json"), []byte("{}"), 0o644)
-
-		found, err := findOpenClawConfig(tmpDir)
-		if err != nil {
-			t.Fatalf("findOpenClawConfig: %v", err)
-		}
-		if found != openclawPath {
-			t.Errorf("should prefer openclaw.json, got %q", found)
-		}
-	})
-
-	t.Run("error when no config found", func(t *testing.T) {
-		tmpDir := t.TempDir()
-
-		_, err := findOpenClawConfig(tmpDir)
-		if err == nil {
-			t.Fatal("expected error when no config found")
-		}
-	})
-}
-
-func TestRewriteWorkspacePath(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{"default path", "~/.openclaw/workspace", "~/.picoclaw/workspace"},
-		{"custom path", "/custom/path", "/custom/path"},
-		{"empty", "", ""},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := rewriteWorkspacePath(tt.input)
-			if got != tt.want {
-				t.Errorf("rewriteWorkspacePath(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestRunDryRun(t *testing.T) {
-	openclawHome := t.TempDir()
-	picoClawHome := t.TempDir()
-
-	wsDir := filepath.Join(openclawHome, "workspace")
-	os.MkdirAll(wsDir, 0o755)
-	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0o644)
-	os.WriteFile(filepath.Join(wsDir, "AGENTS.md"), []byte("# Agents"), 0o644)
-
-	configData := map[string]any{
-		"providers": map[string]any{
-			"anthropic": map[string]any{
-				"apiKey": "test-key",
-			},
-		},
-	}
-	data, _ := json.Marshal(configData)
-	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
+func TestMigrateInstanceGetCurrentHandlerWithSource(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
 
 	opts := Options{
-		DryRun:       true,
-		OpenClawHome: openclawHome,
-		PicoClawHome: picoClawHome,
+		Source:     "openclaw",
+		SourceHome: tmpDir,
 	}
+	instance := NewMigrateInstance(opts)
 
-	result, err := Run(opts)
-	if err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	picoWs := filepath.Join(picoClawHome, "workspace")
-	if _, err := os.Stat(filepath.Join(picoWs, "SOUL.md")); !os.IsNotExist(err) {
-		t.Error("dry run should not create files")
-	}
-	if _, err := os.Stat(filepath.Join(picoClawHome, "config.json")); !os.IsNotExist(err) {
-		t.Error("dry run should not create config")
-	}
-
-	_ = result
+	handler, err := instance.getCurrentHandler()
+	require.NoError(t, err)
+	require.NotNil(t, handler)
+	assert.Equal(t, "openclaw", handler.GetSourceName())
 }
 
-func TestRunFullMigration(t *testing.T) {
-	openclawHome := t.TempDir()
-	picoClawHome := t.TempDir()
-
-	wsDir := filepath.Join(openclawHome, "workspace")
-	os.MkdirAll(wsDir, 0o755)
-	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul from OpenClaw"), 0o644)
-	os.WriteFile(filepath.Join(wsDir, "AGENTS.md"), []byte("# Agents from OpenClaw"), 0o644)
-	os.WriteFile(filepath.Join(wsDir, "USER.md"), []byte("# User from OpenClaw"), 0o644)
-
-	memDir := filepath.Join(wsDir, "memory")
-	os.MkdirAll(memDir, 0o755)
-	os.WriteFile(filepath.Join(memDir, "MEMORY.md"), []byte("# Memory notes"), 0o644)
-
-	configData := map[string]any{
-		"providers": map[string]any{
-			"anthropic": map[string]any{
-				"apiKey": "sk-ant-migrate-test",
-			},
-			"openrouter": map[string]any{
-				"apiKey": "sk-or-migrate-test",
-			},
-		},
-		"channels": map[string]any{
-			"telegram": map[string]any{
-				"enabled": true,
-				"token":   "tg-migrate-test",
-			},
-		},
-	}
-	data, _ := json.Marshal(configData)
-	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
-
-	opts := Options{
-		Force:        true,
-		OpenClawHome: openclawHome,
-		PicoClawHome: picoClawHome,
+func TestMigrateInstanceGetCurrentHandlerNotFound(t *testing.T) {
+	instance := &MigrateInstance{
+		options:  Options{},
+		handlers: make(map[string]Operation),
 	}
 
-	result, err := Run(opts)
-	if err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	picoWs := filepath.Join(picoClawHome, "workspace")
-
-	soulData, err := os.ReadFile(filepath.Join(picoWs, "SOUL.md"))
-	if err != nil {
-		t.Fatalf("reading SOUL.md: %v", err)
-	}
-	if string(soulData) != "# Soul from OpenClaw" {
-		t.Errorf("SOUL.md content = %q, want %q", string(soulData), "# Soul from OpenClaw")
-	}
-
-	agentsData, err := os.ReadFile(filepath.Join(picoWs, "AGENTS.md"))
-	if err != nil {
-		t.Fatalf("reading AGENTS.md: %v", err)
-	}
-	if string(agentsData) != "# Agents from OpenClaw" {
-		t.Errorf("AGENTS.md content = %q", string(agentsData))
-	}
-
-	memData, err := os.ReadFile(filepath.Join(picoWs, "memory", "MEMORY.md"))
-	if err != nil {
-		t.Fatalf("reading memory/MEMORY.md: %v", err)
-	}
-	if string(memData) != "# Memory notes" {
-		t.Errorf("MEMORY.md content = %q", string(memData))
-	}
-
-	picoConfig, err := config.LoadConfig(filepath.Join(picoClawHome, "config.json"))
-	if err != nil {
-		t.Fatalf("loading PicoClaw config: %v", err)
-	}
-	if picoConfig.Providers.Anthropic.APIKey != "sk-ant-migrate-test" {
-		t.Errorf("Anthropic.APIKey = %q, want %q", picoConfig.Providers.Anthropic.APIKey, "sk-ant-migrate-test")
-	}
-	if picoConfig.Providers.OpenRouter.APIKey != "sk-or-migrate-test" {
-		t.Errorf("OpenRouter.APIKey = %q, want %q", picoConfig.Providers.OpenRouter.APIKey, "sk-or-migrate-test")
-	}
-	if !picoConfig.Channels.Telegram.Enabled {
-		t.Error("Telegram should be enabled")
-	}
-	if picoConfig.Channels.Telegram.Token != "tg-migrate-test" {
-		t.Errorf("Telegram.Token = %q, want %q", picoConfig.Channels.Telegram.Token, "tg-migrate-test")
-	}
-
-	if result.FilesCopied < 3 {
-		t.Errorf("expected at least 3 files copied, got %d", result.FilesCopied)
-	}
-	if !result.ConfigMigrated {
-		t.Error("config should have been migrated")
-	}
-	if len(result.Errors) > 0 {
-		t.Errorf("expected no errors, got %v", result.Errors)
-	}
+	_, err := instance.getCurrentHandler()
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "not found")
 }
 
-func TestRunOpenClawNotFound(t *testing.T) {
-	opts := Options{
-		OpenClawHome: "/nonexistent/path/to/openclaw",
-		PicoClawHome: t.TempDir(),
+func TestMigrateInstancePlanWithInvalidSource(t *testing.T) {
+	instance := &MigrateInstance{
+		options:  Options{},
+		handlers: make(map[string]Operation),
 	}
 
-	_, err := Run(opts)
-	if err == nil {
-		t.Fatal("expected error when OpenClaw not found")
-	}
+	_, _, err := instance.Plan(Options{}, "/tmp/source", "/tmp/target")
+	require.Error(t, err)
 }
 
-func TestRunMutuallyExclusiveFlags(t *testing.T) {
-	opts := Options{
+func TestMigrateInstancePlanConfigOnlyAndWorkspaceOnlyMutuallyExclusive(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	instance := NewMigrateInstance(Options{SourceHome: tmpDir})
+	require.NotNil(t, instance)
+
+	_, err = instance.Run(Options{
 		ConfigOnly:    true,
 		WorkspaceOnly: true,
-	}
-
-	_, err := Run(opts)
-	if err == nil {
-		t.Fatal("expected error for mutually exclusive flags")
-	}
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "mutually exclusive")
 }
 
-func TestBackupFile(t *testing.T) {
+func TestMigrateInstancePlanRefreshSetsWorkspaceOnly(t *testing.T) {
+	opts := Options{
+		Refresh:    true,
+		SourceHome: "/tmp/nonexistent",
+	}
+	instance := NewMigrateInstance(opts)
+	require.NotNil(t, instance)
+
+	_, err := instance.Run(opts)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "not found")
+}
+
+func TestMigrateInstancePlanSourceNotFound(t *testing.T) {
+	opts := Options{
+		SourceHome: "/tmp/nonexistent-source-home",
+	}
+	instance := NewMigrateInstance(opts)
+
+	_, err := instance.Run(opts)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "not found")
+}
+
+func TestMigrateInstanceExecute(t *testing.T) {
 	tmpDir := t.TempDir()
-	filePath := filepath.Join(tmpDir, "test.md")
-	os.WriteFile(filePath, []byte("original content"), 0o644)
+	sourceDir := filepath.Join(tmpDir, "source")
+	targetDir := filepath.Join(tmpDir, "target")
+	workspaceDir := filepath.Join(sourceDir, "workspace")
 
-	if err := backupFile(filePath); err != nil {
-		t.Fatalf("backupFile: %v", err)
+	err := os.MkdirAll(workspaceDir, 0o755)
+	require.NoError(t, err)
+
+	err = os.WriteFile(filepath.Join(workspaceDir, "test.txt"), []byte("test"), 0o644)
+	require.NoError(t, err)
+
+	instance := &MigrateInstance{
+		options:  Options{Source: "mock"},
+		handlers: make(map[string]Operation),
 	}
+	instance.Register("mock", &mockOperation{sourceHome: sourceDir, sourceWs: workspaceDir})
 
-	bakPath := filePath + ".bak"
-	bakData, err := os.ReadFile(bakPath)
-	if err != nil {
-		t.Fatalf("reading backup: %v", err)
-	}
-	if string(bakData) != "original content" {
-		t.Errorf("backup content = %q, want %q", string(bakData), "original content")
-	}
-}
-
-func TestCopyFile(t *testing.T) {
-	tmpDir := t.TempDir()
-	srcPath := filepath.Join(tmpDir, "src.md")
-	dstPath := filepath.Join(tmpDir, "dst.md")
-
-	os.WriteFile(srcPath, []byte("file content"), 0o644)
-
-	if err := copyFile(srcPath, dstPath); err != nil {
-		t.Fatalf("copyFile: %v", err)
-	}
-
-	data, err := os.ReadFile(dstPath)
-	if err != nil {
-		t.Fatalf("reading copy: %v", err)
-	}
-	if string(data) != "file content" {
-		t.Errorf("copy content = %q, want %q", string(data), "file content")
-	}
-}
-
-func TestRunConfigOnly(t *testing.T) {
-	openclawHome := t.TempDir()
-	picoClawHome := t.TempDir()
-
-	wsDir := filepath.Join(openclawHome, "workspace")
-	os.MkdirAll(wsDir, 0o755)
-	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0o644)
-
-	configData := map[string]any{
-		"providers": map[string]any{
-			"anthropic": map[string]any{
-				"apiKey": "sk-config-only",
-			},
+	actions := []Action{
+		{
+			Type:        ActionCopy,
+			Source:      filepath.Join(workspaceDir, "test.txt"),
+			Target:      filepath.Join(targetDir, "workspace", "test.txt"),
+			Description: "copy file",
 		},
 	}
-	data, _ := json.Marshal(configData)
-	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
 
-	opts := Options{
-		Force:        true,
-		ConfigOnly:   true,
-		OpenClawHome: openclawHome,
-		PicoClawHome: picoClawHome,
-	}
+	result := instance.Execute(actions, workspaceDir, targetDir)
+	require.NotNil(t, result)
+	assert.Equal(t, 1, result.FilesCopied)
 
-	result, err := Run(opts)
-	if err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	if !result.ConfigMigrated {
-		t.Error("config should have been migrated")
-	}
-
-	picoWs := filepath.Join(picoClawHome, "workspace")
-	if _, err := os.Stat(filepath.Join(picoWs, "SOUL.md")); !os.IsNotExist(err) {
-		t.Error("config-only should not copy workspace files")
-	}
+	_, err = os.Stat(filepath.Join(targetDir, "workspace", "test.txt"))
+	assert.NoError(t, err)
 }
 
-func TestRunWorkspaceOnly(t *testing.T) {
-	openclawHome := t.TempDir()
-	picoClawHome := t.TempDir()
+func TestMigrateInstanceExecuteWithInvalidSource(t *testing.T) {
+	tmpDir := t.TempDir()
+	sourceDir := filepath.Join(tmpDir, "source")
+	err := os.MkdirAll(sourceDir, 0o755)
+	require.NoError(t, err)
 
-	wsDir := filepath.Join(openclawHome, "workspace")
-	os.MkdirAll(wsDir, 0o755)
-	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0o644)
+	instance := &MigrateInstance{
+		options:  Options{Source: "mock"},
+		handlers: make(map[string]Operation),
+	}
+	instance.Register("mock", &mockOperation{sourceHome: sourceDir})
 
-	configData := map[string]any{
-		"providers": map[string]any{
-			"anthropic": map[string]any{
-				"apiKey": "sk-ws-only",
-			},
+	actions := []Action{
+		{
+			Type:        ActionCopy,
+			Source:      filepath.Join(sourceDir, "nonexistent.txt"),
+			Target:      filepath.Join(tmpDir, "target.txt"),
+			Description: "copy file",
 		},
 	}
-	data, _ := json.Marshal(configData)
-	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
 
-	opts := Options{
-		Force:         true,
-		WorkspaceOnly: true,
-		OpenClawHome:  openclawHome,
-		PicoClawHome:  picoClawHome,
-	}
-
-	result, err := Run(opts)
-	if err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	if result.ConfigMigrated {
-		t.Error("workspace-only should not migrate config")
-	}
-
-	picoWs := filepath.Join(picoClawHome, "workspace")
-	soulData, err := os.ReadFile(filepath.Join(picoWs, "SOUL.md"))
-	if err != nil {
-		t.Fatalf("reading SOUL.md: %v", err)
-	}
-	if string(soulData) != "# Soul" {
-		t.Errorf("SOUL.md content = %q", string(soulData))
-	}
+	result := instance.Execute(actions, sourceDir, tmpDir)
+	require.NotNil(t, result)
+	assert.Equal(t, 0, result.FilesCopied)
+	assert.Greater(t, len(result.Errors), 0)
+}
+
+func TestMigrateInstanceExecuteCreateDir(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	instance := &MigrateInstance{
+		options:  Options{Source: "mock"},
+		handlers: make(map[string]Operation),
+	}
+	instance.Register("mock", &mockOperation{})
+
+	actions := []Action{
+		{
+			Type:        ActionCreateDir,
+			Target:      filepath.Join(tmpDir, "new", "dir"),
+			Description: "create directory",
+		},
+	}
+
+	result := instance.Execute(actions, "", "")
+	require.NotNil(t, result)
+	assert.Equal(t, 1, result.DirsCreated)
+
+	_, err := os.Stat(filepath.Join(tmpDir, "new", "dir"))
+	assert.NoError(t, err)
+}
+
+func TestMigrateInstanceExecuteBackup(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	sourceFile := filepath.Join(tmpDir, "source.txt")
+	targetFile := filepath.Join(tmpDir, "target.txt")
+
+	err := os.WriteFile(sourceFile, []byte("source"), 0o644)
+	require.NoError(t, err)
+
+	err = os.WriteFile(targetFile, []byte("target"), 0o644)
+	require.NoError(t, err)
+
+	instance := &MigrateInstance{
+		options:  Options{Source: "mock"},
+		handlers: make(map[string]Operation),
+	}
+	instance.Register("mock", &mockOperation{})
+
+	actions := []Action{
+		{
+			Type:        ActionBackup,
+			Source:      sourceFile,
+			Target:      targetFile,
+			Description: "backup and overwrite",
+		},
+	}
+
+	result := instance.Execute(actions, tmpDir, tmpDir)
+	require.NotNil(t, result)
+	assert.Equal(t, 1, result.BackupsCreated)
+	assert.Equal(t, 1, result.FilesCopied)
+
+	bakFile := targetFile + ".bak"
+	_, err = os.Stat(bakFile)
+	assert.NoError(t, err)
+
+	content, err := os.ReadFile(targetFile)
+	assert.NoError(t, err)
+	assert.Equal(t, "source", string(content))
+}
+
+func TestMigrateInstanceExecuteSkip(t *testing.T) {
+	instance := &MigrateInstance{
+		options:  Options{Source: "mock"},
+		handlers: make(map[string]Operation),
+	}
+	instance.Register("mock", &mockOperation{})
+
+	actions := []Action{
+		{
+			Type:        ActionSkip,
+			Source:      "/tmp/source.txt",
+			Target:      "/tmp/target.txt",
+			Description: "skip file",
+		},
+	}
+
+	result := instance.Execute(actions, "", "")
+	require.NotNil(t, result)
+	assert.Equal(t, 1, result.FilesSkipped)
+}
+
+func TestMigrateInstancePrintSummary(t *testing.T) {
+	instance := NewMigrateInstance(Options{})
+
+	result := &Result{
+		FilesCopied:    5,
+		ConfigMigrated: true,
+		BackupsCreated: 2,
+		FilesSkipped:   3,
+		Warnings:       []string{"warning 1"},
+		Errors:         []error{},
+	}
+
+	instance.PrintSummary(result)
+}
+
+func TestMigrateInstancePrintSummaryWithErrors(t *testing.T) {
+	instance := NewMigrateInstance(Options{})
+
+	result := &Result{
+		FilesCopied:    0,
+		ConfigMigrated: false,
+		BackupsCreated: 0,
+		FilesSkipped:   0,
+		Warnings:       []string{},
+		Errors:         []error{assert.AnError},
+	}
+
+	instance.PrintSummary(result)
+}
+
+func TestMigrateInstancePrintSummaryNoActions(t *testing.T) {
+	instance := NewMigrateInstance(Options{})
+
+	result := &Result{
+		FilesCopied:    0,
+		ConfigMigrated: false,
+		BackupsCreated: 0,
+		FilesSkipped:   0,
+		Warnings:       []string{},
+		Errors:         []error{},
+	}
+
+	instance.PrintSummary(result)
+}
+
+func TestPrintPlan(t *testing.T) {
+	actions := []Action{
+		{
+			Type:        ActionConvertConfig,
+			Source:      "/source/config.json",
+			Target:      "/target/config.json",
+			Description: "convert config",
+		},
+		{
+			Type:        ActionCopy,
+			Source:      "/source/file.txt",
+			Target:      "/target/file.txt",
+			Description: "copy file",
+		},
+		{
+			Type:        ActionBackup,
+			Source:      "/source/existing.txt",
+			Target:      "/target/existing.txt",
+			Description: "backup and overwrite",
+		},
+		{
+			Type:        ActionSkip,
+			Source:      "/source/skipped.txt",
+			Target:      "/target/skipped.txt",
+			Description: "skip file",
+		},
+		{
+			Type:        ActionCreateDir,
+			Target:      "/target/newdir",
+			Description: "create directory",
+		},
+	}
+
+	warnings := []string{
+		"Warning: source directory not found",
+	}
+
+	PrintPlan(actions, warnings)
+}
+
+func TestPrintPlanEmpty(t *testing.T) {
+	PrintPlan([]Action{}, []string{})
+}
+
+type mockOperation struct {
+	sourceHome   string
+	sourceConfig string
+	sourceWs     string
+	migrateFiles []string
+	migrateDirs  []string
+}
+
+func (m *mockOperation) GetSourceName() string { return "mock" }
+func (m *mockOperation) GetSourceHome() (string, error) {
+	if m.sourceHome != "" {
+		return m.sourceHome, nil
+	}
+	return "/tmp/mock", nil
+}
+
+func (m *mockOperation) GetSourceWorkspace() (string, error) {
+	if m.sourceWs != "" {
+		return m.sourceWs, nil
+	}
+	if m.sourceHome != "" {
+		return filepath.Join(m.sourceHome, "workspace"), nil
+	}
+	return "/tmp/mock/workspace", nil
+}
+
+func (m *mockOperation) GetSourceConfigFile() (string, error) {
+	if m.sourceConfig != "" {
+		return m.sourceConfig, nil
+	}
+	return "/tmp/mock/config.json", nil
+}
+func (m *mockOperation) ExecuteConfigMigration(src, dst string) error { return nil }
+func (m *mockOperation) GetMigrateableFiles() []string {
+	if m.migrateFiles != nil {
+		return m.migrateFiles
+	}
+	return []string{}
+}
+
+func (m *mockOperation) GetMigrateableDirs() []string {
+	if m.migrateDirs != nil {
+		return m.migrateDirs
+	}
+	return []string{}
 }
diff --git a/pkg/migrate/sources/openclaw/common.go b/pkg/migrate/sources/openclaw/common.go
new file mode 100644
index 000000000..d57dbe34f
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/common.go
@@ -0,0 +1,30 @@
+package openclaw
+
+var migrateableFiles = []string{
+	"AGENTS.md",
+	"SOUL.md",
+	"USER.md",
+	"TOOLS.md",
+	"HEARTBEAT.md",
+}
+
+var migrateableDirs = []string{
+	"memory",
+	"skills",
+}
+
+var supportedChannels = map[string]bool{
+	"whatsapp":  true,
+	"telegram":  true,
+	"feishu":    true,
+	"discord":   true,
+	"maixcam":   true,
+	"qq":        true,
+	"dingtalk":  true,
+	"slack":     true,
+	"matrix":    true,
+	"line":      true,
+	"onebot":    true,
+	"wecom":     true,
+	"wecom_app": true,
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_config.go b/pkg/migrate/sources/openclaw/openclaw_config.go
new file mode 100644
index 000000000..19d63bb77
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_config.go
@@ -0,0 +1,1112 @@
+package openclaw
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type OpenClawConfig struct {
+	Auth     *OpenClawAuth     `json:"auth"`
+	Models   *OpenClawModels   `json:"models"`
+	Agents   *OpenClawAgents   `json:"agents"`
+	Tools    *OpenClawTools    `json:"tools"`
+	Channels *OpenClawChannels `json:"channels"`
+	Cron     json.RawMessage   `json:"cron"`
+	Hooks    json.RawMessage   `json:"hooks"`
+	Skills   *OpenClawSkills   `json:"skills"`
+	Memory   json.RawMessage   `json:"memory"`
+	Session  json.RawMessage   `json:"session"`
+}
+
+type OpenClawAuth struct {
+	Profiles json.RawMessage `json:"profiles"`
+	Order    json.RawMessage `json:"order"`
+}
+
+type OpenClawModels struct {
+	Providers map[string]json.RawMessage `json:"providers"`
+}
+
+type ProviderConfig struct {
+	BaseUrl string        `json:"baseUrl"`
+	Api     string        `json:"api"`
+	Models  []ModelConfig `json:"models"`
+	ApiKey  string        `json:"apiKey"`
+}
+
+type OpenClawModelConfig struct {
+	ID            string   `json:"id"`
+	Name          string   `json:"name"`
+	Reasoning     bool     `json:"reasoning"`
+	Input         []string `json:"input"`
+	Cost          Cost     `json:"cost"`
+	ContextWindow int      `json:"contextWindow"`
+	MaxTokens     int      `json:"maxTokens"`
+	Api           string   `json:"api,omitempty"`
+}
+
+type Cost struct {
+	Input      float64 `json:"input"`
+	Output     float64 `json:"output"`
+	CacheRead  float64 `json:"cacheRead"`
+	CacheWrite float64 `json:"cacheWrite"`
+}
+
+type OpenClawTools struct {
+	Profile *string  `json:"profile"`
+	Allow   []string `json:"allow"`
+	Deny    []string `json:"deny"`
+}
+
+type OpenClawAgents struct {
+	Defaults *OpenClawAgentDefaults `json:"defaults"`
+	List     []OpenClawAgentEntry   `json:"list"`
+}
+
+type OpenClawAgentDefaults struct {
+	Model     *OpenClawAgentModel `json:"model"`
+	Workspace *string             `json:"workspace"`
+	Tools     *OpenClawAgentTools `json:"tools"`
+	Identity  *string             `json:"identity"`
+}
+
+type OpenClawAgentModel struct {
+	Simple    string   `json:"-"`
+	Primary   *string  `json:"primary"`
+	Fallbacks []string `json:"fallbacks"`
+}
+
+func (m *OpenClawAgentModel) GetPrimary() string {
+	if m.Simple != "" {
+		return m.Simple
+	}
+	if m.Primary != nil {
+		return *m.Primary
+	}
+	return ""
+}
+
+func (m *OpenClawAgentModel) GetFallbacks() []string {
+	return m.Fallbacks
+}
+
+type OpenClawAgentEntry struct {
+	ID        string              `json:"id"`
+	Name      *string             `json:"name"`
+	Model     *OpenClawAgentModel `json:"model"`
+	Tools     *OpenClawAgentTools `json:"tools"`
+	Workspace *string             `json:"workspace"`
+	Skills    []string            `json:"skills"`
+	Identity  *string             `json:"identity"`
+}
+
+type OpenClawAgentTools struct {
+	Profile   *string  `json:"profile"`
+	Allow     []string `json:"allow"`
+	Deny      []string `json:"deny"`
+	AlsoAllow []string `json:"alsoAllow"`
+}
+
+type OpenClawChannels struct {
+	Telegram    *OpenClawTelegramConfig    `json:"telegram"`
+	Discord     *OpenClawDiscordConfig     `json:"discord"`
+	Slack       *OpenClawSlackConfig       `json:"slack"`
+	WhatsApp    *OpenClawWhatsAppConfig    `json:"whatsapp"`
+	Signal      *OpenClawSignalConfig      `json:"signal"`
+	Matrix      *OpenClawMatrixConfig      `json:"matrix"`
+	GoogleChat  *OpenClawGoogleChatConfig  `json:"googlechat"`
+	Teams       *OpenClawTeamsConfig       `json:"msteams"`
+	IRC         *OpenClawIrcConfig         `json:"irc"`
+	Mattermost  *OpenClawMattermostConfig  `json:"mattermost"`
+	Feishu      *OpenClawFeishuConfig      `json:"feishu"`
+	IMessage    *OpenClawIMessageConfig    `json:"imessage"`
+	BlueBubbles *OpenClawBlueBubblesConfig `json:"bluebubbles"`
+	QQ          *OpenClawQQConfig          `json:"qq"`
+	DingTalk    *OpenClawDingTalkConfig    `json:"dingtalk"`
+	MaixCam     *OpenClawMaixCamConfig     `json:"maixcam"`
+}
+
+type OpenClawTelegramConfig struct {
+	BotToken    *string  `json:"botToken"`
+	AllowFrom   []string `json:"allowFrom"`
+	GroupPolicy *string  `json:"groupPolicy"`
+	DmPolicy    *string  `json:"dmPolicy"`
+	Enabled     *bool    `json:"enabled"`
+}
+
+type OpenClawDiscordConfig struct {
+	Token       *string         `json:"token"`
+	Guilds      json.RawMessage `json:"guilds"`
+	DmPolicy    *string         `json:"dmPolicy"`
+	GroupPolicy *string         `json:"groupPolicy"`
+	AllowFrom   []string        `json:"allowFrom"`
+	Enabled     *bool           `json:"enabled"`
+}
+
+type OpenClawSlackConfig struct {
+	BotToken    *string  `json:"botToken"`
+	AppToken    *string  `json:"appToken"`
+	DmPolicy    *string  `json:"dmPolicy"`
+	GroupPolicy *string  `json:"groupPolicy"`
+	AllowFrom   []string `json:"allowFrom"`
+	Enabled     *bool    `json:"enabled"`
+}
+
+type OpenClawWhatsAppConfig struct {
+	AuthDir     *string  `json:"authDir"`
+	DmPolicy    *string  `json:"dmPolicy"`
+	AllowFrom   []string `json:"allowFrom"`
+	GroupPolicy *string  `json:"groupPolicy"`
+	Enabled     *bool    `json:"enabled"`
+	BridgeURL   *string  `json:"bridgeUrl"`
+}
+
+type OpenClawSignalConfig struct {
+	HttpUrl   *string  `json:"httpUrl"`
+	HttpHost  *string  `json:"httpHost"`
+	HttpPort  *int     `json:"httpPort"`
+	Account   *string  `json:"account"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawMatrixConfig struct {
+	Homeserver  *string  `json:"homeserver"`
+	UserID      *string  `json:"userId"`
+	AccessToken *string  `json:"accessToken"`
+	Rooms       []string `json:"rooms"`
+	DmPolicy    *string  `json:"dmPolicy"`
+	AllowFrom   []string `json:"allowFrom"`
+	Enabled     *bool    `json:"enabled"`
+}
+
+type OpenClawGoogleChatConfig struct {
+	ServiceAccountFile *string `json:"serviceAccountFile"`
+	WebhookPath        *string `json:"webhookPath"`
+	BotUser            *string `json:"botUser"`
+	DmPolicy           *string `json:"dmPolicy"`
+	Enabled            *bool   `json:"enabled"`
+}
+
+type OpenClawTeamsConfig struct {
+	AppID       *string  `json:"appId"`
+	AppPassword *string  `json:"appPassword"`
+	TenantID    *string  `json:"tenantId"`
+	DmPolicy    *string  `json:"dmPolicy"`
+	AllowFrom   []string `json:"allowFrom"`
+	Enabled     *bool    `json:"enabled"`
+}
+
+type OpenClawIrcConfig struct {
+	Host      *string  `json:"host"`
+	Port      *int     `json:"port"`
+	TLS       *bool    `json:"tls"`
+	Nick      *string  `json:"nick"`
+	Password  *string  `json:"password"`
+	Channels  []string `json:"channels"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawMattermostConfig struct {
+	BotToken  *string  `json:"botToken"`
+	BaseURL   *string  `json:"baseUrl"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawFeishuConfig struct {
+	AppID             *string  `json:"appId"`
+	AppSecret         *string  `json:"appSecret"`
+	Domain            *string  `json:"domain"`
+	DmPolicy          *string  `json:"dmPolicy"`
+	Enabled           *bool    `json:"enabled"`
+	VerificationToken *string  `json:"verificationToken"`
+	EncryptKey        *string  `json:"encryptKey"`
+	AllowFrom         []string `json:"allowFrom"`
+}
+
+type OpenClawIMessageConfig struct {
+	CliPath   *string  `json:"cliPath"`
+	DbPath    *string  `json:"dbPath"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawBlueBubblesConfig struct {
+	ServerURL *string  `json:"serverUrl"`
+	Password  *string  `json:"password"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawQQConfig struct {
+	AppID     *string  `json:"appId"`
+	AppSecret *string  `json:"appSecret"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawDingTalkConfig struct {
+	AppID     *string  `json:"appId"`
+	AppSecret *string  `json:"appSecret"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawMaixCamConfig struct {
+	Host      *string  `json:"host"`
+	Port      *int     `json:"port"`
+	DmPolicy  *string  `json:"dmPolicy"`
+	AllowFrom []string `json:"allowFrom"`
+	Enabled   *bool    `json:"enabled"`
+}
+
+type OpenClawSkills struct {
+	Entries map[string]json.RawMessage `json:"entries"`
+	Load    json.RawMessage            `json:"load"`
+}
+
+type OpenClawProviderConfig struct {
+	APIKey  string `json:"api_key"`
+	BaseURL string `json:"base_url"`
+}
+
+func (c *OpenClawConfig) GetEnabled() bool {
+	return true
+}
+
+func LoadOpenClawConfig(path string) (*OpenClawConfig, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read config: %w", err)
+	}
+
+	var config OpenClawConfig
+	if err := json.Unmarshal(data, &config); err != nil {
+		return nil, fmt.Errorf("failed to parse JSON: %w", err)
+	}
+
+	return &config, nil
+}
+
+func LoadOpenClawConfigFromDir(dir string) (*OpenClawConfig, error) {
+	candidates := []string{
+		filepath.Join(dir, "openclaw.json"),
+		filepath.Join(dir, "config.json"),
+	}
+
+	for _, p := range candidates {
+		if _, err := os.Stat(p); err == nil {
+			return LoadOpenClawConfig(p)
+		}
+	}
+
+	return nil, fmt.Errorf("no config file found in %s", dir)
+}
+
+func GetProviderConfig(models *OpenClawModels) map[string]OpenClawProviderConfig {
+	result := make(map[string]OpenClawProviderConfig)
+	if models == nil || models.Providers == nil {
+		return result
+	}
+
+	for name, raw := range models.Providers {
+		var prov OpenClawProviderConfig
+		if err := json.Unmarshal(raw, &prov); err != nil {
+			continue
+		}
+		mappedName := mapProvider(name)
+		result[mappedName] = prov
+	}
+
+	return result
+}
+
+func GetProviderConfigFromDir(dir string) map[string]ProviderConfig {
+	result := make(map[string]ProviderConfig)
+	p := filepath.Join(dir, "agents", "main", "agent", "models.json")
+
+	if _, err := os.Stat(p); err != nil {
+		return result
+	}
+
+	data, err := os.ReadFile(p)
+	if err != nil {
+		return result
+	}
+	var models OpenClawModels
+	if err := json.Unmarshal(data, &models); err != nil {
+		return result
+	}
+
+	for name, raw := range models.Providers {
+		var prov ProviderConfig
+		if err := json.Unmarshal(raw, &prov); err != nil {
+			continue
+		}
+		mappedName := mapProvider(name)
+		result[mappedName] = prov
+	}
+	return result
+}
+
+func (c *OpenClawConfig) IsChannelEnabled(name string) bool {
+	switch name {
+	case "telegram":
+		return c.Channels.Telegram == nil || c.Channels.Telegram.Enabled == nil || *c.Channels.Telegram.Enabled
+	case "discord":
+		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":
+		return c.Channels.Feishu == nil || c.Channels.Feishu.Enabled == nil || *c.Channels.Feishu.Enabled
+	default:
+		return false
+	}
+}
+
+func GetChannelAllowFrom(ch any) []string {
+	switch c := ch.(type) {
+	case *OpenClawTelegramConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
+	case *OpenClawDiscordConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
+	case *OpenClawSlackConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
+	case *OpenClawMatrixConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
+	case *OpenClawWhatsAppConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
+	case *OpenClawFeishuConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
+	default:
+		return nil
+	}
+}
+
+func (c *OpenClawConfig) GetDefaultModel() (provider, model string) {
+	if c.Agents == nil || c.Agents.Defaults == nil || c.Agents.Defaults.Model == nil {
+		return "anthropic", "claude-sonnet-4-20250514"
+	}
+
+	primary := c.Agents.Defaults.Model.GetPrimary()
+	if primary == "" {
+		return "anthropic", "claude-sonnet-4-20250514"
+	}
+
+	parts := strings.Split(primary, "/")
+	if len(parts) > 1 {
+		return mapProvider(parts[0]), parts[1]
+	}
+
+	return "anthropic", primary
+}
+
+func (c *OpenClawConfig) GetDefaultWorkspace() string {
+	if c.Agents == nil || c.Agents.Defaults == nil || c.Agents.Defaults.Workspace == nil {
+		return ""
+	}
+	return rewriteWorkspacePath(*c.Agents.Defaults.Workspace)
+}
+
+func (c *OpenClawConfig) GetAgents() []OpenClawAgentEntry {
+	if c.Agents == nil {
+		return nil
+	}
+	return c.Agents.List
+}
+
+func (c *OpenClawConfig) HasSkills() bool {
+	return c.Skills != nil && c.Skills.Entries != nil && len(c.Skills.Entries) > 0
+}
+
+func (c *OpenClawConfig) HasMemory() bool {
+	return c.Memory != nil && len(c.Memory) > 0
+}
+
+func (c *OpenClawConfig) HasCron() bool {
+	return c.Cron != nil && len(c.Cron) > 0
+}
+
+func (c *OpenClawConfig) HasHooks() bool {
+	return c.Hooks != nil && len(c.Hooks) > 0
+}
+
+func (c *OpenClawConfig) HasSession() bool {
+	return c.Session != nil && len(c.Session) > 0
+}
+
+func (c *OpenClawConfig) HasAuthProfiles() bool {
+	return c.Auth != nil && c.Auth.Profiles != nil && len(c.Auth.Profiles) > 0
+}
+
+func (c *OpenClawConfig) ConvertToPicoClaw(sourceHome string) (*PicoClawConfig, []string, error) {
+	cfg := &PicoClawConfig{}
+	var warnings []string
+
+	provider, modelName := c.GetDefaultModel()
+	cfg.Agents.Defaults.Workspace = c.GetDefaultWorkspace()
+	cfg.Agents.Defaults.ModelName = modelName
+
+	providerConfigs := GetProviderConfigFromDir(sourceHome)
+	defaultAPIKey := ""
+	defaultBaseURL := ""
+
+	if provCfg, ok := providerConfigs[provider]; ok {
+		defaultAPIKey = provCfg.ApiKey
+		defaultBaseURL = provCfg.BaseUrl
+	}
+
+	cfg.ModelList = []ModelConfig{
+		{
+			ModelName: modelName,
+			Model:     fmt.Sprintf("%s/%s", provider, modelName),
+			APIKey:    defaultAPIKey,
+			APIBase:   defaultBaseURL,
+		},
+	}
+
+	for provName, provCfg := range providerConfigs {
+		if provName == provider {
+			continue
+		}
+		if provCfg.ApiKey != "" {
+			continue
+		}
+		cfg.ModelList = append(cfg.ModelList, ModelConfig{
+			ModelName: fmt.Sprintf("%s", provName),
+			Model:     fmt.Sprintf("%s/%s", provName, provName),
+			APIKey:    provCfg.ApiKey,
+			APIBase:   provCfg.BaseUrl,
+		})
+	}
+
+	cfg.Channels = c.convertChannels(&warnings)
+
+	agentList := c.convertAgents(&warnings)
+	if len(agentList) > 0 {
+		cfg.Agents.List = agentList
+	}
+
+	if c.HasSkills() {
+		warnings = append(
+			warnings,
+			fmt.Sprintf(
+				"Skills (%d entries) not automatically migrated - reinstall via picoclaw CLI",
+				len(c.Skills.Entries),
+			),
+		)
+	}
+	if c.HasMemory() {
+		warnings = append(warnings, "Memory backend config not migrated - PicoClaw uses SQLite with vector embeddings")
+	}
+	if c.HasCron() {
+		warnings = append(
+			warnings,
+			"Cron job scheduling not supported in PicoClaw - consider using external schedulers",
+		)
+	}
+	if c.HasHooks() {
+		warnings = append(warnings, "Webhook hooks not supported in PicoClaw - use event system instead")
+	}
+	if c.HasSession() {
+		warnings = append(warnings, "Session scope config differs - PicoClaw uses per-agent sessions by default")
+	}
+	if c.HasAuthProfiles() {
+		warnings = append(
+			warnings,
+			"Auth profiles (API keys, OAuth tokens) not migrated for security - set env vars manually",
+		)
+	}
+
+	return cfg, warnings, nil
+}
+
+type ModelConfig struct {
+	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"`
+}
+
+type PicoClawConfig struct {
+	Agents    AgentsConfig   `json:"agents"`
+	Bindings  []AgentBinding `json:"bindings,omitempty"`
+	Channels  ChannelsConfig `json:"channels"`
+	ModelList []ModelConfig  `json:"model_list"`
+	Gateway   GatewayConfig  `json:"gateway"`
+	Tools     ToolsConfig    `json:"tools"`
+}
+
+type AgentsConfig struct {
+	Defaults AgentDefaults `json:"defaults"`
+	List     []AgentConfig `json:"list,omitempty"`
+}
+
+type AgentDefaults struct {
+	Workspace           string   `json:"workspace"`
+	RestrictToWorkspace bool     `json:"restrict_to_workspace"`
+	Provider            string   `json:"provider"`
+	ModelName           string   `json:"model_name"`
+	Model               string   `json:"model,omitempty"`
+	ModelFallbacks      []string `json:"model_fallbacks,omitempty"`
+	ImageModel          string   `json:"image_model,omitempty"`
+	ImageModelFallbacks []string `json:"image_model_fallbacks,omitempty"`
+	MaxTokens           int      `json:"max_tokens"`
+	Temperature         *float64 `json:"temperature,omitempty"`
+	MaxToolIterations   int      `json:"max_tool_iterations"`
+}
+
+type AgentConfig struct {
+	ID        string            `json:"id"`
+	Default   bool              `json:"default,omitempty"`
+	Name      string            `json:"name,omitempty"`
+	Workspace string            `json:"workspace,omitempty"`
+	Model     *AgentModelConfig `json:"model,omitempty"`
+	Skills    []string          `json:"skills,omitempty"`
+}
+
+type AgentModelConfig struct {
+	Primary   string   `json:"primary,omitempty"`
+	Fallbacks []string `json:"fallbacks,omitempty"`
+}
+
+type AgentBinding struct {
+	AgentID string       `json:"agent_id"`
+	Match   BindingMatch `json:"match"`
+}
+
+type BindingMatch struct {
+	Channel   string     `json:"channel"`
+	AccountID string     `json:"account_id,omitempty"`
+	Peer      *PeerMatch `json:"peer,omitempty"`
+	GuildID   string     `json:"guild_id,omitempty"`
+	TeamID    string     `json:"team_id,omitempty"`
+}
+
+type PeerMatch struct {
+	Kind string `json:"kind"`
+	ID   string `json:"id"`
+}
+
+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"`
+	Matrix   MatrixConfig   `json:"matrix"`
+	LINE     LINEConfig     `json:"line"`
+}
+
+type WhatsAppConfig struct {
+	Enabled   bool     `json:"enabled"`
+	BridgeURL string   `json:"bridge_url"`
+	AllowFrom []string `json:"allow_from"`
+}
+
+type TelegramConfig struct {
+	Enabled   bool     `json:"enabled"`
+	Token     string   `json:"token"`
+	Proxy     string   `json:"proxy"`
+	AllowFrom []string `json:"allow_from"`
+}
+
+type FeishuConfig struct {
+	Enabled           bool     `json:"enabled"`
+	AppID             string   `json:"app_id"`
+	AppSecret         string   `json:"app_secret"`
+	EncryptKey        string   `json:"encrypt_key"`
+	VerificationToken string   `json:"verification_token"`
+	AllowFrom         []string `json:"allow_from"`
+}
+
+type DiscordConfig struct {
+	Enabled     bool     `json:"enabled"`
+	Token       string   `json:"token"`
+	MentionOnly bool     `json:"mention_only"`
+	AllowFrom   []string `json:"allow_from"`
+}
+
+type MaixCamConfig struct {
+	Enabled   bool     `json:"enabled"`
+	Host      string   `json:"host"`
+	Port      int      `json:"port"`
+	AllowFrom []string `json:"allow_from"`
+}
+
+type QQConfig struct {
+	Enabled   bool     `json:"enabled"`
+	AppID     string   `json:"app_id"`
+	AppSecret string   `json:"app_secret"`
+	AllowFrom []string `json:"allow_from"`
+}
+
+type DingTalkConfig struct {
+	Enabled      bool     `json:"enabled"`
+	ClientID     string   `json:"client_id"`
+	ClientSecret string   `json:"client_secret"`
+	AllowFrom    []string `json:"allow_from"`
+}
+
+type SlackConfig struct {
+	Enabled   bool     `json:"enabled"`
+	BotToken  string   `json:"bot_token"`
+	AppToken  string   `json:"app_token"`
+	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"`
+	ChannelAccessToken string   `json:"channel_access_token"`
+	WebhookHost        string   `json:"webhook_host"`
+	WebhookPort        int      `json:"webhook_port"`
+	WebhookPath        string   `json:"webhook_path"`
+	AllowFrom          []string `json:"allow_from"`
+}
+
+type GatewayConfig struct {
+	Host string `json:"host"`
+	Port int    `json:"port"`
+}
+
+type ToolsConfig struct {
+	Web  WebToolsConfig `json:"web"`
+	Cron CronConfig     `json:"cron"`
+	Exec ExecConfig     `json:"exec"`
+}
+
+type WebToolsConfig struct {
+	Brave      BraveConfig      `json:"brave"`
+	Tavily     TavilyConfig     `json:"tavily"`
+	DuckDuckGo DuckDuckGoConfig `json:"duckduckgo"`
+	Perplexity PerplexityConfig `json:"perplexity"`
+	Proxy      string           `json:"proxy,omitempty"`
+}
+
+type BraveConfig struct {
+	Enabled    bool   `json:"enabled"`
+	APIKey     string `json:"api_key"`
+	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"`
+}
+
+type DuckDuckGoConfig struct {
+	Enabled    bool `json:"enabled"`
+	MaxResults int  `json:"max_results"`
+}
+
+type PerplexityConfig struct {
+	Enabled    bool   `json:"enabled"`
+	APIKey     string `json:"api_key"`
+	MaxResults int    `json:"max_results"`
+}
+
+type CronConfig struct {
+	ExecTimeoutMinutes int `json:"exec_timeout_minutes"`
+}
+
+type ExecConfig struct {
+	EnableDenyPatterns bool     `json:"enable_deny_patterns"`
+	CustomDenyPatterns []string `json:"custom_deny_patterns"`
+}
+
+func (c *OpenClawConfig) convertChannels(warnings *[]string) ChannelsConfig {
+	channels := ChannelsConfig{}
+
+	if c.Channels == nil {
+		return channels
+	}
+
+	if c.Channels.Telegram != nil {
+		enabled := c.Channels.Telegram.Enabled == nil || *c.Channels.Telegram.Enabled
+		channels.Telegram = TelegramConfig{
+			Enabled:   enabled,
+			AllowFrom: c.Channels.Telegram.AllowFrom,
+		}
+		if c.Channels.Telegram.BotToken != nil {
+			channels.Telegram.Token = *c.Channels.Telegram.BotToken
+		}
+	}
+
+	if c.Channels.Discord != nil {
+		enabled := c.Channels.Discord.Enabled == nil || *c.Channels.Discord.Enabled
+		channels.Discord = DiscordConfig{
+			Enabled:   enabled,
+			AllowFrom: c.Channels.Discord.AllowFrom,
+		}
+		if c.Channels.Discord.Token != nil {
+			channels.Discord.Token = *c.Channels.Discord.Token
+		}
+	}
+
+	if c.Channels.Slack != nil {
+		enabled := c.Channels.Slack.Enabled == nil || *c.Channels.Slack.Enabled
+		channels.Slack = SlackConfig{
+			Enabled:   enabled,
+			AllowFrom: c.Channels.Slack.AllowFrom,
+		}
+		if c.Channels.Slack.BotToken != nil {
+			channels.Slack.BotToken = *c.Channels.Slack.BotToken
+		}
+		if c.Channels.Slack.AppToken != nil {
+			channels.Slack.AppToken = *c.Channels.Slack.AppToken
+		}
+	}
+
+	if c.Channels.WhatsApp != nil {
+		enabled := c.Channels.WhatsApp.Enabled == nil || *c.Channels.WhatsApp.Enabled
+		channels.WhatsApp = WhatsAppConfig{
+			Enabled:   enabled,
+			AllowFrom: c.Channels.WhatsApp.AllowFrom,
+		}
+		if c.Channels.WhatsApp.BridgeURL != nil {
+			channels.WhatsApp.BridgeURL = *c.Channels.WhatsApp.BridgeURL
+		}
+	}
+
+	if c.Channels.Feishu != nil {
+		enabled := c.Channels.Feishu.Enabled == nil || *c.Channels.Feishu.Enabled
+		channels.Feishu = FeishuConfig{
+			Enabled:   enabled,
+			AllowFrom: c.Channels.Feishu.AllowFrom,
+		}
+		if c.Channels.Feishu.AppID != nil {
+			channels.Feishu.AppID = *c.Channels.Feishu.AppID
+		}
+		if c.Channels.Feishu.AppSecret != nil {
+			channels.Feishu.AppSecret = *c.Channels.Feishu.AppSecret
+		}
+		if c.Channels.Feishu.EncryptKey != nil {
+			channels.Feishu.EncryptKey = *c.Channels.Feishu.EncryptKey
+		}
+		if c.Channels.Feishu.VerificationToken != nil {
+			channels.Feishu.VerificationToken = *c.Channels.Feishu.VerificationToken
+		}
+	}
+
+	if c.Channels.QQ != nil && supportedChannels["qq"] {
+		channels.QQ = QQConfig{
+			Enabled:   true,
+			AllowFrom: c.Channels.QQ.AllowFrom,
+		}
+		if c.Channels.QQ.AppID != nil {
+			channels.QQ.AppID = *c.Channels.QQ.AppID
+		}
+		if c.Channels.QQ.AppSecret != nil {
+			channels.QQ.AppSecret = *c.Channels.QQ.AppSecret
+		}
+	}
+
+	if c.Channels.DingTalk != nil && supportedChannels["dingtalk"] {
+		channels.DingTalk = DingTalkConfig{
+			Enabled:   true,
+			AllowFrom: c.Channels.DingTalk.AllowFrom,
+		}
+		if c.Channels.DingTalk.AppID != nil {
+			channels.DingTalk.ClientID = *c.Channels.DingTalk.AppID
+		}
+		if c.Channels.DingTalk.AppSecret != nil {
+			channels.DingTalk.ClientSecret = *c.Channels.DingTalk.AppSecret
+		}
+	}
+
+	if c.Channels.MaixCam != nil && supportedChannels["maixcam"] {
+		channels.MaixCam = MaixCamConfig{
+			Enabled:   true,
+			AllowFrom: c.Channels.MaixCam.AllowFrom,
+		}
+		if c.Channels.MaixCam.Host != nil {
+			channels.MaixCam.Host = *c.Channels.MaixCam.Host
+		}
+		if c.Channels.MaixCam.Port != nil {
+			channels.MaixCam.Port = *c.Channels.MaixCam.Port
+		}
+	}
+
+	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.IRC != nil {
+		*warnings = append(*warnings, "Channel 'irc': No PicoClaw adapter available")
+	}
+	if c.Channels.Mattermost != nil {
+		*warnings = append(*warnings, "Channel 'mattermost': No PicoClaw adapter available")
+	}
+	if c.Channels.IMessage != nil {
+		*warnings = append(*warnings, "Channel 'imessage': macOS-only channel - requires manual setup")
+	}
+	if c.Channels.BlueBubbles != nil {
+		*warnings = append(
+			*warnings,
+			"Channel 'bluebubbles': No PicoClaw adapter available - consider iMessage instead",
+		)
+	}
+
+	return channels
+}
+
+func (c *OpenClawConfig) convertAgents(warnings *[]string) []AgentConfig {
+	var agents []AgentConfig
+
+	if c.Agents == nil {
+		return agents
+	}
+
+	for _, entry := range c.Agents.List {
+		agentID := entry.ID
+		if agentID == "" {
+			continue
+		}
+
+		agentName := agentID
+		if entry.Name != nil {
+			agentName = *entry.Name
+		}
+
+		agentCfg := AgentConfig{
+			ID:      agentID,
+			Name:    agentName,
+			Default: len(agents) == 0,
+		}
+
+		if entry.Workspace != nil {
+			agentCfg.Workspace = rewriteWorkspacePath(*entry.Workspace)
+		}
+
+		if entry.Model != nil {
+			primary := entry.Model.GetPrimary()
+			if primary != "" {
+				agentCfg.Model = &AgentModelConfig{
+					Primary:   primary,
+					Fallbacks: entry.Model.GetFallbacks(),
+				}
+			}
+		}
+
+		if len(entry.Skills) > 0 {
+			agentCfg.Skills = entry.Skills
+		}
+
+		agents = append(agents, agentCfg)
+	}
+
+	return agents
+}
+
+func (c *PicoClawConfig) ToStandardConfig() *config.Config {
+	cfg := config.DefaultConfig()
+
+	cfg.Agents.Defaults.Workspace = c.Agents.Defaults.Workspace
+	cfg.Agents.Defaults.Provider = c.Agents.Defaults.Provider
+	cfg.Agents.Defaults.ModelName = c.Agents.Defaults.ModelName
+	cfg.Agents.Defaults.ModelFallbacks = c.Agents.Defaults.ModelFallbacks
+
+	for _, m := range c.ModelList {
+		cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+			ModelName: m.ModelName,
+			Model:     m.Model,
+			APIBase:   m.APIBase,
+			APIKey:    m.APIKey,
+			Proxy:     m.Proxy,
+		})
+	}
+
+	cfg.Channels = c.Channels.ToStandardChannels()
+	cfg.Gateway = c.Gateway.ToStandardGateway()
+	cfg.Tools = c.Tools.ToStandardTools()
+
+	cfg.Agents.List = make([]config.AgentConfig, len(c.Agents.List))
+	for i, a := range c.Agents.List {
+		cfg.Agents.List[i] = config.AgentConfig{
+			ID:        a.ID,
+			Default:   a.Default,
+			Name:      a.Name,
+			Workspace: a.Workspace,
+			Skills:    a.Skills,
+		}
+		if a.Model != nil {
+			cfg.Agents.List[i].Model = &config.AgentModelConfig{
+				Primary:   a.Model.Primary,
+				Fallbacks: a.Model.Fallbacks,
+			}
+		}
+	}
+
+	return cfg
+}
+
+func (c ChannelsConfig) ToStandardChannels() config.ChannelsConfig {
+	return config.ChannelsConfig{
+		WhatsApp: config.WhatsAppConfig{
+			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,
+		},
+		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,
+		},
+		Matrix: config.MatrixConfig{
+			Enabled:      c.Matrix.Enabled,
+			Homeserver:   c.Matrix.Homeserver,
+			UserID:       c.Matrix.UserID,
+			AccessToken:  c.Matrix.AccessToken,
+			AllowFrom:    c.Matrix.AllowFrom,
+			JoinOnInvite: true,
+		},
+		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,
+		},
+	}
+}
+
+func (c GatewayConfig) ToStandardGateway() config.GatewayConfig {
+	return config.GatewayConfig{
+		Host: c.Host,
+		Port: c.Port,
+	}
+}
+
+func (c ToolsConfig) ToStandardTools() config.ToolsConfig {
+	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,
+			},
+			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,
+		},
+		Cron: config.CronToolsConfig{
+			ExecTimeoutMinutes: c.Cron.ExecTimeoutMinutes,
+		},
+		Exec: config.ExecConfig{
+			EnableDenyPatterns: c.Exec.EnableDenyPatterns,
+			CustomDenyPatterns: c.Exec.CustomDenyPatterns,
+		},
+	}
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_config_test.go b/pkg/migrate/sources/openclaw/openclaw_config_test.go
new file mode 100644
index 000000000..3a7d0c686
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_config_test.go
@@ -0,0 +1,808 @@
+package openclaw
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestLoadOpenClawConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"agents": {
+			"defaults": {
+				"model": {
+					"primary": "anthropic/claude-sonnet-4-20250514"
+				},
+				"workspace": "~/.openclaw/workspace"
+			},
+			"list": [
+				{
+					"id": "main",
+					"name": "Main Agent",
+					"model": {
+						"primary": "openai/gpt-4o",
+						"fallbacks": ["claude-3-opus"]
+					}
+				}
+			]
+		},
+		"channels": {
+			"telegram": {
+				"enabled": true,
+				"botToken": "test-token",
+				"allowFrom": ["user1", "user2"]
+			},
+			"discord": {
+				"enabled": true,
+				"token": "discord-token"
+			}
+		},
+		"models": {
+			"providers": {
+				"anthropic": {
+					"api_key": "sk-ant-test",
+					"base_url": "https://api.anthropic.com"
+				},
+				"openai": {
+					"api_key": "sk-test"
+				}
+			}
+		}
+	}`
+
+	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)
+	}
+
+	if cfg.Agents == nil {
+		t.Error("agents should not be nil")
+	}
+
+	if cfg.Agents.Defaults == nil {
+		t.Error("agents.defaults should not be nil")
+	}
+
+	provider, model := cfg.GetDefaultModel()
+	if provider != "anthropic" {
+		t.Errorf("expected provider 'anthropic', got '%s'", provider)
+	}
+	if model != "claude-sonnet-4-20250514" {
+		t.Errorf("expected model 'claude-sonnet-4-20250514', got '%s'", model)
+	}
+
+	workspace := cfg.GetDefaultWorkspace()
+	if workspace != "~/.picoclaw/workspace" {
+		t.Errorf("expected workspace '~/.picoclaw/workspace', got '%s'", workspace)
+	}
+
+	agents := cfg.GetAgents()
+	if len(agents) != 1 {
+		t.Errorf("expected 1 agent, got %d", len(agents))
+	}
+	if agents[0].ID != "main" {
+		t.Errorf("expected agent id 'main', got '%s'", agents[0].ID)
+	}
+
+	if cfg.Channels == nil {
+		t.Error("channels should not be nil")
+	}
+	if cfg.Channels.Telegram == nil {
+		t.Error("telegram channel should not be nil")
+	}
+	if cfg.Channels.Telegram.BotToken == nil || *cfg.Channels.Telegram.BotToken != "test-token" {
+		t.Error("telegram bot token not parsed correctly")
+	}
+}
+
+func TestGetProviderConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"models": {
+			"providers": {
+				"anthropic": {
+					"api_key": "sk-ant-test",
+					"base_url": "https://api.anthropic.com",
+					"max_tokens": 4096
+				},
+				"openai": {
+					"api_key": "sk-test",
+					"base_url": "https://api.openai.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)
+	}
+
+	providers := GetProviderConfig(cfg.Models)
+	if len(providers) != 2 {
+		t.Errorf("expected 2 providers, got %d", len(providers))
+	}
+
+	if anthropic, ok := providers["anthropic"]; ok {
+		if anthropic.APIKey != "sk-ant-test" {
+			t.Errorf("expected anthropic api_key 'sk-ant-test', got '%s'", anthropic.APIKey)
+		}
+		if anthropic.BaseURL != "https://api.anthropic.com" {
+			t.Errorf("expected anthropic base_url 'https://api.anthropic.com', got '%s'", anthropic.BaseURL)
+		}
+	} else {
+		t.Error("anthropic provider not found")
+	}
+
+	if openai, ok := providers["openai"]; ok {
+		if openai.APIKey != "sk-test" {
+			t.Errorf("expected openai api_key 'sk-test', got '%s'", openai.APIKey)
+		}
+	} else {
+		t.Error("openai provider not found")
+	}
+}
+
+func TestConvertToPicoClaw(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"agents": {
+			"defaults": {
+				"model": {
+					"primary": "anthropic/claude-sonnet-4-20250514"
+				},
+				"workspace": "~/.openclaw/workspace"
+			},
+			"list": [
+				{
+					"id": "main",
+					"name": "Main Agent"
+				},
+				{
+					"id": "assistant",
+					"name": "Assistant",
+					"skills": ["skill1", "skill2"]
+				}
+			]
+		},
+		"channels": {
+			"telegram": {
+				"enabled": true,
+				"botToken": "test-token",
+				"allowFrom": ["user1", "user2"]
+			},
+			"discord": {
+				"enabled": false,
+				"token": "discord-token"
+			},
+			"whatsapp": {
+				"enabled": true,
+				"bridgeUrl": "http://localhost:3000"
+			},
+			"feishu": {
+				"enabled": true,
+				"appId": "app-id",
+				"appSecret": "app-secret",
+				"allowFrom": ["user3"]
+			},
+			"signal": {
+				"enabled": true
+			}
+		},
+		"models": {
+			"providers": {
+				"anthropic": {
+					"api_key": "sk-ant-test"
+				},
+				"openai": {
+					"api_key": "sk-test"
+				}
+			}
+		},
+		"skills": {
+			"entries": {
+				"skill1": {}
+			}
+		},
+		"memory": {"enabled": true},
+		"cron": {"enabled": true}
+	}`
+
+	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.Agents.Defaults.ModelName != "claude-sonnet-4-20250514" {
+		t.Errorf("expected model 'claude-sonnet-4-20250514', got '%s'", picoCfg.Agents.Defaults.ModelName)
+	}
+	if picoCfg.Agents.Defaults.Workspace != "~/.picoclaw/workspace" {
+		t.Errorf("expected workspace '~/.picoclaw/workspace', got '%s'", picoCfg.Agents.Defaults.Workspace)
+	}
+
+	if len(picoCfg.Agents.List) != 2 {
+		t.Errorf("expected 2 agents, got %d", len(picoCfg.Agents.List))
+	}
+	if picoCfg.Agents.List[0].ID != "main" {
+		t.Errorf("expected first agent id 'main', got '%s'", picoCfg.Agents.List[0].ID)
+	}
+	if picoCfg.Agents.List[1].Skills == nil || len(picoCfg.Agents.List[1].Skills) != 2 {
+		t.Errorf("expected 2 skills for assistant agent")
+	}
+
+	if !picoCfg.Channels.Telegram.Enabled {
+		t.Error("telegram should be enabled")
+	}
+	if picoCfg.Channels.Telegram.Token != "test-token" {
+		t.Errorf("expected telegram token 'test-token', got '%s'", picoCfg.Channels.Telegram.Token)
+	}
+
+	if picoCfg.Channels.WhatsApp.BridgeURL != "http://localhost:3000" {
+		t.Errorf("expected whatsapp bridge URL 'http://localhost:3000', got '%s'", picoCfg.Channels.WhatsApp.BridgeURL)
+	}
+
+	if picoCfg.Channels.Feishu.AppID != "app-id" {
+		t.Errorf("expected feishu app ID 'app-id', got '%s'", picoCfg.Channels.Feishu.AppID)
+	}
+
+	if len(picoCfg.ModelList) != 1 {
+		t.Errorf("expected 1 model config (no models.json provided), got %d", len(picoCfg.ModelList))
+	}
+
+	foundWarning := false
+	for _, w := range warnings {
+		if len(w) > 0 {
+			foundWarning = true
+			break
+		}
+	}
+	if !foundWarning {
+		t.Log("warnings should be generated for skills, memory, cron, and unsupported channels")
+	}
+}
+
+func TestConvertToPicoClawWithQQAndDingTalk(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"agents": {
+			"defaults": {
+				"model": {
+					"primary": "anthropic/claude-sonnet-4-20250514"
+				}
+			}
+		},
+		"channels": {
+			"qq": {
+				"enabled": true,
+				"appId": "qq-app-id",
+				"appSecret": "qq-app-secret"
+			},
+			"dingtalk": {
+				"enabled": true,
+				"appId": "ding-app-id",
+				"appSecret": "ding-app-secret"
+			},
+			"maixcam": {
+				"enabled": true,
+				"host": "192.168.1.100",
+				"port": 9000
+			},
+			"slack": {
+				"enabled": true,
+				"botToken": "xoxb-test",
+				"appToken": "xapp-test"
+			}
+		}
+	}`
+
+	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.QQ.Enabled {
+		t.Error("qq should be enabled")
+	}
+	if picoCfg.Channels.QQ.AppID != "qq-app-id" {
+		t.Errorf("expected qq app ID 'qq-app-id', got '%s'", picoCfg.Channels.QQ.AppID)
+	}
+
+	if !picoCfg.Channels.DingTalk.Enabled {
+		t.Error("dingtalk should be enabled")
+	}
+	if picoCfg.Channels.DingTalk.ClientID != "ding-app-id" {
+		t.Errorf("expected dingtalk client ID 'ding-app-id', got '%s'", picoCfg.Channels.DingTalk.ClientID)
+	}
+
+	if !picoCfg.Channels.MaixCam.Enabled {
+		t.Error("maixcam should be enabled")
+	}
+	if picoCfg.Channels.MaixCam.Host != "192.168.1.100" {
+		t.Errorf("expected maixcam host '192.168.1.100', got '%s'", picoCfg.Channels.MaixCam.Host)
+	}
+	if picoCfg.Channels.MaixCam.Port != 9000 {
+		t.Errorf("expected maixcam port 9000, got %d", picoCfg.Channels.MaixCam.Port)
+	}
+
+	if !picoCfg.Channels.Slack.Enabled {
+		t.Error("slack should be enabled")
+	}
+	if picoCfg.Channels.Slack.BotToken != "xoxb-test" {
+		t.Errorf("expected slack bot token 'xoxb-test', got '%s'", picoCfg.Channels.Slack.BotToken)
+	}
+	if picoCfg.Channels.Slack.AppToken != "xapp-test" {
+		t.Errorf("expected slack app token 'xapp-test', got '%s'", picoCfg.Channels.Slack.AppToken)
+	}
+}
+
+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"),
+		Fallbacks: []string{"claude-3-sonnet", "claude-3-haiku"},
+	}
+
+	primary := model.GetPrimary()
+	if primary != "anthropic/claude-3-opus" {
+		t.Errorf("expected primary 'anthropic/claude-3-opus', got '%s'", primary)
+	}
+
+	fallbacks := model.GetFallbacks()
+	if len(fallbacks) != 2 {
+		t.Errorf("expected 2 fallbacks, got %d", len(fallbacks))
+	}
+
+	model2 := &OpenClawAgentModel{
+		Simple: "claude-3-opus",
+	}
+
+	primary2 := model2.GetPrimary()
+	if primary2 != "claude-3-opus" {
+		t.Errorf("expected primary 'claude-3-opus' from Simple, got '%s'", primary2)
+	}
+}
+
+func TestChannelEnabled(t *testing.T) {
+	cfg := &OpenClawConfig{
+		Channels: &OpenClawChannels{
+			Telegram: &OpenClawTelegramConfig{
+				Enabled: boolPtr(true),
+			},
+			Discord: &OpenClawDiscordConfig{
+				Enabled: boolPtr(false),
+			},
+			Slack: &OpenClawSlackConfig{
+				Enabled: boolPtr(true),
+			},
+		},
+	}
+
+	if !cfg.IsChannelEnabled("telegram") {
+		t.Error("telegram should be enabled")
+	}
+	if cfg.IsChannelEnabled("discord") {
+		t.Error("discord should be disabled")
+	}
+	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)")
+	}
+}
+
+func TestGetDefaultModel(t *testing.T) {
+	cfg := &OpenClawConfig{
+		Agents: &OpenClawAgents{
+			Defaults: &OpenClawAgentDefaults{
+				Model: &OpenClawAgentModel{
+					Primary: strPtr("openai/gpt-4"),
+				},
+			},
+		},
+	}
+
+	provider, model := cfg.GetDefaultModel()
+	if provider != "openai" {
+		t.Errorf("expected provider 'openai', got '%s'", provider)
+	}
+	if model != "gpt-4" {
+		t.Errorf("expected model 'gpt-4', got '%s'", model)
+	}
+}
+
+func TestGetDefaultModelWithNoDefaults(t *testing.T) {
+	cfg := &OpenClawConfig{}
+
+	provider, model := cfg.GetDefaultModel()
+	if provider != "anthropic" {
+		t.Errorf("expected default provider 'anthropic', got '%s'", provider)
+	}
+	if model != "claude-sonnet-4-20250514" {
+		t.Errorf("expected default model 'claude-sonnet-4-20250514', got '%s'", model)
+	}
+}
+
+func TestHasFunctions(t *testing.T) {
+	cfg := &OpenClawConfig{
+		Skills:  &OpenClawSkills{Entries: map[string]json.RawMessage{"skill1": nil}},
+		Memory:  json.RawMessage(`{"enabled": true}`),
+		Cron:    json.RawMessage(`{"enabled": true}`),
+		Hooks:   json.RawMessage(`{"enabled": true}`),
+		Session: json.RawMessage(`{"enabled": true}`),
+		Auth:    &OpenClawAuth{Profiles: json.RawMessage(`{"profile1": {}}`)},
+	}
+
+	if !cfg.HasSkills() {
+		t.Error("should have skills")
+	}
+	if !cfg.HasMemory() {
+		t.Error("should have memory")
+	}
+	if !cfg.HasCron() {
+		t.Error("should have cron")
+	}
+	if !cfg.HasHooks() {
+		t.Error("should have hooks")
+	}
+	if !cfg.HasSession() {
+		t.Error("should have session")
+	}
+	if !cfg.HasAuthProfiles() {
+		t.Error("should have auth profiles")
+	}
+
+	cfg2 := &OpenClawConfig{}
+	if cfg2.HasSkills() {
+		t.Error("should not have skills")
+	}
+	if cfg2.HasMemory() {
+		t.Error("should not have memory")
+	}
+}
+
+func TestLoadOpenClawConfigFromDir(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{"agents": {}}`
+	err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+	if err != nil {
+		t.Fatalf("failed to write test config: %v", err)
+	}
+
+	cfg, err := LoadOpenClawConfigFromDir(tmpDir)
+	if err != nil {
+		t.Fatalf("failed to load config from dir: %v", err)
+	}
+
+	if cfg.Agents == nil {
+		t.Error("agents should not be nil")
+	}
+
+	_, err = LoadOpenClawConfigFromDir("/nonexistent/dir")
+	if err == nil {
+		t.Error("should return error for nonexistent dir")
+	}
+}
+
+func TestToStandardConfig(t *testing.T) {
+	picoCfg := &PicoClawConfig{
+		Agents: AgentsConfig{
+			Defaults: AgentDefaults{
+				Provider:  "anthropic",
+				ModelName: "claude-sonnet-4-20250514",
+				Workspace: "~/.picoclaw/workspace",
+			},
+			List: []AgentConfig{
+				{
+					ID:      "main",
+					Name:    "Main Agent",
+					Default: true,
+				},
+			},
+		},
+		ModelList: []ModelConfig{
+			{
+				ModelName: "claude-sonnet-4-20250514",
+				Model:     "anthropic/claude-sonnet-4-20250514",
+				APIKey:    "sk-ant-test",
+			},
+		},
+		Channels: ChannelsConfig{
+			Telegram: TelegramConfig{
+				Enabled:   true,
+				Token:     "test-token",
+				AllowFrom: []string{"user1"},
+			},
+			WhatsApp: WhatsAppConfig{
+				Enabled:   true,
+				BridgeURL: "http://localhost:3000",
+			},
+		},
+		Gateway: GatewayConfig{
+			Host: "0.0.0.0",
+			Port: 8080,
+		},
+	}
+
+	stdCfg := picoCfg.ToStandardConfig()
+
+	if stdCfg.Agents.Defaults.Provider != "anthropic" {
+		t.Errorf("expected provider 'anthropic', got '%s'", stdCfg.Agents.Defaults.Provider)
+	}
+	if stdCfg.Agents.Defaults.ModelName != "claude-sonnet-4-20250514" {
+		t.Errorf("expected model name 'claude-sonnet-4-20250514', got '%s'", stdCfg.Agents.Defaults.ModelName)
+	}
+	if stdCfg.Agents.Defaults.Workspace != "~/.picoclaw/workspace" {
+		t.Errorf("expected workspace '~/.picoclaw/workspace', got '%s'", stdCfg.Agents.Defaults.Workspace)
+	}
+
+	if len(stdCfg.Agents.List) != 1 {
+		t.Errorf("expected 1 agent, got %d", len(stdCfg.Agents.List))
+	}
+	if stdCfg.Agents.List[0].ID != "main" {
+		t.Errorf("expected agent id 'main', got '%s'", stdCfg.Agents.List[0].ID)
+	}
+
+	foundModel := false
+	var foundAPIKey string
+	for _, m := range stdCfg.ModelList {
+		if m.ModelName == "claude-sonnet-4-20250514" {
+			foundModel = true
+			foundAPIKey = m.APIKey
+			break
+		}
+	}
+	if !foundModel {
+		t.Error("expected to find claude-sonnet-4-20250514 model config")
+	}
+	if foundAPIKey != "sk-ant-test" {
+		t.Errorf("expected api key 'sk-ant-test', got '%s'", foundAPIKey)
+	}
+
+	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.Gateway.Port != 8080 {
+		t.Errorf("expected gateway port 8080, got %d", stdCfg.Gateway.Port)
+	}
+}
+
+func TestLoadProviderConfigFromAgentsDir(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	agentsDir := filepath.Join(tmpDir, "agents", "main", "agent")
+	err := os.MkdirAll(agentsDir, 0o755)
+	if err != nil {
+		t.Fatalf("failed to create agents dir: %v", err)
+	}
+
+	modelsJSON := `{
+		"providers": {
+			"anthropic": {
+				"baseUrl": "https://api.anthropic.com",
+				"api": "anthropic",
+				"apiKey": "sk-ant-from-models",
+				"models": [
+					{
+						"id": "claude-sonnet-4-20250514",
+						"name": "Claude Sonnet 4"
+					}
+				]
+			},
+			"openai": {
+				"baseUrl": "https://api.openai.com",
+				"api": "openai",
+				"apiKey": "sk-from-models",
+				"models": [
+					{
+						"id": "gpt-4o",
+						"name": "GPT-4o"
+					}
+				]
+			},
+			"zhipu": {
+				"baseUrl": "https://open.bigmodel.cn/api/paas/v4",
+				"api": "openai",
+				"apiKey": "zhipu-key",
+				"models": []
+			}
+		}
+	}`
+
+	err = os.WriteFile(filepath.Join(agentsDir, "models.json"), []byte(modelsJSON), 0o644)
+	if err != nil {
+		t.Fatalf("failed to write models.json: %v", err)
+	}
+
+	providers := GetProviderConfigFromDir(tmpDir)
+	if len(providers) != 3 {
+		t.Errorf("expected 3 providers, got %d", len(providers))
+	}
+
+	if anthropic, ok := providers["anthropic"]; ok {
+		if anthropic.ApiKey != "sk-ant-from-models" {
+			t.Errorf("expected anthropic apiKey 'sk-ant-from-models', got '%s'", anthropic.ApiKey)
+		}
+		if anthropic.BaseUrl != "https://api.anthropic.com" {
+			t.Errorf("expected anthropic baseUrl 'https://api.anthropic.com', got '%s'", anthropic.BaseUrl)
+		}
+	} else {
+		t.Error("anthropic provider not found")
+	}
+
+	if openai, ok := providers["openai"]; ok {
+		if openai.ApiKey != "sk-from-models" {
+			t.Errorf("expected openai apiKey 'sk-from-models', got '%s'", openai.ApiKey)
+		}
+		if openai.BaseUrl != "https://api.openai.com" {
+			t.Errorf("expected openai baseUrl 'https://api.openai.com', got '%s'", openai.BaseUrl)
+		}
+	} else {
+		t.Error("openai provider not found")
+	}
+
+	if zhipu, ok := providers["zhipu"]; ok {
+		if zhipu.ApiKey != "zhipu-key" {
+			t.Errorf("expected zhipu apiKey 'zhipu-key', got '%s'", zhipu.ApiKey)
+		}
+		if zhipu.BaseUrl != "https://open.bigmodel.cn/api/paas/v4" {
+			t.Errorf("expected zhipu baseUrl 'https://open.bigmodel.cn/api/paas/v4', got '%s'", zhipu.BaseUrl)
+		}
+	} else {
+		t.Error("zhipu provider not found")
+	}
+}
+
+func TestGetProviderConfigFromDirNotExist(t *testing.T) {
+	providers := GetProviderConfigFromDir("/nonexistent/path")
+	if len(providers) != 0 {
+		t.Errorf("expected 0 providers for nonexistent path, got %d", len(providers))
+	}
+}
+
+func strPtr(s string) *string {
+	return &s
+}
+
+func boolPtr(b bool) *bool {
+	return &b
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_handler.go b/pkg/migrate/sources/openclaw/openclaw_handler.go
new file mode 100644
index 000000000..aaff119f1
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_handler.go
@@ -0,0 +1,148 @@
+package openclaw
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/migrate/internal"
+)
+
+var providerMapping = map[string]string{
+	"anthropic":  "anthropic",
+	"claude":     "anthropic",
+	"openai":     "openai",
+	"gpt":        "openai",
+	"groq":       "groq",
+	"ollama":     "ollama",
+	"openrouter": "openrouter",
+	"deepseek":   "deepseek",
+	"together":   "together",
+	"mistral":    "mistral",
+	"fireworks":  "fireworks",
+	"google":     "google",
+	"gemini":     "google",
+	"xai":        "xai",
+	"grok":       "xai",
+	"cerebras":   "cerebras",
+	"sambanova":  "sambanova",
+}
+
+type OpenclawHandler struct {
+	opts             Options
+	sourceConfigFile string
+	sourceWorkspace  string
+}
+
+type (
+	Options   = internal.Options
+	Action    = internal.Action
+	Result    = internal.Result
+	Operation = internal.Operation
+)
+
+func NewOpenclawHandler(opts Options) (Operation, error) {
+	home, err := resolveSourceHome(opts.SourceHome)
+	if err != nil {
+		return nil, err
+	}
+	opts.SourceHome = home
+
+	configFile, err := findSourceConfig(home)
+	if err != nil {
+		return nil, err
+	}
+	return &OpenclawHandler{
+		opts:             opts,
+		sourceWorkspace:  filepath.Join(opts.SourceHome, "workspace"),
+		sourceConfigFile: configFile,
+	}, nil
+}
+
+func (o *OpenclawHandler) GetSourceName() string {
+	return "openclaw"
+}
+
+func (o *OpenclawHandler) GetSourceHome() (string, error) {
+	return o.opts.SourceHome, nil
+}
+
+func (o *OpenclawHandler) GetSourceWorkspace() (string, error) {
+	return o.sourceWorkspace, nil
+}
+
+func (o *OpenclawHandler) GetSourceConfigFile() (string, error) {
+	return o.sourceConfigFile, nil
+}
+
+func (o *OpenclawHandler) GetMigrateableFiles() []string {
+	return migrateableFiles
+}
+
+func (o *OpenclawHandler) GetMigrateableDirs() []string {
+	return migrateableDirs
+}
+
+func (o *OpenclawHandler) ExecuteConfigMigration(srcConfigPath, dstConfigPath string) error {
+	openclawCfg, err := LoadOpenClawConfig(srcConfigPath)
+	if err != nil {
+		return err
+	}
+
+	picoCfg, warnings, err := openclawCfg.ConvertToPicoClaw(o.opts.SourceHome)
+	if err != nil {
+		return err
+	}
+
+	for _, w := range warnings {
+		fmt.Printf("  Warning: %s\n", w)
+	}
+
+	incoming := picoCfg.ToStandardConfig()
+	if err := os.MkdirAll(filepath.Dir(dstConfigPath), 0o755); err != nil {
+		return err
+	}
+
+	return config.SaveConfig(dstConfigPath, incoming)
+}
+
+func resolveSourceHome(override string) (string, error) {
+	if override != "" {
+		return internal.ExpandHome(override), nil
+	}
+	if envHome := os.Getenv("OPENCLAW_HOME"); envHome != "" {
+		return internal.ExpandHome(envHome), nil
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("resolving home directory: %w", err)
+	}
+	return filepath.Join(home, ".openclaw"), nil
+}
+
+func findSourceConfig(sourceHome string) (string, error) {
+	candidates := []string{
+		filepath.Join(sourceHome, "openclaw.json"),
+		filepath.Join(sourceHome, "config.json"),
+	}
+	for _, p := range candidates {
+		if _, err := os.Stat(p); err == nil {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("no config file found in %s (tried openclaw.json, config.json)", sourceHome)
+}
+
+func rewriteWorkspacePath(path string) string {
+	path = strings.Replace(path, ".openclaw", ".picoclaw", 1)
+	return path
+}
+
+func mapProvider(provider string) string {
+	if mapped, ok := providerMapping[strings.ToLower(provider)]; ok {
+		return mapped
+	}
+	return strings.ToLower(provider)
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_handler_test.go b/pkg/migrate/sources/openclaw/openclaw_handler_test.go
new file mode 100644
index 000000000..35bd09be0
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_handler_test.go
@@ -0,0 +1,247 @@
+package openclaw
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewOpenclawHandler(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, handler)
+}
+
+func TestNewOpenclawHandlerNoConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	_, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.Error(t, err)
+}
+
+func TestOpenclawHandlerGetSourceName(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+
+	assert.Equal(t, "openclaw", handler.GetSourceName())
+}
+
+func TestOpenclawHandlerGetSourceHome(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+
+	home, err := handler.GetSourceHome()
+	require.NoError(t, err)
+	assert.Equal(t, tmpDir, home)
+}
+
+func TestOpenclawHandlerGetSourceWorkspace(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+
+	workspace, err := handler.GetSourceWorkspace()
+	require.NoError(t, err)
+	assert.Equal(t, filepath.Join(tmpDir, "workspace"), workspace)
+}
+
+func TestOpenclawHandlerGetSourceConfigFile(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+
+	configFile, err := handler.GetSourceConfigFile()
+	require.NoError(t, err)
+	assert.Equal(t, configPath, configFile)
+}
+
+func TestOpenclawHandlerGetSourceConfigFileWithConfigJson(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+
+	configFile, err := handler.GetSourceConfigFile()
+	require.NoError(t, err)
+	assert.Equal(t, configPath, configFile)
+}
+
+func TestOpenclawHandlerGetMigrateableFiles(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+
+	files := handler.GetMigrateableFiles()
+	assert.NotEmpty(t, files)
+	assert.Contains(t, files, "AGENTS.md")
+	assert.Contains(t, files, "SOUL.md")
+	assert.Contains(t, files, "USER.md")
+}
+
+func TestOpenclawHandlerGetMigrateableDirs(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	handler, err := NewOpenclawHandler(Options{
+		SourceHome: tmpDir,
+	})
+	require.NoError(t, err)
+
+	dirs := handler.GetMigrateableDirs()
+	assert.NotEmpty(t, dirs)
+	assert.Contains(t, dirs, "memory")
+	assert.Contains(t, dirs, "skills")
+}
+
+func TestResolveSourceHome(t *testing.T) {
+	result, err := resolveSourceHome("/custom/path")
+	require.NoError(t, err)
+	assert.Equal(t, "/custom/path", result)
+}
+
+func TestResolveSourceHomeWithEnvVar(t *testing.T) {
+	t.Setenv("OPENCLAW_HOME", "/env/path")
+
+	result, err := resolveSourceHome("")
+	require.NoError(t, err)
+	assert.Equal(t, "/env/path", result)
+}
+
+func TestResolveSourceHomeWithTilde(t *testing.T) {
+	home, err := os.UserHomeDir()
+	require.NoError(t, err)
+
+	result, err := resolveSourceHome("~/openclaw")
+	require.NoError(t, err)
+	assert.Equal(t, filepath.Join(home, "openclaw"), result)
+}
+
+func TestFindSourceConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	result, err := findSourceConfig(tmpDir)
+	require.NoError(t, err)
+	assert.Equal(t, configPath, result)
+}
+
+func TestFindSourceConfigWithConfigJson(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+	err := os.WriteFile(configPath, []byte("{}"), 0o644)
+	require.NoError(t, err)
+
+	result, err := findSourceConfig(tmpDir)
+	require.NoError(t, err)
+	assert.Equal(t, configPath, result)
+}
+
+func TestFindSourceConfigNotFound(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	_, err := findSourceConfig(tmpDir)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "no config file found")
+}
+
+func TestMapProvider(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected string
+	}{
+		{"anthropic", "anthropic"},
+		{"claude", "anthropic"},
+		{"openai", "openai"},
+		{"gpt", "openai"},
+		{"groq", "groq"},
+		{"ollama", "ollama"},
+		{"openrouter", "openrouter"},
+		{"deepseek", "deepseek"},
+		{"together", "together"},
+		{"mistral", "mistral"},
+		{"fireworks", "fireworks"},
+		{"google", "google"},
+		{"gemini", "google"},
+		{"xai", "xai"},
+		{"grok", "xai"},
+		{"cerebras", "cerebras"},
+		{"sambanova", "sambanova"},
+		{"unknown", "unknown"},
+		{"", ""},
+	}
+
+	for _, tt := range tests {
+		result := mapProvider(tt.input)
+		assert.Equal(t, tt.expected, result, "mapProvider(%q)", tt.input)
+	}
+}
+
+func TestRewriteWorkspacePath(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected string
+	}{
+		{"~/.openclaw/workspace", "~/.picoclaw/workspace"},
+		{"/home/user/.openclaw/workspace", "/home/user/.picoclaw/workspace"},
+		{"/path/without/openclaw/change", "/path/without/openclaw/change"},
+		{"", ""},
+	}
+
+	for _, tt := range tests {
+		result := rewriteWorkspacePath(tt.input)
+		assert.Equal(t, tt.expected, result, "rewriteWorkspacePath(%q)", tt.input)
+	}
+}
diff --git a/pkg/providers/anthropic/provider.go b/pkg/providers/anthropic/provider.go
index 35f6b8f62..242ded175 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"
 }
@@ -113,7 +149,20 @@ func buildParams(
 	for _, msg := range messages {
 		switch msg.Role {
 		case "system":
-			system = append(system, anthropic.TextBlockParam{Text: msg.Content})
+			// Prefer structured SystemParts for per-block cache_control.
+			// This enables LLM-side KV cache reuse: the static block's prefix
+			// hash stays stable across requests while dynamic parts change freely.
+			if len(msg.SystemParts) > 0 {
+				for _, part := range msg.SystemParts {
+					block := anthropic.TextBlockParam{Text: part.Text}
+					if part.CacheControl != nil && part.CacheControl.Type == "ephemeral" {
+						block.CacheControl = anthropic.NewCacheControlEphemeralParam()
+					}
+					system = append(system, block)
+				}
+			} else {
+				system = append(system, anthropic.TextBlockParam{Text: msg.Content})
+			}
 		case "user":
 			if msg.ToolCallID != "" {
 				anthropicMessages = append(anthropicMessages,
@@ -131,7 +180,16 @@ 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))
+					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 {
@@ -151,8 +209,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,
 	}
@@ -169,9 +231,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 {
@@ -199,14 +332,18 @@ func translateTools(tools []ToolDefinition) []anthropic.ToolUnionParam {
 }
 
 func parseResponse(resp *anthropic.Message) *LLMResponse {
-	var content string
+	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 += tb.Text
+			content.WriteString(tb.Text)
 		case "tool_use":
 			tu := block.AsToolUse()
 			var args map[string]any
@@ -233,7 +370,8 @@ func parseResponse(resp *anthropic.Message) *LLMResponse {
 	}
 
 	return &LLMResponse{
-		Content:      content,
+		Content:      content.String(),
+		Reasoning:    reasoning.String(),
 		ToolCalls:    toolCalls,
 		FinishReason: finishReason,
 		Usage: &UsageInfo{
@@ -251,8 +389,8 @@ func normalizeBaseURL(apiBase string) string {
 	}
 
 	base = strings.TrimRight(base, "/")
-	if strings.HasSuffix(base, "/v1") {
-		base = strings.TrimSuffix(base, "/v1")
+	if before, ok := strings.CutSuffix(base, "/v1"); ok {
+		base = before
 	}
 	if base == "" {
 		return defaultBaseURL
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/antigravity_provider.go b/pkg/providers/antigravity_provider.go
index cff67c88c..8a1890212 100644
--- a/pkg/providers/antigravity_provider.go
+++ b/pkg/providers/antigravity_provider.go
@@ -404,64 +404,6 @@ type antigravityJSONResponse struct {
 	} `json:"usageMetadata"`
 }
 
-func (p *AntigravityProvider) parseJSONResponse(body []byte) (*LLMResponse, error) {
-	var resp antigravityJSONResponse
-	if err := json.Unmarshal(body, &resp); err != nil {
-		return nil, fmt.Errorf("parsing antigravity response: %w", err)
-	}
-
-	if len(resp.Candidates) == 0 {
-		return nil, fmt.Errorf("antigravity: no candidates in response")
-	}
-
-	candidate := resp.Candidates[0]
-	var contentParts []string
-	var toolCalls []ToolCall
-
-	for _, part := range candidate.Content.Parts {
-		if part.Text != "" {
-			contentParts = append(contentParts, part.Text)
-		}
-		if part.FunctionCall != nil {
-			argumentsJSON, _ := json.Marshal(part.FunctionCall.Args)
-			toolCalls = append(toolCalls, ToolCall{
-				ID:        fmt.Sprintf("call_%s_%d", part.FunctionCall.Name, time.Now().UnixNano()),
-				Name:      part.FunctionCall.Name,
-				Arguments: part.FunctionCall.Args,
-				Function: &FunctionCall{
-					Name:             part.FunctionCall.Name,
-					Arguments:        string(argumentsJSON),
-					ThoughtSignature: extractPartThoughtSignature(part.ThoughtSignature, part.ThoughtSignatureSnake),
-				},
-			})
-		}
-	}
-
-	finishReason := "stop"
-	if len(toolCalls) > 0 {
-		finishReason = "tool_calls"
-	}
-	if candidate.FinishReason == "MAX_TOKENS" {
-		finishReason = "length"
-	}
-
-	var usage *UsageInfo
-	if resp.UsageMetadata.TotalTokenCount > 0 {
-		usage = &UsageInfo{
-			PromptTokens:     resp.UsageMetadata.PromptTokenCount,
-			CompletionTokens: resp.UsageMetadata.CandidatesTokenCount,
-			TotalTokens:      resp.UsageMetadata.TotalTokenCount,
-		}
-	}
-
-	return &LLMResponse{
-		Content:      strings.Join(contentParts, ""),
-		ToolCalls:    toolCalls,
-		FinishReason: finishReason,
-		Usage:        usage,
-	}, nil
-}
-
 func (p *AntigravityProvider) parseSSEResponse(body string) (*LLMResponse, error) {
 	var contentParts []string
 	var toolCalls []ToolCall
@@ -698,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))
 	}
@@ -739,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/claude_cli_provider.go b/pkg/providers/claude_cli_provider.go
index 74ec33b98..6c4f6a767 100644
--- a/pkg/providers/claude_cli_provider.go
+++ b/pkg/providers/claude_cli_provider.go
@@ -100,44 +100,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..d4d648f5a 100644
--- a/pkg/providers/claude_cli_provider_test.go
+++ b/pkg/providers/claude_cli_provider_test.go
@@ -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_test.go b/pkg/providers/codex_cli_credentials_test.go
index 43b21700a..1e88c1120 100644
--- a/pkg/providers/codex_cli_credentials_test.go
+++ b/pkg/providers/codex_cli_credentials_test.go
@@ -43,12 +43,18 @@ func TestReadCodexCliCredentials_Valid(t *testing.T) {
 	}
 }
 
+// readCodexCliCredentialsErr calls ReadCodexCliCredentials and returns only the
+// error, for tests that only need to assert on failure.
+func readCodexCliCredentialsErr() error {
+	_, _, _, err := ReadCodexCliCredentials() //nolint:dogsled
+	return err
+}
+
 func TestReadCodexCliCredentials_MissingFile(t *testing.T) {
 	tmpDir := t.TempDir()
 	t.Setenv("CODEX_HOME", tmpDir)
 
-	_, _, _, err := ReadCodexCliCredentials()
-	if err == nil {
+	if err := readCodexCliCredentialsErr(); err == nil {
 		t.Fatal("expected error for missing auth.json")
 	}
 }
@@ -64,8 +70,7 @@ func TestReadCodexCliCredentials_EmptyToken(t *testing.T) {
 
 	t.Setenv("CODEX_HOME", tmpDir)
 
-	_, _, _, err := ReadCodexCliCredentials()
-	if err == nil {
+	if err := readCodexCliCredentialsErr(); err == nil {
 		t.Fatal("expected error for empty access_token")
 	}
 }
@@ -80,8 +85,7 @@ func TestReadCodexCliCredentials_InvalidJSON(t *testing.T) {
 
 	t.Setenv("CODEX_HOME", tmpDir)
 
-	_, _, _, err := ReadCodexCliCredentials()
-	if err == nil {
+	if err := readCodexCliCredentialsErr(); err == nil {
 		t.Fatal("expected error for invalid JSON")
 	}
 }
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_provider.go b/pkg/providers/codex_provider.go
index ecc983642..47618300a 100644
--- a/pkg/providers/codex_provider.go
+++ b/pkg/providers/codex_provider.go
@@ -106,8 +106,8 @@ func (p *CodexProvider) Chat(
 		if evt.Type == "response.completed" || evt.Type == "response.failed" || evt.Type == "response.incomplete" {
 			evtResp := evt.Response
 			if evtResp.ID != "" {
-				copy := evtResp
-				resp = &copy
+				evtRespCopy := evtResp
+				resp = &evtRespCopy
 			}
 		}
 	}
@@ -163,8 +163,8 @@ func resolveCodexModel(model string) (string, string) {
 		return codexDefaultModel, "empty model"
 	}
 
-	if strings.HasPrefix(m, "openai/") {
-		m = strings.TrimPrefix(m, "openai/")
+	if after, ok := strings.CutPrefix(m, "openai/"); ok {
+		m = after
 	} else if strings.Contains(m, "/") {
 		return codexDefaultModel, "non-openai model namespace"
 	}
@@ -208,6 +208,11 @@ func buildCodexParams(
 	for _, msg := range messages {
 		switch msg.Role {
 		case "system":
+			// Use the full concatenated system prompt (static + dynamic + summary)
+			// as instructions. This keeps behavior consistent with Anthropic and
+			// OpenAI-compat adapters where the complete system context lives in
+			// one place. Prefix caching is handled by prompt_cache_key below,
+			// not by splitting content across instructions vs input messages.
 			instructions = msg.Content
 		case "user":
 			if msg.ToolCallID != "" {
@@ -289,6 +294,13 @@ func buildCodexParams(
 		params.Instructions = openai.Opt(defaultCodexInstructions)
 	}
 
+	// Prompt caching: pass a stable cache key so OpenAI can bucket requests
+	// and reuse prefix KV cache across calls with the same key.
+	// See: https://platform.openai.com/docs/guides/prompt-caching
+	if cacheKey, ok := options["prompt_cache_key"].(string); ok && cacheKey != "" {
+		params.PromptCacheKey = openai.Opt(cacheKey)
+	}
+
 	if len(tools) > 0 || enableWebSearch {
 		params.Tools = translateToolsForCodex(tools, enableWebSearch)
 	}
diff --git a/pkg/providers/cooldown_test.go b/pkg/providers/cooldown_test.go
index 47f43ad5c..b517e7feb 100644
--- a/pkg/providers/cooldown_test.go
+++ b/pkg/providers/cooldown_test.go
@@ -138,7 +138,7 @@ func TestCooldown_FailureWindowReset(t *testing.T) {
 	ct, current := newTestTracker(now)
 
 	// 4 errors → 1h cooldown
-	for i := 0; i < 4; i++ {
+	for range 4 {
 		ct.MarkFailure("openai", FailoverRateLimit)
 		*current = current.Add(2 * time.Second) // small advance between errors
 	}
@@ -230,7 +230,7 @@ func TestCooldown_ConcurrentAccess(t *testing.T) {
 	ct := NewCooldownTracker()
 	var wg sync.WaitGroup
 
-	for i := 0; i < 100; i++ {
+	for range 100 {
 		wg.Add(3)
 		go func() {
 			defer wg.Done()
diff --git a/pkg/providers/error_classifier.go b/pkg/providers/error_classifier.go
index 9125f2f36..f9b6e9c71 100644
--- a/pkg/providers/error_classifier.go
+++ b/pkg/providers/error_classifier.go
@@ -6,6 +6,13 @@ import (
 	"strings"
 )
 
+// Common patterns in Go HTTP error messages
+var httpStatusPatterns = []*regexp.Regexp{
+	regexp.MustCompile(`status[:\s]+(\d{3})`),
+	regexp.MustCompile(`http[/\s]+\d*\.?\d*\s+(\d{3})`),
+	regexp.MustCompile(`\b([3-5]\d{2})\b`),
+}
+
 // errorPattern defines a single pattern (string or regex) for error classification.
 type errorPattern struct {
 	substring string
@@ -210,20 +217,13 @@ func classifyByMessage(msg string) FailoverReason {
 }
 
 // extractHTTPStatus extracts an HTTP status code from an error message.
-// Looks for patterns like "status: 429", "status 429", "HTTP 429", or standalone "429".
+// Looks for patterns like "status: 429", "status 429", "http/1.1 429", "http 429", or standalone "429".
 func extractHTTPStatus(msg string) int {
-	// Common patterns in Go HTTP error messages
-	patterns := []*regexp.Regexp{
-		regexp.MustCompile(`status[:\s]+(\d{3})`),
-		regexp.MustCompile(`HTTP[/\s]+\d*\.?\d*\s+(\d{3})`),
-	}
-
-	for _, p := range patterns {
+	for _, p := range httpStatusPatterns {
 		if m := p.FindStringSubmatch(msg); len(m) > 1 {
 			return parseDigits(m[1])
 		}
 	}
-
 	return 0
 }
 
diff --git a/pkg/providers/error_classifier_test.go b/pkg/providers/error_classifier_test.go
index 865aea57a..67d9af62b 100644
--- a/pkg/providers/error_classifier_test.go
+++ b/pkg/providers/error_classifier_test.go
@@ -305,7 +305,8 @@ func TestExtractHTTPStatus(t *testing.T) {
 	}{
 		{"status: 429 rate limited", 429},
 		{"status 401 unauthorized", 401},
-		{"HTTP/1.1 502 Bad Gateway", 502},
+		{"http/1.1 502 bad gateway", 502},
+		{"error 429", 429},
 		{"no status code here", 0},
 		{"random number 12345", 0},
 	}
diff --git a/pkg/providers/factory.go b/pkg/providers/factory.go
index 9a2c7a771..4a00b6e42 100644
--- a/pkg/providers/factory.go
+++ b/pkg/providers/factory.go
@@ -117,6 +117,33 @@ var standardProviderRegistry = map[string]providerDefaults{
 			return cfg.Providers.Moonshot.APIKey, cfg.Providers.Moonshot.APIBase, cfg.Providers.Moonshot.Proxy
 		},
 	},
+	"litellm": {
+		defaultBase: "http://localhost:4000/v1",
+		getConfig: func(cfg *config.Config) (string, string, string) {
+			return cfg.Providers.LiteLLM.APIKey, cfg.Providers.LiteLLM.APIBase, cfg.Providers.LiteLLM.Proxy
+		},
+		hasKey: func(cfg *config.Config) bool {
+			return cfg.Providers.LiteLLM.APIKey != "" || cfg.Providers.LiteLLM.APIBase != ""
+		},
+	},
+	"vivgrid": {
+		defaultBase: "https://api.vivgrid.com/v1",
+		getConfig: func(cfg *config.Config) (string, string, string) {
+			return cfg.Providers.Vivgrid.APIKey, cfg.Providers.Vivgrid.APIBase, cfg.Providers.Vivgrid.Proxy
+		},
+	},
+	"avian": {
+		defaultBase: "https://api.avian.io/v1",
+		getConfig: func(cfg *config.Config) (string, string, string) {
+			return cfg.Providers.Avian.APIKey, cfg.Providers.Avian.APIBase, cfg.Providers.Avian.Proxy
+		},
+	},
+	"minimax": {
+		defaultBase: "https://api.minimaxi.com/v1",
+		getConfig: func(cfg *config.Config) (string, string, string) {
+			return cfg.Providers.Minimax.APIKey, cfg.Providers.Minimax.APIBase, cfg.Providers.Minimax.Proxy
+		},
+	},
 }
 
 // providerNameAliases maps alternative provider names to their canonical names in the registry.
@@ -286,6 +313,33 @@ var modelInferenceRegistry = []modelInferenceEntry{
 			return applyStandardProvider(cfg, sel, standardProviderRegistry["mistral"])
 		},
 	},
+	// Vivgrid
+	{
+		matches: func(_, m string, cfg *config.Config) bool {
+			return strings.HasPrefix(m, "vivgrid/") && cfg.Providers.Vivgrid.APIKey != ""
+		},
+		apply: func(cfg *config.Config, sel *providerSelection) bool {
+			return applyStandardProvider(cfg, sel, standardProviderRegistry["vivgrid"])
+		},
+	},
+	// Minimax
+	{
+		matches: func(lm, m string, cfg *config.Config) bool {
+			return (strings.Contains(lm, "minimax") || strings.HasPrefix(m, "minimax/")) && cfg.Providers.Minimax.APIKey != ""
+		},
+		apply: func(cfg *config.Config, sel *providerSelection) bool {
+			return applyStandardProvider(cfg, sel, standardProviderRegistry["minimax"])
+		},
+	},
+	// Avian
+	{
+		matches: func(_, m string, cfg *config.Config) bool {
+			return strings.HasPrefix(m, "avian/") && cfg.Providers.Avian.APIKey != ""
+		},
+		apply: func(cfg *config.Config, sel *providerSelection) bool {
+			return applyStandardProvider(cfg, sel, standardProviderRegistry["avian"])
+		},
+	},
 	// VLLM (fallback if API base is configured)
 	{
 		matches: func(_, _ string, cfg *config.Config) bool {
@@ -298,7 +352,7 @@ var modelInferenceRegistry = []modelInferenceEntry{
 }
 
 func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
-	model := cfg.Agents.Defaults.Model
+	model := cfg.Agents.Defaults.GetModelName()
 	providerName := strings.ToLower(cfg.Agents.Defaults.Provider)
 	lowerModel := strings.ToLower(model)
 
diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index 7d5566eef..a798154cb 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -53,7 +53,7 @@ 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 protocols: openai, litellm, anthropic, antigravity, claude-cli, codex-cli, github-copilot
 // Returns the provider, the model ID (without protocol prefix), and any error.
 func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, error) {
 	if cfg == nil {
@@ -84,11 +84,18 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 		if apiBase == "" {
 			apiBase = getDefaultAPIBase(protocol)
 		}
-		return NewHTTPProviderWithMaxTokensField(cfg.APIKey, apiBase, cfg.Proxy, cfg.MaxTokensField), modelID, nil
+		return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+			cfg.APIKey,
+			apiBase,
+			cfg.Proxy,
+			cfg.MaxTokensField,
+			cfg.RequestTimeout,
+		), modelID, nil
 
-	case "openrouter", "groq", "zhipu", "gemini", "nvidia",
+	case "litellm", "openrouter", "groq", "zhipu", "gemini", "nvidia",
 		"ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
-		"volcengine", "vllm", "qwen", "mistral":
+		"vivgrid", "volcengine", "vllm", "qwen", "mistral", "avian",
+		"minimax":
 		// All other OpenAI-compatible HTTP providers
 		if cfg.APIKey == "" && cfg.APIBase == "" {
 			return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
@@ -97,7 +104,13 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 		if apiBase == "" {
 			apiBase = getDefaultAPIBase(protocol)
 		}
-		return NewHTTPProviderWithMaxTokensField(cfg.APIKey, apiBase, cfg.Proxy, cfg.MaxTokensField), modelID, nil
+		return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+			cfg.APIKey,
+			apiBase,
+			cfg.Proxy,
+			cfg.MaxTokensField,
+			cfg.RequestTimeout,
+		), modelID, nil
 
 	case "anthropic":
 		if cfg.AuthMethod == "oauth" || cfg.AuthMethod == "token" {
@@ -116,7 +129,13 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 		if cfg.APIKey == "" {
 			return nil, "", fmt.Errorf("api_key is required for anthropic protocol (model: %s)", cfg.Model)
 		}
-		return NewHTTPProviderWithMaxTokensField(cfg.APIKey, apiBase, cfg.Proxy, cfg.MaxTokensField), modelID, nil
+		return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+			cfg.APIKey,
+			apiBase,
+			cfg.Proxy,
+			cfg.MaxTokensField,
+			cfg.RequestTimeout,
+		), modelID, nil
 
 	case "antigravity":
 		return NewAntigravityProvider(), modelID, nil
@@ -162,6 +181,8 @@ 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 "groq":
 		return "https://api.groq.com/openai/v1"
 	case "zhipu":
@@ -180,6 +201,8 @@ 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":
@@ -188,6 +211,10 @@ func getDefaultAPIBase(protocol string) string {
 		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"
 	default:
 		return ""
 	}
diff --git a/pkg/providers/factory_provider_test.go b/pkg/providers/factory_provider_test.go
index 6b133101a..17bc55d25 100644
--- a/pkg/providers/factory_provider_test.go
+++ b/pkg/providers/factory_provider_test.go
@@ -6,7 +6,11 @@
 package providers
 
 import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/sipeed/picoclaw/pkg/config"
 )
@@ -104,6 +108,7 @@ func TestCreateProviderFromConfig_DefaultAPIBase(t *testing.T) {
 		{"groq", "groq"},
 		{"openrouter", "openrouter"},
 		{"cerebras", "cerebras"},
+		{"vivgrid", "vivgrid"},
 		{"qwen", "qwen"},
 		{"vllm", "vllm"},
 		{"deepseek", "deepseek"},
@@ -131,6 +136,32 @@ 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",
+		APIKey:    "test-key",
+		APIBase:   "http://localhost:4000/v1",
+	}
+
+	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_Anthropic(t *testing.T) {
 	cfg := &config.ModelConfig{
 		ModelName: "test-anthropic",
@@ -247,3 +278,42 @@ func TestCreateProviderFromConfig_EmptyModel(t *testing.T) {
 		t.Fatal("CreateProviderFromConfig() expected error for empty model")
 	}
 }
+
+func TestCreateProviderFromConfig_RequestTimeoutPropagation(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(1500 * time.Millisecond)
+		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-timeout",
+		Model:          "openai/gpt-4o",
+		APIBase:        server.URL,
+		RequestTimeout: 1,
+	}
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if modelID != "gpt-4o" {
+		t.Fatalf("modelID = %q, want %q", modelID, "gpt-4o")
+	}
+
+	_, err = provider.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		modelID,
+		nil,
+	)
+	if err == nil {
+		t.Fatal("Chat() expected timeout error, got nil")
+	}
+	errMsg := err.Error()
+	if !strings.Contains(errMsg, "context deadline exceeded") && !strings.Contains(errMsg, "Client.Timeout exceeded") {
+		t.Fatalf("Chat() error = %q, want timeout-related error", errMsg)
+	}
+}
diff --git a/pkg/providers/factory_test.go b/pkg/providers/factory_test.go
index 5680f23b3..36ccda4a1 100644
--- a/pkg/providers/factory_test.go
+++ b/pkg/providers/factory_test.go
@@ -17,6 +17,27 @@ func TestResolveProviderSelection(t *testing.T) {
 		wantProxy     string
 		wantErrSubstr string
 	}{
+		{
+			name: "explicit litellm provider uses configured base",
+			setup: func(cfg *config.Config) {
+				cfg.Agents.Defaults.Provider = "litellm"
+				cfg.Providers.LiteLLM.APIKey = "litellm-key"
+				cfg.Providers.LiteLLM.APIBase = "http://localhost:4000/v1"
+				cfg.Providers.LiteLLM.Proxy = "http://127.0.0.1:7890"
+			},
+			wantType:    providerTypeHTTPCompat,
+			wantAPIBase: "http://localhost:4000/v1",
+			wantProxy:   "http://127.0.0.1:7890",
+		},
+		{
+			name: "explicit litellm provider defaults base when only key is configured",
+			setup: func(cfg *config.Config) {
+				cfg.Agents.Defaults.Provider = "litellm"
+				cfg.Providers.LiteLLM.APIKey = "litellm-key"
+			},
+			wantType:    providerTypeHTTPCompat,
+			wantAPIBase: "http://localhost:4000/v1",
+		},
 		{
 			name: "explicit claude-cli provider routes to cli provider type",
 			setup: func(cfg *config.Config) {
@@ -67,6 +88,17 @@ func TestResolveProviderSelection(t *testing.T) {
 			wantAPIBase: "https://integrate.api.nvidia.com/v1",
 			wantProxy:   "http://127.0.0.1:7890",
 		},
+		{
+			name: "explicit vivgrid provider uses defaults",
+			setup: func(cfg *config.Config) {
+				cfg.Agents.Defaults.Provider = "vivgrid"
+				cfg.Providers.Vivgrid.APIKey = "vivgrid-key"
+				cfg.Providers.Vivgrid.Proxy = "http://127.0.0.1:7890"
+			},
+			wantType:    providerTypeHTTPCompat,
+			wantAPIBase: "https://api.vivgrid.com/v1",
+			wantProxy:   "http://127.0.0.1:7890",
+		},
 		{
 			name: "openrouter model uses openrouter defaults",
 			setup: func(cfg *config.Config) {
diff --git a/pkg/providers/fallback.go b/pkg/providers/fallback.go
index ecd451ec9..7ba563b66 100644
--- a/pkg/providers/fallback.go
+++ b/pkg/providers/fallback.go
@@ -43,11 +43,26 @@ func NewFallbackChain(cooldown *CooldownTracker) *FallbackChain {
 
 // ResolveCandidates parses model config into a deduplicated candidate list.
 func ResolveCandidates(cfg ModelConfig, defaultProvider string) []FallbackCandidate {
+	return ResolveCandidatesWithLookup(cfg, defaultProvider, nil)
+}
+
+func ResolveCandidatesWithLookup(
+	cfg ModelConfig,
+	defaultProvider string,
+	lookup func(raw string) (resolved string, ok bool),
+) []FallbackCandidate {
 	seen := make(map[string]bool)
 	var candidates []FallbackCandidate
 
 	addCandidate := func(raw string) {
-		ref := ParseModelRef(raw, defaultProvider)
+		candidateRaw := strings.TrimSpace(raw)
+		if lookup != nil {
+			if resolved, ok := lookup(candidateRaw); ok {
+				candidateRaw = resolved
+			}
+		}
+
+		ref := ParseModelRef(candidateRaw, defaultProvider)
 		if ref == nil {
 			return
 		}
diff --git a/pkg/providers/fallback_test.go b/pkg/providers/fallback_test.go
index e872c672e..1783ebcb5 100644
--- a/pkg/providers/fallback_test.go
+++ b/pkg/providers/fallback_test.go
@@ -17,12 +17,6 @@ func successRun(content string) func(ctx context.Context, provider, model string
 	}
 }
 
-func failRun(err error) func(ctx context.Context, provider, model string) (*LLMResponse, error) {
-	return func(ctx context.Context, provider, model string) (*LLMResponse, error) {
-		return nil, err
-	}
-}
-
 func TestFallback_SingleCandidate_Success(t *testing.T) {
 	ct := NewCooldownTracker()
 	fc := NewFallbackChain(ct)
@@ -459,6 +453,75 @@ func TestResolveCandidates_EmptyPrimary(t *testing.T) {
 	}
 }
 
+func TestResolveCandidatesWithLookup_AliasResolvesToNestedModel(t *testing.T) {
+	cfg := ModelConfig{
+		Primary:   "step-3.5-flash",
+		Fallbacks: nil,
+	}
+
+	lookup := func(raw string) (string, bool) {
+		if raw == "step-3.5-flash" {
+			return "openrouter/stepfun/step-3.5-flash:free", true
+		}
+		return "", false
+	}
+
+	candidates := ResolveCandidatesWithLookup(cfg, "", lookup)
+	if len(candidates) != 1 {
+		t.Fatalf("candidates = %d, want 1", len(candidates))
+	}
+	if candidates[0].Provider != "openrouter" {
+		t.Fatalf("provider = %q, want openrouter", candidates[0].Provider)
+	}
+	if candidates[0].Model != "stepfun/step-3.5-flash:free" {
+		t.Fatalf("model = %q, want stepfun/step-3.5-flash:free", candidates[0].Model)
+	}
+}
+
+func TestResolveCandidatesWithLookup_DeduplicateAfterLookup(t *testing.T) {
+	cfg := ModelConfig{
+		Primary:   "step-3.5-flash",
+		Fallbacks: []string{"openrouter/stepfun/step-3.5-flash:free"},
+	}
+
+	lookup := func(raw string) (string, bool) {
+		if raw == "step-3.5-flash" {
+			return "openrouter/stepfun/step-3.5-flash:free", true
+		}
+		return "", false
+	}
+
+	candidates := ResolveCandidatesWithLookup(cfg, "", lookup)
+	if len(candidates) != 1 {
+		t.Fatalf("candidates = %d, want 1", len(candidates))
+	}
+}
+
+func TestResolveCandidatesWithLookup_AliasWithoutProtocolUsesDefaultProvider(t *testing.T) {
+	cfg := ModelConfig{
+		Primary:   "glm-5",
+		Fallbacks: nil,
+	}
+
+	lookup := func(raw string) (string, bool) {
+		if raw == "glm-5" {
+			return "glm-5", true
+		}
+		return "", false
+	}
+
+	candidates := ResolveCandidatesWithLookup(cfg, "openai", lookup)
+	if len(candidates) != 1 {
+		t.Fatalf("candidates = %d, want 1", len(candidates))
+	}
+	if candidates[0].Provider != "openai" {
+		t.Fatalf("provider = %q, want openai", candidates[0].Provider)
+	}
+	if candidates[0].Model != "glm-5" {
+		t.Fatalf("model = %q, want glm-5", candidates[0].Model)
+	}
+}
+
 func TestFallbackExhaustedError_Message(t *testing.T) {
 	e := &FallbackExhaustedError{
 		Attempts: []FallbackAttempt{
diff --git a/pkg/providers/github_copilot_provider.go b/pkg/providers/github_copilot_provider.go
index 6124881f7..6d642b2b5 100644
--- a/pkg/providers/github_copilot_provider.go
+++ b/pkg/providers/github_copilot_provider.go
@@ -4,60 +4,84 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"sync"
 
 	copilot "github.com/github/copilot-sdk/go"
 )
 
 type GitHubCopilotProvider struct {
 	uri         string
-	connectMode string // `stdio` or `grpc``
+	connectMode string // "stdio" or "grpc"
 
+	client  *copilot.Client
 	session *copilot.Session
+
+	mu sync.Mutex
 }
 
 func NewGitHubCopilotProvider(uri string, connectMode string, model string) (*GitHubCopilotProvider, error) {
-	var session *copilot.Session
 	if connectMode == "" {
 		connectMode = "grpc"
 	}
-	switch connectMode {
 
+	switch connectMode {
 	case "stdio":
-		// todo
+		// TODO: Implement stdio mode for GitHub Copilot provider
+		// See https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md for details
+		return nil, fmt.Errorf("stdio mode not implemented for GitHub Copilot provider; please use 'grpc' mode instead")
 	case "grpc":
 		client := copilot.NewClient(&copilot.ClientOptions{
 			CLIUrl: uri,
 		})
 		if err := client.Start(context.Background()); err != nil {
 			return nil, fmt.Errorf(
-				"Can't connect to Github Copilot, https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#connecting-to-an-external-cli-server for details",
+				"can't connect to Github Copilot: %w; `https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md#connecting-to-an-external-cli-server` for details",
+				err,
 			)
 		}
-		defer client.Stop()
-		session, _ = client.CreateSession(context.Background(), &copilot.SessionConfig{
+
+		session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
 			Model: model,
 			Hooks: &copilot.SessionHooks{},
 		})
+		if err != nil {
+			client.Stop()
+			return nil, fmt.Errorf("create session failed: %w", err)
+		}
 
+		return &GitHubCopilotProvider{
+			uri:         uri,
+			connectMode: connectMode,
+			client:      client,
+			session:     session,
+		}, nil
+	default:
+		return nil, fmt.Errorf("unknown connect mode: %s", connectMode)
+	}
+}
+
+func (p *GitHubCopilotProvider) Close() {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.client != nil {
+		p.client.Stop()
+		p.client = nil
+		p.session = nil
 	}
-
-	return &GitHubCopilotProvider{
-		uri:         uri,
-		connectMode: connectMode,
-		session:     session,
-	}, nil
 }
 
-// Chat sends a chat request to GitHub Copilot
 func (p *GitHubCopilotProvider) Chat(
-	ctx context.Context, messages []Message, tools []ToolDefinition, model string, options map[string]any,
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
 ) (*LLMResponse, error) {
 	type tempMessage struct {
 		Role    string `json:"role"`
 		Content string `json:"content"`
 	}
 	out := make([]tempMessage, 0, len(messages))
-
 	for _, msg := range messages {
 		out = append(out, tempMessage{
 			Role:    msg.Role,
@@ -65,11 +89,32 @@ func (p *GitHubCopilotProvider) Chat(
 		})
 	}
 
-	fullcontent, _ := json.Marshal(out)
+	fullcontent, err := json.Marshal(out)
+	if err != nil {
+		return nil, fmt.Errorf("marshal messages: %w", err)
+	}
+	p.mu.Lock()
+	session := p.session
+	p.mu.Unlock()
 
-	content, _ := p.session.Send(ctx, copilot.MessageOptions{
+	if session == nil {
+		return nil, fmt.Errorf("provider closed")
+	}
+
+	resp, err := session.SendAndWait(ctx, copilot.MessageOptions{
 		Prompt: string(fullcontent),
 	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to send message to copilot: %w", err)
+	}
+
+	if resp == nil {
+		return nil, fmt.Errorf("empty response from copilot")
+	}
+	if resp.Data.Content == nil {
+		return nil, fmt.Errorf("no content in copilot response")
+	}
+	content := *resp.Data.Content
 
 	return &LLMResponse{
 		FinishReason: "stop",
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index d0c4344f3..5c328f418 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -8,6 +8,7 @@ package providers
 
 import (
 	"context"
+	"time"
 
 	"github.com/sipeed/picoclaw/pkg/providers/openai_compat"
 )
@@ -23,8 +24,21 @@ func NewHTTPProvider(apiKey, apiBase, proxy string) *HTTPProvider {
 }
 
 func NewHTTPProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *HTTPProvider {
+	return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(apiKey, apiBase, proxy, maxTokensField, 0)
+}
+
+func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+	apiKey, apiBase, proxy, maxTokensField string,
+	requestTimeoutSeconds int,
+) *HTTPProvider {
 	return &HTTPProvider{
-		delegate: openai_compat.NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField),
+		delegate: openai_compat.NewProvider(
+			apiKey,
+			apiBase,
+			proxy,
+			openai_compat.WithMaxTokensField(maxTokensField),
+			openai_compat.WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+		),
 	}
 }
 
diff --git a/pkg/providers/legacy_provider.go b/pkg/providers/legacy_provider.go
index eb13cec65..26905159f 100644
--- a/pkg/providers/legacy_provider.go
+++ b/pkg/providers/legacy_provider.go
@@ -16,11 +16,23 @@ import (
 // The old providers config is automatically converted to model_list during config loading.
 // Returns the provider, the model ID to use, and any error.
 func CreateProvider(cfg *config.Config) (LLMProvider, string, error) {
-	model := cfg.Agents.Defaults.Model
+	model := cfg.Agents.Defaults.GetModelName()
 
-	// Ensure model_list is populated (should be done by LoadConfig, but handle edge cases)
-	if len(cfg.ModelList) == 0 && cfg.HasProvidersConfig() {
-		cfg.ModelList = config.ConvertProvidersToModelList(cfg)
+	// 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
diff --git a/pkg/providers/openai_compat/provider.go b/pkg/providers/openai_compat/provider.go
index 236a048c4..0e8db7409 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"
@@ -25,6 +26,7 @@ type (
 	ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition
 	ExtraContent           = protocoltypes.ExtraContent
 	GoogleExtra            = protocoltypes.GoogleExtra
+	ReasoningDetail        = protocoltypes.ReasoningDetail
 )
 
 type Provider struct {
@@ -34,13 +36,27 @@ type Provider struct {
 	httpClient     *http.Client
 }
 
-func NewProvider(apiKey, apiBase, proxy string) *Provider {
-	return NewProviderWithMaxTokensField(apiKey, apiBase, proxy, "")
+type Option func(*Provider)
+
+const defaultRequestTimeout = 120 * time.Second
+
+func WithMaxTokensField(maxTokensField string) Option {
+	return func(p *Provider) {
+		p.maxTokensField = maxTokensField
+	}
 }
 
-func NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *Provider {
+func WithRequestTimeout(timeout time.Duration) Option {
+	return func(p *Provider) {
+		if timeout > 0 {
+			p.httpClient.Timeout = timeout
+		}
+	}
+}
+
+func NewProvider(apiKey, apiBase, proxy string, opts ...Option) *Provider {
 	client := &http.Client{
-		Timeout: 120 * time.Second,
+		Timeout: defaultRequestTimeout,
 	}
 
 	if proxy != "" {
@@ -54,12 +70,36 @@ func NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string
 		}
 	}
 
-	return &Provider{
-		apiKey:         apiKey,
-		apiBase:        strings.TrimRight(apiBase, "/"),
-		maxTokensField: maxTokensField,
-		httpClient:     client,
+	p := &Provider{
+		apiKey:     apiKey,
+		apiBase:    strings.TrimRight(apiBase, "/"),
+		httpClient: client,
 	}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(p)
+		}
+	}
+
+	return p
+}
+
+func NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *Provider {
+	return NewProvider(apiKey, apiBase, proxy, WithMaxTokensField(maxTokensField))
+}
+
+func NewProviderWithMaxTokensFieldAndTimeout(
+	apiKey, apiBase, proxy, maxTokensField string,
+	requestTimeoutSeconds int,
+) *Provider {
+	return NewProvider(
+		apiKey,
+		apiBase,
+		proxy,
+		WithMaxTokensField(maxTokensField),
+		WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+	)
 }
 
 func (p *Provider) Chat(
@@ -77,7 +117,7 @@ func (p *Provider) Chat(
 
 	requestBody := map[string]any{
 		"model":    model,
-		"messages": messages,
+		"messages": serializeMessages(messages),
 	}
 
 	if len(tools) > 0 {
@@ -111,6 +151,18 @@ 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.
+	if cacheKey, ok := options["prompt_cache_key"].(string); ok && cacheKey != "" {
+		if !strings.Contains(p.apiBase, "generativelanguage.googleapis.com") {
+			requestBody["prompt_cache_key"] = cacheKey
+		}
+	}
+
 	jsonData, err := json.Marshal(requestBody)
 	if err != nil {
 		return nil, fmt.Errorf("failed to marshal request: %w", err)
@@ -132,24 +184,102 @@ 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)
-	}
+	contentType := resp.Header.Get("Content-Type")
 
+	// Non-200: read a prefix to tell HTML error page apart from JSON error body.
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("API request failed:\n  Status: %d\n  Body:   %s", resp.StatusCode, string(body))
+		body, readErr := io.ReadAll(io.LimitReader(resp.Body, 256))
+		if readErr != nil {
+			return nil, fmt.Errorf("failed to read response: %w", readErr)
+		}
+		if looksLikeHTML(body, contentType) {
+			return nil, wrapHTMLResponseError(resp.StatusCode, body, contentType, p.apiBase)
+		}
+		return nil, fmt.Errorf(
+			"API request failed:\n  Status: %d\n  Body:   %s",
+			resp.StatusCode,
+			responsePreview(body, 128),
+		)
 	}
 
-	return parseResponse(body)
+	// Peek without consuming so the full stream reaches the JSON decoder.
+	reader := bufio.NewReader(resp.Body)
+	prefix, err := reader.Peek(256) // io.EOF/ErrBufferFull are normal; only real errors abort
+	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, p.apiBase)
+	}
+
+	out, err := parseResponse(reader)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse JSON response: %w", err)
+	}
+
+	return out, nil
 }
 
-func parseResponse(body []byte) (*LLMResponse, error) {
+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,
+	)
+}
+
+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"))
+}
+
+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
+}
+
+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 parseResponse(body io.Reader) (*LLMResponse, error) {
 	var apiResponse struct {
 		Choices []struct {
 			Message struct {
-				Content   string `json:"content"`
-				ToolCalls []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 {
@@ -168,8 +298,8 @@ func parseResponse(body []byte) (*LLMResponse, error) {
 		Usage *UsageInfo `json:"usage"`
 	}
 
-	if err := json.Unmarshal(body, &apiResponse); err != nil {
-		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	if err := json.NewDecoder(body).Decode(&apiResponse); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
 	}
 
 	if len(apiResponse.Choices) == 0 {
@@ -221,16 +351,85 @@ func parseResponse(body []byte) (*LLMResponse, error) {
 	}
 
 	return &LLMResponse{
-		Content:      choice.Message.Content,
-		ToolCalls:    toolCalls,
-		FinishReason: choice.FinishReason,
-		Usage:        apiResponse.Usage,
+		Content:          choice.Message.Content,
+		ReasoningContent: choice.Message.ReasoningContent,
+		Reasoning:        choice.Message.Reasoning,
+		ReasoningDetails: choice.Message.ReasoningDetails,
+		ToolCalls:        toolCalls,
+		FinishReason:     choice.FinishReason,
+		Usage:            apiResponse.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"`
+	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,
+					},
+				})
+			}
+		}
+
+		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 normalizeModel(model, apiBase string) string {
-	idx := strings.Index(model, "/")
-	if idx == -1 {
+	before, after, ok := strings.Cut(model, "/")
+	if !ok {
 		return model
 	}
 
@@ -238,10 +437,11 @@ func normalizeModel(model, apiBase string) string {
 		return model
 	}
 
-	prefix := strings.ToLower(model[:idx])
+	prefix := strings.ToLower(before)
 	switch prefix {
-	case "moonshot", "nvidia", "groq", "ollama", "deepseek", "google", "openrouter", "zhipu", "mistral":
-		return model[idx+1:]
+	case "litellm", "moonshot", "nvidia", "groq", "ollama", "deepseek", "google",
+		"openrouter", "zhipu", "mistral", "vivgrid", "minimax":
+		return after
 	default:
 		return model
 	}
diff --git a/pkg/providers/openai_compat/provider_test.go b/pkg/providers/openai_compat/provider_test.go
index 42f9d42ab..9a3a7acc5 100644
--- a/pkg/providers/openai_compat/provider_test.go
+++ b/pkg/providers/openai_compat/provider_test.go
@@ -1,11 +1,18 @@
 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/protocoltypes"
 )
 
 func TestProviderChat_UsesMaxCompletionTokensForGLM(t *testing.T) {
@@ -101,6 +108,100 @@ func TestProviderChat_ParsesToolCalls(t *testing.T) {
 	}
 }
 
+func TestProviderChat_ParsesReasoningContent(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":           "The answer is 2",
+						"reasoning_content": "Let me think step by step... 1+1=2",
+						"tool_calls": []map[string]any{
+							{
+								"id":   "call_1",
+								"type": "function",
+								"function": map[string]any{
+									"name":      "calculator",
+									"arguments": "{\"expr\":\"1+1\"}",
+								},
+							},
+						},
+					},
+					"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: "1+1=?"}}, nil, "kimi-k2.5", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+	if out.ReasoningContent != "Let me think step by step... 1+1=2" {
+		t.Fatalf("ReasoningContent = %q, want %q", out.ReasoningContent, "Let me think step by step... 1+1=2")
+	}
+	if out.Content != "The answer is 2" {
+		t.Fatalf("Content = %q, want %q", out.Content, "The answer is 2")
+	}
+	if len(out.ToolCalls) != 1 {
+		t.Fatalf("len(ToolCalls) = %d, want 1", len(out.ToolCalls))
+	}
+}
+
+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)
@@ -114,6 +215,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
 
@@ -155,12 +382,17 @@ func TestProviderChat_StripsMoonshotPrefixAndNormalizesKimiTemperature(t *testin
 	}
 }
 
-func TestProviderChat_StripsGroqAndOllamaPrefixes(t *testing.T) {
+func TestProviderChat_StripsGroqOllamaDeepseekVivgridPrefixes(t *testing.T) {
 	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",
@@ -176,6 +408,11 @@ func TestProviderChat_StripsGroqAndOllamaPrefixes(t *testing.T) {
 			input:     "deepseek/deepseek-chat",
 			wantModel: "deepseek-chat",
 		},
+		{
+			name:      "strips vivgrid prefix",
+			input:     "vivgrid/auto",
+			wantModel: "auto",
+		},
 	}
 
 	for _, tt := range tests {
@@ -280,4 +517,173 @@ 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")
+	}
+}
+
+func TestProvider_RequestTimeoutDefault(t *testing.T) {
+	p := NewProviderWithMaxTokensFieldAndTimeout("key", "https://example.com/v1", "", "", 0)
+	if p.httpClient.Timeout != defaultRequestTimeout {
+		t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, defaultRequestTimeout)
+	}
+}
+
+func TestProvider_RequestTimeoutOverride(t *testing.T) {
+	p := NewProviderWithMaxTokensFieldAndTimeout("key", "https://example.com/v1", "", "", 300)
+	if p.httpClient.Timeout != 300*time.Second {
+		t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, 300*time.Second)
+	}
+}
+
+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" {
+		t.Fatalf("maxTokensField = %q, want %q", p.maxTokensField, "max_completion_tokens")
+	}
+}
+
+func TestProvider_FunctionalOptionRequestTimeout(t *testing.T) {
+	p := NewProvider("key", "https://example.com/v1", "", WithRequestTimeout(45*time.Second))
+	if p.httpClient.Timeout != 45*time.Second {
+		t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, 45*time.Second)
+	}
+}
+
+func TestProvider_FunctionalOptionRequestTimeoutNonPositive(t *testing.T) {
+	p := NewProvider("key", "https://example.com/v1", "", WithRequestTimeout(-1*time.Second))
+	if p.httpClient.Timeout != defaultRequestTimeout {
+		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 := 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 := 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 := 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"])
+	}
+}
+
+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 := 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 5e1c6d397..194c1aa6f 100644
--- a/pkg/providers/protocoltypes/types.go
+++ b/pkg/providers/protocoltypes/types.go
@@ -25,10 +25,20 @@ type FunctionCall struct {
 }
 
 type LLMResponse struct {
-	Content      string     `json:"content"`
-	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
-	FinishReason string     `json:"finish_reason"`
-	Usage        *UsageInfo `json:"usage,omitempty"`
+	Content          string            `json:"content"`
+	ReasoningContent string            `json:"reasoning_content,omitempty"`
+	ToolCalls        []ToolCall        `json:"tool_calls,omitempty"`
+	FinishReason     string            `json:"finish_reason"`
+	Usage            *UsageInfo        `json:"usage,omitempty"`
+	Reasoning        string            `json:"reasoning"`
+	ReasoningDetails []ReasoningDetail `json:"reasoning_details"`
+}
+
+type ReasoningDetail struct {
+	Format string `json:"format"`
+	Index  int    `json:"index"`
+	Type   string `json:"type"`
+	Text   string `json:"text"`
 }
 
 type UsageInfo struct {
@@ -37,11 +47,29 @@ type UsageInfo struct {
 	TotalTokens      int `json:"total_tokens"`
 }
 
+// CacheControl marks a content block for LLM-side prefix caching.
+// Currently only "ephemeral" is supported (used by Anthropic).
+type CacheControl struct {
+	Type string `json:"type"` // "ephemeral"
+}
+
+// ContentBlock represents a structured segment of a system message.
+// Adapters that understand SystemParts can use these blocks to set
+// per-block cache control (e.g. Anthropic's cache_control: ephemeral).
+type ContentBlock struct {
+	Type         string        `json:"type"` // "text"
+	Text         string        `json:"text"`
+	CacheControl *CacheControl `json:"cache_control,omitempty"`
+}
+
 type Message struct {
-	Role       string     `json:"role"`
-	Content    string     `json:"content"`
-	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
-	ToolCallID string     `json:"tool_call_id,omitempty"`
+	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"`
+	ToolCallID       string         `json:"tool_call_id,omitempty"`
 }
 
 type ToolDefinition struct {
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 9a4ee3533..175e99aa1 100644
--- a/pkg/providers/types.go
+++ b/pkg/providers/types.go
@@ -17,6 +17,8 @@ type (
 	ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition
 	ExtraContent           = protocoltypes.ExtraContent
 	GoogleExtra            = protocoltypes.GoogleExtra
+	ContentBlock           = protocoltypes.ContentBlock
+	CacheControl           = protocoltypes.CacheControl
 )
 
 type LLMProvider interface {
@@ -30,6 +32,18 @@ type LLMProvider interface {
 	GetDefaultModel() string
 }
 
+type StatefulProvider interface {
+	LLMProvider
+	Close()
+}
+
+// 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
+}
+
 // FailoverReason classifies why an LLM request failed for fallback decisions.
 type FailoverReason string
 
diff --git a/pkg/routing/agent_id_test.go b/pkg/routing/agent_id_test.go
index 050fe0645..f9a65c969 100644
--- a/pkg/routing/agent_id_test.go
+++ b/pkg/routing/agent_id_test.go
@@ -1,6 +1,9 @@
 package routing
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestNormalizeAgentID_Empty(t *testing.T) {
 	if got := NormalizeAgentID(""); got != DefaultAgentID {
@@ -57,11 +60,11 @@ func TestNormalizeAgentID_AllInvalid(t *testing.T) {
 }
 
 func TestNormalizeAgentID_TruncatesAt64(t *testing.T) {
-	long := ""
-	for i := 0; i < 100; i++ {
-		long += "a"
+	var long strings.Builder
+	for range 100 {
+		long.WriteString("a")
 	}
-	got := NormalizeAgentID(long)
+	got := NormalizeAgentID(long.String())
 	if len(got) > MaxAgentIDLength {
 		t.Errorf("length = %d, want <= %d", len(got), MaxAgentIDLength)
 	}
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/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/routing/session_key.go b/pkg/routing/session_key.go
index e12f0d1d8..eab592bec 100644
--- a/pkg/routing/session_key.go
+++ b/pkg/routing/session_key.go
@@ -163,6 +163,15 @@ func resolveLinkedPeerID(identityLinks map[string][]string, channel, peerID stri
 		scopedCandidate := fmt.Sprintf("%s:%s", channel, strings.ToLower(peerID))
 		candidates[scopedCandidate] = true
 	}
+
+	// If peerID is already in canonical "platform:id" format, also add the
+	// bare ID part as a candidate for backward compatibility with identity_links
+	// that use raw IDs (e.g. "123" instead of "telegram:123").
+	if idx := strings.Index(rawCandidate, ":"); idx > 0 && idx < len(rawCandidate)-1 {
+		bareID := rawCandidate[idx+1:]
+		candidates[bareID] = true
+	}
+
 	if len(candidates) == 0 {
 		return ""
 	}
diff --git a/pkg/routing/session_key_test.go b/pkg/routing/session_key_test.go
index 81e4ce018..ad7a1ca02 100644
--- a/pkg/routing/session_key_test.go
+++ b/pkg/routing/session_key_test.go
@@ -115,6 +115,51 @@ func TestBuildAgentPeerSessionKey_IdentityLink(t *testing.T) {
 	}
 }
 
+func TestResolveLinkedPeerID_CanonicalPeerID(t *testing.T) {
+	// When peerID is already in canonical "platform:id" format,
+	// it should match identity_links that use the bare ID.
+	links := map[string][]string{
+		"john": {"123"},
+	}
+	got := resolveLinkedPeerID(links, "telegram", "telegram:123")
+	if got != "john" {
+		t.Errorf("resolveLinkedPeerID with canonical peerID = %q, want %q", got, "john")
+	}
+}
+
+func TestResolveLinkedPeerID_CanonicalInLinks(t *testing.T) {
+	// When identity_links contain canonical IDs and peerID is canonical too
+	links := map[string][]string{
+		"john": {"telegram:123", "discord:456"},
+	}
+	got := resolveLinkedPeerID(links, "telegram", "telegram:123")
+	if got != "john" {
+		t.Errorf("resolveLinkedPeerID canonical in links = %q, want %q", got, "john")
+	}
+}
+
+func TestResolveLinkedPeerID_BarePeerIDMatchesCanonicalLink(t *testing.T) {
+	// When peerID is bare "123" and links have "telegram:123",
+	// the scoped candidate "telegram:123" should match.
+	links := map[string][]string{
+		"john": {"telegram:123"},
+	}
+	got := resolveLinkedPeerID(links, "telegram", "123")
+	if got != "john" {
+		t.Errorf("resolveLinkedPeerID bare peer matches canonical link = %q, want %q", got, "john")
+	}
+}
+
+func TestResolveLinkedPeerID_NoMatch(t *testing.T) {
+	links := map[string][]string{
+		"john": {"telegram:123"},
+	}
+	got := resolveLinkedPeerID(links, "discord", "999")
+	if got != "" {
+		t.Errorf("resolveLinkedPeerID no match = %q, want empty", got)
+	}
+}
+
 func TestParseAgentSessionKey_Valid(t *testing.T) {
 	parsed := ParseAgentSessionKey("agent:sales:telegram:direct:user123")
 	if parsed == nil {
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 3210509df..c9f19f25d 100644
--- a/pkg/skills/installer.go
+++ b/pkg/skills/installer.go
@@ -2,27 +2,21 @@ package skills
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
 	"os"
 	"path/filepath"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 type SkillInstaller struct {
 	workspace string
 }
 
-type AvailableSkill struct {
-	Name        string   `json:"name"`
-	Repository  string   `json:"repository"`
-	Description string   `json:"description"`
-	Author      string   `json:"author"`
-	Tags        []string `json:"tags"`
-}
-
 func NewSkillInstaller(workspace string) *SkillInstaller {
 	return &SkillInstaller{
 		workspace: workspace,
@@ -44,7 +38,7 @@ func (si *SkillInstaller) InstallFromGitHub(ctx context.Context, repo string) er
 		return fmt.Errorf("failed to create request: %w", err)
 	}
 
-	resp, err := client.Do(req)
+	resp, err := utils.DoRequestWithRetry(client, req)
 	if err != nil {
 		return fmt.Errorf("failed to fetch skill: %w", err)
 	}
@@ -64,7 +58,9 @@ func (si *SkillInstaller) InstallFromGitHub(ctx context.Context, repo string) er
 	}
 
 	skillPath := filepath.Join(skillDir, "SKILL.md")
-	if err := os.WriteFile(skillPath, body, 0o644); err != nil {
+
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	if err := fileutil.WriteFileAtomic(skillPath, body, 0o600); err != nil {
 		return fmt.Errorf("failed to write skill file: %w", err)
 	}
 
@@ -84,35 +80,3 @@ func (si *SkillInstaller) Uninstall(skillName string) error {
 
 	return nil
 }
-
-func (si *SkillInstaller) ListAvailableSkills(ctx context.Context) ([]AvailableSkill, error) {
-	url := "https://raw.githubusercontent.com/sipeed/picoclaw-skills/main/skills.json"
-
-	client := &http.Client{Timeout: 15 * time.Second}
-	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
-	}
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("failed to fetch skills list: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("failed to fetch skills list: HTTP %d", resp.StatusCode)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var skills []AvailableSkill
-	if err := json.Unmarshal(body, &skills); err != nil {
-		return nil, fmt.Errorf("failed to parse skills list: %w", err)
-	}
-
-	return skills, nil
-}
diff --git a/pkg/skills/loader.go b/pkg/skills/loader.go
index 5749d8983..30d84635a 100644
--- a/pkg/skills/loader.go
+++ b/pkg/skills/loader.go
@@ -13,7 +13,11 @@ import (
 	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
-var namePattern = regexp.MustCompile(`^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$`)
+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)*`)
+)
 
 const (
 	MaxNameLength        = 64
@@ -60,6 +64,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,
@@ -236,7 +263,7 @@ func (sl *SkillsLoader) parseSimpleYAML(content string) map[string]string {
 	normalized := strings.ReplaceAll(content, "\r\n", "\n")
 	normalized = strings.ReplaceAll(normalized, "\r", "\n")
 
-	for _, line := range strings.Split(normalized, "\n") {
+	for line := range strings.SplitSeq(normalized, "\n") {
 		line = strings.TrimSpace(line)
 		if line == "" || strings.HasPrefix(line, "#") {
 			continue
@@ -257,10 +284,7 @@ func (sl *SkillsLoader) parseSimpleYAML(content string) map[string]string {
 
 func (sl *SkillsLoader) extractFrontmatter(content string) string {
 	// Support \n (Unix), \r\n (Windows), and \r (classic Mac) line endings for frontmatter blocks
-	// (?s) enables DOTALL so . matches newlines;
-	// ^--- at start, then ... --- at start of line, honoring all three line ending types
-	re := regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---`)
-	match := re.FindStringSubmatch(content)
+	match := reFrontmatter.FindStringSubmatch(content)
 	if len(match) > 1 {
 		return match[1]
 	}
@@ -268,12 +292,7 @@ func (sl *SkillsLoader) extractFrontmatter(content string) string {
 }
 
 func (sl *SkillsLoader) stripFrontmatter(content string) string {
-	// Support \n (Unix), \r\n (Windows), and \r (classic Mac) line endings for frontmatter blocks
-	// (?s) enables DOTALL so . matches newlines;
-	// ^--- at start, then ... --- at start of line, honoring all three line ending types
-	// Match zero or more trailing line endings after closing --- (handles both with and without blank lines)
-	re := regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---(?:\r\n|\n|\r)*`)
-	return re.ReplaceAllString(content, "")
+	return reStripFrontmatter.ReplaceAllString(content, "")
 }
 
 func escapeXML(s string) string {
diff --git a/pkg/skills/loader_test.go b/pkg/skills/loader_test.go
index 9428bea62..31619f9c2 100644
--- a/pkg/skills/loader_test.go
+++ b/pkg/skills/loader_test.go
@@ -326,3 +326,19 @@ 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)
+}
diff --git a/pkg/skills/search_cache.go b/pkg/skills/search_cache.go
index 5d7d2797e..1686e3f98 100644
--- a/pkg/skills/search_cache.go
+++ b/pkg/skills/search_cache.go
@@ -1,7 +1,7 @@
 package skills
 
 import (
-	"sort"
+	"slices"
 	"strings"
 	"sync"
 	"time"
@@ -183,7 +183,7 @@ func buildTrigrams(s string) []uint32 {
 	}
 
 	// Sort and Deduplication
-	sort.Slice(trigrams, func(i, j int) bool { return trigrams[i] < trigrams[j] })
+	slices.Sort(trigrams)
 	n := 1
 	for i := 1; i < len(trigrams); i++ {
 		if trigrams[i] != trigrams[i-1] {
diff --git a/pkg/skills/search_cache_test.go b/pkg/skills/search_cache_test.go
index 816bdfb93..6bbb0e6eb 100644
--- a/pkg/skills/search_cache_test.go
+++ b/pkg/skills/search_cache_test.go
@@ -153,7 +153,7 @@ func TestSearchCacheConcurrency(t *testing.T) {
 
 	// Concurrent writes
 	go func() {
-		for i := 0; i < 100; i++ {
+		for i := range 100 {
 			cache.Put("query-write-"+string(rune('a'+i%26)), []SearchResult{{Slug: "x"}})
 		}
 		done <- struct{}{}
@@ -161,7 +161,7 @@ func TestSearchCacheConcurrency(t *testing.T) {
 
 	// Concurrent reads
 	go func() {
-		for i := 0; i < 100; i++ {
+		for range 100 {
 			cache.Get("query-write-a")
 		}
 		done <- struct{}{}
diff --git a/pkg/state/state.go b/pkg/state/state.go
index 1a92f82ed..57f371f12 100644
--- a/pkg/state/state.go
+++ b/pkg/state/state.go
@@ -8,6 +8,8 @@ import (
 	"path/filepath"
 	"sync"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
 // State represents the persistent state for a workspace.
@@ -38,7 +40,9 @@ func NewManager(workspace string) *Manager {
 	oldStateFile := filepath.Join(workspace, "state.json")
 
 	// Create state directory if it doesn't exist
-	os.MkdirAll(stateDir, 0o755)
+	if err := os.MkdirAll(stateDir, 0o755); err != nil {
+		log.Fatalf("[FATAL] state: failed to create state directory: %v", err)
+	}
 
 	sm := &Manager{
 		workspace: workspace,
@@ -52,13 +56,17 @@ func NewManager(workspace string) *Manager {
 		if data, err := os.ReadFile(oldStateFile); err == nil {
 			if err := json.Unmarshal(data, sm.state); err == nil {
 				// Migrate to new location
-				sm.saveAtomic()
+				if err := sm.saveAtomic(); err != nil {
+					log.Printf("[WARN] state: failed to save state: %v", err)
+				}
 				log.Printf("[INFO] state: migrated state from %s to %s", oldStateFile, stateFile)
 			}
 		}
 	} else {
 		// Load from new location
-		sm.load()
+		if err := sm.load(); err != nil {
+			log.Printf("[WARN] state: failed to load state: %v", err)
+		}
 	}
 
 	return sm
@@ -124,33 +132,20 @@ func (sm *Manager) GetTimestamp() time.Time {
 // saveAtomic performs an atomic save using temp file + rename.
 // This ensures that the state file is never corrupted:
 // 1. Write to a temp file
-// 2. Rename temp file to target (atomic on POSIX systems)
-// 3. If rename fails, cleanup the temp file
+// 2. Sync to disk (critical for SD cards/flash storage)
+// 3. Rename temp file to target (atomic on POSIX systems)
+// 4. If rename fails, cleanup the temp file
 //
 // Must be called with the lock held.
 func (sm *Manager) saveAtomic() error {
-	// Create temp file in the same directory as the target
-	tempFile := sm.stateFile + ".tmp"
-
-	// Marshal state to JSON
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	// Using 0o600 (owner read/write only) for secure default permissions.
 	data, err := json.MarshalIndent(sm.state, "", "  ")
 	if err != nil {
 		return fmt.Errorf("failed to marshal state: %w", err)
 	}
 
-	// Write to temp file
-	if err := os.WriteFile(tempFile, data, 0o644); err != nil {
-		return fmt.Errorf("failed to write temp file: %w", err)
-	}
-
-	// Atomic rename from temp to target
-	if err := os.Rename(tempFile, sm.stateFile); err != nil {
-		// Cleanup temp file if rename fails
-		os.Remove(tempFile)
-		return fmt.Errorf("failed to rename temp file: %w", err)
-	}
-
-	return nil
+	return fileutil.WriteFileAtomic(sm.stateFile, data, 0o600)
 }
 
 // load loads the state from disk.
diff --git a/pkg/state/state_test.go b/pkg/state/state_test.go
index f717a5bb4..e5e116ef6 100644
--- a/pkg/state/state_test.go
+++ b/pkg/state/state_test.go
@@ -2,8 +2,10 @@ package state
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"testing"
 )
@@ -135,7 +137,7 @@ func TestConcurrentAccess(t *testing.T) {
 
 	// Test concurrent writes
 	done := make(chan bool, 10)
-	for i := 0; i < 10; i++ {
+	for i := range 10 {
 		go func(idx int) {
 			channel := fmt.Sprintf("channel-%d", idx)
 			sm.SetLastChannel(channel)
@@ -144,7 +146,7 @@ func TestConcurrentAccess(t *testing.T) {
 	}
 
 	// Wait for all goroutines to complete
-	for i := 0; i < 10; i++ {
+	for range 10 {
 		<-done
 	}
 
@@ -214,3 +216,39 @@ func TestNewManager_EmptyWorkspace(t *testing.T) {
 		t.Error("Expected zero timestamp for new state")
 	}
 }
+
+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.
+	if os.Getenv("BE_CRASHER") == "1" {
+		tmpDir := os.Getenv("CRASH_DIR")
+
+		statePath := filepath.Join(tmpDir, "state")
+		if err := os.WriteFile(statePath, []byte("I'm a file, not a folder"), 0o644); err != nil {
+			fmt.Printf("setup failed: %v", err)
+			os.Exit(0)
+		}
+
+		NewManager(tmpDir)
+		os.Exit(0)
+	}
+
+	tmpDir, err := os.MkdirTemp("", "state-crash-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cmd := exec.Command(os.Args[0], "-test.run=TestNewManager_MkdirFailureCrashes")
+	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
+	}
+
+	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 562fffc84..6af0aa9e1 100644
--- a/pkg/tools/cron.go
+++ b/pkg/tools/cron.go
@@ -3,7 +3,7 @@ package tools
 import (
 	"context"
 	"fmt"
-	"sync"
+	"strings"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
@@ -23,9 +23,6 @@ type CronTool struct {
 	executor    JobExecutor
 	msgBus      *bus.MessageBus
 	execTool    *ExecTool
-	channel     string
-	chatID      string
-	mu          sync.RWMutex
 }
 
 // NewCronTool creates a new CronTool
@@ -33,15 +30,19 @@ type CronTool struct {
 func NewCronTool(
 	cronService *cron.CronService, executor JobExecutor, msgBus *bus.MessageBus, workspace string, restrict bool,
 	execTimeout time.Duration, config *config.Config,
-) *CronTool {
-	execTool := NewExecToolWithConfig(workspace, restrict, config)
+) (*CronTool, error) {
+	execTool, err := NewExecToolWithConfig(workspace, restrict, config)
+	if err != nil {
+		return nil, fmt.Errorf("unable to configure exec tool: %w", err)
+	}
+
 	execTool.SetTimeout(execTimeout)
 	return &CronTool{
 		cronService: cronService,
 		executor:    executor,
 		msgBus:      msgBus,
 		execTool:    execTool,
-	}
+	}, nil
 }
 
 // Name returns the tool name
@@ -97,14 +98,6 @@ func (t *CronTool) Parameters() map[string]any {
 	}
 }
 
-// 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)
@@ -114,7 +107,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":
@@ -128,11 +121,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.")
@@ -150,6 +141,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
@@ -218,7 +215,8 @@ func (t *CronTool) listJobs() *ToolResult {
 		return SilentResult("No scheduled jobs")
 	}
 
-	result := "Scheduled jobs:\n"
+	var result strings.Builder
+	result.WriteString("Scheduled jobs:\n")
 	for _, j := range jobs {
 		var scheduleInfo string
 		if j.Schedule.Kind == "every" && j.Schedule.EveryMS != nil {
@@ -230,10 +228,10 @@ func (t *CronTool) listJobs() *ToolResult {
 		} else {
 			scheduleInfo = "unknown"
 		}
-		result += fmt.Sprintf("- %s (id: %s, %s)\n", j.Name, j.ID, scheduleInfo)
+		result.WriteString(fmt.Sprintf("- %s (id: %s, %s)\n", j.Name, j.ID, scheduleInfo))
 	}
 
-	return SilentResult(result)
+	return SilentResult(result.String())
 }
 
 func (t *CronTool) removeJob(args map[string]any) *ToolResult {
@@ -294,7 +292,9 @@ func (t *CronTool) ExecuteJob(ctx context.Context, job *cron.CronJob) string {
 			output = fmt.Sprintf("Scheduled command '%s' executed:\n%s", job.Payload.Command, result.ForLLM)
 		}
 
-		t.msgBus.PublishOutbound(bus.OutboundMessage{
+		pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer pubCancel()
+		t.msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
 			Channel: channel,
 			ChatID:  chatID,
 			Content: output,
@@ -304,7 +304,9 @@ func (t *CronTool) ExecuteJob(ctx context.Context, job *cron.CronJob) string {
 
 	// If deliver=true, send message directly without agent processing
 	if job.Payload.Deliver {
-		t.msgBus.PublishOutbound(bus.OutboundMessage{
+		pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer pubCancel()
+		t.msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
 			Channel: channel,
 			ChatID:  chatID,
 			Content: job.Payload.Message,
diff --git a/pkg/tools/edit.go b/pkg/tools/edit.go
index d3ab267bf..d5bebf4a2 100644
--- a/pkg/tools/edit.go
+++ b/pkg/tools/edit.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"regexp"
 	"strings"
 )
 
@@ -15,14 +16,12 @@ type EditFileTool struct {
 }
 
 // NewEditFileTool creates a new EditFileTool with optional directory restriction.
-func NewEditFileTool(workspace string, restrict bool) *EditFileTool {
-	var fs fileSystem
-	if restrict {
-		fs = &sandboxFs{workspace: workspace}
-	} else {
-		fs = &hostFs{}
+func NewEditFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *EditFileTool {
+	var patterns []*regexp.Regexp
+	if len(allowPaths) > 0 {
+		patterns = allowPaths[0]
 	}
-	return &EditFileTool{fs: fs}
+	return &EditFileTool{fs: buildFs(workspace, restrict, patterns)}
 }
 
 func (t *EditFileTool) Name() string {
@@ -80,14 +79,12 @@ type AppendFileTool struct {
 	fs fileSystem
 }
 
-func NewAppendFileTool(workspace string, restrict bool) *AppendFileTool {
-	var fs fileSystem
-	if restrict {
-		fs = &sandboxFs{workspace: workspace}
-	} else {
-		fs = &hostFs{}
+func NewAppendFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *AppendFileTool {
+	var patterns []*regexp.Regexp
+	if len(allowPaths) > 0 {
+		patterns = allowPaths[0]
 	}
-	return &AppendFileTool{fs: fs}
+	return &AppendFileTool{fs: buildFs(workspace, restrict, patterns)}
 }
 
 func (t *AppendFileTool) Name() string {
diff --git a/pkg/tools/filesystem.go b/pkg/tools/filesystem.go
index 37db8b4ae..6b1cb1475 100644
--- a/pkg/tools/filesystem.go
+++ b/pkg/tools/filesystem.go
@@ -2,14 +2,24 @@ 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"
 )
 
+const MaxReadFileSize = 64 * 1024 // 64KB limit to avoid context overflow
+
 // validatePath ensures the given path is within the workspace if restrict is true.
 func validatePath(path, workspace string, restrict bool) (string, error) {
 	if workspace == "" {
@@ -82,17 +92,30 @@ func isWithinWorkspace(candidate, workspace string) bool {
 }
 
 type ReadFileTool struct {
-	fs fileSystem
+	fs      fileSystem
+	maxSize int64
 }
 
-func NewReadFileTool(workspace string, restrict bool) *ReadFileTool {
-	var fs fileSystem
-	if restrict {
-		fs = &sandboxFs{workspace: workspace}
-	} else {
-		fs = &hostFs{}
+func NewReadFileTool(
+	workspace string,
+	restrict bool,
+	maxReadFileSize int,
+	allowPaths ...[]*regexp.Regexp,
+) *ReadFileTool {
+	var patterns []*regexp.Regexp
+	if len(allowPaths) > 0 {
+		patterns = allowPaths[0]
+	}
+
+	maxSize := int64(maxReadFileSize)
+	if maxSize <= 0 {
+		maxSize = MaxReadFileSize
+	}
+
+	return &ReadFileTool{
+		fs:      buildFs(workspace, restrict, patterns),
+		maxSize: maxSize,
 	}
-	return &ReadFileTool{fs: fs}
 }
 
 func (t *ReadFileTool) Name() string {
@@ -100,7 +123,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 {
@@ -109,7 +132,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"},
@@ -122,25 +155,183 @@ 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 {
 	fs fileSystem
 }
 
-func NewWriteFileTool(workspace string, restrict bool) *WriteFileTool {
-	var fs fileSystem
-	if restrict {
-		fs = &sandboxFs{workspace: workspace}
-	} else {
-		fs = &hostFs{}
+func NewWriteFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *WriteFileTool {
+	var patterns []*regexp.Regexp
+	if len(allowPaths) > 0 {
+		patterns = allowPaths[0]
 	}
-	return &WriteFileTool{fs: fs}
+	return &WriteFileTool{fs: buildFs(workspace, restrict, patterns)}
 }
 
 func (t *WriteFileTool) Name() string {
@@ -190,14 +381,12 @@ type ListDirTool struct {
 	fs fileSystem
 }
 
-func NewListDirTool(workspace string, restrict bool) *ListDirTool {
-	var fs fileSystem
-	if restrict {
-		fs = &sandboxFs{workspace: workspace}
-	} else {
-		fs = &hostFs{}
+func NewListDirTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *ListDirTool {
+	var patterns []*regexp.Regexp
+	if len(allowPaths) > 0 {
+		patterns = allowPaths[0]
 	}
-	return &ListDirTool{fs: fs}
+	return &ListDirTool{fs: buildFs(workspace, restrict, patterns)}
 }
 
 func (t *ListDirTool) Name() string {
@@ -252,6 +441,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.
@@ -276,25 +466,23 @@ func (h *hostFs) ReadDir(path string) ([]os.DirEntry, error) {
 }
 
 func (h *hostFs) WriteFile(path string, data []byte) error {
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("failed to create parent directories: %w", err)
-	}
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	// Using 0o600 (owner read/write only) for secure default permissions.
+	return fileutil.WriteFileAtomic(path, data, 0o600)
+}
 
-	// We use a "write-then-rename" pattern here to ensure an atomic write.
-	// This prevents the target file from being left in a truncated or partial state
-	// if the operation is interrupted, as the rename operation is atomic on Linux.
-	tmpPath := fmt.Sprintf("%s.%d.tmp", path, time.Now().UnixNano())
-	if err := os.WriteFile(tmpPath, data, 0o644); err != nil {
-		os.Remove(tmpPath) // Ensure cleanup of partial/empty temp file
-		return fmt.Errorf("failed to write temp file: %w", err)
+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)
 	}
-
-	if err := os.Rename(tmpPath, path); err != nil {
-		os.Remove(tmpPath)
-		return fmt.Errorf("failed to replace original file: %w", err)
-	}
-	return nil
+	return f, nil
 }
 
 // sandboxFs is a sandboxed fileSystem that operates within a strictly defined workspace using os.Root.
@@ -351,20 +539,46 @@ func (r *sandboxFs) WriteFile(path string, data []byte) error {
 			}
 		}
 
-		// We use a "write-then-rename" pattern here to ensure an atomic write.
-		// This prevents the target file from being left in a truncated or partial state
-		// if the operation is interrupted, as the rename operation is atomic on Linux.
-		tmpRelPath := fmt.Sprintf("%s.%d.tmp", relPath, time.Now().UnixNano())
+		// Use atomic write pattern with explicit sync for flash storage reliability.
+		// Using 0o600 (owner read/write only) for secure default permissions.
+		tmpRelPath := fmt.Sprintf(".tmp-%d-%d", os.Getpid(), time.Now().UnixNano())
 
-		if err := root.WriteFile(tmpRelPath, data, 0o644); err != nil {
-			root.Remove(tmpRelPath) // Ensure cleanup of partial/empty temp file
-			return fmt.Errorf("failed to write to temp file: %w", err)
+		tmpFile, err := root.OpenFile(tmpRelPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
+		if err != nil {
+			root.Remove(tmpRelPath)
+			return fmt.Errorf("failed to open temp file: %w", err)
+		}
+
+		if _, err := tmpFile.Write(data); err != nil {
+			tmpFile.Close()
+			root.Remove(tmpRelPath)
+			return fmt.Errorf("failed to write temp file: %w", err)
+		}
+
+		// CRITICAL: Force sync to storage medium before rename.
+		// This ensures data is physically written to disk, not just cached.
+		if err := tmpFile.Sync(); err != nil {
+			tmpFile.Close()
+			root.Remove(tmpRelPath)
+			return fmt.Errorf("failed to sync temp file: %w", err)
+		}
+
+		if err := tmpFile.Close(); err != nil {
+			root.Remove(tmpRelPath)
+			return fmt.Errorf("failed to close temp file: %w", err)
 		}
 
 		if err := root.Rename(tmpRelPath, relPath); err != nil {
 			root.Remove(tmpRelPath)
 			return fmt.Errorf("failed to rename temp file over target: %w", err)
 		}
+
+		// Sync directory to ensure rename is durable
+		if dirFile, err := root.Open("."); err == nil {
+			_ = dirFile.Sync()
+			dirFile.Close()
+		}
+
 		return nil
 	})
 }
@@ -382,6 +596,84 @@ 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 {
+	sandbox  *sandboxFs
+	host     hostFs
+	patterns []*regexp.Regexp
+}
+
+func (w *whitelistFs) matches(path string) bool {
+	for _, p := range w.patterns {
+		if p.MatchString(path) {
+			return true
+		}
+	}
+	return false
+}
+
+func (w *whitelistFs) ReadFile(path string) ([]byte, error) {
+	if w.matches(path) {
+		return w.host.ReadFile(path)
+	}
+	return w.sandbox.ReadFile(path)
+}
+
+func (w *whitelistFs) WriteFile(path string, data []byte) error {
+	if w.matches(path) {
+		return w.host.WriteFile(path, data)
+	}
+	return w.sandbox.WriteFile(path, data)
+}
+
+func (w *whitelistFs) ReadDir(path string) ([]os.DirEntry, error) {
+	if w.matches(path) {
+		return w.host.ReadDir(path)
+	}
+	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 {
+	if !restrict {
+		return &hostFs{}
+	}
+	sandbox := &sandboxFs{workspace: workspace}
+	if len(patterns) > 0 {
+		return &whitelistFs{sandbox: sandbox, patterns: patterns}
+	}
+	return sandbox
+}
+
 // Helper to get a safe relative path for os.Root usage
 func getSafeRelPath(workspace, path string) (string, error) {
 	if workspace == "" {
diff --git a/pkg/tools/filesystem_test.go b/pkg/tools/filesystem_test.go
index 6f896e22d..0bbf6caf0 100644
--- a/pkg/tools/filesystem_test.go
+++ b/pkg/tools/filesystem_test.go
@@ -5,6 +5,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"testing"
 
@@ -17,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,
@@ -44,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",
@@ -58,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)
 	}
 }
@@ -270,7 +271,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,
 	})
@@ -288,7 +289,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()
@@ -486,3 +487,160 @@ func TestRootRW_Write(t *testing.T) {
 	assert.NoError(t, err)
 	assert.Equal(t, newData, content)
 }
+
+// TestWhitelistFs_AllowsMatchingPaths verifies that whitelistFs allows access to
+// paths matching the whitelist patterns while blocking non-matching paths.
+func TestWhitelistFs_AllowsMatchingPaths(t *testing.T) {
+	workspace := t.TempDir()
+	outsideDir := t.TempDir()
+	outsideFile := filepath.Join(outsideDir, "allowed.txt")
+	os.WriteFile(outsideFile, []byte("outside content"), 0o644)
+
+	// Pattern allows access to the outsideDir.
+	patterns := []*regexp.Regexp{regexp.MustCompile(`^` + regexp.QuoteMeta(outsideDir))}
+
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize, patterns)
+
+	// Read from whitelisted path should succeed.
+	result := tool.Execute(context.Background(), map[string]any{"path": outsideFile})
+	if result.IsError {
+		t.Errorf("expected whitelisted path to be readable, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "outside content") {
+		t.Errorf("expected file content, got: %s", result.ForLLM)
+	}
+
+	// Read from non-whitelisted path outside workspace should fail.
+	otherDir := t.TempDir()
+	otherFile := filepath.Join(otherDir, "blocked.txt")
+	os.WriteFile(otherFile, []byte("blocked"), 0o644)
+
+	result = tool.Execute(context.Background(), map[string]any{"path": otherFile})
+	if !result.IsError {
+		t.Errorf("expected non-whitelisted path to be blocked, 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/i2c.go b/pkg/tools/i2c.go
index 0387a26d3..779b1d5a7 100644
--- a/pkg/tools/i2c.go
+++ b/pkg/tools/i2c.go
@@ -117,13 +117,19 @@ func (t *I2CTool) detect() *ToolResult {
 	return SilentResult(fmt.Sprintf("Found %d I2C bus(es):\n%s", len(buses), string(result)))
 }
 
+// Helper functions for I2C operations (used by platform-specific implementations)
+
 // isValidBusID checks that a bus identifier is a simple number (prevents path injection)
+//
+//nolint:unused // Used by i2c_linux.go
 func isValidBusID(id string) bool {
 	matched, _ := regexp.MatchString(`^\d+$`, id)
 	return matched
 }
 
 // parseI2CAddress extracts and validates an I2C address from args
+//
+//nolint:unused // Used by i2c_linux.go
 func parseI2CAddress(args map[string]any) (int, *ToolResult) {
 	addrFloat, ok := args["address"].(float64)
 	if !ok {
@@ -137,6 +143,8 @@ func parseI2CAddress(args map[string]any) (int, *ToolResult) {
 }
 
 // parseI2CBus extracts and validates an I2C bus from args
+//
+//nolint:unused // Used by i2c_linux.go
 func parseI2CBus(args map[string]any) (string, *ToolResult) {
 	bus, ok := args["bus"].(string)
 	if !ok || bus == "" {
diff --git a/pkg/tools/mcp_tool.go b/pkg/tools/mcp_tool.go
new file mode 100644
index 000000000..6e53cf354
--- /dev/null
+++ b/pkg/tools/mcp_tool.go
@@ -0,0 +1,246 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"hash/fnv"
+	"strings"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// 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
+}
+
+// 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,
+	}
+}
+
+// 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))
+	}
+
+	// Extract text content from result
+	output := extractContentText(result.Content)
+
+	return &ToolResult{
+		ForLLM:  output,
+		IsError: false,
+	}
+}
+
+// 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, v.Text)
+		case *mcp.ImageContent:
+			// For images, just indicate that an image was returned
+			parts = append(parts, fmt.Sprintf("[Image: %s]", v.MIMEType))
+		default:
+			// For other content types, use string representation
+			parts = append(parts, fmt.Sprintf("[Content: %T]", v))
+		}
+	}
+	return strings.Join(parts, "\n")
+}
diff --git a/pkg/tools/mcp_tool_test.go b/pkg/tools/mcp_tool_test.go
new file mode 100644
index 000000000..95bb0f992
--- /dev/null
+++ b/pkg/tools/mcp_tool_test.go
@@ -0,0 +1,492 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// 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"])
+	}
+}
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/registry.go b/pkg/tools/registry.go
index 6ecb8ae7c..0635f47d7 100644
--- a/pkg/tools/registry.go
+++ b/pkg/tools/registry.go
@@ -3,35 +3,151 @@ package tools
 import (
 	"context"
 	"fmt"
+	"sort"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"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
 }
 
 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
+	}
+	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,
+	}
+	r.version.Add(1)
+	logger.DebugCF("tools", "Registered hidden tool", map[string]any{"name": name})
+}
+
+// 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 {
@@ -39,8 +155,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,
@@ -63,22 +180,23 @@ 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)
-	}
+	// 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 AsyncTool and callback is provided, set callback
-	if asyncTool, ok := tool.(AsyncTool); ok && asyncCallback != nil {
-		asyncTool.SetCallback(asyncCallback)
-		logger.DebugCF("tool", "Async callback injected",
+	// 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()
+	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)
 	}
-
-	start := time.Now()
-	result := tool.Execute(ctx, args)
 	duration := time.Since(start)
 
 	// Log based on result type
@@ -107,13 +225,33 @@ func (r *ToolRegistry) ExecuteWithContext(
 	return result
 }
 
+// sortedToolNames returns tool names in sorted order for deterministic iteration.
+// This is critical for KV cache stability: non-deterministic map iteration would
+// produce different system prompts and tool definitions on each call, invalidating
+// the LLM's prefix cache even when no tools have changed.
+func (r *ToolRegistry) sortedToolNames() []string {
+	names := make([]string, 0, len(r.tools))
+	for name := range r.tools {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
 func (r *ToolRegistry) GetDefinitions() []map[string]any {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
 
-	definitions := make([]map[string]any, 0, len(r.tools))
-	for _, tool := range r.tools {
-		definitions = append(definitions, ToolToSchema(tool))
+	sorted := r.sortedToolNames()
+	definitions := make([]map[string]any, 0, len(sorted))
+	for _, name := range sorted {
+		entry := r.tools[name]
+
+		if !entry.IsCore && entry.TTL <= 0 {
+			continue
+		}
+
+		definitions = append(definitions, ToolToSchema(r.tools[name].Tool))
 	}
 	return definitions
 }
@@ -124,9 +262,16 @@ func (r *ToolRegistry) ToProviderDefs() []providers.ToolDefinition {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
 
-	definitions := make([]providers.ToolDefinition, 0, len(r.tools))
-	for _, tool := range r.tools {
-		schema := ToolToSchema(tool)
+	sorted := r.sortedToolNames()
+	definitions := make([]providers.ToolDefinition, 0, len(sorted))
+	for _, name := range sorted {
+		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)
@@ -155,11 +300,7 @@ func (r *ToolRegistry) List() []string {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
 
-	names := make([]string, 0, len(r.tools))
-	for name := range r.tools {
-		names = append(names, name)
-	}
-	return names
+	return r.sortedToolNames()
 }
 
 // Count returns the number of registered tools.
@@ -175,9 +316,16 @@ func (r *ToolRegistry) GetSummaries() []string {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
 
-	summaries := make([]string, 0, len(r.tools))
-	for _, tool := range r.tools {
-		summaries = append(summaries, fmt.Sprintf("- `%s` - %s", tool.Name(), tool.Description()))
+	sorted := r.sortedToolNames()
+	summaries := make([]string, 0, len(sorted))
+	for _, name := range sorted {
+		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
 }
diff --git a/pkg/tools/registry_test.go b/pkg/tools/registry_test.go
index 8ae13b20c..92d7d5abd 100644
--- a/pkg/tools/registry_test.go
+++ b/pkg/tools/registry_test.go
@@ -25,24 +25,24 @@ 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
 }
 
 // --- helpers ---
@@ -136,34 +136,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 +189,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")
 	}
@@ -329,7 +339,7 @@ func TestToolRegistry_ConcurrentAccess(t *testing.T) {
 	r := NewToolRegistry()
 	var wg sync.WaitGroup
 
-	for i := 0; i < 50; i++ {
+	for i := range 50 {
 		wg.Add(1)
 		go func(n int) {
 			defer wg.Done()
diff --git a/pkg/tools/result.go b/pkg/tools/result.go
index b13055b1c..cab833284 100644
--- a/pkg/tools/result.go
+++ b/pkg/tools/result.go
@@ -30,6 +30,10 @@ type ToolResult struct {
 	// Err is the underlying error (not JSON serialized).
 	// Used for internal error handling and logging.
 	Err error `json:"-"`
+
+	// Media contains media store refs produced by this tool.
+	// When non-empty, the agent will publish these as OutboundMediaMessage.
+	Media []string `json:"media,omitempty"`
 }
 
 // NewToolResult creates a basic ToolResult with content for the LLM.
@@ -120,6 +124,19 @@ func UserResult(content string) *ToolResult {
 	}
 }
 
+// MediaResult creates a ToolResult with media refs for the user.
+// The agent will publish these refs as OutboundMediaMessage.
+//
+// Example:
+//
+//	result := MediaResult("Image generated successfully", []string{"media://abc123"})
+func MediaResult(forLLM string, mediaRefs []string) *ToolResult {
+	return &ToolResult{
+		ForLLM: forLLM,
+		Media:  mediaRefs,
+	}
+}
+
 // MarshalJSON implements custom JSON serialization.
 // The Err field is excluded from JSON output via the json:"-" tag.
 func (tr *ToolResult) MarshalJSON() ([]byte, error) {
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..1a03e58ed
--- /dev/null
+++ b/pkg/tools/send_file.go
@@ -0,0 +1,150 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"mime"
+	"os"
+	"path/filepath"
+	"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
+
+	defaultChannel string
+	defaultChatID  string
+}
+
+func NewSendFileTool(workspace string, restrict bool, maxFileSize int, store media.MediaStore) *SendFileTool {
+	if maxFileSize <= 0 {
+		maxFileSize = config.DefaultMaxMediaSize
+	}
+	return &SendFileTool{
+		workspace:   workspace,
+		restrict:    restrict,
+		maxFileSize: maxFileSize,
+		mediaStore:  store,
+	}
+}
+
+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 := validatePath(path, t.workspace, t.restrict)
+	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",
+	}, 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})
+}
+
+// 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..08d129674
--- /dev/null
+++ b/pkg/tools/send_file_test.go
@@ -0,0 +1,176 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"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])
+	}
+}
+
+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 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 6883172cd..b8a811d03 100644
--- a/pkg/tools/shell.go
+++ b/pkg/tools/shell.go
@@ -21,65 +21,89 @@ type ExecTool struct {
 	timeout             time.Duration
 	denyPatterns        []*regexp.Regexp
 	allowPatterns       []*regexp.Regexp
+	customAllowPatterns []*regexp.Regexp
 	restrictToWorkspace bool
 }
 
-var defaultDenyPatterns = []*regexp.Regexp{
-	regexp.MustCompile(`\brm\s+-[rf]{1,2}\b`),
-	regexp.MustCompile(`\bdel\s+/[fq]\b`),
-	regexp.MustCompile(`\brmdir\s+/s\b`),
-	regexp.MustCompile(`\b(format|mkfs|diskpart)\b\s`), // Match disk wiping commands (must be followed by space/args)
-	regexp.MustCompile(`\bdd\s+if=`),
-	regexp.MustCompile(`>\s*/dev/sd[a-z]\b`), // Block writes to disk devices (but allow /dev/null)
-	regexp.MustCompile(`\b(shutdown|reboot|poweroff)\b`),
-	regexp.MustCompile(`:\(\)\s*\{.*\};\s*:`),
-	regexp.MustCompile(`\$\([^)]+\)`),
-	regexp.MustCompile(`\$\{[^}]+\}`),
-	regexp.MustCompile("`[^`]+`"),
-	regexp.MustCompile(`\|\s*sh\b`),
-	regexp.MustCompile(`\|\s*bash\b`),
-	regexp.MustCompile(`;\s*rm\s+-[rf]`),
-	regexp.MustCompile(`&&\s*rm\s+-[rf]`),
-	regexp.MustCompile(`\|\|\s*rm\s+-[rf]`),
-	regexp.MustCompile(`>\s*/dev/null\s*>&?\s*\d?`),
-	regexp.MustCompile(`<<\s*EOF`),
-	regexp.MustCompile(`\$\(\s*cat\s+`),
-	regexp.MustCompile(`\$\(\s*curl\s+`),
-	regexp.MustCompile(`\$\(\s*wget\s+`),
-	regexp.MustCompile(`\$\(\s*which\s+`),
-	regexp.MustCompile(`\bsudo\b`),
-	regexp.MustCompile(`\bchmod\s+[0-7]{3,4}\b`),
-	regexp.MustCompile(`\bchown\b`),
-	regexp.MustCompile(`\bpkill\b`),
-	regexp.MustCompile(`\bkillall\b`),
-	regexp.MustCompile(`\bkill\s+-[9]\b`),
-	regexp.MustCompile(`\bcurl\b.*\|\s*(sh|bash)`),
-	regexp.MustCompile(`\bwget\b.*\|\s*(sh|bash)`),
-	regexp.MustCompile(`\bnpm\s+install\s+-g\b`),
-	regexp.MustCompile(`\bpip\s+install\s+--user\b`),
-	regexp.MustCompile(`\bapt\s+(install|remove|purge)\b`),
-	regexp.MustCompile(`\byum\s+(install|remove)\b`),
-	regexp.MustCompile(`\bdnf\s+(install|remove)\b`),
-	regexp.MustCompile(`\bdocker\s+run\b`),
-	regexp.MustCompile(`\bdocker\s+exec\b`),
-	regexp.MustCompile(`\bgit\s+push\b`),
-	regexp.MustCompile(`\bgit\s+force\b`),
-	regexp.MustCompile(`\bssh\b.*@`),
-	regexp.MustCompile(`\beval\b`),
-	regexp.MustCompile(`\bsource\s+.*\.sh\b`),
-}
+var (
+	defaultDenyPatterns = []*regexp.Regexp{
+		regexp.MustCompile(`\brm\s+-[rf]{1,2}\b`),
+		regexp.MustCompile(`\bdel\s+/[fq]\b`),
+		regexp.MustCompile(`\brmdir\s+/s\b`),
+		// Match disk wiping commands (must be followed by space/args)
+		regexp.MustCompile(
+			`\b(format|mkfs|diskpart)\b\s`,
+		),
+		regexp.MustCompile(`\bdd\s+if=`),
+		// Block writes to block devices (all common naming schemes).
+		regexp.MustCompile(
+			`>\s*/dev/(sd[a-z]|hd[a-z]|vd[a-z]|xvd[a-z]|nvme\d|mmcblk\d|loop\d|dm-\d|md\d|sr\d|nbd\d)`,
+		),
+		regexp.MustCompile(`\b(shutdown|reboot|poweroff)\b`),
+		regexp.MustCompile(`:\(\)\s*\{.*\};\s*:`),
+		regexp.MustCompile(`\$\([^)]+\)`),
+		regexp.MustCompile(`\$\{[^}]+\}`),
+		regexp.MustCompile("`[^`]+`"),
+		regexp.MustCompile(`\|\s*sh\b`),
+		regexp.MustCompile(`\|\s*bash\b`),
+		regexp.MustCompile(`;\s*rm\s+-[rf]`),
+		regexp.MustCompile(`&&\s*rm\s+-[rf]`),
+		regexp.MustCompile(`\|\|\s*rm\s+-[rf]`),
+		regexp.MustCompile(`<<\s*EOF`),
+		regexp.MustCompile(`\$\(\s*cat\s+`),
+		regexp.MustCompile(`\$\(\s*curl\s+`),
+		regexp.MustCompile(`\$\(\s*wget\s+`),
+		regexp.MustCompile(`\$\(\s*which\s+`),
+		regexp.MustCompile(`\bsudo\b`),
+		regexp.MustCompile(`\bchmod\s+[0-7]{3,4}\b`),
+		regexp.MustCompile(`\bchown\b`),
+		regexp.MustCompile(`\bpkill\b`),
+		regexp.MustCompile(`\bkillall\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`),
+		regexp.MustCompile(`\bpip\s+install\s+--user\b`),
+		regexp.MustCompile(`\bapt\s+(install|remove|purge)\b`),
+		regexp.MustCompile(`\byum\s+(install|remove)\b`),
+		regexp.MustCompile(`\bdnf\s+(install|remove)\b`),
+		regexp.MustCompile(`\bdocker\s+run\b`),
+		regexp.MustCompile(`\bdocker\s+exec\b`),
+		regexp.MustCompile(`\bgit\s+push\b`),
+		regexp.MustCompile(`\bgit\s+force\b`),
+		regexp.MustCompile(`\bssh\b.*@`),
+		regexp.MustCompile(`\beval\b`),
+		regexp.MustCompile(`\bsource\s+.*\.sh\b`),
+	}
 
-func NewExecTool(workingDir string, restrict bool) *ExecTool {
+	// absolutePathPattern matches absolute file paths in commands (Unix and Windows).
+	absolutePathPattern = regexp.MustCompile(`[A-Za-z]:\\[^\\\"']+|/[^\s\"']+`)
+
+	// safePaths are kernel pseudo-devices that are always safe to reference in
+	// commands, regardless of workspace restriction. They contain no user data
+	// and cannot cause destructive writes.
+	safePaths = map[string]bool{
+		"/dev/null":    true,
+		"/dev/zero":    true,
+		"/dev/random":  true,
+		"/dev/urandom": true,
+		"/dev/stdin":   true,
+		"/dev/stdout":  true,
+		"/dev/stderr":  true,
+	}
+)
+
+func NewExecTool(workingDir string, restrict bool) (*ExecTool, error) {
 	return NewExecToolWithConfig(workingDir, restrict, nil)
 }
 
-func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Config) *ExecTool {
+func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Config) (*ExecTool, error) {
 	denyPatterns := make([]*regexp.Regexp, 0)
+	customAllowPatterns := make([]*regexp.Regexp, 0)
 
-	enableDenyPatterns := true
 	if config != nil {
 		execConfig := config.Tools.Exec
-		enableDenyPatterns = execConfig.EnableDenyPatterns
+		enableDenyPatterns := execConfig.EnableDenyPatterns
 		if enableDenyPatterns {
 			denyPatterns = append(denyPatterns, defaultDenyPatterns...)
 			if len(execConfig.CustomDenyPatterns) > 0 {
@@ -87,8 +111,7 @@ func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Conf
 				for _, pattern := range execConfig.CustomDenyPatterns {
 					re, err := regexp.Compile(pattern)
 					if err != nil {
-						fmt.Printf("Invalid custom deny pattern %q: %v\n", pattern, err)
-						continue
+						return nil, fmt.Errorf("invalid custom deny pattern %q: %w", pattern, err)
 					}
 					denyPatterns = append(denyPatterns, re)
 				}
@@ -97,17 +120,30 @@ func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Conf
 			// If deny patterns are disabled, we won't add any patterns, allowing all commands.
 			fmt.Println("Warning: deny patterns are disabled. All commands will be allowed.")
 		}
+		for _, pattern := range execConfig.CustomAllowPatterns {
+			re, err := regexp.Compile(pattern)
+			if err != nil {
+				return nil, fmt.Errorf("invalid custom allow pattern %q: %w", pattern, err)
+			}
+			customAllowPatterns = append(customAllowPatterns, re)
+		}
 	} else {
 		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,
 		restrictToWorkspace: restrict,
-	}
+	}, nil
 }
 
 func (t *ExecTool) Name() string {
@@ -260,9 +296,20 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
 	cmd := strings.TrimSpace(command)
 	lower := strings.ToLower(cmd)
 
-	for _, pattern := range t.denyPatterns {
+	// Custom allow patterns exempt a command from deny checks.
+	explicitlyAllowed := false
+	for _, pattern := range t.customAllowPatterns {
 		if pattern.MatchString(lower) {
-			return "Command blocked by safety guard (dangerous pattern detected)"
+			explicitlyAllowed = true
+			break
+		}
+	}
+
+	if !explicitlyAllowed {
+		for _, pattern := range t.denyPatterns {
+			if pattern.MatchString(lower) {
+				return "Command blocked by safety guard (dangerous pattern detected)"
+			}
 		}
 	}
 
@@ -289,8 +336,7 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
 			return ""
 		}
 
-		pathPattern := regexp.MustCompile(`[A-Za-z]:\\[^\\\"']+|/[^\s\"']+`)
-		matches := pathPattern.FindAllString(cmd, -1)
+		matches := absolutePathPattern.FindAllString(cmd, -1)
 
 		for _, raw := range matches {
 			p, err := filepath.Abs(raw)
@@ -298,6 +344,10 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
 				continue
 			}
 
+			if safePaths[p] {
+				continue
+			}
+
 			rel, err := filepath.Rel(cwdPath, p)
 			if err != nil {
 				continue
diff --git a/pkg/tools/shell_test.go b/pkg/tools/shell_test.go
index 6d35815e8..ff9ea4a15 100644
--- a/pkg/tools/shell_test.go
+++ b/pkg/tools/shell_test.go
@@ -7,11 +7,16 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 // TestShellTool_Success verifies successful command execution
 func TestShellTool_Success(t *testing.T) {
-	tool := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
 
 	ctx := context.Background()
 	args := map[string]any{
@@ -38,7 +43,10 @@ func TestShellTool_Success(t *testing.T) {
 
 // TestShellTool_Failure verifies failed command execution
 func TestShellTool_Failure(t *testing.T) {
-	tool := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
 
 	ctx := context.Background()
 	args := map[string]any{
@@ -65,7 +73,11 @@ func TestShellTool_Failure(t *testing.T) {
 
 // TestShellTool_Timeout verifies command timeout handling
 func TestShellTool_Timeout(t *testing.T) {
-	tool := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
+
 	tool.SetTimeout(100 * time.Millisecond)
 
 	ctx := context.Background()
@@ -93,7 +105,10 @@ func TestShellTool_WorkingDir(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "test.txt")
 	os.WriteFile(testFile, []byte("test content"), 0o644)
 
-	tool := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
 
 	ctx := context.Background()
 	args := map[string]any{
@@ -114,7 +129,10 @@ func TestShellTool_WorkingDir(t *testing.T) {
 
 // TestShellTool_DangerousCommand verifies safety guard blocks dangerous commands
 func TestShellTool_DangerousCommand(t *testing.T) {
-	tool := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
 
 	ctx := context.Background()
 	args := map[string]any{
@@ -133,9 +151,32 @@ 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 := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
 
 	ctx := context.Background()
 	args := map[string]any{}
@@ -150,7 +191,10 @@ func TestShellTool_MissingCommand(t *testing.T) {
 
 // TestShellTool_StderrCapture verifies stderr is captured and included
 func TestShellTool_StderrCapture(t *testing.T) {
-	tool := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
 
 	ctx := context.Background()
 	args := map[string]any{
@@ -170,7 +214,10 @@ func TestShellTool_StderrCapture(t *testing.T) {
 
 // TestShellTool_OutputTruncation verifies long output is truncated
 func TestShellTool_OutputTruncation(t *testing.T) {
-	tool := NewExecTool("", false)
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
 
 	ctx := context.Background()
 	// Generate long output (>10000 chars)
@@ -198,7 +245,11 @@ func TestShellTool_WorkingDir_OutsideWorkspace(t *testing.T) {
 		t.Fatalf("failed to create outside dir: %v", err)
 	}
 
-	tool := NewExecTool(workspace, true)
+	tool, err := NewExecTool(workspace, true)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
+
 	result := tool.Execute(context.Background(), map[string]any{
 		"command":     "pwd",
 		"working_dir": outsideDir,
@@ -232,7 +283,11 @@ func TestShellTool_WorkingDir_SymlinkEscape(t *testing.T) {
 		t.Skipf("symlinks not supported in this environment: %v", err)
 	}
 
-	tool := NewExecTool(workspace, true)
+	tool, err := NewExecTool(workspace, true)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
+
 	result := tool.Execute(context.Background(), map[string]any{
 		"command":     "cat secret.txt",
 		"working_dir": link,
@@ -249,7 +304,11 @@ func TestShellTool_WorkingDir_SymlinkEscape(t *testing.T) {
 // TestShellTool_RestrictToWorkspace verifies workspace restriction
 func TestShellTool_RestrictToWorkspace(t *testing.T) {
 	tmpDir := t.TempDir()
-	tool := NewExecTool(tmpDir, false)
+	tool, err := NewExecTool(tmpDir, false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
+
 	tool.SetRestrictToWorkspace(true)
 
 	ctx := context.Background()
@@ -272,3 +331,115 @@ func TestShellTool_RestrictToWorkspace(t *testing.T) {
 		)
 	}
 }
+
+// TestShellTool_DevNullAllowed verifies that /dev/null redirections are not blocked (issue #964).
+func TestShellTool_DevNullAllowed(t *testing.T) {
+	tmpDir := t.TempDir()
+	tool, err := NewExecTool(tmpDir, true)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	commands := []string{
+		"echo hello 2>/dev/null",
+		"echo hello >/dev/null",
+		"echo hello > /dev/null",
+		"echo hello 2> /dev/null",
+		"echo hello >/dev/null 2>&1",
+		"find " + tmpDir + " -name '*.go' 2>/dev/null",
+	}
+
+	for _, cmd := range commands {
+		result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+		if result.IsError && strings.Contains(result.ForLLM, "blocked") {
+			t.Errorf("command should not be blocked: %s\n  error: %s", cmd, result.ForLLM)
+		}
+	}
+}
+
+// TestShellTool_BlockDevices verifies that writes to block devices are blocked (issue #965).
+func TestShellTool_BlockDevices(t *testing.T) {
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	blocked := []string{
+		"echo x > /dev/sda",
+		"echo x > /dev/hda",
+		"echo x > /dev/vda",
+		"echo x > /dev/xvda",
+		"echo x > /dev/nvme0n1",
+		"echo x > /dev/mmcblk0",
+		"echo x > /dev/loop0",
+		"echo x > /dev/dm-0",
+		"echo x > /dev/md0",
+		"echo x > /dev/sr0",
+		"echo x > /dev/nbd0",
+	}
+
+	for _, cmd := range blocked {
+		result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+		if !result.IsError {
+			t.Errorf("expected block device write to be blocked: %s", cmd)
+		}
+	}
+}
+
+// TestShellTool_SafePathsInWorkspaceRestriction verifies that safe kernel pseudo-devices
+// are allowed even when workspace restriction is active.
+func TestShellTool_SafePathsInWorkspaceRestriction(t *testing.T) {
+	tmpDir := t.TempDir()
+	tool, err := NewExecTool(tmpDir, true)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	// These reference paths outside workspace but should be allowed via safePaths.
+	commands := []string{
+		"cat /dev/urandom | head -c 16 | od",
+		"echo test > /dev/null",
+		"dd if=/dev/zero bs=1 count=1",
+	}
+
+	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("safe path should not be blocked by workspace check: %s\n  error: %s", cmd, result.ForLLM)
+		}
+	}
+}
+
+// TestShellTool_CustomAllowPatterns verifies that custom allow patterns exempt
+// commands from deny pattern checks.
+func TestShellTool_CustomAllowPatterns(t *testing.T) {
+	cfg := &config.Config{
+		Tools: config.ToolsConfig{
+			Exec: config.ExecConfig{
+				EnableDenyPatterns:  true,
+				CustomAllowPatterns: []string{`\bgit\s+push\s+origin\b`},
+			},
+		},
+	}
+
+	tool, err := NewExecToolWithConfig("", false, cfg)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	// "git push origin main" should be allowed by custom allow pattern.
+	result := tool.Execute(context.Background(), map[string]any{
+		"command": "git push origin main",
+	})
+	if result.IsError && strings.Contains(result.ForLLM, "blocked") {
+		t.Errorf("custom allow pattern should exempt 'git push origin main', got: %s", result.ForLLM)
+	}
+
+	// "git push upstream main" should still be blocked (does not match allow pattern).
+	result = tool.Execute(context.Background(), map[string]any{
+		"command": "git push upstream main",
+	})
+	if !result.IsError {
+		t.Errorf("'git push upstream main' should still be blocked by deny pattern")
+	}
+}
diff --git a/pkg/tools/shell_timeout_unix_test.go b/pkg/tools/shell_timeout_unix_test.go
index 04ef8e441..357e1276e 100644
--- a/pkg/tools/shell_timeout_unix_test.go
+++ b/pkg/tools/shell_timeout_unix_test.go
@@ -22,7 +22,11 @@ func processExists(pid int) bool {
 }
 
 func TestShellTool_TimeoutKillsChildProcess(t *testing.T) {
-	tool := NewExecTool(t.TempDir(), false)
+	tool, err := NewExecTool(t.TempDir(), false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
+
 	tool.SetTimeout(500 * time.Millisecond)
 
 	args := map[string]any{
diff --git a/pkg/tools/skills_install.go b/pkg/tools/skills_install.go
index 55c0b678d..71bfe730b 100644
--- a/pkg/tools/skills_install.go
+++ b/pkg/tools/skills_install.go
@@ -9,6 +9,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/skills"
 	"github.com/sipeed/picoclaw/pkg/utils"
@@ -197,5 +198,6 @@ func writeOriginMeta(targetDir, registryName, slug, version string) error {
 		return err
 	}
 
-	return os.WriteFile(filepath.Join(targetDir, ".skill-origin.json"), data, 0o644)
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	return fileutil.WriteFileAtomic(filepath.Join(targetDir, ".skill-origin.json"), data, 0o600)
 }
diff --git a/pkg/tools/spawn.go b/pkg/tools/spawn.go
index 73d385cb0..be40ffda2 100644
--- a/pkg/tools/spawn.go
+++ b/pkg/tools/spawn.go
@@ -3,29 +3,23 @@ package tools
 import (
 	"context"
 	"fmt"
+	"strings"
 )
 
 type SpawnTool struct {
 	manager        *SubagentManager
-	originChannel  string
-	originChatID   string
 	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 {
 	return &SpawnTool{
-		manager:       manager,
-		originChannel: "cli",
-		originChatID:  "direct",
+		manager: manager,
 	}
 }
 
-// SetCallback implements AsyncTool interface for async completion notification
-func (t *SpawnTool) SetCallback(cb AsyncCallback) {
-	t.callback = cb
-}
-
 func (t *SpawnTool) Name() string {
 	return "spawn"
 }
@@ -55,19 +49,24 @@ 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 {
-		return ErrorResult("task is required")
+	if !ok || strings.TrimSpace(task) == "" {
+		return ErrorResult("task is required and must be a non-empty string")
 	}
 
 	label, _ := args["label"].(string)
@@ -84,8 +83,20 @@ func (t *SpawnTool) Execute(ctx context.Context, args map[string]any) *ToolResul
 		return ErrorResult("Subagent manager not configured")
 	}
 
+	// Read channel/chatID from context (injected by registry).
+	// Fall back to "cli"/"direct" for non-conversation callers (e.g., CLI, tests)
+	// to preserve the same defaults as the original NewSpawnTool constructor.
+	channel := ToolChannel(ctx)
+	if channel == "" {
+		channel = "cli"
+	}
+	chatID := ToolChatID(ctx)
+	if chatID == "" {
+		chatID = "direct"
+	}
+
 	// Pass callback to manager for async completion notification
-	result, err := t.manager.Spawn(ctx, task, label, agentID, t.originChannel, t.originChatID, t.callback)
+	result, err := t.manager.Spawn(ctx, task, label, agentID, channel, chatID, cb)
 	if err != nil {
 		return ErrorResult(fmt.Sprintf("failed to spawn subagent: %v", err))
 	}
diff --git a/pkg/tools/spawn_test.go b/pkg/tools/spawn_test.go
new file mode 100644
index 000000000..43223b8db
--- /dev/null
+++ b/pkg/tools/spawn_test.go
@@ -0,0 +1,79 @@
+package tools
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+func TestSpawnTool_Execute_EmptyTask(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+	tool := NewSpawnTool(manager)
+
+	ctx := context.Background()
+
+	tests := []struct {
+		name string
+		args map[string]any
+	}{
+		{"empty string", map[string]any{"task": ""}},
+		{"whitespace only", map[string]any{"task": "   "}},
+		{"tabs and newlines", map[string]any{"task": "\t\n  "}},
+		{"missing task key", map[string]any{"label": "test"}},
+		{"wrong type", map[string]any{"task": 123}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := tool.Execute(ctx, tt.args)
+			if result == nil {
+				t.Fatal("Result should not be nil")
+			}
+			if !result.IsError {
+				t.Error("Expected error for invalid task parameter")
+			}
+			if !strings.Contains(result.ForLLM, "task is required") {
+				t.Errorf("Error message should mention 'task is required', got: %s", result.ForLLM)
+			}
+		})
+	}
+}
+
+func TestSpawnTool_Execute_ValidTask(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+	tool := NewSpawnTool(manager)
+
+	ctx := context.Background()
+	args := map[string]any{
+		"task":  "Write a haiku about coding",
+		"label": "haiku-task",
+	}
+
+	result := tool.Execute(ctx, args)
+	if result == nil {
+		t.Fatal("Result should not be nil")
+	}
+	if result.IsError {
+		t.Errorf("Expected success for valid task, got error: %s", result.ForLLM)
+	}
+	if !result.Async {
+		t.Error("SpawnTool should return async result")
+	}
+}
+
+func TestSpawnTool_Execute_NilManager(t *testing.T) {
+	tool := NewSpawnTool(nil)
+
+	ctx := context.Background()
+	args := map[string]any{"task": "test task"}
+
+	result := tool.Execute(ctx, args)
+	if !result.IsError {
+		t.Error("Expected error for nil manager")
+	}
+	if !strings.Contains(result.ForLLM, "Subagent manager not configured") {
+		t.Errorf("Error message should mention manager not configured, got: %s", result.ForLLM)
+	}
+}
diff --git a/pkg/tools/spi.go b/pkg/tools/spi.go
index d6a88a5b0..0ca17e84f 100644
--- a/pkg/tools/spi.go
+++ b/pkg/tools/spi.go
@@ -119,7 +119,11 @@ func (t *SPITool) list() *ToolResult {
 	return SilentResult(fmt.Sprintf("Found %d SPI device(s):\n%s", len(devices), string(result)))
 }
 
+// Helper function for SPI operations (used by platform-specific implementations)
+
 // parseSPIArgs extracts and validates common SPI parameters
+//
+//nolint:unused // Used by spi_linux.go
 func parseSPIArgs(args map[string]any) (device string, speed uint32, mode uint8, bits uint8, errMsg string) {
 	dev, ok := args["device"].(string)
 	if !ok || dev == "" {
diff --git a/pkg/tools/subagent.go b/pkg/tools/subagent.go
index 91ebff636..e51cbaafa 100644
--- a/pkg/tools/subagent.go
+++ b/pkg/tools/subagent.go
@@ -6,7 +6,6 @@ import (
 	"sync"
 	"time"
 
-	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
@@ -27,7 +26,6 @@ type SubagentManager struct {
 	mu             sync.RWMutex
 	provider       providers.LLMProvider
 	defaultModel   string
-	bus            *bus.MessageBus
 	workspace      string
 	tools          *ToolRegistry
 	maxIterations  int
@@ -41,13 +39,11 @@ type SubagentManager struct {
 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,
@@ -132,12 +128,12 @@ After completing the task, provide a clear summary of what was done.`
 		},
 	}
 
-	// Check if context is already cancelled before starting
+	// Check if context is already canceled before starting
 	select {
 	case <-ctx.Done():
 		sm.mu.Lock()
-		task.Status = "cancelled"
-		task.Result = "Task cancelled before execution"
+		task.Status = "canceled"
+		task.Result = "Task canceled before execution"
 		sm.mu.Unlock()
 		return
 	default:
@@ -185,10 +181,10 @@ After completing the task, provide a clear summary of what was done.`
 	if err != nil {
 		task.Status = "failed"
 		task.Result = fmt.Sprintf("Error: %v", err)
-		// Check if it was cancelled
+		// Check if it was canceled
 		if ctx.Err() != nil {
-			task.Status = "cancelled"
-			task.Result = "Task cancelled during execution"
+			task.Status = "canceled"
+			task.Result = "Task canceled during execution"
 		}
 		result = &ToolResult{
 			ForLLM:  task.Result,
@@ -214,18 +210,6 @@ After completing the task, provide a clear summary of what was done.`
 			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)
-		sm.bus.PublishInbound(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,
-		})
-	}
 }
 
 func (sm *SubagentManager) GetTask(taskID string) (*SubagentTask, bool) {
@@ -250,16 +234,12 @@ func (sm *SubagentManager) ListTasks() []*SubagentTask {
 // Unlike SpawnTool which runs tasks asynchronously, SubagentTool waits for completion
 // and returns the result directly in the ToolResult.
 type SubagentTool struct {
-	manager       *SubagentManager
-	originChannel string
-	originChatID  string
+	manager *SubagentManager
 }
 
 func NewSubagentTool(manager *SubagentManager) *SubagentTool {
 	return &SubagentTool{
-		manager:       manager,
-		originChannel: "cli",
-		originChatID:  "direct",
+		manager: manager,
 	}
 }
 
@@ -288,11 +268,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 {
@@ -339,13 +314,24 @@ func (t *SubagentTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		}
 	}
 
+	// Fall back to "cli"/"direct" for non-conversation callers (e.g., CLI, tests)
+	// to preserve the same defaults as the original NewSubagentTool constructor.
+	channel := ToolChannel(ctx)
+	if channel == "" {
+		channel = "cli"
+	}
+	chatID := ToolChatID(ctx)
+	if chatID == "" {
+		chatID = "direct"
+	}
+
 	loopResult, err := RunToolLoop(ctx, ToolLoopConfig{
 		Provider:      sm.provider,
 		Model:         sm.defaultModel,
 		Tools:         tools,
 		MaxIterations: maxIter,
 		LLMOptions:    llmOptions,
-	}, messages, t.originChannel, t.originChatID)
+	}, messages, channel, chatID)
 	if err != nil {
 		return ErrorResult(fmt.Sprintf("Subagent execution failed: %v", err)).WithError(err)
 	}
diff --git a/pkg/tools/subagent_tool_test.go b/pkg/tools/subagent_tool_test.go
index 59bfdffae..4b6f130a5 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,12 +46,11 @@ 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()
+	ctx := WithToolContext(context.Background(), "cli", "direct")
 	args := map[string]any{"task": "Do something"}
 	result := tool.Execute(ctx, args)
 
@@ -74,7 +72,7 @@ func TestSubagentManager_SetLLMOptions_AppliesToRunToolLoop(t *testing.T) {
 // 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 +83,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 +98,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 +145,13 @@ 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")
 
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), "telegram", "chat-123")
 	args := map[string]any{
 		"task":  "Write a haiku about coding",
 		"label": "haiku-task",
@@ -219,8 +202,7 @@ 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)
 
 	ctx := context.Background()
@@ -243,7 +225,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 +275,12 @@ 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)
 
-	// 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,8 +300,7 @@ 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)
 
 	ctx := context.Background()
diff --git a/pkg/tools/toolloop.go b/pkg/tools/toolloop.go
index cdfe0d6ce..244f0d4a2 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,53 @@ 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
+
+		for i, tc := range normalizedToolCalls {
+			results[i].tc = tc
+
+			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.ForLLM
+			if contentForLLM == "" && r.result.Err != nil {
+				contentForLLM = r.result.Err.Error()
 			}
 
-			// Determine content for LLM
-			contentForLLM := toolResult.ForLLM
-			if contentForLLM == "" && toolResult.Err != nil {
-				contentForLLM = toolResult.Err.Error()
-			}
-
-			// Add tool result message
-			toolResultMsg := providers.Message{
+			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/web.go b/pkg/tools/web.go
index 452e95e0f..eeceabd98 100644
--- a/pkg/tools/web.go
+++ b/pkg/tools/web.go
@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -15,14 +16,74 @@ import (
 
 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"
+
+	// HTTP client timeouts for web tool providers.
+	searchTimeout     = 10 * time.Second // Brave, Tavily, DuckDuckGo
+	perplexityTimeout = 30 * time.Second // Perplexity (LLM-based, slower)
+	fetchTimeout      = 60 * time.Second // WebFetchTool
+
+	defaultMaxChars = 50000
+	maxRedirects    = 5
 )
 
+// Pre-compiled regexes for HTML text extraction
+var (
+	reScript     = regexp.MustCompile(`<script[\s\S]*?</script>`)
+	reStyle      = regexp.MustCompile(`<style[\s\S]*?</style>`)
+	reTags       = regexp.MustCompile(`<[^>]+>`)
+	reWhitespace = regexp.MustCompile(`[^\S\n]+`)
+	reBlankLines = regexp.MustCompile(`\n{3,}`)
+
+	// DuckDuckGo result extraction
+	reDDGLink    = regexp.MustCompile(`<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)</a>`)
+	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,
+		},
+	}
+
+	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
+}
+
 type SearchProvider interface {
 	Search(ctx context.Context, query string, count int) (string, error)
 }
 
 type BraveSearchProvider struct {
 	apiKey string
+	proxy  string
+	client *http.Client
 }
 
 func (p *BraveSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
@@ -37,8 +98,7 @@ func (p *BraveSearchProvider) Search(ctx context.Context, query string, count in
 	req.Header.Set("Accept", "application/json")
 	req.Header.Set("X-Subscription-Token", p.apiKey)
 
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := p.client.Do(req)
 	if err != nil {
 		return "", fmt.Errorf("request failed: %w", err)
 	}
@@ -49,6 +109,10 @@ func (p *BraveSearchProvider) Search(ctx context.Context, query string, count in
 		return "", fmt.Errorf("failed to read response: %w", err)
 	}
 
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("brave api error (status %d): %s", resp.StatusCode, string(body))
+	}
+
 	var searchResp struct {
 		Web struct {
 			Results []struct {
@@ -88,6 +152,8 @@ func (p *BraveSearchProvider) Search(ctx context.Context, query string, count in
 type TavilySearchProvider struct {
 	apiKey  string
 	baseURL string
+	proxy   string
+	client  *http.Client
 }
 
 func (p *TavilySearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
@@ -119,8 +185,7 @@ func (p *TavilySearchProvider) Search(ctx context.Context, query string, count i
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("User-Agent", userAgent)
 
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := p.client.Do(req)
 	if err != nil {
 		return "", fmt.Errorf("request failed: %w", err)
 	}
@@ -167,7 +232,10 @@ func (p *TavilySearchProvider) Search(ctx context.Context, query string, count i
 	return strings.Join(lines, "\n"), nil
 }
 
-type DuckDuckGoSearchProvider struct{}
+type DuckDuckGoSearchProvider struct {
+	proxy  string
+	client *http.Client
+}
 
 func (p *DuckDuckGoSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
 	searchURL := fmt.Sprintf("https://html.duckduckgo.com/html/?q=%s", url.QueryEscape(query))
@@ -179,8 +247,7 @@ func (p *DuckDuckGoSearchProvider) Search(ctx context.Context, query string, cou
 
 	req.Header.Set("User-Agent", userAgent)
 
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := p.client.Do(req)
 	if err != nil {
 		return "", fmt.Errorf("request failed: %w", err)
 	}
@@ -201,8 +268,7 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
 	// Try finding the result links directly first, as they are the most critical
 	// Pattern: <a class="result__a" href="...">Title</a>
 	// The previous regex was a bit strict. Let's make it more flexible for attributes order/content
-	reLink := regexp.MustCompile(`<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)</a>`)
-	matches := reLink.FindAllStringSubmatch(html, count+5)
+	matches := reDDGLink.FindAllStringSubmatch(html, count+5)
 
 	if len(matches) == 0 {
 		return fmt.Sprintf("No results found or extraction failed. Query: %s", query), nil
@@ -219,12 +285,11 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
 
 	// A better regex approach: iterate through text and find matches in order
 	// But for now, let's grab all snippets too
-	reSnippet := regexp.MustCompile(`<a class="result__snippet[^"]*".*?>([\s\S]*?)</a>`)
-	snippetMatches := reSnippet.FindAllStringSubmatch(html, count+5)
+	snippetMatches := reDDGSnippet.FindAllStringSubmatch(html, count+5)
 
 	maxItems := min(len(matches), count)
 
-	for i := 0; i < maxItems; i++ {
+	for i := range maxItems {
 		urlStr := matches[i][1]
 		title := stripTags(matches[i][2])
 		title = strings.TrimSpace(title)
@@ -232,9 +297,9 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
 		// URL decoding if needed
 		if strings.Contains(urlStr, "uddg=") {
 			if u, err := url.QueryUnescape(urlStr); err == nil {
-				idx := strings.Index(u, "uddg=")
-				if idx != -1 {
-					urlStr = u[idx+5:]
+				_, after, ok := strings.Cut(u, "uddg=")
+				if ok {
+					urlStr = after
 				}
 			}
 		}
@@ -255,12 +320,13 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
 }
 
 func stripTags(content string) string {
-	re := regexp.MustCompile(`<[^>]+>`)
-	return re.ReplaceAllString(content, "")
+	return reTags.ReplaceAllString(content, "")
 }
 
 type PerplexitySearchProvider struct {
 	apiKey string
+	proxy  string
+	client *http.Client
 }
 
 func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
@@ -295,8 +361,7 @@ func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, cou
 	req.Header.Set("Authorization", "Bearer "+p.apiKey)
 	req.Header.Set("User-Agent", userAgent)
 
-	client := &http.Client{Timeout: 30 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := p.client.Do(req)
 	if err != nil {
 		return "", fmt.Errorf("request failed: %w", err)
 	}
@@ -330,6 +395,150 @@ func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, cou
 	return fmt.Sprintf("Results for: %s (via Perplexity)\n%s", query, searchResp.Choices[0].Message.Content), nil
 }
 
+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 create request: %w", err)
+	}
+
+	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)
+
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("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("GLM Search API error (status %d): %s", resp.StatusCode, string(body))
+	}
+
+	var searchResp struct {
+		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)
+	}
+
+	results := searchResp.SearchResult
+	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 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 WebSearchTool struct {
 	provider   SearchProvider
 	maxResults int
@@ -348,44 +557,95 @@ type WebSearchToolOptions struct {
 	PerplexityAPIKey     string
 	PerplexityMaxResults int
 	PerplexityEnabled    bool
+	SearXNGBaseURL       string
+	SearXNGMaxResults    int
+	SearXNGEnabled       bool
+	GLMSearchAPIKey      string
+	GLMSearchBaseURL     string
+	GLMSearchEngine      string
+	GLMSearchMaxResults  int
+	GLMSearchEnabled     bool
+	Proxy                string
 }
 
-func NewWebSearchTool(opts WebSearchToolOptions) *WebSearchTool {
+func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) {
 	var provider SearchProvider
 	maxResults := 5
 
-	// Priority: Perplexity > Brave > Tavily > DuckDuckGo
+	// Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > GLM Search
 	if opts.PerplexityEnabled && opts.PerplexityAPIKey != "" {
-		provider = &PerplexitySearchProvider{apiKey: opts.PerplexityAPIKey}
+		client, err := 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}
 		if opts.PerplexityMaxResults > 0 {
 			maxResults = opts.PerplexityMaxResults
 		}
 	} else if opts.BraveEnabled && opts.BraveAPIKey != "" {
-		provider = &BraveSearchProvider{apiKey: opts.BraveAPIKey}
+		client, err := 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}
 		if opts.BraveMaxResults > 0 {
 			maxResults = opts.BraveMaxResults
 		}
+	} else if opts.SearXNGEnabled && opts.SearXNGBaseURL != "" {
+		provider = &SearXNGSearchProvider{baseURL: opts.SearXNGBaseURL}
+		if opts.SearXNGMaxResults > 0 {
+			maxResults = opts.SearXNGMaxResults
+		}
 	} else if opts.TavilyEnabled && opts.TavilyAPIKey != "" {
+		client, err := 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,
 			baseURL: opts.TavilyBaseURL,
+			proxy:   opts.Proxy,
+			client:  client,
 		}
 		if opts.TavilyMaxResults > 0 {
 			maxResults = opts.TavilyMaxResults
 		}
 	} else if opts.DuckDuckGoEnabled {
-		provider = &DuckDuckGoSearchProvider{}
+		client, err := createHTTPClient(opts.Proxy, searchTimeout)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create HTTP client for DuckDuckGo: %w", err)
+		}
+		provider = &DuckDuckGoSearchProvider{proxy: opts.Proxy, client: client}
 		if opts.DuckDuckGoMaxResults > 0 {
 			maxResults = opts.DuckDuckGoMaxResults
 		}
+	} else if opts.GLMSearchEnabled && opts.GLMSearchAPIKey != "" {
+		client, err := 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
+		return nil, nil
 	}
 
 	return &WebSearchTool{
 		provider:   provider,
 		maxResults: maxResults,
-	}
+	}, nil
 }
 
 func (t *WebSearchTool) Name() string {
@@ -440,16 +700,40 @@ func (t *WebSearchTool) Execute(ctx context.Context, args map[string]any) *ToolR
 }
 
 type WebFetchTool struct {
-	maxChars int
+	maxChars        int
+	proxy           string
+	client          *http.Client
+	fetchLimitBytes int64
 }
 
-func NewWebFetchTool(maxChars int) *WebFetchTool {
+func NewWebFetchTool(maxChars int, fetchLimitBytes int64) (*WebFetchTool, error) {
+	// createHTTPClient cannot fail with an empty proxy string.
+	return NewWebFetchToolWithProxy(maxChars, "", fetchLimitBytes)
+}
+
+func NewWebFetchToolWithProxy(maxChars int, proxy string, fetchLimitBytes int64) (*WebFetchTool, error) {
 	if maxChars <= 0 {
-		maxChars = 50000
+		maxChars = defaultMaxChars
+	}
+	client, err := createHTTPClient(proxy, fetchTimeout)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create HTTP client for web fetch: %w", err)
+	}
+	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+		if len(via) >= maxRedirects {
+			return fmt.Errorf("stopped after %d redirects", maxRedirects)
+		}
+		return nil
+	}
+	if fetchLimitBytes <= 0 {
+		fetchLimitBytes = 10 * 1024 * 1024 // Security Fallback
 	}
 	return &WebFetchTool{
-		maxChars: maxChars,
-	}
+		maxChars:        maxChars,
+		proxy:           proxy,
+		client:          client,
+		fetchLimitBytes: fetchLimitBytes,
+	}, nil
 }
 
 func (t *WebFetchTool) Name() string {
@@ -511,30 +795,21 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 
 	req.Header.Set("User-Agent", userAgent)
 
-	client := &http.Client{
-		Timeout: 60 * time.Second,
-		Transport: &http.Transport{
-			MaxIdleConns:        10,
-			IdleConnTimeout:     30 * time.Second,
-			DisableCompression:  false,
-			TLSHandshakeTimeout: 15 * time.Second,
-		},
-		CheckRedirect: func(req *http.Request, via []*http.Request) error {
-			if len(via) >= 5 {
-				return fmt.Errorf("stopped after 5 redirects")
-			}
-			return nil
-		},
-	}
-
-	resp, err := client.Do(req)
+	resp, err := t.client.Do(req)
 	if err != nil {
 		return ErrorResult(fmt.Sprintf("request failed: %v", err))
 	}
+
+	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))
 	}
 
@@ -578,31 +853,26 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 	resultJSON, _ := json.MarshalIndent(result, "", "  ")
 
 	return &ToolResult{
-		ForLLM: fmt.Sprintf(
+		ForLLM: string(resultJSON),
+		ForUser: fmt.Sprintf(
 			"Fetched %d bytes from %s (extractor: %s, truncated: %v)",
 			len(text),
 			urlStr,
 			extractor,
 			truncated,
 		),
-		ForUser: string(resultJSON),
 	}
 }
 
 func (t *WebFetchTool) extractText(htmlContent string) string {
-	re := regexp.MustCompile(`<script[\s\S]*?</script>`)
-	result := re.ReplaceAllLiteralString(htmlContent, "")
-	re = regexp.MustCompile(`<style[\s\S]*?</style>`)
-	result = re.ReplaceAllLiteralString(result, "")
-	re = regexp.MustCompile(`<[^>]+>`)
-	result = re.ReplaceAllLiteralString(result, "")
+	result := reScript.ReplaceAllLiteralString(htmlContent, "")
+	result = reStyle.ReplaceAllLiteralString(result, "")
+	result = reTags.ReplaceAllLiteralString(result, "")
 
 	result = strings.TrimSpace(result)
 
-	re = regexp.MustCompile(`[^\S\n]+`)
-	result = re.ReplaceAllString(result, " ")
-	re = regexp.MustCompile(`\n{3,}`)
-	result = re.ReplaceAllString(result, "\n\n")
+	result = reWhitespace.ReplaceAllString(result, " ")
+	result = reBlankLines.ReplaceAllString(result, "\n\n")
 
 	lines := strings.Split(result, "\n")
 	var cleanLines []string
diff --git a/pkg/tools/web_test.go b/pkg/tools/web_test.go
index 75e0d8d16..bdd30d385 100644
--- a/pkg/tools/web_test.go
+++ b/pkg/tools/web_test.go
@@ -1,14 +1,21 @@
 package tools
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
+const testFetchLimit = int64(10 * 1024 * 1024)
+
 // TestWebTool_WebFetch_Success verifies successful URL fetching
 func TestWebTool_WebFetch_Success(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -18,7 +25,11 @@ func TestWebTool_WebFetch_Success(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool := NewWebFetchTool(50000)
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+
 	ctx := context.Background()
 	args := map[string]any{
 		"url": server.URL,
@@ -31,14 +42,14 @@ func TestWebTool_WebFetch_Success(t *testing.T) {
 		t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
 	}
 
-	// ForUser should contain the fetched content
-	if !strings.Contains(result.ForUser, "Test Page") {
-		t.Errorf("Expected ForUser to contain 'Test Page', got: %s", result.ForUser)
+	// ForLLM should contain the fetched content (full JSON result)
+	if !strings.Contains(result.ForLLM, "Test Page") {
+		t.Errorf("Expected ForLLM to contain 'Test Page', got: %s", result.ForLLM)
 	}
 
-	// ForLLM should contain summary
-	if !strings.Contains(result.ForLLM, "bytes") && !strings.Contains(result.ForLLM, "extractor") {
-		t.Errorf("Expected ForLLM to contain summary, got: %s", result.ForLLM)
+	// ForUser should contain summary
+	if !strings.Contains(result.ForUser, "bytes") && !strings.Contains(result.ForUser, "extractor") {
+		t.Errorf("Expected ForUser to contain summary, got: %s", result.ForUser)
 	}
 }
 
@@ -54,7 +65,11 @@ func TestWebTool_WebFetch_JSON(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool := NewWebFetchTool(50000)
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
 	ctx := context.Background()
 	args := map[string]any{
 		"url": server.URL,
@@ -67,15 +82,19 @@ func TestWebTool_WebFetch_JSON(t *testing.T) {
 		t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
 	}
 
-	// ForUser should contain formatted JSON
-	if !strings.Contains(result.ForUser, "key") && !strings.Contains(result.ForUser, "value") {
-		t.Errorf("Expected ForUser to contain JSON data, got: %s", result.ForUser)
+	// ForLLM should contain formatted JSON
+	if !strings.Contains(result.ForLLM, "key") && !strings.Contains(result.ForLLM, "value") {
+		t.Errorf("Expected ForLLM to contain JSON data, got: %s", result.ForLLM)
 	}
 }
 
 // TestWebTool_WebFetch_InvalidURL verifies error handling for invalid URL
 func TestWebTool_WebFetch_InvalidURL(t *testing.T) {
-	tool := NewWebFetchTool(50000)
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
 	ctx := context.Background()
 	args := map[string]any{
 		"url": "not-a-valid-url",
@@ -96,7 +115,11 @@ 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 := NewWebFetchTool(50000)
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
 	ctx := context.Background()
 	args := map[string]any{
 		"url": "ftp://example.com/file.txt",
@@ -117,7 +140,11 @@ func TestWebTool_WebFetch_UnsupportedScheme(t *testing.T) {
 
 // TestWebTool_WebFetch_MissingURL verifies error handling for missing URL
 func TestWebTool_WebFetch_MissingURL(t *testing.T) {
-	tool := NewWebFetchTool(50000)
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
 	ctx := context.Background()
 	args := map[string]any{}
 
@@ -145,7 +172,11 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool := NewWebFetchTool(1000) // Limit to 1000 chars
+	tool, err := NewWebFetchTool(1000, testFetchLimit) // Limit to 1000 chars
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
 	ctx := context.Background()
 	args := map[string]any{
 		"url": server.URL,
@@ -158,9 +189,9 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
 		t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
 	}
 
-	// ForUser should contain truncated content (not the full 20000 chars)
+	// ForLLM should contain truncated content (not the full 20000 chars)
 	resultMap := make(map[string]any)
-	json.Unmarshal([]byte(result.ForUser), &resultMap)
+	json.Unmarshal([]byte(result.ForLLM), &resultMap)
 	if text, ok := resultMap["text"].(string); ok {
 		if len(text) > 1100 { // Allow some margin
 			t.Errorf("Expected content to be truncated to ~1000 chars, got: %d", len(text))
@@ -173,15 +204,64 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
 	}
 }
 
+func TestWebFetchTool_PayloadTooLarge(t *testing.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")
+		w.WriteHeader(http.StatusOK)
+
+		// Generate a payload intentionally larger than our limit.
+		// Limit: 10 * 1024 * 1024 (10MB). We generate 10MB + 100 bytes of the letter 'A'.
+		largeData := bytes.Repeat([]byte("A"), int(testFetchLimit)+100)
+
+		w.Write(largeData)
+	}))
+	// Ensure the server is shut down at the end of the test
+	defer ts.Close()
+
+	// Initialize the tool
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
+	// Prepare the arguments pointing to the URL of our local mock server
+	args := map[string]any{
+		"url": ts.URL,
+	}
+
+	// Execute the tool
+	ctx := context.Background()
+	result := tool.Execute(ctx, args)
+
+	// Assuming ErrorResult sets the ForLLM field with the error text.
+	if result == nil {
+		t.Fatal("expected a ToolResult, got nil")
+	}
+
+	// Search for the exact error string we set earlier in the Execute method
+	expectedErrorMsg := fmt.Sprintf("size exceeded %d bytes limit", testFetchLimit)
+
+	if !strings.Contains(result.ForLLM, expectedErrorMsg) && !strings.Contains(result.ForUser, expectedErrorMsg) {
+		t.Errorf("test failed: expected error %q, but got: %+v", expectedErrorMsg, result)
+	}
+}
+
 // TestWebTool_WebSearch_NoApiKey verifies that no tool is created when API key is missing
 func TestWebTool_WebSearch_NoApiKey(t *testing.T) {
-	tool := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: ""})
+	tool, err := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: ""})
+	if err != nil {
+		t.Fatalf("Unexpected error: %v", err)
+	}
 	if tool != nil {
 		t.Errorf("Expected nil tool when Brave API key is empty")
 	}
 
 	// Also nil when nothing is enabled
-	tool = NewWebSearchTool(WebSearchToolOptions{})
+	tool, err = NewWebSearchTool(WebSearchToolOptions{})
+	if err != nil {
+		t.Fatalf("Unexpected error: %v", err)
+	}
 	if tool != nil {
 		t.Errorf("Expected nil tool when no provider is enabled")
 	}
@@ -189,7 +269,10 @@ func TestWebTool_WebSearch_NoApiKey(t *testing.T) {
 
 // TestWebTool_WebSearch_MissingQuery verifies error handling for missing query
 func TestWebTool_WebSearch_MissingQuery(t *testing.T) {
-	tool := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: "test-key", BraveMaxResults: 5})
+	tool, err := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: "test-key", BraveMaxResults: 5})
+	if err != nil {
+		t.Fatalf("Unexpected error: %v", err)
+	}
 	ctx := context.Background()
 	args := map[string]any{}
 
@@ -214,7 +297,11 @@ func TestWebTool_WebFetch_HTMLExtraction(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool := NewWebFetchTool(50000)
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
 	ctx := context.Background()
 	args := map[string]any{
 		"url": server.URL,
@@ -227,14 +314,14 @@ func TestWebTool_WebFetch_HTMLExtraction(t *testing.T) {
 		t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
 	}
 
-	// ForUser should contain extracted text (without script/style tags)
-	if !strings.Contains(result.ForUser, "Title") && !strings.Contains(result.ForUser, "Content") {
-		t.Errorf("Expected ForUser to contain extracted text, got: %s", result.ForUser)
+	// ForLLM should contain extracted text (without script/style tags)
+	if !strings.Contains(result.ForLLM, "Title") && !strings.Contains(result.ForLLM, "Content") {
+		t.Errorf("Expected ForLLM to contain extracted text, got: %s", result.ForLLM)
 	}
 
-	// Should NOT contain script or style tags
-	if strings.Contains(result.ForUser, "<script>") || strings.Contains(result.ForUser, "<style>") {
-		t.Errorf("Expected script/style tags to be removed, got: %s", result.ForUser)
+	// Should NOT contain script or style tags in ForLLM
+	if strings.Contains(result.ForLLM, "<script>") || strings.Contains(result.ForLLM, "<style>") {
+		t.Errorf("Expected script/style tags to be removed, got: %s", result.ForLLM)
 	}
 }
 
@@ -315,7 +402,11 @@ func TestWebFetchTool_extractText(t *testing.T) {
 
 // TestWebTool_WebFetch_MissingDomain verifies error handling for URL without domain
 func TestWebTool_WebFetch_MissingDomain(t *testing.T) {
-	tool := NewWebFetchTool(50000)
+	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
 	ctx := context.Background()
 	args := map[string]any{
 		"url": "https://",
@@ -334,6 +425,188 @@ 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)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	} else if tool.maxChars != 1024 {
+		t.Fatalf("maxChars = %d, want %d", tool.maxChars, 1024)
+	}
+
+	if tool.proxy != "http://127.0.0.1:7890" {
+		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)
+	if err != nil {
+		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+	}
+
+	if tool.maxChars != 50000 {
+		t.Fatalf("default maxChars = %d, want %d", tool.maxChars, 50000)
+	}
+}
+
+func TestNewWebSearchTool_PropagatesProxy(t *testing.T) {
+	t.Run("perplexity", func(t *testing.T) {
+		tool, err := NewWebSearchTool(WebSearchToolOptions{
+			PerplexityEnabled:    true,
+			PerplexityAPIKey:     "k",
+			PerplexityMaxResults: 3,
+			Proxy:                "http://127.0.0.1:7890",
+		})
+		if err != nil {
+			t.Fatalf("NewWebSearchTool() error: %v", err)
+		}
+		p, ok := tool.provider.(*PerplexitySearchProvider)
+		if !ok {
+			t.Fatalf("provider type = %T, want *PerplexitySearchProvider", tool.provider)
+		}
+		if p.proxy != "http://127.0.0.1:7890" {
+			t.Fatalf("provider proxy = %q, want %q", p.proxy, "http://127.0.0.1:7890")
+		}
+	})
+
+	t.Run("brave", func(t *testing.T) {
+		tool, err := NewWebSearchTool(WebSearchToolOptions{
+			BraveEnabled:    true,
+			BraveAPIKey:     "k",
+			BraveMaxResults: 3,
+			Proxy:           "http://127.0.0.1:7890",
+		})
+		if err != nil {
+			t.Fatalf("NewWebSearchTool() error: %v", err)
+		}
+		p, ok := tool.provider.(*BraveSearchProvider)
+		if !ok {
+			t.Fatalf("provider type = %T, want *BraveSearchProvider", tool.provider)
+		}
+		if p.proxy != "http://127.0.0.1:7890" {
+			t.Fatalf("provider proxy = %q, want %q", p.proxy, "http://127.0.0.1:7890")
+		}
+	})
+
+	t.Run("duckduckgo", func(t *testing.T) {
+		tool, err := NewWebSearchTool(WebSearchToolOptions{
+			DuckDuckGoEnabled:    true,
+			DuckDuckGoMaxResults: 3,
+			Proxy:                "http://127.0.0.1:7890",
+		})
+		if err != nil {
+			t.Fatalf("NewWebSearchTool() error: %v", err)
+		}
+		p, ok := tool.provider.(*DuckDuckGoSearchProvider)
+		if !ok {
+			t.Fatalf("provider type = %T, want *DuckDuckGoSearchProvider", tool.provider)
+		}
+		if p.proxy != "http://127.0.0.1:7890" {
+			t.Fatalf("provider proxy = %q, want %q", p.proxy, "http://127.0.0.1:7890")
+		}
+	})
+}
+
 // TestWebTool_TavilySearch_Success verifies successful Tavily search
 func TestWebTool_TavilySearch_Success(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -375,12 +648,15 @@ func TestWebTool_TavilySearch_Success(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool := NewWebSearchTool(WebSearchToolOptions{
+	tool, err := NewWebSearchTool(WebSearchToolOptions{
 		TavilyEnabled:    true,
 		TavilyAPIKey:     "test-key",
 		TavilyBaseURL:    server.URL,
 		TavilyMaxResults: 5,
 	})
+	if err != nil {
+		t.Fatalf("NewWebSearchTool() error: %v", err)
+	}
 
 	ctx := context.Background()
 	args := map[string]any{
@@ -405,3 +681,135 @@ func TestWebTool_TavilySearch_Success(t *testing.T) {
 		t.Errorf("Expected 'via Tavily' in output, 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/http_retry.go b/pkg/utils/http_retry.go
new file mode 100644
index 000000000..135ea0ef5
--- /dev/null
+++ b/pkg/utils/http_retry.go
@@ -0,0 +1,60 @@
+package utils
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"time"
+)
+
+const maxRetries = 3
+
+var retryDelayUnit = time.Second
+
+func shouldRetry(statusCode int) bool {
+	return statusCode == http.StatusTooManyRequests ||
+		statusCode >= 500
+}
+
+func DoRequestWithRetry(client *http.Client, req *http.Request) (*http.Response, error) {
+	var resp *http.Response
+	var err error
+
+	for i := range maxRetries {
+		if i > 0 && resp != nil {
+			resp.Body.Close()
+		}
+
+		resp, err = client.Do(req)
+		if err == nil {
+			if resp.StatusCode == http.StatusOK {
+				break
+			}
+			if !shouldRetry(resp.StatusCode) {
+				break
+			}
+		}
+
+		if i < maxRetries-1 {
+			if err = sleepWithCtx(req.Context(), retryDelayUnit*time.Duration(i+1)); err != nil {
+				if resp != nil {
+					resp.Body.Close()
+				}
+				return nil, fmt.Errorf("failed to sleep: %w", err)
+			}
+		}
+	}
+	return resp, err
+}
+
+func sleepWithCtx(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
+	}
+}
diff --git a/pkg/utils/http_retry_test.go b/pkg/utils/http_retry_test.go
new file mode 100644
index 000000000..d64cd5eda
--- /dev/null
+++ b/pkg/utils/http_retry_test.go
@@ -0,0 +1,206 @@
+package utils
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDoRequestWithRetry(t *testing.T) {
+	retryDelayUnit = time.Millisecond
+	t.Cleanup(func() { retryDelayUnit = time.Second })
+
+	testcases := []struct {
+		name           string
+		serverBehavior func(*httptest.Server) int
+		wantSuccess    bool
+		wantAttempts   int
+	}{
+		{
+			name: "success-on-first-attempt",
+			serverBehavior: func(server *httptest.Server) int {
+				return 0
+			},
+			wantSuccess:  true,
+			wantAttempts: 1,
+		},
+		{
+			name: "fail-all-attempts",
+			serverBehavior: func(server *httptest.Server) int {
+				return 4
+			},
+			wantSuccess:  false,
+			wantAttempts: 3,
+		},
+	}
+
+	for _, tc := range testcases {
+		t.Run(tc.name, func(t *testing.T) {
+			attempts := 0
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				attempts++
+				if attempts <= tc.serverBehavior(nil) {
+					w.WriteHeader(http.StatusInternalServerError)
+					return
+				}
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte("success"))
+			}))
+
+			t.Cleanup(func() {
+				server.Close()
+			})
+
+			client := &http.Client{Timeout: 5 * time.Second}
+			req, err := http.NewRequest(http.MethodGet, server.URL, nil)
+			require.NoError(t, err)
+
+			resp, err := DoRequestWithRetry(client, req)
+
+			if tc.wantSuccess {
+				require.NoError(t, err)
+				require.NotNil(t, resp)
+				assert.Equal(t, http.StatusOK, resp.StatusCode)
+				resp.Body.Close()
+			} else {
+				require.NotNil(t, resp)
+				assert.Equal(t, http.StatusInternalServerError, resp.StatusCode)
+				resp.Body.Close()
+			}
+
+			assert.Equal(t, tc.wantAttempts, attempts)
+		})
+	}
+}
+
+func TestDoRequestWithRetry_ContextCancel(t *testing.T) {
+	// Use a long retry delay so cancellation always hits during sleepWithCtx.
+	retryDelayUnit = 10 * time.Second
+	t.Cleanup(func() { retryDelayUnit = time.Second })
+
+	bodyClosed := false
+	firstRoundTripDone := make(chan struct{}, 1)
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte("error"))
+	}))
+	defer server.Close()
+
+	client := server.Client()
+	client.Timeout = 30 * time.Second
+	client.Transport = &bodyCloseTracker{
+		rt:      client.Transport,
+		onClose: func() { bodyClosed = true },
+		// Signal after the first round-trip response is fully constructed on the client side.
+		onRoundTrip: func() {
+			select {
+			case firstRoundTripDone <- struct{}{}:
+			default:
+			}
+		},
+		trackURL: server.URL,
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// Cancel the context after the first round-trip completes on the client side.
+	// This ensures client.Do has returned a valid resp (with body) and the retry
+	// loop is about to enter sleepWithCtx, where the cancel will be detected.
+	go func() {
+		<-firstRoundTripDone
+		cancel()
+	}()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, server.URL, nil)
+	require.NoError(t, err)
+
+	resp, err := DoRequestWithRetry(client, req)
+	if resp != nil {
+		resp.Body.Close()
+	}
+	require.Error(t, err, "expected error from context cancellation")
+	assert.Nil(t, resp, "expected nil response when context is canceled")
+	assert.True(t, bodyClosed, "expected resp.Body to be closed on context cancellation")
+}
+
+// bodyCloseTracker wraps an http.RoundTripper and records when response bodies are closed.
+type bodyCloseTracker struct {
+	rt          http.RoundTripper
+	onClose     func()
+	onRoundTrip func() // called after each successful round-trip
+	trackURL    string
+}
+
+func (t *bodyCloseTracker) RoundTrip(req *http.Request) (*http.Response, error) {
+	resp, err := t.rt.RoundTrip(req)
+	if err != nil {
+		return resp, err
+	}
+	if strings.HasPrefix(req.URL.String(), t.trackURL) {
+		resp.Body = &closeNotifier{ReadCloser: resp.Body, onClose: t.onClose}
+		if t.onRoundTrip != nil {
+			t.onRoundTrip()
+		}
+	}
+	return resp, nil
+}
+
+// closeNotifier wraps an io.ReadCloser to detect Close calls.
+type closeNotifier struct {
+	io.ReadCloser
+	onClose func()
+}
+
+func (c *closeNotifier) Close() error {
+	c.onClose()
+	return c.ReadCloser.Close()
+}
+
+func TestDoRequestWithRetry_Delay(t *testing.T) {
+	retryDelayUnit = time.Millisecond
+	t.Cleanup(func() { retryDelayUnit = time.Second })
+
+	var start time.Time
+	delays := []time.Duration{}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if len(delays) == 0 {
+			delays = append(delays, 0)
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		if len(delays) == 1 {
+			start = time.Now()
+			delays = append(delays, 0)
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		if len(delays) == 2 {
+			elapsed := time.Since(start)
+			delays = append(delays, elapsed)
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("success"))
+		}
+	}))
+	defer server.Close()
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	req, err := http.NewRequest(http.MethodGet, server.URL, nil)
+	require.NoError(t, err)
+
+	resp, err := DoRequestWithRetry(client, req)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+	resp.Body.Close()
+
+	assert.GreaterOrEqual(t, delays[2], time.Millisecond)
+}
diff --git a/pkg/utils/media.go b/pkg/utils/media.go
index a34889fb8..3e1c5d88e 100644
--- a/pkg/utils/media.go
+++ b/pkg/utils/media.go
@@ -3,6 +3,7 @@ package utils
 import (
 	"io"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -52,11 +53,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
@@ -78,7 +80,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 +94,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 +120,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/message.go b/pkg/utils/message.go
deleted file mode 100644
index 1d05950d9..000000000
--- a/pkg/utils/message.go
+++ /dev/null
@@ -1,179 +0,0 @@
-package utils
-
-import (
-	"strings"
-)
-
-// SplitMessage splits long messages into chunks, preserving code block integrity.
-// The function reserves a buffer (10% of maxLen, min 50) to leave room for closing code blocks,
-// but may extend to maxLen when needed.
-// Call SplitMessage with the full text content and the maximum allowed length of a single message;
-// it returns a slice of message chunks that each respect maxLen and avoid splitting fenced code blocks.
-func SplitMessage(content string, maxLen int) []string {
-	var messages []string
-
-	// Dynamic buffer: 10% of maxLen, but at least 50 chars if possible
-	codeBlockBuffer := maxLen / 10
-	if codeBlockBuffer < 50 {
-		codeBlockBuffer = 50
-	}
-	if codeBlockBuffer > maxLen/2 {
-		codeBlockBuffer = maxLen / 2
-	}
-
-	for len(content) > 0 {
-		if len(content) <= maxLen {
-			messages = append(messages, content)
-			break
-		}
-
-		// Effective split point: maxLen minus buffer, to leave room for code blocks
-		effectiveLimit := maxLen - codeBlockBuffer
-		if effectiveLimit < maxLen/2 {
-			effectiveLimit = maxLen / 2
-		}
-
-		// Find natural split point within the effective limit
-		msgEnd := findLastNewline(content[:effectiveLimit], 200)
-		if msgEnd <= 0 {
-			msgEnd = findLastSpace(content[:effectiveLimit], 100)
-		}
-		if msgEnd <= 0 {
-			msgEnd = effectiveLimit
-		}
-
-		// Check if this would end with an incomplete code block
-		candidate := content[:msgEnd]
-		unclosedIdx := findLastUnclosedCodeBlock(candidate)
-
-		if unclosedIdx >= 0 {
-			// Message would end with incomplete code block
-			// Try to extend up to maxLen to include the closing ```
-			if len(content) > msgEnd {
-				closingIdx := findNextClosingCodeBlock(content, msgEnd)
-				if closingIdx > 0 && closingIdx <= maxLen {
-					// Extend to include the closing ```
-					msgEnd = closingIdx
-				} else {
-					// Code block is too long to fit in one chunk or missing closing fence.
-					// Try to split inside by injecting closing and reopening fences.
-					headerEnd := strings.Index(content[unclosedIdx:], "\n")
-					if headerEnd == -1 {
-						headerEnd = unclosedIdx + 3
-					} else {
-						headerEnd += unclosedIdx
-					}
-					header := strings.TrimSpace(content[unclosedIdx:headerEnd])
-
-					// If we have a reasonable amount of content after the header, split inside
-					if msgEnd > headerEnd+20 {
-						// Find a better split point closer to maxLen
-						innerLimit := maxLen - 5 // Leave room for "\n```"
-						betterEnd := findLastNewline(content[:innerLimit], 200)
-						if betterEnd > headerEnd {
-							msgEnd = betterEnd
-						} else {
-							msgEnd = innerLimit
-						}
-						messages = append(messages, strings.TrimRight(content[:msgEnd], " \t\n\r")+"\n```")
-						content = strings.TrimSpace(header + "\n" + content[msgEnd:])
-						continue
-					}
-
-					// Otherwise, try to split before the code block starts
-					newEnd := findLastNewline(content[:unclosedIdx], 200)
-					if newEnd <= 0 {
-						newEnd = findLastSpace(content[:unclosedIdx], 100)
-					}
-					if newEnd > 0 {
-						msgEnd = newEnd
-					} else {
-						// If we can't split before, we MUST split inside (last resort)
-						if unclosedIdx > 20 {
-							msgEnd = unclosedIdx
-						} else {
-							msgEnd = maxLen - 5
-							messages = append(messages, strings.TrimRight(content[:msgEnd], " \t\n\r")+"\n```")
-							content = strings.TrimSpace(header + "\n" + content[msgEnd:])
-							continue
-						}
-					}
-				}
-			}
-		}
-
-		if msgEnd <= 0 {
-			msgEnd = effectiveLimit
-		}
-
-		messages = append(messages, content[:msgEnd])
-		content = strings.TrimSpace(content[msgEnd:])
-	}
-
-	return messages
-}
-
-// findLastUnclosedCodeBlock finds the last opening ``` that doesn't have a closing ```
-// Returns the position of the opening ``` or -1 if all code blocks are complete
-func findLastUnclosedCodeBlock(text string) int {
-	inCodeBlock := false
-	lastOpenIdx := -1
-
-	for i := 0; i < len(text); i++ {
-		if i+2 < len(text) && text[i] == '`' && text[i+1] == '`' && text[i+2] == '`' {
-			// Toggle code block state on each fence
-			if !inCodeBlock {
-				// Entering a code block: record this opening fence
-				lastOpenIdx = i
-			}
-			inCodeBlock = !inCodeBlock
-			i += 2
-		}
-	}
-
-	if inCodeBlock {
-		return lastOpenIdx
-	}
-	return -1
-}
-
-// findNextClosingCodeBlock finds the next closing ``` starting from a position
-// Returns the position after the closing ``` or -1 if not found
-func findNextClosingCodeBlock(text string, startIdx int) int {
-	for i := startIdx; i < len(text); i++ {
-		if i+2 < len(text) && text[i] == '`' && text[i+1] == '`' && text[i+2] == '`' {
-			return i + 3
-		}
-	}
-	return -1
-}
-
-// findLastNewline finds the last newline character within the last N characters
-// Returns the position of the newline or -1 if not found
-func findLastNewline(s string, searchWindow int) int {
-	searchStart := len(s) - searchWindow
-	if searchStart < 0 {
-		searchStart = 0
-	}
-	for i := len(s) - 1; i >= searchStart; i-- {
-		if s[i] == '\n' {
-			return i
-		}
-	}
-	return -1
-}
-
-// findLastSpace finds the last space character within the last N characters
-// Returns the position of the space or -1 if not found
-func findLastSpace(s string, searchWindow int) int {
-	searchStart := len(s) - searchWindow
-	if searchStart < 0 {
-		searchStart = 0
-	}
-	for i := len(s) - 1; i >= searchStart; i-- {
-		if s[i] == ' ' || s[i] == '\t' {
-			return i
-		}
-	}
-	return -1
-}
diff --git a/pkg/utils/message_test.go b/pkg/utils/message_test.go
deleted file mode 100644
index 338509437..000000000
--- a/pkg/utils/message_test.go
+++ /dev/null
@@ -1,151 +0,0 @@
-package utils
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestSplitMessage(t *testing.T) {
-	longText := strings.Repeat("a", 2500)
-	longCode := "```go\n" + strings.Repeat("fmt.Println(\"hello\")\n", 100) + "```" // ~2100 chars
-
-	tests := []struct {
-		name         string
-		content      string
-		maxLen       int
-		expectChunks int                                 // Check number of chunks
-		checkContent func(t *testing.T, chunks []string) // Custom validation
-	}{
-		{
-			name:         "Empty message",
-			content:      "",
-			maxLen:       2000,
-			expectChunks: 0,
-		},
-		{
-			name:         "Short message fits in one chunk",
-			content:      "Hello world",
-			maxLen:       2000,
-			expectChunks: 1,
-		},
-		{
-			name:         "Simple split regular text",
-			content:      longText,
-			maxLen:       2000,
-			expectChunks: 2,
-			checkContent: func(t *testing.T, chunks []string) {
-				if len(chunks[0]) > 2000 {
-					t.Errorf("Chunk 0 too large: %d", len(chunks[0]))
-				}
-				if len(chunks[0])+len(chunks[1]) != len(longText) {
-					t.Errorf("Total length mismatch. Got %d, want %d", len(chunks[0])+len(chunks[1]), len(longText))
-				}
-			},
-		},
-		{
-			name: "Split at newline",
-			// 1750 chars then newline, then more chars.
-			// Dynamic buffer: 2000 / 10 = 200.
-			// Effective limit: 2000 - 200 = 1800.
-			// Split should happen at newline because it's at 1750 (< 1800).
-			// Total length must > 2000 to trigger split. 1750 + 1 + 300 = 2051.
-			content:      strings.Repeat("a", 1750) + "\n" + strings.Repeat("b", 300),
-			maxLen:       2000,
-			expectChunks: 2,
-			checkContent: func(t *testing.T, chunks []string) {
-				if len(chunks[0]) != 1750 {
-					t.Errorf("Expected chunk 0 to be 1750 length (split at newline), got %d", len(chunks[0]))
-				}
-				if chunks[1] != strings.Repeat("b", 300) {
-					t.Errorf("Chunk 1 content mismatch. Len: %d", len(chunks[1]))
-				}
-			},
-		},
-		{
-			name:         "Long code block split",
-			content:      "Prefix\n" + longCode,
-			maxLen:       2000,
-			expectChunks: 2,
-			checkContent: func(t *testing.T, chunks []string) {
-				// Check that first chunk ends with closing fence
-				if !strings.HasSuffix(chunks[0], "\n```") {
-					t.Error("First chunk should end with injected closing fence")
-				}
-				// Check that second chunk starts with execution header
-				if !strings.HasPrefix(chunks[1], "```go") {
-					t.Error("Second chunk should start with injected code block header")
-				}
-			},
-		},
-		{
-			name:         "Preserve Unicode characters",
-			content:      strings.Repeat("\u4e16", 1000), // 3000 bytes
-			maxLen:       2000,
-			expectChunks: 2,
-			checkContent: func(t *testing.T, chunks []string) {
-				// Just verify we didn't panic and got valid strings.
-				// Go strings are UTF-8, if we split mid-rune it would be bad,
-				// but standard slicing might do that.
-				// Let's assume standard behavior is acceptable or check if it produces invalid rune?
-				if !strings.Contains(chunks[0], "\u4e16") {
-					t.Error("Chunk should contain unicode characters")
-				}
-			},
-		},
-	}
-
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			got := SplitMessage(tc.content, tc.maxLen)
-
-			if tc.expectChunks == 0 {
-				if len(got) != 0 {
-					t.Errorf("Expected 0 chunks, got %d", len(got))
-				}
-				return
-			}
-
-			if len(got) != tc.expectChunks {
-				t.Errorf("Expected %d chunks, got %d", tc.expectChunks, len(got))
-				// Log sizes for debugging
-				for i, c := range got {
-					t.Logf("Chunk %d length: %d", i, len(c))
-				}
-				return // Stop further checks if count assumes specific split
-			}
-
-			if tc.checkContent != nil {
-				tc.checkContent(t, got)
-			}
-		})
-	}
-}
-
-func TestSplitMessage_CodeBlockIntegrity(t *testing.T) {
-	// Focused test for the core requirement: splitting inside a code block preserves syntax highlighting
-
-	// 60 chars total approximately
-	content := "```go\npackage main\n\nfunc main() {\n\tprintln(\"Hello\")\n}\n```"
-	maxLen := 40
-
-	chunks := SplitMessage(content, maxLen)
-
-	if len(chunks) != 2 {
-		t.Fatalf("Expected 2 chunks, got %d: %q", len(chunks), chunks)
-	}
-
-	// First chunk must end with "\n```"
-	if !strings.HasSuffix(chunks[0], "\n```") {
-		t.Errorf("First chunk should end with closing fence. Got: %q", chunks[0])
-	}
-
-	// Second chunk must start with the header "```go"
-	if !strings.HasPrefix(chunks[1], "```go") {
-		t.Errorf("Second chunk should start with code block header. Got: %q", chunks[1])
-	}
-
-	// First chunk should contain meaningful content
-	if len(chunks[0]) > 40 {
-		t.Errorf("First chunk exceeded maxLen: length %d", len(chunks[0]))
-	}
-}
diff --git a/pkg/utils/string.go b/pkg/utils/string.go
index 62d9beee0..02f346db4 100644
--- a/pkg/utils/string.go
+++ b/pkg/utils/string.go
@@ -1,5 +1,31 @@
 package utils
 
+import (
+	"strings"
+	"unicode"
+)
+
+// 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.
+func SanitizeMessageContent(input string) string {
+	var sb strings.Builder
+	// Pre-allocate memory to avoid multiple allocations
+	sb.Grow(len(input))
+
+	for _, r := range input {
+		// unicode.IsGraphic returns true if the rune is a Unicode graphic character.
+		// This includes letters, marks, numbers, punctuation, and symbols.
+		// It excludes control characters (Cc), format characters (Cf),
+		// surrogates (Cs), and private use (Co).
+		if unicode.IsGraphic(r) || r == '\n' || r == '\r' || r == '\t' {
+			sb.WriteRune(r)
+		}
+	}
+
+	return sb.String()
+}
+
 // Truncate returns a truncated version of s with at most maxLen runes.
 // Handles multi-byte Unicode characters properly.
 // If the string is truncated, "..." is appended to indicate truncation.
diff --git a/pkg/utils/string_test.go b/pkg/utils/string_test.go
index a44ead228..e3b5af052 100644
--- a/pkg/utils/string_test.go
+++ b/pkg/utils/string_test.go
@@ -104,3 +104,27 @@ func TestTruncate(t *testing.T) {
 		})
 	}
 }
+
+func TestSanitizeMessageContent(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{"empty", "", ""},
+		{"plain text unchanged", "Hello world", "Hello world"},
+		{"strip ZWSP", "Hello\u200bworld", "Helloworld"},
+		{"strip RTL override", "Hi\u202eevil", "Hievil"},
+		{"strip BOM", "\uFEFFcontent", "content"},
+		{"strip multiple", "a\u200c\u202ab\u202cc", "abc"},
+		{"unicode letters preserved", "café \u65e5\u672c\u8a9e", "café \u65e5\u672c\u8a9e"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := SanitizeMessageContent(tt.input)
+			if got != tt.want {
+				t.Errorf("SanitizeMessageContent(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/pkg/voice/transcriber.go b/pkg/voice/transcriber.go
index f973e77fe..e949d7a22 100644
--- a/pkg/voice/transcriber.go
+++ b/pkg/voice/transcriber.go
@@ -10,12 +10,19 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
+	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
+type Transcriber interface {
+	Name() string
+	Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error)
+}
+
 type GroqTranscriber struct {
 	apiKey     string
 	apiBase    string
@@ -152,8 +159,22 @@ func (t *GroqTranscriber) Transcribe(ctx context.Context, audioFilePath string)
 	return &result, nil
 }
 
-func (t *GroqTranscriber) IsAvailable() bool {
-	available := t.apiKey != ""
-	logger.DebugCF("voice", "Checking transcriber availability", map[string]any{"available": available})
-	return available
+func (t *GroqTranscriber) Name() string {
+	return "groq"
+}
+
+// DetectTranscriber inspects cfg and returns the appropriate Transcriber, or
+// nil if no supported transcription provider is configured.
+func DetectTranscriber(cfg *config.Config) Transcriber {
+	// Direct Groq provider config takes priority.
+	if key := cfg.Providers.Groq.APIKey; key != "" {
+		return NewGroqTranscriber(key)
+	}
+	// 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)
+		}
+	}
+	return nil
 }
diff --git a/pkg/voice/transcriber_test.go b/pkg/voice/transcriber_test.go
new file mode 100644
index 000000000..9b6add333
--- /dev/null
+++ b/pkg/voice/transcriber_test.go
@@ -0,0 +1,160 @@
+package voice
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// Ensure GroqTranscriber satisfies the Transcriber interface at compile time.
+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 TestDetectTranscriber(t *testing.T) {
+	tests := []struct {
+		name     string
+		cfg      *config.Config
+		wantNil  bool
+		wantName string
+	}{
+		{
+			name:    "no config",
+			cfg:     &config.Config{},
+			wantNil: true,
+		},
+		{
+			name: "groq provider key",
+			cfg: &config.Config{
+				Providers: config.ProvidersConfig{
+					Groq: config.ProviderConfig{APIKey: "sk-groq-direct"},
+				},
+			},
+			wantName: "groq",
+		},
+		{
+			name: "groq via model list",
+			cfg: &config.Config{
+				ModelList: []config.ModelConfig{
+					{Model: "openai/gpt-4o", APIKey: "sk-openai"},
+					{Model: "groq/llama-3.3-70b", APIKey: "sk-groq-model"},
+				},
+			},
+			wantName: "groq",
+		},
+		{
+			name: "groq model list entry without key is skipped",
+			cfg: &config.Config{
+				ModelList: []config.ModelConfig{
+					{Model: "groq/llama-3.3-70b", APIKey: ""},
+				},
+			},
+			wantNil: true,
+		},
+		{
+			name: "provider key takes priority over model list",
+			cfg: &config.Config{
+				Providers: config.ProvidersConfig{
+					Groq: config.ProviderConfig{APIKey: "sk-groq-direct"},
+				},
+				ModelList: []config.ModelConfig{
+					{Model: "groq/llama-3.3-70b", APIKey: "sk-groq-model"},
+				},
+			},
+			wantName: "groq",
+		},
+	}
+
+	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)
+			}
+		})
+	}
+}
+
+func TestTranscribe(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/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..559005956
--- /dev/null
+++ b/web/Makefile
@@ -0,0 +1,38 @@
+.PHONY: dev dev-frontend dev-backend build test lint clean
+
+# Run both frontend and backend dev servers
+dev:
+	@if [ ! -f backend/picoclaw-web ] || [ ! -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 && go run .
+
+# Build frontend and embed into Go binary
+build:
+	cd frontend && pnpm build:backend
+	cd backend && go build -o picoclaw-web .
+
+# Run all tests
+test:
+	cd backend && go test ./...
+	cd frontend && pnpm lint
+
+# Lint and format
+lint:
+	cd backend && go vet ./...
+	cd frontend && pnpm check
+
+# Clean build artifacts
+clean:
+	rm -rf frontend/dist backend/dist backend/picoclaw-web
+	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..507882823
--- /dev/null
+++ b/web/backend/api/channels.go
@@ -0,0 +1,47 @@
+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: "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: "wecom_app", ConfigKey: "wecom_app"},
+	{Name: "wecom_aibot", ConfigKey: "wecom_aibot"},
+	{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..f160b42b6
--- /dev/null
+++ b/web/backend/api/config.go
@@ -0,0 +1,221 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// 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)
+}
+
+// loadFilteredConfig loads the configuration and filters out default placeholder credentials
+// (like API limits/keys) if the configuration file has not been created yet by the user.
+func (h *Handler) loadFilteredConfig() (*config.Config, error) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return nil, err
+	}
+
+	configExists := false
+	if h.configPath != "" {
+		if _, err := os.Stat(h.configPath); err == nil {
+			configExists = true
+		}
+	}
+
+	if !configExists {
+		for i := range cfg.ModelList {
+			cfg.ModelList[i].APIKey = ""
+			cfg.ModelList[i].AuthMethod = ""
+		}
+	}
+
+	return cfg, nil
+}
+
+// handleGetConfig returns the complete system configuration.
+//
+//	GET /api/config
+func (h *Handler) handleGetConfig(w http.ResponseWriter, r *http.Request) {
+	cfg, err := h.loadFilteredConfig()
+	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 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
+	}
+
+	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"})
+}
+
+// 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
+	}
+
+	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")
+	}
+
+	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/events.go b/web/backend/api/events.go
new file mode 100644
index 000000000..0a8d4a9bb
--- /dev/null
+++ b/web/backend/api/events.go
@@ -0,0 +1,62 @@
+package api
+
+import (
+	"encoding/json"
+	"sync"
+)
+
+// GatewayEvent represents a state change event for the gateway process.
+type GatewayEvent struct {
+	Status string `json:"gateway_status"` // "running", "starting", "stopped", "error"
+	PID    int    `json:"pid,omitempty"`
+}
+
+// EventBroadcaster manages SSE client subscriptions and broadcasts events.
+type EventBroadcaster struct {
+	mu      sync.RWMutex
+	clients map[chan string]struct{}
+}
+
+// NewEventBroadcaster creates a new broadcaster.
+func NewEventBroadcaster() *EventBroadcaster {
+	return &EventBroadcaster{
+		clients: make(map[chan string]struct{}),
+	}
+}
+
+// Subscribe adds a new listener channel and returns it.
+// The caller must call Unsubscribe when done.
+func (b *EventBroadcaster) Subscribe() chan string {
+	ch := make(chan string, 8)
+	b.mu.Lock()
+	b.clients[ch] = struct{}{}
+	b.mu.Unlock()
+	return ch
+}
+
+// Unsubscribe removes a listener channel and closes it.
+func (b *EventBroadcaster) Unsubscribe(ch chan string) {
+	b.mu.Lock()
+	delete(b.clients, ch)
+	b.mu.Unlock()
+	close(ch)
+}
+
+// Broadcast sends a GatewayEvent to all connected SSE clients.
+func (b *EventBroadcaster) Broadcast(event GatewayEvent) {
+	data, err := json.Marshal(event)
+	if err != nil {
+		return
+	}
+
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	for ch := range b.clients {
+		// Non-blocking send; drop event if client is slow
+		select {
+		case ch <- string(data):
+		default:
+		}
+	}
+}
diff --git a/web/backend/api/gateway.go b/web/backend/api/gateway.go
new file mode 100644
index 000000000..1aea1c801
--- /dev/null
+++ b/web/backend/api/gateway.go
@@ -0,0 +1,555 @@
+package api
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// gateway holds the state for the managed gateway process.
+var gateway = struct {
+	mu     sync.Mutex
+	cmd    *exec.Cmd
+	logs   *LogBuffer
+	events *EventBroadcaster
+}{
+	logs:   NewLogBuffer(200),
+	events: NewEventBroadcaster(),
+}
+
+// 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/events", h.handleGatewayEvents)
+	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() {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	if isGatewayProcessAliveLocked() {
+		return
+	}
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		gateway.cmd = nil
+	}
+
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		log.Printf("Skip auto-starting gateway: %v", err)
+		return
+	}
+	if !ready {
+		log.Printf("Skip auto-starting gateway: %s", reason)
+		return
+	}
+
+	pid, err := h.startGatewayLocked()
+	if err != nil {
+		log.Printf("Failed to auto-start gateway: %v", err)
+		return
+	}
+	log.Printf("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
+	}
+
+	hasCredential := strings.TrimSpace(modelCfg.APIKey) != "" ||
+		strings.TrimSpace(modelCfg.AuthMethod) != ""
+	if !hasCredential {
+		return false, fmt.Sprintf("default model %q has no credentials configured", 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 isGatewayProcessAliveLocked() bool {
+	return isCmdProcessAliveLocked(gateway.cmd)
+}
+
+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 (h *Handler) startGatewayLocked() (int, error) {
+	// Locate the picoclaw executable
+	execPath := findPicoclawBinary()
+
+	cmd := exec.Command(execPath, "gateway")
+
+	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 {
+		log.Printf("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
+	pid := cmd.Process.Pid
+	log.Printf("Started picoclaw gateway (PID: %d) from %s", pid, execPath)
+
+	// Broadcast starting event
+	gateway.events.Broadcast(GatewayEvent{Status: "starting", PID: pid})
+
+	// 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 {
+			log.Printf("Gateway process exited: %v", err)
+		} else {
+			log.Printf("Gateway process exited normally")
+		}
+
+		gateway.mu.Lock()
+		if gateway.cmd == cmd {
+			gateway.cmd = nil
+		}
+		gateway.mu.Unlock()
+
+		// Broadcast stopped event
+		gateway.events.Broadcast(GatewayEvent{Status: "stopped"})
+	}()
+
+	// Start a goroutine to probe health and broadcast "running" 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
+			}
+			healthHost := "127.0.0.1"
+			if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
+				healthHost = cfg.Gateway.Host
+			}
+			healthPort := cfg.Gateway.Port
+			if healthPort == 0 {
+				healthPort = 18790
+			}
+			healthURL := fmt.Sprintf("http://%s/health", net.JoinHostPort(healthHost, strconv.Itoa(healthPort)))
+			client := http.Client{Timeout: 1 * time.Second}
+			resp, err := client.Get(healthURL)
+			if err == nil {
+				resp.Body.Close()
+				if resp.StatusCode == http.StatusOK {
+					gateway.events.Broadcast(GatewayEvent{Status: "running", PID: pid})
+					return
+				}
+			}
+		}
+	}()
+
+	return pid, nil
+}
+
+// handleGatewayStart starts the picoclaw gateway subprocess.
+//
+//	POST /api/gateway/start
+func (h *Handler) handleGatewayStart(w http.ResponseWriter, r *http.Request) {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	// Prevent duplicate starts
+	if isGatewayProcessAliveLocked() {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusConflict)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "already_running",
+			"pid":    gateway.cmd.Process.Pid,
+		})
+		return
+	}
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		gateway.cmd = nil
+	}
+
+	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()
+	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.
+//
+//	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 := 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 {
+		http.Error(w, fmt.Sprintf("Failed to stop gateway (PID %d): %v", pid, sigErr), http.StatusInternalServerError)
+		return
+	}
+
+	log.Printf("Sent stop signal to gateway (PID: %d)", pid)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"pid":    pid,
+	})
+}
+
+// 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) {
+	gateway.mu.Lock()
+
+	// Stop existing process if running
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		if isCmdProcessAliveLocked(gateway.cmd) {
+			// Process is alive, send SIGTERM
+			if runtime.GOOS == "windows" {
+				gateway.cmd.Process.Kill()
+			} else {
+				gateway.cmd.Process.Signal(syscall.SIGTERM)
+			}
+
+			// Wait briefly for it to exit
+			gateway.mu.Unlock()
+			time.Sleep(2 * time.Second)
+			gateway.mu.Lock()
+		}
+		gateway.cmd = nil
+	}
+
+	gateway.mu.Unlock()
+
+	// Start fresh via the existing handler
+	h.handleGatewayStart(w, r)
+}
+
+// handleGatewayStatus returns the gateway run status, health info, and logs.
+//
+//	GET /api/gateway/status
+func (h *Handler) handleGatewayStatus(w http.ResponseWriter, r *http.Request) {
+	data := map[string]any{}
+
+	// Check process state
+	gateway.mu.Lock()
+	processAlive := isGatewayProcessAliveLocked()
+	if processAlive {
+		data["pid"] = gateway.cmd.Process.Pid
+	}
+	gateway.mu.Unlock()
+
+	if !processAlive {
+		data["gateway_status"] = "stopped"
+	} else {
+		// Process is alive — probe its health endpoint
+		cfg, err := config.LoadConfig(h.configPath)
+		host := "127.0.0.1"
+		port := 18790
+		if err == 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)
+
+		if err != nil {
+			data["gateway_status"] = "starting"
+		} else {
+			defer resp.Body.Close()
+			if resp.StatusCode != http.StatusOK {
+				data["gateway_status"] = "error"
+				data["status_code"] = resp.StatusCode
+			} else {
+				var healthData map[string]any
+				if decErr := json.NewDecoder(resp.Body).Decode(&healthData); decErr != nil {
+					data["gateway_status"] = "error"
+				} else {
+					for k, v := range healthData {
+						data[k] = v
+					}
+					data["gateway_status"] = "running"
+				}
+			}
+		}
+	}
+
+	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
+		}
+	}
+
+	// Append incremental log data
+	appendGatewayLogs(r, data)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(data)
+}
+
+// appendGatewayLogs reads log_offset and log_run_id query params from the request
+// and populates the response data map with incremental log lines.
+func appendGatewayLogs(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 := gateway.logs.RunID()
+
+	if runID == 0 {
+		data["logs"] = []string{}
+		data["log_total"] = 0
+		data["log_run_id"] = 0
+		return
+	}
+
+	// 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
+}
+
+// handleGatewayEvents serves an SSE stream of gateway state change events.
+//
+//	GET /api/gateway/events
+func (h *Handler) handleGatewayEvents(w http.ResponseWriter, r *http.Request) {
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "SSE not supported", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
+
+	// Subscribe to gateway events
+	ch := gateway.events.Subscribe()
+	defer gateway.events.Unsubscribe(ch)
+
+	// Send initial status so the client doesn't start blank
+	initial := h.currentGatewayStatus()
+	fmt.Fprintf(w, "data: %s\n\n", initial)
+	flusher.Flush()
+
+	for {
+		select {
+		case <-r.Context().Done():
+			return
+		case data, ok := <-ch:
+			if !ok {
+				return
+			}
+			fmt.Fprintf(w, "data: %s\n\n", data)
+			flusher.Flush()
+		}
+	}
+}
+
+// currentGatewayStatus returns the current gateway status as a JSON string.
+func (h *Handler) currentGatewayStatus() string {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	data := map[string]any{
+		"gateway_status": "stopped",
+	}
+	if isGatewayProcessAliveLocked() {
+		data["gateway_status"] = "running"
+		data["pid"] = gateway.cmd.Process.Pid
+	}
+
+	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
+		}
+	}
+
+	encoded, _ := json.Marshal(data)
+	return string(encoded)
+}
+
+// findPicoclawBinary locates the picoclaw executable.
+// Tries the same directory as the current executable first, then falls back to $PATH.
+func findPicoclawBinary() string {
+	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() {
+			return candidate
+		}
+	}
+	return "picoclaw"
+}
+
+// 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_test.go b/web/backend/api/gateway_test.go
new file mode 100644
index 000000000..336bb6a0c
--- /dev/null
+++ b/web/backend/api/gateway_test.go
@@ -0,0 +1,122 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+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.Model = "missing-model"
+	if err := config.SaveConfig(configPath, cfg); 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].APIKey = "test-key"
+	if err := config.SaveConfig(configPath, cfg); 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].APIKey = ""
+	cfg.ModelList[0].AuthMethod = ""
+	if err := config.SaveConfig(configPath, cfg); 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 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"])
+	}
+}
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..5049dd88f
--- /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, []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/web/backend/api/log.go b/web/backend/api/log.go
new file mode 100644
index 000000000..ecf7d422f
--- /dev/null
+++ b/web/backend/api/log.go
@@ -0,0 +1,91 @@
+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).
+type LogBuffer struct {
+	mu    sync.RWMutex
+	lines []string
+	cap   int
+	total int // total lines ever appended in current run
+	runID int
+}
+
+// NewLogBuffer creates a LogBuffer with the given capacity.
+func NewLogBuffer(capacity int) *LogBuffer {
+	return &LogBuffer{
+		lines: make([]string, 0, capacity),
+		cap:   capacity,
+	}
+}
+
+// Append adds a line to the buffer. If the buffer is full, the oldest line is evicted.
+func (b *LogBuffer) Append(line string) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	if len(b.lines) < b.cap {
+		b.lines = append(b.lines, line)
+	} else {
+		b.lines[b.total%b.cap] = line
+	}
+
+	b.total++
+}
+
+// Reset clears the buffer and increments the runID. Call this when starting a new gateway process.
+func (b *LogBuffer) Reset() {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	b.lines = b.lines[:0]
+	b.total = 0
+	b.runID++
+}
+
+// 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) {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	total = b.total
+	runID = b.runID
+
+	if offset >= b.total {
+		return nil, total, runID
+	}
+
+	buffered := len(b.lines)
+
+	// How many new lines since offset
+	newCount := b.total - offset
+	if newCount > buffered {
+		newCount = buffered
+	}
+
+	result := make([]string, newCount)
+
+	if b.total <= b.cap {
+		// Buffer hasn't wrapped yet — simple slice
+		copy(result, b.lines[buffered-newCount:])
+	} else {
+		// Buffer has wrapped — read from ring
+		start := (b.total - newCount) % b.cap
+		for i := range newCount {
+			result[i] = b.lines[(start+i)%b.cap]
+		}
+	}
+
+	return result, total, runID
+}
+
+// RunID returns the current run identifier.
+func (b *LogBuffer) RunID() int {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	return b.runID
+}
diff --git a/web/backend/api/models.go b/web/backend/api/models.go
new file mode 100644
index 000000000..cb57d6f2e
--- /dev/null
+++ b/web/backend/api/models.go
@@ -0,0 +1,298 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// 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"`
+	// Meta
+	Configured bool `json:"configured"`
+	IsDefault  bool `json:"is_default"`
+}
+
+// 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 := h.loadFilteredConfig()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	defaultModel := cfg.Agents.Defaults.GetModelName()
+
+	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,
+			Configured:     m.APIKey != "" || m.AuthMethod != "",
+			IsDefault:      m.ModelName == defaultModel,
+		})
+	}
+
+	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()
+
+	var mc config.ModelConfig
+	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
+	}
+
+	cfg.ModelList = append(cfg.ModelList, mc)
+
+	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()
+
+	var mc config.ModelConfig
+	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.APIKey = cfg.ModelList[idx].APIKey
+	}
+
+	cfg.ModelList[idx] = mc
+
+	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 cfg.Agents.Defaults.Model == deletedModelName {
+		cfg.Agents.Defaults.Model = ""
+	}
+
+	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
+	found := false
+	for _, m := range cfg.ModelList {
+		if m.ModelName == req.ModelName {
+			found = true
+			break
+		}
+	}
+	if !found {
+		http.Error(w, fmt.Sprintf("Model %q not found in model_list", req.ModelName), http.StatusNotFound)
+		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 8 chars show prefix + last 4 chars: "sk-****abcd"
+// Shorter keys are fully masked as "****".
+// Empty keys return empty string.
+func maskAPIKey(key string) string {
+	if key == "" {
+		return ""
+	}
+	if len(key) <= 8 {
+		return "****"
+	}
+	// Show first 3 chars and last 4 chars
+	return key[:3] + "****" + key[len(key)-4:]
+}
diff --git a/web/backend/api/oauth.go b/web/backend/api/oauth.go
new file mode 100644
index 000000000..04cd595f2
--- /dev/null
+++ b/web/backend/api/oauth.go
@@ -0,0 +1,844 @@
+package api
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"html"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"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 {
+				log.Printf("oauth warning: could not fetch google email: %v", err)
+			} else {
+				cp.Email = email
+			}
+		}
+		if cp.ProjectID == "" {
+			projectID, err := oauthFetchAntigravityProject(cp.AccessToken)
+			if err != nil {
+				log.Printf("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
+	}
+
+	switch provider {
+	case oauthProviderOpenAI:
+		cfg.Providers.OpenAI.AuthMethod = authMethod
+	case oauthProviderAnthropic:
+		cfg.Providers.Anthropic.AuthMethod = authMethod
+	case oauthProviderGoogleAntigravity:
+		cfg.Providers.Antigravity.AuthMethod = authMethod
+	default:
+		return fmt.Errorf("unsupported provider %q", provider)
+	}
+
+	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.2",
+			Model:      "openai/gpt-5.2",
+			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..2103e1efc
--- /dev/null
+++ b/web/backend/api/oauth_test.go
@@ -0,0 +1,293 @@
+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.Providers.OpenAI.AuthMethod = "oauth"
+	cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+		ModelName:  "gpt-5.2",
+		Model:      "openai/gpt-5.2",
+		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)
+	}
+	if updated.Providers.OpenAI.AuthMethod != "" {
+		t.Fatalf("providers.openai.auth_method = %q, want empty", updated.Providers.OpenAI.AuthMethod)
+	}
+	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",
+		APIKey:    "sk-default",
+	}}
+	cfg.Agents.Defaults.ModelName = "custom-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..fc942d51c
--- /dev/null
+++ b/web/backend/api/pico.go
@@ -0,0 +1,161 @@
+package api
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"strconv"
+	"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)
+}
+
+// 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 := 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.Token = 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 := fmt.Sprintf("ws://%s/pico/ws", net.JoinHostPort(cfg.Gateway.Host, strconv.Itoa(cfg.Gateway.Port)))
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"token":  token,
+		"ws_url": wsURL,
+	})
+}
+
+// ensurePicoChannel checks if the Pico Channel is properly configured and
+// enables it with sensible defaults if not. Returns true if config was changed.
+func (h *Handler) ensurePicoChannel() (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.Token = generateSecureToken()
+		changed = true
+	}
+
+	if !cfg.Channels.Pico.AllowTokenQuery {
+		cfg.Channels.Pico.AllowTokenQuery = true
+		changed = true
+	}
+
+	// Make sure origins are allowed (frontend might be running on a different port like 5173 during dev)
+	if len(cfg.Channels.Pico.AllowOrigins) == 0 {
+		cfg.Channels.Pico.AllowOrigins = []string{"*"}
+		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()
+	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 := 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,
+	})
+}
+
+// buildWsURL creates a WebSocket URL for the Pico Channel.
+// When the gateway host is "0.0.0.0" or empty, it uses the hostname from the
+// incoming HTTP request so the browser gets a connectable address.
+func buildWsURL(r *http.Request, cfg *config.Config) string {
+	host := cfg.Gateway.Host
+	if host == "" || host == "0.0.0.0" {
+		// Use the hostname the browser used to reach this backend
+		reqHost, _, err := net.SplitHostPort(r.Host)
+		if err != nil {
+			reqHost = r.Host // r.Host might not have a port
+		}
+		host = reqHost
+	}
+	return "ws://" + net.JoinHostPort(host, strconv.Itoa(cfg.Gateway.Port)) + "/pico/ws"
+}
+
+// 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/router.go b/web/backend/api/router.go
new file mode 100644
index 000000000..c250724d1
--- /dev/null
+++ b/web/backend/api/router.go
@@ -0,0 +1,66 @@
+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
+	serverCIDRs  []string
+	oauthMu      sync.Mutex
+	oauthFlows   map[string]*oauthFlow
+	oauthState   map[string]string
+}
+
+// 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),
+	}
+}
+
+// SetServerOptions stores current backend listen options for fallback behavior.
+func (h *Handler) SetServerOptions(port int, public bool, allowedCIDRs []string) {
+	h.serverPort = port
+	h.serverPublic = public
+	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)
+
+	// OS startup / launch-at-login
+	h.registerStartupRoutes(mux)
+
+	// Launcher service parameters (port/public)
+	h.registerLauncherConfigRoutes(mux)
+}
diff --git a/web/backend/api/session.go b/web/backend/api/session.go
new file mode 100644
index 000000000..e3cf674fc
--- /dev/null
+++ b/web/backend/api/session.go
@@ -0,0 +1,286 @@
+package api
+
+import (
+	"encoding/json"
+	"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"`
+	Preview      string `json:"preview"`
+	MessageCount int    `json:"message_count"`
+	Created      string `json:"created"`
+	Updated      string `json:"updated"`
+}
+
+// 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:"
+
+// 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
+}
+
+// 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{}
+
+	for _, entry := range entries {
+		if entry.IsDir() || filepath.Ext(entry.Name()) != ".json" {
+			continue
+		}
+
+		data, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+		if err != nil {
+			continue
+		}
+
+		var sess sessionFile
+		if err := json.Unmarshal(data, &sess); err != nil {
+			continue
+		}
+
+		// Only include Pico channel sessions
+		sessionID, ok := extractPicoSessionID(sess.Key)
+		if !ok {
+			continue
+		}
+
+		// Build a preview from the first user message
+		preview := ""
+		for _, msg := range sess.Messages {
+			if msg.Role == "user" && strings.TrimSpace(msg.Content) != "" {
+				preview = msg.Content
+				break
+			}
+		}
+		if len([]rune(preview)) > 60 {
+			preview = string([]rune(preview)[:60]) + "..."
+		}
+		if preview == "" {
+			preview = "(empty)"
+		}
+
+		// Only count non-empty user and assistant messages
+		validMessageCount := 0
+		for _, msg := range sess.Messages {
+			if (msg.Role == "user" || msg.Role == "assistant") && strings.TrimSpace(msg.Content) != "" {
+				validMessageCount++
+			}
+		}
+
+		items = append(items, sessionListItem{
+			ID:           sessionID,
+			Preview:      preview,
+			MessageCount: validMessageCount,
+			Created:      sess.Created.Format(time.RFC3339),
+			Updated:      sess.Updated.Format(time.RFC3339),
+		})
+	}
+
+	// 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
+	}
+
+	// The sanitized filename replaces ':' with '_':
+	// agent:main:pico:direct:pico:<uuid> -> agent_main_pico_direct_pico_<uuid>.json
+	filename := strings.ReplaceAll(picoSessionPrefix+sessionID, ":", "_") + ".json"
+
+	data, err := os.ReadFile(filepath.Join(dir, filename))
+	if err != nil {
+		http.Error(w, "session not found", http.StatusNotFound)
+		return
+	}
+
+	var sess sessionFile
+	if err := json.Unmarshal(data, &sess); err != nil {
+		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
+	}
+
+	// The sanitized filename replaces ':' with '_':
+	// agent:main:pico:direct:pico:<uuid> -> agent_main_pico_direct_pico_<uuid>.json
+	filename := strings.ReplaceAll(picoSessionPrefix+sessionID, ":", "_") + ".json"
+	filePath := filepath.Join(dir, filename)
+
+	if err := os.Remove(filePath); err != nil {
+		if os.IsNotExist(err) {
+			http.Error(w, "session not found", http.StatusNotFound)
+		} else {
+			http.Error(w, "failed to delete session", http.StatusInternalServerError)
+		}
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}
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/dist/.gitkeep b/web/backend/dist/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/web/backend/embed.go b/web/backend/embed.go
new file mode 100644
index 000000000..556fb7384
--- /dev/null
+++ b/web/backend/embed.go
@@ -0,0 +1,69 @@
+package main
+
+import (
+	"embed"
+	"io/fs"
+	"log"
+	"net/http"
+	"path"
+	"strings"
+)
+
+//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) {
+	// 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)
+		log.Printf(
+			"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/icon.ico b/web/backend/icon.ico
new file mode 100644
index 000000000..4f6539414
Binary files /dev/null and b/web/backend/icon.ico 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..b8c4dc2bb
--- /dev/null
+++ b/web/backend/main.go
@@ -0,0 +1,164 @@
+// 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"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"time"
+
+	"github.com/sipeed/picoclaw/web/backend/api"
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+	"github.com/sipeed/picoclaw/web/backend/middleware"
+)
+
+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")
+
+	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()
+
+	// Resolve config path
+	configPath := getDefaultConfigPath()
+	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 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 {
+		log.Printf("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")
+		}
+		log.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)
+	apiHandler.SetServerOptions(portNum, effectivePublic, launcherCfg.AllowedCIDRs)
+	apiHandler.RegisterRoutes(mux)
+
+	// Frontend Embedded Assets
+	registerEmbedRoutes(mux)
+
+	accessControlledMux, err := middleware.IPAllowlist(launcherCfg.AllowedCIDRs, mux)
+	if err != nil {
+		log.Fatalf("Invalid allowed CIDR configuration: %v", err)
+	}
+
+	// Apply middleware stack
+	handler := middleware.Recoverer(
+		middleware.Logger(
+			middleware.JSONContentType(accessControlledMux),
+		),
+	)
+
+	// Print startup banner
+	fmt.Print(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 := getLocalIP(); ip != "" {
+			fmt.Printf("    >> http://%s:%s <<\n", ip, effectivePort)
+		}
+	}
+	fmt.Println()
+
+	// Auto-open browser
+	if !*noBrowser {
+		go func() {
+			time.Sleep(500 * time.Millisecond)
+			url := "http://localhost:" + effectivePort
+			if err := openBrowser(url); err != nil {
+				log.Printf("Warning: Failed to auto-open browser: %v", err)
+			}
+		}()
+	}
+
+	// Auto-start gateway after backend starts listening.
+	go func() {
+		time.Sleep(1 * time.Second)
+		apiHandler.TryAutoStartGateway()
+	}()
+
+	// Start the Server
+	if err := http.ListenAndServe(addr, handler); err != nil {
+		log.Fatalf("Server failed to start: %v", err)
+	}
+}
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..de9e6d870
--- /dev/null
+++ b/web/backend/middleware/middleware.go
@@ -0,0 +1,70 @@
+package middleware
+
+import (
+	"log"
+	"net/http"
+	"runtime/debug"
+	"strings"
+	"time"
+)
+
+// JSONContentType sets the Content-Type header to application/json for
+// API requests handled by the wrapped handler.
+// SSE endpoints (text/event-stream) are excluded.
+func JSONContentType(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/api/") && !strings.HasSuffix(r.URL.Path, "/events") {
+			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.
+// This is required for SSE (Server-Sent Events) to work through the middleware.
+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)
+		log.Printf("%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 {
+				log.Printf("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/utils.go b/web/backend/utils.go
new file mode 100644
index 000000000..6fa734aeb
--- /dev/null
+++ b/web/backend/utils.go
@@ -0,0 +1,61 @@
+package main
+
+import (
+	"fmt"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+)
+
+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
+)
+
+// getDefaultConfigPath returns the default path to the picoclaw config file.
+func getDefaultConfigPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "config.json"
+	}
+	return filepath.Join(home, ".picoclaw", "config.json")
+}
+
+// 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/web/backend/winres/winres.json b/web/backend/winres/winres.json
new file mode 100644
index 000000000..01ea7364c
--- /dev/null
+++ b/web/backend/winres/winres.json
@@ -0,0 +1,22 @@
+{
+  "RT_GROUP_ICON": {
+    "APP": {
+      "0000": "../icon.ico"
+    }
+  },
+  "RT_MANIFEST": {
+    "#1": {
+      "0409": {
+        "identity": {
+          "name": "PicoClaw Launcher",
+          "version": "0.0.0.0"
+        },
+        "description": "PicoClaw Launcher - Web-based configuration editor",
+        "minimum-os": "win7",
+        "execution-level": "asInvoker",
+        "dpi-awareness": "system",
+        "use-common-controls-v6": true
+      }
+    }
+  }
+}
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..4811cdd9b
--- /dev/null
+++ b/web/frontend/.gitignore
@@ -0,0 +1,26 @@
+# Logs
+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
\ No newline at end of file
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..ee46cdcda
--- /dev/null
+++ b/web/frontend/package.json
@@ -0,0 +1,62 @@
+{
+  "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",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "format": "prettier --check .",
+    "check": "prettier --write . && eslint --fix"
+  },
+  "dependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
+    "@tabler/icons-react": "^3.38.0",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-router": "^1.163.3",
+    "@tanstack/react-router-devtools": "^1.163.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "dayjs": "^1.11.19",
+    "i18next": "^25.8.14",
+    "i18next-browser-languagedetector": "^8.2.1",
+    "jotai": "^2.18.0",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-i18next": "^16.5.4",
+    "react-markdown": "^10.1.0",
+    "react-textarea-autosize": "^8.5.9",
+    "remark-gfm": "^4.0.1",
+    "shadcn": "^3.8.5",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.1",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tanstack/router-plugin": "^1.164.0",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^7.3.1"
+  }
+}
diff --git a/web/frontend/pnpm-lock.yaml b/web/frontend/pnpm-lock.yaml
new file mode 100644
index 000000000..8e89cbbe5
--- /dev/null
+++ b/web/frontend/pnpm-lock.yaml
@@ -0,0 +1,7981 @@
+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.38.0
+        version: 3.38.0(react@19.2.4)
+      '@tailwindcss/vite':
+        specifier: ^4.2.1
+        version: 4.2.1(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))
+      '@tanstack/react-query':
+        specifier: ^5.90.21
+        version: 5.90.21(react@19.2.4)
+      '@tanstack/react-router':
+        specifier: ^1.163.3
+        version: 1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@tanstack/react-router-devtools':
+        specifier: ^1.163.3
+        version: 1.163.3(@tanstack/react-router@1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.163.3)(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.19
+        version: 1.11.19
+      i18next:
+        specifier: ^25.8.14
+        version: 25.8.14(typescript@5.9.3)
+      i18next-browser-languagedetector:
+        specifier: ^8.2.1
+        version: 8.2.1
+      jotai:
+        specifier: ^2.18.0
+        version: 2.18.0(@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.4
+        version: 16.5.4(i18next@25.8.14(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)
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
+      shadcn:
+        specifier: ^3.8.5
+        version: 3.8.5(@types/node@24.11.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.1
+        version: 4.2.1
+      tw-animate-css:
+        specifier: ^1.4.0
+        version: 1.4.0
+    devDependencies:
+      '@eslint/js':
+        specifier: ^9.39.1
+        version: 9.39.3
+      '@tailwindcss/typography':
+        specifier: ^0.5.19
+        version: 0.5.19(tailwindcss@4.2.1)
+      '@tanstack/router-plugin':
+        specifier: ^1.164.0
+        version: 1.164.0(@tanstack/react-router@1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))
+      '@trivago/prettier-plugin-sort-imports':
+        specifier: ^6.0.2
+        version: 6.0.2(prettier@3.8.1)
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.11.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.56.1
+        version: 8.56.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      '@vitejs/plugin-react':
+        specifier: ^5.1.1
+        version: 5.1.4(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))
+      eslint:
+        specifier: ^9.39.1
+        version: 9.39.3(jiti@2.6.1)
+      eslint-config-prettier:
+        specifier: ^10.1.8
+        version: 10.1.8(eslint@9.39.3(jiti@2.6.1))
+      eslint-plugin-react-hooks:
+        specifier: ^7.0.1
+        version: 7.0.1(eslint@9.39.3(jiti@2.6.1))
+      eslint-plugin-react-refresh:
+        specifier: ^0.4.24
+        version: 0.4.26(eslint@9.39.3(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.48.0
+        version: 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      vite:
+        specifier: ^7.3.1
+        version: 7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0)
+
+packages:
+
+  '@antfu/ni@25.0.0':
+    resolution: {integrity: sha512-9q/yCljni37pkMr4sPrI3G4jqdIk074+iukc5aFJl7kmDCCsiJrbZ6zKxnES1Gwg+i9RcDZwvktl23puGslmvA==}
+    hasBin: true
+
+  '@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.28.6':
+    resolution: {integrity: sha512-xOBvwq86HHdB7WUDTfKfT/Vuxh7gElQ+Sfti2Cy6yIWNW05P8iUslOVcZ4/sKbE+/jQaukQAdz/gf3724kYdqw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.0':
+    resolution: {integrity: sha512-IyDgFV5GeDUVX4YdF/3CPULtVGSXXMLh1xVIgdCgxApktqnQV0r7/8Nqthg+8YLGaAtdyIlo2qIdZrbCv4+7ww==}
+    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.28.6':
+    resolution: {integrity: sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==}
+    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.52.0':
+    resolution: {integrity: sha512-CaQcc8JvtzQhUSm9877b6V4Tb7HCotkcyud9X2YwdqtQKwgljkMRwU96fVYKnzN3V0Hj74oP7Es+vZ0mS+Aa1w==}
+    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.3':
+    resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.3':
+    resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.3':
+    resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.3':
+    resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.3':
+    resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.3':
+    resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.3':
+    resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.3':
+    resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.3':
+    resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.3':
+    resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.3':
+    resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.3':
+    resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.3':
+    resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.3':
+    resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.3':
+    resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.3':
+    resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.3':
+    resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.3':
+    resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.3':
+    resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.3':
+    resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.3':
+    resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.3':
+    resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+    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.1':
+    resolution: {integrity: sha512-aw1gNayWpdI/jSYVgzN5pL0cfzU02GT3NBpeT/DXbx1/1x7ZKxFPd9bwrzygx/qiwIQiJ1sw/zD8qY/kRvlGHA==}
+    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.4':
+    resolution: {integrity: sha512-4h4MVF8pmBsncB60r0wSJiIeUKTSD4m7FmTFThG8RHlsg9ajqckLm9OraguFGZE4vVdpiI1Q4+hFnisopmG6gQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/js@9.39.3':
+    resolution: {integrity: sha512-1B1VkCq6FuUNlQvlBYb+1jDu/gV297TIs/OeiaSR9l1H27SVW55ONE1e1Vp16NqP683+xEGzxYtv4XCiDPaQiw==}
+    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.4':
+    resolution: {integrity: sha512-C3HlIdsBxszvm5McXlB8PeOEWfBhcGBTZGkGlWc2U0KFY5IwG5OQEuQ8rq52DZmcHDlPLd+YFBK+cZcytwIFWg==}
+
+  '@floating-ui/dom@1.7.5':
+    resolution: {integrity: sha512-N0bD2kIPInNHUHehXhMke1rBGs1dwqvC9O9KYMyyjK7iXt7GAhnro7UlcuYcGdS/yYOlq0MAVgrow8IbWJwyqg==}
+
+  '@floating-ui/react-dom@2.1.7':
+    resolution: {integrity: sha512-0tLRojf/1Go2JgEVm+3Frg9A3IW8bJgKgdO0BN5RkF//ufuz2joZM63Npau2ff3J6lUVYgDSNzNkR+aH3IVfjg==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@floating-ui/utils@0.2.10':
+    resolution: {integrity: sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ==}
+
+  '@fontsource-variable/inter@5.2.8':
+    resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
+
+  '@hono/node-server@1.19.9':
+    resolution: {integrity: sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw==}
+    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]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-arm-musleabihf@4.59.0':
+    resolution: {integrity: sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==}
+    cpu: [arm]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-arm64-gnu@4.59.0':
+    resolution: {integrity: sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-arm64-musl@4.59.0':
+    resolution: {integrity: sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-loong64-gnu@4.59.0':
+    resolution: {integrity: sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==}
+    cpu: [loong64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-loong64-musl@4.59.0':
+    resolution: {integrity: sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==}
+    cpu: [loong64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-ppc64-gnu@4.59.0':
+    resolution: {integrity: sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-ppc64-musl@4.59.0':
+    resolution: {integrity: sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-riscv64-gnu@4.59.0':
+    resolution: {integrity: sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-riscv64-musl@4.59.0':
+    resolution: {integrity: sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-s390x-gnu@4.59.0':
+    resolution: {integrity: sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-x64-gnu@4.59.0':
+    resolution: {integrity: sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-x64-musl@4.59.0':
+    resolution: {integrity: sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@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.38.0':
+    resolution: {integrity: sha512-kR5wv+m4+GgmnSszg3rQd6SrTFAQ/XnQC/yTwIfuRJSfqB12KoIC7fPbIijFgOHTFlBN5DARnN0IVrR7KYG6/A==}
+    peerDependencies:
+      react: '>= 16'
+
+  '@tabler/icons@3.38.0':
+    resolution: {integrity: sha512-FdETQSpQ3lN7BEjEUzjKhsfTDCamrvMDops4HEMphTm3DmkIFpThoODn8XXZ8Q9MhjshIvphIYVHHB7zpq167w==}
+
+  '@tailwindcss/node@4.2.1':
+    resolution: {integrity: sha512-jlx6sLk4EOwO6hHe1oCGm1Q4AN/s0rSrTTPBGPM0/RQ6Uylwq17FuU8IeJJKEjtc6K6O07zsvP+gDO6MMWo7pg==}
+
+  '@tailwindcss/oxide-android-arm64@4.2.1':
+    resolution: {integrity: sha512-eZ7G1Zm5EC8OOKaesIKuw77jw++QJ2lL9N+dDpdQiAB/c/B2wDh0QPFHbkBVrXnwNugvrbJFk1gK2SsVjwWReg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.2.1':
+    resolution: {integrity: sha512-q/LHkOstoJ7pI1J0q6djesLzRvQSIfEto148ppAd+BVQK0JYjQIFSK3JgYZJa+Yzi0DDa52ZsQx2rqytBnf8Hw==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.2.1':
+    resolution: {integrity: sha512-/f/ozlaXGY6QLbpvd/kFTro2l18f7dHKpB+ieXz+Cijl4Mt9AI2rTrpq7V+t04nK+j9XBQHnSMdeQRhbGyt6fw==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.2.1':
+    resolution: {integrity: sha512-5e/AkgYJT/cpbkys/OU2Ei2jdETCLlifwm7ogMC7/hksI2fC3iiq6OcXwjibcIjPung0kRtR3TxEITkqgn0TcA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.1':
+    resolution: {integrity: sha512-Uny1EcVTTmerCKt/1ZuKTkb0x8ZaiuYucg2/kImO5A5Y/kBz41/+j0gxUZl+hTF3xkWpDmHX+TaWhOtba2Fyuw==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.2.1':
+    resolution: {integrity: sha512-CTrwomI+c7n6aSSQlsPL0roRiNMDQ/YzMD9EjcR+H4f0I1SQ8QqIuPnsVp7QgMkC1Qi8rtkekLkOFjo7OlEFRQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.2.1':
+    resolution: {integrity: sha512-WZA0CHRL/SP1TRbA5mp9htsppSEkWuQ4KsSUumYQnyl8ZdT39ntwqmz4IUHGN6p4XdSlYfJwM4rRzZLShHsGAQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.2.1':
+    resolution: {integrity: sha512-qMFzxI2YlBOLW5PhblzuSWlWfwLHaneBE0xHzLrBgNtqN6mWfs+qYbhryGSXQjFYB1Dzf5w+LN5qbUTPhW7Y5g==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.2.1':
+    resolution: {integrity: sha512-5r1X2FKnCMUPlXTWRYpHdPYUY6a1Ar/t7P24OuiEdEOmms5lyqjDRvVY1yy9Rmioh+AunQ0rWiOTPE8F9A3v5g==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.2.1':
+    resolution: {integrity: sha512-MGFB5cVPvshR85MTJkEvqDUnuNoysrsRxd6vnk1Lf2tbiqNlXpHYZqkqOQalydienEWOHHFyyuTSYRsLfxFJ2Q==}
+    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.1':
+    resolution: {integrity: sha512-YlUEHRHBGnCMh4Nj4GnqQyBtsshUPdiNroZj8VPkvTZSoHsilRCwXcVKnG9kyi0ZFAS/3u+qKHBdDc81SADTRA==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.2.1':
+    resolution: {integrity: sha512-rbO34G5sMWWyrN/idLeVxAZgAKWrn5LiR3/I90Q9MkA67s6T1oB0xtTe+0heoBvHSpbU9Mk7i6uwJnpo4u21XQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.2.1':
+    resolution: {integrity: sha512-yv9jeEFWnjKCI6/T3Oq50yQEOqmpmpfzG1hcZsAOaXFQPfzWprWrlHSdGPEF3WQTi8zu8ohC9Mh9J470nT5pUw==}
+    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.1':
+    resolution: {integrity: sha512-TBf2sJjYeb28jD2U/OhwdW0bbOsxkWPwQ7SrqGf9sVcoYwZj7rkXljroBO9wKBut9XnmQLXanuDUeqQK0lGg/w==}
+    peerDependencies:
+      vite: ^5.2.0 || ^6 || ^7
+
+  '@tanstack/history@1.161.4':
+    resolution: {integrity: sha512-Kp/WSt411ZWYvgXy6uiv5RmhHrz9cAml05AQPrtdAp7eUqvIDbMGPnML25OKbzR3RJ1q4wgENxDTvlGPa9+Mww==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/query-core@5.90.20':
+    resolution: {integrity: sha512-OMD2HLpNouXEfZJWcKeVKUgQ5n+n3A2JFmBaScpNDUqSrQSjiveC7dKMe53uJUg1nDG16ttFPz2xfilz6i2uVg==}
+
+  '@tanstack/react-query@5.90.21':
+    resolution: {integrity: sha512-0Lu6y5t+tvlTJMTO7oh5NSpJfpg/5D41LlThfepTixPYkJ0sE2Jj0m0f6yYqujBwIXlId87e234+MxG3D3g7kg==}
+    peerDependencies:
+      react: ^18 || ^19
+
+  '@tanstack/react-router-devtools@1.163.3':
+    resolution: {integrity: sha512-42VMkV/2Z8ro7xzblPBRNZIEmCNXMzm2jD68G52p2qhjXm38wGpg46qneAESN9FtTQeVWk5aSXs47/jt7lkzmw==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@tanstack/react-router': ^1.163.3
+      '@tanstack/router-core': ^1.163.3
+      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.163.3':
+    resolution: {integrity: sha512-hheBbFVb+PbxtrWp8iy6+TTRTbhx3Pn6hKo8Tv/sWlG89ZMcD1xpQWzx8ukHN9K8YWbh5rdzt4kv6u8X4kB28Q==}
+    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.1':
+    resolution: {integrity: sha512-YzJLnRvy5lIEFTLWBAZmcOjK3+2AepnBv/sr6NZmiqJvq7zTQggyK99Gw8fqYdMdHPQWXjz0epFKJXC+9V2xDA==}
+    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.163.3':
+    resolution: {integrity: sha512-jPptiGq/w3nuPzcMC7RNa79aU+b6OjaDzWJnBcV2UAwL4ThJamRS4h42TdhJE+oF5yH9IEnCOGQdfnbw45LbfA==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/router-devtools-core@1.163.3':
+    resolution: {integrity: sha512-FPi64IP0PT1IkoeyGmsD6JoOVOYAb85VCH0mUbSdD90yV0+1UB6oT+D7K27GXkp7SXMJN3mBEjU5rKnNnmSCIw==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@tanstack/router-core': ^1.163.3
+      csstype: ^3.0.10
+    peerDependenciesMeta:
+      csstype:
+        optional: true
+
+  '@tanstack/router-generator@1.164.0':
+    resolution: {integrity: sha512-Uiyj+RtW0kdeqEd8NEd3Np1Z2nhJ2xgLS8U+5mTvFrm/s3xkM2LYjJHoLzc6am7sKPDsmeF9a4/NYq3R7ZJP0Q==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/router-plugin@1.164.0':
+    resolution: {integrity: sha512-cZPsEMhqzyzmuPuDbsTAzBZaT+cj0pGjwdhjxJfPCM06Ax8v4tFR7n/Ug0UCwnNAUEmKZWN3lA9uT+TxXnk9PQ==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@rsbuild/core': '>=1.0.2'
+      '@tanstack/react-router': ^1.163.3
+      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.4':
+    resolution: {integrity: sha512-r8TpjyIZoqrXXaf2DDyjd44gjGBoyE+/oEaaH68yLI9ySPO1gUWmQENZ1MZnmBnpUGN24NOZxdjDLc8npK0SAw==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/store@0.9.1':
+    resolution: {integrity: sha512-+qcNkOy0N1qSGsP7omVCW0SDrXtaDcycPqBDE726yryiA5eTDFpjBReaYjghVJwNf1pcPMyzIwTGlYjCSQR0Fg==}
+
+  '@tanstack/virtual-file-routes@1.161.4':
+    resolution: {integrity: sha512-42WoRePf8v690qG8yGRe/YOh+oHni9vUaUUfoqlS91U2scd3a5rkLtVsc6b7z60w3RogH0I00vdrC5AaeiZ18w==}
+    engines: {node: '>=20.19'}
+
+  '@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.12':
+    resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}
+
+  '@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@24.11.0':
+    resolution: {integrity: sha512-fPxQqz4VTgPI/IQ+lj9r0h+fDR66bzoeMGHp8ASee+32OSGIkeASsoZuJixsQoVef1QJbeubcPBxKk22QVoWdw==}
+
+  '@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.56.1':
+    resolution: {integrity: sha512-Jz9ZztpB37dNC+HU2HI28Bs9QXpzCz+y/twHOwhyrIRdbuVDxSytJNDl6z/aAKlaRIwC7y8wJdkBv7FxYGgi0A==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      '@typescript-eslint/parser': ^8.56.1
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/parser@8.56.1':
+    resolution: {integrity: sha512-klQbnPAAiGYFyI02+znpBRLyjL4/BrBd0nyWkdC0s/6xFLkXYQ8OoRrSkqacS1ddVxf/LDyODIKbQ5TgKAf/Fg==}
+    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.56.1':
+    resolution: {integrity: sha512-TAdqQTzHNNvlVFfR+hu2PDJrURiwKsUvxFn1M0h95BB8ah5jejas08jUWG4dBA68jDMI988IvtfdAI53JzEHOQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/scope-manager@8.56.1':
+    resolution: {integrity: sha512-YAi4VDKcIZp0O4tz/haYKhmIDZFEUPOreKbfdAN3SzUDMcPhJ8QI99xQXqX+HoUVq8cs85eRKnD+rne2UAnj2w==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/tsconfig-utils@8.56.1':
+    resolution: {integrity: sha512-qOtCYzKEeyr3aR9f28mPJqBty7+DBqsdd63eO0yyDwc6vgThj2UjWfJIcsFeSucYydqcuudMOprZ+x1SpF3ZuQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/type-utils@8.56.1':
+    resolution: {integrity: sha512-yB/7dxi7MgTtGhZdaHCemf7PuwrHMenHjmzgUW1aJpO+bBU43OycnM3Wn+DdvDO/8zzA9HlhaJ0AUGuvri4oGg==}
+    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.56.1':
+    resolution: {integrity: sha512-dbMkdIUkIkchgGDIv7KLUpa0Mda4IYjo4IAMJUZ+3xNoUXxMsk9YtKpTHSChRS85o+H9ftm51gsK1dZReY9CVw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/typescript-estree@8.56.1':
+    resolution: {integrity: sha512-qzUL1qgalIvKWAf9C1HpvBjif+Vm6rcT5wZd4VoMb9+Km3iS3Cv9DY6dMRMDtPnwRAFyAi7YXJpTIEXLvdfPxg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/utils@8.56.1':
+    resolution: {integrity: sha512-HPAVNIME3tABJ61siYlHzSWCGtOoeP2RTIaHXFMPqjrQKCGB9OgUVdiNgH7TJS2JNIQ5qQ4RsAUDuGaGme/KOA==}
+    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.56.1':
+    resolution: {integrity: sha512-KiROIzYdEV85YygXw6BI/Dx4fnBlFQu6Mq4QE4MOH9fFnhohw6wX/OAvDY2/C+ut0I3RSPKenvZJIVYqJNkhEw==}
+    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.1.4':
+    resolution: {integrity: sha512-VIcFLdRi/VYRU8OL/puL7QXMYafHmqOnwTZY50U1JPlCNj30PxCMx65c494b1K9be9hX83KVt0+gTEwTWLqToA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.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'}
+
+  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.0:
+    resolution: {integrity: sha512-lIyg0szRfYbiy67j9KN8IyeD7q7hcmqnJ1ddWmNt19ItGpNN64mnllmxUNFIOdOm6by97jlL6wfpTTJrmnjWAA==}
+    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.30001775:
+    resolution: {integrity: sha512-s3Qv7Lht9zbVKE9XoTyRG6wVDCKdtOFIjBGg3+Yhn6JaytuNKPIjBMTMIY1AnOH3seL5mvF+x33oGAyK3hVt3A==}
+
+  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.0:
+    resolution: {integrity: sha512-itvL5h8RETACmOTFc4UfIyB2RfEHi71Ax6E/PivVxq9NseKbOWpeyHEOIbmAw1rs8Ak0VursQNww7lf7YtUwzg==}
+    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.19:
+    resolution: {integrity: sha512-t5EcLVS6QPBNqM2z8fakk/NKel+Xzshgt8FFKAn+qwlD1pzZWxh0nVCrvFK7ZDb6XucZeF9z8C7CBWTRIVApAw==}
+
+  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.17:
+    resolution: {integrity: sha512-TOOURki4G7sD1wDCjj7NfLaXZZ49dFOeEb5y39IXpb8p0hRzVvfvzZHOi5JcT+PpyAbi/Y+lxPb8eTag2WYH8w==}
+    engines: {bun: '>=1', deno: '>=2', node: '>=16'}
+
+  ee-first@1.1.1:
+    resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
+
+  electron-to-chromium@1.5.302:
+    resolution: {integrity: sha512-sM6HAN2LyK82IyPBpznDRqlTQAtuSaO+ShzFiWTvoMJLHyZ+Y39r8VMfHzwbU8MVBzQ4Wdn85+wlZl2TLGIlwg==}
+
+  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.0:
+    resolution: {integrity: sha512-/ce7+jQ1PQ6rVXwe+jKEg5hW5ciicHwIQUagZkp6IufBoY3YDgdTTY1azVs0qoRgVmvsNB+rbjLJxDAeHHtwsQ==}
+    engines: {node: '>=10.13.0'}
+
+  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.3:
+    resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+    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.3:
+    resolution: {integrity: sha512-VmQ+sifHUbI/IcSopBCF/HO3YiHQx/AVd3UVyYL6weuwW+HvON9VYn5l6Zl1WZzPWXPNZrSQpxwkkZ/VuvJZzg==}
+    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.2.1:
+    resolution: {integrity: sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==}
+    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.3.3:
+    resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==}
+
+  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.3:
+    resolution: {integrity: sha512-VWSRii4t0AFm6ixFFmLLx1t7wS1gh+ckoa84aOeapGum0h+EZd1EhEumSB+ZdDLnEPuucsVB9oB7cxJHap6Afg==}
+    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==}
+
+  fzf@0.5.2:
+    resolution: {integrity: sha512-Tt4kuxLXFKHy8KT40zwsUPUkg1CrsgY25FxA2U/j/0WgEDCk3ddc/zLTCCcbSHX9FcKtLuVaDGtGE/STWC+j3Q==}
+
+  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.0:
+    resolution: {integrity: sha512-uSisMYERbaB9bkA9M4/4dnqyktaEkf1kMHNKq/7DHyxVeWqHQ2mBmVqm5u6/FVHwF3iCNalKcg82Zfl+tffWoA==}
+    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-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
+  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.3:
+    resolution: {integrity: sha512-SFsVSjp8sj5UumXOOFlkZOG6XS9SJDKw0TbwFeV+AJ8xlST8kxK5Z/5EYa111UY8732lK2S/xB653ceuaoGwpg==}
+    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==}
+
+  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.14:
+    resolution: {integrity: sha512-paMUYkfWJMsWPeE/Hejcw+XLhHrQPehem+4wMo+uELnvIwvCG019L9sAIljwjCmEMtFQQO3YeitJY8Kctei3iA==}
+    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.0.1:
+    resolution: {integrity: sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==}
+    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.35:
+    resolution: {integrity: sha512-waFfC72ZNfwLLuJ2iLaoVaqcNo+CAaLR7xCpAn0Y5WfGzkNHv7ZN39Vbi1y+kb+Zs46XHOX3tZNExroFUPX+Kg==}
+    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.1.3:
+    resolution: {integrity: sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==}
+
+  jotai@2.18.0:
+    resolution: {integrity: sha512-XI38kGWAvtxAZ+cwHcTgJsd+kJOJGf3OfL4XYaXWZMZ7IIY8e53abpIHvtVn1eAgJ5dlgwlGFnP4psrZ/vZbtA==}
+    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.31.1:
+    resolution: {integrity: sha512-HXJF3x8w9nQ4jbXRiNppBCqeZPIAfUo8zE/kOEGbW5NZvGc/K7nMxbhIr+YlFlHW5mpbg/YFPdbnCh1wAXCKFg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.31.1:
+    resolution: {integrity: sha512-02uTEqf3vIfNMq3h/z2cJfcOXnQ0GRwQrkmPafhueLb2h7mqEidiCzkE4gBMEH65abHRiQvhdcQ+aP0D0g67sg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.31.1:
+    resolution: {integrity: sha512-1ObhyoCY+tGxtsz1lSx5NXCj3nirk0Y0kB/g8B8DT+sSx4G9djitg9ejFnjb3gJNWo7qXH4DIy2SUHvpoFwfTA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.31.1:
+    resolution: {integrity: sha512-1RINmQKAItO6ISxYgPwszQE1BrsVU5aB45ho6O42mu96UiZBxEXsuQ7cJW4zs4CEodPUioj/QrXW1r9pLUM74A==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.31.1:
+    resolution: {integrity: sha512-OOCm2//MZJ87CdDK62rZIu+aw9gBv4azMJuA8/KB74wmfS3lnC4yoPHm0uXZ/dvNNHmnZnB8XLAZzObeG0nS1g==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.31.1:
+    resolution: {integrity: sha512-WKyLWztD71rTnou4xAD5kQT+982wvca7E6QoLpoawZ1gP9JM0GJj4Tp5jMUh9B3AitHbRZ2/H3W5xQmdEOUlLg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-arm64-musl@1.31.1:
+    resolution: {integrity: sha512-mVZ7Pg2zIbe3XlNbZJdjs86YViQFoJSpc41CbVmKBPiGmC4YrfeOyz65ms2qpAobVd7WQsbW4PdsSJEMymyIMg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-linux-x64-gnu@1.31.1:
+    resolution: {integrity: sha512-xGlFWRMl+0KvUhgySdIaReQdB4FNudfUTARn7q0hh/V67PVGCs3ADFjw+6++kG1RNd0zdGRlEKa+T13/tQjPMA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-x64-musl@1.31.1:
+    resolution: {integrity: sha512-eowF8PrKHw9LpoZii5tdZwnBcYDxRw2rRCyvAXLi34iyeYfqCQNA9rmUM0ce62NlPhCvof1+9ivRaTY6pSKDaA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-win32-arm64-msvc@1.31.1:
+    resolution: {integrity: sha512-aJReEbSEQzx1uBlQizAOBSjcmr9dCdL3XuC/6HLXAxmtErsj2ICo5yYggg1qOODQMtnjNQv2UHb9NpOuFtYe4w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.31.1:
+    resolution: {integrity: sha512-I9aiFrbd7oYHwlnQDqr1Roz+fTz61oDDJX7n9tYF9FJymH1cIN1DtKw3iYt6b8WZgEjoNwVSncwF4wx/ZedMhw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.31.1:
+    resolution: {integrity: sha512-l51N2r93WmGUye3WuFoN5k10zyvrVs0qfKBhyC5ogUQ6Ew6JUSswh78mbSO+IU3nTWsyOArqPCcShdQSadghBQ==}
+    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.10:
+    resolution: {integrity: sha512-G3VUymSE0/iegFnuipujpwyTM2GuZAKXNeerUSrG2+Eg391wW63xFs5ixWsK9MWzr1AGoSkYGmyAzNgbR3+urw==}
+    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.27:
+    resolution: {integrity: sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA==}
+
+  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'}
+
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
+  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==}
+
+  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.6:
+    resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
+    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.4:
+    resolution: {integrity: sha512-6yj+dcfMncEC21QPhOTsW8mOSO+pzFmT6uvU7XXdvM/Cp38zJkmTeMeKmTrmCMD5ToT79FmiE/mRWiYWcJYW4g==}
+    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'}
+
+  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.0:
+    resolution: {integrity: sha512-EAHqADIQondwRZIdeW2I636zgsODzoBDwb3PT/+7TLDWyw1Dy/Xv7iGUIEXXav7usHDE9HVhOU61irI3EnyyHA==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      seroval: ^1.0
+
+  seroval@1.5.0:
+    resolution: {integrity: sha512-OE4cvmJ1uSPrKorFIH9/w/Qwuvi/IMcGbv5RKgcJ/zjA/IohDLU6SVaxFN9FwajbP7nsX0dQqMDes1whk3y+yw==}
+    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@3.8.5:
+    resolution: {integrity: sha512-jPRx44e+eyeV7xwY3BLJXcfrks00+M0h5BGB9l6DdcBW4BpAj4x3lVmVy0TXPEs2iHEisxejr62sZAAw6B1EVA==}
+    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'}
+
+  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.1:
+    resolution: {integrity: sha512-/tBrSQ36vCleJkAOsy9kbNTgaxvGbyOamC30PRePTQe/o1MFwEKHQk4Cn7BNGaPtjp+PuUrByJehM1hgxfq4sw==}
+
+  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==}
+
+  tinyexec@1.0.2:
+    resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==}
+    engines: {node: '>=18'}
+
+  tinyglobby@0.2.15:
+    resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
+    engines: {node: '>=12.0.0'}
+
+  tldts-core@7.0.23:
+    resolution: {integrity: sha512-0g9vrtDQLrNIiCj22HSe9d4mLVG3g5ph5DZ8zCKBr4OtrspmNB6ss7hVyzArAeE88ceZocIEGkyW1Ime7fxPtQ==}
+
+  tldts@7.0.23:
+    resolution: {integrity: sha512-ASdhgQIBSay0R/eXggAkQ53G4nTJqTXqC2kbaBbdDwM7SkjyZyO0OaaN1/FH7U/yCeqOHDwFO5j8+Os/IS1dXw==}
+    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.0:
+    resolution: {integrity: sha512-kXuRi1mtaKMrsLUxz3sQYvVl37B0Ns6MzfrtV5DvJceE9bPyspOqk9xxv7XbZWcfLWbFmm997vl83qUWVJA64w==}
+    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.4.0:
+    resolution: {integrity: sha512-3TaVTaAv2gTiMB35i3FiGJaRfwb3Pyn/j3m/bfAvGe8FB7CF6u+LMYqYlDh7reQf7UNvoTvdfAqHGmPGOSsPmA==}
+    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.4.4:
+    resolution: {integrity: sha512-JnTrzGu+zPV3aXIUhnyWJj4z/wigMsdYajGLIYakqyOW1nPllzXEJee0QQbHj+CTIQtXGlAjuK0UY+2xTyjVAw==}
+    engines: {node: '>=20'}
+
+  type-is@2.0.1:
+    resolution: {integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==}
+    engines: {node: '>= 0.6'}
+
+  typescript-eslint@8.56.1:
+    resolution: {integrity: sha512-U4lM6pjmBX7J5wk4szltF7I1cGBHXZopnAXCMXb3+fZ3B/0Z3hq3wS/CCUB2NZBNAExK92mCU2tEohWuwVMsDQ==}
+    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.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+
+  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-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-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@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:
+
+  '@antfu/ni@25.0.0':
+    dependencies:
+      ansis: 4.2.0
+      fzf: 0.5.2
+      package-manager-detector: 1.6.0
+      tinyexec: 1.0.2
+
+  '@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.28.6
+      '@babel/parser': 7.29.0
+      '@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.0
+      '@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.28.6':
+    dependencies:
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+
+  '@babel/parser@7.29.0':
+    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.28.6': {}
+
+  '@babel/template@7.28.6':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/parser': 7.29.0
+      '@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.0
+      '@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.52.0':
+    dependencies:
+      commander: 11.1.0
+      dotenv: 17.3.1
+      eciesjs: 0.4.17
+      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.3':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm@0.27.3':
+    optional: true
+
+  '@esbuild/android-x64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.3':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.3':
+    optional: true
+
+  '@eslint-community/eslint-utils@4.9.1(eslint@9.39.3(jiti@2.6.1))':
+    dependencies:
+      eslint: 9.39.3(jiti@2.6.1)
+      eslint-visitor-keys: 3.4.3
+
+  '@eslint-community/regexpp@4.12.2': {}
+
+  '@eslint/config-array@0.21.1':
+    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.4':
+    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.3': {}
+
+  '@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.4':
+    dependencies:
+      '@floating-ui/utils': 0.2.10
+
+  '@floating-ui/dom@1.7.5':
+    dependencies:
+      '@floating-ui/core': 1.7.4
+      '@floating-ui/utils': 0.2.10
+
+  '@floating-ui/react-dom@2.1.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@floating-ui/dom': 1.7.5
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+
+  '@floating-ui/utils@0.2.10': {}
+
+  '@fontsource-variable/inter@5.2.8': {}
+
+  '@hono/node-server@1.19.9(hono@4.12.3)':
+    dependencies:
+      hono: 4.12.3
+
+  '@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@24.11.0)':
+    dependencies:
+      '@inquirer/core': 10.3.2(@types/node@24.11.0)
+      '@inquirer/type': 3.0.10(@types/node@24.11.0)
+    optionalDependencies:
+      '@types/node': 24.11.0
+
+  '@inquirer/core@10.3.2(@types/node@24.11.0)':
+    dependencies:
+      '@inquirer/ansi': 1.0.2
+      '@inquirer/figures': 1.0.15
+      '@inquirer/type': 3.0.10(@types/node@24.11.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': 24.11.0
+
+  '@inquirer/figures@1.0.15': {}
+
+  '@inquirer/type@3.0.10(@types/node@24.11.0)':
+    optionalDependencies:
+      '@types/node': 24.11.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.9(hono@4.12.3)
+      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.2.1(express@5.2.1)
+      hono: 4.12.3
+      jose: 6.1.3
+      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.7(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.38.0(react@19.2.4)':
+    dependencies:
+      '@tabler/icons': 3.38.0
+      react: 19.2.4
+
+  '@tabler/icons@3.38.0': {}
+
+  '@tailwindcss/node@4.2.1':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.20.0
+      jiti: 2.6.1
+      lightningcss: 1.31.1
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.2.1
+
+  '@tailwindcss/oxide-android-arm64@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.2.1':
+    optional: true
+
+  '@tailwindcss/oxide@4.2.1':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.2.1
+      '@tailwindcss/oxide-darwin-arm64': 4.2.1
+      '@tailwindcss/oxide-darwin-x64': 4.2.1
+      '@tailwindcss/oxide-freebsd-x64': 4.2.1
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.2.1
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.2.1
+      '@tailwindcss/oxide-linux-arm64-musl': 4.2.1
+      '@tailwindcss/oxide-linux-x64-gnu': 4.2.1
+      '@tailwindcss/oxide-linux-x64-musl': 4.2.1
+      '@tailwindcss/oxide-wasm32-wasi': 4.2.1
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.2.1
+      '@tailwindcss/oxide-win32-x64-msvc': 4.2.1
+
+  '@tailwindcss/typography@0.5.19(tailwindcss@4.2.1)':
+    dependencies:
+      postcss-selector-parser: 6.0.10
+      tailwindcss: 4.2.1
+
+  '@tailwindcss/vite@4.2.1(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))':
+    dependencies:
+      '@tailwindcss/node': 4.2.1
+      '@tailwindcss/oxide': 4.2.1
+      tailwindcss: 4.2.1
+      vite: 7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0)
+
+  '@tanstack/history@1.161.4': {}
+
+  '@tanstack/query-core@5.90.20': {}
+
+  '@tanstack/react-query@5.90.21(react@19.2.4)':
+    dependencies:
+      '@tanstack/query-core': 5.90.20
+      react: 19.2.4
+
+  '@tanstack/react-router-devtools@1.163.3(@tanstack/react-router@1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.163.3)(csstype@3.2.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@tanstack/react-router': 1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@tanstack/router-devtools-core': 1.163.3(@tanstack/router-core@1.163.3)(csstype@3.2.3)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@tanstack/router-core': 1.163.3
+    transitivePeerDependencies:
+      - csstype
+
+  '@tanstack/react-router@1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@tanstack/history': 1.161.4
+      '@tanstack/react-store': 0.9.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@tanstack/router-core': 1.163.3
+      isbot: 5.1.35
+      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.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@tanstack/store': 0.9.1
+      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.163.3':
+    dependencies:
+      '@tanstack/history': 1.161.4
+      '@tanstack/store': 0.9.1
+      cookie-es: 2.0.0
+      seroval: 1.5.0
+      seroval-plugins: 1.5.0(seroval@1.5.0)
+      tiny-invariant: 1.3.3
+      tiny-warning: 1.0.3
+
+  '@tanstack/router-devtools-core@1.163.3(@tanstack/router-core@1.163.3)(csstype@3.2.3)':
+    dependencies:
+      '@tanstack/router-core': 1.163.3
+      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.164.0':
+    dependencies:
+      '@tanstack/router-core': 1.163.3
+      '@tanstack/router-utils': 1.161.4
+      '@tanstack/virtual-file-routes': 1.161.4
+      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.164.0(@tanstack/react-router@1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(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.163.3
+      '@tanstack/router-generator': 1.164.0
+      '@tanstack/router-utils': 1.161.4
+      '@tanstack/virtual-file-routes': 1.161.4
+      chokidar: 3.6.0
+      unplugin: 2.3.11
+      zod: 3.25.76
+    optionalDependencies:
+      '@tanstack/react-router': 1.163.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      vite: 7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@tanstack/router-utils@1.161.4':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/parser': 7.29.0
+      '@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.1': {}
+
+  '@tanstack/virtual-file-routes@1.161.4': {}
+
+  '@trivago/prettier-plugin-sort-imports@6.0.2(prettier@3.8.1)':
+    dependencies:
+      '@babel/generator': 7.29.1
+      '@babel/parser': 7.29.0
+      '@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.0
+      '@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.0
+      '@babel/types': 7.29.0
+
+  '@types/babel__traverse@7.28.0':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@types/debug@4.1.12':
+    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@24.11.0':
+    dependencies:
+      undici-types: 7.16.0
+
+  '@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.56.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/regexpp': 4.12.2
+      '@typescript-eslint/parser': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/scope-manager': 8.56.1
+      '@typescript-eslint/type-utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.56.1
+      eslint: 9.39.3(jiti@2.6.1)
+      ignore: 7.0.5
+      natural-compare: 1.4.0
+      ts-api-utils: 2.4.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/scope-manager': 8.56.1
+      '@typescript-eslint/types': 8.56.1
+      '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.56.1
+      debug: 4.4.3
+      eslint: 9.39.3(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/project-service@8.56.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/tsconfig-utils': 8.56.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.56.1
+      debug: 4.4.3
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/scope-manager@8.56.1':
+    dependencies:
+      '@typescript-eslint/types': 8.56.1
+      '@typescript-eslint/visitor-keys': 8.56.1
+
+  '@typescript-eslint/tsconfig-utils@8.56.1(typescript@5.9.3)':
+    dependencies:
+      typescript: 5.9.3
+
+  '@typescript-eslint/type-utils@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/types': 8.56.1
+      '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      debug: 4.4.3
+      eslint: 9.39.3(jiti@2.6.1)
+      ts-api-utils: 2.4.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/types@8.56.1': {}
+
+  '@typescript-eslint/typescript-estree@8.56.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/project-service': 8.56.1(typescript@5.9.3)
+      '@typescript-eslint/tsconfig-utils': 8.56.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.56.1
+      '@typescript-eslint/visitor-keys': 8.56.1
+      debug: 4.4.3
+      minimatch: 10.2.4
+      semver: 7.7.4
+      tinyglobby: 0.2.15
+      ts-api-utils: 2.4.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/utils@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.3(jiti@2.6.1))
+      '@typescript-eslint/scope-manager': 8.56.1
+      '@typescript-eslint/types': 8.56.1
+      '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
+      eslint: 9.39.3(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/visitor-keys@8.56.1':
+    dependencies:
+      '@typescript-eslint/types': 8.56.1
+      eslint-visitor-keys: 5.0.1
+
+  '@ungap/structured-clone@1.3.0': {}
+
+  '@vitejs/plugin-react@5.1.4(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(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@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(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
+
+  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.0
+      '@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.0: {}
+
+  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.0
+      caniuse-lite: 1.0.30001775
+      electron-to-chromium: 1.5.302
+      node-releases: 2.0.27
+      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.30001775: {}
+
+  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.0(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.19: {}
+
+  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.17:
+    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.302: {}
+
+  emoji-regex@10.6.0: {}
+
+  emoji-regex@8.0.0: {}
+
+  encodeurl@2.0.0: {}
+
+  enhanced-resolve@5.20.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.0
+
+  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.3:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.3
+      '@esbuild/android-arm': 0.27.3
+      '@esbuild/android-arm64': 0.27.3
+      '@esbuild/android-x64': 0.27.3
+      '@esbuild/darwin-arm64': 0.27.3
+      '@esbuild/darwin-x64': 0.27.3
+      '@esbuild/freebsd-arm64': 0.27.3
+      '@esbuild/freebsd-x64': 0.27.3
+      '@esbuild/linux-arm': 0.27.3
+      '@esbuild/linux-arm64': 0.27.3
+      '@esbuild/linux-ia32': 0.27.3
+      '@esbuild/linux-loong64': 0.27.3
+      '@esbuild/linux-mips64el': 0.27.3
+      '@esbuild/linux-ppc64': 0.27.3
+      '@esbuild/linux-riscv64': 0.27.3
+      '@esbuild/linux-s390x': 0.27.3
+      '@esbuild/linux-x64': 0.27.3
+      '@esbuild/netbsd-arm64': 0.27.3
+      '@esbuild/netbsd-x64': 0.27.3
+      '@esbuild/openbsd-arm64': 0.27.3
+      '@esbuild/openbsd-x64': 0.27.3
+      '@esbuild/openharmony-arm64': 0.27.3
+      '@esbuild/sunos-x64': 0.27.3
+      '@esbuild/win32-arm64': 0.27.3
+      '@esbuild/win32-ia32': 0.27.3
+      '@esbuild/win32-x64': 0.27.3
+
+  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.3(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.3(jiti@2.6.1)
+
+  eslint-plugin-react-hooks@7.0.1(eslint@9.39.3(jiti@2.6.1)):
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/parser': 7.29.0
+      eslint: 9.39.3(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.3(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.3(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.3(jiti@2.6.1):
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.3(jiti@2.6.1))
+      '@eslint-community/regexpp': 4.12.2
+      '@eslint/config-array': 0.21.1
+      '@eslint/config-helpers': 0.4.2
+      '@eslint/core': 0.17.0
+      '@eslint/eslintrc': 3.3.4
+      '@eslint/js': 9.39.3
+      '@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.2.1(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.0.1
+
+  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.3.3
+      keyv: 4.5.4
+
+  flatted@3.3.3: {}
+
+  formdata-polyfill@4.0.10:
+    dependencies:
+      fetch-blob: 3.2.0
+
+  forwarded@0.2.0: {}
+
+  fresh@2.0.0: {}
+
+  fs-extra@11.3.3:
+    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: {}
+
+  fzf@0.5.2: {}
+
+  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.0: {}
+
+  has-flag@4.0.0: {}
+
+  has-symbols@1.1.0: {}
+
+  hasown@2.0.2:
+    dependencies:
+      function-bind: 1.1.2
+
+  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-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  headers-polyfill@4.0.3: {}
+
+  hermes-estree@0.25.1: {}
+
+  hermes-parser@0.25.1:
+    dependencies:
+      hermes-estree: 0.25.1
+
+  hono@4.12.3: {}
+
+  html-parse-stringify@3.0.1:
+    dependencies:
+      void-elements: 3.1.0
+
+  html-url-attributes@3.0.1: {}
+
+  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.28.6
+
+  i18next@25.8.14(typescript@5.9.3):
+    dependencies:
+      '@babel/runtime': 7.28.6
+    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.0.1: {}
+
+  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.35: {}
+
+  isexe@2.0.0: {}
+
+  isexe@3.1.5: {}
+
+  javascript-natural-sort@0.7.1: {}
+
+  jiti@2.6.1: {}
+
+  jose@6.1.3: {}
+
+  jotai@2.18.0(@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.31.1:
+    optional: true
+
+  lightningcss-darwin-arm64@1.31.1:
+    optional: true
+
+  lightningcss-darwin-x64@1.31.1:
+    optional: true
+
+  lightningcss-freebsd-x64@1.31.1:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.31.1:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.31.1:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.31.1:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.31.1:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.31.1:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.31.1:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.31.1:
+    optional: true
+
+  lightningcss@1.31.1:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.31.1
+      lightningcss-darwin-arm64: 1.31.1
+      lightningcss-darwin-x64: 1.31.1
+      lightningcss-freebsd-x64: 1.31.1
+      lightningcss-linux-arm-gnueabihf: 1.31.1
+      lightningcss-linux-arm64-gnu: 1.31.1
+      lightningcss-linux-arm64-musl: 1.31.1
+      lightningcss-linux-x64-gnu: 1.31.1
+      lightningcss-linux-x64-musl: 1.31.1
+      lightningcss-win32-arm64-msvc: 1.31.1
+      lightningcss-win32-x64-msvc: 1.31.1
+
+  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.12
+      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.10(@types/node@24.11.0)(typescript@5.9.3):
+    dependencies:
+      '@inquirer/confirm': 5.1.21(@types/node@24.11.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.0
+      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.0
+      type-fest: 5.4.4
+      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.27: {}
+
+  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
+
+  package-manager-detector@1.6.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: {}
+
+  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.6:
+    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.4(i18next@25.8.14(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.28.6
+      html-parse-stringify: 3.0.1
+      i18next: 25.8.14(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.28.6
+      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
+
+  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.0(seroval@1.5.0):
+    dependencies:
+      seroval: 1.5.0
+
+  seroval@1.5.0: {}
+
+  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@3.8.5(@types/node@24.11.0)(typescript@5.9.3):
+    dependencies:
+      '@antfu/ni': 25.0.0
+      '@babel/core': 7.29.0
+      '@babel/parser': 7.29.0
+      '@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.52.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.0(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.3
+      fuzzysort: 3.1.0
+      https-proxy-agent: 7.0.6
+      kleur: 4.1.5
+      msw: 2.12.10(@types/node@24.11.0)(typescript@5.9.3)
+      node-fetch: 3.3.2
+      open: 11.0.0
+      ora: 8.2.0
+      postcss: 8.5.6
+      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
+
+  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.1: {}
+
+  tapable@2.3.0: {}
+
+  tiny-invariant@1.3.3: {}
+
+  tiny-warning@1.0.3: {}
+
+  tinyexec@1.0.2: {}
+
+  tinyglobby@0.2.15:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.3)
+      picomatch: 4.0.3
+
+  tldts-core@7.0.23: {}
+
+  tldts@7.0.23:
+    dependencies:
+      tldts-core: 7.0.23
+
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
+  toidentifier@1.0.1: {}
+
+  tough-cookie@6.0.0:
+    dependencies:
+      tldts: 7.0.23
+
+  trim-lines@3.0.1: {}
+
+  trough@2.2.0: {}
+
+  ts-api-utils@2.4.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.3
+      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.4.4:
+    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.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3):
+    dependencies:
+      '@typescript-eslint/eslint-plugin': 8.56.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/parser': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+      eslint: 9.39.3(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  typescript@5.9.3: {}
+
+  undici-types@7.16.0: {}
+
+  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-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@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0):
+    dependencies:
+      esbuild: 0.27.3
+      fdir: 6.5.0(picomatch@4.0.3)
+      picomatch: 4.0.3
+      postcss: 8.5.6
+      rollup: 4.59.0
+      tinyglobby: 0.2.15
+    optionalDependencies:
+      '@types/node': 24.11.0
+      fsevents: 2.3.3
+      jiti: 2.6.1
+      lightningcss: 1.31.1
+      tsx: 4.21.0
+
+  void-elements@3.1.0: {}
+
+  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@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/src/api/channels.ts b/web/frontend/src/api/channels.ts
new file mode 100644
index 000000000..ecd77632c
--- /dev/null
+++ b/web/frontend/src/api/channels.ts
@@ -0,0 +1,65 @@
+// 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),
+  })
+}
+
+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..5a58d48f0
--- /dev/null
+++ b/web/frontend/src/api/gateway.ts
@@ -0,0 +1,62 @@
+// API client for gateway process management.
+
+interface GatewayStatusResponse {
+  gateway_status: "running" | "starting" | "stopped" | "error"
+  gateway_start_allowed?: boolean
+  gateway_start_reason?: string
+  pid?: number
+  logs?: string[]
+  log_total?: number
+  log_run_id?: number
+  [key: string]: unknown
+}
+
+interface GatewayActionResponse {
+  status: string
+  pid?: 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(options?: {
+  log_offset?: number
+  log_run_id?: number
+}): Promise<GatewayStatusResponse> {
+  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<GatewayStatusResponse>(`/api/gateway/status${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 type { GatewayStatusResponse, GatewayActionResponse }
diff --git a/web/frontend/src/api/models.ts b/web/frontend/src/api/models.ts
new file mode 100644
index 000000000..6a4544c65
--- /dev/null
+++ b/web/frontend/src/api/models.ts
@@ -0,0 +1,91 @@
+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
+  // Meta
+  configured: boolean
+  is_default: 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 }),
+  })
+
+  void 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..56ef148db
--- /dev/null
+++ b/web/frontend/src/api/sessions.ts
@@ -0,0 +1,50 @@
+// Sessions API — list and retrieve chat session history
+
+export interface SessionSummary {
+  id: 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/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/components/app-header.tsx b/web/frontend/src/components/app-header.tsx
new file mode 100644
index 000000000..7a50fe0fb
--- /dev/null
+++ b/web/frontend/src/components/app-header.tsx
@@ -0,0 +1,193 @@
+import {
+  IconBook,
+  IconLanguage,
+  IconLoader2,
+  IconMenu2,
+  IconMoon,
+  IconPlayerPlay,
+  IconPower,
+  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 { 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,
+    start,
+    stop,
+  } = useGateway()
+
+  const isRunning = gwState === "running"
+  const isStarting = gwState === "starting"
+  const isStopped = gwState === "stopped" || gwState === "unknown"
+  const showNotConnectedHint =
+    canStart && (gwState === "stopped" || gwState === "error")
+
+  const [showStopDialog, setShowStopDialog] = React.useState(false)
+
+  const handleGatewayToggle = () => {
+    if (gwLoading || (!isRunning && !canStart)) return
+    if (isRunning) {
+      setShowStopDialog(true)
+    } else {
+      start()
+    }
+  }
+
+  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">
+        {/* Gateway Start/Stop */}
+        <Button
+          variant={isStarting ? "secondary" : "default"}
+          size="sm"
+          className={`h-8 gap-2 px-3 ${
+            isRunning
+              ? "bg-destructive/10 text-destructive hover:bg-destructive/20"
+              : isStopped
+                ? "bg-green-500 text-white hover:bg-green-600"
+                : ""
+          }`}
+          onClick={handleGatewayToggle}
+          disabled={gwLoading || isStarting || (!isRunning && !canStart)}
+        >
+          {gwLoading || isStarting ? (
+            <IconLoader2 className="h-4 w-4 animate-spin opacity-70" />
+          ) : isRunning ? (
+            <IconPower className="h-4 w-4 opacity-80" />
+          ) : (
+            <IconPlayerPlay className="h-4 w-4 opacity-80" />
+          )}
+          <span className="text-xs font-semibold">
+            {isRunning
+              ? t("header.gateway.action.stop")
+              : 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..dc24f8781
--- /dev/null
+++ b/web/frontend/src/components/app-sidebar.tsx
@@ -0,0 +1,215 @@
+import { IconChevronRight } from "@tabler/icons-react"
+import {
+  IconAtom,
+  IconChevronsDown,
+  IconChevronsUp,
+  IconKey,
+  IconListDetails,
+  IconMessageCircle,
+  IconSettings,
+} 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.services",
+    defaultOpen: true,
+  },
+]
+
+export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
+  const routerState = useRouterState()
+  const { t } = useTranslation()
+  const currentPath = routerState.location.pathname
+  const {
+    channelItems,
+    hasMoreChannels,
+    showAllChannels,
+    toggleShowAllChannels,
+  } = useSidebarChannels({ 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.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..b19d11e6a
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-config-page.tsx
@@ -0,0 +1,539 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useAtomValue } from "jotai"
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+import { toast } from "sonner"
+
+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 { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+import { Switch } from "@/components/ui/switch"
+import { gatewayAtom } 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 "wecom":
+      return asString(config.token) !== ""
+    case "wecom_app":
+      return (
+        asString(config.corp_id) !== "" && asString(config.corp_secret) !== ""
+      )
+    case "wecom_aibot":
+      return asString(config.token) !== ""
+    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 ["token"]
+    case "wecom_app":
+      return ["corp_id", "corp_secret"]
+    case "wecom_aibot":
+      return ["token"]
+    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 gateway = useAtomValue(gatewayAtom)
+
+  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 () => {
+    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 {
+      setLoading(false)
+    }
+  }, [channelName, t])
+
+  useEffect(() => {
+    loadData()
+  }, [loadData])
+
+  const previousGatewayStatusRef = useRef(gateway.status)
+  useEffect(() => {
+    const previousStatus = previousGatewayStatusRef.current
+    if (previousStatus !== "running" && gateway.status === "running") {
+      void loadData()
+    }
+    previousGatewayStatusRef.current = gateway.status
+  }, [gateway.status, 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,
+        },
+      })
+      toast.success(t("channels.page.saveSuccess"))
+      await loadData()
+    } catch (e) {
+      const message =
+        e instanceof Error ? e.message : t("channels.page.saveError")
+      setServerError(message)
+      toast.error(message)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  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}
+          />
+        )
+      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..a834a65f9
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/feishu-form.tsx
@@ -0,0 +1,121 @@
+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 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 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>
+      <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..fc5a0a7fd
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/generic-form.tsx
@@ -0,0 +1,377 @@
+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",
+  "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",
+])
+
+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"),
+      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"),
+    }
+    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/chat/assistant-message.tsx b/web/frontend/src/components/chat/assistant-message.tsx
new file mode 100644
index 000000000..150f2f87d
--- /dev/null
+++ b/web/frontend/src/components/chat/assistant-message.tsx
@@ -0,0 +1,62 @@
+import { IconCheck, IconCopy } from "@tabler/icons-react"
+import { useState } from "react"
+import ReactMarkdown from "react-markdown"
+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]}>{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..e8bae89b8
--- /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(
+            "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() || !isConnected}
+          >
+            <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..624ff9c59
--- /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="secondary" 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..0fd23a6a5
--- /dev/null
+++ b/web/frontend/src/components/chat/chat-page.tsx
@@ -0,0 +1,150 @@
+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 [input, setInput] = useState("")
+
+  const {
+    messages,
+    isTyping,
+    activeSessionId,
+    sendMessage,
+    switchSession,
+    newChat,
+  } = usePicoChat()
+
+  const { state: gwState } = useGateway()
+  const isConnected = gwState === "running"
+
+  const {
+    defaultModelName,
+    hasConfiguredModels,
+    apiKeyModels,
+    oauthModels,
+    localModels,
+    handleSetDefault,
+  } = useChatModels({ isConnected })
+
+  const { sessions, hasMore, observerRef, loadSessions, handleDeleteSession } =
+    useSessionHistory({
+      activeSessionId,
+      onDeletedActiveSession: newChat,
+    })
+
+  const handleScroll = (e: React.UIEvent<HTMLDivElement>) => {
+    const { scrollTop, scrollHeight, clientHeight } = e.currentTarget
+    setIsAtBottom(scrollHeight - scrollTop <= clientHeight + 10)
+  }
+
+  useEffect(() => {
+    if (isAtBottom && scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight
+    }
+  }, [messages, isTyping, isAtBottom])
+
+  const handleSend = () => {
+    if (!input.trim() || !isConnected) return
+    sendMessage(input.trim())
+    setInput("")
+  }
+
+  return (
+    <div className="bg-background/95 flex h-full flex-col">
+      <PageHeader
+        title={t("navigation.chat")}
+        titleExtra={
+          hasConfiguredModels && (
+            <ModelSelector
+              defaultModelName={defaultModelName}
+              apiKeyModels={apiKeyModels}
+              oauthModels={oauthModels}
+              localModels={localModels}
+              onValueChange={handleSetDefault}
+            />
+          )
+        }
+      >
+        <Button
+          variant="outline"
+          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}
+          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={isConnected}
+            />
+          )}
+
+          {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={isConnected}
+        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..30afc5d04
--- /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>
+        {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..f2e93295c
--- /dev/null
+++ b/web/frontend/src/components/chat/session-history-menu.tsx
@@ -0,0 +1,98 @@
+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
+  observerRef: RefObject<HTMLDivElement | null>
+  onOpenChange: (open: boolean) => void
+  onSwitchSession: (sessionId: string) => void
+  onDeleteSession: (sessionId: string) => void
+}
+
+export function SessionHistoryMenu({
+  sessions,
+  activeSessionId,
+  hasMore,
+  observerRef,
+  onOpenChange,
+  onSwitchSession,
+  onDeleteSession,
+}: SessionHistoryMenuProps) {
+  const { t } = useTranslation()
+
+  return (
+    <DropdownMenu onOpenChange={onOpenChange}>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline" 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]">
+          {sessions.length === 0 ? (
+            <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.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..b47806f49
--- /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 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..c2d502079
--- /dev/null
+++ b/web/frontend/src/components/config/config-page.tsx
@@ -0,0 +1,337 @@
+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 {
+  AdvancedSection,
+  AgentDefaultsSection,
+  DevicesSection,
+  LauncherSection,
+  RuntimeSection,
+} from "@/components/config/config-sections"
+import {
+  type CoreConfigForm,
+  EMPTY_FORM,
+  EMPTY_LAUNCHER_FORM,
+  type LauncherForm,
+  buildFormFromConfig,
+  parseCIDRText,
+  parseIntField,
+} from "@/components/config/form-model"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+import { Separator } from "@/components/ui/separator"
+
+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,
+    error: launcherError,
+  } = 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 launcherHint = launcherError
+    ? t("pages.config.launcher_load_error")
+    : t("pages.config.launcher_restart_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 maxToolIterations = parseIntField(
+          form.maxToolIterations,
+          "Max tool iterations",
+          { min: 1 },
+        )
+        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 },
+        )
+
+        await patchAppConfig({
+          agents: {
+            defaults: {
+              workspace,
+              restrict_to_workspace: form.restrictToWorkspace,
+              max_tokens: maxTokens,
+              max_tool_iterations: maxToolIterations,
+              summarize_message_threshold: summarizeMessageThreshold,
+              summarize_token_percent: summarizeTokenPercent,
+            },
+          },
+          session: {
+            dm_scope: dmScope,
+          },
+          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} />
+
+              <Separator />
+
+              <RuntimeSection form={form} onFieldChange={updateField} />
+
+              <Separator />
+
+              <LauncherSection
+                launcherForm={launcherForm}
+                onFieldChange={updateLauncherField}
+                launcherHint={launcherHint}
+                disabled={saving || isLauncherLoading}
+              />
+
+              <Separator />
+
+              <DevicesSection
+                form={form}
+                onFieldChange={updateField}
+                autoStartEnabled={autoStartEnabled}
+                autoStartHint={autoStartHint}
+                autoStartDisabled={
+                  isAutoStartLoading ||
+                  Boolean(autoStartError) ||
+                  !autoStartSupported ||
+                  saving
+                }
+                onAutoStartChange={setAutoStartEnabled}
+              />
+
+              <Separator />
+
+              <AdvancedSection />
+
+              <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..340ece333
--- /dev/null
+++ b/web/frontend/src/components/config/config-sections.tsx
@@ -0,0 +1,326 @@
+import { IconCode } from "@tabler/icons-react"
+import { Link } from "@tanstack/react-router"
+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 { Button } from "@/components/ui/button"
+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 AgentDefaultsSectionProps {
+  form: CoreConfigForm
+  onFieldChange: UpdateCoreField
+}
+
+export function AgentDefaultsSection({
+  form,
+  onFieldChange,
+}: AgentDefaultsSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <section className="space-y-3">
+      <div className="space-y-4">
+        <Field
+          label={t("pages.config.workspace")}
+          hint={t("pages.config.workspace_hint")}
+        >
+          <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")}
+          checked={form.restrictToWorkspace}
+          onCheckedChange={(checked) =>
+            onFieldChange("restrictToWorkspace", checked)
+          }
+        />
+
+        <Field
+          label={t("pages.config.max_tokens")}
+          hint={t("pages.config.max_tokens_hint")}
+        >
+          <Input
+            type="number"
+            min={1}
+            value={form.maxTokens}
+            onChange={(e) => onFieldChange("maxTokens", e.target.value)}
+          />
+        </Field>
+
+        <Field
+          label={t("pages.config.max_tool_iterations")}
+          hint={t("pages.config.max_tool_iterations_hint")}
+        >
+          <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")}
+        >
+          <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")}
+        >
+          <Input
+            type="number"
+            min={1}
+            max={100}
+            value={form.summarizeTokenPercent}
+            onChange={(e) =>
+              onFieldChange("summarizeTokenPercent", e.target.value)
+            }
+          />
+        </Field>
+      </div>
+    </section>
+  )
+}
+
+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 (
+    <section className="space-y-3">
+      <div className="space-y-4">
+        <Field
+          label={t("pages.config.session_scope")}
+          hint={t("pages.config.session_scope_hint")}
+        >
+          <Select
+            value={form.dmScope}
+            onValueChange={(value) => onFieldChange("dmScope", value)}
+          >
+            <SelectTrigger>
+              <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")}
+          checked={form.heartbeatEnabled}
+          onCheckedChange={(checked) =>
+            onFieldChange("heartbeatEnabled", checked)
+          }
+        />
+
+        {form.heartbeatEnabled && (
+          <Field
+            label={t("pages.config.heartbeat_interval")}
+            hint={t("pages.config.heartbeat_interval_hint")}
+          >
+            <Input
+              type="number"
+              min={1}
+              value={form.heartbeatInterval}
+              onChange={(e) =>
+                onFieldChange("heartbeatInterval", e.target.value)
+              }
+            />
+          </Field>
+        )}
+      </div>
+    </section>
+  )
+}
+
+interface LauncherSectionProps {
+  launcherForm: LauncherForm
+  onFieldChange: UpdateLauncherField
+  launcherHint: string
+  disabled: boolean
+}
+
+export function LauncherSection({
+  launcherForm,
+  onFieldChange,
+  launcherHint,
+  disabled,
+}: LauncherSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <section className="space-y-3">
+      <div className="space-y-4">
+        <Field
+          label={t("pages.config.server_port")}
+          hint={t("pages.config.server_port_hint")}
+        >
+          <Input
+            type="number"
+            min={1}
+            max={65535}
+            value={launcherForm.port}
+            disabled={disabled}
+            onChange={(e) => onFieldChange("port", e.target.value)}
+          />
+        </Field>
+
+        <SwitchCardField
+          label={t("pages.config.lan_access")}
+          hint={t("pages.config.lan_access_hint")}
+          checked={launcherForm.publicAccess}
+          disabled={disabled}
+          onCheckedChange={(checked) => onFieldChange("publicAccess", checked)}
+        />
+
+        <Field
+          label={t("pages.config.allowed_cidrs")}
+          hint={t("pages.config.allowed_cidrs_hint")}
+        >
+          <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>
+
+        <p className="text-muted-foreground text-xs">{launcherHint}</p>
+      </div>
+    </section>
+  )
+}
+
+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 (
+    <section className="space-y-3">
+      <div className="space-y-4">
+        <SwitchCardField
+          label={t("pages.config.devices_enabled")}
+          hint={t("pages.config.devices_enabled_hint")}
+          checked={form.devicesEnabled}
+          onCheckedChange={(checked) =>
+            onFieldChange("devicesEnabled", checked)
+          }
+        />
+
+        <SwitchCardField
+          label={t("pages.config.monitor_usb")}
+          hint={t("pages.config.monitor_usb_hint")}
+          checked={form.monitorUSB}
+          onCheckedChange={(checked) => onFieldChange("monitorUSB", checked)}
+        />
+
+        <SwitchCardField
+          label={t("pages.config.autostart_label")}
+          hint={autoStartHint}
+          checked={autoStartEnabled}
+          disabled={autoStartDisabled}
+          onCheckedChange={onAutoStartChange}
+        />
+      </div>
+    </section>
+  )
+}
+
+export function AdvancedSection() {
+  const { t } = useTranslation()
+
+  return (
+    <section className="space-y-3">
+      <p className="text-muted-foreground text-sm">
+        {t("pages.config.advanced_desc")}
+      </p>
+      <div>
+        <Button variant="outline" asChild>
+          <Link to="/config/raw">
+            <IconCode className="size-4" />
+            {t("pages.config.open_raw")}
+          </Link>
+        </Button>
+      </div>
+    </section>
+  )
+}
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..0768d3e7f
--- /dev/null
+++ b/web/frontend/src/components/config/form-model.ts
@@ -0,0 +1,172 @@
+export type JsonRecord = Record<string, unknown>
+
+export interface CoreConfigForm {
+  workspace: string
+  restrictToWorkspace: boolean
+  maxTokens: 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,
+  maxTokens: "32768",
+  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)
+
+  return {
+    workspace: asString(defaults.workspace) || EMPTY_FORM.workspace,
+    restrictToWorkspace:
+      defaults.restrict_to_workspace === undefined
+        ? EMPTY_FORM.restrictToWorkspace
+        : asBool(defaults.restrict_to_workspace),
+    maxTokens: asNumberString(defaults.max_tokens, EMPTY_FORM.maxTokens),
+    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)
+}
diff --git a/web/frontend/src/components/config/raw-json-panel.tsx b/web/frontend/src/components/config/raw-json-panel.tsx
new file mode 100644
index 000000000..f67bd89f5
--- /dev/null
+++ b/web/frontend/src/components/config/raw-json-panel.tsx
@@ -0,0 +1,204 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+import { useState } from "react"
+import { useTranslation } from "react-i18next"
+import { toast } from "sonner"
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@/components/ui/alert-dialog"
+import { Button } from "@/components/ui/button"
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { ScrollArea } from "@/components/ui/scroll-area"
+import { Textarea } from "@/components/ui/textarea"
+
+export function RawJsonPanel() {
+  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 (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t("pages.config.raw_json_title")}</CardTitle>
+        <CardDescription>{t("pages.config.raw_json_desc")}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        {isLoading ? (
+          <div className="flex h-64 items-center justify-center">
+            <p>{t("labels.loading")}</p>
+          </div>
+        ) : (
+          <div className="space-y-3">
+            {isDirty && (
+              <div className="rounded-lg border border-yellow-200 bg-yellow-50 p-2 text-sm text-yellow-700">
+                {t("pages.config.unsaved_changes")}
+              </div>
+            )}
+            <div className="bg-muted/30 relative rounded-lg border">
+              <ScrollArea className="h-[calc(100vh-20rem)] min-h-[200px]">
+                <Textarea
+                  value={effectiveEditorValue}
+                  onChange={(e) => {
+                    setEditorValue(e.target.value)
+                    setIsDirty(true)
+                  }}
+                  className="min-h-[200px] resize-none border-0 bg-transparent px-4 py-3 font-mono text-sm shadow-none focus-visible:ring-0"
+                  placeholder={t("pages.config.json_placeholder")}
+                />
+              </ScrollArea>
+            </div>
+            <div className="flex justify-end space-x-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>
+        )}
+      </CardContent>
+    </Card>
+  )
+}
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/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..4c77944a9
--- /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) {
+        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..316e05e4d
--- /dev/null
+++ b/web/frontend/src/components/models/model-card.tsx
@@ -0,0 +1,137 @@
+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
+
+  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>
+          )}
+        </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..b8e80e709
--- /dev/null
+++ b/web/frontend/src/components/models/models-page.tsx
@@ -0,0 +1,213 @@
+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) => {
+    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..9d4aa6975
--- /dev/null
+++ b/web/frontend/src/components/page-header.tsx
@@ -0,0 +1,27 @@
+import { IconMenu2 } from "@tabler/icons-react"
+import type { ReactNode } from "react"
+
+import { SidebarTrigger } from "@/components/ui/sidebar"
+
+interface PageHeaderProps {
+  title: string
+  titleExtra?: ReactNode
+  children?: ReactNode
+}
+
+export function PageHeader({ title, titleExtra, children }: PageHeaderProps) {
+  return (
+    <div className="flex h-14 shrink-0 items-center justify-between px-6 pt-2">
+      <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..c6167d78e
--- /dev/null
+++ b/web/frontend/src/components/secret-placeholder.ts
@@ -0,0 +1,16 @@
+export function maskedSecretPlaceholder(value: unknown, fallback = ""): string {
+  const secret = typeof value === "string" ? value.trim() : ""
+  if (!secret) {
+    return fallback
+  }
+
+  if (secret.length < 7) {
+    const first = secret[0]
+    const last = secret[secret.length - 1]
+    return `${first}***${last}`
+  }
+
+  const prefix = secret.slice(0, Math.min(3, secret.length))
+  const suffix = secret.slice(-Math.min(4, secret.length))
+  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..a0d82cf15
--- /dev/null
+++ b/web/frontend/src/components/shared-form.tsx
@@ -0,0 +1,158 @@
+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"
+
+interface FieldProps {
+  label: string
+  hint?: string
+  error?: string
+  required?: boolean
+  children: ReactNode
+}
+
+export function Field({ label, hint, error, required, children }: FieldProps) {
+  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
+}
+
+export function SwitchCardField({
+  label,
+  hint,
+  error,
+  checked,
+  onCheckedChange,
+  ariaLabel,
+  disabled,
+  children,
+}: SwitchCardFieldProps) {
+  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/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/hooks/use-chat-models.ts b/web/frontend/src/hooks/use-chat-models.ts
new file mode 100644
index 000000000..8a82ceaf3
--- /dev/null
+++ b/web/frontend/src/hooks/use-chat-models.ts
@@ -0,0 +1,87 @@
+import { useCallback, useEffect, useMemo, 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 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) => {
+    try {
+      await setDefaultModel(modelName)
+      setDefaultModelName(modelName)
+      setModelList((prev) =>
+        prev.map((m) => ({ ...m, is_default: m.model_name === modelName })),
+      )
+    } catch (err) {
+      console.error("Failed to set default model:", err)
+    }
+  }, [])
+
+  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.ts b/web/frontend/src/hooks/use-gateway.ts
new file mode 100644
index 000000000..097dc3598
--- /dev/null
+++ b/web/frontend/src/hooks/use-gateway.ts
@@ -0,0 +1,121 @@
+import { useAtom } from "jotai"
+import { useCallback, useEffect, useState } from "react"
+
+import {
+  type GatewayStatusResponse,
+  getGatewayStatus,
+  startGateway,
+  stopGateway,
+} from "@/api/gateway"
+import { gatewayAtom } from "@/store"
+
+// Global variable to ensure we only have one SSE connection
+let sseInitialized = false
+
+export function useGateway() {
+  const [{ status: state, canStart }, setGateway] = useAtom(gatewayAtom)
+  const [loading, setLoading] = useState(false)
+
+  const applyGatewayStatus = useCallback(
+    (data: GatewayStatusResponse) => {
+      setGateway((prev) => ({
+        ...prev,
+        status: data.gateway_status ?? "unknown",
+        canStart: data.gateway_start_allowed ?? true,
+      }))
+    },
+    [setGateway],
+  )
+
+  // Initialize global SSE connection once
+  useEffect(() => {
+    if (sseInitialized) return
+    sseInitialized = true
+
+    getGatewayStatus()
+      .then((data) => applyGatewayStatus(data))
+      .catch(() => {
+        setGateway({
+          status: "unknown",
+          canStart: true,
+        })
+      })
+
+    const statusPoll = window.setInterval(() => {
+      getGatewayStatus()
+        .then((data) => applyGatewayStatus(data))
+        .catch(() => {
+          // ignore polling errors
+        })
+    }, 5000)
+
+    // Subscribe to SSE for real-time updates globally
+    const es = new EventSource("/api/gateway/events")
+
+    es.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data)
+        if (
+          data.gateway_status ||
+          typeof data.gateway_start_allowed === "boolean"
+        ) {
+          setGateway((prev) => ({
+            ...prev,
+            status: data.gateway_status ?? prev.status,
+            canStart:
+              typeof data.gateway_start_allowed === "boolean"
+                ? data.gateway_start_allowed
+                : prev.canStart,
+          }))
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    es.onerror = () => {
+      // EventSource will auto-reconnect
+      setGateway((prev) => ({ ...prev, status: "unknown" }))
+    }
+
+    return () => {
+      window.clearInterval(statusPoll)
+      es.close()
+      sseInitialized = false
+    }
+  }, [applyGatewayStatus, setGateway])
+
+  const start = useCallback(async () => {
+    if (!canStart) return
+
+    setLoading(true)
+    try {
+      await startGateway()
+      // SSE will push the real state changes, but set optimistic state
+      setGateway((prev) => ({ ...prev, status: "starting" }))
+    } catch (err) {
+      console.error("Failed to start gateway:", err)
+      try {
+        const status = await getGatewayStatus()
+        applyGatewayStatus(status)
+      } catch {
+        setGateway((prev) => ({ ...prev, status: "unknown" }))
+      }
+    } finally {
+      setLoading(false)
+    }
+  }, [applyGatewayStatus, canStart, setGateway])
+
+  const stop = useCallback(async () => {
+    setLoading(true)
+    try {
+      await stopGateway()
+    } catch (err) {
+      console.error("Failed to stop gateway:", err)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  return { state, loading, canStart, start, stop }
+}
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..7735ad928
--- /dev/null
+++ b/web/frontend/src/hooks/use-pico-chat.ts
@@ -0,0 +1,388 @@
+import dayjs from "dayjs"
+import { useAtomValue } from "jotai"
+import { useCallback, useEffect, useRef, useState } from "react"
+
+import { getPicoToken } from "@/api/pico"
+import { getSessionHistory } from "@/api/sessions"
+import { gatewayAtom } from "@/store"
+
+// Pico Protocol message types
+interface PicoMessage {
+  type: string
+  id?: string
+  session_id?: string
+  timestamp?: number | string
+  payload?: Record<string, unknown>
+}
+
+export interface ChatMessage {
+  id: string
+  role: "user" | "assistant"
+  content: string
+  timestamp: number | string
+}
+
+type ConnectionState = "disconnected" | "connecting" | "connected" | "error"
+
+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)
+
+    // RFC4122 v4: set version and variant bits.
+    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)}`
+}
+
+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)
+}
+
+// Helper to format message timestamps
+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")
+  }
+
+  // Cross-day formatting
+  if (isThisYear) {
+    return date.format("MMM D LT")
+  }
+
+  return date.format("ll LT")
+}
+
+export function usePicoChat() {
+  const { status: gatewayState } = useAtomValue(gatewayAtom)
+  const [messages, setMessages] = useState<ChatMessage[]>([])
+  const [connectionState, setConnectionState] =
+    useState<ConnectionState>("disconnected")
+  const [isTyping, setIsTyping] = useState(false)
+  const [activeSessionId, setActiveSessionId] =
+    useState<string>(generateSessionId)
+
+  const wsRef = useRef<WebSocket | null>(null)
+  const isConnectingRef = useRef(false)
+  const msgIdCounter = useRef(0)
+  const activeSessionIdRef = useRef(activeSessionId)
+
+  // Keep ref in sync
+  useEffect(() => {
+    activeSessionIdRef.current = activeSessionId
+  }, [activeSessionId])
+
+  const handlePicoMessage = useCallback((msg: PicoMessage) => {
+    const payload = msg.payload || {}
+
+    switch (msg.type) {
+      case "message.create": {
+        const content = (payload.content as string) || ""
+        const messageId = (payload.message_id as string) || `pico-${Date.now()}`
+        // Use provided timestamp or current time
+        const timestampRaw =
+          msg.timestamp !== undefined && Number.isFinite(Number(msg.timestamp))
+            ? normalizeUnixTimestamp(Number(msg.timestamp))
+            : Date.now()
+
+        setMessages((prev) => [
+          ...prev,
+          {
+            id: messageId,
+            role: "assistant",
+            content,
+            timestamp: timestampRaw,
+          },
+        ])
+        setIsTyping(false)
+        break
+      }
+
+      case "message.update": {
+        const content = (payload.content as string) || ""
+        const messageId = payload.message_id as string
+        if (!messageId) break
+
+        setMessages((prev) =>
+          prev.map((m) => (m.id === messageId ? { ...m, content } : m)),
+        )
+        break
+      }
+
+      case "typing.start":
+        setIsTyping(true)
+        break
+
+      case "typing.stop":
+        setIsTyping(false)
+        break
+
+      case "error":
+        console.error("Pico error:", payload)
+        setIsTyping(false)
+        break
+
+      case "pong":
+        // heartbeat response, ignore
+        break
+
+      default:
+        console.log("Unknown pico message type:", msg.type)
+    }
+  }, [])
+
+  const connect = useCallback(async () => {
+    if (
+      isConnectingRef.current ||
+      (wsRef.current &&
+        (wsRef.current.readyState === WebSocket.OPEN ||
+          wsRef.current.readyState === WebSocket.CONNECTING))
+    ) {
+      return
+    }
+
+    isConnectingRef.current = true
+    setConnectionState("connecting")
+
+    try {
+      const { token, ws_url } = await getPicoToken()
+
+      if (!token) {
+        console.error("No pico token available")
+        setConnectionState("error")
+        isConnectingRef.current = false
+        return
+      }
+
+      // If the backend returns a localhost URL but we are accessing it via a LAN IP
+      // (e.g., from a mobile device during dev), rewrite the hostname to match.
+      let finalWsUrl = ws_url
+      try {
+        const parsedUrl = new URL(ws_url)
+        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 (e) {
+        console.warn("Could not parse ws_url:", e)
+      }
+
+      // Build WebSocket URL with session_id
+      const sessionId = activeSessionIdRef.current
+      const url = `${finalWsUrl}?token=${encodeURIComponent(token)}&session_id=${encodeURIComponent(sessionId)}`
+      const socket = new WebSocket(url)
+
+      socket.onopen = () => {
+        setConnectionState("connected")
+        isConnectingRef.current = false
+      }
+
+      socket.onmessage = (event) => {
+        try {
+          const msg: PicoMessage = JSON.parse(event.data)
+          handlePicoMessage(msg)
+        } catch {
+          console.warn("Non-JSON message from pico:", event.data)
+        }
+      }
+
+      socket.onclose = () => {
+        setConnectionState("disconnected")
+        wsRef.current = null
+        isConnectingRef.current = false
+      }
+
+      socket.onerror = () => {
+        setConnectionState("error")
+        isConnectingRef.current = false
+      }
+
+      wsRef.current = socket
+    } catch (err) {
+      console.error("Failed to connect to pico:", err)
+      setConnectionState("error")
+      isConnectingRef.current = false
+    }
+  }, [handlePicoMessage])
+
+  const disconnect = useCallback(() => {
+    if (wsRef.current) {
+      wsRef.current.close()
+      wsRef.current = null
+    }
+    setConnectionState("disconnected")
+    isConnectingRef.current = false
+  }, [])
+
+  // Auto connect/disconnect based on gateway state
+  useEffect(() => {
+    // Wrap in setTimeout to avoid React calling setState synchronously during render
+    const timerId = setTimeout(() => {
+      if (gatewayState === "running") {
+        connect()
+      } else {
+        disconnect()
+      }
+    }, 0)
+
+    return () => clearTimeout(timerId)
+  }, [gatewayState, connect, disconnect])
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => disconnect()
+  }, [disconnect])
+
+  const sendMessage = useCallback((content: string) => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+      console.warn("WebSocket not connected")
+      return
+    }
+
+    const id = `msg-${++msgIdCounter.current}-${Date.now()}`
+    const timestampRaw = Date.now()
+
+    // Add user message to local state
+    setMessages((prev) => [
+      ...prev,
+      { id, role: "user", content, timestamp: timestampRaw },
+    ])
+
+    // Show typing indicator immediately
+    setIsTyping(true)
+
+    // Send via Pico Protocol
+    const picoMsg: PicoMessage = {
+      type: "message.send",
+      id,
+      payload: { content },
+    }
+    wsRef.current.send(JSON.stringify(picoMsg))
+  }, [])
+
+  // Switch to a historical session
+  const switchSession = useCallback(
+    async (sessionId: string) => {
+      // Disconnect current WebSocket
+      disconnect()
+
+      // Set new session ID
+      setActiveSessionId(sessionId)
+      setIsTyping(false)
+
+      // Load history from backend
+      try {
+        const detail = await getSessionHistory(sessionId)
+        // Set all history messages timestamp from the session updated time as fallback,
+        // since currently the backend doesn't return per-message timestamp in the history API.
+        // We'll use the session's updated time for now.
+        const fallbackTime = detail.updated
+
+        setMessages(
+          detail.messages.map((m, i) => ({
+            id: `hist-${i}-${Date.now()}`,
+            role: m.role as "user" | "assistant",
+            content: m.content,
+            timestamp: fallbackTime,
+          })),
+        )
+      } catch (err) {
+        console.error("Failed to load session history:", err)
+        setMessages([])
+      }
+
+      // Reconnect with new session ID (will use the updated ref)
+      // Small delay to ensure state has settled
+      setTimeout(() => {
+        if (gatewayState === "running") {
+          connect()
+        }
+      }, 100)
+    },
+    [disconnect, connect, gatewayState],
+  )
+
+  // Start a new empty chat
+  const newChat = useCallback(() => {
+    if (messages.length === 0) {
+      return
+    }
+
+    disconnect()
+    const newId = generateSessionId()
+    setActiveSessionId(newId)
+    setMessages([])
+    setIsTyping(false)
+
+    // Reconnect with the fresh session
+    setTimeout(() => {
+      if (gatewayState === "running") {
+        connect()
+      }
+    }, 100)
+  }, [disconnect, connect, gatewayState, messages.length])
+
+  return {
+    messages,
+    connectionState,
+    isTyping,
+    activeSessionId,
+    sendMessage,
+    switchSession,
+    newChat,
+  }
+}
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..1a6d5c956
--- /dev/null
+++ b/web/frontend/src/hooks/use-session-history.ts
@@ -0,0 +1,96 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+
+import { type SessionSummary, deleteSession, getSessions } from "@/api/sessions"
+
+const LIMIT = 20
+
+interface UseSessionHistoryOptions {
+  activeSessionId: string
+  onDeletedActiveSession: () => void
+}
+
+export function useSessionHistory({
+  activeSessionId,
+  onDeletedActiveSession,
+}: UseSessionHistoryOptions) {
+  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 loadSessions = useCallback(
+    async (reset = true) => {
+      try {
+        const currentOffset = reset ? 0 : offset
+        if (reset) {
+          setHasMore(true)
+          setOffset(0)
+        }
+
+        const data = await getSessions(currentOffset, LIMIT)
+
+        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 {
+        // silently fail
+      } finally {
+        setIsLoadingMore(false)
+      }
+    },
+    [offset],
+  )
+
+  useEffect(() => {
+    if (!observerRef.current || !hasMore || isLoadingMore) return
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0].isIntersecting && hasMore && !isLoadingMore) {
+          setIsLoadingMore(true)
+          void loadSessions(false)
+        }
+      },
+      { threshold: 0.1 },
+    )
+
+    observer.observe(observerRef.current)
+    return () => observer.disconnect()
+  }, [hasMore, isLoadingMore, 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,
+    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..0848af468
--- /dev/null
+++ b/web/frontend/src/hooks/use-sidebar-channels.ts
@@ -0,0 +1,236 @@
+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 = 5
+const CHANNEL_IMPORTANCE_ORDER = [
+  "discord",
+  "feishu",
+  "telegram",
+  "slack",
+  "line",
+  "wecom",
+  "wecom_app",
+  "wecom_aibot",
+  "dingtalk",
+  "qq",
+  "onebot",
+  "matrix",
+  "pico",
+  "maixcam",
+  "irc",
+  "whatsapp",
+  "whatsapp_native",
+]
+const CHANNEL_IMPORTANCE_INDEX = new Map(
+  CHANNEL_IMPORTANCE_ORDER.map((name, index) => [name, index]),
+)
+
+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,
+  wecom: IconBrandWechat,
+  wecom_app: IconBrandWechat,
+  wecom_aibot: 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 {
+  t: TFunction
+}
+
+export function useSidebarChannels({ 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 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 =
+        CHANNEL_IMPORTANCE_INDEX.get(a.name) ?? Number.MAX_SAFE_INTEGER
+      const bImportance =
+        CHANNEL_IMPORTANCE_INDEX.get(b.name) ?? Number.MAX_SAFE_INTEGER
+      if (aImportance !== bImportance) {
+        return aImportance - bImportance
+      }
+
+      return getChannelDisplayName(a, t).localeCompare(
+        getChannelDisplayName(b, t),
+      )
+    })
+    return list
+  }, [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/hooks/use-websocket.ts b/web/frontend/src/hooks/use-websocket.ts
new file mode 100644
index 000000000..c41b5ed34
--- /dev/null
+++ b/web/frontend/src/hooks/use-websocket.ts
@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+
+export function useWebSocket(path: string) {
+  const [message, setMessage] = useState<string>("No messages yet")
+  const [connected, setConnected] = useState(false)
+  const wsRef = useRef<WebSocket | null>(null)
+
+  const connect = useCallback(() => {
+    if (wsRef.current) {
+      wsRef.current.close()
+    }
+
+    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:"
+    const url = `${protocol}//${window.location.host}${path}`
+    const socket = new WebSocket(url)
+
+    socket.onopen = () => {
+      setConnected(true)
+      setMessage("Connected to WebSocket server.")
+    }
+
+    socket.onmessage = (event) => {
+      setMessage(event.data)
+    }
+
+    socket.onclose = () => {
+      setConnected(false)
+      setMessage("WebSocket connection closed.")
+    }
+
+    socket.onerror = (error) => {
+      setConnected(false)
+      setMessage("WebSocket error occurred.")
+      console.error("WebSocket Error:", error)
+    }
+
+    wsRef.current = socket
+  }, [path])
+
+  useEffect(() => {
+    return () => {
+      wsRef.current?.close()
+    }
+  }, [])
+
+  return { message, connected, connect }
+}
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..f1ed0ac16
--- /dev/null
+++ b/web/frontend/src/i18n/locales/en.json
@@ -0,0 +1,393 @@
+{
+  "navigation": {
+    "chat": "Chat",
+    "model_group": "Models",
+    "models": "Models",
+    "credentials": "Credentials",
+    "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...",
+    "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",
+    "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"
+      },
+      "status": {
+        "starting": "Starting Gateway..."
+      }
+    }
+  },
+  "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"
+    },
+    "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",
+      "wecom_app": "WeCom App",
+      "wecom_aibot": "WeCom AI Bot",
+      "whatsapp": "WhatsApp",
+      "whatsapp_native": "WhatsApp Native",
+      "pico": "Web",
+      "maixcam": "MaixCam",
+      "matrix": "Matrix",
+      "irc": "IRC"
+    },
+    "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",
+      "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"
+    },
+    "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.",
+        "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.",
+        "genericField": "Used to configure {{field}}."
+      }
+    },
+    "validation": {
+      "requiredField": "This field is required."
+    }
+  },
+  "pages": {
+    "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.",
+      "max_tokens": "Max Tokens",
+      "max_tokens_hint": "Upper token limit per model response.",
+      "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",
+      "launcher_load_error": "Failed to load service parameters.",
+      "launcher_restart_hint": "Service parameter changes apply after restarting PicoClaw Web.",
+      "advanced_desc": "Open the raw JSON page to edit every field directly.",
+      "open_raw": "Raw Config",
+      "back_to_visual": "Visual Config",
+      "raw_json_title": "Raw JSON Configuration",
+      "raw_json_desc": "Advanced users can directly edit the raw JSON configuration below.",
+      "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": {
+      "description": "System logs and monitoring."
+    }
+  }
+}
diff --git a/web/frontend/src/i18n/locales/zh.json b/web/frontend/src/i18n/locales/zh.json
new file mode 100644
index 000000000..b66f0f03d
--- /dev/null
+++ b/web/frontend/src/i18n/locales/zh.json
@@ -0,0 +1,393 @@
+{
+  "navigation": {
+    "chat": "对话",
+    "model_group": "模型",
+    "models": "模型",
+    "credentials": "凭据",
+    "services": "服务",
+    "channels_group": "频道",
+    "show_more_channels": "更多",
+    "show_less_channels": "收起",
+    "config": "配置",
+    "logs": "日志"
+  },
+  "chat": {
+    "welcome": "今天我能为您做些什么？",
+    "welcomeDesc": "您可以询问我天气、设置或其他任何任务，我随时为您效劳。",
+    "placeholder": "输入新消息...",
+    "newChat": "新建对话",
+    "notConnected": "服务未运行，请先启动以进行对话。",
+    "thinking": {
+      "step1": "思考中...",
+      "step2": "分析您的请求...",
+      "step3": "准备回复...",
+      "step4": "马上就好..."
+    },
+    "history": "历史记录",
+    "noHistory": "暂无对话历史",
+    "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": "停止服务"
+      },
+      "status": {
+        "starting": "服务启动中..."
+      }
+    }
+  },
+  "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": "默认"
+    },
+    "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": "企业微信",
+      "wecom_app": "企业微信应用",
+      "wecom_aibot": "企业微信 AI 机器人",
+      "whatsapp": "WhatsApp",
+      "whatsapp_native": "WhatsApp Native",
+      "pico": "Web",
+      "maixcam": "MaixCam",
+      "matrix": "Matrix",
+      "irc": "IRC"
+    },
+    "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": "群聊触发前缀",
+      "allowFrom": "允许来源",
+      "allowFromPlaceholder": "例如 123456, 789012",
+      "allowOrigins": "允许来源域名",
+      "allowOriginsPlaceholder": "例如 https://example.com, http://localhost:5173",
+      "secretPlaceholder": "输入密钥",
+      "secretHintSet": "已设置密钥，留空表示不修改。"
+    },
+    "page": {
+      "notFound": "不支持频道“{{name}}”。",
+      "saveSuccess": "频道配置已保存。",
+      "saveError": "保存频道配置失败",
+      "enabled": "已启用",
+      "docLink": "配置文档",
+      "enableLabel": "启用频道"
+    },
+    "form": {
+      "desc": {
+        "token": "机器人访问令牌，用于连接平台 API。",
+        "botToken": "Bot Token，用于发送与接收消息。",
+        "appToken": "App Token，用于 Socket 模式连接。",
+        "appId": "应用唯一标识，用于平台鉴权。",
+        "appSecret": "应用密钥，用于请求签名和鉴权。",
+        "verificationToken": "事件回调验证令牌。",
+        "encryptKey": "消息加密密钥，用于解密回调内容。",
+        "baseUrl": "平台 API 地址，默认使用官方地址。",
+        "proxy": "HTTP 代理地址，用于网络访问。",
+        "mentionOnly": "在群聊中仅当明确提及时才响应。",
+        "typingEnabled": "在生成回复时显示“正在输入”状态。",
+        "placeholderEnabled": "在最终回复发送前，先发送临时占位消息。",
+        "groupTriggerMentionOnly": "在群聊中仅当提及机器人时才响应。",
+        "groupTriggerPrefixes": "群聊触发前缀，多个值用逗号分隔。",
+        "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 扩展能力列表。",
+        "genericField": "用于配置{{field}}。"
+      }
+    },
+    "validation": {
+      "requiredField": "请填写该字段"
+    }
+  },
+  "pages": {
+    "config": {
+      "load_error": "加载配置失败，请刷新后重试。",
+      "workspace": "工作目录",
+      "workspace_hint": "智能体执行文件读写操作时使用的基础目录。",
+      "restrict_workspace": "限制工作目录访问",
+      "restrict_workspace_hint": "仅允许在工作目录内执行文件操作。",
+      "max_tokens": "最大 Token 数",
+      "max_tokens_hint": "单次模型响应允许的最大 Token 数。",
+      "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": "允许访问网段（CIDR）",
+      "allowed_cidrs_hint": "仅允许这些 CIDR 网段的客户端访问服务。可按行或逗号分隔；留空表示允许所有来源。",
+      "allowed_cidrs_placeholder": "192.168.1.0/24\n10.0.0.0/8",
+      "launcher_load_error": "加载服务参数失败。",
+      "launcher_restart_hint": "服务参数变更需重启 PicoClaw Web 后生效。",
+      "advanced_desc": "可打开原始 JSON 页面直接编辑全部字段。",
+      "open_raw": "原始配置",
+      "back_to_visual": "可视化配置",
+      "raw_json_title": "原始 JSON 配置",
+      "raw_json_desc": "高级用户可以直接编辑下方的原始 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": {
+      "description": "系统日志和监控。"
+    }
+  }
+}
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/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..336504075
--- /dev/null
+++ b/web/frontend/src/routeTree.gen.ts
@@ -0,0 +1,229 @@
+/* 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 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'
+
+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 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)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/channels': typeof ChannelsRouteRouteWithChildren
+  '/config': typeof ConfigRouteWithChildren
+  '/credentials': typeof CredentialsRoute
+  '/logs': typeof LogsRoute
+  '/models': typeof ModelsRoute
+  '/channels/$name': typeof ChannelsNameRoute
+  '/config/raw': typeof ConfigRawRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/channels': typeof ChannelsRouteRouteWithChildren
+  '/config': typeof ConfigRouteWithChildren
+  '/credentials': typeof CredentialsRoute
+  '/logs': typeof LogsRoute
+  '/models': typeof ModelsRoute
+  '/channels/$name': typeof ChannelsNameRoute
+  '/config/raw': typeof ConfigRawRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/channels': typeof ChannelsRouteRouteWithChildren
+  '/config': typeof ConfigRouteWithChildren
+  '/credentials': typeof CredentialsRoute
+  '/logs': typeof LogsRoute
+  '/models': typeof ModelsRoute
+  '/channels/$name': typeof ChannelsNameRoute
+  '/config/raw': typeof ConfigRawRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths:
+    | '/'
+    | '/channels'
+    | '/config'
+    | '/credentials'
+    | '/logs'
+    | '/models'
+    | '/channels/$name'
+    | '/config/raw'
+  fileRoutesByTo: FileRoutesByTo
+  to:
+    | '/'
+    | '/channels'
+    | '/config'
+    | '/credentials'
+    | '/logs'
+    | '/models'
+    | '/channels/$name'
+    | '/config/raw'
+  id:
+    | '__root__'
+    | '/'
+    | '/channels'
+    | '/config'
+    | '/credentials'
+    | '/logs'
+    | '/models'
+    | '/channels/$name'
+    | '/config/raw'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ChannelsRouteRoute: typeof ChannelsRouteRouteWithChildren
+  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
+    }
+    '/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
+    }
+  }
+}
+
+interface ChannelsRouteRouteChildren {
+  ChannelsNameRoute: typeof ChannelsNameRoute
+}
+
+const ChannelsRouteRouteChildren: ChannelsRouteRouteChildren = {
+  ChannelsNameRoute: ChannelsNameRoute,
+}
+
+const ChannelsRouteRouteWithChildren = ChannelsRouteRoute._addFileChildren(
+  ChannelsRouteRouteChildren,
+)
+
+interface ConfigRouteChildren {
+  ConfigRawRoute: typeof ConfigRawRoute
+}
+
+const ConfigRouteChildren: ConfigRouteChildren = {
+  ConfigRawRoute: ConfigRawRoute,
+}
+
+const ConfigRouteWithChildren =
+  ConfigRoute._addFileChildren(ConfigRouteChildren)
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ChannelsRouteRoute: ChannelsRouteRouteWithChildren,
+  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..48f228d84
--- /dev/null
+++ b/web/frontend/src/routes/__root.tsx
@@ -0,0 +1,15 @@
+import { Outlet, createRootRoute } from "@tanstack/react-router"
+import { TanStackRouterDevtools } from "@tanstack/react-router-devtools"
+
+import { AppLayout } from "@/components/app-layout"
+
+const RootLayout = () => {
+  return (
+    <AppLayout>
+      <Outlet />
+      <TanStackRouterDevtools />
+    </AppLayout>
+  )
+}
+
+export const Route = createRootRoute({ component: RootLayout })
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..02ce55dfd
--- /dev/null
+++ b/web/frontend/src/routes/config.raw.tsx
@@ -0,0 +1,34 @@
+import { IconAdjustments } from "@tabler/icons-react"
+import { Link, createFileRoute } from "@tanstack/react-router"
+import { useTranslation } from "react-i18next"
+
+import { RawJsonPanel } from "@/components/config/raw-json-panel"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+
+export const Route = createFileRoute("/config/raw")({
+  component: RawConfigPage,
+})
+
+function RawConfigPage() {
+  const { t } = useTranslation()
+
+  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-1 overflow-auto p-3 lg:p-6">
+        <div className="mx-auto max-w-4xl">
+          <RawJsonPanel />
+        </div>
+      </div>
+    </div>
+  )
+}
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..39688bd84
--- /dev/null
+++ b/web/frontend/src/routes/logs.tsx
@@ -0,0 +1,123 @@
+import { createFileRoute } from "@tanstack/react-router"
+import { useAtomValue } from "jotai"
+import { useEffect, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import { getGatewayStatus } from "@/api/gateway"
+import { PageHeader } from "@/components/page-header"
+import { ScrollArea } from "@/components/ui/scroll-area"
+import { gatewayAtom } from "@/store/gateway"
+
+export const Route = createFileRoute("/logs")({
+  component: LogsPage,
+})
+
+function LogsPage() {
+  const { t } = useTranslation()
+  const [logs, setLogs] = useState<string[]>([])
+  const logOffsetRef = useRef<number>(0)
+  const logRunIdRef = useRef<number>(-1)
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  const gateway = useAtomValue(gatewayAtom)
+
+  useEffect(() => {
+    let mounted = true
+    let timeout: ReturnType<typeof setTimeout>
+
+    const fetchLogs = async () => {
+      // Only fetch logs if the gateway is running or starting
+      if (
+        !mounted ||
+        (gateway.status !== "running" && gateway.status !== "starting")
+      ) {
+        if (mounted) {
+          // Still poll the state, but maybe at a slower rate, or we just rely on SSE for status
+          // and restart fast polling when it's running. Let's just re-evaluate every second
+          timeout = setTimeout(fetchLogs, 1000)
+        }
+        return
+      }
+
+      try {
+        const data = await getGatewayStatus({
+          log_offset: logOffsetRef.current,
+          log_run_id: logRunIdRef.current,
+        })
+
+        if (!mounted) return
+
+        if (
+          data.log_run_id !== undefined &&
+          data.log_run_id !== logRunIdRef.current
+        ) {
+          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) {
+          setLogs((prev) => [...prev, ...data.logs!])
+          logOffsetRef.current =
+            data.log_total || logOffsetRef.current + data.logs.length
+        }
+      } catch {
+        // Ignore simple fetch errors during polling
+      } finally {
+        if (mounted) {
+          timeout = setTimeout(fetchLogs, 1000)
+        }
+      }
+    }
+
+    fetchLogs()
+
+    return () => {
+      mounted = false
+      clearTimeout(timeout)
+    }
+  }, [gateway.status])
+
+  useEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollIntoView({ behavior: "smooth" })
+    }
+  }, [logs])
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader title={t("navigation.logs")} />
+
+      <div className="flex flex-1 flex-col overflow-hidden p-4 sm:p-8">
+        <div className="mb-4">
+          <h1 className="text-2xl font-semibold tracking-tight">
+            {t("navigation.logs")}
+          </h1>
+          <p className="text-muted-foreground mt-2 text-sm">
+            {t("pages.logs.description")}
+          </p>
+        </div>
+
+        <div className="bg-muted/30 relative flex-1 overflow-hidden rounded-lg border">
+          <ScrollArea className="h-full">
+            <div className="p-4 font-mono text-sm leading-relaxed">
+              {logs.length === 0 ? (
+                <div className="text-muted-foreground italic">
+                  Waiting for logs...
+                </div>
+              ) : (
+                logs.map((log, i) => (
+                  <div key={i} className="break-all whitespace-pre-wrap">
+                    {log}
+                  </div>
+                ))
+              )}
+              <div ref={scrollRef} />
+            </div>
+          </ScrollArea>
+        </div>
+      </div>
+    </div>
+  )
+}
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/gateway.ts b/web/frontend/src/store/gateway.ts
new file mode 100644
index 000000000..89da9d7fd
--- /dev/null
+++ b/web/frontend/src/store/gateway.ts
@@ -0,0 +1,38 @@
+import { atom, getDefaultStore } from "jotai"
+
+import { type GatewayStatusResponse, getGatewayStatus } from "@/api/gateway"
+
+export type GatewayState =
+  | "running"
+  | "starting"
+  | "stopped"
+  | "error"
+  | "unknown"
+
+export interface GatewayStoreState {
+  status: GatewayState
+  canStart: boolean
+}
+
+// Global atom for gateway state
+export const gatewayAtom = atom<GatewayStoreState>({
+  status: "unknown",
+  canStart: true,
+})
+
+function applyGatewayStatusToStore(data: GatewayStatusResponse) {
+  getDefaultStore().set(gatewayAtom, (prev) => ({
+    ...prev,
+    status: data.gateway_status ?? "unknown",
+    canStart: data.gateway_start_allowed ?? true,
+  }))
+}
+
+export async function refreshGatewayState() {
+  try {
+    const status = await getGatewayStatus()
+    applyGatewayStatusToStore(status)
+  } catch {
+    // Best-effort refresh only; keep current state on error.
+  }
+}
diff --git a/web/frontend/src/store/index.ts b/web/frontend/src/store/index.ts
new file mode 100644
index 000000000..9dfcdf3c7
--- /dev/null
+++ b/web/frontend/src/store/index.ts
@@ -0,0 +1 @@
+export * from "./gateway"
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/AGENTS.md
similarity index 100%
rename from workspace/AGENT.md
rename to workspace/AGENTS.md