docs(plugins): document persisted registry repair

docs/cli/plugins.md

@@ -31,6 +31,8 @@ openclaw plugins inspect --all
 openclaw plugins info <id>
 openclaw plugins enable <id>
 openclaw plugins disable <id>
+openclaw plugins registry
+openclaw plugins registry --refresh
 openclaw plugins uninstall <id>
 openclaw plugins doctor
 openclaw plugins update <id-or-npm-spec>
@@ -195,18 +197,20 @@ openclaw plugins list --verbose
 openclaw plugins list --json
 ```
 
-Use `--enabled` to show only loaded plugins. Use `--verbose` to switch from the
+Use `--enabled` to show only enabled plugins. Use `--verbose` to switch from the
 table view to per-plugin detail lines with source/origin/version/activation
 metadata. Use `--json` for machine-readable inventory plus registry
 diagnostics.
 
-`plugins list` runs discovery from the current CLI environment and config. It is
-useful for checking whether a plugin is enabled/loadable, but it is not a live
-runtime probe of an already-running Gateway process. After changing plugin code,
-enablement, hook policy, or `plugins.load.paths`, restart the Gateway that
-serves the channel before expecting new `register(api)` code or hooks to run.
-For remote/container deployments, verify you are restarting the actual
-`openclaw gateway run` child, not only a wrapper process.
+`plugins list` reads the persisted local plugin registry first, with a
+manifest-only derived fallback when the registry is missing or invalid. It is
+useful for checking whether a plugin is installed, enabled, and visible to cold
+startup planning, but it is not a live runtime probe of an already-running
+Gateway process. After changing plugin code, enablement, hook policy, or
+`plugins.load.paths`, restart the Gateway that serves the channel before
+expecting new `register(api)` code or hooks to run. For remote/container
+deployments, verify you are restarting the actual `openclaw gateway run` child,
+not only a wrapper process.
 
 For runtime hook debugging:
 
@@ -333,6 +337,24 @@ For module-shape failures such as missing `register`/`activate` exports, rerun
 with `OPENCLAW_PLUGIN_LOAD_DEBUG=1` to include a compact export-shape summary in
 the diagnostic output.
 
+### Registry
+
+```bash
+openclaw plugins registry
+openclaw plugins registry --refresh
+openclaw plugins registry --json
+```
+
+The local plugin registry is OpenClaw's persisted cold read model for installed
+plugin identity, enablement, source metadata, and contribution ownership.
+Normal startup, provider owner lookup, channel setup classification, and plugin
+inventory can read it without importing plugin runtime modules.
+
+Use `plugins registry` to inspect whether the persisted registry is present,
+current, or stale. Use `--refresh` to rebuild it from the durable install
+ledger, config policy, and manifest/package metadata. This is a repair path, not
+a runtime activation path.
+
 ### Marketplace
 
 ```bash

docs/gateway/doctor.md

@@ -457,7 +457,7 @@ Doctor prints a summary of the workspace state for the default agent:
 - **Skills status**: counts eligible, missing-requirements, and allowlist-blocked skills.
 - **Legacy workspace dirs**: warns when `~/openclaw` or other legacy workspace directories
   exist alongside the current workspace.
-- **Plugin status**: counts loaded/disabled/errored plugins; lists plugin IDs for any
+- **Plugin status**: counts enabled/disabled/errored plugins; lists plugin IDs for any
   errors; reports bundle plugin capabilities.
 - **Plugin compatibility warnings**: flags plugins that have compatibility issues with
   the current runtime.

docs/tools/plugin.md

@@ -159,12 +159,12 @@ hooks; restart the Gateway process that is serving the live channel before
 expecting updated `register(api)` code, `api.on(...)` hooks, tools, services, or
 provider/runtime hooks to run.
 
-`openclaw plugins list` is a local CLI/config snapshot. A `loaded` plugin there
-means the plugin is discoverable and loadable from the config/files seen by that
-CLI invocation. It does not prove that an already-running remote Gateway child
-has restarted into the same plugin code. On VPS/container setups with wrapper
-processes, send restarts to the actual `openclaw gateway run` process, or use
-`openclaw gateway restart` against the running Gateway.
+`openclaw plugins list` is a local plugin registry/config snapshot. An
+`enabled` plugin there means the persisted registry and current config allow the
+plugin to participate. It does not prove that an already-running remote Gateway
+child has restarted into the same plugin code. On VPS/container setups with
+wrapper processes, send restarts to the actual `openclaw gateway run` process,
+or use `openclaw gateway restart` against the running Gateway.
 
 <Accordion title="Plugin states: disabled vs missing vs invalid">
   - **Disabled**: plugin exists but enablement rules turned it off. Config is preserved.
@@ -256,7 +256,7 @@ Some categories are exclusive (only one active at a time):
 
 ```bash
 openclaw plugins list                       # compact inventory
-openclaw plugins list --enabled            # only loaded plugins
+openclaw plugins list --enabled            # only enabled plugins
 openclaw plugins list --verbose            # per-plugin detail lines
 openclaw plugins list --json               # machine-readable inventory
 openclaw plugins inspect <id>              # deep detail
@@ -264,6 +264,8 @@ openclaw plugins inspect <id> --json       # machine-readable
 openclaw plugins inspect --all             # fleet-wide table
 openclaw plugins info <id>                 # inspect alias
 openclaw plugins doctor                    # diagnostics
+openclaw plugins registry                  # inspect persisted registry state
+openclaw plugins registry --refresh        # rebuild persisted registry
 
 openclaw plugins install <package>         # install (ClawHub first, then npm)
 openclaw plugins install clawhub:<pkg>     # install from ClawHub only
@@ -299,6 +301,13 @@ When `plugins.allow` is already set, `openclaw plugins install` adds the
 installed plugin id to that allowlist before enabling it, so installs are
 immediately loadable after restart.
 
+OpenClaw keeps a persisted local plugin registry as the cold read model for
+plugin inventory, contribution ownership, and startup planning. Install, update,
+uninstall, enable, and disable flows refresh that registry after changing plugin
+state. If the registry is missing, stale, or invalid, `openclaw plugins registry
+--refresh` rebuilds it from the durable install ledger, config policy, and
+manifest/package metadata without loading plugin runtime modules.
+
 `openclaw plugins update <id-or-npm-spec>` applies to tracked installs. Passing
 an npm package spec with a dist-tag or exact version resolves the package name
 back to the tracked plugin record and records the new spec for future updates.