chore(sync): mirror docs from openclaw/openclaw@888448facc

.openclaw-sync/source.json

@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "f204f0c9994fe5cc39cee5f165d597eb5b18ff2a",
-  "syncedAt": "2026-04-25T18:36:49.920Z"
+  "sha": "888448facc1b9d1b65d8da83d734190dcbd7d1ba",
+  "syncedAt": "2026-04-25T18:38:46.902Z"
 }

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-439ff58a4a54f0f4bda959239f382cc3b2f94a282680dcd89bd3f8c93e0f07d0  config-baseline.json
-6ef86147534d12aa5ac7a9cf208b4627177090c92479a71dfd1791096d20353b  config-baseline.core.json
+c8d24c55df89a76f44cd6ab5fdb7c28b0b3a8adadcd2c94a1d81263512075c0f  config-baseline.json
+97c37380e03c167ee710adb0ee297573146e78434635780226b744841628370b  config-baseline.core.json
 7cd9c908f066c143eab2a201efbc9640f483ab28bba92ddeca1d18cc2b528bc3  config-baseline.channel.json
 7825b56a5b3fcdbe2e09ef8fe5d9f12ac3598435afebe20413051e45b0d1968e  config-baseline.plugin.json

docs/cli/plugins.md

@@ -231,7 +231,19 @@ openclaw plugins install -l ./my-plugin
 source path instead of copying over a managed install target.
 
 Use `--pin` on npm installs to save the resolved exact spec (`name@version`) in
-`plugins.installs` while keeping the default behavior unpinned.
+the managed install ledger while keeping the default behavior unpinned.
+
+### Install Ledger
+
+Plugin install metadata is machine-managed state, not user config. New installs
+and updates write it to `plugins/installs.json` under the active OpenClaw state
+directory. The file includes a do-not-edit warning and is used by
+`openclaw plugins update`, uninstall, diagnostics, and the cold plugin registry.
+
+Legacy `plugins.installs` entries in `openclaw.json` remain readable as a
+deprecated compatibility fallback. When install/update/uninstall paths rewrite
+plugin install state, OpenClaw writes the ledger file and removes
+`plugins.installs` from the persisted config payload.
 
 ### Uninstall
 
@@ -241,8 +253,9 @@ openclaw plugins uninstall <id> --dry-run
 openclaw plugins uninstall <id> --keep-files
 ```
 
-`uninstall` removes plugin records from `plugins.entries`, `plugins.installs`,
-the plugin allowlist, and linked `plugins.load.paths` entries when applicable.
+`uninstall` removes plugin records from `plugins.entries`, the managed install
+ledger, the plugin allowlist, and linked `plugins.load.paths` entries when
+applicable.
 For active memory plugins, the memory slot resets to `memory-core`.
 
 By default, uninstall also removes the plugin install directory under the active
@@ -261,8 +274,8 @@ openclaw plugins update @openclaw/voice-call@beta
 openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
 ```
 
-Updates apply to tracked installs in `plugins.installs` and tracked hook-pack
-installs in `hooks.internal.installs`.
+Updates apply to tracked plugin installs in the managed install ledger and
+tracked hook-pack installs in `hooks.internal.installs`.
 
 When you pass a plugin id, OpenClaw reuses the recorded install spec for that
 plugin. That means previously stored dist-tags such as `@beta` and exact pinned

docs/gateway/configuration-reference.md

@@ -186,9 +186,14 @@ See [MCP](/cli/mcp#openclaw-as-an-mcp-client-registry) and
 - Enabled Claude bundle plugins can also contribute embedded Pi defaults from `settings.json`; OpenClaw applies those as sanitized agent settings, not as raw OpenClaw config patches.
 - `plugins.slots.memory`: pick the active memory plugin id, or `"none"` to disable memory plugins.
 - `plugins.slots.contextEngine`: pick the active context engine plugin id; defaults to `"legacy"` unless you install and select another engine.
-- `plugins.installs`: CLI-managed install metadata used by `openclaw plugins update`.
-  - Includes `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
-  - Treat `plugins.installs.*` as managed state; prefer CLI commands over manual edits.
+- `plugins.installs`: deprecated compatibility fallback for legacy
+  CLI-managed install metadata. New plugin installs write the managed
+  `plugins/installs.json` state ledger instead.
+  - Legacy records include `source`, `spec`, `sourcePath`, `installPath`,
+    `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`,
+    `shasum`, `resolvedAt`, `installedAt`.
+  - Treat `plugins.installs.*` as managed state; prefer CLI commands over
+    manual edits.
 
 See [Plugins](/tools/plugin).
 

docs/plugins/architecture-internals.md

@@ -911,13 +911,15 @@ Official external npm entries should prefer an exact `npmSpec` plus
 `expectedIntegrity`. Bare package names and dist-tags still work for
 compatibility, but they surface source-plane warnings so the catalog can move
 toward pinned, integrity-checked installs without breaking existing plugins.
-When onboarding installs from a local catalog path, it records a
-`plugins.installs` entry with `source: "path"` and a workspace-relative
+When onboarding installs from a local catalog path, it records a managed plugin
+install ledger entry with `source: "path"` and a workspace-relative
 `sourcePath` when possible. The absolute operational load path stays in
 `plugins.load.paths`; the install record avoids duplicating local workstation
 paths into long-lived config. This keeps local development installs visible to
 source-plane diagnostics without adding a second raw filesystem-path disclosure
-surface.
+surface. Legacy `plugins.installs` config entries are still read as a
+compatibility fallback while the state-managed `plugins/installs.json` ledger
+becomes the install source of truth.
 
 ## Context engine plugins