chore: fix vitest standalone configs and update package description

- vitest.live.config.ts and vitest.e2e.config.ts now extend root config
- Inherits testTimeout (120s), resolve.alias, pool, setupFiles, excludes
- ui/vitest.node.config.ts gets explicit 120s timeout
- package.json description updated for multi-channel AI gateway
- Removed unused src/utils/time-format.ts

.agents/skills/PR_WORKFLOW.md

@@ -0,0 +1,126 @@
+# PR Review Instructions
+
+Please read this in full and do not skip sections.
+
+## Working rule
+
+Skills execute workflow, maintainers provide judgment.
+Always pause between skills to evaluate technical direction, not just command success.
+
+These three skills must be used in order:
+
+1. `review-pr`
+2. `prepare-pr`
+3. `merge-pr`
+
+They are necessary, but not sufficient. Maintainers must steer between steps and understand the code before moving forward.
+
+Treat PRs as reports first, code second.
+If submitted code is low quality, ignore it and implement the best solution for the problem.
+
+Do not continue if you cannot verify the problem is real or test the fix.
+
+## PR quality bar
+
+- Do not trust PR code by default.
+- Do not merge changes you cannot validate with a reproducible problem and a tested fix.
+- Keep types strict. Do not use `any` in implementation code.
+- Keep external-input boundaries typed and validated, including CLI input, environment variables, network payloads, and tool output.
+- Keep implementations properly scoped. Fix root causes, not local symptoms.
+- Identify and reuse canonical sources of truth so behavior does not drift across the codebase.
+- Harden changes. Always evaluate security impact and abuse paths.
+- Understand the system before changing it. Never make the codebase messier just to clear a PR queue.
+
+## Unified workflow
+
+Entry criteria:
+
+- PR URL/number is known.
+- Problem statement is clear enough to attempt reproduction.
+- A realistic verification path exists (tests, integration checks, or explicit manual validation).
+
+### 1) `review-pr`
+
+Purpose:
+
+- Review only: correctness, value, security risk, tests, docs, and changelog impact.
+- Produce structured findings and a recommendation.
+
+Expected output:
+
+- Recommendation: ready, needs work, needs discussion, or close.
+- `.local/review.md` with actionable findings.
+
+Maintainer checkpoint before `prepare-pr`:
+
+```
+What problem are they trying to solve?
+What is the most optimal implementation?
+Is the code properly scoped?
+Can we fix up everything?
+Do we have any questions?
+```
+
+Stop and escalate instead of continuing if:
+
+- The problem cannot be reproduced or confirmed.
+- The proposed PR scope does not match the stated problem.
+- The design introduces unresolved security or trust-boundary concerns.
+
+### 2) `prepare-pr`
+
+Purpose:
+
+- Make the PR merge-ready on its head branch.
+- Rebase onto current `main`, fix blocker/important findings, and run gates.
+
+Expected output:
+
+- Updated code and tests on the PR head branch.
+- `.local/prep.md` with changes, verification, and current HEAD SHA.
+- Final status: `PR is ready for /mergepr`.
+
+Maintainer checkpoint before `merge-pr`:
+
+```
+Is this the most optimal implementation?
+Is the code properly scoped?
+Is the code properly typed?
+Is the code hardened?
+Do we have enough tests?
+Are tests using fake timers where relevant? (e.g., debounce/throttle, retry backoff, timeout branches, delayed callbacks, polling loops)
+Do not add performative tests, ensure tests are real and there are no regressions.
+Take your time, fix it properly, refactor if necessary.
+Do you see any follow-up refactors we should do?
+Did any changes introduce any potential security vulnerabilities?
+```
+
+Stop and escalate instead of continuing if:
+
+- You cannot verify behavior changes with meaningful tests or validation.
+- Fixing findings requires broad architecture changes outside safe PR scope.
+- Security hardening requirements remain unresolved.
+
+### 3) `merge-pr`
+
+Purpose:
+
+- Merge only after review and prep artifacts are present and checks are green.
+- Use squash merge flow and verify the PR ends in `MERGED` state.
+
+Go or no-go checklist before merge:
+
+- All BLOCKER and IMPORTANT findings are resolved.
+- Verification is meaningful and regression risk is acceptably low.
+- Docs and changelog are updated when required.
+- Required CI checks are green and the branch is not behind `main`.
+
+Expected output:
+
+- Successful merge commit and recorded merge SHA.
+- Worktree cleanup after successful merge.
+
+Maintainer checkpoint after merge:
+
+- Were any refactors intentionally deferred and now need follow-up issue(s)?
+- Did this reveal broader architecture or test gaps we should address?

.agents/skills/merge-pr/SKILL.md

@@ -28,7 +28,7 @@ Merge a prepared PR via `gh pr merge --squash` and clean up the worktree after s
 
 ## Known Footguns
 
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/Development/openclaw`, not `~/openclaw`.
+- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
 - Read `.local/review.md` and `.local/prep.md` in the worktree. Do not skip.
 - Clean up the real worktree directory `.worktrees/pr-<PR>` only after a successful merge.
 - Expect cleanup to remove `.local/` artifacts.
@@ -49,7 +49,7 @@ Create a checklist of all merge steps, print it, then continue and execute the c
 Use an isolated worktree for all merge work.
 
 ```sh
-cd ~/Development/openclaw
+cd ~/dev/openclaw
 # Sanity: confirm you are in the repo
 git rev-parse --show-toplevel
 
@@ -167,7 +167,7 @@ gh pr view <PR> --json state --jq .state
 Run cleanup only if step 6 returned `MERGED`.
 
 ```sh
-cd ~/Development/openclaw
+cd ~/dev/openclaw
 
 git worktree remove ".worktrees/pr-<PR>" --force
 

.agents/skills/prepare-pr/SKILL.md

@@ -30,7 +30,7 @@ Prepare a PR branch for merge with review fixes, green gates, and an updated hea
 
 ## Known Footguns
 
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/openclaw`.
+- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
 - Do not run `git clean -fdx`.
 - Do not run `git add -A` or `git add .`.
 

.agents/skills/review-pr/SKILL.md

@@ -28,7 +28,7 @@ Perform a thorough review-only PR assessment and return a structured recommendat
 
 ## Known Failure Modes
 
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/openclaw`.
+- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
 - Do not stop after printing the checklist. That is not completion.
 
 ## Writing Style for Output
@@ -51,7 +51,7 @@ Create a checklist of all review steps, print it, then continue and execute the
 Use an isolated worktree for all review work.
 
 ```sh
-cd ~/Development/openclaw
+cd ~/dev/openclaw
 # Sanity: confirm you are in the repo
 git rev-parse --show-toplevel
 

.github/actions/detect-docs-only/action.yml

@@ -0,0 +1,41 @@
+name: Detect docs-only changes
+description: >
+  Outputs docs_only=true when all changed files are under docs/ or are
+  markdown (.md/.mdx). Fail-safe: if detection fails, outputs false (run
+  everything). Uses git diff — no API calls, no extra permissions needed.
+
+outputs:
+  docs_only:
+    description: "'true' if all changes are docs/markdown, 'false' otherwise"
+    value: ${{ steps.check.outputs.docs_only }}
+
+runs:
+  using: composite
+  steps:
+    - name: Detect docs-only changes
+      id: check
+      shell: bash
+      run: |
+        if [ "${{ github.event_name }}" = "push" ]; then
+          BASE="${{ github.event.before }}"
+        else
+          # Use the exact base SHA from the event payload — stable regardless
+          # of base branch movement (avoids origin/<ref> drift).
+          BASE="${{ github.event.pull_request.base.sha }}"
+        fi
+
+        # Fail-safe: if we can't diff, assume non-docs (run everything)
+        CHANGED=$(git diff --name-only "$BASE" HEAD 2>/dev/null || echo "UNKNOWN")
+        if [ "$CHANGED" = "UNKNOWN" ] || [ -z "$CHANGED" ]; then
+          echo "docs_only=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Check if all changed files are docs or markdown
+        NON_DOCS=$(echo "$CHANGED" | grep -vE '^docs/|\.md$|\.mdx$' || true)
+        if [ -z "$NON_DOCS" ]; then
+          echo "docs_only=true" >> "$GITHUB_OUTPUT"
+          echo "Docs-only change detected — skipping heavy jobs"
+        else
+          echo "docs_only=false" >> "$GITHUB_OUTPUT"
+        fi

.github/actions/discord-notify/action.yml

@@ -1,69 +0,0 @@
-name: Discord Notify
-description: Send notifications to Discord webhook
-
-inputs:
-  webhook_url:
-    description: Discord webhook URL
-    required: true
-  title:
-    description: Notification title
-    required: true
-  description:
-    description: Notification description
-    required: true
-  color:
-    description: Embed color (decimal)
-    required: false
-    default: "3447003"
-  username:
-    description: Bot username
-    required: false
-    default: "OpenClaw CI"
-  avatar_url:
-    description: Bot avatar URL
-    required: false
-    default: "https://avatars.githubusercontent.com/u/182880377"
-  timestamp:
-    description: Include timestamp
-    required: false
-    default: "true"
-  fields:
-    description: JSON array of embed fields
-    required: false
-    default: "[]"
-
-runs:
-  using: composite
-  steps:
-    - name: Send Discord notification
-      shell: bash
-      run: |
-        TIMESTAMP=""
-        if [ "${{ inputs.timestamp }}" = "true" ]; then
-          TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-        fi
-
-        # Build JSON payload with jq to handle escaping properly
-        PAYLOAD=$(jq -n \
-          --arg username "${{ inputs.username }}" \
-          --arg avatar_url "${{ inputs.avatar_url }}" \
-          --arg title "${{ inputs.title }}" \
-          --arg description "${{ inputs.description }}" \
-          --argjson color "${{ inputs.color }}" \
-          --argjson fields '${{ inputs.fields }}' \
-          --arg timestamp "$TIMESTAMP" \
-          --argjson add_timestamp "${{ inputs.timestamp == 'true' }}" \
-          '{
-            username: $username,
-            avatar_url: $avatar_url,
-            embeds: [{
-              title: $title,
-              description: $description,
-              color: $color,
-              fields: $fields
-            } + (if $add_timestamp then {timestamp: $timestamp} else {} end)]
-          }')
-
-        curl -sS -H "Content-Type: application/json" \
-          -d "$PAYLOAD" \
-          "${{ inputs.webhook_url }}"

.github/actions/setup-pnpm-store-cache/action.yml

