diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 2d81d96c2..326eee037 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "bfa2feaa92b986392eb8fdb9b7ed24577afeeb63",
-  "syncedAt": "2026-04-12T06:48:45.641Z"
+  "sha": "a9c7c2e1edf56dcdbc9c6b31c3410cbbaa6f1d60",
+  "syncedAt": "2026-04-12T08:08:28.544Z"
 }
diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md
index 406e450a3..468e498f2 100644
--- a/docs/plugins/architecture.md
+++ b/docs/plugins/architecture.md
@@ -527,6 +527,9 @@ actual behavior such as hooks, tools, commands, or provider flows.
 Optional manifest `activation` and `setup` blocks stay on the control plane.
 They are metadata-only descriptors for activation planning and setup discovery;
 they do not replace runtime registration, `register(...)`, or `setupEntry`.
+The first activation consumer now uses manifest command hints to narrow CLI
+plugin loading when a primary command is known, instead of always loading every
+CLI-capable plugin up front.
 
 Setup discovery now prefers descriptor-owned ids such as `setup.providers` and
 `setup.cliBackends` to narrow candidate plugins before it falls back to
diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md
index f1a6d424c..86fa25a10 100644
--- a/docs/plugins/manifest.md
+++ b/docs/plugins/manifest.md
@@ -221,6 +221,9 @@ should activate it later.
 
 This block is metadata only. It does not register runtime behavior, and it does
 not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.
+Current consumers use it as a narrowing hint before broader plugin loading, so
+missing activation metadata only costs performance; it should not change
+correctness.
 
 ```json
 {
@@ -242,6 +245,10 @@ not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.
 | `onRoutes`       | No       | `string[]`                                           | Route kinds that should activate this plugin.                     |
 | `onCapabilities` | No       | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. |
 
+For command-triggered planning specifically, OpenClaw still falls back to
+legacy `commandAliases[].cliCommand` or `commandAliases[].name` when a plugin
+has not added explicit `activation.onCommands` metadata yet.
+
 ## setup reference
 
 Use `setup` when setup and onboarding surfaces need cheap plugin-owned metadata