Improve README conversion flow

Lead with a sharper Linux-computer positioning, desktop hero, and scannable feature table.

Put the Launcher first, collapse alternate install paths, add basic troubleshooting, and move starter prompts above the deep dives.

Trim the mid-README Space Agent detour to a footer note while keeping the safety and documentation sections.

.github/AGENTS.md

@@ -0,0 +1,35 @@
+# GitHub Automation DOX
+
+## Purpose
+
+- Own repository automation that runs on GitHub, including workflows and release-planning scripts.
+- Keep CI, Docker publishing, stale issue handling, and release-note generation aligned with repository release rules.
+
+## Ownership
+
+- `workflows/` contains GitHub Actions workflow definitions.
+- `scripts/` contains Python helpers called by workflows.
+- Root-level release rules remain in the root `AGENTS.md`; this file owns automation-specific details.
+
+## Local Contracts
+
+- Docker publishing lives in `workflows/docker-publish.yml` and delegates planning to `scripts/docker_release_plan.py`.
+- Releasable tags are `vX.Y` tags at or above `v1.0`, matching the workflow environment.
+- Release-note generation reads `scripts/openrouter_release_notes_system_prompt.md` from the repository root and requires OpenRouter credentials from workflow environment variables.
+- Keep workflow secrets in GitHub Actions secrets or environment variables. Do not commit credentials, tokens, or generated release bodies containing private data.
+- Workflow scripts must fail loudly with actionable messages when required environment variables or git refs are missing.
+
+## Work Guidance
+
+- Prefer deterministic, testable Python for workflow planning logic instead of complex inline shell in YAML.
+- Preserve manual dispatch behavior when changing Docker publishing.
+- Keep branch, tag, and release behavior synchronized between workflow YAML, release scripts, tests, and root documentation.
+
+## Verification
+
+- Run `pytest tests/test_docker_release_plan.py` after changing Docker publish planning or release workflow behavior.
+- Run targeted tests for any changed script that already has coverage.
+
+## Child DOX Index
+
+No child DOX files.

AGENTS.md

@@ -3,11 +3,11 @@
 [Generated using reconnaissance on 2026-02-22]
 
 ## Quick Reference
-Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)
-Dev Server: python run_ui.py (runs on http://localhost:50001 by default)
+Tech Stack: Framework Python 3.12+ | Agent execution Python 3.13 in Docker | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)
+Dev Server: python run_ui.py (discover host/port from startup output or runtime configuration; do not assume a default port)
 Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)
 Documentation: README.md | docs/
-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)
+Frontend & Plugin DOX: [WebUI](webui/AGENTS.md) | [Components](webui/components/AGENTS.md) | [Frontend JS](webui/js/AGENTS.md) | [Plugins](plugins/AGENTS.md)
 
 ---
 
@@ -41,25 +41,26 @@ Primary Language(s): Python, JavaScript (ES Modules)
 Do not combine these commands; run them individually:
 ```bash
 pip install -r requirements.txt
-pip install -r requirements2.txt
 ```
 - Start WebUI: python run_ui.py
+- 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.
 
 ---
 
 ## Docker Environment
 
-When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework from the code being executed:
+When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework itself from code executed on behalf of the agent:
 
 ### 1. Framework Runtime (/opt/venv-a0)
 - Version: Python 3.12.4
-- Purpose: Runs the Agent Zero backend, API, and core logic.
-- Packages: Contains all dependencies from requirements.txt.
+- 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.
+- Packages: Contains framework dependencies from requirements.txt.
+- Verification: Use this runtime for framework/backend import checks, WebUI startup checks, and plugin hook behavior unless the code explicitly switches environments.
 
-### 2. Execution Runtime (/opt/venv)
+### 2. Agent Execution Runtime (/opt/venv)
 - Version: Python 3.13
-- Purpose: Default environment for the interactive terminal and the agent's code execution tool.
-- Behavior: This is the environment active when you docker exec into the container. Packages installed by the agent via pip install during a task are stored here.
+- Purpose: Default Python environment for the agent's terminal/code-execution tasks and user code run by the agent.
+- 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.
 
 ---
 
@@ -87,9 +88,9 @@ When running in Docker, Agent Zero uses two distinct Python runtimes to isolate
 ├── agents/               # Agent profiles (prompts and config)
 ├── prompts/              # System and message prompt templates
 ├── knowledge/
-│   └── main/about/       # Agent self-knowledge (indexed into vector DB for runtime recall)
+│   └── main/about/       # Agent self-knowledge reference material
 │       ├── identity.md           # Philosophy, principles, project context
-│       ├── architecture.md       # Agent loop, memory pipeline, multi-agent, extensions
+│       ├── architecture.md       # Agent loop, multi-agent coordination, extensions
 │       ├── capabilities.md       # Detailed capabilities and limitations
 │       ├── configuration.md      # LLM roles, providers, profiles, plugins, settings
 │       └── setup-and-deployment.md  # Docker deployment, updates, troubleshooting
@@ -97,15 +98,16 @@ When running in Docker, Agent Zero uses two distinct Python runtimes to isolate
 ```
 
 Key Files:
-- agent.py: Defines AgentContext and the main Agent class.
+- agent.py: Defines AgentContext, LoopData virtual prompt areas (Protocol before history and Extras after history), and the main Agent class.
 - helpers/plugins.py: Plugin discovery and configuration logic.
 - webui/js/AlpineStore.js: Store factory for reactive frontend state.
 - helpers/api.py: Base class for all API endpoints.
+- 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.
 - scripts/openrouter_release_notes_system_prompt.md: Editable system prompt used to generate GitHub release notes during Docker publishing.
-- knowledge/main/about/: Agent self-knowledge files, indexed into the vector DB for runtime recall. Not user-facing docs - written for the agent's internal reference.
-- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.
-- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.
-- docs/agents/AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
+- knowledge/main/about/: Agent self-knowledge files. Not user-facing docs - written for the agent's internal reference.
+- webui/components/AGENTS.md: DOX contract for Alpine component architecture.
+- webui/js/AGENTS.md: DOX contract for frontend infrastructure, modal stack, API helpers, and extension loading.
+- plugins/AGENTS.md: DOX contract for bundled and custom plugin architecture; `usr/plugins/` remains ignored user state.
 
 ---
 
@@ -240,7 +242,6 @@ If pip install fails, try running in a clean virtual environment:
 python -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
-pip install -r requirements2.txt
 ```
 
 ### WebSocket Connection Failures
@@ -249,5 +250,124 @@ pip install -r requirements2.txt
 
 ---
 
-*Last updated: 2026-03-25*
+*Last updated: 2026-06-01*
 *Maintained by: Agent Zero Core Team*
