Merge pull request agent0ai#1254 from 3clyp50/plugins8

plugins: dedicated skill/router flow, agent security scans, plugin validator builtin plugin, docs, and UX

Author: frdel

AGENTS.md

@@ -88,6 +88,13 @@ When running in Docker, Agent Zero uses two distinct Python runtimes to isolate
 ├── plugins/              # Core system plugins
 ├── agents/               # Agent profiles (prompts and config)
 ├── prompts/              # System and message prompt templates
+├── knowledge/
+│   └── main/about/       # Agent self-knowledge (indexed into vector DB for runtime recall)
+│       ├── identity.md           # Philosophy, principles, project context
+│       ├── architecture.md       # Agent loop, memory pipeline, multi-agent, extensions
+│       ├── capabilities.md       # Detailed capabilities and limitations
+│       ├── configuration.md      # LLM roles, providers, profiles, plugins, settings
+│       └── setup-and-deployment.md  # Docker deployment, updates, troubleshooting
 └── tests/                # Pytest suite
 ```
 
@@ -96,6 +103,7 @@ Key Files:
 - python/helpers/plugins.py: Plugin discovery and configuration logic.
 - webui/js/AlpineStore.js: Store factory for reactive frontend state.
 - python/helpers/api.py: Base class for all API endpoints.
+- knowledge/main/about/: Agent self-knowledge files, indexed into the vector DB for runtime recall. Not user-facing docs - written for the agent's internal reference.
 - docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.
 - docs/agents/AGENTS.modals.md: Guide to the stacked modal system.
 - docs/agents/AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
@@ -128,11 +136,13 @@ Key Files:
 - Location: Always develop new plugins in usr/plugins/.
 - Manifest: Every plugin requires a plugin.yaml with name, description, version, and optionally settings_sections, per_project_config, per_agent_config, and always_enabled.
 - Discovery: Conventions based on folder names (api/, tools/, webui/, extensions/).
+- Plugin-local Python imports: Prefer `usr.plugins.<plugin_name>...` for code that lives under `usr/plugins/`. Avoid `sys.path` hacks and avoid symlink-dependent `plugins.<plugin_name>...` imports for community plugins.
 - Runtime hooks: Plugins may also expose hooks in hooks.py, callable by the framework through helpers.plugins.call_plugin_hook(...).
 - Hook runtime: hooks.py executes inside the Agent Zero framework Python environment, so sys.executable -m pip installs dependencies into that same framework runtime.
 - Environment targeting: If a plugin needs packages or binaries for the separate agent execution runtime or system environment, it must explicitly switch environments in a subprocess by targeting the correct interpreter, virtualenv, or package manager.
 - Settings: Use get_plugin_config(plugin_name, agent=agent) to retrieve settings. Plugins can expose a UI for settings via webui/config.html. Plugin settings modals instantiate a local context from $store.pluginSettingsPrototype; bind plugin fields to config.* and use context.* for modal-level state and actions. For plugins wrapping core settings, set context.saveMode = 'core' in x-init.
 - Activation: Global and scoped activation rules are stored as .toggle-1 (ON) and .toggle-0 (OFF). Scoped rules are handled via the plugin "Switch" modal.
+- Cleanup rule: Plugins should not permanently modify the system in ways that outlive the plugin. Deleting a plugin should not leave behind symlinks, unmanaged services, or stray files outside plugin-owned paths unless the user explicitly requested that behavior.
 
 ### Lifecycle Synchronization
 | Action | Backend Extension | Frontend Lifecycle |

README.md

@@ -51,7 +51,7 @@ Or see DeepWiki generated documentation:
 
 Click to open a video to learn how to install Agent Zero:
 
-[![Easy Installation guide](/docs/res/easy_ins_vid.png)](https://www.youtube.com/watch?v=w5v5Kjx51hs)
+[![Easy Installation guide](/docs/res/install_guide.png)](https://www.youtube.com/watch?v=2-qFNUvqrXA)
 
 A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/setup/installation.md).
 

api/plugins.py

@@ -284,9 +284,9 @@ def _run_init_script(self, input: dict) -> dict | Response:
         if not plugin_dir:
             return Response(status=404, response="Plugin not found")
 
-        init_script = files.get_abs_path(plugin_dir, "initialize.py")
+        init_script = files.get_abs_path(plugin_dir, "execute.py")
         if not files.exists(init_script):
-            return Response(status=404, response="initialize.py not found")
+            return Response(status=404, response="execute.py not found")
 
         executed_at = datetime.now(timezone.utc).isoformat()
         try:

docs/README.md

@@ -70,6 +70,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
 - [User Guides](#user-guides)
   - [Usage Guide](guides/usage.md)
     - [Basic Operations](guides/usage.md#basic-operations)
+    - [Plugins and Marketplace](guides/usage.md#plugins-and-marketplace)
     - [Tool Usage](guides/usage.md#tool-usage)
     - [Projects](guides/usage.md#projects)
       - [What Projects Provide](guides/usage.md#what-projects-provide)

docs/agents/AGENTS.plugins.md

@@ -24,7 +24,7 @@ Each plugin lives in usr/plugins/<plugin_name>/.
 ```text
 usr/plugins/<plugin_name>/
 ├── plugin.yaml                   # Required: Title, version, settings + activation metadata
