diff --git a/docs/README.md b/docs/README.md index 8517e8850..935e9e6a3 100644 --- a/docs/README.md +++ b/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) | diff --git a/docs/architecture.md b/docs/architecture.md index c7fea8ab2..6599423f2 100644 --- a/docs/architecture.md +++ b/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 | -| Skill | Add workspace skills under `/skills/`, Agent Plugins v1 under `/plugins/`, or built-in skills under `nanobot/skills/` | +| Agent Plugin | Add a v1 package under `/plugins/` and enable it from Apps | +| MCP | Add `tools.mcpServers` config or bundle the server in an Agent Plugin | +| Skill | Add workspace skills under `/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. diff --git a/docs/concepts.md b/docs/concepts.md index 0e4cdcbfb..068d83933 100644 --- a/docs/concepts.md +++ b/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: diff --git a/docs/configuration.md b/docs/configuration.md index 6a8e010b2..d915ceb1c 100644 --- a/docs/configuration.md +++ b/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 `/plugins/`; a v1 package has `plugin.json` and may add `mcp.json`, `skills//SKILL.md`, or both. +nanobot discovers [Agent Plugins](https://agent-plugins.org/) under `/plugins/`; a v1 package has `plugin.json` and may add `mcp.json`, `skills//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 diff --git a/docs/webui.md b/docs/webui.md index d89db9a63..cafb57b77 100644 --- a/docs/webui.md +++ b/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 -turn. The default **Ready** view shows only tools that can be used immediately: +Open Apps from the sidebar to review and manage installable capabilities. The +default **Ready** view shows only capabilities that can be used immediately: -- **Apps** are local command-line adapters that nanobot runs on your machine. - Installing an adapter does not modify the native desktop or web app it - connects to. +- **Agent Plugins** are local packages that can bundle skills, MCP servers, or + both. A package under `/plugins/` is installed but remains inactive + 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 `@` -to attach that tool to the next message. +After a CLI App or MCP server is available, mention it from the composer with +`@` to attach that tool to the next message. Plugin-provided skills participate +in normal skill discovery and can be invoked with `$skill-name`. ## Skills