Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

docs/.generated/README.md

@@ -0,0 +1,21 @@
+# Generated Docs Artifacts
+
+SHA-256 hash files are the tracked drift-detection artifacts. The full JSON
+baselines are generated locally (gitignored) for inspection only.
+
+**Tracked (committed to git):**
+
+- `config-baseline.sha256` — hashes of config baseline JSON artifacts.
+- `plugin-sdk-api-baseline.sha256` — hashes of Plugin SDK API baseline artifacts.
+
+**Local only (gitignored):**
+
+- `config-baseline.json`, `config-baseline.core.json`, `config-baseline.channel.json`, `config-baseline.plugin.json`
+- `plugin-sdk-api-baseline.json`, `plugin-sdk-api-baseline.jsonl`
+
+Do not edit any of these files by hand.
+
+- Regenerate config baseline: `pnpm config:docs:gen`
+- Validate config baseline: `pnpm config:docs:check`
+- Regenerate Plugin SDK API baseline: `pnpm plugin-sdk:api:gen`
+- Validate Plugin SDK API baseline: `pnpm plugin-sdk:api:check`

docs/.generated/config-baseline.sha256

@@ -0,0 +1,4 @@
+acdf418738f79d29f58cb6cfe5b7ab2d353cbcce2252861a4f527f85ea0c54af  config-baseline.json
+4c98c716bc78e65c274ec374757357c1dcc9b5ec75c9e00ea4c20851531b7d1a  config-baseline.core.json
+c68853362689981ac1cc1e55b9061286c2002104ff1c10bc44ee99a6080e169e  config-baseline.channel.json
+859aa272b0dad53b7080c6fefcf775347ae79a1998ec39dd18b732c90d9df90c  config-baseline.plugin.json

docs/.generated/plugin-sdk-api-baseline.sha256

@@ -0,0 +1,2 @@
+6648558dcec4765bcb21a0837b3c19331129636b55741280ccc2837df9c03579  plugin-sdk-api-baseline.json
+c86d4ddbfc2e5842d87796dc06454fbf3ccf61f851417c38553f98dbf6f49279  plugin-sdk-api-baseline.jsonl

docs/.i18n/README.md

