fix: harden discord forum thread-create (#10062) (thanks @jarvis89757)

* initial commit

* feat: implement deriveSessionTotalTokens function and update usage tests

* Added deriveSessionTotalTokens function to calculate total tokens based on usage and context tokens.
* Updated usage tests to include cases for derived session total tokens.
* Refactored session usage calculations in multiple files to utilize the new function for improved accuracy.

* fix: restore overflow truncation fallback + changelog/test hardening (#11551) (thanks @tyler6204)

.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/workflows/ci.yml

@@ -2,10 +2,34 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
 
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
 jobs:
+  # 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
+
   install-check:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout
@@ -66,6 +90,8 @@ jobs:
           pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
 
   checks:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false
@@ -74,18 +100,12 @@ 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
@@ -156,52 +176,17 @@ jobs:
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
-  secrets:
+  # Lint and format always run, even on docs-only changes.
+  checks-lint:
     runs-on: blacksmith-4vcpu-ubuntu-2404
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: false
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install detect-secrets
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install detect-secrets==1.5.0
-
-      - name: Detect secrets
-        run: |
-          if ! detect-secrets scan --baseline .secrets.baseline; then
-            echo "::error::Secret scanning failed. See docs/gateway/security.md#secret-scanning-detect-secrets"
-            exit 1
-          fi
-
-  checks-windows:
-    runs-on: blacksmith-4vcpu-windows-2025
-    env:
-      NODE_OPTIONS: --max-old-space-size=4096
-      CLAWDBOT_TEST_WORKERS: 1
-    defaults:
-      run:
-        shell: bash
     strategy:
       fail-fast: false
       matrix:
         include:
-          - runtime: node
-            task: build & lint
+          - 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
+          - task: format
+            command: pnpm format
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -266,18 +251,153 @@ jobs:
           pnpm -v
           pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
 
-      - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
+      - name: Run ${{ matrix.task }}
         run: ${{ matrix.command }}
 
-  checks-macos:
-    if: github.event_name == 'pull_request'
-    runs-on: macos-latest
+  secrets:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install detect-secrets
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install detect-secrets==1.5.0
+
+      - name: Detect secrets
+        run: |
+          if ! detect-secrets scan --baseline .secrets.baseline; then
+            echo "::error::Secret scanning failed. See docs/gateway/security.md#secret-scanning-detect-secrets"
+            exit 1
+          fi
+
+  checks-windows:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
+    runs-on: blacksmith-4vcpu-windows-2025
+    env:
+      NODE_OPTIONS: --max-old-space-size=4096
+      # Keep total concurrency predictable on the 4 vCPU runner:
+      # `scripts/test-parallel.mjs` runs some vitest suites in parallel processes.
+      OPENCLAW_TEST_WORKERS: 2
+    defaults:
+      run:
+        shell: bash
     strategy:
       fail-fast: false
       matrix:
         include:
-          - task: test
-            command: pnpm test
+          - runtime: node
+            task: build & 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
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Try to exclude workspace from Windows Defender (best-effort)
+        shell: pwsh
+        run: |
+          $cmd = Get-Command Add-MpPreference -ErrorAction SilentlyContinue
+          if (-not $cmd) {
+            Write-Host "Add-MpPreference not available, skipping Defender exclusions."
+            exit 0
+          }
+
+          try {
+            # Defender sometimes intercepts process spawning (vitest workers). If this fails
+            # (eg hardened images), keep going and rely on worker limiting above.
+            Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE" -ErrorAction Stop
+            Add-MpPreference -ExclusionProcess "node.exe" -ErrorAction Stop
+            Write-Host "Defender exclusions applied."
+          } catch {
+            Write-Warning "Failed to apply Defender exclusions, continuing. $($_.Exception.Message)"
+          }
+
+      - 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 (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 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 }} (${{ matrix.runtime }})
+        run: ${{ matrix.command }}
+
+  # Consolidated macOS job: runs TS tests + Swift lint/build/test sequentially
+  # on a single runner. GitHub limits macOS concurrent jobs to 5 per org;
+  # running 4 separate jobs per PR (as before) starved the queue. One job
+  # per PR allows 5 PRs to run macOS checks simultaneously.
+  macos:
+    needs: [docs-scope]
+    if: github.event_name == 'pull_request' && needs.docs-scope.outputs.docs_only != 'true'
+    runs-on: macos-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -297,6 +417,7 @@ jobs:
           done
           exit 1
 
+      # --- Node/pnpm setup (for TS tests) ---
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
@@ -336,71 +457,20 @@ jobs:
           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 all checks sequentially (fast gates first) ---
+      - name: TS tests (macOS)
         env:
           NODE_OPTIONS: --max-old-space-size=4096
-        run: ${{ matrix.command }}
-
-  macos-app:
-    if: github.event_name == 'pull_request'
-    runs-on: macos-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - task: lint
-            command: |
-              swiftlint --config .swiftlint.yml
-              swiftformat --lint apps/macos/Sources --config .swiftformat
-          - task: build
-            command: |
-              set -euo pipefail
-              for attempt in 1 2 3; do
-                if swift build --package-path apps/macos --configuration release; then
-                  exit 0
-                fi
-                echo "swift build failed (attempt $attempt/3). Retrying…"
-                sleep $((attempt * 20))
-              done
-              exit 1
-          - task: test
-            command: |
-              set -euo pipefail
-              for attempt in 1 2 3; do
-                if swift test --package-path apps/macos --parallel --enable-code-coverage --show-codecov-path; then
-                  exit 0
-                fi
-                echo "swift test failed (attempt $attempt/3). Retrying…"
-                sleep $((attempt * 20))
-              done
-              exit 1
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: false
-
-      - name: 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
+        run: pnpm test
 
+      # --- Xcode/Swift setup ---
       - name: Select Xcode 26.1
         run: |
           sudo xcode-select -s /Applications/Xcode_26.1.app
           xcodebuild -version
 
       - name: Install XcodeGen / SwiftLint / SwiftFormat
-        run: |
-          brew install xcodegen swiftlint swiftformat
+        run: brew install xcodegen swiftlint swiftformat
 
       - name: Show toolchain
         run: |
@@ -408,8 +478,35 @@ jobs:
           xcodebuild -version
           swift --version
 
-      - name: Run ${{ matrix.task }}
-        run: ${{ matrix.command }}
+      - name: Swift lint
+        run: |
+          swiftlint --config .swiftlint.yml
+          swiftformat --lint apps/macos/Sources --config .swiftformat
+
+      - name: Swift build (release)
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if swift build --package-path apps/macos --configuration release; then
+              exit 0
+            fi
+            echo "swift build failed (attempt $attempt/3). Retrying…"
+            sleep $((attempt * 20))
+          done
+          exit 1
+
+      - name: Swift test
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if swift test --package-path apps/macos --parallel --enable-code-coverage --show-codecov-path; then
+              exit 0
+            fi
+            echo "swift test failed (attempt $attempt/3). Retrying…"
+            sleep $((attempt * 20))
+          done
+          exit 1
+
   ios:
     if: false # ignore iOS in CI for now
     runs-on: macos-latest
@@ -584,6 +681,8 @@ jobs:
           PY
 
   android:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false

.github/workflows/formal-conformance.yml

@@ -3,6 +3,10 @@ name: Formal models (informational conformance)
 on:
   pull_request:
 
+concurrency:
+  group: formal-conformance-${{ github.event.pull_request.number || github.ref_name }}
+  cancel-in-progress: true
+
 jobs:
   formal_conformance:
     runs-on: ubuntu-latest

.github/workflows/install-smoke.yml

@@ -6,8 +6,28 @@ on:
   pull_request:
   workflow_dispatch:
 
+concurrency:
+  group: install-smoke-${{ github.event.pull_request.number || github.sha }}
+  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/workflow-sanity.yml

@@ -3,6 +3,11 @@ name: Workflow Sanity
 on:
   pull_request:
   push:
+    branches: [main]
+
+concurrency:
+  group: workflow-sanity-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
 
 jobs:
   no-tabs:

.gitignore

@@ -75,3 +75,4 @@ USER.md
 memory/
 .agent/*.json
 !.agent/workflows/
+local/

.oxlintrc.json

@@ -24,6 +24,7 @@
     "assets/",
     "dist/",
     "docs/_layouts/",
+    "extensions/",
     "node_modules/",
     "patches/",
     "pnpm-lock.yaml/",

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.
+- 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.
+- 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
@@ -10,10 +30,12 @@ Docs: https://docs.openclaw.ai
 - 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.
 - Providers: add xAI (Grok) support. (#9885) Thanks @grp06.
+- Providers: add Baidu Qianfan support. (#8868) Thanks @ide-rea.
 - Web UI: add token usage dashboard. (#10072) Thanks @Takhoffman.
 - Memory: native Voyage AI support. (#7078) Thanks @mcinteerj.
 - Sessions: cap sessions_history payloads to reduce context overflow. (#10000) Thanks @gut-puncture.
 - CLI: sort commands alphabetically in help output. (#8068) Thanks @deepsoumya617.
+- CI: optimize pipeline throughput (macOS consolidation, Windows perf, workflow concurrency). (#10784) Thanks @mcaxtr.
 - Agents: bump pi-mono to 0.52.7; add embedded forward-compat fallback for Opus 4.6 model ids.
 
 ### Added
@@ -26,7 +48,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

Dockerfile

@@ -44,5 +44,5 @@ USER node
 #
 # For container platforms requiring external health checks:
 #   1. Set OPENCLAW_GATEWAY_TOKEN or OPENCLAW_GATEWAY_PASSWORD env var
-#   2. Override CMD: ["node","dist/index.js","gateway","--allow-unconfigured","--bind","lan"]
-CMD ["node", "dist/index.js", "gateway", "--allow-unconfigured"]
+#   2. Override CMD: ["node","openclaw.mjs","gateway","--allow-unconfigured","--bind","lan"]
+CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]

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)
 

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

@@ -17,6 +17,8 @@ the right time, and can optionally deliver output back to a chat.
 If you want _“run this every morning”_ or _“poke the agent in 20 minutes”_,
 cron is the mechanism.
 
+Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
+
 ## TL;DR
 
 - Cron runs **inside the Gateway** (not inside the model).
@@ -462,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/automation/troubleshooting.md

@@ -0,0 +1,122 @@
+---
+summary: "Troubleshoot cron and heartbeat scheduling and delivery"
+read_when:
+  - Cron did not run
+  - Cron ran but no message was delivered
+  - Heartbeat seems silent or skipped
+title: "Automation Troubleshooting"
+---
+
+# Automation troubleshooting
+
+Use this page for scheduler and delivery issues (`cron` + `heartbeat`).
+
+## Command ladder
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then run automation checks:
+
+```bash
+openclaw cron status
+openclaw cron list
+openclaw system heartbeat last
+```
+
+## Cron not firing
+
+```bash
+openclaw cron status
+openclaw cron list
+openclaw cron runs --id <jobId> --limit 20
+openclaw logs --follow
+```
+
+Good output looks like:
+
+- `cron status` reports enabled and a future `nextWakeAtMs`.
+- Job is enabled and has a valid schedule/timezone.
+- `cron runs` shows `ok` or explicit skip reason.
+
+Common signatures:
+
+- `cron: scheduler disabled; jobs will not run automatically` → cron disabled in config/env.
+- `cron: timer tick failed` → scheduler tick crashed; inspect surrounding stack/log context.
+- `reason: not-due` in run output → manual run called without `--force` and job not due yet.
+
+## Cron fired but no delivery
+
+```bash
+openclaw cron runs --id <jobId> --limit 20
+openclaw cron list
+openclaw channels status --probe
+openclaw logs --follow
+```
+
+Good output looks like:
+
+- Run status is `ok`.
+- Delivery mode/target are set for isolated jobs.
+- Channel probe reports target channel connected.
+
+Common signatures:
+
+- Run succeeded but delivery mode is `none` → no external message is expected.
+- Delivery target missing/invalid (`channel`/`to`) → run may succeed internally but skip outbound.
+- Channel auth errors (`unauthorized`, `missing_scope`, `Forbidden`) → delivery blocked by channel credentials/permissions.
+
+## Heartbeat suppressed or skipped
+
+```bash
+openclaw system heartbeat last
+openclaw logs --follow
+openclaw config get agents.defaults.heartbeat
+openclaw channels status --probe
+```
+
+Good output looks like:
+
+- Heartbeat enabled with non-zero interval.
+- Last heartbeat result is `ran` (or skip reason is understood).
+
+Common signatures:
+
+- `heartbeat skipped` with `reason=quiet-hours` → outside `activeHours`.
+- `requests-in-flight` → main lane busy; heartbeat deferred.
+- `empty-heartbeat-file` → `HEARTBEAT.md` exists but has no actionable content.
+- `alerts-disabled` → visibility settings suppress outbound heartbeat messages.
+
+## Timezone and activeHours gotchas
+
+```bash
+openclaw config get agents.defaults.heartbeat.activeHours
+openclaw config get agents.defaults.heartbeat.activeHours.timezone
+openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"
+openclaw cron list
+openclaw logs --follow
+```
+
+Quick rules:
+
+- `Config path not found: agents.defaults.userTimezone` means the key is unset; heartbeat falls back to host timezone (or `activeHours.timezone` if set).
+- Cron without `--tz` uses gateway host timezone.
+- Heartbeat `activeHours` uses configured timezone resolution (`user`, `local`, or explicit IANA tz).
+- ISO timestamps without timezone are treated as UTC for cron `at` schedules.
+
+Common signatures:
+
+- Jobs run at the wrong wall-clock time after host timezone changes.
+- Heartbeat always skipped during your daytime because `activeHours.timezone` is wrong.
+
+Related:
+
+- [/automation/cron-jobs](/automation/cron-jobs)
+- [/gateway/heartbeat](/gateway/heartbeat)
+- [/automation/cron-vs-heartbeat](/automation/cron-vs-heartbeat)
+- [/concepts/timezone](/concepts/timezone)

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
 
@@ -202,6 +202,32 @@ Once verified, the bot can decrypt messages in encrypted rooms.
 | Location        | ✅ Supported (geo URI; altitude ignored)                                              |
 | Native commands | ✅ Supported                                                                          |
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list matrix
+```
+
+Common failures:
+
+- Logged in but room messages ignored: room blocked by `groupPolicy` or room allowlist.
+- DMs ignored: sender pending approval when `channels.matrix.dm.policy="pairing"`.
+- Encrypted rooms fail: crypto support or encryption settings mismatch.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Configuration reference (Matrix)
 
 Full configuration: [Configuration](/gateway/configuration)

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:
@@ -168,6 +168,32 @@ Config:
 - Groups: `signal:group:<groupId>`.
 - Usernames: `username:<name>` (if supported by your Signal account).
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list signal
+```
+
+Common failures:
+
+- Daemon reachable but no replies: verify account/daemon settings (`httpUrl`, `account`) and receive mode.
+- DMs ignored: sender is pending pairing approval.
+- Group messages ignored: group sender/mention gating blocks delivery.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Configuration reference (Signal)
 
 Full configuration: [Configuration](/gateway/configuration)

docs/channels/slack.md

@@ -537,6 +537,32 @@ Slack tool actions can be gated with `channels.slack.actions.*`:
   scopes you expect (`chat:write`, `reactions:write`, `pins:write`,
   `files:write`) or those operations will fail.
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list slack
+```
+
+Common failures:
+
+- Connected but no channel replies: channel blocked by `groupPolicy` or not in `channels.slack.channels` allowlist.
+- DMs ignored: sender not approved when `channels.slack.dm.policy="pairing"`.
+- API errors (`missing_scope`, `not_in_channel`, auth failures): bot/app tokens or Slack scopes are incomplete.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Notes
 
 - Mention gating is controlled via `channels.slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions.

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/troubleshooting.md

@@ -1,30 +1,116 @@
 ---
-summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp/iMessage)"
+summary: "Fast channel level troubleshooting with per channel failure signatures and fixes"
 read_when:
-  - A channel connects but messages don’t flow
-  - Investigating channel misconfiguration (intents, permissions, privacy mode)
+  - Channel transport says connected but replies fail
+  - You need channel specific checks before deep provider docs
 title: "Channel Troubleshooting"
 ---
 
 # Channel troubleshooting
 
-Start with:
+Use this page when a channel connects but behavior is wrong.
+
+## Command ladder
+
+Run these in order first:
 
 ```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
 openclaw doctor
 openclaw channels status --probe
 ```
 
-`channels status --probe` prints warnings when it can detect common channel misconfigurations, and includes small live checks (credentials, some permissions/membership).
+Healthy baseline:
 
-## Channels
+- `Runtime: running`
+- `RPC probe: ok`
+- Channel probe shows connected/ready
 
-- Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
-- Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
-- WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
-- iMessage (legacy): [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
+## WhatsApp
 
-## Telegram quick fixes
+### WhatsApp failure signatures
 
-- Logs show `HttpError: Network request for 'sendMessage' failed` or `sendChatAction` → check IPv6 DNS. If `api.telegram.org` resolves to IPv6 first and the host lacks IPv6 egress, force IPv4 or enable IPv6. See [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting).
-- Logs show `setMyCommands failed` → check outbound HTTPS and DNS reachability to `api.telegram.org` (common on locked-down VPS or proxies).
+| Symptom                         | Fastest check                                       | Fix                                                     |
+| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
+| Connected but no DM replies     | `openclaw pairing list whatsapp`                    | Approve sender or switch DM policy/allowlist.           |
+| Group messages ignored          | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. |
+| Random disconnect/relogin loops | `openclaw channels status --probe` + logs           | Re-login and verify credentials directory is healthy.   |
+
+Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
+
+## Telegram
+
+### Telegram failure signatures
+
+| Symptom                           | Fastest check                                   | Fix                                                       |
+| --------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
+| `/start` but no usable reply flow | `openclaw pairing list telegram`                | Approve pairing or change DM policy.                      |
+| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. |
+| Send failures with network errors | Inspect logs for Telegram API call failures     | Fix DNS/IPv6/proxy routing to `api.telegram.org`.         |
+
+Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
+
+## Discord
+
+### Discord failure signatures
+
+| Symptom                         | Fastest check                       | Fix                                                       |
+| ------------------------------- | ----------------------------------- | --------------------------------------------------------- |
+| Bot online but no guild replies | `openclaw channels status --probe`  | Allow guild/channel and verify message content intent.    |
+| Group messages ignored          | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. |
+| DM replies missing              | `openclaw pairing list discord`     | Approve DM pairing or adjust DM policy.                   |
+
+Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
+
+## Slack
+
+### Slack failure signatures
+
+| Symptom                                | Fastest check                             | Fix                                               |
+| -------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
+| Socket mode connected but no responses | `openclaw channels status --probe`        | Verify app token + bot token and required scopes. |
+| DMs blocked                            | `openclaw pairing list slack`             | Approve pairing or relax DM policy.               |
+| Channel message ignored                | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`.     |
+
+Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
+
+## iMessage and BlueBubbles
+
+### iMessage and BlueBubbles failure signatures
+
+| Symptom                          | Fastest check                                                           | Fix                                                   |
+| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
+| No inbound events                | Verify webhook/server reachability and app permissions                  | Fix webhook URL or BlueBubbles server state.          |
+| Can send but no receive on macOS | Check macOS privacy permissions for Messages automation                 | Re-grant TCC permissions and restart channel process. |
+| DM sender blocked                | `openclaw pairing list imessage` or `openclaw pairing list bluebubbles` | Approve pairing or update allowlist.                  |
+
+Full troubleshooting:
+
+- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
+- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
+
+## Signal
+
+### Signal failure signatures
+
+| Symptom                         | Fastest check                              | Fix                                                      |
+| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
+| Daemon reachable but bot silent | `openclaw channels status --probe`         | Verify `signal-cli` daemon URL/account and receive mode. |
+| DM blocked                      | `openclaw pairing list signal`             | Approve sender or adjust DM policy.                      |
+| Group replies do not trigger    | Check group allowlist and mention patterns | Add sender/group or loosen gating.                       |
+
+Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
+
+## Matrix
+
+### Matrix failure signatures
+
+| Symptom                             | Fastest check                                | Fix                                             |
+| ----------------------------------- | -------------------------------------------- | ----------------------------------------------- |
+| Logged in but ignores room messages | `openclaw channels status --probe`           | Check `groupPolicy` and room allowlist.         |
+| DMs do not process                  | `openclaw pairing list matrix`               | Approve sender or adjust DM policy.             |
+| Encrypted rooms fail                | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. |
+
+Full troubleshooting: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting)

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"
@@ -98,6 +90,10 @@
       "source": "/opencode",
       "destination": "/providers/opencode"
     },
+    {
+      "source": "/qianfan",
+      "destination": "/providers/qianfan"
+    },
     {
       "source": "/mattermost",
       "destination": "/channels/mattermost"
@@ -352,11 +348,11 @@
     },
     {
       "source": "/group-messages",
-      "destination": "/concepts/group-messages"
+      "destination": "/channels/group-messages"
     },
     {
       "source": "/groups",
-      "destination": "/concepts/groups"
+      "destination": "/channels/groups"
     },
     {
       "source": "/health",
@@ -482,6 +478,14 @@
       "source": "/model-failover",
       "destination": "/concepts/model-failover"
     },
+    {
+      "source": "/model",
+      "destination": "/models"
+    },
+    {
+      "source": "/model/",
+      "destination": "/models"
+    },
     {
       "source": "/models",
       "destination": "/concepts/models"
@@ -504,7 +508,7 @@
     },
     {
       "source": "/pairing",
-      "destination": "/start/pairing"
+      "destination": "/channels/pairing"
     },
     {
       "source": "/plans/cron-add-hardening",
@@ -528,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",
@@ -660,11 +664,11 @@
     },
     {
       "source": "/troubleshooting",
-      "destination": "/gateway/troubleshooting"
+      "destination": "/help/troubleshooting"
     },
     {
-      "source": "/web/tui",
-      "destination": "/tui"
+      "source": "/tui",
+      "destination": "/web/tui"
     },
     {
       "source": "/typebox",
@@ -718,9 +722,13 @@
       "source": "/oauth",
       "destination": "/concepts/oauth"
     },
+    {
+      "source": "/plugin",
+      "destination": "/tools/plugin"
+    },
     {
       "source": "/plugins",
-      "destination": "/plugin"
+      "destination": "/tools/plugin"
     },
     {
       "source": "/railway",
@@ -779,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",
@@ -857,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"
                 ]
@@ -880,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": [
@@ -941,37 +960,44 @@
               },
               {
                 "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",
                   "automation/webhook",
                   "automation/gmail-pubsub",
                   "automation/poll",
                   "automation/auth-monitoring"
                 ]
               },
+              {
+                "group": "Hooks",
+                "pages": ["hooks/soul-evil"]
+              },
               {
                 "group": "Media and devices",
                 "pages": [
                   "nodes/index",
+                  "nodes/troubleshooting",
                   "nodes/images",
                   "nodes/audio",
                   "nodes/camera",
@@ -987,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",
@@ -999,14 +1029,15 @@
                   "providers/anthropic",
                   "providers/openai",
                   "providers/openrouter",
-                  "bedrock",
+                  "providers/bedrock",
                   "providers/vercel-ai-gateway",
                   "providers/moonshot",
                   "providers/minimax",
                   "providers/opencode",
                   "providers/glm",
                   "providers/zai",
-                  "providers/synthetic"
+                  "providers/synthetic",
+                  "providers/qianfan"
                 ]
               }
             ]
@@ -1113,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"]
               }
             ]
           },
@@ -1181,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"
                 ]
               },
               {
@@ -1214,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",
@@ -1241,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": "第一步",
@@ -1269,7 +1315,6 @@
               {
                 "group": "安装方式",
                 "pages": [
-                  "zh-CN/install/node",
                   "zh-CN/install/docker",
                   "zh-CN/install/nix",
                   "zh-CN/install/ansible",
@@ -1333,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"
                 ]
@@ -1359,6 +1404,10 @@
                   "zh-CN/concepts/oauth"
                 ]
               },
+              {
+                "group": "引导",
+                "pages": ["zh-CN/start/bootstrapping"]
+              },
               {
                 "group": "会话与记忆",
                 "pages": [
@@ -1419,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",
@@ -1466,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": "配置",
@@ -1482,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"
                 ]
               }
             ]
@@ -1605,7 +1662,7 @@
                   "zh-CN/web/control-ui",
                   "zh-CN/web/dashboard",
                   "zh-CN/web/webchat",
-                  "zh-CN/tui"
+                  "zh-CN/web/tui"
                 ]
               }
             ]
@@ -1674,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"
                 ]
               },
               {
@@ -1707,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):
@@ -1453,7 +1453,7 @@ working directory). The path must exist to be used.
 
 ### `agents.defaults.skipBootstrap`
 
-Disables automatic creation of the workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, and `BOOTSTRAP.md`).
+Disables automatic creation of the workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, and `BOOTSTRAP.md`).
 
 Use this for pre-seeded deployments where your workspace files come from a repo.
 
@@ -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

@@ -13,6 +13,8 @@ title: "Heartbeat"
 Heartbeat runs **periodic agent turns** in the main session so the model can
 surface anything that needs attention without spamming you.
 
+Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
+
 ## Quick start (beginner)
 
 1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence.
@@ -198,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/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

@@ -1,98 +1,265 @@
 ---
-summary: "Troubleshooting hub: symptoms → checks → fixes"
+summary: "Symptom first troubleshooting hub for OpenClaw"
 read_when:
-  - You see an error and want the fix path
-  - The installer says “success” but the CLI doesn’t work
+  - OpenClaw is not working and you need the fastest path to a fix
+  - You want a triage flow before diving into deep runbooks
 title: "Troubleshooting"
 ---
 
 # Troubleshooting
 
+If you only have 2 minutes, use this page as a triage front door.
+
 ## First 60 seconds
 
-Run these in order:
+Run this exact ladder in order:
 
 ```bash
 openclaw status
 openclaw status --all
 openclaw gateway probe
-openclaw logs --follow
+openclaw gateway status
 openclaw doctor
+openclaw channels status --probe
+openclaw logs --follow
 ```
 
-If the gateway is reachable, deep probes:
+Good output in one line:
 
-```bash
-openclaw status --deep
+- `openclaw status` → shows configured channels and no obvious auth errors.
+- `openclaw status --all` → full report is present and shareable.
+- `openclaw gateway probe` → expected gateway target is reachable.
+- `openclaw gateway status` → `Runtime: running` and `RPC probe: ok`.
+- `openclaw doctor` → no blocking config/service errors.
+- `openclaw channels status --probe` → channels report `connected` or `ready`.
+- `openclaw logs --follow` → steady activity, no repeating fatal errors.
+
+## Decision tree
+
+```mermaid
+flowchart TD
+  A[OpenClaw is not working] --> B{What breaks first}
+  B --> C[No replies]
+  B --> D[Dashboard or Control UI will not connect]
+  B --> E[Gateway will not start or service not running]
+  B --> F[Channel connects but messages do not flow]
+  B --> G[Cron or heartbeat did not fire or did not deliver]
+  B --> H[Node is paired but camera canvas screen exec fails]
+  B --> I[Browser tool fails]
+
+  C --> C1[/No replies section/]
+  D --> D1[/Control UI section/]
+  E --> E1[/Gateway section/]
+  F --> F1[/Channel flow section/]
+  G --> G1[/Automation section/]
+  H --> H1[/Node tools section/]
+  I --> I1[/Browser section/]
 ```
 
-## Common “it broke” cases
+<AccordionGroup>
+  <Accordion title="No replies">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw channels status --probe
+    openclaw pairing list <channel>
+    openclaw logs --follow
+    ```
 
-### `openclaw: command not found`
+    Good output looks like:
 
-Almost always a Node/npm PATH issue. Start here:
+    - `Runtime: running`
+    - `RPC probe: ok`
+    - Your channel shows connected/ready in `channels status --probe`
+    - Sender appears approved (or DM policy is open/allowlist)
 
-- [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity)
+    Common log signatures:
 
-### Installer fails (or you need full logs)
+    - `drop guild message (mention required` → mention gating blocked the message in Discord.
+    - `pairing request` → sender is unapproved and waiting for DM pairing approval.
+    - `blocked` / `allowlist` in channel logs → sender, room, or group is filtered.
 
-Re-run the installer in verbose mode to see the full trace and npm output:
+    Deep pages:
 
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
-```
+    - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
+    - [/channels/troubleshooting](/channels/troubleshooting)
+    - [/channels/pairing](/channels/pairing)
 
-For beta installs:
+  </Accordion>
 
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
-```
+  <Accordion title="Dashboard or Control UI will not connect">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw logs --follow
+    openclaw doctor
+    openclaw channels status --probe
+    ```
 
-You can also set `OPENCLAW_VERBOSE=1` instead of the flag.
+    Good output looks like:
 
-### Gateway “unauthorized”, can’t connect, or keeps reconnecting
+    - `Dashboard: http://...` is shown in `openclaw gateway status`
+    - `RPC probe: ok`
+    - No auth loop in logs
 
-- [Gateway troubleshooting](/gateway/troubleshooting)
-- [Gateway authentication](/gateway/authentication)
+    Common log signatures:
 
-### Control UI fails on HTTP (device identity required)
+    - `device identity required` → HTTP/non-secure context cannot complete device auth.
+    - `unauthorized` / reconnect loop → wrong token/password or auth mode mismatch.
+    - `gateway connect failed:` → UI is targeting the wrong URL/port or unreachable gateway.
 
-- [Gateway troubleshooting](/gateway/troubleshooting)
-- [Control UI](/web/control-ui#insecure-http)
+    Deep pages:
 
-### `docs.openclaw.ai` shows an SSL error (Comcast/Xfinity)
+    - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
+    - [/web/control-ui](/web/control-ui)
+    - [/gateway/authentication](/gateway/authentication)
 
-Some Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security.
-Disable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry.
+  </Accordion>
 
-- Xfinity Advanced Security help: [https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security](https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security)
-- Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering
+  <Accordion title="Gateway will not start or service installed but not running">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw logs --follow
+    openclaw doctor
+    openclaw channels status --probe
+    ```
 
-### Service says running, but RPC probe fails
+    Good output looks like:
 
-- [Gateway troubleshooting](/gateway/troubleshooting)
-- [Background process / service](/gateway/background-process)
+    - `Service: ... (loaded)`
+    - `Runtime: running`
+    - `RPC probe: ok`
 
-### Model/auth failures (rate limit, billing, “all models failed”)
+    Common log signatures:
 
-- [Models](/cli/models)
-- [OAuth / auth concepts](/concepts/oauth)
+    - `Gateway start blocked: set gateway.mode=local` → gateway mode is unset/remote.
+    - `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
+    - `another gateway instance is already listening` or `EADDRINUSE` → port already taken.
 
-### `/model` says `model not allowed`
+    Deep pages:
 
-This usually means `agents.defaults.models` is configured as an allowlist. When it’s non-empty,
-only those provider/model keys can be selected.
+    - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
+    - [/gateway/background-process](/gateway/background-process)
+    - [/gateway/configuration](/gateway/configuration)
 
-- Check the allowlist: `openclaw config get agents.defaults.models`
-- Add the model you want (or clear the allowlist) and retry `/model`
-- Use `/models` to browse the allowed providers/models
+  </Accordion>
 
-### When filing an issue
+  <Accordion title="Channel connects but messages do not flow">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw logs --follow
+    openclaw doctor
+    openclaw channels status --probe
+    ```
 
-Paste a safe report:
+    Good output looks like:
 
-```bash
-openclaw status --all
-```
+    - Channel transport is connected.
+    - Pairing/allowlist checks pass.
+    - Mentions are detected where required.
 
-If you can, include the relevant log tail from `openclaw logs --follow`.
+    Common log signatures:
+
+    - `mention required` → group mention gating blocked processing.
+    - `pairing` / `pending` → DM sender is not approved yet.
+    - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → channel permission token issue.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
+    - [/channels/troubleshooting](/channels/troubleshooting)
+
+  </Accordion>
+
+  <Accordion title="Cron or heartbeat did not fire or did not deliver">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw cron status
+    openclaw cron list
+    openclaw cron runs --id <jobId> --limit 20
+    openclaw logs --follow
+    ```
+
+    Good output looks like:
+
+    - `cron.status` shows enabled with a next wake.
+    - `cron runs` shows recent `ok` entries.
+    - Heartbeat is enabled and not outside active hours.
+
+    Common log signatures:
+
+    - `cron: scheduler disabled; jobs will not run automatically` → cron is disabled.
+    - `heartbeat skipped` with `reason=quiet-hours` → outside configured active hours.
+    - `requests-in-flight` → main lane busy; heartbeat wake was deferred.
+    - `unknown accountId` → heartbeat delivery target account does not exist.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
+    - [/automation/troubleshooting](/automation/troubleshooting)
+    - [/gateway/heartbeat](/gateway/heartbeat)
+
+  </Accordion>
+
+  <Accordion title="Node is paired but tool fails camera canvas screen exec">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw nodes status
+    openclaw nodes describe --node <idOrNameOrIp>
+    openclaw logs --follow
+    ```
+
+    Good output looks like:
+
+    - Node is listed as connected and paired for role `node`.
+    - Capability exists for the command you are invoking.
+    - Permission state is granted for the tool.
+
+    Common log signatures:
+
+    - `NODE_BACKGROUND_UNAVAILABLE` → bring node app to foreground.
+    - `*_PERMISSION_REQUIRED` → OS permission was denied/missing.
+    - `SYSTEM_RUN_DENIED: approval required` → exec approval is pending.
+    - `SYSTEM_RUN_DENIED: allowlist miss` → command not on exec allowlist.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
+    - [/nodes/troubleshooting](/nodes/troubleshooting)
+    - [/tools/exec-approvals](/tools/exec-approvals)
+
+  </Accordion>
+
+  <Accordion title="Browser tool fails">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw browser status
+    openclaw logs --follow
+    openclaw doctor
+    ```
+
+    Good output looks like:
+
+    - Browser status shows `running: true` and a chosen browser/profile.
+    - `openclaw` profile starts or `chrome` relay has an attached tab.
+
+    Common log signatures:
+
+    - `Failed to start Chrome CDP on port` → local browser launch failed.
+    - `browser.executablePath not found` → configured binary path is wrong.
+    - `Chrome extension relay is running, but no tab is connected` → extension not attached.
+    - `Browser attachOnly is enabled ... not reachable` → attach-only profile has no live CDP target.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
+    - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
+    - [/tools/chrome-extension](/tools/chrome-extension)
+
+  </Accordion>
+</AccordionGroup>

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/nodes/index.md

@@ -19,6 +19,7 @@ Notes:
 
 - Nodes are **peripherals**, not gateways. They don’t run the gateway service.
 - Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes.
+- Troubleshooting runbook: [/nodes/troubleshooting](/nodes/troubleshooting)
 
 ## Pairing + status
 

docs/nodes/troubleshooting.md

@@ -0,0 +1,112 @@
+---
+summary: "Troubleshoot node pairing, foreground requirements, permissions, and tool failures"
+read_when:
+  - Node is connected but camera/canvas/screen/exec tools fail
+  - You need the node pairing versus approvals mental model
+title: "Node Troubleshooting"
+---
+
+# Node troubleshooting
+
+Use this page when a node is visible in status but node tools fail.
+
+## Command ladder
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then run node specific checks:
+
+```bash
+openclaw nodes status
+openclaw nodes describe --node <idOrNameOrIp>
+openclaw approvals get --node <idOrNameOrIp>
+```
+
+Healthy signals:
+
+- Node is connected and paired for role `node`.
+- `nodes describe` includes the capability you are calling.
+- Exec approvals show expected mode/allowlist.
+
+## Foreground requirements
+
+`canvas.*`, `camera.*`, and `screen.*` are foreground only on iOS/Android nodes.
+
+Quick check and fix:
+
+```bash
+openclaw nodes describe --node <idOrNameOrIp>
+openclaw nodes canvas snapshot --node <idOrNameOrIp>
+openclaw logs --follow
+```
+
+If you see `NODE_BACKGROUND_UNAVAILABLE`, bring the node app to the foreground and retry.
+
+## Permissions matrix
+
+| Capability                   | iOS                                     | Android                                      | macOS node app                | Typical failure code           |
+| ---------------------------- | --------------------------------------- | -------------------------------------------- | ----------------------------- | ------------------------------ |
+| `camera.snap`, `camera.clip` | Camera (+ mic for clip audio)           | Camera (+ mic for clip audio)                | Camera (+ mic for clip audio) | `*_PERMISSION_REQUIRED`        |
+| `screen.record`              | Screen Recording (+ mic optional)       | Screen capture prompt (+ mic optional)       | Screen Recording              | `*_PERMISSION_REQUIRED`        |
+| `location.get`               | While Using or Always (depends on mode) | Foreground/Background location based on mode | Location permission           | `LOCATION_PERMISSION_REQUIRED` |
+| `system.run`                 | n/a (node host path)                    | n/a (node host path)                         | Exec approvals required       | `SYSTEM_RUN_DENIED`            |
+
+## Pairing versus approvals
+
+These are different gates:
+
+1. **Device pairing**: can this node connect to the gateway?
+2. **Exec approvals**: can this node run a specific shell command?
+
+Quick checks:
+
+```bash
+openclaw devices list
+openclaw nodes status
+openclaw approvals get --node <idOrNameOrIp>
+openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
+```
+
+If pairing is missing, approve the node device first.
+If pairing is fine but `system.run` fails, fix exec approvals/allowlist.
+
+## Common node error codes
+
+- `NODE_BACKGROUND_UNAVAILABLE` → app is backgrounded; bring it foreground.
+- `CAMERA_DISABLED` → camera toggle disabled in node settings.
+- `*_PERMISSION_REQUIRED` → OS permission missing/denied.
+- `LOCATION_DISABLED` → location mode is off.
+- `LOCATION_PERMISSION_REQUIRED` → requested location mode not granted.
+- `LOCATION_BACKGROUND_UNAVAILABLE` → app is backgrounded but only While Using permission exists.
+- `SYSTEM_RUN_DENIED: approval required` → exec request needs explicit approval.
+- `SYSTEM_RUN_DENIED: allowlist miss` → command blocked by allowlist mode.
+
+## Fast recovery loop
+
+```bash
+openclaw nodes status
+openclaw nodes describe --node <idOrNameOrIp>
+openclaw approvals get --node <idOrNameOrIp>
+openclaw logs --follow
+```
+
+If still stuck:
+
+- Re-approve device pairing.
+- Re-open node app (foreground).
+- Re-grant OS permissions.
+- Recreate/adjust exec approval policy.
+
+Related:
+
+- [/nodes/index](/nodes/index)
+- [/nodes/camera](/nodes/camera)
+- [/nodes/location-command](/nodes/location-command)
+- [/tools/exec-approvals](/tools/exec-approvals)
+- [/gateway/pairing](/gateway/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,13 +43,14 @@ 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)
 - [MiniMax](/providers/minimax)
 - [Venice (Venice AI, privacy-focused)](/providers/venice)
 - [Ollama (local models)](/providers/ollama)
+- [Qianfan](/providers/qianfan)
 
 ## Transcription providers
 

docs/providers/models.md

@@ -45,7 +45,8 @@ 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,
 see [Model providers](/concepts/model-providers).

docs/providers/qianfan.md

@@ -0,0 +1,38 @@
+---
+summary: "Use Qianfan's unified API to access many models in OpenClaw"
+read_when:
+  - You want a single API key for many LLMs
+  - You need Baidu Qianfan setup guidance
+title: "Qianfan"
+---
+
+# Qianfan Provider Guide
+
+Qianfan is Baidu's MaaS platform, provides a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+## Prerequisites
+
+1. A Baidu Cloud account with Qianfan API access
+2. An API key from the Qianfan console
+3. OpenClaw installed on your system
+
+## Getting Your API Key
+
+1. Visit the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey)
+2. Create a new application or select an existing one
+3. Generate an API key (format: `bce-v3/ALTAK-...`)
+4. Copy the API key for use with OpenClaw
+
+## CLI setup
+
+```bash
+openclaw onboard --auth-choice qianfan-api-key
+```
+
+## Related Documentation
+
+- [OpenClaw Configuration](/gateway/configuration)
+- [Model Providers](/concepts/model-providers)
+- [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/AGENTS.default.md

@@ -110,7 +110,6 @@ git commit -m "Add Clawd workspace"
 - **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
 - **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
 - **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
-- **bird** — X/Twitter CLI to tweet, reply, read threads, and search without a browser.
 - **agent-tools** — Utility toolkit for automations and helper scripts.
 
 ## Usage Notes

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/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/reference/wizard.md

@@ -35,6 +35,7 @@ For a high-level overview, see [Onboarding Wizard](/start/wizard).
     - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
       - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
     - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it.
+    - **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider.
     - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth).
     - **API key**: stores the key for you.
     - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.

docs/start/docs-directory.md

@@ -19,7 +19,7 @@ For a complete map of the docs, see [Docs hubs](/start/hubs).
 - [Slash commands](/tools/slash-commands)
 - [Multi-agent routing](/concepts/multi-agent)
 - [Updating and rollback](/install/updating)
-- [Pairing (DM and nodes)](/start/pairing)
+- [Pairing (DM and nodes)](/channels/pairing)
 - [Nix mode](/install/nix)
 - [OpenClaw assistant setup](/start/openclaw)
 - [Skills](/tools/skills)
@@ -41,8 +41,8 @@ For a complete map of the docs, see [Docs hubs](/start/hubs).
 - [Mattermost (plugin)](/channels/mattermost)
 - [BlueBubbles (iMessage)](/channels/bluebubbles)
 - [iMessage (legacy)](/channels/imessage)
-- [Groups](/concepts/groups)
-- [WhatsApp group messages](/concepts/group-messages)
+- [Groups](/channels/groups)
+- [WhatsApp group messages](/channels/group-messages)
 - [Media images](/nodes/images)
 - [Media audio](/nodes/audio)
 

docs/start/getting-started.md

@@ -115,6 +115,6 @@ If the Control UI loads, your Gateway is ready for use.
 
 ## Next steps
 
-- DM safety and approvals: [Pairing](/start/pairing)
+- DM safety and approvals: [Pairing](/channels/pairing)
 - Connect more channels: [Channels](/channels)
 - Advanced workflows and from source: [Setup](/start/setup)

docs/start/hubs.md

@@ -61,9 +61,9 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Presence](/concepts/presence)
 - [Discovery + transports](/gateway/discovery)
 - [Bonjour](/gateway/bonjour)
-- [Channel routing](/concepts/channel-routing)
-- [Groups](/concepts/groups)
-- [Group messages](/concepts/group-messages)
+- [Channel routing](/channels/channel-routing)
+- [Groups](/channels/groups)
+- [Group messages](/channels/group-messages)
 - [Model failover](/concepts/model-failover)
 - [OAuth](/concepts/oauth)
 
@@ -118,7 +118,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Models](/concepts/models)
 - [Sub-agents](/tools/subagents)
 - [Agent send CLI](/tools/agent-send)
-- [Terminal UI](/tui)
+- [Terminal UI](/web/tui)
 - [Browser control](/tools/browser)
 - [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting)
 - [Polls](/automation/poll)

docs/start/openclaw.md

@@ -80,7 +80,7 @@ When onboarding finishes, we auto-open the dashboard and print a clean (non-toke
 
 OpenClaw reads operating instructions and “memory” from its workspace directory.
 
-By default, OpenClaw uses `~/.openclaw/workspace` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it).
+By default, OpenClaw uses `~/.openclaw/workspace` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it). `MEMORY.md` is optional (not auto-created); when present, it is loaded for normal sessions. Subagent sessions only inject `AGENTS.md` and `TOOLS.md`.
 
 Tip: treat this folder like OpenClaw’s “memory” and make it a git repo (ideally private) so your `AGENTS.md` + memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.
 

docs/start/wizard-cli-reference.md

@@ -145,6 +145,9 @@ What you set:
     Sets `agents.defaults.model` to `openai/gpt-5.1-codex` when model is unset, `openai/*`, or `openai-codex/*`.
 
   </Accordion>
+  <Accordion title="xAI (Grok) API key">
+    Prompts for `XAI_API_KEY` and configures xAI as a model provider.
+  </Accordion>
   <Accordion title="OpenCode Zen">
     Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`).
     Setup URL: [opencode.ai/auth](https://opencode.ai/auth).

docs/tools/browser-login.md

@@ -34,8 +34,7 @@ If you have multiple profiles, pass `--browser-profile <name>` (the default is `
 
 ## X/Twitter: recommended flow
 
-- **Read/search/threads:** use the **bird** CLI skill (no browser, stable).
-  - Repo: [https://github.com/steipete/bird](https://github.com/steipete/bird)
+- **Read/search/threads:** use the **host** browser (manual login).
 - **Post updates:** use the **host** browser (manual login).
 
 ## Sandboxing + host browser access

docs/tools/exec-approvals.md

@@ -102,7 +102,7 @@ Legacy `agents.default` entries are migrated to `agents.main` on load.
 
 Examples:
 
-- `~/Projects/**/bin/bird`
+- `~/Projects/**/bin/peekaboo`
 - `~/.local/bin/*`
 - `/opt/homebrew/bin/rg`
 

docs/tools/index.md

@@ -166,7 +166,7 @@ Example (allow only file tools + browser):
 ## Plugins + tools
 
 Plugins can register **additional tools** (and CLI commands) beyond the core set.
-See [Plugins](/plugin) for install + config, and [Skills](/tools/skills) for how
+See [Plugins](/tools/plugin) for install + config, and [Skills](/tools/skills) for how
 tool usage guidance is injected into prompts. Some plugins ship their own skills
 alongside tools (for example, the voice-call plugin).
 
@@ -406,7 +406,7 @@ Core actions:
 Notes:
 
 - `add` expects a full cron job object (same schema as `cron.add` RPC).
-- `update` uses `{ id, patch }`.
+- `update` uses `{ jobId, patch }` (`id` accepted for compatibility).
 
 ### `gateway`
 

docs/tools/lobster.md

@@ -331,7 +331,7 @@ OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep,
 
 ## Learn more
 
-- [Plugins](/plugin)
+- [Plugins](/tools/plugin)
 - [Plugin tool authoring](/plugins/agent-tools)
 
 ## Case study: community workflows