docs(plugins): clarify unified extension model

docs/README.md

@@ -19,7 +19,7 @@ The recommended first-run path is:
 3. Configure a provider and model in **Settings → Models**.
 4. Send `Hello!` before configuring anything else.
 
-Most people do not need to edit JSON for the first run. The WebUI handles the initial provider, model, and local browser settings. SSH, headless, existing-config, and older-release installs retain `nanobot onboard --wizard` as a terminal fallback. After the WebUI opens, use **Settings** for models and built-in capabilities, **Settings → Channels** for chat apps, and **Apps** for CLI App or MCP integrations.
+Most people do not need to edit JSON for the first run. The WebUI handles the initial provider, model, and local browser settings. SSH, headless, existing-config, and older-release installs retain `nanobot onboard --wizard` as a terminal fallback. After the WebUI opens, use **Settings** for models and built-in capabilities, **Settings → Channels** for chat apps, and **Apps** for Agent Plugins, CLI Apps, and MCP integrations.
 
 ## Add One Capability
 
@@ -32,6 +32,7 @@ Pick the row that matches what you want to accomplish next:
 | Choose a hosted, OAuth, company, or local model | [Provider Cookbook](./provider-cookbook.md) |
 | Add model fallbacks | [Configure Model Fallback](./guides/configure-model-fallback.md) |
 | Enable web search | [Configure Web Search](./guides/configure-web-search.md) |
+| Manage Agent Plugins, CLI Apps, or MCP integrations | [WebUI Apps](./webui.md#apps) |
 | Add an MCP tool server | [Configure MCP Tools](./guides/configure-mcp-tools.md) |
 | Generate images | [Image Generation](./image-generation.md) |
 | Schedule work or create a local trigger | [Automations](./automations.md) |

docs/architecture.md

@@ -201,8 +201,10 @@ When changing tools, channels, file access, WebUI workspace behavior, or network
 | Provider | Add `ProviderSpec` in `providers/registry.py`, add schema field in `config/schema.py`, implement provider only if the generic backend is not enough |
 | Channel | Export a `ChannelPlugin` descriptor, keep its runtime and optional setup surfaces in one package, and follow [`channel-package-guide.md`](./channel-package-guide.md) |
 | Tool | Implement a tool under `agent/tools/` or expose a plugin entry point |
-| MCP | Add `tools.mcpServers` config |
+| Agent Plugin | Add a v1 package under `<workspace>/plugins/` and enable it from Apps |
-| Skill | Add workspace skills under `<workspace>/skills/`, Agent Plugins v1 under `<workspace>/plugins/`, or built-in skills under `nanobot/skills/` |
+| MCP | Add `tools.mcpServers` config or bundle the server in an Agent Plugin |
+| Skill | Add workspace skills under `<workspace>/skills/`, bundle them in an Agent Plugin, or add built-in skills under `nanobot/skills/` |
+| CLI App | Add it to the CLI Apps catalog; the installer owns its executable lifecycle and writes a skills-only Agent Plugin |
 
 Prefer existing registry/discovery patterns over ad hoc wiring.
 

docs/concepts.md

@@ -132,6 +132,26 @@ Dream is a periodic consolidation job. It reads accumulated history and updates
 
 See [`memory.md`](./memory.md) for the detailed design.
 
+## Apps and Agent Plugins
+
+Agent Plugins are nanobot's common package and activation boundary for
+installable capabilities. They organize existing extension types instead of
+replacing them:
+
+| Part | Role |
+|---|---|
+| Agent Plugin | Installable package that can bundle skills, MCP servers, or both |
+| Skill | Workflow guidance loaded progressively or invoked with `$skill-name` |
+| MCP server | Runtime tools exposed to the agent |
+| CLI App | Locally managed executable whose adapter is packaged and activated like a plugin |
+| Apps | WebUI surface for reviewing and managing these capabilities |
+
+Native providers, channels, built-in tools, standalone workspace skills, and
+directly configured MCP servers keep their existing extension paths. See
+[`webui.md#apps`](./webui.md#apps) for the user-facing flow and
+[`configuration.md#agent-plugins-v1`](./configuration.md#agent-plugins-v1) for
+the package contract.
+
 ## Tools and Safety
 
 Tools are discovered automatically from built-in modules and plugin entry points. Common tool groups include:

docs/configuration.md

@@ -2349,7 +2349,7 @@ Disabled skills are excluded from the main agent's skill summary, from always-on
 
 ### Agent Plugins v1
 
-nanobot discovers [Agent Plugins](https://agent-plugins.org/) under `<workspace>/plugins/`; a v1 package has `plugin.json` and may add `mcp.json`, `skills/<name>/SKILL.md`, or both.
+nanobot discovers [Agent Plugins](https://agent-plugins.org/) under `<workspace>/plugins/`; a v1 package has `plugin.json` and may add `mcp.json`, `skills/<name>/SKILL.md`, or both. Agent Plugins are the common package and activation boundary for installable capabilities; they do not replace native providers, channels, tools, standalone workspace skills, or directly configured MCP servers.
 
 Directory presence means installed; activation is explicit in **Apps**. Skills use progressive loading and `$skill-name` invocation, with workspace > plugin > built-in precedence.
 Enabled `stdio` servers receive contained `PLUGIN_ROOT` and isolated `PLUGIN_DATA` paths; explicit

docs/webui.md

@@ -198,12 +198,16 @@ Test a new channel with a private DM. When a supported channel sends a pairing c
 
 ## Apps
 
-Open Apps from the sidebar to manage tools that nanobot can attach to a chat
+Open Apps from the sidebar to review and manage installable capabilities. The
-turn. The default **Ready** view shows only tools that can be used immediately:
+default **Ready** view shows only capabilities that can be used immediately:
 
-- **Apps** are local command-line adapters that nanobot runs on your machine.
+- **Agent Plugins** are local packages that can bundle skills, MCP servers, or
-  Installing an adapter does not modify the native desktop or web app it
+  both. A package under `<workspace>/plugins/` is installed but remains inactive
-  connects to.
+  until you enable it in Apps.
+- **CLI Apps** are local command-line adapters that nanobot runs on your
+  machine. Their installer manages the executable and exposes its adapter
+  through the same plugin activation model. Installing an adapter does not
+  modify the native desktop or web app it connects to.
 - **MCP** lists Model Context Protocol servers. Presets provide known
   configurations, and the **Add MCP server** panel accepts stdio, HTTP, and SSE
   servers. Custom HTTP/SSE servers can use no authentication, OAuth, or request
@@ -219,6 +223,7 @@ are not tools that can be attached to a turn with `@`. Manage them from
 included in nanobot and activate automatically when a file is attached. The
 equivalent CLI for optional integrations remains `nanobot plugins`. See
 [`cli-reference.md`](./cli-reference.md#optional-features).
+That command manages nanobot runtime extras, not Agent Plugin packages.
 
 Some MCP presets connect to hosted keyless endpoints. For example, the Firecrawl
 preset uses Firecrawl's hosted MCP endpoint for search, scrape, crawl, and
@@ -231,8 +236,9 @@ endpoint and exposes `web_search` and `web_fetch` without requiring an API key.
 It is an optional integration and does not replace nanobot's built-in web search
 provider; mention `@parallel-search` when a turn should use it.
 
-After an App or MCP server is available, mention it from the composer with `@`
+After a CLI App or MCP server is available, mention it from the composer with
-to attach that tool to the next message.
+`@` to attach that tool to the next message. Plugin-provided skills participate
+in normal skill discovery and can be invoked with `$skill-name`.
 
 ## Skills