@samitouri / QOSami_Agents_Zero-2 / commits / 82ae8d50

Subdivide root DOX guidance

Trim the root AGENTS.md to project-wide contracts and the top-level child index. Move Docker runtime and GitHub release details into their owning child DOX files.

Alessandro committed Jul 10, 2026 at 18:38 UTC 82ae8d50e0390eb5f1836e0ddf2cd31c021b6bb3

3 files changed +66 -344

.github/AGENTS.md

+5 -2

@@ -9,13 +9,16 @@

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.

12 +- This file owns release automation rules; user-facing release documentation belongs under `docs/`.

14 ## Local Contracts

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 +- On `main`, the newest eligible tag publishes both the version tag and `latest`, then creates or updates its GitHub release after the image push succeeds; other allowed branches publish only their branch tag.

19 +- Manual dispatch without a tag backfills missing Docker Hub tags. Manual dispatch with a tag rebuilds that target and refreshes `latest` and the GitHub release only when it remains the newest eligible tag on `main`.

20 - Release-note generation reads `scripts/openrouter_release_notes_system_prompt.md` from the repository root and requires OpenRouter credentials from workflow environment variables.

21 +- Release notes compare against the previous published GitHub release tag and fall back to `No release notes.` when no meaningful summary is generated.

22 - Keep workflow secrets in GitHub Actions secrets or environment variables. Do not commit credentials, tokens, or generated release bodies containing private data.

23 - Workflow scripts must fail loudly with actionable messages when required environment variables or git refs are missing.

@@ -23,7 +26,7 @@

27 - Prefer deterministic, testable Python for workflow planning logic instead of complex inline shell in YAML.

28 - 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.

29 +- Keep branch, tag, and release behavior synchronized between workflow YAML, release scripts, tests, and user-facing release documentation.

31 ## Verification

AGENTS.md

+59 -341

@@ -1,365 +1,83 @@

1 -# Agent Zero - AGENTS.md

1 +# Agent Zero DOX

3 -[Generated using reconnaissance on 2026-02-22]

3 +## Purpose

5 -## Quick Reference

7 -Dev Server: python run_ui.py (discover host/port from startup output or runtime configuration; do not assume a default port)

8 -Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)

9 -Documentation: README.md | docs/

10 -Frontend & Plugin DOX: [WebUI](webui/AGENTS.md) | [Components](webui/components/AGENTS.md) | [Frontend JS](webui/js/AGENTS.md) | [Plugins](plugins/AGENTS.md)

5 +- Own project-wide engineering rules and the top-level DOX index.

6 +- Keep detailed contracts in the closest applicable child `AGENTS.md`.

12 ----

8 +## Project

14 -## Table of Contents

