docs(plugins): add management quickstart

docs/cli/plugins.md

@@ -13,6 +13,9 @@ Manage Gateway plugins, hook packs, and compatible bundles.
   <Card title="Plugin system" href="/tools/plugin">
     End-user guide for installing, enabling, and troubleshooting plugins.
   </Card>
+  <Card title="Manage plugins" href="/plugins/manage-plugins">
+    Quick examples for install, list, update, uninstall, and publishing.
+  </Card>
   <Card title="Plugin bundles" href="/plugins/bundles">
     Bundle compatibility model.
   </Card>

docs/docs.json

@@ -1182,6 +1182,7 @@
                 "group": "Plugins",
                 "pages": [
                   "tools/plugin",
+                  "plugins/manage-plugins",
                   "plugins/community",
                   "plugins/plugin-inventory",
                   "plugins/reference",

docs/plugins/manage-plugins.md

@@ -0,0 +1,180 @@
+---
+summary: "Quick examples for installing, listing, uninstalling, updating, and publishing OpenClaw plugins"
+read_when:
+  - You want quick plugin install, list, update, or uninstall examples
+  - You want to choose between ClawHub and npm plugin distribution
+  - You are publishing a plugin package
+title: "Manage plugins"
+sidebarTitle: "Manage plugins"
+---
+
+Most plugin workflows are a few commands: search, install, restart the Gateway,
+verify, and uninstall when you no longer need the plugin.
+
+## List plugins
+
+```bash
+openclaw plugins list
+openclaw plugins list --enabled
+openclaw plugins list --verbose
+openclaw plugins list --json
+```
+
+Use `--json` for scripts. It includes registry diagnostics and each plugin's
+static `dependencyStatus` when the plugin package declares `dependencies` or
+`optionalDependencies`.
+
+```bash
+openclaw plugins list --json \
+  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
+```
+
+`plugins list` is a cold inventory check. It shows what OpenClaw can discover
+from config, manifests, and the plugin registry; it does not prove that an
+already-running Gateway process imported the plugin runtime.
+
+## Install plugins
+
+```bash
+# Search ClawHub for plugin packages.
+openclaw plugins search "calendar"
+
+# Bare package specs try ClawHub first, then npm fallback.
+openclaw plugins install <package>
+
+# Force one source.
+openclaw plugins install clawhub:<package>
+openclaw plugins install npm:<package>
+
+# Install a specific version or dist-tag.
+openclaw plugins install clawhub:<package>@1.2.3
+openclaw plugins install clawhub:<package>@beta
+openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
+openclaw plugins install npm:@openclaw/codex@beta
+
+# Install from git or a local development checkout.
+openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
+openclaw plugins install ./my-plugin
+openclaw plugins install --link ./my-plugin
+```
+
+After installing plugin code, restart the Gateway that serves your channels:
+
+```bash
+openclaw gateway restart
+openclaw plugins inspect <plugin-id> --runtime --json
+```
+
+Use `inspect --runtime` when you need proof that the plugin registered runtime
+surfaces such as tools, hooks, services, Gateway methods, or plugin-owned CLI
+commands.
+
+## Update plugins
+
+```bash
+openclaw plugins update <plugin-id>
+openclaw plugins update <npm-package-or-spec>
+openclaw plugins update --all
+```
+
+If a plugin was installed from an npm dist-tag such as `@beta`, later
+`update <plugin-id>` calls reuse that recorded tag. Passing an explicit npm spec
+switches the tracked install to that spec for future updates.
+
+```bash
+openclaw plugins update @scope/openclaw-plugin@beta
+openclaw plugins update @scope/openclaw-plugin
+```
+
+The second command moves a plugin back to the registry's default release line
+when it was previously pinned to an exact version or tag.
+
+## Uninstall plugins
+
+```bash
+openclaw plugins uninstall <plugin-id> --dry-run
+openclaw plugins uninstall <plugin-id>
+openclaw plugins uninstall <plugin-id> --keep-files
+openclaw gateway restart
+```
+
+Uninstall removes the plugin's config entry, plugin index record, allow/deny list
+entries, and linked load paths when applicable. Managed install directories are
+removed unless you pass `--keep-files`.
+
+## Publish plugins
+
+You can publish external plugins to [ClawHub](https://clawhub.ai), npmjs.com, or
+both.
+
+### Publish to ClawHub
+
+ClawHub is the primary public discovery surface for OpenClaw plugins. It gives
+users searchable metadata, version history, and registry scan results before
+install.
+
+```bash
+npm i -g clawhub
+clawhub login
+clawhub package publish your-org/your-plugin --dry-run
+clawhub package publish your-org/your-plugin
+clawhub package publish your-org/your-plugin@v1.0.0
+```
+
+Users install from ClawHub with:
+
+```bash
+openclaw plugins install clawhub:<package>
+openclaw plugins install <package>
+```
+
+The bare form still checks ClawHub first.
+
+### Publish to npmjs.com
+
+Native npm plugins must include a plugin manifest and `package.json` OpenClaw
+entrypoint metadata.
+
+```json package.json
+{
+  "name": "@acme/openclaw-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./dist/index.js"]
+  }
+}
+```
+
+```bash
+npm publish --access public
+```
+
+Users install npm-only with:
+
+```bash
+openclaw plugins install npm:@acme/openclaw-plugin
+openclaw plugins install npm:@acme/openclaw-plugin@beta
+openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
+```
+
+If the same package is also available on ClawHub, `npm:` skips ClawHub lookup and
+forces npm resolution.
+
+## Source choice
+
+- **ClawHub**: use when you want OpenClaw-native discovery, scan summaries,
+  versions, and install hints.
+- **npmjs.com**: use when you already ship JavaScript packages or need npm
+  dist-tags/private registry workflows.
+- **Git**: use when you want to install directly from a branch, tag, or commit.
+- **Local path**: use when you are developing or testing a plugin on the same
+  machine.
+
+## Related
+
+- [Plugins](/tools/plugin) - overview and troubleshooting
+- [`openclaw plugins`](/cli/plugins) - full CLI reference
+- [ClawHub](/tools/clawhub) - publish and registry operations
+- [Building plugins](/plugins/building-plugins) - create a plugin package
+- [Plugin manifest](/plugins/manifest) - manifest and package metadata

docs/tools/plugin.md

@@ -18,6 +18,9 @@ temporary set of OpenClaw-owned plugin packages while that migration finishes.
 
 ## Quick start
 
+For copy-paste install, list, uninstall, update, and publishing examples, see
+[Manage plugins](/plugins/manage-plugins).
+
 <Steps>
   <Step title="See what is loaded">
     ```bash