@@ -0,0 +1,81 @@
+# OpenClaw docs i18n assets
+
+This folder stores translation config for the source docs repo.
+
+Generated locale trees and live translation memory now live in the publish repo:
+
+- repo: `openclaw/docs`
+- local checkout: `~/Projects/openclaw-docs`
+
+## Source of truth
+
+- English docs are authored in `openclaw/openclaw`.
+- The source docs tree lives under `docs/`.
+- The source repo no longer keeps committed generated locale trees such as `docs/zh-CN/**`, `docs/zh-TW/**`, `docs/ja-JP/**`, `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/hi/**`, `docs/ar/**`, `docs/it/**`, `docs/vi/**`, `docs/nl/**`, `docs/fa/**`, `docs/ru/**`, `docs/tr/**`, `docs/uk/**`, `docs/id/**`, `docs/pl/**`, or `docs/th/**`.
+
+## End-to-end flow
+
+1. Edit English docs in `openclaw/openclaw`.
+2. Push to `main`.
+3. `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` mirrors the docs tree into `openclaw/docs`.
+4. The sync script rewrites the publish `docs/docs.json` so the generated locale picker blocks exist there even though they are no longer committed in the source repo.
+5. `openclaw/docs/.github/workflows/translate-all.yml` waits for `main` to settle, translates only stale or missing locale pages, and uploads per-locale artifacts.
+6. The publish repo finalizer applies successful locale artifacts and pushes one aggregate `chore(i18n): refresh translations` commit.
+7. A weekly `full` run reconciles every locale/page path so flaky model failures are retried without making hot docs commits wait.
+
+## Why the split exists
+
+- Keep generated locale output out of the main product repo.
+- Keep Mintlify on a single published docs tree.
+- Preserve the built-in language switcher for Mintlify-supported generated locales by letting the publish repo own generated locale trees.
+- Keep generated Thai (`th`) and Persian (`fa`) docs plus translation memory even though Mintlify does not currently accept those codes in `navigation.languages`. Their absence from the built-in docs language picker is a host limitation, not a failed translation run.
+
+## Locale visibility
+
+- Control UI supports `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `hi`, `ar`, `it`, `vi`, `nl`, `fa`, `ru`, `tr`, `uk`, `id`, `pl`, and `th`.
+- Docs translation workflows generate the same non-English locale set in `openclaw/docs`.
+- The Mintlify docs language picker can expose only the locales accepted by Mintlify `navigation.languages`; Russian (`ru`) and Hindi (`hi`) are now included in the publish configuration.
+- Do not treat locale visibility in generated `docs/docs.json` as proof that translation artifacts exist. Verify each generated locale folder and its translation memory in `openclaw/docs`.
+
+## Files in this folder
+
+- `glossary.<lang>.json` — preferred term mappings used as prompt guidance.
+- `zh-Hans-navigation.json` — curated zh-Hans Mintlify locale navigation reinserted into the publish repo during sync.
+- `ar-navigation.json`, `de-navigation.json`, `es-navigation.json`, `fr-navigation.json`, `id-navigation.json`, `it-navigation.json`, `ja-navigation.json`, `ko-navigation.json`, `pl-navigation.json`, `pt-BR-navigation.json`, and `tr-navigation.json` — starter locale metadata kept alongside the source repo, but the publish sync now clones the full English nav tree for clone-en locales so translated pages are visible in Mintlify without hand-maintaining per-locale nav JSON.
+- `<lang>.tm.jsonl` — translation memory keyed by workflow + model + text hash.
+
+In this repo, generated locale TM files such as `docs/.i18n/zh-CN.tm.jsonl`, `docs/.i18n/zh-TW.tm.jsonl`, `docs/.i18n/ja-JP.tm.jsonl`, `docs/.i18n/es.tm.jsonl`, `docs/.i18n/pt-BR.tm.jsonl`, `docs/.i18n/ko.tm.jsonl`, `docs/.i18n/de.tm.jsonl`, `docs/.i18n/fr.tm.jsonl`, `docs/.i18n/ar.tm.jsonl`, `docs/.i18n/it.tm.jsonl`, `docs/.i18n/vi.tm.jsonl`, `docs/.i18n/nl.tm.jsonl`, `docs/.i18n/fa.tm.jsonl`, `docs/.i18n/tr.tm.jsonl`, `docs/.i18n/uk.tm.jsonl`, `docs/.i18n/id.tm.jsonl`, `docs/.i18n/pl.tm.jsonl`, and `docs/.i18n/th.tm.jsonl` are intentionally no longer committed.
+
+## Glossary format
+
+`glossary.<lang>.json` is an array of entries:
+
+```json
+{
+  "source": "troubleshooting",
+  "target": "故障排除"
+}
+```
+
+Fields:
+
+- `source`: English (or source) phrase to prefer.
+- `target`: preferred translation output.
+
+## Translation mechanics
+
+- `scripts/docs-i18n` still owns translation generation.
+- Doc mode writes `x-i18n.source_hash` into each translated page.
+- The publish workflow precomputes a pending file list by comparing the current English source hash to the stored locale `x-i18n.source_hash`.
+- If the pending count is `0`, the expensive translation step is skipped entirely.
+- If there are pending files, the workflow translates only those files.
+- Locale workers retry transient model-format failures, but unchanged files stay skipped because the same hash check runs on each retry.
+- Locale workers upload artifacts; the publish repo finalizer commits all successful locale outputs together.
+- Published GitHub releases dispatch one aggregate translation refresh so release docs can catch up without waiting for the weekly reconciliation.
+
+## Operational notes
+
+- Sync metadata is written to `.openclaw-sync/source.json` in the publish repo.
+- Source repo secret: `OPENCLAW_DOCS_SYNC_TOKEN`
+- Publish repo secret: `OPENCLAW_DOCS_I18N_OPENAI_API_KEY`
+- If locale output looks stale, check the `Translate All` workflow in `openclaw/docs` first.

docs/.i18n/ar-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "ar",
+  "tabs": [
+    {
+      "tab": "ابدأ",
+      "groups": [
+        {
+          "group": "نظرة عامة",
+          "pages": ["ar/index"]
+        },
+        {
+          "group": "الخطوات الأولى",
+          "pages": ["ar/start/getting-started", "ar/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/de-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "de",
+  "tabs": [
+    {
+      "tab": "Loslegen",
+      "groups": [
+        {
+          "group": "Überblick",
+          "pages": ["de/index"]
+        },
+        {
+          "group": "Erste Schritte",
+          "pages": ["de/start/getting-started", "de/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/es-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "es",
+  "tabs": [
+    {
+      "tab": "Comenzar",
+      "groups": [
+        {
+          "group": "Resumen",
+          "pages": ["es/index"]
+        },
+        {
+          "group": "Primeros pasos",
+          "pages": ["es/start/getting-started", "es/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/fr-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "fr",
+  "tabs": [
+    {
+      "tab": "Commencer",
+      "groups": [
+        {
+          "group": "Vue d'ensemble",
+          "pages": ["fr/index"]
+        },
+        {
+          "group": "Premiers pas",
+          "pages": ["fr/start/getting-started", "fr/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/glossary.ar.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.de.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.es.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.fa.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.fr.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.hi.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.id.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.it.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.ja-JP.json

@@ -0,0 +1,102 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Getting Started",
+    "target": "はじめに"
+  },
+  {
+    "source": "Getting started",
+    "target": "はじめに"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "local loopback",
+    "target": "local loopback"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "Onboarding",
+    "target": "オンボーディング"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Quick start",
+    "target": "クイックスタート"
+  },
+  {
+    "source": "Quick Start",
+    "target": "クイックスタート"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  },
+  {
+    "source": "wizard",
+    "target": "ウィザード"
+  }
+]

docs/.i18n/glossary.ko.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.nl.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.pl.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.pt-BR.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.ru.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.th.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.tr.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.uk.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.vi.json

@@ -0,0 +1,82 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]

docs/.i18n/glossary.zh-TW.json

@@ -0,0 +1,162 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "主動記憶"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "ClickClack",
+    "target": "ClickClack"
+  },
+  {
+    "source": "CLI",
+    "target": "命令列介面"
+  },
+  {
+    "source": "Compaction",
+    "target": "壓縮"
+  },
+  {
+    "source": "Cron",
+    "target": "排程"
+  },
+  {
+    "source": "Dreaming",
+    "target": "夢境整理"
+  },
+  {
+    "source": "Gateway",
+    "target": "閘道"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "心跳偵測"
+  },
+  {
+    "source": "Feishu",
+    "target": "Feishu"
+  },
+  {
+    "source": "IRC",
+    "target": "IRC"
+  },
+  {
+    "source": "LINE",
+    "target": "LINE"
+  },
+  {
+    "source": "Mattermost",
+    "target": "Mattermost"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Nextcloud Talk",
+    "target": "Nextcloud Talk"
+  },
+  {
+    "source": "Node",
+    "target": "節點"
+  },
+  {
+    "source": "Nostr",
+    "target": "Nostr"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "外掛"
+  },
+  {
+    "source": "QQ Bot",
+    "target": "QQ Bot"
+  },
+  {
+    "source": "QQBot",
+    "target": "QQ Bot"
+  },
+  {
+    "source": "QQ bot",
+    "target": "QQ Bot"
+  },
+  {
+    "source": "SMS",
+    "target": "SMS"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Synology Chat",
+    "target": "Synology Chat"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "Tlon",
+    "target": "Tlon"
+  },
+  {
+    "source": "Twitch",
+    "target": "Twitch"
+  },
+  {
+    "source": "Twilio",
+    "target": "Twilio"
+  },
+  {
+    "source": "TUI",
+    "target": "終端介面"
+  },
+  {
+    "source": "WeChat",
+    "target": "微信"
+  },
+  {
+    "source": "Weixin",
+    "target": "微信"
+  },
+  {
+    "source": "Webhook",
+    "target": "網路鉤子"
+  },
+  {
+    "source": "Yuanbao",
+    "target": "騰訊元寶"
+  },
+  {
+    "source": "Zalo",
+    "target": "Zalo"
+  },
+  {
+    "source": "Zalo Personal",
+    "target": "Zalo Personal"
+  },
+  {
+    "source": "Zalo personal",
+    "target": "Zalo Personal"
+  }
+]

docs/.i18n/id-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "id",
+  "tabs": [
+    {
+      "tab": "Mulai",
+      "groups": [
+        {
+          "group": "Ringkasan",
+          "pages": ["id/index"]
+        },
+        {
+          "group": "Langkah pertama",
+          "pages": ["id/start/getting-started", "id/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/it-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "it",
+  "tabs": [
+    {
+      "tab": "Inizia",
+      "groups": [
+        {
+          "group": "Panoramica",
+          "pages": ["it/index"]
+        },
+        {
+          "group": "Primi passi",
+          "pages": ["it/start/getting-started", "it/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/ja-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "ja",
+  "tabs": [
+    {
+      "tab": "はじめに",
+      "groups": [
+        {
+          "group": "概要",
+          "pages": ["ja-JP/index"]
+        },
+        {
+          "group": "初回セットアップ",
+          "pages": ["ja-JP/start/getting-started", "ja-JP/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/ko-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "ko",
+  "tabs": [
+    {
+      "tab": "시작하기",
+      "groups": [
+        {
+          "group": "개요",
+          "pages": ["ko/index"]
+        },
+        {
+          "group": "첫 단계",
+          "pages": ["ko/start/getting-started", "ko/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/pl-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "pl",
+  "tabs": [
+    {
+      "tab": "Start",
+      "groups": [
+        {
+          "group": "Przeglad",
+          "pages": ["pl/index"]
+        },
+        {
+          "group": "Pierwsze kroki",
+          "pages": ["pl/start/getting-started", "pl/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/pt-BR-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "pt-BR",
+  "tabs": [
+    {
+      "tab": "Começar",
+      "groups": [
+        {
+          "group": "Visão geral",
+          "pages": ["pt-BR/index"]
+        },
+        {
+          "group": "Primeiros passos",
+          "pages": ["pt-BR/start/getting-started", "pt-BR/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/tr-navigation.json

@@ -0,0 +1,18 @@
+{
+  "language": "tr",
+  "tabs": [
+    {
+      "tab": "Baslangic",
+      "groups": [
+        {
+          "group": "Genel bakis",
+          "pages": ["tr/index"]
+        },
+        {
+          "group": "Ilk adimlar",
+          "pages": ["tr/start/getting-started", "tr/start/wizard"]
+        }
+      ]
+    }
+  ]
+}

docs/.i18n/translation-workflow.md

@@ -0,0 +1,111 @@
+# Translation workflow
+
+Internal note for the docs publish pipeline. This file is under `docs/.i18n`, which is ignored by the docs-site build and is not published.
+
+## Goals
+
+- English docs deploy quickly after every source docs sync.
+- Locale translation does not run for every hot `main` commit.
+- Translation work is debounced so a burst of docs commits becomes one translation wave.
+- Locale jobs translate only pages whose source hash changed since the last successful locale output.
+- Successful locale outputs are committed together, even if one or more locale jobs fail.
+- A weekly reconciliation reruns every locale/page path to repair missed or flaky translations.
+
+## Event flow
+
+1. `openclaw/openclaw` syncs English docs into `openclaw/docs`.
+2. GitHub Pages deploys English/source changes immediately from the sync commit.
+3. `Translate All` is triggered by the sync commit, release dispatch, manual dispatch, or weekly schedule.
+4. The coordinator waits a cooldown window before starting translation.
+5. After the cooldown, the coordinator reads the current `origin/main` source metadata.
+6. If a newer docs sync arrived during cooldown, the coordinator uses the newer source state.
+7. Per-locale translation jobs run in parallel with `fail-fast: false`.
+8. Each locale job uploads an artifact for the requested source SHA.
+9. The finalizer downloads available artifacts, ignores stale or failed payloads, and pushes one aggregate i18n commit.
+10. After the aggregate commit lands, the finalizer dispatches the Pages deploy once.
+11. The Pages workflow dispatches live smoke after deployment.
+
+## Debounce policy
+
+The coordinator waits 1 hour after a docs sync or release dispatch, then re-reads `origin/main`.
+
+The default cooldown is controlled by the publish repo variable `OPENCLAW_DOCS_TRANSLATION_COOLDOWN_SECONDS`, which defaults to `3600`. Repository dispatch callers may override it with `client_payload.cooldown_seconds`, and manual runs may set `cooldown_seconds`.
+
+If `.openclaw-sync/source.json` changed during the wait, it waits again from the newer state. If `main` keeps moving, the wait is capped by `OPENCLAW_DOCS_TRANSLATION_MAX_WAIT_SECONDS`, which defaults to the cooldown value. The newest observed state is translated after the cap.
+
+Manual and weekly runs do not wait by default.
+
+## Incremental translation
+
+Each translated page stores `x-i18n.source_hash`. Locale jobs compare the current English page hash with the stored locale hash.
+
+Normal runs translate only:
+
+- missing locale pages
+- locale pages with stale `x-i18n.source_hash`
+- pages affected by source deletion/pruning
+
+Internal files under `docs/.i18n/**` are not translation inputs. Push-triggered runs that only change internal i18n files skip before the locale matrix.
+
+If a locale job fails, its artifact is marked failed and carries no payload. The finalizer still commits successful locales. The failed locale remains stale and is picked up by the next incremental run because its source hashes still do not match.
+
+## Artifact contract
+
+Each locale job uploads one artifact named with locale and source SHA:
+
+```text
+i18n-zh-cn-<source-sha>
+```
+
+Artifact contents:
+
+```text
+metadata.json
+changed-files.txt
+deleted-files.txt
+payload/docs/<locale>/**
+payload/docs/.i18n/<locale>.tm.jsonl
+```
+
+`metadata.json` includes the locale, locale slug, source SHA, pending count, changed count, and any failure reason. The finalizer rejects artifacts whose `source_sha` does not match the current `.openclaw-sync/source.json`.
+
+The source repo release workflow dispatches one `translate-all-release` event. The coordinator still accepts old per-locale release events for compatibility, but those are only a fallback.
+
+## Aggregate commit
+
+The finalizer owns the only locale push in the normal path.
+
+Commit message:
+
+```text
+chore(i18n): refresh translations
+```
+
+The commit may contain a partial locale set. The job summary lists applied locales, locales with no changes, missing or failed locales, stale artifacts, and invalid artifacts.
+
+## Weekly reconciliation
+
+The weekly run uses `full` mode. It forces a full reconciliation across every locale and every source page instead of relying only on changed source hashes.
+
+Glossary changes also force full reconciliation because glossary guidance can affect pages whose source hashes did not change.
+
+Expected behavior:
+
+- regenerate or verify every locale page
+- prune stale locale pages
+- refresh translation memory as needed
+- still use parallel locale jobs
+- still commit one aggregate result
+- still tolerate individual locale failures
+
+The weekly run is the repair mechanism for LLM flakiness, partial failures, and missed incremental updates.
+
+## Deployment policy
+
+English deploys from source sync commits.
+
+Translations deploy after the aggregate i18n commit. The finalizer dispatches GitHub Pages once because GitHub suppresses normal push-triggered workflow runs from `GITHUB_TOKEN` commits. The Pages workflow dispatches live smoke after deployment so the smoke test checks the deployed site instead of racing the deploy.
+
+A hot docs day should produce many fast English deploys, but only a small number of locale deploys.
+
+If external deploy providers such as Mintlify watch every push, the aggregate i18n commit is the load reducer. Avoid restoring per-locale pushes to `main`.

docs/.i18n/zh-Hans-navigation.json

@@ -0,0 +1,552 @@
+{
+  "language": "zh-Hans",
+  "tabs": [
+    {
+      "tab": "快速开始",
+      "groups": [
+        {
+          "group": "首页",
+          "pages": ["zh-CN/index"]
+        },
+        {
+          "group": "概览",
+          "pages": ["zh-CN/start/showcase"]
+        },
+        {
+          "group": "核心概念",
+          "pages": ["zh-CN/concepts/features"]
+        },
+        {
+          "group": "第一步",
+          "pages": ["zh-CN/start/getting-started", "zh-CN/start/wizard", "zh-CN/start/onboarding"]
+        },
+        {
+          "group": "指南",
+          "pages": ["zh-CN/start/openclaw"]
+        }
+      ]
+    },
+    {
+      "tab": "安装",
+      "groups": [
+        {
+          "group": "安装概览",
+          "pages": ["zh-CN/install/index", "zh-CN/install/installer"]
+        },
+        {
+          "group": "安装方式",
+          "pages": [
+            "zh-CN/install/docker",
+            "zh-CN/install/nix",
+            "zh-CN/install/ansible",
+            "zh-CN/install/bun"
+          ]
+        },
+        {
+          "group": "维护",
+          "pages": ["zh-CN/install/updating", "zh-CN/install/migrating", "zh-CN/install/uninstall"]
+        },
+        {
+          "group": "托管与部署",
+          "pages": [
+            "zh-CN/vps",
+            "zh-CN/install/fly",
+            "zh-CN/install/hetzner",
+            "zh-CN/install/gcp",
+            "zh-CN/install/macos-vm",
+            "zh-CN/install/exe-dev",
+            "zh-CN/install/railway",
+            "zh-CN/install/render",
+            "zh-CN/install/northflank"
+          ]
+        },
+        {
+          "group": "高级",
+          "pages": ["zh-CN/install/development-channels"]
+        }
+      ]
+    },
+    {
+      "tab": "消息渠道",
+      "groups": [
+        {
+          "group": "概览",
+          "pages": ["zh-CN/channels/index"]
+        },
+        {
+          "group": "消息平台",
+          "pages": [
+            "zh-CN/channels/discord",
+            "zh-CN/channels/feishu",
+            "zh-CN/channels/grammy",
+            "zh-CN/channels/googlechat",
+            "zh-CN/channels/imessage",
+            "zh-CN/channels/line",
+            "zh-CN/channels/matrix",
+            "zh-CN/channels/mattermost",
+            "zh-CN/channels/msteams",
+            "zh-CN/channels/nextcloud-talk",
+            "zh-CN/channels/nostr",
+            "zh-CN/channels/signal",
+            "zh-CN/channels/slack",
+            "zh-CN/channels/telegram",
+            "zh-CN/channels/tlon",
+            "zh-CN/channels/twitch",
+            "zh-CN/channels/whatsapp",
+            "zh-CN/channels/zalo",
+            "zh-CN/channels/zalouser"
+          ]
+        },
+        {
+          "group": "配置",
+          "pages": [
+            "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"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "代理",
+      "groups": [
+        {
+          "group": "基础",
+          "pages": [
+            "zh-CN/pi",
+            "zh-CN/concepts/architecture",
+            "zh-CN/concepts/agent",
+            "zh-CN/concepts/agent-loop",
+            "zh-CN/concepts/system-prompt",
+            "zh-CN/concepts/context",
+            "zh-CN/concepts/agent-workspace",
+            "zh-CN/concepts/oauth"
+          ]
+        },
+        {
+          "group": "引导",
+          "pages": ["zh-CN/start/bootstrapping"]
+        },
+        {
+          "group": "会话与记忆",
+          "pages": [
+            "zh-CN/concepts/session",
+            "zh-CN/concepts/session-pruning",
+            "zh-CN/concepts/session-tool",
+            {
+              "group": "记忆",
+              "pages": [
+                "zh-CN/concepts/memory",
+                "zh-CN/concepts/memory-builtin",
+                "zh-CN/concepts/memory-qmd",
+                "zh-CN/concepts/memory-honcho",
+                "zh-CN/concepts/memory-search",
+                "zh-CN/concepts/active-memory",
+                "zh-CN/concepts/dreaming"
+              ]
+            },
+            "zh-CN/concepts/compaction"
+          ]
+        },
+        {
+          "group": "多代理",
+          "pages": ["zh-CN/concepts/multi-agent", "zh-CN/concepts/presence"]
+        },
+        {
+          "group": "消息与投递",
+          "pages": [
+            "zh-CN/concepts/messages",
+            "zh-CN/concepts/streaming",
+            "zh-CN/concepts/retry",
+            "zh-CN/concepts/queue"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "工具",
+      "groups": [
+        {
+          "group": "概览",
+          "pages": ["zh-CN/tools/index"]
+        },
+        {
+          "group": "内置工具",
+          "pages": [
+            "zh-CN/tools/apply-patch",
+            "zh-CN/brave-search",
+            "zh-CN/tools/elevated",
+            "zh-CN/tools/exec",
+            "zh-CN/tools/exec-approvals",
+            "zh-CN/tools/firecrawl",
+            "zh-CN/tools/llm-task",
+            "zh-CN/tools/lobster",
+            "zh-CN/perplexity",
+            "zh-CN/tools/reactions",
+            "zh-CN/tools/thinking",
+            "zh-CN/tools/web"
+          ]
+        },
+        {
+          "group": "浏览器",
+          "pages": [
+            "zh-CN/tools/browser",
+            "zh-CN/tools/browser-login",
+            "zh-CN/tools/browser-linux-troubleshooting"
+          ]
+        },
+        {
+          "group": "代理协作",
+          "pages": [
+            "zh-CN/tools/agent-send",
+            "zh-CN/tools/subagents",
+            "zh-CN/tools/multi-agent-sandbox-tools"
+          ]
+        },
+        {
+          "group": "技能",
+          "pages": [
+            "zh-CN/tools/creating-skills",
+            "zh-CN/tools/slash-commands",
+            "zh-CN/tools/skills",
+            "zh-CN/tools/skills-config",
+            "zh-CN/tools/plugin"
+          ]
+        },
+        {
+          "group": "扩展",
+          "pages": [
+            "zh-CN/plugins/voice-call",
+            "zh-CN/plugins/zalouser",
+            "zh-CN/plugins/manifest",
+            "zh-CN/plugins/agent-tools",
+            "zh-CN/prose"
+          ]
+        },
+        {
+          "group": "自动化与任务",
+          "pages": ["zh-CN/automation/hooks", "zh-CN/automation/cron-jobs"]
+        },
+        {
+          "group": "媒体与设备",
+          "pages": [
+            "zh-CN/nodes/index",
+            "zh-CN/nodes/troubleshooting",
+            "zh-CN/nodes/media-understanding",
+            "zh-CN/nodes/images",
+            "zh-CN/nodes/audio",
+            "zh-CN/nodes/camera",
+            "zh-CN/nodes/talk",
+            "zh-CN/nodes/voicewake",
+            "zh-CN/nodes/location-command",
+            "zh-CN/tts"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "模型",
+      "groups": [
+        {
+          "group": "概览",
+          "pages": ["zh-CN/providers/index", "zh-CN/providers/models"]
+        },
+        {
+          "group": "模型概念",
+          "pages": ["zh-CN/concepts/models"]
+        },
+        {
+          "group": "配置",
+          "pages": ["zh-CN/concepts/model-providers", "zh-CN/concepts/model-failover"]
+        },
+        {
+          "group": "提供商",
+          "pages": [
+            "zh-CN/providers/anthropic",
+            "zh-CN/providers/bedrock",
+            "zh-CN/providers/claude-max-api-proxy",
+            "zh-CN/providers/deepgram",
+            "zh-CN/providers/github-copilot",
+            "zh-CN/providers/moonshot",
+            "zh-CN/providers/minimax",
+            "zh-CN/providers/opencode",
+            "zh-CN/providers/ollama",
+            "zh-CN/providers/openai",
+            "zh-CN/providers/openrouter",
+            "zh-CN/providers/qianfan",
+            "zh-CN/providers/qwen",
+            "zh-CN/providers/synthetic",
+            "zh-CN/providers/venice",
+            "zh-CN/providers/vercel-ai-gateway",
+            "zh-CN/providers/xiaomi",
+            "zh-CN/providers/zai"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "平台",
+      "groups": [
+        {
+          "group": "平台概览",
+          "pages": [
+            "zh-CN/platforms/index",
+            "zh-CN/platforms/macos",
+            "zh-CN/platforms/linux",
+            "zh-CN/platforms/windows",
+            "zh-CN/platforms/android",
+            "zh-CN/platforms/ios",
+            "zh-CN/platforms/digitalocean",
+            "zh-CN/platforms/oracle",
+            "zh-CN/platforms/raspberry-pi"
+          ]
+        },
+        {
+          "group": "macOS 配套应用",
+          "pages": [
+            "zh-CN/platforms/mac/dev-setup",
+            "zh-CN/platforms/mac/menu-bar",
+            "zh-CN/platforms/mac/voicewake",
+            "zh-CN/platforms/mac/voice-overlay",
+            "zh-CN/platforms/mac/webchat",
+            "zh-CN/platforms/mac/canvas",
+            "zh-CN/platforms/mac/child-process",
+            "zh-CN/platforms/mac/health",
+            "zh-CN/platforms/mac/icon",
+            "zh-CN/platforms/mac/logging",
+            "zh-CN/platforms/mac/permissions",
+            "zh-CN/platforms/mac/remote",
+            "zh-CN/platforms/mac/signing",
+            "zh-CN/platforms/mac/bundled-gateway",
+            "zh-CN/platforms/mac/xpc",
+            "zh-CN/platforms/mac/skills",
+            "zh-CN/platforms/mac/peekaboo"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "网关与运维",
+      "groups": [
+        {
+          "group": "网关",
+          "pages": [
+            "zh-CN/gateway/index",
+            {
+              "group": "配置与运维",
+              "pages": [
+                "zh-CN/gateway/configuration",
+                "zh-CN/gateway/configuration-examples",
+                "zh-CN/gateway/authentication",
+                "zh-CN/gateway/health",
+                "zh-CN/gateway/heartbeat",
+                "zh-CN/gateway/doctor",
+                "zh-CN/gateway/logging",
+                "zh-CN/gateway/gateway-lock",
+                "zh-CN/gateway/background-process",
+                "zh-CN/gateway/multiple-gateways",
+                "zh-CN/gateway/troubleshooting"
+              ]
+            },
+            {
+              "group": "安全与沙箱",
+              "pages": [
+                "zh-CN/gateway/security/index",
+                "zh-CN/gateway/sandboxing",
+                "zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated"
+              ]
+            },
+            {
+              "group": "协议与 API",
+              "pages": [
+                "zh-CN/gateway/protocol",
+                "zh-CN/gateway/bridge-protocol",
+                "zh-CN/gateway/openai-http-api",
+                "zh-CN/gateway/openresponses-http-api",
+                "zh-CN/gateway/tools-invoke-http-api",
+                "zh-CN/gateway/cli-backends",
+                "zh-CN/gateway/local-models"
+              ]
+            },
+            {
+              "group": "网络与发现",
+              "pages": [
+                "zh-CN/gateway/network-model",
+                "zh-CN/gateway/pairing",
+                "zh-CN/gateway/discovery",
+                "zh-CN/gateway/bonjour"
+              ]
+            }
+          ]
+        },
+        {
+          "group": "远程访问",
+          "pages": [
+            "zh-CN/gateway/remote",
+            "zh-CN/gateway/remote-gateway-readme",
+            "zh-CN/gateway/tailscale"
+          ]
+        },
+        {
+          "group": "运维专题",
+          "pages": ["zh-CN/network", "zh-CN/logging"]
+        },
+        {
+          "group": "安全",
+          "pages": ["zh-CN/security/formal-verification"]
+        },
+        {
+          "group": "Web 界面",
+          "pages": [
+            "zh-CN/web/index",
+            "zh-CN/web/control-ui",
+            "zh-CN/web/dashboard",
+            "zh-CN/web/webchat",
+            "zh-CN/web/tui"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "参考",
+      "groups": [
+        {
+          "group": "CLI 命令",
+          "pages": [
+            "zh-CN/cli/index",
+            "zh-CN/cli/acp",
+            "zh-CN/cli/agent",
+            "zh-CN/cli/agents",
+            "zh-CN/cli/approvals",
+            "zh-CN/cli/browser",
+            "zh-CN/cli/channels",
+            "zh-CN/cli/config",
+            "zh-CN/cli/configure",
+            "zh-CN/cli/cron",
+            "zh-CN/cli/dashboard",
+            "zh-CN/cli/devices",
+            "zh-CN/cli/directory",
+            "zh-CN/cli/dns",
+            "zh-CN/cli/docs",
+            "zh-CN/cli/doctor",
+            "zh-CN/cli/gateway",
+            "zh-CN/cli/health",
+            "zh-CN/cli/hooks",
+            "zh-CN/cli/logs",
+            "zh-CN/cli/memory",
+            "zh-CN/cli/message",
+            "zh-CN/cli/models",
+            "zh-CN/cli/node",
+            "zh-CN/cli/nodes",
+            "zh-CN/cli/onboard",
+            "zh-CN/cli/pairing",
+            "zh-CN/cli/plugins",
+            "zh-CN/cli/reset",
+            "zh-CN/cli/sandbox",
+            "zh-CN/cli/security",
+            "zh-CN/cli/sessions",
+            "zh-CN/cli/setup",
+            "zh-CN/cli/skills",
+            "zh-CN/cli/status",
+            "zh-CN/cli/system",
+            "zh-CN/cli/tui",
+            "zh-CN/cli/uninstall",
+            "zh-CN/cli/update",
+            "zh-CN/cli/voicecall",
+            "zh-CN/cli/webhooks"
+          ]
+        },
+        {
+          "group": "RPC 与 API",
+          "pages": ["zh-CN/reference/rpc", "zh-CN/reference/device-models"]
+        },
+        {
+          "group": "模板",
+          "pages": [
+            "zh-CN/reference/AGENTS.default",
+            "zh-CN/reference/templates/AGENTS",
+            "zh-CN/reference/templates/BOOT",
+            "zh-CN/reference/templates/BOOTSTRAP",
+            "zh-CN/reference/templates/HEARTBEAT",
+            "zh-CN/reference/templates/IDENTITY",
+            "zh-CN/reference/templates/SOUL",
+            "zh-CN/reference/templates/TOOLS",
+            "zh-CN/reference/templates/USER"
+          ]
+        },
+        {
+          "group": "技术参考",
+          "pages": [
+            "zh-CN/reference/wizard",
+            "zh-CN/reference/token-use",
+            "zh-CN/reference/api-usage-costs",
+            "zh-CN/reference/transcript-hygiene",
+            "zh-CN/date-time"
+          ]
+        },
+        {
+          "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"
+          ]
+        },
+        {
+          "group": "项目",
+          "pages": ["zh-CN/reference/credits"]
+        },
+        {
+          "group": "发布策略",
+          "pages": ["zh-CN/reference/RELEASING", "zh-CN/reference/test"]
+        }
+      ]
+    },
+    {
+      "tab": "帮助",
+      "groups": [
+        {
+          "group": "帮助",
+          "pages": ["zh-CN/help/index", "zh-CN/help/troubleshooting", "zh-CN/help/faq"]
+        },
+        {
+          "group": "社区",
+          "pages": ["zh-CN/start/lore"]
+        },
+        {
+          "group": "环境与调试",
+          "pages": [
+            "zh-CN/help/environment",
+            "zh-CN/help/debugging",
+            "zh-CN/help/testing",
+            "zh-CN/help/scripts",
+            "zh-CN/debug/node-issue",
+            "zh-CN/diagnostics/flags"
+          ]
+        },
+        {
+          "group": "Node 运行时",
+          "pages": ["zh-CN/install/node"]
+        },
+        {
+          "group": "压缩机制内部参考",
+          "pages": ["zh-CN/reference/session-management-compaction"]
+        },
+        {
+          "group": "开发者设置",
+          "pages": ["zh-CN/start/setup", "zh-CN/pi-dev"]
+        },
+        {
+          "group": "文档元信息",
+          "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory", "zh-CN/AGENTS"]
+        }
+      ]
+    }
+  ]
+}

docs/AGENTS.md

@@ -0,0 +1,45 @@
+# Docs Guide
+
+This directory owns docs authoring, Mintlify link rules, and docs i18n policy.
+
+## Mintlify Rules
+
+- Docs are hosted on Mintlify (`https://docs.openclaw.ai`).
+- Internal doc links in `docs/**/*.md` must stay root-relative with no `.md` or `.mdx` suffix (example: `[Config](/gateway/configuration)`).
+- Section cross-references should use anchors on root-relative paths (example: `[Hooks](/gateway/configuration-reference#hooks)`).
+- Doc headings should avoid em dashes and apostrophes because Mintlify anchor generation is brittle there.
+- README and other GitHub-rendered docs should keep absolute docs URLs so links work outside Mintlify.
+- Docs content must stay generic: no personal device names, hostnames, or local paths; use placeholders like `user@gateway-host`.
+
+## Docs Content Rules
+
+- For docs, UI copy, and picker lists, order services/providers alphabetically unless the section is explicitly describing runtime order or auto-detection order.
+- Keep bundled plugin naming consistent with the repo-wide plugin terminology rules in the root `AGENTS.md`.
+- Generated docs, never hand-edit: `docs/plugins/reference/**`, `docs/plugins/reference.md`, and `docs/plugins/plugin-inventory.md` come from `pnpm plugins:inventory:gen`; `docs/docs_map.md` from `pnpm docs:map:gen`; `docs/maturity/**` from `pnpm maturity:render`.
+
+## Internal Docs
+
+- Long-lived private operator docs belong in `~/Projects/manager/docs/`.
+- Repo-local internal scratch/mirror docs may live under ignored `docs/internal/`.
+- Never add `docs/internal/**` pages to `docs/docs.json` navigation or link them from public docs.
+- `scripts/docs-sync-publish.mjs` excludes and prunes `docs/internal/**` from the public `openclaw/docs` publish repo if a page is force-added later.
+- Internal docs may mention repo paths, private app names, 1Password item names, and runbooks, but never include secret values.
+
+## Maturity Scorecard Editing
+
+`taxonomy.yaml` and `qa/maturity-scores.yaml` are the source inputs; generated maturity docs under `docs/maturity/` are projections and should not be hand-edited for score, LTS, taxonomy, QA profile, or evidence tables.
+`scripts/qa/render-maturity-docs.ts` owns generation; use `pnpm maturity:render` to refresh committed docs and `pnpm maturity:check` to verify them.
+`.github/workflows/maturity-scorecard.yml` renders artifact previews and can open generated-doc PRs; `.github/workflows/openclaw-release-checks.yml` dispatches it for release QA.
+Keep deterministic `qa-evidence.json.scorecard` data in GitHub Actions artifacts unless a maintainer explicitly asks for a sanitized committed projection.
+Human overrides must change source state in a PR and explain the reason plus public or redacted evidence.
+
+## Docs i18n
+
+- Foreign-language docs are not maintained in this repo. The generated publish output lives in the separate `openclaw/docs` repo (often cloned locally as `../openclaw-docs`).
+- Do not add or edit localized docs under `docs/<locale>/**` here.
+- Treat English docs in this repo plus glossary files as the source of truth.
+- Pipeline: update English docs here, update `docs/.i18n/glossary.<locale>.json` as needed, then let the publish-repo sync and `scripts/docs-i18n` run in `openclaw/docs`.
+- Before rerunning `scripts/docs-i18n`, add glossary entries for any new technical terms, page titles, or short nav labels that must stay in English or use a fixed translation.
+- `pnpm docs:check-i18n-glossary` is the guard for changed English doc titles and short internal doc labels.
+- Translation memory lives in generated `docs/.i18n/*.tm.jsonl` files in the publish repo.
+- See `docs/.i18n/README.md`.

docs/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docs/agent-runtime-architecture.md

@@ -0,0 +1,55 @@
+---
+title: "Agent runtime architecture"
+summary: "How OpenClaw structures the built-in agent runtime: code layout, boundaries, resource manifests, and runtime selection."
+---
+
+OpenClaw owns the built-in agent runtime. Runtime code lives under `src/agents/`, model/provider transport lives under `src/llm/`, and plugin-facing contracts are exposed through `openclaw/plugin-sdk/*` barrels.
+
+## Runtime Layout
+
+| Path                                | Owns                                                                                                                                                                                                                      |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/agents/embedded-agent-runner/` | Built-in attempt loop (`run.ts`, `run/`), model selection and provider normalization (`model*.ts`), per-provider request params (`extra-params.*`), compaction, transcript and session wiring.                            |
+| `src/agents/sessions/`              | Session persistence (`session-manager.ts`), resource discovery (`package-manager.ts`, `resource-loader.ts`), in-session `extensions` loading, prompt templates, skills, themes, and TUI-backed tool renderers (`tools/`). |
+| `packages/agent-core/`              | Reusable agent core (`@openclaw/agent-core`): agent loop, harness types, messages, compaction helpers, prompt templates, skills, and session storage contracts.                                                           |
+| `src/agents/runtime/`               | OpenClaw facade that wires `@openclaw/agent-core` to the plugin SDK LLM runtime and re-exports it plus local proxy utilities.                                                                                             |
+| `src/agents/agent-tools*.ts`        | OpenClaw-owned tool definitions, parameter schemas, tool policy, before/after tool-call adapters, and host/sandbox edit tools.                                                                                            |
+| `src/agents/agent-hooks/`           | Built-in runtime hooks: compaction safeguard, compaction instructions, context pruning.                                                                                                                                   |
+| `src/agents/harness/`               | Harness registry, selection policy, and lifecycle for the built-in and plugin-registered harnesses.                                                                                                                       |
+| `src/llm/`                          | Model/provider registry, transport helpers, and provider-specific stream implementations (`src/llm/providers/`).                                                                                                          |
+
+## Boundaries
+
+Core calls the built-in runtime through OpenClaw modules and SDK barrels; no external agent framework packages remain. Plugins use documented `openclaw/plugin-sdk/*` entrypoints and do not import `src/**` internals.
+
+`@earendil-works/pi-tui` remains a third-party dependency: a terminal component toolkit used by the local TUI and session tool renderers. Internalizing it would be a separate vendoring effort.
+
+## Manifests
+
+Resource packages declare OpenClaw resources in `package.json` metadata. Entries are file paths or globs relative to the package root:
+
+```json
+{
+  "openclaw": {
+    "extensions": ["extensions/index.ts"],
+    "skills": ["skills/*.md"],
+    "prompts": ["prompts/*.md"],
+    "themes": ["themes/*.json"]
+  }
+}
+```
+
+Resource types not listed in a manifest fall back to discovery of conventional `extensions/`, `skills/`, `prompts/`, and `themes/` directories.
+
+## Runtime Selection
+
+- The built-in runtime id is `openclaw`. The legacy alias `pi` normalizes to `openclaw`; `codex-app-server` normalizes to `codex`.
+- Plugin harnesses register additional runtime ids (for example `codex`).
+- Runtime policy is model/provider-scoped `agentRuntime.id` config (model entry wins over provider entry). Unset or `default` resolves to `auto`.
+- `auto` selects a registered plugin harness that supports the provider/model, otherwise the built-in OpenClaw runtime.
+- The `openai` provider on the official API endpoint defaults to the `codex` harness; custom `baseUrl` values keep their configured behavior.
+
+## Related
+
+- [OpenClaw agent runtime workflow](/openclaw-agent-runtime)
+- [Agent runtimes](/concepts/agent-runtimes)

docs/announcements/bluebubbles-imessage.md

@@ -0,0 +1,79 @@
+---
+summary: "BlueBubbles support was removed from OpenClaw. Use the bundled iMessage plugin with imsg for new and migrated iMessage setups."
+read_when:
+  - You used the old BlueBubbles channel and need to move to iMessage
+  - You are choosing the supported OpenClaw iMessage setup
+  - You need a short explanation of the BlueBubbles removal
+title: "BlueBubbles removal and the imsg iMessage path"
+---
+
+# BlueBubbles removal and the imsg iMessage path
+
+OpenClaw no longer ships the BlueBubbles channel. iMessage support runs through the bundled `imessage` plugin: the Gateway spawns [`imsg`](https://github.com/steipete/imsg) as a child process, locally or through an SSH wrapper, and talks JSON-RPC over stdin/stdout. No server, no webhook, no port.
+
+If your config still contains `channels.bluebubbles`, migrate it to `channels.imessage`. The legacy `/channels/bluebubbles` docs URL redirects to [Coming from BlueBubbles](/channels/imessage-from-bluebubbles), which has the full config translation table and cutover checklist.
+
+## What changed
+
+- The supported iMessage path has no BlueBubbles HTTP server, webhook route, REST password, or BlueBubbles plugin runtime.
+- OpenClaw reads and watches Messages through `imsg` on the Mac where Messages.app is signed in.
+- Basic send, receive, history, and media use the normal `imsg` surfaces and macOS permissions.
+- Advanced actions (threaded replies, tapbacks, edit, unsend, effects, read receipts, typing indicators, group management) need the private API bridge: run `imsg launch`, which requires SIP disabled.
+- Linux and Windows gateways can still use iMessage by pointing `channels.imessage.cliPath` at an SSH wrapper that runs `imsg` on the signed-in Mac.
+
+## What to do
+
+1. Install and verify `imsg` on the Messages Mac:
+
+   ```bash
+   brew install steipete/tap/imsg
+   imsg --version
+   imsg chats --limit 3
+   imsg rpc --help
+   ```
+
+2. Grant Full Disk Access and Automation permissions to the process context that runs `imsg` and OpenClaw.
+
+3. Translate the old config:
+
+   ```json5
+   {
+     channels: {
+       imessage: {
+         enabled: true,
+         cliPath: "/opt/homebrew/bin/imsg",
+         dmPolicy: "pairing",
+         allowFrom: ["+15555550123"],
+         groupPolicy: "allowlist",
+         groupAllowFrom: ["+15555550123"],
+         groups: {
+           "*": { requireMention: true },
+         },
+         includeAttachments: true,
+       },
+     },
+   }
+   ```
+
+4. Restart the gateway and verify:
+
+   ```bash
+   openclaw channels status --probe
+   ```
+
+5. Test DMs, groups, attachments, and any private API actions you depend on before deleting your old BlueBubbles server.
+
+## Migration notes
+
+- `channels.bluebubbles.serverUrl` and `channels.bluebubbles.password` have no iMessage equivalent; there is no server to reach or authenticate.
+- `allowFrom`, `groupAllowFrom`, `groups`, `includeAttachments`, `attachmentRoots`, `mediaMaxMb`, `textChunkLimit`, and `actions.*` keep their meaning under `channels.imessage`.
+- `channels.imessage.includeAttachments` is still off by default. Set it explicitly if you expect inbound photos, voice memos, videos, or files to reach the agent.
+- With `groupPolicy: "allowlist"`, copy the old `groups` block, including any `"*"` wildcard entry. Group sender allowlists and the group registry are separate gates; a `groups` block with entries but no matching `chat_id` (or no `"*"`) drops the message at runtime, and an empty `groups` block logs a startup warning even though sender filtering still lets messages through.
+- ACP bindings with `match.channel: "bluebubbles"` must change to `"imessage"`.
+- Old BlueBubbles session keys do not become iMessage session keys. Pairing approvals key off sender handles, so copied `allowFrom` entries keep working, but conversation history under BlueBubbles session keys does not carry over.
+
+## See also
+
+- [Coming from BlueBubbles](/channels/imessage-from-bluebubbles)
+- [iMessage](/channels/imessage)
+- [Configuration reference - iMessage](/gateway/config-channels#imessage)

docs/assets/pixel-lobster.svg

@@ -0,0 +1,60 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 16 16" role="img" aria-label="Pixel lobster">
+  <rect width="16" height="16" fill="none"/>
+  <!-- outline -->
+  <g fill="#3a0a0d">
+    <rect x="1" y="5" width="1" height="3"/>
+    <rect x="2" y="4" width="1" height="1"/>
+    <rect x="2" y="8" width="1" height="1"/>
+    <rect x="3" y="3" width="1" height="1"/>
+    <rect x="3" y="9" width="1" height="1"/>
+    <rect x="4" y="2" width="1" height="1"/>
+    <rect x="4" y="10" width="1" height="1"/>
+    <rect x="5" y="2" width="6" height="1"/>
+    <rect x="11" y="2" width="1" height="1"/>
+    <rect x="12" y="3" width="1" height="1"/>
+    <rect x="12" y="9" width="1" height="1"/>
+    <rect x="13" y="4" width="1" height="1"/>
+    <rect x="13" y="8" width="1" height="1"/>
+    <rect x="14" y="5" width="1" height="3"/>
+    <rect x="5" y="11" width="6" height="1"/>
+    <rect x="4" y="12" width="1" height="1"/>
+    <rect x="11" y="12" width="1" height="1"/>
+    <rect x="3" y="13" width="1" height="1"/>
+    <rect x="12" y="13" width="1" height="1"/>
+    <rect x="5" y="14" width="6" height="1"/>
+  </g>
+
+  <!-- body -->
+  <g fill="#ff4f40">
+    <rect x="5" y="3" width="6" height="1"/>
+    <rect x="4" y="4" width="8" height="1"/>
+    <rect x="3" y="5" width="10" height="1"/>
+    <rect x="3" y="6" width="10" height="1"/>
+    <rect x="3" y="7" width="10" height="1"/>
+    <rect x="4" y="8" width="8" height="1"/>
+    <rect x="5" y="9" width="6" height="1"/>
+    <rect x="5" y="12" width="6" height="1"/>
+    <rect x="6" y="13" width="4" height="1"/>
+  </g>
+
+  <!-- claws -->
+  <g fill="#ff775f">
+    <rect x="1" y="6" width="2" height="1"/>
+    <rect x="2" y="5" width="1" height="1"/>
+    <rect x="2" y="7" width="1" height="1"/>
+    <rect x="13" y="6" width="2" height="1"/>
+    <rect x="13" y="5" width="1" height="1"/>
+    <rect x="13" y="7" width="1" height="1"/>
+  </g>
+
+  <!-- eyes -->
+  <g fill="#081016">
+    <rect x="6" y="5" width="1" height="1"/>
+    <rect x="9" y="5" width="1" height="1"/>
+  </g>
+  <g fill="#f5fbff">
+    <rect x="6" y="4" width="1" height="1"/>
+    <rect x="9" y="4" width="1" height="1"/>
+  </g>
+</svg>
+

docs/assets/sponsors/convex-light.svg

@@ -0,0 +1,16 @@
+<svg width="126" height="20" viewBox="0 0 126 20" fill="black" xmlns="http://www.w3.org/2000/svg">
+  <g clip-path="url(#clip0_5_2)">
+    <path d="M3.18483 17.4674C1.30005 15.782 0.357666 13.2908 0.357666 10.0003C0.357666 6.70977 1.31835 4.2186 3.24278 2.53321C5.16415 0.847812 7.79308 0.00350952 11.1265 0.00350952C12.5111 0.00350952 13.7341 0.103028 14.7985 0.308486C15.8629 0.510733 16.8815 0.854231 17.8544 1.34219V6.68088C16.3417 5.92646 14.6246 5.54765 12.7033 5.54765C11.0106 5.54765 9.76021 5.88473 8.95506 6.55889C8.14686 7.23304 7.74429 8.37911 7.74429 10.0003C7.74429 11.5669 8.14076 12.7001 8.93676 13.4C9.72971 14.103 10.9862 14.453 12.7063 14.453C14.527 14.453 16.2563 14.0067 17.8971 13.1175V18.7034C16.0763 19.5669 13.8073 19.9971 11.0899 19.9971C7.70159 19.9971 5.06961 19.1528 3.18483 17.4674Z" />
+    <path d="M19.538 9.99679C19.538 6.73194 20.4224 4.2504 22.1913 2.54896C23.9602 0.847512 26.6257 0 30.1909 0C33.7805 0 36.4644 0.850722 38.2485 2.54896C40.0296 4.24719 40.9201 6.73194 40.9201 9.99679C40.9201 16.6613 37.3427 19.9936 30.1909 19.9936C23.0879 19.9968 19.538 16.6645 19.538 9.99679ZM32.7497 13.3997C33.2743 12.6966 33.5365 11.5634 33.5365 10C33.5365 8.46228 33.2743 7.33547 32.7497 6.61958C32.2251 5.90369 31.3712 5.54735 30.1909 5.54735C29.0381 5.54735 28.2024 5.9069 27.6901 6.61958C27.1777 7.33547 26.9215 8.46228 26.9215 10C26.9215 11.5666 27.1777 12.6998 27.6901 13.3997C28.2024 14.1027 29.035 14.4526 30.1909 14.4526C31.3712 14.4526 32.2221 14.0995 32.7497 13.3997Z" />
+    <path d="M42.6029 0.404494H49.3704L49.5626 1.86196C50.3067 1.32263 51.2552 0.876404 52.408 0.526485C53.5608 0.176565 54.7533 0 55.9854 0C58.2667 0 59.9319 0.5939 60.9841 1.7817C62.0363 2.9695 62.5608 4.80257 62.5608 7.28732V19.5923H55.3328V8.05458C55.3328 7.19101 55.1467 6.57143 54.7747 6.19262C54.4026 5.8138 53.7804 5.62761 52.9082 5.62761C52.3714 5.62761 51.8194 5.75602 51.2552 6.01284C50.691 6.26966 50.2183 6.60032 49.8309 7.00482V19.5923H42.6029V0.404494Z" />
+    <path d="M62.5818 0.404617H70.1178L73.5794 11.6566L77.0409 0.404617H84.5769L77.3855 19.5924H69.7702L62.5818 0.404617Z" />
+    <path d="M86.8523 17.9422C84.6809 16.2279 83.6653 13.252 83.6653 10.0385C83.6653 6.90851 84.4735 4.33066 86.3186 2.54896C88.1637 0.767255 90.9757 0 94.5256 0C97.792 0 100.36 0.796147 102.236 2.38844C104.108 3.98074 105.047 6.15409 105.047 8.9053V12.2665H91.302C91.6436 13.2648 92.0766 13.9872 93.141 14.4334C94.2054 14.8796 95.6907 15.1011 97.5907 15.1011C98.7252 15.1011 99.8841 15.008 101.061 14.8186C101.476 14.7512 102.159 14.6453 102.519 14.565V19.2295C100.723 19.7432 98.3287 20 95.6297 20C91.9973 19.9968 89.0238 19.6565 86.8523 17.9422ZM97.4534 8.13804C97.4534 7.1878 96.4135 5.14286 94.3243 5.14286C92.4396 5.14286 91.1952 7.1557 91.1952 8.13804H97.4534Z" />
+    <path d="M110.723 9.8364L103.955 0.404617H111.799L125.642 19.5924H117.722L114.645 15.3003L111.567 19.5924H103.684L110.723 9.8364Z" />
+    <path d="M117.548 0.404617H125.356L119.363 8.8059L115.398 3.42227L117.548 0.404617Z" />
+  </g>
+  <defs>
+    <clipPath id="clip0_5_2">
+      <rect width="126" height="20" />
+    </clipPath>
+  </defs>
+</svg>

docs/assets/sponsors/convex.svg

@@ -0,0 +1,16 @@
+<svg width="126" height="20" viewBox="0 0 126 20" fill="white" xmlns="http://www.w3.org/2000/svg">
+  <g clip-path="url(#clip0_5_2)">
+    <path d="M3.18483 17.4674C1.30005 15.782 0.357666 13.2908 0.357666 10.0003C0.357666 6.70977 1.31835 4.2186 3.24278 2.53321C5.16415 0.847812 7.79308 0.00350952 11.1265 0.00350952C12.5111 0.00350952 13.7341 0.103028 14.7985 0.308486C15.8629 0.510733 16.8815 0.854231 17.8544 1.34219V6.68088C16.3417 5.92646 14.6246 5.54765 12.7033 5.54765C11.0106 5.54765 9.76021 5.88473 8.95506 6.55889C8.14686 7.23304 7.74429 8.37911 7.74429 10.0003C7.74429 11.5669 8.14076 12.7001 8.93676 13.4C9.72971 14.103 10.9862 14.453 12.7063 14.453C14.527 14.453 16.2563 14.0067 17.8971 13.1175V18.7034C16.0763 19.5669 13.8073 19.9971 11.0899 19.9971C7.70159 19.9971 5.06961 19.1528 3.18483 17.4674Z" />
+    <path d="M19.538 9.99679C19.538 6.73194 20.4224 4.2504 22.1913 2.54896C23.9602 0.847512 26.6257 0 30.1909 0C33.7805 0 36.4644 0.850722 38.2485 2.54896C40.0296 4.24719 40.9201 6.73194 40.9201 9.99679C40.9201 16.6613 37.3427 19.9936 30.1909 19.9936C23.0879 19.9968 19.538 16.6645 19.538 9.99679ZM32.7497 13.3997C33.2743 12.6966 33.5365 11.5634 33.5365 10C33.5365 8.46228 33.2743 7.33547 32.7497 6.61958C32.2251 5.90369 31.3712 5.54735 30.1909 5.54735C29.0381 5.54735 28.2024 5.9069 27.6901 6.61958C27.1777 7.33547 26.9215 8.46228 26.9215 10C26.9215 11.5666 27.1777 12.6998 27.6901 13.3997C28.2024 14.1027 29.035 14.4526 30.1909 14.4526C31.3712 14.4526 32.2221 14.0995 32.7497 13.3997Z" />
+    <path d="M42.6029 0.404494H49.3704L49.5626 1.86196C50.3067 1.32263 51.2552 0.876404 52.408 0.526485C53.5608 0.176565 54.7533 0 55.9854 0C58.2667 0 59.9319 0.5939 60.9841 1.7817C62.0363 2.9695 62.5608 4.80257 62.5608 7.28732V19.5923H55.3328V8.05458C55.3328 7.19101 55.1467 6.57143 54.7747 6.19262C54.4026 5.8138 53.7804 5.62761 52.9082 5.62761C52.3714 5.62761 51.8194 5.75602 51.2552 6.01284C50.691 6.26966 50.2183 6.60032 49.8309 7.00482V19.5923H42.6029V0.404494Z" />
+    <path d="M62.5818 0.404617H70.1178L73.5794 11.6566L77.0409 0.404617H84.5769L77.3855 19.5924H69.7702L62.5818 0.404617Z" />
+    <path d="M86.8523 17.9422C84.6809 16.2279 83.6653 13.252 83.6653 10.0385C83.6653 6.90851 84.4735 4.33066 86.3186 2.54896C88.1637 0.767255 90.9757 0 94.5256 0C97.792 0 100.36 0.796147 102.236 2.38844C104.108 3.98074 105.047 6.15409 105.047 8.9053V12.2665H91.302C91.6436 13.2648 92.0766 13.9872 93.141 14.4334C94.2054 14.8796 95.6907 15.1011 97.5907 15.1011C98.7252 15.1011 99.8841 15.008 101.061 14.8186C101.476 14.7512 102.159 14.6453 102.519 14.565V19.2295C100.723 19.7432 98.3287 20 95.6297 20C91.9973 19.9968 89.0238 19.6565 86.8523 17.9422ZM97.4534 8.13804C97.4534 7.1878 96.4135 5.14286 94.3243 5.14286C92.4396 5.14286 91.1952 7.1557 91.1952 8.13804H97.4534Z" />
+    <path d="M110.723 9.8364L103.955 0.404617H111.799L125.642 19.5924H117.722L114.645 15.3003L111.567 19.5924H103.684L110.723 9.8364Z" />
+    <path d="M117.548 0.404617H125.356L119.363 8.8059L115.398 3.42227L117.548 0.404617Z" />
+  </g>
+  <defs>
+    <clipPath id="clip0_5_2">
+      <rect width="126" height="20" />
+    </clipPath>
+  </defs>
+</svg>

docs/assets/sponsors/github-light.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#111827" aria-hidden="true">
+  <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
+</svg>

docs/assets/sponsors/github.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#fff" aria-hidden="true">
+  <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
+</svg>

docs/assets/sponsors/nvidia-dark.svg

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 164 30" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g>
+        <path d="M160.352,24.069L160.352,23.62L160.64,23.62C160.797,23.62 161.011,23.632 161.011,23.824C161.011,24.032 160.901,24.069 160.715,24.069L160.352,24.069M160.352,24.384L160.544,24.384L160.991,25.168L161.481,25.168L160.987,24.352C161.242,24.333 161.452,24.212 161.452,23.868C161.452,23.441 161.157,23.303 160.659,23.303L159.938,23.303L159.938,25.168L160.352,25.168L160.352,24.384M162.45,24.238C162.45,23.143 161.599,22.508 160.65,22.508C159.695,22.508 158.845,23.143 158.845,24.238C158.845,25.333 159.695,25.971 160.65,25.971C161.598,25.971 162.45,25.333 162.45,24.238M161.93,24.238C161.93,25.036 161.343,25.572 160.65,25.572L160.65,25.566C159.937,25.572 159.361,25.036 159.361,24.238C159.361,23.441 159.938,22.907 160.65,22.907C161.344,22.907 161.93,23.441 161.93,24.238" style="fill:white;"/>
+        <path d="M96.374,5.707L96.376,25.367L101.928,25.367L101.928,5.707L96.374,5.707ZM52.697,5.681L52.697,25.367L58.3,25.367L58.3,10.086L62.67,10.1C64.107,10.1 65.1,10.445 65.793,11.184C66.672,12.12 67.03,13.628 67.03,16.389L67.03,25.367L72.457,25.367L72.457,14.49C72.457,6.727 67.509,5.68 62.668,5.68L52.698,5.68L52.697,5.681ZM105.314,5.708L105.314,25.367L114.32,25.367C119.118,25.367 120.684,24.569 122.377,22.78C123.575,21.524 124.348,18.766 124.348,15.753C124.348,12.99 123.693,10.525 122.551,8.99C120.494,6.245 117.531,5.708 113.106,5.708L105.314,5.708ZM110.822,9.988L113.209,9.988C116.672,9.988 118.912,11.544 118.912,15.579C118.912,19.616 116.672,21.171 113.209,21.171L110.822,21.171L110.822,9.988ZM88.369,5.708L83.735,21.288L79.295,5.709L73.302,5.708L79.642,25.367L87.645,25.367L94.036,5.708L88.369,5.708ZM126.932,25.367L132.485,25.367L132.485,5.709L126.93,5.708L126.932,25.367ZM142.496,5.715L134.743,25.36L140.218,25.36L141.445,21.888L150.62,21.888L151.781,25.36L157.725,25.36L149.913,5.714L142.496,5.715ZM146.1,9.3L149.464,18.504L142.631,18.504L146.101,9.3L146.1,9.3Z" style="fill:white;"/>
+        <path d="M16.889,8.985L16.889,6.28C17.151,6.26 17.417,6.247 17.687,6.238C25.087,6.006 29.942,12.597 29.942,12.597C29.942,12.597 24.698,19.879 19.076,19.879C18.333,19.882 17.594,19.764 16.889,19.529L16.889,11.325C19.769,11.673 20.349,12.945 22.081,15.833L25.933,12.585C25.933,12.585 23.121,8.897 18.381,8.897C17.866,8.897 17.373,8.933 16.889,8.985ZM16.889,0.047L16.889,4.09C17.154,4.069 17.42,4.052 17.687,4.042C27.977,3.696 34.682,12.482 34.682,12.482C34.682,12.482 26.982,21.846 18.959,21.846C18.224,21.846 17.535,21.778 16.889,21.663L16.889,24.161C17.442,24.231 18.015,24.273 18.613,24.273C26.078,24.273 31.477,20.461 36.705,15.948C37.572,16.642 41.121,18.331 41.85,19.071C36.879,23.231 25.295,26.586 18.727,26.586C18.113,26.584 17.5,26.552 16.889,26.49L16.889,30L45.264,30L45.264,0.047L16.889,0.047ZM16.889,19.529L16.889,21.662C9.984,20.432 8.067,13.254 8.067,13.254C8.067,13.254 11.383,9.58 16.889,8.985L16.889,11.325L16.878,11.324C13.988,10.977 11.731,13.677 11.731,13.677C11.731,13.677 12.996,18.221 16.889,19.529ZM4.625,12.943C4.625,12.943 8.717,6.903 16.889,6.28L16.889,4.088C7.838,4.815 0,12.48 0,12.48C0,12.48 4.439,25.313 16.889,26.488L16.889,24.16C7.753,23.011 4.625,12.943 4.625,12.943Z" style="fill:rgb(118,185,0);"/>
+    </g>
+</svg>

docs/assets/sponsors/nvidia.svg

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 164 30" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g>
+        <path d="M160.352,24.069L160.352,23.62L160.64,23.62C160.797,23.62 161.011,23.632 161.011,23.824C161.011,24.032 160.901,24.069 160.715,24.069L160.352,24.069M160.352,24.384L160.544,24.384L160.991,25.168L161.481,25.168L160.987,24.352C161.242,24.333 161.452,24.212 161.452,23.868C161.452,23.441 161.157,23.303 160.659,23.303L159.938,23.303L159.938,25.168L160.352,25.168L160.352,24.384M162.45,24.238C162.45,23.143 161.599,22.508 160.65,22.508C159.695,22.508 158.845,23.143 158.845,24.238C158.845,25.333 159.695,25.971 160.65,25.971C161.598,25.971 162.45,25.333 162.45,24.238M161.93,24.238C161.93,25.036 161.343,25.572 160.65,25.572L160.65,25.566C159.937,25.572 159.361,25.036 159.361,24.238C159.361,23.441 159.938,22.907 160.65,22.907C161.344,22.907 161.93,23.441 161.93,24.238" style="fill:black;"/>
+        <path d="M96.374,5.707L96.376,25.367L101.928,25.367L101.928,5.707L96.374,5.707ZM52.697,5.681L52.697,25.367L58.3,25.367L58.3,10.086L62.67,10.1C64.107,10.1 65.1,10.445 65.793,11.184C66.672,12.12 67.03,13.628 67.03,16.389L67.03,25.367L72.457,25.367L72.457,14.49C72.457,6.727 67.509,5.68 62.668,5.68L52.698,5.68L52.697,5.681ZM105.314,5.708L105.314,25.367L114.32,25.367C119.118,25.367 120.684,24.569 122.377,22.78C123.575,21.524 124.348,18.766 124.348,15.753C124.348,12.99 123.693,10.525 122.551,8.99C120.494,6.245 117.531,5.708 113.106,5.708L105.314,5.708ZM110.822,9.988L113.209,9.988C116.672,9.988 118.912,11.544 118.912,15.579C118.912,19.616 116.672,21.171 113.209,21.171L110.822,21.171L110.822,9.988ZM88.369,5.708L83.735,21.288L79.295,5.709L73.302,5.708L79.642,25.367L87.645,25.367L94.036,5.708L88.369,5.708ZM126.932,25.367L132.485,25.367L132.485,5.709L126.93,5.708L126.932,25.367ZM142.496,5.715L134.743,25.36L140.218,25.36L141.445,21.888L150.62,21.888L151.781,25.36L157.725,25.36L149.913,5.714L142.496,5.715ZM146.1,9.3L149.464,18.504L142.631,18.504L146.101,9.3L146.1,9.3Z" style="fill:black;"/>
+        <path d="M16.889,8.985L16.889,6.28C17.151,6.26 17.417,6.247 17.687,6.238C25.087,6.006 29.942,12.597 29.942,12.597C29.942,12.597 24.698,19.879 19.076,19.879C18.333,19.882 17.594,19.764 16.889,19.529L16.889,11.325C19.769,11.673 20.349,12.945 22.081,15.833L25.933,12.585C25.933,12.585 23.121,8.897 18.381,8.897C17.866,8.897 17.373,8.933 16.889,8.985ZM16.889,0.047L16.889,4.09C17.154,4.069 17.42,4.052 17.687,4.042C27.977,3.696 34.682,12.482 34.682,12.482C34.682,12.482 26.982,21.846 18.959,21.846C18.224,21.846 17.535,21.778 16.889,21.663L16.889,24.161C17.442,24.231 18.015,24.273 18.613,24.273C26.078,24.273 31.477,20.461 36.705,15.948C37.572,16.642 41.121,18.331 41.85,19.071C36.879,23.231 25.295,26.586 18.727,26.586C18.113,26.584 17.5,26.552 16.889,26.49L16.889,30L45.264,30L45.264,0.047L16.889,0.047ZM16.889,19.529L16.889,21.662C9.984,20.432 8.067,13.254 8.067,13.254C8.067,13.254 11.383,9.58 16.889,8.985L16.889,11.325L16.878,11.324C13.988,10.977 11.731,13.677 11.731,13.677C11.731,13.677 12.996,18.221 16.889,19.529ZM4.625,12.943C4.625,12.943 8.717,6.903 16.889,6.28L16.889,4.088C7.838,4.815 0,12.48 0,12.48C0,12.48 4.439,25.313 16.889,26.488L16.889,24.16C7.753,23.011 4.625,12.943 4.625,12.943Z" style="fill:rgb(118,185,0);"/>
+    </g>
+</svg>

docs/assets/sponsors/openai-light.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="black">
+  <path d="M22.282 9.821a5.985 5.985 0 0 0-.516-4.91 6.046 6.046 0 0 0-6.51-2.9A6.065 6.065 0 0 0 4.981 4.18a5.985 5.985 0 0 0-3.998 2.9 6.046 6.046 0 0 0 .743 7.097 5.98 5.98 0 0 0 .51 4.911 6.051 6.051 0 0 0 6.515 2.9A5.985 5.985 0 0 0 13.26 24a6.056 6.056 0 0 0 5.772-4.206 5.99 5.99 0 0 0 3.997-2.9 6.056 6.056 0 0 0-.747-7.073zM13.26 22.43a4.476 4.476 0 0 1-2.876-1.04l.141-.081 4.779-2.758a.795.795 0 0 0 .392-.681v-6.737l2.02 1.168a.071.071 0 0 1 .038.052v5.583a4.504 4.504 0 0 1-4.494 4.494zM3.6 18.304a4.47 4.47 0 0 1-.535-3.014l.142.085 4.783 2.759a.771.771 0 0 0 .78 0l5.843-3.369v2.332a.08.08 0 0 1-.033.062L9.74 19.95a4.5 4.5 0 0 1-6.14-1.646zM2.34 7.896a4.485 4.485 0 0 1 2.366-1.973V11.6a.766.766 0 0 0 .388.676l5.815 3.355-2.02 1.168a.076.076 0 0 1-.071 0l-4.83-2.786A4.504 4.504 0 0 1 2.34 7.872zm16.597 3.855l-5.833-3.387L15.119 7.2a.076.076 0 0 1 .071 0l4.83 2.791a4.494 4.494 0 0 1-.676 8.105v-5.678a.79.79 0 0 0-.407-.667zm2.01-3.023l-.141-.085-4.774-2.782a.776.776 0 0 0-.785 0L9.409 9.23V6.897a.066.066 0 0 1 .028-.061l4.83-2.787a4.5 4.5 0 0 1 6.68 4.66zm-12.64 4.135l-2.02-1.164a.08.08 0 0 1-.038-.057V6.075a4.5 4.5 0 0 1 7.375-3.453l-.142.08L8.704 5.46a.795.795 0 0 0-.393.681zm1.097-2.365l2.602-1.5 2.607 1.5v2.999l-2.597 1.5-2.607-1.5z"/>
+</svg>

docs/assets/sponsors/openai.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="white">
+  <path d="M22.282 9.821a5.985 5.985 0 0 0-.516-4.91 6.046 6.046 0 0 0-6.51-2.9A6.065 6.065 0 0 0 4.981 4.18a5.985 5.985 0 0 0-3.998 2.9 6.046 6.046 0 0 0 .743 7.097 5.98 5.98 0 0 0 .51 4.911 6.051 6.051 0 0 0 6.515 2.9A5.985 5.985 0 0 0 13.26 24a6.056 6.056 0 0 0 5.772-4.206 5.99 5.99 0 0 0 3.997-2.9 6.056 6.056 0 0 0-.747-7.073zM13.26 22.43a4.476 4.476 0 0 1-2.876-1.04l.141-.081 4.779-2.758a.795.795 0 0 0 .392-.681v-6.737l2.02 1.168a.071.071 0 0 1 .038.052v5.583a4.504 4.504 0 0 1-4.494 4.494zM3.6 18.304a4.47 4.47 0 0 1-.535-3.014l.142.085 4.783 2.759a.771.771 0 0 0 .78 0l5.843-3.369v2.332a.08.08 0 0 1-.033.062L9.74 19.95a4.5 4.5 0 0 1-6.14-1.646zM2.34 7.896a4.485 4.485 0 0 1 2.366-1.973V11.6a.766.766 0 0 0 .388.676l5.815 3.355-2.02 1.168a.076.076 0 0 1-.071 0l-4.83-2.786A4.504 4.504 0 0 1 2.34 7.872zm16.597 3.855l-5.833-3.387L15.119 7.2a.076.076 0 0 1 .071 0l4.83 2.791a4.494 4.494 0 0 1-.676 8.105v-5.678a.79.79 0 0 0-.407-.667zm2.01-3.023l-.141-.085-4.774-2.782a.776.776 0 0 0-.785 0L9.409 9.23V6.897a.066.066 0 0 1 .028-.061l4.83-2.787a4.5 4.5 0 0 1 6.68 4.66zm-12.64 4.135l-2.02-1.164a.08.08 0 0 1-.038-.057V6.075a4.5 4.5 0 0 1 7.375-3.453l-.142.08L8.704 5.46a.795.795 0 0 0-.393.681zm1.097-2.365l2.602-1.5 2.607 1.5v2.999l-2.597 1.5-2.607-1.5z"/>
+</svg>

docs/assets/sponsors/vercel-light.svg

@@ -0,0 +1,5 @@
+<svg width="256" height="51" viewBox="0 0 256 50.875" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g transform="scale(0.125)">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M467.444 406.809L233.722 0.335938L0 406.809H467.444ZM703.186 388.306L898.51 18.813H814.024L679.286 287.152L544.547 18.813H460.061L655.385 388.306H703.186ZM2034.31 18.813V388.307H1964.37V18.813H2034.31ZM1644.98 250.395C1644.98 221.599 1650.99 196.272 1663.01 174.415C1675.03 152.557 1691.79 135.731 1713.28 123.935C1734.77 112.139 1759.91 106.241 1788.69 106.241C1814.19 106.241 1837.14 111.792 1857.54 122.894C1877.94 133.996 1894.15 150.476 1906.17 172.333C1918.19 194.191 1924.39 220.905 1924.75 252.477V268.61H1718.75C1720.2 291.508 1726.94 309.549 1738.96 322.733C1751.35 335.57 1767.93 341.988 1788.69 341.988C1801.8 341.988 1813.83 338.519 1824.75 331.58C1835.68 324.641 1843.88 315.274 1849.34 303.478L1920.93 308.682C1912.18 334.702 1895.79 355.519 1871.75 371.131C1847.7 386.744 1820.02 394.55 1788.69 394.55C1759.91 394.55 1734.77 388.652 1713.28 376.856C1691.79 365.06 1675.03 348.233 1663.01 326.376C1650.99 304.518 1644.98 279.192 1644.98 250.395ZM1852.62 224.375C1850.07 201.823 1842.97 185.344 1831.31 174.935C1819.65 164.18 1805.45 158.802 1788.69 158.802C1769.38 158.802 1753.72 164.527 1741.7 175.976C1729.67 187.425 1722.21 203.558 1719.29 224.375H1852.62ZM1526.96 174.935C1538.62 184.303 1545.9 197.313 1548.82 213.966L1620.94 210.323C1618.39 189.16 1610.93 170.772 1598.54 155.159C1586.15 139.547 1570.13 127.578 1550.45 119.251C1531.15 110.577 1509.84 106.241 1486.52 106.241C1457.74 106.241 1432.61 112.139 1411.11 123.935C1389.62 135.731 1372.86 152.557 1360.84 174.415C1348.82 196.272 1342.81 221.599 1342.81 250.395C1342.81 279.192 1348.82 304.518 1360.84 326.376C1372.86 348.233 1389.62 365.06 1411.11 376.856C1432.61 388.652 1457.74 394.55 1486.52 394.55C1510.56 394.55 1532.42 390.213 1552.09 381.54C1571.77 372.519 1587.79 359.856 1600.18 343.549C1612.57 327.243 1620.03 308.161 1622.58 286.304L1549.91 283.181C1547.36 301.569 1540.25 315.794 1528.6 325.855C1516.94 335.57 1502.91 340.427 1486.52 340.427C1463.94 340.427 1446.45 332.621 1434.06 317.008C1421.68 301.396 1415.49 279.192 1415.49 250.395C1415.49 221.599 1421.68 199.395 1434.06 183.782C1446.45 168.17 1463.94 160.364 1486.52 160.364C1502.19 160.364 1515.66 165.221 1526.96 174.935ZM1172.15 112.473H1237.24L1239.12 165.559C1243.74 150.533 1250.16 138.864 1258.39 130.552C1270.32 118.5 1286.96 112.473 1308.29 112.473H1334.87V169.293H1307.75C1292.56 169.293 1280.09 171.359 1270.32 175.491C1260.92 179.624 1253.69 186.166 1248.63 195.12C1243.93 204.073 1241.58 215.437 1241.58 229.211V388.306H1172.15V112.473ZM871.925 174.415C859.904 196.272 853.893 221.599 853.893 250.395C853.893 279.192 859.904 304.518 871.925 326.376C883.947 348.233 900.704 365.06 922.198 376.856C943.691 388.652 968.827 394.55 997.606 394.55C1028.93 394.55 1056.62 386.744 1080.66 371.131C1104.71 355.519 1121.1 334.702 1129.84 308.682L1058.26 303.478C1052.8 315.274 1044.6 324.641 1033.67 331.58C1022.74 338.519 1010.72 341.988 997.606 341.988C976.841 341.988 960.266 335.57 947.88 322.733C935.858 309.549 929.119 291.508 927.662 268.61H1133.67V252.477C1133.3 220.905 1127.11 194.191 1115.09 172.333C1103.07 150.476 1086.86 133.996 1066.46 122.894C1046.06 111.792 1023.11 106.241 997.606 106.241C968.827 106.241 943.691 112.139 922.198 123.935C900.704 135.731 883.947 152.557 871.925 174.415ZM1040.23 174.935C1051.88 185.344 1058.99 201.823 1061.54 224.375H928.208C931.123 203.558 938.591 187.425 950.612 175.976C962.634 164.527 978.298 158.802 997.606 158.802C1014.36 158.802 1028.57 164.18 1040.23 174.935Z" fill="black"/>
+</g>
+</svg>

docs/assets/sponsors/vercel.svg

@@ -0,0 +1,5 @@
+<svg width="256" height="51" viewBox="0 0 256 50.875" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g transform="scale(0.125)">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M467.444 406.809L233.722 0.335938L0 406.809H467.444ZM703.186 388.306L898.51 18.813H814.024L679.286 287.152L544.547 18.813H460.061L655.385 388.306H703.186ZM2034.31 18.813V388.307H1964.37V18.813H2034.31ZM1644.98 250.395C1644.98 221.599 1650.99 196.272 1663.01 174.415C1675.03 152.557 1691.79 135.731 1713.28 123.935C1734.77 112.139 1759.91 106.241 1788.69 106.241C1814.19 106.241 1837.14 111.792 1857.54 122.894C1877.94 133.996 1894.15 150.476 1906.17 172.333C1918.19 194.191 1924.39 220.905 1924.75 252.477V268.61H1718.75C1720.2 291.508 1726.94 309.549 1738.96 322.733C1751.35 335.57 1767.93 341.988 1788.69 341.988C1801.8 341.988 1813.83 338.519 1824.75 331.58C1835.68 324.641 1843.88 315.274 1849.34 303.478L1920.93 308.682C1912.18 334.702 1895.79 355.519 1871.75 371.131C1847.7 386.744 1820.02 394.55 1788.69 394.55C1759.91 394.55 1734.77 388.652 1713.28 376.856C1691.79 365.06 1675.03 348.233 1663.01 326.376C1650.99 304.518 1644.98 279.192 1644.98 250.395ZM1852.62 224.375C1850.07 201.823 1842.97 185.344 1831.31 174.935C1819.65 164.18 1805.45 158.802 1788.69 158.802C1769.38 158.802 1753.72 164.527 1741.7 175.976C1729.67 187.425 1722.21 203.558 1719.29 224.375H1852.62ZM1526.96 174.935C1538.62 184.303 1545.9 197.313 1548.82 213.966L1620.94 210.323C1618.39 189.16 1610.93 170.772 1598.54 155.159C1586.15 139.547 1570.13 127.578 1550.45 119.251C1531.15 110.577 1509.84 106.241 1486.52 106.241C1457.74 106.241 1432.61 112.139 1411.11 123.935C1389.62 135.731 1372.86 152.557 1360.84 174.415C1348.82 196.272 1342.81 221.599 1342.81 250.395C1342.81 279.192 1348.82 304.518 1360.84 326.376C1372.86 348.233 1389.62 365.06 1411.11 376.856C1432.61 388.652 1457.74 394.55 1486.52 394.55C1510.56 394.55 1532.42 390.213 1552.09 381.54C1571.77 372.519 1587.79 359.856 1600.18 343.549C1612.57 327.243 1620.03 308.161 1622.58 286.304L1549.91 283.181C1547.36 301.569 1540.25 315.794 1528.6 325.855C1516.94 335.57 1502.91 340.427 1486.52 340.427C1463.94 340.427 1446.45 332.621 1434.06 317.008C1421.68 301.396 1415.49 279.192 1415.49 250.395C1415.49 221.599 1421.68 199.395 1434.06 183.782C1446.45 168.17 1463.94 160.364 1486.52 160.364C1502.19 160.364 1515.66 165.221 1526.96 174.935ZM1172.15 112.473H1237.24L1239.12 165.559C1243.74 150.533 1250.16 138.864 1258.39 130.552C1270.32 118.5 1286.96 112.473 1308.29 112.473H1334.87V169.293H1307.75C1292.56 169.293 1280.09 171.359 1270.32 175.491C1260.92 179.624 1253.69 186.166 1248.63 195.12C1243.93 204.073 1241.58 215.437 1241.58 229.211V388.306H1172.15V112.473ZM871.925 174.415C859.904 196.272 853.893 221.599 853.893 250.395C853.893 279.192 859.904 304.518 871.925 326.376C883.947 348.233 900.704 365.06 922.198 376.856C943.691 388.652 968.827 394.55 997.606 394.55C1028.93 394.55 1056.62 386.744 1080.66 371.131C1104.71 355.519 1121.1 334.702 1129.84 308.682L1058.26 303.478C1052.8 315.274 1044.6 324.641 1033.67 331.58C1022.74 338.519 1010.72 341.988 997.606 341.988C976.841 341.988 960.266 335.57 947.88 322.733C935.858 309.549 929.119 291.508 927.662 268.61H1133.67V252.477C1133.3 220.905 1127.11 194.191 1115.09 172.333C1103.07 150.476 1086.86 133.996 1066.46 122.894C1046.06 111.792 1023.11 106.241 997.606 106.241C968.827 106.241 943.691 112.139 922.198 123.935C900.704 135.731 883.947 152.557 871.925 174.415ZM1040.23 174.935C1051.88 185.344 1058.99 201.823 1061.54 224.375H928.208C931.123 203.558 938.591 187.425 950.612 175.976C962.634 164.527 978.298 158.802 997.606 158.802C1014.36 158.802 1028.57 164.18 1040.23 174.935Z" fill="white"/>
+</g>
+</svg>

docs/auth-credential-semantics.md

@@ -0,0 +1,103 @@
+---
+summary: "Canonical credential eligibility and resolution semantics for auth profiles"
+title: "Auth credential semantics"
+read_when:
+  - Working on auth profile resolution or credential routing
+  - Debugging model auth failures or profile order
+---
+
+These semantics keep selection-time and runtime auth behavior aligned. They are shared by:
+
+- `resolveAuthProfileOrder` (profile ordering)
+- `resolveApiKeyForProfile` (runtime credential resolution)
+- `openclaw models status --probe`
+- `openclaw doctor` auth checks (`doctor-auth`)
+
+## Stable probe reason codes
+
+Probe results carry a `status` bucket (`ok`, `auth`, `rate_limit`, `billing`, `timeout`, `format`, `unknown`, `no_model`) plus a stable `reasonCode` when the probe never reached a model call:
+
+| `reasonCode`             | Meaning                                                                      |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| `excluded_by_auth_order` | Profile omitted from the explicit auth order for its provider.               |
+| `missing_credential`     | No inline credential or SecretRef is configured.                             |
+| `expired`                | Token `expires` is in the past.                                              |
+| `invalid_expires`        | `expires` is not a valid positive Unix ms timestamp.                         |
+| `unresolved_ref`         | Configured SecretRef could not be resolved.                                  |
+| `ineligible_profile`     | Profile is incompatible with provider config (includes malformed key input). |
+| `no_model`               | Credentials exist but no probeable model candidate resolved.                 |
+
+Eligibility checks report `ok` as the reason code for usable credentials.
+
+## Token credentials
+
+Token credentials (`type: "token"`) support inline `token` and/or `tokenRef`.
+
+### Eligibility rules
+
+1. A token profile is ineligible when both `token` and `tokenRef` are absent (`missing_credential`).
+2. `expires` is optional. When present it must be a finite number of Unix epoch milliseconds greater than `0` and no larger than the maximum JavaScript `Date` timestamp (8640000000000000).
+3. If `expires` is invalid (wrong type, `NaN`, `0`, negative, non-finite, or beyond that maximum), the profile is ineligible with `invalid_expires`.
+4. If `expires` is in the past, the profile is ineligible with `expired`.
+5. `tokenRef` does not bypass `expires` validation.
+
+### Resolution rules
+
+1. Resolver semantics match eligibility semantics for `expires`.
+2. For eligible profiles, token material may be resolved from the inline value or `tokenRef`.
+3. Unresolvable refs produce `unresolved_ref` in `models status --probe` output.
+
+## Agent copy portability
+
+Agent auth inheritance is read-through. When an agent has no local profile, it resolves profiles from the default/main agent store at runtime without copying secret material into its own credential store (`agents/<agentId>/agent/openclaw-agent.sqlite`).
+
+Explicit copy flows, such as `openclaw agents add`, use this portability policy:
+
+- `api_key` and `token` profiles are portable unless `copyToAgents: false`.
+- `oauth` profiles are not portable by default because refresh tokens can be single-use or rotation-sensitive.
+- Provider-owned OAuth flows may opt in with `copyToAgents: true` only when copying refresh material across agents is known safe; the opt-in only applies when the profile carries inline access/refresh material.
+
+Non-portable profiles remain available through read-through inheritance unless the target agent signs in separately and creates its own local profile.
+
+## Config-only auth routes
+
+`auth.profiles` entries with `mode: "aws-sdk"` are routing metadata, not stored credentials. They are valid when the target provider uses `models.providers.<id>.auth: "aws-sdk"`, the route the plugin-owned Amazon Bedrock setup writes. These profile ids may appear in `auth.order` and session overrides even when no matching entry exists in the credential store.
+
+Do not write `type: "aws-sdk"` into the credential store; stored credentials are only `api_key`, `token`, or `oauth`. If a legacy `auth-profiles.json` has such a marker, `openclaw doctor --fix` moves it to `auth.profiles` and removes the marker from the store.
+
+## Explicit auth order filtering
+
+- When `auth.order.<provider>` or the auth-store order override is set for a provider, `models status --probe` only probes profile ids that remain in the resolved auth order for that provider. The stored override wins over `auth.order` config.
+- A stored profile for that provider that is omitted from the explicit order is not silently tried later. Probe output reports it with `reasonCode: excluded_by_auth_order` and the detail `Excluded by auth.order for this provider.`
+
+## Probe target resolution
+
+- Probe targets can come from auth profiles, environment credentials, or `models.json` (result `source`: `profile`, `env`, `models.json`).
+- If a provider has credentials but OpenClaw cannot resolve a probeable model candidate for it, `models status --probe` reports `status: no_model` with `reasonCode: no_model`.
+
+## External CLI credential discovery
+
+- Runtime-only credentials owned by external CLIs (Claude CLI for `claude-cli`, Codex CLI for `openai`, MiniMax CLI for `minimax-portal`) are discovered only when the provider, runtime, or auth profile is in scope for the current operation, or when a stored local profile for that external source already exists.
+- Auth-store callers choose an explicit external-CLI discovery mode: `none` for persisted/plugin auth only, `existing` for refreshing already stored external CLI profiles, or `scoped` for a concrete provider/profile set.
+- Read-only/status paths pass `allowKeychainPrompt: false`; they use file-backed external CLI credentials only and do not read or reuse macOS Keychain results.
+
+## OAuth SecretRef Policy Guard
+
+SecretRef input is for static credentials only. OAuth credentials are runtime-mutable (refresh flows persist rotated tokens), so SecretRef-backed OAuth material would split mutable state across stores.
+
+- If a profile credential is `type: "oauth"`, SecretRef objects are rejected for any credential material field on that profile.
+- If `auth.profiles.<id>.mode` is `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
+- Violations are hard failures (thrown errors) in startup/reload secret preparation and profile resolution paths.
+
+## Legacy-Compatible Messaging
+
+For script compatibility, probe errors keep this first line unchanged:
+
+`Auth profile credentials are missing or expired.`
+
+Human-friendly detail and the stable reason code follow on subsequent lines in the form `↳ Auth reason [code]: ...`.
+
+## Related
+
+- [Secrets management](/gateway/secrets)
+- [Auth storage](/concepts/oauth)

docs/automation/auth-monitoring.md

@@ -0,0 +1,11 @@
+---
+summary: "Redirect to /gateway/authentication"
+title: "Auth monitoring"
+---
+
+This page moved. Model provider authentication lives under [Authentication](/gateway/authentication); ops scripts for monitoring auth state live at [Auth monitoring scripts](/help/scripts#auth-monitoring-scripts).
+
+## Related
+
+- [Automation troubleshooting](/automation/cron-jobs#troubleshooting)
+- [Hooks](/automation/hooks)

docs/automation/clawflow.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to Task Flow"
+title: "ClawFlow"
+---
+
+ClawFlow was renamed to [Task Flow](/automation/taskflow). Use that page for durable multi-step flow orchestration.
+
+## Related
+
+- [Task Flow](/automation/taskflow)
+- [Standing orders](/automation/standing-orders)
+- [Hooks](/automation/hooks)

docs/automation/cron-jobs.md

@@ -0,0 +1,586 @@
+---
+summary: "Scheduled jobs, webhooks, and Gmail PubSub triggers for the Gateway scheduler"
+read_when:
+  - Scheduling background jobs or wakeups
+  - Wiring external triggers (webhooks, Gmail) into OpenClaw
+  - Deciding between heartbeat and cron for scheduled tasks
+title: "Scheduled tasks"
+sidebarTitle: "Scheduled tasks"
+---
+
+Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel, a webhook, or nowhere.
+
+## Quick start
+
+<Steps>
+  <Step title="Add a one-shot reminder">
+    ```bash
+    openclaw cron create "2027-02-01T16:00:00Z" \
+      --name "Reminder" \
+      --session main \
+      --system-event "Reminder: check the cron docs draft" \
+      --wake now \
+      --delete-after-run
+    ```
+  </Step>
+  <Step title="Check your jobs">
+    ```bash
+    openclaw cron list
+    openclaw cron get <job-id>
+    openclaw cron show <job-id>
+    ```
+  </Step>
+  <Step title="See run history">
+    ```bash
+    openclaw cron runs --id <job-id>
+    ```
+  </Step>
+</Steps>
+
+## How cron works
+
+- Cron runs **inside the Gateway process**, not inside the model. The Gateway must be running for schedules to fire.
+- Job definitions, runtime state, and run history persist in OpenClaw's shared SQLite state database, so restarts do not lose schedules.
+- Every cron execution creates a [background task](/automation/tasks) record.
+- One-shot jobs (`--at`) auto-delete after success by default; pass `--keep-after-run` to keep them.
+- Per-run wall-clock budget: `--timeout-seconds` when set. Otherwise, isolated/detached agent-turn jobs are bounded by cron's own 60-minute watchdog before the underlying agent-turn timeout (`agents.defaults.timeoutSeconds`, default 48 hours) would ever apply; command jobs default to 10 minutes.
+- On Gateway startup, overdue isolated agent-turn jobs are rescheduled instead of replayed immediately, keeping model/tool bootstrap work out of the channel-connect window.
+- If you drive `openclaw agent` from system cron or another external scheduler, wrap it with a hard-kill escalation even though the CLI already handles `SIGTERM`/`SIGINT`. Gateway-backed runs ask the Gateway to abort accepted runs; local and embedded fallback runs get the same abort signal. For GNU `timeout`, prefer `timeout -k 60 600 openclaw agent ...` over plain `timeout 600 ...` — the `-k` value is the backstop if the process cannot drain in time. For systemd units, use a `SIGTERM` stop signal with a grace window (`TimeoutStopSec`) before the final kill. Reusing a `--run-id` while the original Gateway run is still active reports the duplicate as in-flight instead of starting a second run.
+
+<AccordionGroup>
+  <Accordion title="Isolated run hardening">
+    - Isolated runs best-effort close tracked browser tabs/processes for their `cron:<jobId>` session on completion, and dispose any bundled MCP runtime instances created for the job through the same shared teardown path used by main-session and custom-session runs. Cleanup failures are ignored so the cron result still wins.
+    - Isolated runs with the narrow cron self-cleanup grant can read scheduler status, a self-filtered list containing only their own job, and that job's run history, and may remove only their own job.
+    - Isolated runs guard against stale acknowledgement replies: if the first result is only an interim status update (`on it`, `pulling everything together`, and similar hints) and no descendant subagent is still responsible for the final answer, OpenClaw re-prompts once for the actual result before delivery.
+    - Structured execution-denial metadata (including node-host `UNAVAILABLE` wrappers whose nested error starts with `SYSTEM_RUN_DENIED` or `INVALID_REQUEST`) is recognized so a blocked command is not reported as a green run, while ordinary assistant prose is not mistaken for a denial.
+    - Run-level agent failures count as job errors even with no reply payload, so model/provider failures increment error counters and trigger failure notifications instead of clearing the job as successful.
+    - When a job hits `timeoutSeconds`, cron aborts the run and gives it a short cleanup window. If it does not drain, Gateway-owned cleanup force-clears that run's session ownership before cron records the timeout, so queued chat work is not stuck behind a stale processing session.
+    - Setup/startup stalls get a phase-specific timeout (for example `cron: isolated agent setup timed out before runner start` or `cron: isolated agent run stalled before execution start (last phase: context-engine)`). These watchdogs cover embedded and CLI-backed providers even before their external CLI process starts, and are capped independently of long `timeoutSeconds` values so cold-start/auth/context failures surface quickly.
+
+  </Accordion>
+  <Accordion title="Task reconciliation">
+    Cron task reconciliation is runtime-owned first, durable-history-backed second: an active cron task stays live while the cron runtime still tracks that job as running, even if an old child session row still exists. Once the runtime stops owning the job and a 5-minute grace window expires, maintenance checks persisted run logs and job state for the matching `cron:<jobId>:<startedAt>` run. A terminal result there finalizes the task ledger; otherwise Gateway-owned maintenance can mark the task `lost`. Offline CLI audit can recover from durable history, but its own empty in-process active-job set is not proof a Gateway-owned run is gone.
+  </Accordion>
+</AccordionGroup>
+
+## Schedule types
+
+| Kind      | CLI flag    | Description                                                                                              |
+| --------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| `at`      | `--at`      | One-shot timestamp (ISO 8601 or relative like `20m`)                                                     |
+| `every`   | `--every`   | Fixed interval (`10m`, `1h`, `1d`)                                                                       |
+| `cron`    | `--cron`    | 5-field or 6-field cron expression with optional `--tz`                                                  |
+| `on-exit` | `--on-exit` | Fire once when a watched command exits (event trigger; survives turn teardown; optional `--on-exit-cwd`) |
+
+Timestamps without a timezone are treated as UTC. Add `--tz America/New_York` to interpret an offset-less `--at` datetime, or to evaluate a cron expression, in that IANA timezone. Cron expressions without `--tz` use the Gateway host timezone. `--tz` is not valid with `--every` or `--on-exit`.
+
+Recurring top-of-hour expressions (minute `0` with a wildcard hour field) are automatically staggered by up to 5 minutes to reduce load spikes. Use `--exact` to force precise timing, or `--stagger 30s` for an explicit window (cron schedules only).
+
+### Day-of-month and day-of-week use OR logic
+
+Cron expressions are parsed by [croner](https://github.com/Hexagon/croner). When both the day-of-month and day-of-week fields are non-wildcard, croner matches when **either** field matches, not both. This is standard Vixie cron behavior.
+
+```bash
+# Intended: "9 AM on the 15th, only if it's a Monday"
+# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
+0 9 15 * 1
+```
+
+This fires roughly 5-6 times a month instead of 0-1 times a month. To require both conditions, use croner's `+` day-of-week modifier (`0 9 15 * +1`), or schedule on one field and guard the other in your job's prompt or command.
+
+## Payloads
+
+Every job carries exactly one payload kind, chosen by flag:
+
+| Payload       | Flag                                           | Runs                                                    |
+| ------------- | ---------------------------------------------- | ------------------------------------------------------- |
+| System event  | `--system-event <text>`                        | Enqueued into the main session, no model call by itself |
+| Agent message | `--message <text>`                             | A model-backed agent turn                               |
+| Command       | `--command <shell>` or `--command-argv <json>` | A shell/process on the Gateway host, no model call      |
+
+### Agent-turn options
+
+<ParamField path="--message" type="string" required>
+  Prompt text (required for isolated/current/custom-session jobs).
+</ParamField>
+<ParamField path="--model" type="string">
+  Model override; must resolve to an allowed model or the run fails with a validation error.
+</ParamField>
+<ParamField path="--fallbacks" type="string">
+  Per-job fallback model list, for example `--fallbacks openai/gpt-5.5,openrouter/meta-llama/llama-3.3-70b-instruct:free`. Pass `--fallbacks ""` for a strict run with no fallbacks.
+</ParamField>
+<ParamField path="--clear-fallbacks" type="boolean">
+  On `cron edit`, removes the per-job fallback override so the job follows configured fallback precedence. Cannot combine with `--fallbacks`.
+</ParamField>
+<ParamField path="--clear-model" type="boolean">
+  On `cron edit`, removes the per-job model override so the job follows normal cron model precedence (stored cron-session override, else agent/default model). Cannot combine with `--model`.
+</ParamField>
+<ParamField path="--thinking" type="string">
+  Thinking level override (`off|minimal|low|medium|high|xhigh|adaptive|max`).
+</ParamField>
+<ParamField path="--clear-thinking" type="boolean">
+  On `cron edit`, removes the per-job thinking override. Cannot combine with `--thinking`.
+</ParamField>
+<ParamField path="--light-context" type="boolean">
+  Skip workspace bootstrap file injection.
+</ParamField>
+<ParamField path="--tools" type="string">
+  Restrict which tools the job can use, for example `--tools exec,read`.
+</ParamField>
+
+`--model` sets the job's primary model; it does not replace a session `/model` override, so configured fallback chains still apply on top of it. An unresolved or disallowed model fails the run with an explicit validation error rather than silently falling back to the default. If a job has `--model` but no explicit or configured fallback list, OpenClaw passes an empty fallback override instead of silently appending the agent primary as a hidden retry target.
+
+Model-selection precedence for isolated jobs, highest first:
+
+1. Per-job payload `model` (explicit config; a disallowed model fails the run)
+2. Gmail hook model override (only when the run came from Gmail and that override is allowed)
+3. User-selected stored cron-session model override
+4. Agent/default model selection
+
+Fast mode follows the resolved live selection. If the selected model config has `params.fastMode`, isolated cron uses it by default; a stored session `fastMode` override (then an agent `fastModeDefault`) still wins over model config either direction. Auto mode uses the model's `params.fastAutoOnSeconds` cutoff, defaulting to 60 seconds.
+
+If a run hits a live model-switch handoff, cron retries with the switched provider/model and persists that selection (and any new auth profile) for the active run. Retries are bounded: after the initial attempt plus 2 switch retries, cron aborts instead of looping.
+
+Before an isolated run starts, OpenClaw checks reachable local endpoints for configured `api: "ollama"` and `api: "openai-completions"` providers whose `baseUrl` is loopback, private-network, or `.local`. This preflight walks the job's configured fallback chain and only marks the run `skipped` once every candidate is unreachable; `--fallbacks ""` keeps that walk strict to just the primary model. A down endpoint records the run as `skipped` with a clear error instead of starting a model call. The result is cached for 5 minutes per endpoint (not per job or model), so many due jobs sharing a dead local Ollama/vLLM/SGLang/LM Studio server cost one probe instead of a request storm. Skipped preflight runs do not increment execution-error backoff; set `failureAlert.includeSkipped` to opt into repeated skip alerts.
+
+### Command payloads
+
+Command payloads run deterministic scripts inside the Gateway scheduler without starting a model-backed turn. They execute on the Gateway host, capture stdout/stderr, record the run in cron history, and reuse the same `announce`, `webhook`, and `none` delivery modes as agent-turn jobs.
+
+<Note>
+Command cron is an operator-admin Gateway automation surface, not an agent `tools.exec` call. Creating, updating, removing, or manually running cron jobs requires `operator.admin`; scheduled command runs later execute inside the Gateway process as that admin-authored automation. Agent exec policy (`tools.exec.mode`, approval prompts, per-agent tool allowlists) governs model-visible exec tools, not command cron payloads.
+</Note>
+
+```bash
+openclaw cron create "*/15 * * * *" \
+  --name "Queue depth probe" \
+  --command "scripts/check-queue.sh" \
+  --command-cwd "/srv/app" \
+  --announce \
+  --channel telegram \
+  --to "-1001234567890"
+```
+
+`--command <shell>` stores `argv: ["sh", "-lc", <shell>]`. Use `--command-argv '["node","scripts/report.mjs"]'` for exact argv execution without shell parsing. Optional `--command-env KEY=VALUE` (repeatable), `--command-input`, `--timeout-seconds` (default 10 minutes), `--no-output-timeout-seconds`, and `--output-max-bytes` control the process environment, stdin, and output bounds.
+
+Delivered text is derived from process output: non-empty stdout wins; if stdout is empty and stderr is non-empty, stderr is delivered; if both are present, cron sends a small `stdout:` / `stderr:` block. Exit code `0` records the run `ok`; non-zero exit, signal, timeout, or no-output timeout records `error` and can trigger failure alerts. A command that prints only `NO_REPLY` uses the normal cron silent-token suppression and posts nothing back to chat.
+
+## Execution styles
+
+| Style           | `--session` value   | Runs in                  | Best for                        |
+| --------------- | ------------------- | ------------------------ | ------------------------------- |
+| Main session    | `main`              | Dedicated cron wake lane | Reminders, system events        |
+| Isolated        | `isolated`          | Dedicated `cron:<jobId>` | Reports, background chores      |
+| Current session | `current`           | Bound at creation time   | Context-aware recurring work    |
+| Custom session  | `session:custom-id` | Persistent named session | Workflows that build on history |
+
+<AccordionGroup>
+  <Accordion title="Main session vs isolated vs custom">
+    **Main session** jobs enqueue a system event into a cron-owned run lane and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). They can use the target main session's last delivery context for replies, but do not append routine cron turns to the human chat lane and do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
+
+    Main-session cron events are self-contained system-event reminders. They do not automatically include the default heartbeat prompt's "Read HEARTBEAT.md" instruction; say that explicitly in the cron event text if a reminder should consult `HEARTBEAT.md`.
+
+  </Accordion>
+  <Accordion title="What 'fresh session' means for isolated jobs">
+    A new transcript/session id per run. OpenClaw carries safe preferences (thinking/fast/verbose settings, labels, explicit user-selected model/auth overrides), but does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
+  </Accordion>
+  <Accordion title="Subagent and Discord delivery">
+    When isolated cron runs orchestrate subagents, delivery prefers the final descendant output over stale parent interim text. If descendants are still running, OpenClaw suppresses that partial parent update instead of announcing it.
+
+    For text-only Discord announce targets, OpenClaw sends the canonical final assistant text once instead of replaying both streamed/intermediate text and the final answer. Media and structured Discord payloads are still delivered separately so attachments and components are not dropped.
+
+  </Accordion>
+</AccordionGroup>
+
+## Delivery and output
+
+| Mode       | What happens                                                        |
+| ---------- | ------------------------------------------------------------------- |
+| `announce` | Fallback-deliver final text to the target if the agent did not send |
+| `webhook`  | POST finished event payload to a URL                                |
+| `none`     | No runner fallback delivery                                         |
+
+Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`; OpenClaw also accepts the Telegram-owned `-1001234567890:123` shorthand. Direct RPC/config callers may pass `delivery.threadId` as a string or number. Slack/Discord/Mattermost targets use explicit prefixes (`channel:<id>`, `user:<id>`). Matrix room IDs are case-sensitive; use the exact room ID or `room:!room:server` form from Matrix.
+
+When announce delivery uses `channel: "last"` or omits `channel`, a provider-prefixed target such as `telegram:123` can select the channel before cron falls back to session history or a single configured channel. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the target prefix must name the same provider; `channel: "whatsapp"` with `to: "telegram:123"` is rejected instead of letting WhatsApp interpret the Telegram ID as a phone number. Target-kind and service prefixes (`channel:<id>`, `user:<id>`, `imessage:<handle>`, `sms:<number>`) stay channel-owned target syntax, not provider selectors.
+
+For isolated jobs, chat delivery is shared: if a chat route is available, the agent can use the `message` tool even with `--no-deliver`. If the agent sends to the configured/current target, OpenClaw skips the fallback announce. Otherwise `announce`, `webhook`, and `none` only control what the runner does with the final reply after the agent turn.
+
+When an agent creates an isolated reminder from an active chat, OpenClaw stores the preserved live delivery target for the fallback announce route. Internal session keys may be lowercase; provider delivery targets are not reconstructed from those keys when current chat context is available.
+
+Implicit announce delivery uses configured channel allowlists to validate and reroute stale targets. DM pairing-store approvals are not fallback automation recipients; set `delivery.to` or configure the channel `allowFrom` entry when a scheduled job should proactively send to a DM.
+
+### Failure notifications
+
+Failure notifications follow a separate destination path:
+
+- `cron.failureDestination` sets a global default for failure notifications.
+- `job.delivery.failureDestination` overrides that per job.
+- If neither is set and the job already delivers via `announce`, failure notifications fall back to that primary announce target.
+- `delivery.failureDestination` is only supported on `sessionTarget="isolated"` jobs unless the primary delivery mode is `webhook`.
+- `failureAlert.includeSkipped: true` opts a job or global cron alert policy into repeated skipped-run alerts. Skipped runs keep a separate consecutive-skip counter, so they do not affect execution-error backoff.
+- `openclaw cron edit` exposes per-job alert tuning: `--failure-alert`/`--no-failure-alert`, `--failure-alert-after <n>`, `--failure-alert-channel`, `--failure-alert-to`, `--failure-alert-cooldown`, `--failure-alert-include-skipped`/`--failure-alert-exclude-skipped`, `--failure-alert-mode`, and `--failure-alert-account-id`.
+
+### Output language
+
+Cron jobs do not infer a reply language from channel, locale, or previous messages. Put the language rule in the scheduled message or template:
+
+```bash
+openclaw cron edit <jobId> \
+  --message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."
+```
+
+For template files, keep the language instruction in the rendered prompt and verify placeholders such as `{{language}}` are filled before the job runs. If the output mixes languages, make the rule explicit, for example: "Use Chinese for narrative text and keep technical terms in English."
+
+## CLI examples
+
+<Tabs>
+  <Tab title="One-shot reminder">
+    ```bash
+    openclaw cron add \
+      --name "Calendar check" \
+      --at "20m" \
+      --session main \
+      --system-event "Next heartbeat: check calendar." \
+      --wake now
+    ```
+  </Tab>
+  <Tab title="Recurring isolated job">
+    ```bash
+    openclaw cron create "0 7 * * *" \
+      "Summarize overnight updates." \
+      --name "Morning brief" \
+      --tz "America/Los_Angeles" \
+      --session isolated \
+      --announce \
+      --channel slack \
+      --to "channel:C1234567890"
+    ```
+  </Tab>
+  <Tab title="Model and thinking override">
+    ```bash
+    openclaw cron add \
+      --name "Deep analysis" \
+      --cron "0 6 * * 1" \
+      --tz "America/Los_Angeles" \
+      --session isolated \
+      --message "Weekly deep analysis of project progress." \
+      --model "opus" \
+      --thinking high \
+      --announce
+    ```
+  </Tab>
+  <Tab title="Webhook output">
+    ```bash
+    openclaw cron create "0 18 * * 1-5" \
+      "Summarize today's deploys as JSON." \
+      --name "Deploy digest" \
+      --webhook "https://example.invalid/openclaw/cron"
+    ```
+  </Tab>
+  <Tab title="Command output">
+    ```bash
+    openclaw cron create "*/15 * * * *" \
+      --name "Queue depth probe" \
+      --command "scripts/check-queue.sh" \
+      --command-cwd "/srv/app" \
+      --announce \
+      --channel telegram \
+      --to "-1001234567890"
+    ```
+  </Tab>
+</Tabs>
+
+## Managing jobs
+
+```bash
+# List all jobs
+openclaw cron list
+
+# Get one stored job as JSON
+openclaw cron get <jobId>
+
+# Show one job, including resolved delivery route
+openclaw cron show <jobId>
+
+# Enable/disable without deleting
+openclaw cron enable <jobId>
+openclaw cron disable <jobId>
+
+# Edit a job
+openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
+
+# Force run a job now
+openclaw cron run <jobId>
+
+# Force run a job now and wait for its terminal status
+openclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s
+
+# Run only if due
+openclaw cron run <jobId> --due
+
+# View run history
+openclaw cron runs --id <jobId> --limit 50
+
+# View one exact run
+openclaw cron runs --id <jobId> --run-id <runId>
+
+# Delete a job
+openclaw cron remove <jobId>
+
+# Agent selection (multi-agent setups)
+openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent ops
+openclaw cron edit <jobId> --clear-agent
+```
+
+`openclaw cron run <jobId>` returns after enqueueing the manual run. Use `--wait` for shutdown hooks, maintenance scripts, or other automation that must block until the queued run finishes; it polls the returned `runId` (default timeout `10m`, poll interval `2s`) and exits `0` for status `ok`, non-zero for `error`, `skipped`, or a wait timeout.
+
+The agent `cron` tool returns compact job summaries (`id`, `name`, `enabled`, `nextRunAtMs`, `scheduleKind`, `lastRunStatus`) from `cron(action: "list")`; use `cron(action: "get", jobId: "...")` for one full job definition. Direct Gateway callers can pass `compact: true` to `cron.list`; omitting it preserves the full response with delivery previews.
+
+`openclaw cron create` is an alias for `openclaw cron add`. New jobs can use a positional schedule (`"0 9 * * 1"`, `"every 1h"`, `"20m"`, or an ISO timestamp) followed by a positional agent prompt. Use `--webhook <url>` on `cron add|create` or `cron edit` to POST the finished run payload to an HTTP endpoint; webhook delivery cannot combine with chat delivery flags (`--announce`, `--channel`, `--to`, `--thread-id`, `--account`). On `cron edit`, `--clear-channel`, `--clear-to`, `--clear-thread-id`, and `--clear-account` unset those routing fields individually (each rejected alongside its matching set flag) — distinct from `--no-deliver`, which only disables runner fallback delivery.
+
+<Note>
+Model override note:
+
+- `openclaw cron add|edit --model ...` changes the job's selected model.
+- If the model is allowed, that exact provider/model reaches the isolated agent run.
+- If it is not allowed or cannot be resolved, cron fails the run with an explicit validation error.
+- API `cron.update` payload patches can set `model: null` to clear a stored job model override.
+- `openclaw cron edit <job-id> --clear-model` clears that override from the CLI (same effect as the `model: null` patch) and cannot combine with `--model`.
+- Configured fallback chains still apply because cron `--model` is a job primary, not a session `/model` override.
+- `openclaw cron add|edit --fallbacks ...` sets payload `fallbacks`, replacing configured fallbacks for that job; `--fallbacks ""` disables fallback and makes the run strict. `openclaw cron edit <job-id> --clear-fallbacks` clears the per-job override.
+- A plain `--model` with no explicit or configured fallback list does not fall through to the agent primary as a silent extra retry target.
+
+</Note>
+
+## Webhooks
+
+Gateway can expose HTTP webhook endpoints for external triggers. Enable in config:
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "shared-secret",
+    path: "/hooks",
+  },
+}
+```
+
+### Authentication
+
+Every request must include the hook token via header:
+
+- `Authorization: Bearer <token>` (recommended)
+- `x-openclaw-token: <token>`
+
+Query-string tokens are rejected.
+
+<AccordionGroup>
+  <Accordion title="POST /hooks/wake">
+    Enqueue a system event for the main session:
+
+    ```bash
+    curl -X POST http://127.0.0.1:18789/hooks/wake \
+      -H 'Authorization: Bearer SECRET' \
+      -H 'Content-Type: application/json' \
+      -d '{"text":"New email received","mode":"now"}'
+    ```
+
+    <ParamField path="text" type="string" required>
+      Event description.
+    </ParamField>
+    <ParamField path="mode" type="string" default="now">
+      `now` or `next-heartbeat`.
+    </ParamField>
+
+  </Accordion>
+  <Accordion title="POST /hooks/agent">
+    Run an isolated agent turn:
+
+    ```bash
+    curl -X POST http://127.0.0.1:18789/hooks/agent \
+      -H 'Authorization: Bearer SECRET' \
+      -H 'Content-Type: application/json' \
+      -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.5"}'
+    ```
+
+    Fields: `message` (required), `name`, `agentId`, `sessionKey` (requires `hooks.allowRequestSessionKey=true`), `idempotencyKey`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.
+
+  </Accordion>
+  <Accordion title="Mapped hooks (POST /hooks/<name>)">
+    Custom hook names resolve via `hooks.mappings` in config. Mappings can transform arbitrary payloads into `wake` or `agent` actions with templates or code transforms.
+  </Accordion>
+</AccordionGroup>
+
+<Warning>
+Keep hook endpoints behind loopback, tailnet, or a trusted reverse proxy.
+
+- Use a dedicated hook token; do not reuse gateway auth tokens.
+- Keep `hooks.path` on a dedicated subpath; `/` is rejected.
+- Set `hooks.allowedAgentIds` to limit which effective agent a hook can target, including the default agent when `agentId` is omitted.
+- Keep `hooks.allowRequestSessionKey=false` unless you require caller-selected sessions.
+- If you enable `hooks.allowRequestSessionKey`, also set `hooks.allowedSessionKeyPrefixes` to constrain allowed session key shapes.
+- Hook payloads are wrapped with safety boundaries by default.
+
+</Warning>
+
+## Gmail PubSub integration
+
+Wire Gmail inbox triggers to OpenClaw via Google PubSub.
+
+<Note>
+**Prerequisites:** `gcloud` CLI, `gog` (gogcli), OpenClaw hooks enabled, Tailscale for the public HTTPS endpoint.
+</Note>
+
+### Wizard setup (recommended)
+
+```bash
+openclaw webhooks gmail setup --account openclaw@gmail.com
+```
+
+This writes `hooks.gmail` config, enables the Gmail preset, and defaults to Tailscale Funnel for the push endpoint (`--tailscale funnel|serve|off`).
+
+### Gateway auto-start
+
+When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts `gog gmail watch serve` on boot and auto-renews the watch. Set `OPENCLAW_SKIP_GMAIL_WATCHER=1` to opt out.
+
+### Manual one-time setup
+
+<Steps>
+  <Step title="Select the GCP project">
+    Select the GCP project that owns the OAuth client used by `gog`:
+
+    ```bash
+    gcloud auth login
+    gcloud config set project <project-id>
+    gcloud services enable gmail.googleapis.com pubsub.googleapis.com
+    ```
+
+  </Step>
+  <Step title="Create topic and grant Gmail push access">
+    ```bash
+    gcloud pubsub topics create gog-gmail-watch
+    gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
+      --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
+      --role=roles/pubsub.publisher
+    ```
+  </Step>
+  <Step title="Start the watch">
+    ```bash
+    gog gmail watch start \
+      --account openclaw@gmail.com \
+      --label INBOX \
+      --topic projects/<project-id>/topics/gog-gmail-watch
+    ```
+  </Step>
+</Steps>
+
+### Gmail model override
+
+```json5
+{
+  hooks: {
+    gmail: {
+      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
+      thinking: "off",
+    },
+  },
+}
+```
+
+## Configuration
+
+```json5
+{
+  cron: {
+    enabled: true,
+    store: "~/.openclaw/cron/jobs.json",
+    maxConcurrentRuns: 8,
+    retry: {
+      maxAttempts: 3,
+      backoffMs: [30000, 60000, 300000],
+      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
+    },
+    webhookToken: "replace-with-dedicated-webhook-token",
+    sessionRetention: "24h",
+    runLog: { maxBytes: "2mb", keepLines: 2000 },
+  },
+}
+```
+
+The `retry` values above are the defaults: up to 3 retries with `30s/60s/5m` backoff, retrying all five transient categories. `webhookToken` is sent as `Authorization: Bearer <token>` on cron webhook POSTs.
+
+`maxConcurrentRuns` limits both scheduled cron dispatch and isolated agent-turn execution, and defaults to 8. Isolated cron agent turns use the queue's dedicated `cron-nested` execution lane internally, so raising this value lets independent cron LLM runs progress in parallel instead of only starting their outer cron wrappers. The shared non-cron `nested` lane is not widened by this setting.
+
+`cron.store` is a logical store key and doctor migration path, not a live JSON file to hand-edit. Job data lives in SQLite; use the CLI or Gateway API for changes.
+
+Disable cron: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
+
+<AccordionGroup>
+  <Accordion title="Retry behavior">
+    **One-shot retry**: transient errors (rate limit, overload, network, timeout, server error) retry up to `retry.maxAttempts` times (default 3) using `retry.backoffMs` (default 30s, 60s, 5m). Permanent errors disable the job immediately.
+
+    **Recurring retry**: consecutive execution errors back off on an extended schedule (30s, 60s, 5m, 15m, 60m). Backoff resets after the next successful run.
+
+  </Accordion>
+  <Accordion title="Maintenance">
+    `cron.sessionRetention` (default `24h`, `false` disables) prunes isolated run-session entries. `cron.runLog.keepLines` limits retained SQLite run-history rows per job; `maxBytes` is retained for config compatibility with older file-backed run logs.
+  </Accordion>
+  <Accordion title="Legacy store migration">
+    On upgrade, run `openclaw doctor --fix` to import legacy `~/.openclaw/cron/jobs.json`, `jobs-state.json`, and `runs/*.jsonl` files into SQLite and rename them with a `.migrated` suffix. Malformed job rows are skipped from runtime and copied to `jobs-quarantine.json` for later repair or review.
+  </Accordion>
+</AccordionGroup>
+
+## Troubleshooting
+
+### Command ladder
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw cron status
+openclaw cron list
+openclaw cron runs --id <jobId> --limit 20
+openclaw system heartbeat last
+openclaw logs --follow
+openclaw doctor
+```
+
+<AccordionGroup>
+  <Accordion title="Cron not firing">
+    - Check `cron.enabled` and the `OPENCLAW_SKIP_CRON` env var.
+    - Confirm the Gateway is running continuously.
+    - For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
+    - `reason: not-due` in run output means the manual run was checked with `openclaw cron run <jobId> --due` and the job was not due yet.
+
+  </Accordion>
+  <Accordion title="Cron fired but no delivery">
+    - Delivery mode `none` means no runner fallback send is expected. The agent can still send directly with the `message` tool when a chat route is available.
+    - Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
+    - For Matrix, copied or legacy jobs with lowercased `delivery.to` room IDs can fail because Matrix room IDs are case-sensitive. Edit the job to the exact `!room:server` or `room:!room:server` value from Matrix.
+    - Channel auth errors (`unauthorized`, `Forbidden`) mean delivery was blocked by credentials.
+    - If the isolated run returns only the silent token (`NO_REPLY` / `no_reply`), OpenClaw suppresses direct outbound delivery and the fallback queued-summary path, so nothing is posted back to chat.
+    - If the agent should message the user itself, check that the job has a usable route (`channel: "last"` with a previous chat, or an explicit channel/target).
+
+  </Accordion>
+  <Accordion title="Cron or heartbeat appears to prevent /new-style rollover">
+    - Daily and idle reset freshness is not based on `updatedAt`; see [Session management](/concepts/session#session-lifecycle).
+    - Cron wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may update the session row for routing/status, but they do not extend `sessionStartedAt` or `lastInteractionAt`.
+    - For legacy rows created before those fields existed, OpenClaw can recover `sessionStartedAt` from the transcript JSONL session header when the file is still available. Legacy idle rows without `lastInteractionAt` use that recovered start time as their idle baseline.
+
+  </Accordion>
+  <Accordion title="Timezone gotchas">
+    - Cron without `--tz` uses the gateway host timezone.
+    - `at` schedules without timezone are treated as UTC.
+    - Heartbeat `activeHours` uses configured timezone resolution.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Automation](/automation) — all automation mechanisms at a glance
+- [Background Tasks](/automation/tasks) — task ledger for cron executions
+- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [Timezone](/concepts/timezone) — timezone configuration

docs/automation/cron-vs-heartbeat.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /automation"
+title: "Cron vs heartbeat"
+---
+
+This page moved. See [Scheduled Tasks (Cron) vs Heartbeat](/automation#scheduled-tasks-cron-vs-heartbeat) for the decision table.
+
+## Related
+
+- [Scheduled tasks](/automation/cron-jobs)
+- [Heartbeat](/gateway/heartbeat)
+- [Background tasks](/automation/tasks)

docs/automation/gmail-pubsub.md

@@ -0,0 +1,11 @@
+---
+summary: "Redirect to /automation/cron-jobs"
+title: "Gmail PubSub"
+---
+
+This page moved to [Gmail PubSub integration](/automation/cron-jobs#gmail-pubsub-integration) on the Scheduled Tasks page.
+
+## Related
+
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Troubleshooting](/automation/cron-jobs#troubleshooting)

docs/automation/hooks.md

@@ -0,0 +1,395 @@
+---
+summary: "Hooks: event-driven automation for commands and lifecycle events"
+read_when:
+  - You want event-driven automation for /new, /reset, /stop, and agent lifecycle events
+  - You want to build, install, or debug hooks
+title: "Hooks"
+---
+
+Hooks are small scripts that run inside the Gateway when agent events fire: commands like `/new`, `/reset`, `/stop`, session compaction, gateway lifecycle, and message flow. They are discovered from directories and managed with `openclaw hooks`. The Gateway loads internal hooks only after you enable hooks or configure at least one hook entry, hook pack, legacy handler, or extra hook directory.
+
+There are two kinds of hooks in OpenClaw:
+
+- **Internal hooks** (this page): run inside the Gateway when agent events fire.
+- **Webhooks**: external HTTP endpoints that let other systems trigger work in OpenClaw. See [Webhooks](/automation/cron-jobs#webhooks).
+
+Hooks can also be bundled inside plugins. `openclaw hooks list` shows both standalone hooks and plugin-managed hooks (displayed as `plugin:<id>`).
+
+## Choose the right surface
+
+OpenClaw has several extension surfaces that look similar but solve different problems:
+
+| If you want to...                                                                                                     | Use...                                | Why                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Save a snapshot on `/new`, log `/reset`, call an external API after `message:sent`, or add coarse operator automation | Internal hooks (`HOOK.md`, this page) | File-based hooks are meant for operator-managed side effects and command/lifecycle automation |
+| Rewrite prompts, block tools, cancel outbound messages, or add ordered middleware/policy                              | Typed plugin hooks via `api.on(...)`  | Typed hooks have explicit contracts, priorities, merge rules, and block/cancel semantics      |
+| Add telemetry-only export or observability                                                                            | Diagnostic events                     | Observability is a separate event bus, not a policy hook surface                              |
+
+Use internal hooks when you want automation that behaves like a small installed integration. Use typed plugin hooks when you need runtime lifecycle control.
+
+## Quick start
+
+```bash
+# List available hooks
+openclaw hooks list
+
+# Enable a hook
+openclaw hooks enable session-memory
+
+# Check hook status
+openclaw hooks check
+
+# Get detailed information
+openclaw hooks info session-memory
+```
+
+## Event types
+
+| Event                    | When it fires                                              |
+| ------------------------ | ---------------------------------------------------------- |
+| `command:new`            | `/new` command issued                                      |
+| `command:reset`          | `/reset` command issued                                    |
+| `command:stop`           | `/stop` command issued                                     |
+| `command`                | Any command event (general listener)                       |
+| `session:compact:before` | Before compaction summarizes history                       |
+| `session:compact:after`  | After compaction completes                                 |
+| `session:patch`          | When session properties are modified                       |
+| `agent:bootstrap`        | Before workspace bootstrap files are injected              |
+| `gateway:startup`        | After channels start and hooks are loaded                  |
+| `gateway:shutdown`       | When gateway shutdown begins                               |
+| `gateway:pre-restart`    | Before an expected gateway restart                         |
+| `message:received`       | Inbound message from any channel                           |
+| `message:transcribed`    | After audio transcription completes                        |
+| `message:preprocessed`   | After media and link preprocessing completes or is skipped |
+| `message:sent`           | Outbound send attempted (`context.success` has the result) |
+
+## Writing hooks
+
+### Hook structure
+
+Each hook is a directory containing two files:
+
+```text
+my-hook/
+├── HOOK.md          # Metadata + documentation
+└── handler.ts       # Handler implementation
+```
+
+The handler file can be `handler.ts`, `handler.js`, `index.ts`, or `index.js`.
+
+### HOOK.md format
+
+```markdown
+---
+name: my-hook
+description: "Short description of what this hook does"
+metadata:
+  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
+---
+
+# My Hook
+
+Detailed documentation goes here.
+```
+
+**Metadata fields** (`metadata.openclaw`):
+
+| Field      | Description                                          |
+| ---------- | ---------------------------------------------------- |
+| `emoji`    | Display emoji for CLI                                |
+| `events`   | Array of events to listen for                        |
+| `export`   | Named export to use (defaults to `"default"`)        |
+| `os`       | Required platforms (e.g., `["darwin", "linux"]`)     |
+| `requires` | Required `bins`, `anyBins`, `env`, or `config` paths |
+| `always`   | Bypass eligibility checks (boolean)                  |
+| `hookKey`  | Config key override (defaults to the hook name)      |
+| `homepage` | Docs URL shown by `openclaw hooks info`              |
+| `install`  | Installation methods                                 |
+
+### Handler implementation
+
+```typescript
+const handler = async (event) => {
+  if (event.type !== "command" || event.action !== "new") {
+    return;
+  }
+
+  console.log(`[my-hook] New command triggered`);
+  // Your logic here
+
+  // Optionally send a reply on replyable surfaces
+  event.messages.push("Hook executed!");
+};
+
+export default handler;
+```
+
+Each event includes: `type`, `action`, `sessionKey`, `timestamp`, `messages`, and `context` (event-specific data). Typed plugin hook contexts for agent and tool hooks can also include `trace`, a read-only W3C-compatible diagnostic trace context that plugins may pass into structured logs for OTEL correlation.
+
+Strings pushed to `event.messages` are delivered back to the chat only for
+`command:new` and `command:reset` (routed as a reply to the originating
+conversation) and for `session:compact:before` / `session:compact:after`
+(sent as compaction status notices). All other events, including
+`command:stop`, `message:*`, `agent:bootstrap`, `session:patch`, and
+`gateway:*`, ignore pushed messages.
+
+### Event context highlights
+
+**Command events** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.senderId`, `context.workspaceDir`, `context.cfg`.
+
+**Command events** (`command:stop`): `context.sessionEntry`, `context.sessionId`, `context.commandSource`, `context.senderId`.
+
+**Message events** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (provider-specific data including `senderId`, `senderName`, `guildId`). `context.content` prefers a nonblank command body for command-like messages, then falls back to the raw inbound body and generic body; it does not include agent-only enrichment such as thread history or link summaries.
+
+**Message events** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`, plus `context.error` when sending failed.
+
+**Message events** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
+
+**Message events** (`message:preprocessed`): `context.bodyForAgent` (final enriched body), `context.from`, `context.channelId`.
+
+**Bootstrap events** (`agent:bootstrap`): `context.bootstrapFiles` (mutable array), `context.agentId`.
+
+**Session patch events** (`session:patch`): `context.sessionEntry`, `context.patch` (only changed fields), `context.cfg`. Only privileged clients can trigger patch events; the context is a clone, so handlers cannot mutate the live session entry.
+
+**Compaction events**: `session:compact:before` includes `messageCount`, `tokenCount`. `session:compact:after` adds `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
+
+`command:stop` observes the user issuing `/stop`; it is cancellation/command
+lifecycle, not an agent-finalization gate. Plugins that need to inspect a
+natural final answer and ask the agent for one more pass should use the typed
+plugin hook `before_agent_finalize` instead. See [Plugin hooks](/plugins/hooks).
+
+**Gateway lifecycle events**: `gateway:shutdown` includes `reason` and `restartExpectedMs` and fires when gateway shutdown begins. `gateway:pre-restart` includes the same context but only fires when shutdown is part of an expected restart and a finite `restartExpectedMs` value is supplied. During shutdown, each lifecycle hook wait is best-effort and bounded so shutdown continues if a handler stalls. The default wait budget is 5 seconds for `gateway:shutdown` and 10 seconds for `gateway:pre-restart`.
+
+Use `gateway:pre-restart` for short restart notices while channels are still available:
+
+```typescript
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default async function handler(event) {
+  if (event.type !== "gateway" || event.action !== "pre-restart") {
+    return;
+  }
+
+  const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);
+  await execFileAsync("openclaw", [
+    "system",
+    "event",
+    "--mode",
+    "now",
+    "--text",
+    `Gateway restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,
+  ]);
+}
+```
+
+Between the `gateway:shutdown` (or `gateway:pre-restart`) event and the rest of the shutdown sequence, the gateway also fires a typed `session_end` plugin hook for every session that was still active when the process stopped. The event's `reason` is `shutdown` for a plain SIGTERM/SIGINT stop and `restart` when the close was scheduled as part of an expected restart. This drain is bounded so a slow `session_end` handler cannot block process exit, and sessions that have already been finalized through replace / reset / delete / compaction are skipped to avoid double-firing.
+
+## Hook discovery
+
+Hooks are discovered from four sources:
+
+1. **Bundled hooks**: shipped with OpenClaw
+2. **Plugin hooks**: bundled inside installed plugins; can override bundled hooks with the same name
+3. **Managed hooks**: `~/.openclaw/hooks/` (user-installed, shared across workspaces); can override bundled and plugin hooks. Extra directories from `hooks.internal.load.extraDirs` share this precedence.
+4. **Workspace hooks**: `<workspace>/hooks/` (per-agent, disabled by default until explicitly enabled)
+
+Workspace hooks can add new hook names but cannot override bundled, managed, or plugin-provided hooks with the same name.
+
+The Gateway skips internal hook discovery on startup until internal hooks are configured. Enable a bundled or managed hook with `openclaw hooks enable <name>`, install a hook pack, or set `hooks.internal.enabled=true` to opt in. When you enable one named hook, the Gateway loads only that hook's handler; `hooks.internal.enabled=true`, extra hook directories, and legacy handlers opt into broad discovery.
+
+### Hook packs
+
+Hook packs are npm packages that export hooks via `openclaw.hooks` in `package.json`. Install with:
+
+```bash
+openclaw plugins install <path-or-spec>
+```
+
+Npm specs are registry-only (package name + optional exact version or dist-tag). Git/URL/file specs and semver ranges are rejected. The older `openclaw hooks install` and `openclaw hooks update` commands are deprecated aliases for `openclaw plugins install` / `openclaw plugins update`.
+
+## Bundled hooks
+
+| Hook                  | Events                                            | What it does                                                   |
+| --------------------- | ------------------------------------------------- | -------------------------------------------------------------- |
+| session-memory        | `command:new`, `command:reset`                    | Saves session context to `<workspace>/memory/`                 |
+| bootstrap-extra-files | `agent:bootstrap`                                 | Injects additional bootstrap files from glob patterns          |
+| command-logger        | `command`                                         | Logs all commands to `~/.openclaw/logs/commands.log`           |
+| compaction-notifier   | `session:compact:before`, `session:compact:after` | Sends visible chat notices when session compaction starts/ends |
+| boot-md               | `gateway:startup`                                 | Runs `BOOT.md` when the gateway starts                         |
+
+Enable any bundled hook:
+
+```bash
+openclaw hooks enable <hook-name>
+```
+
+<a id="session-memory"></a>
+
+### session-memory details
+
+Extracts the last user/assistant messages (default 15, configurable with `hooks.internal.entries.session-memory.messages`) and saves them to `<workspace>/memory/YYYY-MM-DD-HHMM.md` using the host local date. Memory capture runs in the background so `/new` and `/reset` acknowledgements are not delayed by transcript reads or optional slug generation. Set `hooks.internal.entries.session-memory.llmSlug: true` to generate descriptive filename slugs with the configured model (falls back to timestamp slugs when unavailable). Requires `workspace.dir` to be configured.
+
+<a id="bootstrap-extra-files"></a>
+
+### bootstrap-extra-files config
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "bootstrap-extra-files": {
+          "enabled": true,
+          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
+        }
+      }
+    }
+  }
+}
+```
+
+`patterns` and `files` are accepted as aliases of `paths`. Paths resolve relative to the workspace and must stay inside it. Only recognized bootstrap basenames are loaded (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
+
+<a id="command-logger"></a>
+
+### command-logger details
+
+Logs every slash command as a JSON line (timestamp, action, session key, sender ID, source) to `~/.openclaw/logs/commands.log`.
+
+<a id="compaction-notifier"></a>
+
+### compaction-notifier details
+
+Sends short status messages into the current conversation when OpenClaw starts and finishes compacting the session transcript. This makes long turns less confusing on chat surfaces because the user can see that the assistant is summarizing context and will continue after compaction.
+
+<a id="boot-md"></a>
+
+### boot-md details
+
+Runs `BOOT.md` at gateway startup for each configured agent scope, if the file exists in that agent's resolved workspace.
+
+## Plugin hooks
+
+Plugins can register typed hooks through the Plugin SDK for deeper integration:
+intercepting tool calls, modifying prompts, controlling message flow, and more.
+Use plugin hooks when you need `before_tool_call`, `before_agent_reply`,
+`before_install`, or other in-process lifecycle hooks.
+
+Plugin-managed internal hooks are different: they participate in this page's
+coarse command/lifecycle event system and show up in `openclaw hooks list` as
+`plugin:<id>`. Use those for side effects and compatibility with hook packs, not
+for ordered middleware or policy gates.
+
+For the complete plugin hook reference, see [Plugin hooks](/plugins/hooks).
+
+## Configuration
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "session-memory": { "enabled": true },
+        "command-logger": { "enabled": false }
+      }
+    }
+  }
+}
+```
+
+Per-hook environment values satisfy a hook's `requires.env` eligibility checks (alongside the process environment), and handlers can read them from their hook config entry:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "my-hook": {
+          "enabled": true,
+          "env": { "MY_CUSTOM_VAR": "value" }
+        }
+      }
+    }
+  }
+}
+```
+
+Extra hook directories:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "load": {
+        "extraDirs": ["/path/to/more/hooks"]
+      }
+    }
+  }
+}
+```
+
+<Note>
+The legacy `hooks.internal.handlers` array config format is still supported for backwards compatibility, but new hooks should use the discovery-based system.
+</Note>
+
+## CLI reference
+
+```bash
+# List all hooks (add --eligible, --verbose, or --json)
+openclaw hooks list
+
+# Show detailed info about a hook
+openclaw hooks info <hook-name>
+
+# Show eligibility summary
+openclaw hooks check
+
+# Enable/disable
+openclaw hooks enable <hook-name>
+openclaw hooks disable <hook-name>
+```
+
+## Best practices
+
+- **Keep handlers fast.** Hooks run during command processing. Fire-and-forget heavy work with `void processInBackground(event)`.
+- **Handle errors gracefully.** Wrap risky operations in try/catch; do not throw so other handlers can run.
+- **Filter events early.** Return immediately if the event type/action is not relevant.
+- **Use specific event keys.** Prefer `"events": ["command:new"]` over `"events": ["command"]` to reduce overhead.
+
+## Troubleshooting
+
+### Hook not discovered
+
+```bash
+# Verify directory structure
+ls -la ~/.openclaw/hooks/my-hook/
+# Should show: HOOK.md, handler.ts
+
+# List all discovered hooks
+openclaw hooks list
+```
+
+### Hook not eligible
+
+```bash
+openclaw hooks info my-hook
+```
+
+Check for missing binaries (PATH), environment variables, config values, or OS compatibility.
+
+### Hook not executing
+
+1. Verify the hook is enabled: `openclaw hooks list`
+2. Restart your gateway process so hooks reload.
+3. Check gateway logs: `openclaw logs --follow | grep -i hook`
+
+## Related
+
+- [CLI Reference: hooks](/cli/hooks)
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Plugin hooks](/plugins/hooks) — in-process plugin lifecycle hooks
+- [Configuration](/gateway/configuration-reference#hooks)

docs/automation/index.md

@@ -0,0 +1,135 @@
+---
+doc-schema-version: 1
+summary: "Overview of automation mechanisms: tasks, cron, hooks, standing orders, and Task Flow"
+read_when:
+  - Deciding how to automate work with OpenClaw
+  - Choosing between heartbeat, cron, commitments, hooks, and standing orders
+  - Looking for the right automation entry point
+title: "Automation"
+---
+
+OpenClaw runs work in the background through tasks, scheduled jobs, inferred
+commitments, event hooks, and standing instructions. Use this page to pick the
+right mechanism.
+
+## Quick decision guide
+
+```mermaid
+flowchart TD
+    START([What do you need?]) --> Q1{Schedule work?}
+    START --> Q2{Track detached work?}
+    START --> Q3{Orchestrate multi-step flows?}
+    START --> Q4{React to lifecycle events?}
+    START --> Q5{Give the agent persistent instructions?}
+    START --> Q6{Remember a natural follow-up?}
+
+    Q1 -->|Yes| Q1a{Exact timing or flexible?}
+    Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"]
+    Q1a -->|Flexible| HEARTBEAT[Heartbeat]
+
+    Q2 -->|Yes| TASKS[Background Tasks]
+    Q3 -->|Yes| FLOW[Task Flow]
+    Q4 -->|Yes| HOOKS[Hooks]
+    Q5 -->|Yes| SO[Standing Orders]
+    Q6 -->|Yes| COMMITMENTS[Inferred Commitments]
+```
+
+| Use case                                | Recommended            | Why                                              |
+| --------------------------------------- | ---------------------- | ------------------------------------------------ |
+| Send daily report at 9 AM sharp         | Scheduled Tasks (Cron) | Exact timing, isolated execution                 |
+| Remind me in 20 minutes                 | Scheduled Tasks (Cron) | One-shot with precise timing (`--at`)            |
+| Run weekly deep analysis                | Scheduled Tasks (Cron) | Standalone task, can use different model         |
+| Check inbox every 30 min                | Heartbeat              | Batches with other checks, context-aware         |
+| Monitor calendar for upcoming events    | Heartbeat              | Natural fit for periodic awareness               |
+| Check in after a mentioned interview    | Inferred Commitments   | Memory-like follow-up, no exact reminder request |
+| Gentle care check-in after user context | Inferred Commitments   | Scoped to the same agent and channel             |
+| Inspect status of a subagent or ACP run | Background Tasks       | Tasks ledger tracks all detached work            |
+| Audit what ran and when                 | Background Tasks       | `openclaw tasks list` and `openclaw tasks audit` |
+| Multi-step research then summarize      | Task Flow              | Durable orchestration with revision tracking     |
+| Run a script on session reset           | Hooks                  | Event-driven, fires on lifecycle events          |
+| Execute code on every tool call         | Plugin hooks           | In-process hooks can intercept tool calls        |
+| Always check compliance before replying | Standing Orders        | Injected into every session automatically        |
+
+### Scheduled Tasks (Cron) vs Heartbeat
+
+| Dimension       | Scheduled Tasks (Cron)              | Heartbeat                             |
+| --------------- | ----------------------------------- | ------------------------------------- |
+| Timing          | Exact (cron expressions, one-shot)  | Approximate (default every 30 min)    |
+| Session context | Fresh (isolated) or shared          | Full main-session context             |
+| Task records    | Always created                      | Never created                         |
+| Delivery        | Channel, webhook, or silent         | Inline in main session                |
+| Best for        | Reports, reminders, background jobs | Inbox checks, calendar, notifications |
+
+Use Scheduled Tasks (Cron) when you need precise timing or isolated execution. Use Heartbeat when the work benefits from full session context and approximate timing is fine.
+
+## Core concepts
+
+### Scheduled tasks (cron)
+
+Cron is the Gateway's built-in scheduler for precise timing. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook endpoint. Supports one-shot reminders, recurring expressions, and inbound webhook triggers.
+
+See [Scheduled Tasks](/automation/cron-jobs).
+
+### Tasks
+
+The background task ledger tracks all detached work: ACP runs, subagent spawns, isolated cron executions, and CLI operations. Tasks are records, not schedulers. Use `openclaw tasks list` and `openclaw tasks audit` to inspect them.
+
+See [Background Tasks](/automation/tasks).
+
+### Inferred commitments
+
+Commitments are opt-in, short-lived follow-up memories. OpenClaw infers them
+from normal conversations, scopes them to the same agent and channel, and
+delivers due check-ins through heartbeat. Exact user-requested reminders still
+belong to cron.
+
+See [Inferred Commitments](/concepts/commitments).
+
+### Task Flow
+
+Task Flow is the flow orchestration substrate above background tasks. It manages durable multi-step flows with managed and mirrored sync modes, revision tracking, and `openclaw tasks flow list|show|cancel` for inspection.
+
+See [Task Flow](/automation/taskflow).
+
+### Standing orders
+
+Standing orders grant the agent permanent operating authority for defined programs. They live in workspace files (typically `AGENTS.md`) and are injected into every session. Combine with cron for time-based enforcement.
+
+See [Standing Orders](/automation/standing-orders).
+
+### Hooks
+
+Internal hooks are event-driven scripts triggered by agent lifecycle events
+(`/new`, `/reset`, `/stop`), session compaction, gateway startup, and message
+flow. They are discovered from hook directories and managed with
+`openclaw hooks`. For in-process tool-call interception, use
+[Plugin hooks](/plugins/hooks).
+
+See [Hooks](/automation/hooks).
+
+### Heartbeat
+
+Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records and do not extend daily/idle session reset freshness. Use `HEARTBEAT.md` for a small checklist, or a `tasks:` block when you want due-only periodic checks inside heartbeat itself. Empty heartbeat files skip as `empty-heartbeat-file`; due-only task mode skips as `no-tasks-due`. Heartbeats defer while cron work is active or queued, and `heartbeat.skipWhenBusy` can also defer an agent while that same agent's session-keyed subagent or nested lanes are busy.
+
+See [Heartbeat](/gateway/heartbeat).
+
+## How they work together
+
+- **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders. All cron executions create task records.
+- **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
+- **Hooks** react to specific events (session resets, compaction, message flow) with custom scripts. Plugin hooks cover tool calls.
+- **Standing orders** give the agent persistent context and authority boundaries.
+- **Task Flow** coordinates multi-step flows above individual tasks.
+- **Tasks** automatically track all detached work so you can inspect and audit it.
+
+## Related
+
+- [Scheduled Tasks](/automation/cron-jobs) — precise scheduling and one-shot reminders
+- [Inferred Commitments](/concepts/commitments) — memory-like follow-up check-ins
+- [Background Tasks](/automation/tasks) — task ledger for all detached work
+- [Task Flow](/automation/taskflow) — durable multi-step flow orchestration
+- [Hooks](/automation/hooks) — event-driven lifecycle scripts
+- [Plugin hooks](/plugins/hooks) — in-process tool, prompt, message, and lifecycle hooks
+- [Standing Orders](/automation/standing-orders) — persistent agent instructions
+- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [Configuration Reference](/gateway/configuration-reference) — all config keys

docs/automation/poll.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /cli/message"
+title: "Polls"
+---
+
+This page moved. Poll documentation, including `openclaw message poll` flags and per-channel limits, lives in [Message tool](/cli/message).
+
+## Related
+
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Scheduled tasks](/automation/cron-jobs)
+- [Background tasks](/automation/tasks)

docs/automation/standing-orders.md

@@ -0,0 +1,238 @@
+---
+summary: "Define permanent operating authority for autonomous agent programs"
+read_when:
+  - Setting up autonomous agent workflows that run without per-task prompting
+  - Defining what the agent can do independently vs. what needs human approval
+  - Structuring multi-program agents with clear boundaries and escalation rules
+title: "Standing orders"
+---
+
+Standing orders grant your agent **permanent operating authority** for defined programs. Instead of prompting the agent for each task, you define programs with clear scope, triggers, and escalation rules, and the agent executes autonomously within those boundaries: "You own the weekly report. Compile it every Friday, send it, and only escalate if something looks wrong."
+
+## Why standing orders
+
+**Without standing orders:** you prompt the agent for every task, routine work gets forgotten or delayed, and you become the bottleneck.
+
+**With standing orders:** the agent executes autonomously within defined boundaries, routine work happens on schedule, and you only get involved for exceptions and approvals.
+
+## How they work
+
+Standing orders are defined in your [agent workspace](/concepts/agent-workspace) files. The recommended approach is to include them directly in `AGENTS.md` (which is auto-injected every session) so the agent always has them in context. For larger configurations, you can also place them in a dedicated file like `standing-orders.md` and reference it from `AGENTS.md`.
+
+Each program specifies:
+
+1. **Scope** - what the agent is authorized to do
+2. **Triggers** - when to execute (schedule, event, or condition)
+3. **Approval gates** - what requires human sign-off before acting
+4. **Escalation rules** - when to stop and ask for help
+
+The agent loads these instructions every session via the workspace bootstrap files (see [Agent Workspace](/concepts/agent-workspace) for the full list of auto-injected files) and executes against them, combined with [cron jobs](/automation/cron-jobs) for time-based enforcement.
+
+<Tip>
+Put standing orders in `AGENTS.md` to guarantee they're loaded every session. The workspace bootstrap automatically injects `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, and `MEMORY.md` - but not arbitrary files in subdirectories.
+</Tip>
+
+## Anatomy of a standing order
+
+```markdown
+## Program: Weekly Status Report
+
+**Authority:** Compile data, generate report, deliver to stakeholders
+**Trigger:** Every Friday at 4 PM (enforced via cron job)
+**Approval gate:** None for standard reports. Flag anomalies for human review.
+**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm)
+
+### Execution steps
+
+1. Pull metrics from configured sources
+2. Compare to prior week and targets
+3. Generate report in Reports/weekly/YYYY-MM-DD.md
+4. Deliver summary via configured channel
+5. Log completion to Agent/Logs/
+
+### What NOT to do
+
+- Do not send reports to external parties
+- Do not modify source data
+- Do not skip delivery if metrics look bad - report accurately
+```
+
+## Standing orders plus cron jobs
+
+Standing orders define **what** the agent is authorized to do. [Cron jobs](/automation/cron-jobs) define **when** it happens. They work together:
+
+```text
+Standing Order: "You own the daily inbox triage"
+    ↓
+Cron Job (8 AM daily): "Execute inbox triage per standing orders"
+    ↓
+Agent: Reads standing orders → executes steps → reports results
+```
+
+The cron job prompt should reference the standing order rather than duplicating it:
+
+```bash
+openclaw cron add \
+  --name daily-inbox-triage \
+  --cron "0 8 * * 1-5" \
+  --tz America/New_York \
+  --timeout-seconds 300 \
+  --announce \
+  --channel imessage \
+  --to "+1XXXXXXXXXX" \
+  --message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns."
+```
+
+## Examples
+
+### Example 1: content and social media (weekly cycle)
+
+```markdown
+## Program: Content & Social Media
+
+**Authority:** Draft content, schedule posts, compile engagement reports
+**Approval gate:** All posts require owner review for first 30 days, then standing approval
+**Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief)
+
+### Weekly cycle
+
+- **Monday:** Review platform metrics and audience engagement
+- **Tuesday-Thursday:** Draft social posts, create blog content
+- **Friday:** Compile weekly marketing brief → deliver to owner
+
+### Content rules
+
+- Voice must match the brand (see SOUL.md or brand voice guide)
+- Never identify as AI in public-facing content
+- Include metrics when available
+- Focus on value to audience, not self-promotion
+```
+
+### Example 2: finance operations (event-triggered)
+
+```markdown
+## Program: Financial Processing
+
+**Authority:** Process transaction data, generate reports, send summaries
+**Approval gate:** None for analysis. Recommendations require owner approval.
+**Trigger:** New data file detected OR scheduled monthly cycle
+
+### When new data arrives
+
+1. Detect new file in designated input directory
+2. Parse and categorize all transactions
+3. Compare against budget targets
+4. Flag: unusual items, threshold breaches, new recurring charges
+5. Generate report in designated output directory
+6. Deliver summary to owner via configured channel
+
+### Escalation rules
+
+- Single item > $500: immediate alert
+- Category > budget by 20%: flag in report
+- Unrecognizable transaction: ask owner for categorization
+- Failed processing after 2 retries: report failure, do not guess
+```
+
+### Example 3: monitoring and alerts (continuous)
+
+```markdown
+## Program: System Monitoring
+
+**Authority:** Check system health, restart services, send alerts
+**Approval gate:** Restart services automatically. Escalate if restart fails twice.
+**Trigger:** Every heartbeat cycle
+
+### Checks
+
+- Service health endpoints responding
+- Disk space above threshold
+- Pending tasks not stale (>24 hours)
+- Delivery channels operational
+
+### Response matrix
+
+| Condition        | Action                   | Escalate?                |
+| ---------------- | ------------------------ | ------------------------ |
+| Service down     | Restart automatically    | Only if restart fails 2x |
+| Disk space < 10% | Alert owner              | Yes                      |
+| Stale task > 24h | Remind owner             | No                       |
+| Channel offline  | Log and retry next cycle | If offline > 2 hours     |
+```
+
+## Execute-verify-report pattern
+
+Standing orders work best when combined with strict execution discipline. Every task in a standing order should follow this loop:
+
+1. **Execute** - Do the actual work (don't just acknowledge the instruction)
+2. **Verify** - Confirm the result is correct (file exists, message delivered, data parsed)
+3. **Report** - Tell the owner what was done and what was verified
+
+```markdown
+### Execution rules
+
+- Every task follows Execute-Verify-Report. No exceptions.
+- "I'll do that" is not execution. Do it, then report.
+- "Done" without verification is not acceptable. Prove it.
+- If execution fails: retry once with adjusted approach.
+- If still fails: report failure with diagnosis. Never silently fail.
+- Never retry indefinitely - 3 attempts max, then escalate.
+```
+
+This pattern prevents the most common agent failure mode: acknowledging a task without completing it.
+
+## Multi-program architecture
+
+For agents managing multiple concerns, organize standing orders as separate programs with clear boundaries:
+
+```markdown
+## Program 1: [Domain A] (Weekly)
+
+...
+
+## Program 2: [Domain B] (Monthly + On-Demand)
+
+...
+
+## Program 3: [Domain C] (As-Needed)
+
+...
+
+## Escalation Rules (All Programs)
+
+- [Common escalation criteria]
+- [Approval gates that apply across programs]
+```
+
+Each program should have:
+
+- Its own **trigger cadence** (weekly, monthly, event-driven, continuous)
+- Its own **approval gates** (some programs need more oversight than others)
+- Clear **boundaries** (the agent should know where one program ends and another begins)
+
+## Best practices
+
+### Do
+
+- Start with narrow authority and expand as trust builds
+- Define explicit approval gates for high-risk actions
+- Include "What NOT to do" sections - boundaries matter as much as permissions
+- Combine with cron jobs for reliable time-based execution
+- Review agent logs weekly to verify standing orders are being followed
+- Update standing orders as your needs evolve - they're living documents
+
+### Avoid
+
+- Grant broad authority on day one ("do whatever you think is best")
+- Skip escalation rules - every program needs a "when to stop and ask" clause
+- Assume the agent will remember verbal instructions - put everything in the file
+- Mix concerns in a single program - separate programs for separate domains
+- Forget to enforce with cron jobs - standing orders without triggers become suggestions
+
+## Related
+
+- [Automation](/automation): all automation mechanisms at a glance.
+- [Cron jobs](/automation/cron-jobs): schedule enforcement for standing orders.
+- [Hooks](/automation/hooks): event-driven scripts for agent lifecycle events.
+- [Webhooks](/automation/cron-jobs#webhooks): inbound HTTP event triggers.
+- [Agent workspace](/concepts/agent-workspace): where standing orders live, including the full list of auto-injected bootstrap files (`AGENTS.md`, `SOUL.md`, etc.).

docs/automation/taskflow.md

@@ -0,0 +1,168 @@
+---
+summary: "Task Flow orchestration layer above background tasks"
+read_when:
+  - You want to understand how Task Flow relates to background tasks
+  - You encounter Task Flow or openclaw tasks flow in release notes or docs
+  - You want to inspect or manage durable flow state
+title: "Task flow"
+---
+
+Task Flow is the orchestration layer above [background tasks](/automation/tasks). A flow is a durable record of multi-step work with its own status, JSON state, revision counter, and linked task records. Flows survive gateway restarts; individual tasks remain the unit of detached work.
+
+## When to use Task Flow
+
+| Scenario                                  | Use                                         |
+| ----------------------------------------- | ------------------------------------------- |
+| Single background job                     | Plain task                                  |
+| Multi-step pipeline driven by plugin code | Task Flow (managed)                         |
+| Detached ACP or subagent spawn            | Task Flow (mirrored, created automatically) |
+| One-shot reminder                         | Cron job                                    |
+
+## Sync modes
+
+### Managed mode
+
+A managed flow has a controller: plugin code that creates the flow through the plugin runtime Task Flow API with a goal and a required controller id, then drives it explicitly.
+
+- Each step runs as a background task created under the flow; the flow's owner key and requester origin carry over to child tasks.
+- The controller advances the flow between `running`, `waiting`, and terminal states, and stores arbitrary JSON step state on the flow record.
+- Every mutation passes the flow's expected revision. A stale write is rejected as a revision conflict instead of clobbering newer state.
+- Once cancellation is requested, new child tasks are refused, and the flow finalizes as `cancelled` when no child task remains active.
+
+Example: a weekly report flow that (1) gathers data, (2) generates the report, and (3) delivers it, one background task per step:
+
+```
+Flow: weekly-report
+  Step 1: gather-data     → task created → succeeded
+  Step 2: generate-report → task created → succeeded
+  Step 3: deliver         → task created → running
+```
+
+### Mirrored mode
+
+OpenClaw creates a mirrored one-task flow automatically when a detached ACP or subagent run starts (session-scoped tasks with deliverable completion). The flow record mirrors its single backing task - status, goal, and timing - so detached spawns get a stable flow handle for status and retry surfaces without a controller. Mirrored flows show sync mode `task_mirrored` in the CLI.
+
+## Flow statuses
+
+| Status      | Meaning                                                                    |
+| ----------- | -------------------------------------------------------------------------- |
+| `queued`    | Created, not yet progressing                                               |
+| `running`   | Flow is actively progressing                                               |
+| `waiting`   | Managed flow is parked on wait metadata (timer, external event)            |
+| `blocked`   | A step finished without a usable result; `blockedTaskId`/summary say which |
+| `succeeded` | Completed successfully                                                     |
+| `failed`    | Completed with an error                                                    |
+| `cancelled` | Cancel requested and all child tasks settled                               |
+| `lost`      | Flow lost its authoritative backing state                                  |
+
+## Durable state and revision tracking
+
+Flow records persist in the shared SQLite state database (`~/.openclaw/state/openclaw.sqlite`, `flow_runs` table) alongside task records, so progress survives gateway restarts. Each write bumps the flow's `revision`; concurrent writers that pass a stale expected revision get a conflict and must re-read. WAL growth is bounded by SQLite autocheckpointing plus periodic passive checkpoints, with truncate checkpoints on shutdown. The legacy `flows/registry.sqlite` sidecar from older installs is imported by `openclaw doctor`.
+
+## Cancel behavior
+
+`openclaw tasks flow cancel` sets a sticky cancel intent on the flow, cancels its active child tasks, and refuses new managed child tasks. Once no child task remains active, the flow finalizes as `cancelled` - immediately, or via the maintenance sweep if children take longer to settle. The intent is persisted, so a cancelled flow stays cancelled even if the gateway restarts before all child tasks have terminated.
+
+## CLI commands
+
+```bash
+# List active and recent flows
+openclaw tasks flow list [--status <status>] [--json]
+
+# Show details for a specific flow
+openclaw tasks flow show <lookup> [--json]
+
+# Cancel a running flow and its active tasks
+openclaw tasks flow cancel <lookup>
+```
+
+| Command                           | Description                                                             |
+| --------------------------------- | ----------------------------------------------------------------------- |
+| `openclaw tasks flow list`        | Tracked flows with sync mode, status, revision, controller, task counts |
+| `openclaw tasks flow show <id>`   | Inspect one flow by flow id or owner key, including linked tasks        |
+| `openclaw tasks flow cancel <id>` | Cancel a running flow and its active tasks                              |
+
+Flows are also covered by `openclaw tasks audit` (stale or broken flow findings) and `openclaw tasks maintenance` (finalizes stuck cancels, prunes terminal flows after 7 days).
+
+## Reliable scheduled workflow pattern
+
+For recurring workflows such as market intelligence briefings, treat the schedule, orchestration, and reliability checks as separate layers:
+
+1. Use [Scheduled Tasks](/automation/cron-jobs) for timing.
+2. Use a persistent cron session when the workflow should build on prior context.
+3. Use [Lobster](/tools/lobster) for deterministic steps, approval gates, and resume tokens.
+4. Use Task Flow to track the multi-step run across child tasks, waits, retries, and gateway restarts.
+
+Example cron shape:
+
+```bash
+openclaw cron add \
+  --name "Market intelligence brief" \
+  --cron "0 7 * * 1-5" \
+  --tz "America/New_York" \
+  --session session:market-intel \
+  --message "Run the market-intel Lobster workflow. Verify source freshness before summarizing." \
+  --announce \
+  --channel slack \
+  --to "channel:C1234567890"
+```
+
+Use `--session session:<id>` instead of `isolated` when the recurring workflow needs deliberate history, previous run summaries, or standing context. Use `isolated` when each run should start fresh and all required state is explicit in the workflow.
+
+Inside the workflow, put reliability checks before the LLM summary step:
+
+```yaml
+name: market-intel-brief
+steps:
+  - id: preflight
+    command: market-intel check --json
+  - id: collect
+    command: market-intel collect --json
+    stdin: $preflight.json
+  - id: summarize
+    command: market-intel summarize --json
+    stdin: $collect.json
+  - id: approve
+    command: market-intel deliver --preview
+    stdin: $summarize.json
+    approval: required
+  - id: deliver
+    command: market-intel deliver --execute
+    stdin: $summarize.json
+    condition: $approve.approved
+```
+
+Recommended preflight checks:
+
+- Browser availability and profile choice, for example `openclaw` for managed state or `user` when a signed-in Chrome session is required. See [Browser](/tools/browser).
+- API credentials and quota for each source.
+- Network reachability for required endpoints.
+- Required tools enabled for the agent, such as `lobster`, `browser`, and `llm-task`.
+- Failure destination configured for cron so preflight failures are visible. See [Scheduled Tasks](/automation/cron-jobs#delivery-and-output).
+
+Recommended data provenance fields for every collected item:
+
+```json
+{
+  "sourceUrl": "https://example.com/report",
+  "retrievedAt": "2026-04-24T12:00:00Z",
+  "asOf": "2026-04-24",
+  "title": "Example report",
+  "content": "..."
+}
+```
+
+Have the workflow reject or mark stale items before summarization. The LLM step should receive only structured JSON and should be asked to preserve `sourceUrl`, `retrievedAt`, and `asOf` in its output. Use [LLM Task](/tools/llm-task) when you need a schema-validated model step inside the workflow.
+
+For reusable team or community workflows, package the CLI, `.lobster` files, and any setup notes as a skill or plugin and publish it through [ClawHub](/clawhub). Keep workflow-specific guardrails in that package unless the plugin API is missing a needed generic capability.
+
+## How flows relate to tasks
+
+Flows coordinate tasks, not replace them. A single flow may drive multiple background tasks over its lifetime. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
+
+## Related
+
+- [Background Tasks](/automation/tasks) - the detached work ledger that flows coordinate
+- [CLI: tasks](/cli/tasks) - CLI command reference for `openclaw tasks flow`
+- [Automation Overview](/automation) - all automation mechanisms at a glance
+- [Cron Jobs](/automation/cron-jobs) - scheduled jobs that may feed into flows

docs/automation/tasks.md

@@ -0,0 +1,374 @@
+---
+summary: "Background task tracking for ACP runs, subagents, cron executions, and CLI operations"
+read_when:
+  - Inspecting background work in progress or recently completed
+  - Debugging delivery failures for detached agent runs
+  - Understanding how background runs relate to sessions, cron, and heartbeat
+title: "Background tasks"
+sidebarTitle: "Background tasks"
+---
+
+<Note>
+Looking for scheduling? See [Automation](/automation) for choosing the right mechanism. This page is the activity ledger for background work, not the scheduler.
+</Note>
+
+Background tasks track work that runs **outside your main conversation session**: ACP runs, subagent spawns, cron job executions, and CLI-initiated operations.
+
+Tasks do **not** replace sessions, cron jobs, or heartbeats - they are the **activity ledger** that records what detached work happened, when, and whether it succeeded.
+
+<Note>
+Not every agent run creates a task. Heartbeat turns and normal interactive chat do not. All cron executions, ACP spawns, subagent spawns, and gateway-dispatched CLI agent commands do.
+</Note>
+
+## TL;DR
+
+- Tasks are **records**, not schedulers - cron and heartbeat decide _when_ work runs, tasks track _what happened_.
+- ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
+- Each task moves through `queued → running → terminal` (succeeded, failed, timed_out, cancelled, or lost).
+- Cron tasks stay live while the cron runtime still owns the job; if the in-memory runtime state is gone, task maintenance first checks durable cron run history before marking a task lost.
+- Completion is push-driven: detached work can notify directly or wake the requester session/heartbeat when it finishes, so status polling loops are usually the wrong shape.
+- Isolated cron runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
+- Isolated cron delivery suppresses stale interim parent replies while descendant subagent work is still draining, and it prefers final descendant output when that arrives before delivery.
+- Completion notifications are delivered directly to a channel or queued for the next heartbeat.
+- `openclaw tasks list` shows all tasks; `openclaw tasks audit` surfaces issues.
+- Terminal records are kept for 7 days (`lost` records for 24 hours), then automatically pruned.
+
+## Quick start
+
+<Tabs>
+  <Tab title="List and filter">
+    ```bash
+    # List all tasks (newest first)
+    openclaw tasks list
+
+    # Filter by runtime or status
+    openclaw tasks list --runtime acp
+    openclaw tasks list --status running
+    ```
+
+  </Tab>
+  <Tab title="Inspect">
+    ```bash
+    # Show details for a specific task (by task ID, run ID, or session key)
+    openclaw tasks show <lookup>
+    ```
+  </Tab>
+  <Tab title="Cancel and notify">
+    ```bash
+    # Cancel a running task (kills the child session)
+    openclaw tasks cancel <lookup>
+
+    # Change notification policy for a task
+    openclaw tasks notify <lookup> state_changes
+    ```
+
+  </Tab>
+  <Tab title="Audit and maintenance">
+    ```bash
+    # Run a health audit
+    openclaw tasks audit
+
+    # Preview or apply maintenance
+    openclaw tasks maintenance
+    openclaw tasks maintenance --apply
+    ```
+
+  </Tab>
+  <Tab title="Task flow">
+    ```bash
+    # Inspect TaskFlow state
+    openclaw tasks flow list
+    openclaw tasks flow show <lookup>
+    openclaw tasks flow cancel <lookup>
+    ```
+  </Tab>
+</Tabs>
+
+## What creates a task
+
+| Source                 | Runtime type | When a task record is created                                          | Default notify policy |
+| ---------------------- | ------------ | ---------------------------------------------------------------------- | --------------------- |
+| ACP background runs    | `acp`        | Spawning a child ACP session                                           | `done_only`           |
+| Subagent orchestration | `subagent`   | Spawning a subagent via `sessions_spawn`                               | `done_only`           |
+| Cron jobs (all types)  | `cron`       | Every cron execution (main-session and isolated)                       | `silent`              |
+| CLI operations         | `cli`        | `openclaw agent` commands that run through the gateway                 | `silent`              |
+| Agent media jobs       | `cli`        | Session-backed `image_generate`/`music_generate`/`video_generate` runs | `silent`              |
+
+<AccordionGroup>
+  <Accordion title="Notify defaults for cron and media">
+    Cron tasks (main-session and isolated) use `silent` notify policy - they create records for tracking but do not generate task notifications of their own; cron owns its delivery path.
+
+    Session-backed `image_generate`, `music_generate`, and `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished media itself. The requester agent follows its normal visible-reply contract: automatic final reply when configured, or `message(action="send")` plus `NO_REPLY` when the session requires message-tool replies. If the requester session is no longer active or its active wake fails, and the completion agent misses some or all generated media, OpenClaw sends an idempotent direct fallback with only the missing media to the original channel target.
+
+  </Accordion>
+  <Accordion title="Concurrent media-generation guardrail">
+    While a session-backed media-generation task is still active, `image_generate`, `music_generate`, and `video_generate` guard against accidental retries: repeating the call for the same prompt/request returns the matching active task status instead of starting a duplicate, while a distinct prompt can start its own task. Use `action: "status"` when you want an explicit progress/status lookup from the agent side.
+  </Accordion>
+  <Accordion title="What does not create tasks">
+    - Heartbeat turns - main-session; see [Heartbeat](/gateway/heartbeat)
+    - Normal interactive chat turns
+    - Direct `/command` responses
+
+  </Accordion>
+</AccordionGroup>
+
+## Task lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> queued
+    queued --> running : agent starts
+    running --> succeeded : completes ok
+    running --> failed : error
+    running --> timed_out : timeout exceeded
+    queued --> cancelled : operator cancels
+    running --> cancelled : operator cancels
+    queued --> lost : backing state gone > 5 min
+    running --> lost : backing state gone > 5 min
+```
+
+| Status      | What it means                                                               |
+| ----------- | --------------------------------------------------------------------------- |
+| `queued`    | Created, waiting for the agent to start                                     |
+| `running`   | Agent turn is actively executing                                            |
+| `succeeded` | Completed successfully                                                      |
+| `failed`    | Completed with an error                                                     |
+| `timed_out` | Exceeded the configured timeout                                             |
+| `cancelled` | Stopped by the operator via `openclaw tasks cancel`, or the run was aborted |
+| `lost`      | The runtime lost authoritative backing state after a 5-minute grace period  |
+
+Transitions happen automatically - agent run lifecycle events (start, end, error) update the task status; you do not manage it manually.
+
+Agent run completion is authoritative for active task records. A successful detached run finalizes as `succeeded`, ordinary run errors finalize as `failed`, timeouts finalize as `timed_out`, and cancel/abort outcomes finalize as `cancelled`. Once a task is terminal, later lifecycle signals do not downgrade it - an operator-cancelled or already-`failed`/`timed_out`/`lost` task stays that way even if a success signal arrives afterwards.
+
+`lost` is runtime-aware:
+
+- ACP tasks: only a live in-process ACP turn in the Gateway proves the run is alive; persisted session metadata alone does not. Offline CLI audit stays conservative and never reclaims ACP tasks.
+- Subagent tasks: backing child session disappeared from the target agent store (or carries a restart-recovery tombstone).
+- Cron tasks: the cron runtime no longer tracks the job as active and durable cron run history does not show a terminal result for that run. Offline CLI audit does not treat its own empty in-process cron runtime state as authority.
+- CLI tasks: tasks with a run id/source id use the live run context, so lingering child-session or chat-session rows do not keep them alive after the gateway-owned run disappears. Legacy CLI tasks without run identity still fall back to the child session. Gateway-backed `openclaw agent` runs also finalize from their run result, so completed runs do not sit active until the sweeper marks them `lost`.
+
+## Delivery and notifications
+
+When a task reaches a terminal state, OpenClaw notifies you. There are two delivery paths:
+
+**Direct delivery** - if the task has a channel target (the `requesterOrigin`), the completion message goes straight to that channel (Discord, Slack, Telegram, etc.). Group and channel task completions are instead routed through the requester session so the parent agent can write the visible reply. For subagent completions, OpenClaw also preserves bound thread/topic routing when available and can fill a missing `to` / account from the requester session's stored route (`lastChannel` / `lastTo` / `lastAccountId`) before giving up on direct delivery.
+
+**Session-queued delivery** - if direct delivery fails or no origin is set, the update is queued as a system event in the requester's session and surfaces on the next heartbeat.
+
+<Tip>
+Session-queued task completions trigger an immediate heartbeat wake, so you see the result quickly - you do not have to wait for the next scheduled heartbeat tick.
+</Tip>
+
+That means the usual workflow is push-based: start detached work once, then let the runtime wake or notify you on completion. Poll task state only when you need debugging, intervention, or an explicit audit.
+
+### Notification policies
+
+Control how much you hear about each task:
+
+| Policy                | What is delivered                                       |
+| --------------------- | ------------------------------------------------------- |
+| `done_only` (default) | Only terminal state (succeeded, failed, etc.)           |
+| `state_changes`       | Every state transition and progress update              |
+| `silent`              | Nothing at all (default for cron, CLI, and media tasks) |
+
+Change the policy while a task is running:
+
+```bash
+openclaw tasks notify <lookup> state_changes
+```
+
+## CLI reference
+
+<AccordionGroup>
+  <Accordion title="tasks list">
+    ```bash
+    openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
+    ```
+
+    Output columns: Task, Kind, Status, Delivery, Run, Child Session, Summary. Bare `openclaw tasks` behaves like `openclaw tasks list`.
+
+  </Accordion>
+  <Accordion title="tasks show">
+    ```bash
+    openclaw tasks show <lookup> [--json]
+    ```
+
+    The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary.
+
+  </Accordion>
+  <Accordion title="tasks cancel">
+    ```bash
+    openclaw tasks cancel <lookup>
+    ```
+
+    For ACP and subagent tasks, this kills the child session; ACP and cron cancellations route through the running Gateway (`tasks.cancel`). For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
+
+  </Accordion>
+  <Accordion title="tasks notify">
+    ```bash
+    openclaw tasks notify <lookup> <done_only|state_changes|silent>
+    ```
+  </Accordion>
+  <Accordion title="tasks audit">
+    ```bash
+    openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]
+    ```
+
+    Surfaces operational issues for tasks **and** TaskFlows in one report. Findings also appear in `openclaw status` when issues are detected.
+
+    Task findings:
+
+    | Finding                   | Severity   | Trigger                                                                                                      |
+    | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
+    | `stale_queued`            | warn       | Queued for more than 10 minutes                                                                              |
+    | `stale_running`           | error      | Running for more than 30 minutes                                                                             |
+    | `lost`                    | warn/error | Runtime-backed task ownership disappeared; retained lost tasks warn until `cleanupAfter`, then become errors |
+    | `delivery_failed`         | warn       | Delivery failed and notify policy is not `silent`                                                            |
+    | `missing_cleanup`         | warn       | Terminal task with no cleanup timestamp                                                                      |
+    | `inconsistent_timestamps` | warn       | Timeline violation (for example ended before started)                                                        |
+
+    TaskFlow findings:
+
+    | Finding                | Severity   | Trigger                                                                    |
+    | ---------------------- | ---------- | --------------------------------------------------------------------------- |
+    | `restore_failed`       | error      | Flow registry restore from SQLite failed                                    |
+    | `stale_running`        | error      | Running flow has not advanced for more than 30 minutes                      |
+    | `stale_waiting`        | warn       | Waiting flow has not advanced for more than 30 minutes                      |
+    | `stale_blocked`        | warn       | Blocked flow has not advanced for more than 30 minutes                      |
+    | `cancel_stuck`         | warn       | Cancel requested over 5 minutes ago, no active child tasks, still nonterminal |
+    | `missing_linked_tasks` | warn/error | Stale managed flow with no linked tasks or wait state                       |
+    | `blocked_task_missing` | warn       | Blocked flow points at a task id that no longer exists                      |
+
+  </Accordion>
+  <Accordion title="tasks maintenance">
+    ```bash
+    openclaw tasks maintenance [--json]
+    openclaw tasks maintenance --apply [--json]
+    ```
+
+    Use this to preview or apply reconciliation, cleanup stamping, and pruning for tasks, TaskFlow state, and stale cron run session registry rows.
+
+    Reconciliation is runtime-aware:
+
+    - ACP tasks require a live in-process turn in the Gateway; subagent tasks check their backing child session.
+    - Subagent tasks whose child session has a restart-recovery tombstone are marked lost instead of being treated as recoverable backing sessions.
+    - Cron tasks check whether the cron runtime still owns the job, then recover terminal status from persisted cron run logs/job state before falling back to `lost`. Only the Gateway process is authoritative for the in-memory cron active-job set; offline CLI audit uses durable history but does not mark a cron task lost solely because that local set is empty.
+    - CLI tasks with run identity check the owning live run context, not just child-session or chat-session rows.
+
+    Completion cleanup is also runtime-aware:
+
+    - Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
+    - Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
+    - Isolated cron delivery waits out descendant subagent follow-up when needed and suppresses stale parent acknowledgement text instead of announcing it.
+    - Subagent completion delivery uses the child's latest visible assistant text only. Tool/toolResult output is not promoted into child result text. Terminal failed runs announce failure status without replaying captured reply text.
+    - Cleanup failures do not mask the real task outcome.
+
+    When applying maintenance, OpenClaw also removes stale `cron:<jobId>:run:<runId>` session registry rows older than 7 days, while preserving rows for currently running cron jobs and leaving non-cron session rows untouched.
+
+  </Accordion>
+  <Accordion title="tasks flow list | show | cancel">
+    ```bash
+    openclaw tasks flow list [--status <status>] [--json]
+    openclaw tasks flow show <lookup> [--json]
+    openclaw tasks flow cancel <lookup>
+    ```
+
+    The flow lookup token accepts a flow id or owner key. Use these when the orchestrating [Task Flow](/automation/taskflow) is the thing you care about rather than one individual background task record.
+
+  </Accordion>
+</AccordionGroup>
+
+## Chat task board (`/tasks`)
+
+Use `/tasks` in any chat session to see background tasks linked to that session. The board shows up to five active and recently completed tasks with runtime, status, timing, and progress or error detail.
+
+When the current session has no visible linked tasks, `/tasks` falls back to agent-local task counts so you still get an overview without leaking other-session details.
+
+For the full operator ledger, use the CLI: `openclaw tasks list`.
+
+## Status integration (task pressure)
+
+`openclaw status` includes an at-a-glance task line:
+
+```
+Tasks    2 active · 1 queued · 1 running · 1 issue · audit clean · 6 tracked
+```
+
+The summary counts active work (`queued` + `running`), failures (`failed` + `timed_out` + `lost`), audit findings, and total tracked records; the JSON payload also breaks counts down by runtime (`acp`, `subagent`, `cron`, `cli`).
+
+Both `/status` and the `session_status` tool use a cleanup-aware task snapshot: active tasks are preferred, expired rows are hidden, and terminal tasks only appear for a short recent window (5 minutes), with failures focused when no active work remains. This keeps the status card on what matters right now.
+
+## Storage and maintenance
+
+### Where tasks live
+
+Task records and delivery state persist in the shared OpenClaw SQLite state database:
+
+```
+~/.openclaw/state/openclaw.sqlite   (tables: task_runs, task_delivery_state, flow_runs)
+```
+
+Set `OPENCLAW_STATE_DIR` to move the whole state root (default `~/.openclaw`) elsewhere; the shared database path moves with it.
+
+The registry loads into memory on first use and persists every write back to SQLite, so records survive gateway restarts. WAL growth stays bounded through SQLite's default autocheckpoint threshold plus periodic `PASSIVE` checkpoints; shutdown and explicit maintenance checkpoints use `TRUNCATE` so normal closes reclaim WAL space without making the background sweeper wait on active readers.
+
+Legacy sidecar stores from older installs (`tasks/runs.sqlite`, `flows/registry.sqlite`) are imported into the shared database by `openclaw doctor`.
+
+### Automatic maintenance
+
+A sweeper runs every **60 seconds** (first pass about 5 seconds after gateway start) and handles four things:
+
+<Steps>
+  <Step title="Reconciliation">
+    Checks whether active tasks still have authoritative runtime backing. ACP tasks require a live in-process turn, subagent tasks use child-session state, cron tasks use active-job ownership plus durable run history, and CLI tasks with run identity use the owning run context. If backing state is gone for more than 5 minutes (30 minutes for childless native subagent tasks), the task is marked `lost`.
+  </Step>
+  <Step title="ACP session repair">
+    Closes terminal or orphaned parent-owned one-shot ACP sessions, and closes stale terminal or orphaned persistent ACP sessions only when no active conversation binding remains.
+  </Step>
+  <Step title="Cleanup stamping">
+    Sets a `cleanupAfter` timestamp on terminal tasks (terminal time + retention window). During retention, lost tasks still appear in audit as warnings; after `cleanupAfter` expires or when cleanup metadata is missing, they become errors.
+  </Step>
+  <Step title="Pruning">
+    Deletes records past their `cleanupAfter` date.
+  </Step>
+</Steps>
+
+<Note>
+**Retention:** terminal task records are kept for **7 days** (`lost` records for **24 hours**), then automatically pruned. No configuration needed.
+</Note>
+
+## How tasks relate to other systems
+
+<AccordionGroup>
+  <Accordion title="Tasks and Task Flow">
+    [Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
+
+  </Accordion>
+  <Accordion title="Tasks and cron">
+    Cron job definitions, runtime execution state, and run history live in OpenClaw's shared SQLite state database. **Every** cron execution creates a task record - both main-session and isolated - with `silent` notify policy, so cron runs are tracked without generating task notifications of their own.
+
+    See [Cron Jobs](/automation/cron-jobs).
+
+  </Accordion>
+  <Accordion title="Tasks and heartbeat">
+    Heartbeat runs are main-session turns - they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly.
+
+    See [Heartbeat](/gateway/heartbeat).
+
+  </Accordion>
+  <Accordion title="Tasks and sessions">
+    A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Its `agentId` identifies the agent executing the work, while the requester and owner fields preserve launch and control context. Sessions are conversation context; tasks are activity tracking on top of that.
+  </Accordion>
+  <Accordion title="Tasks and agent runs">
+    A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status - you do not need to manage the lifecycle manually.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Automation](/automation) - all automation mechanisms at a glance
+- [CLI: Tasks](/cli/tasks) - CLI command reference
+- [Heartbeat](/gateway/heartbeat) - periodic main-session turns
+- [Scheduled Tasks](/automation/cron-jobs) - scheduling background work
+- [Task Flow](/automation/taskflow) - flow orchestration above tasks

docs/automation/troubleshooting.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /automation/cron-jobs"
+title: "Automation troubleshooting"
+---
+
+This page moved. Automation troubleshooting now lives at [Scheduled Tasks](/automation/cron-jobs#troubleshooting).
+
+## Related
+
+- [Hooks](/automation/hooks)
+- [Background tasks](/automation/tasks)
+- [Gateway troubleshooting](/gateway/troubleshooting)

docs/automation/webhook.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /automation/cron-jobs"
+title: "Webhooks"
+---
+
+This page moved. Webhook documentation now lives at [Scheduled Tasks](/automation/cron-jobs#webhooks).
+
+## Related
+
+- [Poll](/automation/poll)
+- [Gmail PubSub](/automation/gmail-pubsub)
+- [Hooks](/automation/hooks)

docs/brave-search.md

@@ -0,0 +1,11 @@
+---
+summary: "Redirect to /tools/brave-search"
+title: "Brave search"
+redirect: /tools/brave-search
+---
+
+This page has moved to [Brave Search](/tools/brave-search).
+
+## Related
+
+- [Web tools](/tools/web)

docs/channels/access-groups.md

@@ -0,0 +1,197 @@
+---
+summary: "Reusable sender allowlists for message channels"
+read_when:
+  - Configuring the same allowlist across multiple message channels
+  - Sharing DM and group sender access rules
+  - Reviewing message-channel access control
+title: "Access groups"
+---
+
+Access groups are named sender lists you define once under `accessGroups` and reference from channel allowlists with `accessGroup:<name>`.
+
+Use them when the same people should be allowed across several message channels, or when one trusted set should apply to both DMs and group sender authorization.
+
+A group grants nothing by itself. It only matters where an allowlist field references it.
+
+## Static message sender groups
+
+Static sender groups use `type: "message.senders"`. `members` is keyed by message-channel id, plus `"*"` for entries shared by every channel:
+
+```json5
+{
+  accessGroups: {
+    operators: {
+      type: "message.senders",
+      members: {
+        "*": ["global-owner-id"],
+        discord: ["discord:123456789012345678"],
+        telegram: ["987654321"],
+        whatsapp: ["+15551234567"],
+      },
+    },
+  },
+}
+```
+
+| Key                        | Meaning                                                                     |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `"*"`                      | Shared entries checked for every message channel that references the group. |
+| `discord`, `telegram`, ... | Entries checked only for that channel's allowlist matching.                 |
+
+Entries are matched with the destination channel's normal `allowFrom` rules. OpenClaw does not translate sender ids between channels: if Alice has a Telegram id and a Discord id, list both ids under the matching channel keys.
+
+## Reference groups from allowlists
+
+Reference a group with `accessGroup:<name>` anywhere the message channel path supports sender allowlists.
+
+DM allowlist example:
+
+```json5
+{
+  accessGroups: {
+    operators: {
+      type: "message.senders",
+      members: {
+        discord: ["discord:123456789012345678"],
+        telegram: ["987654321"],
+      },
+    },
+  },
+  channels: {
+    discord: {
+      dmPolicy: "allowlist",
+      allowFrom: ["accessGroup:operators"],
+    },
+    telegram: {
+      dmPolicy: "allowlist",
+      allowFrom: ["accessGroup:operators"],
+    },
+  },
+}
+```
+
+Group sender allowlist example:
+
+```json5
+{
+  accessGroups: {
+    oncall: {
+      type: "message.senders",
+      members: {
+        whatsapp: ["+15551234567"],
+        googlechat: ["users/1234567890"],
+      },
+    },
+  },
+  channels: {
+    whatsapp: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["accessGroup:oncall"],
+    },
+    googlechat: {
+      groups: {
+        "spaces/AAA": {
+          users: ["accessGroup:oncall"],
+        },
+      },
+    },
+  },
+}
+```
+
+You can mix groups and direct entries:
+
+```json5
+{
+  channels: {
+    discord: {
+      dmPolicy: "allowlist",
+      allowFrom: ["accessGroup:operators", "discord:123456789012345678"],
+    },
+  },
+}
+```
+
+## Supported message-channel paths
+
+Access groups work in the shared message-channel authorization paths:
+
+- DM sender allowlists such as `channels.<channel>.allowFrom`
+- group sender allowlists such as `channels.<channel>.groupAllowFrom`
+- channel-specific per-room sender allowlists that use the same sender matching rules (for example Google Chat `groups.<space>.users`)
+- command authorization paths that reuse message-channel sender allowlists
+
+Channel support depends on whether that channel is wired through the shared OpenClaw sender-authorization helpers. Current bundled support includes ClickClack, Discord, Feishu, Google Chat, iMessage, IRC, LINE, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Signal, Slack, SMS, Telegram, WhatsApp, Zalo, and Zalo Personal. Static `message.senders` groups are channel-agnostic, so new message channels get them by using the shared plugin SDK ingress helpers instead of custom allowlist expansion.
+
+## Discord channel audiences
+
+Discord also supports a dynamic access group type:
+
+```json5
+{
+  accessGroups: {
+    maintainers: {
+      type: "discord.channelAudience",
+      guildId: "1456350064065904867",
+      channelId: "1456744319972282449",
+      membership: "canViewChannel",
+    },
+  },
+  channels: {
+    discord: {
+      dmPolicy: "allowlist",
+      allowFrom: ["accessGroup:maintainers"],
+    },
+  },
+}
+```
+
+`discord.channelAudience` means "allow Discord DM senders who can currently view this guild channel." OpenClaw resolves the sender through Discord at authorization time and applies Discord `ViewChannel` permission rules. `membership` is optional and defaults to `canViewChannel`.
+
+Use this when a Discord channel is already the source of truth for a team, such as `#maintainers` or `#on-call`.
+
+Requirements and failure behavior:
+
+- The bot needs access to the guild and channel.
+- The bot needs the Discord Developer Portal **Server Members Intent**.
+- The access group fails closed when Discord returns `Missing Access`, the sender cannot be resolved as a guild member, or the channel belongs to another guild.
+
+More Discord-specific examples: [Discord access control](/channels/discord#access-control-and-routing)
+
+## Plugin diagnostics
+
+Plugin authors can inspect structured access-group state without expanding it back into a flat allowlist:
+
+```typescript
+import { resolveAccessGroupAllowFromState } from "openclaw/plugin-sdk/access-groups";
+
+const state = await resolveAccessGroupAllowFromState({
+  accessGroups: cfg.accessGroups,
+  allowFrom: channelConfig.allowFrom,
+  channel: "my-channel",
+  accountId: "default",
+  senderId,
+  isSenderAllowed,
+});
+```
+
+The result reports referenced, matched, missing, unsupported, and failed groups. Use it for diagnostics or conformance tests. Use `expandAllowFromWithAccessGroups(...)` only for compatibility paths that still expect a flat `allowFrom` array.
+
+## Security notes
+
+- Access groups are allowlist aliases, not roles. They do not create owners, approve pairing requests, or grant tool permissions by themselves.
+- `dmPolicy: "open"` still requires `"*"` in the effective DM allowlist. Referencing an access group is not the same as public access.
+- Missing group names fail closed. If `allowFrom` contains `accessGroup:operators` and `accessGroups.operators` is absent, that entry authorizes nobody.
+- Keep channel ids stable. Prefer numeric/user ids over display names when the channel supports both.
+
+## Troubleshooting
+
+If a sender should match but is blocked:
+
+1. Confirm the allowlist field contains the exact `accessGroup:<name>` reference.
+2. Confirm `accessGroups.<name>.type` is correct.
+3. Confirm the sender id is listed under the matching channel key, or under `"*"`.
+4. Confirm the entry uses that channel's normal allowlist syntax.
+5. For Discord channel audiences, confirm the bot can see the guild channel and has Server Members Intent enabled.
+
+Run `openclaw doctor` after editing access-control config. It catches many invalid allowlist and policy combinations before runtime.