15 -1. [Project Overview](#project-overview)

16 -2. [Core Commands](#core-commands)

17 -3. [Docker Environment](#docker-environment)

18 -4. [Project Structure](#project-structure)

19 -5. [Development Patterns & Conventions](#development-patterns--conventions)

20 -6. [Safety and Permissions](#safety-and-permissions)

21 -7. [Code Examples](#code-examples)

22 -8. [Git Workflow](#git-workflow)

23 -9. [Release Notes](#release-notes)

24 -10. [Troubleshooting](#troubleshooting)

10 +- Stack: Python 3.12+ framework, Python 3.13 agent execution runtime, Flask, Alpine.js, LiteLLM, and Socket.IO.

11 +- Start the WebUI with `python run_ui.py`; discover its URL from startup output, Docker mappings, or explicit configuration rather than assuming a port.

12 +- Run the full test suite with `pytest` or a focused file with `pytest tests/test_name.py`.

13 +- Human-facing documentation lives in `README.md` and `docs/`.

26 ----

15 +## Root Ownership

28 -## Project Overview

17 +- `agent.py` owns `Agent`, `AgentContext`, and loop data.

18 +- `initialize.py` owns framework initialization.

19 +- `models.py` owns model-provider configuration and LiteLLM integration.

20 +- `run_ui.py` is the WebUI entry point.

21 +- `DockerfileLocal` must remain compatible with the contracts under `docker/`.

22 +- Runtime or user state under `usr/` and `tmp/` is intentionally outside tracked DOX unless the user explicitly asks otherwise.

30 -Agent Zero is a dynamic, organic agentic framework designed to grow and learn. It uses the operating system as a tool, featuring a multi-agent cooperation model where every agent can create subordinates to break down tasks.

24 +## Project-Wide Contracts

32 -Type: Full-Stack Agentic Framework (Python Backend + Alpine.js Frontend)

33 -Status: Active Development

34 -Primary Language(s): Python, JavaScript (ES Modules)

26 +- Import `AgentContext` and `AgentContextType` from `agent`, not `helpers.context`.

27 +- Never commit secrets, `.env` files, API keys, tokens, or private user data.

28 +- Preserve authentication and CSRF protections.

29 +- Use Linux paths and commands in examples.

30 +- Treat the Docker container exposed at `localhost:32080` as the live plugin/backend runtime when that target is named.

31 +- Copy live core-plugin changes back into tracked source under `plugins/`.

32 +- Develop new custom plugins under ignored `usr/plugins/`; tracked bundled plugins live under `plugins/`.

33 +- Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime.

36 ----

35 +## Permissions

38 -## Core Commands

37 +Allowed without asking:

40 -### Setup

41 -Do not combine these commands; run them individually:

42 -```bash

43 -pip install -r requirements.txt

44 -```

45 -- Start WebUI: python run_ui.py

46 -- Discover the WebUI URL from startup output, launcher/Docker port mappings, or explicit `--host`/`--port`/`WEB_UI_PORT` configuration; do not hardcode a default port.

39 +- Read repository files.

40 +- Update files under `usr/`.

48 ----

42 +Ask before:

50 -## Docker Environment

44 +- Installing dependencies.

45 +- Deleting core files outside `usr/` or `tmp/`.

46 +- Modifying `agent.py` or `initialize.py`.

47 +- Creating commits or pushing branches.

52 -When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework itself from code executed on behalf of the agent:

49 +## DOX Workflow

54 -### 1. Framework Runtime (/opt/venv-a0)

55 -- Version: Python 3.12.4

56 -- Purpose: Runs the Agent Zero framework itself: WebUI backend, API, core loop, scheduler, framework imports, and plugin hooks/tools that execute inside the framework process.

57 -- Packages: Contains framework dependencies from requirements.txt.

58 -- Verification: Use this runtime for framework/backend import checks, WebUI startup checks, and plugin hook behavior unless the code explicitly switches environments.

59 -

60 -### 2. Agent Execution Runtime (/opt/venv)

61 -- Version: Python 3.13

62 -- Purpose: Default Python environment for the agent's terminal/code-execution tasks and user code run by the agent.

63 -- Behavior: Packages installed by the agent during a task belong here so task dependencies do not pollute or prove the framework runtime. Do not use this runtime as evidence that framework imports, WebUI startup, or plugin hooks work.

64 -

65 ----

66 -

67 -## Project Structure

68 -

69 -```

70 -/

71 -├── agent.py # Core Agent and AgentContext definitions

72 -├── initialize.py # Framework initialization logic

73 -├── models.py # LLM provider configurations

74 -├── run_ui.py # WebUI server entry point

75 -├── api/ # API Handlers (ApiHandler subclasses) + WsHandler subclasses (ws_*.py)

76 -├── extensions/ # Backend lifecycle extensions

77 -├── helpers/ # Shared Python utilities (plugins, files, etc.)

78 -├── tools/ # Agent tools (Tool subclasses)

79 -├── webui/

80 -│ ├── components/ # Alpine.js components

81 -│ ├── js/ # Core frontend logic (modals, stores, etc.)

82 -│ └── index.html # Main UI shell

83 -├── usr/ # User data directory (isolated from core)

84 -│ ├── plugins/ # Custom user plugins

85 -│ ├── settings.json # User-specific configuration

86 -│ └── workdir/ # Default agent workspace

87 -├── plugins/ # Core system plugins

88 -├── agents/ # Agent profiles (prompts and config)

89 -├── prompts/ # System and message prompt templates

90 -├── knowledge/

91 -│ └── main/about/ # Agent self-knowledge reference material

92 -│ ├── identity.md # Philosophy, principles, project context

93 -│ ├── architecture.md # Agent loop, multi-agent coordination, extensions

94 -│ ├── capabilities.md # Detailed capabilities and limitations

95 -│ ├── configuration.md # LLM roles, providers, profiles, plugins, settings

96 -│ └── setup-and-deployment.md # Docker deployment, updates, troubleshooting

97 -└── tests/ # Pytest suite

98 -```

99 -

100 -Key Files:

101 -- agent.py: Defines AgentContext, LoopData virtual prompt areas (Protocol before history and Extras after history), and the main Agent class.

102 -- helpers/plugins.py: Plugin discovery and configuration logic.

103 -- webui/js/AlpineStore.js: Store factory for reactive frontend state.

104 -- helpers/api.py: Base class for all API endpoints.

105 -- models.py: LLM provider configuration and LiteLLM wrappers; framework LiteLLM defaults such as `drop_params=True` are merged with `litellm_global_kwargs`, configured values override framework defaults, documented module-level switches such as `drop_params` are applied to LiteLLM, and merged kwargs are passed per call.

106 -- scripts/openrouter_release_notes_system_prompt.md: Editable system prompt used to generate GitHub release notes during Docker publishing.

107 -- knowledge/main/about/: Agent self-knowledge files. Not user-facing docs - written for the agent's internal reference.

108 -- webui/components/AGENTS.md: DOX contract for Alpine component architecture.

109 -- webui/js/AGENTS.md: DOX contract for frontend infrastructure, modal stack, API helpers, and extension loading.

110 -- plugins/AGENTS.md: DOX contract for bundled and custom plugin architecture; `usr/plugins/` remains ignored user state.

111 -

112 ----

113 -

114 -## Development Patterns & Conventions

115 -

116 -### Backend (Python)

117 -- Context Access: Use from agent import AgentContext, AgentContextType (not helpers.context).

118 -- Communication: Use mq from helpers.messages to log proactive UI messages:

119 - mq.log_user_message(context.id, "Message", source="Plugin")

120 -- API Handlers: Derive from ApiHandler in helpers/api.py.

121 -- Extensions: Use the extension framework in helpers/extension.py for lifecycle hooks.

122 -- Error Handling: Use RepairableException for errors the LLM might be able to fix.

123 -

124 -### Frontend (Alpine.js)

125 -- Store Gating: Always wrap store-dependent content in a template:

126 -```html

127 -<div x-data>

128 - <template x-if="$store.myStore">

129 - <div x-init="$store.myStore.onOpen()">...</div>

130 - </template>

131 -</div>

132 -```

133 -- Store Registration: Use createStore from /js/AlpineStore.js.

134 -- Template Expression Scope: Keep Alpine attributes declarative: property reads, bindings, guards, and short method calls. Put object or array construction, cloning, multi-step mutation, async workflows, and reusable behavior in named JavaScript store or component methods; simple toggles and assignments may stay inline.

135 -- Modals: Use openModal(path) and closeModal() from /js/modals.js.

136 -

137 -### Plugin Architecture

138 -- Location: Always develop new plugins in usr/plugins/.

139 -- Manifest: Every plugin requires a plugin.yaml with name, description, version, and optionally settings_sections, per_project_config, per_agent_config, and always_enabled.

140 -- Discovery: Conventions based on folder names (api/, tools/, webui/, extensions/).

141 -- Plugin-local Python imports: Prefer `usr.plugins.<plugin_name>...` for code that lives under `usr/plugins/`. Avoid `sys.path` hacks and avoid symlink-dependent `plugins.<plugin_name>...` imports for community plugins.

142 -- Runtime hooks: Plugins may also expose hooks in hooks.py, callable by the framework through helpers.plugins.call_plugin_hook(...).

143 -- Hook runtime: hooks.py executes inside the Agent Zero framework Python environment, so sys.executable -m pip installs dependencies into that same framework runtime.

144 -- Environment targeting: If a plugin needs packages or binaries for the separate agent execution runtime or system environment, it must explicitly switch environments in a subprocess by targeting the correct interpreter, virtualenv, or package manager.

145 -- Settings: Use get_plugin_config(plugin_name, agent=agent) to retrieve settings. Plugins can expose a UI for settings via webui/config.html. Plugin settings modals instantiate a local context from $store.pluginSettingsPrototype; bind plugin fields to config.* and use context.* for modal-level state and actions.

146 -- Activation: Global and scoped activation rules are stored as .toggle-1 (ON) and .toggle-0 (OFF). Scoped rules are handled via the plugin "Switch" modal.

147 -- Cleanup rule: Plugins should not permanently modify the system in ways that outlive the plugin. Deleting a plugin should not leave behind symlinks, unmanaged services, or stray files outside plugin-owned paths unless the user explicitly requested that behavior.

148 -

149 -### Releases

150 -- Docker publishing automation lives in `.github/workflows/docker-publish.yml`.

151 -- Releasable tags follow `v{X}.{Y}` and only tags `>= v1.0` are considered by the workflow.

152 -- The latest eligible tag on `main` also creates or updates a GitHub release after the Docker image push succeeds.

153 -- GitHub release notes are generated on the fly in `.github/scripts/docker_release_plan.py` by comparing the new tag against the previous published GitHub release tag, collecting commit subjects and descriptions in that range, and sending them to OpenRouter.

154 -- The OpenRouter call uses `OPENROUTER_API_KEY` and `OPENROUTER_MODEL_NAME` from the workflow environment, with the system prompt stored in `scripts/openrouter_release_notes_system_prompt.md`.

155 -- Prioritize user-visible features, important fixes, infra or packaging changes, and breaking notes. Skip low-signal churn.

156 -- If the generated summary has no meaningful content, the release body falls back to `No release notes.`

157 -

158 -### Lifecycle Synchronization

159 -| Action | Backend Extension | Frontend Lifecycle |

160 -|---|---|---|

161 -| Initialization | agent_init | init() in Store |

162 -| Mounting | N/A | x-create directive |

163 -| Processing | monologue_start/end | UI loading state |

164 -| Cleanup | context_deleted | x-destroy directive |

165 -

166 ----

167 -

168 -## Safety and Permissions

169 -

170 -### Allowed Without Asking

171 -- Read any file in the repository.

172 -- Update code files in usr/.

173 -

174 -### Ask Before Executing

175 -- pip install (new dependencies).

176 -- Deleting core files outside of usr/ or tmp/.

177 -- Modifying agent.py or initialize.py.

178 -- Making git commits or pushes.

179 -

180 -### Never Do

181 -- Commit, hardcode or leak secrets or .env files.

182 -- Bypass CSRF or authentication checks.

183 -- Hardcode API keys.

184 -

185 ----

186 -

187 -## Code Examples

188 -

189 -### API Handler (Good)

190 -```python

191 -from helpers.api import ApiHandler, Request, Response

192 -

193 -class MyHandler(ApiHandler):

194 - async def process(self, input: dict, request: Request) -> dict | Response:

195 - # Business logic here

196 - return {"ok": True, "data": "result"}

197 -```

198 -

199 -### Alpine Store (Good)

200 -```javascript

201 -import { createStore } from "/js/AlpineStore.js";

202 -

203 -export const store = createStore("myStore", {

204 - items: [],

205 - init() { /* global setup */ },

206 - onOpen() { /* mount setup */ },

207 - cleanup() { /* unmount cleanup */ }

208 -});

209 -```

210 -

211 -### Tool Definition (Good)

212 -```python

213 -from helpers.tool import Tool, Response

214 -

215 -class MyTool(Tool):

216 - async def execute(self, **kwargs):

217 - # Tool logic

218 - return Response(message="Success", break_loop=False)

219 -```

220 -

221 ----

222 -

223 -## Git Workflow

224 -

225 -- Docker publish automation lives in `.github/workflows/docker-publish.yml`.

226 -- Release tags handled by automation must match `vX.Y` and be `>= v1.0`.

227 -- Allowed release branches are configured at the top of the workflow. `main` publishes `<tag>` and `latest`; other allowed branches publish only the branch tag.

228 -- Manual dispatch accepts an optional tag. Without a tag it backfills missing Docker Hub tags. With a tag it rebuilds that exact target and only refreshes `latest` and the GitHub release when that tag is still the newest eligible tag on `main`.

229 -

230 ----

231 -

232 -## Release Notes

233 -

234 -- The latest eligible `main` tag generates its GitHub release notes during Docker publish instead of reading committed Markdown files.

235 -- The release-note prompt is editable in `scripts/openrouter_release_notes_system_prompt.md`.

236 -- The commit range starts at the previous published GitHub release tag, not merely the previous semantic tag in the repository.

237 -

238 -## Troubleshooting

239 -

240 -### Dependency Conflicts

241 -If pip install fails, try running in a clean virtual environment:

242 -```bash

243 -python -m venv .venv

244 -source .venv/bin/activate

245 -pip install -r requirements.txt

246 -```

247 -

248 -### WebSocket Connection Failures

249 -- Check if X-CSRF-Token is being sent.

250 -- Ensure the runtime ID in the session matches the current server instance.

251 -

252 ----

253 -

254 -*Last updated: 2026-06-01*

255 -*Maintained by: Agent Zero Core Team*

256 -

257 -

258 -# DOX framework

259 -

260 -- DOX is highly performant AGENTS.md hierarchy installed here

261 -- Agent must follow DOX instructions across any edits

262 -

263 -## Core Contract

264 -

265 -- AGENTS.md files are binding work contracts for their subtrees

266 -- 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

267 -

268 -## Read Before Editing

269 -

270 -1. Read the root AGENTS.md

271 -2. Identify every file or folder you expect to touch

272 -3. Walk from the repository root to each target path

273 -4. Read every AGENTS.md found along each route

274 -5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there

275 -6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules

276 -7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX

277 -

278 -Do not rely on prior context. Re-read the applicable DOX chain in the current session before editing.

279 -

280 -## Update After Editing

281 -

282 -Every meaningful change requires a DOX pass before the task is done.

283 -

284 -Update the closest owning AGENTS.md when a change affects:

285 -

286 -- purpose, scope, ownership, or responsibilities

287 -- durable structure, contracts, workflows, or operating rules

288 -- required inputs, outputs, permissions, constraints, side effects, or artifacts

289 -- user preferences about behavior, communication, process, organization, or quality

290 -- AGENTS.md creation, deletion, move, rename, or index contents

291 -

292 -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.

293 -

294 -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.

295 -

296 -## Hierarchy

297 -

298 -- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index

299 -- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index

300 -- Each parent explains what its direct children cover and what stays owned by the parent

301 -- The closer a doc is to the work, the more specific and practical it must be

302 -

303 -## Child Doc Shape

304 -

305 -- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards

306 -- 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

307 -- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists

308 -

309 -Default section order:

310 -- Purpose

311 -- Ownership

312 -- Local Contracts

313 -- Work Guidance

314 -- Verification

315 -- Child DOX Index

316 -

317 -## Style

318 -

319 -- Keep docs concise, current, and operational

320 -- Document stable contracts, not diary entries

321 -- Put broad rules in parent docs and concrete details in child docs

322 -- Prefer direct bullets with explicit names

323 -- Do not duplicate rules across many files unless each scope needs a local version

324 -- Delete stale notes instead of explaining history

325 -- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist

326 -

327 -## Closeout

328 -

329 -1. Re-check changed paths against the DOX chain

330 -2. Update nearest owning docs and any affected parents or children

331 -3. Refresh every affected Child DOX Index

332 -4. Remove stale or contradictory text

333 -5. Run existing verification when relevant

334 -6. Report any docs intentionally left unchanged and why

335 -

336 -## User Preferences

337 -

338 -- Do not document changes in `usr/` or `tmp/`; treat both as ignored runtime/user-state folders unless explicitly requested otherwise.

51 +- `AGENTS.md` files are binding contracts for their subtrees.

52 +- Before editing, read this file and every `AGENTS.md` on the path to each target; the closest contract controls local details without weakening parent rules.

53 +- Keep work understandable from the applicable DOX chain. Put project-wide rules here and concrete ownership, workflows, inputs, outputs, side effects, and verification in child docs.

54 +- Create a child `AGENTS.md` only for a durable boundary with distinct ownership or workflow.

55 +- Child docs should use: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index.

56 +- After every meaningful change, re-check the affected paths, update the closest owning docs and indexes, remove stale guidance, and run relevant verification.

57 +- Do not document ignored `usr/` or `tmp/` changes unless explicitly requested.

58 +- Keep DOX concise, current, operational, and free of diary entries or duplicated parent guidance.

60 ## Child DOX Index

342 -Direct child DOX files:

343 -

62 | Child | Scope |

63 | --- | --- |

64 | [.github/AGENTS.md](.github/AGENTS.md) | GitHub Actions workflows and release automation scripts. |

347 -| [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and profile-local tools. |

348 -| [api/AGENTS.md](api/AGENTS.md) | HTTP API handlers and WebSocket handler entry points. |

65 +| [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and tools. |

66 +| [api/AGENTS.md](api/AGENTS.md) | HTTP API and WebSocket handler entry points. |

67 | [conf/AGENTS.md](conf/AGENTS.md) | Repository-shipped configuration defaults and templates. |

350 -| [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, image definitions, and runtime compose files. |

351 -| [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation, developer guides, screenshots, and agent deep dives. |

352 -| [extensions/AGENTS.md](extensions/AGENTS.md) | Core lifecycle extension hook implementations for backend and WebUI surfaces. |

353 -| [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend framework utilities and cross-cutting runtime services. |

354 -| [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge and indexed reference material. |

355 -| [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helper scripts outside the main WebUI bundle. |

356 -| [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins shipped with the framework. |

357 -| [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates loaded by agents and framework workflows. |

358 -| [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts invoked by automation or maintainers. |

359 -| [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills and their agent-facing instructions. |

68 +| [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, images, compose files, and runtime layout. |

69 +| [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation and screenshots. |

70 +| [extensions/AGENTS.md](extensions/AGENTS.md) | Backend and WebUI lifecycle extensions. |

71 +| [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend utilities and runtime services. |

72 +| [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge. |

73 +| [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helpers outside the WebUI bundle. |

74 +| [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins and custom-plugin architecture. |

75 +| [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates. |

76 +| [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts and automation inputs. |

77 +| [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills. |

78 | [tests/AGENTS.md](tests/AGENTS.md) | Pytest regression and contract tests. |

79 | [tools/AGENTS.md](tools/AGENTS.md) | Core agent tool implementations. |

362 -| [webui/AGENTS.md](webui/AGENTS.md) | Flask-served Alpine.js WebUI shell, frontend modules, components, CSS, assets, and vendor libraries. |

80 +| [webui/AGENTS.md](webui/AGENTS.md) | Alpine.js WebUI shell, components, JavaScript, CSS, and assets. |

82 Intentionally unindexed local or generated roots:

@@ -369,6 +87,6 @@ Intentionally unindexed local or generated roots:

87 | `.pytest_cache/`, `__pycache__/` | Generated test and bytecode caches. |

88 | `.vscode/`, `.windsurf/` | Editor-local configuration and assistant metadata. |

89 | `logs/` | Runtime output. |

372 -| `tmp/` | Ignored runtime caches, uploads, and generated working files; do not document changes here unless explicitly requested. |

373 -| `usr/` | Ignored local user data, settings, plugins, uploads, chats, and workdirs; do not document changes here unless explicitly requested. |

374 -| `python/` | Generated or legacy runtime cache mirror; current source lives in root-level `api/`, `helpers/`, `tools/`, and `extensions/`. |

90 +| `tmp/` | Ignored runtime caches, uploads, and generated work. |

91 +| `usr/` | Ignored local user data, settings, plugins, chats, and workdirs. |

92 +| `python/` | Generated or legacy runtime mirror; current source is in root modules and tracked source directories. |

docker/AGENTS.md

+2 -1

@@ -13,7 +13,8 @@

14 ## Local Contracts

16 -- Preserve the two-runtime model documented in the root contract: framework runtime under `/opt/venv-a0` and agent execution runtime under `/opt/venv`.

16 +- Preserve the two-runtime model: the Python 3.12 framework runtime under `/opt/venv-a0` runs the WebUI, APIs, scheduler, framework imports, and plugin hooks; the Python 3.13 agent execution runtime under `/opt/venv` runs agent terminal tasks and user code.

17 +- Verify backend imports and plugin hooks with `/opt/venv-a0`; packages installed into `/opt/venv` do not prove framework compatibility.

18 - Do not bake secrets, local `.env` values, or user data into images.

19 - Keep compose mounts aligned with `usr/`, `logs/`, and other runtime-state expectations.

20 - Image changes that affect GitHub publishing must stay synchronized with `.github/workflows/docker-publish.yml`.