Add file-level DOX docs & update AGENTS indexes

Add comprehensive file-level DOX documentation across the repo and update directory AGENTS.md indexes. Many new `*.py.dox.md` files were added under api, helpers, tools, plugins, extensions, webui, and other dirs to document endpoint purpose, ownership, runtime contracts, work guidance, and verification. Several AGENTS.md files were created or updated (agents profiles, api, docker, extensions, helpers, plugins, skills, webui components, etc.) to list child DOX files and clarify documentation/work guidance. Also add example and bundled profile DOX files (agent0, default, developer, hacker, researcher) and minor updates to helpers/dirty_json.py and its tests. These changes improve on-disk documentation coverage and establish the convention that each direct runtime file should have a matching `*.dox.md` describing its contracts and verification steps.
2026-07-09 17:08:29 +00:00 · 2026-06-08 12:41:53 +02:00 · 2026-06-08 12:41:53 +02:00 · e138e33ca9
commit e138e33ca9
parent 08306be650
312 changed files with 13246 additions and 10 deletions
--- a/api/AGENTS.md
+++ b/api/AGENTS.md
@ -19,17 +19,23 @@
 - 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

--- a/api/agent_profile_set.py.dox.md
+++ b/api/agent_profile_set.py.dox.md
@ -0,0 +1,46 @@
+# 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.
+- Imported dependency areas include: `agent`, `helpers`, `helpers.api`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `initialize`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `str.strip`, `context.is_running`, `_agent_profile_labels`, `initialize_agent`, `save_tmp_chat`, `mark_dirty_for_context`, `subagents.get_all_agents_list`, `Response`, `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.
--- a/api/agents.py.dox.md
+++ b/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.
--- a/api/api_files_get.py.dox.md
+++ b/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.
--- a/api/api_log_get.py.dox.md
+++ b/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.
--- a/api/api_message.py.dox.md
+++ b/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.
--- a/api/api_reset_chat.py.dox.md
+++ b/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.
--- a/api/api_terminate_chat.py.dox.md
+++ b/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.
--- a/api/backup_create.py.dox.md
+++ b/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.
--- a/api/backup_get_defaults.py.dox.md
+++ b/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.
--- a/api/backup_inspect.py.dox.md
+++ b/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.
--- a/api/backup_preview_grouped.py.dox.md
+++ b/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.
--- a/api/backup_restore.py.dox.md
+++ b/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.
--- a/api/backup_restore_preview.py.dox.md
+++ b/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.
--- a/api/backup_test.py.dox.md
+++ b/api/backup_test.py.dox.md
@ -0,0 +1,47 @@
+# 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`.
+
+## 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.
--- a/api/banners.py.dox.md
+++ b/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.
--- a/api/cache_reset.py.dox.md
+++ b/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.
--- a/api/chat_create.py.dox.md
+++ b/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.
--- a/api/chat_export.py.dox.md
+++ b/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.
--- a/api/chat_files_path_get.py.dox.md
+++ b/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.
--- a/api/chat_load.py.dox.md
+++ b/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.
--- a/api/chat_remove.py.dox.md
+++ b/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.
--- a/api/chat_reset.py.dox.md
+++ b/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.
--- a/api/csrf_token.py.dox.md
+++ b/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.
--- a/api/ctx_window_get.py.dox.md
+++ b/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.
--- a/api/delete_work_dir_file.py.dox.md
+++ b/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.
--- a/api/delete_work_dir_files.py.dox.md
+++ b/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.
--- a/api/download_work_dir_file.py.dox.md
+++ b/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.
--- a/api/download_work_dir_files.py.dox.md
+++ b/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.
--- a/api/edit_work_dir_file.py.dox.md
+++ b/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.
--- a/api/file_info.py.dox.md
+++ b/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.
--- a/api/get_work_dir_files.py.dox.md
+++ b/api/get_work_dir_files.py.dox.md
@ -0,0 +1,47 @@
+# 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`.
+- 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.
--- a/api/health.py.dox.md
+++ b/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.
--- a/api/history_get.py.dox.md
+++ b/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.
--- a/api/image_get.py.dox.md
+++ b/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.
--- a/api/load_webui_extensions.py.dox.md
+++ b/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.
--- a/api/logout.py.dox.md
+++ b/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.
--- a/api/mcp_server_get_detail.py.dox.md
+++ b/api/mcp_server_get_detail.py.dox.md
@ -0,0 +1,43 @@
+# mcp_server_get_detail.py DOX
+
+## Purpose
+
+- Own the `mcp_server_get_detail.py` API endpoint.
+- This module handles MCP server server get detail requests.
+- 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`.
+- 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_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.
--- a/api/mcp_server_get_log.py.dox.md
+++ b/api/mcp_server_get_log.py.dox.md
@ -0,0 +1,43 @@
+# mcp_server_get_log.py DOX
+
+## Purpose
+
+- Own the `mcp_server_get_log.py` API endpoint.
+- This module handles MCP server server get log requests.
+- 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`.
+- 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_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.
--- a/api/mcp_servers_apply.py.dox.md
+++ b/api/mcp_servers_apply.py.dox.md
@ -0,0 +1,44 @@
+# mcp_servers_apply.py DOX
+
+## Purpose
+
+- Own the `mcp_servers_apply.py` API endpoint.
+- This module handles MCP server servers apply requests.
+- 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`.
+- 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: settings/state persistence.
+- Imported dependency areas include: `helpers.api`, `helpers.mcp_handler`, `helpers.settings`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `set_settings_delta`, `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.
--- a/api/mcp_servers_status.py.dox.md
+++ b/api/mcp_servers_status.py.dox.md
@ -0,0 +1,43 @@
+# mcp_servers_status.py DOX
+
+## Purpose
+
+- Own the `mcp_servers_status.py` API endpoint.
+- This module handles MCP server servers status requests.
+- 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`.
+- 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_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.
--- a/api/message.py.dox.md
+++ b/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.
--- a/api/message_async.py.dox.md
+++ b/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.
--- a/api/message_queue_add.py.dox.md
+++ b/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.
--- a/api/message_queue_remove.py.dox.md
+++ b/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.
--- a/api/message_queue_send.py.dox.md
+++ b/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.
--- a/api/notification_create.py.dox.md
+++ b/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.
--- a/api/notifications_clear.py.dox.md
+++ b/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.
--- a/api/notifications_history.py.dox.md
+++ b/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.
--- a/api/notifications_mark_read.py.dox.md
+++ b/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.
--- a/api/nudge.py.dox.md
+++ b/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.
--- a/api/pause.py.dox.md
+++ b/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.
--- a/api/plugins.py.dox.md
+++ b/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.
--- a/api/plugins_list.py.dox.md
+++ b/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.
--- a/api/poll.py.dox.md
+++ b/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.
--- a/api/projects.py.dox.md
+++ b/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.
--- a/api/rename_work_dir_file.py.dox.md
+++ b/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.
--- a/api/restart.py.dox.md
+++ b/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.
--- a/api/rfc.py.dox.md
+++ b/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.
--- a/api/scheduler_task_create.py.dox.md
+++ b/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.
--- a/api/scheduler_task_delete.py.dox.md
+++ b/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.
--- a/api/scheduler_task_run.py.dox.md
+++ b/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.
--- a/api/scheduler_task_update.py.dox.md
+++ b/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.
--- a/api/scheduler_tasks_list.py.dox.md
+++ b/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.
--- a/api/scheduler_tick.py.dox.md
+++ b/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.
--- a/api/self_update_get.py.dox.md
+++ b/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.
--- a/api/self_update_schedule.py.dox.md
+++ b/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.
--- a/api/self_update_tags.py.dox.md
+++ b/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.
--- a/api/settings_get.py.dox.md
+++ b/api/settings_get.py.dox.md
@ -0,0 +1,46 @@
+# settings_get.py DOX
+
+## Purpose
+
+- Own the `settings_get.py` API endpoint.
+- This module returns current application settings.
+- Keep this file-level DOX profile synchronized with `settings_get.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `settings_get.py` owns the runtime implementation.
+- `settings_get.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GetSettings` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+  - `get_methods(cls) -> 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.
+- `GetSettings` is an `ApiHandler`.
+- `GetSettings` defines `process(...)`.
+- `GetSettings` defines `get_methods(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `settings.get_settings`, `settings.convert_out`.
+- 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.
--- a/api/settings_set.py.dox.md
+++ b/api/settings_set.py.dox.md
@ -0,0 +1,44 @@
+# settings_set.py DOX
+
+## Purpose
+
+- Own the `settings_set.py` API endpoint.
+- This module persists application settings updates.
+- Keep this file-level DOX profile synchronized with `settings_set.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `settings_set.py` owns the runtime implementation.
+- `settings_set.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SetSettings` (`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`.
+- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
+- `SetSettings` is an `ApiHandler`.
+- `SetSettings` defines `process(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `settings.convert_in`, `settings.set_settings`, `settings.convert_out`, `settings.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.
--- a/api/settings_workdir_file_structure.py.dox.md
+++ b/api/settings_workdir_file_structure.py.dox.md
@ -0,0 +1,46 @@
+# settings_workdir_file_structure.py DOX
+
+## Purpose
+
+- Own the `settings_workdir_file_structure.py` API endpoint.
+- This module handles settings workdir file structure API requests.
+- Keep this file-level DOX profile synchronized with `settings_workdir_file_structure.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `settings_workdir_file_structure.py` owns the runtime implementation.
+- `settings_workdir_file_structure.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SettingsWorkdirFileStructure` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+  - `get_methods(cls) -> 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.
+- `SettingsWorkdirFileStructure` is an `ApiHandler`.
+- `SettingsWorkdirFileStructure` defines `process(...)`.
+- `SettingsWorkdirFileStructure` defines `get_methods(...)`.
+- Observed side-effect areas: filesystem reads, settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `files.get_abs_path_development`, `Exception`, `file_tree.file_tree`.
+- 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.
--- a/api/skills.py.dox.md
+++ b/api/skills.py.dox.md
@ -0,0 +1,54 @@
+# skills.py DOX
+
+## Purpose
+
+- Own the `skills.py` API endpoint.
+- This module lists and manages available skills for settings and agent-facing skill flows.
+- Keep this file-level DOX profile synchronized with `skills.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `skills.py` owns the runtime implementation.
+- `skills.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Skills` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+  - `list_skills(self, input: Input)`
+  - `delete_skill(self, input: Input)`
+
+## 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.
+- `Skills` is an `ApiHandler`.
+- `Skills` defines `process(...)`.
+- Observed side-effect areas: filesystem reads, filesystem deletion.
+- Imported dependency areas include: `helpers`, `helpers.api`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `skills.list_skills`, `result.sort`, `str.strip`, `skills.delete_skill`, `projects.get_project_folder`, `runtime.is_development`, `Exception`, `self.list_skills`, `strip`, `files.normalize_a0_path`, `files.get_abs_path`, `self.delete_skill`, `files.is_in_dir`, `projects.get_project_meta`.
+- 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_prompt_gating.py`
+  - `tests/test_browser_agent_regressions.py`
+  - `tests/test_document_query_plugin.py`
+  - `tests/test_fasta2a_client.py`
+  - `tests/test_office_canvas_setup.py`
+  - `tests/test_office_document_store.py`
+  - `tests/test_skills_runtime.py`
+  - `tests/test_time_travel.py`
+
+## Child DOX Index
+
+No child DOX files.
--- a/api/skills_import.py.dox.md
+++ b/api/skills_import.py.dox.md
@ -0,0 +1,44 @@
+# skills_import.py DOX
+
+## Purpose
+
+- Own the `skills_import.py` API endpoint.
+- This module handles skills import API requests.
+- Keep this file-level DOX profile synchronized with `skills_import.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `skills_import.py` owns the runtime implementation.
+- `skills_import.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SkillsImport` (`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.
+- `SkillsImport` is an `ApiHandler`.
+- `SkillsImport` defines `process(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
+- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `strip.lower`, `Path`, `tmp_dir.mkdir`, `secure_filename`, `time.strftime`, `skills_file.save`, `strip`, `files.get_abs_path`, `base.lower.endswith`, `import_skills`, `files.deabsolute_path`, `uuid.uuid4`, `tmp_path.unlink`, `base.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.
+- 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.
--- a/api/skills_import_preview.py.dox.md
+++ b/api/skills_import_preview.py.dox.md
@ -0,0 +1,44 @@
+# skills_import_preview.py DOX
+
+## Purpose
+
+- Own the `skills_import_preview.py` API endpoint.
+- This module handles skills import preview API requests.
+- Keep this file-level DOX profile synchronized with `skills_import_preview.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `skills_import_preview.py` owns the runtime implementation.
+- `skills_import_preview.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SkillsImportPreview` (`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.
+- `SkillsImportPreview` is an `ApiHandler`.
+- `SkillsImportPreview` defines `process(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
+- Imported dependency areas include: `__future__`, `helpers`, `helpers.api`, `helpers.skills_import`, `os`, `pathlib`, `time`, `uuid`, `werkzeug.datastructures`, `werkzeug.utils`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.use_context`, `strip.lower`, `Path`, `tmp_dir.mkdir`, `secure_filename`, `time.strftime`, `skills_file.save`, `strip`, `files.get_abs_path`, `base.lower.endswith`, `import_skills`, `files.deabsolute_path`, `uuid.uuid4`, `tmp_path.unlink`, `base.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.
+- 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.
--- a/api/subagents.py.dox.md
+++ b/api/subagents.py.dox.md
@ -0,0 +1,49 @@
+# subagents.py DOX
+
+## Purpose
+
+- Own the `subagents.py` API endpoint.
+- This module returns subordinate agent profile data for UI and delegation flows.
+- Keep this file-level DOX profile synchronized with `subagents.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `subagents.py` owns the runtime implementation.
+- `subagents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Subagents` (`ApiHandler`)
+  - `async process(self, input: Input, request: Request) -> Output`
+  - `get_subagents_list(self)`
+  - `load_agent(self, name: str | None)`
+  - `save_agent(self, name: str | None, data: dict | None)`
+  - `delete_agent(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.
+- `Subagents` is an `ApiHandler`.
+- `Subagents` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion.
+- Imported dependency areas include: `helpers`, `helpers.api`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `subagents.get_agents_list`, `subagents.load_agent_data`, `subagents.SubAgent`, `subagents.save_agent_data`, `subagents.delete_agent_data`, `self.use_context`, `Exception`, `self.get_subagents_list`, `self.load_agent`, `self.save_agent`, `self.delete_agent`.
+- 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_skills_runtime.py`
+
+## Child DOX Index
+
+No child DOX files.
--- a/api/tunnel.py.dox.md
+++ b/api/tunnel.py.dox.md
@ -0,0 +1,48 @@
+# tunnel.py DOX
+
+## Purpose
+
+- Own the `tunnel.py` API endpoint.
+- This module manages tunnel provider status, start, and stop actions.
+- Keep this file-level DOX profile synchronized with `tunnel.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `tunnel.py` owns the runtime implementation.
+- `tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Tunnel` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+- Top-level functions:
+- `async process(input: dict) -> dict | Response`
+- `stop()`
+
+## 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.
+- `Tunnel` is an `ApiHandler`.
+- `Tunnel` defines `process(...)`.
+- Observed side-effect areas: tunnel state.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TunnelManager.get_instance`, `tunnel_manager.stop_tunnel`, `runtime.get_web_ui_port`, `tunnel_manager.start_tunnel`, `tunnel_manager.get_last_error`, `process`, `tunnel_manager.get_notifications`, `stop`, `tunnel_manager.get_tunnel_url`.
+- 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_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
--- a/api/tunnel_proxy.py.dox.md
+++ b/api/tunnel_proxy.py.dox.md
@ -0,0 +1,46 @@
+# tunnel_proxy.py DOX
+
+## Purpose
+
+- Own the `tunnel_proxy.py` API endpoint.
+- This module proxies tunnel-related HTTP traffic through the configured tunnel provider.
+- Keep this file-level DOX profile synchronized with `tunnel_proxy.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `tunnel_proxy.py` owns the runtime implementation.
+- `tunnel_proxy.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `TunnelProxy` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+- Top-level functions:
+- `async process(input: dict) -> 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.
+- `TunnelProxy` is an `ApiHandler`.
+- `TunnelProxy` defines `process(...)`.
+- Observed side-effect areas: network calls, settings/state persistence, tunnel state.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.tunnel_manager`, `requests`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `runtime.get_arg`, `requests.post`, `process`, `dotenv.get_dotenv_value`, `response.json`, `local_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.
+- 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.
--- a/api/upload.py.dox.md
+++ b/api/upload.py.dox.md
@ -0,0 +1,47 @@
+# upload.py DOX
+
+## Purpose
+
+- Own the `upload.py` API endpoint.
+- This module accepts general uploads into runtime upload storage.
+- Keep this file-level DOX profile synchronized with `upload.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `upload.py` owns the runtime implementation.
+- `upload.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `UploadFile` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+  - `allowed_file(self, filename)`
+
+## 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.
+- `UploadFile` is an `ApiHandler`.
+- `UploadFile` defines `process(...)`.
+- Observed side-effect areas: filesystem reads, settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.api`, `helpers.security`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `request.files.getlist`, `Exception`, `self.allowed_file`, `safe_filename`, `file.save`, `files.get_abs_path`.
+- 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_image_get_security.py`
+
+## Child DOX Index
+
+No child DOX files.
--- a/api/upload_work_dir_files.py.dox.md
+++ b/api/upload_work_dir_files.py.dox.md
@ -0,0 +1,47 @@
+# upload_work_dir_files.py DOX
+
+## Purpose
+
+- Own the `upload_work_dir_files.py` API endpoint.
+- This module handles workdir file operations for upload work dir files.
+- Keep this file-level DOX profile synchronized with `upload_work_dir_files.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `upload_work_dir_files.py` owns the runtime implementation.
+- `upload_work_dir_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `UploadWorkDirFiles` (`ApiHandler`)
+  - `async process(self, input: dict, request: Request) -> dict | Response`
+- Top-level functions:
+- `async upload_files(uploaded_files: list[FileStorage], current_path: str)`
+- `async upload_file(current_path: str, filename: str, base64_content: 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.
+- `UploadWorkDirFiles` is an `ApiHandler`.
+- `UploadWorkDirFiles` defines `process(...)`.
+- Observed side-effect areas: filesystem writes.
+- Imported dependency areas include: `api`, `base64`, `helpers`, `helpers.api`, `helpers.file_browser`, `os`, `posixpath`, `werkzeug.datastructures`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `runtime.is_development`, `FileBrowser`, `browser.save_file_b64`, `request.files.getlist`, `browser.save_files`, `Exception`, `upload_files`, `runtime.call_development_function`, `file.stream.read`, `base64.b64encode.decode`, `extension.call_extensions_async`, `base64.b64encode`, `posixpath.join`, `str.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.
--- a/api/ws_dev_test.py.dox.md
+++ b/api/ws_dev_test.py.dox.md
@ -0,0 +1,44 @@
+# ws_dev_test.py DOX
+
+## Purpose
+
+- Own the `ws_dev_test.py` API endpoint.
+- This module provides a development WebSocket test namespace.
+- Keep this file-level DOX profile synchronized with `ws_dev_test.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ws_dev_test.py` owns the runtime implementation.
+- `ws_dev_test.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `WsDevTest` (`WsHandler`)
+  - `async process(self, event: str, data: dict, sid: str) -> dict[str, Any] | WsResult | 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.
+- `WsDevTest` is a `WsHandler`.
+- `WsDevTest` defines `process(...)`.
+- Observed side-effect areas: filesystem writes, network calls, WebSocket state.
+- Imported dependency areas include: `asyncio`, `helpers`, `helpers.print_style`, `helpers.ws`, `helpers.ws_manager`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `event.startswith`, `self.manager.register_diagnostic_watcher`, `self.manager.unregister_diagnostic_watcher`, `PrintStyle.info`, `PrintStyle.debug`, `PrintStyle.warning`, `runtime.is_development`, `WsResult.error`, `self.broadcast`, `asyncio.sleep`, `self.emit_to`, `self.dispatch_to_all_sids`.
+- 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.
--- a/api/ws_hello.py.dox.md
+++ b/api/ws_hello.py.dox.md
@ -0,0 +1,44 @@
+# ws_hello.py DOX
+
+## Purpose
+
+- Own the `ws_hello.py` API endpoint.
+- This module provides a small WebSocket hello/test namespace.
+- Keep this file-level DOX profile synchronized with `ws_hello.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ws_hello.py` owns the runtime implementation.
+- `ws_hello.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `WsHello` (`WsHandler`)
+  - `async process(self, event: str, data: dict, sid: str) -> dict | 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.
+- `WsHello` is a `WsHandler`.
+- `WsHello` defines `process(...)`.
+- Observed side-effect areas: WebSocket state.
+- Imported dependency areas include: `helpers.print_style`, `helpers.ws`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `PrintStyle.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.
--- a/api/ws_webui.py.dox.md
+++ b/api/ws_webui.py.dox.md
@ -0,0 +1,49 @@
+# ws_webui.py DOX
+
+## Purpose
+
+- Own the `ws_webui.py` API endpoint.
+- This module owns the primary WebUI WebSocket namespace and event bridge.
+- Keep this file-level DOX profile synchronized with `ws_webui.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ws_webui.py` owns the runtime implementation.
+- `ws_webui.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `WsWebui` (`WsHandler`)
+  - `async on_connect(self, sid: str) -> None`
+  - `async on_disconnect(self, sid: str) -> None`
+  - `async process(self, event: str, data: dict, sid: str) -> dict | 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.
+- `WsWebui` is a `WsHandler`.
+- `WsWebui` defines `process(...)`.
+- Observed side-effect areas: network calls, WebSocket state, settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.ws`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `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.
+- Related tests observed by source search:
+  - `tests/test_state_sync_handler.py`
+  - `tests/test_state_sync_welcome_screen.py`
+  - `tests/test_ws_handlers.py`
+
+## Child DOX Index
+
+No child DOX files.