-├── initialize.py                 # Optional: one-time setup script (dependencies, models, etc.)
+├── execute.py                    # Optional: user-triggered plugin script
 ├── hooks.py                      # Optional: runtime hook functions callable by the framework
 ├── default_config.yaml           # Optional: fallback settings defaults
 ├── README.md                     # Optional: shown in Plugin List UI
@@ -44,11 +44,42 @@ usr/plugins/<plugin_name>/
     └── ...                       # Full plugin pages/components
 ```
 
+### Python import rule for user plugins
+
+For plugin-local Python code in `usr/plugins/<plugin_name>/`, import through the
+fully qualified `usr.plugins.<plugin_name>...` package path.
+
+Good (DO):
+
+```python
+from usr.plugins.my_plugin.helpers.runtime import do_work
+import usr.plugins.my_plugin.helpers.state as state
+```
+
+Avoid (DON'T):
+
+```python
+# sys.path hacks
+sys.path.insert(0, ...)
+from helpers.runtime import do_work
+
+# persistent symlink-based imports
+from plugins.my_plugin.helpers.runtime import do_work
+```
+
+Why:
+
+- `usr.plugins...` works without renaming `helpers/`
+- it avoids `sys.path` mutation for plugin-local imports
+- it avoids installation-time symlinks into `/a0/plugins/`
+- it keeps plugin removal reversible, with no import wiring left behind
+
 ### plugin.yaml (runtime manifest)
 
-This is the manifest file that lives inside your plugin directory and drives runtime behavior. It is distinct from the index manifest used when publishing to the Plugin Index (see Section 7).
+This is the manifest file that lives inside your plugin directory and drives runtime behavior. It is distinct from the index manifest (`index.yaml`) used when publishing to the Plugin Index (see Section 7).
 
 ```yaml
+name: my_plugin              # required for community plugins (^[a-z0-9_]+$, must match dir name)
 title: My Plugin
 description: What this plugin does.
 version: 1.0.0
@@ -61,6 +92,7 @@ always_enabled: false
 ```
 
 Field reference:
+- `name`: Plugin identifier. Required by CI when submitting to the Plugin Index. Must be `^[a-z0-9_]+$` and match the index folder name exactly.
 - `title`: UI display name
 - `description`: Short plugin summary
 - `version`: Plugin version string
@@ -69,6 +101,16 @@ Field reference:
 - `per_agent_config`: Enables agent-profile-scoped settings and toggle rules
 - `always_enabled`: Forces ON and disables toggle controls in the UI (reserved for framework use)
 
+### execute.py (plugin script)
+
+Plugins can include an optional `execute.py` file at the plugin root for user-triggered work such as setup, post-install steps, maintenance, migrations, repair flows, or resource refreshes. It is started manually from the Plugins UI, never automatically, and should print progress while returning `0` on success.
+
+Design guidance:
+- use `execute.py` for manual operations the user may need to run again later
+- prefer making it rerunnable or state-aware
+- avoid placing framework-internal automatic behavior here; that belongs in `hooks.py` or lifecycle extensions
+- do not make permanent system modifications that remain after plugin deletion unless the user explicitly asked for them and the plugin also provides a clear cleanup path
+
 ### hooks.py (framework runtime hooks)
 
 Plugins can include an optional `hooks.py` file at the plugin root. Agent Zero loads this module on demand and calls exported functions by name through `helpers.plugins.call_plugin_hook(...)`.
@@ -77,6 +119,7 @@ Plugins can include an optional `hooks.py` file at the plugin root. Agent Zero l
 - Use it for framework-internal operations such as install-time setup, plugin registration work, filesystem preparation, cache updates, or other tasks that need access to Agent Zero internals.
 - Hook functions may be synchronous or async. Async hooks are awaited by the framework.
 - Hook modules are cached until plugin caches are cleared, so changes may require a plugin refresh/reload cycle.
+- Plugin hooks should be cleanup-safe. A plugin should not leave behind permanent system modifications, symlinks, files outside its owned paths, or background services that survive plugin removal unless that behavior is explicitly part of the user-facing contract.
 
 Current example: the plugin installer calls `install()` from `hooks.py` after a plugin is copied into place.
 
@@ -191,12 +234,13 @@ embedding:
 
 The **Plugin Index** is a community-maintained repository at https://github.com/agent0ai/a0-plugins that lists plugins available to the Agent Zero community. Plugins listed there can be discovered and installed by other users.
 
-### Two Distinct plugin.yaml Files
+### Two Distinct Manifest Files
 
-There are two completely different `plugin.yaml` schemas used at different stages. They must not be confused:
+There are two completely different manifest files used at different stages. They must not be confused:
 
-**Runtime manifest** (inside your plugin repo/directory, drives Agent Zero behavior):
+**Runtime manifest** (`plugin.yaml`, inside your plugin repo/directory — drives Agent Zero behavior):
 ```yaml
