docs: CLI + gateway + plugin harness coverage for 48h changes

docs/cli/plugins.md

@@ -68,6 +68,13 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
 Bare package names are checked against ClawHub first, then npm. Security note:
 treat plugin installs like running code. Prefer pinned versions.
 
+If your `plugins` section is backed by a single-file `$include`, `plugins install`,
+`plugins update`, `plugins enable`, `plugins disable`, and `plugins uninstall`
+write through to that included file and leave `openclaw.json` untouched. Root
+includes, include arrays, and includes with sibling overrides fail closed
+instead of flattening. See [Config includes](/gateway/configuration) for the
+supported shapes.
+
 If config is invalid, `plugins install` normally fails closed and tells you to
 run `openclaw doctor --fix` first. The only documented exception is a narrow
 bundled-plugin recovery path for plugins that explicitly opt into
@@ -79,6 +86,11 @@ the same id from a new local path, archive, ClawHub package, or npm artifact.
 For routine upgrades of an already tracked npm plugin, prefer
 `openclaw plugins update <id-or-npm-spec>`.
 
+If you run `plugins install` for a plugin id that is already installed, OpenClaw
+stops and points you at `plugins update <id-or-npm-spec>` for a normal upgrade,
+or at `plugins install <package> --force` when you genuinely want to overwrite
+the current install from a different source.
+
 `--pin` applies to npm installs only. It is not supported with `--marketplace`,
 because marketplace installs persist marketplace source metadata instead of an
 npm spec.