diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index d32bba100..65d21f6dc 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "9eeceaca438777c131e7933e50b35533654fce24",
-  "syncedAt": "2026-04-24T22:55:52.618Z"
+  "sha": "0c46e8000e2b1d32d0d28c1fa63e25f09190a48f",
+  "syncedAt": "2026-04-24T22:56:25.348Z"
 }
diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index f5fe9f6c4..068ea6bb3 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -1,2 +1,2 @@
-b4fb88ca434fb92a38bb068cc0b1863b1f22bcde2ce21499c3077ea7e8460775  plugin-sdk-api-baseline.json
-0f373c8820c0cd17b13dddf520dd286d9dec85234eb0a7f94dac07432572ede7  plugin-sdk-api-baseline.jsonl
+eb5c790aaa54be7b1380eb5a162db50dd314e052aedb5e608290092c33d999f2  plugin-sdk-api-baseline.json
+0d2fd80f69e0c3488b6bdbbbb035b08ab108637790d1f30b8e4f84c71c5bc8e2  plugin-sdk-api-baseline.jsonl
diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md
index 7bb19b60a..c6f499175 100644
--- a/docs/tools/plugin.md
+++ b/docs/tools/plugin.md
@@ -366,6 +366,21 @@ activation. The loader still falls back to `activate(api)` for older plugins,
 but bundled plugins and new external plugins should treat `register` as the
 public contract.
 
+`api.registrationMode` tells a plugin why its entry is being loaded:
+
+| Mode            | Meaning                                                                                                |
+| --------------- | ------------------------------------------------------------------------------------------------------ |
+| `full`          | Runtime activation. Register tools, hooks, services, commands, routes, and other live side effects.    |
+| `discovery`     | Read-only capability discovery. Register providers and metadata, but skip expensive live side effects. |
+| `setup-only`    | Channel setup metadata loading through a lightweight setup entry.                                      |
+| `setup-runtime` | Channel setup loading that also needs the runtime entry.                                               |
+| `cli-metadata`  | CLI command metadata collection only.                                                                  |
+
+Plugin entries that open sockets, databases, background workers, or long-lived
+clients should guard those side effects with `api.registrationMode === "full"`.
+Discovery loads are cached separately from activating loads and do not replace
+the running Gateway registry.
+
 Common registration methods:
 
 | Method                                  | What it registers           |