@@ -0,0 +1,41 @@
+name: Setup pnpm + store cache
+description: Prepare pnpm via corepack and restore pnpm store cache.
+inputs:
+  pnpm-version:
+    description: pnpm version to activate via corepack.
+    required: false
+    default: "10.23.0"
+  cache-key-suffix:
+    description: Suffix appended to the cache key.
+    required: false
+    default: "node22"
+runs:
+  using: composite
+  steps:
+    - name: Setup pnpm (corepack retry)
+      shell: bash
+      run: |
+        set -euo pipefail
+        corepack enable
+        for attempt in 1 2 3; do
+          if corepack prepare "pnpm@${{ inputs.pnpm-version }}" --activate; then
+            pnpm -v
+            exit 0
+          fi
+          echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+          sleep $((attempt * 10))
+        done
+        exit 1
+
+    - name: Resolve pnpm store path
+      id: pnpm-store
+      shell: bash
+      run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+    - name: Restore pnpm store cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ steps.pnpm-store.outputs.path }}
+        key: ${{ runner.os }}-pnpm-store-${{ inputs.cache-key-suffix }}-${{ hashFiles('pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-${{ inputs.cache-key-suffix }}-

.github/instructions/copilot.instructions.md

@@ -0,0 +1,64 @@
+# OpenClaw Codebase Patterns
+
+**Always reuse existing code - no redundancy!**
+
+## Tech Stack
+
+- **Runtime**: Node 22+ (Bun also supported for dev/scripts)
+- **Language**: TypeScript (ESM, strict mode)
+- **Package Manager**: pnpm (keep `pnpm-lock.yaml` in sync)
+- **Lint/Format**: Oxlint, Oxfmt (`pnpm check`)
+- **Tests**: Vitest with V8 coverage
+- **CLI Framework**: Commander + clack/prompts
+- **Build**: tsdown (outputs to `dist/`)
+
+## Anti-Redundancy Rules
+
+- Avoid files that just re-export from another file. Import directly from the original source.
+- If a function already exists, import it - do NOT create a duplicate in another file.
+- Before creating any formatter, utility, or helper, search for existing implementations first.
+
+## Source of Truth Locations
+
+### Formatting Utilities (`src/infra/`)
+
+- **Time formatting**: `src\infra\format-time`
+
+**NEVER create local `formatAge`, `formatDuration`, `formatElapsedTime` functions - import from centralized modules.**
+
+### Terminal Output (`src/terminal/`)
+
+- Tables: `src/terminal/table.ts` (`renderTable`)
+- Themes/colors: `src/terminal/theme.ts` (`theme.success`, `theme.muted`, etc.)
+- Progress: `src/cli/progress.ts` (spinners, progress bars)
+
+### CLI Patterns
+
+- CLI option wiring: `src/cli/`
+- Commands: `src/commands/`
+- Dependency injection via `createDefaultDeps`
+
+## Import Conventions
+
+- Use `.js` extension for cross-package imports (ESM)
+- Direct imports only - no re-export wrapper files
+- Types: `import type { X }` for type-only imports
+
+## Code Quality
+
+- TypeScript (ESM), strict typing, avoid `any`
+- Keep files under ~700 LOC - extract helpers when larger
+- Colocated tests: `*.test.ts` next to source files
+- Run `pnpm check` before commits (lint + format)
+- Run `pnpm tsgo` for type checking
+
+## Stack & Commands
+
+- **Package manager**: pnpm (`pnpm install`)
+- **Dev**: `pnpm openclaw ...` or `pnpm dev`
+- **Type-check**: `pnpm tsgo`
+- **Lint/format**: `pnpm check`
+- **Tests**: `pnpm test`
+- **Build**: `pnpm build`
+
+If you are coding together with a human, do NOT use scripts/committer, but git directly and run the above commands manually to ensure quality.

.github/workflows/ci.yml

@@ -10,7 +10,118 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  install-check:
+  # Detect docs-only changes to skip heavy jobs (test, build, Windows, macOS, Android).
+  # Lint and format always run. Fail-safe: if detection fails, run everything.
+  docs-scope:
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.check.outputs.docs_only }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: false
+
+      - name: Detect docs-only changes
+        id: check
+        uses: ./.github/actions/detect-docs-only
+
+  # Detect which heavy areas are touched so PRs can skip unrelated expensive jobs.
+  # Push to main keeps broad coverage.
+  changed-scope:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
+    runs-on: ubuntu-latest
+    outputs:
+      run_node: ${{ steps.scope.outputs.run_node }}
+      run_macos: ${{ steps.scope.outputs.run_macos }}
+      run_android: ${{ steps.scope.outputs.run_android }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: false
+
+      - name: Detect changed scopes
+        id: scope
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ "${{ github.event_name }}" = "push" ]; then
+            BASE="${{ github.event.before }}"
+          else
+            BASE="${{ github.event.pull_request.base.sha }}"
+          fi
+
+          CHANGED="$(git diff --name-only "$BASE" HEAD 2>/dev/null || echo "UNKNOWN")"
+          if [ "$CHANGED" = "UNKNOWN" ] || [ -z "$CHANGED" ]; then
+            # Fail-safe: run broad checks if detection fails.
+            echo "run_node=true" >> "$GITHUB_OUTPUT"
+            echo "run_macos=true" >> "$GITHUB_OUTPUT"
+            echo "run_android=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          run_node=false
+          run_macos=false
+          run_android=false
+          has_non_docs=false
+          has_non_native_non_docs=false
+
+          while IFS= read -r path; do
+            [ -z "$path" ] && continue
+            case "$path" in
+              docs/*|*.md|*.mdx)
+                continue
+                ;;
+              *)
+                has_non_docs=true
+                ;;
+            esac
+
+            case "$path" in
+              apps/macos/*|apps/ios/*|apps/shared/*|Swabble/*)
+                run_macos=true
+                ;;
+            esac
+
+            case "$path" in
+              apps/android/*|apps/shared/*)
+                run_android=true
+                ;;
+            esac
+
+            case "$path" in
+              src/*|test/*|extensions/*|packages/*|scripts/*|ui/*|.github/*|openclaw.mjs|package.json|pnpm-lock.yaml|pnpm-workspace.yaml|tsconfig*.json|vitest*.ts|tsdown.config.ts|.oxlintrc.json|.oxfmtrc.jsonc)
+                run_node=true
+                ;;
+            esac
+
+            case "$path" in
+              apps/android/*|apps/ios/*|apps/macos/*|apps/shared/*|Swabble/*|appcast.xml)
+                ;;
+              *)
+                has_non_native_non_docs=true
+                ;;
+            esac
+          done <<< "$CHANGED"
+
+          # If there are non-doc files outside native app trees, keep Node checks enabled.
+          if [ "$run_node" = false ] && [ "$has_non_docs" = true ] && [ "$has_non_native_non_docs" = true ]; then
+            run_node=true
+          fi
+
+          echo "run_node=${run_node}" >> "$GITHUB_OUTPUT"
+          echo "run_macos=${run_macos}" >> "$GITHUB_OUTPUT"
+          echo "run_android=${run_android}" >> "$GITHUB_OUTPUT"
+
+  # Build dist once for Node-relevant changes and share it with downstream jobs.
+  build-artifacts:
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout
@@ -37,20 +148,76 @@ jobs:
           node-version: 22.x
           check-latest: true
 
-      - name: Setup pnpm (corepack retry)
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies (frozen)
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Build dist
+        run: pnpm build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-build
+          path: dist/
+          retention-days: 1
+
+  install-check:
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
         run: |
           set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
               exit 0
             fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
             sleep $((attempt * 10))
           done
           exit 1
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
+
       - name: Runtime versions
         run: |
           node -v
@@ -71,6 +238,8 @@ jobs:
           pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
 
   checks:
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false
@@ -79,21 +248,15 @@ jobs:
           - runtime: node
             task: tsgo
             command: pnpm tsgo
-          - runtime: node
-            task: lint
-            command: pnpm build && pnpm lint
           - runtime: node
             task: test
             command: pnpm canvas:a2ui:bundle && pnpm test
           - runtime: node
             task: protocol
             command: pnpm protocol:check
-          - runtime: node
-            task: format
-            command: pnpm format
           - runtime: bun
             task: test
-            command: pnpm canvas:a2ui:bundle && bunx vitest run
+            command: pnpm canvas:a2ui:bundle && bunx vitest run --config vitest.unit.config.ts
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -119,19 +282,11 @@ jobs:
           node-version: 22.x
           check-latest: true
 
-      - name: Setup pnpm (corepack retry)
-        run: |
-          set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
-              exit 0
-            fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
-            sleep $((attempt * 10))
-          done
-          exit 1
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -161,6 +316,76 @@ jobs:
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
+  # Lint and format always run, even on docs-only changes.
+  checks-lint:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: lint
+            command: pnpm lint
+          - task: format
+            command: pnpm format
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          bun -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Run ${{ matrix.task }}
+        run: ${{ matrix.command }}
+
   secrets:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
@@ -187,6 +412,8 @@ jobs:
           fi
 
   checks-windows:
+    needs: [docs-scope, changed-scope, build-artifacts]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-windows-2025
     env:
       NODE_OPTIONS: --max-old-space-size=4096
@@ -201,8 +428,8 @@ jobs:
       matrix:
         include:
           - runtime: node
-            task: build & lint
-            command: pnpm build && pnpm lint
+            task: lint
+            command: pnpm lint
           - runtime: node
             task: test
             command: pnpm canvas:a2ui:bundle && pnpm test
@@ -247,25 +474,31 @@ jobs:
           done
           exit 1
 
+      - name: Download dist artifact (lint lane)
+        if: matrix.task == 'lint'
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-build
+          path: dist/
+
+      - name: Verify dist artifact (lint lane)
+        if: matrix.task == 'lint'
+        run: |
+          set -euo pipefail
+          test -s dist/index.js
+          test -s dist/plugin-sdk/index.js
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 22.x
           check-latest: true
 
-      - name: Setup pnpm (corepack retry)
-        run: |
-          set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
-              exit 0
-            fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
-            sleep $((attempt * 10))
-          done
-          exit 1
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -300,7 +533,8 @@ jobs:
   # running 4 separate jobs per PR (as before) starved the queue. One job
   # per PR allows 5 PRs to run macOS checks simultaneously.
   macos:
-    if: github.event_name == 'pull_request'
+    needs: [docs-scope, changed-scope]
+    if: github.event_name == 'pull_request' && needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_macos == 'true'
     runs-on: macos-latest
     steps:
       - name: Checkout
@@ -328,19 +562,11 @@ jobs:
           node-version: 22.x
           check-latest: true
 
-      - name: Setup pnpm (corepack retry)
-        run: |
-          set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
-              exit 0
-            fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
-            sleep $((attempt * 10))
-          done
-          exit 1
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Runtime versions
         run: |
@@ -585,6 +811,8 @@ jobs:
           PY
 
   android:
+    needs: [docs-scope, changed-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_android == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false

.github/workflows/deployment-strategy.yml

@@ -1,349 +0,0 @@
-name: Deployment Strategy
-
-# Reusable deployment workflow for staged releases
-#
-# Deployment targets by stage:
-# - alpha: npm @alpha tag only
-# - beta: npm @beta tag + Docker (ghcr.io) beta tag
-# - stable: npm @latest + Docker latest + multi-arch manifest
-
-on:
-  workflow_call:
-    inputs:
-      deployment_stage:
-        description: "Deployment stage: alpha, beta, or stable"
-        required: true
-        type: string
-      app_version:
-        description: "Version of the application to deploy"
-        required: true
-        type: string
-      source_branch:
-        description: "Source branch for deployment"
-        required: true
-        type: string
-    outputs:
-      deployment_status:
-        description: "Status of the deployment"
-        value: ${{ jobs.deploy-summary.outputs.status }}
-      npm_url:
-        description: "npm package URL"
-        value: ${{ jobs.deploy-summary.outputs.npm_url }}
-      docker_url:
-        description: "Docker image URL"
-        value: ${{ jobs.deploy-summary.outputs.docker_url }}
-    secrets:
-      NPM_TOKEN:
-        required: false
-      DISCORD_WEBHOOK_URL:
-        required: false
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}
-
-jobs:
-  # npm publish (all stages)
-  npm-publish:
-    name: npm Publish (${{ inputs.deployment_stage }})
-    runs-on: blacksmith-4vcpu-ubuntu-2404
-    outputs:
-      status: ${{ steps.publish.outputs.status }}
-      npm_url: ${{ steps.publish.outputs.npm_url }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.source_branch }}
-          submodules: false
-
-      - name: Checkout submodules (retry)
-        run: |
-          set -euo pipefail
-          git submodule sync --recursive
-          for attempt in 1 2 3 4 5; do
-            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
-              exit 0
-            fi
-            echo "Submodule update failed (attempt $attempt/5). Retrying…"
-            sleep $((attempt * 10))
-          done
-          exit 1
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.x
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Setup pnpm (corepack retry)
-        run: |
-          set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
-              exit 0
-            fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
-            sleep $((attempt * 10))
-          done
-          exit 1
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
-
-      - name: Build
-        run: pnpm build
-
-      - name: Determine npm tag
-        id: npm-tag
-        run: |
-          case "${{ inputs.deployment_stage }}" in
-            alpha)
-              echo "tag=alpha" >> $GITHUB_OUTPUT
-              ;;
-            beta)
-              echo "tag=beta" >> $GITHUB_OUTPUT
-              ;;
-            stable)
-              echo "tag=latest" >> $GITHUB_OUTPUT
-              ;;
-          esac
-
-      - name: Publish to npm
-        id: publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: |
-          if [ -z "$NODE_AUTH_TOKEN" ]; then
-            echo "NPM_TOKEN not set, skipping publish"
-            echo "status=skipped" >> $GITHUB_OUTPUT
-            echo "npm_url=" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-
-          NPM_TAG="${{ steps.npm-tag.outputs.tag }}"
-
-          if npm publish --tag "$NPM_TAG" --access public; then
-            echo "status=success" >> $GITHUB_OUTPUT
-            echo "npm_url=https://www.npmjs.com/package/openclaw/v/${{ inputs.app_version }}" >> $GITHUB_OUTPUT
-          else
-            echo "status=failed" >> $GITHUB_OUTPUT
-            echo "npm_url=" >> $GITHUB_OUTPUT
-            exit 1
-          fi
-
-  # Docker build - amd64 (beta+ only)
-  docker-amd64:
-    name: Docker amd64 (${{ inputs.deployment_stage }})
-    if: inputs.deployment_stage != 'alpha'
-    runs-on: ubuntu-latest
-    permissions:
-      packages: write
-      contents: read
-    outputs:
-      digest: ${{ steps.build.outputs.digest }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.source_branch }}
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=raw,value=${{ inputs.app_version }}-amd64
-            type=raw,value=${{ inputs.deployment_stage }}-amd64
-
-      - name: Build and push amd64
-        id: build
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          platforms: linux/amd64
-          labels: ${{ steps.meta.outputs.labels }}
-          tags: ${{ steps.meta.outputs.tags }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          provenance: false
-          push: true
-
-  # Docker build - arm64 (beta+ only)
-  docker-arm64:
-    name: Docker arm64 (${{ inputs.deployment_stage }})
-    if: inputs.deployment_stage != 'alpha'
-    runs-on: ubuntu-24.04-arm
-    permissions:
-      packages: write
-      contents: read
-    outputs:
-      digest: ${{ steps.build.outputs.digest }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.source_branch }}
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=raw,value=${{ inputs.app_version }}-arm64
-            type=raw,value=${{ inputs.deployment_stage }}-arm64
-
-      - name: Build and push arm64
-        id: build
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          platforms: linux/arm64
-          labels: ${{ steps.meta.outputs.labels }}
-          tags: ${{ steps.meta.outputs.tags }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          provenance: false
-          push: true
-
-  # Create multi-arch manifest (beta+ only)
-  docker-manifest:
-    name: Docker Manifest (${{ inputs.deployment_stage }})
-    if: inputs.deployment_stage != 'alpha'
-    runs-on: ubuntu-latest
-    needs: [docker-amd64, docker-arm64]
-    permissions:
-      packages: write
-      contents: read
-    outputs:
-      docker_url: ${{ steps.manifest.outputs.docker_url }}
-    steps:
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create and push manifest
-        id: manifest
-        run: |
-          STAGE="${{ inputs.deployment_stage }}"
-          VERSION="${{ inputs.app_version }}"
-          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
-
-          # Create version manifest
-          docker buildx imagetools create \
-            -t "${IMAGE}:${VERSION}" \
-            "${IMAGE}:${VERSION}-amd64" \
-            "${IMAGE}:${VERSION}-arm64"
-
-          # Create stage manifest (beta or latest)
-          if [ "$STAGE" = "stable" ]; then
-            docker buildx imagetools create \
-              -t "${IMAGE}:latest" \
-              "${IMAGE}:${VERSION}-amd64" \
-              "${IMAGE}:${VERSION}-arm64"
-            echo "docker_url=${IMAGE}:latest" >> $GITHUB_OUTPUT
-          else
-            docker buildx imagetools create \
-              -t "${IMAGE}:${STAGE}" \
-              "${IMAGE}:${VERSION}-amd64" \
-              "${IMAGE}:${VERSION}-arm64"
-            echo "docker_url=${IMAGE}:${STAGE}" >> $GITHUB_OUTPUT
-          fi
-
-  # Deployment summary
-  deploy-summary:
-    name: Deployment Summary
-    runs-on: ubuntu-latest
-    needs: [npm-publish, docker-manifest]
-    if: "!cancelled()"
-    outputs:
-      status: ${{ steps.summary.outputs.status }}
-      npm_url: ${{ steps.summary.outputs.npm_url }}
-      docker_url: ${{ steps.summary.outputs.docker_url }}
-    steps:
-      - name: Summarize deployment
-        id: summary
-        run: |
-          NPM_STATUS="${{ needs.npm-publish.outputs.status || 'skipped' }}"
-          NPM_URL="${{ needs.npm-publish.outputs.npm_url }}"
-          DOCKER_URL="${{ needs.docker-manifest.outputs.docker_url || '' }}"
-
-          echo "npm_url=$NPM_URL" >> $GITHUB_OUTPUT
-          echo "docker_url=$DOCKER_URL" >> $GITHUB_OUTPUT
-
-          if [ "$NPM_STATUS" = "success" ] || [ "$NPM_STATUS" = "skipped" ]; then
-            echo "status=success" >> $GITHUB_OUTPUT
-          else
-            echo "status=failed" >> $GITHUB_OUTPUT
-          fi
-
-          # Generate summary
-          echo "## Deployment Summary" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
-          echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
-          echo "| Stage | ${{ inputs.deployment_stage }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| Version | ${{ inputs.app_version }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| npm | $NPM_STATUS |" >> $GITHUB_STEP_SUMMARY
-          echo "| Docker | ${{ needs.docker-manifest.result || 'skipped' }} |" >> $GITHUB_STEP_SUMMARY
-
-  # Discord notification
-  notify:
-    name: Discord Notification
-    needs: deploy-summary
-    if: "!cancelled()"
-    runs-on: ubuntu-latest
-    env:
-      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Discord success notification
-        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.deploy-summary.outputs.status == 'success' }}
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "🚀 Deployed: ${{ inputs.deployment_stage }} v${{ inputs.app_version }}"
-          description: |
-            **npm**: ${{ needs.deploy-summary.outputs.npm_url || 'skipped' }}
-            **Docker**: ${{ needs.deploy-summary.outputs.docker_url || 'skipped' }}
-          color: "3066993"
-
-      - name: Discord failure notification
-        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.deploy-summary.outputs.status != 'success' }}
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "❌ Deployment Failed: ${{ inputs.deployment_stage }}"
-          description: |
-            **Version**: ${{ inputs.app_version }}
-            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
-          color: "15158332"

.github/workflows/feature-pr.yml

@@ -1,97 +0,0 @@
-name: Feature PR
-
-# Auto-create PR from dev/* branches to develop
-# This is the entry point for new features into the staging pipeline
-
-# NOTE: push triggers disabled until staging pipeline is activated.
-# To enable: uncomment the push block and remove workflow_dispatch.
-#   push:
-#     branches:
-#       - "dev/**"
-#       - "feature/**"
-#       - "fix/**"
-on:
-  workflow_dispatch:
-
-concurrency:
-  group: feature-pr-${{ github.ref_name }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  create-pr:
-    name: Create PR to develop
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Ensure develop branch exists
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          if git ls-remote --heads origin develop | grep -q develop; then
-            echo "develop branch already exists"
-          else
-            echo "develop branch does not exist — creating from main"
-            git push origin origin/main:refs/heads/develop
-          fi
-
-      - name: Check for existing PR
-        id: check-pr
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          BRANCH="${{ github.ref_name }}"
-          TARGET="develop"
-
-          # Check if PR already exists
-          EXISTING=$(gh pr list --head "$BRANCH" --base "$TARGET" --json number --jq '.[0].number // empty')
-
-          if [ -n "$EXISTING" ]; then
-            echo "exists=true" >> $GITHUB_OUTPUT
-            echo "pr_number=$EXISTING" >> $GITHUB_OUTPUT
-            echo "PR #$EXISTING already exists for $BRANCH → $TARGET"
-          else
-            echo "exists=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Create PR
-        if: steps.check-pr.outputs.exists != 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          BRANCH="${{ github.ref_name }}"
-          TARGET="develop"
-
-          # Extract title from branch name (dev/foo-bar → foo bar)
-          TITLE=$(echo "$BRANCH" | sed 's|^dev/||; s|^feature/||; s|^fix/||; s|-| |g; s|_| |g')
-
-          # Capitalize first letter
-          TITLE="$(echo "${TITLE:0:1}" | tr '[:lower:]' '[:upper:]')${TITLE:1}"
-
-          # Create PR body
-          BODY=$(cat << 'PRBODY'
-          Auto-created PR from feature branch.
-
-          ## Changes
-
-          <!-- Describe your changes here -->
-
-          ---
-          *This PR was auto-created by the feature-pr workflow.*
-          PRBODY
-          )
-
-          gh pr create \
-            --base "$TARGET" \
-            --head "$BRANCH" \
-            --title "$TITLE" \
-            --body "$BODY"
-
-          echo "Created PR: $BRANCH → $TARGET"

.github/workflows/generate-changelog.yml

@@ -1,129 +0,0 @@
-name: Generate Changelog
-
-on:
-  workflow_call:
-    inputs:
-      version:
-        description: "Version for the changelog"
-        required: true
-        type: string
-      release_type:
-        description: "Release type: alpha, beta, or stable"
-        required: true
-        type: string
-    outputs:
-      changelog:
-        description: "Generated changelog content"
-        value: ${{ jobs.generate.outputs.changelog }}
-      changelog_file:
-        description: "Path to changelog file"
-        value: ${{ jobs.generate.outputs.changelog_file }}
-
-jobs:
-  generate:
-    name: Generate Changelog
-    runs-on: ubuntu-latest
-    outputs:
-      changelog: ${{ steps.generate.outputs.changelog }}
-      changelog_file: ${{ steps.generate.outputs.changelog_file }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate changelog
-        id: generate
-        run: |
-          VERSION="${{ inputs.version }}"
-          RELEASE_TYPE="${{ inputs.release_type }}"
-          DATE=$(date +%Y-%m-%d)
-
-          # Start building changelog
-          CHANGELOG="## v${VERSION} (${DATE})\n\n"
-
-          # Initialize sections
-          FEATURES=""
-          FIXES=""
-          DOCS=""
-          CHORES=""
-          OTHER=""
-
-          # Get commits since last tag
-          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-
-          if [ -n "$LATEST_TAG" ]; then
-            COMMITS=$(git log ${LATEST_TAG}..HEAD --oneline --format="%s")
-          else
-            COMMITS=$(git log --oneline --format="%s" | head -50)
-          fi
-
-          # Categorize commits by conventional commit type
-          while IFS= read -r commit; do
-            if [ -z "$commit" ]; then
-              continue
-            fi
-            
-            # Extract type from conventional commit
-            if [[ "$commit" =~ ^feat(\(.+\))?:\ (.+)$ ]]; then
-              FEATURES="${FEATURES}- ${BASH_REMATCH[2]}\n"
-            elif [[ "$commit" =~ ^fix(\(.+\))?:\ (.+)$ ]]; then
-              FIXES="${FIXES}- ${BASH_REMATCH[2]}\n"
-            elif [[ "$commit" =~ ^docs(\(.+\))?:\ (.+)$ ]]; then
-              DOCS="${DOCS}- ${BASH_REMATCH[2]}\n"
-            elif [[ "$commit" =~ ^chore(\(.+\))?:\ (.+)$ ]]; then
-              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
-            elif [[ "$commit" =~ ^refactor(\(.+\))?:\ (.+)$ ]]; then
-              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
-            elif [[ "$commit" =~ ^test(\(.+\))?:\ (.+)$ ]]; then
-              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
-            elif [[ "$commit" =~ ^ci(\(.+\))?:\ (.+)$ ]]; then
-              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
-            else
-              # Non-conventional commit, add to other
-              OTHER="${OTHER}- ${commit}\n"
-            fi
-          done <<< "$COMMITS"
-
-          # Build final changelog
-          if [ -n "$FEATURES" ]; then
-            CHANGELOG="${CHANGELOG}### ✨ Features\n\n${FEATURES}\n"
-          fi
-
-          if [ -n "$FIXES" ]; then
-            CHANGELOG="${CHANGELOG}### 🐛 Bug Fixes\n\n${FIXES}\n"
-          fi
-
-          if [ -n "$DOCS" ]; then
-            CHANGELOG="${CHANGELOG}### 📚 Documentation\n\n${DOCS}\n"
-          fi
-
-          if [ -n "$CHORES" ]; then
-            CHANGELOG="${CHANGELOG}### 🔧 Maintenance\n\n${CHORES}\n"
-          fi
-
-          if [ -n "$OTHER" ]; then
-            CHANGELOG="${CHANGELOG}### Other Changes\n\n${OTHER}\n"
-          fi
-
-          # If no categorized commits, add a simple message
-          if [ -z "$FEATURES" ] && [ -z "$FIXES" ] && [ -z "$DOCS" ] && [ -z "$CHORES" ] && [ -z "$OTHER" ]; then
-            CHANGELOG="${CHANGELOG}No notable changes in this release.\n"
-          fi
-
-          # Add release metadata
-          CHANGELOG="${CHANGELOG}\n---\n\n"
-          CHANGELOG="${CHANGELOG}**Release Type**: ${RELEASE_TYPE}\n"
-          CHANGELOG="${CHANGELOG}**Full Changelog**: https://github.com/${{ github.repository }}/compare/${LATEST_TAG:-initial}...v${VERSION}\n"
-
-          # Escape for multiline output (random delimiter prevents collision with commit messages)
-          DELIMITER="CHANGELOG_$(openssl rand -hex 16)"
-          echo "changelog<<${DELIMITER}" >> $GITHUB_OUTPUT
-          echo -e "$CHANGELOG" >> $GITHUB_OUTPUT
-          echo "${DELIMITER}" >> $GITHUB_OUTPUT
-          echo "changelog_file=CHANGELOG.md" >> $GITHUB_OUTPUT
-
-          # Also write to step summary
-          echo "## Generated Changelog" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo -e "$CHANGELOG" >> $GITHUB_STEP_SUMMARY

.github/workflows/hotfix-pr.yml

@@ -1,96 +0,0 @@
-name: Hotfix PR
-
-# Emergency hotfix workflow - bypasses staging pipeline
-# Use for critical security fixes or production-breaking bugs only
-#
-# Flow: hotfix/* → main (directly, with expedited review)
-
-# NOTE: push triggers disabled until staging pipeline is activated.
-# To enable: uncomment the push block and remove workflow_dispatch.
-#   push:
-#     branches:
-#       - "hotfix/**"
-on:
-  workflow_dispatch:
-
-concurrency:
-  group: hotfix-${{ github.ref_name }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  create-pr:
-    name: Create Hotfix PR
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Check for existing PR
-        id: check-pr
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          BRANCH="${{ github.ref_name }}"
-
-          EXISTING=$(gh pr list --head "$BRANCH" --base main --json number --jq '.[0].number // empty')
-
-          if [ -n "$EXISTING" ]; then
-            echo "exists=true" >> $GITHUB_OUTPUT
-            echo "pr_number=$EXISTING" >> $GITHUB_OUTPUT
-            echo "Hotfix PR #$EXISTING already exists"
-          else
-            echo "exists=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Create Hotfix PR
-        if: steps.check-pr.outputs.exists != 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          BRANCH="${{ github.ref_name }}"
-
-          # Extract title from branch name
-          TITLE=$(echo "$BRANCH" | sed 's|^hotfix/||; s|-| |g; s|_| |g')
-          TITLE="🚨 HOTFIX: $(echo "${TITLE:0:1}" | tr '[:lower:]' '[:upper:]')${TITLE:1}"
-
-          # Create PR body
-          BODY=$(cat << 'PRBODY'
-          ## 🚨 Emergency Hotfix
-
-          **This PR bypasses the normal staging pipeline.**
-
-          ### What's broken?
-          <!-- Describe the production issue -->
-
-          ### Root cause
-          <!-- Brief explanation of what went wrong -->
-
-          ### Fix
-          <!-- What this hotfix does -->
-
-          ### Verification
-          - [ ] Tested locally
-          - [ ] Reviewed by at least one other maintainer
-          - [ ] Post-merge monitoring plan in place
-
-          ---
-          ⚠️ **After merging:** Cherry-pick this fix to `develop`, `alpha`, and `beta` branches to keep them in sync.
-
-          *This PR was auto-created by the hotfix-pr workflow.*
-          PRBODY
-          )
-
-          gh pr create \
-            --base main \
-            --head "$BRANCH" \
-            --title "$TITLE" \
-            --label "hotfix,priority:critical" \
-            --body "$BODY"
-
-          echo "Created hotfix PR: $BRANCH → main"

.github/workflows/install-smoke.yml

@@ -11,7 +11,23 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  docs-scope:
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.check.outputs.docs_only }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect docs-only changes
+        id: check
+        uses: ./.github/actions/detect-docs-only
+
   install-smoke:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout CLI

.github/workflows/promote-branch.yml

@@ -1,321 +0,0 @@
-name: Promote Branch
-
-# Staged branch promotion for openclaw:
-#
-# develop → alpha → beta → main
-#
-# - External contributors: target `develop`
-# - develop → alpha: auto-creates PR after core checks pass
-# - alpha → beta: auto-creates PR after alpha tests pass (+ secrets scan)
-# - beta → main: auto-creates PR after full tests pass (+ Windows)
-#
-# Merging to main triggers a release (handled separately by release workflow)
-
-# NOTE: push triggers disabled until staging pipeline is activated.
-# To enable: uncomment the push block below.
-#   push:
-#     branches:
-#       - develop
-#       - alpha
-#       - beta
-#     paths-ignore:
-#       - "docs/**"
-#       - "*.md"
-on:
-  workflow_dispatch:
-    inputs:
-      source_branch:
-        description: "Source branch to promote from"
-        required: true
-        type: choice
-        options:
-          - develop
-          - alpha
-          - beta
-      skip_tests:
-        description: "Skip tests (use with caution)"
-        required: false
-        type: boolean
-        default: false
-
-concurrency:
-  group: promote-${{ github.ref_name }}
-  cancel-in-progress: false
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  # Determine promotion target
-  determine-target:
-    name: Determine Target Branch
-    runs-on: ubuntu-latest
-    outputs:
-      source: ${{ steps.determine.outputs.source }}
-      target: ${{ steps.determine.outputs.target }}
-      test_stage: ${{ steps.determine.outputs.test_stage }}
-      should_promote: ${{ steps.determine.outputs.should_promote }}
-    steps:
-      - name: Determine promotion target
-        id: determine
-        run: |
-          # Get source branch
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            SOURCE="${{ inputs.source_branch }}"
-          else
-            SOURCE="${{ github.ref_name }}"
-          fi
-
-          echo "source=$SOURCE" >> $GITHUB_OUTPUT
-
-          case "$SOURCE" in
-            develop)
-              echo "target=alpha" >> $GITHUB_OUTPUT
-              echo "test_stage=develop" >> $GITHUB_OUTPUT
-              echo "should_promote=true" >> $GITHUB_OUTPUT
-              ;;
-            alpha)
-              echo "target=beta" >> $GITHUB_OUTPUT
-              echo "test_stage=alpha" >> $GITHUB_OUTPUT
-              echo "should_promote=true" >> $GITHUB_OUTPUT
-              ;;
-            beta)
-              echo "target=main" >> $GITHUB_OUTPUT
-              echo "test_stage=beta" >> $GITHUB_OUTPUT
-              echo "should_promote=true" >> $GITHUB_OUTPUT
-              ;;
-            *)
-              echo "target=" >> $GITHUB_OUTPUT
-              echo "test_stage=" >> $GITHUB_OUTPUT
-              echo "should_promote=false" >> $GITHUB_OUTPUT
-              ;;
-          esac
-
-  # Ensure target branch exists (create from main if not)
-  ensure-target-branch:
-    name: Ensure Target Branch
-    needs: determine-target
-    if: needs.determine-target.outputs.should_promote == 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Create target branch if missing
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          TARGET="${{ needs.determine-target.outputs.target }}"
-
-          if git ls-remote --exit-code origin "refs/heads/$TARGET" >/dev/null 2>&1; then
-            echo "Branch '$TARGET' already exists"
-          else
-            echo "Branch '$TARGET' does not exist — creating from main"
-            git push origin "origin/main:refs/heads/$TARGET"
-          fi
-
-  # Run stage-appropriate tests
-  run-tests:
-    name: Run Tests
-    needs: [determine-target, ensure-target-branch]
-    if: ${{ needs.determine-target.outputs.should_promote == 'true' && (github.event_name != 'workflow_dispatch' || !inputs.skip_tests) }}
-    uses: ./.github/workflows/testing-strategy.yml
-    with:
-      test_stage: ${{ needs.determine-target.outputs.test_stage }}
-      app_version: ${{ github.sha }}
-    secrets: inherit
-
-  # Create promotion PR
-  create-promotion-pr:
-    name: Create Promotion PR
-    needs: [determine-target, ensure-target-branch, run-tests]
-    if: |
-      !cancelled() &&
-      needs.determine-target.outputs.should_promote == 'true' &&
-      (needs.run-tests.outputs.test_status == 'passed' || (github.event_name == 'workflow_dispatch' && inputs.skip_tests))
-    runs-on: ubuntu-latest
-    outputs:
-      pr_number: ${{ steps.output-pr.outputs.pull-request-number }}
-      pr_url: ${{ steps.output-pr.outputs.pull-request-url }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ needs.determine-target.outputs.source }}
-          fetch-depth: 0
-
-      - name: Get commit info
-        id: commits
-        run: |
-          TARGET="${{ needs.determine-target.outputs.target }}"
-
-          # Fetch target branch
-          git fetch origin $TARGET 2>/dev/null || true
-
-          # Get commits not in target
-          if git rev-parse origin/$TARGET >/dev/null 2>&1; then
-            COMMIT_COUNT=$(git rev-list --count origin/$TARGET..HEAD 2>/dev/null || echo "0")
-            COMMIT_SUMMARY=$(git log origin/$TARGET..HEAD --oneline --format="- %s (%h)" 2>/dev/null | head -20 || echo "Initial promotion")
-          else
-            COMMIT_COUNT=$(git rev-list --count HEAD 2>/dev/null || echo "0")
-            COMMIT_SUMMARY=$(git log --oneline --format="- %s (%h)" 2>/dev/null | head -20 || echo "Initial promotion")
-          fi
-
-          echo "count=$COMMIT_COUNT" >> $GITHUB_OUTPUT
-          DELIM="COMMITS_$(openssl rand -hex 16)"
-          echo "summary<<${DELIM}" >> $GITHUB_OUTPUT
-          echo "$COMMIT_SUMMARY" >> $GITHUB_OUTPUT
-          echo "${DELIM}" >> $GITHUB_OUTPUT
-
-      - name: Check for existing PR
-        id: check-pr
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          SOURCE="${{ needs.determine-target.outputs.source }}"
-          TARGET="${{ needs.determine-target.outputs.target }}"
-
-          EXISTING=$(gh pr list --head "$SOURCE" --base "$TARGET" --json number --jq '.[0].number // empty')
-
-          if [ -n "$EXISTING" ]; then
-            echo "exists=true" >> $GITHUB_OUTPUT
-            echo "pr_number=$EXISTING" >> $GITHUB_OUTPUT
-            echo "pr_url=https://github.com/${{ github.repository }}/pull/$EXISTING" >> $GITHUB_OUTPUT
-            echo "Promotion PR #$EXISTING already exists for $SOURCE → $TARGET"
-          else
-            echo "exists=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Create Pull Request
-        id: create-pr
-        if: steps.check-pr.outputs.exists != 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          SOURCE="${{ needs.determine-target.outputs.source }}"
-          TARGET="${{ needs.determine-target.outputs.target }}"
-          TEST_STAGE="${{ needs.determine-target.outputs.test_stage }}"
-          COMMIT_COUNT="${{ steps.commits.outputs.count }}"
-
-          # Write PR body to a temp file to avoid shell quoting issues
-          BODY_FILE=$(mktemp)
-          cat > "$BODY_FILE" <<__PRBODY__
-          ## Staged Promotion
-
-          | Property | Value |
-          |----------|-------|
-          | Source | \`${SOURCE}\` |
-          | Target | \`${TARGET}\` |
-          | Test Stage | \`${TEST_STAGE}\` |
-
-          ### Changes (${COMMIT_COUNT} commits)
-
-          ${{ steps.commits.outputs.summary }}
-
-          ### Checklist
-
-          - [ ] Changes reviewed
-          - [ ] CI passing
-          - [ ] Ready to promote
-
-          ---
-          *Auto-generated by the branch promotion workflow.*
-          __PRBODY__
-
-          PR_URL=$(gh pr create \
-            --base "$TARGET" \
-            --head "$SOURCE" \
-            --title "🚀 Promote: $SOURCE → $TARGET" \
-            --body-file "$BODY_FILE" \
-            --label "promotion")
-
-          rm -f "$BODY_FILE"
-
-          PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$')
-
-          echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT
-          echo "pr_url=$PR_URL" >> $GITHUB_OUTPUT
-          echo "Created promotion PR: $SOURCE → $TARGET"
-
-      - name: Output existing PR
-        id: output-pr
-        run: |
-          if [ "${{ steps.check-pr.outputs.exists }}" = "true" ]; then
-            echo "pull-request-number=${{ steps.check-pr.outputs.pr_number }}" >> $GITHUB_OUTPUT
-            echo "pull-request-url=${{ steps.check-pr.outputs.pr_url }}" >> $GITHUB_OUTPUT
-          else
-            echo "pull-request-number=${{ steps.create-pr.outputs.pr_number }}" >> $GITHUB_OUTPUT
-            echo "pull-request-url=${{ steps.create-pr.outputs.pr_url }}" >> $GITHUB_OUTPUT
-          fi
-
-  # Auto-merge for develop → alpha (fast-track, new PRs only)
-  auto-merge:
-    name: Auto-merge (develop → alpha)
-    needs: [determine-target, create-promotion-pr]
-    if: |
-      needs.determine-target.outputs.source == 'develop' &&
-      needs.create-promotion-pr.outputs.pr_number != '' &&
-      needs.create-promotion-pr.result == 'success'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Enable auto-merge
-        run: |
-          gh pr merge ${{ needs.create-promotion-pr.outputs.pr_number }} \
-            --auto \
-            --squash \
-            --repo ${{ github.repository }}
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  # Notify about promotion
-  notify-promotion:
-    name: Notify Promotion
-    needs: [determine-target, create-promotion-pr]
-    if: "!cancelled() && needs.create-promotion-pr.outputs.pr_url != ''"
-    runs-on: ubuntu-latest
-    env:
-      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Discord notification
-        if: env.DISCORD_WEBHOOK_URL != ''
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "🔄 Promotion PR: ${{ needs.determine-target.outputs.source }} → ${{ needs.determine-target.outputs.target }}"
-          description: |
-            **PR**: ${{ needs.create-promotion-pr.outputs.pr_url }}
-            **Stage**: ${{ needs.determine-target.outputs.test_stage }}
-          color: "3447003"
-
-  # Handle failed tests
-  notify-failure:
-    name: Notify Test Failure
-    needs: [determine-target, run-tests]
-    if: |
-      !cancelled() &&
-      needs.run-tests.outputs.test_status != 'passed' &&
-      !inputs.skip_tests
-    runs-on: ubuntu-latest
-    env:
-      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Discord notification
-        if: env.DISCORD_WEBHOOK_URL != ''
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "❌ Promotion Blocked: ${{ needs.determine-target.outputs.source }}"
-          description: |
-            **Target**: ${{ needs.determine-target.outputs.target }}
-            **Reason**: Tests failed
-            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
-          color: "15158332"

.github/workflows/release-orchestrator.yml

@@ -1,265 +0,0 @@
-name: Release Orchestrator
-
-# Orchestrates staged releases for openclaw
-#
-# This workflow is called when code is promoted to main (stable release)
-# or can be triggered manually for alpha/beta releases from their branches.
-#
-# Flow: version → changelog → test → deploy → release
-
-# NOTE: push-to-main trigger disabled until staging pipeline is activated.
-# To enable: uncomment the push block below.
-#   push:
-#     branches:
-#       - main
-#     paths-ignore:
-#       - "docs/**"
-#       - "*.md"
-#       - ".github/workflows/docs-*.yml"
-on:
-  workflow_call:
-    inputs:
-      release_type:
-        description: "Release type: alpha, beta, or stable"
-        required: true
-        type: string
-      source_branch:
-        description: "Source branch for the release"
-        required: true
-        type: string
-      dry_run:
-        description: "Perform a dry run without publishing"
-        required: false
-        type: boolean
-        default: false
-    outputs:
-      version:
-        description: "The released version"
-        value: ${{ jobs.version.outputs.new_version }}
-      release_url:
-        description: "URL to the GitHub release"
-        value: ${{ jobs.release.outputs.release_url }}
-      status:
-        description: "Release status"
-        value: ${{ jobs.release.outputs.status }}
-    secrets:
-      NPM_TOKEN:
-        required: false
-      DISCORD_WEBHOOK_URL:
-        required: false
-
-concurrency:
-  group: release-${{ github.ref_name }}
-  cancel-in-progress: false
-
-permissions:
-  contents: write
-  packages: write
-
-jobs:
-  # Determine release parameters (push vs workflow_call)
-  determine-params:
-    name: Determine Parameters
-    runs-on: ubuntu-latest
-    outputs:
-      release_type: ${{ steps.params.outputs.release_type }}
-      source_branch: ${{ steps.params.outputs.source_branch }}
-      dry_run: ${{ steps.params.outputs.dry_run }}
-    steps:
-      - name: Set parameters
-        id: params
-        run: |
-          # When triggered by push to main, use stable defaults
-          if [ "${{ github.event_name }}" = "push" ]; then
-            echo "release_type=stable" >> $GITHUB_OUTPUT
-            echo "source_branch=main" >> $GITHUB_OUTPUT
-            echo "dry_run=false" >> $GITHUB_OUTPUT
-          else
-            # workflow_call - use provided inputs
-            echo "release_type=${{ inputs.release_type }}" >> $GITHUB_OUTPUT
-            echo "source_branch=${{ inputs.source_branch }}" >> $GITHUB_OUTPUT
-            echo "dry_run=${{ inputs.dry_run }}" >> $GITHUB_OUTPUT
-          fi
-
-  # Get commits since last release
-  get-commits:
-    name: Get Commits
-    needs: determine-params
-    runs-on: ubuntu-latest
-    outputs:
-      commits: ${{ steps.commits.outputs.commits }}
-      has_changes: ${{ steps.commits.outputs.has_changes }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          ref: ${{ needs.determine-params.outputs.source_branch }}
-
-      - name: Get commits since last tag
-        id: commits
-        run: |
-          # Get latest tag for this release type
-          case "${{ needs.determine-params.outputs.release_type }}" in
-            alpha)
-              PATTERN="v*-alpha.*"
-              ;;
-            beta)
-              PATTERN="v*-beta.*"
-              ;;
-            stable)
-              PATTERN="v[0-9]*.[0-9]*.[0-9]*"
-              ;;
-          esac
-
-          # Filter out prerelease tags for stable (glob * matches -alpha/-beta suffixes)
-          if [ "${{ needs.determine-params.outputs.release_type }}" = "stable" ]; then
-            LATEST_TAG=$(git tag -l "$PATTERN" --sort=-v:refname | grep -v -E '-(alpha|beta)\.' | head -1)
-          else
-            LATEST_TAG=$(git tag -l "$PATTERN" --sort=-v:refname | head -1)
-          fi
-
-          if [ -z "$LATEST_TAG" ]; then
-            # No previous tag, use all commits
-            LATEST_TAG=$(git rev-list --max-parents=0 HEAD)
-            echo "No previous ${{ needs.determine-params.outputs.release_type }} tag found, using initial commit"
-          else
-            echo "Latest ${{ needs.determine-params.outputs.release_type }} tag: $LATEST_TAG"
-          fi
-
-          COMMITS=$(git log ${LATEST_TAG}..HEAD --oneline --format="- %s (%h)")
-
-          if [ -z "$COMMITS" ]; then
-            echo "has_changes=false" >> $GITHUB_OUTPUT
-            echo "commits=" >> $GITHUB_OUTPUT
-          else
-            echo "has_changes=true" >> $GITHUB_OUTPUT
-            DELIM="COMMITS_$(openssl rand -hex 16)"
-            echo "commits<<${DELIM}" >> $GITHUB_OUTPUT
-            echo "$COMMITS" >> $GITHUB_OUTPUT
-            echo "${DELIM}" >> $GITHUB_OUTPUT
-          fi
-
-  # Version operations
-  version:
-    name: Version
-    needs: [determine-params, get-commits]
-    if: needs.get-commits.outputs.has_changes == 'true'
-    uses: ./.github/workflows/version-operations.yml
-    with:
-      release_type: ${{ needs.determine-params.outputs.release_type }}
-      source_branch: ${{ needs.determine-params.outputs.source_branch }}
-      should_bump: true
-      dry_run: ${{ needs.determine-params.outputs.dry_run }}
-
-  # Generate changelog
-  changelog:
-    name: Changelog
-    needs: [determine-params, get-commits, version]
-    if: needs.get-commits.outputs.has_changes == 'true'
-    uses: ./.github/workflows/generate-changelog.yml
-    with:
-      version: ${{ needs.version.outputs.new_version }}
-      release_type: ${{ needs.determine-params.outputs.release_type }}
-
-  # Run full test suite for the release type
-  test:
-    name: Test
-    needs: [determine-params, get-commits, version]
-    if: needs.get-commits.outputs.has_changes == 'true'
-    uses: ./.github/workflows/testing-strategy.yml
-    with:
-      test_stage: ${{ needs.determine-params.outputs.release_type }}
-      app_version: ${{ needs.version.outputs.new_version }}
-    secrets: inherit
-
-  # Deploy (npm + Docker)
-  deploy:
-    name: Deploy
-    needs: [determine-params, version, test]
-    if: ${{ needs.determine-params.outputs.dry_run != 'true' && needs.test.outputs.test_status == 'passed' }}
-    uses: ./.github/workflows/deployment-strategy.yml
-    with:
-      deployment_stage: ${{ needs.determine-params.outputs.release_type }}
-      app_version: ${{ needs.version.outputs.new_version }}
-      source_branch: ${{ needs.determine-params.outputs.source_branch }}
-    secrets: inherit
-
-  # Create GitHub release
-  release:
-    name: GitHub Release
-    needs: [determine-params, version, changelog, deploy]
-    if: ${{ needs.determine-params.outputs.dry_run != 'true' }}
-    runs-on: ubuntu-latest
-    outputs:
-      release_url: ${{ steps.create-release.outputs.html_url }}
-      status: ${{ steps.status.outputs.status }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ needs.determine-params.outputs.source_branch }}
-
-      - name: Create GitHub Release
-        id: create-release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ needs.version.outputs.new_version }}
-          name: openclaw ${{ needs.version.outputs.new_version }}
-          body: ${{ needs.changelog.outputs.changelog }}
-          prerelease: ${{ needs.determine-params.outputs.release_type != 'stable' }}
-          draft: false
-
-      - name: Set status
-        id: status
-        run: echo "status=success" >> $GITHUB_OUTPUT
-
-  # Notify on success
-  notify-success:
-    name: Notify Success
-    needs: [determine-params, version, release]
-    if: ${{ !cancelled() && needs.release.result == 'success' }}
-    runs-on: ubuntu-latest
-    env:
-      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Discord notification
-        if: env.DISCORD_WEBHOOK_URL != ''
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "🎉 Released: openclaw v${{ needs.version.outputs.new_version }}"
-          description: |
-            **Type**: ${{ needs.determine-params.outputs.release_type }}
-            **Release**: ${{ needs.release.outputs.release_url }}
-          color: "3066993"
-
-  # Notify on failure
-  notify-failure:
-    name: Notify Failure
-    needs: [determine-params, version, test, deploy, release]
-    if: |
-      !cancelled() &&
-      needs.version.result != 'skipped' &&
-      (needs.test.result == 'failure' || needs.deploy.result == 'failure' || needs.release.result == 'failure')
-    runs-on: ubuntu-latest
-    env:
-      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Discord notification
-        if: env.DISCORD_WEBHOOK_URL != ''
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "❌ Release Failed: ${{ needs.determine-params.outputs.release_type }}"
-          description: |
-            **Branch**: ${{ needs.determine-params.outputs.source_branch }}
-            **Tests**: ${{ needs.test.outputs.test_status }}
-            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
-          color: "15158332"

.github/workflows/release.yml

@@ -1,51 +0,0 @@
-name: Release
-
-# Manual release workflow - triggers the release orchestrator
-#
-# Branch → Release Type mapping:
-#   alpha  → releases from 'alpha' branch with -alpha.N suffix
-#   beta   → releases from 'beta' branch with -beta.N suffix
-#   stable → releases from 'main' branch with YYYY.M.D version
-
-on:
-  workflow_dispatch:
-    inputs:
-      release_type:
-        description: "Release type"
-        required: true
-        type: choice
-        options:
-          - alpha
-          - beta
-          - stable
-        default: "alpha"
-      dry_run:
-        description: "Dry run (no publish)"
-        required: false
-        type: boolean
-        default: false
-
-jobs:
-  determine-branch:
-    runs-on: ubuntu-latest
-    outputs:
-      branch: ${{ steps.branch.outputs.name }}
-    steps:
-      - name: Determine source branch
-        id: branch
-        run: |
-          case "${{ inputs.release_type }}" in
-            alpha)  echo "name=alpha" >> $GITHUB_OUTPUT ;;
-            beta)   echo "name=beta" >> $GITHUB_OUTPUT ;;
-            stable) echo "name=main" >> $GITHUB_OUTPUT ;;
-          esac
-
-  release:
-    name: Release
-    needs: determine-branch
-    uses: ./.github/workflows/release-orchestrator.yml
-    with:
-      release_type: ${{ inputs.release_type }}
-      source_branch: ${{ needs.determine-branch.outputs.branch }}
-      dry_run: ${{ inputs.dry_run }}
-    secrets: inherit

.github/workflows/rollback.yml

@@ -1,256 +0,0 @@
-name: Rollback
-
-# Emergency rollback workflow
-#
-# Reverts npm + Docker to a previous known-good version.
-# Does NOT revert git — the bad commits stay in history.
-# Create a hotfix branch to fix forward after rolling back.
-#
-# What it does:
-#   1. Re-tags the previous version as @latest / :latest on npm + Docker
-#   2. Creates a GitHub release noting the rollback
-#   3. Notifies Discord
-#
-# What it does NOT do:
-#   - Revert git commits (fix forward instead)
-#   - Remove the bad version from npm (use `npm unpublish` manually if needed)
-
-on:
-  workflow_dispatch:
-    inputs:
-      rollback_to:
-        description: "Version to roll back to (e.g. 2026.2.5)"
-        required: true
-        type: string
-      reason:
-        description: "Reason for rollback"
-        required: true
-        type: string
-      rollback_npm:
-        description: "Roll back npm dist-tag"
-        required: false
-        type: boolean
-        default: true
-      rollback_docker:
-        description: "Roll back Docker :latest tag"
-        required: false
-        type: boolean
-        default: true
-
-concurrency:
-  group: rollback
-  cancel-in-progress: false
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}
-
-jobs:
-  # Validate the target version exists
-  validate:
-    name: Validate Target Version
-    runs-on: ubuntu-latest
-    outputs:
-      tag_exists: ${{ steps.check.outputs.tag_exists }}
-      npm_exists: ${{ steps.check.outputs.npm_exists }}
-      docker_exists: ${{ steps.check.outputs.docker_exists }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Validate version
-        id: check
-        run: |
-          VERSION="${{ inputs.rollback_to }}"
-
-          # Check git tag
-          if git tag -l "v${VERSION}" | grep -q .; then
-            echo "tag_exists=true" >> $GITHUB_OUTPUT
-            echo "✅ Git tag v${VERSION} exists"
-          else
-            echo "tag_exists=false" >> $GITHUB_OUTPUT
-            echo "❌ Git tag v${VERSION} not found"
-          fi
-
-          # Check npm
-          if npm view "openclaw@${VERSION}" version 2>/dev/null | grep -q "${VERSION}"; then
-            echo "npm_exists=true" >> $GITHUB_OUTPUT
-            echo "✅ npm version ${VERSION} exists"
-          else
-            echo "npm_exists=false" >> $GITHUB_OUTPUT
-            echo "⚠️ npm version ${VERSION} not found (npm rollback will be skipped)"
-          fi
-
-          # Check Docker
-          if docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${VERSION}" >/dev/null 2>&1; then
-            echo "docker_exists=true" >> $GITHUB_OUTPUT
-            echo "✅ Docker image ${VERSION} exists"
-          else
-            echo "docker_exists=false" >> $GITHUB_OUTPUT
-            echo "⚠️ Docker image ${VERSION} not found (Docker rollback will be skipped)"
-          fi
-
-      - name: Fail if tag doesn't exist
-        if: steps.check.outputs.tag_exists != 'true'
-        run: |
-          echo "::error::Version v${{ inputs.rollback_to }} does not exist as a git tag"
-          exit 1
-
-  # Roll back npm dist-tag
-  rollback-npm:
-    name: Rollback npm
-    needs: validate
-    if: ${{ inputs.rollback_npm && needs.validate.outputs.npm_exists == 'true' }}
-    runs-on: ubuntu-latest
-    outputs:
-      status: ${{ steps.rollback.outputs.status }}
-    steps:
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.x
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Roll back npm @latest tag
-        id: rollback
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: |
-          VERSION="${{ inputs.rollback_to }}"
-
-          if [ -z "$NODE_AUTH_TOKEN" ]; then
-            echo "::warning::NPM_TOKEN not set, skipping npm rollback"
-            echo "status=skipped" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-
-          # Move the @latest dist-tag to the rollback version
-          if npm dist-tag add "openclaw@${VERSION}" latest; then
-            echo "status=success" >> $GITHUB_OUTPUT
-            echo "✅ npm @latest now points to ${VERSION}"
-
-            # Show current dist-tags for verification
-            npm dist-tag ls openclaw
-          else
-            echo "status=failed" >> $GITHUB_OUTPUT
-            echo "::error::Failed to update npm dist-tag"
-            exit 1
-          fi
-
-  # Roll back Docker :latest tag
-  rollback-docker:
-    name: Rollback Docker
-    needs: validate
-    if: ${{ inputs.rollback_docker && needs.validate.outputs.docker_exists == 'true' }}
-    runs-on: ubuntu-latest
-    permissions:
-      packages: write
-      contents: read
-    outputs:
-      status: ${{ steps.rollback.outputs.status }}
-    steps:
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Roll back Docker :latest tag
-        id: rollback
-        run: |
-          VERSION="${{ inputs.rollback_to }}"
-          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
-
-          # Re-tag the rollback version as :latest
-          if docker buildx imagetools create -t "${IMAGE}:latest" "${IMAGE}:${VERSION}"; then
-            echo "status=success" >> $GITHUB_OUTPUT
-            echo "✅ Docker :latest now points to ${VERSION}"
-          else
-            echo "status=failed" >> $GITHUB_OUTPUT
-            echo "::error::Failed to retag Docker image"
-            exit 1
-          fi
-
-  # Create rollback release note
-  create-rollback-release:
-    name: Create Rollback Release
-    needs: [validate, rollback-npm, rollback-docker]
-    if: "!cancelled() && needs.validate.result == 'success'"
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Get current version
-        id: current
-        run: |
-          CURRENT=$(node -p "require('./package.json').version")
-          echo "version=$CURRENT" >> $GITHUB_OUTPUT
-
-      - name: Create rollback release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ inputs.rollback_to }}
-          name: "⚠️ Rollback to openclaw ${{ inputs.rollback_to }}"
-          body: |
-            ## ⚠️ Rollback
-
-            | Property | Value |
-            |----------|-------|
-            | Rolled back from | `${{ steps.current.outputs.version }}` |
-            | Rolled back to | `${{ inputs.rollback_to }}` |
-            | Initiated by | @${{ github.actor }} |
-
-            ### Reason
-
-            ${{ inputs.reason }}
-
-            ### Rollback Status
-
-            | Target | Status |
-            |--------|--------|
-            | npm @latest | ${{ needs.rollback-npm.outputs.status || 'skipped' }} |
-            | Docker :latest | ${{ needs.rollback-docker.outputs.status || 'skipped' }} |
-
-            ### Next Steps
-
-            1. Investigate the issue in the rolled-back version
-            2. Create a `hotfix/*` branch with the fix
-            3. Merge via the hotfix workflow to restore forward progress
-
-            ---
-            *This release was created by the rollback workflow.*
-          make_latest: false
-          prerelease: false
-
-  # Notify
-  notify:
-    name: Discord Notification
-    needs: [validate, rollback-npm, rollback-docker, create-rollback-release]
-    if: "!cancelled() && needs.validate.result == 'success'"
-    runs-on: ubuntu-latest
-    env:
-      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Discord notification
-        if: env.DISCORD_WEBHOOK_URL != ''
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "⚠️ ROLLBACK: openclaw → v${{ inputs.rollback_to }}"
-          description: |
-            **Reason**: ${{ inputs.reason }}
-            **Initiated by**: @${{ github.actor }}
-            **npm**: ${{ needs.rollback-npm.outputs.status || 'skipped' }}
-            **Docker**: ${{ needs.rollback-docker.outputs.status || 'skipped' }}
-          color: "15105570"

.github/workflows/testing-strategy.yml

@@ -1,153 +0,0 @@
-name: Testing Strategy
-
-# Reusable testing workflow for staged releases
-# Passes test_stage to ci.yml to control which platform tests run
-#
-# Progressive test coverage by stage:
-# - develop/alpha: core checks + secrets + android
-# - beta: + Windows tests
-# - stable: + macOS tests, macOS app, install smoke
-
-on:
-  workflow_call:
-    inputs:
-      test_stage:
-        description: "Testing stage: develop, alpha, beta, or stable"
-        required: true
-        type: string
-      app_version:
-        description: "Version of the application being tested"
-        required: false
-        type: string
-        default: "dev"
-    outputs:
-      test_status:
-        description: "Overall test status"
-        value: ${{ jobs.test-summary.outputs.overall_status }}
-    secrets:
-      DISCORD_WEBHOOK_URL:
-        required: false
-
-jobs:
-  # Run CI with stage-appropriate platform gates
-  ci:
-    name: Core CI
-    uses: ./.github/workflows/ci.yml
-    with:
-      test_stage: ${{ inputs.test_stage }}
-    secrets: inherit
-
-  # Install smoke test (stable only)
-  install-smoke:
-    name: Install Smoke Test
-    if: inputs.test_stage == 'stable'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup pnpm (corepack retry)
-        run: |
-          set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
-              exit 0
-            fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
-            sleep $((attempt * 10))
-          done
-          exit 1
-
-      - name: Install pnpm deps (minimal)
-        run: pnpm install --ignore-scripts --frozen-lockfile
-
-      - name: Run installer smoke tests
-        env:
-          CLAWDBOT_INSTALL_URL: https://openclaw.ai/install.sh
-          CLAWDBOT_INSTALL_CLI_URL: https://openclaw.ai/install-cli.sh
-          CLAWDBOT_NO_ONBOARD: "1"
-          CLAWDBOT_INSTALL_SMOKE_SKIP_CLI: "1"
-          CLAWDBOT_INSTALL_SMOKE_SKIP_NONROOT: "1"
-          CLAWDBOT_INSTALL_SMOKE_SKIP_PREVIOUS: "1"
-        run: pnpm test:install:smoke
-
-  # Test summary
-  test-summary:
-    name: Test Summary (${{ inputs.test_stage }})
-    runs-on: ubuntu-latest
-    needs: [ci, install-smoke]
-    if: "!cancelled()"
-    outputs:
-      overall_status: ${{ steps.summary.outputs.overall_status }}
-    steps:
-      - name: Generate summary
-        id: summary
-        run: |
-          echo "## 🧪 Test Results - ${{ inputs.test_stage }}" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "| Test Suite | Result |" >> $GITHUB_STEP_SUMMARY
-          echo "|------------|--------|" >> $GITHUB_STEP_SUMMARY
-          echo "| CI (checks + secrets) | ${{ needs.ci.result }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| Install Smoke | ${{ needs.install-smoke.result || 'skipped' }} |" >> $GITHUB_STEP_SUMMARY
-
-          # CI must pass (includes platform-specific jobs based on test_stage)
-          if [ "${{ needs.ci.result }}" != "success" ]; then
-            echo "overall_status=failed" >> $GITHUB_OUTPUT
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "### ❌ CI failed" >> $GITHUB_STEP_SUMMARY
-            exit 0
-          fi
-
-          # Stage-specific checks
-          STAGE="${{ inputs.test_stage }}"
-          FAILED=false
-
-          if [ "$STAGE" = "stable" ]; then
-            if [ "${{ needs.install-smoke.result }}" = "failure" ]; then
-              FAILED=true
-            fi
-          fi
-
-          if [ "$FAILED" = "true" ]; then
-            echo "overall_status=failed" >> $GITHUB_OUTPUT
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "### ❌ Some stage-specific tests failed" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "overall_status=passed" >> $GITHUB_OUTPUT
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "### ✅ All required tests passed!" >> $GITHUB_STEP_SUMMARY
-          fi
-
-  # Discord notifications
-  notify:
-    name: Discord Notification
-    needs: test-summary
-    if: "!cancelled()"
-    runs-on: ubuntu-latest
-    env:
-      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Discord success notification
-        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.test-summary.outputs.overall_status == 'passed' }}
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "✅ Tests Passed: ${{ inputs.test_stage }} v${{ inputs.app_version }}"
-          description: "All tests passed for ${{ inputs.test_stage }} stage!"
-          color: "3066993"
-
-      - name: Discord failure notification
-        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.test-summary.outputs.overall_status != 'passed' }}
-        uses: ./.github/actions/discord-notify
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
-          title: "❌ Tests Failed: ${{ inputs.test_stage }} v${{ inputs.app_version }}"
-          description: |
-            Some tests failed for ${{ inputs.test_stage }} stage.
-            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
-          color: "15158332"

.github/workflows/version-operations.yml

@@ -1,188 +0,0 @@
-name: Version Operations
-
-# Version bump workflow for openclaw
-#
-# Version format: YYYY.M.D (stable) or YYYY.M.D-{alpha,beta}.N (prerelease)
-# Examples: 2026.2.6, 2026.2.6-alpha.1, 2026.2.6-beta.3
-
-on:
-  workflow_call:
-    inputs:
-      release_type:
-        description: "Release type: alpha, beta, or stable"
-        required: true
-        type: string
-      source_branch:
-        description: "Source branch"
-        required: true
-        type: string
-      should_bump:
-        description: "Whether to bump the version"
-        required: false
-        type: boolean
-        default: true
-      dry_run:
-        description: "Perform a dry run without committing"
-        required: false
-        type: boolean
-        default: false
-    outputs:
-      current_version:
-        description: "Current version before bump"
-        value: ${{ jobs.version.outputs.current_version }}
-      new_version:
-        description: "New version after bump"
-        value: ${{ jobs.version.outputs.new_version }}
-      version_tag:
-        description: "Version tag (with v prefix)"
-        value: ${{ jobs.version.outputs.version_tag }}
-
-permissions:
-  contents: write
-
-jobs:
-  version:
-    name: Version Operations
-    runs-on: ubuntu-latest
-    outputs:
-      current_version: ${{ steps.get-version.outputs.current }}
-      new_version: ${{ steps.bump-version.outputs.new }}
-      version_tag: ${{ steps.bump-version.outputs.tag }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.source_branch }}
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.x
-
-      - name: Get current version
-        id: get-version
-        run: |
-          CURRENT_VERSION=$(node -p "require('./package.json').version")
-          echo "current=$CURRENT_VERSION" >> $GITHUB_OUTPUT
-          echo "Current version: $CURRENT_VERSION"
-
-      - name: Calculate new version
-        id: bump-version
-        run: |
-          CURRENT="${{ steps.get-version.outputs.current }}"
-          RELEASE_TYPE="${{ inputs.release_type }}"
-
-          # Get current date components
-          YEAR=$(date +%Y)
-          MONTH=$(date +%-m)
-          DAY=$(date +%-d)
-          TODAY="${YEAR}.${MONTH}.${DAY}"
-
-          # Parse current version to check if it's today + same type
-          # Patterns: YYYY.M.D or YYYY.M.D-type.N
-          if [[ "$CURRENT" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(-([a-z]+)\.([0-9]+))?$ ]]; then
-            CURR_DATE="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.${BASH_REMATCH[3]}"
-            CURR_TYPE="${BASH_REMATCH[5]}"
-            CURR_NUM="${BASH_REMATCH[6]:-0}"
-          else
-            CURR_DATE=""
-            CURR_TYPE=""
-            CURR_NUM=0
-          fi
-
-          case "$RELEASE_TYPE" in
-            alpha)
-              if [ "$CURR_DATE" = "$TODAY" ] && [ "$CURR_TYPE" = "alpha" ]; then
-                # Same day, same type - increment prerelease number
-                NEW_NUM=$((CURR_NUM + 1))
-              else
-                # New day or different type - start at 1
-                NEW_NUM=1
-              fi
-              NEW_VERSION="${TODAY}-alpha.${NEW_NUM}"
-              ;;
-            beta)
-              if [ "$CURR_DATE" = "$TODAY" ] && [ "$CURR_TYPE" = "beta" ]; then
-                NEW_NUM=$((CURR_NUM + 1))
-              else
-                NEW_NUM=1
-              fi
-              NEW_VERSION="${TODAY}-beta.${NEW_NUM}"
-              ;;
-            stable)
-              # Stable releases use date; append counter if tag already exists
-              if git tag -l "v${TODAY}" | grep -q .; then
-                # Tag exists, find next available counter
-                COUNTER=1
-                while git tag -l "v${TODAY}.${COUNTER}" | grep -q .; do
-                  COUNTER=$((COUNTER + 1))
-                done
-                NEW_VERSION="${TODAY}.${COUNTER}"
-              else
-                NEW_VERSION="${TODAY}"
-              fi
-              ;;
-            *)
-              echo "Unknown release type: $RELEASE_TYPE"
-              exit 1
-              ;;
-          esac
-
-          echo "new=$NEW_VERSION" >> $GITHUB_OUTPUT
-          echo "tag=v$NEW_VERSION" >> $GITHUB_OUTPUT
-          echo "New version: $NEW_VERSION"
-
-      - name: Update package.json
-        if: ${{ inputs.should_bump && !inputs.dry_run }}
-        run: |
-          NEW_VERSION="${{ steps.bump-version.outputs.new }}"
-
-          # Update package.json version
-          node -e "
-            const fs = require('fs');
-            const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-            pkg.version = '$NEW_VERSION';
-            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
-          "
-
-          echo "Updated package.json to version $NEW_VERSION"
-
-      - name: Sync extension versions
-        if: ${{ inputs.should_bump && !inputs.dry_run }}
-        run: |
-          # Run plugins:sync if available (aligns extension package versions)
-          if npm run --silent plugins:sync 2>/dev/null; then
-            echo "Extension versions synced"
-          else
-            echo "plugins:sync not available, skipping"
-          fi
-
-      - name: Commit version bump
-        if: ${{ inputs.should_bump && !inputs.dry_run }}
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-          NEW_VERSION="${{ steps.bump-version.outputs.new }}"
-
-          # Stage all version-related changes
-          git add package.json
-          git add extensions/*/package.json 2>/dev/null || true
-
-          # Check if there are changes to commit
-          if git diff --cached --quiet; then
-            echo "No version changes to commit"
-          else
-            git commit -m "chore: bump version to $NEW_VERSION"
-            git push origin ${{ inputs.source_branch }}
-          fi
-
-      - name: Create tag
-        if: ${{ inputs.should_bump && !inputs.dry_run }}
-        run: |
-          TAG="${{ steps.bump-version.outputs.tag }}"
-
-          git tag -a "$TAG" -m "Release $TAG"
-          git push origin "$TAG"

.gitignore

@@ -72,6 +72,7 @@ USER.md
 .serena/
 
 # Agent credentials and memory (NEVER COMMIT)
-memory/
+/memory/
 .agent/*.json
 !.agent/workflows/
+local/

CHANGELOG.md

@@ -2,10 +2,37 @@
 
 Docs: https://docs.openclaw.ai
 
+## 2026.2.6-4
+
+### Added
+
+- Gateway: add `agents.create`, `agents.update`, `agents.delete` RPC methods for web UI agent management. (#11045) Thanks @advaitpaliwal.
+
+### Fixes
+
+- Discord: support forum/media `thread create` starter messages, wire `message thread create --message`, and harden thread-create routing. (#10062) Thanks @jarvis89757.
+- Web UI: make chat refresh smoothly scroll to the latest messages and suppress new-messages badge flash during manual refresh.
+- Cron: route text-only isolated agent announces through the shared subagent announce flow; add exponential backoff for repeated errors; preserve future `nextRunAtMs` on restart; include current-boundary schedule matches; prevent stale threadId reuse across targets; and add per-job execution timeout. (#11641) Thanks @tyler6204.
+- Subagents: stabilize announce timing, preserve compaction metrics across retries, clamp overflow-prone long timeouts, and cap impossible context usage token totals. (#11551) Thanks @tyler6204.
+- Agents: recover from context overflow caused by oversized tool results (pre-emptive capping + fallback truncation). (#11579) Thanks @tyler6204.
+- Telegram: render markdown spoilers with `<tg-spoiler>` HTML tags. (#11543) Thanks @ezhikkk.
+- Gateway/CLI: when `gateway.bind=lan`, use a LAN IP for probe URLs and Control UI links. (#11448) Thanks @AnonO6.
+- Memory: set Voyage embeddings `input_type` for improved retrieval. (#10818) Thanks @mcinteerj.
+- Memory/QMD: run boot refresh in background by default, add configurable QMD maintenance timeouts, and retry QMD after fallback failures. (#9690, #9705)
+- Media understanding: recognize `.caf` audio attachments for transcription. (#10982) Thanks @succ985.
+- State dir: honor `OPENCLAW_STATE_DIR` for default device identity and canvas storage paths. (#4824) Thanks @kossoy.
+- Doctor/State dir: suppress repeated legacy migration warnings only for valid symlink mirrors, while keeping warnings for empty or invalid legacy trees. (#11709) Thanks @gumadeiras.
+- Tests: harden flaky hotspots by removing timer sleeps, consolidating onboarding provider-auth coverage, and improving memory test realism. (#11598) Thanks @gumadeiras.
+
 ## 2026.2.6
 
 ### Changes
 
+- Hygiene: remove `workspace:*` from `dependencies` in msteams, nostr, zalo extensions (breaks external `npm install`; keep in `devDependencies` only).
+- Hygiene: add non-root `sandbox` user to `Dockerfile.sandbox` and `Dockerfile.sandbox-browser`.
+- Hygiene: remove dead `vitest` key from `package.json` (superseded by `vitest.config.ts`).
+- Hygiene: remove redundant top-level `overrides` from `package.json` (pnpm uses `pnpm.overrides`).
+- Hygiene: sync `onlyBuiltDependencies` between `pnpm-workspace.yaml` and `package.json` (add missing `node-llama-cpp`, sort alphabetically).
 - Cron: default `wakeMode` is now `"now"` for new jobs (was `"next-heartbeat"`). (#10776) Thanks @tyler6204.
 - Cron: `cron run` defaults to force execution; use `--due` to restrict to due-only. (#10776) Thanks @tyler6204.
 - Models: support Anthropic Opus 4.6 and OpenAI Codex gpt-5.3-codex (forward-compat fallbacks). (#9853, #10720, #9995) Thanks @TinyTb, @calvin-hpnet, @tyler6204.
@@ -28,7 +55,6 @@ Docs: https://docs.openclaw.ai
 
 - Cron: scheduler reliability (timer drift, restart catch-up, lock contention, stale running markers). (#10776) Thanks @tyler6204.
 - Cron: store migration hardening (legacy field migration, parse error handling, explicit delivery mode persistence). (#10776) Thanks @tyler6204.
-- Memory: set Voyage embeddings `input_type` for improved retrieval. (#10818) Thanks @mcinteerj.
 - Telegram: auto-inject DM topic threadId in message tool + subagent announce. (#7235) Thanks @Lukavyi.
 - Security: require auth for Gateway canvas host and A2UI assets. (#9518) Thanks @coygeek.
 - Cron: fix scheduling and reminder delivery regressions; harden next-run recompute + timer re-arming + legacy schedule fields. (#9733, #9823, #9948, #9932) Thanks @tyler6204, @pycckuu, @j2h4u, @fujiwara-tofu-shop.

CLAUDE.md

@@ -1 +1 @@
-AGENTS.md
+AGENTS.md

CONTRIBUTING.md

@@ -25,9 +25,6 @@ Welcome to the lobster tank! 🦞
 - **Gustavo Madeira Santana** - Multi-agents, CLI, web UI
   - GitHub: [@gumadeiras](https://github.com/gumadeiras) · X: [@gumadeiras](https://x.com/gumadeiras)
 
-- **Maximilian Nussbaumer** - DevOps, CI/CD
-  - GitHub: [@quotentiroler](https://github.com/quotentiroler)
-
 ## How to Contribute
 
 1. **Bugs & small fixes** → Open a PR!
@@ -79,46 +76,3 @@ We are currently prioritizing:
 - **Performance**: Optimizing token usage and compaction logic.
 
 Check the [GitHub Issues](https://github.com/openclaw/openclaw/issues) for "good first issue" labels!
-
-## Core vs ClawHub
-
-Not everything belongs in the main repo. Here's how to decide:
-
-| Belongs in **Core**                            | Belongs on **[ClawHub](https://clawhub.ai)**         |
-| ---------------------------------------------- | ---------------------------------------------------- |
-| Channel integrations (Telegram, Discord, etc.) | Domain-specific skills (QR codes, image tools, etc.) |
-| CLI commands and infrastructure                | Custom workflows and automations                     |
-| Provider integrations (LLM backends)           | Niche or experimental utilities                      |
-| Security, routing, and core plumbing           | Third-party service integrations                     |
-
-**Rule of thumb:** if it adds new dependencies or is useful to some users but not most, it belongs on ClawHub. When in doubt, ask in Discord or open a Discussion before writing code.
-
-Skills submitted as PRs to this repo will be redirected to ClawHub. If the core maintainers later decide certain functionality should be first-party, it will be integrated into core.
-
-## Branch Strategy
-
-> **Note:** The staged promotion pipeline is not yet active. Workflows are in
-> place but dormant. For now, open PRs targeting `main` as usual. Once the
-> pipeline is activated, the flow below will apply.
-
-We will use staged branch promotion to keep `main` stable:
-
-```
-dev/* / feature/* / fix/*  →  develop  →  alpha  →  beta  →  main
-```
-
-### For External Contributors (once pipeline is active)
-
-1. Fork the repo
-2. Create your branch (`dev/my-feature`, `fix/some-bug`, etc.)
-3. Open a PR targeting `develop` (not `main`)
-4. CI runs lightweight checks only — no heavy platform tests on your PR
-5. Once merged to `develop`, your changes promote through alpha → beta → main automatically
-
-### For Maintainers (once pipeline is active)
-
-- **Regular changes**: merge to `develop`, let the pipeline promote
-- **Hotfixes**: use `hotfix/*` branches for emergency fixes that bypass staging directly to `main`
-- **Docs-only changes**: skip the test pipeline automatically (paths-ignore)
-
-See [Pipeline docs](https://docs.openclaw.ai/reference/pipeline) for full details.

Dockerfile.sandbox

@@ -13,4 +13,8 @@ RUN apt-get update \
     ripgrep \
   && rm -rf /var/lib/apt/lists/*
 
+RUN useradd --create-home --shell /bin/bash sandbox
+USER sandbox
+WORKDIR /home/sandbox
+
 CMD ["sleep", "infinity"]

Dockerfile.sandbox-browser

@@ -23,6 +23,10 @@ RUN apt-get update \
 COPY scripts/sandbox-browser-entrypoint.sh /usr/local/bin/openclaw-sandbox-browser
 RUN chmod +x /usr/local/bin/openclaw-sandbox-browser
 
+RUN useradd --create-home --shell /bin/bash sandbox
+USER sandbox
+WORKDIR /home/sandbox
+
 EXPOSE 9222 5900 6080
 
 CMD ["openclaw-sandbox-browser"]

README.md

@@ -23,9 +23,10 @@ It answers you on the channels you already use (WhatsApp, Telegram, Slack, Disco
 
 If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
 
-[Website](https://openclaw.ai) · [Docs](https://docs.openclaw.ai) · [DeepWiki](https://deepwiki.com/openclaw/openclaw) · [Getting Started](https://docs.openclaw.ai/start/getting-started) · [Updating](https://docs.openclaw.ai/install/updating) · [Showcase](https://docs.openclaw.ai/start/showcase) · [FAQ](https://docs.openclaw.ai/start/faq) · [Wizard](https://docs.openclaw.ai/start/wizard) · [Nix](https://github.com/openclaw/nix-clawdbot) · [Docker](https://docs.openclaw.ai/install/docker) · [Discord](https://discord.gg/clawd)
+[Website](https://openclaw.ai) · [Docs](https://docs.openclaw.ai) · [DeepWiki](https://deepwiki.com/openclaw/openclaw) · [Getting Started](https://docs.openclaw.ai/start/getting-started) · [Updating](https://docs.openclaw.ai/install/updating) · [Showcase](https://docs.openclaw.ai/start/showcase) · [FAQ](https://docs.openclaw.ai/start/faq) · [Wizard](https://docs.openclaw.ai/start/wizard) · [Nix](https://github.com/openclaw/nix-openclaw) · [Docker](https://docs.openclaw.ai/install/docker) · [Discord](https://discord.gg/clawd)
 
-Preferred setup: run the onboarding wizard (`openclaw onboard`). It walks through gateway, workspace, channels, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
+Preferred setup: run the onboarding wizard (`openclaw onboard`) in your terminal.
+The wizard guides you step by step through setting up the gateway, workspace, channels, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
 Works with npm, pnpm, or bun.
 New install? Start here: [Getting started](https://docs.openclaw.ai/start/getting-started)
 

SECURITY.md

@@ -4,8 +4,13 @@ If you believe you've found a security issue in OpenClaw, please report it priva
 
 ## Reporting
 
-- Email: `steipete@gmail.com`
-- What to include: reproduction steps, impact assessment, and (if possible) a minimal PoC.
+For full reporting instructions - including which repo to report to and how - see our [Trust page](https://trust.openclaw.ai).
+
+Include: reproduction steps, impact assessment, and (if possible) a minimal PoC.
+
+## Security & Trust
+
+**Jamieson O'Reilly** ([@theonejvo](https://twitter.com/theonejvo)) is Security & Trust at OpenClaw. Jamieson is the founder of [Dvuln](https://dvuln.com) and brings extensive experience in offensive security, penetration testing, and security program development.
 
 ## Bug Bounties
 

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -1589,6 +1589,140 @@ public struct AgentSummary: Codable, Sendable {
     }
 }
 
+public struct AgentsCreateParams: Codable, Sendable {
+    public let name: String
+    public let workspace: String
+    public let emoji: String?
+    public let avatar: String?
+
+    public init(
+        name: String,
+        workspace: String,
+        emoji: String?,
+        avatar: String?
+    ) {
+        self.name = name
+        self.workspace = workspace
+        self.emoji = emoji
+        self.avatar = avatar
+    }
+    private enum CodingKeys: String, CodingKey {
+        case name
+        case workspace
+        case emoji
+        case avatar
+    }
+}
+
+public struct AgentsCreateResult: Codable, Sendable {
+    public let ok: Bool
+    public let agentid: String
+    public let name: String
+    public let workspace: String
+
+    public init(
+        ok: Bool,
+        agentid: String,
+        name: String,
+        workspace: String
+    ) {
+        self.ok = ok
+        self.agentid = agentid
+        self.name = name
+        self.workspace = workspace
+    }
+    private enum CodingKeys: String, CodingKey {
+        case ok
+        case agentid = "agentId"
+        case name
+        case workspace
+    }
+}
+
+public struct AgentsUpdateParams: Codable, Sendable {
+    public let agentid: String
+    public let name: String?
+    public let workspace: String?
+    public let model: String?
+    public let avatar: String?
+
+    public init(
+        agentid: String,
+        name: String?,
+        workspace: String?,
+        model: String?,
+        avatar: String?
+    ) {
+        self.agentid = agentid
+        self.name = name
+        self.workspace = workspace
+        self.model = model
+        self.avatar = avatar
+    }
+    private enum CodingKeys: String, CodingKey {
+        case agentid = "agentId"
+        case name
+        case workspace
+        case model
+        case avatar
+    }
+}
+
+public struct AgentsUpdateResult: Codable, Sendable {
+    public let ok: Bool
+    public let agentid: String
+
+    public init(
+        ok: Bool,
+        agentid: String
+    ) {
+        self.ok = ok
+        self.agentid = agentid
+    }
+    private enum CodingKeys: String, CodingKey {
+        case ok
+        case agentid = "agentId"
+    }
+}
+
+public struct AgentsDeleteParams: Codable, Sendable {
+    public let agentid: String
+    public let deletefiles: Bool?
+
+    public init(
+        agentid: String,
+        deletefiles: Bool?
+    ) {
+        self.agentid = agentid
+        self.deletefiles = deletefiles
+    }
+    private enum CodingKeys: String, CodingKey {
+        case agentid = "agentId"
+        case deletefiles = "deleteFiles"
+    }
+}
+
+public struct AgentsDeleteResult: Codable, Sendable {
+    public let ok: Bool
+    public let agentid: String
+    public let removedbindings: Int
+
+    public init(
+        ok: Bool,
+        agentid: String,
+        removedbindings: Int
+    ) {
+        self.ok = ok
+        self.agentid = agentid
+        self.removedbindings = removedbindings
+    }
+    private enum CodingKeys: String, CodingKey {
+        case ok
+        case agentid = "agentId"
+        case removedbindings = "removedBindings"
+    }
+}
+
 public struct AgentsFileEntry: Codable, Sendable {
     public let name: String
     public let path: String

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -1589,6 +1589,140 @@ public struct AgentSummary: Codable, Sendable {
     }
 }
 
+public struct AgentsCreateParams: Codable, Sendable {
+    public let name: String
+    public let workspace: String
+    public let emoji: String?
+    public let avatar: String?
+
+    public init(
+        name: String,
+        workspace: String,
+        emoji: String?,
+        avatar: String?
+    ) {
+        self.name = name
+        self.workspace = workspace
+        self.emoji = emoji
+        self.avatar = avatar
+    }
+    private enum CodingKeys: String, CodingKey {
+        case name
+        case workspace
+        case emoji
+        case avatar
+    }
+}
+
+public struct AgentsCreateResult: Codable, Sendable {
+    public let ok: Bool
+    public let agentid: String
+    public let name: String
+    public let workspace: String
+
+    public init(
+        ok: Bool,
+        agentid: String,
+        name: String,
+        workspace: String
+    ) {
+        self.ok = ok
+        self.agentid = agentid
+        self.name = name
+        self.workspace = workspace
+    }
+    private enum CodingKeys: String, CodingKey {
+        case ok
+        case agentid = "agentId"
+        case name
+        case workspace
+    }
+}
+
+public struct AgentsUpdateParams: Codable, Sendable {
+    public let agentid: String
+    public let name: String?
+    public let workspace: String?
+    public let model: String?
+    public let avatar: String?
+
+    public init(
+        agentid: String,
+        name: String?,
+        workspace: String?,
+        model: String?,
+        avatar: String?
+    ) {
+        self.agentid = agentid
+        self.name = name
+        self.workspace = workspace
+        self.model = model
+        self.avatar = avatar
+    }
+    private enum CodingKeys: String, CodingKey {
+        case agentid = "agentId"
+        case name
+        case workspace
+        case model
+        case avatar
+    }
+}
+
+public struct AgentsUpdateResult: Codable, Sendable {
+    public let ok: Bool
+    public let agentid: String
+
+    public init(
+        ok: Bool,
+        agentid: String
+    ) {
+        self.ok = ok
+        self.agentid = agentid
+    }
+    private enum CodingKeys: String, CodingKey {
+        case ok
+        case agentid = "agentId"
+    }
+}
+
+public struct AgentsDeleteParams: Codable, Sendable {
+    public let agentid: String
+    public let deletefiles: Bool?
+
+    public init(
+        agentid: String,
+        deletefiles: Bool?
+    ) {
+        self.agentid = agentid
+        self.deletefiles = deletefiles
+    }
+    private enum CodingKeys: String, CodingKey {
+        case agentid = "agentId"
+        case deletefiles = "deleteFiles"
+    }
+}
+
+public struct AgentsDeleteResult: Codable, Sendable {
+    public let ok: Bool
+    public let agentid: String
+    public let removedbindings: Int
+
+    public init(
+        ok: Bool,
+        agentid: String,
+        removedbindings: Int
+    ) {
+        self.ok = ok
+        self.agentid = agentid
+        self.removedbindings = removedbindings
+    }
+    private enum CodingKeys: String, CodingKey {
+        case ok
+        case agentid = "agentId"
+        case removedbindings = "removedBindings"
+    }
+}
+
 public struct AgentsFileEntry: Codable, Sendable {
     public let name: String
     public let path: String

docs/automation/cron-jobs.md

@@ -464,6 +464,13 @@ openclaw system event --mode now --text "Next heartbeat: check battery."
 - Check the Gateway is running continuously (cron runs inside the Gateway process).
 - For `cron` schedules: confirm timezone (`--tz`) vs the host timezone.
 
+### A recurring job keeps delaying after failures
+
+- OpenClaw applies exponential retry backoff for recurring jobs after consecutive errors:
+  30s, 1m, 5m, 15m, then 60m between retries.
+- Backoff resets automatically after the next successful run.
+- One-shot (`at`) jobs disable after a terminal run (`ok`, `error`, or `skipped`) and do not retry.
+
 ### Telegram delivers to the wrong place
 
 - For forum topics, use `-100…:topic:<id>` so it’s explicit and unambiguous.

docs/automation/hooks.md

@@ -17,7 +17,7 @@ Hooks are small scripts that run when something happens. There are two kinds:
 - **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
 - **Webhooks**: external HTTP webhooks that let other systems trigger work in OpenClaw. See [Webhook Hooks](/automation/webhook) or use `openclaw webhooks` for Gmail helper commands.
 
-Hooks can also be bundled inside plugins; see [Plugins](/plugin#plugin-hooks).
+Hooks can also be bundled inside plugins; see [Plugins](/tools/plugin#plugin-hooks).
 
 Common uses:
 

docs/channels/bluebubbles.md

@@ -18,7 +18,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
 - OpenClaw talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
 - Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
 - Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
-- Pairing/allowlist works the same way as other channels (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
+- Pairing/allowlist works the same way as other channels (`/channels/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
 - Reactions are surfaced as system events just like Slack/Telegram so agents can "mention" them before replying.
 - Advanced features: edit, unsend, reply threading, message effects, group management.
 
@@ -149,7 +149,7 @@ DMs:
 - Approve via:
   - `openclaw pairing list bluebubbles`
   - `openclaw pairing approve bluebubbles <CODE>`
-- Pairing is the default token exchange. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
 
 Groups:
 
@@ -337,4 +337,4 @@ Prefer `chat_guid` for stable routing:
 - OpenClaw auto-hides known-broken actions based on the BlueBubbles server's macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`.
 - For status/health info: `openclaw status --all` or `openclaw status --deep`.
 
-For general channel workflow reference, see [Channels](/channels) and the [Plugins](/plugin) guide.
+For general channel workflow reference, see [Channels](/channels) and the [Plugins](/tools/plugin) guide.

docs/channels/broadcast-groups.md

@@ -437,6 +437,6 @@ Planned features:
 
 ## See Also
 
-- [Multi-Agent Configuration](/multi-agent-sandbox-tools)
-- [Routing Configuration](/concepts/channel-routing)
+- [Multi-Agent Configuration](/tools/multi-agent-sandbox-tools)
+- [Routing Configuration](/channels/channel-routing)
 - [Session Management](/concepts/sessions)

docs/channels/channel-routing.md

@@ -68,7 +68,7 @@ Config:
 }
 ```
 
-See: [Broadcast Groups](/broadcast-groups).
+See: [Broadcast Groups](/channels/broadcast-groups).
 
 ## Config overview
 

docs/channels/groups.md

@@ -371,4 +371,4 @@ The agent system prompt includes a group intro on the first turn of a new group
 
 ## WhatsApp specifics
 
-See [Group messages](/concepts/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
+See [Group messages](/channels/group-messages) for WhatsApp-only behavior (history injection, mention handling details).

docs/channels/imessage.md

@@ -224,7 +224,7 @@ DMs:
 - Approve via:
   - `openclaw pairing list imessage`
   - `openclaw pairing approve imessage <CODE>`
-- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/channels/pairing)
 
 Groups:
 

docs/channels/index.md

@@ -39,7 +39,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - Channels can run simultaneously; configure multiple and OpenClaw will route per chat.
 - Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and
   stores more state on disk.
-- Group behavior varies by channel; see [Groups](/concepts/groups).
+- Group behavior varies by channel; see [Groups](/channels/groups).
 - DM pairing and allowlists are enforced for safety; see [Security](/gateway/security).
 - Telegram internals: [grammY notes](/channels/grammy).
 - Troubleshooting: [Channel troubleshooting](/channels/troubleshooting).

docs/channels/matrix.md

@@ -34,7 +34,7 @@ openclaw plugins install ./extensions/matrix
 If you choose Matrix during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Setup
 

docs/channels/mattermost.md

@@ -31,7 +31,7 @@ openclaw plugins install ./extensions/mattermost
 If you choose Mattermost during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup
 

docs/channels/msteams.md

@@ -36,7 +36,7 @@ openclaw plugins install ./extensions/msteams
 If you choose Teams during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 

docs/channels/nextcloud-talk.md

@@ -28,7 +28,7 @@ openclaw plugins install ./extensions/nextcloud-talk
 If you choose Nextcloud Talk during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 

docs/channels/signal.md

@@ -109,7 +109,7 @@ DMs:
 - Approve via:
   - `openclaw pairing list signal`
   - `openclaw pairing approve signal <CODE>`
-- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/channels/pairing)
 - UUID-only senders (from `sourceUuid`) are stored as `uuid:<id>` in `channels.signal.allowFrom`.
 
 Groups:

docs/channels/telegram.md

@@ -351,7 +351,7 @@ Use the global setting when all Telegram bots/accounts should behave the same. U
 - Approve via:
   - `openclaw pairing list telegram`
   - `openclaw pairing approve telegram <CODE>`
-- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/channels/pairing)
 - `channels.telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID. The wizard accepts `@username` and resolves it to the numeric ID when possible.
 
 #### Finding your Telegram user ID

docs/channels/tlon.md

@@ -30,7 +30,7 @@ Local checkout (when running from a git repo):
 openclaw plugins install ./extensions/tlon
 ```
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Setup
 

docs/channels/twitch.md

@@ -25,7 +25,7 @@ Local checkout (when running from a git repo):
 openclaw plugins install ./extensions/twitch
 ```
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 

docs/channels/zalo.md

@@ -15,7 +15,7 @@ Zalo ships as a plugin and is not bundled with the core install.
 
 - Install via CLI: `openclaw plugins install @openclaw/zalo`
 - Or select **Zalo** during onboarding and confirm the install prompt
-- Details: [Plugins](/plugin)
+- Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 
@@ -104,7 +104,7 @@ Multi-account support: use `channels.zalo.accounts` with per-account tokens and
 - Approve via:
   - `openclaw pairing list zalo`
   - `openclaw pairing approve zalo <CODE>`
-- Pairing is the default token exchange. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
 - `channels.zalo.allowFrom` accepts numeric user IDs (no username lookup available).
 
 ## Long-polling vs webhook

docs/channels/zalouser.md

@@ -18,7 +18,7 @@ Zalo Personal ships as a plugin and is not bundled with the core install.
 
 - Install via CLI: `openclaw plugins install @openclaw/zalouser`
 - Or from a source checkout: `openclaw plugins install ./extensions/zalouser`
-- Details: [Plugins](/plugin)
+- Details: [Plugins](/tools/plugin)
 
 ## Prerequisite: zca-cli
 

docs/cli/cron.md

@@ -21,6 +21,8 @@ output internal. `--deliver` remains as a deprecated alias for `--announce`.
 
 Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
 
+Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
+
 ## Common edits
 
 Update delivery settings without changing the message:

docs/cli/hooks.md

@@ -12,8 +12,8 @@ Manage agent hooks (event-driven automations for commands like `/new`, `/reset`,
 
 Related:
 
-- Hooks: [Hooks](/hooks)
-- Plugin hooks: [Plugins](/plugin#plugin-hooks)
+- Hooks: [Hooks](/automation/hooks)
+- Plugin hooks: [Plugins](/tools/plugin#plugin-hooks)
 
 ## List All Hooks
 
@@ -248,7 +248,7 @@ openclaw hooks enable session-memory
 
 **Output:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
 
-**See:** [session-memory documentation](/hooks#session-memory)
+**See:** [session-memory documentation](/automation/hooks#session-memory)
 
 ### command-logger
 
@@ -275,7 +275,7 @@ cat ~/.openclaw/logs/commands.log | jq .
 grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
 ```
 
-**See:** [command-logger documentation](/hooks#command-logger)
+**See:** [command-logger documentation](/automation/hooks#command-logger)
 
 ### soul-evil
 
@@ -301,4 +301,4 @@ Runs `BOOT.md` when the gateway starts (after channels start).
 openclaw hooks enable boot-md
 ```
 
-**See:** [boot-md documentation](/hooks#boot-md)
+**See:** [boot-md documentation](/automation/hooks#boot-md)

docs/cli/index.md

@@ -255,7 +255,7 @@ Manage extensions and their config:
 - `openclaw plugins enable <id>` / `disable <id>` — toggle `plugins.entries.<id>.enabled`.
 - `openclaw plugins doctor` — report plugin load errors.
 
-Most plugin changes require a gateway restart. See [/plugin](/plugin).
+Most plugin changes require a gateway restart. See [/plugin](/tools/plugin).
 
 ## Memory
 

docs/cli/memory.md

@@ -14,7 +14,7 @@ Provided by the active memory plugin (default: `memory-core`; set `plugins.slots
 Related:
 
 - Memory concept: [Memory](/concepts/memory)
-- Plugins: [Plugins](/plugin)
+- Plugins: [Plugins](/tools/plugin)
 
 ## Examples
 

docs/cli/message.md

@@ -118,7 +118,7 @@ Name lookup:
 - `thread create`
   - Channels: Discord
   - Required: `--thread-name`, `--target` (channel id)
-  - Optional: `--message-id`, `--auto-archive-min`
+  - Optional: `--message-id`, `--message`, `--auto-archive-min`
 
 - `thread list`
   - Channels: Discord

docs/cli/pairing.md

@@ -11,7 +11,7 @@ Approve or inspect DM pairing requests (for channels that support pairing).
 
 Related:
 
-- Pairing flow: [Pairing](/start/pairing)
+- Pairing flow: [Pairing](/channels/pairing)
 
 ## Commands
 

docs/cli/plugins.md

@@ -12,7 +12,7 @@ Manage Gateway plugins/extensions (loaded in-process).
 
 Related:
 
-- Plugin system: [Plugins](/plugin)
+- Plugin system: [Plugins](/tools/plugin)
 - Plugin manifest + schema: [Plugin manifest](/plugins/manifest)
 - Security hardening: [Security](/gateway/security)
 

docs/cli/tui.md

@@ -12,7 +12,7 @@ Open the terminal UI connected to the Gateway.
 
 Related:
 
-- TUI guide: [TUI](/tui)
+- TUI guide: [TUI](/web/tui)
 
 ## Examples
 

docs/concepts/agent-loop.md

@@ -75,7 +75,7 @@ OpenClaw has two hook systems:
   Use this to add/remove bootstrap context files.
 - **Command hooks**: `/new`, `/reset`, `/stop`, and other command events (see Hooks doc).
 
-See [Hooks](/hooks) for setup and examples.
+See [Hooks](/automation/hooks) for setup and examples.
 
 ### Plugin hooks (agent + gateway lifecycle)
 
@@ -90,7 +90,7 @@ These run inside the agent loop or gateway pipeline:
 - **`session_start` / `session_end`**: session lifecycle boundaries.
 - **`gateway_start` / `gateway_stop`**: gateway lifecycle events.
 
-See [Plugins](/plugin#plugin-hooks) for the hook API and registration details.
+See [Plugins](/tools/plugin#plugin-hooks) for the hook API and registration details.
 
 ## Streaming + partial replies
 

docs/concepts/agent-workspace.md

@@ -228,6 +228,6 @@ Suggested `.gitignore` starter:
 ## Advanced notes
 
 - Multi-agent routing can use different workspaces per agent. See
-  [Channel routing](/concepts/channel-routing) for routing configuration.
+  [Channel routing](/channels/channel-routing) for routing configuration.
 - If `agents.defaults.sandbox` is enabled, non-main sessions can use per-session sandbox
   workspaces under `agents.defaults.sandbox.workspaceRoot`.

docs/concepts/agent.md

@@ -120,4 +120,4 @@ At minimum, set:
 
 ---
 
-_Next: [Group Chats](/concepts/group-messages)_ 🦞
+_Next: [Group Chats](/channels/group-messages)_ 🦞

docs/concepts/architecture.md

@@ -97,7 +97,7 @@ Client                    Gateway
 - Gateway auth (`gateway.auth.*`) still applies to **all** connections, local or
   remote.
 
-Details: [Gateway protocol](/gateway/protocol), [Pairing](/start/pairing),
+Details: [Gateway protocol](/gateway/protocol), [Pairing](/channels/pairing),
 [Security](/gateway/security).
 
 ## Protocol typing and codegen

docs/concepts/context.md

@@ -27,7 +27,7 @@ Context is _not the same thing_ as “memory”: memory can be stored on disk an
 - `/usage tokens` → append per-reply usage footer to normal replies.
 - `/compact` → summarize older history into a compact entry to free window space.
 
-See also: [Slash commands](/tools/slash-commands), [Token use & costs](/token-use), [Compaction](/concepts/compaction).
+See also: [Slash commands](/tools/slash-commands), [Token use & costs](/reference/token-use), [Compaction](/concepts/compaction).
 
 ## Example output
 

docs/concepts/memory.md

@@ -127,12 +127,18 @@ out to QMD for retrieval. Key points:
 
 - The gateway writes a self-contained QMD home under
   `~/.openclaw/agents/<agentId>/qmd/` (config + cache + sqlite DB).
-- Collections are rewritten from `memory.qmd.paths` (plus default workspace
-  memory files) into `index.yml`, then `qmd update` + `qmd embed` run on boot and
-  on a configurable interval (`memory.qmd.update.interval`, default 5 m).
+- Collections are created via `qmd collection add` from `memory.qmd.paths`
+  (plus default workspace memory files), then `qmd update` + `qmd embed` run
+  on boot and on a configurable interval (`memory.qmd.update.interval`,
+  default 5 m).
+- Boot refresh now runs in the background by default so chat startup is not
+  blocked; set `memory.qmd.update.waitForBootSync = true` to keep the previous
+  blocking behavior.
 - Searches run via `qmd query --json`. If QMD fails or the binary is missing,
   OpenClaw automatically falls back to the builtin SQLite manager so memory tools
   keep working.
+- OpenClaw does not expose QMD embed batch-size tuning today; batch behavior is
+  controlled by QMD itself.
 - **First search may be slow**: QMD may download local GGUF models (reranker/query
   expansion) on the first `qmd query` run.
   - OpenClaw sets `XDG_CONFIG_HOME`/`XDG_CACHE_HOME` automatically when it runs QMD.
@@ -170,7 +176,9 @@ out to QMD for retrieval. Key points:
   stable `name`).
 - `sessions`: opt into session JSONL indexing (`enabled`, `retentionDays`,
   `exportDir`).
-- `update`: controls refresh cadence (`interval`, `debounceMs`, `onBoot`, `embedInterval`).
+- `update`: controls refresh cadence and maintenance execution:
+  (`interval`, `debounceMs`, `onBoot`, `waitForBootSync`, `embedInterval`,
+  `commandTimeoutMs`, `updateTimeoutMs`, `embedTimeoutMs`).
 - `limits`: clamp recall payload (`maxResults`, `maxSnippetChars`,
   `maxInjectedChars`, `timeoutMs`).
 - `scope`: same schema as [`session.sendPolicy`](/gateway/configuration#session).

docs/concepts/messages.md

@@ -142,7 +142,7 @@ OpenClaw can expose or hide model reasoning:
 - Reasoning content still counts toward token usage when produced by the model.
 - Telegram supports reasoning stream into the draft bubble.
 
-Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/token-use).
+Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/reference/token-use).
 
 ## Prefixes, threading, and replies
 

docs/concepts/models.md

@@ -194,7 +194,7 @@ Scan results are ranked by:
 Input
 
 - OpenRouter `/models` list (filter `:free`)
-- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/environment))
+- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/help/environment))
 - Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
 - Probe controls: `--timeout`, `--concurrency`
 

docs/concepts/multi-agent.md

@@ -112,7 +112,7 @@ Example:
 Notes:
 
 - DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.
-- For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups).
+- For shared groups, bind the group to one agent or use [Broadcast groups](/channels/broadcast-groups).
 
 ## Routing rules (how messages pick an agent)
 
@@ -373,4 +373,4 @@ Note: `tools.elevated` is **global** and sender-based; it is not configurable pe
 If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
 For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples.
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for detailed examples.

docs/docs.json

@@ -38,18 +38,6 @@
     ]
   },
   "redirects": [
-    {
-      "source": "/cron",
-      "destination": "/cron-jobs"
-    },
-    {
-      "source": "/model",
-      "destination": "/models"
-    },
-    {
-      "source": "/model/",
-      "destination": "/models"
-    },
     {
       "source": "/messages",
       "destination": "/concepts/messages"
@@ -62,6 +50,10 @@
       "source": "/compaction",
       "destination": "/concepts/compaction"
     },
+    {
+      "source": "/cron",
+      "destination": "/cron-jobs"
+    },
     {
       "source": "/minimax",
       "destination": "/providers/minimax"
@@ -356,11 +348,11 @@
     },
     {
       "source": "/group-messages",
-      "destination": "/concepts/group-messages"
+      "destination": "/channels/group-messages"
     },
     {
       "source": "/groups",
-      "destination": "/concepts/groups"
+      "destination": "/channels/groups"
     },
     {
       "source": "/health",
@@ -486,6 +478,14 @@
       "source": "/model-failover",
       "destination": "/concepts/model-failover"
     },
+    {
+      "source": "/model",
+      "destination": "/models"
+    },
+    {
+      "source": "/model/",
+      "destination": "/models"
+    },
     {
       "source": "/models",
       "destination": "/concepts/models"
@@ -508,7 +508,7 @@
     },
     {
       "source": "/pairing",
-      "destination": "/start/pairing"
+      "destination": "/channels/pairing"
     },
     {
       "source": "/plans/cron-add-hardening",
@@ -532,11 +532,11 @@
     },
     {
       "source": "/provider-routing",
-      "destination": "/concepts/channel-routing"
+      "destination": "/channels/channel-routing"
     },
     {
       "source": "/concepts/provider-routing",
-      "destination": "/concepts/channel-routing"
+      "destination": "/channels/channel-routing"
     },
     {
       "source": "/queue",
@@ -667,8 +667,8 @@
       "destination": "/help/troubleshooting"
     },
     {
-      "source": "/web/tui",
-      "destination": "/tui"
+      "source": "/tui",
+      "destination": "/web/tui"
     },
     {
       "source": "/typebox",
@@ -722,9 +722,13 @@
       "source": "/oauth",
       "destination": "/concepts/oauth"
     },
+    {
+      "source": "/plugin",
+      "destination": "/tools/plugin"
+    },
     {
       "source": "/plugins",
-      "destination": "/plugin"
+      "destination": "/tools/plugin"
     },
     {
       "source": "/railway",
@@ -783,9 +787,17 @@
           {
             "tab": "Get started",
             "groups": [
+              {
+                "group": "Home",
+                "pages": ["index"]
+              },
               {
                 "group": "Overview",
-                "pages": ["index", "concepts/features", "start/showcase"]
+                "pages": ["start/showcase"]
+              },
+              {
+                "group": "Core concepts",
+                "pages": ["concepts/features"]
               },
               {
                 "group": "First steps",
@@ -861,11 +873,11 @@
               {
                 "group": "Configuration",
                 "pages": [
-                  "start/pairing",
-                  "concepts/group-messages",
-                  "concepts/groups",
-                  "broadcast-groups",
-                  "concepts/channel-routing",
+                  "channels/pairing",
+                  "channels/group-messages",
+                  "channels/groups",
+                  "channels/broadcast-groups",
+                  "channels/channel-routing",
                   "channels/location",
                   "channels/troubleshooting"
                 ]
@@ -884,10 +896,13 @@
                   "concepts/system-prompt",
                   "concepts/context",
                   "concepts/agent-workspace",
-                  "start/bootstrapping",
                   "concepts/oauth"
                 ]
               },
+              {
+                "group": "Bootstrapping",
+                "pages": ["start/bootstrapping"]
+              },
               {
                 "group": "Sessions and memory",
                 "pages": [
@@ -945,25 +960,26 @@
               },
               {
                 "group": "Agent coordination",
-                "pages": ["tools/agent-send", "tools/subagents", "multi-agent-sandbox-tools"]
+                "pages": ["tools/agent-send", "tools/subagents", "tools/multi-agent-sandbox-tools"]
               },
               {
-                "group": "Skills and extensions",
+                "group": "Skills",
                 "pages": [
                   "tools/slash-commands",
                   "tools/skills",
                   "tools/skills-config",
                   "tools/clawhub",
-                  "plugin",
-                  "plugins/voice-call",
-                  "plugins/zalouser"
+                  "tools/plugin"
                 ]
               },
+              {
+                "group": "Extensions",
+                "pages": ["plugins/voice-call", "plugins/zalouser"]
+              },
               {
                 "group": "Automation",
                 "pages": [
-                  "hooks",
-                  "hooks/soul-evil",
+                  "automation/hooks",
                   "automation/cron-jobs",
                   "automation/cron-vs-heartbeat",
                   "automation/troubleshooting",
@@ -973,6 +989,10 @@
                   "automation/auth-monitoring"
                 ]
               },
+              {
+                "group": "Hooks",
+                "pages": ["hooks/soul-evil"]
+              },
               {
                 "group": "Media and devices",
                 "pages": [
@@ -993,7 +1013,11 @@
             "groups": [
               {
                 "group": "Overview",
-                "pages": ["providers/index", "providers/models", "concepts/models"]
+                "pages": ["providers/index", "providers/models"]
+              },
+              {
+                "group": "Model concepts",
+                "pages": ["concepts/models"]
               },
               {
                 "group": "Configuration",
@@ -1005,7 +1029,7 @@
                   "providers/anthropic",
                   "providers/openai",
                   "providers/openrouter",
-                  "bedrock",
+                  "providers/bedrock",
                   "providers/vercel-ai-gateway",
                   "providers/moonshot",
                   "providers/minimax",
@@ -1120,7 +1144,7 @@
               },
               {
                 "group": "Web interfaces",
-                "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "tui"]
+                "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "web/tui"]
               }
             ]
           },
@@ -1188,14 +1212,16 @@
               },
               {
                 "group": "Technical reference",
+                "pages": ["reference/wizard", "reference/token-use"]
+              },
+              {
+                "group": "Concept internals",
                 "pages": [
-                  "reference/wizard",
                   "concepts/typebox",
                   "concepts/markdown-formatting",
                   "concepts/typing-indicators",
                   "concepts/usage-tracking",
-                  "concepts/timezone",
-                  "token-use"
+                  "concepts/timezone"
                 ]
               },
               {
@@ -1221,18 +1247,23 @@
               },
               {
                 "group": "Environment and debugging",
-                "pages": [
-                  "install/node",
-                  "environment",
-                  "debugging",
-                  "testing",
-                  "scripts",
-                  "reference/session-management-compaction"
-                ]
+                "pages": ["help/environment", "help/debugging", "help/testing", "help/scripts"]
               },
               {
-                "group": "Developer workflows",
-                "pages": ["start/setup", "help/submitting-a-pr", "help/submitting-an-issue"]
+                "group": "Node runtime",
+                "pages": ["install/node"]
+              },
+              {
+                "group": "Compaction internals",
+                "pages": ["reference/session-management-compaction"]
+              },
+              {
+                "group": "Developer setup",
+                "pages": ["start/setup"]
+              },
+              {
+                "group": "Contributing",
+                "pages": ["help/submitting-a-pr", "help/submitting-an-issue"]
               },
               {
                 "group": "Docs meta",
@@ -1248,9 +1279,17 @@
           {
             "tab": "快速开始",
             "groups": [
+              {
+                "group": "首页",
+                "pages": ["zh-CN/index"]
+              },
               {
                 "group": "概览",
-                "pages": ["zh-CN/index", "zh-CN/concepts/features", "zh-CN/start/showcase"]
+                "pages": ["zh-CN/start/showcase"]
+              },
+              {
+                "group": "核心概念",
+                "pages": ["zh-CN/concepts/features"]
               },
               {
                 "group": "第一步",
@@ -1276,7 +1315,6 @@
               {
                 "group": "安装方式",
                 "pages": [
-                  "zh-CN/install/node",
                   "zh-CN/install/docker",
                   "zh-CN/install/nix",
                   "zh-CN/install/ansible",
@@ -1340,11 +1378,11 @@
               {
                 "group": "配置",
                 "pages": [
-                  "zh-CN/start/pairing",
-                  "zh-CN/concepts/group-messages",
-                  "zh-CN/concepts/groups",
-                  "zh-CN/broadcast-groups",
-                  "zh-CN/concepts/channel-routing",
+                  "zh-CN/channels/pairing",
+                  "zh-CN/channels/group-messages",
+                  "zh-CN/channels/groups",
+                  "zh-CN/channels/broadcast-groups",
+                  "zh-CN/channels/channel-routing",
                   "zh-CN/channels/location",
                   "zh-CN/channels/troubleshooting"
                 ]
@@ -1366,6 +1404,10 @@
                   "zh-CN/concepts/oauth"
                 ]
               },
+              {
+                "group": "引导",
+                "pages": ["zh-CN/start/bootstrapping"]
+              },
               {
                 "group": "会话与记忆",
                 "pages": [
@@ -1426,38 +1468,45 @@
                 "pages": [
                   "zh-CN/tools/agent-send",
                   "zh-CN/tools/subagents",
-                  "zh-CN/multi-agent-sandbox-tools"
+                  "zh-CN/tools/multi-agent-sandbox-tools"
                 ]
               },
               {
-                "group": "技能与扩展",
+                "group": "技能",
                 "pages": [
                   "zh-CN/tools/slash-commands",
                   "zh-CN/tools/skills",
                   "zh-CN/tools/skills-config",
                   "zh-CN/tools/clawhub",
-                  "zh-CN/plugin",
-                  "zh-CN/plugins/voice-call",
-                  "zh-CN/plugins/zalouser"
+                  "zh-CN/tools/plugin"
                 ]
               },
+              {
+                "group": "扩展",
+                "pages": ["zh-CN/plugins/voice-call", "zh-CN/plugins/zalouser"]
+              },
               {
                 "group": "自动化",
                 "pages": [
-                  "zh-CN/hooks",
-                  "zh-CN/hooks/soul-evil",
+                  "zh-CN/automation/hooks",
                   "zh-CN/automation/cron-jobs",
                   "zh-CN/automation/cron-vs-heartbeat",
+                  "zh-CN/automation/troubleshooting",
                   "zh-CN/automation/webhook",
                   "zh-CN/automation/gmail-pubsub",
                   "zh-CN/automation/poll",
                   "zh-CN/automation/auth-monitoring"
                 ]
               },
+              {
+                "group": "Hooks",
+                "pages": ["zh-CN/hooks/soul-evil"]
+              },
               {
                 "group": "媒体与设备",
                 "pages": [
                   "zh-CN/nodes/index",
+                  "zh-CN/nodes/troubleshooting",
                   "zh-CN/nodes/images",
                   "zh-CN/nodes/audio",
                   "zh-CN/nodes/camera",
@@ -1473,11 +1522,11 @@
             "groups": [
               {
                 "group": "概览",
-                "pages": [
-                  "zh-CN/providers/index",
-                  "zh-CN/providers/models",
-                  "zh-CN/concepts/models"
-                ]
+                "pages": ["zh-CN/providers/index", "zh-CN/providers/models"]
+              },
+              {
+                "group": "模型概念",
+                "pages": ["zh-CN/concepts/models"]
               },
               {
                 "group": "配置",
@@ -1489,14 +1538,15 @@
                   "zh-CN/providers/anthropic",
                   "zh-CN/providers/openai",
                   "zh-CN/providers/openrouter",
-                  "zh-CN/bedrock",
+                  "zh-CN/providers/bedrock",
                   "zh-CN/providers/vercel-ai-gateway",
                   "zh-CN/providers/moonshot",
                   "zh-CN/providers/minimax",
                   "zh-CN/providers/opencode",
                   "zh-CN/providers/glm",
                   "zh-CN/providers/zai",
-                  "zh-CN/providers/synthetic"
+                  "zh-CN/providers/synthetic",
+                  "zh-CN/providers/qianfan"
                 ]
               }
             ]
@@ -1612,7 +1662,7 @@
                   "zh-CN/web/control-ui",
                   "zh-CN/web/dashboard",
                   "zh-CN/web/webchat",
-                  "zh-CN/tui"
+                  "zh-CN/web/tui"
                 ]
               }
             ]
@@ -1681,13 +1731,16 @@
               },
               {
                 "group": "技术参考",
+                "pages": ["zh-CN/reference/wizard", "zh-CN/reference/token-use"]
+              },
+              {
+                "group": "概念内部机制",
                 "pages": [
                   "zh-CN/concepts/typebox",
                   "zh-CN/concepts/markdown-formatting",
                   "zh-CN/concepts/typing-indicators",
                   "zh-CN/concepts/usage-tracking",
-                  "zh-CN/concepts/timezone",
-                  "zh-CN/token-use"
+                  "zh-CN/concepts/timezone"
                 ]
               },
               {
@@ -1714,17 +1767,28 @@
               {
                 "group": "环境与调试",
                 "pages": [
-                  "zh-CN/environment",
-                  "zh-CN/debugging",
-                  "zh-CN/testing",
-                  "zh-CN/scripts",
-                  "zh-CN/reference/session-management-compaction"
+                  "zh-CN/help/environment",
+                  "zh-CN/help/debugging",
+                  "zh-CN/help/testing",
+                  "zh-CN/help/scripts"
                 ]
               },
               {
-                "group": "开发者工作流",
+                "group": "Node 运行时",
+                "pages": ["zh-CN/install/node"]
+              },
+              {
+                "group": "压缩机制内部参考",
+                "pages": ["zh-CN/reference/session-management-compaction"]
+              },
+              {
+                "group": "开发者设置",
                 "pages": ["zh-CN/start/setup"]
               },
+              {
+                "group": "贡献",
+                "pages": ["zh-CN/help/submitting-a-pr", "zh-CN/help/submitting-an-issue"]
+              },
               {
                 "group": "文档元信息",
                 "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory"]

docs/experiments/plans/group-policy-hardening.md

@@ -36,5 +36,5 @@ false negatives when deciding whether to respond in DMs or groups.
 
 ## Related docs
 
-- [Group Chats](/concepts/groups)
+- [Group Chats](/channels/groups)
 - [Telegram Provider](/channels/telegram)

docs/gateway/configuration.md

@@ -289,7 +289,7 @@ process env is missing the key (same non-overriding rule):
 }
 ```
 
-See [/environment](/environment) for full precedence and sources.
+See [/environment](/help/environment) for full precedence and sources.
 
 ### `env.shellEnv` (optional)
 
@@ -788,7 +788,7 @@ levels in one gateway:
 - **Read-only** tools + workspace
 - **No filesystem access** (messaging/session tools only)
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence and
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence and
 additional examples.
 
 Full access (no sandbox):
@@ -2857,7 +2857,7 @@ Example:
 Controls plugin discovery, allow/deny, and per-plugin config. Plugins are loaded
 from `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, plus any
 `plugins.load.paths` entries. **Config changes require a gateway restart.**
-See [/plugin](/plugin) for full usage.
+See [/plugin](/tools/plugin) for full usage.
 
 Fields:
 

docs/gateway/heartbeat.md

@@ -200,7 +200,7 @@ Use `accountId` to target a specific account on multi-account channels like Tele
 - `session`: optional session key for heartbeat runs.
   - `main` (default): agent main session.
   - Explicit session key (copy from `openclaw sessions --json` or the [sessions CLI](/cli/sessions)).
-  - Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).
+  - Session key formats: see [Sessions](/concepts/session) and [Groups](/channels/groups).
 - `target`:
   - `last` (default): deliver to the last used external channel.
   - explicit channel: `whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`.

docs/gateway/sandboxing.md

@@ -168,7 +168,7 @@ Debugging:
 
 Each agent can override sandbox + tools:
 `agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy).
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence.
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence.
 
 ## Minimal enable example
 
@@ -189,5 +189,5 @@ See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence.
 ## Related docs
 
 - [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox)
-- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools)
+- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools)
 - [Security](/gateway/security)

docs/gateway/security/formal-verification.md

@@ -1,164 +0,0 @@
----
-title: Formal Verification (Security Models)
-summary: Machine-checked security models for OpenClaw’s highest-risk paths.
-permalink: /security/formal-verification/
----
-
-# Formal Verification (Security Models)
-
-This page tracks OpenClaw’s **formal security models** (TLA+/TLC today; more as needed).
-
-> Note: some older links may refer to the previous project name.
-
-**Goal (north star):** provide a machine-checked argument that OpenClaw enforces its
-intended security policy (authorization, session isolation, tool gating, and
-misconfiguration safety), under explicit assumptions.
-
-**What this is (today):** an executable, attacker-driven **security regression suite**:
-
-- Each claim has a runnable model-check over a finite state space.
-- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class.
-
-**What this is not (yet):** a proof that “OpenClaw is secure in all respects” or that the full TypeScript implementation is correct.
-
-## Where the models live
-
-Models are maintained in a separate repo: [vignesh07/clawdbot-formal-models](https://github.com/vignesh07/clawdbot-formal-models).
-
-## Important caveats
-
-- These are **models**, not the full TypeScript implementation. Drift between model and code is possible.
-- Results are bounded by the state space explored by TLC; “green” does not imply security beyond the modeled assumptions and bounds.
-- Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs).
-
-## Reproducing results
-
-Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer:
-
-- CI-run models with public artifacts (counterexample traces, run logs)
-- a hosted “run this model” workflow for small, bounded checks
-
-Getting started:
-
-```bash
-git clone https://github.com/vignesh07/clawdbot-formal-models
-cd clawdbot-formal-models
-
-# Java 11+ required (TLC runs on the JVM).
-# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
-
-make <target>
-```
-
-### Gateway exposure and open gateway misconfiguration
-
-**Claim:** binding beyond loopback without auth can make remote compromise possible / increases exposure; token/password blocks unauth attackers (per the model assumptions).
-
-- Green runs:
-  - `make gateway-exposure-v2`
-  - `make gateway-exposure-v2-protected`
-- Red (expected):
-  - `make gateway-exposure-v2-negative`
-
-See also: `docs/gateway-exposure-matrix.md` in the models repo.
-
-### Nodes.run pipeline (highest-risk capability)
-
-**Claim:** `nodes.run` requires (a) node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay (in the model).
-
-- Green runs:
-  - `make nodes-pipeline`
-  - `make approvals-token`
-- Red (expected):
-  - `make nodes-pipeline-negative`
-  - `make approvals-token-negative`
-
-### Pairing store (DM gating)
-
-**Claim:** pairing requests respect TTL and pending-request caps.
-
-- Green runs:
-  - `make pairing`
-  - `make pairing-cap`
-- Red (expected):
-  - `make pairing-negative`
-  - `make pairing-cap-negative`
-
-### Ingress gating (mentions + control-command bypass)
-
-**Claim:** in group contexts requiring mention, an unauthorized “control command” cannot bypass mention gating.
-
-- Green:
-  - `make ingress-gating`
-- Red (expected):
-  - `make ingress-gating-negative`
-
-### Routing/session-key isolation
-
-**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked/configured.
-
-- Green:
-  - `make routing-isolation`
-- Red (expected):
-  - `make routing-isolation-negative`
-
-## v1++: additional bounded models (concurrency, retries, trace correctness)
-
-These are follow-on models that tighten fidelity around real-world failure modes (non-atomic updates, retries, and message fan-out).
-
-### Pairing store concurrency / idempotency
-
-**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., “check-then-write” must be atomic / locked; refresh shouldn’t create duplicates).
-
-What it means:
-
-- Under concurrent requests, you can’t exceed `MaxPending` for a channel.
-- Repeated requests/refreshes for the same `(channel, sender)` should not create duplicate live pending rows.
-
-- Green runs:
-  - `make pairing-race` (atomic/locked cap check)
-  - `make pairing-idempotency`
-  - `make pairing-refresh`
-  - `make pairing-refresh-race`
-- Red (expected):
-  - `make pairing-race-negative` (non-atomic begin/commit cap race)
-  - `make pairing-idempotency-negative`
-  - `make pairing-refresh-negative`
-  - `make pairing-refresh-race-negative`
-
-### Ingress trace correlation / idempotency
-
-**Claim:** ingestion should preserve trace correlation across fan-out and be idempotent under provider retries.
-
-What it means:
-
-- When one external event becomes multiple internal messages, every part keeps the same trace/event identity.
-- Retries do not result in double-processing.
-- If provider event IDs are missing, dedupe falls back to a safe key (e.g., trace ID) to avoid dropping distinct events.
-
-- Green:
-  - `make ingress-trace`
-  - `make ingress-trace2`
-  - `make ingress-idempotency`
-  - `make ingress-dedupe-fallback`
-- Red (expected):
-  - `make ingress-trace-negative`
-  - `make ingress-trace2-negative`
-  - `make ingress-idempotency-negative`
-  - `make ingress-dedupe-fallback-negative`
-
-### Routing dmScope precedence + identityLinks
-
-**Claim:** routing must keep DM sessions isolated by default, and only collapse sessions when explicitly configured (channel precedence + identity links).
-
-What it means:
-
-- Channel-specific dmScope overrides must win over global defaults.
-- identityLinks should collapse only within explicit linked groups, not across unrelated peers.
-
-- Green:
-  - `make routing-precedence`
-  - `make routing-identitylinks`
-- Red (expected):
-  - `make routing-precedence-negative`
-  - `make routing-identitylinks-negative`

docs/gateway/security/index.md

@@ -175,7 +175,7 @@ Plugins run **in-process** with the Gateway. Treat them as trusted code:
   - OpenClaw uses `npm pack` and then runs `npm install --omit=dev` in that directory (npm lifecycle scripts can execute code during install).
   - Prefer pinned, exact versions (`@scope/pkg@1.2.3`), and inspect the unpacked code on disk before enabling.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## DM access model (pairing / allowlist / open / disabled)
 
@@ -193,7 +193,7 @@ openclaw pairing list <channel>
 openclaw pairing approve <channel> <code>
 ```
 
-Details + files on disk: [Pairing](/start/pairing)
+Details + files on disk: [Pairing](/channels/pairing)
 
 ## DM session isolation (multi-user mode)
 
@@ -229,7 +229,7 @@ OpenClaw has two separate “who can trigger me?” layers:
     - `channels.discord.guilds` / `channels.slack.channels`: per-surface allowlists + mention defaults.
   - **Security note:** treat `dmPolicy="open"` and `groupPolicy="open"` as last-resort settings. They should be barely used; prefer pairing + allowlists unless you fully trust every member of the room.
 
-Details: [Configuration](/gateway/configuration) and [Groups](/concepts/groups)
+Details: [Configuration](/gateway/configuration) and [Groups](/channels/groups)
 
 ## Prompt injection (what it is, why it matters)
 
@@ -627,7 +627,7 @@ access those accounts and data. Treat browser profiles as **sensitive state**:
 
 With multi-agent routing, each agent can have its own sandbox + tool policy:
 use this to give **full access**, **read-only**, or **no access** per agent.
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for full details
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for full details
 and precedence rules.
 
 Common use cases:

docs/gateway/troubleshooting.md

@@ -56,8 +56,8 @@ Common signatures:
 Related:
 
 - [/channels/troubleshooting](/channels/troubleshooting)
-- [/start/pairing](/start/pairing)
-- [/concepts/groups](/concepts/groups)
+- [/channels/pairing](/channels/pairing)
+- [/channels/groups](/channels/groups)
 
 ## Dashboard control ui connectivity
 

docs/help/faq.md

@@ -707,7 +707,7 @@ See [Models](/cli/models) and [OAuth](/concepts/oauth).
 
 ### Is AWS Bedrock supported
 
-Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option.
+Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option.
 
 ### How does Codex auth work
 
@@ -1177,7 +1177,7 @@ Yes - if your private traffic is **DMs** and your public traffic is **groups**.
 
 Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`.
 
-Setup walkthrough + example config: [Groups: personal DMs + public groups](/concepts/groups#pattern-personal-dms-public-groups-single-agent)
+Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent)
 
 Key config reference: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)
 
@@ -1427,7 +1427,7 @@ The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **a
 - **Sub-agents:** spawn background work from a main agent when you want parallelism.
 - **TUI:** connect to the Gateway and switch agents/sessions.
 
-Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/tui).
+Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/web/tui).
 
 ### Can the OpenClaw browser run headless
 
@@ -1681,7 +1681,7 @@ You can also define inline env vars in config (applied only if missing from the
 }
 ```
 
-See [/environment](/environment) for full precedence and sources.
+See [/environment](/help/environment) for full precedence and sources.
 
 ### I started the Gateway via the service and my env vars disappeared What now
 
@@ -1729,7 +1729,7 @@ openclaw models status
 ```
 
 Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).
-See [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment).
+See [/concepts/model-providers](/concepts/model-providers) and [/environment](/help/environment).
 
 ## Sessions and multiple chats
 
@@ -1902,11 +1902,11 @@ Two common causes:
 - Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).
 - You configured `channels.whatsapp.groups` without `"*"` and the group isn't allowlisted.
 
-See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).
+See [Groups](/channels/groups) and [Group messages](/channels/group-messages).
 
 ### Do groupsthreads share context with DMs
 
-Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).
+Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/channels/groups) and [Group messages](/channels/group-messages).
 
 ### How many workspaces and agents can I create
 
@@ -1994,7 +1994,7 @@ Safe options:
 
 - `/model` in chat (quick, per-session)
 - `openclaw models set ...` (updates just model config)
-- `openclaw configure --section models` (interactive)
+- `openclaw configure --section model` (interactive)
 - edit `agents.defaults.model` in `~/.openclaw/openclaw.json`
 
 Avoid `config.apply` with a partial object unless you intend to replace the whole config.
@@ -2609,7 +2609,7 @@ openclaw logs --follow
 In the TUI, use `/status` to see the current state. If you expect replies in a chat
 channel, make sure delivery is enabled (`/deliver on`).
 
-Docs: [TUI](/tui), [Slash commands](/tools/slash-commands).
+Docs: [TUI](/web/tui), [Slash commands](/tools/slash-commands).
 
 ### How do I completely stop then start the Gateway
 
@@ -2701,7 +2701,7 @@ credentials or revoke access without impacting your personal accounts.
 Start small. Give access only to the tools and accounts you actually need, and expand
 later if required.
 
-Docs: [Security](/gateway/security), [Pairing](/start/pairing).
+Docs: [Security](/gateway/security), [Pairing](/channels/pairing).
 
 ### Can I give it autonomy over my text messages and is that safe
 

docs/help/troubleshooting.md

@@ -83,7 +83,7 @@ flowchart TD
 
     - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
     - [/channels/troubleshooting](/channels/troubleshooting)
-    - [/start/pairing](/start/pairing)
+    - [/channels/pairing](/channels/pairing)
 
   </Accordion>
 

docs/hooks/soul-evil.md

@@ -66,4 +66,4 @@ Create `SOUL_EVIL.md` in the agent workspace root (next to `SOUL.md`).
 
 ## See Also
 
-- [Hooks](/hooks)
+- [Hooks](/automation/hooks)

docs/install/ansible.md

@@ -107,7 +107,7 @@ Should show **only port 22** (SSH) open. All other services (gateway, Docker) ar
 
 Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN.
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for sandbox configuration.
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration.
 
 ## Manual Installation
 
@@ -205,4 +205,4 @@ For detailed security architecture and troubleshooting:
 - [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — full deployment guide
 - [Docker](/install/docker) — containerized gateway setup
 - [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
-- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) — per-agent isolation
+- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) — per-agent isolation

docs/install/docker.md

@@ -336,7 +336,7 @@ mixed access levels in one gateway:
 - Read-only tools + read-only workspace (family/work agent)
 - No filesystem/shell tools (public agent)
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for examples,
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for examples,
 precedence, and troubleshooting.
 
 ### Default behavior

docs/network.md

@@ -21,7 +21,7 @@ devices across localhost, LAN, and tailnet.
 
 ## Pairing + identity
 
-- [Pairing overview (DM + nodes)](/start/pairing)
+- [Pairing overview (DM + nodes)](/channels/pairing)
 - [Gateway-owned node pairing](/gateway/pairing)
 - [Devices CLI (pairing + token rotation)](/cli/devices)
 - [Pairing CLI (DM approvals)](/cli/pairing)

docs/plugins/manifest.md

@@ -13,7 +13,7 @@ OpenClaw uses this manifest to validate configuration **without executing plugin
 code**. Missing or invalid manifests are treated as plugin errors and block
 config validation.
 
-See the full plugin system guide: [Plugins](/plugin).
+See the full plugin system guide: [Plugins](/tools/plugin).
 
 ## Required fields
 

docs/prose.md

@@ -31,7 +31,7 @@ Restart the Gateway after enabling the plugin.
 
 Dev/local checkout: `openclaw plugins install ./extensions/open-prose`
 
-Related docs: [Plugins](/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
+Related docs: [Plugins](/tools/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
 
 ## Slash command
 

docs/providers/index.md

@@ -43,7 +43,7 @@ See [Venice AI](/providers/venice).
 - [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
 - [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
 - [OpenCode Zen](/providers/opencode)
-- [Amazon Bedrock](/bedrock)
+- [Amazon Bedrock](/providers/bedrock)
 - [Z.AI](/providers/zai)
 - [Xiaomi](/providers/xiaomi)
 - [GLM models](/providers/glm)

docs/providers/models.md

@@ -45,7 +45,7 @@ See [Venice AI](/providers/venice).
 - [GLM models](/providers/glm)
 - [MiniMax](/providers/minimax)
 - [Venice (Venice AI)](/providers/venice)
-- [Amazon Bedrock](/bedrock)
+- [Amazon Bedrock](/providers/bedrock)
 - [Qianfan](/providers/qianfan)
 
 For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,

docs/providers/qianfan.md

@@ -32,7 +32,7 @@ openclaw onboard --auth-choice qianfan-api-key
 
 ## Related Documentation
 
-- [OpenClaw Configuration](/configuration)
+- [OpenClaw Configuration](/gateway/configuration)
 - [Model Providers](/concepts/model-providers)
-- [Agent Setup](/agents)
+- [Agent Setup](/concepts/agent)
 - [Qianfan API Documentation](https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb)

docs/refactor/plugin-sdk.md

@@ -211,4 +211,4 @@ Notes:
 - New connector templates depend only on SDK + runtime.
 - External plugins can be developed and updated without core source access.
 
-Related docs: [Plugins](/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).
+Related docs: [Plugins](/tools/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).

docs/reference/api-usage-costs.md

@@ -29,7 +29,7 @@ OpenClaw features that can generate provider usage or paid API calls.
 - `openclaw status --usage` and `openclaw channels list` show provider **usage windows**
   (quota snapshots, not per-message costs).
 
-See [Token use & costs](/token-use) for details and examples.
+See [Token use & costs](/reference/token-use) for details and examples.
 
 ## How keys are discovered
 
@@ -48,7 +48,7 @@ OpenClaw can pick up credentials from:
 Every reply or tool call uses the **current model provider** (OpenAI, Anthropic, etc). This is the
 primary source of usage and cost.
 
-See [Models](/providers/models) for pricing config and [Token use & costs](/token-use) for display.
+See [Models](/providers/models) for pricing config and [Token use & costs](/reference/token-use) for display.
 
 ### 2) Media understanding (audio/image/video)
 

docs/reference/pipeline.md

@@ -1,131 +0,0 @@
-# Release Pipeline
-
-This document describes openclaw's staged release pipeline for contributors and maintainers.
-
-## Branch Strategy
-
-```
-dev/* ──────► develop ──────► alpha ──────► beta ──────► main
-feature/*         │              │            │            │
-fix/*             │              │            │            │
-                  ▼              ▼            ▼            ▼
-              Internal       Alpha         Beta        Stable
-              testing      testers       testers      release
-```
-
-### Branch Purposes
-
-| Branch                        | Purpose             | npm tag   | Who uses it      |
-| ----------------------------- | ------------------- | --------- | ---------------- |
-| `dev/*`, `feature/*`, `fix/*` | Active development  | -         | Contributors     |
-| `develop`                     | Integration branch  | -         | CI validation    |
-| `alpha`                       | Early testing       | `@alpha`  | Internal testers |
-| `beta`                        | Pre-release testing | `@beta`   | Beta testers     |
-| `main`                        | Production releases | `@latest` | Everyone         |
-
-## Workflow Overview
-
-### 1. Feature Development
-
-1. Create a branch: `git checkout -b dev/my-feature`
-2. Make changes and push
-3. **Auto-PR created** to `develop` via `feature-pr.yml`
-4. Get review, iterate, merge to `develop`
-
-### 2. Promotion Through Stages
-
-When code lands in `develop`, the `promote-branch.yml` workflow:
-
-1. Runs tests appropriate for that stage
-2. Creates a PR to the next branch (develop → alpha → beta → main)
-3. Auto-merges `develop → alpha` if tests pass
-4. Requires manual approval for `alpha → beta` and `beta → main`
-
-### 3. Releases
-
-Releases are triggered manually via the **Release** workflow:
-
-1. Go to Actions → Release → Run workflow
-2. Select release type: `alpha`, `beta`, or `stable`
-3. Workflow runs: version bump → changelog → tests → npm publish → Docker push
-
-## Test Coverage by Stage
-
-| Stage   | Tests Run                                             |
-| ------- | ----------------------------------------------------- |
-| develop | tsgo, lint, format, protocol, unit tests (Node + Bun) |
-| alpha   | + secrets scan                                        |
-| beta    | + Windows tests                                       |
-| stable  | + macOS tests, install smoke tests                    |
-
-## Emergency Hotfixes
-
-For critical production issues:
-
-1. Create branch: `git checkout -b hotfix/critical-bug`
-2. Push → **Auto-PR created** directly to `main`
-3. Get expedited review (skip staging)
-4. After merge, cherry-pick to `develop`, `alpha`, `beta` to sync
-
-```bash
-# After hotfix merges to main
-git checkout develop && git cherry-pick <commit-sha> && git push
-git checkout alpha && git cherry-pick <commit-sha> && git push
-git checkout beta && git cherry-pick <commit-sha> && git push
-```
-
-## npm Installation by Channel
-
-```bash
-# Stable (default)
-npm install -g openclaw
-
-# Beta testing
-npm install -g openclaw@beta
-
-# Alpha testing (bleeding edge)
-npm install -g openclaw@alpha
-```
-
-## Docker Images
-
-Images are published to GitHub Container Registry:
-
-```bash
-# Stable
-docker pull ghcr.io/openclaw/openclaw:latest
-
-# Beta
-docker pull ghcr.io/openclaw/openclaw:beta
-
-# Specific version
-docker pull ghcr.io/openclaw/openclaw:2026.2.6
-```
-
-## Version Format
-
-- **Stable**: `YYYY.M.D` (e.g., `2026.2.6`)
-- **Beta**: `YYYY.M.D-beta.N` (e.g., `2026.2.6-beta.1`)
-- **Alpha**: `YYYY.M.D-alpha.N` (e.g., `2026.2.6-alpha.3`)
-
-## Setup
-
-### Required Secrets
-
-Configure these in GitHub repo Settings → Secrets and variables → Actions:
-
-| Secret                | Required?            | Purpose                                                 | How to get it                                               |
-| --------------------- | -------------------- | ------------------------------------------------------- | ----------------------------------------------------------- |
-| `GITHUB_TOKEN`        | Automatic            | PR creation, Docker registry, branch ops                | Provided by GitHub Actions — no setup needed                |
-| `NPM_TOKEN`           | Yes (for publishing) | npm publish with `@alpha`, `@beta`, `@latest` tags      | npmjs.com → Access Tokens → Generate New Token → Automation |
-| `DISCORD_WEBHOOK_URL` | Optional             | Notifications for promotions, test results, deployments | Discord → Server Settings → Integrations → Webhooks         |
-
-Without `NPM_TOKEN`, the pipeline runs normally but skips npm publishing. Without `DISCORD_WEBHOOK_URL`, notifications are silently skipped.
-
-### Branch Setup
-
-Staging branches are auto-created from `main` when the first promotion runs. No manual setup required.
-
-### Rollback
-
-The rollback workflow (`Actions → Rollback`) re-tags npm and Docker to a previous version. Requires `NPM_TOKEN` and is manual-trigger only.

docs/reference/session-management-compaction.md

@@ -154,7 +154,7 @@ If you’re tuning limits:
 - The context window comes from the model catalog (and can be overridden via config).
 - `contextTokens` in the store is a runtime estimate/reporting value; don’t treat it as a strict guarantee.
 
-For more, see [/token-use](/token-use).
+For more, see [/token-use](/reference/token-use).
 
 ---
 

docs/reference/test.md

@@ -7,7 +7,7 @@ title: "Tests"
 
 # Tests
 
-- Full testing kit (suites, live, Docker): [Testing](/testing)
+- Full testing kit (suites, live, Docker): [Testing](/help/testing)
 
 - `pnpm test:force`: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don’t collide with a running instance. Use this when a prior gateway run left port 18789 occupied.
 - `pnpm test:coverage`: Runs Vitest with V8 coverage. Global thresholds are 70% lines/branches/functions/statements. Coverage excludes integration-heavy entrypoints (CLI wiring, gateway/telegram bridges, webchat static server) to keep the target focused on unit-testable logic.

docs/security/CONTRIBUTING-THREAT-MODEL.md

@@ -0,0 +1,90 @@
+# Contributing to the OpenClaw Threat Model
+
+Thanks for helping make OpenClaw more secure. This threat model is a living document and we welcome contributions from anyone - you don't need to be a security expert.
+
+## Ways to Contribute
+
+### Add a Threat
+
+Spotted an attack vector or risk we haven't covered? Open an issue on [openclaw/trust](https://github.com/openclaw/trust/issues) and describe it in your own words. You don't need to know any frameworks or fill in every field - just describe the scenario.
+
+**Helpful to include (but not required):**
+
+- The attack scenario and how it could be exploited
+- Which parts of OpenClaw are affected (CLI, gateway, channels, ClawHub, MCP servers, etc.)
+- How severe you think it is (low / medium / high / critical)
+- Any links to related research, CVEs, or real-world examples
+
+We'll handle the ATLAS mapping, threat IDs, and risk assessment during review. If you want to include those details, great - but it's not expected.
+
+> **This is for adding to the threat model, not reporting live vulnerabilities.** If you've found an exploitable vulnerability, see our [Trust page](https://trust.openclaw.ai) for responsible disclosure instructions.
+
+### Suggest a Mitigation
+
+Have an idea for how to address an existing threat? Open an issue or PR referencing the threat. Useful mitigations are specific and actionable - for example, "per-sender rate limiting of 10 messages/minute at the gateway" is better than "implement rate limiting."
+
+### Propose an Attack Chain
+
+Attack chains show how multiple threats combine into a realistic attack scenario. If you see a dangerous combination, describe the steps and how an attacker would chain them together. A short narrative of how the attack unfolds in practice is more valuable than a formal template.
+
+### Fix or Improve Existing Content
+
+Typos, clarifications, outdated info, better examples - PRs welcome, no issue needed.
+
+## What We Use
+
+### MITRE ATLAS
+
+This threat model is built on [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems), a framework designed specifically for AI/ML threats like prompt injection, tool misuse, and agent exploitation. You don't need to know ATLAS to contribute - we map submissions to the framework during review.
+
+### Threat IDs
+
+Each threat gets an ID like `T-EXEC-003`. The categories are:
+
+| Code    | Category                                   |
+| ------- | ------------------------------------------ |
+| RECON   | Reconnaissance - information gathering     |
+| ACCESS  | Initial access - gaining entry             |
+| EXEC    | Execution - running malicious actions      |
+| PERSIST | Persistence - maintaining access           |
+| EVADE   | Defense evasion - avoiding detection       |
+| DISC    | Discovery - learning about the environment |
+| EXFIL   | Exfiltration - stealing data               |
+| IMPACT  | Impact - damage or disruption              |
+
+IDs are assigned by maintainers during review. You don't need to pick one.
+
+### Risk Levels
+
+| Level        | Meaning                                                           |
+| ------------ | ----------------------------------------------------------------- |
+| **Critical** | Full system compromise, or high likelihood + critical impact      |
+| **High**     | Significant damage likely, or medium likelihood + critical impact |
+| **Medium**   | Moderate risk, or low likelihood + high impact                    |
+| **Low**      | Unlikely and limited impact                                       |
+
+If you're unsure about the risk level, just describe the impact and we'll assess it.
+
+## Review Process
+
+1. **Triage** - We review new submissions within 48 hours
+2. **Assessment** - We verify feasibility, assign ATLAS mapping and threat ID, validate risk level
+3. **Documentation** - We ensure everything is formatted and complete
+4. **Merge** - Added to the threat model and visualization
+
+## Resources
+
+- [ATLAS Website](https://atlas.mitre.org/)
+- [ATLAS Techniques](https://atlas.mitre.org/techniques/)
+- [ATLAS Case Studies](https://atlas.mitre.org/studies/)
+- [OpenClaw Threat Model](./THREAT-MODEL-ATLAS.md)
+
+## Contact
+
+- **Security vulnerabilities:** See our [Trust page](https://trust.openclaw.ai) for reporting instructions
+- **Threat model questions:** Open an issue on [openclaw/trust](https://github.com/openclaw/trust/issues)
+- **General chat:** Discord #security channel
+
+## Recognition
+
+Contributors to the threat model are recognized in the threat model acknowledgments, release notes, and the OpenClaw security hall of fame for significant contributions.

docs/security/README.md

@@ -0,0 +1,17 @@
+# OpenClaw Security & Trust
+
+**Live:** [trust.openclaw.ai](https://trust.openclaw.ai)
+
+## Documents
+
+- [Threat Model](./THREAT-MODEL-ATLAS.md) - MITRE ATLAS-based threat model for the OpenClaw ecosystem
+- [Contributing to the Threat Model](./CONTRIBUTING-THREAT-MODEL.md) - How to add threats, mitigations, and attack chains
+
+## Reporting Vulnerabilities
+
+See the [Trust page](https://trust.openclaw.ai) for full reporting instructions covering all repos.
+
+## Contact
+
+- **Jamieson O'Reilly** ([@theonejvo](https://twitter.com/theonejvo)) - Security & Trust
+- Discord: #security channel

docs/security/THREAT-MODEL-ATLAS.md

@@ -0,0 +1,603 @@
+# OpenClaw Threat Model v1.0
+
+## MITRE ATLAS Framework
+
+**Version:** 1.0-draft
+**Last Updated:** 2026-02-04
+**Methodology:** MITRE ATLAS + Data Flow Diagrams
+**Framework:** [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems)
+
+### Framework Attribution
+
+This threat model is built on [MITRE ATLAS](https://atlas.mitre.org/), the industry-standard framework for documenting adversarial threats to AI/ML systems. ATLAS is maintained by [MITRE](https://www.mitre.org/) in collaboration with the AI security community.
+
+**Key ATLAS Resources:**
+
+- [ATLAS Techniques](https://atlas.mitre.org/techniques/)
+- [ATLAS Tactics](https://atlas.mitre.org/tactics/)
+- [ATLAS Case Studies](https://atlas.mitre.org/studies/)
+- [ATLAS GitHub](https://github.com/mitre-atlas/atlas-data)
+- [Contributing to ATLAS](https://atlas.mitre.org/resources/contribute)
+
+### Contributing to This Threat Model
+
+This is a living document maintained by the OpenClaw community. See [CONTRIBUTING-THREAT-MODEL.md](./CONTRIBUTING-THREAT-MODEL.md) for guidelines on contributing:
+
+- Reporting new threats
+- Updating existing threats
+- Proposing attack chains
+- Suggesting mitigations
+
+---
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+This threat model documents adversarial threats to the OpenClaw AI agent platform and ClawHub skill marketplace, using the MITRE ATLAS framework designed specifically for AI/ML systems.
+
+### 1.2 Scope
+
+| Component              | Included | Notes                                            |
+| ---------------------- | -------- | ------------------------------------------------ |
+| OpenClaw Agent Runtime | Yes      | Core agent execution, tool calls, sessions       |
+| Gateway                | Yes      | Authentication, routing, channel integration     |
+| Channel Integrations   | Yes      | WhatsApp, Telegram, Discord, Signal, Slack, etc. |
+| ClawHub Marketplace    | Yes      | Skill publishing, moderation, distribution       |
+| MCP Servers            | Yes      | External tool providers                          |
+| User Devices           | Partial  | Mobile apps, desktop clients                     |
+
+### 1.3 Out of Scope
+
+Nothing is explicitly out of scope for this threat model.
+
+---
+
+## 2. System Architecture
+
+### 2.1 Trust Boundaries
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    UNTRUSTED ZONE                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
+│  │  WhatsApp   │  │  Telegram   │  │   Discord   │  ...         │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
+│         │                │                │                      │
+└─────────┼────────────────┼────────────────┼──────────────────────┘
+          │                │                │
+          ▼                ▼                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 1: Channel Access                 │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                      GATEWAY                              │   │
+│  │  • Device Pairing (30s grace period)                      │   │
+│  │  • AllowFrom / AllowList validation                       │   │
+│  │  • Token/Password/Tailscale auth                          │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 2: Session Isolation              │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                   AGENT SESSIONS                          │   │
+│  │  • Session key = agent:channel:peer                       │   │
+│  │  • Tool policies per agent                                │   │
+│  │  • Transcript logging                                     │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 3: Tool Execution                 │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                  EXECUTION SANDBOX                        │   │
+│  │  • Docker sandbox OR Host (exec-approvals)                │   │
+│  │  • Node remote execution                                  │   │
+│  │  • SSRF protection (DNS pinning + IP blocking)            │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 4: External Content               │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │              FETCHED URLs / EMAILS / WEBHOOKS             │   │
+│  │  • External content wrapping (XML tags)                   │   │
+│  │  • Security notice injection                              │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 TRUST BOUNDARY 5: Supply Chain                   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                      CLAWHUB                              │   │
+│  │  • Skill publishing (semver, SKILL.md required)           │   │
+│  │  • Pattern-based moderation flags                         │   │
+│  │  • VirusTotal scanning (coming soon)                      │   │
+│  │  • GitHub account age verification                        │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Data Flows
+
+| Flow | Source  | Destination | Data               | Protection           |
+| ---- | ------- | ----------- | ------------------ | -------------------- |
+| F1   | Channel | Gateway     | User messages      | TLS, AllowFrom       |
+| F2   | Gateway | Agent       | Routed messages    | Session isolation    |
+| F3   | Agent   | Tools       | Tool invocations   | Policy enforcement   |
+| F4   | Agent   | External    | web_fetch requests | SSRF blocking        |
+| F5   | ClawHub | Agent       | Skill code         | Moderation, scanning |
+| F6   | Agent   | Channel     | Responses          | Output filtering     |
+
+---
+
+## 3. Threat Analysis by ATLAS Tactic
+
+### 3.1 Reconnaissance (AML.TA0002)
+
+#### T-RECON-001: Agent Endpoint Discovery
+
+| Attribute               | Value                                                                |
+| ----------------------- | -------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0006 - Active Scanning                                          |
+| **Description**         | Attacker scans for exposed OpenClaw gateway endpoints                |
+| **Attack Vector**       | Network scanning, shodan queries, DNS enumeration                    |
+| **Affected Components** | Gateway, exposed API endpoints                                       |
+| **Current Mitigations** | Tailscale auth option, bind to loopback by default                   |
+| **Residual Risk**       | Medium - Public gateways discoverable                                |
+| **Recommendations**     | Document secure deployment, add rate limiting on discovery endpoints |
+
+#### T-RECON-002: Channel Integration Probing
+
+| Attribute               | Value                                                              |
+| ----------------------- | ------------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0006 - Active Scanning                                        |
+| **Description**         | Attacker probes messaging channels to identify AI-managed accounts |
+| **Attack Vector**       | Sending test messages, observing response patterns                 |
+| **Affected Components** | All channel integrations                                           |
+| **Current Mitigations** | None specific                                                      |
+| **Residual Risk**       | Low - Limited value from discovery alone                           |
+| **Recommendations**     | Consider response timing randomization                             |
+
+---
+
+### 3.2 Initial Access (AML.TA0004)
+
+#### T-ACCESS-001: Pairing Code Interception
+
+| Attribute               | Value                                                    |
+| ----------------------- | -------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access                |
+| **Description**         | Attacker intercepts pairing code during 30s grace period |
+| **Attack Vector**       | Shoulder surfing, network sniffing, social engineering   |
+| **Affected Components** | Device pairing system                                    |
+| **Current Mitigations** | 30s expiry, codes sent via existing channel              |
+| **Residual Risk**       | Medium - Grace period exploitable                        |
+| **Recommendations**     | Reduce grace period, add confirmation step               |
+
+#### T-ACCESS-002: AllowFrom Spoofing
+
+| Attribute               | Value                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access                                      |
+| **Description**         | Attacker spoofs allowed sender identity in channel                             |
+| **Attack Vector**       | Depends on channel - phone number spoofing, username impersonation             |
+| **Affected Components** | AllowFrom validation per channel                                               |
+| **Current Mitigations** | Channel-specific identity verification                                         |
+| **Residual Risk**       | Medium - Some channels vulnerable to spoofing                                  |
+| **Recommendations**     | Document channel-specific risks, add cryptographic verification where possible |
+
+#### T-ACCESS-003: Token Theft
+
+| Attribute               | Value                                                       |
+| ----------------------- | ----------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access                   |
+| **Description**         | Attacker steals authentication tokens from config files     |
+| **Attack Vector**       | Malware, unauthorized device access, config backup exposure |
+| **Affected Components** | ~/.openclaw/credentials/, config storage                    |
+| **Current Mitigations** | File permissions                                            |
+| **Residual Risk**       | High - Tokens stored in plaintext                           |
+| **Recommendations**     | Implement token encryption at rest, add token rotation      |
+
+---
+
+### 3.3 Execution (AML.TA0005)
+
+#### T-EXEC-001: Direct Prompt Injection
+
+| Attribute               | Value                                                                                     |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0051.000 - LLM Prompt Injection: Direct                                              |
+| **Description**         | Attacker sends crafted prompts to manipulate agent behavior                               |
+| **Attack Vector**       | Channel messages containing adversarial instructions                                      |
+| **Affected Components** | Agent LLM, all input surfaces                                                             |
+| **Current Mitigations** | Pattern detection, external content wrapping                                              |
+| **Residual Risk**       | Critical - Detection only, no blocking; sophisticated attacks bypass                      |
+| **Recommendations**     | Implement multi-layer defense, output validation, user confirmation for sensitive actions |
+
+#### T-EXEC-002: Indirect Prompt Injection
+
+| Attribute               | Value                                                       |
+| ----------------------- | ----------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0051.001 - LLM Prompt Injection: Indirect              |
+| **Description**         | Attacker embeds malicious instructions in fetched content   |
+| **Attack Vector**       | Malicious URLs, poisoned emails, compromised webhooks       |
+| **Affected Components** | web_fetch, email ingestion, external data sources           |
+| **Current Mitigations** | Content wrapping with XML tags and security notice          |
+| **Residual Risk**       | High - LLM may ignore wrapper instructions                  |
+| **Recommendations**     | Implement content sanitization, separate execution contexts |
+
+#### T-EXEC-003: Tool Argument Injection
+
+| Attribute               | Value                                                        |
+| ----------------------- | ------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0051.000 - LLM Prompt Injection: Direct                 |
+| **Description**         | Attacker manipulates tool arguments through prompt injection |
+| **Attack Vector**       | Crafted prompts that influence tool parameter values         |
+| **Affected Components** | All tool invocations                                         |
+| **Current Mitigations** | Exec approvals for dangerous commands                        |
+| **Residual Risk**       | High - Relies on user judgment                               |
+| **Recommendations**     | Implement argument validation, parameterized tool calls      |
+
+#### T-EXEC-004: Exec Approval Bypass
+
+| Attribute               | Value                                                      |
+| ----------------------- | ---------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0043 - Craft Adversarial Data                         |
+| **Description**         | Attacker crafts commands that bypass approval allowlist    |
+| **Attack Vector**       | Command obfuscation, alias exploitation, path manipulation |
+| **Affected Components** | exec-approvals.ts, command allowlist                       |
+| **Current Mitigations** | Allowlist + ask mode                                       |
+| **Residual Risk**       | High - No command sanitization                             |
+| **Recommendations**     | Implement command normalization, expand blocklist          |
+
+---
+
+### 3.4 Persistence (AML.TA0006)
+
+#### T-PERSIST-001: Malicious Skill Installation
+
+| Attribute               | Value                                                                    |
+| ----------------------- | ------------------------------------------------------------------------ |
+| **ATLAS ID**            | AML.T0010.001 - Supply Chain Compromise: AI Software                     |
+| **Description**         | Attacker publishes malicious skill to ClawHub                            |
+| **Attack Vector**       | Create account, publish skill with hidden malicious code                 |
+| **Affected Components** | ClawHub, skill loading, agent execution                                  |
+| **Current Mitigations** | GitHub account age verification, pattern-based moderation flags          |
+| **Residual Risk**       | Critical - No sandboxing, limited review                                 |
+| **Recommendations**     | VirusTotal integration (in progress), skill sandboxing, community review |
+
+#### T-PERSIST-002: Skill Update Poisoning
+
+| Attribute               | Value                                                          |
+| ----------------------- | -------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0010.001 - Supply Chain Compromise: AI Software           |
+| **Description**         | Attacker compromises popular skill and pushes malicious update |
+| **Attack Vector**       | Account compromise, social engineering of skill owner          |
+| **Affected Components** | ClawHub versioning, auto-update flows                          |
+| **Current Mitigations** | Version fingerprinting                                         |
+| **Residual Risk**       | High - Auto-updates may pull malicious versions                |
+| **Recommendations**     | Implement update signing, rollback capability, version pinning |
+
+#### T-PERSIST-003: Agent Configuration Tampering
+
+| Attribute               | Value                                                           |
+| ----------------------- | --------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0010.002 - Supply Chain Compromise: Data                   |
+| **Description**         | Attacker modifies agent configuration to persist access         |
+| **Attack Vector**       | Config file modification, settings injection                    |
+| **Affected Components** | Agent config, tool policies                                     |
+| **Current Mitigations** | File permissions                                                |
+| **Residual Risk**       | Medium - Requires local access                                  |
+| **Recommendations**     | Config integrity verification, audit logging for config changes |
+
+---
+
+### 3.5 Defense Evasion (AML.TA0007)
+
+#### T-EVADE-001: Moderation Pattern Bypass
+
+| Attribute               | Value                                                                  |
+| ----------------------- | ---------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0043 - Craft Adversarial Data                                     |
+| **Description**         | Attacker crafts skill content to evade moderation patterns             |
+| **Attack Vector**       | Unicode homoglyphs, encoding tricks, dynamic loading                   |
+| **Affected Components** | ClawHub moderation.ts                                                  |
+| **Current Mitigations** | Pattern-based FLAG_RULES                                               |
+| **Residual Risk**       | High - Simple regex easily bypassed                                    |
+| **Recommendations**     | Add behavioral analysis (VirusTotal Code Insight), AST-based detection |
+
+#### T-EVADE-002: Content Wrapper Escape
+
+| Attribute               | Value                                                     |
+| ----------------------- | --------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0043 - Craft Adversarial Data                        |
+| **Description**         | Attacker crafts content that escapes XML wrapper context  |
+| **Attack Vector**       | Tag manipulation, context confusion, instruction override |
+| **Affected Components** | External content wrapping                                 |
+| **Current Mitigations** | XML tags + security notice                                |
+| **Residual Risk**       | Medium - Novel escapes discovered regularly               |
+| **Recommendations**     | Multiple wrapper layers, output-side validation           |
+
+---
+
+### 3.6 Discovery (AML.TA0008)
+
+#### T-DISC-001: Tool Enumeration
+
+| Attribute               | Value                                                 |
+| ----------------------- | ----------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access             |
+| **Description**         | Attacker enumerates available tools through prompting |
+| **Attack Vector**       | "What tools do you have?" style queries               |
+| **Affected Components** | Agent tool registry                                   |
+| **Current Mitigations** | None specific                                         |
+| **Residual Risk**       | Low - Tools generally documented                      |
+| **Recommendations**     | Consider tool visibility controls                     |
+
+#### T-DISC-002: Session Data Extraction
+
+| Attribute               | Value                                                 |
+| ----------------------- | ----------------------------------------------------- |
+| **ATLAS ID**            | AML.T0040 - AI Model Inference API Access             |
+| **Description**         | Attacker extracts sensitive data from session context |
+| **Attack Vector**       | "What did we discuss?" queries, context probing       |
+| **Affected Components** | Session transcripts, context window                   |
+| **Current Mitigations** | Session isolation per sender                          |
+| **Residual Risk**       | Medium - Within-session data accessible               |
+| **Recommendations**     | Implement sensitive data redaction in context         |
+
+---
+
+### 3.7 Collection & Exfiltration (AML.TA0009, AML.TA0010)
+
+#### T-EXFIL-001: Data Theft via web_fetch
+
+| Attribute               | Value                                                                  |
+| ----------------------- | ---------------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0009 - Collection                                                 |
+| **Description**         | Attacker exfiltrates data by instructing agent to send to external URL |
+| **Attack Vector**       | Prompt injection causing agent to POST data to attacker server         |
+| **Affected Components** | web_fetch tool                                                         |
+| **Current Mitigations** | SSRF blocking for internal networks                                    |
+| **Residual Risk**       | High - External URLs permitted                                         |
+| **Recommendations**     | Implement URL allowlisting, data classification awareness              |
+
+#### T-EXFIL-002: Unauthorized Message Sending
+
+| Attribute               | Value                                                            |
+| ----------------------- | ---------------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0009 - Collection                                           |
+| **Description**         | Attacker causes agent to send messages containing sensitive data |
+| **Attack Vector**       | Prompt injection causing agent to message attacker               |
+| **Affected Components** | Message tool, channel integrations                               |
+| **Current Mitigations** | Outbound messaging gating                                        |
+| **Residual Risk**       | Medium - Gating may be bypassed                                  |
+| **Recommendations**     | Require explicit confirmation for new recipients                 |
+
+#### T-EXFIL-003: Credential Harvesting
+
+| Attribute               | Value                                                   |
+| ----------------------- | ------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0009 - Collection                                  |
+| **Description**         | Malicious skill harvests credentials from agent context |
+| **Attack Vector**       | Skill code reads environment variables, config files    |
+| **Affected Components** | Skill execution environment                             |
+| **Current Mitigations** | None specific to skills                                 |
+| **Residual Risk**       | Critical - Skills run with agent privileges             |
+| **Recommendations**     | Skill sandboxing, credential isolation                  |
+
+---
+
+### 3.8 Impact (AML.TA0011)
+
+#### T-IMPACT-001: Unauthorized Command Execution
+
+| Attribute               | Value                                               |
+| ----------------------- | --------------------------------------------------- |
+| **ATLAS ID**            | AML.T0031 - Erode AI Model Integrity                |
+| **Description**         | Attacker executes arbitrary commands on user system |
+| **Attack Vector**       | Prompt injection combined with exec approval bypass |
+| **Affected Components** | Bash tool, command execution                        |
+| **Current Mitigations** | Exec approvals, Docker sandbox option               |
+| **Residual Risk**       | Critical - Host execution without sandbox           |
+| **Recommendations**     | Default to sandbox, improve approval UX             |
+
+#### T-IMPACT-002: Resource Exhaustion (DoS)
+
+| Attribute               | Value                                              |
+| ----------------------- | -------------------------------------------------- |
+| **ATLAS ID**            | AML.T0031 - Erode AI Model Integrity               |
+| **Description**         | Attacker exhausts API credits or compute resources |
+| **Attack Vector**       | Automated message flooding, expensive tool calls   |
+| **Affected Components** | Gateway, agent sessions, API provider              |
+| **Current Mitigations** | None                                               |
+| **Residual Risk**       | High - No rate limiting                            |
+| **Recommendations**     | Implement per-sender rate limits, cost budgets     |
+
+#### T-IMPACT-003: Reputation Damage
+
+| Attribute               | Value                                                   |
+| ----------------------- | ------------------------------------------------------- |
+| **ATLAS ID**            | AML.T0031 - Erode AI Model Integrity                    |
+| **Description**         | Attacker causes agent to send harmful/offensive content |
+| **Attack Vector**       | Prompt injection causing inappropriate responses        |
+| **Affected Components** | Output generation, channel messaging                    |
+| **Current Mitigations** | LLM provider content policies                           |
+| **Residual Risk**       | Medium - Provider filters imperfect                     |
+| **Recommendations**     | Output filtering layer, user controls                   |
+
+---
+
+## 4. ClawHub Supply Chain Analysis
+
+### 4.1 Current Security Controls
+
+| Control              | Implementation              | Effectiveness                                        |
+| -------------------- | --------------------------- | ---------------------------------------------------- |
+| GitHub Account Age   | `requireGitHubAccountAge()` | Medium - Raises bar for new attackers                |
+| Path Sanitization    | `sanitizePath()`            | High - Prevents path traversal                       |
+| File Type Validation | `isTextFile()`              | Medium - Only text files, but can still be malicious |
+| Size Limits          | 50MB total bundle           | High - Prevents resource exhaustion                  |
+| Required SKILL.md    | Mandatory readme            | Low security value - Informational only              |
+| Pattern Moderation   | FLAG_RULES in moderation.ts | Low - Easily bypassed                                |
+| Moderation Status    | `moderationStatus` field    | Medium - Manual review possible                      |
+
+### 4.2 Moderation Flag Patterns
+
+Current patterns in `moderation.ts`:
+
+```javascript
+// Known-bad identifiers
+/(keepcold131\/ClawdAuthenticatorTool|ClawdAuthenticatorTool)/i
+
+// Suspicious keywords
+/(malware|stealer|phish|phishing|keylogger)/i
+/(api[-_ ]?key|token|password|private key|secret)/i
+/(wallet|seed phrase|mnemonic|crypto)/i
+/(discord\.gg|webhook|hooks\.slack)/i
+/(curl[^\n]+\|\s*(sh|bash))/i
+/(bit\.ly|tinyurl\.com|t\.co|goo\.gl|is\.gd)/i
+```
+
+**Limitations:**
+
+- Only checks slug, displayName, summary, frontmatter, metadata, file paths
+- Does not analyze actual skill code content
+- Simple regex easily bypassed with obfuscation
+- No behavioral analysis
+
+### 4.3 Planned Improvements
+
+| Improvement            | Status                                | Impact                                                                |
+| ---------------------- | ------------------------------------- | --------------------------------------------------------------------- |
+| VirusTotal Integration | In Progress                           | High - Code Insight behavioral analysis                               |
+| Community Reporting    | Partial (`skillReports` table exists) | Medium                                                                |
+| Audit Logging          | Partial (`auditLogs` table exists)    | Medium                                                                |
+| Badge System           | Implemented                           | Medium - `highlighted`, `official`, `deprecated`, `redactionApproved` |
+
+---
+
+## 5. Risk Matrix
+
+### 5.1 Likelihood vs Impact
+
+| Threat ID     | Likelihood | Impact   | Risk Level   | Priority |
+| ------------- | ---------- | -------- | ------------ | -------- |
+| T-EXEC-001    | High       | Critical | **Critical** | P0       |
+| T-PERSIST-001 | High       | Critical | **Critical** | P0       |
+| T-EXFIL-003   | Medium     | Critical | **Critical** | P0       |
+| T-IMPACT-001  | Medium     | Critical | **High**     | P1       |
+| T-EXEC-002    | High       | High     | **High**     | P1       |
+| T-EXEC-004    | Medium     | High     | **High**     | P1       |
+| T-ACCESS-003  | Medium     | High     | **High**     | P1       |
+| T-EXFIL-001   | Medium     | High     | **High**     | P1       |
+| T-IMPACT-002  | High       | Medium   | **High**     | P1       |
+| T-EVADE-001   | High       | Medium   | **Medium**   | P2       |
+| T-ACCESS-001  | Low        | High     | **Medium**   | P2       |
+| T-ACCESS-002  | Low        | High     | **Medium**   | P2       |
+| T-PERSIST-002 | Low        | High     | **Medium**   | P2       |
+
+### 5.2 Critical Path Attack Chains
+
+**Attack Chain 1: Skill-Based Data Theft**
+
+```
+T-PERSIST-001 → T-EVADE-001 → T-EXFIL-003
+(Publish malicious skill) → (Evade moderation) → (Harvest credentials)
+```
+
+**Attack Chain 2: Prompt Injection to RCE**
+
+```
+T-EXEC-001 → T-EXEC-004 → T-IMPACT-001
+(Inject prompt) → (Bypass exec approval) → (Execute commands)
+```
+
+**Attack Chain 3: Indirect Injection via Fetched Content**
+
+```
+T-EXEC-002 → T-EXFIL-001 → External exfiltration
+(Poison URL content) → (Agent fetches & follows instructions) → (Data sent to attacker)
+```
+
+---
+
+## 6. Recommendations Summary
+
+### 6.1 Immediate (P0)
+
+| ID    | Recommendation                              | Addresses                  |
+| ----- | ------------------------------------------- | -------------------------- |
+| R-001 | Complete VirusTotal integration             | T-PERSIST-001, T-EVADE-001 |
+| R-002 | Implement skill sandboxing                  | T-PERSIST-001, T-EXFIL-003 |
+| R-003 | Add output validation for sensitive actions | T-EXEC-001, T-EXEC-002     |
+
+### 6.2 Short-term (P1)
+
+| ID    | Recommendation                           | Addresses    |
+| ----- | ---------------------------------------- | ------------ |
+| R-004 | Implement rate limiting                  | T-IMPACT-002 |
+| R-005 | Add token encryption at rest             | T-ACCESS-003 |
+| R-006 | Improve exec approval UX and validation  | T-EXEC-004   |
+| R-007 | Implement URL allowlisting for web_fetch | T-EXFIL-001  |
+
+### 6.3 Medium-term (P2)
+
+| ID    | Recommendation                                        | Addresses     |
+| ----- | ----------------------------------------------------- | ------------- |
+| R-008 | Add cryptographic channel verification where possible | T-ACCESS-002  |
+| R-009 | Implement config integrity verification               | T-PERSIST-003 |
+| R-010 | Add update signing and version pinning                | T-PERSIST-002 |
+
+---
+
+## 7. Appendices
+
+### 7.1 ATLAS Technique Mapping
+
+| ATLAS ID      | Technique Name                 | OpenClaw Threats                                                 |
+| ------------- | ------------------------------ | ---------------------------------------------------------------- |
+| AML.T0006     | Active Scanning                | T-RECON-001, T-RECON-002                                         |
+| AML.T0009     | Collection                     | T-EXFIL-001, T-EXFIL-002, T-EXFIL-003                            |
+| AML.T0010.001 | Supply Chain: AI Software      | T-PERSIST-001, T-PERSIST-002                                     |
+| AML.T0010.002 | Supply Chain: Data             | T-PERSIST-003                                                    |
+| AML.T0031     | Erode AI Model Integrity       | T-IMPACT-001, T-IMPACT-002, T-IMPACT-003                         |
+| AML.T0040     | AI Model Inference API Access  | T-ACCESS-001, T-ACCESS-002, T-ACCESS-003, T-DISC-001, T-DISC-002 |
+| AML.T0043     | Craft Adversarial Data         | T-EXEC-004, T-EVADE-001, T-EVADE-002                             |
+| AML.T0051.000 | LLM Prompt Injection: Direct   | T-EXEC-001, T-EXEC-003                                           |
+| AML.T0051.001 | LLM Prompt Injection: Indirect | T-EXEC-002                                                       |
+
+### 7.2 Key Security Files
+
+| Path                                | Purpose                     | Risk Level   |
+| ----------------------------------- | --------------------------- | ------------ |
+| `src/infra/exec-approvals.ts`       | Command approval logic      | **Critical** |
+| `src/gateway/auth.ts`               | Gateway authentication      | **Critical** |
+| `src/web/inbound/access-control.ts` | Channel access control      | **Critical** |
+| `src/infra/net/ssrf.ts`             | SSRF protection             | **Critical** |
+| `src/security/external-content.ts`  | Prompt injection mitigation | **Critical** |
+| `src/agents/sandbox/tool-policy.ts` | Tool policy enforcement     | **Critical** |
+| `convex/lib/moderation.ts`          | ClawHub moderation          | **High**     |
+| `convex/lib/skillPublish.ts`        | Skill publishing flow       | **High**     |
+| `src/routing/resolve-route.ts`      | Session isolation           | **Medium**   |
+
+### 7.3 Glossary
+
+| Term                 | Definition                                                |
+| -------------------- | --------------------------------------------------------- |
+| **ATLAS**            | MITRE's Adversarial Threat Landscape for AI Systems       |
+| **ClawHub**          | OpenClaw's skill marketplace                              |
+| **Gateway**          | OpenClaw's message routing and authentication layer       |
+| **MCP**              | Model Context Protocol - tool provider interface          |
+| **Prompt Injection** | Attack where malicious instructions are embedded in input |
+| **Skill**            | Downloadable extension for OpenClaw agents                |
+| **SSRF**             | Server-Side Request Forgery                               |
+
+---
+
+_This threat model is a living document. Report security issues to security@openclaw.ai_