@samitouri / QOSami_Agents_Zero-2 / commits / 175baa49

Add AGENTS.md DOX files and migrate docs

Introduce DOX (AGENTS.md) contracts across the repository to formalize ownership and local work contracts: adds .github/AGENTS.md plus AGENTS.md files for agents, api, conf, docker, docs, extensions, helpers, knowledge, lib, plugins, prompts, scripts, skills, tests, tools, usr, webui (and several subfolders). Update root AGENTS.md (content and last-updated date) to include DOX framework guidance and a child DOX index. Update .gitignore to allow usr/ and usr/plugins AGENTS.md files. Remove legacy deep-dive files under docs/agents (banners, components, modals, plugins) and migrate frontend/plugin references to webui/ and plugins/ DOX locations. Also adjust plugins/README.md and several skills/*/SKILL.md files to align with the new DOX layout.

frdel committed Jun 1, 2026 at 13:55 UTC 175baa49db36ea102e426fa69e78bd0cae1c45b9
35 files changed +999 -1422
.github/AGENTS.md new
+35
@@ -0,0 +1,35 @@
1 +# GitHub Automation DOX
2 +
3 +## Purpose
4 +
5 +- Own repository automation that runs on GitHub, including workflows and release-planning scripts.
6 +- Keep CI, Docker publishing, stale issue handling, and release-note generation aligned with repository release rules.
7 +
8 +## Ownership
9 +
10 +- `workflows/` contains GitHub Actions workflow definitions.
11 +- `scripts/` contains Python helpers called by workflows.
12 +- Root-level release rules remain in the root `AGENTS.md`; this file owns automation-specific details.
13 +
14 +## Local Contracts
15 +
16 +- Docker publishing lives in `workflows/docker-publish.yml` and delegates planning to `scripts/docker_release_plan.py`.
17 +- Releasable tags are `vX.Y` tags at or above `v1.0`, matching the workflow environment.
18 +- Release-note generation reads `scripts/openrouter_release_notes_system_prompt.md` from the repository root and requires OpenRouter credentials from workflow environment variables.
19 +- Keep workflow secrets in GitHub Actions secrets or environment variables. Do not commit credentials, tokens, or generated release bodies containing private data.
20 +- Workflow scripts must fail loudly with actionable messages when required environment variables or git refs are missing.
21 +
22 +## Work Guidance
23 +
24 +- Prefer deterministic, testable Python for workflow planning logic instead of complex inline shell in YAML.
25 +- Preserve manual dispatch behavior when changing Docker publishing.
26 +- Keep branch, tag, and release behavior synchronized between workflow YAML, release scripts, tests, and root documentation.
27 +
28 +## Verification
29 +
30 +- Run `pytest tests/test_docker_release_plan.py` after changing Docker publish planning or release workflow behavior.
31 +- Run targeted tests for any changed script that already has coverage.
32 +
33 +## Child DOX Index
34 +
35 +No child DOX files.
AGENTS.md
+124 -5
@@ -7,7 +7,7 @@ Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)
7 Dev Server: python run_ui.py (runs on http://localhost:50001 by default)
8 Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)
9 Documentation: README.md | docs/
10 -Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](docs/agents/AGENTS.plugins.md) | [Banners & Discovery](docs/agents/AGENTS.banners.md)
10 +Frontend & Plugin DOX: [WebUI](webui/AGENTS.md) | [Components](webui/components/AGENTS.md) | [Frontend JS](webui/js/AGENTS.md) | [Plugins](plugins/AGENTS.md)
11
12 ---
13
@@ -103,9 +103,9 @@ Key Files:
103 - helpers/api.py: Base class for all API endpoints.
104 - scripts/openrouter_release_notes_system_prompt.md: Editable system prompt used to generate GitHub release notes during Docker publishing.
105 - 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.
106 -- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.
107 -- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.
108 -- docs/agents/AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
106 +- webui/components/AGENTS.md: DOX contract for Alpine component architecture.
107 +- webui/js/AGENTS.md: DOX contract for frontend infrastructure, modal stack, API helpers, and extension loading.
108 +- plugins/AGENTS.md: DOX contract for bundled and custom plugin architecture; `usr/plugins/` remains ignored user state.
109
110 ---
111
@@ -249,5 +249,124 @@ pip install -r requirements2.txt
249
250 ---
251
252 -*Last updated: 2026-03-25*
252 +*Last updated: 2026-06-01*
253 *Maintained by: Agent Zero Core Team*
254 +
255 +
256 +# DOX framework
257 +
258 +- DOX is highly performant AGENTS.md hierarchy installed here
259 +- Agent must follow DOX instructions across any edits
260 +
261 +## Core Contract
262 +
263 +- AGENTS.md files are binding work contracts for their subtrees
264 +- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it
265 +
266 +## Read Before Editing
267 +
268 +1. Read the root AGENTS.md
269 +2. Identify every file or folder you expect to touch
270 +3. Walk from the repository root to each target path
271 +4. Read every AGENTS.md found along each route
272 +5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
273 +6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
274 +7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX
275 +
276 +Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.
277 +
278 +## Update After Editing
279 +
280 +Every meaningful change requires a DOX pass before the task is done.
281 +
282 +Update the closest owning AGENTS.md when a change affects:
283 +
284 +- purpose, scope, ownership, or responsibilities
285 +- durable structure, contracts, workflows, or operating rules
286 +- required inputs, outputs, permissions, constraints, side effects, or artifacts
287 +- user preferences about behavior, communication, process, organization, or quality
288 +- AGENTS.md creation, deletion, move, rename, or index contents
289 +
290 +Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.
291 +
292 +Do not create or update DOX docs for changes confined to ignored runtime or user-state folders under `usr/` or `tmp/` unless the user explicitly asks for those folders to be documented.
293 +
294 +## Hierarchy
295 +
296 +- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
297 +- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
298 +- Each parent explains what its direct children cover and what stays owned by the parent
299 +- The closer a doc is to the work, the more specific and practical it must be
300 +
301 +## Child Doc Shape
302 +
303 +- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
304 +- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
305 +- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists
306 +
307 +Default section order:
308 +- Purpose
309 +- Ownership
310 +- Local Contracts
311 +- Work Guidance
312 +- Verification
313 +- Child DOX Index
314 +
315 +## Style
316 +
317 +- Keep docs concise, current, and operational
318 +- Document stable contracts, not diary entries
319 +- Put broad rules in parent docs and concrete details in child docs
320 +- Prefer direct bullets with explicit names
321 +- Do not duplicate rules across many files unless each scope needs a local version
322 +- Delete stale notes instead of explaining history
323 +- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist
324 +
325 +## Closeout
326 +
327 +1. Re-check changed paths against the DOX chain
328 +2. Update nearest owning docs and any affected parents or children
329 +3. Refresh every affected Child DOX Index
330 +4. Remove stale or contradictory text
331 +5. Run existing verification when relevant
332 +6. Report any docs intentionally left unchanged and why
333 +
334 +## User Preferences
335 +
336 +- Do not document changes in `usr/` or `tmp/`; treat both as ignored runtime/user-state folders unless explicitly requested otherwise.
337 +
338 +## Child DOX Index
339 +
340 +Direct child DOX files:
341 +
342 +| Child | Scope |
343 +| --- | --- |
344 +| [.github/AGENTS.md](.github/AGENTS.md) | GitHub Actions workflows and release automation scripts. |
345 +| [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and profile-local tools. |
346 +| [api/AGENTS.md](api/AGENTS.md) | HTTP API handlers and WebSocket handler entry points. |
347 +| [conf/AGENTS.md](conf/AGENTS.md) | Repository-shipped configuration defaults and templates. |
348 +| [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, image definitions, and runtime compose files. |
349 +| [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation, developer guides, screenshots, and agent deep dives. |
350 +| [extensions/AGENTS.md](extensions/AGENTS.md) | Core lifecycle extension hook implementations for backend and WebUI surfaces. |
351 +| [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend framework utilities and cross-cutting runtime services. |
352 +| [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge and indexed reference material. |
353 +| [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helper scripts outside the main WebUI bundle. |
354 +| [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins shipped with the framework. |
355 +| [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates loaded by agents and framework workflows. |
356 +| [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts invoked by automation or maintainers. |
357 +| [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills and their agent-facing instructions. |
358 +| [tests/AGENTS.md](tests/AGENTS.md) | Pytest regression and contract tests. |
359 +| [tools/AGENTS.md](tools/AGENTS.md) | Core agent tool implementations. |
360 +| [webui/AGENTS.md](webui/AGENTS.md) | Flask-served Alpine.js WebUI shell, frontend modules, components, CSS, assets, and vendor libraries. |
361 +
362 +Intentionally unindexed local or generated roots:
363 +
364 +| Path | Reason |
365 +| --- | --- |
366 +| `.conda/`, `.venv/` | Local Python environments. |
367 +| `.pytest_cache/`, `__pycache__/` | Generated test and bytecode caches. |
368 +| `.vscode/`, `.windsurf/` | Editor-local configuration and assistant metadata. |
369 +| `logs/` | Runtime output. |
370 +| `tmp/` | Ignored runtime caches, uploads, and generated working files; do not document changes here unless explicitly requested. |
371 +| `usr/` | Ignored local user data, settings, plugins, uploads, chats, and workdirs; do not document changes here unless explicitly requested. |
372 +| `python/` | Generated or legacy runtime cache mirror; current source lives in root-level `api/`, `helpers/`, `tools/`, and `extensions/`. |
agents/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Agent Profiles DOX
2 +
3 +## Purpose
4 +
5 +- Own bundled agent profiles, profile-specific prompts, and profile-local tools.
6 +- Keep profile behavior understandable without requiring edits to core framework prompts.
7 +
8 +## Ownership
9 +
10 +- Each direct profile directory owns its `agent.yaml`, optional `prompts/`, optional `tools/`, and optional `extensions/`.
11 +- `_example/` demonstrates profile layout and should stay suitable as a reference.
12 +- User-created local profiles belong under `usr/agents/`, not here, unless they are intended to ship with the product.
13 +
14 +## Local Contracts
15 +
16 +- `agent.yaml` is the profile entry point and must stay valid YAML.
17 +- Profile prompt overrides should be narrow and named to match the core prompt they extend or replace.
18 +- Profile-local tools must follow the same `Tool` contract as root `tools/`.
19 +- Do not put secrets, provider API keys, local paths, or user-specific settings in bundled profiles.
20 +
21 +## Work Guidance
22 +
23 +- Prefer small profile-specific prompt files over duplicating large core prompts.
24 +- Keep examples generic and runnable in a clean checkout.
25 +- When changing profile behavior, check how the WebUI profile picker and backend profile loader discover profiles.
26 +
27 +## Verification
28 +
29 +- Run `pytest` or targeted tests covering profile loading when changing `agent.yaml` structure or profile discovery.
30 +- Manually inspect YAML validity for changed profiles if no targeted test exists.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
api/AGENTS.md new
+36
@@ -0,0 +1,36 @@
1 +# API Handlers DOX
2 +
3 +## Purpose
4 +
5 +- Own backend HTTP API handlers and WebSocket handler entry points.
6 +- Keep route-level behavior, authentication, CSRF, input parsing, and response shapes explicit.
7 +
8 +## Ownership
9 +
10 +- Files in this directory are discovered by the route registration layer in `helpers/api.py` and WebSocket registration code.
11 +- `ws_*.py` files define WebSocket namespaces or handlers through `helpers.ws.WsHandler`.
12 +- Plugin-provided API handlers belong inside plugin `api/` folders and follow the same base contracts.
13 +
14 +## Local Contracts
15 +
16 +- HTTP handlers must derive from `helpers.api.ApiHandler`.
17 +- Implement `async def process(self, input: dict, request: Request) -> dict | Response`.
18 +- Override `get_methods()`, `requires_auth()`, `requires_csrf()`, `requires_api_key()`, or `requires_loopback()` only when the endpoint contract requires it.
19 +- Keep CSRF and authentication protections intact for browser-facing state-changing endpoints.
20 +- WebSocket handlers must derive from `helpers.ws.WsHandler` and validate event data before using it.
21 +- Do not return secrets, raw environment values, private files, or unfiltered exception details to clients.
22 +
23 +## Work Guidance
24 +
25 +- Use helpers for shared behavior instead of duplicating persistence, auth, file, project, plugin, or notification logic in endpoints.
26 +- Keep request and response payloads stable; update frontend callers and tests together when payloads change.
27 +- Prefer `Response` for files, redirects, status codes, and plain-text errors; return dictionaries for JSON success payloads.
28 +
29 +## Verification
30 +
31 +- Run targeted `pytest tests/test_*api*.py`, endpoint-specific tests, or WebSocket tests after changing handler behavior.
32 +- For auth, CSRF, upload/download, tunnel, or file endpoints, run the nearest security regression tests.
33 +
34 +## Child DOX Index
35 +
36 +No child DOX files.
conf/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Configuration Defaults DOX
2 +
3 +## Purpose
4 +
5 +- Own repository-shipped configuration defaults and templates.
6 +- Keep clean-checkout defaults safe, portable, and free of user-specific state.
7 +
8 +## Ownership
9 +
10 +- `model_providers.yaml` defines built-in provider metadata and LiteLLM wiring defaults.
11 +- `*.default.gitignore` files define templates copied or used for generated user/project/workdir directories.
12 +- Runtime user settings belong under ignored `usr/` local state and are not documented with local DOX files.
13 +
14 +## Local Contracts
15 +
16 +- Do not commit API keys, provider secrets, local account identifiers, or private endpoints.
17 +- Keep provider IDs and settings keys stable unless all loaders, UI references, migrations, and tests are updated.
18 +- Defaults must work in a clean checkout and in Docker.
19 +- Templates must avoid accidentally unignoring private runtime content.
20 +
21 +## Work Guidance
22 +
23 +- Prefer adding provider metadata here only when it is broadly useful to shipped Agent Zero.
24 +- Keep comments concise and operational.
25 +- Coordinate provider changes with model settings UI, plugin model overrides, and docs.
26 +
27 +## Verification
28 +
29 +- Run targeted model/provider tests after changing `model_providers.yaml`.
30 +- Check generated ignore templates manually when changing `*.default.gitignore`.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
docker/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Docker DOX
2 +
3 +## Purpose
4 +
5 +- Own Docker build contexts and runtime container definitions.
6 +- Keep framework runtime, agent execution runtime, exposed ports, mounted paths, and image build assumptions explicit.
7 +
8 +## Ownership
9 +
10 +- `base/` owns the base image context.
11 +- `run/` owns the runnable image context and compose file.
12 +- Root `DockerfileLocal` is owned by the root contract but must stay compatible with this directory.
13 +
14 +## Local Contracts
15 +
16 +- Preserve the two-runtime model documented in the root contract: framework runtime under `/opt/venv-a0` and agent execution runtime under `/opt/venv`.
17 +- Do not bake secrets, local `.env` values, or user data into images.
18 +- Keep compose mounts aligned with `usr/`, `logs/`, and other runtime-state expectations.
19 +- Image changes that affect GitHub publishing must stay synchronized with `.github/workflows/docker-publish.yml`.
20 +
21 +## Work Guidance
22 +
23 +- Keep Dockerfile steps cache-friendly and explicit about which runtime they target.
24 +- Avoid broad copies of ignored runtime folders.
25 +- Update setup docs when ports, volumes, startup commands, or runtime layout change.
26 +
27 +## Verification
28 +
29 +- Build the affected Docker context when Docker behavior changes.
30 +- Run Docker-related tests or startup smoke checks when changing runtime entrypoints.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
docs/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Documentation DOX
2 +
3 +## Purpose
4 +
5 +- Own human-facing documentation, screenshots, setup guides, developer guides, and documentation assets.
6 +- Keep docs accurate to current source behavior and practical user workflows.
7 +
8 +## Ownership
9 +
10 +- `README.md`, `quickstart.md`, `guides/`, and `setup/` cover user-facing setup and workflows.
11 +- `developer/` covers compact developer references and source handoffs.
12 +- `res/` contains documentation images and other documentation assets.
13 +
14 +## Local Contracts
15 +
16 +- Prefer local docs for practical workflows and direct users to DeepWiki for source-linked internals when appropriate.
17 +- Do not document secrets, private deployment details, unreleased credentials, or user-specific runtime state.
18 +- Screenshots and assets must be relevant to the documented UI state and should be updated when UI changes make them misleading.
19 +- Keep links relative inside the docs tree unless they intentionally point to external community or reference resources.
20 +
21 +## Work Guidance
22 +
23 +- Update docs in the same change when user-visible behavior, setup steps, settings names, plugin workflows, or UI labels change.
24 +- Keep user guides task-oriented and avoid duplicating architecture contracts already owned by source-adjacent DOX files.
25 +- When editing screenshots or binary assets, avoid unrelated metadata churn.
26 +
27 +## Verification
28 +
29 +- Check changed internal links manually or with an available link checker.
30 +- For setup or Docker docs, verify commands against current scripts and Docker files.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
docs/agents/AGENTS.banners.md deleted
-95
@@ -1,95 +0,0 @@
1 -# Creating Discovery Cards and Banners
2 -
3 -Agent Zero allows plugin developers to surface UI elements using the `banners` extension point. This allows your plugin to present information, prompts, or actionable "discovery cards" directly on the Welcome Screen without needing to inject arbitrary HTML into the frontend.
4 -
5 -## The `banners` Extension Point
6 -
7 -Banners are collected on the backend and sent to the frontend UI as an array of dictionaries. By appending to the `banners` array inside a Python extension, you can easily surface your plugin to the user.
8 -
9 -To inject a banner, you create a Python extension script hooking into `banners`.
10 -
11 -### Where to put your extension script
12 -
13 -Create a python file in your plugin's extensions folder:
14 -`plugins/<your_plugin>/extensions/python/banners/10_my_plugin_banner.py`
15 -
16 -*(Note: the `10_` prefix is for ordering; extensions run in alphabetical order).*
17 -
18 -## Banner Types
19 -
20 -The UI distinguishes banners primarily by the `type` property.
21 -
22 -### 1. Alert Banners (`info`, `warning`, `error`)
23 -These are standard top-level alerts displayed on the welcome screen.
24 -
25 -```python
26 -banners.append({
27 - "id": "my-plugin-warning",
28 - "type": "warning",
29 - "priority": 90,
30 - "title": "My Plugin Issue",
31 - "html": "<strong>Action required:</strong> Please configure your settings.",
32 - "dismissible": True,
33 -})
34 -```
35 -
36 -### 2. Discovery Cards (`hero`, `feature`)
37 -These are rich, interactive cards displayed in the Discovery section. They are designed to prompt the user to try new plugins or features.
38 -
39 -* `hero`: A wide, prominent card. Usually reserved for core system features (e.g., the Plugin Hub).
40 -* `feature`: A smaller card in a grid layout. This is the **recommended type** for plugin contributors to showcase their plugin.
41 -
42 -### Anatomy of a Discovery Card
43 -
44 -Here is an example of injecting a `feature` card for a custom plugin:
45 -
46 -```python
47 -from helpers.extension import Extension
48 -from helpers import plugins
49 -
50 -class MyPluginDiscoveryCard(Extension):
51 - """Injects a discovery card for My Custom Plugin."""
52 -
53 - async def execute(self, banners: list = [], frontend_context: dict = {}, **kwargs):
54 - # 1. Condition Check
55 - # Only show the discovery card if the user hasn't configured the plugin yet.
56 - config = plugins.get_plugin_config("my_custom_plugin") or {}
57 -
58 - # If the API key is already set, we don't need to advertise the setup!
59 - if config.get("api_key"):
60 - return
61 -
62 - # 2. Add the Card
63 - banners.append({
64 - "id": "discovery-my-custom-plugin",
65 - "type": "feature", # 'feature' or 'hero'
66 - "title": "Connect My Service", # Card title
67 - "description": "Unlock amazing capabilities by linking your account.",
68 -
69 - # Visuals (use either thumbnail OR icon)
70 - "thumbnail": "/plugins/my_custom_plugin/assets/thumb.png", # Path to image
71 - "icon": "bolt", # Or a Material Symbol icon name
72 -
73 - # Call To Action (CTA)
74 - "cta_text": "Setup Now",
75 - "cta_action": "open-plugin-config:my_custom_plugin", # Opens your plugin's config modal
76 -
77 - # Behavior
78 - "dismissible": True, # Let the user hide it
79 - "priority": 40, # Higher numbers appear first
80 - })
81 -```
82 -
83 -## Call To Action (CTA) Actions
84 -
85 -When a user clicks the button on a discovery card, the `cta_action` string determines what happens. The frontend currently supports the following actions:
86 -
87 -* `open-plugin-config:<plugin_folder_name>`: Automatically opens the settings modal for the specified plugin. (e.g., `open-plugin-config:_telegram_integration`).
88 -* `open-plugin-hub`: Opens the main Plugin Hub UI.
89 -* `open-url:<url>`: Opens a web link in a new browser tab. (e.g., `open-url:https://example.com/docs`).
90 -
91 -## Best Practices
92 -
93 -1. **Check Configuration First**: Always check your plugin's configuration before injecting a card. If the user has already set up your plugin, they shouldn't keep seeing a discovery card asking them to set it up.
94 -2. **Unique IDs**: Ensure your banner `id` is highly unique (e.g., prefix it with your plugin name) to avoid collisions with other plugins.
95 -3. **Use `feature` type**: Community plugins should stick to the `feature` type rather than `hero` to ensure a clean grid layout for users.
\ No newline at end of file
docs/agents/AGENTS.components.md deleted
-648
@@ -1,648 +0,0 @@
1 -# Agent Zero Component System
2 -
3 -> Generated from codebase reconnaissance on 2026-01-10
4 -> Scope: `webui/components/` - Self-contained Alpine.js component architecture
5 -
6 -## Quick Reference
7 -
8 -| Aspect | Value |
9 -|--------|-------|
10 -| Tech Stack | Alpine.js, ES Modules, CSS Variables |
11 -| Component Tag | `<x-component path="...">` |
12 -| State Management | `createStore(name, model)` from `/js/AlpineStore.js` |
13 -| Modals | `openModal(path)` / `closeModal()` from `/js/modals.js` |
14 -| API Layer | `callJsonApi()` / `fetchApi()` from `/js/api.js` |
15 -
16 ----
17 -
18 -## Table of Contents
19 -
20 -1. [Architecture Overview](#1-architecture-overview)
21 -2. [Component Structure](#2-component-structure)
22 -3. [Store Pattern](#3-store-pattern)
23 -4. [Lifecycle Management](#4-lifecycle-management)
24 -5. [Integration Layer](#5-integration-layer)
25 -6. [Alpine.js Directives](#6-alpinejs-directives)
26 -7. [Patterns and Conventions](#7-patterns-and-conventions)
27 -8. [Pitfalls and Anti-Patterns](#8-pitfalls-and-anti-patterns)
28 -9. [Porting Guide](#9-porting-guide)
29 -
30 ----
31 -
32 -## 1. Architecture Overview
33 -
34 -### Core Files (Integration Layer)
35 -
36 -| File | Purpose |
37 -|------|---------|
38 -| `/js/components.js` | Component loader - hydrates `<x-component>` tags |
39 -| `/js/AlpineStore.js` | Store factory with Alpine proxy |
40 -| `/js/modals.js` | Modal stack management |
41 -| `/js/initFw.js` | Bootstrap: loads Alpine, registers custom directives |
42 -| `/js/api.js` | CSRF-protected API client (`callJsonApi`, `fetchApi`) |
43 -
44 -### Component Resolution
45 -
46 -```
47 -<x-component path="sidebar/left-sidebar.html">
48 - ↓
49 - Resolves to: components/sidebar/left-sidebar.html
50 - ↓
51 - Loader: importComponent() fetches, parses, injects
52 -```
53 -
54 -- Path auto-prefixes `components/` if not present
55 -- Component HTML cached after first fetch
56 -- Module scripts cached by virtual URL
57 -- MutationObserver auto-loads dynamically inserted components
58 -
59 -### Data Flow
60 -
61 -```
62 -Component HTML
63 - ↓
64 -imports Store module
65 - ↓
66 -createStore() registers with Alpine
67 - ↓
68 -Template binds via $store.name
69 - ↓
70 -User actions → store methods → state updates → reactive UI
71 -```
72 -
73 ----
74 -
75 -## 2. Component Structure
76 -
77 -### Anatomy of a Component
78 -
79 -```html
80 -<html>
81 -<head>
82 - <!-- Module imports MUST be in <head> -->
83 - <script type="module">
84 - import { store } from "/components/feature/feature-store.js";
85 - </script>
86 -</head>
87 -
88 -<body>
89 - <!-- Store gate: prevents render until store registered -->
90 - <div x-data>
91 - <template x-if="$store.featureStore">
92 - <!-- Single root element inside template (mandatory) -->
93 - <div class="feature-container">
94 - <p x-text="$store.featureStore.value"></p>
95 - <button @click="$store.featureStore.action()">Do Thing</button>
96 - </div>
97 - </template>
98 - </div>
99 -
100 - <!-- Inline styles scoped to component -->
101 - <style>
102 - .feature-container {
103 - color: var(--color-text);
104 - }
105 - </style>
106 -</body>
107 -</html>
108 -```
109 -
110 -### Key Rules
111 -
112 -| Rule | Rationale |
113 -|------|-----------|
114 -| Scripts in `<head>`, content in `<body>` | Loader extracts separately |
115 -| Use `type="module"` for scripts | Enables ES imports, caching |
116 -| Wrap with `x-data` + `x-if="$store.X"` | Prevents render before store ready |
117 -| `<template>` has ONE root element | Alpine limitation |
118 -| Styles inline in component | Self-contained, no global CSS files |
119 -
120 -### Nesting Components
121 -
122 -```html
123 -<div class="parent-container">
124 - <x-component path="child/child-component.html"></x-component>
125 -</div>
126 -```
127 -
128 -Components can nest other components. Loader recursively processes `x-component` tags.
129 -
130 ----
131 -
132 -## 3. Store Pattern
133 -
134 -### Creating a Store
135 -
136 -```javascript
137 -// /components/feature/feature-store.js
138 -import { createStore } from "/js/AlpineStore.js";
139 -
140 -const model = {
141 - // State
142 - items: [],
143 - loading: false,
144 - _initialized: false,
145 -
146 - // Lifecycle (called once by Alpine when store registers)
147 - init() {
148 - if (this._initialized) return;
149 - this._initialized = true;
150 - this.load();
151 - },
152 -
153 - // Actions
154 - async load() {
155 - this.loading = true;
156 - // ... fetch data
157 - this.loading = false;
158 - },
159 -
160 - // Computed-like getters (Alpine reactivity works)
161 - get itemCount() {
162 - return this.items.length;
163 - }
164 -};
165 -
166 -export const store = createStore("featureStore", model);
167 -```
168 -
169 -### Store Proxy Behavior
170 -
171 -`createStore()` returns a proxy that:
172 -- Before Alpine boots: reads/writes directly to `model` object
173 -- After Alpine boots: reads/writes through `Alpine.store(name)`
174 -
175 -This enables safe module-level initialization before Alpine loads.
176 -
177 -### Store Access
178 -
179 -| Context | Syntax |
180 -|---------|--------|
181 -| Template (Alpine) | `$store.featureStore.prop` |
182 -| Module import | `import { store } from "./feature-store.js"; store.prop` |
183 -| Global (avoid) | `Alpine.store("featureStore").prop` |
184 -
185 -Prefer module imports over global lookups.
186 -
187 -### Persistence Helpers
188 -
189 -```javascript
190 -import { saveState, loadState } from "/js/AlpineStore.js";
191 -
192 -// Save to localStorage (exclude functions automatically)
193 -const snapshot = saveState(store, [], ["transientField"]);
194 -localStorage.setItem("myStore", JSON.stringify(snapshot));
195 -
196 -// Restore
197 -const saved = JSON.parse(localStorage.getItem("myStore"));
198 -loadState(store, saved);
199 -```
200 -
201 ----
202 -
203 -## 4. Lifecycle Management
204 -
205 -### Custom Alpine Directives
206 -
207 -Registered in `/js/initFw.js`:
208 -
209 -| Directive | When Fires | Use Case |
210 -|-----------|------------|----------|
211 -| `x-create` | Once on mount | Initialize, subscribe to events |
212 -| `x-destroy` | On unmount/cleanup | Unsubscribe, clear timers |
213 -| `x-every-second` | Every 1s while mounted | Polling, countdowns |
214 -| `x-every-minute` | Every 60s while mounted | Low-frequency updates |
215 -| `x-every-hour` | Every 3600s while mounted | Rare periodic tasks |
216 -
217 -### Usage Pattern
218 -
219 -```html
220 -<div
221 - x-create="$store.myStore.onOpen()"
222 - x-destroy="$store.myStore.cleanup()"
223 ->
224 - <!-- content -->
225 -</div>
226 -```
227 -
228 -### Store Lifecycle Pattern
229 -
230 -```javascript
231 -const model = {
232 - _initialized: false,
233 - resizeHandler: null,
234 -
235 - init() {
236 - // Guard: runs only once per app lifetime
237 - if (this._initialized) return;
238 - this._initialized = true;
239 - // Global setup: event listeners, intervals
240 - this.resizeHandler = () => this.handleResize();
241 - window.addEventListener("resize", this.resizeHandler);
242 - },
243 -
244 - // Called via x-create when component mounts (can run multiple times)
245 - onOpen() {
246 - this.loadData();
247 - },
248 -
249 - // Called via x-destroy when component unmounts
250 - cleanup() {
251 - // Clear component-specific state, not global listeners
252 - },
253 -
254 - // For full teardown (rarely needed)
255 - destroy() {
256 - if (this.resizeHandler) {
257 - window.removeEventListener("resize", this.resizeHandler);
258 - this.resizeHandler = null;
259 - }
260 - this._initialized = false;
261 - }
262 -};
263 -```
264 -
265 -Key distinction:
266 -- `init()` → once per app load (store registration)
267 -- `onOpen()` → each time component mounts (modal opens, etc.)
268 -- `cleanup()`/`destroy()` → teardown resources
269 -
270 ----
271 -
272 -## 5. Integration Layer
273 -
274 -### API Calls
275 -
276 -```javascript
277 -import { callJsonApi, fetchApi } from "/js/api.js";
278 -
279 -// JSON POST with CSRF
280 -const result = await callJsonApi("/endpoint", { key: "value" });
281 -
282 -// Raw fetch with CSRF
283 -const response = await fetchApi("/endpoint", {
284 - method: "GET",
285 - headers: { "Accept": "application/json" }
286 -});
287 -```
288 -
289 -- `callJsonApi`: JSON-in, JSON-out, throws on non-2xx
290 -- `fetchApi`: Adds CSRF header, handles 403 retry, redirects to `/login`
291 -
292 -### Modals
293 -
294 -```javascript
295 -import { openModal, closeModal } from "/js/modals.js";
296 -
297 -// Open (returns Promise that resolves when modal closes)
298 -await openModal("feature/feature-modal.html");
299 -
300 -// Close topmost modal
301 -closeModal();
302 -
303 -// Close specific modal by path
304 -closeModal("feature/feature-modal.html");
305 -```
306 -
307 -Modal component receives title from `<title>` tag:
308 -```html
309 -<head>
310 - <title>My Modal Title</title>
311 -</head>
312 -```
313 -
314 -Modal footer (outside scroll area):
315 -```html
316 -<div data-modal-footer>
317 - <button @click="closeModal()">Close</button>
318 -</div>
319 -```
320 -
321 -### Attribute Inheritance
322 -
323 -Parent `x-component` attributes accessible via `globalThis.xAttrs(element)`:
324 -
325 -```html
326 -<!-- Parent -->
327 -<x-component path="child.html" mydata='{"id": 123}'></x-component>
328 -
329 -<!-- Child can access -->
330 -<script type="module">
331 - const attrs = globalThis.xAttrs(document.currentScript);
332 - console.log(attrs.mydata.id); // 123
333 -</script>
334 -```
335 -
336 ----
337 -
338 -## 6. Alpine.js Directives
339 -
340 -### Common Patterns
341 -
342 -| Pattern | Syntax |
343 -|---------|--------|
344 -| Reactive text | `x-text="$store.s.value"` |
345 -| Conditional render | `x-if="$store.s.condition"` |
346 -| Visibility toggle | `x-show="$store.s.visible"` |
347 -| Class binding | `:class="{'active': $store.s.isActive}"` |
348 -| Event handler | `@click="$store.s.action()"` |
349 -| Two-way bind | `x-model="$store.s.inputValue"` |
350 -| List iteration | `<template x-for="item in $store.s.items">` |
351 -| Init expression | `x-init="$store.s.load()"` |
352 -
353 -### Store Gating (Critical Pattern)
354 -
355 -```html
356 -<div x-data>
357 - <template x-if="$store.myStore">
358 - <!-- Renders only when store exists -->
359 - </template>
360 -</div>
361 -```
362 -
363 -Always gate components that depend on stores. Prevents errors during initial load race.
364 -
365 ----
366 -
367 -## 7. Patterns and Conventions
368 -
369 -### ✅ DO
370 -
371 -| Pattern | Example |
372 -|---------|---------|
373 -| Self-contained components | All HTML/CSS/JS in one component folder |
374 -| Module imports with absolute paths | `import { store } from "/components/..."` |
375 -| CSS variables for theming | `color: var(--color-text)` |
376 -| Guard `init()` with `_initialized` | Prevents duplicate setup |
377 -| Use `display: contents` for flex chains | Wrapper doesn't break parent flex |
378 -| Inline component styles | `<style>` in component `<body>` |
379 -| Import stores in `<head>` | Ensures registration before render |
380 -| Name stores uniquely | `createStore("featureStore", ...)` |
381 -
382 -### CSS Variable Theming
383 -
384 -```css
385 -.component {
386 - background: var(--color-panel);
387 - color: var(--color-text);
388 - border: 1px solid var(--color-border);
389 - padding: var(--spacing-md);
390 - transition: all var(--transition-speed) ease-in-out;
391 - font-size: var(--font-size-normal);
392 -}
393 -```
394 -
395 -### Flex Chain Preservation
396 -
397 -When `x-component` wrapper would break flex layout:
398 -
399 -```css
400 -#parent-container > x-component,
401 -#parent-container > x-component > div[x-data] {
402 - display: contents;
403 -}
404 -```
405 -
406 ----
407 -
408 -## 8. Pitfalls and Anti-Patterns
409 -
410 -### 🚫 DON'T
411 -
412 -| Anti-Pattern | Why | Fix |
413 -|--------------|-----|-----|
414 -| Global CSS files | Breaks encapsulation | Inline styles per component |
415 -| `window.Alpine.store()` lookups | Timing issues, coupling | Import store module directly |
416 -| Call `init()` from `x-init` | Runs multiple times | Use guard, or use `x-create` for per-mount |
417 -| Multiple roots in `<template>` | Alpine breaks | Wrap in single `<div>` |
418 -| `.catch(() => null)` for errors | Hides bugs | Let errors surface, use notifications |
419 -| Scripts outside `<head>` | May not load before template | Move to `<head>` with `type="module"` |
420 -| Hardcoded colors | Breaks theming | Use CSS variables |
421 -| Relative imports `./file.js` | Path resolution issues | Use absolute `/components/...` |
422 -
423 -### Common Mistakes
424 -
425 -Race condition: store not ready
426 -```html
427 -<!-- ❌ BAD: No gate -->
428 -<div x-data>
429 - <p x-text="$store.myStore.value"></p>
430 -</div>
431 -
432 -<!-- ✅ GOOD: Store gate -->
433 -<div x-data>
434 - <template x-if="$store.myStore">
435 - <p x-text="$store.myStore.value"></p>
436 - </template>
437 -</div>
438 -```
439 -
440 -Duplicate initialization
441 -```javascript
442 -// ❌ BAD: Runs every time store accessed
443 -init() {
444 - window.addEventListener("resize", this.handler);
445 -}
446 -
447 -// ✅ GOOD: Guard pattern
448 -init() {
449 - if (this._initialized) return;
450 - this._initialized = true;
451 - window.addEventListener("resize", this.handler);
452 -}
453 -```
454 -
455 -Leaking listeners
456 -```javascript
457 -// ❌ BAD: No cleanup
458 -init() {
459 - this.interval = setInterval(() => this.tick(), 1000);
460 -}
461 -
462 -// ✅ GOOD: With cleanup
463 -init() {
464 - this.interval = setInterval(() => this.tick(), 1000);
465 -},
466 -destroy() {
467 - clearInterval(this.interval);
468 -}
469 -```
470 -
471 ----
472 -
473 -## 9. Porting Guide
474 -
475 -### Minimum Requirements for External Apps
476 -
477 -1. Files to copy:
478 - ```
479 - /js/components.js # Component loader
480 - /js/AlpineStore.js # Store factory
481 - /js/modals.js # Modal system (optional)
482 - /js/initFw.js # Alpine bootstrap + directives
483 - ```
484 -
485 -2. Dependencies:
486 - - Alpine.js (vendor or CDN)
487 - - CSS variables (define your theme)
488 -
489 -3. Bootstrap sequence:
490 - ```javascript
491 - // initFw.js pattern:
492 - await import("path/to/alpine.min.js");
493 -
494 - // Register custom directives
495 - Alpine.directive("destroy", ...);
496 - Alpine.directive("create", ...);
497 - // etc.
498 - ```
499 -
500 -4. HTML entry point:
501 - ```html
502 - <script type="module" src="/js/initFw.js"></script>
503 - <x-component path="app/root.html"></x-component>
504 - ```
505 -
506 -### Adaptation Checklist
507 -
508 -- [ ] Define CSS variables for theming (`--color-*`, `--spacing-*`, etc.)
509 -- [ ] Set up component directory structure
510 -- [ ] Configure build tool to serve `/components/` path (or adjust loader)
511 -- [ ] Create API wrapper matching your backend (replace `api.js`)
512 -- [ ] Test MutationObserver behavior with your router/SPA framework
513 -- [ ] Verify module caching behavior in production build
514 -
515 -### Integration with Frameworks
516 -
517 -| Framework | Consideration |
518 -|-----------|--------------|
519 -| Vanilla/Static | Works directly, include initFw.js |
520 -| Electron | Works, may need CSP adjustments for Blob URLs |
521 -| React/Vue | Mount Alpine in specific container, avoid conflicts |
522 -| SPA Routers | MutationObserver handles dynamic inserts |
523 -
524 ----
525 -
526 -## Directory Structure Reference
527 -
528 -```
529 -webui/components/
530 -├── _examples/ # Reference implementations
531 -│ ├── _example-component.html
532 -│ └── _example-store.js
533 -├── chat/
534 -│ ├── input/
535 -│ │ ├── chat-bar.html
536 -│ │ └── input-store.js
537 -│ └── ...
538 -├── sidebar/
539 -│ ├── sidebar-store.js
540 -│ ├── left-sidebar.html
541 -│ └── chats/
542 -│ └── chats-list.html
543 -├── modals/
544 -│ └── file-browser/
545 -│ ├── file-browser.html
546 -│ └── file-browser-store.js
547 -├── notifications/
548 -│ ├── notification-store.js
549 -│ └── notification-toast-stack.html
550 -└── settings/
551 - └── ...
552 -```
553 -
554 -Naming conventions:
555 -- Components: `feature-name.html`
556 -- Stores: `feature-store.js` or `feature-name-store.js`
557 -- Modals: placed in `modals/` or feature folder
558 -
559 ----
560 -
561 -## Key Exports Summary
562 -
563 -### `/js/components.js`
564 -```javascript
565 -export async function importComponent(path, targetElement)
566 -export async function loadComponents(roots)
567 -export function getParentAttributes(el)
568 -// Global: globalThis.xAttrs
569 -```
570 -
571 -### `/js/AlpineStore.js`
572 -```javascript
573 -export function createStore(name, initialState)
574 -export function getStore(name)
575 -export function saveState(store, include, exclude)
576 -export function loadState(store, state, include, exclude)
577 -```
578 -
579 -### `/js/modals.js`
580 -```javascript
581 -export function openModal(modalPath)
582 -export function closeModal(modalPath?)
583 -export function scrollModal(id)
584 -// Globals: globalThis.openModal, closeModal, scrollModal
585 -```
586 -
587 -### `/js/api.js`
588 -```javascript
589 -export async function callJsonApi(endpoint, data)
590 -export async function fetchApi(url, request)
591 -```
592 -
593 ----
594 -
595 -## Addendum: Additional Patterns
596 -
597 -### Alpine Transitions
598 -
599 -Use `x-transition` for enter/leave animations:
600 -
601 -```html
602 -<div x-show="visible"
603 - x-transition:enter="fade-enter"
604 - x-transition:leave="fade-leave">
605 -```
606 -
607 -### Two-Click Confirmation (`$confirmClick`)
608 -
609 -Magic helper for destructive actions:
610 -
611 -```html
612 -<button @click="$confirmClick($event, () => $store.myStore.delete(item.id))">
613 - <span class="material-symbols-outlined">delete</span>
614 -</button>
615 -```
616 -
617 -First click arms (icon changes to checkmark), second click confirms. Auto-resets after 2s.
618 -
619 -### Device Detection
620 -
621 -Body receives `device-touch` or `device-mouse` class via `/js/initializer.js`. Use for input-type-specific styling:
622 -
623 -```css
624 -.device-touch .hover-only { display: none; }
625 -```
626 -
627 -### CSS Variables Reference
628 -
629 -Defined in `/webui/index.css`:
630 -
631 -| Variable | Purpose |
632 -|----------|---------|
633 -| `--color-background` | Page background |
634 -| `--color-text` | Primary text |
635 -| `--color-primary` | Headings, emphasis |
636 -| `--color-panel` | Card/sidebar backgrounds |
637 -| `--color-border` | Borders, dividers |
638 -| `--color-accent` | Highlights, actions |
639 -| `--color-input` | Form field backgrounds |
640 -| `--spacing-xs/sm/md/lg` | Consistent spacing scale |
641 -| `--font-size-small/normal/large` | Typography scale |
642 -| `--transition-speed` | Animation duration (0.3s) |
643 -
644 -Theme switching via `.light-mode` class on root element.
645 -
646 ----
647 -
648 -*End of Component System Documentation*
docs/agents/AGENTS.modals.md deleted
-325
@@ -1,325 +0,0 @@
1 -# Agent Zero — Frontend Modals (stacked `openModal/closeModal`)
2 -
3 -This document covers the stacked modal system used by Agent Zero’s frontend, implemented in:
4 -
5 -- `webui/js/modals.js`
6 -- `webui/css/modals.css`
7 -
8 -It also defines conventions for writing modal components in `webui/components/modals/` and `webui/components/settings/`.
9 -
10 -> Legacy note: there is an older overlay / teleport modal style in the codebase (e.g. `x-teleport` + `.modal-overlay`). Avoid it for new work. This doc is about the stacked modal system.
11 -
12 ----
13 -
14 -## Prerequisites & concepts (quick orientation)
15 -
16 -### Alpine.js and `$store`
17 -
18 -The UI uses Alpine.js for reactivity (`x-show`, `x-if`, `x-on`, `x-model`, …). Stores are registered via `createStore()` and read in HTML via `$store.<storeName>`.
19 -
20 -- Alpine initialization + lifecycle directives: `webui/js/initFw.js`
21 -- Store wrapper: `webui/js/AlpineStore.js`
22 -
23 -### `<x-component>` and `importComponent()`
24 -
25 -Agent Zero uses a custom `<x-component path="...">` tag that is populated by the component loader.
26 -
27 -The modal system does not rely on `<x-component>` directly; instead it calls the same loader function:
28 -
29 -- `importComponent(path, targetElement)` from `webui/js/components.js`
30 -
31 -That loader fetches component HTML, injects its `<style>` and `<script>` tags, and supports nested components.
32 -
33 ----
34 -
35 -## Why a “stacked modal system”?
36 -
37 -Agent Zero can open modals from many places (sidebar, settings, message actions), and sometimes a modal opens another modal.
38 -
39 -The stacked system provides:
40 -
41 -- A single modal container structure for consistent UI
42 -- A stack so nested modals work predictably
43 -- A single backdrop that always sits behind the active modal
44 -- A content loader that supports component HTML + `<style>` + `<script type="module">` the same way `<x-component>` does
45 -
46 ----
47 -
48 -## Core API
49 -
50 -File: `webui/js/modals.js`
51 -
52 -### `openModal(modalPath): Promise<void>`
53 -
54 -- Creates a new modal element and pushes it onto a stack.
55 -- Loads modal contents into the modal body by calling the component loader (`importComponent`).
56 -- Resolves the returned promise when the modal element is removed from the DOM.
57 -
58 -Edge cases / failure behavior (current implementation):
59 -
60 -- Invalid `modalPath` does not reject the returned promise. Instead, the modal remains open and shows an error message inside the modal body; the promise still resolves when the user closes the modal.
61 -- Calling `openModal()` multiple times with the same `modalPath` creates multiple modal instances (no deduping).
62 -
63 -Modal paths are component paths, e.g.:
64 -
65 -- `modals/file-browser/file-browser.html`
66 -- `modals/history/history.html`
67 -- `settings/settings.html`
68 -
69 -### `closeModal(modalPath?: string): void`
70 -
71 -- If no path is passed, closes the top modal.
72 -- If `modalPath` is passed, finds and closes that modal in the stack.
73 -
74 -Edge cases / failure behavior:
75 -
76 -- If the stack is empty, `closeModal()` is a no-op.
77 -- If `modalPath` is provided but not found, it is a no-op.
78 -
79 -### `scrollModal(id: string): void`
80 -
81 -Scrolls within the top modal’s `.modal-scroll` to an element by id.
82 -
83 ----
84 -
85 -## Modal DOM structure (what `modals.js` creates)
86 -
87 -When `openModal()` runs, it creates this outer shell:
88 -
89 -- `.modal` (full-screen fixed overlay container)
90 - - `.modal-inner`
91 - - `.modal-header` (title + close button)
92 - - `.modal-scroll`
93 - - `.modal-bd` (where the component HTML is imported)
94 - - `.modal-footer-slot` (used when the modal provides a footer)
95 -
96 -The component HTML is imported into `.modal-bd`.
97 -
98 -The title is taken from `<title>` inside the imported document (fallback: the modalPath).
99 -
100 -### Sizing and scrolling (CSS behavior)
101 -
102 -File: `webui/css/modals.css`
103 -
104 -- `.modal` is full-screen fixed positioning.
105 -- `.modal-inner` is centered and constrained:
106 - - `width: 90%`
107 - - `max-width: 960px`
108 - - `max-height: 90vh`
109 -- Tall modals scroll inside `.modal-scroll` (`overflow-y: auto`).
110 -- If the modal provides a footer, `.modal-footer-slot` is pinned under the scroll area (the body scrolls; the footer doesn’t).
111 -
112 ----
113 -
114 -## Footer support (`data-modal-footer`)
115 -
116 -Some modals want a footer that stays fixed while the body scrolls.
117 -
118 -Pattern:
119 -
120 -- In your modal component HTML, include a footer element marked with `data-modal-footer`.
121 -- `modals.js` will move that element out of the scroll area and into `.modal-footer-slot`.
122 -- `modals.js` adds `.modal-with-footer` to `.modal-inner` so CSS can lay out the scroll area correctly.
123 -
124 -Example patterns in the repo:
125 -
126 -- `webui/components/settings/settings.html` (Save / Cancel footer)
127 -- `webui/components/modals/file-browser/file-browser.html`
128 -- `webui/components/modals/scheduler/scheduler-modal.html`
129 -
130 -### Practical advice
131 -
132 -- The footer element must exist *after the component is loaded*, but `modals.js` uses a `requestAnimationFrame` to let Alpine mount first.
133 -- If you conditionally render the footer, keep it stable (don't constantly create/destroy it) or you'll fight the relocation.
134 -
135 ----
136 -
137 -## Shared CSS and button conventions
138 -
139 -File: `webui/css/modals.css`
140 -
141 -Modals should reuse shared CSS classes rather than redefining common styles. The modal system provides base classes for buttons, footers, and layout that work consistently across all modals.
142 -
143 -### Button classes
144 -
145 -Use these standard button classes for modal actions:
146 -
147 -| Class | Use case | Visual style |
148 -|-------|----------|--------------|
149 -| `btn btn-ok` | Positive/confirmatory actions (Save, Create, Confirm) | Solid blue background, white text |
150 -| `btn btn-cancel` | Dismissive/negative actions (Cancel, Close, Delete) | Transparent with accent border |
151 -
152 -Footer button order convention: positive action first (left), negative action second (right).
153 -
154 -Example footer markup:
155 -
156 -```html
157 -<div class="modal-footer" data-modal-footer>
158 - <button class="btn btn-ok" @click="$store.myStore.save()">Save</button>
159 - <button class="btn btn-cancel" @click="window.closeModal('...')">Cancel</button>
160 -</div>
161 -```
162 -
163 -### Available shared classes
164 -
165 -Before writing component-specific CSS, check `webui/css/modals.css` for:
166 -
167 -- `.btn`, `.btn-ok`, `.btn-cancel`, `.btn-field` — button styles
168 -- `.modal-footer` — footer container layout
169 -- `.section`, `.section-title`, `.section-description` — content sections
170 -- `.loading` — shimmer loading placeholder
171 -- `.toolbar-button`, `.toolbar-group` — editor toolbar elements
172 -- Range input styling for sliders
173 -
174 -### When to add component-specific CSS
175 -
176 -Add styles in your component's `<style>` tag only when:
177 -
178 -- The style is truly unique to that component's layout/behavior
179 -- No existing shared class covers the use case
180 -- You need to override a shared class for a specific context (use sparingly)
181 -
182 -Avoid redefining `.btn`, `.modal-footer`, or other shared classes in component CSS—this creates inconsistency and maintenance burden.
183 -
184 ----
185 -
186 -## Closing behavior (what users expect)
187 -
188 -### Close by button
189 -
190 -The shell provides a close button (`.modal-close`) that always closes the top modal.
191 -
192 -### Close by Escape
193 -
194 -`Escape` closes the top modal only (stack semantics).
195 -
196 -### Close by click-outside
197 -
198 -To avoid accidental close during drag/select, the shell only closes on click-outside when:
199 -
200 -- both `mousedown` and `mouseup` occurred on the modal container itself (`.modal`), not on inner content.
201 -
202 ----
203 -
204 -## Stacking + backdrop + z-index
205 -
206 -File: `webui/js/modals.js`
207 -
208 -- A single `.modal-backdrop` is used for all modals.
209 -- Z-index logic:
210 - - Base z-index for modals is `3000`
211 - - Each modal gets `base + index*20`
212 - - Backdrop sits below the top modal, and between the top two when multiple modals are open.
213 -
214 -Outcome:
215 -
216 -- Nested modals don’t “flatten” into each other.
217 -- The backdrop always darkens the page behind the active modal without hiding lower modals incorrectly.
218 -
219 -### Floating no-backdrop modals
220 -
221 -Use `.modal-floating` on the outer `.modal` when a modal should behave like a floating utility panel instead of a blocking dialog. This is for special live surfaces where the user should keep seeing and interacting with the chat or dashboard behind the panel. The Browser now primarily lives in the Canvas, Agent Zero's right-side workspace for live surfaces, but its floating/windowed surface follows the same non-blocking modal contract.
222 -
223 -Working contract:
224 -
225 -- `.modal-floating` suppresses the shared `.modal-backdrop` for that modal.
226 -- `.modal-floating` makes the full-screen `.modal` shell pointer-transparent.
227 -- `.modal-floating .modal-inner` remains pointer-active, so the floating panel itself still receives clicks, keyboard focus, drag handlers, resize handles, and form input.
228 -- Floating modal sizing, dragging, and resizing are still component-owned unless promoted to shared modal CSS later. The modal system only provides the backdrop and pointer-event behavior.
229 -
230 -Good to know:
231 -
232 -- A floating modal does not close by clicking the page behind it, because those clicks pass through to the app. Keep an obvious close button in the modal header.
233 -- If a floating modal opens another normal modal, the normal modal can still use the backdrop; stacking remains governed by the shared z-index logic.
234 -- Use `.modal-no-backdrop` only when a component needs backdrop suppression without click-through floating behavior. Prefer `.modal-floating` for utility panels.
235 -- Do not use `.modal-floating` for destructive confirmations, settings forms, auth, import/export, or workflows that require the user to finish or dismiss the dialog before interacting with the rest of the app.
236 -
237 ----
238 -
239 -## Writing a modal component (conventions)
240 -
241 -### File location
242 -
243 -Prefer:
244 -
245 -- `webui/components/modals/<name>/<name>.html` (+ optional `*-store.js`)
246 -
247 -Settings uses:
248 -
249 -- `webui/components/settings/settings.html` and nested settings components.
250 -
251 -### Recommended HTML skeleton
252 -
253 -Use this structure:
254 -
255 -- `<head><title>...</title>`
256 -- A `<script type="module">` that imports your store (so it registers before Alpine evaluates bindings)
257 -- `<body>` with:
258 - - a single root wrapper
259 - - Alpine lifecycle hooks (`x-create`/`x-init` + `x-destroy`) to run open/cleanup logic
260 -- A `<style>` tag at the bottom of the component file containing all modal-specific styling
261 -
262 -Good examples:
263 -
264 -- `webui/components/modals/history/history.html`
265 -- `webui/components/modals/context/context.html`
266 -- `webui/components/modals/scheduler/scheduler-modal.html`
267 -
268 -### Store conventions
269 -
270 -- Define stores via `createStore()` from `webui/js/AlpineStore.js`.
271 -- UI reads state through `$store.<storeName>`.
272 -- Prefer a small public API:
273 - - `open()` / `openModal()` to open the modal
274 - - `destroy()` / `cleanup()` to reset transient state
275 -
276 ----
277 -
278 -## “Don’t” list (keeps the system sane)
279 -
280 -- Don’t add `document.addEventListener('alpine:init', ...)` blocks inside component HTML — it conflicts with `initFw.js` ordering and can register handlers twice when components are reloaded.
281 -- Don’t manually manipulate `.modal-inner` or `.modal-scroll` structure — `modals.js` owns the shell and footer-slot mechanics; manual changes create layout/scroll bugs.
282 -- Don’t introduce a new modal overlay system; keep the stack, mixed systems break z-index/backdrop expectations and make nested modals unreliable.
283 -- Don’t assume a modal is the only one open; always write logic that behaves correctly when stacked — `Escape`/close behavior, z-index, and focus should all be “top modal wins”.
284 -- Don’t open a new modal synchronously from another modal’s close handler — it can race stack removal and produce transient z-index/backdrop glitches; schedule via `requestAnimationFrame` if needed.
285 -- Don’t store sensitive data in modal stores without explicit cleanup — stores often outlive a modal’s DOM and can leak values across reopen.
286 -- Don’t rely on modal state persisting across close/reopen cycles — design stores so `open()` rehydrates and `destroy()`/`cleanup()` resets transient state.
287 -
288 ----
289 -
290 -## Debugging checklist
291 -
292 -### Modal opens but content never appears
293 -
294 -- Verify the path passed to `openModal()` is correct and resolves under `webui/components/`.
295 -- Check browser console for fetch/import errors.
296 -- If you use `<script type="module" src="...">` in the component, ensure the URL is correct.
297 -
298 -### Footer is inside the scroll area (not pinned)
299 -
300 -- Ensure your footer element has the `data-modal-footer` attribute.
301 -- Ensure it exists after the component loads (if you gate it behind `x-if`, ensure the store is available).
302 -
303 -### Closing behavior is weird with nested modals
304 -
305 -- Remember `Escape` closes only the top modal.
306 -- `closeModal('some/path.html')` closes that modal wherever it is in the stack.
307 -
308 -### Modal opens but `$store.someStore` is undefined
309 -
310 -- Ensure the modal HTML imports its store in a `<script type="module">` block (so the store registers before Alpine evaluates bindings).
311 -- Ensure the store name matches what the markup reads (store registered as `createStore("history", ...)` is accessed as `$store.history`).
312 -- If you guard with `<template x-if="$store.someStore">`, verify you’re using the correct store key and not a stale name.
313 -
314 -### Modal won’t close / UI feels “stuck”
315 -
316 -- `closeModal()` removes the modal element immediately; if your store keeps polling or timers alive, the UI may still feel active—ensure you have `x-destroy` cleanup (`destroy()`/`cleanup()`).
317 -- As a last resort, inspect and remove leftover modal nodes in DevTools (`document.querySelectorAll('.modal').forEach(m => m.remove())`) and reset any store state that assumes the modal is open.
318 -
319 -### Inspecting stack/z-index issues
320 -
321 -- In DevTools Elements:
322 - - inspect `.modal` elements (multiple means you have a stack)
323 - - check the `style="z-index: ..."` on `.modal-inner`
324 - - verify `.modal-backdrop` exists and sits between modals when stacked
325 -- If the footer is not pinned, confirm your footer element has `data-modal-footer` and that `.modal-inner` has `.modal-with-footer`.
docs/agents/AGENTS.plugins.md deleted
-336
@@ -1,336 +0,0 @@
1 -# Agent Zero - Plugins Guide
2 -
3 -This guide covers the Python Backend and Frontend Web UI plugin architecture. Use this as the definitive reference for building and extending Agent Zero.
4 -
5 ----
6 -
7 -## 1. Architecture Overview
8 -
9 -Agent Zero uses a convention-over-configuration plugin model where runtime capabilities are discovered from the directory structure.
10 -
11 -### Internal Components
12 -
13 -1. Backend discovery (python/helpers/plugins.py): Resolves roots (usr/plugins/ first, then plugins/) and builds the effective set of plugins.
14 -2. Path resolution (python/helpers/subagents.py): Injects plugin paths into the agent's search space for prompts, tools, and configurations.
15 -3. Python extensions (python/helpers/extension.py): Executes named lifecycle hooks from `extensions/python/<point>/` and implicit `@extensible` hooks from `extensions/python/_functions/<module>/<qualname>/<start|end>/`.
16 -4. Web UI extensions (webui/js/extensions.js): Injects HTML/JS contributions into core UI breakpoints (x-extension).
17 -
18 ----
19 -
20 -## 2. File Structure
21 -
22 -Each plugin lives in usr/plugins/<plugin_name>/.
23 -
24 -```text
25 -usr/plugins/<plugin_name>/
26 -├── plugin.yaml # Required: Title, version, settings + activation metadata
27 -├── execute.py # Optional: user-triggered plugin script
28 -├── hooks.py # Optional: runtime hook functions callable by the framework
29 -├── default_config.yaml # Optional: fallback settings defaults
30 -├── README.md # Optional locally; strongly recommended for community plugins (Plugin Hub)
31 -├── LICENSE # Optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submission
32 -├── conf/
33 -│ └── model_providers.yaml # Optional: add or override model providers
34 -├── api/ # API handlers (ApiHandler subclasses)
35 -├── tools/ # Agent tools (Tool subclasses)
36 -├── helpers/ # Shared Python logic
37 -├── prompts/ # Prompt templates
38 -├── agents/ # Agent profiles (agents/<profile>/agent.yaml)
39 -├── extensions/
40 -│ ├── python/<point>/ # Named backend lifecycle hooks
41 -│ ├── python/_functions/<module>/<qualname>/<start|end>/ # Implicit @extensible hooks
42 -│ └── webui/<point>/ # UI HTML/JS contributions
43 -└── webui/
44 - ├── config.html # Optional: Plugin settings UI
45 - └── ... # Full plugin pages/components
46 -```
47 -
48 -### Python extension layouts
49 -
50 -Use one of these backend extension layouts, depending on what you are extending:
51 -
52 -- `extensions/python/<extension_point>/` for named lifecycle hooks such as `system_prompt`, `monologue_start`, or `tool_execute_before`
53 -- `extensions/python/_functions/<module>/<qualname>/<start|end>/` for implicit `@extensible` call sites
54 -
55 -The `_functions` layout preserves every module segment and every nested `__qualname__` segment. Do not use the retired flattened form `extensions/python/<module>_<qualname>_<start|end>/`; those folder names no longer match the runtime lookup logic.
56 -
57 -### Python import rule for user plugins
58 -
59 -For plugin-local Python code in `usr/plugins/<plugin_name>/`, import through the
60 -fully qualified `usr.plugins.<plugin_name>...` package path.
61 -
62 -Good (DO):
63 -
64 -```python
65 -from usr.plugins.my_plugin.helpers.runtime import do_work
66 -import usr.plugins.my_plugin.helpers.state as state
67 -```
68 -
69 -Avoid (DON'T):
70 -
71 -```python
72 -# sys.path hacks
73 -sys.path.insert(0, ...)
74 -from helpers.runtime import do_work
75 -
76 -# persistent symlink-based imports
77 -from plugins.my_plugin.helpers.runtime import do_work
78 -```
79 -
80 -Why:
81 -
82 -- `usr.plugins...` works without renaming `helpers/`
83 -- it avoids `sys.path` mutation for plugin-local imports
84 -- it avoids installation-time symlinks into `/a0/plugins/`
85 -- it keeps plugin removal reversible, with no import wiring left behind
86 -
87 -### plugin.yaml (runtime manifest)
88 -
89 -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).
90 -
91 -```yaml
92 -name: my_plugin # required for community plugins (^[a-z0-9_]+$, must match dir name)
93 -title: My Plugin
94 -description: What this plugin does.
95 -version: 1.0.0
96 -settings_sections:
97 - - agent
98 -per_project_config: false
99 -per_agent_config: false
100 -# Optional: lock plugin permanently ON in UI/back-end
101 -always_enabled: false
102 -```
103 -
104 -Field reference:
105 -- `name`: Plugin identifier. Required by CI when submitting to the Plugin Index. Must be `^[a-z0-9_]+$` and match the index folder name exactly.
106 -- `title`: UI display name
107 -- `description`: Short plugin summary
108 -- `version`: Plugin version string
109 -- `settings_sections`: Which Settings tabs show a subsection for this plugin. Valid values: `agent`, `external`, `mcp`, `developer`, `backup`. Use `[]` for no subsection.
110 -- `per_project_config`: Enables project-scoped settings and toggle rules
111 -- `per_agent_config`: Enables agent-profile-scoped settings and toggle rules
112 -- `always_enabled`: Forces ON and disables toggle controls in the UI (reserved for framework use)
113 -
114 -### execute.py (plugin script)
115 -
116 -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.
117 -
118 -Design guidance:
119 -- use `execute.py` for manual operations the user may need to run again later
120 -- prefer making it rerunnable or state-aware
121 -- avoid placing framework-internal automatic behavior here; that belongs in `hooks.py` or lifecycle extensions
122 -- 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
123 -
124 -### hooks.py (framework runtime hooks)
125 -
126 -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(...)`.
127 -
128 -- `hooks.py` runs inside the **Agent Zero framework runtime and Python environment**, not the separate agent execution environment.
129 -- Use it for framework-internal operations such as install-time setup, pre-update cleanup or preparation, plugin registration work, filesystem preparation, cache updates, or other tasks that need access to Agent Zero internals.
130 -- Hook functions may be synchronous or async. Async hooks are awaited by the framework.
131 -- Hook modules are cached until plugin caches are cleared, so changes may require a plugin refresh/reload cycle.
132 -- 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.
133 -
134 -Current built-in usage:
135 -- the plugin installer calls `install()` from `hooks.py` after a plugin is copied into place
136 -- the plugin updater calls `pre_update()` from `hooks.py` immediately before pulling new plugin code into place
137 -
138 -### Runtime and dependency implications
139 -
140 -- If `hooks.py` installs Python packages with `sys.executable -m pip`, those packages are installed into the **same Python environment that runs Agent Zero itself**.
141 -- This is the correct place for Python dependencies that your plugin's backend code needs while running inside the framework runtime.
142 -- It is **not** the right place for dependencies meant only for the separate agent execution runtime or for arbitrary system-level tooling.
143 -
144 -If your plugin needs to install packages or binaries for the agent execution environment instead of the framework runtime, launch a subprocess that explicitly activates or targets that other environment first. In practice this means invoking the correct interpreter or shell for that environment rather than relying on the current process environment. For example:
145 -
146 -- target a specific Python interpreter path for that runtime
147 -- activate the desired virtualenv inside a subprocess shell command before running `pip`
148 -- invoke the appropriate package manager from a subprocess prepared for that environment
149 -
150 -In Docker deployments, this distinction is especially important:
151 -
152 -- Framework runtime: `/opt/venv-a0`
153 -- Agent execution runtime: `/opt/venv`
154 -
155 -So a `hooks.py` install step affects `/opt/venv-a0` unless you intentionally switch to `/opt/venv` (or another target) inside your subprocess.
156 -
157 ----
158 -
159 -## 3. Frontend Extensions
160 -
161 -### HTML Breakpoints
162 -Core UI defines insertion points like <x-extension id="sidebar-quick-actions-main-start"></x-extension>.
163 -To contribute:
164 -1. Place HTML files in extensions/webui/<extension_point>/.
165 -2. Include a root x-data scope.
166 -3. Include an x-move-* directive (e.g., x-move-to-start, x-move-after="#id").
167 -
168 -### JS Hooks
169 -Place *.js files in extensions/webui/<extension_point>/ and export a default async function. They are called via callJsExtensions("<point>", context).
170 -
171 -Core JS hooks can also expose runtime UI surfaces when static HTML breakpoints are not a fit. For example, `confirm_dialog_after_render` runs after the shared confirm dialog is built and receives the rendered dialog/body/footer nodes plus any caller-provided `extensionContext`.
172 -
173 -For tool chat rows (`type === "tool"`), after built-in badge rules, core calls `get_tool_message_handler` with a mutable object containing `tool_name`, `kvps`, and `handler`. Plugins can set `handler` to entirely take over rendering for their `_tool_name`. A plugin can import `drawMessageToolSimple` and call it internally (e.g., passing `{ ...args, code: "WWW" }`) if it just wants standard tool row styling with a custom badge.
174 -
175 -### User Feedback: Notifications, Not Inline Errors
176 -Plugin UI must use the **A0 notification system** for errors, success, and warnings. Do not render dedicated error/success boxes (e.g. a red block bound to `store.error`). Use the notification store so toasts and notification history stay consistent across the app.
177 -
178 -- **Frontend (Alpine/store)**: Import `toastFrontendError`, `toastFrontendSuccess`, `toastFrontendWarning`, `toastFrontendInfo` from `/components/notifications/notification-store.js`, or call `$store.notificationStore.frontendError(message, title)` etc.
179 -- **Backend (Python)**: Use `AgentNotification.error(...)`, `AgentNotification.success(...)` from `helpers.notification`.
180 -
181 -See [Notifications](../developer/notifications.md) for the full API.
182 -
183 ----
184 -
185 -## 4. Plugin Settings
186 -
187 -1. Add webui/config.html to your plugin.
188 -2. The plugin settings wrapper instantiates a local modal context from $store.pluginSettingsPrototype.
189 -3. Bind plugin fields to config.* and use context.* for modal-level state and actions.
190 -4. Settings are scoped per-project and per-agent automatically.
191 -
192 -### Resolution Priority (Highest First)
193 -1. project/.a0proj/agents/<profile>/plugins/<name>/config.json
194 -2. project/.a0proj/plugins/<name>/config.json
195 -3. usr/agents/<profile>/plugins/<name>/config.json
196 -4. usr/plugins/<name>/config.json
197 -5. plugins/<name>/default_config.yaml (fallback defaults)
198 -
199 -## 5. Model Providers
200 -
201 -Plugins can add or override model providers by placing a `conf/model_providers.yaml` inside their plugin directory. The file follows the same format as the main `conf/model_providers.yaml`.
202 -
203 -At startup (and whenever a plugin is enabled/disabled), the system:
204 -1. Loads the base `conf/model_providers.yaml`.
205 -2. Discovers `conf/model_providers.yaml` from all enabled plugins.
206 -3. Merges them in order — matching provider IDs are overwritten, new IDs are appended.
207 -
208 -Example plugin provider file (`usr/plugins/my_plugin/conf/model_providers.yaml`):
209 -```yaml
210 -chat:
211 - my_custom_provider:
212 - name: My Custom LLM
213 - litellm_provider: openai
214 - kwargs:
215 - api_base: https://my-llm.example.com/v1
216 -
217 -embedding:
218 - my_custom_embed:
219 - name: My Embeddings
220 - litellm_provider: openai
221 - kwargs:
222 - api_base: https://my-embed.example.com/v1
223 -```
224 -
225 ----
226 -
227 -## 6. Plugin Activation Model
228 -
229 -- Global and scoped activation are independent, with no inheritance between scopes.
230 -- Activation flags are files: `.toggle-1` (ON) and `.toggle-0` (OFF).
231 -- The plugin list shows a binary `ON`/`OFF` global activation switch.
232 -- `always_enabled: true` in `plugin.yaml` forces ON and disables toggle controls in the UI.
233 -- For plugins with project/profile scoping, the plugin config modal is the canonical per-scope activation surface.
234 -
235 ----
236 -
237 -## 7. Routes
238 -
239 -| Route | Purpose |
240 -|---|---|
241 -| GET /plugins/<name>/<path> | Serve static assets |
242 -| POST /api/plugins/<name>/<handler> | Call plugin API |
243 -| POST /api/plugins | Management (actions: get_config, save_config, list_configs, delete_config, toggle_plugin, get_doc) |
244 -
245 ----
246 -
247 -## 8. Plugin Index & Community Sharing
248 -
249 -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.
250 -
251 -### Two Distinct Manifest Files
252 -
253 -There are two completely different manifest files used at different stages. They must not be confused:
254 -
255 -**Runtime manifest** (`plugin.yaml`, inside your plugin repo/directory — drives Agent Zero behavior):
256 -```yaml
257 -name: my_plugin # REQUIRED for index submission; must match index folder name
258 -title: My Plugin
259 -description: What this plugin does.
260 -version: 1.0.0
261 -settings_sections:
262 - - agent
263 -per_project_config: false
264 -per_agent_config: false
265 -always_enabled: false
266 -```
267 -
268 -**Index manifest** (`index.yaml`, submitted to the `a0-plugins` repo under `plugins/<your_plugin_name>/` — drives discoverability only):
269 -```yaml
270 -title: My Plugin
271 -description: What this plugin does.
272 -github: https://github.com/yourname/your-plugin-repo
273 -tags:
274 - - tools
275 - - example
276 -screenshots: # optional, up to 5 full image URLs
277 - - https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png
278 -```
279 -
280 -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. That repository must also include a `LICENSE` file at its root so community users have explicit terms of use.
281 -
282 -### Repository Structure for Community Plugins
283 -
284 -When creating a plugin intended for the community, the plugin should be a standalone GitHub repository where the plugin directory contents live at the repo root:
285 -
286 -```text
287 -your-plugin-repo/ ← GitHub repository root
288 -├── plugin.yaml ← runtime manifest (title, description, version, ...)
289 -├── default_config.yaml
290 -├── README.md
291 -├── LICENSE ← required for Plugin Index (community) plugins
292 -├── api/
293 -├── tools/
294 -├── extensions/
295 -└── webui/
296 -```
297 -
298 -Users install it locally by cloning (or downloading) the repo contents into `/a0/usr/plugins/<plugin_name>/`.
299 -
300 -### Submitting to the Plugin Index
301 -
302 -1. Create a GitHub repository for your plugin with the runtime `plugin.yaml` (including the `name` field) at the repo root.
303 -2. Fork `https://github.com/agent0ai/a0-plugins`.
304 -3. Create a folder `plugins/<your_plugin_name>/` containing only an `index.yaml` (and optionally a square thumbnail image ≤ 20 KB).
305 -4. Open a Pull Request with exactly one new plugin folder.
306 -5. CI validates the submission automatically. A maintainer reviews and merges.
307 -
308 -Index submission rules:
309 -- One plugin per PR
310 -- Folder name: unique, stable, `^[a-z0-9_]+$` (lowercase, numbers, underscores — no hyphens)
311 -- Folder name must exactly match the `name` field in your remote `plugin.yaml`
312 -- Folders starting with `_` are reserved for internal use
313 -- `github` must point to a public repo that contains `plugin.yaml` at its root with a matching `name` field
314 -- The same repo must contain `LICENSE` at its root (community contribution requirement)
315 -- `title` max 50 characters, `description` max 500 characters
316 -- `index.yaml` total max 2000 characters
317 -- `tags`: optional, up to 5, use recommended tags from https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
318 -- `screenshots`: optional, up to 5 full image URLs (png/jpg/webp, each ≤ 2 MB)
319 -
320 -### Plugin Hub
321 -
322 -The Plugin Hub is provided by the always-enabled `_plugin_installer` plugin. Users can reach it from the **Plugins** dialog in two ways:
323 -
324 -- the **Browse** tab in `webui/components/plugins/list/plugin-list.html`
325 -- 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
326 -
327 -Both routes surface Plugin Index entries inside Agent Zero. The Plugin Hub supports search, filtering, sorting, and a detail view with README content and installation actions.
328 -
329 ----
330 -
331 -## 9. See Also
332 -
333 -- `docs/developer/plugins.md` for the compact plugin starting point and sharing checklist
334 -- `plugins/README.md` for the bundled-vs-user plugin directory overview and quick links
335 -- `skills/a0-plugin-router/SKILL.md` for the agent-facing entry point that routes plugin tasks to the right specialist skill
336 -- `AGENTS.md` for the main framework guide
extensions/AGENTS.md new
+39
@@ -0,0 +1,39 @@
1 +# Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own core lifecycle extension implementations for backend and WebUI extension points.
6 +- Keep built-in hook behavior ordered, discoverable, and compatible with plugin extension discovery.
7 +
8 +## Ownership
9 +
10 +- `python/` contains backend lifecycle hooks executed through `helpers.extension`.
11 +- `webui/` contains frontend extension contributions loaded through `webui/js/extensions.js`.
12 +- Plugin-specific extensions belong inside each plugin's `extensions/` directory.
13 +
14 +## Local Contracts
15 +
16 +- Extension directory names are runtime extension point names.
17 +- File ordering matters when names include numeric prefixes.
18 +- Extensions must be safe to run repeatedly when the lifecycle point can fire multiple times.
19 +- Secret masking, auth, security, and persistence extensions must not be bypassed by convenience changes.
20 +
21 +## Work Guidance
22 +
23 +- Keep extension code small and focused on its hook point.
24 +- Move shared logic into `helpers/` when it is reused outside one extension.
25 +- Coordinate changes with plugin extension docs and tests when extension point semantics change.
26 +
27 +## Verification
28 +
29 +- Run targeted lifecycle, prompt, stream, WebSocket, or WebUI extension tests for changed hook points.
30 +- Smoke-test startup when changing initialization, migration, or system-prompt extensions.
31 +
32 +## Child DOX Index
33 +
34 +Direct child DOX files:
35 +
36 +| Child | Scope |
37 +| --- | --- |
38 +| [python/AGENTS.md](python/AGENTS.md) | Backend lifecycle extension hook files. |
39 +| [webui/AGENTS.md](webui/AGENTS.md) | Frontend extension contributions. |
extensions/python/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Python Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own built-in backend lifecycle extensions under `extensions/python/`.
6 +- Keep Python hook behavior compatible with `helpers.extension.call_extensions_async` and `call_extensions_sync`.
7 +
8 +## Ownership
9 +
10 +- Each direct subdirectory is one named extension point.
11 +- Python files inside an extension point are loaded in deterministic filename order.
12 +- Implicit `@extensible` hook implementations use `_functions/<module>/<qualname>/<start|end>/` layout when present.
13 +
14 +## Local Contracts
15 +
16 +- Extension functions must match the arguments supplied by their hook point.
17 +- Preserve numeric prefixes when ordering affects prompt construction, stream masking, persistence, or cleanup.
18 +- Use `AgentContext` from `agent` when context access is needed.
19 +- Do not log unmasked secrets, raw hidden prompt sections, or private user data.
20 +
21 +## Work Guidance
22 +
23 +- Keep extension modules import-light; many hooks run during hot paths.
24 +- Use mutable `ctx` or `data` dictionaries according to the hook contract when rewriting content.
25 +- Add or update tests when a hook changes prompt content, message history, tool output, streaming, or persistence behavior.
26 +
27 +## Verification
28 +
29 +- Run targeted tests for the affected lifecycle area.
30 +- Run a startup smoke check for `agent_init`, `startup_migration`, or `system_prompt` changes when practical.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
extensions/webui/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# WebUI Extensions DOX
2 +
3 +## Purpose
4 +
5 +- Own built-in frontend extension contributions under `extensions/webui/`.
6 +- Keep WebUI extension points compatible with the core loader and plugin extension model.
7 +
8 +## Ownership
9 +
10 +- Each direct subdirectory is one frontend extension point.
11 +- `.html` files are injected as component references through `<x-extension>`.
12 +- `.js` and `.mjs` files export default functions called by `callJsExtensions`.
13 +
14 +## Local Contracts
15 +
16 +- HTML contributions must be valid component fragments and include Alpine state only where needed.
17 +- JavaScript extension modules must export a default function.
18 +- Extension code must not assume a plugin is installed unless it guards that dependency.
19 +- Keep extension point names synchronized with `x-extension` IDs and `callJsExtensions()` callers.
20 +
21 +## Work Guidance
22 +
23 +- Prefer small extension modules that delegate to existing WebUI stores or helpers.
24 +- Use the notification store for user-facing success, warning, or error feedback.
25 +- Avoid global DOM queries when an extension hook provides scoped nodes or context.
26 +
27 +## Verification
28 +
29 +- Manually load the WebUI or run targeted frontend/WebUI tests after changing visible extension behavior.
30 +- Verify extension cache clearing paths when adding new extension points.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
helpers/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Backend Helpers DOX
2 +
3 +## Purpose
4 +
5 +- Own shared Python framework utilities used by agents, APIs, tools, plugins, WebSockets, persistence, and runtime services.
6 +- Keep cross-cutting behavior stable and tested.
7 +
8 +## Ownership
9 +
10 +- Helper modules provide reusable services; feature-specific route handlers belong in `api/`, tool behavior in `tools/`, and plugin-local logic inside plugin directories.
11 +- Security, auth, settings, file access, plugin discovery, extension dispatch, notifications, state snapshots, scheduler, tunnel, and WebSocket primitives live here.
12 +
13 +## Local Contracts
14 +
15 +- Preserve public helper APIs used by core code and plugins unless all callers, docs, and tests are updated.
16 +- Use structured parsers and serializers for YAML, JSON, paths, and URLs instead of ad hoc string handling.
17 +- Keep path handling constrained to intended roots for user files, uploads, downloads, projects, and workdirs.
18 +- Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values.
19 +- Use `RepairableException` for errors an agent may be able to fix.
20 +
21 +## Work Guidance
22 +
23 +- Prefer cohesive helper modules over adding unrelated utilities to large files.
24 +- Keep imports acyclic where possible; defer imports inside functions only when needed to avoid startup cycles.
25 +- For changes touching auth, CSRF, files, plugins, tunnels, WebSockets, or model calls, read the caller and tests before editing.
26 +
27 +## Verification
28 +
29 +- Run targeted tests for changed helper modules.
30 +- Run security regression tests for auth, CSRF, filesystem, WebSocket, tunnel, upload, or image-serving changes.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
knowledge/AGENTS.md new
+33
@@ -0,0 +1,33 @@
1 +# Knowledge DOX
2 +
3 +## Purpose
4 +
5 +- Own built-in agent self-knowledge and repository-shipped indexed reference content.
6 +- Keep internal reference material accurate for runtime recall without mixing in user-private data.
7 +
8 +## Ownership
9 +
10 +- `main/about/` contains built-in Agent Zero self-knowledge.
11 +- `fragments/`, `instruments/`, and `solutions/` are reserved knowledge roots.
12 +- User-local knowledge belongs under `usr/knowledge/`.
13 +
14 +## Local Contracts
15 +
16 +- Do not place secrets, chat transcripts, private user memory, or local deployment details in repository knowledge.
17 +- Keep self-knowledge consistent with current architecture, configuration, capabilities, and setup docs.
18 +- Markdown here is for agent runtime context, not general marketing copy.
19 +
20 +## Work Guidance
21 +
22 +- Update self-knowledge when durable runtime behavior, setup, configuration, or agent capabilities change.
23 +- Keep entries concise and specific enough for retrieval.
24 +- Prefer source-grounded statements over aspirational descriptions.
25 +
26 +## Verification
27 +
28 +- Re-read touched source or docs before changing self-knowledge.
29 +- Run any available indexing or knowledge tests when changing retrieval-sensitive structure.
30 +
31 +## Child DOX Index
32 +
33 +No child DOX files.
lib/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# Library Assets DOX
2 +
3 +## Purpose
4 +
5 +- Own small browser-side helper scripts outside the main WebUI module tree.
6 +- Keep injected browser automation assets stable and narrowly scoped.
7 +
8 +## Ownership
9 +
10 +- `browser/` contains scripts used by browser automation and DOM extraction flows.
11 +- Main WebUI code belongs under `webui/`.
12 +
13 +## Local Contracts
14 +
15 +- Browser helper scripts must not depend on unavailable bundlers or Node build steps.
16 +- Keep scripts safe to inject into arbitrary pages by minimizing global side effects.
17 +- Do not collect secrets or page data beyond what the calling tool explicitly needs.
18 +
19 +## Work Guidance
20 +
21 +- Prefer plain JavaScript with clear inputs and outputs.
22 +- Coordinate DOM extraction changes with browser tools, browser plugins, and tests.
23 +- Avoid adding large third-party libraries here.
24 +
25 +## Verification
26 +
27 +- Run browser-agent or browser-tool regression tests after changing browser helper scripts.
28 +- Manually smoke-test browser flows when tests do not cover the changed path.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
plugins/AGENTS.md new
+63
@@ -0,0 +1,63 @@
1 +# Plugins DOX
2 +
3 +## Purpose
4 +
5 +- Own bundled system plugins shipped with Agent Zero.
6 +- Provide the tracked plugin architecture contract for both bundled plugins and custom plugins developed under ignored `usr/plugins/`.
7 +- Keep plugin behavior discoverable, reversible, and compatible across bundled and custom roots without creating DOX files inside `usr/`.
8 +
9 +## Ownership
10 +
11 +- Each direct `_plugin_name/` directory owns its `plugin.yaml`, optional `default_config.yaml`, `hooks.py`, API handlers, helpers, tools, prompts, skills, extensions, WebUI assets, and README.
12 +- Plugins may also own `execute.py`, `conf/model_providers.yaml`, plugin-distributed `agents/<profile>/agent.yaml`, static assets, and plugin-local docs.
13 +- `README.md` owns the high-level core plugin architecture summary and community Plugin Index guidance.
14 +- Custom or experimental user plugins belong under `usr/plugins/`, not here, but this file remains their tracked DOX contract.
15 +- Do not create `AGENTS.md` files under `usr/plugins/` unless the user explicitly asks for ignored user-state documentation.
16 +
17 +## Local Contracts
18 +
19 +- Every plugin directory must include a valid `plugin.yaml`.
20 +- Runtime manifest fields include `name`, `title`, `description`, `version`, `settings_sections`, `per_project_config`, `per_agent_config`, and `always_enabled`.
21 +- Core plugins may use `plugins.<plugin_name>...` imports when they are shipped from this tree.
22 +- User plugins under `usr/plugins/` must use `usr.plugins.<plugin_name>...` imports and avoid `sys.path` hacks or persistent symlink-based imports.
23 +- Plugin extension layouts must use `extensions/python/<point>/`, `extensions/python/_functions/<module>/<qualname>/<start|end>/`, and `extensions/webui/<point>/`.
24 +- The `_functions` extension layout preserves every module and nested qualname segment; do not use retired flattened extension folder names.
25 +- Plugin settings defaults belong in `default_config.yaml`; runtime user settings belong under `usr/`.
26 +- Plugin settings resolution order is project/profile, project, user/profile, user plugin config, then bundled `default_config.yaml`.
27 +- `webui/config.html` settings UIs must bind plugin values to `config.*` and modal state/actions to `context.*` through `$store.pluginSettingsPrototype`.
28 +- Plugin model provider overrides belong in plugin `conf/model_providers.yaml` and merge after base `conf/model_providers.yaml`.
29 +- Global and scoped activation are independent and use `.toggle-1` and `.toggle-0`; `always_enabled: true` forces ON and disables UI toggles.
30 +- `hooks.py` runs in the framework runtime. Explicitly target another runtime if a plugin must prepare the agent execution environment.
31 +- `execute.py` is manual user-triggered setup, maintenance, repair, migration, or refresh work; automatic framework behavior belongs in hooks or lifecycle extensions.
32 +- Plugin routes are `GET /plugins/<name>/<path>`, `POST /api/plugins/<name>/<handler>`, and `POST /api/plugins` for management actions.
33 +- Frontend plugin HTML extensions live under `extensions/webui/<point>/`, include a root Alpine scope, and use `x-move-*` directives when targeting static breakpoints.
34 +- Frontend plugin JS extensions live under `extensions/webui/<point>/` and export a default function.
35 +- Plugin UI must use the A0 notification system for errors, warnings, success, and info instead of inline success/error boxes.
36 +- Banners and discovery cards are provided through Python `banners` extensions by appending dictionaries with unique `id`, `type`, `priority`, and display fields to the `banners` list.
37 +- Alert banner types are `info`, `warning`, and `error`; discovery card types are `hero` and `feature`.
38 +- Banner/card fields may include `title`, `html`, `description`, `thumbnail`, `icon`, `cta_text`, `cta_action`, and `dismissible` depending on type.
39 +- Community discovery cards should use `type: "feature"`; reserve `hero` cards for core system features.
40 +- Supported discovery CTA actions are `open-plugin-config:<plugin_folder_name>`, `open-plugin-hub`, and `open-url:<url>`.
41 +- Plugin deletion or disablement should not leave unmanaged services, symlinks, or files outside plugin-owned paths unless explicitly documented with cleanup.
42 +
43 +## Work Guidance
44 +
45 +- Prefer plugin-local helpers for behavior used only by one plugin.
46 +- Use shared `helpers/` only for reusable framework behavior.
47 +- Use the notification system for plugin UI feedback.
48 +- Keep plugin README and docs current when user-visible plugin behavior changes.
49 +- Check configuration before injecting setup or discovery banners so configured plugins do not keep advertising setup.
50 +- Use highly unique banner IDs prefixed by plugin name.
51 +- When preparing community plugins, keep plugin contents at the standalone repository root with `plugin.yaml`, `README.md`, and a root `LICENSE`.
52 +- Plugin Index submissions use a separate `index.yaml` under `a0-plugins/plugins/<name>/`; do not confuse it with runtime `plugin.yaml`.
53 +
54 +## Verification
55 +
56 +- Run plugin-specific tests after changing a bundled plugin.
57 +- Run framework tests for touched extension points, API handlers, tools, settings, or WebUI surfaces.
58 +- For plugins with external services or browser/desktop integrations, perform a targeted smoke check when practical.
59 +- For banner/discovery changes, verify the Welcome Screen renders alert banners, feature cards, dismiss behavior, priority ordering, and CTA behavior.
60 +
61 +## Child DOX Index
62 +
63 +No child DOX files.
plugins/README.md
+1 -1
@@ -11,7 +11,7 @@ This directory contains the system-level plugins bundled with Agent Zero.
11
12 For detailed guides on how to create, extend, or configure plugins, refer to:
13
14 -- [`docs/agents/AGENTS.plugins.md`](../docs/agents/AGENTS.plugins.md): Full-stack plugin architecture, manifest format, extension points, and Plugin Index submission.
14 +- [`plugins/AGENTS.md`](AGENTS.md): Bundled and custom plugin architecture, manifest format, extension points, banners, and Plugin Index submission rules.
15 - [`docs/developer/plugins.md`](../docs/developer/plugins.md): Human-facing developer guide covering the full plugin lifecycle.
16 - [`AGENTS.md`](../AGENTS.md): Main framework guide and backend context.
17 - [`skills/a0-plugin-router/SKILL.md`](../skills/a0-plugin-router/SKILL.md): Agent-facing entry point that routes plugin tasks to the appropriate specialist skill.
prompts/AGENTS.md new
+35
@@ -0,0 +1,35 @@
1 +# Prompts DOX
2 +
3 +## Purpose
4 +
5 +- Own core prompt templates used by agents, tools, framework messages, behavior updates, summaries, skills, projects, and system context.
6 +- Keep prompt contracts explicit and synchronized with code that renders them.
7 +
8 +## Ownership
9 +
10 +- `agent.*.md` and companion `.py` files provide system, context, tool, project, skill, and behavior prompt material.
11 +- `fw.*.md` files provide framework-generated message templates.
12 +- Profile-specific prompt overrides belong under `agents/<profile>/prompts/`.
13 +- Plugin prompt additions belong under the relevant plugin `prompts/` directory.
14 +
15 +## Local Contracts
16 +
17 +- Do not include secrets, real API keys, or private user data in prompt templates.
18 +- Keep placeholder names, include aliases, and template assumptions synchronized with prompt-loading code and extensions.
19 +- Prompt changes can alter agent behavior; keep edits narrow and intentional.
20 +- Maintain clear separation between core behavior prompts and profile/plugin-specific customization.
21 +
22 +## Work Guidance
23 +
24 +- Read the rendering path before changing placeholders or filenames.
25 +- Prefer small prompt additions over broad rewrites when fixing a specific behavior.
26 +- Update tests or snapshots when prompt budget, required sections, or generated system content changes.
27 +
28 +## Verification
29 +
30 +- Run targeted prompt, budget, snapshot, tool, or behavior tests after prompt changes.
31 +- Inspect rendered prompt output when changing template wiring or placeholders.
32 +
33 +## Child DOX Index
34 +
35 +No child DOX files.
scripts/AGENTS.md new
+32
@@ -0,0 +1,32 @@
1 +# Scripts DOX
2 +
3 +## Purpose
4 +
5 +- Own maintainer and automation scripts that live outside GitHub workflow directories.
6 +- Keep scripts deterministic, documented by nearby callers, and safe to run in clean checkouts.
7 +
8 +## Ownership
9 +
10 +- `openrouter_release_notes_system_prompt.md` is consumed by `.github/scripts/docker_release_plan.py`.
11 +- Additional repository maintenance scripts belong here when they are not runtime application code.
12 +
13 +## Local Contracts
14 +
15 +- Do not commit secrets, generated credentials, private release notes, or local machine paths.
16 +- Scripts used by CI must have stable inputs and fail with actionable errors.
17 +- Keep script behavior synchronized with `.github/AGENTS.md`, workflow YAML, and tests.
18 +
19 +## Work Guidance
20 +
21 +- Prefer standard library Python or simple shell-compatible assets unless a dependency already exists for the script's runtime.
22 +- Keep prompts and automation inputs concise and version-controlled.
23 +- Update callers when renaming or moving scripts.
24 +
25 +## Verification
26 +
27 +- Run targeted tests for any automation script with coverage.
28 +- For release-note prompt changes, inspect generated output format expectations in `.github/scripts/docker_release_plan.py`.
29 +
30 +## Child DOX Index
31 +
32 +No child DOX files.
skills/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Bundled Skills DOX
2 +
3 +## Purpose
4 +
5 +- Own bundled Agent Zero skills and their agent-facing instructions.
6 +- Keep skill workflows accurate, composable, and safe for runtime loading.
7 +
8 +## Ownership
9 +
10 +- Each direct skill directory owns its `SKILL.md` and any local supporting files.
11 +- Plugin-distributed skills belong under the relevant plugin directory.
12 +- User-local skills belong under `usr/skills/`.
13 +
14 +## Local Contracts
15 +
16 +- Every skill directory must include a `SKILL.md`.
17 +- Skill instructions must be operational and scoped to the skill's purpose.
18 +- Do not include secrets, private user data, or environment-specific credentials.
19 +- Supporting files referenced by a skill must exist relative to that skill directory.
20 +
21 +## Work Guidance
22 +
23 +- Keep skills focused on repeatable workflows that agents should actively follow.
24 +- Prefer updating an existing skill over creating overlapping skill variants.
25 +- When a skill refers to repository paths, commands, or plugin architecture, keep those references current with source and docs.
26 +
27 +## Verification
28 +
29 +- Run skill runtime/import tests after changing skill loading assumptions or skill format.
30 +- Manually read changed `SKILL.md` files for broken relative references.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
skills/a0-contribute-plugin/SKILL.md
+1 -1
@@ -230,7 +230,7 @@ gh pr create \
230
231 ## References
232
233 -- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`
233 +- Plugin architecture: `/a0/plugins/AGENTS.md`
234 - Developer lifecycle guide: `/a0/docs/developer/plugins.md`
235 - Plugin Index repo: https://github.com/agent0ai/a0-plugins
236 - Recommended tags: https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
skills/a0-create-agent/SKILL.md
+1 -1
@@ -22,7 +22,7 @@ Related skills: `/a0/skills/a0-development/SKILL.md` (broader framework guide) |
22 Primary references:
23 - `/a0/agents/_example/` — the canonical reference profile (tool + extension + prompt overrides)
24 - `/a0/agents/default/` — the base profile every other profile inherits from
25 -- `/a0/docs/agents/AGENTS.plugins.md` — plugin-distributed profiles + per-profile config
25 +- `/a0/plugins/AGENTS.md` — plugin-distributed profiles + per-profile config
26
27 ---
28
skills/a0-create-plugin/SKILL.md
+4 -3
@@ -21,9 +21,10 @@ Related skills: `/a0/skills/a0-review-plugin/SKILL.md` | `/a0/skills/a0-contribu
21
22 Primary references:
23 - /a0/AGENTS.md (Full-stack architecture & AgentContext)
24 -- /a0/docs/agents/AGENTS.components.md (Component system deep dive)
25 -- /a0/docs/agents/AGENTS.modals.md (Modal system & CSS conventions)
26 -- /a0/docs/agents/AGENTS.plugins.md (Extension points, plugin.yaml, settings system, Plugin Index)
24 +- /a0/plugins/AGENTS.md (Plugin contract, plugin.yaml, settings, banners, extension contracts, Plugin Index)
25 +- /a0/webui/components/AGENTS.md (Component system and modal component conventions)
26 +- /a0/webui/js/AGENTS.md (Modal stack, API helpers, extension loader)
27 +- /a0/webui/css/AGENTS.md (Modal CSS and shared visual primitives)
28 - /a0/docs/developer/plugins.md (Developer lifecycle and publishing)
29
30 ---
skills/a0-debug-plugin/SKILL.md
+1 -1
@@ -183,5 +183,5 @@ Plugins are re-scanned when:
183
184 ## References
185
186 -- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`
186 +- Plugin architecture: `/a0/plugins/AGENTS.md`
187 - Manage (install/update/uninstall): read `/a0/skills/a0-manage-plugin/SKILL.md`
skills/a0-manage-plugin/SKILL.md
+1 -1
@@ -358,7 +358,7 @@ Plugins with `always_enabled: true` in `plugin.yaml` cannot be toggled (framewor
358
359 ## References
360
361 -- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`
361 +- Plugin architecture: `/a0/plugins/AGENTS.md`
362 - Developer lifecycle guide: `/a0/docs/developer/plugins.md`
363 - Debug a broken plugin: read `/a0/skills/a0-debug-plugin/SKILL.md`
364 - Create a new plugin: read `/a0/skills/a0-create-plugin/SKILL.md`
skills/a0-plugin-router/SKILL.md
+3 -3
@@ -111,7 +111,7 @@ For `@extensible` targets, the only valid implicit hook layout is `extensions/py
111
112 ### Deep-Dive References
113
114 -- Architecture + extension points: `/a0/docs/agents/AGENTS.plugins.md`
114 +- Architecture + extension points: `/a0/plugins/AGENTS.md`
115 - Developer guide: `/a0/docs/developer/plugins.md`
116 -- Component system: `/a0/docs/agents/AGENTS.components.md`
117 -- Modal system: `/a0/docs/agents/AGENTS.modals.md`
116 +- Component system: `/a0/webui/components/AGENTS.md`
117 +- Modal system: `/a0/webui/js/AGENTS.md` and `/a0/webui/css/AGENTS.md`
skills/a0-review-plugin/SKILL.md
+2 -2
@@ -168,7 +168,7 @@ Fix required: version missing in plugin.yaml, inline error box in webui/settings
168 ## References
169
170 - Detailed pattern checklists: read `checklists.md` in this skill directory
171 -- Plugin architecture: `/a0/docs/agents/AGENTS.plugins.md`
171 +- Plugin architecture: `/a0/plugins/AGENTS.md`
172 - Developer lifecycle guide: `/a0/docs/developer/plugins.md`
173 -- Component system: `/a0/docs/agents/AGENTS.components.md`
173 +- Component system: `/a0/webui/components/AGENTS.md`
174 - If review passes and user wants to publish: read `/a0/skills/a0-contribute-plugin/SKILL.md`
tests/AGENTS.md new
+34
@@ -0,0 +1,34 @@
1 +# Tests DOX
2 +
3 +## Purpose
4 +
5 +- Own pytest regression, security, integration, and contract tests.
6 +- Keep tests focused on behavior that should remain stable across framework changes.
7 +
8 +## Ownership
9 +
10 +- Test files live directly under `tests/` and are named for the behavior or subsystem they cover.
11 +- Shared fixtures should be added only when multiple tests need them.
12 +- Runtime artifacts created during tests should use pytest temporary directories or existing isolated test helpers.
13 +
14 +## Local Contracts
15 +
16 +- Tests must not require real API keys, network-only services, private user data, or local `usr/` runtime state.
17 +- Keep tests deterministic and isolated from existing chats, uploads, downloads, memory, and settings.
18 +- Prefer exercising public helper/API contracts over fragile implementation details when practical.
19 +- Security regression tests should assert the protected behavior directly.
20 +
21 +## Work Guidance
22 +
23 +- Add focused tests near the affected subsystem's existing tests.
24 +- Use descriptive test names that state the regression or contract.
25 +- Avoid broad sleeps or real-time dependencies; use monkeypatching or controlled clocks where possible.
26 +
27 +## Verification
28 +
29 +- Run `pytest` for broad changes.
30 +- Run `pytest tests/test_name.py` for narrow changes and mention any broader test gaps at closeout.
31 +
32 +## Child DOX Index
33 +
34 +No child DOX files.
tools/AGENTS.md new
+35
@@ -0,0 +1,35 @@
1 +# Agent Tools DOX
2 +
3 +## Purpose
4 +
5 +- Own core agent tool implementations available to Agent Zero agents.
6 +- Keep tool execution contracts, progress logging, intervention handling, and tool-result formatting stable.
7 +
8 +## Ownership
9 +
10 +- Tool modules in this directory are discovered by the framework and should define `Tool` subclasses.
11 +- Shared tool base classes and response contracts live in `helpers/tool.py`.
12 +- Plugin-specific tools belong in plugin `tools/` directories.
13 +
14 +## Local Contracts
15 +
16 +- Tools must derive from `helpers.tool.Tool` and implement `async def execute(...)`.
17 +- Return `helpers.tool.Response(message=..., break_loop=...)`.
18 +- Use `await self.agent.handle_intervention(...)` when a long-running or external result should respect pause/intervention flow.
19 +- Sanitize or mask secrets before logging, returning, or storing tool outputs.
20 +- Do not perform destructive filesystem or network actions without the tool contract making that behavior explicit.
21 +
22 +## Work Guidance
23 +
24 +- Keep tool output concise enough for message history while preserving actionable detail.
25 +- Put reusable parsing, provider, filesystem, or network logic in `helpers/`.
26 +- Update prompt tool instructions when changing tool names, arguments, or behavior.
27 +
28 +## Verification
29 +
30 +- Run targeted tool tests after changing a tool or its prompt contract.
31 +- Run prompt/snapshot tests when tool instructions or output shape changes.
32 +
33 +## Child DOX Index
34 +
35 +No child DOX files.
webui/AGENTS.md new
+50
@@ -0,0 +1,50 @@
1 +# WebUI DOX
2 +
3 +## Purpose
4 +
5 +- Own the Flask-served Alpine.js WebUI shell, frontend modules, components, CSS, static assets, and vendored browser libraries.
6 +- Keep the UI coherent with backend APIs, WebSocket state, plugin extension points, and documented frontend patterns.
7 +
8 +## Ownership
9 +
10 +- `index.html`, `index.js`, and `index.css` define the main UI shell.
11 +- `components/` owns self-contained Alpine components and component stores.
12 +- `js/` owns shared frontend modules, API clients, WebSocket clients, stores, extension loaders, and utility code.
13 +- `css/` owns shared stylesheet modules.
14 +- `public/` owns first-party static image/icon assets.
15 +- `vendor/` owns vendored third-party browser libraries.
16 +
17 +## Local Contracts
18 +
19 +- Store-dependent UI must be gated with `x-data` and `x-if="$store.storeName"` before using the store.
20 +- Use `createStore` from `/js/AlpineStore.js` for frontend stores.
21 +- Use `openModal(path)` and `closeModal()` from `/js/modals.js` for modal flows.
22 +- Use `/js/api.js` helpers so CSRF and auth behavior stays consistent.
23 +- Component tags use `<x-component path="...">`; paths are resolved under `webui/components/` when not already prefixed.
24 +- Frontend extension breakpoints use `<x-extension id="...">` and are loaded through `/js/extensions.js`.
25 +- Component HTML loaded by the shared loader may include `<title>`, module scripts, body content, and scoped styles; modal content uses the same loader path.
26 +- Do not bypass WebSocket origin/auth/CSRF assumptions from frontend code.
27 +- Avoid editing vendored files unless intentionally updating the vendor asset.
28 +
29 +## Work Guidance
30 +
31 +- Put component-specific markup and styles under `components/`; put reusable frontend infrastructure under `js/`; put shared visual primitives under `css/`.
32 +- Keep UI text and controls consistent with existing components.
33 +- Use notifications for user-facing success, warning, and error feedback where the app already uses notification flows.
34 +- Coordinate API payload changes with backend handlers and tests.
35 +
36 +## Verification
37 +
38 +- Run targeted WebUI/frontend tests when available.
39 +- Manually smoke-test visible UI changes with `python run_ui.py` when behavior cannot be covered by tests.
40 +- Verify desktop and mobile layout for substantial UI changes.
41 +
42 +## Child DOX Index
43 +
44 +Direct child DOX files:
45 +
46 +| Child | Scope |
47 +| --- | --- |
48 +| [components/AGENTS.md](components/AGENTS.md) | Alpine component HTML, component stores, and component-local styles. |
49 +| [css/AGENTS.md](css/AGENTS.md) | Shared WebUI stylesheet modules. |
50 +| [js/AGENTS.md](js/AGENTS.md) | Shared frontend JavaScript modules and client-side infrastructure. |
webui/components/AGENTS.md new
+59
@@ -0,0 +1,59 @@
1 +# WebUI Components DOX
2 +
3 +## Purpose
4 +
5 +- Own self-contained Alpine.js components, component stores, and component-local styles.
6 +- Keep component lifecycle, store registration, and nested component loading consistent.
7 +
8 +## Ownership
9 +
10 +- Each subdirectory owns a UI feature area such as sidebar, settings, projects, notifications, plugins, canvas, or welcome screens.
11 +- `*-store.js` files own component state and actions.
12 +- Component HTML files own their markup, local module imports, and local scoped styles.
13 +- `_examples/` contains reference implementations for component and store shape.
14 +- Modal components normally live under `modals/<name>/<name>.html`; settings components live under `settings/`.
15 +
16 +## Local Contracts
17 +
18 +- Module imports belong in the component `<head>`.
19 +- Module scripts must use `type="module"` and import stores before Alpine evaluates bindings.
20 +- Rendered content belongs in the component `<body>`.
21 +- Wrap store-dependent content with `x-data` and a `template x-if="$store.name"` gate.
22 +- A gated `<template>` must contain one root element.
23 +- Keep component-specific styles in the component `<style>` block; use shared CSS only for primitives that are genuinely reused.
24 +- Use CSS variables from `index.css` for color, spacing, typography, borders, and transitions.
25 +- Use `x-create` for per-mount setup and `x-destroy` for cleanup; do not call long-lived store `init()` from `x-init`.
26 +- Store `init()` must be idempotent and guarded when it registers global listeners, intervals, or one-time data.
27 +- Store state can be read as `$store.name` in templates and through direct module imports in JavaScript; avoid `window.Alpine.store()` lookups in component code.
28 +- Use `globalThis.xAttrs(element)` only for explicit parent `<x-component>` attribute inheritance.
29 +- Use shared API, modal, notification, confirmation, and store helpers instead of ad hoc globals.
30 +- Components that use polling directives may use `x-every-second`, `x-every-minute`, or `x-every-hour` only while mounted.
31 +- Use `$confirmClick` for destructive two-click confirmations where the existing UI pattern fits.
32 +- Name component files `feature-name.html` and stores `feature-store.js` or `feature-name-store.js`.
33 +
34 +## Work Guidance
35 +
36 +- Keep component stores cohesive and avoid cross-component state mutation unless a shared store owns that state.
37 +- Prefer nested `<x-component path="...">` for reusable UI pieces.
38 +- Use absolute imports such as `/components/...` and `/js/...` so loader-generated module URLs resolve reliably.
39 +- Preserve flex layouts through loader wrappers with `display: contents` on the specific wrapper chain when needed.
40 +- Use `callJsonApi()` for JSON-in/JSON-out calls and `fetchApi()` for raw fetches that still need CSRF handling.
41 +- Use `openModal(path)` for modal entry points; modal titles come from component `<title>`.
42 +- Add modal footers with `data-modal-footer` so `modals.js` can move them to the pinned footer slot.
43 +- Keep modal footer elements stable after load; conditional footers should not be repeatedly created and destroyed.
44 +- Use `.modal-floating` only for non-blocking utility panels where page clicks must pass through; do not use it for destructive confirmations, settings, auth, import/export, or required workflows.
45 +- Do not add `document.addEventListener("alpine:init", ...)` blocks inside component HTML.
46 +- Do not use legacy `x-teleport` plus `.modal-overlay` modal patterns for new work.
47 +- Do not introduce a second modal overlay system or manually reshape `.modal-inner`, `.modal-scroll`, or `.modal-footer-slot`.
48 +- Do not hide fetch, import, or lifecycle errors with broad `.catch(() => null)` handlers; surface failures through notifications or console errors as appropriate.
49 +- Do not store sensitive modal values in long-lived stores without explicit cleanup on close.
50 +
51 +## Verification
52 +
53 +- Manually exercise the affected component in the WebUI for visible or lifecycle changes.
54 +- Run targeted tests for settings, plugins, notifications, projects, state sync, or other touched flows when available.
55 +- For modal changes, verify open, close button, Escape, click-outside, stacked modal, scroll, and pinned footer behavior.
56 +
57 +## Child DOX Index
58 +
59 +No child DOX files.
webui/css/AGENTS.md new
+45
@@ -0,0 +1,45 @@
1 +# WebUI CSS DOX
2 +
3 +## Purpose
4 +
5 +- Own shared stylesheet modules for the WebUI.
6 +- Keep shared visual primitives stable across components and pages.
7 +
8 +## Ownership
9 +
10 +- Each CSS file owns a named surface or primitive family such as buttons, messages, modals, notifications, scheduler, settings, surfaces, tables, or toast.
11 +- Component-specific styles should usually stay inside the component HTML unless they are intentionally shared.
12 +- `modals.css` owns the shared stacked modal shell, backdrop, scroll area, footer slot, modal button classes, floating/no-backdrop modal behavior, and shared modal section primitives.
13 +- `index.css` defines global theme variables such as `--color-*`, `--spacing-*`, `--font-size-*`, and `--transition-speed`.
14 +
15 +## Local Contracts
16 +
17 +- Use existing CSS variables and naming patterns before introducing new global tokens.
18 +- Avoid broad selectors that unexpectedly restyle plugin UI or unrelated components.
19 +- Keep layout rules responsive and verify text does not overflow fixed controls.
20 +- Shared modal buttons use `btn btn-ok` for positive actions and `btn btn-cancel` for dismissive or negative actions.
21 +- Modal footer action order is positive action first, dismissive or negative action second.
22 +- Modal footers use `.modal-footer` plus `data-modal-footer`; do not redefine `.btn`, `.modal-footer`, `.modal-inner`, or `.modal-scroll` inside components.
23 +- Shared modal sizing keeps `.modal-inner` centered with `width: 90%`, `max-width: 960px`, and `max-height: 90vh`.
24 +- Tall modal bodies must scroll inside `.modal-scroll`; pinned footer content must stay outside that scroll area.
25 +- `.modal-floating` must keep the full-screen shell pointer-transparent while `.modal-inner` remains pointer-active.
26 +- Use `.modal-no-backdrop` only for backdrop suppression without click-through floating behavior.
27 +- Do not add decorative one-note palette changes that conflict with existing WebUI design.
28 +
29 +## Work Guidance
30 +
31 +- Keep shared CSS small and scoped to clear class families.
32 +- Coordinate class renames with all component and plugin references.
33 +- Prefer improving an existing primitive over creating a near-duplicate style family.
34 +- Use component-local styles for unique layouts and shared CSS for repeated primitives such as modal sections, toolbars, buttons, tables, notifications, and surfaces.
35 +- Preserve modal sizing and scrolling expectations: centered `.modal-inner`, constrained viewport height, body scroll inside `.modal-scroll`, and footer outside the scroll area.
36 +
37 +## Verification
38 +
39 +- Manually inspect affected WebUI screens at desktop and mobile widths for shared CSS changes.
40 +- Run visual or frontend tests if the touched style has coverage.
41 +- For modal CSS, test a tall modal, a footer modal, a stacked modal, and a floating modal.
42 +
43 +## Child DOX Index
44 +
45 +No child DOX files.
webui/js/AGENTS.md new
+61
@@ -0,0 +1,61 @@
1 +# WebUI JavaScript DOX
2 +
3 +## Purpose
4 +
5 +- Own shared frontend JavaScript modules, client-side infrastructure, API helpers, WebSocket clients, stores, extension loaders, and UI utilities.
6 +- Keep frontend contracts stable for core UI and plugin extensions.
7 +
8 +## Ownership
9 +
10 +- `AlpineStore.js` owns store creation and persistence helpers.
11 +- `api.js` owns CSRF-aware HTTP helpers.
12 +- `websocket.js` owns browser WebSocket client behavior.
13 +- `extensions.js` owns frontend extension loading.
14 +- `components.js` owns `<x-component>` loading, component caching, module injection, nested component processing, and `globalThis.xAttrs`.
15 +- `modals.js` owns the stacked modal shell, `openModal`, `closeModal`, `scrollModal`, footer relocation, backdrop, and modal z-index behavior.
16 +- `initFw.js` owns Alpine bootstrap and custom lifecycle directives such as `x-create`, `x-destroy`, and periodic `x-every-*` hooks.
17 +- Other modules own focused UI utilities such as modals, messages, safe markdown, shortcuts, TTS/STT, surfaces, and initialization.
18 +
19 +## Local Contracts
20 +
21 +- Use ES modules and browser-compatible JavaScript.
22 +- Route JSON and fetch calls through `api.js` unless a caller has a specific nonstandard transport contract.
23 +- `callJsonApi()` is for JSON request/response flows and must preserve CSRF/auth behavior.
24 +- `fetchApi()` must continue adding CSRF headers, retrying 403 CSRF refresh paths, and redirecting to `/login` when required.
25 +- `createStore(name, model)` must continue working before and after Alpine boots by proxying to the raw model first and Alpine store later.
26 +- `saveState()` and `loadState()` must not persist functions and should support include/exclude filtering for transient fields.
27 +- `openModal(path)` returns a promise that resolves when that modal DOM node is removed; invalid paths show an in-modal error instead of rejecting.
28 +- Opening the same modal path multiple times must continue creating multiple stack entries; no dedupe is assumed.
29 +- `closeModal()` with no path closes the top modal; `closeModal(path)` closes that path wherever it is in the stack; missing paths are no-ops.
30 +- Modal stack semantics are top-modal-first for Escape, close buttons, z-index, and backdrop placement.
31 +- The modal shell structure is `.modal` > `.modal-inner` > `.modal-header`, `.modal-scroll` containing `.modal-bd`, and `.modal-footer-slot`.
32 +- `data-modal-footer` content is relocated from modal body into `.modal-footer-slot`.
33 +- Click-outside close requires both `mousedown` and `mouseup` on the outer `.modal` container.
34 +- `scrollModal(id)` scrolls inside the top modal's `.modal-scroll`.
35 +- Keep extension loader cache keys and extension point names stable for plugins.
36 +- HTML extension loading turns discovered HTML files into `<x-component>` tags; JavaScript extensions must export a default function.
37 +- Frontend extension hooks such as `confirm_dialog_after_render` and `get_tool_message_handler` must preserve their mutable context contracts.
38 +- Sanitize or safely render user/model-provided HTML and markdown.
39 +- Do not expose secrets in localStorage, console logs, URLs, or WebSocket payloads.
40 +
41 +## Work Guidance
42 +
43 +- Prefer small named exports over adding globals.
44 +- Keep frontend API payload assumptions synchronized with backend handlers.
45 +- Use existing modal, notification, cache, device, and surface utilities before adding new infrastructure.
46 +- Check plugin extension callers before changing shared extension behavior.
47 +- Preserve the single shared modal shell and backdrop model; do not add a parallel overlay implementation.
48 +- Preserve modal z-index spacing with a stable base stack and a shared backdrop below the active modal.
49 +- If opening a new modal from a close handler, schedule it with `requestAnimationFrame` to avoid stack removal races.
50 +- Keep modal state cleanup explicit because stores can outlive their DOM.
51 +- Device-specific styling may rely on the `device-touch` or `device-mouse` body class set during initialization.
52 +
53 +## Verification
54 +
55 +- Run targeted frontend/WebUI tests when available.
56 +- Manually smoke-test startup, API calls, WebSocket state sync, and affected UI flows after infrastructure changes.
57 +- For modal infrastructure, verify duplicate paths can stack, missing paths stay closable, Escape closes only the top modal, and click-outside requires both mouse down and mouse up on the overlay container.
58 +
59 +## Child DOX Index
60 +
61 +No child DOX files.