+
+
+# DOX framework
+
+- DOX is highly performant AGENTS.md hierarchy installed here
+- Agent must follow DOX instructions across any edits
+
+## Core Contract
+
+- AGENTS.md files are binding work contracts for their subtrees
+- 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
+
+## Read Before Editing
+
+1. Read the root AGENTS.md
+2. Identify every file or folder you expect to touch
+3. Walk from the repository root to each target path
+4. Read every AGENTS.md found along each route
+5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
+6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
+7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX
+
+Do not rely on prior context. Re-read the applicable DOX chain in the current session before editing.
+
+## Update After Editing
+
+Every meaningful change requires a DOX pass before the task is done.
+
+Update the closest owning AGENTS.md when a change affects:
+
+- purpose, scope, ownership, or responsibilities
+- durable structure, contracts, workflows, or operating rules
+- required inputs, outputs, permissions, constraints, side effects, or artifacts
+- user preferences about behavior, communication, process, organization, or quality
+- AGENTS.md creation, deletion, move, rename, or index contents
+
+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.
+
+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.
+
+## Hierarchy
+
+- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
+- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
+- Each parent explains what its direct children cover and what stays owned by the parent
+- The closer a doc is to the work, the more specific and practical it must be
+
+## Child Doc Shape
+
+- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
+- 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
+- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists
+
+Default section order:
+- Purpose
+- Ownership
+- Local Contracts
+- Work Guidance
+- Verification
+- Child DOX Index
+
+## Style
+
+- Keep docs concise, current, and operational
+- Document stable contracts, not diary entries
+- Put broad rules in parent docs and concrete details in child docs
+- Prefer direct bullets with explicit names
+- Do not duplicate rules across many files unless each scope needs a local version
+- Delete stale notes instead of explaining history
+- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist
+
+## Closeout
+
+1. Re-check changed paths against the DOX chain
+2. Update nearest owning docs and any affected parents or children
+3. Refresh every affected Child DOX Index
+4. Remove stale or contradictory text
+5. Run existing verification when relevant
+6. Report any docs intentionally left unchanged and why
+
+## User Preferences
+
+- Do not document changes in `usr/` or `tmp/`; treat both as ignored runtime/user-state folders unless explicitly requested otherwise.
+
+## Child DOX Index
+
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [.github/AGENTS.md](.github/AGENTS.md) | GitHub Actions workflows and release automation scripts. |
+| [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and profile-local tools. |
+| [api/AGENTS.md](api/AGENTS.md) | HTTP API handlers and WebSocket handler entry points. |
+| [conf/AGENTS.md](conf/AGENTS.md) | Repository-shipped configuration defaults and templates. |
+| [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, image definitions, and runtime compose files. |
+| [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation, developer guides, screenshots, and agent deep dives. |
+| [extensions/AGENTS.md](extensions/AGENTS.md) | Core lifecycle extension hook implementations for backend and WebUI surfaces. |
+| [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend framework utilities and cross-cutting runtime services. |
+| [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge and indexed reference material. |
+| [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helper scripts outside the main WebUI bundle. |
+| [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins shipped with the framework. |
+| [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates loaded by agents and framework workflows. |
+| [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts invoked by automation or maintainers. |
+| [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills and their agent-facing instructions. |
+| [tests/AGENTS.md](tests/AGENTS.md) | Pytest regression and contract tests. |
+| [tools/AGENTS.md](tools/AGENTS.md) | Core agent tool implementations. |
+| [webui/AGENTS.md](webui/AGENTS.md) | Flask-served Alpine.js WebUI shell, frontend modules, components, CSS, assets, and vendor libraries. |
+
+Intentionally unindexed local or generated roots:
+
+| Path | Reason |
+| --- | --- |
+| `.conda/`, `.venv/` | Local Python environments. |
+| `.pytest_cache/`, `__pycache__/` | Generated test and bytecode caches. |
+| `.vscode/`, `.windsurf/` | Editor-local configuration and assistant metadata. |
+| `logs/` | Runtime output. |
+| `tmp/` | Ignored runtime caches, uploads, and generated working files; do not document changes here unless explicitly requested. |
+| `usr/` | Ignored local user data, settings, plugins, uploads, chats, and workdirs; do not document changes here unless explicitly requested. |
+| `python/` | Generated or legacy runtime cache mirror; current source lives in root-level `api/`, `helpers/`, `tools/`, and `extensions/`. |

README.md

@@ -3,48 +3,62 @@
 <img src="docs/res/a0-vector-graphics/horizontal_banner.svg" alt="Agent Zero Banner" width="100%"/>
 
 # Agent Zero
-### AI agents with a full Linux system at their fingertips.
+### Give your agent a full Linux computer.
 
-Agent Zero is a dynamic, organic agentic framework for running AI agents that can create tools, write code, browse the web, cooperate with other agents, and keep learning from your goals and projects.
+Agent Zero is an open agent framework for work that needs more than chat: a Dockerized Linux desktop, a browser with DOM annotation, live document cowork, projects, skills, plugins, and a bridge back to your host machine.
 
 [![Website](https://img.shields.io/badge/Website-agent--zero.ai-0A192F?style=for-the-badge&logo=vercel&logoColor=white)](https://agent-zero.ai)
 [![Docs](https://img.shields.io/badge/Docs-Read%20the%20guides-1F6FEB?style=for-the-badge&logo=readthedocs&logoColor=white)](./docs/)
 [![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/B8KZKNsPpj)
 [![GitHub Sponsors](https://img.shields.io/badge/Sponsors-Thank%20you-FF69B4?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/agent0ai)
-
-[Introduction](#what-is-agent-zero) |
-[Space Agent](#agent-zero-and-space-agent) |
-[Quick Start](#how-to-install) |
-[LLM Plans](#use-your-openai-codex-plan) |
-[CLI Connector](#a0-cli-connector-use-agent-zero-on-your-host-machine) |
-[Browser](#native-browser-with-annotations-and-extensions) |
-[Desktop](#linux-desktop-and-libreoffice-cowork) |
-[Features](#what-makes-agent-zero-different) |
-[Examples](#try-these-first) |
-[Docs](#documentation)
-
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/agent0ai/agent-zero)
-[Ask ChatGPT](https://chatgpt.com/?q=Analyze%20this%3A%20https%3A%2F%2Fgithub.com%2Fagent0ai%2Fagent-zero) |
-[Ask Claude](https://claude.ai/new?q=Analyze%20this%3A%20https%3A%2F%2Fgithub.com%2Fagent0ai%2Fagent-zero)
 
+[Quick Start](#quick-start) |
+[Why Agent Zero](#why-agent-zero) |
+[Try These First](#try-these-first) |
+[Deep Dives](#deep-dives) |
+[Docs](#documentation)
 
 </div>
 
 <div align="center">
-<a href="https://www.youtube.com/watch?v=k78HX_RA9Q0&t=19s">
-<img src="docs/res/thumbnail-install.webp" alt="Agent Zero Installation Guide" width="100%"/>
-</a>
+<img alt="Agent Zero driving Blender in its built-in XFCE desktop" src="docs/res/usage/webui/agentzero-xfce-computer.gif" width="100%" />
 </div>
 
-# What Is Agent Zero
+# Why Agent Zero
 
-Agent Zero is not a predefined one-purpose agent.
+| Feature | Why it matters |
+| --- | --- |
+| **Full Linux desktop** | The agent can use real GUI software, terminals, files, and desktop apps inside the Canvas. |
+| **Browser DOM annotation** | Click page elements and turn them into inspect, change, lift, or review instructions. |
+| **Live document cowork** | Edit Markdown, Writer, Spreadsheet, and Presentation files together instead of losing work in chat. |
+| **Plugin Hub** | Install 100+ community plugins or publish your own extension points. |
+| **Projects and memory** | Keep files, instructions, secrets, memories, repositories, and model presets isolated per project. |
+| **Host-machine bridge** | Connect with the A0 CLI so the same agent can work in your real local repositories. |
+| **Multi-agent cooperation** | Let agents delegate research, coding, analysis, or review tasks to focused subagents. |
+| **Transparent internals** | Prompts, tools, plugins, skills, and settings are inspectable and editable. |
 
-It is a transparent, extensible framework where the agent can use the operating system as a tool: a real Linux environment, terminal, code execution, files, memory, browser automation, plugins, and tools it learns to create along the way.
+# Quick Start
 
-The goal is simple: give an AI agent enough environment, memory, communication, and freedom to solve real tasks while keeping the work inspectable and steerable by you.
+## Recommended: A0 Launcher
 
-## How To Install
+The desktop **A0 Launcher** is the fastest guided path on a personal machine. Download it, open it, and let it check Docker, create Instances, manage ports, and connect to local or remote Agent Zero installs.
+
+Agent Zero runs wherever Docker runs, from a $6 VPS or Raspberry Pi to a local workstation or GPU server.
+
+| Architecture | macOS | Linux | Windows |
+| --- | --- | --- | --- |
+| x86 | [Mac Intel](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-macos-x64.dmg) | [Linux x86](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-linux-x64.AppImage) | [Windows x86](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-windows-x64.exe) |
+| ARM64 | [Mac Apple Silicon](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-macos-arm64.dmg) | [Linux ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-linux-arm64.AppImage) | [Windows ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v1.2/a0-launcher-1.2-windows-arm64.exe) |
+
+See the [A0 Launcher v1.2 release](https://github.com/agent0ai/a0-launcher/releases/tag/v1.2) for release notes and updater metadata. See the [Launcher guide](./docs/guides/launcher.md) for the first-run walkthrough.
+
+<details>
+<summary><strong>Other install paths</strong></summary>
+
+## A0 Install
+
+Use **A0 Install** when you want the terminal path: SSH sessions, servers, recovery shells, or a scriptable setup. It creates Dockerized Agent Zero instances, mounts each instance's data into `/a0/usr` inside the container, and uses a reuse-before-setup policy: it tries your current Docker CLI configuration, `DOCKER_HOST`, Docker contexts, and known local Docker-compatible endpoints before setting up a runtime.
 
 ### macOS / Linux
 
@@ -58,89 +72,131 @@ curl -fsSL https://bash.agent-zero.ai | bash
 irm https://ps.agent-zero.ai | iex
 ```
 
-### Docker Desktop already installed? Use this command directly
+### Headless / scripted
+
+For servers and automation, run the installer in Quick Start mode so it creates one instance and exits without opening menus:
+
+```bash
+curl -fsSL https://bash.agent-zero.ai | bash -s -- --quick-start --name agent-zero --port 5080
+```
+
+```powershell
+& ([scriptblock]::Create((irm https://ps.agent-zero.ai))) -QuickStart -Name agent-zero -Port 5080
+```
+
+Use `--skip-runtime-setup` / `-SkipRuntimeSetup` when Docker must already be working and the installer should not try to set up a runtime. See the [A0 Install repository](https://github.com/agent0ai/a0-install) for all installer flags.
+
+## Docker already installed? Run this directly
 
 ```bash
 docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero
 ```
 
-Then open the Web UI, configure your LLM provider, and start with a concrete task. For the full setup path, including updates and platform notes, see the [Installation guide](./docs/setup/installation.md).
+Open the Web UI, configure your LLM provider, and start with a concrete task. For the full setup and onboarding experience, see the [Installation guide](./docs/setup/installation.md).
 
-# What Makes Agent Zero Different
+</details>
 
-## Computer as a Tool
+## Troubleshooting
 
-Agent Zero can use a Kali Linux system to accomplish your task. It can inspect files, run commands, write code, install and use tools, create scripts, search the web, and adapt its workflow as the task evolves.
+- **Docker is not running:** start Docker Desktop or your Docker service, then reopen the Launcher or rerun the install command.
+- **Port 80 is already in use:** use the Launcher to pick another port, or run Docker directly with `-p 5080:80` and open `http://localhost:5080`.
+- **Installing on a server:** use the A0 Install Quick Start command with `--quick-start --name agent-zero --port 5080`.
+- **Still blocked:** see the [Troubleshooting guide](./docs/guides/troubleshooting.md).
 
-The important idea is not a fixed list of buttons. The important idea is that the agent can build and use the right tool when the work demands it.
+# Try These First
 
-## Canvas
+- **Annotate a design you like:** "Open this template site in the Browser. I'll annotate the hero section - re-implement it in my project's React + Tailwind stack."
+- **Cowork on a spreadsheet:** "Create an editable ODS budget model with assumptions and monthly projections."
+- **Drive a desktop app:** "Use the Linux Desktop to open Blender and create a simple 3D logo for me."
+- **Review a web UI:** "Open my local app in the Browser. I will annotate the page with comments; then implement the requested UI fixes."
+- **Create a specialist:** "Create an Agent Profile for financial analysis with cautious reasoning, clear assumptions, and spreadsheet-first deliverables."
+- **Recover a workspace:** "Show me recent Time Travel snapshots and explain what changed before I revert anything."
 
-Agent Zero is becoming more visual and shared. The right-side Canvas gives agents and humans working surfaces for browser sessions, documents, workspace history, and other plugin panels.
+# Deep Dives
 
-The Canvas makes agent work visible. You can watch it browse, inspect what changed, open files, cowork on deliverables, and intervene before a small mistake becomes a large one.
+## A Real Linux Desktop in the Canvas
 
-## Linux Desktop and LibreOffice Cowork
+Agent Zero opens its own Linux desktop inside the right-side Canvas. Not a remote VM, not a shared clipboard, but a real XFCE desktop session running in the container.
 
-<img alt="Agent Zero Desktop Canvas" src="docs/res/usage/webui/desktop-canvas.png" />
+That means the agent can drive *real desktop software*: open Blender to model a 3D object, jump into a terminal window, manage files visually, run a GUI tool that has no API.
+
+You watch every action, and you can intervene at any moment because your mouse and keyboard share the same desktop.
+
+See the [Desktop guide](./docs/guides/desktop.md) for the walkthrough, prompt examples, and how Desktop differs from Browser.
+
+## Native Browser With DOM Annotations
+
+<img alt="Annotating a webpage element in the Agent Zero browser" src="docs/res/usage/browser/annotation.gif" />
 <br>
 
-The Desktop surface opens Agent Zero's own Linux desktop in the Canvas. It is useful when the work needs a real GUI: Linux desktop apps, a terminal window, visual file management, or LibreOffice running where you and the agent can both see it.
+Agent Zero ships a built-in Browser with an optional live surface in the Canvas. The agent can open pages, read them, click, type, upload files, and take screenshots - the usual. The unusual part is **Annotate mode**.
 
-<img alt="Cowork on Documents" width="1406" height="720" src="https://github.com/user-attachments/assets/4ad71888-4f0d-484a-b68b-631ad99187d7" />
+Annotate mode turns any webpage into an interactive directive surface. Click an element to:
+
+- **Change it** - "make this button blue and round the corners" runs as a JS instruction the agent applies and verifies.
+- **Inspect it** - pull the DOM, the styles, the parent chain, the framework hints into the conversation.
+- **Lift it** - see a card, hero, or component on someone else's site that you like? Capture it and have the agent re-implement it in your own project's stack.
+- **Comment it** - leave actionable notes pinned to elements during a UI review; the agent reads the comments and ships the fixes.
+
+The Docker browser is the default live Browser surface. Browser history keeps screenshots of important steps, so older chats can still show what the agent saw. The Browser also supports Chrome extensions inside the Docker browser, and **Bring Your Own Browser** through the A0 CLI Connector lets the agent drive Chrome, Edge, Brave, Opera, Vivaldi, or Chromium on your own machine.
+
+See the [Browser guide](./docs/guides/browser.md) for screenshots, settings, host-browser setup, and troubleshooting.
+
+## Cowork on Documents
+
+### Markdown Editor With Live Cowork
+
+<img alt="Agent Zero writing a TODO plan in the Canvas markdown editor" src="docs/res/usage/webui/markdown-editor.gif" />
 <br>
 
-Create, open, and cowork with the AI on documents, spreadsheets, and presentation decks with the LibreOffice stack.
+The Canvas includes a rich Markdown editor designed for genuine cowork. Ask the agent to "write a plan to do X in a TODO.md in the open doc" and you'll see the file appear in the editor, character by character, while you keep typing in another section.
 
-The Desktop toolbar can create Markdown, Writer, Spreadsheet, and Presentation files. LibreOffice Writer, Calc, and Impress run inside the Desktop, so you can type by hand while Agent Zero creates, updates, saves, and verifies the same files.
+It's not a preview pane. It's a real editor with toolbar, formatting buttons, tables, and an editable source view - built so that the agent's edits and yours are equal first-class operations on the same document.
 
-The document Canvas supports Markdown by default, with LibreOffice-native ODT, ODS, and ODP workflows when binary office artifacts are needed. Microsoft Office compatibility imports and exports remain available when explicitly requested.
+Use it for plans, TODOs, meeting notes, RFCs, project handoffs, or any artifact where the deliverable should *live as text* rather than be trapped inside chat scrollback.
 
-Markdown, Writer, Spreadsheet, and Presentation files share a compact active-file header with save, rename, close, and creation controls in both Canvas and modal views.
+### LibreOffice Integration
 
-See the [Desktop guide](./docs/guides/desktop.md) for the screenshot walkthrough, prompt examples, and how Desktop differs from Browser.
+LibreOffice Writer, Calc, and Impress are wired up so you can type by hand while Agent Zero creates, updates, saves, and verifies the same files in real time.
 
-## Native Browser With Annotations and Extensions
+ODT, ODS, and ODP binary formats are first-class citizens in the Agent Zero Desktop environment to align with the Open Document Format (ODF).
 
-<img alt="Agent Zero Browser Canvas and tool history" src="docs/res/usage/browser/browser-canvas-wide.png" />
+Use the Desktop toolbar to create and edit Writer, Spreadsheet, and Presentation LibreOffice files.
+
+## Plugin Hub - 100+ Community Plugins
+
+<img alt="Agent Zero Plugin Hub showing community plugins" src="docs/res/usage/plugins/plugin-hub-browse.png" />
 <br>
 
-Agent Zero includes a built-in Browser with an optional live surface in the Canvas. The agent can open pages, read them, click, type, upload files, and take screenshots.
+Agent Zero is built for extension, not just configuration. The built-in **Plugin Hub** browses a growing catalog of community plugins - currently more than 100, covering:
 
-The Docker browser is the default live Browser surface. With A0 CLI, Agent Zero can also use **Bring Your Own Browser** to work with Chrome, Edge, or Chromium on your own computer. Open the Browser surface when you want to watch the Docker browser, or ask Agent Zero to show it in the Canvas.
+- **Development frameworks** like the [BMAD Method](https://github.com/bmad-code-org/bmad-method) (full software development lifecycle with 20 specialist agents) and [Agent Skills](https://github.com/addyosmani/agent-skills).
+- **Memory systems** - alternative memory backends, intelligent consolidation strategies, vector recall plugins.
+- **Tools and integrations** - embedded terminals, custom browsers, deployment helpers, API clients.
+- **UI extensions** - chat rename controls, sidebar tweaks, theme packs, custom Canvas panels.
+- **Workflow plugins** - schedulers, multi-agent orchestration, project automations.
 
-Browser history keeps screenshots of important steps, so older chats can still show what the agent saw.
+Install with a click from the Web UI, or publish your own to the index repository. Combined with custom prompts in `prompts/`, custom tools in `tools/`, MCP servers, A2A connectors, and project-scoped configuration, Agent Zero gives you a real surface area to shape the agent into whatever you need.
 
-For web and mobile development, Annotate mode lets you click page elements or regions and leave actionable comments for the agent targeted at the page itself. You can review a UI visually, mark what needs to change, and send those notes straight back into the conversation.
-
-The Browser also supports Chrome extensions inside the Docker browser. See the [Browser guide](./docs/guides/browser.md) for screenshots, settings, host-browser setup, and troubleshooting.
+See the [Skills guide](./docs/guides/skills.md), the [Create a Small Plugin](./docs/guides/create-plugin.md) tutorial, and the [MCP setup](./docs/guides/mcp-setup.md) guide.
 
 ## Use Your OpenAI Codex Plan
 
-Agent Zero can now connect to your OpenAI Codex plan through the new OAuth flow. Sign in with your account, pick the Codex-backed provider, and let Agent Zero use the plan you already have.
-
 <img alt="OAuth LLM plans in Agent Zero" src="docs/res/codex-screenshot.png" />
 <br>
 
-Click "Connect", enter the device code in the OpenAI page. Choose your model after checking the list, and you're all set.
+Agent Zero connects to your OpenAI Codex plan through the new OAuth flow. Sign in with your account, pick the Codex-backed provider, and let Agent Zero use the plan you already have. Click "Connect", enter the device code in the OpenAI page, choose your model, and you're set.
 
-This is the first step toward account-backed LLM plans in Agent Zero. More integrations are coming, including Gemini CLI, Claude Code based on extra-usage, and more.
+This is the first step toward account-backed LLM plans in Agent Zero. More integrations are coming, including Gemini CLI and Claude Code through extra-usage.
 
-# A0 CLI Connector: Use Agent Zero on Your Host Machine
+## A0 CLI Connector: Extend Onto Your Host Machine
 
-The **A0 CLI Connector** is not a separate CLI agent. It connects to a running
-Agent Zero instance and gives that instance a terminal-native bridge to your
-host machine.
-
-Agent Zero stays responsible for the reasoning loop, memory, projects, profiles,
-model choices, and tools. The CLI is how you intentionally let that Agent
-Zero instance work beyond the Docker container: on your host machine, in a
-terminal-first workflow, or against a server where you do not want a GUI at all.
-
-<img alt="A0 CLI Connector connected shell" src="docs/res/usage/a0-cli/a0-cli-start.png" />
+<img alt="A0 CLI driving the host browser through a Google Cloud VM creation flow" src="docs/res/usage/a0-cli/host-browser.gif" />
 <br>
 
-Install the connector on the machine you want Agent Zero to work on, not inside the Agent Zero container.
+The **A0 CLI Connector** is not a separate CLI agent. It connects to a running Agent Zero instance and gives that instance a terminal-native bridge to your host machine - so the same agent (with all its memory, projects, and skills) can also work on real files outside the Docker container.
+
+Install the connector on the machine you want Agent Zero to work on, **not** inside the Agent Zero container.
 
 ### macOS / Linux
 
@@ -154,83 +210,42 @@ curl -LsSf https://cli.agent-zero.ai/install.sh | sh
 irm https://cli.agent-zero.ai/install.ps1 | iex
 ```
 
-Then run:
-
-```bash
-a0
-```
-
-`a0` connects your terminal to an existing Agent Zero instance. It can usually discover a local instance automatically, or you can point it at a remote Agent Zero URL hosted somewhere else, such as a VPS or tunnel.
-
-Inside the shell, use `Ctrl+P` for the command palette, `/chats` to switch work, `/models` or `/presets` to adjust models, and `/browser status` to check Browser mode.
-
-When you activate **Read+Write** access and the **Remote Code Execution Tool** in the CLI, Agent Zero can operate on the filesystem and shell of the machine where `a0` is running. That means it can work on your real local project files, not only files inside the Docker sandbox.
+Then run `a0` to connect your terminal to an existing Agent Zero instance. It can usually discover a local instance automatically, or you can point it at a remote URL hosted somewhere else, such as a VPS or tunnel.
 
 This is especially useful if you:
 
 - prefer CLI workflows;
 - want Agent Zero to work in an existing local repository;
 - are running Agent Zero on a remote server;
-- need code execution on a headless machine without using the Web UI;
-- want Docker isolation for Agent Zero while still granting explicit, controlled access to selected host-side work.
+- want Docker isolation for Agent Zero while still granting explicit, controlled access to host-side work.
 
-For full setup details, manual fallback installation, and remote-host tips, see the [A0 CLI Connector guide](./docs/guides/a0-cli-connector.md).
+For full setup, see the [A0 CLI Connector guide](https://www.agent-zero.ai/p/docs/a0-cli-connector/) (or the [in-repo guide](./docs/guides/a0-cli-connector.md)).
 
+## Projects, Skills, Agent Profiles, and Model Presets
 
-### Projects, Skills, Agent Profiles, and Model Presets
+**Projects** isolate workspaces, instructions, memory, secrets, knowledge, repositories, and model presets. Clone a public or private Git repo into a project and give the agent context that belongs to that work alone.
 
-Projects isolate workspaces, instructions, memory, secrets, knowledge, repositories, and model presets. Clone a public or private Git repo into an isolated project and give the agent context that belongs to that work alone.
+**Skills** can be loaded on demand by Agent Zero, or pinned from the chat input when you want a specific procedure to stay active.
 
-Skills can be loaded on demand by Agent Zero, or pinned from the chat input when
-you want a specific procedure to stay active. Agent Profiles change the broader
-working style of the current chat. Model Presets are named shortcuts for model
-setups, so users can quickly switch between fast, balanced, cheap, local, or
-high-power model choices.
+**Agent Profiles** change the broader working style of the current chat.
 
-### Multi-Agent Cooperation
+**Model Presets** are named shortcuts for model setups, so you can quickly switch between fast, balanced, cheap, local, or high-power model choices.
+
+## Multi-Agent Cooperation
 
 Every agent can create subordinate agents to break down work. The superior gives tasks and receives reports; subagents keep their own contexts focused and return their findings when done.
 
 This makes Agent Zero useful for research, software engineering, data analysis, plugin development, and tasks where several specialized perspectives are better than one overloaded context.
 
-### Transparent and Extensible by Design
+## Transparent and Extensible by Design
 
 Almost nothing is hidden. Prompts live in `prompts/`, tools live in `tools/` or plugins, and built-in behavior can be inspected, changed, replaced, or extended.
 
 Agent Zero supports plugins, MCP, A2A, custom tools, custom prompts, project-scoped configuration, environment-based deployment settings, and a Web UI designed to keep the agent's work readable in real time.
 
-### Also Included
+## Time Travel
 
-- Fully Dockerized runtime with a clean Web UI.
-- Real-time streamed output so you can interrupt, redirect, or refine the work as it happens.
-- Speech-to-text and text-to-speech support through the built-in `_kokoro_tts` and `_whisper_stt` plugins, with browser-native speech synthesis as the fallback output path.
-- Chat load/save, generated HTML logs, file browser, settings UI, and deployment-friendly `A0_SET_` configuration.
-
-## Try These First
-
-- **Research with the Browser tool:** "Use the Browser tool to compare three project management tools for a small AI team, and summarize the tradeoffs with source links."
-- **Cowork on a spreadsheet:** "Create an editable ODS budget model with assumptions and monthly projections."
-- **Review a web UI:** "Open my local app in the Browser. I will annotate the page with comments; then implement the requested UI fixes."
-- **Work inside a Git project:** "Clone this repository into a new project, understand the layout, and propose the safest first improvement."
-- **Create a specialist:** "Create an Agent Profile for financial analysis with cautious reasoning, clear assumptions, and spreadsheet-first deliverables."
-- **Recover a workspace:** "Show me recent Time Travel snapshots and explain what changed before I revert anything."
-
-## Agent Zero and Space Agent
-
-Agent Zero is the open framework and Linux-powered agent workbench.
-
-[Space Agent](https://github.com/agent0ai/space-agent) is our newer product direction for the agent-shaped workspace: a Space the agent can reshape from inside your browser, with live demos, a desktop app, and a path to running a real server for yourself or your team.
-
-<p align="left">
-  <a href="https://www.youtube.com/watch?v=CNRHxEZ8yqs"><img src="https://github.com/agent0ai/space-agent/raw/main/.github/thumbnail.webp" alt="Watch Space Agent on YouTube" width="560" /></a>
-</p>
-
-If you want the raw power and deep customizability of an agent with a full Linux system, start here with Agent Zero. If you want the polished Space experience for easier personal, team, desktop, or self-hosted use, explore [Space Agent](https://github.com/agent0ai/space-agent).
-
-
-## Time Travel (powered by Space Agent)
-
-Time Travel gives Agent Zero-owned `/a0/usr` workspaces snapshot history, diff inspection, travel, and revert. It is designed for recoverable agent work: see what changed, compare files, inspect a past state, and roll back when needed. Try it in Space Agent as well (link above).
+Time Travel gives Agent Zero-owned `/a0/usr` workspaces snapshot history, diff inspection, travel, and revert. It is designed for recoverable agent work: see what changed, compare files, inspect a past state, and roll back when needed.
 
 <img alt="Time Travel" src="docs/res/time-travel.png" />
 
@@ -239,7 +254,8 @@ It is not a replacement for Git or backups. It is a practical safety layer for t
 ## Real-World Use Cases
 
 - **Software engineering:** inspect a codebase, make scoped edits, run tests, explain tradeoffs, and keep a recoverable history of file changes.
-- **Host-machine development:** connect with `a0`, grant Read+Write and remote execution when needed, and let Agent Zero work in your real local repositories.
+- **Host-machine development:** connect with `a0` and let Agent Zero work in your real local repositories, or clone them through Git Projects feature in the Web UI.
+- **Design inspiration and UI iteration:** browse the web, annotate elements you like, and pull components into your own stack.
 - **Financial analysis and charting:** collect data, correlate events, create spreadsheets, and generate editable charts.
 - **Office deliverables:** cowork on documents, spreadsheets, and presentation decks instead of trapping the result in chat text.
 - **Web and mobile QA:** browse an app, annotate UI issues, install browser extensions, and turn visual comments into actionable fixes.
@@ -247,18 +263,6 @@ It is not a replacement for Git or backups. It is a practical safety layer for t
 - **Client/project isolation:** keep memory, secrets, instructions, files, and model choices separated by project.
 - **Scheduled operations:** run recurring checks and monitoring tasks with project-scoped context and credentials.
 
-## Safety Model
-
-Agent Zero is powerful because it can use a real environment. Treat it with the same respect you would give a capable developer with shell access.
-
-- Keep it running inside Docker or another isolated environment.
-- Do not mount your entire home directory unless you understand the risk.
-- Grant A0 CLI Read+Write access and remote code execution only for machines and workspaces you trust.
-- Store credentials in project secrets or settings, not in prompts or public files.
-- Review actions that touch accounts, money, production systems, or private data.
-- Keep backups for important workspaces.
-- Install browser extensions and third-party plugins only from sources you trust.
-
 ## Documentation
 
 | I want to... | Start here |
@@ -267,7 +271,7 @@ Agent Zero is powerful because it can use a real environment. Treat it with the
 | Learn the UI and basic workflow | [Quickstart](./docs/quickstart.md) |
 | Browse, annotate, and use Browser screenshots | [Browser guide](./docs/guides/browser.md) |
 | Use the Linux desktop and LibreOffice | [Desktop guide](./docs/guides/desktop.md) |
-| Connect Agent Zero to host-machine files and shell | [A0 CLI Connector](./docs/guides/a0-cli-connector.md) |
+| Connect Agent Zero to host-machine files and shell | [A0 CLI Connector](https://www.agent-zero.ai/p/docs/a0-cli-connector/) |
 | Use projects and Git workspaces | [Projects guide](./docs/guides/projects.md) |
 | Create a small plugin | [Create a Small Plugin](./docs/guides/create-plugin.md) |
 | Add or remove active skills | [Skills guide](./docs/guides/skills.md) |
@@ -285,7 +289,7 @@ Agent Zero is powerful because it can use a real environment. Treat it with the
 
 Agent Zero is built for people who want to understand and shape their tools.
 
-You can help by improving docs, creating skills, publishing plugins, testing model/provider setups, reporting bugs, sharing workflows, or contributing core improvements. Start with the [Contributing guide](./docs/guides/contribution.md), browse the [Plugin Hub](./docs/guides/usage.md), or bring ideas to Discord.
+You can help by improving docs, creating skills, publishing plugins, testing model/provider setups, reporting bugs, sharing workflows, or contributing core improvements. Start with the [Contributing guide](./docs/guides/contribution.md), browse the [Plugin Hub](https://www.agent-zero.ai/p/docs/plugins/#plugin-hub), or bring ideas to Discord.
 
 ## Community and Support
 
@@ -294,3 +298,16 @@ You can help by improving docs, creating skills, publishing plugins, testing mod
 - [YouTube](https://www.youtube.com/@AgentZeroFW) for demos and tutorials.
 - [X](https://x.com/Agent0ai), [LinkedIn](https://www.linkedin.com/company/109758317), and [Warpcast](https://warpcast.com/agent-zero) for updates.
 - [GitHub Issues](https://github.com/agent0ai/agent-zero/issues) for bugs and feature requests.
+
+[Space Agent](https://github.com/agent0ai/space-agent) is the related, more polished product direction for the agent-shaped workspace. Agent Zero remains the open framework and Linux-powered workbench.
+
+## Safety Model
+
+Agent Zero is powerful because it can use a real environment.
+
+- Keep it running inside Docker or another isolated environment.
+- Do not mount your entire home directory unless you understand the risk.
+- Grant A0 CLI Read+Write access and remote code execution only for machines and workspaces you trust.
+- Store credentials in project secrets or settings, not in prompts or public files.
+- Review actions that touch accounts, money, production systems, or private data.
+- Keep backups for important workspaces.

agent.py

@@ -1,4 +1,4 @@
-import asyncio, random, string, threading
+import asyncio, json, random, re, string, threading
 
 from collections import OrderedDict
 from dataclasses import dataclass, field
@@ -32,6 +32,15 @@ from typing import Callable
 from helpers.localization import Localization
 from helpers import extension
 from helpers.errors import RepairableException, InterventionException, HandledException
+from helpers.llm_result import (
+    LLMResult,
+    RESPONSE_METADATA_KEY,
+    function_call_output_item,
+    metadata_from_llm_result,
+    result_from_metadata,
+)
+from helpers.litellm_transport import ResponsesTransport
+from helpers.responses_tools import build_responses_function_tools, original_tool_name
 
 class AgentContextType(Enum):
     USER = "user"
@@ -329,6 +338,8 @@ class LoopData:
         self.system = []
         self.user_message: history.Message | None = None
         self.history_output: list[history.OutputMessage] = []
+        self.protocol_temporary: OrderedDict[str, history.MessageContent] = OrderedDict()
+        self.protocol_persistent: OrderedDict[str, history.MessageContent] = OrderedDict()
         self.extras_temporary: OrderedDict[str, history.MessageContent] = OrderedDict()
         self.extras_persistent: OrderedDict[str, history.MessageContent] = OrderedDict()
         self.last_response = ""
@@ -346,6 +357,9 @@ class Agent:
     DATA_NAME_SUPERIOR = "_superior"
     DATA_NAME_SUBORDINATE = "_subordinate"
     DATA_NAME_CTX_WINDOW = "ctx_window"
+    DATA_NAME_RESPONSES_STATE = "responses_state"
+    DATA_NAME_RESPONSES_TOOL_NAME_MAP = "responses_tool_name_map"
+    DATA_NAME_RESPONSES_COMPUTER_SESSION = "responses_computer_session_id"
 
     @extension.extensible
     def __init__(
@@ -468,11 +482,12 @@ class Agent:
                                 return stop_response
 
                         # call main LLM
-                        agent_response, _reasoning = await self.call_chat_model(
+                        llm_result = await self.call_chat_model_turn(
                             messages=prompt,
                             response_callback=stream_callback,
                             reasoning_callback=reasoning_callback,
                         )
+                        agent_response = llm_result.response
                         await self.handle_intervention(agent_response)
 
                         # Notify extensions to finalize their stream filters
@@ -492,7 +507,12 @@ class Agent:
                         ):  # if assistant_response is the same as last message in history, let him know
                             # Append the assistant's response to the history
                             log_item = self.loop_data.params_temporary.get("log_item_generating")
-                            self.hist_add_ai_response(agent_response, id=log_item.id if log_item else "")
+                            assistant_message = self.hist_add_ai_response(
+                                agent_response,
+                                id=log_item.id if log_item else "",
+                                llm_result=llm_result,
+                            )
+                            self._remember_llm_result_state(llm_result, assistant_message)
                             # Append warning message to the history
                             warning_msg = self.read_prompt("fw.msg_repeat.md")
                             wmsg = self.hist_add_warning(message=warning_msg)
@@ -504,9 +524,16 @@ class Agent:
                         else:  # otherwise proceed with tool
                             # Append the assistant's response to the history
                             log_item = self.loop_data.params_temporary.get("log_item_generating")
-                            self.hist_add_ai_response(agent_response, id=log_item.id if log_item else "")
+                            assistant_message = self.hist_add_ai_response(
+                                agent_response,
+                                id=log_item.id if log_item else "",
+                                llm_result=llm_result,
+                            )
+                            self._remember_llm_result_state(llm_result, assistant_message)
                             # process tools requested in agent message
-                            tools_result = await self.process_tools(agent_response)
+                            tools_result = await self.process_llm_result_tools(
+                                llm_result
+                            )
                             if tools_result:  # final response of message loop available
                                 return tools_result  # break the execution if the task is done
 
@@ -555,24 +582,28 @@ class Agent:
         # concatenate system prompt
         system_text = "\n\n".join(loop_data.system)
 
-        # join extras
-        extras = history.Message(  # type: ignore[abstract]
-            False,
-            content=self.read_prompt(
-                "agent.context.extras.md",
-                extras=dirty_json.stringify(
-                    {**loop_data.extras_persistent, **loop_data.extras_temporary}
-                ),
-            ),
-        ).output()
+        # join protocol and extras
+        protocol = self._build_context_message(
+            "agent.context.protocol.md",
+            "protocol",
+            {**loop_data.protocol_persistent, **loop_data.protocol_temporary},
+            include_empty=False,
+        )
+        extras = self._build_context_message(
+            "agent.context.extras.md",
+            "extras",
+            {**loop_data.extras_persistent, **loop_data.extras_temporary},
+            include_empty=True,
+        )
+        loop_data.protocol_temporary.clear()
         loop_data.extras_temporary.clear()
 
-        # convert history + extras to LLM format
+        # convert protocol + history + extras to LLM format
         history_langchain: list[BaseMessage] = history.output_langchain(
-            loop_data.history_output + extras
+            protocol + loop_data.history_output + extras
         )
 
-        # build full prompt from system prompt, message history and extrS
+        # build full prompt from system prompt, protocol, message history and extras
         full_prompt: list[BaseMessage] = [
             SystemMessage(content=system_text),
             *history_langchain,
@@ -584,12 +615,30 @@ class Agent:
             Agent.DATA_NAME_CTX_WINDOW,
             {
                 "text": full_text,
-                "tokens": tokens.approximate_tokens(full_text),
+                "tokens": tokens.approximate_prompt_tokens(full_text),
             },
         )
 
         return full_prompt
 
+    def _build_context_message(
+        self,
+        prompt_file: str,
+        variable_name: str,
+        values: dict[str, history.MessageContent],
+        include_empty: bool,
+    ) -> list[history.OutputMessage]:
+        if not include_empty and not values:
+            return []
+
+        return history.Message(  # type: ignore[abstract]
+            False,
+            content=self.read_prompt(
+                prompt_file,
+                **{variable_name: dirty_json.stringify(values)},
+            ),
+        ).output()
+
     @extension.extensible
     async def handle_exception(self, location: str, exception: Exception):
         if exception:
@@ -664,7 +713,12 @@ class Agent:
 
     @extension.extensible
     def hist_add_message(
-        self, ai: bool, content: history.MessageContent, tokens: int = 0, id: str = ""
+        self,
+        ai: bool,
+        content: history.MessageContent,
+        tokens: int = 0,
+        id: str = "",
+        metadata: dict[str, Any] | None = None,
     ):
         self.last_message = Localization.get().now()
         # Allow extensions to process content before adding to history
@@ -673,7 +727,11 @@ class Agent:
             "hist_add_before", self, content_data=content_data, ai=ai
         )
         return self.history.add_message(
-            ai=ai, content=content_data["content"], tokens=tokens, id=id
+            ai=ai,
+            content=content_data["content"],
+            tokens=tokens,
+            id=id,
+            metadata=metadata,
         )
 
     @extension.extensible
@@ -706,10 +764,17 @@ class Agent:
         return msg
 
     @extension.extensible
-    def hist_add_ai_response(self, message: str, id: str = ""):
+    def hist_add_ai_response(
+        self, message: str, id: str = "", llm_result: LLMResult | None = None
+    ):
         self.loop_data.last_response = message
         content = self.parse_prompt("fw.ai_response.md", message=message)
-        return self.hist_add_message(True, content=content, id=id)
+        return self.hist_add_message(
+            True,
+            content=content,
+            id=id,
+            metadata=metadata_from_llm_result(llm_result),
+        )
 
     @extension.extensible
     def hist_add_warning(self, message: history.MessageContent, id: str = ""):
@@ -719,13 +784,28 @@ class Agent:
     @extension.extensible
     def hist_add_tool_result(self, tool_name: str, tool_result: str, **kwargs):
         msg_id = kwargs.pop("id", "")
+        responses_item = kwargs.pop("_responses_output_item", None) or kwargs.pop(
+            "responses_item", None
+        )
+        metadata = (
+            {
+                RESPONSE_METADATA_KEY: {
+                    "input_items": [responses_item],
+                    "output_items": [],
+                    "mode": "responses",
+                    "state": "provider",
+                }
+            }
+            if isinstance(responses_item, dict)
+            else None
+        )
         data = {
             "tool_name": tool_name,
             "tool_result": tool_result,
             **kwargs,
         }
         extension.call_extensions_sync("hist_add_tool_result", self, data=data)
-        return self.hist_add_message(False, content=data, id=msg_id)
+        return self.hist_add_message(False, content=data, id=msg_id, metadata=metadata)
 
     def concat_messages(
         self, messages
@@ -830,6 +910,164 @@ class Agent:
 
         return response, reasoning
 
+    @extension.extensible
+    async def call_chat_model_turn(
+        self,
+        messages: list[BaseMessage],
+        response_callback: Callable[[str, str], Awaitable[str | None]] | None = None,
+        reasoning_callback: Callable[[str, str], Awaitable[None]] | None = None,
+        background: bool = False,
+        explicit_caching: bool = True,
+    ) -> LLMResult:
+        model = self.get_chat_model()
+        model_kwargs = getattr(model, "kwargs", {}) if model else {}
+        if isinstance(model_kwargs, dict) and model_kwargs.get("responses_delete_on_chat_delete") is False:
+            self.set_data("responses_delete_on_chat_delete", False)
+        response_tools, name_map = build_responses_function_tools(self)
+        self.set_data(Agent.DATA_NAME_RESPONSES_TOOL_NAME_MAP, name_map)
+
+        call_data = {
+            "model": model,
+            "messages": messages,
+            "response_callback": response_callback,
+            "reasoning_callback": reasoning_callback,
+            "background": background,
+            "explicit_caching": explicit_caching,
+            "a0_responses_function_tools": response_tools,
+        }
+
+        previous_state = self._responses_state_for_model(model)
+        if previous_state:
+            history_counter = int(previous_state.get("history_counter", 0) or 0)
+            call_data["previous_response_id"] = previous_state.get("response_id", "")
+            call_data["responses_input_items"] = self._responses_input_items_since(
+                model,
+                history_counter,
+            )
+        call_data["responses_local_input_items"] = self._responses_prompt_input_items(
+            model,
+            messages,
+        )
+
+        await extension.call_extensions_async(
+            "chat_model_call_before", self, call_data=call_data
+        )
+
+        turn_kwargs = {
+            "a0_responses_function_tools": call_data.get(
+                "a0_responses_function_tools"
+            ),
+            "responses_local_input_items": call_data.get(
+                "responses_local_input_items"
+            ),
+        }
+        for key in (
+            "responses_builtin_tools",
+            "responses_state",
+            "previous_response_id",
+            "responses_input_items",
+        ):
+            if call_data.get(key) is not None:
+                turn_kwargs[key] = call_data.get(key)
+
+        llm_result = await call_data["model"].unified_turn(
+            messages=call_data["messages"],
+            reasoning_callback=call_data["reasoning_callback"],
+            response_callback=call_data["response_callback"],
+            rate_limiter_callback=(
+                self.rate_limiter_callback if not call_data["background"] else None
+            ),
+            explicit_caching=call_data["explicit_caching"],
+            **turn_kwargs,
+        )
+
+        downgraded = llm_result.capability.get("builtin_tool_downgrades")
+        if downgraded:
+            self.context.log.log(
+                type="info",
+                heading="Responses capability downgrade",
+                content=(
+                    "Provider rejected Responses built-in tool(s); omitted: "
+                    + ", ".join(str(item) for item in downgraded)
+                ),
+            )
+
+        await extension.call_extensions_async(
+            "chat_model_call_after",
+            self,
+            call_data=call_data,
+            response=llm_result.response,
+            reasoning=llm_result.reasoning,
+        )
+
+        return llm_result
+
+    def _responses_state_for_model(self, model: Any) -> dict[str, Any]:
+        state = self.get_data(Agent.DATA_NAME_RESPONSES_STATE)
+        if not isinstance(state, dict):
+            return {}
+        provider_model_key = str(getattr(model, "model_name", "") or "")
+        if state.get("provider_model_key") != provider_model_key:
+            return {}
+        if not state.get("response_id"):
+            return {}
+        return state
+
+    def _responses_input_items_since(
+        self, model: Any, sequence: int
+    ) -> list[dict[str, Any]]:
+        items: list[dict[str, Any]] = []
+        for message in self.history.messages_since(sequence):
+            items.extend(self._responses_input_items_for_message(model, message))
+        return items
+
+    def _responses_input_items_for_message(
+        self, model: Any, message: history.Message
+    ) -> list[dict[str, Any]]:
+        result = result_from_metadata(message.metadata)
+        if result:
+            if message.ai and result.output_items:
+                return [item.to_dict() for item in result.output_items]
+            if not message.ai and result.input_items:
+                return [dict(item) for item in result.input_items]
+
+        output = message.output()
+        langchain_messages = history.output_langchain(output)
+        if hasattr(model, "_convert_messages"):
+            converted = model._convert_messages(langchain_messages)
+            return ResponsesTransport.input_from_messages(converted)
+        return []
+
+    def _responses_prompt_input_items(
+        self, model: Any, messages: list[BaseMessage]
+    ) -> list[dict[str, Any]]:
+        if not hasattr(model, "_convert_messages"):
+            return []
+        converted = model._convert_messages(messages)
+        return ResponsesTransport.input_from_messages(converted)
+
+    def _remember_llm_result_state(
+        self, llm_result: LLMResult, history_message: history.Message
+    ) -> None:
+        if not llm_result.response_id:
+            return
+        current = self.get_data(Agent.DATA_NAME_RESPONSES_STATE)
+        response_ids = []
+        if isinstance(current, dict) and isinstance(current.get("response_ids"), list):
+            response_ids = [str(item) for item in current["response_ids"] if item]
+        if llm_result.response_id not in response_ids:
+            response_ids.append(llm_result.response_id)
+        self.set_data(
+            Agent.DATA_NAME_RESPONSES_STATE,
+            {
+                "response_id": llm_result.response_id,
+                "previous_response_id": llm_result.previous_response_id,
+                "provider_model_key": llm_result.provider_model_key,
+                "history_counter": history_message.sequence,
+                "response_ids": response_ids,
+            },
+        )
+
     @extension.extensible
     async def rate_limiter_callback(
         self, message: str, key: str, total: int, limit: int
@@ -863,6 +1101,310 @@ class Agent:
         while self.context.paused:
             await asyncio.sleep(0.1)
 
+    async def process_llm_result_tools(self, llm_result: LLMResult):
+        await self._log_response_builtin_items(llm_result)
+        if llm_result.function_calls:
+            for function_call in llm_result.function_calls:
+                name_map = self.get_data(Agent.DATA_NAME_RESPONSES_TOOL_NAME_MAP)
+                tool_name = original_tool_name(function_call.name, name_map)
+                response_item_factory = lambda response, call=function_call: function_call_output_item(
+                    call.call_id,
+                    response.message,
+                )
+                result = await self._execute_tool_request(
+                    tool_name=tool_name,
+                    tool_args=function_call.arguments,
+                    message=llm_result.response,
+                    raw_tool_name=tool_name,
+                    responses_item_factory=response_item_factory,
+                )
+                if result:
+                    return result
+            return None
+        if llm_result.builtin_items and not llm_result.response:
+            return None
+        if (
+            llm_result.mode == "responses"
+            and llm_result.response
+            and extract_tools.json_parse_dirty(llm_result.response) is None
+        ):
+            return llm_result.response
+        return await self.process_tools(llm_result.response)
+
+    async def _execute_tool_request(
+        self,
+        tool_name: str,
+        tool_args: dict,
+        message: str,
+        raw_tool_name: str = "",
+        responses_item_factory: Callable[[Any], dict[str, Any]] | None = None,
+    ):
+        raw_tool_name = raw_tool_name or tool_name
+        tool_method = None
+        tool = None
+
+        try:
+            import helpers.mcp_handler as mcp_helper
+
+            mcp_tool_candidate = mcp_helper.MCPConfig.get_instance().get_tool(
+                self, tool_name
+            )
+            if mcp_tool_candidate:
+                tool = mcp_tool_candidate
+        except ImportError:
+            PrintStyle(
+                background_color="black", font_color="yellow", padding=True
+            ).print("MCP helper module not found. Skipping MCP tool lookup.")
+        except Exception as e:
+            PrintStyle(background_color="black", font_color="red", padding=True).print(
+                f"Failed to get MCP tool '{tool_name}': {e}"
+            )
+
+        if not tool:
+            tool = self.get_tool(
+                name=tool_name,
+                method=tool_method,
+                args=tool_args,
+                message=message,
+                loop_data=self.loop_data,
+            )
+
+        if not tool:
+            error_detail = (
+                f"Tool '{raw_tool_name}' not found or could not be initialized."
+            )
+            wmsg = self.hist_add_warning(error_detail)
+            PrintStyle(font_color="red", padding=True).print(error_detail)
+            self.context.log.log(
+                type="warning",
+                content=f"{self.agent_name}: {error_detail}",
+                id=wmsg.id,
+            )
+            return None
+
+        self.loop_data.current_tool = tool  # type: ignore
+        try:
+            await self.handle_intervention()
+
+            await tool.before_execution(**tool_args)
+            await self.handle_intervention()
+
+            await extension.call_extensions_async(
+                "tool_execute_before",
+                self,
+                tool_args=tool_args or {},
+                tool_name=tool_name,
+            )
+
+            response = await tool.execute(**tool_args)
+            await self.handle_intervention()
+
+            await extension.call_extensions_async(
+                "tool_execute_after",
+                self,
+                response=response,
+                tool_name=tool_name,
+            )
+
+            if responses_item_factory:
+                response.additional = {
+                    **(response.additional or {}),
+                    "_responses_output_item": responses_item_factory(response),
+                }
+
+            await tool.after_execution(response)
+            await self.handle_intervention()
+
+            if response.break_loop:
+                self._clear_responses_pending_state()
+                return response.message
+        finally:
+            self.loop_data.current_tool = None
+        return None
+
+    async def _log_response_builtin_items(self, llm_result: LLMResult) -> None:
+        for item in llm_result.builtin_items:
+            if item.type == "computer_call":
+                await self._handle_responses_computer_call(item.data)
+                continue
+            if item.type == "mcp_approval_request":
+                self._handle_responses_mcp_approval_request(item.data)
+                continue
+            self.context.log.log(
+                type="info",
+                heading=f"Responses tool item: {item.type}",
+                content=json.dumps(item.data, ensure_ascii=False, default=str),
+            )
+
+    async def _handle_responses_computer_call(self, item: dict[str, Any]) -> None:
+        safety_checks = item.get("pending_safety_checks") or item.get("safety_checks")
+        if safety_checks:
+            message = (
+                "Responses computer_call requested safety-check acknowledgement. "
+                "Agent Zero requires explicit user acknowledgement before executing it."
+            )
+            output_item = {
+                "type": "computer_call_output",
+                "call_id": str(item.get("call_id") or item.get("id") or ""),
+                "output": {"type": "input_text", "text": message},
+            }
+            self.hist_add_tool_result(
+                "computer_call",
+                message,
+                responses_item=output_item,
+            )
+            self.context.log.log(type="warning", content=message)
+            return
+
+        args = self._computer_call_args(item)
+        if not args:
+            message = "Responses computer_call action is unsupported by Agent Zero."
+            output_item = {
+                "type": "computer_call_output",
+                "call_id": str(item.get("call_id") or item.get("id") or ""),
+                "output": {"type": "input_text", "text": message},
+            }
+            self.hist_add_tool_result(
+                "computer_call",
+                message,
+                responses_item=output_item,
+            )
+            self.context.log.log(type="warning", content=message)
+            return
+
+        if args.get("action") != "start_session" and not args.get("session_id"):
+            session_id = str(
+                self.get_data(Agent.DATA_NAME_RESPONSES_COMPUTER_SESSION) or ""
+            )
+            if session_id:
+                args["session_id"] = session_id
+
+        response_item_factory = lambda response: self._computer_call_output_item(
+            item,
+            response,
+        )
+        result = await self._execute_tool_request(
+            tool_name="computer_use_remote",
+            tool_args=args,
+            message=json.dumps(item, ensure_ascii=False, default=str),
+            raw_tool_name="computer_call",
+            responses_item_factory=response_item_factory,
+        )
+        _ = result
+
+    def _handle_responses_mcp_approval_request(self, item: dict[str, Any]) -> None:
+        request_id = str(
+            item.get("approval_request_id") or item.get("id") or item.get("call_id") or ""
+        )
+        message = (
+            "Responses MCP approval request received. Agent Zero denied it because "
+            "provider-hosted MCP approval requires explicit user approval."
+        )
+        output_item = {
+            "type": "mcp_approval_response",
+            "approval_request_id": request_id,
+            "approve": False,
+        }
+        self.hist_add_tool_result(
+            "mcp_approval_request",
+            message,
+            responses_item=output_item,
+        )
+        self.context.log.log(
+            type="warning",
+            heading="Responses MCP approval required",
+            content=message,
+        )
+
+    def _computer_call_args(self, item: dict[str, Any]) -> dict[str, Any]:
+        action = item.get("action")
+        action_data = dict(action) if isinstance(action, dict) else {}
+        action_type = str(
+            action_data.get("type")
+            or action_data.get("action")
+            or item.get("action_type")
+            or ""
+        ).strip().lower()
+        args: dict[str, Any] = {}
+
+        if action_type in {"screenshot", "capture"}:
+            args["action"] = "capture"
+        elif action_type in {"move", "mousemove"}:
+            args.update({"action": "move", "x": action_data.get("x"), "y": action_data.get("y")})
+        elif action_type in {"click", "double_click"}:
+            args.update(
+                {
+                    "action": "click",
+                    "x": action_data.get("x"),
+                    "y": action_data.get("y"),
+                    "button": action_data.get("button", "left"),
+                    "count": 2 if action_type == "double_click" else action_data.get("count", 1),
+                }
+            )
+        elif action_type == "scroll":
+            args.update(
+                {
+                    "action": "scroll",
+                    "dx": action_data.get("dx", action_data.get("scroll_x", 0)),
+                    "dy": action_data.get("dy", action_data.get("scroll_y", 0)),
+                }
+            )
+        elif action_type in {"keypress", "key"}:
+            args.update(
+                {
+                    "action": "key",
+                    "keys": action_data.get("keys") or action_data.get("key"),
+                }
+            )
+        elif action_type in {"type", "input_text"}:
+            args.update({"action": "type", "text": action_data.get("text", "")})
+        else:
+            return {}
+
+        session_id = item.get("session_id") or action_data.get("session_id")
+        if session_id:
+            args["session_id"] = session_id
+        return args
+
+    def _computer_call_output_item(
+        self, source_item: dict[str, Any], response: Any
+    ) -> dict[str, Any]:
+        output: dict[str, Any] = {
+            "type": "input_text",
+            "text": str(getattr(response, "message", "") or ""),
+        }
+        additional = getattr(response, "additional", None)
+        raw_content = additional.get("raw_content") if isinstance(additional, dict) else None
+        if isinstance(raw_content, list):
+            for content in raw_content:
+                if not isinstance(content, dict):
+                    continue
+                if content.get("type") != "image_url":
+                    continue
+                image_url = content.get("image_url")
+                url = image_url.get("url") if isinstance(image_url, dict) else image_url
+                if url:
+                    output = {"type": "input_image", "image_url": url}
+                    break
+
+        session_id_match = re_search_session_id(str(getattr(response, "message", "") or ""))
+        if session_id_match:
+            self.set_data(Agent.DATA_NAME_RESPONSES_COMPUTER_SESSION, session_id_match)
+
+        return {
+            "type": "computer_call_output",
+            "call_id": str(source_item.get("call_id") or source_item.get("id") or ""),
+            "output": output,
+        }
+
+    def _clear_responses_pending_state(self) -> None:
+        state = self.get_data(Agent.DATA_NAME_RESPONSES_STATE)
+        if isinstance(state, dict):
+            state = dict(state)
+            state.pop("response_id", None)
+            state.pop("previous_response_id", None)
+            self.set_data(Agent.DATA_NAME_RESPONSES_STATE, state)
+
     @extension.extensible
     async def process_tools(self, msg: str):
         # search for tool usage requests in agent message
@@ -1037,3 +1579,8 @@ class Agent:
             loop_data=loop_data,
             **kwargs,
         )
+
+
+def re_search_session_id(text: str) -> str:
+    match = re.search(r"session_id=([A-Za-z0-9_.:-]+)", text or "")
+    return match.group(1) if match else ""

agents/AGENTS.md

@@ -0,0 +1,44 @@
+# Agent Profiles DOX
+
+## Purpose
+
+- Own bundled agent profiles, profile-specific prompts, and profile-local tools.
+- Keep profile behavior understandable without requiring edits to core framework prompts.
+
+## Ownership
+
+- Each direct profile directory owns its `agent.yaml`, optional `prompts/`, optional `tools/`, and optional `extensions/`.
+- `_example/` demonstrates profile layout and should stay suitable as a reference.
+- User-created local profiles belong under `usr/agents/`, not here, unless they are intended to ship with the product.
+
+## Local Contracts
+
+- `agent.yaml` is the profile entry point and must stay valid YAML.
+- Profile prompt overrides should be narrow and named to match the core prompt they extend or replace.
+- Profile-local tools must follow the same `Tool` contract as root `tools/`.
+- Do not put secrets, provider API keys, local paths, or user-specific settings in bundled profiles.
+
+## Work Guidance
+
+- Prefer small profile-specific prompt files over duplicating large core prompts.
+- Keep examples generic and runnable in a clean checkout.
+- When changing profile behavior, check how the WebUI profile picker and backend profile loader discover profiles.
+
+## Verification
+
+- Run `pytest` or targeted tests covering profile loading when changing `agent.yaml` structure or profile discovery.
+- Manually inspect YAML validity for changed profiles if no targeted test exists.
+
+## Child DOX Index
+
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [_example/AGENTS.md](_example/AGENTS.md) | Reference profile demonstrating profile-local prompts, tools, and extensions. |
+| [agent0/AGENTS.md](agent0/AGENTS.md) | Main user-facing Agent Zero profile metadata. |
+| [default/AGENTS.md](default/AGENTS.md) | Base profile metadata and inherited prompt specifics. |
+| [developer/AGENTS.md](developer/AGENTS.md) | Software development specialist profile. |
+| [hacker/AGENTS.md](hacker/AGENTS.md) | Cyber security and penetration testing specialist profile. |
+| [researcher/AGENTS.md](researcher/AGENTS.md) | Research, data analysis, and reporting specialist profile. |
+| [tiny-local/AGENTS.md](tiny-local/AGENTS.md) | Small/local model profile with an action-first communication prompt. |

agents/_example/AGENTS.md

@@ -0,0 +1,33 @@
+# Example Agent Profile DOX
+
+## Purpose
+
+- Own the reference profile used to demonstrate bundled profile layout.
+- Show how profile-local prompts, tools, and extensions fit beside `agent.yaml`.
+
+## Ownership
+
+- `agent.yaml` owns the example profile metadata.
+- `prompts/` owns prompt override examples.
+- `tools/` owns profile-local tool examples.
+- `extensions/` owns profile-local lifecycle extension examples.
+
+## Local Contracts
+
+- Keep this profile generic, minimal, and safe to copy into user or plugin profile work.
+- Do not add product behavior here that should live in a real bundled profile.
+- Profile-local tools and extensions must follow the same contracts as root tools and extensions.
+
+## Work Guidance
+
+- Prefer simple examples that illustrate structure over complex behavior.
+- Update related skill guidance when the example profile layout changes.
+
+## Verification
+
+- Manually inspect YAML and prompt filenames after edits.
+- Run profile-loading tests when changing discovery or profile schema assumptions.
+
+## Child DOX Index
+
+No child DOX files.

agents/agent0/AGENTS.md

@@ -0,0 +1,31 @@
+# Agent 0 Profile DOX
+
+## Purpose
+
+- Own the main user-facing Agent Zero profile metadata.
+- Keep the primary assistant profile discoverable and distinct from subordinate specialist profiles.
+
+## Ownership
+
+- `agent.yaml` owns the profile title, description, and delegation context.
+- Prompt behavior is inherited from the default profile unless a local prompt override is added.
+
+## Local Contracts
+
+- Keep `Agent 0` suitable as the direct conversation agent for the system.
+- Do not add narrow specialist behavior that belongs in `developer/`, `researcher/`, `hacker/`, or a custom user profile.
+- Do not store user-specific preferences, provider settings, or secrets in this profile.
+
+## Work Guidance
+
+- Keep metadata concise because it appears in profile selection and delegation contexts.
+- Coordinate substantial behavior changes with default prompts and WebUI profile selection.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run profile-loading tests when changing schema or discovery behavior.
+
+## Child DOX Index
+
+No child DOX files.

agents/default/AGENTS.md

@@ -0,0 +1,32 @@
+# Default Agent Profile DOX
+
+## Purpose
+
+- Own base profile metadata and default prompt specifics inherited by specialized profiles.
+- Provide the shared behavior layer for bundled and custom profiles.
+
+## Ownership
+
+- `agent.yaml` owns default profile metadata.
+- `agent.system.main.specifics.md` owns default profile-specific system prompt content.
+- Additional prompt overrides under this directory become shared defaults unless a child profile overrides them.
+
+## Local Contracts
+
+- Keep default behavior broad, framework-compatible, and safe for inheritance.
+- Avoid role-specific instructions that belong in specialist profiles.
+- Prompt filenames must match the framework prompt override names they target.
+
+## Work Guidance
+
+- Prefer small, explicit prompt changes with clear inheritance impact.
+- Check bundled specialist profiles after changing default behavior.
+
+## Verification
+
+- Manually inspect YAML and prompt rendering assumptions after edits.
+- Run prompt/profile tests when changing inherited prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.

agents/developer/AGENTS.md

@@ -0,0 +1,32 @@
+# Developer Agent Profile DOX
+
+## Purpose
+
+- Own the bundled software development specialist profile.
+- Keep development, debugging, refactoring, and architecture behavior separate from general agent defaults.
+
+## Ownership
+
+- `agent.yaml` owns title, description, and delegation context for software development work.
+- `prompts/` owns developer-specific prompt overrides when present.
+- `extensions/` owns developer-specific lifecycle hooks when present.
+
+## Local Contracts
+
+- Keep this profile focused on software engineering tasks.
+- Do not hardcode repository-local credentials, paths, or project-specific conventions.
+- Prompt overrides must preserve the framework tool-call and response contracts.
+
+## Work Guidance
+
+- Align developer behavior with the root engineering and tool contracts.
+- Prefer profile prompt edits over core prompt edits when the behavior is specific to development tasks.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run prompt/profile tests when changing profile loading or developer prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.

agents/developer/prompts/agent.system.main.communication.md

@@ -2,9 +2,9 @@
 
 ### Initial Interview
 
-When 'Master Developer' agent receives a development task, it must execute a comprehensive requirements elicitation protocol to ensure complete specification of all parameters, constraints, and success criteria before initiating autonomous development operations.
+When 'Master Developer' agent receives a development task, first decide whether the request is already actionable. For clear, bounded coding tasks, infer reasonable defaults from the repository, inspect local specs/tests, implement, and verify. Ask the user only when ambiguity blocks safe progress, would change the deliverable materially, or risks destructive/unwanted work.
 
-The agent SHALL conduct a structured interview process to establish:
+For broad or underspecified development mandates, conduct a structured interview process to establish:
 - **Scope Boundaries**: Precise delineation of features, modules, and integrations included/excluded from the development mandate
 - **Technical Requirements**: Expected performance benchmarks, scalability needs, from prototype to production-grade implementations
 - **Output Specifications**: Deliverable preferences (source code, containers, documentation), deployment targets, testing requirements
@@ -13,7 +13,7 @@ The agent SHALL conduct a structured interview process to establish:
 - **Timeline Parameters**: Sprint cycles, release deadlines, milestone deliverables, continuous deployment schedules
 - **Success Metrics**: Explicit criteria for determining code quality, system performance, and feature completeness
 
-The agent must utilize the 'response' tool iteratively until achieving complete clarity on all dimensions. Only when the agent can execute the entire development lifecycle without further clarification should autonomous work commence. This front-loaded investment in requirements understanding prevents costly refactoring and ensures alignment with user expectations.
+Use the 'response' tool iteratively only for blocking questions. Do not ask an interview when the user asked for a small script, bug fix, refactor, test addition, or inspection task that can be handled from local context. For these tasks, move quickly through inspect -> implement -> test -> cleanup -> concise final report.
 
 ### Thinking (thoughts)
 
@@ -80,4 +80,4 @@ Exactly one JSON object per response cycle.
 }
 ~~~
 
-{{ include "agent.system.main.communication_additions.md" }}
+{{ include "agent.system.main.communication_additions.md" }}

agents/developer/prompts/agent.system.main.specifics.md

@@ -40,6 +40,10 @@ You are Agent Zero 'Master Developer' - an autonomous intelligence system engine
 4. **Innovation Focus**: Leverage cutting-edge technologies while maintaining pragmatic stability requirements
 5. **Practical Delivery**: Ship working software that solves real problems with elegant, maintainable solutions
 
+### Delivery Discipline
+
+For coding-agent and terminal-heavy tasks, scale the core coding discipline rather than replacing it. Read repository facts first, keep edits scoped, delegate only bounded components with testable outputs, verify integration points and exact artifacts, clean generated work, and report only what was checked.
+
 Your expertise enables transformation of complex technical challenges into elegant, scalable solutions that power mission-critical systems at the highest performance levels.
 
 

agents/hacker/AGENTS.md

@@ -0,0 +1,31 @@
+# Hacker Agent Profile DOX
+
+## Purpose
+
+- Own the bundled cyber security and penetration testing specialist profile.
+- Keep security-audit behavior scoped to this profile instead of default agent behavior.
+
+## Ownership
+
+- `agent.yaml` owns title, description, and delegation context for security work.
+- `prompts/` owns security-specific prompt overrides when present.
+
+## Local Contracts
+
+- Keep the profile focused on authorized security analysis, vulnerability research, and defensive audit tasks.
+- Do not add secrets, target-specific credentials, or local environment assumptions.
+- Preserve the framework tool-call contract and safety expectations.
+
+## Work Guidance
+
+- Keep security instructions operational and bounded to legitimate testing contexts.
+- Coordinate broad safety changes with core prompts and relevant tests.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run prompt/profile tests when changing profile discovery or security prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.

agents/researcher/AGENTS.md

@@ -0,0 +1,31 @@
+# Researcher Agent Profile DOX
+
+## Purpose
+
+- Own the bundled research, data analysis, and reporting specialist profile.
+- Keep evidence-gathering and report-oriented behavior separate from general defaults.
+
+## Ownership
+
+- `agent.yaml` owns title, description, and delegation context for research work.
+- `prompts/` owns researcher-specific prompt overrides when present.
+
+## Local Contracts
+
+- Keep this profile focused on information gathering, analysis, synthesis, and reporting.
+- Do not bake in project-specific sources, credentials, or local paths.
+- Preserve the framework tool-call and response contracts.
+
+## Work Guidance
+
+- Prefer prompt changes that improve citation, evidence handling, and analysis quality for research tasks.
+- Coordinate broad research behavior changes with document or browser plugin contracts when relevant.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run prompt/profile tests when changing discovery or researcher prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.

agents/tiny-local/AGENTS.md

@@ -0,0 +1,38 @@
+# Tiny Local Agent Profile DOX
+
+## Purpose
+
+- Own the bundled Tiny Local profile for small/local chat models.
+- Keep local-model behavior prompt-only and isolated from core framework execution.
+
+## Ownership
+
+- `agent.yaml` owns profile metadata for discovery and profile switching.
+- `prompts/agent.system.main.communication.md` owns the local-model communication contract.
+- `prompts/agent.system.main.solving.md` owns the local-model problem-solving contract and suppresses inherited visible reasoning requirements.
+- `prompts/fw.msg_repeat.md` owns Tiny Local's profile-specific recovery instructions when the framework rejects a duplicate assistant message.
+- `prompts/agent.system.tools.md` owns the Tiny Local tools wrapper and final output-shape reminder after tool listing.
+- `prompts/agent.system.tool.*.md` files own Tiny Local-specific tool examples that avoid inherited reasoning fields and repeated writes.
+
+## Local Contracts
+
+- Preserve the normal Agent Zero tool-call shape: `tool_name` plus `tool_args`.
+- Do not add parser repair, duplicate suppression runtime, model transport, or text-editor runtime behavior here.
+- Duplicate-message handling may be tightened through profile prompts only.
+- Keep prompt text short enough for small local models to follow.
+- Treat continuation requests such as `proceed` or `continue` as commands to execute the next unfinished step, not as prompts for another status response.
+- Do not include user-specific provider names, API keys, local paths, or secrets.
+
+## Work Guidance
+
+- Prefer prompt wording changes over new files when tightening this profile, except when replacing inherited tool examples for local-model compliance.
+- Keep this profile suitable for Ollama, LM Studio, Qwen, and comparable local models.
+
+## Verification
+
+- Render the `tiny-local` system prompt after communication prompt changes.
+- Run `pytest tests/test_default_prompt_budget.py` for prompt and profile regressions.
+
+## Child DOX Index
+
+No child DOX files.

agents/tiny-local/agent.yaml

@@ -0,0 +1,3 @@
+title: Tiny Local
+description: Action-first profile for small local models that need a minimal tool-call contract.
+context: Use this agent when running small local chat models through Ollama, LM Studio, or similar providers and the model tends to explain actions instead of calling tools.

agents/tiny-local/prompts/agent.system.main.communication.md

@@ -0,0 +1,31 @@
+## Communication
+
+You are Agent Zero. Act on the user's behalf.
+
+When the user asks you to do something, do it directly. Do not explain how the user could do it themselves.
+
+Your visible assistant message must be exactly one valid JSON object.
+
+Use exactly these top-level fields: `"tool_name"` and `"tool_args"`.
+
+Do not include markdown fences, prose before the JSON, prose after the JSON, hidden reasoning, analysis, thoughts, or headlines.
+
+Choose a tool from the tools listed in this system prompt. Do not invent tool names, action names, or generic names such as `read`, `write`, `terminal`, or `multi`.
+
+For a final user-facing answer, use the `response` tool.
+
+Use `response` only when the work is complete, blocked, or the user is only acknowledging completed work.
+
+If the user says "proceed", "continue", "go ahead", "do it", "excellent proceed", or similar after you named a next step or there is unfinished work, do not answer with a promise or status update. Call the next appropriate tool.
+
+Final-answer shape:
+
+`{"tool_name":"response","tool_args":{"text":"Answer briefly."}}`
+
+For work that requires a command, file action, browser action, or any other available tool, call the appropriate tool immediately. Do not explain what command the user could run manually.
+
+If the framework warns that your prior message was malformed, repeated, or reasoning-only, output a corrected JSON tool request immediately without explaining the warning.
+
+When the warning says you sent the same message again, do not resend the same JSON. Change the tool, action, arguments, or final answer so the next message is meaningfully different.
+
+{{ include "agent.system.main.communication_additions.md" }}

agents/tiny-local/prompts/agent.system.main.solving.md

@@ -0,0 +1,18 @@
+## Problem Solving
+
+Act directly and keep hidden reasoning out of the visible JSON.
+
+For simple questions, answer with the `response` tool.
+
+Continuation words such as "proceed", "continue", "go ahead", "do it", and "excellent proceed" mean execute the next unfinished step. Do not respond by saying you will begin, continue, start, proceed, or investigate. Use a real tool call unless the task is already complete or blocked.
+
+For tasks that need shell commands, files, browser actions, or other capabilities:
+- choose the appropriate listed tool immediately
+- keep one tool call per turn unless the `parallel` tool is listed and truly useful
+- inspect outputs before deciding the next tool call
+- never claim success from timeout output or a still-running command
+- after a successful tool result, do not repeat the same exact tool call
+- after a repeated-message warning, do not repeat the same status response or exact tool request; choose the next different executable action or report a blocker
+- when finished, use the `response` tool with a brief result
+
+Do not include `thoughts`, `headline`, analysis, plans, or prose outside the JSON object.

agents/tiny-local/prompts/agent.system.tool.code_exe.md

@@ -0,0 +1,24 @@
+### code_execution_tool
+Run terminal, Python, or Node.js commands.
+
+Arguments in `tool_args`:
+- `runtime`: `terminal`, `python`, `nodejs`, or `output`
+- `code`: command or script code
+- `session`: terminal session id; default `0`
+- `reset`: kill a session before running; `true` or `false`
+
+Rules:
+- Put the command or script in `code`.
+- Use `runtime=output` to poll running work.
+- Use `input` for interactive terminal prompts.
+- If a session is stuck, call this tool again with the same `session` and `reset=true`.
+- Do not claim success from timeout output or a still-running command.
+- When counting files, prefer `find` over `ls` so hidden files and type filters are handled.
+
+Examples:
+
+`{"tool_name":"code_execution_tool","tool_args":{"runtime":"terminal","session":0,"reset":false,"code":"ls -1 /tmp | wc -l"}}`
+
+`{"tool_name":"code_execution_tool","tool_args":{"runtime":"python","session":0,"reset":false,"code":"import os\nprint(os.getcwd())"}}`
+
+`{"tool_name":"code_execution_tool","tool_args":{"runtime":"output","session":0}}`

agents/tiny-local/prompts/agent.system.tool.response.md

@@ -0,0 +1,13 @@
+### response
+Final answer to the user.
+
+Use this tool only when the task is done, blocked, or no tool is needed.
+
+Do not use this tool for "proceed", "continue", "go ahead", or similar continuation requests when there is an unfinished next step. Call a real tool instead.
+
+Arguments in `tool_args`:
+- `text`: concise final answer text
+
+Example:
+
+`{"tool_name":"response","tool_args":{"text":"There are 24 files in /tmp."}}`

agents/tiny-local/prompts/agent.system.tool.text_editor.md

@@ -0,0 +1,26 @@
+### text_editor
+Read, write, or patch Markdown and plain text files.
+
+Actions in `tool_args.action`:
+- `read`: read a file
+- `write`: create or overwrite a file
+- `patch`: edit an existing file
+
+Common arguments:
+- `path`: absolute file path
+- `content`: full file content for `write`
+- `open_in_canvas`: set `true` when the user explicitly asks to open a Markdown file in the Canvas or Editor
+
+Rules:
+- Use this tool for `.md` and plain text files.
+- Use `write` to create a new Markdown file.
+- If the user asks to open the file in the Canvas or Editor, include `"open_in_canvas": true` in the same `write` or `patch` call.
+- After a successful write or patch result, do not repeat the same tool call. Use the `response` tool unless a different action is needed.
+
+Examples:
+
+`{"tool_name":"text_editor","tool_args":{"action":"write","path":"/a0/usr/workdir/TODO.md","content":"# TODO\n- [ ] First item\n","open_in_canvas":true}}`
+
+`{"tool_name":"text_editor","tool_args":{"action":"read","path":"/a0/usr/workdir/TODO.md"}}`
+
+`{"tool_name":"text_editor","tool_args":{"action":"patch","path":"/a0/usr/workdir/TODO.md","old_text":"- [ ] First item","new_text":"- [x] First item"}}`

agents/tiny-local/prompts/agent.system.tools.md

@@ -0,0 +1,17 @@
+## Available Tools
+
+Use only the tools listed below. Match tool names exactly.
+
+Every tool request must be exactly one JSON object with only these top-level fields:
+- `tool_name`
+- `tool_args`
+
+Action names are not tool names. Do not invent top-level `multi`, `read`, `write`, `terminal`, or generic batch tools.
+
+{{tools}}
+
+## Tiny Local Output Rule
+
+Some inherited tool examples may show `thoughts` or `headline`. Ignore that shape for this profile.
+
+Do not include `thoughts`, `headline`, analysis, markdown fences, or prose outside the JSON object.

agents/tiny-local/prompts/fw.msg_repeat.md

@@ -0,0 +1,13 @@
+You have sent the same message again. You have to do something else.
+
+Your repeated JSON was recorded, but it did not execute another tool. Do not send the same JSON object again.
+
+Choose one different action now:
+- If work is unfinished, call a real tool for the next unfinished step.
+- If your previous JSON used `response` while work remains, replace it with the next real tool call.
+- If a file write or patch already succeeded, read that file or answer with the observed result.
+- If a command already ran, inspect its output or run a different next command.
+- If the user only said "proceed" or "continue", continue with the next real tool call.
+- If no different action is possible, use `response` with a brief blocker.
+
+Output exactly one JSON object with `tool_name` and `tool_args`. No prose or markdown.

api/AGENTS.md

@@ -0,0 +1,42 @@
+# API Handlers DOX
+
+## Purpose
+
+- Own backend HTTP API handlers and WebSocket handler entry points.
+- Keep route-level behavior, authentication, CSRF, input parsing, and response shapes explicit.
+
+## Ownership
+
+- Files in this directory are discovered by the route registration layer in `helpers/api.py` and WebSocket registration code.
+- `ws_*.py` files define WebSocket namespaces or handlers through `helpers.ws.WsHandler`.
+- Plugin-provided API handlers belong inside plugin `api/` folders and follow the same base contracts.
+
+## Local Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`.
+- Implement `async def process(self, input: dict, request: Request) -> dict | Response`.
+- Override `get_methods()`, `requires_auth()`, `requires_csrf()`, `requires_api_key()`, or `requires_loopback()` only when the endpoint contract requires it.
+- Keep CSRF and authentication protections intact for browser-facing state-changing endpoints.
+- WebSocket handlers must derive from `helpers.ws.WsHandler` and validate event data before using it.
+- Do not return secrets, raw environment values, private files, or unfiltered exception details to clients.
+- This directory is a file-documented DOX profile: every direct `*.py` endpoint or WebSocket module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename.
+- The `*.py.dox.md` file owns endpoint purpose, request/response concepts, auth/CSRF/API-key/loopback assumptions, side effects, important helper dependencies, and verification guidance.
+- When a Python endpoint is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change.
+- Do not leave stale file-level DOX after endpoint deletion or rename.
+
+## Work Guidance
+
+- Use helpers for shared behavior instead of duplicating persistence, auth, file, project, plugin, or notification logic in endpoints.
+- Keep request and response payloads stable; update frontend callers and tests together when payloads change.
+- Prefer `Response` for files, redirects, status codes, and plain-text errors; return dictionaries for JSON success payloads.
+- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed endpoint behavior is described there.
+
+## Verification
+
+- Run targeted `pytest tests/test_*api*.py`, endpoint-specific tests, or WebSocket tests after changing handler behavior.
+- For auth, CSRF, upload/download, tunnel, or file endpoints, run the nearest security regression tests.
+- Check file-level documentation coverage with a script or shell loop that verifies each `api/*.py` has a matching `api/*.py.dox.md`.
+
+## Child DOX Index
+
+No child DOX files.

api/agent_profile_set.py

@@ -1,4 +1,4 @@
-from agent import Agent, AgentContext
+from agent import AgentContext
 from helpers import subagents
 from helpers.api import ApiHandler, Request, Response
 from helpers.persist_chat import save_tmp_chat
@@ -39,11 +39,7 @@ class SetAgentProfile(ApiHandler):
 
         config = initialize_agent(override_settings={"agent_profile": profile})
         context.config = config
-
-        agent = context.agent0
-        while agent:
-            agent.config = config
-            agent = agent.get_data(Agent.DATA_NAME_SUBORDINATE)
+        context.agent0.config = config
 
         save_tmp_chat(context)
         mark_dirty_for_context(context.id, reason="agent_profile_change")

api/agent_profile_set.py.dox.md

@@ -0,0 +1,48 @@
+# agent_profile_set.py DOX
+
+## Purpose
+
+- Own the `agent_profile_set.py` API endpoint.
+- This module sets the active agent profile for a chat context and returns profile label metadata.
+- Keep this file-level DOX profile synchronized with `agent_profile_set.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `agent_profile_set.py` owns the runtime implementation.
+- `agent_profile_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SetAgentProfile` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+- Top-level functions:
+- `_agent_profile_labels() -> dict[str, str]`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SetAgentProfile` is an `ApiHandler`.
+- `SetAgentProfile` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, settings/state persistence.
+- Switching a chat profile updates the context and top-level agent profile only; existing subordinate agents keep their own profile configs.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.persist_chat`, `helpers.state_monitor_integration`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `str.strip`, `context.is_running`, `_agent_profile_labels`, `initialize_agent`, `context.agent0.config`, `save_tmp_chat`, `mark_dirty_for_context`, `subagents.get_all_agents_list`, `Response`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_subagent_profiles.py`
+
+## Child DOX Index
+
+No child DOX files.

api/agents.py.dox.md

@@ -0,0 +1,48 @@
+# agents.py DOX
+
+## Purpose
+
+- Own the `agents.py` API endpoint.
+- This module lists available agent profiles for selection and delegation UI flows.
+- Keep this file-level DOX profile synchronized with `agents.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `agents.py` owns the runtime implementation.
+- `agents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Agents` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Agents` is an `ApiHandler`.
+- `Agents` defines `process(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `subagents.get_all_agents_list`, `Exception`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_default_prompt_budget.py`
+  - `tests/test_office_document_store.py`
+  - `tests/test_projects.py`
+  - `tests/test_skills_runtime.py`
+  - `tests/test_time_travel.py`
+
+## Child DOX Index
+
+No child DOX files.

api/api_files_get.py.dox.md

@@ -0,0 +1,52 @@
+# api_files_get.py DOX
+
+## Purpose
+
+- Own the `api_files_get.py` API endpoint.
+- This module returns downloadable or inspectable files exposed through the external API surface.
+- Keep this file-level DOX profile synchronized with `api_files_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `api_files_get.py` owns the runtime implementation.
+- `api_files_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ApiFilesGet` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `requires_api_key(cls) -> bool`
+  - `get_methods(cls) -> list[str]`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ApiFilesGet` is an `ApiHandler`.
+- `ApiFilesGet` defines `process(...)`.
+- `ApiFilesGet` defines `get_methods(...)`.
+- `ApiFilesGet` defines `requires_auth(...)`.
+- `ApiFilesGet` defines `requires_csrf(...)`.
+- `ApiFilesGet` defines `requires_api_key(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
+- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `helpers.print_style`, `json`, `os`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Response`, `PrintStyle.error`, `path.startswith`, `PrintStyle`, `json.dumps`, `path.replace`, `files.get_abs_path`, `os.path.basename`, `os.path.exists`, `PrintStyle.warning`, `f.read`, `base64.b64encode.decode`, `base64.b64encode`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/api_log_get.py.dox.md

@@ -0,0 +1,52 @@
+# api_log_get.py DOX
+
+## Purpose
+
+- Own the `api_log_get.py` API endpoint.
+- This module returns API/chat log data for external API clients.
+- Keep this file-level DOX profile synchronized with `api_log_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `api_log_get.py` owns the runtime implementation.
+- `api_log_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ApiLogGet` (`ApiHandler`)
+  - `get_methods(cls) -> list[str]`
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `requires_api_key(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ApiLogGet` is an `ApiHandler`.
+- `ApiLogGet` defines `process(...)`.
+- `ApiLogGet` defines `get_methods(...)`.
+- `ApiLogGet` defines `requires_auth(...)`.
+- `ApiLogGet` defines `requires_csrf(...)`.
+- `ApiLogGet` defines `requires_api_key(...)`.
+- Observed side-effect areas: settings/state persistence, secret handling.
+- Imported dependency areas include: `agent`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.use`, `Response`, `context.log.output`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/api_message.py.dox.md

@@ -0,0 +1,51 @@
+# api_message.py DOX
+
+## Purpose
+
+- Own the `api_message.py` API endpoint.
+- This module accepts external API messages and dispatches them into Agent Zero chat processing.
+- Keep this file-level DOX profile synchronized with `api_message.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `api_message.py` owns the runtime implementation.
+- `api_message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ApiMessage` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `requires_api_key(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ApiMessage` is an `ApiHandler`.
+- `ApiMessage` defines `process(...)`.
+- `ApiMessage` defines `requires_auth(...)`.
+- `ApiMessage` defines `requires_csrf(...)`.
+- `ApiMessage` defines `requires_api_key(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `agent`, `base64`, `datetime`, `helpers`, `helpers.api`, `helpers.print_style`, `helpers.projects`, `helpers.security`, `initialize`, `os`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `context.set_data`, `datetime.now`, `Response`, `files.get_abs_path`, `os.makedirs`, `AgentContext.use`, `context.get_data`, `initialize_agent`, `AgentContext`, `context.log.log`, `context.communicate`, `ValueError`, `uuid.uuid4`, `UserMessage`, `task.result`, `PrintStyle.error`, `safe_filename`, `base64.b64decode`, `os.path.join`, `activate_project`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_api_chat_lifetime.py`
+
+## Child DOX Index
+
+No child DOX files.

api/api_reset_chat.py.dox.md

@@ -0,0 +1,52 @@
+# api_reset_chat.py DOX
+
+## Purpose
+
+- Own the `api_reset_chat.py` API endpoint.
+- This module resets an API-created chat context.
+- Keep this file-level DOX profile synchronized with `api_reset_chat.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `api_reset_chat.py` owns the runtime implementation.
+- `api_reset_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ApiResetChat` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `requires_api_key(cls) -> bool`
+  - `get_methods(cls) -> list[str]`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ApiResetChat` is an `ApiHandler`.
+- `ApiResetChat` defines `process(...)`.
+- `ApiResetChat` defines `get_methods(...)`.
+- `ApiResetChat` defines `requires_auth(...)`.
+- `ApiResetChat` defines `requires_csrf(...)`.
+- `ApiResetChat` defines `requires_api_key(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.print_style`, `json`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.use`, `context.reset`, `persist_chat.save_tmp_chat`, `persist_chat.remove_msg_files`, `Response`, `PrintStyle.error`, `PrintStyle`, `json.dumps`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/api_terminate_chat.py.dox.md

@@ -0,0 +1,52 @@
+# api_terminate_chat.py DOX
+
+## Purpose
+
+- Own the `api_terminate_chat.py` API endpoint.
+- This module terminates an API-created chat context.
+- Keep this file-level DOX profile synchronized with `api_terminate_chat.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `api_terminate_chat.py` owns the runtime implementation.
+- `api_terminate_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ApiTerminateChat` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `requires_api_key(cls) -> bool`
+  - `get_methods(cls) -> list[str]`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ApiTerminateChat` is an `ApiHandler`.
+- `ApiTerminateChat` defines `process(...)`.
+- `ApiTerminateChat` defines `get_methods(...)`.
+- `ApiTerminateChat` defines `requires_auth(...)`.
+- `ApiTerminateChat` defines `requires_csrf(...)`.
+- `ApiTerminateChat` defines `requires_api_key(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `agent`, `helpers.api`, `helpers.persist_chat`, `helpers.print_style`, `json`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.remove`, `remove_chat`, `Response`, `PrintStyle.error`, `PrintStyle`, `json.dumps`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/backup_create.py.dox.md

@@ -0,0 +1,49 @@
+# backup_create.py DOX
+
+## Purpose
+
+- Own the `backup_create.py` API endpoint.
+- This module handles backup create requests.
+- Keep this file-level DOX profile synchronized with `backup_create.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup_create.py` owns the runtime implementation.
+- `backup_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupCreate` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `BackupCreate` is an `ApiHandler`.
+- `BackupCreate` defines `process(...)`.
+- `BackupCreate` defines `requires_auth(...)`.
+- `BackupCreate` defines `requires_loopback(...)`.
+- Observed side-effect areas: filesystem writes.
+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `save_tmp_chats`, `BackupService`, `send_file`, `backup_service.create_backup`, `line.strip`, `line.startswith`, `patterns_string.split`, `line.strip.startswith`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_download_toast_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.

api/backup_get_defaults.py.dox.md

@@ -0,0 +1,47 @@
+# backup_get_defaults.py DOX
+
+## Purpose
+
+- Own the `backup_get_defaults.py` API endpoint.
+- This module handles backup get defaults requests.
+- Keep this file-level DOX profile synchronized with `backup_get_defaults.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup_get_defaults.py` owns the runtime implementation.
+- `backup_get_defaults.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupGetDefaults` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `BackupGetDefaults` is an `ApiHandler`.
+- `BackupGetDefaults` defines `process(...)`.
+- `BackupGetDefaults` defines `requires_auth(...)`.
+- `BackupGetDefaults` defines `requires_loopback(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.backup`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `BackupService`, `backup_service.get_default_backup_metadata`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/backup_inspect.py.dox.md

@@ -0,0 +1,47 @@
+# backup_inspect.py DOX
+
+## Purpose
+
+- Own the `backup_inspect.py` API endpoint.
+- This module handles backup inspect requests.
+- Keep this file-level DOX profile synchronized with `backup_inspect.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup_inspect.py` owns the runtime implementation.
+- `backup_inspect.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupInspect` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `BackupInspect` is an `ApiHandler`.
+- `BackupInspect` defines `process(...)`.
+- `BackupInspect` defines `requires_auth(...)`.
+- `BackupInspect` defines `requires_loopback(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `werkzeug.datastructures`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `BackupService`, `backup_service.inspect_backup`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/backup_preview_grouped.py.dox.md

@@ -0,0 +1,47 @@
+# backup_preview_grouped.py DOX
+
+## Purpose
+
+- Own the `backup_preview_grouped.py` API endpoint.
+- This module handles backup preview grouped requests.
+- Keep this file-level DOX profile synchronized with `backup_preview_grouped.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup_preview_grouped.py` owns the runtime implementation.
+- `backup_preview_grouped.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupPreviewGrouped` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `BackupPreviewGrouped` is an `ApiHandler`.
+- `BackupPreviewGrouped` defines `process(...)`.
+- `BackupPreviewGrouped` defines `requires_auth(...)`.
+- `BackupPreviewGrouped` defines `requires_loopback(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `BackupService`, `search_filter.strip`, `backup_service.test_patterns`, `search_filter.lower`, `path.strip.split`, `line.strip`, `line.startswith`, `groups.add`, `patterns_string.split`, `path.strip`, `join`, `f.lower`, `line.strip.startswith`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/backup_restore.py.dox.md

@@ -0,0 +1,49 @@
+# backup_restore.py DOX
+
+## Purpose
+
+- Own the `backup_restore.py` API endpoint.
+- This module handles backup restore requests.
+- Keep this file-level DOX profile synchronized with `backup_restore.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup_restore.py` owns the runtime implementation.
+- `backup_restore.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupRestore` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `BackupRestore` is an `ApiHandler`.
+- `BackupRestore` defines `process(...)`.
+- `BackupRestore` defines `requires_auth(...)`.
+- `BackupRestore` defines `requires_loopback(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `helpers.persist_chat`, `json`, `werkzeug.datastructures`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `load_tmp_chats`, `backup_service.restore_backup`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_self_update_tag_filter.py`
+
+## Child DOX Index
+
+No child DOX files.

api/backup_restore_preview.py.dox.md

@@ -0,0 +1,48 @@
+# backup_restore_preview.py DOX
+
+## Purpose
+
+- Own the `backup_restore_preview.py` API endpoint.
+- This module handles backup restore preview requests.
+- Keep this file-level DOX profile synchronized with `backup_restore_preview.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup_restore_preview.py` owns the runtime implementation.
+- `backup_restore_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupRestorePreview` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `BackupRestorePreview` is an `ApiHandler`.
+- `BackupRestorePreview` defines `process(...)`.
+- `BackupRestorePreview` defines `requires_auth(...)`.
+- `BackupRestorePreview` defines `requires_loopback(...)`.
+- Observed side-effect areas: filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `helpers.api`, `helpers.backup`, `json`, `werkzeug.datastructures`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `request.form.get.lower`, `json.loads`, `BackupService`, `backup_service.preview_restore`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/backup_test.py

@@ -47,12 +47,13 @@ class BackupTest(ApiHandler):
 
             backup_service = BackupService()
             matched_files = await backup_service.test_patterns(metadata, max_files=max_files)
+            truncated = max_files is not None and len(matched_files) >= max_files
 
             return {
                 "success": True,
                 "files": matched_files,
                 "total_count": len(matched_files),
-                "truncated": len(matched_files) >= max_files
+                "truncated": truncated
             }
 
         except Exception as e:

api/backup_test.py.dox.md

@@ -0,0 +1,48 @@
+# backup_test.py DOX
+
+## Purpose
+
+- Own the `backup_test.py` API endpoint.
+- This module handles backup test requests.
+- Keep this file-level DOX profile synchronized with `backup_test.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup_test.py` owns the runtime implementation.
+- `backup_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupTest` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `BackupTest` is an `ApiHandler`.
+- `BackupTest` defines `process(...)`.
+- `BackupTest` defines `requires_auth(...)`.
+- `BackupTest` defines `requires_loopback(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.backup`.
+- The `truncated` response flag is true only when a finite `max_files` limit is supplied and the result reaches that limit.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `BackupService`, `backup_service.test_patterns`, `line.strip`, `line.startswith`, `patterns_string.split`, `line.strip.startswith`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/banners.py.dox.md

@@ -0,0 +1,46 @@
+# banners.py DOX
+
+## Purpose
+
+- Own the `banners.py` API endpoint.
+- This module collects alert banners and discovery cards from backend extensions.
+- Keep this file-level DOX profile synchronized with `banners.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `banners.py` owns the runtime implementation.
+- `banners.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GetBanners` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `GetBanners` is an `ApiHandler`.
+- `GetBanners` defines `process(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.extension`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `call_extensions_async`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_model_config_api_keys.py`
+  - `tests/test_oauth_static.py`
+  - `tests/test_webui_extension_surfaces.py`
+
+## Child DOX Index
+
+No child DOX files.

api/cache_reset.py.dox.md

@@ -0,0 +1,53 @@
+# cache_reset.py DOX
+
+## Purpose
+
+- Own the `cache_reset.py` API endpoint.
+- This module handles cache reset API requests.
+- Keep this file-level DOX profile synchronized with `cache_reset.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `cache_reset.py` owns the runtime implementation.
+- `cache_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `CacheReset` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `requires_api_key(cls) -> bool`
+  - `requires_loopback(cls) -> bool`
+  - `get_methods(cls) -> list[str]`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `CacheReset` is an `ApiHandler`.
+- `CacheReset` defines `process(...)`.
+- `CacheReset` defines `get_methods(...)`.
+- `CacheReset` defines `requires_auth(...)`.
+- `CacheReset` defines `requires_csrf(...)`.
+- `CacheReset` defines `requires_api_key(...)`.
+- `CacheReset` defines `requires_loopback(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `cache.clear_all`, `cache.clear`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/chat_create.py.dox.md

@@ -0,0 +1,45 @@
+# chat_create.py DOX
+
+## Purpose
+
+- Own the `chat_create.py` API endpoint.
+- This module handles chat create requests.
+- Keep this file-level DOX profile synchronized with `chat_create.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `chat_create.py` owns the runtime implementation.
+- `chat_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `CreateChat` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `CreateChat` is an `ApiHandler`.
+- `CreateChat` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `mark_dirty_all`, `guids.generate_id`, `current_context.get_data`, `current_context.get_output_data`, `new_context.set_data`, `new_context.set_output_data`, `is_chat_override_allowed`, `settings.get_settings`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_browser_agent_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.

api/chat_export.py.dox.md

@@ -0,0 +1,44 @@
+# chat_export.py DOX
+
+## Purpose
+
+- Own the `chat_export.py` API endpoint.
+- This module handles chat export requests.
+- Keep this file-level DOX profile synchronized with `chat_export.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `chat_export.py` owns the runtime implementation.
+- `chat_export.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ExportChat` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ExportChat` is an `ApiHandler`.
+- `ExportChat` defines `process(...)`.
+- Observed side-effect areas: filesystem writes.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `persist_chat.export_json_chat`, `Exception`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/chat_files_path_get.py.dox.md

@@ -0,0 +1,44 @@
+# chat_files_path_get.py DOX
+
+## Purpose
+
+- Own the `chat_files_path_get.py` API endpoint.
+- This module handles chat files path get requests.
+- Keep this file-level DOX profile synchronized with `chat_files_path_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `chat_files_path_get.py` owns the runtime implementation.
+- `chat_files_path_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GetChatFilesPath` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `GetChatFilesPath` is an `ApiHandler`.
+- `GetChatFilesPath` defines `process(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `projects.get_context_project_name`, `Exception`, `files.normalize_a0_path`, `projects.get_project_folder`, `settings.get_settings`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/chat_load.py.dox.md

@@ -0,0 +1,44 @@
+# chat_load.py DOX
+
+## Purpose
+
+- Own the `chat_load.py` API endpoint.
+- This module handles chat load requests.
+- Keep this file-level DOX profile synchronized with `chat_load.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `chat_load.py` owns the runtime implementation.
+- `chat_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `LoadChats` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `LoadChats` is an `ApiHandler`.
+- `LoadChats` defines `process(...)`.
+- Observed side-effect areas: filesystem writes.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `persist_chat.load_json_chats`, `Exception`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/chat_remove.py.dox.md

@@ -0,0 +1,44 @@
+# chat_remove.py DOX
+
+## Purpose
+
+- Own the `chat_remove.py` API endpoint.
+- This module handles chat remove requests.
+- Keep this file-level DOX profile synchronized with `chat_remove.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `chat_remove.py` owns the runtime implementation.
+- `chat_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `RemoveChat` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `RemoveChat` is an `ApiHandler`.
+- `RemoveChat` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.task_scheduler`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `scheduler.cancel_tasks_by_context`, `AgentContext.use`, `AgentContext.remove`, `persist_chat.remove_chat`, `scheduler.get_tasks_by_context_id`, `mark_dirty_all`, `context.reset`, `scheduler.reload`, `scheduler.remove_task_by_uuid`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/chat_reset.py.dox.md

@@ -0,0 +1,44 @@
+# chat_reset.py DOX
+
+## Purpose
+
+- Own the `chat_reset.py` API endpoint.
+- This module handles chat reset requests.
+- Keep this file-level DOX profile synchronized with `chat_reset.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `chat_reset.py` owns the runtime implementation.
+- `chat_reset.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Reset` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Reset` is an `ApiHandler`.
+- `Reset` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.task_scheduler`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TaskScheduler.get.cancel_tasks_by_context`, `self.use_context`, `context.reset`, `persist_chat.save_tmp_chat`, `persist_chat.remove_msg_files`, `mark_dirty_all`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/csrf_token.py

@@ -1,5 +1,4 @@
 import secrets
-from urllib.parse import urlparse
 from helpers.api import (
     ApiHandler,
     Input,
@@ -9,6 +8,7 @@ from helpers.api import (
     session,
 )
 from helpers import runtime, dotenv, login
+from helpers.tunnel_origins import origin_from_url
 import fnmatch
 
 ALLOWED_ORIGINS_KEY = "ALLOWED_ORIGINS"
@@ -82,11 +82,7 @@ class GetCsrfToken(ApiHandler):
             )
         if not r:
             return None
-        # parse and normalize
-        p = urlparse(r)
-        if not p.scheme or not p.hostname:
-            return None
-        return f"{p.scheme}://{p.hostname}" + (f":{p.port}" if p.port else "")
+        return origin_from_url(r)
 
     async def get_allowed_origins(self) -> list[str]:
         # get the allowed origins from the environment
@@ -107,8 +103,10 @@ class GetCsrfToken(ApiHandler):
             from api.tunnel_proxy import process as tunnel_api_process
 
             tunnel = await tunnel_api_process({"action": "get"})
-            if tunnel and isinstance(tunnel, dict) and tunnel["success"]:
-                allowed_origins.append(tunnel["tunnel_url"])
+            if tunnel and isinstance(tunnel, dict) and tunnel.get("success"):
+                tunnel_origin = origin_from_url(tunnel.get("tunnel_url"))
+                if tunnel_origin:
+                    allowed_origins.append(tunnel_origin)
         except Exception:
             pass
 

api/csrf_token.py.dox.md

@@ -0,0 +1,57 @@
+# csrf_token.py DOX
+
+## Purpose
+
+- Own the `csrf_token.py` API endpoint.
+- This module issues or refreshes CSRF tokens for browser API clients.
+- Keep this file-level DOX profile synchronized with `csrf_token.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `csrf_token.py` owns the runtime implementation.
+- `csrf_token.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GetCsrfToken` (`ApiHandler`)
+  - `get_methods(cls) -> list[str]`
+  - `requires_csrf(cls) -> bool`
+  - `async process(self, input: Input, request: Request) -> Output`
+  - `async check_allowed_origin(self, request: Request)`
+  - `async is_allowed_origin(self, request: Request)`
+  - `get_origin_from_request(self, request: Request)`
+  - `async get_allowed_origins(self) -> list[str]`
+  - `get_default_allowed_origins(self) -> list[str]`
+- Notable constants/configuration names: `ALLOWED_ORIGINS_KEY`.
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `GetCsrfToken` is an `ApiHandler`.
+- `GetCsrfToken` defines `process(...)`.
+- `GetCsrfToken` defines `get_methods(...)`.
+- `GetCsrfToken` defines `requires_csrf(...)`.
+- Observed side-effect areas: filesystem writes, network calls, secret handling, tunnel state.
+- Imported dependency areas include: `fnmatch`, `helpers`, `helpers.api`, `secrets`, `urllib.parse`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `login.is_login_required`, `self.initialize_allowed_origins`, `self.get_origin_from_request`, `urlparse`, `dotenv.get_dotenv_value`, `self.get_default_allowed_origins`, `dotenv.save_dotenv_value`, `self.check_allowed_origin`, `secrets.token_urlsafe`, `runtime.get_runtime_id`, `self.is_allowed_origin`, `self.get_allowed_origins`, `origin.strip`, `join`, `fnmatch.fnmatch`, `split`, `tunnel_api_process`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_http_auth_csrf.py`
+  - `tests/test_self_update_tag_filter.py`
+  - `tests/test_ws_security.py`
+
+## Child DOX Index
+
+No child DOX files.

api/ctx_window_get.py.dox.md

@@ -0,0 +1,44 @@
+# ctx_window_get.py DOX
+
+## Purpose
+
+- Own the `ctx_window_get.py` API endpoint.
+- This module handles ctx window get API requests.
+- Keep this file-level DOX profile synchronized with `ctx_window_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ctx_window_get.py` owns the runtime implementation.
+- `ctx_window_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GetCtxWindow` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `GetCtxWindow` is an `ApiHandler`.
+- `GetCtxWindow` defines `process(...)`.
+- Observed side-effect areas: secret handling.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `agent.get_data`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/delete_work_dir_file.py.dox.md

@@ -0,0 +1,46 @@
+# delete_work_dir_file.py DOX
+
+## Purpose
+
+- Own the `delete_work_dir_file.py` API endpoint.
+- This module handles workdir file operations for delete work dir file.
+- Keep this file-level DOX profile synchronized with `delete_work_dir_file.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `delete_work_dir_file.py` owns the runtime implementation.
+- `delete_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `DeleteWorkDirFile` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+- Top-level functions:
+- `async delete_file(file_path: str)`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `DeleteWorkDirFile` is an `ApiHandler`.
+- `DeleteWorkDirFile` defines `process(...)`.
+- Observed side-effect areas: filesystem deletion.
+- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `FileBrowser`, `browser.delete_file`, `file_path.startswith`, `runtime.call_development_function`, `extension.call_extensions_async`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/delete_work_dir_files.py.dox.md

@@ -0,0 +1,47 @@
+# delete_work_dir_files.py DOX
+
+## Purpose
+
+- Own the `delete_work_dir_files.py` API endpoint.
+- This module handles workdir file operations for delete work dir files.
+- Keep this file-level DOX profile synchronized with `delete_work_dir_files.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `delete_work_dir_files.py` owns the runtime implementation.
+- `delete_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `DeleteWorkDirFiles` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+- Top-level functions:
+- `async delete_files(paths: list[str]) -> dict`
+- `collapse_nested_paths(paths: list[str]) -> list[str]`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `DeleteWorkDirFiles` is an `ApiHandler`.
+- `DeleteWorkDirFiles` defines `process(...)`.
+- Observed side-effect areas: filesystem deletion.
+- Imported dependency areas include: `api`, `api.download_work_dir_files`, `helpers`, `helpers.api`, `helpers.file_browser`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `FileBrowser`, `collapse_nested_paths`, `browser.delete_file`, `normalize_paths`, `runtime.call_development_function`, `path.strip`, `extension.call_extensions_async`, `item.count`, `clean_path.startswith`, `parent.rstrip`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/download_work_dir_file.py.dox.md

@@ -0,0 +1,53 @@
+# download_work_dir_file.py DOX
+
+## Purpose
+
+- Own the `download_work_dir_file.py` API endpoint.
+- This module handles workdir file operations for download work dir file.
+- Keep this file-level DOX profile synchronized with `download_work_dir_file.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `download_work_dir_file.py` owns the runtime implementation.
+- `download_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `DownloadFile` (`ApiHandler`)
+  - `get_methods(cls)`
+  - `async process(self, input: Input, request: Request) -> Output`
+- Top-level functions:
+- `stream_file_download(file_source, download_name, chunk_size=...)`: Create a streaming response for file downloads that shows progress in browser.
+- `make_disposition(download_name: str) -> str`
+- `resolve_download_path(path: str) -> str`: Resolve a requested download path and keep it within the runtime base dir.
+- `async fetch_file(path)`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `DownloadFile` is an `ApiHandler`.
+- `DownloadFile` defines `process(...)`.
+- `DownloadFile` defines `get_methods(...)`.
+- Observed side-effect areas: filesystem reads, network calls.
+- Imported dependency areas include: `api`, `base64`, `flask`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `mimetypes.guess_type`, `Response`, `quote`, `Path.resolve`, `Path`, `candidate.is_absolute`, `os.path.getsize`, `generate`, `download_name.encode.decode`, `candidate.resolve`, `resolve`, `resolved.relative_to`, `Exception`, `file.read`, `base64.b64encode.decode`, `file_source.tell`, `file_source.seek`, `ValueError`, `file_path.startswith`, `runtime.call_development_function`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_download_toast_regressions.py`
+  - `tests/test_office_canvas_setup.py`
+
+## Child DOX Index
+
+No child DOX files.

api/download_work_dir_files.py.dox.md

@@ -0,0 +1,54 @@
+# download_work_dir_files.py DOX
+
+## Purpose
+
+- Own the `download_work_dir_files.py` API endpoint.
+- This module handles workdir file operations for download work dir files.
+- Keep this file-level DOX profile synchronized with `download_work_dir_files.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `download_work_dir_files.py` owns the runtime implementation.
+- `download_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `DownloadFiles` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+- Top-level functions:
+- `normalize_paths(paths) -> list[str]`
+- `selected_archive_name(count: int) -> str`
+- `create_selected_zip(paths: list[str], current_path: str=...) -> str`
+- `resolve_download_path(path: str, base_dir: Path) -> Path`
+- `collapse_nested_paths(paths: list[Path]) -> list[Path]`
+- `archive_root_name(source_path: Path, current_dir: Path | None, base_dir: Path) -> str`
+- `unique_archive_name(name: str, used_names: set[str]) -> str`
+- `write_zip_entry(zip_file: zipfile.ZipFile, source_path: Path, arc_root: str) -> None`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `DownloadFiles` is an `ApiHandler`.
+- `DownloadFiles` defines `process(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
+- Imported dependency areas include: `api.download_work_dir_file`, `base64`, `flask`, `helpers`, `helpers.api`, `helpers.localization`, `io`, `os`, `pathlib`, `tempfile`, `zipfile`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Localization.get.now.strftime`, `Path.resolve`, `normalize_paths`, `collapse_nested_paths`, `Path`, `os.path.splitext`, `source_path.is_dir`, `zip_file.write`, `selected_archive_name`, `runtime.is_development`, `stream_file_download`, `ValueError`, `raw_path.strip`, `resolve_download_path`, `current_dir.is_file`, `resolved.exists`, `FileNotFoundError`, `tempfile.NamedTemporaryFile`, `zipfile.ZipFile`, `candidate.is_absolute`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_download_toast_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.

api/edit_work_dir_file.py.dox.md

@@ -0,0 +1,50 @@
+# edit_work_dir_file.py DOX
+
+## Purpose
+
+- Own the `edit_work_dir_file.py` API endpoint.
+- This module handles workdir file operations for edit work dir file.
+- Keep this file-level DOX profile synchronized with `edit_work_dir_file.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `edit_work_dir_file.py` owns the runtime implementation.
+- `edit_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `EditWorkDirFile` (`ApiHandler`)
+  - `get_methods(cls)`
+  - `async process(self, input: Input, request: Request) -> Output`
+- Top-level functions:
+- `async load_file(file_path: str) -> dict`
+- `save_file(file_path: str, content: str) -> bool`
+- Notable constants/configuration names: `MAX_EDIT_FILE_SIZE`, `BINARY_SAMPLE_SIZE`.
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `EditWorkDirFile` is an `ApiHandler`.
+- `EditWorkDirFile` defines `process(...)`.
+- `EditWorkDirFile` defines `get_methods(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`, `mimetypes`, `os`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `FileBrowser`, `browser.get_full_path`, `os.path.isdir`, `os.path.getsize`, `files.is_probably_binary_file`, `mimetypes.guess_type`, `browser.save_text_file`, `error_str.strip`, `Exception`, `os.path.basename`, `error_str.split`, `file.read`, `line.split.strip`, `file_path.startswith`, `content.encode`, `runtime.call_development_function`, `extension.call_extensions_async`, `self._extract_error_message`, `line.split`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/file_info.py.dox.md

@@ -0,0 +1,47 @@
+# file_info.py DOX
+
+## Purpose
+
+- Own the `file_info.py` API endpoint.
+- This module handles file info API requests.
+- Keep this file-level DOX profile synchronized with `file_info.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `file_info.py` owns the runtime implementation.
+- `file_info.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `FileInfoApi` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+- `FileInfo` (`TypedDict`)
+- Top-level functions:
+- `async get_file_info(path: str) -> FileInfo`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `FileInfoApi` is an `ApiHandler`.
+- `FileInfoApi` defines `process(...)`.
+- Observed side-effect areas: filesystem reads.
+- Imported dependency areas include: `helpers`, `helpers.api`, `os`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `files.get_abs_path`, `os.path.exists`, `os.path.dirname`, `os.path.basename`, `runtime.call_development_function`, `os.path.isdir`, `os.path.isfile`, `os.path.islink`, `os.path.getsize`, `os.path.getmtime`, `os.path.getctime`, `os.path.splitext`, `os.stat`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/get_work_dir_files.py

@@ -9,7 +9,7 @@ class GetWorkDirFiles(ApiHandler):
         return ["GET"]
 
     async def process(self, input: dict, request: Request) -> dict | Response:
-        current_path = request.args.get("path", "")
+        current_path = request.args.get("path", "") or "$WORK_DIR"
         if current_path == "$WORK_DIR":
             # if runtime.is_development():
             #     current_path = "work_dir"

api/get_work_dir_files.py.dox.md

@@ -0,0 +1,48 @@
+# get_work_dir_files.py DOX
+
+## Purpose
+
+- Own the `get_work_dir_files.py` API endpoint.
+- This module handles workdir file operations for get work dir files.
+- Keep this file-level DOX profile synchronized with `get_work_dir_files.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `get_work_dir_files.py` owns the runtime implementation.
+- `get_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GetWorkDirFiles` (`ApiHandler`)
+  - `get_methods(cls)`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+- Top-level functions:
+- `async get_files(path)`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `GetWorkDirFiles` is an `ApiHandler`.
+- `GetWorkDirFiles` defines `process(...)`.
+- `GetWorkDirFiles` defines `get_methods(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.file_browser`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `FileBrowser`, `browser.get_files`, `runtime.call_development_function`.
+- Empty `path` requests and explicit `$WORK_DIR` requests resolve to the default workdir path before `FileBrowser` is called, so the WebUI never receives an empty startup path for the default file browser view.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/health.py.dox.md

@@ -0,0 +1,52 @@
+# health.py DOX
+
+## Purpose
+
+- Own the `health.py` API endpoint.
+- This module reports process health for probes and startup checks.
+- Keep this file-level DOX profile synchronized with `health.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `health.py` owns the runtime implementation.
+- `health.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `HealthCheck` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `get_methods(cls) -> list[str]`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `HealthCheck` is an `ApiHandler`.
+- `HealthCheck` defines `process(...)`.
+- `HealthCheck` defines `get_methods(...)`.
+- `HealthCheck` defines `requires_auth(...)`.
+- `HealthCheck` defines `requires_csrf(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `git.get_git_info`, `errors.error_text`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_oauth_providers.py`
+  - `tests/test_office_document_store.py`
+  - `tests/test_self_update_tag_filter.py`
+
+## Child DOX Index
+
+No child DOX files.

api/history_get.py.dox.md

@@ -0,0 +1,44 @@
+# history_get.py DOX
+
+## Purpose
+
+- Own the `history_get.py` API endpoint.
+- This module handles history get API requests.
+- Keep this file-level DOX profile synchronized with `history_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `history_get.py` owns the runtime implementation.
+- `history_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GetHistory` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `GetHistory` is an `ApiHandler`.
+- `GetHistory` defines `process(...)`.
+- Observed side-effect areas: secret handling.
+- Imported dependency areas include: `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `agent.history.output_text`, `agent.history.get_tokens`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/image_get.py.dox.md

@@ -0,0 +1,53 @@
+# image_get.py DOX
+
+## Purpose
+
+- Own the `image_get.py` API endpoint.
+- This module serves allowed image references and fallback file-type icons.
+- Keep this file-level DOX profile synchronized with `image_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `image_get.py` owns the runtime implementation.
+- `image_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ImageGet` (`ApiHandler`)
+  - `get_methods(cls) -> list[str]`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+- Top-level functions:
+- `_resolve_allowed_image_path(path: str) -> str`: Resolve a requested image path and keep it inside Agent Zero's base dir.
+- `_set_image_headers(response: Response, filename: str, file_ext: str) -> None`
+- `_send_file_type_icon(file_ext, filename=...)`: Return appropriate icon for file type
+- `_send_fallback_icon(icon_name)`: Return fallback icon from public directory
+- Notable constants/configuration names: `IMAGE_EXTENSIONS`, `SVG_EXTENSIONS`, `SVG_CONTENT_SECURITY_POLICY`.
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ImageGet` is an `ApiHandler`.
+- `ImageGet` defines `process(...)`.
+- `ImageGet` defines `get_methods(...)`.
+- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, settings/state persistence.
+- Imported dependency areas include: `base64`, `helpers`, `helpers.api`, `io`, `mimetypes`, `os`, `pathlib`, `urllib.parse`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `runtime.is_development`, `Path.resolve`, `candidate.resolve`, `quote`, `_send_fallback_icon`, `files.get_abs_path`, `send_file`, `os.path.splitext.lower`, `os.path.basename`, `Path`, `candidate.is_absolute`, `resolved.relative_to`, `os.path.exists`, `ValueError`, `_set_image_headers`, `_send_file_type_icon`, `files.fix_dev_path`, `_resolve_allowed_image_path`, `files.exists`, `files.get_base_dir`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_image_get_security.py`
+
+## Child DOX Index
+
+No child DOX files.

api/load_webui_extensions.py.dox.md

@@ -0,0 +1,44 @@
+# load_webui_extensions.py DOX
+
+## Purpose
+
+- Own the `load_webui_extensions.py` API endpoint.
+- This module returns frontend extension manifests/files for a WebUI extension point.
+- Keep this file-level DOX profile synchronized with `load_webui_extensions.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `load_webui_extensions.py` owns the runtime implementation.
+- `load_webui_extensions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `LoadWebuiExtensions` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `LoadWebuiExtensions` is an `ApiHandler`.
+- `LoadWebuiExtensions` defines `process(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `extension.get_webui_extensions`, `Response`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_webui_extension_surfaces.py`
+
+## Child DOX Index
+
+No child DOX files.

api/logout.py.dox.md

@@ -0,0 +1,47 @@
+# logout.py DOX
+
+## Purpose
+
+- Own the `logout.py` API endpoint.
+- This module clears login/session state for the current client.
+- Keep this file-level DOX profile synchronized with `logout.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `logout.py` owns the runtime implementation.
+- `logout.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ApiLogout` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `ApiLogout` is an `ApiHandler`.
+- `ApiLogout` defines `process(...)`.
+- `ApiLogout` defines `requires_auth(...)`.
+- Observed side-effect areas: secret handling.
+- Imported dependency areas include: `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `session.clear`, `session.pop`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.

api/mcp_server_get_detail.py

@@ -9,9 +9,11 @@ class McpServerGetDetail(ApiHandler):
         
         # try:
             server_name = input.get("server_name")
+            project_name = str(input.get("project_name", "") or "").strip()
             if not server_name:
                 return {"success": False, "error": "Missing server_name"}
-            detail = MCPConfig.get_instance().get_server_detail(server_name)
+            config = MCPConfig.get_project_instance(project_name) if project_name else MCPConfig.get_instance()
+            detail = config.get_server_detail(server_name)
             return {"success": True, "detail": detail}
         # except Exception as e:
         #     return {"success": False, "error": str(e)}

api/mcp_server_get_detail.py.dox.md

@@ -0,0 +1,45 @@
+# mcp_server_get_detail.py DOX
+
+## Purpose
+
+- Own the `mcp_server_get_detail.py` API endpoint.
+- This module handles MCP server detail requests for global or project scope.
+- Keep this file-level DOX profile synchronized with `mcp_server_get_detail.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `mcp_server_get_detail.py` owns the runtime implementation.
+- `mcp_server_get_detail.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `McpServerGetDetail` (`ApiHandler`)
+  - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- The request accepts `server_name` and optional `project_name`; when `project_name` is present, detail resolves through the project-scoped MCP configuration.
+- Detail responses include the server tools visible to the manager UI. Tools disabled through a server `disabled_tools` config list remain present in this detail list with a `disabled` flag so the UI can re-enable them.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `McpServerGetDetail` is an `ApiHandler`.
+- `McpServerGetDetail` defines `process(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_detail`, `MCPConfig.get_project_instance`, `MCPConfig.get_instance`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/mcp_server_get_log.py

@@ -9,9 +9,11 @@ class McpServerGetLog(ApiHandler):
         
         # try:
             server_name = input.get("server_name")
+            project_name = str(input.get("project_name", "") or "").strip()
             if not server_name:
                 return {"success": False, "error": "Missing server_name"}
-            log = MCPConfig.get_instance().get_server_log(server_name)
+            config = MCPConfig.get_project_instance(project_name) if project_name else MCPConfig.get_instance()
+            log = config.get_server_log(server_name)
             return {"success": True, "log": log}
         # except Exception as e:
         #     return {"success": False, "error": str(e)}

api/mcp_server_get_log.py.dox.md

@@ -0,0 +1,44 @@
+# mcp_server_get_log.py DOX
+
+## Purpose
+
+- Own the `mcp_server_get_log.py` API endpoint.
+- This module handles MCP server log requests for global or project scope.
+- Keep this file-level DOX profile synchronized with `mcp_server_get_log.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `mcp_server_get_log.py` owns the runtime implementation.
+- `mcp_server_get_log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `McpServerGetLog` (`ApiHandler`)
+  - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- The request accepts `server_name` and optional `project_name`; when `project_name` is present, logs resolve through the project-scoped MCP configuration.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `McpServerGetLog` is an `ApiHandler`.
+- `McpServerGetLog` defines `process(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_server_log`, `MCPConfig.get_project_instance`, `MCPConfig.get_instance`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/mcp_server_scan.py

@@ -0,0 +1,232 @@
+import asyncio
+from shutil import which
+from typing import Any
+from urllib.parse import urlparse
+
+from helpers.api import ApiHandler, Request, Response
+from helpers.mcp_handler import MCPConfig, normalize_name
+
+
+_PROMPT_INJECTION_MARKERS = (
+    "ignore previous",
+    "ignore all previous",
+    "system prompt",
+    "developer message",
+    "hidden instruction",
+    "exfiltrate",
+    "leak secret",
+    "credential",
+)
+
+
+class McpServerScan(ApiHandler):
+    async def process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response:
+        server = dict(input.get("server") or {})
+        allow_local_execution = bool(input.get("allow_local_execution", False))
+        allow_remote_network = bool(input.get("allow_remote_network", False))
+        inspect_runtime = input.get("inspect_runtime", True) is not False
+
+        server = self._normalize_server(server)
+        warnings = self._static_warnings(server)
+        is_local = not (server.get("url") or server.get("serverUrl"))
+        has_static_errors = any(warning.get("level") == "error" for warning in warnings)
+
+        runtime_status: list[dict[str, Any]] = []
+        runtime_detail: dict[str, Any] = {}
+        runtime_error = ""
+
+        should_inspect_runtime = (
+            inspect_runtime
+            and not has_static_errors
+            and ((is_local and allow_local_execution) or (not is_local and allow_remote_network))
+        )
+
+        if should_inspect_runtime:
+            try:
+                scan_config = await asyncio.to_thread(
+                    lambda: MCPConfig(servers_list=[server], config_scope="scan")
+                )
+                runtime_status = scan_config.get_servers_status()
+                runtime_detail = scan_config.get_server_detail(server.get("name", ""))
+                warnings.extend(self._tool_warnings(runtime_detail.get("tools", [])))
+            except Exception as exc:
+                runtime_error = str(exc)
+                warnings.append(
+                    {
+                        "level": "error",
+                        "title": "Runtime inspection failed",
+                        "message": runtime_error,
+                    }
+                )
+        elif is_local and inspect_runtime:
+            warnings.append(
+                {
+                    "level": "warning",
+                    "title": "Local command not executed",
+                    "message": "Local stdio MCP inspection requires explicit trust because it runs the configured command.",
+                }
+            )
+        elif not is_local and inspect_runtime and has_static_errors:
+            warnings.append(
+                {
+                    "level": "info",
+                    "title": "Runtime inspection skipped",
+                    "message": "Fix static scan errors before attempting runtime MCP inspection.",
+                }
+            )
+        elif not is_local and inspect_runtime:
+            warnings.append(
+                {
+                    "level": "info",
+                    "title": "Remote runtime inspection skipped",
+                    "message": "Enable trusted remote inspection to contact the MCP URL and list exposed tools.",
+                }
+            )
+
+        return {
+            "success": True,
+            "server": self._redact_server(server),
+            "risk_level": self._risk_level(warnings),
+            "warnings": warnings,
+            "status": runtime_status,
+            "detail": runtime_detail,
+            "runtime_error": runtime_error,
+        }
+
+    def _normalize_server(self, server: dict[str, Any]) -> dict[str, Any]:
+        name = str(server.get("name") or "").strip()
+        url = str(server.get("url") or server.get("serverUrl") or "").strip()
+        command = str(server.get("command") or "").strip()
+
+        if not name:
+            name = self._derive_name(url, command)
+        server["name"] = normalize_name(name or "mcp_server")
+
+        if url:
+            server["url"] = url
+            server.setdefault("type", "streamable-http")
+        elif command:
+            server["command"] = command
+            server["type"] = "stdio"
+
+        return server
+
+    def _derive_name(self, url: str, command: str) -> str:
+        if url:
+            parsed = urlparse(url)
+            parts = [part for part in parsed.path.split("/") if part]
+            return parts[-1] if parts else parsed.hostname or "remote_mcp"
+        if command:
+            return command.rsplit("/", 1)[-1]
+        return "mcp_server"
+
+    def _static_warnings(self, server: dict[str, Any]) -> list[dict[str, str]]:
+        warnings: list[dict[str, str]] = []
+        url = str(server.get("url") or "").strip()
+        command = str(server.get("command") or "").strip()
+
+        if url:
+            parsed = urlparse(url)
+            if parsed.scheme not in {"http", "https"}:
+                warnings.append(
+                    {
+                        "level": "error",
+                        "title": "Unsupported URL scheme",
+                        "message": "Remote MCP URLs should use http or https.",
+                    }
+                )
+            elif parsed.scheme == "http" and parsed.hostname not in {"localhost", "127.0.0.1", "::1"}:
+                warnings.append(
+                    {
+                        "level": "warning",
+                        "title": "Unencrypted remote URL",
+                        "message": "Prefer HTTPS for remote MCP servers outside localhost.",
+                    }
+                )
+            if not parsed.netloc:
+                warnings.append(
+                    {
+                        "level": "error",
+                        "title": "Invalid remote URL",
+                        "message": "The remote MCP URL is missing a host.",
+                    }
+                )
+        elif command:
+            if which(command) is None:
+                warnings.append(
+                    {
+                        "level": "warning",
+                        "title": "Command not found",
+                        "message": f"'{command}' is not currently available on PATH.",
+                    }
+                )
+            if command in {"bash", "sh", "zsh", "fish", "python", "python3", "node"}:
+                warnings.append(
+                    {
+                        "level": "warning",
+                        "title": "General-purpose interpreter",
+                        "message": "Review the command and arguments carefully before running this local MCP server.",
+                    }
+                )
+        else:
+            warnings.append(
+                {
+                    "level": "error",
+                    "title": "Missing connection target",
+                    "message": "Provide either a remote URL or a local command.",
+                }
+            )
+
+        if isinstance(server.get("headers"), dict) and server["headers"]:
+            warnings.append(
+                {
+                    "level": "info",
+                    "title": "Headers configured",
+                    "message": "Header values are redacted in scan output. Keep tokens in trusted settings only.",
+                }
+            )
+
+        if isinstance(server.get("env"), dict) and server["env"]:
+            warnings.append(
+                {
+                    "level": "info",
+                    "title": "Environment configured",
+                    "message": "Environment values are redacted in scan output. Avoid hardcoding secrets in MCP configs.",
+                }
+            )
+
+        return warnings
+
+    def _tool_warnings(self, tools: Any) -> list[dict[str, str]]:
+        warnings: list[dict[str, str]] = []
+        if not isinstance(tools, list):
+            return warnings
+
+        for tool in tools:
+            if not isinstance(tool, dict):
+                continue
+            haystack = f"{tool.get('name', '')}\n{tool.get('description', '')}".lower()
+            if any(marker in haystack for marker in _PROMPT_INJECTION_MARKERS):
+                warnings.append(
+                    {
+                        "level": "warning",
+                        "title": "Suspicious tool description",
+                        "message": f"Review tool '{tool.get('name', 'unknown')}' for prompt-injection style language.",
+                    }
+                )
+        return warnings
+
+    def _redact_server(self, server: dict[str, Any]) -> dict[str, Any]:
+        redacted = dict(server)
+        for key in ("headers", "env"):
+            if isinstance(redacted.get(key), dict):
+                redacted[key] = {name: "***" for name in redacted[key]}
+        return redacted
+
+    def _risk_level(self, warnings: list[dict[str, str]]) -> str:
+        levels = {warning.get("level", "info") for warning in warnings}
+        if "error" in levels:
+            return "error"
+        if "warning" in levels:
+            return "warning"
+        return "ok"

api/mcp_server_scan.py.dox.md

@@ -0,0 +1,45 @@
+# mcp_server_scan.py DOX
+
+## Purpose
+
+- Own the `mcp_server_scan.py` API endpoint.
+- Provide static and optional runtime inspection for a single MCP server draft before it is added to global or project MCP config.
+- Keep this file-level DOX profile synchronized with `mcp_server_scan.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `mcp_server_scan.py` owns the runtime implementation.
+- `mcp_server_scan.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `McpServerScan` (`ApiHandler`)
+  - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- The request accepts a `server` draft object, `inspect_runtime`, `allow_remote_network`, and `allow_local_execution`.
+- Remote runtime inspection may contact the configured MCP URL to list tools only when `allow_remote_network` is true and static checks have no errors.
+- Local stdio runtime inspection must not execute unless `allow_local_execution` is true.
+- Response data redacts `headers` and `env` values.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- Imported dependency areas include: `asyncio`, `helpers.api`, `helpers.mcp_handler`, `shutil`, `typing`, `urllib.parse`.
+
+## Key Concepts
+
+- Static checks report invalid URLs, non-HTTPS remote URLs, missing local commands, interpreter-style local commands, headers/env presence, and obvious prompt-injection markers in inspected tool descriptions.
+- Static errors skip runtime inspection; remote network inspection and local command execution both require explicit trust flags.
+- Runtime inspection creates a temporary `MCPConfig` in a worker thread so stdio/remote tool listing does not call `asyncio.run()` inside the request event loop.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Do not return secret values, raw environment values, or private files.
+- Keep scanner warnings explicit about local command execution risk.
+
+## Verification
+
+- Run endpoint-specific or MCP helper tests for changed behavior; smoke-test remote URL and local-command scan paths when practical.
+
+## Child DOX Index
+
+No child DOX files.

api/mcp_servers_apply.py

@@ -5,20 +5,27 @@ from typing import Any
 
 from helpers.mcp_handler import MCPConfig
 from helpers.settings import set_settings_delta
+from helpers import projects
 
 
 class McpServersApply(ApiHandler):
     async def process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response:
         mcp_servers = input["mcp_servers"]
+        project_name = str(input.get("project_name", "") or "").strip()
         try:
-            # MCPConfig.update(mcp_servers) # done in settings automatically
-            set_settings_delta({"mcp_servers": "[]"}) # to force reinitialization
-            set_settings_delta({"mcp_servers": mcp_servers})
+            if project_name:
+                projects.save_project_mcp_servers(project_name, mcp_servers)
+                config = MCPConfig.refresh_project(project_name)
+            else:
+                # MCPConfig.update(mcp_servers) # done in settings automatically
+                set_settings_delta({"mcp_servers": "[]"}) # to force reinitialization
+                set_settings_delta({"mcp_servers": mcp_servers})
 
-            time.sleep(1) # wait at least a second
-            # MCPConfig.wait_for_lock() # wait until config lock is released
-            status = MCPConfig.get_instance().get_servers_status()
-            return {"success": True, "status": status}
+                time.sleep(1) # wait at least a second
+                # MCPConfig.wait_for_lock() # wait until config lock is released
+                config = MCPConfig.get_instance()
+            status = config.get_servers_status()
+            return {"success": True, "status": status, "mcp_servers": mcp_servers, "project_name": project_name}
 
         except Exception as e:
             return {"success": False, "error": str(e)}

api/mcp_servers_apply.py.dox.md

@@ -0,0 +1,47 @@
+# mcp_servers_apply.py DOX
+
+## Purpose
+
+- Own the `mcp_servers_apply.py` API endpoint.
+- This module handles MCP servers apply requests for global or project scope.
+- Keep this file-level DOX profile synchronized with `mcp_servers_apply.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `mcp_servers_apply.py` owns the runtime implementation.
+- `mcp_servers_apply.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `McpServersApply` (`ApiHandler`)
+  - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- The request accepts `config` and optional `project_name`.
+- Without `project_name`, the endpoint persists global `mcp_servers_config` through settings and refreshes the global `MCPConfig`.
+- With `project_name`, the endpoint saves `.a0proj/mcp_servers.json` through `helpers.projects.save_project_mcp_servers(...)` and refreshes that project's merged MCP config.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `McpServersApply` is an `ApiHandler`.
+- `McpServersApply` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, settings/state persistence.
+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `helpers.projects`, `helpers.settings`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `set_settings_delta`, `projects.save_project_mcp_servers`, `MCPConfig.refresh_project`, `time.sleep`, `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_instance`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/mcp_servers_status.py

@@ -9,7 +9,9 @@ class McpServersStatuss(ApiHandler):
     async def process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response:
         
         # try:
-            status = MCPConfig.get_instance().get_servers_status()
+            project_name = (input or {}).get("project_name") if isinstance(input, dict) else None
+            config = MCPConfig.get_project_instance(project_name) if project_name else MCPConfig.get_instance()
+            status = config.get_servers_status()
             return {"success": True, "status": status}
         # except Exception as e:
         #     return {"success": False, "error": str(e)}

api/mcp_servers_status.py.dox.md

@@ -0,0 +1,45 @@
+# mcp_servers_status.py DOX
+
+## Purpose
+
+- Own the `mcp_servers_status.py` API endpoint.
+- This module handles MCP servers status requests for global or project scope.
+- Keep this file-level DOX profile synchronized with `mcp_servers_status.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `mcp_servers_status.py` owns the runtime implementation.
+- `mcp_servers_status.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `McpServersStatuss` (`ApiHandler`)
+  - `async process(self, input: dict[Any, Any], request: Request) -> dict[Any, Any] | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- The request accepts optional `project_name`; when present, status resolves through the merged project-scoped MCP configuration.
+- `tool_count` reports enabled MCP tools only; tools disabled by a server `disabled_tools` list stay hidden from agent-facing status counts.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `McpServersStatuss` is an `ApiHandler`.
+- `McpServersStatuss` defines `process(...)`.
+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `MCPConfig.get_instance.get_servers_status`, `MCPConfig.get_project_instance`, `MCPConfig.get_instance`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/message.py.dox.md

@@ -0,0 +1,54 @@
+# message.py DOX
+
+## Purpose
+
+- Own the `message.py` API endpoint.
+- This module submits a user message and runs agent processing synchronously through the UI API.
+- Keep this file-level DOX profile synchronized with `message.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `message.py` owns the runtime implementation.
+- `message.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Message` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+  - `async respond(self, task: DeferredTask, context: AgentContext)`
+  - `async communicate(self, input: dict, request: Request)`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Message` is an `ApiHandler`.
+- `Message` defines `process(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, scheduler state.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.defer`, `helpers.security`, `os`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `request.content_type.startswith`, `self.use_context`, `mq.log_user_message`, `self.communicate`, `self.respond`, `task.result`, `request.files.getlist`, `files.get_abs_path`, `request.get_json`, `extension.call_extensions_async`, `context.communicate`, `os.makedirs`, `UserMessage`, `safe_filename`, `attachment.save`, `context.get_agent`, `os.path.join`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/email_parser_test.py`
+  - `tests/rate_limiter_test.py`
+  - `tests/test_api_chat_lifetime.py`
+  - `tests/test_browser_agent_regressions.py`
+  - `tests/test_chat_compaction.py`
+  - `tests/test_docker_release_plan.py`
+  - `tests/test_document_query_fallback.py`
+  - `tests/test_download_toast_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.

api/message_async.py.dox.md

@@ -0,0 +1,42 @@
+# message_async.py DOX
+
+## Purpose
+
+- Own the `message_async.py` API endpoint.
+- This module submits a user message for asynchronous agent processing.
+- Keep this file-level DOX profile synchronized with `message_async.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `message_async.py` owns the runtime implementation.
+- `message_async.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `MessageAsync` (`Message`)
+  - `async respond(self, task: DeferredTask, context: AgentContext)`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- Observed side-effect areas: scheduler state.
+- Imported dependency areas include: `agent`, `api.message`, `helpers.defer`.
+
+## Key Concepts
+
+- This module is primarily declarative or delegates behavior through classes/imported objects.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/message_queue_add.py.dox.md

@@ -0,0 +1,44 @@
+# message_queue_add.py DOX
+
+## Purpose
+
+- Own the `message_queue_add.py` API endpoint.
+- This module handles message queue add API requests.
+- Keep this file-level DOX profile synchronized with `message_queue_add.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `message_queue_add.py` owns the runtime implementation.
+- `message_queue_add.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `MessageQueueAdd` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `MessageQueueAdd` is an `ApiHandler`.
+- `MessageQueueAdd` defines `process(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `input.get.strip`, `mq.add`, `mark_dirty_for_context`, `Response`, `mq.get_queue`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/message_queue_remove.py.dox.md

@@ -0,0 +1,44 @@
+# message_queue_remove.py DOX
+
+## Purpose
+
+- Own the `message_queue_remove.py` API endpoint.
+- This module handles message queue remove API requests.
+- Keep this file-level DOX profile synchronized with `message_queue_remove.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `message_queue_remove.py` owns the runtime implementation.
+- `message_queue_remove.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `MessageQueueRemove` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `MessageQueueRemove` is an `ApiHandler`.
+- `MessageQueueRemove` defines `process(...)`.
+- Observed side-effect areas: filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `mq.remove`, `mark_dirty_for_context`, `Response`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/message_queue_send.py.dox.md

@@ -0,0 +1,44 @@
+# message_queue_send.py DOX
+
+## Purpose
+
+- Own the `message_queue_send.py` API endpoint.
+- This module handles message queue send API requests.
+- Keep this file-level DOX profile synchronized with `message_queue_send.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `message_queue_send.py` owns the runtime implementation.
+- `message_queue_send.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `MessageQueueSend` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `MessageQueueSend` is an `ApiHandler`.
+- `MessageQueueSend` defines `process(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.state_monitor_integration`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `mq.send_message`, `mark_dirty_for_context`, `Response`, `mq.has_queue`, `mq.send_all_aggregated`, `mq.pop_item`, `mq.pop_first`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/notification_create.py.dox.md

@@ -0,0 +1,46 @@
+# notification_create.py DOX
+
+## Purpose
+
+- Own the `notification_create.py` API endpoint.
+- This module handles notification notification create requests.
+- Keep this file-level DOX profile synchronized with `notification_create.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `notification_create.py` owns the runtime implementation.
+- `notification_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `NotificationCreate` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `NotificationCreate` is an `ApiHandler`.
+- `NotificationCreate` defines `process(...)`.
+- `NotificationCreate` defines `requires_auth(...)`.
+- Imported dependency areas include: `flask`, `helpers.api`, `helpers.notification`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `NotificationManager.send_notification`, `NotificationType`, `notification.output`, `notification_type.lower`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_download_toast_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.

api/notifications_clear.py.dox.md

@@ -0,0 +1,45 @@
+# notifications_clear.py DOX
+
+## Purpose
+
+- Own the `notifications_clear.py` API endpoint.
+- This module handles notification notifications clear requests.
+- Keep this file-level DOX profile synchronized with `notifications_clear.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `notifications_clear.py` owns the runtime implementation.
+- `notifications_clear.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `NotificationsClear` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `NotificationsClear` is an `ApiHandler`.
+- `NotificationsClear` defines `process(...)`.
+- `NotificationsClear` defines `requires_auth(...)`.
+- Imported dependency areas include: `agent`, `flask`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.clear_all`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/notifications_history.py.dox.md

@@ -0,0 +1,45 @@
+# notifications_history.py DOX
+
+## Purpose
+
+- Own the `notifications_history.py` API endpoint.
+- This module handles notification notifications history requests.
+- Keep this file-level DOX profile synchronized with `notifications_history.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `notifications_history.py` owns the runtime implementation.
+- `notifications_history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `NotificationsHistory` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `NotificationsHistory` is an `ApiHandler`.
+- `NotificationsHistory` defines `process(...)`.
+- `NotificationsHistory` defines `requires_auth(...)`.
+- Imported dependency areas include: `agent`, `flask`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.output_all`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/notifications_mark_read.py.dox.md

@@ -0,0 +1,45 @@
+# notifications_mark_read.py DOX
+
+## Purpose
+
+- Own the `notifications_mark_read.py` API endpoint.
+- This module handles notification notifications mark read requests.
+- Keep this file-level DOX profile synchronized with `notifications_mark_read.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `notifications_mark_read.py` owns the runtime implementation.
+- `notifications_mark_read.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `NotificationsMarkRead` (`ApiHandler`)
+  - `requires_auth(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `NotificationsMarkRead` is an `ApiHandler`.
+- `NotificationsMarkRead` defines `process(...)`.
+- `NotificationsMarkRead` defines `requires_auth(...)`.
+- Imported dependency areas include: `agent`, `flask`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager`, `notification_manager.mark_read_by_ids`, `notification_manager.mark_all_read`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/nudge.py.dox.md

@@ -0,0 +1,44 @@
+# nudge.py DOX
+
+## Purpose
+
+- Own the `nudge.py` API endpoint.
+- This module handles nudge API requests.
+- Keep this file-level DOX profile synchronized with `nudge.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `nudge.py` owns the runtime implementation.
+- `nudge.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Nudge` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Nudge` is an `ApiHandler`.
+- `Nudge` defines `process(...)`.
+- Imported dependency areas include: `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `context.nudge`, `context.log.log`, `Exception`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_browser_agent_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.

api/pause.py.dox.md

@@ -0,0 +1,45 @@
+# pause.py DOX
+
+## Purpose
+
+- Own the `pause.py` API endpoint.
+- This module handles pause API requests.
+- Keep this file-level DOX profile synchronized with `pause.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `pause.py` owns the runtime implementation.
+- `pause.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Pause` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Pause` is an `ApiHandler`.
+- `Pause` defines `process(...)`.
+- Imported dependency areas include: `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_multi_tab_isolation.py`
+  - `tests/test_snapshot_schema_v1.py`
+
+## Child DOX Index
+
+No child DOX files.

api/plugins.py.dox.md

@@ -0,0 +1,52 @@
+# plugins.py DOX
+
+## Purpose
+
+- Own the `plugins.py` API endpoint.
+- This module manages plugin actions and plugin settings through the core API.
+- Keep this file-level DOX profile synchronized with `plugins.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `plugins.py` owns the runtime implementation.
+- `plugins.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Plugins` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Plugins` is an `ApiHandler`.
+- `Plugins` defines `process(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.localization`, `json`, `os`, `subprocess`, `sys`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Response`, `plugins.find_plugin_assets`, `plugins.get_plugin_meta`, `plugins.get_default_plugin_config`, `plugins.save_plugin_config`, `plugins.toggle_plugin`, `plugins.find_plugin_dir`, `files.get_abs_path`, `Localization.get.now_iso`, `plugins.determine_plugin_asset_path`, `self._get_config`, `self._get_toggle_status`, `self._list_configs`, `self._delete_config`, `self._delete_plugin`, `self._get_default_config`, `self._save_config`, `self._toggle_plugin`, `self._get_doc`, `self._run_execute_script`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_a0_connector_computer_use_metadata.py`
+  - `tests/test_a0_connector_prompt_gating.py`
+  - `tests/test_browser_agent_regressions.py`
+  - `tests/test_chat_compaction.py`
+  - `tests/test_default_prompt_budget.py`
+  - `tests/test_document_query_plugin.py`
+  - `tests/test_error_retry_plugin.py`
+  - `tests/test_host_browser_connector.py`
+
+## Child DOX Index
+
+No child DOX files.

api/plugins_list.py.dox.md

@@ -0,0 +1,46 @@
+# plugins_list.py DOX
+
+## Purpose
+
+- Own the `plugins_list.py` API endpoint.
+- This module returns plugin inventory and activation metadata for plugin UI surfaces.
+- Keep this file-level DOX profile synchronized with `plugins_list.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `plugins_list.py` owns the runtime implementation.
+- `plugins_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `PluginsList` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `PluginsList` is an `ApiHandler`.
+- `PluginsList` defines `process(...)`.
+- Observed side-effect areas: plugin state, settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `plugins.get_enhanced_plugins_list`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_plugin_activation_ui.py`
+  - `tests/test_speech_plugin_split.py`
+
+## Child DOX Index
+
+No child DOX files.

api/poll.py.dox.md

@@ -0,0 +1,52 @@
+# poll.py DOX
+
+## Purpose
+
+- Own the `poll.py` API endpoint.
+- This module returns chat/log/status changes for polling clients.
+- Keep this file-level DOX profile synchronized with `poll.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `poll.py` owns the runtime implementation.
+- `poll.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Poll` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Poll` is an `ApiHandler`.
+- `Poll` defines `process(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `helpers.api`, `helpers.state_snapshot`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `build_snapshot`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_multi_tab_isolation.py`
+  - `tests/test_oauth_github_copilot.py`
+  - `tests/test_oauth_providers.py`
+  - `tests/test_office_document_store.py`
+  - `tests/test_snapshot_parity.py`
+  - `tests/test_snapshot_schema_v1.py`
+  - `tests/test_timezone_regressions.py`
+  - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.

api/projects.py.dox.md

@@ -0,0 +1,59 @@
+# projects.py DOX
+
+## Purpose
+
+- Own the `projects.py` API endpoint.
+- This module manages project create, update, delete, clone, and metadata flows.
+- Keep this file-level DOX profile synchronized with `projects.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `projects.py` owns the runtime implementation.
+- `projects.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Projects` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+  - `get_active_projects_list(self)`
+  - `get_active_projects_options(self)`
+  - `create_project(self, project: dict | None)`
+  - `clone_project(self, project: dict | None)`
+  - `load_project(self, name: str | None)`
+  - `update_project(self, project: dict | None)`
+  - `delete_project(self, name: str | None)`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Projects` is an `ApiHandler`.
+- `Projects` defines `process(...)`.
+- Observed side-effect areas: filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.notification`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `projects.get_active_projects_list`, `projects.BasicProjectData`, `projects.create_project`, `projects.load_edit_project_data`, `NotificationManager.send_notification`, `projects.EditProjectData`, `projects.update_project`, `projects.delete_project`, `projects.activate_project`, `projects.deactivate_project`, `projects.load_basic_project_data`, `projects.get_file_structure`, `self.use_context`, `Exception`, `projects.clone_git_project`, `self.get_active_projects_list`, `self.get_active_projects_options`, `self.load_project`, `self.create_project`, `self.clone_project`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_model_config_project_presets.py`
+  - `tests/test_office_document_store.py`
+  - `tests/test_plugin_activation_ui.py`
+  - `tests/test_projects.py`
+  - `tests/test_skills_runtime.py`
+  - `tests/test_task_scheduler_timezone.py`
+  - `tests/test_time_travel.py`
+  - `tests/test_tool_action_contracts.py`
+
+## Child DOX Index
+
+No child DOX files.

api/rename_work_dir_file.py.dox.md

@@ -0,0 +1,47 @@
+# rename_work_dir_file.py DOX
+
+## Purpose
+
+- Own the `rename_work_dir_file.py` API endpoint.
+- This module handles workdir file operations for rename work dir file.
+- Keep this file-level DOX profile synchronized with `rename_work_dir_file.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `rename_work_dir_file.py` owns the runtime implementation.
+- `rename_work_dir_file.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `RenameWorkDirFile` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+- Top-level functions:
+- `async rename_item(file_path: str, new_name: str) -> bool`
+- `async create_folder(parent_path: str, folder_name: str) -> bool`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `RenameWorkDirFile` is an `ApiHandler`.
+- `RenameWorkDirFile` defines `process(...)`.
+- Observed side-effect areas: filesystem writes.
+- Imported dependency areas include: `api`, `helpers`, `helpers.api`, `helpers.file_browser`, `posixpath`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `FileBrowser`, `browser.rename_item`, `browser.create_folder`, `strip`, `runtime.call_development_function`, `posixpath.join`, `file_path.startswith`, `extension.call_extensions_async`, `str.rstrip`, `posixpath.dirname`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/restart.py.dox.md

@@ -0,0 +1,48 @@
+# restart.py DOX
+
+## Purpose
+
+- Own the `restart.py` API endpoint.
+- This module requests server restart or reload behavior.
+- Keep this file-level DOX profile synchronized with `restart.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `restart.py` owns the runtime implementation.
+- `restart.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Restart` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `Restart` is an `ApiHandler`.
+- `Restart` defines `process(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `process.reload`, `Response`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_browser_agent_regressions.py`
+  - `tests/test_download_toast_regressions.py`
+  - `tests/test_self_update_tag_filter.py`
+  - `tests/test_timezone_regressions.py`
+  - `tests/test_ws_manager.py`
+
+## Child DOX Index
+
+No child DOX files.

api/rfc.py.dox.md

@@ -0,0 +1,47 @@
+# rfc.py DOX
+
+## Purpose
+
+- Own the `rfc.py` API endpoint.
+- This module dispatches remote function calls through the RFC helper layer.
+- Keep this file-level DOX profile synchronized with `rfc.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `rfc.py` owns the runtime implementation.
+- `rfc.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `RFC` (`ApiHandler`)
+  - `requires_csrf(cls) -> bool`
+  - `requires_auth(cls) -> bool`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `RFC` is an `ApiHandler`.
+- `RFC` defines `process(...)`.
+- `RFC` defines `requires_auth(...)`.
+- `RFC` defines `requires_csrf(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `runtime.handle_rfc`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/scheduler_task_create.py.dox.md

@@ -0,0 +1,44 @@
+# scheduler_task_create.py DOX
+
+## Purpose
+
+- Own the `scheduler_task_create.py` API endpoint.
+- This module handles scheduler task create requests.
+- Keep this file-level DOX profile synchronized with `scheduler_task_create.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `scheduler_task_create.py` owns the runtime implementation.
+- `scheduler_task_create.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SchedulerTaskCreate` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SchedulerTaskCreate` is an `ApiHandler`.
+- `SchedulerTaskCreate` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, secret handling, scheduler state.
+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.projects`, `helpers.task_scheduler`, `random`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `PrintStyle`, `scheduler.get_task_by_uuid`, `serialize_task`, `Localization.get.set_timezone`, `scheduler.reload`, `ValueError`, `ScheduledTask.create`, `scheduler.add_task`, `requested_project_slug.strip`, `load_basic_project_data`, `random.randint`, `schedule.split`, `TaskSchedule`, `PlannedTask.create`, `AdHocTask.create`, `printer.error`, `type`, `parse_task_plan`, `parse_task_schedule`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/scheduler_task_delete.py.dox.md

@@ -0,0 +1,44 @@
+# scheduler_task_delete.py DOX
+
+## Purpose
+
+- Own the `scheduler_task_delete.py` API endpoint.
+- This module handles scheduler task delete requests.
+- Keep this file-level DOX profile synchronized with `scheduler_task_delete.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `scheduler_task_delete.py` owns the runtime implementation.
+- `scheduler_task_delete.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SchedulerTaskDelete` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SchedulerTaskDelete` is an `ApiHandler`.
+- `SchedulerTaskDelete` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.localization`, `helpers.task_scheduler`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `scheduler.get_task_by_uuid`, `Localization.get.set_timezone`, `scheduler.reload`, `self.use_context`, `scheduler.cancel_running_task`, `AgentContext.remove`, `persist_chat.remove_chat`, `scheduler.remove_task_by_uuid`, `context.reset`, `scheduler.update_task`, `scheduler.save`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/scheduler_task_run.py.dox.md

@@ -0,0 +1,44 @@
+# scheduler_task_run.py DOX
+
+## Purpose
+
+- Own the `scheduler_task_run.py` API endpoint.
+- This module handles scheduler task run requests.
+- Keep this file-level DOX profile synchronized with `scheduler_task_run.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `scheduler_task_run.py` owns the runtime implementation.
+- `scheduler_task_run.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SchedulerTaskRun` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SchedulerTaskRun` is an `ApiHandler`.
+- `SchedulerTaskRun` defines `process(...)`.
+- Observed side-effect areas: settings/state persistence, scheduler state.
+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `PrintStyle`, `scheduler.get_task_by_uuid`, `Localization.get.set_timezone`, `scheduler.reload`, `self._printer.error`, `scheduler.serialize_task`, `scheduler.run_task_by_uuid`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/scheduler_task_update.py.dox.md

@@ -0,0 +1,44 @@
+# scheduler_task_update.py DOX
+
+## Purpose
+
+- Own the `scheduler_task_update.py` API endpoint.
+- This module handles scheduler task update requests.
+- Keep this file-level DOX profile synchronized with `scheduler_task_update.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `scheduler_task_update.py` owns the runtime implementation.
+- `scheduler_task_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SchedulerTaskUpdate` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SchedulerTaskUpdate` is an `ApiHandler`.
+- `SchedulerTaskUpdate` defines `process(...)`.
+- Observed side-effect areas: settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.task_scheduler`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `scheduler.get_task_by_uuid`, `serialize_task`, `Localization.get.set_timezone`, `scheduler.reload`, `TaskState`, `scheduler.update_task`, `parse_task_schedule`, `parse_task_plan`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/scheduler_tasks_list.py.dox.md

@@ -0,0 +1,44 @@
+# scheduler_tasks_list.py DOX
+
+## Purpose
+
+- Own the `scheduler_tasks_list.py` API endpoint.
+- This module handles scheduler tasks list requests.
+- Keep this file-level DOX profile synchronized with `scheduler_tasks_list.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `scheduler_tasks_list.py` owns the runtime implementation.
+- `scheduler_tasks_list.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SchedulerTasksList` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SchedulerTasksList` is an `ApiHandler`.
+- `SchedulerTasksList` defines `process(...)`.
+- Observed side-effect areas: scheduler state.
+- Imported dependency areas include: `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`, `traceback`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `scheduler.serialize_all_tasks`, `Localization.get.set_timezone`, `scheduler.reload`, `PrintStyle.error`, `traceback.format_exc`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/scheduler_tick.py.dox.md

@@ -0,0 +1,50 @@
+# scheduler_tick.py DOX
+
+## Purpose
+
+- Own the `scheduler_tick.py` API endpoint.
+- This module handles scheduler tick requests.
+- Keep this file-level DOX profile synchronized with `scheduler_tick.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `scheduler_tick.py` owns the runtime implementation.
+- `scheduler_tick.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SchedulerTick` (`ApiHandler`)
+  - `requires_loopback(cls) -> bool`
+  - `requires_auth(cls) -> bool`
+  - `requires_csrf(cls) -> bool`
+  - `async process(self, input: Input, request: Request) -> Output`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SchedulerTick` is an `ApiHandler`.
+- `SchedulerTick` defines `process(...)`.
+- `SchedulerTick` defines `requires_auth(...)`.
+- `SchedulerTick` defines `requires_csrf(...)`.
+- `SchedulerTick` defines `requires_loopback(...)`.
+- Observed side-effect areas: settings/state persistence, scheduler state.
+- Imported dependency areas include: `datetime`, `helpers.api`, `helpers.localization`, `helpers.print_style`, `helpers.task_scheduler`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `datetime.now.strftime`, `PrintStyle`, `scheduler.get_tasks`, `scheduler.serialize_all_tasks`, `Localization.get.set_timezone`, `scheduler.reload`, `scheduler.tick`, `datetime.now`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/self_update_get.py.dox.md

@@ -0,0 +1,45 @@
+# self_update_get.py DOX
+
+## Purpose
+
+- Own the `self_update_get.py` API endpoint.
+- This module handles self update get API requests.
+- Keep this file-level DOX profile synchronized with `self_update_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `self_update_get.py` owns the runtime implementation.
+- `self_update_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SelfUpdateGet` (`ApiHandler`)
+  - `get_methods(cls) -> list[str]`
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SelfUpdateGet` is an `ApiHandler`.
+- `SelfUpdateGet` defines `process(...)`.
+- `SelfUpdateGet` defines `get_methods(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self_update.get_update_info`, `runtime.is_dockerized`, `self_update.load_pending_update`, `self_update.load_last_status`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.

api/self_update_schedule.py.dox.md

@@ -0,0 +1,45 @@
+# self_update_schedule.py DOX
+
+## Purpose
+
+- Own the `self_update_schedule.py` API endpoint.
+- This module handles self update schedule API requests.
+- Keep this file-level DOX profile synchronized with `self_update_schedule.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `self_update_schedule.py` owns the runtime implementation.
+- `self_update_schedule.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SelfUpdateSchedule` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SelfUpdateSchedule` is an `ApiHandler`.
+- `SelfUpdateSchedule` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, subprocess/runtime control.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `runtime.is_dockerized`, `self_update.schedule_update`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- Related tests observed by source search:
+  - `tests/test_self_update_tag_filter.py`
+
+## Child DOX Index
+
+No child DOX files.

api/self_update_tags.py.dox.md

@@ -0,0 +1,43 @@
+# self_update_tags.py DOX
+
+## Purpose
+
+- Own the `self_update_tags.py` API endpoint.
+- This module handles self update tags API requests.
+- Keep this file-level DOX profile synchronized with `self_update_tags.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `self_update_tags.py` owns the runtime implementation.
+- `self_update_tags.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SelfUpdateTags` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+
+## Runtime Contracts
+
+- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SelfUpdateTags` is an `ApiHandler`.
+- `SelfUpdateTags` defines `process(...)`.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `str.strip.lower`, `self_update.get_repo_version_info.get.strip.lower`, `self_update.get_available_branch_values`, `self_update.get_selector_tag_options`, `str.strip`, `self_update.get_repo_version_info.get.strip`, `runtime.is_dockerized`, `self_update.get_repo_version_info`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve authentication, CSRF, loopback, and API-key checks unless the endpoint contract explicitly changes.
+- Update frontend callers, plugin callers, and tests together when payload shape changes.
+- Use `helpers.api.Response` for non-JSON responses, files, redirects, or status-specific replies.
+
+## Verification
+
+- Run endpoint-specific or API/WebSocket tests for changed behavior; smoke-test browser callers when no focused test exists.
+- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
+
+## Child DOX Index
+
+No child DOX files.