+name: my_plugin              # REQUIRED for index submission; must match index folder name
 title: My Plugin
 description: What this plugin does.
 version: 1.0.0
@@ -207,17 +251,19 @@ per_agent_config: false
 always_enabled: false
 ```
 
-**Index manifest** (submitted to the `a0-plugins` repo under `plugins/<your-plugin-name>/`, drives discoverability only):
+**Index manifest** (`index.yaml`, submitted to the `a0-plugins` repo under `plugins/<your_plugin_name>/` — drives discoverability only):
 ```yaml
 title: My Plugin
 description: What this plugin does.
 github: https://github.com/yourname/your-plugin-repo
 tags:
   - tools
   - example
+screenshots:                    # optional, up to 5 full image URLs
+  - https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png
 ```
 
-The index manifest contains only four fields (`title`, `description`, `github`, `tags`) and must not include runtime fields. The `github` field must point to the root of a GitHub repository that itself contains a runtime `plugin.yaml` at the repository root.
+The index manifest is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` field must point to the root of a GitHub repository that contains a runtime `plugin.yaml` at the repository root, and that `plugin.yaml` must include a `name` field matching the index folder name exactly.
 
 ### Repository Structure for Community Plugins
 
@@ -239,23 +285,31 @@ Users install it locally by cloning (or downloading) the repo contents into `/a0
 
 ### Submitting to the Plugin Index
 
-1. Create a GitHub repository for your plugin with the runtime `plugin.yaml` at the repo root.
+1. Create a GitHub repository for your plugin with the runtime `plugin.yaml` (including the `name` field) at the repo root.
 2. Fork `https://github.com/agent0ai/a0-plugins`.
-3. Create a folder `plugins/<your-plugin-name>/` containing only an index `plugin.yaml` (and optionally a square thumbnail image ≤ 20 KB).
+3. Create a folder `plugins/<your_plugin_name>/` containing only an `index.yaml` (and optionally a square thumbnail image ≤ 20 KB).
 4. Open a Pull Request with exactly one new plugin folder.
 5. CI validates the submission automatically. A maintainer reviews and merges.
 
 Index submission rules:
 - One plugin per PR
-- Folder name must be unique, stable, lowercase, kebab-case
+- Folder name: unique, stable, `^[a-z0-9_]+$` (lowercase, numbers, underscores — no hyphens)
+- Folder name must exactly match the `name` field in your remote `plugin.yaml`
 - Folders starting with `_` are reserved for internal use
-- `github` must point to a public repo that contains `plugin.yaml` at its root
+- `github` must point to a public repo that contains `plugin.yaml` at its root with a matching `name` field
 - `title` max 50 characters, `description` max 500 characters
+- `index.yaml` total max 2000 characters
 - `tags`: optional, up to 5, use recommended tags from https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
+- `screenshots`: optional, up to 5 full image URLs (png/jpg/webp, each ≤ 2 MB)
+
+### Plugin Marketplace
+
+The marketplace is provided by the always-enabled `_plugin_installer` plugin. Users can reach it from the **Plugins** dialog in two ways:
 
-### Plugin Marketplace (Coming Soon)
+- the **Browse** tab in `webui/components/plugins/list/plugin-list.html`
+- the **Install** toolbar action injected by `plugins/_plugin_installer/extensions/webui/plugins-list-header-buttons/install-buttons.html`, which opens `plugins/_plugin_installer/webui/main.html` on its own **Browse** tab
 
-A built-in **Plugin Marketplace** plugin (always active) will allow users to browse the Plugin Index and install or update community plugins directly from the Agent Zero UI. This section will be updated once the marketplace plugin is released.
+Both routes surface Plugin Index entries inside Agent Zero. The marketplace supports search, filtering, sorting, and a detail view with README content and installation actions.
 
 ---
 

docs/developer/architecture.md

@@ -65,7 +65,7 @@ This architecture ensures:
 | `usr/secrets.env` | Secrets store (managed via Settings -> Secrets) |
 | `conf/model_providers.yaml` | Model provider defaults and settings |
 | `agent.py` | Core agent implementation |
-| `initialize.py` | Framework initialization |
+| `execute.py` | Framework initialization |
 | `models.py` | Model providers and configs |
 | `preload.py` | Pre-initialization routines |
 | `prepare.py` | Environment preparation |