Skip to content

Agent Zero AI framework

Add file-level DOX docs & update AGENTS indexes

frdele138e33ca998
diff --git a/agents/AGENTS.md b/agents/AGENTS.md
index cce3cbc96..d2df985b1 100644
--- a/agents/AGENTS.md
+++ b/agents/AGENTS.md
@@ -31,4 +31,13 @@
## Child DOX Index
-No child DOX files.
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [_example/AGENTS.md](_example/AGENTS.md) | Reference profile demonstrating profile-local prompts, tools, and extensions. |
+| [agent0/AGENTS.md](agent0/AGENTS.md) | Main user-facing Agent Zero profile metadata. |
+| [default/AGENTS.md](default/AGENTS.md) | Base profile metadata and inherited prompt specifics. |
+| [developer/AGENTS.md](developer/AGENTS.md) | Software development specialist profile. |
+| [hacker/AGENTS.md](hacker/AGENTS.md) | Cyber security and penetration testing specialist profile. |
+| [researcher/AGENTS.md](researcher/AGENTS.md) | Research, data analysis, and reporting specialist profile. |
diff --git a/agents/_example/AGENTS.md b/agents/_example/AGENTS.md
new file mode 100644
index 000000000..555428ee6
--- /dev/null
+++ b/agents/_example/AGENTS.md
@@ -0,0 +1,33 @@
+# Example Agent Profile DOX
+
+## Purpose
+
+- Own the reference profile used to demonstrate bundled profile layout.
+- Show how profile-local prompts, tools, and extensions fit beside `agent.yaml`.
+
+## Ownership
+
+- `agent.yaml` owns the example profile metadata.
+- `prompts/` owns prompt override examples.
+- `tools/` owns profile-local tool examples.
+- `extensions/` owns profile-local lifecycle extension examples.
+
+## Local Contracts
+
+- Keep this profile generic, minimal, and safe to copy into user or plugin profile work.
+- Do not add product behavior here that should live in a real bundled profile.
+- Profile-local tools and extensions must follow the same contracts as root tools and extensions.
+
+## Work Guidance
+
+- Prefer simple examples that illustrate structure over complex behavior.
+- Update related skill guidance when the example profile layout changes.
+
+## Verification
+
+- Manually inspect YAML and prompt filenames after edits.
+- Run profile-loading tests when changing discovery or profile schema assumptions.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/agents/agent0/AGENTS.md b/agents/agent0/AGENTS.md
new file mode 100644
index 000000000..65528190a
--- /dev/null
+++ b/agents/agent0/AGENTS.md
@@ -0,0 +1,31 @@
+# Agent 0 Profile DOX
+
+## Purpose
+
+- Own the main user-facing Agent Zero profile metadata.
+- Keep the primary assistant profile discoverable and distinct from subordinate specialist profiles.
+
+## Ownership
+
+- `agent.yaml` owns the profile title, description, and delegation context.
+- Prompt behavior is inherited from the default profile unless a local prompt override is added.
+
+## Local Contracts
+
+- Keep `Agent 0` suitable as the direct conversation agent for the system.
+- Do not add narrow specialist behavior that belongs in `developer/`, `researcher/`, `hacker/`, or a custom user profile.
+- Do not store user-specific preferences, provider settings, or secrets in this profile.
+
+## Work Guidance
+
+- Keep metadata concise because it appears in profile selection and delegation contexts.
+- Coordinate substantial behavior changes with default prompts and WebUI profile selection.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run profile-loading tests when changing schema or discovery behavior.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/agents/default/AGENTS.md b/agents/default/AGENTS.md
new file mode 100644
index 000000000..130d84cc1
--- /dev/null
+++ b/agents/default/AGENTS.md
@@ -0,0 +1,32 @@
+# Default Agent Profile DOX
+
+## Purpose
+
+- Own base profile metadata and default prompt specifics inherited by specialized profiles.
+- Provide the shared behavior layer for bundled and custom profiles.
+
+## Ownership
+
+- `agent.yaml` owns default profile metadata.
+- `agent.system.main.specifics.md` owns default profile-specific system prompt content.
+- Additional prompt overrides under this directory become shared defaults unless a child profile overrides them.
+
+## Local Contracts
+
+- Keep default behavior broad, framework-compatible, and safe for inheritance.
+- Avoid role-specific instructions that belong in specialist profiles.
+- Prompt filenames must match the framework prompt override names they target.
+
+## Work Guidance
+
+- Prefer small, explicit prompt changes with clear inheritance impact.
+- Check bundled specialist profiles after changing default behavior.
+
+## Verification
+
+- Manually inspect YAML and prompt rendering assumptions after edits.
+- Run prompt/profile tests when changing inherited prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/agents/developer/AGENTS.md b/agents/developer/AGENTS.md
new file mode 100644
index 000000000..b2d189fff
--- /dev/null
+++ b/agents/developer/AGENTS.md
@@ -0,0 +1,32 @@
+# Developer Agent Profile DOX
+
+## Purpose
+
+- Own the bundled software development specialist profile.
+- Keep development, debugging, refactoring, and architecture behavior separate from general agent defaults.
+
+## Ownership
+
+- `agent.yaml` owns title, description, and delegation context for software development work.
+- `prompts/` owns developer-specific prompt overrides when present.
+- `extensions/` owns developer-specific lifecycle hooks when present.
+
+## Local Contracts
+
+- Keep this profile focused on software engineering tasks.
+- Do not hardcode repository-local credentials, paths, or project-specific conventions.
+- Prompt overrides must preserve the framework tool-call and response contracts.
+
+## Work Guidance
+
+- Align developer behavior with the root engineering and tool contracts.
+- Prefer profile prompt edits over core prompt edits when the behavior is specific to development tasks.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run prompt/profile tests when changing profile loading or developer prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/agents/hacker/AGENTS.md b/agents/hacker/AGENTS.md
new file mode 100644
index 000000000..9daeaed00
--- /dev/null
+++ b/agents/hacker/AGENTS.md
@@ -0,0 +1,31 @@
+# Hacker Agent Profile DOX
+
+## Purpose
+
+- Own the bundled cyber security and penetration testing specialist profile.
+- Keep security-audit behavior scoped to this profile instead of default agent behavior.
+
+## Ownership
+
+- `agent.yaml` owns title, description, and delegation context for security work.
+- `prompts/` owns security-specific prompt overrides when present.
+
+## Local Contracts
+
+- Keep the profile focused on authorized security analysis, vulnerability research, and defensive audit tasks.
+- Do not add secrets, target-specific credentials, or local environment assumptions.
+- Preserve the framework tool-call contract and safety expectations.
+
+## Work Guidance
+
+- Keep security instructions operational and bounded to legitimate testing contexts.
+- Coordinate broad safety changes with core prompts and relevant tests.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run prompt/profile tests when changing profile discovery or security prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/agents/researcher/AGENTS.md b/agents/researcher/AGENTS.md
new file mode 100644
index 000000000..e6ba59c70
--- /dev/null
+++ b/agents/researcher/AGENTS.md
@@ -0,0 +1,31 @@
+# Researcher Agent Profile DOX
+
+## Purpose
+
+- Own the bundled research, data analysis, and reporting specialist profile.
+- Keep evidence-gathering and report-oriented behavior separate from general defaults.
+
+## Ownership
+
+- `agent.yaml` owns title, description, and delegation context for research work.
+- `prompts/` owns researcher-specific prompt overrides when present.
+
+## Local Contracts
+
+- Keep this profile focused on information gathering, analysis, synthesis, and reporting.
+- Do not bake in project-specific sources, credentials, or local paths.
+- Preserve the framework tool-call and response contracts.
+
+## Work Guidance
+
+- Prefer prompt changes that improve citation, evidence handling, and analysis quality for research tasks.
+- Coordinate broad research behavior changes with document, memory, or browser plugin contracts when relevant.
+
+## Verification
+
+- Manually inspect `agent.yaml` for valid YAML after edits.
+- Run prompt/profile tests when changing discovery or researcher prompt behavior.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/api/AGENTS.md b/api/AGENTS.md
index 7e471b399..02344d435 100644
--- 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
diff --git a/api/agent_profile_set.py.dox.md b/api/agent_profile_set.py.dox.md
new file mode 100644
index 000000000..845ee9b1d
--- /dev/null
+++ 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.
diff --git a/api/agents.py.dox.md b/api/agents.py.dox.md
new file mode 100644
index 000000000..e7f6895ac
--- /dev/null
+++ 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.
diff --git a/api/api_files_get.py.dox.md b/api/api_files_get.py.dox.md
new file mode 100644
index 000000000..c14bf9f13
--- /dev/null
+++ 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.
diff --git a/api/api_log_get.py.dox.md b/api/api_log_get.py.dox.md
new file mode 100644
index 000000000..043a9c9cf
--- /dev/null
+++ 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.
diff --git a/api/api_message.py.dox.md b/api/api_message.py.dox.md
new file mode 100644
index 000000000..646939cad
--- /dev/null
+++ 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.
diff --git a/api/api_reset_chat.py.dox.md b/api/api_reset_chat.py.dox.md
new file mode 100644
index 000000000..5120f46cd
--- /dev/null
+++ 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.
diff --git a/api/api_terminate_chat.py.dox.md b/api/api_terminate_chat.py.dox.md
new file mode 100644
index 000000000..541a6d007
--- /dev/null
+++ 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.
diff --git a/api/backup_create.py.dox.md b/api/backup_create.py.dox.md
new file mode 100644
index 000000000..be6076326
--- /dev/null
+++ 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.
diff --git a/api/backup_get_defaults.py.dox.md b/api/backup_get_defaults.py.dox.md
new file mode 100644
index 000000000..8f2c1966d
--- /dev/null
+++ 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.
diff --git a/api/backup_inspect.py.dox.md b/api/backup_inspect.py.dox.md
new file mode 100644
index 000000000..363dd63dc
--- /dev/null
+++ 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.
diff --git a/api/backup_preview_grouped.py.dox.md b/api/backup_preview_grouped.py.dox.md
new file mode 100644
index 000000000..24e075981
--- /dev/null
+++ 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.
diff --git a/api/backup_restore.py.dox.md b/api/backup_restore.py.dox.md
new file mode 100644
index 000000000..78e74737d
--- /dev/null
+++ 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.
diff --git a/api/backup_restore_preview.py.dox.md b/api/backup_restore_preview.py.dox.md
new file mode 100644
index 000000000..572473a0a
--- /dev/null
+++ 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.
diff --git a/api/backup_test.py.dox.md b/api/backup_test.py.dox.md
new file mode 100644
index 000000000..c5f01a155
--- /dev/null
+++ 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.
diff --git a/api/banners.py.dox.md b/api/banners.py.dox.md
new file mode 100644
index 000000000..9d007e7d5
--- /dev/null
+++ 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.
diff --git a/api/cache_reset.py.dox.md b/api/cache_reset.py.dox.md
new file mode 100644
index 000000000..a7164d5d5
--- /dev/null
+++ 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.
diff --git a/api/chat_create.py.dox.md b/api/chat_create.py.dox.md
new file mode 100644
index 000000000..3546f4389
--- /dev/null
+++ 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.
diff --git a/api/chat_export.py.dox.md b/api/chat_export.py.dox.md
new file mode 100644
index 000000000..03b5a0c91
--- /dev/null
+++ 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.
diff --git a/api/chat_files_path_get.py.dox.md b/api/chat_files_path_get.py.dox.md
new file mode 100644
index 000000000..63f0a2b6e
--- /dev/null
+++ 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.
diff --git a/api/chat_load.py.dox.md b/api/chat_load.py.dox.md
new file mode 100644
index 000000000..4718a9fc6
--- /dev/null
+++ 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.
diff --git a/api/chat_remove.py.dox.md b/api/chat_remove.py.dox.md
new file mode 100644
index 000000000..ac1ffc0f8
--- /dev/null
+++ 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.
diff --git a/api/chat_reset.py.dox.md b/api/chat_reset.py.dox.md
new file mode 100644
index 000000000..39a886a53
--- /dev/null
+++ 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.
diff --git a/api/csrf_token.py.dox.md b/api/csrf_token.py.dox.md
new file mode 100644
index 000000000..3570d2471
--- /dev/null
+++ 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.
diff --git a/api/ctx_window_get.py.dox.md b/api/ctx_window_get.py.dox.md
new file mode 100644
index 000000000..2de01bf37
--- /dev/null
+++ 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.
diff --git a/api/delete_work_dir_file.py.dox.md b/api/delete_work_dir_file.py.dox.md
new file mode 100644
index 000000000..536b70fcb
--- /dev/null
+++ 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.
diff --git a/api/delete_work_dir_files.py.dox.md b/api/delete_work_dir_files.py.dox.md
new file mode 100644
index 000000000..2c68d3ca2
--- /dev/null
+++ 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.
diff --git a/api/download_work_dir_file.py.dox.md b/api/download_work_dir_file.py.dox.md
new file mode 100644
index 000000000..87085765a
--- /dev/null
+++ 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.
diff --git a/api/download_work_dir_files.py.dox.md b/api/download_work_dir_files.py.dox.md
new file mode 100644
index 000000000..478669fa8
--- /dev/null
+++ 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.
diff --git a/api/edit_work_dir_file.py.dox.md b/api/edit_work_dir_file.py.dox.md
new file mode 100644
index 000000000..e5615517b
--- /dev/null
+++ 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.
diff --git a/api/file_info.py.dox.md b/api/file_info.py.dox.md
new file mode 100644
index 000000000..e3612589d
--- /dev/null
+++ 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.
diff --git a/api/get_work_dir_files.py.dox.md b/api/get_work_dir_files.py.dox.md
new file mode 100644
index 000000000..3d3048650
--- /dev/null
+++ 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.
diff --git a/api/health.py.dox.md b/api/health.py.dox.md
new file mode 100644
index 000000000..236812f56
--- /dev/null
+++ 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.
diff --git a/api/history_get.py.dox.md b/api/history_get.py.dox.md
new file mode 100644
index 000000000..8f2f1ddca
--- /dev/null
+++ 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.
diff --git a/api/image_get.py.dox.md b/api/image_get.py.dox.md
new file mode 100644
index 000000000..b9b0da35b
--- /dev/null
+++ 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.
diff --git a/api/load_webui_extensions.py.dox.md b/api/load_webui_extensions.py.dox.md
new file mode 100644
index 000000000..c2d41e06a
--- /dev/null
+++ 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.
diff --git a/api/logout.py.dox.md b/api/logout.py.dox.md
new file mode 100644
index 000000000..e125a43e7
--- /dev/null
+++ 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.
diff --git a/api/mcp_server_get_detail.py.dox.md b/api/mcp_server_get_detail.py.dox.md
new file mode 100644
index 000000000..e4539d725
--- /dev/null
+++ 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.
diff --git a/api/mcp_server_get_log.py.dox.md b/api/mcp_server_get_log.py.dox.md
new file mode 100644
index 000000000..3baf7453e
--- /dev/null
+++ 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.
diff --git a/api/mcp_servers_apply.py.dox.md b/api/mcp_servers_apply.py.dox.md
new file mode 100644
index 000000000..1a0a0d326
--- /dev/null
+++ 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.
diff --git a/api/mcp_servers_status.py.dox.md b/api/mcp_servers_status.py.dox.md
new file mode 100644
index 000000000..6a66a3eb3
--- /dev/null
+++ 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.
diff --git a/api/message.py.dox.md b/api/message.py.dox.md
new file mode 100644
index 000000000..9ec63fc71
--- /dev/null
+++ 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.
diff --git a/api/message_async.py.dox.md b/api/message_async.py.dox.md
new file mode 100644
index 000000000..6a6ba0093
--- /dev/null
+++ 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.
diff --git a/api/message_queue_add.py.dox.md b/api/message_queue_add.py.dox.md
new file mode 100644
index 000000000..f727a70f1
--- /dev/null
+++ 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.
diff --git a/api/message_queue_remove.py.dox.md b/api/message_queue_remove.py.dox.md
new file mode 100644
index 000000000..8bf876b05
--- /dev/null
+++ 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.
diff --git a/api/message_queue_send.py.dox.md b/api/message_queue_send.py.dox.md
new file mode 100644
index 000000000..4f7294a94
--- /dev/null
+++ 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.
diff --git a/api/notification_create.py.dox.md b/api/notification_create.py.dox.md
new file mode 100644
index 000000000..a83b82cf4
--- /dev/null
+++ 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.
diff --git a/api/notifications_clear.py.dox.md b/api/notifications_clear.py.dox.md
new file mode 100644
index 000000000..dc5503b73
--- /dev/null
+++ 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.
diff --git a/api/notifications_history.py.dox.md b/api/notifications_history.py.dox.md
new file mode 100644
index 000000000..a14b5bc86
--- /dev/null
+++ 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.
diff --git a/api/notifications_mark_read.py.dox.md b/api/notifications_mark_read.py.dox.md
new file mode 100644
index 000000000..a06cbbdcf
--- /dev/null
+++ 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.
diff --git a/api/nudge.py.dox.md b/api/nudge.py.dox.md
new file mode 100644
index 000000000..f1be2cf3d
--- /dev/null
+++ 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.
diff --git a/api/pause.py.dox.md b/api/pause.py.dox.md
new file mode 100644
index 000000000..37d0528e9
--- /dev/null
+++ 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.
diff --git a/api/plugins.py.dox.md b/api/plugins.py.dox.md
new file mode 100644
index 000000000..e64b22dc9
--- /dev/null
+++ 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.
diff --git a/api/plugins_list.py.dox.md b/api/plugins_list.py.dox.md
new file mode 100644
index 000000000..599b5a307
--- /dev/null
+++ 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.
diff --git a/api/poll.py.dox.md b/api/poll.py.dox.md
new file mode 100644
index 000000000..851a03318
--- /dev/null
+++ 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.
diff --git a/api/projects.py.dox.md b/api/projects.py.dox.md
new file mode 100644
index 000000000..d55500c21
--- /dev/null
+++ 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.
diff --git a/api/rename_work_dir_file.py.dox.md b/api/rename_work_dir_file.py.dox.md
new file mode 100644
index 000000000..624bedc54
--- /dev/null
+++ 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.
diff --git a/api/restart.py.dox.md b/api/restart.py.dox.md
new file mode 100644
index 000000000..4e3156f6e
--- /dev/null
+++ 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.
diff --git a/api/rfc.py.dox.md b/api/rfc.py.dox.md
new file mode 100644
index 000000000..6598649ea
--- /dev/null
+++ 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.
diff --git a/api/scheduler_task_create.py.dox.md b/api/scheduler_task_create.py.dox.md
new file mode 100644
index 000000000..332118085
--- /dev/null
+++ 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.
diff --git a/api/scheduler_task_delete.py.dox.md b/api/scheduler_task_delete.py.dox.md
new file mode 100644
index 000000000..2112e95ee
--- /dev/null
+++ 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.
diff --git a/api/scheduler_task_run.py.dox.md b/api/scheduler_task_run.py.dox.md
new file mode 100644
index 000000000..f4aa4b158
--- /dev/null
+++ 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.
diff --git a/api/scheduler_task_update.py.dox.md b/api/scheduler_task_update.py.dox.md
new file mode 100644
index 000000000..a7c9bfced
--- /dev/null
+++ 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.
diff --git a/api/scheduler_tasks_list.py.dox.md b/api/scheduler_tasks_list.py.dox.md
new file mode 100644
index 000000000..5e5533206
--- /dev/null
+++ 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.
diff --git a/api/scheduler_tick.py.dox.md b/api/scheduler_tick.py.dox.md
new file mode 100644
index 000000000..d19ae305c
--- /dev/null
+++ 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.
diff --git a/api/self_update_get.py.dox.md b/api/self_update_get.py.dox.md
new file mode 100644
index 000000000..261cac93f
--- /dev/null
+++ 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.
diff --git a/api/self_update_schedule.py.dox.md b/api/self_update_schedule.py.dox.md
new file mode 100644
index 000000000..b865070c9
--- /dev/null
+++ 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.
diff --git a/api/self_update_tags.py.dox.md b/api/self_update_tags.py.dox.md
new file mode 100644
index 000000000..fdf78cd23
--- /dev/null
+++ 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.
diff --git a/api/settings_get.py.dox.md b/api/settings_get.py.dox.md
new file mode 100644
index 000000000..e584283fd
--- /dev/null
+++ 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.
diff --git a/api/settings_set.py.dox.md b/api/settings_set.py.dox.md
new file mode 100644
index 000000000..0f08f9862
--- /dev/null
+++ 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.
diff --git a/api/settings_workdir_file_structure.py.dox.md b/api/settings_workdir_file_structure.py.dox.md
new file mode 100644
index 000000000..e52a742ef
--- /dev/null
+++ 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.
diff --git a/api/skills.py.dox.md b/api/skills.py.dox.md
new file mode 100644
index 000000000..8da5af317
--- /dev/null
+++ 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.
diff --git a/api/skills_import.py.dox.md b/api/skills_import.py.dox.md
new file mode 100644
index 000000000..4940e833a
--- /dev/null
+++ 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.
diff --git a/api/skills_import_preview.py.dox.md b/api/skills_import_preview.py.dox.md
new file mode 100644
index 000000000..107f55b2a
--- /dev/null
+++ 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.
diff --git a/api/subagents.py.dox.md b/api/subagents.py.dox.md
new file mode 100644
index 000000000..85777218f
--- /dev/null
+++ 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.
diff --git a/api/tunnel.py.dox.md b/api/tunnel.py.dox.md
new file mode 100644
index 000000000..3618edc6e
--- /dev/null
+++ 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.
diff --git a/api/tunnel_proxy.py.dox.md b/api/tunnel_proxy.py.dox.md
new file mode 100644
index 000000000..b713482c9
--- /dev/null
+++ 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.
diff --git a/api/upload.py.dox.md b/api/upload.py.dox.md
new file mode 100644
index 000000000..9fccb571f
--- /dev/null
+++ 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.
diff --git a/api/upload_work_dir_files.py.dox.md b/api/upload_work_dir_files.py.dox.md
new file mode 100644
index 000000000..6cf9370ae
--- /dev/null
+++ 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.
diff --git a/api/ws_dev_test.py.dox.md b/api/ws_dev_test.py.dox.md
new file mode 100644
index 000000000..aaad42608
--- /dev/null
+++ 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.
diff --git a/api/ws_hello.py.dox.md b/api/ws_hello.py.dox.md
new file mode 100644
index 000000000..863b99167
--- /dev/null
+++ 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.
diff --git a/api/ws_webui.py.dox.md b/api/ws_webui.py.dox.md
new file mode 100644
index 000000000..a9cebf317
--- /dev/null
+++ 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.
diff --git a/docker/AGENTS.md b/docker/AGENTS.md
index 0b58f32e8..757608953 100644
--- a/docker/AGENTS.md
+++ b/docker/AGENTS.md
@@ -31,4 +31,9 @@
## Child DOX Index
-No child DOX files.
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [base/AGENTS.md](base/AGENTS.md) | Base image Dockerfile, copied filesystem, and installation scripts. |
+| [run/AGENTS.md](run/AGENTS.md) | Runnable image Dockerfile, compose example, entrypoints, and install scripts. |
diff --git a/docker/base/AGENTS.md b/docker/base/AGENTS.md
new file mode 100644
index 000000000..bcfb986d7
--- /dev/null
+++ b/docker/base/AGENTS.md
@@ -0,0 +1,34 @@
+# Docker Base Image DOX
+
+## Purpose
+
+- Own the Agent Zero base image build context.
+- Build the operating system, package, Python, SearXNG, SSH, and bootstrap layers reused by runnable images.
+
+## Ownership
+
+- `Dockerfile` owns base image layering and installation order.
+- `build.txt` owns maintainer build and push command notes.
+- `fs/ins/` owns installation scripts copied into the image.
+- Files under `fs/` are copied to container root during the base build.
+
+## Local Contracts
+
+- Preserve cache-friendly package and runtime installation stages.
+- Keep locale and timezone defaults compatible with the root Docker contract.
+- Do not add secrets, user data, or local environment files to the image context.
+- Installation scripts must be noninteractive and suitable for multi-architecture buildx runs.
+
+## Work Guidance
+
+- Keep base dependencies here only when they are common to runnable Agent Zero images.
+- Coordinate Python runtime changes with root Docker documentation and runnable image setup.
+
+## Verification
+
+- Build `docker/base` when changing Dockerfile or install scripts.
+- Run a runnable image smoke check when base runtime behavior changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/docker/run/AGENTS.md b/docker/run/AGENTS.md
new file mode 100644
index 000000000..f2bacfdf2
--- /dev/null
+++ b/docker/run/AGENTS.md
@@ -0,0 +1,36 @@
+# Docker Runtime Image DOX
+
+## Purpose
+
+- Own the runnable Agent Zero image context and local compose example.
+- Install Agent Zero from a selected branch onto the base image and prepare runtime entrypoints.
+
+## Ownership
+
+- `Dockerfile` owns branch-based image assembly, exposed ports, and container startup command.
+- `docker-compose.yml` owns the local compose service example.
+- `build.txt` owns maintainer build and push command notes.
+- `fs/exe/` owns runtime entrypoint, supervisor, self-update, Node eval, and service scripts.
+- `fs/ins/` owns preinstall, installation, virtualenv, Playwright, SSH, and postinstall scripts.
+- Files under `fs/` are copied to container root during the runtime build.
+
+## Local Contracts
+
+- `BRANCH` is required for branch-based Docker builds.
+- Preserve exposed ports for SSH, HTTP, and tunneled services unless docs and workflows are updated together.
+- Keep the two-runtime Python model aligned with the root contract.
+- Do not bake secrets, local `.env` values, or user data into the image.
+
+## Work Guidance
+
+- Keep startup scripts explicit about framework runtime versus execution runtime.
+- Coordinate tag, branch, and publishing changes with GitHub workflow automation.
+
+## Verification
+
+- Build `docker/run` when changing Dockerfile or install scripts.
+- Smoke-test container startup after entrypoint, supervisor, port, or compose changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/AGENTS.md b/extensions/python/AGENTS.md
index 53538a8e1..270a98afd 100644
--- a/extensions/python/AGENTS.md
+++ b/extensions/python/AGENTS.md
@@ -31,4 +31,37 @@
## Child DOX Index
-No child DOX files.
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [_functions/AGENTS.md](_functions/AGENTS.md) | Implicit `@extensible` backend hook implementations. |
+| [agent_init/AGENTS.md](agent_init/AGENTS.md) | Agent context initialization hooks. |
+| [banners/AGENTS.md](banners/AGENTS.md) | Backend banner and discovery-card contributions. |
+| [before_main_llm_call/AGENTS.md](before_main_llm_call/AGENTS.md) | Pre-main-model-call behavior. |
+| [error_format/AGENTS.md](error_format/AGENTS.md) | Error formatting and masking behavior. |
+| [hist_add_before/AGENTS.md](hist_add_before/AGENTS.md) | Pre-history-insertion masking behavior. |
+| [hist_add_tool_result/AGENTS.md](hist_add_tool_result/AGENTS.md) | Tool-result history side effects. |
+| [job_loop/AGENTS.md](job_loop/AGENTS.md) | Periodic backend maintenance jobs. |
+| [message_loop_end/AGENTS.md](message_loop_end/AGENTS.md) | End-of-message-loop history and persistence behavior. |
+| [message_loop_prompts_after/AGENTS.md](message_loop_prompts_after/AGENTS.md) | Prompt extras appended after message-loop prompt construction. |
+| [message_loop_prompts_before/AGENTS.md](message_loop_prompts_before/AGENTS.md) | Pre-prompt-construction message-loop gates. |
+| [message_loop_start/AGENTS.md](message_loop_start/AGENTS.md) | Start-of-message-loop iteration state. |
+| [monologue_end/AGENTS.md](monologue_end/AGENTS.md) | End-of-monologue UI and cleanup behavior. |
+| [monologue_start/AGENTS.md](monologue_start/AGENTS.md) | Start-of-monologue behavior such as chat renaming. |
+| [process_chain_end/AGENTS.md](process_chain_end/AGENTS.md) | Process-chain completion and queued-message handling. |
+| [reasoning_stream/AGENTS.md](reasoning_stream/AGENTS.md) | Full reasoning stream handling. |
+| [reasoning_stream_chunk/AGENTS.md](reasoning_stream_chunk/AGENTS.md) | Reasoning stream chunk masking. |
+| [reasoning_stream_end/AGENTS.md](reasoning_stream_end/AGENTS.md) | Reasoning stream finalization. |
+| [response_stream/AGENTS.md](response_stream/AGENTS.md) | Full assistant response stream handling. |
+| [response_stream_chunk/AGENTS.md](response_stream_chunk/AGENTS.md) | Assistant response chunk masking. |
+| [response_stream_end/AGENTS.md](response_stream_end/AGENTS.md) | Assistant response stream finalization. |
+| [startup_migration/AGENTS.md](startup_migration/AGENTS.md) | Startup migrations. |
+| [system_prompt/AGENTS.md](system_prompt/AGENTS.md) | Core system prompt section construction. |
+| [tool_execute_after/AGENTS.md](tool_execute_after/AGENTS.md) | Post-tool-execution processing. |
+| [tool_execute_before/AGENTS.md](tool_execute_before/AGENTS.md) | Pre-tool-execution processing. |
+| [user_message_ui/AGENTS.md](user_message_ui/AGENTS.md) | User-visible UI message hooks. |
+| [util_model_call_before/AGENTS.md](util_model_call_before/AGENTS.md) | Pre-utility-model-call masking. |
+| [webui_ws_connect/AGENTS.md](webui_ws_connect/AGENTS.md) | WebUI WebSocket connect behavior. |
+| [webui_ws_disconnect/AGENTS.md](webui_ws_disconnect/AGENTS.md) | WebUI WebSocket disconnect behavior. |
+| [webui_ws_event/AGENTS.md](webui_ws_event/AGENTS.md) | Incoming WebUI WebSocket event behavior. |
diff --git a/extensions/python/_functions/AGENTS.md b/extensions/python/_functions/AGENTS.md
new file mode 100644
index 000000000..0b21bd510
--- /dev/null
+++ b/extensions/python/_functions/AGENTS.md
@@ -0,0 +1,29 @@
+# Python Function Extensions DOX
+
+## Purpose
+
+- Own implicit `@extensible` backend hook implementations.
+- Preserve nested module, class/function, method, and `start`/`end` extension layout.
+
+## Ownership
+
+- Each nested path mirrors a Python module and qualname segment.
+- Leaf `start/` and `end/` directories own ordered extension files for that extensible function point.
+
+## Local Contracts
+
+- Do not flatten nested qualname paths into retired legacy folder names.
+- Extension functions must match the implicit hook's supplied arguments.
+- Preserve ordering prefixes where exception handling, watchdog registration, or cleanup depends on them.
+
+## Work Guidance
+
+- Keep implicit hook extensions narrow and colocated with the exact function point they extend.
+
+## Verification
+
+- Run targeted tests for the affected function point after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/agent_init/AGENTS.md b/extensions/python/agent_init/AGENTS.md
new file mode 100644
index 000000000..3121c8244
--- /dev/null
+++ b/extensions/python/agent_init/AGENTS.md
@@ -0,0 +1,26 @@
+# Agent Init Extensions DOX
+
+## Purpose
+
+- Own backend extensions that run when an agent context initializes.
+
+## Ownership
+
+- Ordered Python files own initial UI message setup and profile settings load behavior.
+
+## Local Contracts
+
+- Keep initialization idempotent for contexts that may be restored or reloaded.
+- Preserve ordering between initial message creation and profile settings loading.
+
+## Work Guidance
+
+- Coordinate changes with profile loading, settings resolution, and startup smoke checks.
+
+## Verification
+
+- Smoke-test new chat/context initialization after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/banners/AGENTS.md b/extensions/python/banners/AGENTS.md
new file mode 100644
index 000000000..d49581a27
--- /dev/null
+++ b/extensions/python/banners/AGENTS.md
@@ -0,0 +1,27 @@
+# Banner Extensions DOX
+
+## Purpose
+
+- Own backend banner and discovery-card contributions.
+
+## Ownership
+
+- Ordered Python files append alert banners or discovery cards to the mutable `banners` list.
+
+## Local Contracts
+
+- Banner IDs must be unique and stable.
+- Use supported banner/card fields and types only.
+- Do not expose secrets, local paths, or raw system diagnostics in banner text.
+
+## Work Guidance
+
+- Gate setup or warning banners on current configuration/status where possible.
+
+## Verification
+
+- Smoke-test welcome-screen banner rendering, ordering, dismissal, and CTA behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/before_main_llm_call/AGENTS.md b/extensions/python/before_main_llm_call/AGENTS.md
new file mode 100644
index 000000000..36214e3b3
--- /dev/null
+++ b/extensions/python/before_main_llm_call/AGENTS.md
@@ -0,0 +1,26 @@
+# Before Main LLM Call Extensions DOX
+
+## Purpose
+
+- Own backend behavior that runs immediately before the main LLM call.
+
+## Ownership
+
+- Ordered Python files own pre-call logging or context preparation for streaming/model execution.
+
+## Local Contracts
+
+- Do not mutate prompt or history data unless the hook contract explicitly passes mutable state for that purpose.
+- Avoid logging secrets, hidden prompt sections, or private user data.
+
+## Work Guidance
+
+- Keep this hook light because it sits on the main model hot path.
+
+## Verification
+
+- Run targeted model-call or streaming tests after behavior changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/error_format/AGENTS.md b/extensions/python/error_format/AGENTS.md
new file mode 100644
index 000000000..6dd136a73
--- /dev/null
+++ b/extensions/python/error_format/AGENTS.md
@@ -0,0 +1,26 @@
+# Error Format Extensions DOX
+
+## Purpose
+
+- Own backend error formatting and masking before errors are shown or logged.
+
+## Ownership
+
+- Ordered Python files own mutation of error-format data passed by the hook.
+
+## Local Contracts
+
+- Preserve secret masking and safe user-facing error messages.
+- Do not expose raw tokens, credentials, hidden prompts, or private payloads.
+
+## Work Guidance
+
+- Keep masking rules conservative and synchronized with tool/model error surfaces.
+
+## Verification
+
+- Test or inspect representative masked and unmasked error paths after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/hist_add_before/AGENTS.md b/extensions/python/hist_add_before/AGENTS.md
new file mode 100644
index 000000000..7553e0618
--- /dev/null
+++ b/extensions/python/hist_add_before/AGENTS.md
@@ -0,0 +1,26 @@
+# History Add Before Extensions DOX
+
+## Purpose
+
+- Own preprocessing before messages are added to agent history.
+
+## Ownership
+
+- Ordered Python files own history content masking before persistence or model reuse.
+
+## Local Contracts
+
+- Preserve secret and sensitive-content masking before history storage.
+- Do not remove fields required by downstream history organization or replay.
+
+## Work Guidance
+
+- Coordinate history mutation changes with message persistence and memory behavior.
+
+## Verification
+
+- Test message history insertion for masked content after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/hist_add_tool_result/AGENTS.md b/extensions/python/hist_add_tool_result/AGENTS.md
new file mode 100644
index 000000000..0c92126a9
--- /dev/null
+++ b/extensions/python/hist_add_tool_result/AGENTS.md
@@ -0,0 +1,26 @@
+# History Tool Result Extensions DOX
+
+## Purpose
+
+- Own processing after tool results are added to history.
+
+## Ownership
+
+- Ordered Python files own tool-call file persistence and related history side effects.
+
+## Local Contracts
+
+- Preserve tool result traceability without leaking secrets.
+- Keep file artifacts inside expected runtime/user-owned paths.
+
+## Work Guidance
+
+- Coordinate changes with tool output storage and chat persistence behavior.
+
+## Verification
+
+- Smoke-test a tool call that produces persisted output after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/job_loop/AGENTS.md b/extensions/python/job_loop/AGENTS.md
new file mode 100644
index 000000000..afa7597a3
--- /dev/null
+++ b/extensions/python/job_loop/AGENTS.md
@@ -0,0 +1,26 @@
+# Job Loop Extensions DOX
+
+## Purpose
+
+- Own periodic backend maintenance jobs.
+
+## Ownership
+
+- Ordered Python files own cleanup of expired API chats, cache trimming, and future job-loop tasks.
+
+## Local Contracts
+
+- Jobs must be idempotent and safe to run repeatedly.
+- Keep cleanup scoped to owned caches, temporary contexts, or documented runtime state.
+
+## Work Guidance
+
+- Avoid expensive work on every loop; use timestamps or thresholds when practical.
+
+## Verification
+
+- Run targeted cleanup/cache tests or smoke-test job-loop startup after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/message_loop_end/AGENTS.md b/extensions/python/message_loop_end/AGENTS.md
new file mode 100644
index 000000000..8927890a9
--- /dev/null
+++ b/extensions/python/message_loop_end/AGENTS.md
@@ -0,0 +1,26 @@
+# Message Loop End Extensions DOX
+
+## Purpose
+
+- Own backend behavior that runs after a message loop completes.
+
+## Ownership
+
+- Ordered Python files own history organization and chat persistence at loop end.
+
+## Local Contracts
+
+- Preserve history consistency before saving chats.
+- Do not skip persistence for successful loops unless the hook contract explicitly permits it.
+
+## Work Guidance
+
+- Coordinate changes with chat serialization, history organization, and WebUI refresh behavior.
+
+## Verification
+
+- Smoke-test sending a message, reloading the chat, and checking persisted history after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/message_loop_prompts_after/AGENTS.md b/extensions/python/message_loop_prompts_after/AGENTS.md
new file mode 100644
index 000000000..c19db6eb0
--- /dev/null
+++ b/extensions/python/message_loop_prompts_after/AGENTS.md
@@ -0,0 +1,27 @@
+# Message Loop Prompts After Extensions DOX
+
+## Purpose
+
+- Own prompt extras appended after primary message-loop prompt construction.
+
+## Ownership
+
+- Ordered Python files own current datetime, skill recall/load context, agent info, and workdir extras injection.
+
+## Local Contracts
+
+- Keep injected content bounded and clearly attributed.
+- Preserve ordering where later prompt extras depend on earlier recall or load results.
+- Do not expose secrets or private files from workdir extras.
+
+## Work Guidance
+
+- Coordinate prompt-extra changes with skill, workdir, and profile contracts.
+
+## Verification
+
+- Inspect rendered prompt extras or run prompt-construction tests after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/message_loop_prompts_before/AGENTS.md b/extensions/python/message_loop_prompts_before/AGENTS.md
new file mode 100644
index 000000000..3483592c7
--- /dev/null
+++ b/extensions/python/message_loop_prompts_before/AGENTS.md
@@ -0,0 +1,26 @@
+# Message Loop Prompts Before Extensions DOX
+
+## Purpose
+
+- Own preprocessing before message-loop prompt construction.
+
+## Ownership
+
+- Ordered Python files own history organization waits and related prompt-preparation gates.
+
+## Local Contracts
+
+- Preserve history consistency before prompts are assembled.
+- Avoid blocking indefinitely on background organization tasks.
+
+## Work Guidance
+
+- Keep waiting behavior observable and bounded.
+
+## Verification
+
+- Smoke-test prompt construction after chats with pending history organization.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/message_loop_start/AGENTS.md b/extensions/python/message_loop_start/AGENTS.md
new file mode 100644
index 000000000..a0c6c1790
--- /dev/null
+++ b/extensions/python/message_loop_start/AGENTS.md
@@ -0,0 +1,26 @@
+# Message Loop Start Extensions DOX
+
+## Purpose
+
+- Own backend behavior that runs at the start of each message loop iteration.
+
+## Ownership
+
+- Ordered Python files own iteration counters and future loop-start state setup.
+
+## Local Contracts
+
+- Keep per-loop counters deterministic and scoped to the active context.
+- Do not reset state owned by monologue-level hooks.
+
+## Work Guidance
+
+- Coordinate loop-start state changes with logging, streaming, and process-chain behavior.
+
+## Verification
+
+- Smoke-test multi-turn conversations after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/monologue_end/AGENTS.md b/extensions/python/monologue_end/AGENTS.md
new file mode 100644
index 000000000..b842ba071
--- /dev/null
+++ b/extensions/python/monologue_end/AGENTS.md
@@ -0,0 +1,26 @@
+# Monologue End Extensions DOX
+
+## Purpose
+
+- Own backend behavior that runs when a monologue ends.
+
+## Ownership
+
+- Ordered Python files own waiting-for-input UI message behavior and future monologue-end cleanup.
+
+## Local Contracts
+
+- Preserve clear UI state when the agent stops for user input.
+- Do not leave loading/processing indicators stale.
+
+## Work Guidance
+
+- Coordinate changes with WebUI loading state and message-loop persistence.
+
+## Verification
+
+- Smoke-test an agent response that returns to waiting-for-input state.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/monologue_start/AGENTS.md b/extensions/python/monologue_start/AGENTS.md
new file mode 100644
index 000000000..93615ed68
--- /dev/null
+++ b/extensions/python/monologue_start/AGENTS.md
@@ -0,0 +1,26 @@
+# Monologue Start Extensions DOX
+
+## Purpose
+
+- Own backend behavior that runs when a monologue starts.
+
+## Ownership
+
+- Ordered Python files own automatic chat renaming and future monologue-start setup.
+
+## Local Contracts
+
+- Keep automatic rename behavior bounded and non-destructive.
+- Do not override explicit user chat names without the intended guard conditions.
+
+## Work Guidance
+
+- Coordinate rename behavior with chat persistence and WebUI refresh.
+
+## Verification
+
+- Smoke-test new chat naming and existing named chat behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/process_chain_end/AGENTS.md b/extensions/python/process_chain_end/AGENTS.md
new file mode 100644
index 000000000..c70340417
--- /dev/null
+++ b/extensions/python/process_chain_end/AGENTS.md
@@ -0,0 +1,26 @@
+# Process Chain End Extensions DOX
+
+## Purpose
+
+- Own backend behavior after process-chain execution completes.
+
+## Ownership
+
+- Ordered Python files own queued-message processing and future process-chain completion behavior.
+
+## Local Contracts
+
+- Preserve queue ordering and avoid duplicate message processing.
+- Keep queue side effects synchronized with chat persistence and WebUI state.
+
+## Work Guidance
+
+- Coordinate changes with message queue components and external integration plugins.
+
+## Verification
+
+- Smoke-test queued messages and final response handling after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/reasoning_stream/AGENTS.md b/extensions/python/reasoning_stream/AGENTS.md
new file mode 100644
index 000000000..6cd3e6b2e
--- /dev/null
+++ b/extensions/python/reasoning_stream/AGENTS.md
@@ -0,0 +1,26 @@
+# Reasoning Stream Extensions DOX
+
+## Purpose
+
+- Own handling of full reasoning stream updates.
+
+## Ownership
+
+- Ordered Python files own logging reasoning content from stream state.
+
+## Local Contracts
+
+- Preserve masking and privacy rules for reasoning content.
+- Keep stream logging compatible with chunk and end hooks.
+
+## Work Guidance
+
+- Coordinate reasoning stream changes with UI log rendering and hidden-content policy.
+
+## Verification
+
+- Smoke-test reasoning stream display/logging when the active model provides reasoning.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/reasoning_stream_chunk/AGENTS.md b/extensions/python/reasoning_stream_chunk/AGENTS.md
new file mode 100644
index 000000000..4e7461224
--- /dev/null
+++ b/extensions/python/reasoning_stream_chunk/AGENTS.md
@@ -0,0 +1,26 @@
+# Reasoning Stream Chunk Extensions DOX
+
+## Purpose
+
+- Own handling of incremental reasoning stream chunks.
+
+## Ownership
+
+- Ordered Python files own chunk-level masking before reasoning is displayed or stored.
+
+## Local Contracts
+
+- Mask secrets and sensitive content before chunk data reaches logs or UI.
+- Keep chunk mutation compatible with final stream-end masking.
+
+## Work Guidance
+
+- Keep chunk processing lightweight for streaming performance.
+
+## Verification
+
+- Smoke-test streamed reasoning with representative sensitive patterns after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/reasoning_stream_end/AGENTS.md b/extensions/python/reasoning_stream_end/AGENTS.md
new file mode 100644
index 000000000..d702b22ad
--- /dev/null
+++ b/extensions/python/reasoning_stream_end/AGENTS.md
@@ -0,0 +1,26 @@
+# Reasoning Stream End Extensions DOX
+
+## Purpose
+
+- Own finalization of reasoning stream content.
+
+## Ownership
+
+- Ordered Python files own final reasoning masking and end-of-stream cleanup.
+
+## Local Contracts
+
+- Preserve final masking even if earlier chunk masking missed content.
+- Keep end-state consistent with reasoning stream log entries.
+
+## Work Guidance
+
+- Coordinate final masking changes with chunk masking and UI rendering.
+
+## Verification
+
+- Smoke-test reasoning stream completion with sensitive-content cases.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/response_stream/AGENTS.md b/extensions/python/response_stream/AGENTS.md
new file mode 100644
index 000000000..53a42df09
--- /dev/null
+++ b/extensions/python/response_stream/AGENTS.md
@@ -0,0 +1,27 @@
+# Response Stream Extensions DOX
+
+## Purpose
+
+- Own handling of full assistant response stream updates.
+
+## Ownership
+
+- Ordered Python files own response logging, include-alias replacement, and live response updates.
+
+## Local Contracts
+
+- Keep streaming output synchronized with UI log items.
+- Preserve include-alias replacement semantics where prompts/tools rely on them.
+- Do not expose unmasked secrets in live responses.
+
+## Work Guidance
+
+- Coordinate stream changes with chunk/end hooks and message rendering.
+
+## Verification
+
+- Smoke-test streamed responses, live updates, and include alias replacement after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/response_stream_chunk/AGENTS.md b/extensions/python/response_stream_chunk/AGENTS.md
new file mode 100644
index 000000000..9ceff97a6
--- /dev/null
+++ b/extensions/python/response_stream_chunk/AGENTS.md
@@ -0,0 +1,26 @@
+# Response Stream Chunk Extensions DOX
+
+## Purpose
+
+- Own handling of incremental assistant response chunks.
+
+## Ownership
+
+- Ordered Python files own chunk-level response masking.
+
+## Local Contracts
+
+- Mask secrets before response chunks reach UI or persisted logs.
+- Keep chunk processing compatible with final response stream masking.
+
+## Work Guidance
+
+- Keep per-chunk work lightweight for streaming responsiveness.
+
+## Verification
+
+- Smoke-test streaming responses with sensitive patterns after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/response_stream_end/AGENTS.md b/extensions/python/response_stream_end/AGENTS.md
new file mode 100644
index 000000000..963620e5d
--- /dev/null
+++ b/extensions/python/response_stream_end/AGENTS.md
@@ -0,0 +1,26 @@
+# Response Stream End Extensions DOX
+
+## Purpose
+
+- Own finalization of assistant response stream content.
+
+## Ownership
+
+- Ordered Python files own final masking and stream-end log updates.
+
+## Local Contracts
+
+- Preserve final masking before response content is considered complete.
+- Keep log state consistent with streamed chunks and final response text.
+
+## Work Guidance
+
+- Coordinate finalization changes with live response and message rendering behavior.
+
+## Verification
+
+- Smoke-test response completion and persisted message display after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/startup_migration/AGENTS.md b/extensions/python/startup_migration/AGENTS.md
new file mode 100644
index 000000000..a4c9e202a
--- /dev/null
+++ b/extensions/python/startup_migration/AGENTS.md
@@ -0,0 +1,27 @@
+# Startup Migration Extensions DOX
+
+## Purpose
+
+- Own backend startup migrations.
+
+## Ownership
+
+- Ordered Python files in this folder own idempotent migration steps that run during startup.
+
+## Local Contracts
+
+- Migrations must be safe to run repeatedly.
+- Preserve user data and create backups or reversible paths when changing durable state.
+- Keep long-running work bounded and observable.
+
+## Work Guidance
+
+- Add migrations only for durable state changes that cannot be handled lazily elsewhere.
+
+## Verification
+
+- Smoke-test startup on a clean checkout and on representative existing user state when practical.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/system_prompt/AGENTS.md b/extensions/python/system_prompt/AGENTS.md
new file mode 100644
index 000000000..bc4ee6448
--- /dev/null
+++ b/extensions/python/system_prompt/AGENTS.md
@@ -0,0 +1,27 @@
+# System Prompt Extensions DOX
+
+## Purpose
+
+- Own construction of core system prompt sections.
+
+## Ownership
+
+- Ordered Python files own main, tools, MCP, secrets, skills, and project prompt sections.
+
+## Local Contracts
+
+- Preserve ordering where sections depend on earlier context.
+- Keep secret-related prompt sections masked and scoped.
+- Prompt additions must be bounded and compatible with tool-call contracts.
+
+## Work Guidance
+
+- Coordinate broad system prompt changes with profiles, skills, tools, plugins, and prompt tests.
+
+## Verification
+
+- Inspect rendered system prompts or run prompt-construction tests after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/tool_execute_after/AGENTS.md b/extensions/python/tool_execute_after/AGENTS.md
new file mode 100644
index 000000000..54c4557c5
--- /dev/null
+++ b/extensions/python/tool_execute_after/AGENTS.md
@@ -0,0 +1,26 @@
+# Tool Execute After Extensions DOX
+
+## Purpose
+
+- Own backend processing immediately after tool execution.
+
+## Ownership
+
+- Ordered Python files own post-tool secret masking and future tool-result postprocessing.
+
+## Local Contracts
+
+- Mask secrets before tool results reach history, UI, or model-visible context.
+- Do not alter tool `break_loop` or response semantics unless the hook contract owns that behavior.
+
+## Work Guidance
+
+- Coordinate with tool implementations and history hooks when changing tool result data.
+
+## Verification
+
+- Smoke-test tool execution with sensitive output after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/tool_execute_before/AGENTS.md b/extensions/python/tool_execute_before/AGENTS.md
new file mode 100644
index 000000000..6d5f6f8bf
--- /dev/null
+++ b/extensions/python/tool_execute_before/AGENTS.md
@@ -0,0 +1,27 @@
+# Tool Execute Before Extensions DOX
+
+## Purpose
+
+- Own backend processing immediately before tool execution.
+
+## Ownership
+
+- Ordered Python files own prior tool-output replacement and secret unmasking before execution.
+
+## Local Contracts
+
+- Unmask only values required by the target tool.
+- Preserve safety checks and do not expose secrets to logs or unrelated tools.
+- Keep ordering stable where replacement must occur before unmasking or execution.
+
+## Work Guidance
+
+- Coordinate with secret handling, tool argument preparation, and plugin tool gates.
+
+## Verification
+
+- Smoke-test tool execution with masked secret arguments and prior-output references after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/user_message_ui/AGENTS.md b/extensions/python/user_message_ui/AGENTS.md
new file mode 100644
index 000000000..55428a4d7
--- /dev/null
+++ b/extensions/python/user_message_ui/AGENTS.md
@@ -0,0 +1,26 @@
+# User Message UI Extensions DOX
+
+## Purpose
+
+- Own backend behavior triggered around user-visible UI messages.
+
+## Ownership
+
+- Ordered Python files own update-check messaging and future user-message UI hooks.
+
+## Local Contracts
+
+- Keep proactive UI messages relevant, non-spammy, and safe for display.
+- Do not expose local diagnostics or update data that should stay internal.
+
+## Work Guidance
+
+- Gate recurring messages so they do not repeat unnecessarily across chats or tabs.
+
+## Verification
+
+- Smoke-test UI message rendering after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/util_model_call_before/AGENTS.md b/extensions/python/util_model_call_before/AGENTS.md
new file mode 100644
index 000000000..dc0bd77f8
--- /dev/null
+++ b/extensions/python/util_model_call_before/AGENTS.md
@@ -0,0 +1,26 @@
+# Utility Model Call Before Extensions DOX
+
+## Purpose
+
+- Own preprocessing before utility model calls.
+
+## Ownership
+
+- Ordered Python files own secret masking and future utility-call preparation.
+
+## Local Contracts
+
+- Mask secrets before utility prompts leave the framework.
+- Keep utility model inputs compatible with callers expecting structured outputs.
+
+## Work Guidance
+
+- Coordinate masking changes with main model call and error-format masking behavior.
+
+## Verification
+
+- Test utility model calls that include masked secret patterns after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/webui_ws_connect/AGENTS.md b/extensions/python/webui_ws_connect/AGENTS.md
new file mode 100644
index 000000000..f722ae7b2
--- /dev/null
+++ b/extensions/python/webui_ws_connect/AGENTS.md
@@ -0,0 +1,26 @@
+# WebUI WebSocket Connect Extensions DOX
+
+## Purpose
+
+- Own backend behavior when a WebUI WebSocket client connects.
+
+## Ownership
+
+- Ordered Python files own state-sync behavior for new WebSocket connections.
+
+## Local Contracts
+
+- Preserve WebSocket auth/session assumptions.
+- Send only state the connected client is allowed to receive.
+
+## Work Guidance
+
+- Coordinate connect behavior with frontend WebSocket client and sync store.
+
+## Verification
+
+- Smoke-test WebUI connection and initial state sync after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/webui_ws_disconnect/AGENTS.md b/extensions/python/webui_ws_disconnect/AGENTS.md
new file mode 100644
index 000000000..703652891
--- /dev/null
+++ b/extensions/python/webui_ws_disconnect/AGENTS.md
@@ -0,0 +1,26 @@
+# WebUI WebSocket Disconnect Extensions DOX
+
+## Purpose
+
+- Own backend behavior when a WebUI WebSocket client disconnects.
+
+## Ownership
+
+- Ordered Python files own state-sync cleanup for disconnect events.
+
+## Local Contracts
+
+- Cleanup must be idempotent and safe for repeated disconnect events.
+- Do not remove shared state still needed by other active clients.
+
+## Work Guidance
+
+- Coordinate disconnect behavior with frontend reconnect and sync indicators.
+
+## Verification
+
+- Smoke-test disconnect and reconnect behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/python/webui_ws_event/AGENTS.md b/extensions/python/webui_ws_event/AGENTS.md
new file mode 100644
index 000000000..a47e147b2
--- /dev/null
+++ b/extensions/python/webui_ws_event/AGENTS.md
@@ -0,0 +1,26 @@
+# WebUI WebSocket Event Extensions DOX
+
+## Purpose
+
+- Own backend behavior for incoming WebUI WebSocket events.
+
+## Ownership
+
+- Ordered Python files own state-sync event handling and future WebSocket event extensions.
+
+## Local Contracts
+
+- Validate event names and payloads before acting on them.
+- Preserve auth/session boundaries for all WebSocket events.
+
+## Work Guidance
+
+- Coordinate event changes with frontend WebSocket client and sync store.
+
+## Verification
+
+- Smoke-test relevant WebSocket events after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/AGENTS.md b/extensions/webui/AGENTS.md
index 11f949ca5..d2421a144 100644
--- a/extensions/webui/AGENTS.md
+++ b/extensions/webui/AGENTS.md
@@ -31,4 +31,17 @@
## Child DOX Index
-No child DOX files.
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [fetch_api_call_after/AGENTS.md](fetch_api_call_after/AGENTS.md) | Frontend hooks after raw `fetchApi()` calls. |
+| [fetch_api_call_before/AGENTS.md](fetch_api_call_before/AGENTS.md) | Frontend hooks before raw `fetchApi()` calls. |
+| [get_message_handler/AGENTS.md](get_message_handler/AGENTS.md) | Message rendering handler extensions. |
+| [initFw_end/AGENTS.md](initFw_end/AGENTS.md) | Post-WebUI-framework-initialization extensions. |
+| [json_api_call_after/AGENTS.md](json_api_call_after/AGENTS.md) | Frontend hooks after `callJsonApi()` calls. |
+| [json_api_call_before/AGENTS.md](json_api_call_before/AGENTS.md) | Frontend hooks before `callJsonApi()` calls. |
+| [right_canvas_register_surfaces/AGENTS.md](right_canvas_register_surfaces/AGENTS.md) | Built-in right-canvas surface registrations. |
+| [set_messages_after_loop/AGENTS.md](set_messages_after_loop/AGENTS.md) | Frontend hooks after message DOM updates. |
+| [set_messages_before_loop/AGENTS.md](set_messages_before_loop/AGENTS.md) | Frontend hooks before message DOM updates. |
+| [webui_ws_push/AGENTS.md](webui_ws_push/AGENTS.md) | WebUI WebSocket push-event behavior. |
diff --git a/extensions/webui/fetch_api_call_after/AGENTS.md b/extensions/webui/fetch_api_call_after/AGENTS.md
new file mode 100644
index 000000000..963be5f11
--- /dev/null
+++ b/extensions/webui/fetch_api_call_after/AGENTS.md
@@ -0,0 +1,26 @@
+# Fetch API Call After Extensions DOX
+
+## Purpose
+
+- Own frontend extension hooks that run after raw `fetchApi()` calls.
+
+## Ownership
+
+- Files in this folder own after-call behavior for CSRF-aware raw fetch flows.
+
+## Local Contracts
+
+- JavaScript modules must export a default function when present.
+- Do not consume response bodies unless the hook contract explicitly passes a clone or mutable context for that purpose.
+
+## Work Guidance
+
+- Keep after-call extensions lightweight and safe for all fetch callers.
+
+## Verification
+
+- Smoke-test frontend API calls after adding behavior here.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/fetch_api_call_before/AGENTS.md b/extensions/webui/fetch_api_call_before/AGENTS.md
new file mode 100644
index 000000000..c715757d5
--- /dev/null
+++ b/extensions/webui/fetch_api_call_before/AGENTS.md
@@ -0,0 +1,26 @@
+# Fetch API Call Before Extensions DOX
+
+## Purpose
+
+- Own frontend extension hooks that run before raw `fetchApi()` calls.
+
+## Ownership
+
+- Files in this folder own before-call behavior for CSRF-aware raw fetch flows.
+
+## Local Contracts
+
+- JavaScript modules must export a default function when present.
+- Preserve CSRF, auth, and redirect behavior owned by `/js/api.js`.
+
+## Work Guidance
+
+- Avoid broad request mutation that surprises unrelated API callers.
+
+## Verification
+
+- Smoke-test affected frontend API calls after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/get_message_handler/AGENTS.md b/extensions/webui/get_message_handler/AGENTS.md
new file mode 100644
index 000000000..ea0a36977
--- /dev/null
+++ b/extensions/webui/get_message_handler/AGENTS.md
@@ -0,0 +1,27 @@
+# Get Message Handler Extensions DOX
+
+## Purpose
+
+- Own frontend extensions that provide or modify message rendering handlers.
+
+## Ownership
+
+- Files in this folder own handler registration behavior for rendered chat messages.
+
+## Local Contracts
+
+- JavaScript modules must export a default function when present.
+- Preserve mutable context contracts used by `/js/messages.js`.
+- Do not render unsanitized model or user content.
+
+## Work Guidance
+
+- Coordinate handler changes with message components and plugin message extensions.
+
+## Verification
+
+- Smoke-test message rendering for affected message types after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/initFw_end/AGENTS.md b/extensions/webui/initFw_end/AGENTS.md
new file mode 100644
index 000000000..5f18507b4
--- /dev/null
+++ b/extensions/webui/initFw_end/AGENTS.md
@@ -0,0 +1,27 @@
+# Init Framework End Extensions DOX
+
+## Purpose
+
+- Own frontend extensions that run after WebUI framework initialization.
+
+## Ownership
+
+- JavaScript files own post-bootstrap global setup such as self-update helpers.
+
+## Local Contracts
+
+- JavaScript modules must export a default function.
+- Setup must be idempotent across reloads and cache resets.
+- Do not register duplicate global listeners.
+
+## Work Guidance
+
+- Coordinate initialization changes with `/js/initFw.js` and component lifecycle directives.
+
+## Verification
+
+- Smoke-test WebUI startup and browser console after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/json_api_call_after/AGENTS.md b/extensions/webui/json_api_call_after/AGENTS.md
new file mode 100644
index 000000000..96f356b8d
--- /dev/null
+++ b/extensions/webui/json_api_call_after/AGENTS.md
@@ -0,0 +1,26 @@
+# JSON API Call After Extensions DOX
+
+## Purpose
+
+- Own frontend extension hooks that run after `callJsonApi()` calls.
+
+## Ownership
+
+- JavaScript files own after-call behavior such as cache reset handling.
+
+## Local Contracts
+
+- JavaScript modules must export a default function.
+- Preserve JSON API response contracts and avoid hiding errors from callers.
+
+## Work Guidance
+
+- Keep global side effects narrow and tied to explicit API results or mutable contexts.
+
+## Verification
+
+- Smoke-test JSON API callers affected by extension changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/json_api_call_before/AGENTS.md b/extensions/webui/json_api_call_before/AGENTS.md
new file mode 100644
index 000000000..b14f04ea9
--- /dev/null
+++ b/extensions/webui/json_api_call_before/AGENTS.md
@@ -0,0 +1,26 @@
+# JSON API Call Before Extensions DOX
+
+## Purpose
+
+- Own frontend extension hooks that run before `callJsonApi()` calls.
+
+## Ownership
+
+- Files in this folder own before-call behavior for JSON API requests.
+
+## Local Contracts
+
+- JavaScript modules must export a default function when present.
+- Preserve CSRF/auth behavior and JSON payload shape expected by `/js/api.js`.
+
+## Work Guidance
+
+- Avoid broad request mutation that affects unrelated plugin or core API calls.
+
+## Verification
+
+- Smoke-test affected JSON API calls after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/right_canvas_register_surfaces/AGENTS.md b/extensions/webui/right_canvas_register_surfaces/AGENTS.md
new file mode 100644
index 000000000..d62eb20da
--- /dev/null
+++ b/extensions/webui/right_canvas_register_surfaces/AGENTS.md
@@ -0,0 +1,27 @@
+# Right Canvas Surface Extensions DOX
+
+## Purpose
+
+- Own frontend registration of built-in right-canvas surfaces.
+
+## Ownership
+
+- JavaScript files own registration of remote link, space agent, and future core canvas surfaces.
+
+## Local Contracts
+
+- JavaScript modules must export a default function.
+- Surface IDs must be unique and stable.
+- Registered surfaces must point to valid components or handlers.
+
+## Work Guidance
+
+- Coordinate surface registration changes with `webui/components/canvas/` and related plugin panels.
+
+## Verification
+
+- Smoke-test opening each registered right-canvas surface after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/set_messages_after_loop/AGENTS.md b/extensions/webui/set_messages_after_loop/AGENTS.md
new file mode 100644
index 000000000..724987ba7
--- /dev/null
+++ b/extensions/webui/set_messages_after_loop/AGENTS.md
@@ -0,0 +1,26 @@
+# Set Messages After Loop Extensions DOX
+
+## Purpose
+
+- Own frontend extensions that run after message DOM updates complete.
+
+## Ownership
+
+- Files in this folder own after-render message behavior.
+
+## Local Contracts
+
+- JavaScript modules must export a default function when present.
+- Preserve message DOM stability and avoid duplicate controls on repeated renders.
+
+## Work Guidance
+
+- Use stable markers when injecting controls into message elements.
+
+## Verification
+
+- Smoke-test message rerendering and extension-injected controls after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/set_messages_before_loop/AGENTS.md b/extensions/webui/set_messages_before_loop/AGENTS.md
new file mode 100644
index 000000000..d417ba566
--- /dev/null
+++ b/extensions/webui/set_messages_before_loop/AGENTS.md
@@ -0,0 +1,26 @@
+# Set Messages Before Loop Extensions DOX
+
+## Purpose
+
+- Own frontend extensions that run before message DOM updates.
+
+## Ownership
+
+- Files in this folder own pre-render message behavior.
+
+## Local Contracts
+
+- JavaScript modules must export a default function when present.
+- Do not remove DOM state needed by message rendering unless the mutable context owns it.
+
+## Work Guidance
+
+- Coordinate pre-render behavior with `/js/messages.js` and message components.
+
+## Verification
+
+- Smoke-test message updates after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/extensions/webui/webui_ws_push/AGENTS.md b/extensions/webui/webui_ws_push/AGENTS.md
new file mode 100644
index 000000000..58d838730
--- /dev/null
+++ b/extensions/webui/webui_ws_push/AGENTS.md
@@ -0,0 +1,27 @@
+# WebUI WebSocket Push Extensions DOX
+
+## Purpose
+
+- Own frontend behavior for WebUI WebSocket push events.
+
+## Ownership
+
+- JavaScript files own push-event side effects such as cache clearing.
+
+## Local Contracts
+
+- JavaScript modules must export a default function.
+- Validate event payload shape before acting.
+- Keep cache or state resets scoped to the event type.
+
+## Work Guidance
+
+- Coordinate push behavior with backend WebSocket event extensions and frontend stores.
+
+## Verification
+
+- Smoke-test relevant WebSocket push events after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/AGENTS.md b/helpers/AGENTS.md
index bb70bf289..dc7584d32 100644
--- a/helpers/AGENTS.md
+++ b/helpers/AGENTS.md
@@ -18,17 +18,23 @@
- Project metadata defaults must remain backwards-compatible; missing `include_agents_md` is treated as enabled and project instruction file content is injected with an explicit source path.
- Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values.
- Use `RepairableException` for errors an agent may be able to fix.
+- This directory is a file-documented DOX profile: every direct `*.py` helper 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 helper purpose, public classes/functions, cross-module contracts, persistence or side effects, path/security assumptions, important dependencies, and verification guidance.
+- When a helper module 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 helper deletion or rename.
## Work Guidance
- Prefer cohesive helper modules over adding unrelated utilities to large files.
- Keep imports acyclic where possible; defer imports inside functions only when needed to avoid startup cycles.
- For changes touching auth, CSRF, files, plugins, tunnels, WebSockets, or model calls, read the caller and tests before editing.
+- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed helper behavior is described there.
## Verification
- Run targeted tests for changed helper modules.
- Run security regression tests for auth, CSRF, filesystem, WebSocket, tunnel, upload, or image-serving changes.
+- Check file-level documentation coverage with a script or shell loop that verifies each `helpers/*.py` has a matching `helpers/*.py.dox.md`.
## Child DOX Index
diff --git a/helpers/api.py.dox.md b/helpers/api.py.dox.md
new file mode 100644
index 000000000..d9d6bb546
--- /dev/null
+++ b/helpers/api.py.dox.md
@@ -0,0 +1,71 @@
+# api.py DOX
+
+## Purpose
+
+- Own the `api.py` helper module.
+- This module defines API handler registration, request security gates, CSRF checks, and watchdog registration.
+- Keep this file-level DOX profile synchronized with `api.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `api.py` owns the runtime implementation.
+- `api.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ApiHandler` (no explicit base class)
+ - `requires_loopback(cls) -> bool`
+ - `requires_api_key(cls) -> bool`
+ - `requires_auth(cls) -> bool`
+ - `get_methods(cls) -> list[str]`
+ - `requires_csrf(cls) -> bool`
+ - `async process(self, input: Input, request: Request) -> Output`
+ - `async handle_request(self, request: Request) -> Response`
+ - `use_context(self, ctxid: str, create_if_not_exists: bool=...)`
+- Top-level functions:
+- `requires_api_key(f)`
+- `requires_loopback(f)`
+- `requires_auth(f)`
+- `csrf_protect(f)`
+- `register_api_route(app: Flask, lock: ThreadLockType) -> None`
+- `register_watchdogs()`
+- Notable constants/configuration names: `CACHE_AREA`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- `ApiHandler` defines `process(...)`.
+- `ApiHandler` defines `get_methods(...)`.
+- `ApiHandler` defines `requires_auth(...)`.
+- `ApiHandler` defines `requires_csrf(...)`.
+- `ApiHandler` defines `requires_api_key(...)`.
+- `ApiHandler` defines `requires_loopback(...)`.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `abc`, `flask`, `functools`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `json`, `pathlib`, `threading`, `typing`, `werkzeug.wrappers.response`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `wraps`, `app.add_url_rule`, `watchdog.add_watchdog`, `cls.requires_auth`, `_use_context`, `login.get_credentials_hash`, `files.get_abs_path`, `handler_cls.requires_csrf`, `handler_cls.requires_api_key`, `handler_cls.requires_auth`, `handler_cls.requires_loopback`, `cache.add`, `PrintStyle.debug`, `cache.clear`, `get_settings`, `f`, `is_loopback_address`, `Response`, `redirect`, `files.is_in_dir`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_api_chat_lifetime.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_fasta2a_client.py`
+ - `tests/test_fastmcp_openapi_security.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_image_get_security.py`
+ - `tests/test_model_config_api_keys.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/attachment_manager.py.dox.md b/helpers/attachment_manager.py.dox.md
new file mode 100644
index 000000000..46dd4a930
--- /dev/null
+++ b/helpers/attachment_manager.py.dox.md
@@ -0,0 +1,47 @@
+# attachment_manager.py DOX
+
+## Purpose
+
+- Own the `attachment_manager.py` helper module.
+- This module tracks uploaded or generated attachments associated with chat contexts.
+- Keep this file-level DOX profile synchronized with `attachment_manager.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `attachment_manager.py` owns the runtime implementation.
+- `attachment_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `AttachmentManager` (no explicit base class)
+ - `is_allowed_file(self, filename: str) -> bool`
+ - `get_file_type(self, filename: str) -> str`
+ - `get_file_extension(filename: str) -> str`
+ - `validate_mime_type(self, file) -> bool`
+ - `save_file(self, file: FileStorage, name: str) -> Tuple[str, Dict]`
+ - `generate_image_preview(self, image_path: str, max_size: int=...) -> Optional[str]`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
+- Imported dependency areas include: `PIL`, `base64`, `helpers.print_style`, `helpers.security`, `io`, `os`, `typing`, `werkzeug.datastructures`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `os.makedirs`, `self.get_file_extension`, `set.union`, `filename.rsplit.lower`, `safe_filename`, `os.path.join`, `self.get_file_type`, `file.save`, `ValueError`, `self.generate_image_preview`, `PrintStyle.error`, `img.thumbnail`, `io.BytesIO`, `img.save`, `base64.b64encode.decode`, `mime_type.split`, `img.convert`, `filename.rsplit`, `base64.b64encode`, `buffer.getvalue`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/backup.py.dox.md b/helpers/backup.py.dox.md
new file mode 100644
index 000000000..a72c49377
--- /dev/null
+++ b/helpers/backup.py.dox.md
@@ -0,0 +1,50 @@
+# backup.py DOX
+
+## Purpose
+
+- Own the `backup.py` helper module.
+- This module builds, inspects, previews, tests, and restores Agent Zero backup archives.
+- Keep this file-level DOX profile synchronized with `backup.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `backup.py` owns the runtime implementation.
+- `backup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `BackupService` (no explicit base class)
+ - `get_default_backup_metadata(self) -> Dict[str, Any]`
+ - `async test_patterns(self, metadata: Dict[str, Any], max_files: int=...) -> List[Dict[str, Any]]`
+ - `async create_backup(self, include_patterns: List[str], exclude_patterns: List[str], include_hidden: bool=..., backup_name: str=...) -> str`
+ - `async inspect_backup(self, backup_file) -> Dict[str, Any]`
+ - `async preview_restore(self, backup_file, restore_include_patterns: Optional[List[str]]=..., restore_exclude_patterns: Optional[List[str]]=..., overwrite_policy: str=..., clean_before_restore: bool=..., user_edited_metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]`
+ - `async restore_backup(self, backup_file, restore_include_patterns: Optional[List[str]]=..., restore_exclude_patterns: Optional[List[str]]=..., overwrite_policy: str=..., clean_before_restore: bool=..., user_edited_metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling.
+- Imported dependency areas include: `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `json`, `os`, `pathspec`, `platform`, `tempfile`, `typing`, `zipfile`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self._get_agent_zero_version`, `files.get_abs_path`, `Localization.get.now_iso`, `self._get_default_patterns`, `self._parse_patterns`, `self.agent_zero_root.rstrip`, `patterns.split`, `join`, `file_path.lstrip`, `backed_up_agent_root.rstrip`, `current_agent_root.rstrip`, `self._patterns_to_string`, `self._get_explicit_patterns`, `tempfile.mkdtemp`, `os.path.join`, `self._translate_patterns`, `git.get_git_info`, `line.strip`, `line.startswith`, `getpass.getuser`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_office_document_store.py`
+ - `tests/test_self_update_tag_filter.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/browser.py.dox.md b/helpers/browser.py.dox.md
new file mode 100644
index 000000000..0ac4afcca
--- /dev/null
+++ b/helpers/browser.py.dox.md
@@ -0,0 +1,46 @@
+# browser.py DOX
+
+## Purpose
+
+- Own the `browser.py` helper module.
+- This module holds shared browser helper state used by browser-facing integrations.
+- Keep this file-level DOX profile synchronized with `browser.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `browser.py` owns the runtime implementation.
+- `browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion.
+
+## 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 public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_a0_connector_prompt_gating.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_oauth_gemini_api.py`
+ - `tests/test_oauth_providers.py`
+ - `tests/test_oauth_static.py`
+ - `tests/test_oauth_xai_grok.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/cache.py.dox.md b/helpers/cache.py.dox.md
new file mode 100644
index 000000000..abe865f75
--- /dev/null
+++ b/helpers/cache.py.dox.md
@@ -0,0 +1,64 @@
+# cache.py DOX
+
+## Purpose
+
+- Own the `cache.py` helper module.
+- This module provides in-process cache areas with optional global and area toggles.
+- Keep this file-level DOX profile synchronized with `cache.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `cache.py` owns the runtime implementation.
+- `cache.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `CacheEntry` (no explicit base class)
+- Top-level functions:
+- `toggle_global(enabled: bool) -> None`
+- `toggle_area(area: str, enabled: bool) -> None`
+- `has(area: str, key: Any) -> bool`
+- `add(area: str, key: Any, data: Any) -> None`
+- `get(area: str, key: Any, default: Any=...) -> Any`
+- `remove(area: str, key: Any) -> None`
+- `clear(area: str) -> None`
+- `trim_cache(area: str, seconds: float=...) -> None`
+- `clear_all() -> None`
+- `_is_enabled(area: str) -> bool`
+- `_create_entry(value: Any) -> CacheEntry`
+- `_touch_entry(entry: CacheEntry) -> None`
+- `_get_matching_areas(area: str) -> list[str]`
+- `determine_cache_key(agent, *additional)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion, plugin state, settings/state persistence.
+- Imported dependency areas include: `dataclasses`, `fnmatch`, `threading`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `threading.RLock`, `dataclass`, `CacheEntry`, `time.time`, `_is_enabled`, `_touch_entry`, `_create_entry`, `_cache.pop`, `_get_matching_areas`, `_cache.clear`, `agent.context.get_data`, `area_cache.pop`, `fnmatch.fnmatch`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_file_tree_visualize.py`
+ - `tests/test_office_canvas_setup.py`
+ - `tests/test_office_document_store.py`
+ - `tests/test_self_update_tag_filter.py`
+ - `tests/test_time_travel.py`
+ - `tests/test_webui_extension_surfaces.py`
+ - `tests/test_whatsapp_bridge_manager.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/call_llm.py.dox.md b/helpers/call_llm.py.dox.md
new file mode 100644
index 000000000..0ba5bd966
--- /dev/null
+++ b/helpers/call_llm.py.dox.md
@@ -0,0 +1,43 @@
+# call_llm.py DOX
+
+## Purpose
+
+- Own the `call_llm.py` helper module.
+- This module wraps LiteLLM/model calls with examples, streaming, and extension hooks.
+- Keep this file-level DOX profile synchronized with `call_llm.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `call_llm.py` owns the runtime implementation.
+- `call_llm.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Example` (`TypedDict`)
+- Top-level functions:
+- `async call_llm(system: str, model: BaseChatModel | BaseLLM, message: str, examples: list[Example]=..., callback: Callable[[str], None] | None=...)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: model calls.
+- Imported dependency areas include: `langchain.prompts`, `langchain.schema`, `langchain_core.language_models.chat_models`, `langchain_core.language_models.llms`, `langchain_core.messages`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `ChatPromptTemplate.from_messages`, `FewShotChatMessagePromptTemplate`, `few_shot_prompt.format`, `chain.astream`, `HumanMessage`, `AIMessage`, `SystemMessage`, `callback`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/chat_media.py.dox.md b/helpers/chat_media.py.dox.md
new file mode 100644
index 000000000..5aa9af9fb
--- /dev/null
+++ b/helpers/chat_media.py.dox.md
@@ -0,0 +1,60 @@
+# chat_media.py DOX
+
+## Purpose
+
+- Own the `chat_media.py` helper module.
+- This module materializes, stores, and resolves chat-scoped image/media artifacts.
+- Keep this file-level DOX profile synchronized with `chat_media.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `chat_media.py` owns the runtime implementation.
+- `chat_media.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ChatImage` (no explicit base class)
+- Top-level functions:
+- `screenshot_dir(context_id: str, source: str) -> Path`
+- `artifact_dir(context_id: str, category: ImageCategory=..., source: str=...) -> Path`
+- `save_image_bytes(context_id: str, payload: bytes, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
+- `save_image_base64(context_id: str, data: str, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
+- `save_image_file(context_id: str, path: str | Path, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
+- `save_image_data_url(context_id: str, data_url: str, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
+- `materialize_image_ref(context_id: str, url: str, source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> str`
+- `is_chat_scoped_path(context_id: str, path: str | Path) -> bool`
+- `infer_source(value: str=..., preferred_name: str=...) -> str`
+- `category_for_source(source: str) -> ImageCategory`
+- `_guess_image_mime(path: Path) -> str`
+- `_is_data_image_url(value: str) -> bool`
+- `_split_image_data_url(data_url: str) -> tuple[str, str]`
+- Notable constants/configuration names: `DEFAULT_MAX_IMAGE_BYTES`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
+- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `pathlib`, `time`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `artifact_dir`, `bytes`, `media_artifacts.normalize_mime`, `media_artifacts.guess_extension`, `media_artifacts.safe_filename`, `Path`, `time.strftime`, `path.parent.mkdir`, `path.write_bytes`, `ChatImage`, `media_artifacts.decode_base64_payload`, `save_image_bytes`, `image_path.read_bytes`, `_split_image_data_url`, `save_image_base64`, `str.strip`, `category_for_source`, `_is_data_image_url`, `images.resolve_ref`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_tool_action_contracts.py`
+ - `tests/test_vision_load_image_refs.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/cli_tunnel.py.dox.md b/helpers/cli_tunnel.py.dox.md
new file mode 100644
index 000000000..da8fc4a0c
--- /dev/null
+++ b/helpers/cli_tunnel.py.dox.md
@@ -0,0 +1,54 @@
+# cli_tunnel.py DOX
+
+## Purpose
+
+- Own the `cli_tunnel.py` helper module.
+- This module provides shared download and install mechanics for CLI-based tunnel providers.
+- Keep this file-level DOX profile synchronized with `cli_tunnel.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `cli_tunnel.py` owns the runtime implementation.
+- `cli_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `CliTunnelHelper` (`TunnelHelper`)
+ - `start(self)`
+ - `stop(self)`
+- Top-level functions:
+- `executable_name(name)`
+- `chmod_executable(path)`
+- `notify_download(notify, message, data=...)`
+- `notify_download_complete(notify, message, data=...)`
+- `download_file(url, destination, notify=...)`
+- `platform_parts()`
+- `extract_named_members_from_tar(archive_path, destination_dir, member_names)`
+- `extract_named_members_from_zip(archive_path, destination_dir, member_names)`
+- Notable constants/configuration names: `RUNTIME_BIN_DIR`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, tunnel state.
+- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.tunnel_common`, `os`, `pathlib`, `platform`, `queue`, `shutil`, `subprocess`, `tarfile`, `tempfile`, `threading`, `time`, `urllib.request`, `zipfile`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `callable`, `destination.parent.mkdir`, `notify_download`, `tempfile.mkstemp`, `os.close`, `platform.system.lower`, `platform.machine.lower`, `destination_dir.mkdir`, `path.chmod`, `notify`, `temp_path.replace`, `notify_download_complete`, `RuntimeError`, `archive.getmembers`, `zipfile.ZipFile`, `archive.infolist`, `super.__init__`, `self.url_pattern.search`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/cloudflare_tunnel.py.dox.md b/helpers/cloudflare_tunnel.py.dox.md
new file mode 100644
index 000000000..e2172dcae
--- /dev/null
+++ b/helpers/cloudflare_tunnel.py.dox.md
@@ -0,0 +1,43 @@
+# cloudflare_tunnel.py DOX
+
+## Purpose
+
+- Own the `cloudflare_tunnel.py` helper module.
+- This module implements Cloudflare tunnel provider lifecycle behavior.
+- Keep this file-level DOX profile synchronized with `cloudflare_tunnel.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `cloudflare_tunnel.py` owns the runtime implementation.
+- `cloudflare_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `CloudflareTunnel` (`FlaredanticTunnelHelper`)
+ - `build_tunnel(self)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: settings/state persistence, tunnel state.
+- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `FlareConfig`, `FlareTunnel`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/context.py.dox.md b/helpers/context.py.dox.md
new file mode 100644
index 000000000..8b6e76a51
--- /dev/null
+++ b/helpers/context.py.dox.md
@@ -0,0 +1,54 @@
+# context.py DOX
+
+## Purpose
+
+- Own the `context.py` helper module.
+- This module provides compatibility helpers for reading and writing `AgentContext` data.
+- Keep this file-level DOX profile synchronized with `context.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `context.py` owns the runtime implementation.
+- `context.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `_ensure_context() -> Dict[str, Any]`: Make sure a context dict exists, and return it.
+- `set_context_data(key: str, value: Any)`: Set context data for the current async/task context.
+- `delete_context_data(key: str)`: Delete a key from the current async/task context.
+- `get_context_data(key: Optional[str]=..., default: T=...) -> T`: Get a key from the current context, or the full dict if key is None.
+- `clear_context_data()`: Completely clear the context dict.
+- Notable constants/configuration names: `T`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion, scheduler state.
+- Imported dependency areas include: `contextvars`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TypeVar`, `ContextVar`, `_ensure_context`, `cast`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_a0_connector_prompt_gating.py`
+ - `tests/test_api_chat_lifetime.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_error_retry_plugin.py`
+ - `tests/test_extensions_stress.py`
+ - `tests/test_file_tree_visualize.py`
+ - `tests/test_history_compression_wait.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/context_utils.py.dox.md b/helpers/context_utils.py.dox.md
new file mode 100644
index 000000000..725340ecd
--- /dev/null
+++ b/helpers/context_utils.py.dox.md
@@ -0,0 +1,41 @@
+# context_utils.py DOX
+
+## Purpose
+
+- Own the `context_utils.py` helper module.
+- This module provides context managers/utilities for current context binding.
+- Keep this file-level DOX profile synchronized with `context_utils.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `context_utils.py` owns the runtime implementation.
+- `context_utils.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `use_context(lock: ThreadLockType, ctxid: str, create_if_not_exists: bool=...)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: WebSocket state, settings/state persistence.
+- Imported dependency areas include: `threading`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.first`, `AgentContext`, `Exception`, `initialize_agent`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/crypto.py.dox.md b/helpers/crypto.py.dox.md
new file mode 100644
index 000000000..a66e730ca
--- /dev/null
+++ b/helpers/crypto.py.dox.md
@@ -0,0 +1,48 @@
+# crypto.py DOX
+
+## Purpose
+
+- Own the `crypto.py` helper module.
+- This module hashes, verifies, encrypts, and decrypts data for signed or protected payloads.
+- Keep this file-level DOX profile synchronized with `crypto.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `crypto.py` owns the runtime implementation.
+- `crypto.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `hash_data(data: str, password: str)`
+- `verify_data(data: str, hash: str, password: str)`
+- `_generate_private_key()`
+- `_generate_public_key(private_key: rsa.RSAPrivateKey)`
+- `_decode_public_key(public_key: str) -> rsa.RSAPublicKey`
+- `encrypt_data(data: str, public_key_pem: str)`
+- `_encrypt_data(data: bytes, public_key: rsa.RSAPublicKey)`
+- `decrypt_data(data: str, private_key: rsa.RSAPrivateKey)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: secret handling.
+- Imported dependency areas include: `cryptography.hazmat.primitives`, `cryptography.hazmat.primitives.asymmetric`, `hashlib`, `hmac`, `os`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `hmac.new.hexdigest`, `rsa.generate_private_key`, `private_key.public_key.public_bytes.hex`, `bytes.fromhex`, `serialization.load_pem_public_key`, `_encrypt_data`, `public_key.encrypt`, `b.hex`, `private_key.decrypt`, `b.decode`, `hash_data`, `TypeError`, `data.encode`, `_decode_public_key`, `padding.OAEP`, `hmac.new`, `private_key.public_key.public_bytes`, `password.encode`, `padding.MGF1`, `hashes.SHA256`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/defer.py.dox.md b/helpers/defer.py.dox.md
new file mode 100644
index 000000000..cccc3da9f
--- /dev/null
+++ b/helpers/defer.py.dox.md
@@ -0,0 +1,55 @@
+# defer.py DOX
+
+## Purpose
+
+- Own the `defer.py` helper module.
+- This module runs deferred or child async tasks on managed event-loop threads.
+- Keep this file-level DOX profile synchronized with `defer.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `defer.py` owns the runtime implementation.
+- `defer.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `EventLoopThread` (no explicit base class)
+ - `terminate(self)`
+ - `run_coroutine(self, coro)`
+- `ChildTask` (no explicit base class)
+- `DeferredTask` (no explicit base class)
+ - `start_task(self, func: Callable[..., Coroutine[Any, Any, Any]], *args, **kwargs)`
+ - `is_ready(self) -> bool`
+ - `result_sync(self, timeout: Optional[float]=...) -> Any`
+ - `async result(self, timeout: Optional[float]=...) -> Any`
+ - `kill(self, terminate_thread: bool=...) -> None`
+ - `kill_children(self) -> None`
+ - `is_alive(self) -> bool`
+ - `restart(self, terminate_thread: bool=...) -> None`
+- Notable constants/configuration names: `T`, `THREAD_BACKGROUND`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: scheduler state.
+- Imported dependency areas include: `asyncio`, `concurrent.futures`, `dataclasses`, `threading`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TypeVar`, `threading.Lock`, `self._start`, `asyncio.set_event_loop`, `self.loop.run_forever`, `loop.is_running`, `asyncio.run_coroutine_threadsafe`, `EventLoopThread`, `self._start_task`, `self.kill`, `self.event_loop_thread.run_coroutine`, `self.kill_children`, `asyncio.get_running_loop`, `func`, `asyncio.iscoroutine`, `Future`, `asyncio.wrap_future`, `asyncio.current_task`, `asyncio.new_event_loop`, `threading.Thread`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/dirty_json.py b/helpers/dirty_json.py
index 8b731bee4..8e7b21012 100644
--- a/helpers/dirty_json.py
+++ b/helpers/dirty_json.py
@@ -214,7 +214,7 @@ class DirtyJson:
def _parse_key(self):
self._skip_whitespace()
if self.current_char in ['"', "'"]:
- return self._parse_string()
+ return self._parse_string(is_key=True)
else:
return self._parse_unquoted_key()
@@ -260,11 +260,18 @@ class DirtyJson:
self._pop_stack()
return
- def _parse_string(self):
+ def _parse_string(self, is_key: bool = False):
result = ""
quote_char = self.current_char
self._advance() # Skip opening quote
- while self.current_char is not None and self.current_char != quote_char:
+ while self.current_char is not None:
+ if self.current_char == quote_char:
+ if self._is_closing_quote(is_key):
+ break
+ result += self.current_char
+ self._advance()
+ continue
+
if self.current_char == "\\":
self._advance()
if self.current_char in ['"', "'", "\\", "/", "b", "f", "n", "r", "t"]:
@@ -298,6 +305,67 @@ class DirtyJson:
self._advance() # Skip closing quote
return result
+ def _is_closing_quote(self, is_key: bool) -> bool:
+ next_index = self._skip_padding_from(self.index + 1)
+ if next_index >= len(self.json_string):
+ return True
+
+ next_char = self.json_string[next_index]
+ if is_key:
+ return next_char in [":", ",", "}", "]"]
+
+ if next_char in [",", "}", "]"]:
+ return True
+
+ return self._looks_like_missing_comma_before_key(next_index)
+
+ def _looks_like_missing_comma_before_key(self, index: int) -> bool:
+ if not self.stack or not isinstance(self.stack[-1], dict):
+ return False
+ if index >= len(self.json_string) or self.json_string[index] not in ['"', "'"]:
+ return False
+
+ quote_char = self.json_string[index]
+ index += 1
+ while index < len(self.json_string):
+ char = self.json_string[index]
+ if char == "\\":
+ index += 2
+ continue
+ if char == quote_char:
+ next_index = self._skip_padding_from(index + 1)
+ return (
+ next_index < len(self.json_string)
+ and self.json_string[next_index] == ":"
+ )
+ if char in ["\n", "\r", "{", "}", "[", "]", ","]:
+ return False
+ index += 1
+
+ return False
+
+ def _skip_padding_from(self, index: int) -> int:
+ while index < len(self.json_string):
+ char = self.json_string[index]
+ if char.isspace():
+ index += 1
+ elif char == "/" and index + 1 < len(self.json_string):
+ next_char = self.json_string[index + 1]
+ if next_char == "/":
+ index += 2
+ while index < len(self.json_string) and self.json_string[index] != "\n":
+ index += 1
+ elif next_char == "*":
+ end = self.json_string.find("*/", index + 2)
+ if end == -1:
+ return len(self.json_string)
+ index = end + 2
+ else:
+ break
+ else:
+ break
+ return index
+
def _parse_multiline_string(self):
result = ""
quote_char = self.current_char
diff --git a/helpers/dirty_json.py.dox.md b/helpers/dirty_json.py.dox.md
new file mode 100644
index 000000000..030a5c652
--- /dev/null
+++ b/helpers/dirty_json.py.dox.md
@@ -0,0 +1,51 @@
+# dirty_json.py DOX
+
+## Purpose
+
+- Own the `dirty_json.py` helper module.
+- This module parses and serializes relaxed JSON-like model output.
+- Keep this file-level DOX profile synchronized with `dirty_json.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `dirty_json.py` owns the runtime implementation.
+- `dirty_json.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `DirtyJson` (no explicit base class)
+ - `parse_string(json_string)`
+ - `parse(self, json_string)`
+ - `feed(self, chunk)`
+ - `get_start_pos(self, input_str: str) -> int`
+- Top-level functions:
+- `try_parse(json_string: str)`
+- `parse(json_string: str)`
+- `stringify(obj, **kwargs)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, settings/state persistence.
+- Imported dependency areas include: `json`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `DirtyJson.parse_string`, `json.dumps`, `json.loads`, `self._reset`, `self.stack.pop`, `DirtyJson`, `parser.parse`, `self.get_start_pos`, `self._parse`, `self._advance`, `self._skip_whitespace`, `self._parse_object_content`, `self._parse_array_content`, `self._skip_padding_from`, `self._looks_like_missing_comma_before_key`, `result.strip`, `self.current_char.isspace`, `self._parse_value`, `self._continue_parsing`, `self._parse_object`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_dirty_json.py`
+ - `tests/test_projects.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/docker.py.dox.md b/helpers/docker.py.dox.md
new file mode 100644
index 000000000..e932e7bcc
--- /dev/null
+++ b/helpers/docker.py.dox.md
@@ -0,0 +1,53 @@
+# docker.py DOX
+
+## Purpose
+
+- Own the `docker.py` helper module.
+- This module manages Docker container operations used by runtime helpers.
+- Keep this file-level DOX profile synchronized with `docker.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `docker.py` owns the runtime implementation.
+- `docker.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `DockerContainerManager` (no explicit base class)
+ - `init_docker(self)`
+ - `cleanup_container(self) -> None`
+ - `get_image_containers(self)`
+ - `start_container(self) -> None`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion, subprocess/runtime control, WebSocket state.
+- Imported dependency areas include: `atexit`, `docker`, `helpers.errors`, `helpers.files`, `helpers.log`, `helpers.print_style`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.init_docker`, `PrintStyle.standard`, `self.client.containers.run`, `time.sleep`, `docker.from_env`, `self.container.stop`, `self.container.remove`, `existing_container.start`, `self.logger.log`, `format_error`, `PrintStyle.error`, `PrintStyle.hint`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_default_prompt_budget.py`
+ - `tests/test_docker_release_plan.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_model_search.py`
+ - `tests/test_office_canvas_setup.py`
+ - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/document_query.py.dox.md b/helpers/document_query.py.dox.md
new file mode 100644
index 000000000..7d205d988
--- /dev/null
+++ b/helpers/document_query.py.dox.md
@@ -0,0 +1,41 @@
+# document_query.py DOX
+
+## Purpose
+
+- Own the `document_query.py` helper module.
+- This module provides compatibility exports for document query behavior.
+- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `document_query.py` owns the runtime implementation.
+- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: plugin state.
+- Imported dependency areas include: `plugins._document_query.helpers.document_query`.
+
+## 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 public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_document_query_fallback.py`
+ - `tests/test_document_query_plugin.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/dotenv.py.dox.md b/helpers/dotenv.py.dox.md
new file mode 100644
index 000000000..2e142d657
--- /dev/null
+++ b/helpers/dotenv.py.dox.md
@@ -0,0 +1,48 @@
+# dotenv.py DOX
+
+## Purpose
+
+- Own the `dotenv.py` helper module.
+- This module loads and updates `.env` configuration values.
+- Keep this file-level DOX profile synchronized with `dotenv.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `dotenv.py` owns the runtime implementation.
+- `dotenv.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `load_dotenv()`
+- `get_dotenv_file_path()`
+- `get_dotenv_value(key: str, default: Any=...)`
+- `save_dotenv_value(key: str, value: str)`
+- Notable constants/configuration names: `KEY_AUTH_LOGIN`, `KEY_AUTH_PASSWORD`, `KEY_RFC_PASSWORD`, `KEY_ROOT_PASSWORD`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, secret handling.
+- Imported dependency areas include: `dotenv`, `files`, `os`, `re`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `_load_dotenv`, `get_abs_path`, `os.getenv`, `get_dotenv_file_path`, `load_dotenv`, `os.path.isfile`, `f.readlines`, `f.seek`, `f.writelines`, `f.truncate`, `f.write`, `re.match`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/email_parser_test.py`
+ - `tests/test_model_config_api_keys.py`
+ - `tests/test_timezone_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/duckduckgo_search.py.dox.md b/helpers/duckduckgo_search.py.dox.md
new file mode 100644
index 000000000..5090f5042
--- /dev/null
+++ b/helpers/duckduckgo_search.py.dox.md
@@ -0,0 +1,40 @@
+# duckduckgo_search.py DOX
+
+## Purpose
+
+- Own the `duckduckgo_search.py` helper module.
+- This module queries DuckDuckGo search through the configured helper path.
+- Keep this file-level DOX profile synchronized with `duckduckgo_search.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `duckduckgo_search.py` owns the runtime implementation.
+- `duckduckgo_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `search(query: str, results=..., region=..., time=...) -> list[str]`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `duckduckgo_search`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `DDGS`, `ddgs.text`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/email_client.py.dox.md b/helpers/email_client.py.dox.md
new file mode 100644
index 000000000..976e32cd9
--- /dev/null
+++ b/helpers/email_client.py.dox.md
@@ -0,0 +1,39 @@
+# email_client.py DOX
+
+## Purpose
+
+- Own the `email_client.py` helper module.
+- This module provides shared email client plumbing for mail integrations.
+- Keep this file-level DOX profile synchronized with `email_client.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `email_client.py` owns the runtime implementation.
+- `email_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling.
+
+## 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 public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/email_parser_test.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/ephemeral_images.py.dox.md b/helpers/ephemeral_images.py.dox.md
new file mode 100644
index 000000000..62b7a36a0
--- /dev/null
+++ b/helpers/ephemeral_images.py.dox.md
@@ -0,0 +1,58 @@
+# ephemeral_images.py DOX
+
+## Purpose
+
+- Own the `ephemeral_images.py` helper module.
+- This module stores temporary image payloads by reference for safe short-lived access.
+- Keep this file-level DOX profile synchronized with `ephemeral_images.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ephemeral_images.py` owns the runtime implementation.
+- `ephemeral_images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `EphemeralImage` (no explicit base class)
+ - `data_url(self) -> str`
+ - `display_name(self) -> str`
+- Top-level functions:
+- `put_image_bytes(context_id: str, mime: str, payload: bytes, name: str=..., ttl_seconds: float=...) -> str`
+- `put_image(context_id: str, mime: str, data: str, name: str=..., ttl_seconds: float=...) -> str`
+- `is_ref(value: object) -> bool`
+- `display_ref(ref: str) -> str`
+- `get_image(ref: str, context_id: str=...) -> EphemeralImage | None`
+- `consume_image(ref: str, context_id: str=...) -> EphemeralImage | None`
+- `delete_image(ref: str) -> None`
+- `clear_context(context_id: str) -> None`
+- `_resolve_image(ref: str, context_id: str=..., consume: bool) -> EphemeralImage | None`
+- `_compact_base64(data: str) -> str`
+- `_normalize_mime(mime: str) -> str`
+- `_prune_expired_locked(now: float | None=...) -> None`
+- Notable constants/configuration names: `REF_PREFIX`, `DEFAULT_TTL_SECONDS`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion.
+- Imported dependency areas include: `__future__`, `base64`, `dataclasses`, `threading`, `time`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `threading.RLock`, `base64.b64encode.decode`, `put_image`, `_compact_base64`, `base64.b64decode`, `_normalize_mime`, `time.time`, `EphemeralImage`, `str.strip.startswith`, `str.strip`, `_resolve_image`, `join`, `str.strip.lower`, `ValueError`, `_prune_expired_locked`, `is_ref`, `_store.pop`, `value.startswith`, `display_ref`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/errors.py.dox.md b/helpers/errors.py.dox.md
new file mode 100644
index 000000000..c551fc8d5
--- /dev/null
+++ b/helpers/errors.py.dox.md
@@ -0,0 +1,54 @@
+# errors.py DOX
+
+## Purpose
+
+- Own the `errors.py` helper module.
+- This module defines framework exceptions and safe error formatting.
+- Keep this file-level DOX profile synchronized with `errors.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `errors.py` owns the runtime implementation.
+- `errors.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `RepairableException` (`Exception`)
+- `InterventionException` (`Exception`)
+- `HandledException` (`Exception`)
+- Top-level functions:
+- `handle_error(e: Exception)`
+- `error_text(e: Exception)`
+- `format_error(e: Exception, start_entries=..., end_entries=..., error_message_position: Literal['top', 'bottom', 'none']=...)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `asyncio`, `re`, `traceback`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `join`, `traceback_text.split`, `traceback.format_exception`, `re.match`, `type`, `line.strip.startswith`, `trimmed_lines.strip`, `error_message.strip`, `line.strip`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_fasta2a_client.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_office_desktop_state.py`
+ - `tests/test_office_document_store.py`
+ - `tests/test_skills_runtime.py`
+ - `tests/test_speech_plugin_split.py`
+ - `tests/test_time_travel.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/extension.py.dox.md b/helpers/extension.py.dox.md
new file mode 100644
index 000000000..4271cc57c
--- /dev/null
+++ b/helpers/extension.py.dox.md
@@ -0,0 +1,63 @@
+# extension.py DOX
+
+## Purpose
+
+- Own the `extension.py` helper module.
+- This module discovers and dispatches Python and WebUI extension hooks.
+- Keep this file-level DOX profile synchronized with `extension.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `extension.py` owns the runtime implementation.
+- `extension.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `_Unset` (no explicit base class)
+- `Extension` (no explicit base class)
+ - `execute(self, **kwargs) -> None | Awaitable[None]`
+- Top-level functions:
+- `_log_extension_call(name: str)`
+- `extensible(func)`: Make a function emit two implicit extension points around its execution.
+- `async call_extensions_async(extension_point: str, agent: 'Agent|None'=..., **kwargs)`
+- `call_extensions_sync(extension_point: str, agent: 'Agent|None'=..., **kwargs)`
+- `get_webui_extensions(agent: 'Agent | None', extension_point: str, filters: list[str] | None=...)`
+- `_get_extension_classes(extension_point: str, agent: 'Agent|None'=..., **kwargs) -> list[Type[Extension]]`
+- `_get_file_from_module(module_name: str) -> str`
+- `_get_extensions(folder: str)`
+- `register_extensions_watchdogs()`
+- Notable constants/configuration names: `DEFAULT_EXTENSIONS_FOLDER`, `USER_EXTENSIONS_FOLDER`, `_EXTENSIONS_CACHE_AREA`, `_CLASSES_CACHE_AREA`, `_UNSET`, `_EXTENSIONS_LOG_COUNTS`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- `Extension` defines `execute(...)`.
+- Observed side-effect areas: filesystem reads, WebSocket state, plugin state.
+- Imported dependency areas include: `abc`, `functools`, `helpers`, `helpers.print_style`, `inspect`, `os`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `_Unset`, `inspect.iscoroutinefunction`, `wraps`, `_log_extension_call`, `_get_extension_classes`, `subagents.get_paths`, `cache.determine_cache_key`, `cache.add`, `files.get_abs_path`, `modules.load_classes_from_folder`, `watchdog.add_watchdog`, `os.path.join`, `_get_agent`, `_prepare_inputs`, `_process_result`, `call_extensions_sync`, `cls.execute`, `files.deabsolute_path`, `_get_file_from_module`, `module_name.split`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_a0_connector_prompt_gating.py`
+ - `tests/test_api_chat_lifetime.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_error_retry_plugin.py`
+ - `tests/test_extensions_stress.py`
+ - `tests/test_history_compression_wait.py`
+ - `tests/test_model_config_api_keys.py`
+ - `tests/test_oauth_codex.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/extract_tools.py.dox.md b/helpers/extract_tools.py.dox.md
new file mode 100644
index 000000000..9c65b8ced
--- /dev/null
+++ b/helpers/extract_tools.py.dox.md
@@ -0,0 +1,48 @@
+# extract_tools.py DOX
+
+## Purpose
+
+- Own the `extract_tools.py` helper module.
+- This module normalizes and repairs model-emitted tool-call JSON.
+- Keep this file-level DOX profile synchronized with `extract_tools.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `extract_tools.py` owns the runtime implementation.
+- `extract_tools.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `json_parse_dirty(json: str) -> dict[str, Any] | None`
+- `normalize_tool_request(tool_request: Any) -> tuple[str, dict]`
+- `extract_json_root_string(content: str) -> str | None`
+- `extract_json_object_string(content)`
+- `extract_json_string(content)`
+- `fix_json_string(json_string)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `dirty_json`, `helpers.modules`, `re`, `regex`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `extract_json_object_string`, `content.find`, `DirtyJson`, `content.rfind`, `regex.search`, `re.sub`, `json.strip`, `ValueError`, `tool_name.split`, `parser.parse`, `match.group`, `match.group.replace`, `DirtyJson.parse_string`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_stream_tool_early_stop.py`
+ - `tests/test_tool_request_normalization.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/faiss_monkey_patch.py.dox.md b/helpers/faiss_monkey_patch.py.dox.md
new file mode 100644
index 000000000..bfbacf50a
--- /dev/null
+++ b/helpers/faiss_monkey_patch.py.dox.md
@@ -0,0 +1,38 @@
+# faiss_monkey_patch.py DOX
+
+## Purpose
+
+- Own the `faiss_monkey_patch.py` helper module.
+- This module applies compatibility patches for FAISS behavior.
+- Keep this file-level DOX profile synchronized with `faiss_monkey_patch.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `faiss_monkey_patch.py` owns the runtime implementation.
+- `faiss_monkey_patch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `numpy`, `sys`, `types`, `warnings`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `types.ModuleType`, `SimpleNamespace`, `warnings.catch_warnings`, `warnings.simplefilter`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/fasta2a_client.py.dox.md b/helpers/fasta2a_client.py.dox.md
new file mode 100644
index 000000000..e5ef5b6a8
--- /dev/null
+++ b/helpers/fasta2a_client.py.dox.md
@@ -0,0 +1,50 @@
+# fasta2a_client.py DOX
+
+## Purpose
+
+- Own the `fasta2a_client.py` helper module.
+- This module connects Agent Zero to external A2A agents.
+- Keep this file-level DOX profile synchronized with `fasta2a_client.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `fasta2a_client.py` owns the runtime implementation.
+- `fasta2a_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `AgentConnection` (no explicit base class)
+ - `async get_agent_card(self) -> Dict[str, Any]`
+ - `async send_message(self, message: str, attachments: Optional[List[str]]=..., context_id: Optional[str]=..., metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]`
+ - `async get_task(self, task_id: str) -> Dict[str, Any]`
+ - `async wait_for_completion(self, task_id: str, poll_interval: int=..., max_wait: int=...) -> Dict[str, Any]`
+ - `async close(self)`
+- Top-level functions:
+- `async connect_to_agent(agent_url: str, timeout: int=...) -> AgentConnection`: Create a connection to a remote agent.
+- `is_client_available() -> bool`: Check if FastA2A client is available.
+- Notable constants/configuration names: `_PRINTER`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `helpers.print_style`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `PrintStyle`, `AgentConnection`, `PrintStyle.warning`, `agent_url.rstrip`, `httpx.AsyncClient`, `A2AClient`, `TimeoutError`, `connection.get_agent_card`, `RuntimeError`, `agent_url.startswith`, `os.getenv`, `self._http_client.aclose`, `self.close`, `response.raise_for_status`, `response.json`, `self.get_agent_card`, `uuid.uuid4`, `self._a2a_client.send_message`, `self._a2a_client.get_task`, `self.get_task`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/fasta2a_server.py.dox.md b/helpers/fasta2a_server.py.dox.md
new file mode 100644
index 000000000..cd8e00755
--- /dev/null
+++ b/helpers/fasta2a_server.py.dox.md
@@ -0,0 +1,52 @@
+# fasta2a_server.py DOX
+
+## Purpose
+
+- Own the `fasta2a_server.py` helper module.
+- This module serves Agent Zero through a dynamic A2A proxy.
+- Keep this file-level DOX profile synchronized with `fasta2a_server.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `fasta2a_server.py` owns the runtime implementation.
+- `fasta2a_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `AgentZeroWorker` (`Worker`)
+ - `async run_task(self, params: Any) -> None`
+ - `async cancel_task(self, params: Any) -> None`
+ - `build_message_history(self, history: List[Any]) -> List[Message]`
+ - `build_artifacts(self, result: Any) -> List[Artifact]`
+- `DynamicA2AProxy` (no explicit base class)
+ - `get_instance()`
+ - `reconfigure(self, token: str)`
+- Top-level functions:
+- `is_available()`: Check if FastA2A is available and properly configured.
+- `get_proxy()`: Get the FastA2A proxy instance.
+- Notable constants/configuration names: `_PRINTER`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `agent`, `asyncio`, `atexit`, `contextlib`, `helpers`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `starlette.requests`, `threading`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `PrintStyle`, `DynamicA2AProxy.get_instance`, `super.__init__`, `join`, `UserMessage`, `threading.Lock`, `atexit.register`, `self._configure`, `settings.get_settings`, `path.startswith`, `self._convert_message`, `initialize_agent`, `AgentContext`, `context.log.log`, `context.communicate`, `context.reset`, `AgentContext.remove`, `remove_chat`, `self.storage.update_task`, `self._register_shutdown`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/file_browser.py.dox.md b/helpers/file_browser.py.dox.md
new file mode 100644
index 000000000..3f8f2e43a
--- /dev/null
+++ b/helpers/file_browser.py.dox.md
@@ -0,0 +1,51 @@
+# file_browser.py DOX
+
+## Purpose
+
+- Own the `file_browser.py` helper module.
+- This module builds safe file-browser views over allowed filesystem roots.
+- Keep this file-level DOX profile synchronized with `file_browser.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `file_browser.py` owns the runtime implementation.
+- `file_browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `FileBrowser` (no explicit base class)
+ - `save_file_b64(self, current_path: str, filename: str, base64_content: str)`
+ - `save_files(self, files: List, current_path: str=...) -> Tuple[List[str], List[str]]`
+ - `delete_file(self, file_path: str) -> bool`
+ - `rename_item(self, file_path: str, new_name: str) -> bool`
+ - `create_folder(self, parent_path: str, folder_name: str) -> bool`
+ - `save_text_file(self, file_path: str, content: str) -> bool`
+ - `get_files(self, current_path: str=...) -> Dict`
+ - `get_full_path(self, file_path: str, allow_dir: bool=...) -> str`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, settings/state persistence.
+- Imported dependency areas include: `base64`, `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `helpers.security`, `os`, `pathlib`, `shutil`, `subprocess`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `self._get_file_extension`, `file.seek`, `file.tell`, `resolve`, `os.makedirs`, `os.path.exists`, `full_path.with_name`, `new_path.exists`, `os.rename`, `target_dir.exists`, `filename.rsplit.lower`, `subprocess.run`, `result.stdout.strip.split`, `self._get_files_via_ls`, `files.exists`, `ValueError`, `str.startswith`, `file.write`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/file_tree.py.dox.md b/helpers/file_tree.py.dox.md
new file mode 100644
index 000000000..db3625d70
--- /dev/null
+++ b/helpers/file_tree.py.dox.md
@@ -0,0 +1,63 @@
+# file_tree.py DOX
+
+## Purpose
+
+- Own the `file_tree.py` helper module.
+- This module renders bounded file-tree summaries for prompts and UI surfaces.
+- Keep this file-level DOX profile synchronized with `file_tree.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `file_tree.py` owns the runtime implementation.
+- `file_tree.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `_TreeEntry` (no explicit base class)
+ - `as_dict(self) -> dict[str, Any]`
+- Top-level functions:
+- `_from_timestamp(timestamp: float) -> datetime`
+- `file_tree(relative_path: str, max_depth: int=..., max_lines: int=..., folders_first: bool=..., max_folders: int=..., max_files: int=..., sort: tuple[Literal['name', 'created', 'modified'], Literal['asc', 'desc']]=..., ignore: str | None=..., output_mode: Literal['string', 'flat', 'nested']=...) -> str | list[dict]`: Render a directory tree relative to the repository base path.
+- `_normalize_relative_path(path: str) -> str`
+- `_directory_has_visible_entries(directory: str, root_abs_path: str, ignore_spec: PathSpec, cache: dict[str, bool], max_depth_remaining: int) -> bool`
+- `_create_summary_comment(parent: _TreeEntry, noun: str, count: int) -> _TreeEntry`
+- `_create_global_limit_comment(parent: _TreeEntry, hidden_children: Sequence[_TreeEntry]) -> _TreeEntry`
+- `_create_folder_unprocessed_comment(folder_node: _TreeEntry, folder_path: str, abs_root: str, ignore_spec: Optional[PathSpec]) -> Optional[_TreeEntry]`
+- `_prune_to_visible(node: _TreeEntry, visible_ids: set[int]) -> None`
+- `_mark_last_flags(node: _TreeEntry) -> None`
+- `_refresh_render_metadata(node: _TreeEntry) -> None`
+- `_resolve_ignore_patterns(ignore: str | None, root_abs_path: str) -> Optional[PathSpec]`
+- `_list_directory_children(directory: str, root_abs_path: str, ignore_spec: Optional[PathSpec], max_depth_remaining: int, cache: dict[str, bool]) -> tuple[list[os.DirEntry], list[os.DirEntry]]`
+- `_apply_sorting_and_limits(folders: list[_TreeEntry], files: list[_TreeEntry], folders_first: bool, sort: tuple[str, str], max_folders: int | None, max_files: int | None, directory_node: _TreeEntry) -> list[_TreeEntry]`
+- `_format_line(node: _TreeEntry) -> str`
+- `_build_tree_items_flat(items: Sequence[_TreeEntry]) -> list[dict]`
+- `_to_nested_structure(items: Sequence[_TreeEntry]) -> list[dict]`
+- `_iter_depth_first(items: Sequence[_TreeEntry]) -> Iterable[_TreeEntry]`
+- Notable constants/configuration names: `SORT_BY_NAME`, `SORT_BY_CREATED`, `SORT_BY_MODIFIED`, `SORT_ASC`, `SORT_DESC`, `OUTPUT_MODE_STRING`, `OUTPUT_MODE_FLAT`, `OUTPUT_MODE_NESTED`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, subprocess/runtime control, WebSocket state.
+- Imported dependency areas include: `__future__`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathspec`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `datetime.fromtimestamp`, `files_helper.get_abs_path`, `files_helper.get_abs_path_dockerized`, `_resolve_ignore_patterns`, `os.stat`, `_TreeEntry`, `deque`, `queue.clear`, `_mark_last_flags`, `_refresh_render_metadata`, `path.replace`, `normalized.startswith`, `join`, `_create_global_limit_comment`, `ignore.startswith`, `PathSpec.from_lines`, `segments.reverse`, `os.path.exists`, `FileNotFoundError`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_file_tree_visualize.py`
+ - `tests/test_skills_runtime.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/files.py.dox.md b/helpers/files.py.dox.md
new file mode 100644
index 000000000..b4f153240
--- /dev/null
+++ b/helpers/files.py.dox.md
@@ -0,0 +1,82 @@
+# files.py DOX
+
+## Purpose
+
+- Own the `files.py` helper module.
+- This module owns repository/user path helpers and file read/write/parsing primitives.
+- Keep this file-level DOX profile synchronized with `files.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `files.py` owns the runtime implementation.
+- `files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `VariablesPlugin` (`ABC`)
+ - `get_variables(self, file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]`
+- Top-level functions:
+- `load_plugin_variables(file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]`
+- `parse_file(_filename: str, _directories: list[str] | None=..., _encoding=..., **kwargs)`
+- `read_prompt_file(_file: str, _directories: list[str] | None=..., _encoding=..., **kwargs)`
+- `evaluate_text_conditions(_content: str, **kwargs)`
+- `read_file(relative_path: str, encoding=...)`
+- `read_file_json(relative_path: str, encoding=...)`
+- `read_file_yaml(relative_path: str, encoding=...)`
+- `read_file_bin(relative_path: str)`
+- `read_file_base64(relative_path)`
+- `is_probably_binary_bytes(data: bytes, threshold: float=...) -> bool`: Binary detection.
+- `is_probably_binary_file(file_path: str, sample_size: int=..., threshold: float=...) -> bool`: Binary detection by reading only the first ~sample_size bytes of a file.
+- `replace_placeholders_text(_content: str, **kwargs)`
+- `replace_placeholders_json(_content: str, **kwargs)`
+- `replace_placeholders_dict(_content: dict, **kwargs)`
+- `process_includes(_content: str, _directories: list[str], _source_file: str=..., _source_dir: str=..., **kwargs)`
+- `_get_dirs_after(_directories: list[str], _source_dir: str) -> list[str]`: Return directories after _source_dir in the priority list.
+- `find_file_in_dirs(_filename: str, _directories: list[str])`: This function searches for a filename in a list of directories in order.
+- `get_unique_filenames_in_dirs(dir_paths: list[str], pattern: str=..., type: Literal['file', 'dir', 'any']=...)`
+- `find_existing_paths_by_pattern(pattern: str)`
+- `remove_code_fences(text)`
+- `is_full_json_template(text)`
+- `write_file(relative_path: str, content: str, encoding: str=...)`
+- `delete_file(relative_path: str)`
+- `write_file_bin(relative_path: str, content: bytes)`
+- `write_file_base64(relative_path: str, content: str)`
+- `delete_dir(relative_path: str)`
+- `move_dir(old_path: str, new_path: str)`
+- `move_dir_safe(src, dst, rename_format=...)`
+- `create_dir_safe(dst, rename_format=...)`
+- `create_dir(relative_path: str)`
+- Notable constants/configuration names: `AGENTS_DIR`, `PLUGINS_DIR`, `PROJECTS_DIR`, `EXTENSIONS_DIR`, `USER_DIR`, `TEMP_DIR`, `API_DIR`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `abc`, `base64`, `fnmatch`, `glob`, `helpers`, `helpers.strings`, `json`, `mimetypes`, `os`, `re`, `shutil`, `simpleeval`, `tempfile`, `typing`, `zipfile`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `os.path.dirname`, `os.path.abspath`, `find_file_in_dirs`, `is_full_json_template`, `remove_code_fences`, `evaluate_text_conditions`, `replace_placeholders_text`, `process_includes`, `re.compile`, `_process`, `get_abs_path`, `is_probably_binary_bytes`, `replace_value`, `re.sub`, `os.path.normpath`, `FileNotFoundError`, `result.sort`, `glob.glob`, `matches.sort`, `re.fullmatch`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_a0_connector_prompt_gating.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_default_prompt_budget.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_file_tree_visualize.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_image_get_security.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/functions.py.dox.md b/helpers/functions.py.dox.md
new file mode 100644
index 000000000..c2e00daac
--- /dev/null
+++ b/helpers/functions.py.dox.md
@@ -0,0 +1,45 @@
+# functions.py DOX
+
+## Purpose
+
+- Own the `functions.py` helper module.
+- This module provides safe generic callable execution helpers.
+- Keep this file-level DOX profile synchronized with `functions.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `functions.py` owns the runtime implementation.
+- `functions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `safe_call(func, *args, **kwargs)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `inspect`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `inspect.signature`, `func`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_a0_connector_prompt_gating.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_error_retry_plugin.py`
+ - `tests/test_oauth_codex.py`
+ - `tests/test_oauth_providers.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/git.py.dox.md b/helpers/git.py.dox.md
new file mode 100644
index 000000000..857c3966c
--- /dev/null
+++ b/helpers/git.py.dox.md
@@ -0,0 +1,70 @@
+# git.py DOX
+
+## Purpose
+
+- Own the `git.py` helper module.
+- This module reads local and remote Git release/commit metadata safely.
+- Keep this file-level DOX profile synchronized with `git.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `git.py` owns the runtime implementation.
+- `git.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `GitHeadInfo` (no explicit base class)
+- `GitReleaseInfo` (no explicit base class)
+- `GitRemoteReleaseInfo` (no explicit base class)
+- `GitRemoteReleasesResult` (no explicit base class)
+- `GitRemoteCommitsInfo` (no explicit base class)
+- `GitRepoReleaseInfo` (no explicit base class)
+- Top-level functions:
+- `strip_auth_from_url(url: str) -> str`: Remove any authentication info from URL.
+- `extract_author_repo(url: str) -> tuple[str, str]`
+- `_format_git_timestamp(timestamp: int) -> str`
+- `_split_describe_version(describe: str) -> tuple[str, int]`
+- `_format_release_version(branch: str, short_tag: str, commits_since_tag: int, commit_hash: str) -> str`
+- `get_remote_releases(author: str, repo: str) -> GitRemoteReleasesResult`
+- `get_remote_commits_since_local(repo_path: str) -> GitRemoteCommitsInfo`
+- `get_repo_release_info(repo_path: str) -> GitRepoReleaseInfo`
+- `get_git_info()`
+- `get_version()`
+- `is_official_agent_zero_repo() -> bool`: Return True when origin points to agent0ai/agent-zero.
+- `clone_repo(url: str, dest: str, token: str | None=...)`: Clone a git repository. Uses http.extraHeader for token auth (never stored in URL/config).
+- `update_repo(repo_path: str) -> Repo`
+- `get_repo_status(repo_path: str) -> dict`: Get Git repository status, ignoring A0 project metadata files.
+- Notable constants/configuration names: `A0_IGNORE_PATTERNS`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, filesystem deletion, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `base64`, `dataclasses`, `datetime`, `git`, `giturlparse`, `helpers`, `helpers.localization`, `os`, `re`, `subprocess`, `urllib.parse`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `urlparse`, `urlunparse`, `parse`, `strip`, `repo.endswith`, `datetime.fromtimestamp.strftime`, `describe.strip`, `re.fullmatch`, `files.get_base_dir`, `get_repo_release_info`, `os.environ.copy`, `subprocess.run`, `Repo`, `repo.active_branch.tracking_branch`, `strip_auth_from_url`, `ValueError`, `match.group`, `branch.upper`, `author.strip`, `repo.strip`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_docker_release_plan.py`
+ - `tests/test_git_version_label.py`
+ - `tests/test_model_config_api_keys.py`
+ - `tests/test_model_config_project_presets.py`
+ - `tests/test_model_search.py`
+ - `tests/test_oauth_github_copilot.py`
+ - `tests/test_oauth_providers.py`
+ - `tests/test_onboarding_static.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/guids.py.dox.md b/helpers/guids.py.dox.md
new file mode 100644
index 000000000..9fea993bf
--- /dev/null
+++ b/helpers/guids.py.dox.md
@@ -0,0 +1,40 @@
+# guids.py DOX
+
+## Purpose
+
+- Own the `guids.py` helper module.
+- This module generates framework IDs.
+- Keep this file-level DOX profile synchronized with `guids.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `guids.py` owns the runtime implementation.
+- `guids.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `generate_id(length: int=...) -> str`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `random`, `string`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `join`, `random.choices`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/history.py.dox.md b/helpers/history.py.dox.md
new file mode 100644
index 000000000..0e07d4a9e
--- /dev/null
+++ b/helpers/history.py.dox.md
@@ -0,0 +1,109 @@
+# history.py DOX
+
+## Purpose
+
+- Own the `history.py` helper module.
+- This module owns chat history message records and model-output conversion.
+- Keep this file-level DOX profile synchronized with `history.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `history.py` owns the runtime implementation.
+- `history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `RawMessage` (`TypedDict`)
+- `OutputMessage` (`TypedDict`)
+- `Record` (no explicit base class)
+ - `get_tokens(self) -> int`
+ - `async compress(self) -> bool`
+ - `output(self) -> list[OutputMessage]`
+ - `async summarize(self) -> str`
+ - `to_dict(self) -> dict`
+ - `from_dict(data: dict, history: 'History')`
+ - `output_langchain(self)`
+ - `output_text(self, human_label=..., ai_label=...)`
+- `Message` (`Record`)
+ - `get_tokens(self) -> int`
+ - `calculate_tokens(self)`
+ - `set_summary(self, summary: str)`
+ - `async compress(self)`
+ - `output(self)`
+ - `output_langchain(self)`
+ - `output_text(self, human_label=..., ai_label=...)`
+ - `to_dict(self)`
+- `Topic` (`Record`)
+ - `get_tokens(self)`
+ - `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message`
+ - `output(self) -> list[OutputMessage]`
+ - `async summarize(self)`
+ - `compress_large_messages(self, message_ratio: float=...) -> bool`
+ - `async compress(self) -> bool`
+ - `async compress_attention(self, ratio: float=...) -> bool`
+ - `async summarize_messages(self, messages: list[Message])`
+- `Bulk` (`Record`)
+ - `get_tokens(self)`
+ - `output(self, human_label: str=..., ai_label: str=...) -> list[OutputMessage]`
+ - `async compress(self)`
+ - `async summarize(self)`
+ - `to_dict(self)`
+ - `from_dict(data: dict, history: 'History')`
+- `History` (`Record`)
+ - `get_tokens(self) -> int`
+ - `is_over_limit(self)`
+ - `get_bulks_tokens(self) -> int`
+ - `get_topics_tokens(self) -> int`
+ - `get_current_topic_tokens(self) -> int`
+ - `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message`
+ - `new_topic(self)`
+ - `output(self) -> list[OutputMessage]`
+- Top-level functions:
+- `deserialize_history(json_data: str, agent) -> History`
+- `_stringify_output(output: OutputMessage, ai_label=..., human_label=...)`
+- `_stringify_content(content: MessageContent) -> str`
+- `_output_content_langchain(content: MessageContent)`
+- `group_outputs_abab(outputs: list[OutputMessage]) -> list[OutputMessage]`
+- `group_messages_abab(messages: list[BaseMessage]) -> list[BaseMessage]`
+- `output_langchain(messages: list[OutputMessage])`
+- `output_text(messages: list[OutputMessage], ai_label=..., human_label=...)`
+- `_merge_outputs(a: MessageContent, b: MessageContent) -> MessageContent`
+- `_merge_properties(a: Dict[str, MessageContent], b: Dict[str, MessageContent]) -> Dict[str, MessageContent]`
+- `_is_raw_message(obj: object) -> bool`
+- `_is_embedded_data(obj: object) -> bool`
+- `_json_dumps(obj)`
+- `_json_loads(obj)`
+- Notable constants/configuration names: `BULK_MERGE_COUNT`, `TOPICS_MERGE_COUNT`, `CURRENT_TOPIC_RATIO`, `HISTORY_TOPIC_RATIO`, `HISTORY_BULK_RATIO`, `CURRENT_TOPIC_ATTENTION_COMPRESSION`, `HISTORY_TOPIC_ATTENTION_COMPRESSION`, `LARGE_MESSAGE_TO_CURRENT_TOPIC_RATIO`, `LARGE_MESSAGE_TO_HISTORY_TOPIC_RATIO`, `RAW_MESSAGE_OUTPUT_TEXT_TRIM`, `COMPRESSION_TARGET_RATIO`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, filesystem deletion, model calls, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `abc`, `asyncio`, `collections`, `collections.abc`, `enum`, `helpers`, `json`, `langchain_core.messages`, `math`, `plugins._model_config.helpers.model_config`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `History`, `_is_raw_message`, `_json_dumps`, `group_messages_abab`, `join`, `make_list`, `cast`, `a.copy`, `json.dumps`, `json.loads`, `globals.from_dict`, `output_langchain`, `output_text`, `self.output_text`, `tokens.approximate_tokens`, `self.calculate_tokens`, `Message`, `get_chat_model_config`, `large_msgs.sort`, `self.compress_large_messages`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_chat_compaction.py`
+ - `tests/test_error_retry_plugin.py`
+ - `tests/test_history_compression_wait.py`
+ - `tests/test_mcp_handler_multimodal.py`
+ - `tests/test_memory_quality.py`
+ - `tests/test_model_config_project_presets.py`
+ - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/images.py.dox.md b/helpers/images.py.dox.md
new file mode 100644
index 000000000..1d2cd0320
--- /dev/null
+++ b/helpers/images.py.dox.md
@@ -0,0 +1,48 @@
+# images.py DOX
+
+## Purpose
+
+- Own the `images.py` helper module.
+- This module resolves, compresses, and serializes image references for model inputs.
+- Keep this file-level DOX profile synchronized with `images.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `images.py` owns the runtime implementation.
+- `images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `prepare_content(content: Any) -> Any`
+- `is_local_ref(url: str) -> bool`
+- `to_data_url(url: str) -> str`
+- `resolve_ref(url: str) -> Path`
+- `compress_image(image_data: bytes, max_pixels: int=..., quality: int=...) -> bytes`: Compress an image by scaling it down and converting to JPEG with quality settings.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, network calls, settings/state persistence.
+- Imported dependency areas include: `PIL`, `base64`, `io`, `math`, `mimetypes`, `pathlib`, `typing`, `urllib.parse`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `url.lower`, `lowered.startswith`, `resolve_ref`, `base64.b64encode.decode`, `Path.expanduser`, `raw_path.startswith`, `FileNotFoundError`, `io.BytesIO`, `img.save`, `output.getvalue`, `prepare_content`, `url.startswith`, `mimetypes.guess_type`, `ValueError`, `url.lower.startswith`, `unquote`, `seen.add`, `math.sqrt`, `img.resize`, `img.convert`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_image_get_security.py`
+ - `tests/test_vision_load_image_refs.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/integration_commands.py.dox.md b/helpers/integration_commands.py.dox.md
new file mode 100644
index 000000000..b7462926e
--- /dev/null
+++ b/helpers/integration_commands.py.dox.md
@@ -0,0 +1,53 @@
+# integration_commands.py DOX
+
+## Purpose
+
+- Own the `integration_commands.py` helper module.
+- This module parses external integration slash commands such as project/config/send controls.
+- Keep this file-level DOX profile synchronized with `integration_commands.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `integration_commands.py` owns the runtime implementation.
+- `integration_commands.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `extract_command_line(text: str) -> str`
+- `parse_command(text: str) -> tuple[str, str] | None`
+- `try_handle_command(context: 'AgentContext', text: str) -> str | None`
+- `_handle_queue(context: 'AgentContext', args: str) -> str`
+- `_handle_project(context: 'AgentContext', args: str) -> str`
+- `_handle_config(context: 'AgentContext', args: str) -> str`
+- `_format_project_entry(item: dict) -> str`
+- `_describe_project(items: list[dict], current_name: str) -> str`
+- `_describe_override(override: dict | None) -> str`
+- `_strip_quotes(value: str) -> str`
+- `_normalize_lookup(value: str) -> str`
+- `_match_named_item(items: list[dict], desired: str, keys: tuple[str, ...]) -> tuple[dict | None, list[dict]]`
+- Notable constants/configuration names: `_CLEAR_VALUES`, `_SUPPORTED_COMMANDS`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence.
+- Imported dependency areas include: `__future__`, `helpers`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `plugins._model_config.helpers`, `re`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `splitlines`, `extract_command_line`, `line.partition`, `command.strip.lower`, `parse_command`, `mq.get_queue`, `args.strip.lower`, `mq.send_all_aggregated`, `mark_dirty_for_context`, `_strip_quotes`, `_match_named_item`, `projects.activate_project`, `model_config.is_chat_override_allowed`, `context.get_data`, `context.set_data`, `save_tmp_chat`, `str.strip`, `value.strip`, `value.lower.strip`, `re.sub`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/job_loop.py.dox.md b/helpers/job_loop.py.dox.md
new file mode 100644
index 000000000..b0414749d
--- /dev/null
+++ b/helpers/job_loop.py.dox.md
@@ -0,0 +1,46 @@
+# job_loop.py DOX
+
+## Purpose
+
+- Own the `job_loop.py` helper module.
+- This module runs periodic scheduler and maintenance loops.
+- Keep this file-level DOX profile synchronized with `job_loop.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `job_loop.py` owns the runtime implementation.
+- `job_loop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `async run_loop()`
+- `async scheduler_tick()`
+- `pause_loop()`
+- `resume_loop()`
+- Notable constants/configuration names: `SLEEP_TIME`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: scheduler state.
+- Imported dependency areas include: `asyncio`, `datetime`, `helpers`, `helpers.print_style`, `helpers.task_scheduler`, `time`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `time.time`, `runtime.is_development`, `scheduler.tick`, `call_extensions_async`, `resume_loop`, `asyncio.sleep`, `runtime.call_development_function`, `PrintStyle.error`, `scheduler_tick`, `errors.format_error`, `PrintStyle`, `errors.error_text`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_api_chat_lifetime.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/kvp.py.dox.md b/helpers/kvp.py.dox.md
new file mode 100644
index 000000000..d7e6e0de0
--- /dev/null
+++ b/helpers/kvp.py.dox.md
@@ -0,0 +1,52 @@
+# kvp.py DOX
+
+## Purpose
+
+- Own the `kvp.py` helper module.
+- This module provides runtime and persistent key-value storage helpers.
+- Keep this file-level DOX profile synchronized with `kvp.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `kvp.py` owns the runtime implementation.
+- `kvp.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `_persistent_dir() -> str`
+- `_validate_key(key: str) -> None`
+- `_key_to_path(key: str) -> str`
+- `get_runtime(key: str, default: Any=...) -> Any`
+- `set_runtime(key: str, value: Any) -> None`
+- `remove_runtime(key: str) -> None`
+- `find_runtime(pattern: str) -> list[str]`
+- `get_persistent(key: str, default: Any=...) -> Any`
+- `set_persistent(key: str, value: Any) -> None`
+- `remove_persistent(key: str) -> None`
+- `find_persistent(pattern: str) -> list[str]`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `fnmatch`, `glob`, `helpers.files`, `json`, `os`, `tempfile`, `threading`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `threading.RLock`, `get_abs_path`, `_validate_key`, `os.path.join`, `_key_to_path`, `os.path.dirname`, `_persistent_dir`, `ValueError`, `_runtime_store.pop`, `os.makedirs`, `tempfile.mkstemp`, `glob.glob`, `keys.sort`, `os.replace`, `os.unlink`, `os.path.isdir`, `json.load`, `os.fdopen`, `json.dump`, `f.flush`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/localization.py.dox.md b/helpers/localization.py.dox.md
new file mode 100644
index 000000000..b33e410b8
--- /dev/null
+++ b/helpers/localization.py.dox.md
@@ -0,0 +1,50 @@
+# localization.py DOX
+
+## Purpose
+
+- Own the `localization.py` helper module.
+- This module loads and resolves localized UI/application text.
+- Keep this file-level DOX profile synchronized with `localization.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `localization.py` owns the runtime implementation.
+- `localization.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Localization` (no explicit base class)
+ - `get(cls, *args, **kwargs)`
+ - `get_timezone(self) -> str`
+ - `get_tzinfo(self)`
+ - `get_offset_minutes(self) -> int`
+ - `apply_process_timezone(self) -> None`
+ - `now(self) -> datetime`
+ - `now_iso(self, sep: str=..., timespec: str=...) -> str`
+ - `localize_naive_datetime(self, dt: datetime) -> datetime`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, settings/state persistence.
+- Imported dependency areas include: `datetime`, `helpers.dotenv`, `helpers.print_style`, `os`, `pytz`, `time`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `get_dotenv_value`, `pytz.timezone`, `datetime.now`, `now_in_tz.utcoffset`, `self.now.isoformat`, `self.get_tzinfo`, `cls`, `self.set_timezone`, `self._compute_offset_minutes`, `self.apply_process_timezone`, `tzinfo.localize`, `PrintStyle.debug`, `save_dotenv_value`, `localtime_str.strip.replace`, `local_datetime_obj.astimezone`, `utc_dt.astimezone`, `local_datetime_obj.isoformat`, `dt.astimezone`, `local_dt.isoformat`, `time.tzset`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_timezone_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/log.py.dox.md b/helpers/log.py.dox.md
new file mode 100644
index 000000000..ce74dec69
--- /dev/null
+++ b/helpers/log.py.dox.md
@@ -0,0 +1,68 @@
+# log.py DOX
+
+## Purpose
+
+- Own the `log.py` helper module.
+- This module owns chat log items, outputs, truncation, and dirty-state integration.
+- Keep this file-level DOX profile synchronized with `log.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `log.py` owns the runtime implementation.
+- `log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `LogItem` (no explicit base class)
+ - `update(self, type: Type | None=..., heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., **kwargs)`
+ - `stream(self, heading: str | None=..., content: str | None=..., **kwargs)`
+ - `output(self)`
+- `LogOutput` (no explicit base class)
+- `Log` (no explicit base class)
+ - `log(self, type: Type, heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., id: Optional[str]=..., **kwargs) -> LogItem`
+ - `set_progress(self, progress: str, no: int=..., active: bool=...)`
+ - `set_initial_progress(self)`
+ - `output(self, start=..., end=...)`
+ - `reset(self)`
+- Top-level functions:
+- `_lazy_mark_dirty_all(reason: str | None=...) -> None`
+- `_lazy_mark_dirty_for_context(context_id: str, reason: str | None=...) -> None`
+- `_truncate_heading(text: str | None) -> str`
+- `_truncate_progress(text: str | None) -> str`
+- `_truncate_key(text: str) -> str`
+- `_truncate_value(val: T) -> T`
+- `_truncate_content(text: str | None, type: Type) -> str`
+- Notable constants/configuration names: `_MARK_DIRTY_ALL`, `_MARK_DIRTY_FOR_CONTEXT`, `T`, `HEADING_MAX_LEN`, `CONTENT_MAX_LEN`, `RESPONSE_CONTENT_MAX_LEN`, `KEY_MAX_LEN`, `VALUE_MAX_LEN`, `PROGRESS_MAX_LEN`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `collections`, `copy`, `dataclasses`, `helpers.secrets`, `helpers.strings`, `json`, `threading`, `time`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TypeVar`, `dataclass`, `_MARK_DIRTY_ALL`, `_MARK_DIRTY_FOR_CONTEXT`, `truncate_text_by_ratio`, `cast`, `threading.RLock`, `self.set_initial_progress`, `self._update_item`, `self._notify_state_monitor`, `_lazy_mark_dirty_all`, `_lazy_mark_dirty_for_context`, `self._mask_recursive`, `_truncate_progress`, `self.set_progress`, `LogOutput`, `_truncate_value`, `json.dumps`, `time.time`, `self.log._update_item`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_chat_compaction.py`
+ - `tests/test_error_retry_plugin.py`
+ - `tests/test_fasta2a_client.py`
+ - `tests/test_file_tree_visualize.py`
+ - `tests/test_history_compression_wait.py`
+ - `tests/test_http_auth_csrf.py`
+ - `tests/test_mcp_handler_multimodal.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/login.py.dox.md b/helpers/login.py.dox.md
new file mode 100644
index 000000000..344895198
--- /dev/null
+++ b/helpers/login.py.dox.md
@@ -0,0 +1,49 @@
+# login.py DOX
+
+## Purpose
+
+- Own the `login.py` helper module.
+- This module checks login requirements and credential hashes.
+- Keep this file-level DOX profile synchronized with `login.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `login.py` owns the runtime implementation.
+- `login.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `get_credentials_hash()`
+- `is_login_required()`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: secret handling.
+- Imported dependency areas include: `hashlib`, `helpers`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dotenv.get_dotenv_value`, `hashlib.sha256.hexdigest`, `hashlib.sha256`, `encode`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_http_auth_csrf.py`
+ - `tests/test_oauth_gemini_api.py`
+ - `tests/test_oauth_github_copilot.py`
+ - `tests/test_oauth_providers.py`
+ - `tests/test_oauth_xai_grok.py`
+ - `tests/test_tunnel_remote_link.py`
+ - `tests/test_ws_security.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/mcp_handler.py.dox.md b/helpers/mcp_handler.py.dox.md
new file mode 100644
index 000000000..fc98db4f0
--- /dev/null
+++ b/helpers/mcp_handler.py.dox.md
@@ -0,0 +1,90 @@
+# mcp_handler.py DOX
+
+## Purpose
+
+- Own the `mcp_handler.py` helper module.
+- This module loads MCP server configuration and exposes MCP tools to agents.
+- Keep this file-level DOX profile synchronized with `mcp_handler.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `mcp_handler.py` owns the runtime implementation.
+- `mcp_handler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `MCPTool` (`Tool`)
+ - `get_log_object(self) -> LogItem`
+ - `async execute(self, **kwargs)`
+ - `async before_execution(self, **kwargs)`
+ - `async after_execution(self, response: Response, **kwargs)`
+- `MCPServerRemote` (`BaseModel`)
+ - `get_error(self) -> str`
+ - `get_log(self) -> str`
+ - `get_tools(self) -> List[dict[str, Any]]`
+ - `has_tool(self, tool_name: str) -> bool`
+ - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
+ - `update(self, config: dict[str, Any]) -> 'MCPServerRemote'`
+ - `async initialize(self) -> 'MCPServerRemote'`
+- `MCPServerLocal` (`BaseModel`)
+ - `get_error(self) -> str`
+ - `get_log(self) -> str`
+ - `get_tools(self) -> List[dict[str, Any]]`
+ - `has_tool(self, tool_name: str) -> bool`
+ - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
+ - `update(self, config: dict[str, Any]) -> 'MCPServerLocal'`
+ - `async initialize(self) -> 'MCPServerLocal'`
+- `MCPConfig` (`BaseModel`)
+ - `get_instance(cls) -> 'MCPConfig'`
+ - `wait_for_lock(cls)`
+ - `update(cls, config_str: str) -> Any`
+ - `normalize_config(cls, servers: Any)`
+ - `get_server_log(self, server_name: str) -> str`
+ - `get_servers_status(self) -> list[dict[str, Any]]`
+ - `get_server_detail(self, server_name: str) -> dict[str, Any]`
+ - `is_initialized(self) -> bool`
+- `MCPClientBase` (`ABC`)
+ - `async update_tools(self) -> 'MCPClientBase'`
+ - `has_tool(self, tool_name: str) -> bool`
+ - `get_tools(self) -> List[dict[str, Any]]`
+ - `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
+ - `get_log(self)`
+- `MCPClientLocal` (`MCPClientBase`)
+- `CustomHTTPClientFactory` (`ABC`)
+- `MCPClientRemote` (`MCPClientBase`)
+ - `get_session_id(self) -> Optional[str]`
+- Top-level functions:
+- `_mcp_get(item: Any, key: str, default: Any=...) -> Any`
+- `normalize_name(name: str) -> str`
+- `_determine_server_type(config_dict: dict) -> str`: Determine the server type based on configuration, with backward compatibility.
+- `_is_streaming_http_type(server_type: str) -> bool`: Check if the server type is a streaming HTTP variant.
+- `initialize_mcp(mcp_servers_config: str)`
+- Notable constants/configuration names: `MCP_MEDIA_TOKENS_ESTIMATE`, `MAX_MCP_RESOURCE_TEXT_CHARS`, `T`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- `MCPTool` is a `Tool`.
+- `MCPTool` defines `execute(...)`.
+- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling.
+- Imported dependency areas include: `abc`, `anyio.streams.memory`, `asyncio`, `contextlib`, `datetime`, `helpers`, `helpers.log`, `helpers.print_style`, `helpers.tool`, `httpx`, `json`, `mcp`, `mcp.client.sse`, `mcp.client.stdio`, `mcp.client.streamable_http`, `mcp.shared.message`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TypeVar`, `name.strip.lower`, `re.sub`, `Field`, `PrivateAttr`, `threading.Lock`, `config_dict.lower`, `server_type.lower`, `MCPConfig.get_instance.is_initialized`, `self.agent.context.log.log`, `str.strip`, `media_artifacts.guess_extension`, `callable`, `self._content_item_dump`, `join`, `Response`, `self.get_log_object`, `self._raw_tool_response`, `additional.pop`, `self._coerce_media_token_estimate`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_mcp_handler_multimodal.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/mcp_server.py.dox.md b/helpers/mcp_server.py.dox.md
new file mode 100644
index 000000000..4151d3d89
--- /dev/null
+++ b/helpers/mcp_server.py.dox.md
@@ -0,0 +1,54 @@
+# mcp_server.py DOX
+
+## Purpose
+
+- Own the `mcp_server.py` helper module.
+- This module serves Agent Zero chats through a dynamic MCP proxy.
+- Keep this file-level DOX profile synchronized with `mcp_server.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `mcp_server.py` owns the runtime implementation.
+- `mcp_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ToolResponse` (`BaseModel`)
+- `ToolError` (`BaseModel`)
+- `DynamicMcpProxy` (no explicit base class)
+ - `get_instance()`
+ - `reconfigure(self, token: str)`
+- Top-level functions:
+- `async send_message(message: Annotated[str, Field(description='The message to send to the remote Agent Zero Instance', title='message')], attachments: Annotated[list[str], Field(description='Optional: A list of attachments (file paths or web urls) to send to the remote Agent Zero Instance with the message. Default: Empty list', title='attachments')] | None=..., chat_id: Annotated[str, Field(description='Optional: ID of the chat. Used to continue a chat. This value is returned in response to sending previous message. Default: Empty string', title='chat_id')] | None=..., persistent_chat: Annotated[bool, Field(description='Optional: Whether to use a persistent chat. If true, the chat will be saved and can be continued later. Default: False.', title='persistent_chat')] | None=...) -> Annotated[Union[ToolResponse, ToolError], Field(description='The response from the remote Agent Zero Instance', title='response')]`
+- `async finish_chat(chat_id: Annotated[str, Field(description='ID of the chat to be finished. This value is returned in response to sending previous message.', title='chat_id')]) -> Annotated[Union[ToolResponse, ToolError], Field(description='The response from the remote Agent Zero Instance', title='response')]`
+- `async _run_chat(context: AgentContext, message: str, attachments: list[str] | None=...)`
+- `async mcp_middleware(request: Request, call_next)`: Middleware to check if MCP server is enabled.
+- Notable constants/configuration names: `_PRINTER`, `SEND_MESSAGE_DESCRIPTION`, `FINISH_CHAT_DESCRIPTION`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `agent`, `asyncio`, `contextvars`, `fastmcp`, `fastmcp.server.http`, `helpers`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `openai`, `os`, `pydantic`, `starlette.exceptions`, `starlette.middleware`, `starlette.middleware.base`, `starlette.requests`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `PrintStyle`, `contextvars.ContextVar`, `FastMCP`, `mcp_server.tool`, `Field`, `settings.get_settings`, `initialize_agent`, `AgentContext`, `ToolError`, `ToolResponse`, `context.reset`, `AgentContext.remove`, `remove_chat`, `context.communicate`, `threading.RLock`, `self.reconfigure`, `StreamableHTTPSessionManager`, `mcp_server._get_additional_http_routes`, `create_base_app`, `PrintStyle.error`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_default_prompt_budget.py`
+ - `tests/test_fasta2a_client.py`
+ - `tests/test_ws_security.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/media_artifacts.py.dox.md b/helpers/media_artifacts.py.dox.md
new file mode 100644
index 000000000..9f4d0c39f
--- /dev/null
+++ b/helpers/media_artifacts.py.dox.md
@@ -0,0 +1,60 @@
+# media_artifacts.py DOX
+
+## Purpose
+
+- Own the `media_artifacts.py` helper module.
+- This module validates, decodes, names, and normalizes media artifact payloads.
+- Keep this file-level DOX profile synchronized with `media_artifacts.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `media_artifacts.py` owns the runtime implementation.
+- `media_artifacts.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `MediaArtifactError` (`ValueError`)
+- `EmptyBase64Data` (`MediaArtifactError`)
+- `InvalidBase64Data` (`MediaArtifactError`)
+- `ArtifactTooLarge` (`MediaArtifactError`)
+- `Base64Payload` (no explicit base class)
+- `ImageDataUrl` (no explicit base class)
+- `SavedArtifact` (no explicit base class)
+- Top-level functions:
+- `compact_base64(data: str) -> str`
+- `estimated_base64_decoded_size(data: str) -> int`
+- `decode_base64_payload(data: str, max_bytes: int | None=...) -> Base64Payload`
+- `normalize_mime(mime_type: str, default: str=..., required_prefix: str=...) -> str`
+- `guess_extension(mime_type: str, fallback: str=...) -> str`
+- `filename_from_uri(uri: str) -> str`
+- `safe_filename(value: str, default: str=..., default_extension: str=...) -> str`
+- `image_data_url_from_base64(data: str, mime_type: str=..., max_bytes: int | None=...) -> ImageDataUrl`
+- `save_base64_artifact(data: str, mime_type: str=..., directory_parts: tuple[str, ...], preferred_name: str=..., default_filename: str=..., max_bytes: int | None=...) -> SavedArtifact`
+- Notable constants/configuration names: `DEFAULT_MAX_ARTIFACT_SIZE_BYTES`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, network calls.
+- Imported dependency areas include: `__future__`, `base64`, `binascii`, `dataclasses`, `helpers`, `mimetypes`, `pathlib`, `urllib.parse`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `join`, `compact_base64`, `Base64Payload`, `str.strip.lower`, `str.strip`, `urlparse`, `decode_base64_payload`, `normalize_mime`, `ImageDataUrl`, `guess_extension`, `safe_filename`, `Path`, `artifact_dir.mkdir`, `path.write_bytes`, `SavedArtifact`, `super.__init__`, `EmptyBase64Data`, `estimated_base64_decoded_size`, `base64.b64decode`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_mcp_handler_multimodal.py`
+ - `tests/test_media_artifacts.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/message_queue.py.dox.md b/helpers/message_queue.py.dox.md
new file mode 100644
index 000000000..df300ed67
--- /dev/null
+++ b/helpers/message_queue.py.dox.md
@@ -0,0 +1,53 @@
+# message_queue.py DOX
+
+## Purpose
+
+- Own the `message_queue.py` helper module.
+- This module stores and drains queued user messages for a context.
+- Keep this file-level DOX profile synchronized with `message_queue.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `message_queue.py` owns the runtime implementation.
+- `message_queue.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `get_queue(context: 'AgentContext') -> list`: Get current queue from context.data.
+- `_get_next_seq(context: 'AgentContext') -> int`: Get next sequence number.
+- `_sync_output(context: 'AgentContext')`: Sync queue to output_data for frontend polling.
+- `add(context: 'AgentContext', text: str, attachments: list[str] | None=..., item_id: str | None=...) -> dict`: Add message to queue. Attachments should be filenames, will be converted to full paths.
+- `remove(context: 'AgentContext', item_id: str | None=...) -> int`: Remove item(s). If item_id is None, clears all. Returns remaining count.
+- `pop_first(context: 'AgentContext') -> dict | None`: Remove and return first item.
+- `pop_item(context: 'AgentContext', item_id: str) -> dict | None`: Remove and return specific item.
+- `has_queue(context: 'AgentContext') -> bool`: Check if queue has items.
+- `log_user_message(context: 'AgentContext', message: str, attachment_paths: list[str], message_id: str | None=..., source: str=...)`: Log user message to console and UI. Used by message API and queue processing.
+- `send_message(context: 'AgentContext', item: dict, source: str=...)`: Send a single queued message (log + communicate).
+- `send_next(context: 'AgentContext') -> bool`: Send next queued message. Returns True if sent, False if queue empty.
+- `send_all_aggregated(context: 'AgentContext') -> int`: Aggregate and send all queued messages as one. Returns count of items sent.
+- Notable constants/configuration names: `QUEUE_KEY`, `QUEUE_SEQ_KEY`, `UPLOAD_FOLDER`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `context.set_data`, `get_queue`, `context.set_output_data`, `_sync_output`, `queue.pop`, `context.log.log`, `log_user_message`, `context.communicate`, `pop_first`, `has_queue`, `join`, `context.get_data`, `att.startswith`, `_get_next_seq`, `uuid.uuid4`, `UserMessage`, `send_message`, `guids.generate_id`, `os.path.basename`, `PrintStyle`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/messages.py.dox.md b/helpers/messages.py.dox.md
new file mode 100644
index 000000000..e61772114
--- /dev/null
+++ b/helpers/messages.py.dox.md
@@ -0,0 +1,50 @@
+# messages.py DOX
+
+## Purpose
+
+- Own the `messages.py` helper module.
+- This module truncates message payloads for display and storage safety.
+- Keep this file-level DOX profile synchronized with `messages.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `messages.py` owns the runtime implementation.
+- `messages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `truncate_text(agent, output, threshold=...)`
+- `truncate_dict_by_ratio(agent, data: dict | list | str, threshold_chars: int, truncate_to: int)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
+- Imported dependency areas include: `json`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `agent.read_prompt`, `process_item`, `json.dumps`, `truncate_text`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/email_parser_test.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_chat_compaction.py`
+ - `tests/test_document_query_fallback.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_fasta2a_client.py`
+ - `tests/test_mcp_handler_multimodal.py`
+ - `tests/test_oauth_codex.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/microsoft_tunnel.py.dox.md b/helpers/microsoft_tunnel.py.dox.md
new file mode 100644
index 000000000..32ee7027c
--- /dev/null
+++ b/helpers/microsoft_tunnel.py.dox.md
@@ -0,0 +1,50 @@
+# microsoft_tunnel.py DOX
+
+## Purpose
+
+- Own the `microsoft_tunnel.py` helper module.
+- This module implements Microsoft Dev Tunnel provider behavior.
+- Keep this file-level DOX profile synchronized with `microsoft_tunnel.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `microsoft_tunnel.py` owns the runtime implementation.
+- `microsoft_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `AgentZeroMicrosoftTunnel` (`MicrosoftTunnel`)
+ - `notify(self, event, message, data=...)`
+ - `agent_zero_notifications(self)`
+- `MicrosoftDevTunnel` (`FlaredanticTunnelHelper`)
+ - `build_tunnel(self)`
+ - `start(self)`
+- Top-level functions:
+- `default_microsoft_tunnel_id()`
+- Notable constants/configuration names: `MICROSOFT_TUNNEL_ID_ENV_KEYS`, `MICROSOFT_TUNNEL_TIMEOUT`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, network calls, settings/state persistence, tunnel state.
+- Imported dependency areas include: `flaredantic`, `getpass`, `hashlib`, `helpers`, `helpers.tunnel_common`, `os`, `socket`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `join`, `strip`, `hashlib.sha256.hexdigest`, `self.notify`, `callable`, `self._notify_progress`, `self._run_cmd`, `MicrosoftConfig`, `AgentZeroMicrosoftTunnel`, `getpass.getuser`, `socket.gethostname`, `files.get_abs_path`, `super.notify`, `parent`, `super.start`, `hashlib.sha256`, `MicrosoftTunnelError`, `default_microsoft_tunnel_id`, `RuntimeError`, `seed.encode`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/migration.py.dox.md b/helpers/migration.py.dox.md
new file mode 100644
index 000000000..c548951ab
--- /dev/null
+++ b/helpers/migration.py.dox.md
@@ -0,0 +1,52 @@
+# migration.py DOX
+
+## Purpose
+
+- Own the `migration.py` helper module.
+- This module migrates legacy user data and runtime layout at startup.
+- Keep this file-level DOX profile synchronized with `migration.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `migration.py` owns the runtime implementation.
+- `migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `startup_migration() -> None`
+- `migrate_user_data() -> None`: Migrate user data from /tmp and other locations to /usr.
+- `convert_agents_json_yaml() -> None`
+- `_move_dir(src: str, dst: str, overwrite: bool=...) -> None`: Move a directory from src to dst if src exists and dst does not.
+- `_move_file(src: str, dst: str, overwrite: bool=...) -> None`: Move a file from src to dst if src exists and dst does not.
+- `_migrate_memory(base_path: str=...) -> None`: Migrate memory subdirectories.
+- `_merge_dir_contents(src_parent: str, dst_parent: str) -> None`: Moves all items from src_parent to dst_parent.
+- `_cleanup_obsolete() -> None`: Remove directories that are no longer needed.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `helpers`, `helpers.print_style`, `json`, `os`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `migrate_user_data`, `convert_agents_json_yaml`, `extension.call_extensions_sync`, `_move_dir`, `_move_file`, `_migrate_memory`, `_merge_dir_contents`, `_cleanup_obsolete`, `subagents.get_agents_roots`, `files.get_subdirectories`, `files.list_files`, `files.deabsolute_path`, `files.exists`, `files.move_dir`, `files.move_file`, `files.get_abs_path`, `os.path.isdir`, `os.path.join`, `files.delete_dir`, `os.path.isfile`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_office_canvas_setup.py`
+ - `tests/test_office_document_store.py`
+ - `tests/test_speech_plugin_split.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/modules.py.dox.md b/helpers/modules.py.dox.md
new file mode 100644
index 000000000..9f42143ed
--- /dev/null
+++ b/helpers/modules.py.dox.md
@@ -0,0 +1,53 @@
+# modules.py DOX
+
+## Purpose
+
+- Own the `modules.py` helper module.
+- This module imports modules and classes dynamically with namespace cache control.
+- Keep this file-level DOX profile synchronized with `modules.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `modules.py` owns the runtime implementation.
+- `modules.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `import_module(file_path: str) -> ModuleType`
+- `load_classes_from_folder(folder: str, name_pattern: str, base_class: Type[T], one_per_file: bool=...) -> list[Type[T]]`
+- `load_classes_from_file(file: str, base_class: type[T], one_per_file: bool=...) -> list[type[T]]`
+- `purge_namespace(namespace: str)`
+- Notable constants/configuration names: `T`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion.
+- Imported dependency areas include: `fnmatch`, `helpers.files`, `importlib`, `importlib.util`, `inspect`, `os`, `re`, `sys`, `types`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TypeVar`, `get_abs_path`, `os.path.basename.replace`, `importlib.util.spec_from_file_location`, `importlib.util.module_from_spec`, `spec.loader.exec_module`, `import_module`, `inspect.getmembers`, `to_delete.sort`, `importlib.invalidate_caches`, `ImportError`, `os.path.join`, `os.path.basename`, `issubclass`, `os.listdir`, `name.startswith`, `n.count`, `fnmatch`, `file_name.endswith`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_a0_connector_prompt_gating.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_docker_release_plan.py`
+ - `tests/test_error_retry_plugin.py`
+ - `tests/test_file_tree_visualize.py`
+ - `tests/test_git_version_label.py`
+ - `tests/test_mcp_handler_multimodal.py`
+ - `tests/test_memory_quality.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/network.py.dox.md b/helpers/network.py.dox.md
new file mode 100644
index 000000000..792836311
--- /dev/null
+++ b/helpers/network.py.dox.md
@@ -0,0 +1,55 @@
+# network.py DOX
+
+## Purpose
+
+- Own the `network.py` helper module.
+- This module validates public URLs and fetches remote resources safely.
+- Keep this file-level DOX profile synchronized with `network.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `network.py` owns the runtime implementation.
+- `network.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `HttpFetchResult` (no explicit base class)
+- `UnsafeUrlError` (`ValueError`)
+- Top-level functions:
+- `_build_request_headers() -> dict[str, str]`
+- `_normalize_content_type(content_type: str | None) -> str | None`
+- `resolve_host_ips(hostname: str) -> tuple[ipaddress._BaseAddress, ...]`
+- `validate_public_http_url(url: str) -> tuple[ipaddress._BaseAddress, ...]`
+- `fetch_public_http_resource(url: str, max_bytes: int, max_redirects: int=..., timeout: tuple[float, float]=...) -> HttpFetchResult`
+- `is_loopback_address(address: str) -> bool`: Check whether *address* resolves to a loopback interface.
+- Notable constants/configuration names: `SAFE_HTTP_SCHEMES`, `DEFAULT_FETCH_TIMEOUT`, `DEFAULT_HTTP_USER_AGENT`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: network calls, secret handling.
+- Imported dependency areas include: `__future__`, `dataclasses`, `ipaddress`, `os`, `requests`, `socket`, `struct`, `urllib.parse`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `frozenset`, `dataclass`, `strip`, `urlparse`, `parsed.hostname.rstrip.lower`, `resolve_host_ips`, `requests.Session`, `ValueError`, `content_type.split.strip.lower`, `socket.getaddrinfo`, `ipaddress.ip_address`, `seen.add`, `UnsafeUrlError`, `hostname.endswith`, `validate_public_http_url`, `socket.inet_pton`, `_checkers`, `parsed.hostname.rstrip`, `os.getenv`, `content_type.split.strip`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_oauth_gemini_api.py`
+ - `tests/test_oauth_github_copilot.py`
+ - `tests/test_oauth_xai_grok.py`
+ - `tests/test_plugin_scan_prompt.py`
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/notification.py.dox.md b/helpers/notification.py.dox.md
new file mode 100644
index 000000000..d8f198f4a
--- /dev/null
+++ b/helpers/notification.py.dox.md
@@ -0,0 +1,62 @@
+# notification.py DOX
+
+## Purpose
+
+- Own the `notification.py` helper module.
+- This module owns notification data models and notification manager state.
+- Keep this file-level DOX profile synchronized with `notification.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `notification.py` owns the runtime implementation.
+- `notification.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `NotificationType` (`Enum`)
+- `NotificationPriority` (`Enum`)
+- `NotificationItem` (no explicit base class)
+ - `mark_read(self)`
+ - `output(self)`
+- `NotificationManager` (no explicit base class)
+ - `send_notification(type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem`
+ - `add_notification(self, type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem`
+ - `get_recent_notifications(self, seconds: int=...) -> list[NotificationItem]`
+ - `output(self, start: int | None=..., end: int | None=...) -> list[dict]`
+ - `output_all(self) -> list[dict]`
+ - `mark_read_by_ids(self, notification_ids: list[str]) -> int`
+ - `update_item(self, no: int, **kwargs) -> None`
+ - `mark_all_read(self)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `dataclasses`, `datetime`, `enum`, `helpers.localization`, `threading`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.manager.update_item`, `threading.RLock`, `AgentContext.get_notification_manager.add_notification`, `mark_dirty_all`, `self._update_item`, `NotificationType`, `Localization.get.serialize_datetime`, `uuid.uuid4`, `Localization.get.now`, `timedelta`, `n.output`, `AgentContext.get_notification_manager`, `next`, `NotificationPriority`, `NotificationItem`, `self._enforce_limit`, `seen.add`, `notifications.output`, `nid.strip`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_multi_tab_isolation.py`
+ - `tests/test_self_update_tag_filter.py`
+ - `tests/test_snapshot_parity.py`
+ - `tests/test_snapshot_schema_v1.py`
+ - `tests/test_state_monitor.py`
+ - `tests/test_state_sync_handler.py`
+ - `tests/test_state_sync_welcome_screen.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/performance.py.dox.md b/helpers/performance.py.dox.md
new file mode 100644
index 000000000..36181986d
--- /dev/null
+++ b/helpers/performance.py.dox.md
@@ -0,0 +1,42 @@
+# performance.py DOX
+
+## Purpose
+
+- Own the `performance.py` helper module.
+- This module provides lightweight performance tracing helpers.
+- Keep this file-level DOX profile synchronized with `performance.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `performance.py` owns the runtime implementation.
+- `performance.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `trace_performance(show_all=..., color=..., unicode=...)`: Decorator that profiles a function and prints a call tree when it finishes.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `functools`, `inspect`, `pyinstrument`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `inspect.iscoroutinefunction`, `functools.wraps`, `Profiler`, `profiler.start`, `profiler.stop`, `func`, `profiler.output_text`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_extensions_stress.py`
+ - `tests/test_ws_manager.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/perplexity_search.py.dox.md b/helpers/perplexity_search.py.dox.md
new file mode 100644
index 000000000..1144ec0e9
--- /dev/null
+++ b/helpers/perplexity_search.py.dox.md
@@ -0,0 +1,41 @@
+# perplexity_search.py DOX
+
+## Purpose
+
+- Own the `perplexity_search.py` helper module.
+- This module queries Perplexity search using configured model/provider credentials.
+- Keep this file-level DOX profile synchronized with `perplexity_search.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `perplexity_search.py` owns the runtime implementation.
+- `perplexity_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `perplexity_search(query: str, model_name=..., api_key=..., base_url=...)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: secret handling.
+- Imported dependency areas include: `models`, `openai`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `OpenAI`, `client.chat.completions.create`, `models.get_api_key`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/persist_chat.py.dox.md b/helpers/persist_chat.py.dox.md
new file mode 100644
index 000000000..bf251b8e7
--- /dev/null
+++ b/helpers/persist_chat.py.dox.md
@@ -0,0 +1,65 @@
+# persist_chat.py DOX
+
+## Purpose
+
+- Own the `persist_chat.py` helper module.
+- This module persists and reloads chat contexts and message artifacts.
+- Keep this file-level DOX profile synchronized with `persist_chat.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `persist_chat.py` owns the runtime implementation.
+- `persist_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `_fallback_datetime_iso() -> str`
+- `_parse_persisted_datetime(value: str | None) -> datetime`
+- `get_chat_folder_path(ctxid: str)`: Get the folder path for any context (chat or task).
+- `get_chat_msg_files_folder(ctxid: str)`
+- `save_tmp_chat(context: AgentContext)`: Save context to the chats folder
+- `save_tmp_chats()`: Save all contexts to the chats folder
+- `load_tmp_chats()`: Load all contexts from the chats folder
+- `_get_chat_file_path(ctxid: str)`
+- `_convert_v080_chats()`
+- `load_json_chats(jsons: list[str])`: Load contexts from JSON strings
+- `export_json_chat(context: AgentContext)`: Export context as JSON string
+- `remove_chat(ctxid)`: Remove a chat or task context
+- `remove_msg_files(ctxid)`: Remove all message files for a chat or task context
+- `_serialize_context(context: AgentContext)`
+- `_serialize_agent(agent: Agent)`
+- `_serialize_log(log: Log)`
+- `_deserialize_context(data)`
+- `_deserialize_agents(agents: list[dict[str, Any]], config: AgentConfig, context: AgentContext) -> Agent`
+- `_deserialize_log(data: dict[str, Any]) -> 'Log'`
+- `_safe_json_serialize(obj, **kwargs)`
+- Notable constants/configuration names: `CHATS_FOLDER`, `LOG_SIZE`, `CHAT_FILE_NAME`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
+- Imported dependency areas include: `agent`, `collections`, `datetime`, `helpers`, `helpers.localization`, `helpers.log`, `initialize`, `json`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `datetime.fromtimestamp.isoformat`, `datetime.fromisoformat`, `files.get_abs_path`, `_get_chat_file_path`, `files.make_dirs`, `_serialize_context`, `_safe_json_serialize`, `files.write_file`, `_convert_v080_chats`, `files.list_files`, `get_chat_folder_path`, `files.delete_dir`, `get_chat_msg_files_folder`, `agent.history.serialize`, `initialize_agent`, `_deserialize_log`, `AgentContext`, `_deserialize_agents`, `Log`, `log.set_initial_progress`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_api_chat_lifetime.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_persist_chat_log_ids.py`
+ - `tests/test_tool_action_contracts.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/plugins.py.dox.md b/helpers/plugins.py.dox.md
new file mode 100644
index 000000000..4447d8850
--- /dev/null
+++ b/helpers/plugins.py.dox.md
@@ -0,0 +1,81 @@
+# plugins.py DOX
+
+## Purpose
+
+- Own the `plugins.py` helper module.
+- This module discovers plugins, resolves plugin config/toggles, runs hooks, and tracks plugin updates.
+- 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:
+- `PluginAssetFile` (`TypedDict`)
+- `PluginMetadata` (`BaseModel`)
+- `PluginListItem` (`BaseModel`)
+- `PluginUpdateInfo` (`BaseModel`)
+- Top-level functions:
+- `register_watchdogs()`
+- `after_plugin_change(plugin_names: list[str] | None=..., python_change: bool=...)`
+- `refresh_plugin_modules(plugin_names: list[str] | None=...)`
+- `clear_plugin_cache(plugin_names: list[str] | None=...)`
+- `get_plugin_roots(plugin_name: str=...) -> List[str]`: Plugin root directories, ordered by priority (user first).
+- `get_plugins_list()`
+- `get_enhanced_plugins_list(custom: bool=..., builtin: bool=..., plugin_names: list[str] | None=...) -> List[PluginListItem]`: Discover plugins by directory convention. First root wins on ID conflict.
+- `get_custom_plugins_updates(plugin_names: list[str] | None=...) -> List[PluginUpdateInfo]`
+- `get_plugin_meta(plugin_name: str)`
+- `find_plugin_dir(plugin_name: str)`
+- `uninstall_plugin(plugin_name)`
+- `delete_plugin(plugin_name: str)`
+- `get_plugin_paths(*subpaths) -> List[str]`
+- `get_enabled_plugin_paths(agent: Agent | None, *subpaths) -> List[str]`
+- `get_enabled_plugins(agent: Agent | None)`
+- `determined_toggle_from_paths(default: bool, paths: Iterator[str])`
+- `get_toggle_state(plugin_name: str) -> ToggleState`
+- `toggle_plugin(plugin_name: str, enabled: bool, project_name: str=..., agent_profile: str=..., clear_overrides: bool=...)`
+- `get_plugin_config(plugin_name: str, agent: Agent | None=..., project_name: str | None=..., agent_profile: str | None=...)`
+- `get_default_plugin_config(plugin_name: str)`
+- `save_plugin_config(plugin_name: str, project_name: str, agent_profile: str, settings: dict)`
+- `find_plugin_asset(plugin_name: str, *subpaths, project_name=..., agent_profile=...)`
+- `find_plugin_assets(*subpaths, plugin_name: str=..., project_name: str=..., agent_profile: str=..., only_first: bool=...) -> list[PluginAssetFile]`
+- `determine_plugin_asset_path(plugin_name: str, project_name: str, agent_profile: str, *subpaths)`
+- `send_frontend_reload_notification(plugin_names: list[str] | None=...)`: If the plugin changed has webui extensions, notify frontend to reload the page
+- `call_plugin_hook(plugin_name: str, hook_name: str, default: Any=..., *args, **kwargs)`
+- `_apply_defaults_from_env(plugin_name: str, config: dict[str, Any])`
+- Notable constants/configuration names: `_META_TARGET_RE`, `META_FILE_NAME`, `CONFIG_FILE_NAME`, `CONFIG_DEFAULT_FILE_NAME`, `DISABLED_FILE_NAME`, `ENABLED_FILE_NAME`, `TOGGLE_FILE_PATTERN`, `HOOKS_SCRIPT`, `HOOKS_CACHE_AREA`, `PLUGINS_LIST_CACHE_AREA`, `ENABLED_PLUGINS_LIST_CACHE_AREA`, `ENABLED_PLUGINS_PATHS_CACHE_AREA`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `__future__`, `asyncio`, `glob`, `helpers`, `helpers.defer`, `helpers.watchdog`, `json`, `pathlib`, `pydantic`, `re`, `regex`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `re.compile`, `Field`, `watchdog.add_watchdog`, `clear_plugin_cache`, `send_frontend_reload_notification`, `DeferredTask.start_task`, `get_plugin_roots`, `result.sort`, `cache.add`, `get_enhanced_plugins_list`, `find_plugin_dir`, `files.get_abs_path`, `files.exists`, `call_plugin_hook`, `delete_plugin`, `files.delete_dir`, `after_plugin_change`, `get_enabled_plugins`, `get_plugins_list`, `get_plugin_meta`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/print_catch.py.dox.md b/helpers/print_catch.py.dox.md
new file mode 100644
index 000000000..16c630d70
--- /dev/null
+++ b/helpers/print_catch.py.dox.md
@@ -0,0 +1,40 @@
+# print_catch.py DOX
+
+## Purpose
+
+- Own the `print_catch.py` helper module.
+- This module captures printed output from async callables.
+- Keep this file-level DOX profile synchronized with `print_catch.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `print_catch.py` owns the runtime implementation.
+- `print_catch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `capture_prints_async(func: Callable[..., Awaitable[Any]], *args, **kwargs) -> Tuple[Awaitable[Any], Callable[[], str]]`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `asyncio`, `io`, `sys`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `io.StringIO`, `captured_output.getvalue`, `wrapped_func`, `func`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/print_style.py.dox.md b/helpers/print_style.py.dox.md
new file mode 100644
index 000000000..193a9bb26
--- /dev/null
+++ b/helpers/print_style.py.dox.md
@@ -0,0 +1,54 @@
+# print_style.py DOX
+
+## Purpose
+
+- Own the `print_style.py` helper module.
+- This module formats console/debug output consistently.
+- Keep this file-level DOX profile synchronized with `print_style.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `print_style.py` owns the runtime implementation.
+- `print_style.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `PrintStyle` (no explicit base class)
+ - `get(self, *args, sep=..., **kwargs)`
+ - `print(self, *args, sep=..., end=..., flush=...)`
+ - `stream(self, *args, sep=..., flush=...)`
+ - `is_last_line_empty(self)`
+ - `standard(*args, sep=..., end=..., flush=...)`
+ - `hint(*args, sep=..., end=..., flush=...)`
+ - `info(*args, sep=..., end=..., flush=...)`
+ - `success(*args, sep=..., end=..., flush=...)`
+- Top-level functions:
+- `_get_runtime()`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, WebSocket state, secret handling.
+- Imported dependency areas include: `atexit`, `collections.abc`, `datetime`, `html`, `os`, `strings`, `sys`, `webcolors`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `atexit.register`, `self._get_rgb_color_code`, `join`, `html.escape.replace`, `sep.join`, `self._format_args`, `sanitize_string`, `self._add_padding_if_needed`, `end.endswith`, `self._log_html`, `sys.stdin.readlines`, `PrintStyle._prefixed_args`, `files.get_abs_path`, `os.makedirs`, `datetime.now.strftime`, `os.path.join`, `f.write`, `self.secrets_mgr.mask_values`, `self._get_styled_text`, `self._get_html_styled_text`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_print_style.py`
+ - `tests/test_tool_action_contracts.py`
+ - `tests/test_ws_manager.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/process.py.dox.md b/helpers/process.py.dox.md
new file mode 100644
index 000000000..217a7b3aa
--- /dev/null
+++ b/helpers/process.py.dox.md
@@ -0,0 +1,54 @@
+# process.py DOX
+
+## Purpose
+
+- Own the `process.py` helper module.
+- This module manages process reload, restart, exit, and server references.
+- Keep this file-level DOX profile synchronized with `process.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `process.py` owns the runtime implementation.
+- `process.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `set_server(server)`
+- `get_server(server)`
+- `stop_server()`
+- `reload()`
+- `restart_process()`
+- `exit_process()`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: subprocess/runtime control.
+- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `sys`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `stop_server`, `runtime.is_dockerized`, `PrintStyle.standard`, `os.execv`, `sys.exit`, `_server.shutdown`, `exit_process`, `restart_process`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_api_chat_lifetime.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_docker_release_plan.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_git_version_label.py`
+ - `tests/test_image_get_security.py`
+ - `tests/test_model_config_project_presets.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/projects.py.dox.md b/helpers/projects.py.dox.md
new file mode 100644
index 000000000..08b674859
--- /dev/null
+++ b/helpers/projects.py.dox.md
@@ -0,0 +1,85 @@
+# projects.py DOX
+
+## Purpose
+
+- Own the `projects.py` helper module.
+- This module owns project metadata, workspace creation, Git status, and project-scoped settings.
+- 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:
+- `FileStructureInjectionSettings` (`TypedDict`)
+- `SubAgentSettings` (`TypedDict`)
+- `BasicProjectData` (`TypedDict`)
+- `GitStatusData` (`TypedDict`)
+- `EditProjectData` (`BasicProjectData`)
+- Top-level functions:
+- `get_projects_parent_folder()`
+- `get_project_folder(name: str)`
+- `get_project_meta(name: str, *sub_dirs)`
+- `delete_project(name: str)`
+- `create_project(name: str, data: BasicProjectData)`
+- `clone_git_project(name: str, git_url: str, git_token: str, data: BasicProjectData)`: Clone a git repository as a new A0 project. Token is used only for cloning via http header.
+- `load_project_header(name: str)`
+- `_default_file_structure_settings()`
+- `_normalizeBasicData(data: BasicProjectData) -> BasicProjectData`
+- `_normalizeEditData(data: EditProjectData) -> EditProjectData`
+- `_edit_data_to_basic_data(data: EditProjectData)`
+- `_basic_data_to_edit_data(data: BasicProjectData) -> EditProjectData`
+- `update_project(name: str, data: EditProjectData)`
+- `load_basic_project_data(name: str) -> BasicProjectData`
+- `load_edit_project_data(name: str) -> EditProjectData`
+- `save_project_header(name: str, data: BasicProjectData)`
+- `load_project_llm_data(name: str) -> dict`
+- `save_project_llm_settings(name: str, llm_data: object)`
+- `get_active_projects_list()`
+- `_get_projects_list(parent_dir)`
+- `activate_project(context_id: str, name: str, mark_dirty: bool=...)`
+- `deactivate_project(context_id: str, mark_dirty: bool=...)`
+- `reactivate_project_in_chats(name: str)`
+- `deactivate_project_in_chats(name: str)`
+- `build_system_prompt_vars(name: str)`
+- `get_additional_instructions_files(name: str)`
+- `get_project_instruction_files(name: str, include_agents_md: bool=...) -> list[tuple[str, str]]`
+- `get_project_agents_md_instruction_file(name: str) -> tuple[str, str] | None`
+- `_format_project_instruction_files(instruction_files: list[tuple[str, str]]) -> str`
+- `_normalize_include_agents_md(value: object) -> bool`
+- Notable constants/configuration names: `PROJECTS_PARENT_DIR`, `PROJECT_META_DIR`, `PROJECT_INSTRUCTIONS_DIR`, `PROJECT_KNOWLEDGE_DIR`, `PROJECT_HEADER_FILE`, `PROJECT_AGENTS_MD_FILES`, `CONTEXT_DATA_KEY_PROJECT`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `files.get_abs_path`, `files.delete_dir`, `deactivate_project_in_chats`, `files.create_dir_safe`, `create_project_meta_folders`, `_normalizeBasicData`, `save_project_header`, `save_project_llm_settings`, `files.basename`, `dirty_json.parse`, `FileStructureInjectionSettings`, `cast`, `_normalizeEditData`, `load_edit_project_data`, `_edit_data_to_basic_data`, `save_project_variables`, `save_project_secrets`, `save_project_subagents`, `reactivate_project_in_chats`, `load_basic_project_data`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/providers.py.dox.md b/helpers/providers.py.dox.md
new file mode 100644
index 000000000..083ccecfc
--- /dev/null
+++ b/helpers/providers.py.dox.md
@@ -0,0 +1,61 @@
+# providers.py DOX
+
+## Purpose
+
+- Own the `providers.py` helper module.
+- This module loads model provider configuration and provider metadata.
+- Keep this file-level DOX profile synchronized with `providers.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `providers.py` owns the runtime implementation.
+- `providers.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `FieldOption` (`TypedDict`)
+- `ProviderManager` (no explicit base class)
+ - `get_instance(cls)`
+ - `reload(cls)`
+ - `get_providers(self, provider_type: ModelType) -> List[FieldOption]`
+ - `get_raw_providers(self, provider_type: ModelType) -> List[Dict[str, str]]`
+ - `get_provider_config(self, provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]`
+- Top-level functions:
+- `get_providers(provider_type: ModelType) -> List[FieldOption]`: Convenience function to get providers of a specific type.
+- `get_raw_providers(provider_type: ModelType) -> List[Dict[str, str]]`: Return full metadata for providers of a given type.
+- `get_provider_config(provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]`: Return metadata for a single provider (None if not found).
+- `reload_providers()`: Re-merge base + plugin provider configs. Call after plugin changes.
+- Notable constants/configuration names: `PROVIDER_MANAGER_CACHE_AREA`, `PROVIDER_MANAGER_CACHE_KEY`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence.
+- Imported dependency areas include: `helpers`, `typing`, `yaml`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `ProviderManager.get_instance.get_providers`, `ProviderManager.get_instance.get_raw_providers`, `ProviderManager.get_instance.get_provider_config`, `ProviderManager.reload`, `cache.remove`, `cls.get_instance`, `inst._load_providers`, `files.get_abs_path`, `self._normalise_yaml`, `get_enabled_plugin_paths`, `provider_id.lower`, `self.get_raw_providers`, `cls`, `cache.add`, `self._load_providers`, `self._load_yaml`, `items.sort`, `ProviderManager.get_instance`, `lower`, `yaml.safe_load`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_fastmcp_openapi_security.py`
+ - `tests/test_model_config_api_keys.py`
+ - `tests/test_oauth_codex.py`
+ - `tests/test_oauth_gemini_api.py`
+ - `tests/test_oauth_github_copilot.py`
+ - `tests/test_oauth_providers.py`
+ - `tests/test_oauth_xai_grok.py`
+ - `tests/test_onboarding_static.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/rate_limiter.py.dox.md b/helpers/rate_limiter.py.dox.md
new file mode 100644
index 000000000..22572ec2b
--- /dev/null
+++ b/helpers/rate_limiter.py.dox.md
@@ -0,0 +1,45 @@
+# rate_limiter.py DOX
+
+## Purpose
+
+- Own the `rate_limiter.py` helper module.
+- This module provides simple rate-limiting primitives.
+- Keep this file-level DOX profile synchronized with `rate_limiter.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `rate_limiter.py` owns the runtime implementation.
+- `rate_limiter.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `RateLimiter` (no explicit base class)
+ - `add(self, **kwargs)`
+ - `async cleanup(self)`
+ - `async get_total(self, key: str) -> int`
+ - `async wait(self, callback: Callable[[str, str, int, int], Awaitable[bool]] | None=...)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `asyncio`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `asyncio.Lock`, `time.time`, `self.cleanup`, `asyncio.sleep`, `self.get_total`, `callback`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_stream_tool_early_stop.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/rfc.py.dox.md b/helpers/rfc.py.dox.md
new file mode 100644
index 000000000..dbe29b918
--- /dev/null
+++ b/helpers/rfc.py.dox.md
@@ -0,0 +1,48 @@
+# rfc.py DOX
+
+## Purpose
+
+- Own the `rfc.py` helper module.
+- This module implements remote function call dispatch and serialization.
+- 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:
+- `RFCInput` (`TypedDict`)
+- `RFCCall` (`TypedDict`)
+- Top-level functions:
+- `async call_rfc(url: str, password: str, module: str, function_name: str, args: list, kwargs: dict)`
+- `async handle_rfc(rfc_call: RFCCall, password: str)`
+- `async _call_function(module: str, function_name: str, *args, **kwargs)`
+- `_get_function(module: str, function_name: str)`
+- `async _send_json_data(url: str, data)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, network calls, settings/state persistence, secret handling.
+- Imported dependency areas include: `aiohttp`, `helpers`, `importlib`, `inspect`, `json`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `RFCInput`, `RFCCall`, `json.loads`, `_get_function`, `inspect.iscoroutinefunction`, `importlib.import_module`, `_send_json_data`, `crypto.verify_data`, `Exception`, `_call_function`, `func`, `aiohttp.ClientSession`, `json.dumps`, `crypto.hash_data`, `session.post`, `response.json`, `response.text`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/rfc_exchange.py.dox.md b/helpers/rfc_exchange.py.dox.md
new file mode 100644
index 000000000..c960dabd9
--- /dev/null
+++ b/helpers/rfc_exchange.py.dox.md
@@ -0,0 +1,42 @@
+# rfc_exchange.py DOX
+
+## Purpose
+
+- Own the `rfc_exchange.py` helper module.
+- This module handles privileged RFC exchange data such as root password provisioning.
+- Keep this file-level DOX profile synchronized with `rfc_exchange.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `rfc_exchange.py` owns the runtime implementation.
+- `rfc_exchange.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `async get_root_password()`
+- `_provide_root_password(public_key_pem: str)`
+- `_get_root_password()`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `helpers`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `runtime.is_dockerized`, `_get_root_password`, `crypto.encrypt_data`, `crypto._generate_private_key`, `crypto._generate_public_key`, `crypto.decrypt_data`, `dotenv.get_dotenv_value`, `runtime.call_development_function`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/rfc_files.py.dox.md b/helpers/rfc_files.py.dox.md
new file mode 100644
index 000000000..d05d75828
--- /dev/null
+++ b/helpers/rfc_files.py.dox.md
@@ -0,0 +1,70 @@
+# rfc_files.py DOX
+
+## Purpose
+
+- Own the `rfc_files.py` helper module.
+- This module exposes RFC-safe filesystem operations.
+- Keep this file-level DOX profile synchronized with `rfc_files.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `rfc_files.py` owns the runtime implementation.
+- `rfc_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `get_abs_path(*relative_paths)`: Convert relative paths to absolute paths based on the base directory.
+- `read_file_bin(relative_path: str, backup_dirs=...) -> bytes`: Read binary file content.
+- `read_file_base64(relative_path: str, backup_dirs=...) -> str`: Read file content and return as base64 string.
+- `write_file_binary(relative_path: str, content: bytes) -> bool`: Write binary content to a file.
+- `write_file_base64(relative_path: str, content: str) -> bool`: Write base64 content to a file.
+- `delete_file(relative_path: str) -> bool`: Delete a file.
+- `delete_directory(relative_path: str) -> bool`: Delete a directory recursively.
+- `list_directory(relative_path: str, include_hidden: bool=...) -> list`: List directory contents.
+- `make_directories(relative_path: str) -> bool`: Create directories recursively.
+- `path_exists(relative_path: str) -> bool`: Check if a path exists.
+- `file_exists(relative_path: str) -> bool`: Check if a file exists.
+- `folder_exists(relative_path: str) -> bool`: Check if a folder exists.
+- `get_subdirectories(relative_path: str, include: str | list[str]=..., exclude: str | list[str] | None=...) -> list[str]`: Get subdirectories in a directory.
+- `zip_directory(relative_path: str) -> str`: Create a zip archive of a directory.
+- `move_file(source_path: str, destination_path: str) -> bool`: Move a file from source to destination.
+- `read_directory_as_zip(relative_path: str) -> bytes`: Read entire directory contents as a zip file.
+- `find_file_in_dirs(file_path: str, backup_dirs: list[str]) -> str`: Find a file in the main directory or backup directories.
+- `_read_file_binary_impl(file_path: str) -> str`: Implementation function to read a file in binary mode.
+- `_write_file_binary_impl(file_path: str, b64_content: str) -> bool`: Implementation function to write binary content to a file.
+- `_delete_file_impl(file_path: str) -> bool`: Implementation function to delete a file.
+- `_delete_folder_impl(folder_path: str) -> bool`: Implementation function to delete a folder recursively.
+- `_list_folder_impl(folder_path: str, include_hidden: bool=...) -> list`: Implementation function to list folder contents.
+- `_make_dirs_impl(folder_path: str) -> bool`: Implementation function to create directories.
+- `_path_exists_impl(file_path: str) -> bool`: Implementation function to check if path exists.
+- `_file_exists_impl(file_path: str) -> bool`: Implementation function to check if file exists.
+- `_folder_exists_impl(folder_path: str) -> bool`: Implementation function to check if folder exists.
+- `_get_subdirectories_impl(folder_path: str, include: str | list[str], exclude: str | list[str] | None) -> list[str]`: Implementation function to get subdirectories.
+- `_zip_dir_impl(folder_path: str) -> str`: Implementation function to create a zip archive of a directory.
+- `_move_file_impl(source_path: str, destination_path: str) -> bool`: Implementation function to move a file.
+- `_read_directory_impl(dir_path: str) -> str`: Implementation function to zip a directory and return base64 encoded zip.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
+- Imported dependency areas include: `base64`, `fnmatch`, `helpers`, `os`, `shutil`, `tempfile`, `zipfile`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `os.path.abspath`, `os.path.join`, `find_file_in_dirs`, `runtime.call_development_function_sync`, `base64.b64decode`, `get_abs_path`, `base64.b64encode.decode`, `FileNotFoundError`, `os.path.exists`, `os.path.basename`, `os.path.isfile`, `Exception`, `os.makedirs`, `os.remove`, `os.path.isdir`, `shutil.rmtree`, `os.listdir`, `items.sort`, `tempfile.NamedTemporaryFile`, `zipfile.ZipFile`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/runtime.py.dox.md b/helpers/runtime.py.dox.md
new file mode 100644
index 000000000..e9e5ae922
--- /dev/null
+++ b/helpers/runtime.py.dox.md
@@ -0,0 +1,69 @@
+# runtime.py DOX
+
+## Purpose
+
+- Own the `runtime.py` helper module.
+- This module owns runtime identity, environment flags, and startup arguments.
+- Keep this file-level DOX profile synchronized with `runtime.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `runtime.py` owns the runtime implementation.
+- `runtime.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `initialize()`
+- `get_arg(name: str)`
+- `has_arg(name: str)`
+- `is_dockerized() -> bool`
+- `is_development() -> bool`
+- `get_local_url()`
+- `get_runtime_id() -> str`
+- `get_persistent_id() -> str`
+- `async call_development_function(func: Callable[..., Awaitable[T]], *args, **kwargs) -> T`
+- `async call_development_function(func: Callable[..., T], *args, **kwargs) -> T`
+- `async call_development_function(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T`
+- `async handle_rfc(rfc_call: rfc.RFCCall)`
+- `_get_rfc_password() -> str`
+- `_get_rfc_url() -> str`
+- `call_development_function_sync(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T`
+- `get_web_ui_port()`
+- `get_tunnel_api_port()`
+- `get_platform()`
+- `is_windows()`
+- `get_terminal_executable()`
+- Notable constants/configuration names: `T`, `R`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence, secret handling, tunnel state.
+- Imported dependency areas include: `argparse`, `asyncio`, `helpers`, `inspect`, `nest_asyncio`, `pathlib`, `queue`, `secrets`, `sys`, `threading`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `nest_asyncio.apply`, `TypeVar`, `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_known_args`, `vars`, `is_dockerized`, `dotenv.get_dotenv_value`, `is_development`, `settings.get_settings`, `url.endswith`, `queue.Queue`, `threading.Thread`, `thread.start`, `thread.join`, `thread.is_alive`, `result_queue.get_nowait`, `cast`, `is_windows`, `get_arg`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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_default_prompt_budget.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_http_auth_csrf.py`
+ - `tests/test_image_get_security.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/searxng.py.dox.md b/helpers/searxng.py.dox.md
new file mode 100644
index 000000000..889e62df1
--- /dev/null
+++ b/helpers/searxng.py.dox.md
@@ -0,0 +1,43 @@
+# searxng.py DOX
+
+## Purpose
+
+- Own the `searxng.py` helper module.
+- This module queries SearXNG search.
+- Keep this file-level DOX profile synchronized with `searxng.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `searxng.py` owns the runtime implementation.
+- `searxng.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `async search(query: str)`
+- `async _search(query: str)`
+- Notable constants/configuration names: `URL`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: network calls, settings/state persistence.
+- Imported dependency areas include: `aiohttp`, `helpers`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `runtime.call_development_function`, `aiohttp.ClientSession`, `session.post`, `response.json`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/secrets.py.dox.md b/helpers/secrets.py.dox.md
new file mode 100644
index 000000000..2824362aa
--- /dev/null
+++ b/helpers/secrets.py.dox.md
@@ -0,0 +1,62 @@
+# secrets.py DOX
+
+## Purpose
+
+- Own the `secrets.py` helper module.
+- This module loads, aliases, masks, and streams secret values safely.
+- Keep this file-level DOX profile synchronized with `secrets.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `secrets.py` owns the runtime implementation.
+- `secrets.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `EnvLine` (no explicit base class)
+- `StreamingSecretsFilter` (no explicit base class)
+ - `process_chunk(self, chunk: str) -> str`
+ - `finalize(self) -> str`
+- `SecretsManager` (no explicit base class)
+ - `get_instance(cls, *secrets_files) -> 'SecretsManager'`
+ - `read_secrets_raw(self) -> str`
+ - `load_secrets(self) -> Dict[str, str]`
+ - `save_secrets(self, secrets_content: str)`
+ - `save_secrets_with_merge(self, submitted_content: str)`
+ - `get_keys(self) -> List[str]`
+ - `get_secrets_for_prompt(self) -> str`
+ - `create_streaming_filter(self) -> 'StreamingSecretsFilter'`
+- Top-level functions:
+- `alias_for_key(key: str, placeholder: str=...) -> str`
+- `get_secrets_manager(context: 'AgentContext|None'=...) -> SecretsManager`
+- `get_project_secrets_manager(project_name: str, merge_with_global: bool=...) -> SecretsManager`
+- `get_default_secrets_manager() -> SecretsManager`
+- Notable constants/configuration names: `ALIAS_PATTERN`, `DEFAULT_SECRETS_FILE`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling.
+- Imported dependency areas include: `dataclasses`, `dotenv.parser`, `helpers`, `helpers.errors`, `helpers.extension`, `io`, `os`, `re`, `threading`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `key.upper`, `placeholder.format`, `SecretsManager.get_instance`, `self._replace_full_values`, `self._longest_suffix_prefix`, `threading.RLock`, `join`, `files.write_file`, `self._invalidate_all_caches`, `self.load_secrets`, `self.read_secrets_raw`, `self.parse_env_lines`, `self._serialize_env_lines`, `StreamingSecretsFilter`, `re.sub`, `self.parse_env_content`, `parse_stream`, `AgentContext.current`, `projects.get_context_project_name`, `files.get_abs_path`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_plugin_scan_prompt.py`
+ - `tests/test_print_style.py`
+ - `tests/test_time_travel.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/security.py.dox.md b/helpers/security.py.dox.md
new file mode 100644
index 000000000..882286b52
--- /dev/null
+++ b/helpers/security.py.dox.md
@@ -0,0 +1,45 @@
+# security.py DOX
+
+## Purpose
+
+- Own the `security.py` helper module.
+- This module contains small security helpers such as filename sanitization.
+- Keep this file-level DOX profile synchronized with `security.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `security.py` owns the runtime implementation.
+- `security.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `safe_filename(filename: str) -> Optional[str]`
+- Notable constants/configuration names: `FORBIDDEN_CHARS_RE`, `WINDOWS_RESERVED`, `FILENAME_MAX_LENGTH`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion.
+- Imported dependency areas include: `pathlib`, `re`, `typing`, `unicodedata`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `re.compile`, `frozenset`, `unicodedata.normalize`, `FORBIDDEN_CHARS_RE.sub`, `filename.lstrip.rstrip`, `Path`, `join`, `stem.upper`, `filename.lstrip`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_fastmcp_openapi_security.py`
+ - `tests/test_image_get_security.py`
+ - `tests/test_ws_security.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/self_update.py.dox.md b/helpers/self_update.py.dox.md
new file mode 100644
index 000000000..b1e552539
--- /dev/null
+++ b/helpers/self_update.py.dox.md
@@ -0,0 +1,77 @@
+# self_update.py DOX
+
+## Purpose
+
+- Own the `self_update.py` helper module.
+- This module manages self-update status, scheduling, tag selection, and durable scripts.
+- Keep this file-level DOX profile synchronized with `self_update.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `self_update.py` owns the runtime implementation.
+- `self_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `PendingUpdateConfig` (`TypedDict`)
+- `UpdateStatus` (`TypedDict`)
+- `SelectorTagOption` (`TypedDict`)
+- Top-level functions:
+- `_now_iso() -> str`
+- `get_update_file_path() -> Path`
+- `get_status_file_path() -> Path`
+- `get_log_file_path() -> Path`
+- `get_durable_exe_dir() -> Path`
+- `get_durable_self_update_manager_path() -> Path`
+- `_load_yaml(path: Path) -> dict[str, Any] | None`
+- `_write_yaml(path: Path, payload: dict[str, Any]) -> None`
+- `load_pending_update() -> PendingUpdateConfig | None`
+- `load_last_status() -> UpdateStatus | None`
+- `get_log_text() -> str`
+- `get_default_backup_dir(repo_dir: str | Path | None=...) -> Path`
+- `get_repo_dir(repo_dir: str | Path | None=...) -> Path`
+- `get_repo_self_update_manager_path(repo_dir: str | Path | None=...) -> Path`
+- `_get_official_remote_url() -> str`
+- `_run_git_raw(*args) -> str`
+- `_run_git(repo_dir: str | Path, *args) -> str`
+- `_normalize_describe_to_version(describe: str) -> str`
+- `_split_describe_version(describe: str) -> tuple[str, int]`
+- `_is_latest_selector_tag(tag: str) -> bool`
+- `_get_tag_release_time_in_repo(repo_dir: str | Path, tag: str) -> str`
+- `get_repo_version_info(repo_dir: str | Path | None=...) -> dict[str, str]`
+- `_sanitize_filename(name: str, default_name: str) -> str`
+- `_slugify_version(text: str) -> str`
+- `build_default_backup_name(current_version: str, target_tag: str | None=...) -> str`
+- `_resolve_backup_path(backup_path: str, repo_dir: str | Path | None=...) -> Path`
+- `_is_excluded_self_update_branch(branch: str) -> bool`
+- `_sort_branch_names(branches: list[str]) -> list[str]`
+- `_get_remote_branch_names() -> list[str]`
+- `_get_local_origin_branch_names(repo_dir: str | Path | None=...) -> list[str]`
+- Notable constants/configuration names: `OFFICIAL_REPO_AUTHOR`, `OFFICIAL_REPO_NAME`, `BRANCH_OPTIONS`, `SUPPORTED_BRANCHES`, `BACKUP_CONFLICT_POLICIES`, `MIN_SELECTOR_VERSION`, `REMOTE_BRANCH_TAG_CACHE_TTL_SECONDS`, `REMOTE_BRANCH_LIST_CACHE_TTL_SECONDS`, `UPDATE_FILE_PATH`, `STATUS_FILE_PATH`, `LOG_FILE_PATH`, `DURABLE_EXE_DIR`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence.
+- Imported dependency areas include: `__future__`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathlib`, `re`, `subprocess`, `tempfile`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Path`, `Localization.get.now_iso`, `yaml.loads`, `path.parent.mkdir`, `path.write_text`, `_load_yaml`, `get_log_file_path`, `path.read_text`, `subprocess.run`, `completed.stdout.strip`, `re.fullmatch`, `describe.strip`, `tag.strip`, `get_repo_dir`, `_run_git`, `_normalize_describe_to_version`, `strip`, `re.sub.strip`, `Localization.get.now.strftime`, `path.resolve`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_office_document_store.py`
+ - `tests/test_self_update_tag_filter.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/serveo_tunnel.py.dox.md b/helpers/serveo_tunnel.py.dox.md
new file mode 100644
index 000000000..c209237f1
--- /dev/null
+++ b/helpers/serveo_tunnel.py.dox.md
@@ -0,0 +1,43 @@
+# serveo_tunnel.py DOX
+
+## Purpose
+
+- Own the `serveo_tunnel.py` helper module.
+- This module implements Serveo tunnel provider behavior.
+- Keep this file-level DOX profile synchronized with `serveo_tunnel.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `serveo_tunnel.py` owns the runtime implementation.
+- `serveo_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ServeoTunnelHelper` (`FlaredanticTunnelHelper`)
+ - `build_tunnel(self)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: settings/state persistence, tunnel state.
+- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `ServeoConfig`, `ServeoTunnel`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/server_startup.py.dox.md b/helpers/server_startup.py.dox.md
new file mode 100644
index 000000000..a8417341c
--- /dev/null
+++ b/helpers/server_startup.py.dox.md
@@ -0,0 +1,62 @@
+# server_startup.py DOX
+
+## Purpose
+
+- Own the `server_startup.py` helper module.
+- This module runs Uvicorn startup with health checks and retry tracking.
+- Keep this file-level DOX profile synchronized with `server_startup.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `server_startup.py` owns the runtime implementation.
+- `server_startup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `StartupConfig` (no explicit base class)
+ - `from_env(cls) -> 'StartupConfig'`
+- `StartupStageRecord` (no explicit base class)
+- `StartupMonitor` (no explicit base class)
+ - `mark(self, stage: str, detail: str | None=...) -> None`
+ - `stage(self, stage: str, detail: str | None=...) -> Iterator[None]`
+ - `lifespan(self)`
+ - `attach_server(self, server: uvicorn.Server) -> None`
+ - `start_watchdog(self) -> None`
+ - `mark_ready(self, source: str=...) -> None`
+ - `is_ready(self) -> bool`
+ - `close(self) -> None`
+- `_UvicornServerWrapper` (no explicit base class)
+ - `shutdown(self) -> None`
+- Top-level functions:
+- `_env_int(name: str, default: int, minimum: int=...) -> int`
+- `_env_float(name: str, default: float, minimum: float=...) -> float`
+- `get_health_probe_host(bind_host: str) -> str`
+- `run_uvicorn_with_retries(host: str, port: int, build_asgi_app: Callable[[StartupMonitor], object], flush_callback: Callable[[str], None], access_log: bool=..., log_level: str=..., ws: str=..., startup_config: StartupConfig | None=...) -> None`
+- `_run_server_attempt(host: str, health_host: str, port: int, startup_monitor: StartupMonitor, build_asgi_app: Callable[[StartupMonitor], object], flush_callback: Callable[[str], None], access_log: bool, log_level: str, ws: str) -> bool`
+- `wait_for_health(host: str, port: int, startup_monitor: StartupMonitor) -> None`
+- `_serve_uvicorn(server: uvicorn.Server) -> None`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, network calls, subprocess/runtime control, settings/state persistence.
+- Imported dependency areas include: `asyncio`, `collections`, `contextlib`, `dataclasses`, `faulthandler`, `helpers`, `helpers.print_style`, `os`, `sys`, `threading`, `time`, `typing`, `urllib.request`, `uvicorn`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `get_health_probe_host`, `PrintStyle.debug`, `RuntimeError`, `startup_monitor.start_watchdog`, `server.config.get_loop_factory`, `cls`, `time.monotonic`, `deque`, `threading.Event`, `threading.RLock`, `self.mark`, `threading.Thread`, `self._watchdog_thread.start`, `self._ready.is_set`, `self.snapshot`, `PrintStyle.error`, `join`, `StartupConfig.from_env`, `StartupMonitor`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/settings.py.dox.md b/helpers/settings.py.dox.md
new file mode 100644
index 000000000..ef35d05c0
--- /dev/null
+++ b/helpers/settings.py.dox.md
@@ -0,0 +1,88 @@
+# settings.py DOX
+
+## Purpose
+
+- Own the `settings.py` helper module.
+- This module defines settings models, defaults, validation, and serialization.
+- Keep this file-level DOX profile synchronized with `settings.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `settings.py` owns the runtime implementation.
+- `settings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Settings` (`TypedDict`)
+- `PartialSettings` (`Settings`)
+- `FieldOption` (`TypedDict`)
+- `SettingsField` (`TypedDict`)
+- `SettingsSection` (`TypedDict`)
+- `ModelProvider` (`ProvidersFO`)
+- `SettingsOutputAdditional` (`TypedDict`)
+- `SettingsOutput` (`TypedDict`)
+- Top-level functions:
+- `get_default_value(name: str, value: T) -> T`: Load setting value from .env with A0_SET_ prefix, falling back to default.
+- `_ensure_option_present(options: list[OptionT] | None, current_value: str | None) -> list[OptionT]`: Ensure the currently selected value exists in a dropdown options list.
+- `_is_valid_timezone(value: str) -> bool`
+- `_normalize_timezone_setting(value: Any, default: str=...) -> str`
+- `_normalize_time_format(value: Any, default: str=...) -> str`
+- `_resolve_runtime_timezone(setting_value: str, browser_timezone: str | None=...) -> str`
+- `_timezone_options() -> list[FieldOption]`
+- `convert_out(settings: Settings) -> SettingsOutput`
+- `_get_api_key_field(settings: Settings, provider: str, title: str) -> SettingsField`
+- `convert_in(settings: Settings) -> Settings`
+- `get_settings() -> Settings`
+- `reload_settings() -> Settings`
+- `set_runtime_settings_snapshot(settings: Settings) -> None`
+- `set_settings(settings: Settings, apply: bool=..., browser_timezone: str | None=...)`
+- `set_settings_delta(delta: dict, apply: bool=...)`
+- `merge_settings(original: Settings, delta: dict) -> Settings`
+- `normalize_settings(settings: Settings) -> Settings`
+- `_adjust_to_version(settings: Settings, default: Settings)`
+- `_load_sensitive_settings(settings: Settings)`
+- `_read_settings_file() -> Settings | None`
+- `_write_settings_file(settings: Settings)`
+- `_remove_sensitive_settings(settings: Settings)`
+- `_write_sensitive_settings(settings: Settings)`
+- `get_default_settings() -> Settings`
+- `_apply_timezone_setting(previous: Settings | None, browser_timezone: str | None=...) -> None`
+- `_apply_settings(previous: Settings | None, browser_timezone: str | None=...)`
+- `_env_to_dict(data: str)`
+- `_dict_to_env(data_dict)`
+- `set_root_password(password: str)`
+- `get_runtime_config(set: Settings)`
+- Notable constants/configuration names: `T`, `PASSWORD_PLACEHOLDER`, `API_KEY_PLACEHOLDER`, `TIMEZONE_AUTO`, `TIME_FORMAT_12H`, `TIME_FORMAT_24H`, `SETTINGS_FILE`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, model calls, WebSocket state, plugin state, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `base64`, `hashlib`, `helpers`, `helpers.notification`, `helpers.print_style`, `helpers.providers`, `helpers.secrets`, `json`, `models`, `os`, `pytz`, `re`, `subprocess`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `TypeVar`, `files.get_abs_path`, `dotenv.get_dotenv_value`, `opts.insert`, `str.strip`, `_is_valid_timezone`, `str.strip.lower`, `_normalize_timezone_setting`, `SettingsOutput`, `get_default_settings`, `_ensure_option_present`, `_resolve_runtime_timezone`, `get_default_secrets_manager`, `get_settings`, `normalize_settings`, `_load_sensitive_settings`, `settings.copy`, `_write_settings_file`, `reload_settings`, `set_settings`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_fasta2a_client.py`
+ - `tests/test_mcp_handler_multimodal.py`
+ - `tests/test_model_config_api_keys.py`
+ - `tests/test_model_config_project_presets.py`
+ - `tests/test_oauth_static.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/skills.py.dox.md b/helpers/skills.py.dox.md
new file mode 100644
index 000000000..dd23b4aba
--- /dev/null
+++ b/helpers/skills.py.dox.md
@@ -0,0 +1,83 @@
+# skills.py DOX
+
+## Purpose
+
+- Own the `skills.py` helper module.
+- This module discovers, parses, filters, and resolves Agent Zero skills.
+- 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:
+- `ActiveSkillEntry` (`TypedDict`)
+- `CatalogSkill` (`TypedDict`)
+- `Skill` (no explicit base class)
+- Top-level functions:
+- `get_skills_base_dir() -> Path`
+- `get_skill_roots(agent: Agent | None=...) -> List[str]`
+- `_is_hidden_path(path: Path) -> bool`
+- `discover_skill_md_files(root: Path) -> List[Path]`: Recursively discover SKILL.md files under a root directory.
+- `_coerce_list(value: Any) -> List[str]`
+- `_normalize_name(name: str) -> str`
+- `_read_text(path: Path) -> str`
+- `split_frontmatter(markdown: str) -> Tuple[Dict[str, Any], str, List[str]]`: Splits a SKILL.md into (frontmatter_dict, body_text, errors).
+- `_parse_frontmatter_fallback(frontmatter_text: str) -> Dict[str, Any]`
+- `parse_frontmatter(frontmatter_text: str) -> Tuple[Dict[str, Any], List[str]]`: Parse YAML frontmatter with PyYAML when available,
+- `skill_from_markdown(skill_md_path: Path, include_content: bool=..., validate: bool=...) -> Optional[Skill]`
+- `list_skills(agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> List[Skill]`: List skills, optionally filtered by agent scope.
+- `delete_skill(skill_path: str) -> None`: Delete a skill directory.
+- `find_skill(skill_name: str, agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> Optional[Skill]`
+- `load_skill_for_agent(skill_name: str, agent: Agent | None=...) -> str`: Load skill and format it as a complete string for agent context.
+- `_get_skill_files(skill_dir: Path) -> str`: Get file tree for skill directory.
+- `search_skills(query: str, limit: int=..., agent: Agent | None=..., include_hidden: bool=...) -> List[Skill]`
+- `validate_skill(skill: Skill) -> List[str]`
+- `validate_skill_md(skill_md_path: Path) -> List[str]`
+- `_normalize_max_active_skills(value: Any) -> int`
+- `get_max_active_skills(agent: Agent | None=..., project_name: str | None=...) -> int`
+- `normalize_skills_config(config: dict[str, Any] | None) -> dict[str, Any]`
+- `normalize_active_skills(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]`
+- `normalize_hidden_skills(raw: Any) -> list[ActiveSkillEntry]`
+- `normalize_skill_entries(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]`
+- `list_skill_catalog(project_name: str=..., agent: Agent | None=...) -> list[CatalogSkill]`
+- `get_scope_active_skills(agent: Agent | None) -> list[ActiveSkillEntry]`
+- `get_scope_hidden_skills(agent: Agent | None) -> list[ActiveSkillEntry]`
+- `get_chat_active_skills(context: Any | None) -> list[ActiveSkillEntry]`
+- `get_chat_disabled_skills(context: Any | None) -> list[ActiveSkillEntry]`
+- Notable constants/configuration names: `MAX_ACTIVE_SKILLS`, `ACTIVE_SKILLS_PLUGIN_NAME`, `AGENT_DATA_NAME_LOADED_SKILLS`, `CONTEXT_DATA_NAME_CHAT_ACTIVE_SKILLS`, `CONTEXT_DATA_NAME_CHAT_DISABLED_SKILLS`, `CONTEXT_DATA_NAME_CHAT_VISIBLE_SKILLS`, `_NAME_RE`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `os`, `pathlib`, `re`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `re.compile`, `field`, `Path`, `root.rglob`, `results.sort`, `re.sub`, `path.read_text`, `text.splitlines`, `join.strip`, `parse_frontmatter`, `frontmatter_text.splitlines`, `_parse_frontmatter_fallback`, `split_frontmatter`, `str.strip`, `_coerce_list`, `Skill`, `get_skill_roots`, `_filter_hidden_skills`, `files.get_abs_path`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/skills_cli.py.dox.md b/helpers/skills_cli.py.dox.md
new file mode 100644
index 000000000..02aa7922d
--- /dev/null
+++ b/helpers/skills_cli.py.dox.md
@@ -0,0 +1,51 @@
+# skills_cli.py DOX
+
+## Purpose
+
+- Own the `skills_cli.py` helper module.
+- This module provides command-line skill listing, search, validation, and creation helpers.
+- Keep this file-level DOX profile synchronized with `skills_cli.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `skills_cli.py` owns the runtime implementation.
+- `skills_cli.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Skill` (no explicit base class)
+- Top-level functions:
+- `get_skills_dirs() -> List[Path]`: Get all skill directories
+- `parse_skill_file(skill_path: Path) -> Optional[Skill]`: Parse a SKILL.md file and return a Skill object
+- `list_skills() -> List[Skill]`: List all available skills
+- `find_skill(name: str) -> Optional[Skill]`: Find a skill by name
+- `search_skills(query: str) -> List[Skill]`: Search skills by name, description, or tags
+- `validate_skill(skill: Skill) -> List[str]`: Validate a skill and return list of issues
+- `create_skill(name: str, description: str=..., author: str=...) -> Path`: Create a new skill from template
+- `print_skill_table(skills: List[Skill])`: Print skills in a formatted table
+- `main()`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling.
+- Imported dependency areas include: `argparse`, `dataclasses`, `datetime`, `helpers`, `os`, `pathlib`, `re`, `sys`, `typing`, `yaml`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `sys.path.insert`, `field`, `Path`, `get_skills_dirs`, `list_skills`, `query.lower`, `exists`, `custom_dir.mkdir`, `skill_dir.exists`, `skill_dir.mkdir`, `mkdir`, `skill_file.write_text`, `readme.write_text`, `argparse.ArgumentParser`, `parser.add_subparsers`, `subparsers.add_parser`, `list_parser.add_argument`, `create_parser.add_argument`, `show_parser.add_argument`, `validate_parser.add_argument`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/skills_import.py.dox.md b/helpers/skills_import.py.dox.md
new file mode 100644
index 000000000..9da611849
--- /dev/null
+++ b/helpers/skills_import.py.dox.md
@@ -0,0 +1,55 @@
+# skills_import.py DOX
+
+## Purpose
+
+- Own the `skills_import.py` helper module.
+- This module plans and imports skill bundles into user, project, or profile scopes.
+- 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:
+- `ImportPlanItem` (no explicit base class)
+- `ImportResult` (no explicit base class)
+- Top-level functions:
+- `_is_within(child: Path, parent: Path) -> bool`
+- `_derive_namespace(source: Path) -> str`
+- `_candidate_skill_roots(source_dir: Path) -> List[Path]`: Heuristics to find likely skill roots inside a repo/pack:
+- `_unzip_to_temp_dir(zip_path: Path) -> Path`: Extract a zip into a temp folder under tmp/skill_imports (inside Agent Zero base dir).
+- `build_import_plan(source: Path, dest_root: Path, namespace: Optional[str]=...) -> Tuple[List[ImportPlanItem], Path]`: Build a copy plan for importing skills from a source folder.
+- `_resolve_conflict(dest: Path, policy: ConflictPolicy) -> Tuple[Path, bool]`: Returns (final_dest_path, should_copy).
+- `get_project_skills_folder(project_name: str) -> Path`: Get the skills folder path for a project.
+- `get_agent_profile_skills_folder(profile_name: str) -> Path`
+- `get_project_agent_profile_skills_folder(project_name: str, profile_name: str) -> Path`
+- `resolve_skills_destination_root(project_name: Optional[str], agent_profile: Optional[str]) -> Path`
+- `import_skills(source_path: str, namespace: Optional[str]=..., conflict: ConflictPolicy=..., dry_run: bool=..., project_name: Optional[str]=..., agent_profile: Optional[str]=...) -> ImportResult`: Import external Skills into usr/skills/<namespace>/...
+- Notable constants/configuration names: `PROJECT_SKILLS_DIR`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state.
+- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.skills`, `os`, `pathlib`, `shutil`, `tempfile`, `time`, `typing`, `zipfile`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `strip`, `plugins.is_dir`, `Path`, `base_tmp.mkdir`, `time.strftime`, `target.mkdir`, `_candidate_skill_roots`, `Path.expanduser`, `resolve_skills_destination_root`, `dest_root.mkdir`, `build_import_plan`, `ImportResult`, `child.resolve.relative_to`, `direct.is_dir`, `discover_skill_md_files`, `plugins.iterdir`, `files.get_abs_path`, `zipfile.ZipFile`, `z.extractall`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/state_migration.py.dox.md b/helpers/state_migration.py.dox.md
new file mode 100644
index 000000000..9af4faa8c
--- /dev/null
+++ b/helpers/state_migration.py.dox.md
@@ -0,0 +1,45 @@
+# state_migration.py DOX
+
+## Purpose
+
+- Own the `state_migration.py` helper module.
+- This module moves retired state tree paths to current runtime locations.
+- Keep this file-level DOX profile synchronized with `state_migration.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `state_migration.py` owns the runtime implementation.
+- `state_migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `migrate_retired_state_tree(source: Path, destination: Path, owner: str, migrated: list[str], warnings: list[str], errors: list[str]) -> None`: Move retired plugin state into its plugin-owned state directory.
+- `_move_path(source: Path, target: Path, migrated: list[str]) -> None`
+- `_next_conflict_path(path: Path) -> Path`
+- `_remove_empty_dir(path: Path, owner: str, warnings: list[str]) -> None`
+- `_same_path(left: Path, right: Path) -> bool`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, plugin state, settings/state persistence.
+- Imported dependency areas include: `__future__`, `pathlib`, `shutil`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `_same_path`, `final_target.parent.mkdir`, `shutil.move`, `path.with_name`, `_move_path`, `source.is_dir`, `target.is_dir`, `source.rmdir`, `target.exists`, `target.is_symlink`, `_next_conflict_path`, `candidate.exists`, `candidate.is_symlink`, `path.rmdir`, `source.exists`, `source.is_symlink`, `destination.mkdir`, `_remove_empty_dir`, `source.iterdir`, `left.resolve`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/state_monitor.py.dox.md b/helpers/state_monitor.py.dox.md
new file mode 100644
index 000000000..a84115652
--- /dev/null
+++ b/helpers/state_monitor.py.dox.md
@@ -0,0 +1,59 @@
+# state_monitor.py DOX
+
+## Purpose
+
+- Own the `state_monitor.py` helper module.
+- This module tracks dirty state and connection projections for WebUI sync.
+- Keep this file-level DOX profile synchronized with `state_monitor.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `state_monitor.py` owns the runtime implementation.
+- `state_monitor.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ConnectionProjection` (no explicit base class)
+- `StateMonitor` (no explicit base class)
+ - `bind_manager(self, manager: 'WsManager', handler_id: str | None=...) -> None`
+ - `register_sid(self, namespace: str, sid: str) -> None`
+ - `unregister_sid(self, namespace: str, sid: str) -> None`
+ - `mark_dirty_all(self, reason: str | None=...) -> None`
+ - `mark_dirty_for_context(self, context_id: str, reason: str | None=...) -> None`
+ - `update_projection(self, namespace: str, sid: str, request: StateRequestV1, seq_base: int) -> None`
+ - `mark_dirty(self, namespace: str, sid: str, reason: str | None=..., wave_id: str | None=...) -> None`
+- Top-level functions:
+- `get_state_monitor() -> StateMonitor`
+- `_reset_state_monitor_for_testing() -> None`
+- Notable constants/configuration names: `_STATE_MONITOR_HOLDER`, `_STATE_MONITOR_LOCK`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion, WebSocket state, settings/state persistence, scheduler state.
+- Imported dependency areas include: `__future__`, `asyncio`, `dataclasses`, `helpers`, `helpers.print_style`, `helpers.state_snapshot`, `helpers.ws`, `helpers.ws_manager`, `os`, `threading`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `threading.RLock`, `field`, `ws_debug`, `_ws_debug_enabled`, `context_id.strip`, `loop.call_soon_threadsafe`, `self._schedule_debounce_on_loop`, `asyncio.get_running_loop`, `asyncio.current_task`, `loop.is_closed`, `self._debounce_handles.pop`, `self._push_tasks.pop`, `self._projections.pop`, `self.mark_dirty`, `self._mark_dirty_on_loop`, `runtime.is_development`, `loop.call_later`, `StateMonitor`, `ConnectionProjection`, `handle.cancel`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_model_config_api_keys.py`
+ - `tests/test_multi_tab_isolation.py`
+ - `tests/test_state_monitor.py`
+ - `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.
diff --git a/helpers/state_monitor_integration.py.dox.md b/helpers/state_monitor_integration.py.dox.md
new file mode 100644
index 000000000..15c7e3530
--- /dev/null
+++ b/helpers/state_monitor_integration.py.dox.md
@@ -0,0 +1,43 @@
+# state_monitor_integration.py DOX
+
+## Purpose
+
+- Own the `state_monitor_integration.py` helper module.
+- This module bridges dirty-state calls into the shared state monitor.
+- Keep this file-level DOX profile synchronized with `state_monitor_integration.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `state_monitor_integration.py` owns the runtime implementation.
+- `state_monitor_integration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `mark_dirty_all(reason: str | None=...) -> None`
+- `mark_dirty_for_context(context_id: str, reason: str | None=...) -> None`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `__future__`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `get_state_monitor.mark_dirty_all`, `get_state_monitor.mark_dirty_for_context`, `get_state_monitor`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_model_config_api_keys.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/state_snapshot.py.dox.md b/helpers/state_snapshot.py.dox.md
new file mode 100644
index 000000000..ac27b97c5
--- /dev/null
+++ b/helpers/state_snapshot.py.dox.md
@@ -0,0 +1,63 @@
+# state_snapshot.py DOX
+
+## Purpose
+
+- Own the `state_snapshot.py` helper module.
+- This module builds and validates typed WebUI state snapshots.
+- Keep this file-level DOX profile synchronized with `state_snapshot.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `state_snapshot.py` owns the runtime implementation.
+- `state_snapshot.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SnapshotV1` (`TypedDict`)
+- `StateRequestV1` (no explicit base class)
+- `StateRequestValidationError` (`ValueError`)
+- Top-level functions:
+- `_annotation_to_isinstance_types(annotation: Any) -> tuple[type, ...]`: Convert type annotation to tuple suitable for isinstance().
+- `_build_schema_from_typeddict(td: type) -> dict[str, tuple[type, ...]]`: Extract field names and isinstance-compatible types from TypedDict.
+- `validate_snapshot_schema_v1(snapshot: Mapping[str, Any]) -> None`
+- `_coerce_non_negative_int(value: Any, default: int=...) -> int`
+- `_get_agent_profile_labels() -> dict[str, str]`
+- `_apply_agent_profile_metadata(context_data: dict[str, Any], ctx: AgentContext, labels: dict[str, str]) -> None`
+- `parse_state_request_payload(payload: Mapping[str, Any]) -> StateRequestV1`
+- `_coerce_state_request_inputs(context: Any, log_from: Any, notifications_from: Any, timezone: Any) -> StateRequestV1`
+- `advance_state_request_after_snapshot(request: StateRequestV1, snapshot: Mapping[str, Any]) -> StateRequestV1`
+- `async build_snapshot_from_request(request: StateRequestV1) -> SnapshotV1`: Build a poll-shaped snapshot for both /poll and state_push.
+- `_notify_timezone_changed(previous_timezone: str, current_timezone: str) -> None`
+- `async build_snapshot(context: str | None, log_from: int, notifications_from: int, timezone: str | None) -> SnapshotV1`
+- Notable constants/configuration names: `_SNAPSHOT_V1_SCHEMA`, `SNAPSHOT_SCHEMA_V1_KEYS`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: plugin state, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `__future__`, `agent`, `dataclasses`, `helpers.dotenv`, `helpers.localization`, `helpers.task_scheduler`, `pytz`, `types`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `dataclass`, `_build_schema_from_typeddict`, `get_origin`, `timezone.strip`, `StateRequestV1`, `localization.get_timezone`, `localization.set_timezone`, `ctxid.strip`, `_coerce_non_negative_int`, `AgentContext.get_notification_manager`, `notification_manager.output`, `_get_agent_profile_labels`, `ctxs.sort`, `tasks.sort`, `validate_snapshot_schema_v1`, `_coerce_state_request_inputs`, `super.__init__`, `get_args`, `_annotation_to_isinstance_types`, `TypeError`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_multi_tab_isolation.py`
+ - `tests/test_snapshot_parity.py`
+ - `tests/test_snapshot_schema_v1.py`
+ - `tests/test_state_monitor.py`
+ - `tests/test_state_sync_handler.py`
+ - `tests/test_state_sync_welcome_screen.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/strings.py.dox.md b/helpers/strings.py.dox.md
new file mode 100644
index 000000000..ccc055650
--- /dev/null
+++ b/helpers/strings.py.dox.md
@@ -0,0 +1,49 @@
+# strings.py DOX
+
+## Purpose
+
+- Own the `strings.py` helper module.
+- This module sanitizes, formats, truncates, and expands framework string content.
+- Keep this file-level DOX profile synchronized with `strings.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `strings.py` owns the runtime implementation.
+- `strings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `sanitize_string(s: str, encoding: str=...) -> str`
+- `calculate_valid_match_lengths(first: bytes | str, second: bytes | str, deviation_threshold: int=..., deviation_reset: int=..., ignore_patterns: list[bytes | str]=..., debug: bool=...) -> tuple[int, int]`
+- `format_key(key: str) -> str`: Format a key string to be more readable.
+- `dict_to_text(d: dict) -> str`
+- `truncate_text(text: str, length: int, at_end: bool=..., replacement: str=...) -> str`
+- `truncate_text_by_ratio(text: str, threshold: int, replacement: str=..., ratio: float=...) -> str`: Truncate text with replacement at a specified ratio position.
+- `replace_file_includes(text: str, placeholder_pattern: str=...) -> str`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem deletion.
+- Imported dependency areas include: `helpers`, `re`, `sys`, `time`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `s.encode.decode`, `join`, `join.rstrip`, `re.sub`, `skip_ignored_patterns`, `match.group`, `s.encode`, `sys.stdout.write`, `sys.stdout.flush`, `time.sleep`, `c.isupper`, `result.islower`, `word.capitalize`, `files.fix_dev_path`, `files.read_file`, `re.match`, `formatted.split`, `c.isalnum`, `format_key`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_model_search.py`
+ - `tests/test_whatsapp_number_utils.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/subagents.py.dox.md b/helpers/subagents.py.dox.md
new file mode 100644
index 000000000..9b954ff80
--- /dev/null
+++ b/helpers/subagents.py.dox.md
@@ -0,0 +1,61 @@
+# subagents.py DOX
+
+## Purpose
+
+- Own the `subagents.py` helper module.
+- This module discovers, merges, loads, and saves agent profile definitions.
+- 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:
+- `SubAgentListItem` (`BaseModel`)
+ - `post_validator(self)`
+- `SubAgent` (`SubAgentListItem`)
+- Top-level functions:
+- `get_agents_list(project_name: str | None=...) -> list[SubAgentListItem]`
+- `get_agents_dict(project_name: str | None=...) -> dict[str, SubAgentListItem]`
+- `_get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentListItem]`
+- `load_agent_data(name: str, project_name: str | None=...) -> SubAgent`
+- `save_agent_data(name: str, subagent: SubAgent) -> None`
+- `delete_agent_data(name: str) -> None`
+- `_load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None`
+- `_merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None`
+- `_merge_agent_list_items(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem`
+- `get_agents_roots() -> list[str]`
+- `get_all_agents_list() -> list[dict[str, str]]`
+- `_merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]`
+- `get_default_promp_file_names() -> list[str]`
+- `get_available_agents_dict(project_name: str | None) -> dict[str, SubAgentListItem]`
+- `get_paths(agent: 'Agent|None', *subpaths, must_exist_completely: bool=..., include_project: bool=..., include_user: bool=..., include_default: bool=..., include_plugins: bool=..., default_root: str=...) -> list[str]`: Returns list of file paths for the given agent and subpaths, searched in order of priority:
+- Notable constants/configuration names: `GLOBAL_DIR`, `USER_DIR`, `DEFAULT_AGENTS_DIR`, `USER_AGENTS_DIR`, `PATHS_CACHE_AREA`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence.
+- Imported dependency areas include: `helpers`, `json`, `os`, `pydantic`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `cache.toggle_area`, `model_validator`, `_get_agents_list_from_dir`, `plugins.get_enabled_plugin_paths`, `_merge_agent_dicts`, `files.get_subdirectories`, `_load_agent_data_from_dir`, `_merge_agent`, `files.write_file`, `files.delete_dir`, `SubAgent`, `SubAgentListItem`, `files.find_existing_paths_by_pattern`, `get_agents_roots`, `files.list_files`, `get_agents_dict`, `cache.determine_cache_key`, `cache.add`, `projects.get_project_meta`, `FileNotFoundError`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_skills_runtime.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/system_packages.py.dox.md b/helpers/system_packages.py.dox.md
new file mode 100644
index 000000000..f1078d3b7
--- /dev/null
+++ b/helpers/system_packages.py.dox.md
@@ -0,0 +1,44 @@
+# system_packages.py DOX
+
+## Purpose
+
+- Own the `system_packages.py` helper module.
+- This module runs apt operations with retry behavior.
+- Keep this file-level DOX profile synchronized with `system_packages.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `system_packages.py` owns the runtime implementation.
+- `system_packages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `run_apt_with_retries(runner: Callable[[], subprocess.CompletedProcess[str]], lock_timeout_seconds: int=..., retry_seconds: int=...) -> subprocess.CompletedProcess[str]`: Run an apt/dpkg command, serializing in-process callers and waiting out apt locks.
+- `is_apt_lock_error(result: subprocess.CompletedProcess[str]) -> bool`
+- Notable constants/configuration names: `APT_LOCK_TIMEOUT_SECONDS`, `APT_LOCK_RETRY_SECONDS`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: subprocess/runtime control.
+- Imported dependency areas include: `__future__`, `subprocess`, `threading`, `time`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `threading.RLock`, `lower`, `time.monotonic`, `runner`, `time.sleep`, `is_apt_lock_error`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/tailscale_tunnel.py.dox.md b/helpers/tailscale_tunnel.py.dox.md
new file mode 100644
index 000000000..90afd506e
--- /dev/null
+++ b/helpers/tailscale_tunnel.py.dox.md
@@ -0,0 +1,64 @@
+# tailscale_tunnel.py DOX
+
+## Purpose
+
+- Own the `tailscale_tunnel.py` helper module.
+- This module implements Tailscale tunnel install and provider lifecycle behavior.
+- Keep this file-level DOX profile synchronized with `tailscale_tunnel.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `tailscale_tunnel.py` owns the runtime implementation.
+- `tailscale_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `TailscaleTunnel` (`CliTunnelHelper`)
+ - `stop(self)`
+- Top-level functions:
+- `tailscale_arch()`
+- `tailscale_archive_url()`
+- `install_tailscale(notify=...)`
+- `resolve_tailscaled_binary(binary_path)`
+- `notify_info(notify, message, data=...)`
+- `tailscale_socket_args(socket_path=...)`
+- `tailscale_command(binary_path, args, socket_path=...)`
+- `tailscale_status(binary_path, socket_path=...)`
+- `tailscale_funnel_help(binary_path, socket_path=...)`
+- `compact_output(lines)`
+- `tailscale_daemon_hint(output)`
+- `tailscale_daemon_ready(binary_path, socket_path)`
+- `read_recent_tailscaled_log()`
+- `start_tailscaled(binary_path, notify=...)`
+- `stop_managed_tailscaled()`
+- `tailscale_up_failure_message(output, timed_out=...)`
+- `run_tailscale_up(binary_path, notify=..., timeout=..., socket_path=...)`
+- `ensure_tailscale_funnel_command(binary_path, socket_path=...)`
+- `ensure_tailscale_ready(binary_path, notify=...)`
+- Notable constants/configuration names: `TAILSCALE_URL_RE`, `TAILSCALE_LOGIN_URL_RE`, `TAILSCALE_STABLE_PACKAGES_URL`, `TAILSCALE_UP_TIMEOUT`, `TAILSCALE_FUNNEL_TIMEOUT`, `TAILSCALE_FUNNEL_HTTPS_PORT`, `TAILSCALE_DAEMON_START_TIMEOUT`, `TAILSCALE_RUNTIME_DIR`, `TAILSCALE_STATE_DIR`, `TAILSCALE_SOCKET_PATH`, `TAILSCALE_DAEMON_LOG_PATH`, `TAILSCALE_DAEMON_PID_PATH`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, tunnel state.
+- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.cli_tunnel`, `json`, `os`, `pathlib`, `queue`, `re`, `shutil`, `subprocess`, `threading`, `time`, `urllib.parse`, `urllib.request`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `re.compile`, `Path`, `files.get_abs_path`, `cli_tunnel.platform_parts`, `tailscale_arch`, `pattern.search`, `urllib.parse.urljoin`, `shutil.which`, `tailscale_archive_url`, `cli_tunnel.download_file`, `Path.with_name`, `sibling.exists`, `callable`, `subprocess.run`, `join`, `output.lower`, `tailscale_status`, `compact_output`, `resolve_tailscaled_binary`, `tailscale_daemon_ready`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/task_scheduler.py.dox.md b/helpers/task_scheduler.py.dox.md
new file mode 100644
index 000000000..7292b4faf
--- /dev/null
+++ b/helpers/task_scheduler.py.dox.md
@@ -0,0 +1,112 @@
+# task_scheduler.py DOX
+
+## Purpose
+
+- Own the `task_scheduler.py` helper module.
+- This module models, serializes, schedules, runs, and persists scheduled tasks.
+- Keep this file-level DOX profile synchronized with `task_scheduler.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `task_scheduler.py` owns the runtime implementation.
+- `task_scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `TaskState` (`str`, `Enum`)
+- `TaskType` (`str`, `Enum`)
+- `TaskSchedule` (`BaseModel`)
+ - `to_crontab(self) -> str`
+- `TaskPlan` (`BaseModel`)
+ - `create(cls, todo: list[datetime] | None=..., in_progress: datetime | None=..., done: list[datetime] | None=...)`
+ - `add_todo(self, launch_time: datetime)`
+ - `set_in_progress(self, launch_time: datetime)`
+ - `set_done(self, launch_time: datetime)`
+ - `get_next_launch_time(self) -> datetime | None`
+ - `should_launch(self) -> datetime | None`
+- `BaseTask` (`BaseModel`)
+ - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., **kwargs)`
+ - `check_schedule(self, frequency_seconds: float=...) -> bool`
+ - `get_next_run(self) -> datetime | None`
+ - `is_dedicated(self) -> bool`
+ - `get_next_run_minutes(self) -> int | None`
+ - `async on_run(self)`
+ - `async on_finish(self)`
+ - `async on_error(self, error: str)`
+- `AdHocTask` (`BaseTask`)
+ - `create(cls, name: str, system_prompt: str, prompt: str, token: str, attachments: list[str] | None=..., context_id: str | None=..., project_name: str | None=..., project_color: str | None=...)`
+ - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., token: str | None=..., **kwargs)`
+- `ScheduledTask` (`BaseTask`)
+ - `create(cls, name: str, system_prompt: str, prompt: str, schedule: TaskSchedule, attachments: list[str] | None=..., context_id: str | None=..., timezone: str | None=..., project_name: str | None=..., project_color: str | None=...)`
+ - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., schedule: TaskSchedule | None=..., **kwargs)`
+ - `check_schedule(self, frequency_seconds: float=...) -> bool`
+ - `get_next_run(self) -> datetime | None`
+- `PlannedTask` (`BaseTask`)
+ - `create(cls, name: str, system_prompt: str, prompt: str, plan: TaskPlan, attachments: list[str] | None=..., context_id: str | None=..., project_name: str | None=..., project_color: str | None=...)`
+ - `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., plan: TaskPlan | None=..., **kwargs)`
+ - `check_schedule(self, frequency_seconds: float=...) -> bool`
+ - `get_next_run(self) -> datetime | None`
+ - `async on_run(self)`
+ - `async on_finish(self)`
+ - `async on_success(self, result: str)`
+ - `async on_error(self, error: str)`
+- `SchedulerTaskList` (`BaseModel`)
+ - `get(cls) -> 'SchedulerTaskList'`
+ - `async reload(self) -> 'SchedulerTaskList'`
+ - `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'SchedulerTaskList'`
+ - `async save(self) -> 'SchedulerTaskList'`
+ - `async update_task_by_uuid(self, task_uuid: str, updater_func: Callable[[Union[ScheduledTask, AdHocTask, PlannedTask]], None], verify_func: Callable[[Union[ScheduledTask, AdHocTask, PlannedTask]], bool]=...) -> Union[ScheduledTask, AdHocTask, PlannedTask] | None`
+ - `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
+ - `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
+ - `async get_due_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
+- `TaskScheduler` (no explicit base class)
+ - `get(cls) -> 'TaskScheduler'`
+ - `cancel_running_task(self, task_uuid: str, terminate_thread: bool=...) -> bool`
+ - `cancel_tasks_by_context(self, context_id: str, terminate_thread: bool=...) -> bool`
+ - `async reload(self)`
+ - `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
+ - `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
+ - `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'TaskScheduler'`
+ - `async remove_task_by_uuid(self, task_uuid: str) -> 'TaskScheduler'`
+- Top-level functions:
+- `normalize_schedule_timezone(timezone_name: str | None) -> str`
+- `_now() -> datetime`
+- `_localize_task_datetime(dt: datetime) -> datetime`
+- `serialize_datetime(dt: Optional[datetime]) -> Optional[str]`: Serialize a datetime object to ISO format string in the user's timezone.
+- `parse_datetime(dt_str: Optional[str]) -> Optional[datetime]`: Parse ISO format datetime string with timezone awareness.
+- `serialize_task_schedule(schedule: TaskSchedule) -> Dict[str, str]`: Convert TaskSchedule to a standardized dictionary format.
+- `parse_task_schedule(schedule_data: Dict[str, str]) -> TaskSchedule`: Parse dictionary into TaskSchedule with validation.
+- `serialize_task_plan(plan: TaskPlan) -> Dict[str, Any]`: Convert TaskPlan to a standardized dictionary format.
+- `parse_task_plan(plan_data: Dict[str, Any]) -> TaskPlan`: Parse dictionary into TaskPlan with validation.
+- `serialize_task(task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> Dict[str, Any]`: Standardized serialization for task objects with proper handling of all complex types.
+- `serialize_tasks(tasks: list[Union[ScheduledTask, AdHocTask, PlannedTask]]) -> list[Dict[str, Any]]`: Serialize a list of tasks to a list of dictionaries.
+- `deserialize_task(task_data: Dict[str, Any], task_class: Optional[Type[T]]=...) -> T`: Deserialize dictionary into appropriate task object with validation.
+- Notable constants/configuration names: `SCHEDULER_FOLDER`, `LOCAL_TIMEZONE_ALIASES`, `T`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `agent`, `asyncio`, `crontab`, `datetime`, `enum`, `helpers`, `helpers.defer`, `helpers.files`, `helpers.localization`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `nest_asyncio`, `os`, `os.path`, `pydantic`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `nest_asyncio.apply`, `TypeVar`, `str.strip`, `callable`, `datetime.now`, `tzinfo.localize`, `Field`, `PrivateAttr`, `Localization.get.serialize_datetime`, `normalize_schedule_timezone`, `Localization.get.get_timezone`, `pytz.timezone`, `now`, `localize`, `cls`, `_localize_task_datetime`, `self.todo.remove`, `self.get_next_launch_time`, `super.__init__`, `threading.RLock`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_task_scheduler_timezone.py`
+ - `tests/test_timezone_regressions.py`
+ - `tests/test_tool_action_contracts.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/timed_input.py.dox.md b/helpers/timed_input.py.dox.md
new file mode 100644
index 000000000..5bcc3ce95
--- /dev/null
+++ b/helpers/timed_input.py.dox.md
@@ -0,0 +1,40 @@
+# timed_input.py DOX
+
+## Purpose
+
+- Own the `timed_input.py` helper module.
+- This module reads terminal input with timeout handling.
+- Keep this file-level DOX profile synchronized with `timed_input.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `timed_input.py` owns the runtime implementation.
+- `timed_input.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `timeout_input(prompt, timeout=...)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `inputimeout`, `sys`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `inputimeout`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/tokens.py.dox.md b/helpers/tokens.py.dox.md
new file mode 100644
index 000000000..c42637a8e
--- /dev/null
+++ b/helpers/tokens.py.dox.md
@@ -0,0 +1,54 @@
+# tokens.py DOX
+
+## Purpose
+
+- Own the `tokens.py` helper module.
+- This module counts and approximates tokens and trims text to budgets.
+- Keep this file-level DOX profile synchronized with `tokens.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `tokens.py` owns the runtime implementation.
+- `tokens.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `count_tokens(text: str, encoding_name=...) -> int`
+- `approximate_tokens(text: str) -> int`
+- `sanitize_embedded_image_data_urls(text: str) -> str`
+- `approximate_prompt_tokens(text: str) -> int`
+- `trim_to_tokens(text: str, max_tokens: int, direction: Literal['start', 'end'], ellipsis: str=...) -> str`
+- Notable constants/configuration names: `APPROX_BUFFER`, `TRIM_BUFFER`, `EMBEDDED_IMAGE_DATA_PLACEHOLDER`, `_EMBEDDED_IMAGE_DATA_URL_PATTERN`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: secret handling.
+- Imported dependency areas include: `re`, `tiktoken`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `re.compile`, `tiktoken.get_encoding`, `encoding.encode`, `_EMBEDDED_IMAGE_DATA_URL_PATTERN.sub`, `approximate_tokens`, `count_tokens`, `sanitize_embedded_image_data_urls`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_chat_compaction.py`
+ - `tests/test_default_prompt_budget.py`
+ - `tests/test_history_compression_wait.py`
+ - `tests/test_mcp_handler_multimodal.py`
+ - `tests/test_oauth_codex.py`
+ - `tests/test_oauth_gemini_api.py`
+ - `tests/test_oauth_xai_grok.py`
+ - `tests/test_ws_security.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/tool.py.dox.md b/helpers/tool.py.dox.md
new file mode 100644
index 000000000..5577d7fbc
--- /dev/null
+++ b/helpers/tool.py.dox.md
@@ -0,0 +1,58 @@
+# tool.py DOX
+
+## Purpose
+
+- Own the `tool.py` helper module.
+- This module defines the base agent tool class and response contract.
+- Keep this file-level DOX profile synchronized with `tool.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `tool.py` owns the runtime implementation.
+- `tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Response` (no explicit base class)
+- `Tool` (no explicit base class)
+ - `async execute(self, **kwargs) -> Response`
+ - `async set_progress(self, content: str | None)`
+ - `add_progress(self, content: str | None)`
+ - `async before_execution(self, **kwargs)`
+ - `async after_execution(self, response: Response, **kwargs)`
+ - `get_log_object(self)`
+ - `nice_key(self, key: str)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- `Tool` defines `execute(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `abc`, `agent`, `dataclasses`, `helpers.extension`, `helpers.print_style`, `helpers.strings`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.get_log_object`, `sanitize_string`, `self.agent.hist_add_tool_result`, `self.agent.context.log.log`, `key.split`, `join`, `call_extensions_async`, `response.message.strip`, `uuid.uuid4`, `PrintStyle`, `PrintStyle.stream`, `words.capitalize`, `word.lower`, `self.nice_key`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_a0_connector_prompt_gating.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_default_prompt_budget.py`
+ - `tests/test_dirty_json.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_fastmcp_openapi_security.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_mcp_handler_multimodal.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/tunnel_common.py.dox.md b/helpers/tunnel_common.py.dox.md
new file mode 100644
index 000000000..2aa35d8ca
--- /dev/null
+++ b/helpers/tunnel_common.py.dox.md
@@ -0,0 +1,51 @@
+# tunnel_common.py DOX
+
+## Purpose
+
+- Own the `tunnel_common.py` helper module.
+- This module contains shared tunnel provider helper classes and event parsing.
+- Keep this file-level DOX profile synchronized with `tunnel_common.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `tunnel_common.py` owns the runtime implementation.
+- `tunnel_common.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `TunnelHelper` (no explicit base class)
+ - `notify_starting(self, label)`
+ - `notify_url_ready(self, label, url)`
+ - `notify_stopped(self, label)`
+- `FlaredanticTunnelHelper` (`TunnelHelper`)
+ - `build_tunnel(self)`
+ - `start(self)`
+ - `stop(self)`
+- Top-level functions:
+- `event_value(event)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: tunnel state.
+- Imported dependency areas include: `flaredantic`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `callable`, `self._notify`, `self.notify_starting`, `self.build_tunnel`, `self.tunnel.start`, `self.notify_stopped`, `self.notify_callback`, `self.notify_url_ready`, `self.tunnel.stop`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/tunnel_manager.py.dox.md b/helpers/tunnel_manager.py.dox.md
new file mode 100644
index 000000000..c90749a20
--- /dev/null
+++ b/helpers/tunnel_manager.py.dox.md
@@ -0,0 +1,51 @@
+# tunnel_manager.py DOX
+
+## Purpose
+
+- Own the `tunnel_manager.py` helper module.
+- This module selects and coordinates configured tunnel providers.
+- Keep this file-level DOX profile synchronized with `tunnel_manager.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `tunnel_manager.py` owns the runtime implementation.
+- `tunnel_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `TunnelManager` (no explicit base class)
+ - `get_instance(cls)`
+ - `get_notifications(self)`
+ - `get_last_error(self)`
+ - `start_tunnel(self, port=..., provider=...)`
+ - `stop_tunnel(self)`
+ - `get_tunnel_url(self)`
+- Top-level functions:
+- `normalize_provider(provider)`
+- Notable constants/configuration names: `SUPPORTED_TUNNEL_PROVIDERS`, `TUNNEL_PROVIDER_ALIASES`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: tunnel state.
+- Imported dependency areas include: `collections`, `flaredantic`, `helpers.cloudflare_tunnel`, `helpers.microsoft_tunnel`, `helpers.print_style`, `helpers.serveo_tunnel`, `helpers.tailscale_tunnel`, `helpers.tunnel_common`, `threading`, `time`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `strip.lower`, `threading.Lock`, `join`, `ValueError`, `deque`, `self.notifications.clear`, `ServeoTunnelHelper`, `self._ensure_subscribed`, `strip`, `notifier.subscribe`, `CloudflareTunnel`, `MicrosoftDevTunnel`, `TailscaleTunnel`, `normalize_provider`, `threading.Thread`, `tunnel_thread.start`, `cls`, `event_value`, `PrintStyle.error`, `self._append_notification`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_tunnel_remote_link.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/ui_server.py.dox.md b/helpers/ui_server.py.dox.md
new file mode 100644
index 000000000..5f634884e
--- /dev/null
+++ b/helpers/ui_server.py.dox.md
@@ -0,0 +1,57 @@
+# ui_server.py DOX
+
+## Purpose
+
+- Own the `ui_server.py` helper module.
+- This module configures and owns Flask/WebUI runtime route handlers.
+- Keep this file-level DOX profile synchronized with `ui_server.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ui_server.py` owns the runtime implementation.
+- `ui_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `UiServerRuntime` (no explicit base class)
+ - `create(cls) -> 'UiServerRuntime'`
+ - `refresh_runtime_settings(self) -> None`
+ - `register_http_routes(self) -> None`
+ - `register_transport_handlers(self) -> None`
+ - `build_asgi_app(self, startup_monitor: StartupMonitor)`
+ - `access_log_enabled(self) -> bool`
+- `UiRouteHandlers` (no explicit base class)
+ - `async login_handler(self)`
+ - `async logout_handler(self)`
+ - `async serve_index(self)`
+ - `async serve_builtin_plugin_asset(self, plugin_name, asset_path)`
+ - `async serve_plugin_asset(self, plugin_name, asset_path)`
+ - `async serve_extension_asset(self, asset_path)`
+- Top-level functions:
+- `configure_process_environment() -> None`
+- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, WebSocket state, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `asyncio`, `dataclasses`, `datetime`, `flask`, `helpers`, `helpers.api`, `helpers.extension`, `helpers.files`, `helpers.print_style`, `helpers.server_startup`, `helpers.ws`, `helpers.ws_manager`, `logging`, `os`, `secrets`, `socketio`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `logging.getLogger.setLevel`, `Localization.get.apply_process_timezone`, `field`, `Flask`, `threading.RLock`, `socketio.AsyncServer`, `WsManager`, `set_shared_ws_manager`, `cls`, `server_runtime.refresh_runtime_settings`, `settings_helper.get_settings`, `settings_helper.set_runtime_settings_snapshot`, `self.ws_manager.set_server_restart_broadcast`, `UiRouteHandlers`, `self.webapp.add_url_rule`, `register_api_route`, `register_ws_namespace`, `files.read_file`, `render_template_string`, `session.pop`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/update_check.py.dox.md b/helpers/update_check.py.dox.md
new file mode 100644
index 000000000..f25ef598a
--- /dev/null
+++ b/helpers/update_check.py.dox.md
@@ -0,0 +1,41 @@
+# update_check.py DOX
+
+## Purpose
+
+- Own the `update_check.py` helper module.
+- This module checks available Agent Zero updates.
+- Keep this file-level DOX profile synchronized with `update_check.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `update_check.py` owns the runtime implementation.
+- `update_check.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `async check_version()`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: network calls, settings/state persistence.
+- Imported dependency areas include: `hashlib`, `helpers`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `git.get_version`, `git.is_official_agent_zero_repo`, `hashlib.sha256.hexdigest`, `httpx.AsyncClient`, `response.json`, `client.post`, `hashlib.sha256`, `runtime.get_persistent_id.encode`, `runtime.get_persistent_id`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/vector_db.py.dox.md b/helpers/vector_db.py.dox.md
new file mode 100644
index 000000000..bc88f84a1
--- /dev/null
+++ b/helpers/vector_db.py.dox.md
@@ -0,0 +1,53 @@
+# vector_db.py DOX
+
+## Purpose
+
+- Own the `vector_db.py` helper module.
+- This module wraps FAISS vector storage, retrieval, and comparator behavior.
+- Keep this file-level DOX profile synchronized with `vector_db.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `vector_db.py` owns the runtime implementation.
+- `vector_db.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `MyFaiss` (`FAISS`)
+ - `get_by_ids(self, ids: Sequence[str]) -> List[Document]`
+ - `async aget_by_ids(self, ids: Sequence[str]) -> List[Document]`
+ - `get_all_docs(self) -> dict[str, Document]`
+- `VectorDB` (no explicit base class)
+ - `async search_by_similarity_threshold(self, query: str, limit: int, threshold: float, filter: str=...)`
+ - `async search_by_metadata(self, filter: str, limit: int=...) -> list[Document]`
+ - `async insert_documents(self, docs: list[Document])`
+ - `async delete_documents_by_ids(self, ids: list[str])`
+- Top-level functions:
+- `format_docs_plain(docs: list[Document]) -> list[str]`
+- `cosine_normalizer(val: float) -> float`
+- `get_comparator(condition: str)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion.
+- Imported dependency areas include: `agent`, `faiss`, `helpers`, `langchain.embeddings`, `langchain.storage`, `langchain_community.docstore.in_memory`, `langchain_community.vectorstores`, `langchain_community.vectorstores.utils`, `langchain_core.documents`, `simpleeval`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.get_by_ids`, `agent.get_embedding_model`, `self._get_embeddings`, `faiss.IndexFlatIP`, `MyFaiss`, `get_comparator`, `self.db.get_all_docs`, `InMemoryByteStore`, `CacheBackedEmbeddings.from_bytes_store`, `self.db.asearch`, `comparator`, `guids.generate_id`, `zip`, `self.db.add_documents`, `self.db.aget_by_ids`, `simple_eval`, `self.embeddings.embed_query`, `InMemoryDocstore`, `self.db.adelete`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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.
diff --git a/helpers/virtual_desktop.py.dox.md b/helpers/virtual_desktop.py.dox.md
new file mode 100644
index 000000000..34e7b2510
--- /dev/null
+++ b/helpers/virtual_desktop.py.dox.md
@@ -0,0 +1,74 @@
+# virtual_desktop.py DOX
+
+## Purpose
+
+- Own the `virtual_desktop.py` helper module.
+- This module registers and proxies virtual desktop sessions.
+- Keep this file-level DOX profile synchronized with `virtual_desktop.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `virtual_desktop.py` owns the runtime implementation.
+- `virtual_desktop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `VirtualDesktopEndpoint` (no explicit base class)
+- `VirtualDesktopRegistry` (no explicit base class)
+ - `register(self, endpoint: VirtualDesktopEndpoint) -> None`
+ - `unregister(self, token: str) -> None`
+ - `proxy_for_token(self, token: str) -> VirtualDesktopEndpoint | None`
+ - `resize(self, token: str, width: int, height: int) -> dict[str, Any]`
+- Top-level functions:
+- `register_session(token: str, host: str, port: int, owner: str=..., title: str=..., resize: ResizeCallback | None=...) -> None`
+- `unregister_session(token: str) -> None`
+- `proxy_for_token(token: str) -> VirtualDesktopEndpoint | None`
+- `resize_session(token: str, width: int, height: int) -> dict[str, Any]`
+- `get_registry() -> VirtualDesktopRegistry`
+- `session_url(token: str, title: str=...) -> str`
+- `collect_status() -> dict[str, Any]`
+- `find_xpra_html_root() -> Path | None`
+- `_package_installed(package: str) -> bool`
+- `normalize_size(width: int | float | str, height: int | float | str, max_width: int=..., max_height: int=..., min_width: int=..., min_height: int=...) -> tuple[int, int]`
+- `normalize_desktop_display_size(width: int | float | str, height: int | float | str, max_width: int=..., max_height: int=..., min_width: int=..., min_height: int=..., min_aspect_ratio: float=...) -> tuple[int, int]`
+- `resize_display(display: int, width: int, height: int, max_width: int=..., max_height: int=..., window_class: str=..., keys: tuple[str, ...]=..., xauthority: str=..., home: str=...) -> dict[str, Any]`
+- `_ensure_xrandr_mode(env: dict[str, str], width: int, height: int) -> None`
+- `_select_xrandr_mode(env: dict[str, str], width: int, height: int) -> subprocess.CompletedProcess[str]`
+- `_xrandr_output_modes(env: dict[str, str]) -> tuple[str, set[str]]`
+- `current_display_size(display: int, xauthority: str=..., home: str=...) -> tuple[int, int] | None`
+- `fit_window_until(display: int, width: int, height: int, window_class: str=..., keys: tuple[str, ...]=..., settle_seconds: float=..., timeout_seconds: float=..., process: subprocess.Popen[Any] | None=..., xauthority: str=..., home: str=...) -> None`
+- `fit_window(display: int, width: int, height: int, window_class: str=..., keys: tuple[str, ...]=..., xauthority: str=..., home: str=...) -> bool`
+- `has_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> bool`
+- `find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str`
+- `close_windows(display: int, names: tuple[str, ...]=..., window_class: str=..., xauthority: str=..., home: str=...) -> int`
+- `_find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str`
+- `_display_env(display: int, xauthority: str=..., home: str=...) -> dict[str, str]`
+- Notable constants/configuration names: `STATE_DIR`, `DEFAULT_WIDTH`, `DEFAULT_HEIGHT`, `MAX_WIDTH`, `MAX_HEIGHT`, `MIN_WIDTH`, `MIN_HEIGHT`, `MIN_DESKTOP_ASPECT_RATIO`, `SESSION_PATH`, `XPRA_HTML_ROOT_CANDIDATES`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.localization`, `math`, `os`, `pathlib`, `re`, `shutil`, `subprocess`, `threading`, `time`, `typing`, `urllib.parse`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `get_registry.register`, `get_registry.unregister`, `get_registry.proxy_for_token`, `get_registry.resize`, `quote`, `urlencode`, `find_xpra_html_root`, `subprocess.run`, `normalize_size`, `shutil.which`, `_display_env`, `current_display_size`, `_ensure_xrandr_mode`, `_select_xrandr_mode`, `time.sleep`, `strip`, `_xrandr_output_modes`, `result.stdout.splitlines`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_office_canvas_setup.py`
+ - `tests/test_office_desktop_state.py`
+ - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/virtual_desktop_routes.py.dox.md b/helpers/virtual_desktop_routes.py.dox.md
new file mode 100644
index 000000000..b784fca80
--- /dev/null
+++ b/helpers/virtual_desktop_routes.py.dox.md
@@ -0,0 +1,55 @@
+# virtual_desktop_routes.py DOX
+
+## Purpose
+
+- Own the `virtual_desktop_routes.py` helper module.
+- This module installs virtual desktop gateway route hooks.
+- Keep this file-level DOX profile synchronized with `virtual_desktop_routes.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `virtual_desktop_routes.py` owns the runtime implementation.
+- `virtual_desktop_routes.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `VirtualDesktopGateway` (no explicit base class)
+ - `async http(self, scope: Scope, receive: Receive, send: Send) -> None`
+ - `async resize(self, scope: Scope, receive: Receive, send: Send) -> None`
+ - `async proxy_http(self, scope: Scope, receive: Receive, send: Send, token: str, upstream_path: str) -> None`
+ - `async websocket(self, scope: Scope, receive: Receive, send: Send) -> None`
+ - `async open_websocket(self, endpoint: virtual_desktop.VirtualDesktopEndpoint, target: str, subprotocols: tuple[str, ...]) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, WSConnection, str | None]`
+ - `async browser_to_xpra(self, websocket: WebSocket, upstream: WSConnection, writer: asyncio.StreamWriter) -> None`
+ - `async xpra_to_browser(self, websocket: WebSocket, upstream: WSConnection, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None`
+ - `session_request(self, path: str) -> tuple[str, str] | None`
+- Top-level functions:
+- `install_route_hooks() -> None`
+- `is_installed() -> bool`
+- Notable constants/configuration names: `HOP_BY_HOP_HEADERS`, `XPRA_MENU_CUSTOM_PATCH`, `XPRA_WINDOW_OFFSET_WARNING`, `XPRA_WINDOW_OFFSET_WARNING_PATCH`, `XPRA_WINDOW_SCRIPT`, `XPRA_WINDOW_SCRIPT_PATCH`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, secret handling.
+- Imported dependency areas include: `__future__`, `asyncio`, `flask.sessions`, `helpers`, `http.client`, `http.cookies`, `starlette.requests`, `starlette.responses`, `starlette.types`, `starlette.websockets`, `urllib.parse`, `wsproto`, `wsproto.events`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.relative_path`, `self.session_request`, `self.query`, `virtual_desktop.proxy_for_token`, `WebSocket`, `self.upstream_target`, `WSConnection`, `writer.write`, `rest.partition`, `unquote`, `quote`, `http.client.HTTPConnection`, `query_string.decode`, `urlsplit`, `location.startswith`, `path.startswith`, `parse_qs`, `login.get_credentials_hash`, `SecureCookieSessionInterface.get_signing_serializer`, `dict.get.decode`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_office_canvas_setup.py`
+ - `tests/test_office_document_store.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/wait.py.dox.md b/helpers/wait.py.dox.md
new file mode 100644
index 000000000..a647c28ef
--- /dev/null
+++ b/helpers/wait.py.dox.md
@@ -0,0 +1,49 @@
+# wait.py DOX
+
+## Purpose
+
+- Own the `wait.py` helper module.
+- This module formats and runs managed waits with progress updates.
+- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `wait.py` owns the runtime implementation.
+- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `format_remaining_time(total_seconds: float) -> str`
+- `async managed_wait(agent, target_time, is_duration_wait, log, get_heading_callback)`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Imported dependency areas include: `asyncio`, `helpers.localization`, `helpers.print_style`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `divmod`, `join`, `Localization.get.now`, `total_seconds`, `agent.handle_intervention`, `asyncio.sleep`, `pause_duration.total_seconds`, `PrintStyle.info`, `get_heading_callback`, `format_remaining_time`, `Localization.get.serialize_datetime`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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_default_prompt_budget.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_download_toast_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/watchdog.py.dox.md b/helpers/watchdog.py.dox.md
new file mode 100644
index 000000000..920b4703c
--- /dev/null
+++ b/helpers/watchdog.py.dox.md
@@ -0,0 +1,72 @@
+# watchdog.py DOX
+
+## Purpose
+
+- Own the `watchdog.py` helper module.
+- This module registers filesystem watchdogs with debouncing and path filtering.
+- Keep this file-level DOX profile synchronized with `watchdog.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `watchdog.py` owns the runtime implementation.
+- `watchdog.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `_DispatchHandler` (no explicit base class)
+ - `dispatch(self, event: Any)`
+- `_Watch` (no explicit base class)
+- `_PendingBatch` (no explicit base class)
+- `_WatchRegistry` (no explicit base class)
+ - `add(self, id: str, roots: list[str], patterns: list[str] | None, ignore_patterns: list[str] | None, events: WatchEvents, debounce: float, handler: WatchHandler) -> None`
+ - `remove(self, id: str) -> bool`
+ - `clear(self) -> None`
+ - `start(self) -> None`
+ - `stop(self) -> None`
+ - `dispatch(self, scheduled_root: str, event: Any) -> None`
+- Top-level functions:
+- `_normalize_root(root: str) -> str`
+- `_normalize_roots(roots: list[str]) -> list[str]`
+- `_normalize_patterns(patterns: list[str] | None, default: list[str] | None=...) -> list[str]`
+- `_normalize_events(events: WatchEvents) -> frozenset[WatchEvent]`
+- `_map_event_type(event_type: str) -> WatchEvent | None`
+- `_normalize_debounce(debounce: float) -> float`
+- `_covering_roots(roots: Iterable[str]) -> set[str]`
+- `_is_same_or_nested(path: str, root: str) -> bool`
+- `_is_under_watch(path: str, watch: _Watch) -> bool`
+- `_compile_matcher(root: str, patterns: list[str], ignore_patterns: list[str]) -> PatternMatcher`
+- `_compile_single_matcher(root: str, patterns: list[str]) -> PatternMatcher`
+- `add_watchdog(id: str, roots: list[str], patterns: list[str] | None=..., ignore_patterns: list[str] | None=..., events: WatchEvents=..., debounce: float=..., handler: WatchHandler | None=...) -> None`
+- `remove_watchdog(id: str) -> bool`
+- `clear_watchdogs() -> None`
+- `start_watchdog_daemon() -> None`
+- `stop_watchdog_daemon() -> None`
+- Notable constants/configuration names: `_DEFAULT_PATTERNS`, `_DEFAULT_IGNORE_PATTERNS`, `_VALID_EVENTS`, `_EVENT_ALIASES`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
+- Imported dependency areas include: `__future__`, `dataclasses`, `os`, `pathlib`, `threading`, `typing`, `watchdog.observers`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `frozenset`, `dataclass`, `_WatchRegistry`, `_registry.start`, `os.path.abspath`, `_compile_single_matcher`, `_registry.add`, `_registry.remove`, `_registry.clear`, `_registry.stop`, `self.registry.dispatch`, `threading.RLock`, `self._ensure_watchdog_available`, `_normalize_roots`, `_normalize_patterns`, `_normalize_events`, `_normalize_debounce`, `self._stop_observer`, `_map_event_type`, `_covering_roots`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_model_config_api_keys.py`
+ - `tests/test_model_config_project_presets.py`
+ - `tests/test_time_travel.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/ws.py.dox.md b/helpers/ws.py.dox.md
new file mode 100644
index 000000000..5eb7279f6
--- /dev/null
+++ b/helpers/ws.py.dox.md
@@ -0,0 +1,75 @@
+# ws.py DOX
+
+## Purpose
+
+- Own the `ws.py` helper module.
+- This module defines WebSocket handler registration, origin validation, and security checks.
+- Keep this file-level DOX profile synchronized with `ws.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ws.py` owns the runtime implementation.
+- `ws.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ConnectionNotFoundError` (`RuntimeError`)
+- `_SecurityContext` (no explicit base class)
+- `WsHandler` (no explicit base class)
+ - `namespace(self) -> str`
+ - `manager(self) -> 'WsManager'`
+ - `identifier(self) -> str`
+ - `bind_manager(self, manager: 'WsManager', namespace: str | None=...) -> None`
+ - `requires_loopback(cls) -> bool`
+ - `requires_api_key(cls) -> bool`
+ - `requires_auth(cls) -> bool`
+ - `requires_csrf(cls) -> bool`
+- Top-level functions:
+- `_ws_debug_enabled() -> bool`: Check A0_WS_DEBUG env var - lightweight, no heavy imports.
+- `ws_debug(message: str) -> None`: Log *message* via :class:`PrintStyle` when ``A0_WS_DEBUG`` is active.
+- `_default_port_for_scheme(scheme: str) -> int | None`
+- `normalize_origin(value: Any) -> str | None`: Normalize an Origin/Referer header value to scheme://host[:port].
+- `_parse_host_header(value: Any) -> tuple[str | None, int | None]`
+- `validate_ws_origin(environ: dict[str, Any]) -> tuple[bool, str | None]`: Validate the browser Origin during the Socket.IO handshake.
+- `_check_security(handler_cls: type[WsHandler], ctx: _SecurityContext) -> dict[str, Any] | None`: Return an error payload dict if the check fails, or ``None`` on success.
+- `register_ws_namespace(socketio_server: socketio.AsyncServer, webapp: Flask, lock: ThreadLockType, manager: 'WsManager | None'=...) -> None`
+- `_error_response(code: str, message: str, correlation_id: str) -> dict[str, Any]`
+- Notable constants/configuration names: `NAMESPACE`, `CACHE_AREA`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- `WsHandler` defines `process(...)`.
+- `WsHandler` defines `requires_auth(...)`.
+- `WsHandler` defines `requires_csrf(...)`.
+- `WsHandler` defines `requires_api_key(...)`.
+- `WsHandler` defines `requires_loopback(...)`.
+- Observed side-effect areas: filesystem reads, filesystem deletion, network calls, WebSocket state, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `abc`, `dataclasses`, `flask`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `os`, `pathlib`, `socketio`, `threading`, `typing`, `urllib.parse`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `threading.Lock`, `os.getenv.strip.lower`, `_ws_debug_enabled`, `urlparse`, `normalize_origin`, `_parse_host_header`, `handler_cls.requires_loopback`, `handler_cls.requires_auth`, `handler_cls.requires_csrf`, `handler_cls.requires_api_key`, `socketio_server.on`, `PrintStyle.debug`, `value.strip`, `origin_parsed.hostname.lower`, `_default_port_for_scheme`, `req_host.lower`, `forwarded_host_raw.strip`, `forwarded_host_raw.split.strip`, `forwarded_proto_raw.strip`, `forwarded_proto_raw.split.strip.lower`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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_docker_release_plan.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_git_version_label.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_multi_tab_isolation.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/ws_manager.py.dox.md b/helpers/ws_manager.py.dox.md
new file mode 100644
index 000000000..3d8f6da61
--- /dev/null
+++ b/helpers/ws_manager.py.dox.md
@@ -0,0 +1,70 @@
+# ws_manager.py DOX
+
+## Purpose
+
+- Own the `ws_manager.py` helper module.
+- This module manages WebSocket connections, event validation, buffering, and dispatch.
+- Keep this file-level DOX profile synchronized with `ws_manager.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `ws_manager.py` owns the runtime implementation.
+- `ws_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `WsResult` (no explicit base class)
+ - `ok(cls, data: dict[str, Any] | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
+ - `error(cls, code: str, message: str, details: Any | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
+ - `as_result(self, handler_id: str, fallback_correlation_id: str | None, duration_ms: float | None=...) -> dict[str, Any]`
+- `BufferedEvent` (no explicit base class)
+- `ConnectionInfo` (no explicit base class)
+- `_HandlerExecution` (no explicit base class)
+- `WsManager` (no explicit base class)
+ - `register_diagnostic_watcher(self, namespace: str, sid: str) -> bool`
+ - `unregister_diagnostic_watcher(self, namespace: str, sid: str) -> None`
+ - `register_handlers(self, handlers_by_namespace: dict[str, Iterable[WsHandler]]) -> None`
+ - `iter_namespaces(self) -> list[str]`
+ - `async process_client_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, handlers: list[WsHandler]) -> dict[str, Any]`
+ - `async handle_connect(self, namespace: str, sid: str, user_id: str | None=...) -> None`
+ - `async handle_disconnect(self, namespace: str, sid: str) -> None`
+ - `async route_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, ack: Optional[Callable[[Any], None]]=..., include_handlers: Set[str] | None=..., exclude_handlers: Set[str] | None=..., allow_exclude: bool=..., handler_id: str | None=...) -> dict[str, Any]`
+- Top-level functions:
+- `validate_event_type(event_type: str) -> str`: Validate an event name: must be lowercase_snake_case and not reserved.
+- `async send_data(event_type: str, data: dict[str, Any], endpoint_name: str=..., connection_id: str | None=...) -> None`: Convenience wrapper around :pymeth:`WsManager.send_data`.
+- `_utcnow() -> datetime`
+- `set_shared_ws_manager(manager: 'WsManager') -> None`
+- `get_shared_ws_manager() -> 'WsManager'`
+- Notable constants/configuration names: `_EVENT_NAME_PATTERN`, `_RESERVED_EVENT_NAMES`, `BUFFER_MAX_SIZE`, `BUFFER_TTL`, `DIAGNOSTIC_EVENT`, `LIFECYCLE_CONNECT_EVENT`, `LIFECYCLE_DISCONNECT_EVENT`, `STATE_PUSH_EVENT`, `SERVER_RESTART_EVENT`, `ERR_NO_HANDLERS`, `ERR_HANDLER_ERROR`, `ERR_INVALID_FILTER`, `ERR_INVALID_EVENT`, `ERR_CONNECTION_NOT_FOUND`, `ERR_TIMEOUT`.
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem deletion, network calls, WebSocket state, settings/state persistence, scheduler state.
+- Imported dependency areas include: `__future__`, `asyncio`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.defer`, `helpers.print_style`, `helpers.ws`, `os`, `re`, `socketio`, `threading`, `time`, `typing`, `uuid`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `re.compile`, `timedelta`, `get_shared_ws_manager`, `datetime.now`, `field`, `cls`, `TypeError`, `_EVENT_NAME_PATTERN.fullmatch`, `ValueError`, `manager.send_data`, `RuntimeError`, `defaultdict`, `runtime.is_development`, `ws_debug`, `self._ensure_dispatcher_loop`, `dispatcher_loop.is_closed`, `asyncio.run_coroutine_threadsafe`, `_utcnow.isoformat.replace`, `self._copy_diagnostic_watchers`, `self._lifecycle_tasks.add`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_state_sync_handler.py`
+ - `tests/test_state_sync_welcome_screen.py`
+ - `tests/test_tool_action_contracts.py`
+ - `tests/test_ws_handlers.py`
+ - `tests/test_ws_manager.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/yaml.py.dox.md b/helpers/yaml.py.dox.md
new file mode 100644
index 000000000..41f1da445
--- /dev/null
+++ b/helpers/yaml.py.dox.md
@@ -0,0 +1,52 @@
+# yaml.py DOX
+
+## Purpose
+
+- Own the `yaml.py` helper module.
+- This module wraps YAML loading/dumping and JSON conversion helpers.
+- Keep this file-level DOX profile synchronized with `yaml.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `yaml.py` owns the runtime implementation.
+- `yaml.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Top-level functions:
+- `loads(text: str)`
+- `dumps(obj, **kwargs) -> str`
+- `from_json(text: str, **yaml_dump_kwargs) -> str`
+- `to_json(text: str, **json_dump_kwargs) -> str`
+
+## Runtime Contracts
+
+- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
+- Observed side-effect areas: filesystem writes, settings/state persistence.
+- Imported dependency areas include: `json`, `yaml`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `yaml.safe_load`, `yaml.safe_dump`, `dumps`, `loads`, `json.dumps`, `json.loads`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Preserve public helper APIs used by core code and plugins unless every caller is updated.
+- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
+- Prefer adding cohesive helper functions here only when behavior is reused across modules.
+
+## Verification
+
+- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
+- 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_model_config_api_keys.py`
+ - `tests/test_model_config_project_presets.py`
+ - `tests/test_oauth_codex.py`
+ - `tests/test_oauth_providers.py`
+ - `tests/test_office_canvas_setup.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md
index ba9e518d3..2a60a0c5d 100644
--- a/plugins/AGENTS.md
+++ b/plugins/AGENTS.md
@@ -60,4 +60,35 @@
## Child DOX Index
-No child DOX files.
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [_a0_connector/AGENTS.md](_a0_connector/AGENTS.md) | HTTP and WebSocket connector integration with remote tools and runtime bridges. |
+| [_browser/AGENTS.md](_browser/AGENTS.md) | Playwright browser tool, helpers, viewer, and browser panel UI. |
+| [_chat_branching/AGENTS.md](_chat_branching/AGENTS.md) | Chat branching from an existing message. |
+| [_chat_compaction/AGENTS.md](_chat_compaction/AGENTS.md) | Full-chat compaction into a summary message. |
+| [_code_execution/AGENTS.md](_code_execution/AGENTS.md) | Terminal, Python, and Node.js execution tools and shell runtimes. |
+| [_desktop/AGENTS.md](_desktop/AGENTS.md) | Linux desktop runtime, sessions, and desktop surface. |
+| [_discovery/AGENTS.md](_discovery/AGENTS.md) | Welcome-screen plugin discovery cards and promotions. |
+| [_document_query/AGENTS.md](_document_query/AGENTS.md) | Document parsing, indexing, and Q&A tools. |
+| [_editor/AGENTS.md](_editor/AGENTS.md) | Native Markdown editor surface and sessions. |
+| [_email_integration/AGENTS.md](_email_integration/AGENTS.md) | IMAP/Exchange polling and SMTP reply integration. |
+| [_error_retry/AGENTS.md](_error_retry/AGENTS.md) | Critical exception retry lifecycle hooks. |
+| [_infection_check/AGENTS.md](_infection_check/AGENTS.md) | Prompt-injection safety analysis before tool execution. |
+| [_kokoro_tts/AGENTS.md](_kokoro_tts/AGENTS.md) | Kokoro text-to-speech integration. |
+| [_memory/AGENTS.md](_memory/AGENTS.md) | Persistent vector memory, knowledge import, tools, and dashboard. |
+| [_model_config/AGENTS.md](_model_config/AGENTS.md) | Model selection, presets, API-key checks, and scoped overrides. |
+| [_oauth/AGENTS.md](_oauth/AGENTS.md) | OAuth-backed model-provider connections and local proxy routes. |
+| [_office/AGENTS.md](_office/AGENTS.md) | LibreOffice office artifacts and office canvas sessions. |
+| [_onboarding/AGENTS.md](_onboarding/AGENTS.md) | First-time model onboarding wizard. |
+| [_plugin_installer/AGENTS.md](_plugin_installer/AGENTS.md) | Plugin install and update flows from ZIP, Git, and Plugin Index. |
+| [_plugin_scan/AGENTS.md](_plugin_scan/AGENTS.md) | LLM-guided security scanner for third-party plugins. |
+| [_plugin_validator/AGENTS.md](_plugin_validator/AGENTS.md) | Plugin manifest, structure, convention, and security validator. |
+| [_promptinclude/AGENTS.md](_promptinclude/AGENTS.md) | Promptinclude scanning and prompt injection. |
+| [_skills/AGENTS.md](_skills/AGENTS.md) | Active and hidden skill configuration and prompt injection. |
+| [_telegram_integration/AGENTS.md](_telegram_integration/AGENTS.md) | Telegram bot integration and per-user chat sessions. |
+| [_text_editor/AGENTS.md](_text_editor/AGENTS.md) | Native text read, write, and patch tool. |
+| [_time_travel/AGENTS.md](_time_travel/AGENTS.md) | Workspace history, diff, travel, snapshot, and revert flows. |
+| [_whatsapp_integration/AGENTS.md](_whatsapp_integration/AGENTS.md) | WhatsApp Baileys bridge integration. |
+| [_whisper_stt/AGENTS.md](_whisper_stt/AGENTS.md) | Whisper speech-to-text integration. |
diff --git a/plugins/_a0_connector/AGENTS.md b/plugins/_a0_connector/AGENTS.md
new file mode 100644
index 000000000..3a9e483c2
--- /dev/null
+++ b/plugins/_a0_connector/AGENTS.md
@@ -0,0 +1,31 @@
+# A0 Connector Plugin DOX
+
+## Purpose
+
+- Own the current Agent Zero connector plugin for HTTP and WebSocket integration.
+- Provide remote execution, text-editing freshness, and connector runtime bridges.
+
+## Ownership
+
+- `plugin.yaml` owns plugin metadata and settings scope.
+- `api/` owns connector WebSocket and API entry points.
+- `helpers/` owns chat context, event bridge, execution config, freshness, version, and WebSocket runtime helpers.
+- `tools/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own connector-facing agent and UI contributions.
+
+## Local Contracts
+
+- Preserve session-auth and `auth.handlers` activation assumptions.
+- Keep remote tool prompts synchronized with remote tool behavior.
+- Do not bypass WebSocket authentication or leak connector session data.
+
+## Work Guidance
+
+- Coordinate connector runtime changes with API, tools, prompts, and WebUI viewer behavior together.
+
+## Verification
+
+- Run connector-specific tests or smoke-test HTTP and `/ws` integration when changing runtime behavior.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_browser/AGENTS.md b/plugins/_browser/AGENTS.md
new file mode 100644
index 000000000..96d9f905c
--- /dev/null
+++ b/plugins/_browser/AGENTS.md
@@ -0,0 +1,32 @@
+# Browser Plugin DOX
+
+## Purpose
+
+- Own the built-in Playwright browser tool and WebUI browser viewer.
+- Bridge browser automation, page inspection helpers, and browser panel UI.
+
+## Ownership
+
+- `plugin.yaml` and `default_config.yaml` own metadata and browser settings defaults.
+- `tools/browser.py` owns the agent-facing browser tool.
+- `helpers/` owns Playwright runtime, selectors, URL helpers, extension management, and connector runtime logic.
+- `api/` owns status, extension, and browser WebSocket handlers.
+- `assets/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own browser scripts, prompts, skill guidance, hook contributions, and UI.
+
+## Local Contracts
+
+- Keep browser actions safe around external pages, credentials, and user data.
+- Preserve Playwright lifecycle cleanup and WebSocket viewer compatibility.
+- Do not hardcode user-specific browser paths or secrets.
+
+## Work Guidance
+
+- Coordinate tool, helper, and panel changes so browser state shown in the UI matches tool behavior.
+
+## Verification
+
+- Smoke-test browser launch, navigation, DOM capture, and WebUI viewer after runtime changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_chat_branching/AGENTS.md b/plugins/_chat_branching/AGENTS.md
new file mode 100644
index 000000000..b10df9993
--- /dev/null
+++ b/plugins/_chat_branching/AGENTS.md
@@ -0,0 +1,31 @@
+# Chat Branching Plugin DOX
+
+## Purpose
+
+- Own branching a chat from any existing message.
+- Keep log and history trimming behavior consistent when creating a branched conversation.
+
+## Ownership
+
+- `plugin.yaml` and `README.md` own metadata and user-facing behavior notes.
+- `api/branch_chat.py` owns branch creation, clone, trim, persist, and refresh behavior.
+- `extensions/` owns WebUI button injection.
+- `webui/` owns plugin thumbnail assets.
+
+## Local Contracts
+
+- Preserve UUID-based linking between log entries and history messages.
+- Branched chats must include history only up to the selected message.
+- Do not mutate the source chat while creating a branch.
+
+## Work Guidance
+
+- Coordinate UI button injection with message rendering extension points.
+
+## Verification
+
+- Smoke-test branching from several message positions and confirm source chat remains unchanged.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_chat_compaction/AGENTS.md b/plugins/_chat_compaction/AGENTS.md
new file mode 100644
index 000000000..c1d7b418a
--- /dev/null
+++ b/plugins/_chat_compaction/AGENTS.md
@@ -0,0 +1,32 @@
+# Chat Compaction Plugin DOX
+
+## Purpose
+
+- Own compacting an entire chat history into a single optimized summary message.
+- Keep compaction prompt, helper, API, and modal behavior aligned.
+
+## Ownership
+
+- `plugin.yaml` and `default_config.yaml` own metadata and compaction defaults.
+- `api/compact_chat.py` owns the compaction endpoint.
+- `helpers/compactor.py` owns summary generation and history rewrite logic.
+- `prompts/` owns compaction system and message prompts.
+- `webui/` owns the compaction modal and store.
+
+## Local Contracts
+
+- Preserve chat history integrity and persistence after compaction.
+- Keep generated summaries bounded by configured model and token limits.
+- Do not discard original context data unless the compaction flow explicitly owns that behavior.
+
+## Work Guidance
+
+- Coordinate prompt changes with helper behavior and UI confirmation text.
+
+## Verification
+
+- Smoke-test compacting a chat and reloading it after persistence.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_code_execution/AGENTS.md b/plugins/_code_execution/AGENTS.md
new file mode 100644
index 000000000..2de8457f1
--- /dev/null
+++ b/plugins/_code_execution/AGENTS.md
@@ -0,0 +1,30 @@
+# Code Execution Plugin DOX
+
+## Purpose
+
+- Own terminal, Python, and Node.js code execution through persistent local or SSH-backed sessions.
+
+## Ownership
+
+- `tools/` owns the code execution and input tools.
+- `helpers/` owns local shell, SSH shell, and TTY session management.
+- `prompts/` owns execution prompt and runtime response fragments.
+- `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own settings, metadata, hooks, and UI config.
+
+## Local Contracts
+
+- Keep session concurrency, timeout, streaming, and reset behavior predictable.
+- Explicitly target local versus SSH execution runtimes.
+- Do not hardcode secrets, SSH credentials, or local user paths.
+
+## Work Guidance
+
+- Preserve long-running command output retrieval and busy-session guards when changing execution flow.
+
+## Verification
+
+- Smoke-test terminal, Python, Node.js, output polling, and reset paths after tool changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_desktop/AGENTS.md b/plugins/_desktop/AGENTS.md
new file mode 100644
index 000000000..2f2b300fd
--- /dev/null
+++ b/plugins/_desktop/AGENTS.md
@@ -0,0 +1,30 @@
+# Desktop Plugin DOX
+
+## Purpose
+
+- Own the Agent Zero Linux desktop runtime, Xpra/Xfce session integration, and live desktop surface.
+
+## Ownership
+
+- `helpers/` owns desktop routes, session lifecycle, state, and prompt context.
+- `api/desktop_session.py` owns desktop session API behavior.
+- `hooks.py` owns route registration and plugin lifecycle hooks.
+- `prompts/`, `assets/`, `skills/`, `extensions/`, and `webui/` own desktop context, assets, skill guidance, hooks, and panel UI.
+
+## Local Contracts
+
+- Preserve session startup, cleanup, and route protection for desktop access.
+- Keep desktop state injected into prompts accurate and bounded.
+- Do not expose desktop routes without the expected auth protections.
+
+## Work Guidance
+
+- Coordinate runtime and panel changes so live UI reflects actual desktop session state.
+
+## Verification
+
+- Smoke-test desktop startup, panel connection, route access, and session cleanup after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_discovery/AGENTS.md b/plugins/_discovery/AGENTS.md
new file mode 100644
index 000000000..d2440d5ab
--- /dev/null
+++ b/plugins/_discovery/AGENTS.md
@@ -0,0 +1,29 @@
+# Plugin Discovery DOX
+
+## Purpose
+
+- Own contextual plugin discovery cards and welcome-screen promotions.
+
+## Ownership
+
+- `plugin.yaml` owns metadata and always-enabled status.
+- `extensions/` owns backend or WebUI discovery contributions.
+- `webui/discovery-store.js` owns discovery UI state and actions.
+
+## Local Contracts
+
+- Discovery cards must be accurate, dismissible where appropriate, and avoid advertising already-complete setup.
+- CTA actions must match supported welcome-screen action contracts.
+- Keep card IDs unique and plugin-prefixed.
+
+## Work Guidance
+
+- Prefer backend status checks before surfacing setup or integration prompts.
+
+## Verification
+
+- Smoke-test welcome-screen discovery cards, ordering, dismissal, and CTA behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_document_query/AGENTS.md b/plugins/_document_query/AGENTS.md
new file mode 100644
index 000000000..c39208f94
--- /dev/null
+++ b/plugins/_document_query/AGENTS.md
@@ -0,0 +1,30 @@
+# Document Query Plugin DOX
+
+## Purpose
+
+- Own document loading, parsing, indexing, and Q&A over local and remote documents.
+
+## Ownership
+
+- `tools/document_query.py` owns the agent-facing query tool.
+- `helpers/` owns fetching, parser routing, indexing, and query orchestration.
+- `prompts/` owns document-query tool and optimization prompts.
+- `hooks.py`, `default_config.yaml`, `plugin.yaml`, `skills/`, `extensions/`, and `webui/` own dependency bootstrap, settings, metadata, skill guidance, hooks, and UI.
+
+## Local Contracts
+
+- Respect configured size, timeout, retry, parser concurrency, and OCR limits.
+- Fetch local and remote resources safely and avoid leaking document contents beyond intended prompt/tool use.
+- Keep optional dependency installation targeted to the framework runtime.
+
+## Work Guidance
+
+- Coordinate parser changes with timeout handling and fallback behavior.
+
+## Verification
+
+- Smoke-test representative PDF, text/HTML, image/OCR, and remote-document queries after parser changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_editor/AGENTS.md b/plugins/_editor/AGENTS.md
new file mode 100644
index 000000000..92969d629
--- /dev/null
+++ b/plugins/_editor/AGENTS.md
@@ -0,0 +1,30 @@
+# Editor Plugin DOX
+
+## Purpose
+
+- Own the native Markdown editor surface for canvas and floating modal workflows.
+
+## Ownership
+
+- `api/` owns editor session and WebSocket handlers.
+- `helpers/` owns markdown session and open-file context helpers.
+- `prompts/` owns agent-visible open-file context.
+- `webui/` owns editor panel, preview, store, and main surface.
+- `extensions/` owns editor hook contributions.
+
+## Local Contracts
+
+- Keep editor session state synchronized across API, WebSocket, and WebUI panel behavior.
+- Do not expose unsaved content or local paths beyond intended chat/context surfaces.
+
+## Work Guidance
+
+- Coordinate editor preview and session changes with canvas surface registration.
+
+## Verification
+
+- Smoke-test opening, editing, previewing, and reconnecting editor sessions after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_email_integration/AGENTS.md b/plugins/_email_integration/AGENTS.md
new file mode 100644
index 000000000..8d3d09c7e
--- /dev/null
+++ b/plugins/_email_integration/AGENTS.md
@@ -0,0 +1,30 @@
+# Email Integration Plugin DOX
+
+## Purpose
+
+- Own communicating with Agent Zero through email inboxes and SMTP replies.
+
+## Ownership
+
+- `helpers/handler.py` owns mailbox polling, state, dispatch, routing, and reply flow.
+- `helpers/imap_client.py` and `helpers/smtp_client.py` own inbound and outbound mail transports.
+- `helpers/dispatcher.py`, `prompts/`, and attachment helpers own routing decisions and message formatting.
+- `api/`, `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own tests, settings, metadata, hooks, and config UI.
+
+## Local Contracts
+
+- Treat mailbox credentials and downloaded attachments as sensitive.
+- Preserve UID/state tracking so restarts do not duplicate old mail.
+- Keep SMTP replies threaded and safe around user-visible errors.
+
+## Work Guidance
+
+- Coordinate polling, dispatch prompts, and WebUI settings when adding account or routing behavior.
+
+## Verification
+
+- Smoke-test connection checks, polling, attachment handling, dispatch routing, and SMTP replies when practical.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_error_retry/AGENTS.md b/plugins/_error_retry/AGENTS.md
new file mode 100644
index 000000000..ae1a15541
--- /dev/null
+++ b/plugins/_error_retry/AGENTS.md
@@ -0,0 +1,30 @@
+# Error Retry Plugin DOX
+
+## Purpose
+
+- Own retry behavior for unexpected critical exceptions in agent loops.
+
+## Ownership
+
+- `extensions/` owns retry counter reset and critical-exception retry hooks.
+- `default_config.yaml` owns retry count defaults.
+- `webui/config.html` owns settings UI.
+- `plugin.yaml` and `README.md` own metadata and behavior notes.
+
+## Local Contracts
+
+- Do not retry controlled flow exceptions such as `HandledException` and `RepairableException`.
+- Keep retry counts scoped per monologue.
+- Preserve clear agent-facing history injection when retrying a critical exception.
+
+## Work Guidance
+
+- Keep retry behavior conservative and observable through logs/UI.
+
+## Verification
+
+- Test or simulate critical, handled, and repairable exception paths after hook changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_infection_check/AGENTS.md b/plugins/_infection_check/AGENTS.md
new file mode 100644
index 000000000..6f88ee127
--- /dev/null
+++ b/plugins/_infection_check/AGENTS.md
@@ -0,0 +1,29 @@
+# Infection Check Plugin DOX
+
+## Purpose
+
+- Own prompt-injection safety checks over streamed reasoning/response content before tool execution.
+
+## Ownership
+
+- `helpers/checker.py` owns safety analysis orchestration and gate behavior.
+- `extensions/` owns stream collection and tool-execution blocking hooks.
+- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own settings, metadata, behavior notes, and config UI.
+
+## Local Contracts
+
+- Preserve configured `thoughts` and `complete` analysis modes.
+- Tool execution must wait for required safety verdicts.
+- Do not log or expose chain-of-thought or sensitive prompt content beyond intended warning flows.
+
+## Work Guidance
+
+- Keep termination and clarification loops bounded and explicit.
+
+## Verification
+
+- Smoke-test ok, clarify, and terminate verdicts around tool execution after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_kokoro_tts/AGENTS.md b/plugins/_kokoro_tts/AGENTS.md
new file mode 100644
index 000000000..8e7ffc6bf
--- /dev/null
+++ b/plugins/_kokoro_tts/AGENTS.md
@@ -0,0 +1,31 @@
+# Kokoro TTS Plugin DOX
+
+## Purpose
+
+- Own built-in Kokoro text-to-speech integration and browser TTS fallback coordination.
+
+## Ownership
+
+- `api/` owns synthesize and status endpoints.
+- `helpers/` owns runtime and migration behavior.
+- `hooks.py` owns provider registration/lifecycle behavior.
+- `webui/` owns settings and speech UI integration.
+- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes.
+
+## Local Contracts
+
+- Keep Kokoro dependencies on Docker/bootstrap paths, not opportunistic runtime installs.
+- Preserve browser-native fallback when the plugin is disabled or unavailable.
+- Do not expose generated speech artifacts outside intended response paths.
+
+## Work Guidance
+
+- Coordinate status endpoint behavior with frontend fallback decisions.
+
+## Verification
+
+- Smoke-test status, synthesis, configured voice/speed, and disabled fallback behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_memory/AGENTS.md b/plugins/_memory/AGENTS.md
new file mode 100644
index 000000000..622026f57
--- /dev/null
+++ b/plugins/_memory/AGENTS.md
@@ -0,0 +1,31 @@
+# Memory Plugin DOX
+
+## Purpose
+
+- Own persistent memory, knowledge import, vector indexing, and memory management UI.
+
+## Ownership
+
+- `helpers/memory.py` owns FAISS store loading, embedding metadata, and knowledge preload.
+- `helpers/knowledge_import.py` and `helpers/memory_consolidation.py` own import and consolidation behavior.
+- `tools/` owns memory save/load/delete/forget and behavior adjustment tools.
+- `api/` and `webui/` own memory dashboard and knowledge reindex/import flows.
+- `prompts/`, `default_config.yaml`, and `plugin.yaml` own memory prompts, defaults, and metadata.
+
+## Local Contracts
+
+- Keep memory scoped by configured subdirectory/context.
+- Preserve embedding metadata needed to rebuild indexes safely.
+- Avoid storing transient action-history noise as durable memory.
+
+## Work Guidance
+
+- Coordinate tool, prompt, and consolidation changes so saved memories remain useful and bounded.
+
+## Verification
+
+- Smoke-test save, recall, delete, dashboard search/update, and knowledge import/reindex after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_model_config/AGENTS.md b/plugins/_model_config/AGENTS.md
new file mode 100644
index 000000000..be2979411
--- /dev/null
+++ b/plugins/_model_config/AGENTS.md
@@ -0,0 +1,30 @@
+# Model Configuration Plugin DOX
+
+## Purpose
+
+- Own LLM model selection, presets, API-key checks, scoped overrides, and model settings UI.
+
+## Ownership
+
+- `helpers/model_config.py` owns config resolution, presets, overrides, and runtime model object construction.
+- `api/` owns model config, override, preset, search, and API-key endpoints.
+- `webui/` owns model settings, summaries, switcher, and API-key UI.
+- `default_config.yaml`, `default_presets.yaml`, `provider_metadata.yaml`, `hooks.py`, and `plugin.yaml` own defaults, metadata, hooks, and manifest.
+
+## Local Contracts
+
+- Preserve global, project, agent, and chat override resolution order.
+- Keep provider metadata and API-key checks safe around secrets.
+- Coordinate OAuth-backed providers with `_oauth` instead of hardcoding provider-specific auth here.
+
+## Work Guidance
+
+- Keep backend model config shape and frontend settings fields synchronized.
+
+## Verification
+
+- Run model-config and onboarding-related tests when model provider, preset, or API-key behavior changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_office/AGENTS.md b/plugins/_office/AGENTS.md
new file mode 100644
index 000000000..2e0c54b0e
--- /dev/null
+++ b/plugins/_office/AGENTS.md
@@ -0,0 +1,30 @@
+# LibreOffice Plugin DOX
+
+## Purpose
+
+- Own ODF-first LibreOffice office artifact workflows for Writer, Calc, and Impress files.
+
+## Ownership
+
+- `tools/office_artifact.py` owns the agent-facing office artifact tool.
+- `helpers/` owns artifact editing, canvas context, document storage, LibreOffice runtime, and presentation writing.
+- `api/` owns office session and WebSocket handlers.
+- `hooks.py`, `prompts/`, `skills/`, `extensions/`, and `webui/` own lifecycle behavior, prompts, skill guidance, hooks, and office panel UI.
+
+## Local Contracts
+
+- Preserve document storage integrity and live session synchronization.
+- Keep LibreOffice operations bounded to intended workspaces and artifact paths.
+- Do not expose document contents or temporary files beyond intended UI/tool flows.
+
+## Work Guidance
+
+- Coordinate tool, session, and panel changes so canvas state reflects document state.
+
+## Verification
+
+- Smoke-test creating, editing, previewing, and reconnecting office artifact sessions after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_onboarding/AGENTS.md b/plugins/_onboarding/AGENTS.md
new file mode 100644
index 000000000..3bfcd8d2c
--- /dev/null
+++ b/plugins/_onboarding/AGENTS.md
@@ -0,0 +1,28 @@
+# Onboarding Plugin DOX
+
+## Purpose
+
+- Own the built-in first-time onboarding wizard for model configuration.
+
+## Ownership
+
+- `plugin.yaml` owns metadata and always-enabled status.
+- `webui/` owns onboarding providers, wizard store, modal/page markup, and thumbnail.
+
+## Local Contracts
+
+- Keep onboarding provider choices synchronized with model configuration and provider metadata.
+- Do not ask for or expose API keys outside approved settings/API flows.
+- Avoid blocking already-configured users with unnecessary onboarding prompts.
+
+## Work Guidance
+
+- Coordinate provider changes with `_model_config` and `_oauth` when account-backed providers are involved.
+
+## Verification
+
+- Smoke-test first-run onboarding, provider selection, completion, and skip/close behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_plugin_installer/AGENTS.md b/plugins/_plugin_installer/AGENTS.md
new file mode 100644
index 000000000..6e213ec7e
--- /dev/null
+++ b/plugins/_plugin_installer/AGENTS.md
@@ -0,0 +1,30 @@
+# Plugin Installer DOX
+
+## Purpose
+
+- Own installing and updating plugins from ZIP uploads, Git repositories, and the community Plugin Index.
+
+## Ownership
+
+- `helpers/install.py` owns archive extraction, Git install/update, validation, hook execution, and install finalization.
+- `api/plugin_install.py` owns install/update/index API dispatch.
+- `webui/` owns Plugin Hub, ZIP, Git, detail, and shared install UI.
+- `plugin.yaml` and `README.md` own metadata and behavior notes.
+
+## Local Contracts
+
+- Install third-party plugins into `usr/plugins/`, not bundled `plugins/`.
+- Reject unsafe archive paths, missing manifests, invalid manifests, and plugin name conflicts.
+- Run plugin install hooks and refresh plugin state after successful changes.
+
+## Work Guidance
+
+- Keep installer validation aligned with plugin contracts and Plugin Index expectations.
+
+## Verification
+
+- Smoke-test ZIP install, Git install, Plugin Hub install, and Git update paths after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_plugin_scan/AGENTS.md b/plugins/_plugin_scan/AGENTS.md
new file mode 100644
index 000000000..c51293e84
--- /dev/null
+++ b/plugins/_plugin_scan/AGENTS.md
@@ -0,0 +1,30 @@
+# Plugin Scanner DOX
+
+## Purpose
+
+- Own LLM-guided security scanning for third-party Agent Zero plugins.
+
+## Ownership
+
+- `helpers/prompt.py` owns scan prompt construction from selectable checks.
+- `api/` owns scan queue, start, and synchronous run endpoints.
+- `webui/` owns scan checks, prompt template, store, UI, and thumbnail.
+- `plugin.yaml` and `README.md` own metadata and behavior notes.
+
+## Local Contracts
+
+- Keep scan prompts explicit about source handling, security categories, and report expectations.
+- Temporary scan contexts must be isolated and cleaned up as intended.
+- Do not install or execute scanned plugin code as part of scanning unless explicitly designed and documented.
+
+## Work Guidance
+
+- Coordinate check schema changes with prompt builder and frontend selection UI.
+
+## Verification
+
+- Smoke-test a synchronous scan and selected-check scan after prompt or API changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_plugin_validator/AGENTS.md b/plugins/_plugin_validator/AGENTS.md
new file mode 100644
index 000000000..abd194f30
--- /dev/null
+++ b/plugins/_plugin_validator/AGENTS.md
@@ -0,0 +1,30 @@
+# Plugin Validator DOX
+
+## Purpose
+
+- Own structured validation of Agent Zero plugins against manifest, structure, code-pattern, and security conventions.
+
+## Ownership
+
+- `helpers/prompt.py` owns validation prompt construction.
+- `api/` owns ZIP preparation, queue, start, and synchronous run endpoints.
+- `webui/` owns validation checks, guidance, prompt template, store, UI, and thumbnail.
+- `plugin.yaml` and `README.md` own metadata and behavior notes.
+
+## Local Contracts
+
+- Keep validation criteria aligned with `plugins/AGENTS.md`, WebUI contracts, and Plugin Index requirements.
+- Temporary validation source directories and contexts must be cleaned up as intended.
+- Do not confuse runtime `plugin.yaml` with Plugin Index `index.yaml`.
+
+## Work Guidance
+
+- Coordinate checklist changes with prompt builder and frontend check selection.
+
+## Verification
+
+- Smoke-test local, Git, and ZIP validation paths when API or prompt behavior changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_promptinclude/AGENTS.md b/plugins/_promptinclude/AGENTS.md
new file mode 100644
index 000000000..8fab1b39f
--- /dev/null
+++ b/plugins/_promptinclude/AGENTS.md
@@ -0,0 +1,30 @@
+# Prompt Include Plugin DOX
+
+## Purpose
+
+- Own automatic prompt injection of persistent behavioral rules and preferences from `*.promptinclude.md` files.
+
+## Ownership
+
+- `helpers/scanner.py` owns workspace scanning, ignore handling, token budgeting, and trimming.
+- `prompts/` owns prompt-inclusion fragments.
+- `extensions/` owns prompt injection hooks.
+- `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own defaults, metadata, behavior notes, and settings UI.
+
+## Local Contracts
+
+- Respect gitignore-style filtering, per-file budgets, and total token budgets.
+- Include only intended promptinclude files from configured workspaces.
+- Keep scan result status fields accurate for skipped, cropped, and included files.
+
+## Work Guidance
+
+- Coordinate scanner changes with prompt fragments so included content is clearly attributed.
+
+## Verification
+
+- Smoke-test include, ignore, crop, and over-budget cases after scanner changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_skills/AGENTS.md b/plugins/_skills/AGENTS.md
new file mode 100644
index 000000000..1371f2bf9
--- /dev/null
+++ b/plugins/_skills/AGENTS.md
@@ -0,0 +1,31 @@
+# Skills Plugin DOX
+
+## Purpose
+
+- Own active and hidden skill configuration injected into prompt extras on each turn.
+
+## Ownership
+
+- `hooks.py` owns skill prompt injection and plugin lifecycle behavior.
+- `api/skills_catalog.py` owns skill catalog access.
+- `prompts/agent.system.active_skills.md` owns injected active-skill prompt content.
+- `webui/` owns skill settings UI and store.
+- `default_config.yaml`, `plugin.yaml`, `README.md`, and `LICENSE` own defaults, metadata, docs, and license.
+
+## Local Contracts
+
+- Keep active skill lists bounded by configured caps.
+- Store configured skills in normalized portable paths.
+- Hidden skills affect catalog/search/load visibility but must not be injected as active prompt content.
+
+## Work Guidance
+
+- Coordinate active-skill resolution changes with core skill loading and settings UI.
+
+## Verification
+
+- Run skill runtime/catalog tests or smoke-test active, hidden, global, project, and chat-scope behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_telegram_integration/AGENTS.md b/plugins/_telegram_integration/AGENTS.md
new file mode 100644
index 000000000..bbbc062f0
--- /dev/null
+++ b/plugins/_telegram_integration/AGENTS.md
@@ -0,0 +1,30 @@
+# Telegram Integration Plugin DOX
+
+## Purpose
+
+- Own Telegram bot integration for Agent Zero with polling, webhook, per-user sessions, and file exchange.
+
+## Ownership
+
+- `helpers/bot_manager.py` owns bot lifecycle.
+- `helpers/handler.py` and `helpers/telegram_client.py` own message routing, replies, and Telegram API interaction.
+- `helpers/dependencies.py` and `requirements.txt` own framework-runtime dependency bootstrap.
+- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own tests/webhook endpoints, prompt fragments, hooks, settings, metadata, docs, and UI.
+
+## Local Contracts
+
+- Treat bot tokens, chat IDs, attachments, and user data as sensitive.
+- Keep allowed-user, group-mode, project, model, and `/send` controls enforced.
+- Install Telegram dependencies into the framework runtime only when required.
+
+## Work Guidance
+
+- Coordinate bot lifecycle changes with job-loop hooks and settings reload behavior.
+
+## Verification
+
+- Smoke-test connection checks, polling or webhook delivery, per-user context reuse, attachments, and replies when practical.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_text_editor/AGENTS.md b/plugins/_text_editor/AGENTS.md
new file mode 100644
index 000000000..f18d552d3
--- /dev/null
+++ b/plugins/_text_editor/AGENTS.md
@@ -0,0 +1,30 @@
+# Text Editor Plugin DOX
+
+## Purpose
+
+- Own the native LLM-friendly text editing tool for reading, writing, and patching text files.
+
+## Ownership
+
+- `tools/text_editor.py` owns method dispatch and agent-facing tool behavior.
+- `helpers/` owns file operations, patch requests, context patching, stale-read tracking, and patch state.
+- `prompts/` owns read/write/patch success and error messages.
+- `default_config.yaml`, `plugin.yaml`, `README.md`, `extensions/`, and `webui/` own defaults, metadata, docs, hooks, and config UI.
+
+## Local Contracts
+
+- Preserve stale-read protection before patch operations.
+- Validate patch structures before applying edits.
+- Read back changed regions after writes or patches where the tool contract requires confirmation.
+
+## Work Guidance
+
+- Coordinate helper changes with prompt responses so the agent receives actionable edit feedback.
+
+## Verification
+
+- Smoke-test read, write, patch, stale-read rejection, and error handling after tool changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_time_travel/AGENTS.md b/plugins/_time_travel/AGENTS.md
new file mode 100644
index 000000000..0998d949f
--- /dev/null
+++ b/plugins/_time_travel/AGENTS.md
@@ -0,0 +1,30 @@
+# Time Travel Plugin DOX
+
+## Purpose
+
+- Own Agent Zero workspace history, diff inspection, travel, snapshots, and revert for active `/a0/usr` workspaces.
+
+## Ownership
+
+- `helpers/time_travel.py` owns history storage, diff, travel, snapshot, preview, and revert mechanics.
+- `api/` owns history list, diff, preview, revert, snapshot, and travel endpoints.
+- `webui/` owns the time-travel panel, store, main surface, and thumbnail.
+- `plugin.yaml` and `extensions/` own metadata and hook contributions.
+
+## Local Contracts
+
+- Keep history operations scoped to Agent Zero-owned workspaces.
+- Revert and travel operations must avoid unintended writes outside managed workspace paths.
+- Preserve enough metadata for clear preview and diff inspection before destructive actions.
+
+## Work Guidance
+
+- Coordinate API and UI changes so users can inspect effects before applying travel or revert operations.
+
+## Verification
+
+- Smoke-test snapshot, list, diff, preview, travel, and revert flows after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_whatsapp_integration/AGENTS.md b/plugins/_whatsapp_integration/AGENTS.md
new file mode 100644
index 000000000..ebb14eef4
--- /dev/null
+++ b/plugins/_whatsapp_integration/AGENTS.md
@@ -0,0 +1,31 @@
+# WhatsApp Integration Plugin DOX
+
+## Purpose
+
+- Own WhatsApp communication through a Baileys-based Node.js bridge.
+
+## Ownership
+
+- `helpers/bridge_manager.py` owns bridge lifecycle.
+- `helpers/handler.py` and `helpers/wa_client.py` own message routing and bridge API interaction.
+- `helpers/storage_paths.py`, attachment helpers, and number utilities own storage, attachment, and phone-number handling.
+- `whatsapp-bridge/` owns the Node.js bridge package.
+- `api/`, `prompts/`, `extensions/`, `default_config.yaml`, `plugin.yaml`, `README.md`, and `webui/` own QR/start/disconnect/test endpoints, prompt fragments, hooks, settings, metadata, docs, and UI.
+
+## Local Contracts
+
+- Treat WhatsApp sessions, QR data, phone numbers, attachments, and bridge state as sensitive.
+- Keep allowed-number and group-response controls enforced.
+- Do not leave unmanaged bridge services outside plugin-owned runtime paths.
+
+## Work Guidance
+
+- Coordinate Node bridge changes with Python bridge client and settings UI.
+
+## Verification
+
+- Smoke-test dependency install, bridge start, QR pairing, allowed-number filtering, message routing, and replies when practical.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/plugins/_whisper_stt/AGENTS.md b/plugins/_whisper_stt/AGENTS.md
new file mode 100644
index 000000000..4509ccb5a
--- /dev/null
+++ b/plugins/_whisper_stt/AGENTS.md
@@ -0,0 +1,31 @@
+# Whisper STT Plugin DOX
+
+## Purpose
+
+- Own built-in Whisper speech-to-text integration, microphone runtime settings, and transcription delivery behavior.
+
+## Ownership
+
+- `api/` owns transcribe and status endpoints.
+- `helpers/` owns runtime and migration behavior.
+- `hooks.py` owns provider registration/lifecycle behavior.
+- `webui/` owns settings, main speech UI, store, and styling.
+- `default_config.yaml`, `plugin.yaml`, and `README.md` own defaults, metadata, and behavior notes.
+
+## Local Contracts
+
+- Keep dependency installation and model bootstrap on Docker/bootstrap paths.
+- Preserve configured message mode, language, silence threshold, silence duration, and waiting timeout behavior.
+- Do not expose raw audio or transcriptions beyond intended UI/API paths.
+
+## Work Guidance
+
+- Coordinate status endpoint behavior with frontend microphone and transcription state.
+
+## Verification
+
+- Smoke-test status, transcription, model/language settings, send/draft modes, and silence handling after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/AGENTS.md b/skills/AGENTS.md
index 92f7a9dd0..28cc26b15 100644
--- a/skills/AGENTS.md
+++ b/skills/AGENTS.md
@@ -31,4 +31,17 @@
## Child DOX Index
-No child DOX files.
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [a0-contribute-plugin/AGENTS.md](a0-contribute-plugin/AGENTS.md) | Publishing plugins to the community Plugin Index. |
+| [a0-create-agent/AGENTS.md](a0-create-agent/AGENTS.md) | Creating Agent Zero agent profiles. |
+| [a0-create-plugin/AGENTS.md](a0-create-plugin/AGENTS.md) | Creating or extending Agent Zero plugins. |
+| [a0-debug-plugin/AGENTS.md](a0-debug-plugin/AGENTS.md) | Diagnosing plugin loading, API, frontend, and extension issues. |
+| [a0-development/AGENTS.md](a0-development/AGENTS.md) | Broad Agent Zero framework development guidance. |
+| [a0-manage-plugin/AGENTS.md](a0-manage-plugin/AGENTS.md) | Plugin install, update, scan, enable, disable, and removal workflows. |
+| [a0-plugin-router/AGENTS.md](a0-plugin-router/AGENTS.md) | Routing plugin-related user requests to specialist skills. |
+| [a0-review-plugin/AGENTS.md](a0-review-plugin/AGENTS.md) | Full plugin audit workflow and checklists. |
+| [build-skill/AGENTS.md](build-skill/AGENTS.md) | Building and improving Agent Zero skills. |
+| [scheduled-tasks/AGENTS.md](scheduled-tasks/AGENTS.md) | Managing scheduled, planned, and adhoc tasks. |
diff --git a/skills/a0-contribute-plugin/AGENTS.md b/skills/a0-contribute-plugin/AGENTS.md
new file mode 100644
index 000000000..2067e5306
--- /dev/null
+++ b/skills/a0-contribute-plugin/AGENTS.md
@@ -0,0 +1,29 @@
+# Plugin Contribution Skill DOX
+
+## Purpose
+
+- Own the workflow for publishing an Agent Zero plugin to the community Plugin Index.
+- Keep contribution guidance aligned with current Plugin Hub and `a0-plugins` repository requirements.
+
+## Ownership
+
+- `SKILL.md` owns trigger metadata and the contribution procedure.
+
+## Local Contracts
+
+- Keep repository, `index.yaml`, manifest, license, validation, and PR guidance current.
+- Do not hardcode user credentials, personal repository names, or private URLs.
+- Keep handoffs to plugin review and management skills accurate.
+
+## Work Guidance
+
+- Update this skill when Plugin Index CI rules, manifest expectations, or submission flow changes.
+- Prefer concise command examples that a user can adapt.
+
+## Verification
+
+- Manually read `SKILL.md` for broken links, stale paths, and invalid relative references.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/a0-create-agent/AGENTS.md b/skills/a0-create-agent/AGENTS.md
new file mode 100644
index 000000000..bb455953b
--- /dev/null
+++ b/skills/a0-create-agent/AGENTS.md
@@ -0,0 +1,29 @@
+# Agent Creation Skill DOX
+
+## Purpose
+
+- Own the workflow for creating Agent Zero agent profiles.
+- Keep guidance for user, plugin-distributed, and project-scoped profiles accurate.
+
+## Ownership
+
+- `SKILL.md` owns trigger metadata, intake flow, profile blueprint schema, and file creation guidance.
+
+## Local Contracts
+
+- Default new user profiles to `usr/agents/`, not bundled `agents/`.
+- Keep `agent.yaml`, prompt inheritance, tools, and extension guidance synchronized with profile loader behavior.
+- Do not encourage storing secrets or provider credentials in profiles.
+
+## Work Guidance
+
+- Keep intake lightweight and progressive for user-facing profile creation.
+- Update examples when the bundled `_example/` or profile schema changes.
+
+## Verification
+
+- Manually read `SKILL.md` for stale paths and blueprint/schema drift.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/a0-create-plugin/AGENTS.md b/skills/a0-create-plugin/AGENTS.md
new file mode 100644
index 000000000..758c25df9
--- /dev/null
+++ b/skills/a0-create-plugin/AGENTS.md
@@ -0,0 +1,29 @@
+# Plugin Creation Skill DOX
+
+## Purpose
+
+- Own the workflow for creating, extending, or modifying Agent Zero plugins.
+- Keep full-stack plugin conventions accurate for API, tools, extensions, settings UI, and WebUI integration.
+
+## Ownership
+
+- `SKILL.md` owns trigger metadata, plugin scaffold guidance, manifest rules, and frontend/backend patterns.
+
+## Local Contracts
+
+- New custom plugins must default to `usr/plugins/`.
+- Keep plugin manifest, settings, extension layout, Store Gating, and notification guidance synchronized with `plugins/AGENTS.md` and WebUI contracts.
+- Do not recommend hardcoding secrets, bypassing auth, or persistent unmanaged side effects.
+
+## Work Guidance
+
+- Update this skill when plugin loader, Plugin Hub, settings modal, extension, or WebUI patterns change.
+- Keep code examples short and aligned with current helper APIs.
+
+## Verification
+
+- Manually read `SKILL.md` for stale paths and broken handoffs to related plugin skills.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/a0-debug-plugin/AGENTS.md b/skills/a0-debug-plugin/AGENTS.md
new file mode 100644
index 000000000..42abc66c3
--- /dev/null
+++ b/skills/a0-debug-plugin/AGENTS.md
@@ -0,0 +1,28 @@
+# Plugin Debug Skill DOX
+
+## Purpose
+
+- Own the troubleshooting workflow for Agent Zero plugin loading, activation, API, frontend, extension, settings, and hook problems.
+
+## Ownership
+
+- `SKILL.md` owns diagnostic order, commands, and common failure cases.
+
+## Local Contracts
+
+- Keep route formats, import guidance, extension layouts, toggle files, and settings resolution aligned with runtime behavior.
+- Do not recommend destructive cleanup unless the user explicitly asks and the target is clear.
+- Keep diagnostics safe around secrets and local user data.
+
+## Work Guidance
+
+- Add checks when new plugin surfaces or loader failure modes are introduced.
+- Prefer targeted commands that identify the first failing layer.
+
+## Verification
+
+- Manually read `SKILL.md` for stale commands and plugin path assumptions.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/a0-development/AGENTS.md b/skills/a0-development/AGENTS.md
new file mode 100644
index 000000000..b53fd4cc0
--- /dev/null
+++ b/skills/a0-development/AGENTS.md
@@ -0,0 +1,29 @@
+# Development Skill DOX
+
+## Purpose
+
+- Own the broad Agent Zero development guide used by agents extending the framework.
+- Keep architecture, tools, extensions, API, agents, prompts, projects, and skills guidance in sync with the repository.
+
+## Ownership
+
+- `SKILL.md` owns the development overview, path conventions, and implementation references.
+
+## Local Contracts
+
+- Keep paths and examples current with source files and DOX contracts.
+- Route plugin-specific tasks to the plugin router or specialist plugin skills.
+- Do not duplicate long contracts that belong in narrower AGENTS.md files when a reference is enough.
+
+## Work Guidance
+
+- Update this skill after durable framework workflow, extension, tool, API, prompt, or profile changes.
+- Keep examples operational and compatible with the current helper classes.
+
+## Verification
+
+- Manually read `SKILL.md` for stale architecture references and broken related-skill links.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/a0-manage-plugin/AGENTS.md b/skills/a0-manage-plugin/AGENTS.md
new file mode 100644
index 000000000..144b4636f
--- /dev/null
+++ b/skills/a0-manage-plugin/AGENTS.md
@@ -0,0 +1,28 @@
+# Plugin Management Skill DOX
+
+## Purpose
+
+- Own the workflow for browsing, scanning, installing, updating, enabling, disabling, and uninstalling Agent Zero plugins.
+
+## Ownership
+
+- `SKILL.md` owns management routing, Plugin Hub usage, security scan guidance, and lifecycle commands.
+
+## Local Contracts
+
+- Keep Plugin Hub URLs, install API behavior, scan expectations, and activation semantics current.
+- Warn about third-party plugin execution risk before install workflows.
+- Do not recommend unmanaged deletion outside plugin-owned paths.
+
+## Work Guidance
+
+- Update this skill when installer, scanner, validator, Plugin Index, or toggle behavior changes.
+- Keep diagnostics and install examples consistent with plugin helper APIs.
+
+## Verification
+
+- Manually read `SKILL.md` for stale endpoints, paths, and security guidance.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/a0-plugin-router/AGENTS.md b/skills/a0-plugin-router/AGENTS.md
new file mode 100644
index 000000000..72d8f5331
--- /dev/null
+++ b/skills/a0-plugin-router/AGENTS.md
@@ -0,0 +1,29 @@
+# Plugin Router Skill DOX
+
+## Purpose
+
+- Own routing for Agent Zero plugin-related user requests.
+- Keep handoffs to plugin creation, review, contribution, management, and debugging skills accurate.
+
+## Ownership
+
+- `SKILL.md` owns intent classification, routing table, and concise plugin system overview.
+
+## Local Contracts
+
+- Keep related skill names and responsibilities synchronized with the actual skill directories.
+- Keep plugin root, discovery, manifest, and extension layout summaries aligned with `plugins/AGENTS.md`.
+- Ask only when plugin intent is ambiguous.
+
+## Work Guidance
+
+- Update this skill when plugin lifecycle skills are renamed, added, or reorganized.
+- Keep the overview brief enough to serve routing, not replace specialist skills.
+
+## Verification
+
+- Manually read `SKILL.md` for stale skill paths and routing gaps.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/a0-review-plugin/AGENTS.md b/skills/a0-review-plugin/AGENTS.md
new file mode 100644
index 000000000..be2637ef0
--- /dev/null
+++ b/skills/a0-review-plugin/AGENTS.md
@@ -0,0 +1,30 @@
+# Plugin Review Skill DOX
+
+## Purpose
+
+- Own the full audit workflow for Agent Zero plugins.
+- Keep manifest, structure, code-pattern, security, and duplicate-detection checks current.
+
+## Ownership
+
+- `SKILL.md` owns the review workflow and phase order.
+- `checklists.md` owns detailed review criteria loaded when needed.
+
+## Local Contracts
+
+- Keep review checks aligned with current plugin contracts, WebUI patterns, and Plugin Index expectations.
+- Treat user plugins as `usr/plugins/` artifacts unless explicitly reviewing bundled core plugins.
+- Do not expose secrets or private plugin data in review output.
+
+## Work Guidance
+
+- Update both `SKILL.md` and `checklists.md` when plugin conventions or security expectations change.
+- Keep findings actionable and grouped by review phase.
+
+## Verification
+
+- Manually read changed skill files for stale paths, duplicated checks, and broken references.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/build-skill/AGENTS.md b/skills/build-skill/AGENTS.md
new file mode 100644
index 000000000..c591f6511
--- /dev/null
+++ b/skills/build-skill/AGENTS.md
@@ -0,0 +1,30 @@
+# Build Skill DOX
+
+## Purpose
+
+- Own the workflow for creating, improving, auditing, and refactoring Agent Zero skills.
+- Keep skill format guidance aligned with runtime discovery and loading.
+
+## Ownership
+
+- `SKILL.md` owns standard skill shape, writing rules, placement rules, and validation guidance.
+
+## Local Contracts
+
+- Every skill folder must contain `SKILL.md`.
+- Keep frontmatter and directory-shape guidance synchronized with skill loader behavior.
+- Prefer plugin-scoped skills when the workflow is owned by a plugin.
+
+## Work Guidance
+
+- Update this skill when skill metadata, discovery, or validation behavior changes.
+- Keep examples concise and avoid duplicating long reference material in the skill body.
+
+## Verification
+
+- Manually read `SKILL.md` for stale test commands and format assumptions.
+- Run skill runtime tests when changing skill loader contracts.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/skills/scheduled-tasks/AGENTS.md b/skills/scheduled-tasks/AGENTS.md
new file mode 100644
index 000000000..2902a7c93
--- /dev/null
+++ b/skills/scheduled-tasks/AGENTS.md
@@ -0,0 +1,29 @@
+# Scheduled Tasks Skill DOX
+
+## Purpose
+
+- Own the workflow for managing Agent Zero scheduled, planned, and adhoc tasks.
+- Keep scheduler tool usage and date/time guidance accurate.
+
+## Ownership
+
+- `SKILL.md` owns scheduler action descriptions, schedule field guidance, safety rules, and examples.
+
+## Local Contracts
+
+- Inspect existing tasks before create, update, delete, or run operations.
+- Use cron-like `schedule` fields for recurring tasks and ISO datetimes in `plan` for planned tasks.
+- Do not create recursive scheduling prompts or run scheduled tasks unless the user asks.
+
+## Work Guidance
+
+- Update this skill when scheduler tool actions, field names, or timezone behavior changes.
+- Keep examples valid JSON tool arguments.
+
+## Verification
+
+- Manually read `SKILL.md` for stale scheduler action names and date guidance.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tests/test_dirty_json.py b/tests/test_dirty_json.py
index 011b23d5f..2715366e9 100644
--- a/tests/test_dirty_json.py
+++ b/tests/test_dirty_json.py
@@ -54,3 +54,42 @@ def test_completed_remains_true_after_trailing_content() -> None:
}
assert parser.completed is True
+
+
+def test_value_keeps_unescaped_markdown_quotes_until_structural_delimiter() -> None:
+ payload = (
+ "{\n"
+ ' "tool_name": "response",\n'
+ ' "tool_args": {\n'
+ ' "text": "The rule:\\n\\n> *"'
+ 'Create a child AGENTS.md when a folder becomes a boundary."'
+ '*\\n\\nAdding `css/AGENTS.md` that says *"'
+ 'this folder contains CSS"'
+ '* is duplication."\n'
+ " }\n"
+ "}"
+ )
+
+ parsed = DirtyJson.parse_string(payload)
+
+ assert parsed["tool_args"] == {
+ "text": (
+ "The rule:\n\n"
+ '> *"Create a child AGENTS.md when a folder becomes a boundary."*\n\n'
+ 'Adding `css/AGENTS.md` that says *"this folder contains CSS"* is duplication.'
+ )
+ }
+
+
+def test_value_keeps_unescaped_quotes_on_single_line() -> None:
+ parsed = DirtyJson.parse_string(
+ '{"text":"He said "hello" before closing","ok":true}'
+ )
+
+ assert parsed == {"text": 'He said "hello" before closing', "ok": True}
+
+
+def test_value_can_still_end_before_quoted_key_when_comma_is_missing() -> None:
+ parsed = DirtyJson.parse_string('{"first":"one" "second":"two"}')
+
+ assert parsed == {"first": "one", "second": "two"}
diff --git a/tools/AGENTS.md b/tools/AGENTS.md
index ed3cc8a37..0218740e0 100644
--- a/tools/AGENTS.md
+++ b/tools/AGENTS.md
@@ -18,17 +18,23 @@
- Use `await self.agent.handle_intervention(...)` when a long-running or external result should respect pause/intervention flow.
- Sanitize or mask secrets before logging, returning, or storing tool outputs.
- Do not perform destructive filesystem or network actions without the tool contract making that behavior explicit.
+- This directory is a file-documented DOX profile: every direct `*.py` tool 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 tool purpose, tool arguments/concepts, output and `break_loop` behavior, side effects, important helper dependencies, prompt-contract notes, and verification guidance.
+- When a tool module 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 tool deletion or rename.
## Work Guidance
- Keep tool output concise enough for message history while preserving actionable detail.
- Put reusable parsing, provider, filesystem, or network logic in `helpers/`.
- Update prompt tool instructions when changing tool names, arguments, or behavior.
+- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed tool behavior is described there.
## Verification
- Run targeted tool tests after changing a tool or its prompt contract.
- Run prompt/snapshot tests when tool instructions or output shape changes.
+- Check file-level documentation coverage with a script or shell loop that verifies each `tools/*.py` has a matching `tools/*.py.dox.md`.
## Child DOX Index
diff --git a/tools/a2a_chat.py.dox.md b/tools/a2a_chat.py.dox.md
new file mode 100644
index 000000000..78d6ae143
--- /dev/null
+++ b/tools/a2a_chat.py.dox.md
@@ -0,0 +1,51 @@
+# a2a_chat.py DOX
+
+## Purpose
+
+- Own the `a2a_chat.py` agent tool.
+- This module lets the agent message an external A2A agent and extract the assistant reply.
+- Keep this file-level DOX profile synchronized with `a2a_chat.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `a2a_chat.py` owns the runtime implementation.
+- `a2a_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `A2AChatTool` (`Tool`)
+ - `async execute(self, **kwargs)`
+- Top-level functions:
+- `_session_key(agent_url: str) -> str`: Keep root and explicit /a2a URLs in the same conversation cache.
+- `_text_from_part(part: Any) -> str`
+- `_text_from_message(message: Any) -> str`
+- `_extract_latest_assistant_text(task_response: Any) -> str`
+- Notable constants/configuration names: `A2A_EMPTY_RESPONSE_ERROR`.
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `A2AChatTool` is a `Tool`.
+- `A2AChatTool` defines `execute(...)`.
+- Observed side-effect areas: filesystem writes, scheduler state.
+- Imported dependency areas include: `helpers.fasta2a_client`, `helpers.print_style`, `helpers.tool`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `agent_url.rstrip`, `normalized.endswith`, `_text_from_message`, `normalized.rstrip`, `message.strip`, `join`, `_session_key`, `value.strip`, `_text_from_part`, `is_client_available`, `Response`, `self.agent.get_data`, `sessions.pop`, `_extract_latest_assistant_text`, `PrintStyle.error`, `connect_to_agent`, `conn.send_message`, `conn.wait_for_completion`, `self.agent.set_data`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_tool_action_contracts.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/call_subordinate.py.dox.md b/tools/call_subordinate.py.dox.md
new file mode 100644
index 000000000..544873f0b
--- /dev/null
+++ b/tools/call_subordinate.py.dox.md
@@ -0,0 +1,46 @@
+# call_subordinate.py DOX
+
+## Purpose
+
+- Own the `call_subordinate.py` agent tool.
+- This module delegates work to a subordinate Agent Zero profile and returns its result.
+- Keep this file-level DOX profile synchronized with `call_subordinate.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `call_subordinate.py` owns the runtime implementation.
+- `call_subordinate.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Delegation` (`Tool`)
+ - `async execute(self, message=..., reset=..., **kwargs)`
+ - `get_log_object(self)`
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `Delegation` is a `Tool`.
+- `Delegation` defines `execute(...)`.
+- Observed side-effect areas: filesystem writes, settings/state persistence.
+- Imported dependency areas include: `agent`, `extensions.python.hist_add_tool_result`, `helpers.tool`, `initialize`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self.agent.get_data`, `subordinate.hist_add_user_message`, `subordinate.history.new_topic`, `Response`, `self.agent.context.log.log`, `initialize_agent`, `Agent`, `sub.set_data`, `self.agent.set_data`, `UserMessage`, `subordinate.monologue`, `self.agent.read_prompt`, `str.lower.strip`, `str.lower`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_default_prompt_budget.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/document_query.py.dox.md b/tools/document_query.py.dox.md
new file mode 100644
index 000000000..dea7310d7
--- /dev/null
+++ b/tools/document_query.py.dox.md
@@ -0,0 +1,41 @@
+# document_query.py DOX
+
+## Purpose
+
+- Own the `document_query.py` agent tool.
+- This module loads and queries documents through the document query plugin compatibility path.
+- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `document_query.py` owns the runtime implementation.
+- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- Observed side-effect areas: plugin state.
+- Imported dependency areas include: `plugins._document_query.tools.document_query`.
+
+## 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
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_document_query_fallback.py`
+ - `tests/test_document_query_plugin.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/notify_user.py.dox.md b/tools/notify_user.py.dox.md
new file mode 100644
index 000000000..17cc9a44f
--- /dev/null
+++ b/tools/notify_user.py.dox.md
@@ -0,0 +1,44 @@
+# notify_user.py DOX
+
+## Purpose
+
+- Own the `notify_user.py` agent tool.
+- This module sends a user-facing notification from the agent.
+- Keep this file-level DOX profile synchronized with `notify_user.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `notify_user.py` owns the runtime implementation.
+- `notify_user.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `NotifyUserTool` (`Tool`)
+ - `async execute(self, **kwargs)`
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `NotifyUserTool` is a `Tool`.
+- `NotifyUserTool` defines `execute(...)`.
+- Imported dependency areas include: `agent`, `helpers.notification`, `helpers.tool`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager.add_notification`, `Response`, `NotificationType`, `NotificationPriority`, `AgentContext.get_notification_manager`, `self.agent.read_prompt`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_tool_action_contracts.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/response.py.dox.md b/tools/response.py.dox.md
new file mode 100644
index 000000000..a2d18ac0d
--- /dev/null
+++ b/tools/response.py.dox.md
@@ -0,0 +1,53 @@
+# response.py DOX
+
+## Purpose
+
+- Own the `response.py` agent tool.
+- This module emits the final or intermediate agent response to the user.
+- Keep this file-level DOX profile synchronized with `response.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `response.py` owns the runtime implementation.
+- `response.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `ResponseTool` (`Tool`)
+ - `async execute(self, **kwargs)`
+ - `async before_execution(self, **kwargs)`
+ - `async after_execution(self, response, **kwargs)`
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `ResponseTool` is a `Tool`.
+- `ResponseTool` defines `execute(...)`.
+- Imported dependency areas include: `helpers.tool`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Response`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/chunk_parser_test.py`
+ - `tests/rate_limiter_test.py`
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_chat_compaction.py`
+ - `tests/test_dirty_json.py`
+ - `tests/test_download_toast_regressions.py`
+ - `tests/test_fasta2a_client.py`
+ - `tests/test_fastmcp_openapi_security.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/scheduler.py.dox.md b/tools/scheduler.py.dox.md
new file mode 100644
index 000000000..a36f2bc07
--- /dev/null
+++ b/tools/scheduler.py.dox.md
@@ -0,0 +1,63 @@
+# scheduler.py DOX
+
+## Purpose
+
+- Own the `scheduler.py` agent tool.
+- This module creates, updates, lists, runs, waits for, and deletes scheduled/planned/adhoc tasks.
+- Keep this file-level DOX profile synchronized with `scheduler.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `scheduler.py` owns the runtime implementation.
+- `scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SchedulerTool` (`Tool`)
+ - `async execute(self, **kwargs)`
+ - `async list_tasks(self, **kwargs) -> Response`
+ - `async find_task_by_name(self, **kwargs) -> Response`
+ - `async show_task(self, **kwargs) -> Response`
+ - `async run_task(self, **kwargs) -> Response`
+ - `async delete_task(self, **kwargs) -> Response`
+ - `async update_task(self, **kwargs) -> Response`
+ - `async create_scheduled_task(self, **kwargs) -> Response`
+- Top-level functions:
+- `_current_action(tool: Tool, kwargs: dict) -> str`
+- `_normalize_timezone(value: Any) -> str | None`
+- `_schedule_timezone(kwargs: dict) -> str | None`
+- `_task_schedule_from_input(schedule: Any, timezone: str | None=...) -> TaskSchedule`
+- `_validate_task_schedule(task_schedule: TaskSchedule) -> str`
+- `_task_plan_from_input(plan: Any) -> tuple[TaskPlan | None, str]`
+- Notable constants/configuration names: `DEFAULT_WAIT_TIMEOUT`, `LOCAL_TIMEZONE_ALIASES`.
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `SchedulerTool` is a `Tool`.
+- `SchedulerTool` defines `execute(...)`.
+- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
+- Imported dependency areas include: `agent`, `asyncio`, `datetime`, `helpers`, `helpers.localization`, `helpers.projects`, `helpers.task_scheduler`, `helpers.tool`, `json`, `pytz`, `random`, `re`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `str.strip`, `_normalize_timezone`, `TaskSchedule`, `task_schedule.to_crontab`, `timezone_name.lower`, `Localization.get.get_timezone`, `pytz.timezone`, `schedule.split`, `re.match`, `parse_datetime`, `TaskPlan.create`, `_current_action`, `get_context_project_name`, `TaskScheduler.get.get_tasks`, `Response`, `TaskScheduler.get.find_task_by_name`, `TaskScheduler.get.get_task_by_uuid`, `scheduler.get_task_by_uuid`, `self._resolve_project_metadata`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_task_scheduler_timezone.py`
+ - `tests/test_timezone_regressions.py`
+ - `tests/test_tool_action_contracts.py`
+ - `tests/test_tool_request_normalization.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/search_engine.py.dox.md b/tools/search_engine.py.dox.md
new file mode 100644
index 000000000..102ee68c4
--- /dev/null
+++ b/tools/search_engine.py.dox.md
@@ -0,0 +1,46 @@
+# search_engine.py DOX
+
+## Purpose
+
+- Own the `search_engine.py` agent tool.
+- This module runs web search through the configured search helper.
+- Keep this file-level DOX profile synchronized with `search_engine.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `search_engine.py` owns the runtime implementation.
+- `search_engine.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SearchEngine` (`Tool`)
+ - `async execute(self, query=..., **kwargs)`
+ - `async searxng_search(self, question)`
+ - `format_result_searxng(self, result, source)`
+- Notable constants/configuration names: `SEARCH_ENGINE_RESULTS`.
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `SearchEngine` is a `Tool`.
+- `SearchEngine` defines `execute(...)`.
+- Imported dependency areas include: `asyncio`, `helpers`, `helpers.errors`, `helpers.print_style`, `helpers.searxng`, `helpers.tool`, `os`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Response`, `self.format_result_searxng`, `join.strip`, `self.searxng_search`, `self.agent.handle_intervention`, `searxng`, `handle_error`, `join`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution 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.
diff --git a/tools/skills_tool.py.dox.md b/tools/skills_tool.py.dox.md
new file mode 100644
index 000000000..e93b91e50
--- /dev/null
+++ b/tools/skills_tool.py.dox.md
@@ -0,0 +1,51 @@
+# skills_tool.py DOX
+
+## Purpose
+
+- Own the `skills_tool.py` agent tool.
+- This module searches, loads, and lists Agent Zero skills for the agent.
+- Keep this file-level DOX profile synchronized with `skills_tool.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `skills_tool.py` owns the runtime implementation.
+- `skills_tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `SkillsTool` (`Tool`)
+ - `get_log_object(self)`
+ - `async before_execution(self, **kwargs)`
+ - `async execute(self, **kwargs) -> Response`
+- Top-level functions:
+- `max_loaded_skills() -> int`
+- Notable constants/configuration names: `DATA_NAME_LOADED_SKILLS`.
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `SkillsTool` is a `Tool`.
+- `SkillsTool` defines `execute(...)`.
+- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence.
+- Imported dependency areas include: `__future__`, `helpers`, `helpers.print_style`, `helpers.tool`, `pathlib`, `typing`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `skill_name.strip`, `super.get_log_object`, `self._normalize_skill_name`, `self.get_log_object`, `skills_helper.list_skills`, `join`, `skills_helper.search_skills`, `skills_helper.find_skill`, `skill.path.resolve`, `Path`, `resolved.read_text`, `skill_name.startswith`, `skill_name.endswith`, `self._current_action`, `self.agent.context.log.log`, `Response`, `strip`, `loaded.remove`, `target.is_absolute`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_tool_action_contracts.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/unknown.py.dox.md b/tools/unknown.py.dox.md
new file mode 100644
index 000000000..1264ab30f
--- /dev/null
+++ b/tools/unknown.py.dox.md
@@ -0,0 +1,48 @@
+# unknown.py DOX
+
+## Purpose
+
+- Own the `unknown.py` agent tool.
+- This module handles unknown or malformed tool-call requests.
+- Keep this file-level DOX profile synchronized with `unknown.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `unknown.py` owns the runtime implementation.
+- `unknown.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `Unknown` (`Tool`)
+ - `async execute(self, **kwargs)`
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `Unknown` is a `Tool`.
+- `Unknown` defines `execute(...)`.
+- Imported dependency areas include: `extensions.python.system_prompt._11_tools_prompt`, `helpers.tool`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Response`, `build_tools_prompt`, `self.agent.read_prompt`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_file_tree_visualize.py`
+ - `tests/test_oauth_providers.py`
+ - `tests/test_socketio_unknown_namespace.py`
+ - `tests/test_tunnel_remote_link.py`
+ - `tests/test_ws_manager.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/vision_load.py.dox.md b/tools/vision_load.py.dox.md
new file mode 100644
index 000000000..da9531242
--- /dev/null
+++ b/tools/vision_load.py.dox.md
@@ -0,0 +1,50 @@
+# vision_load.py DOX
+
+## Purpose
+
+- Own the `vision_load.py` agent tool.
+- This module loads images into model-visible content for vision-capable models.
+- Keep this file-level DOX profile synchronized with `vision_load.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `vision_load.py` owns the runtime implementation.
+- `vision_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `VisionLoad` (`Tool`)
+ - `async execute(self, paths: list[str]=..., **kwargs) -> Response`
+ - `async after_execution(self, response: Response, **kwargs)`
+- Notable constants/configuration names: `TOKENS_ESTIMATE`.
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `VisionLoad` is a `Tool`.
+- `VisionLoad` defines `execute(...)`.
+- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence, secret handling.
+- Imported dependency areas include: `helpers`, `helpers.print_style`, `helpers.tool`, `mimetypes`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `self._get_max_embeds`, `Response`, `str.strip`, `self._context_id`, `chat_media.infer_source`, `chat_media.category_for_source`, `chat_media.save_image_base64`, `chat_media.save_image_data_url`, `chat_media.materialize_image_ref`, `str.strip.lower`, `ephemeral_images.is_ref`, `cls._is_data_image_url`, `self._is_data_image_url`, `plugins.get_plugin_config`, `images.to_data_url`, `normalized.startswith`, `ephemeral_images.display_ref`, `join`, `self.agent.hist_add_tool_result`, `history.RawMessage`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
+- Related tests observed by source search:
+ - `tests/test_browser_agent_regressions.py`
+ - `tests/test_host_browser_connector.py`
+ - `tests/test_office_desktop_state.py`
+ - `tests/test_vision_load_image_refs.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/tools/wait.py.dox.md b/tools/wait.py.dox.md
new file mode 100644
index 000000000..1f2a461f8
--- /dev/null
+++ b/tools/wait.py.dox.md
@@ -0,0 +1,54 @@
+# wait.py DOX
+
+## Purpose
+
+- Own the `wait.py` agent tool.
+- This module lets the agent wait for a managed duration while respecting intervention flow.
+- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat.
+
+## Ownership
+
+- `wait.py` owns the runtime implementation.
+- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
+- Classes:
+- `WaitTool` (`Tool`)
+ - `async execute(self, **kwargs) -> Response`
+ - `get_log_object(self)`
+ - `get_heading(self, text: str=..., done: bool=...)`
+
+## Runtime Contracts
+
+- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
+- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
+- `WaitTool` is a `Tool`.
+- `WaitTool` defines `execute(...)`.
+- Observed side-effect areas: settings/state persistence.
+- Imported dependency areas include: `asyncio`, `datetime`, `helpers.localization`, `helpers.print_style`, `helpers.tool`, `helpers.wait`.
+
+## Key Concepts
+
+- Important called helpers/classes observed in the source: `Localization.get.now`, `PrintStyle.info`, `self.agent.read_prompt`, `Response`, `self.agent.context.log.log`, `self.agent.handle_intervention`, `timedelta`, `managed_wait`, `Localization.get.localtime_str_to_utc_dt`, `wait_duration.total_seconds`, `Localization.get.serialize_datetime`, `self.get_heading`, `ValueError`.
+- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
+
+## Work Guidance
+
+- Keep tool output concise, model-readable, and safe for history persistence.
+- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
+- Respect intervention flow for long-running, external, or user-visible operations.
+
+## Verification
+
+- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution 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_default_prompt_budget.py`
+ - `tests/test_document_query_plugin.py`
+ - `tests/test_download_toast_regressions.py`
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/AGENTS.md b/webui/AGENTS.md
index cb0d16344..27cce4b4f 100644
--- a/webui/AGENTS.md
+++ b/webui/AGENTS.md
@@ -48,3 +48,5 @@ Direct child DOX files:
| [components/AGENTS.md](components/AGENTS.md) | Alpine component HTML, component stores, and component-local styles. |
| [css/AGENTS.md](css/AGENTS.md) | Shared WebUI stylesheet modules. |
| [js/AGENTS.md](js/AGENTS.md) | Shared frontend JavaScript modules and client-side infrastructure. |
+| [public/AGENTS.md](public/AGENTS.md) | First-party static WebUI images, icons, splash art, and PWA assets. |
+| [vendor/AGENTS.md](vendor/AGENTS.md) | Vendored third-party browser libraries. |
diff --git a/webui/components/AGENTS.md b/webui/components/AGENTS.md
index 5390fb3bc..606f4ab65 100644
--- a/webui/components/AGENTS.md
+++ b/webui/components/AGENTS.md
@@ -56,4 +56,21 @@
## Child DOX Index
-No child DOX files.
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [_examples/AGENTS.md](_examples/AGENTS.md) | Reference component and store examples. |
+| [canvas/AGENTS.md](canvas/AGENTS.md) | Right-canvas component surface and store. |
+| [chat/AGENTS.md](chat/AGENTS.md) | Chat composer, attachments, queue, navigation, and top-section components. |
+| [dropdown/AGENTS.md](dropdown/AGENTS.md) | Shared dropdown component. |
+| [messages/AGENTS.md](messages/AGENTS.md) | Message rendering helpers, action buttons, process groups, and resize behavior. |
+| [modals/AGENTS.md](modals/AGENTS.md) | Modal component workflows loaded through the shared modal stack. |
+| [notifications/AGENTS.md](notifications/AGENTS.md) | Toasts, notification modal, icons, and notification store. |
+| [plugins/AGENTS.md](plugins/AGENTS.md) | Plugin settings, info, list, execution, and toggle components. |
+| [projects/AGENTS.md](projects/AGENTS.md) | Project creation, selection, edit, secrets, model, skill, and file-structure components. |
+| [settings/AGENTS.md](settings/AGENTS.md) | Settings shell and built-in settings subsections. |
+| [sidebar/AGENTS.md](sidebar/AGENTS.md) | Left sidebar layout, chat/task lists, top actions, and preferences. |
+| [sync/AGENTS.md](sync/AGENTS.md) | WebUI sync status component and store. |
+| [tooltips/AGENTS.md](tooltips/AGENTS.md) | Shared tooltip store and behavior. |
+| [welcome/AGENTS.md](welcome/AGENTS.md) | Welcome screen, discovery cards, banners, and welcome state. |
diff --git a/webui/components/_examples/AGENTS.md b/webui/components/_examples/AGENTS.md
new file mode 100644
index 000000000..882ae3eea
--- /dev/null
+++ b/webui/components/_examples/AGENTS.md
@@ -0,0 +1,27 @@
+# Component Examples DOX
+
+## Purpose
+
+- Own reference component and store examples for WebUI component authors.
+
+## Ownership
+
+- `_example-component.html` owns the component markup example.
+- `_example-store.js` owns the store pattern example.
+
+## Local Contracts
+
+- Keep examples aligned with current component loader, Store Gating, and `createStore` patterns.
+- Do not add product behavior or dependencies here.
+
+## Work Guidance
+
+- Prefer small examples that demonstrate current conventions clearly.
+
+## Verification
+
+- Manually inspect examples after component contract changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/canvas/AGENTS.md b/webui/components/canvas/AGENTS.md
new file mode 100644
index 000000000..3ec1d5006
--- /dev/null
+++ b/webui/components/canvas/AGENTS.md
@@ -0,0 +1,28 @@
+# Canvas Components DOX
+
+## Purpose
+
+- Own the right-canvas component surface and its state.
+
+## Ownership
+
+- `right-canvas.html` owns canvas markup.
+- `right-canvas-store.js` owns canvas state, surface registration, and actions.
+- `right-canvas.css` owns canvas-specific styling.
+
+## Local Contracts
+
+- Keep registered surfaces compatible with WebUI extension hooks.
+- Preserve responsive layout and avoid overlapping the chat/sidebar shells.
+
+## Work Guidance
+
+- Use existing surface and extension helpers before adding new canvas infrastructure.
+
+## Verification
+
+- Smoke-test right-canvas open, close, resize, and registered surfaces after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/chat/AGENTS.md b/webui/components/chat/AGENTS.md
new file mode 100644
index 000000000..220667ecb
--- /dev/null
+++ b/webui/components/chat/AGENTS.md
@@ -0,0 +1,32 @@
+# Chat Components DOX
+
+## Purpose
+
+- Own chat composer, attachments, message queue, navigation, and top-section component groups.
+
+## Ownership
+
+- `input/` owns composer input, progress, banners, and bottom action bars.
+- `attachments/` owns drag/drop and attachment preview UI.
+- `message-queue/` owns queued message display and store state.
+- `navigation/` owns chat navigation state.
+- `top-section/` owns chat header/top area.
+
+## Local Contracts
+
+- Preserve Store Gating for all store-backed chat components.
+- Use shared API, WebSocket, notification, and attachment helpers where available.
+- Do not bypass CSRF or WebSocket state-sync expectations.
+
+## Work Guidance
+
+- Keep composer and attachment changes responsive across desktop and mobile.
+- Coordinate payload changes with backend chat, upload, and WebSocket handlers.
+
+## Verification
+
+- Smoke-test sending, queued messages, attachments, drag/drop, and navigation after visible changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/dropdown/AGENTS.md b/webui/components/dropdown/AGENTS.md
new file mode 100644
index 000000000..a6e9f284e
--- /dev/null
+++ b/webui/components/dropdown/AGENTS.md
@@ -0,0 +1,26 @@
+# Dropdown Component DOX
+
+## Purpose
+
+- Own the shared dropdown component used by WebUI controls.
+
+## Ownership
+
+- `dropdown.html` owns dropdown markup, behavior hooks, and component-local styling.
+
+## Local Contracts
+
+- Keep keyboard, focus, and click-outside behavior compatible with existing callers.
+- Avoid caller-specific assumptions in the shared dropdown.
+
+## Work Guidance
+
+- Prefer component attributes and slots over hardcoded option sets.
+
+## Verification
+
+- Smoke-test each caller that uses the dropdown after behavior changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/messages/AGENTS.md b/webui/components/messages/AGENTS.md
new file mode 100644
index 000000000..78c340802
--- /dev/null
+++ b/webui/components/messages/AGENTS.md
@@ -0,0 +1,29 @@
+# Message Components DOX
+
+## Purpose
+
+- Own message rendering helpers, action buttons, process groups, and resize behavior.
+
+## Ownership
+
+- `action-buttons/` owns simple message action controls.
+- `process-group/` owns grouped process-step DOM and styling helpers.
+- `resize/` owns message resize state.
+
+## Local Contracts
+
+- Keep message DOM helpers compatible with extension points that modify rendered messages.
+- Sanitize or safely render model/user-provided content through shared rendering paths.
+- Avoid layout shifts that break long-running message streaming.
+
+## Work Guidance
+
+- Coordinate changes with `webui/js/messages.js` and frontend extension hooks.
+
+## Verification
+
+- Smoke-test message rendering, action buttons, process groups, and resizing after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/modals/AGENTS.md b/webui/components/modals/AGENTS.md
new file mode 100644
index 000000000..45783107e
--- /dev/null
+++ b/webui/components/modals/AGENTS.md
@@ -0,0 +1,30 @@
+# Modal Components DOX
+
+## Purpose
+
+- Own WebUI modal component content loaded through the shared modal stack.
+
+## Ownership
+
+- Each direct child folder owns one modal workflow and its store.
+- Modal HTML files own body content, titles, scoped styles, and `data-modal-footer` content.
+- Modal store files own modal-local state and cleanup.
+
+## Local Contracts
+
+- Use `openModal(path)` and `closeModal()` from `/js/modals.js`.
+- Keep footer content marked with `data-modal-footer` when using pinned modal actions.
+- Do not introduce a parallel overlay, backdrop, or teleport modal system.
+
+## Work Guidance
+
+- Keep modal state cleanup explicit because stores may outlive DOM nodes.
+- Preserve stacked modal, Escape, click-outside, scroll, and footer behavior.
+
+## Verification
+
+- Smoke-test open, close, Escape, click-outside, scrolling, stacked modals, and pinned footers after modal changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/notifications/AGENTS.md b/webui/components/notifications/AGENTS.md
new file mode 100644
index 000000000..071bf076f
--- /dev/null
+++ b/webui/components/notifications/AGENTS.md
@@ -0,0 +1,30 @@
+# Notification Components DOX
+
+## Purpose
+
+- Own WebUI toast, modal, icon, and notification store behavior.
+
+## Ownership
+
+- `notification-store.js` owns notification state and public helper actions.
+- `notification-toast-stack.html` owns toast rendering.
+- `notification-modal.html` owns notification detail modal UI.
+- `notification-icons.html` owns shared notification icon markup.
+
+## Local Contracts
+
+- Use the notification system for user-facing success, warning, info, and error feedback.
+- Keep public helper names stable for core and plugin callers.
+- Avoid exposing secrets or raw auth payloads in notification text.
+
+## Work Guidance
+
+- Coordinate helper changes with plugin UI contracts and existing frontend imports.
+
+## Verification
+
+- Smoke-test toast display, dismiss, modal details, and notification severity styling.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/plugins/AGENTS.md b/webui/components/plugins/AGENTS.md
new file mode 100644
index 000000000..219c01176
--- /dev/null
+++ b/webui/components/plugins/AGENTS.md
@@ -0,0 +1,30 @@
+# Plugin Components DOX
+
+## Purpose
+
+- Own core WebUI plugin settings, info, list, execution, and toggle components.
+
+## Ownership
+
+- Root plugin component files own shared plugin settings and info screens.
+- `list/` owns plugin list and execute modal components.
+- `toggle/` owns scoped plugin activation UI.
+- Store files own plugin modal and settings state.
+
+## Local Contracts
+
+- Keep plugin settings modals bound through `$store.pluginSettingsPrototype` conventions.
+- Preserve global and scoped toggle semantics using `.toggle-1` and `.toggle-0`.
+- Use notification helpers for plugin UI feedback.
+
+## Work Guidance
+
+- Coordinate plugin API payload changes with `helpers/plugins.py` and plugin API handlers.
+
+## Verification
+
+- Smoke-test plugin list, settings, scoped toggles, plugin info, and execute modal after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/projects/AGENTS.md b/webui/components/projects/AGENTS.md
new file mode 100644
index 000000000..d5a9855c9
--- /dev/null
+++ b/webui/components/projects/AGENTS.md
@@ -0,0 +1,30 @@
+# Project Components DOX
+
+## Purpose
+
+- Own WebUI project creation, selection, editing, secrets, model, skill, and file-structure components.
+
+## Ownership
+
+- `projects-store.js` owns project state and actions.
+- `project-create.html`, `project-list.html`, and `project-selector.html` own project creation and navigation UI.
+- `project-edit*.html` files own project editing subsections.
+- `project-file-structure-test.html` owns file-structure test UI.
+
+## Local Contracts
+
+- Keep project API payloads synchronized with backend project handlers.
+- Do not expose project secrets in logs, URLs, or long-lived frontend state unnecessarily.
+- Preserve scoped settings interactions with plugins, models, and skills.
+
+## Work Guidance
+
+- Verify project edit flows when changing shared project store state.
+
+## Verification
+
+- Smoke-test create, select, edit, secrets, LLM, skills, and file-structure flows after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/settings/AGENTS.md b/webui/components/settings/AGENTS.md
new file mode 100644
index 000000000..f44e4a596
--- /dev/null
+++ b/webui/components/settings/AGENTS.md
@@ -0,0 +1,29 @@
+# Settings Components DOX
+
+## Purpose
+
+- Own WebUI settings shell and built-in settings subsections.
+
+## Ownership
+
+- `settings.html` and `settings-store.js` own the settings shell and state.
+- Subdirectories own settings areas such as agent, external, developer, MCP, backup, plugins, secrets, skills, tunnel, and A2A.
+
+## Local Contracts
+
+- Keep settings payloads synchronized with backend APIs and plugin settings contracts.
+- Do not store secrets in localStorage, URLs, or console output.
+- Preserve Store Gating and modal footer conventions in settings components.
+
+## Work Guidance
+
+- Prefer subsection-local stores for complex settings areas.
+- Coordinate plugin settings UI changes with `webui/components/plugins/` and `plugins/AGENTS.md`.
+
+## Verification
+
+- Smoke-test changed settings tabs and save/reload behavior after visible or API changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/sidebar/AGENTS.md b/webui/components/sidebar/AGENTS.md
new file mode 100644
index 000000000..5cacb10d9
--- /dev/null
+++ b/webui/components/sidebar/AGENTS.md
@@ -0,0 +1,31 @@
+# Sidebar Components DOX
+
+## Purpose
+
+- Own left sidebar layout, chat/task lists, top actions, and bottom preferences components.
+
+## Ownership
+
+- `left-sidebar.html` and `sidebar-store.js` own sidebar shell and shared state.
+- `top-section/` owns header and quick actions.
+- `chats/` owns chat list UI and state.
+- `tasks/` owns task list UI and state.
+- `bottom/` owns lower sidebar controls and preferences panel.
+
+## Local Contracts
+
+- Preserve responsive sidebar behavior and collapsed/expanded state.
+- Keep chat and task list updates compatible with WebSocket state sync.
+- Avoid text or controls overflowing fixed sidebar widths.
+
+## Work Guidance
+
+- Coordinate navigation and state changes with WebSocket sync and chat/project stores.
+
+## Verification
+
+- Smoke-test sidebar collapse, chat list, task list, quick actions, and preferences after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/sync/AGENTS.md b/webui/components/sync/AGENTS.md
new file mode 100644
index 000000000..d47d46b80
--- /dev/null
+++ b/webui/components/sync/AGENTS.md
@@ -0,0 +1,27 @@
+# Sync Components DOX
+
+## Purpose
+
+- Own WebUI state synchronization status UI and store.
+
+## Ownership
+
+- `sync-store.js` owns sync status state.
+- `sync-status.html` owns sync indicator markup.
+
+## Local Contracts
+
+- Keep sync state compatible with WebSocket state-sync events.
+- Avoid noisy user-facing alerts for transient sync state unless existing UX expects them.
+
+## Work Guidance
+
+- Coordinate sync changes with WebSocket client and backend WebSocket extensions.
+
+## Verification
+
+- Smoke-test connection, reconnect, and state refresh indicators after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/tooltips/AGENTS.md b/webui/components/tooltips/AGENTS.md
new file mode 100644
index 000000000..6fb50e7fe
--- /dev/null
+++ b/webui/components/tooltips/AGENTS.md
@@ -0,0 +1,26 @@
+# Tooltip Components DOX
+
+## Purpose
+
+- Own shared tooltip state and behavior for WebUI controls.
+
+## Ownership
+
+- `tooltip-store.js` owns tooltip state, positioning, and actions.
+
+## Local Contracts
+
+- Keep tooltip positioning compatible with desktop and mobile layouts.
+- Do not make tooltips required for completing a workflow.
+
+## Work Guidance
+
+- Prefer concise tooltip text and stable positioning around icon-only controls.
+
+## Verification
+
+- Smoke-test hover/focus tooltip behavior after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/components/welcome/AGENTS.md b/webui/components/welcome/AGENTS.md
new file mode 100644
index 000000000..4237418aa
--- /dev/null
+++ b/webui/components/welcome/AGENTS.md
@@ -0,0 +1,28 @@
+# Welcome Components DOX
+
+## Purpose
+
+- Own the WebUI welcome screen, discovery cards, banners, and related state.
+
+## Ownership
+
+- `welcome-screen.html` owns welcome screen markup and layout.
+- `welcome-store.js` owns welcome state, banners, cards, and actions.
+
+## Local Contracts
+
+- Keep banner and discovery card behavior compatible with Python `banners` extensions.
+- Supported banner/card CTA actions must stay synchronized with plugin discovery contracts.
+- Do not show setup prompts for already configured plugins when backend status can prevent it.
+
+## Work Guidance
+
+- Coordinate visual card or CTA changes with plugin discovery and onboarding surfaces.
+
+## Verification
+
+- Smoke-test alert banners, feature cards, dismissal, priority ordering, and CTA actions after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/public/AGENTS.md b/webui/public/AGENTS.md
new file mode 100644
index 000000000..cdf8bfddc
--- /dev/null
+++ b/webui/public/AGENTS.md
@@ -0,0 +1,32 @@
+# WebUI Public Assets DOX
+
+## Purpose
+
+- Own first-party static images, icons, splash art, and PWA assets served by the WebUI.
+- Keep visual assets stable for core UI surfaces and settings sections.
+
+## Ownership
+
+- SVG files own first-party icons and settings/category symbols.
+- Raster files own splash, thumbnail, and app-icon imagery.
+- Asset filenames are part of the frontend reference contract when used by HTML, CSS, JS, or plugins.
+
+## Local Contracts
+
+- Do not add secrets, user uploads, generated runtime files, or private branding assets here.
+- Keep asset paths stable or update every frontend reference in the same change.
+- Prefer optimized web formats and reasonable file sizes for assets loaded during startup.
+
+## Work Guidance
+
+- Use this folder for shared first-party assets, not component-specific images that belong with a plugin or component.
+- Check contrast and legibility for icon changes in both light and dark UI contexts when relevant.
+
+## Verification
+
+- Manually smoke-test pages that reference changed assets.
+- Run frontend checks when asset references are covered by tests.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/AGENTS.md b/webui/vendor/AGENTS.md
new file mode 100644
index 000000000..28ad931ce
--- /dev/null
+++ b/webui/vendor/AGENTS.md
@@ -0,0 +1,42 @@
+# WebUI Vendor Assets DOX
+
+## Purpose
+
+- Own vendored third-party browser libraries served by the WebUI.
+- Keep external library updates intentional, isolated, and reviewable.
+
+## Ownership
+
+- Each direct child directory owns one vendored library or library bundle.
+- Vendored files should be treated as upstream artifacts, with local edits avoided unless clearly documented.
+
+## Local Contracts
+
+- Do not edit vendored files for application behavior when a wrapper or caller can own the change.
+- Preserve license, version, and distribution assumptions for third-party assets.
+- Do not add package-manager caches, build outputs, or unrelated downloaded artifacts.
+
+## Work Guidance
+
+- Prefer replacing a vendor bundle with a clean upstream build over hand-editing minified files.
+- Coordinate library path changes with all HTML, CSS, and JS imports.
+
+## Verification
+
+- Manually smoke-test UI paths that load an updated vendor library.
+- Run frontend checks when imports or wrappers are covered.
+
+## Child DOX Index
+
+Direct child DOX files:
+
+| Child | Scope |
+| --- | --- |
+| [_ace/AGENTS.md](_ace/AGENTS.md) | Minimal Ace editor subset used by core editor surfaces. |
+| [ace-min/AGENTS.md](ace-min/AGENTS.md) | Full minified Ace distribution and supporting assets. |
+| [alpine/AGENTS.md](alpine/AGENTS.md) | Vendored Alpine.js core and collapse plugin. |
+| [dompurify/AGENTS.md](dompurify/AGENTS.md) | Vendored DOMPurify sanitizer module. |
+| [flatpickr/AGENTS.md](flatpickr/AGENTS.md) | Vendored Flatpickr date/time picker assets. |
+| [google/AGENTS.md](google/AGENTS.md) | Vendored Google Material Symbols font and stylesheet. |
+| [katex/AGENTS.md](katex/AGENTS.md) | Vendored KaTeX rendering assets. |
+| [marked/AGENTS.md](marked/AGENTS.md) | Vendored Marked markdown parser module. |
diff --git a/webui/vendor/_ace/AGENTS.md b/webui/vendor/_ace/AGENTS.md
new file mode 100644
index 000000000..716d83274
--- /dev/null
+++ b/webui/vendor/_ace/AGENTS.md
@@ -0,0 +1,27 @@
+# Ace Minimal Vendor DOX
+
+## Purpose
+
+- Own the minimal Ace editor files used by focused WebUI editor flows.
+
+## Ownership
+
+- JavaScript mode, theme, worker, and loader files are vendored Ace artifacts.
+- `ace.min.css` owns local Ace styling required by the bundled files.
+
+## Local Contracts
+
+- Avoid hand-editing Ace source files; replace from a known upstream build when updating.
+- Keep filenames stable for existing WebUI imports.
+
+## Work Guidance
+
+- Prefer adding only the modes and themes actually needed by core UI surfaces.
+
+## Verification
+
+- Smoke-test editor surfaces that load this subset after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/ace-min/AGENTS.md b/webui/vendor/ace-min/AGENTS.md
new file mode 100644
index 000000000..ec6faa949
--- /dev/null
+++ b/webui/vendor/ace-min/AGENTS.md
@@ -0,0 +1,28 @@
+# Ace Min Vendor DOX
+
+## Purpose
+
+- Own the full minified Ace editor distribution and static assets.
+
+## Ownership
+
+- `ace.js`, extensions, modes, themes, workers, keybindings, and image assets are vendored Ace artifacts.
+
+## Local Contracts
+
+- Treat files as upstream-generated assets.
+- Do not hand-edit minified or generated files for product behavior.
+- Preserve referenced asset filenames unless all imports are updated.
+
+## Work Guidance
+
+- Replace this directory with a clean upstream distribution when updating Ace.
+- Keep unrelated generated files and local caches out of this vendor bundle.
+
+## Verification
+
+- Smoke-test editor and code-input surfaces after vendor updates.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/alpine/AGENTS.md b/webui/vendor/alpine/AGENTS.md
new file mode 100644
index 000000000..64cb52cb2
--- /dev/null
+++ b/webui/vendor/alpine/AGENTS.md
@@ -0,0 +1,27 @@
+# Alpine Vendor DOX
+
+## Purpose
+
+- Own vendored Alpine.js browser runtime files used by the WebUI.
+
+## Ownership
+
+- `alpine.min.js` owns the Alpine core runtime.
+- `alpine.collapse.min.js` owns the collapse plugin runtime.
+
+## Local Contracts
+
+- Do not modify vendored Alpine runtime files directly.
+- Keep load order compatible with `webui/js/initFw.js` and component initialization.
+
+## Work Guidance
+
+- Update Alpine as a deliberate vendor bump and smoke-test component lifecycle directives.
+
+## Verification
+
+- Smoke-test WebUI startup, component loading, and store initialization after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/dompurify/AGENTS.md b/webui/vendor/dompurify/AGENTS.md
new file mode 100644
index 000000000..693d2ad0f
--- /dev/null
+++ b/webui/vendor/dompurify/AGENTS.md
@@ -0,0 +1,27 @@
+# DOMPurify Vendor DOX
+
+## Purpose
+
+- Own the vendored DOMPurify sanitizer module used for safe HTML rendering.
+
+## Ownership
+
+- `purify.es.mjs` owns the browser module imported by WebUI sanitization paths.
+
+## Local Contracts
+
+- Do not weaken sanitizer behavior through local edits.
+- Keep import paths synchronized with markdown and message rendering code.
+
+## Work Guidance
+
+- Replace with a clean upstream module when updating.
+- Coordinate sanitizer updates with security-sensitive rendering tests.
+
+## Verification
+
+- Run or manually exercise HTML/markdown rendering paths after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/flatpickr/AGENTS.md b/webui/vendor/flatpickr/AGENTS.md
new file mode 100644
index 000000000..5e94ab2e8
--- /dev/null
+++ b/webui/vendor/flatpickr/AGENTS.md
@@ -0,0 +1,27 @@
+# Flatpickr Vendor DOX
+
+## Purpose
+
+- Own vendored Flatpickr date and time picker assets.
+
+## Ownership
+
+- `flatpickr.min.js` owns picker runtime behavior.
+- `flatpickr.min.css` owns picker vendor styling.
+
+## Local Contracts
+
+- Do not hand-edit minified vendor files for application behavior.
+- Keep scheduler and date-input imports synchronized with file paths.
+
+## Work Guidance
+
+- Replace from a clean upstream release when updating.
+
+## Verification
+
+- Smoke-test scheduler or date/time inputs after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/google/AGENTS.md b/webui/vendor/google/AGENTS.md
new file mode 100644
index 000000000..effd8c15b
--- /dev/null
+++ b/webui/vendor/google/AGENTS.md
@@ -0,0 +1,27 @@
+# Google Icons Vendor DOX
+
+## Purpose
+
+- Own vendored Google Material Symbols font and stylesheet assets.
+
+## Ownership
+
+- `google-icons.css` owns the font-face and icon class definitions.
+- `google-icons.ttf` owns the font binary used by the WebUI.
+
+## Local Contracts
+
+- Keep font filenames and CSS references synchronized.
+- Do not add unrelated remote font assets or tracking references.
+
+## Work Guidance
+
+- Replace font and stylesheet together when updating icon coverage.
+
+## Verification
+
+- Smoke-test visible icon surfaces after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/katex/AGENTS.md b/webui/vendor/katex/AGENTS.md
new file mode 100644
index 000000000..983d15276
--- /dev/null
+++ b/webui/vendor/katex/AGENTS.md
@@ -0,0 +1,28 @@
+# KaTeX Vendor DOX
+
+## Purpose
+
+- Own vendored KaTeX assets used for math rendering.
+
+## Ownership
+
+- `katex.min.js` owns core rendering behavior.
+- `katex.auto-render.min.js` owns auto-render support.
+- `katex.min.css` owns KaTeX styling.
+
+## Local Contracts
+
+- Do not hand-edit minified vendor files.
+- Keep markdown/message rendering imports synchronized with asset paths.
+
+## Work Guidance
+
+- Replace from a clean upstream release when updating KaTeX.
+
+## Verification
+
+- Smoke-test markdown or message content containing math after changes.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/webui/vendor/marked/AGENTS.md b/webui/vendor/marked/AGENTS.md
new file mode 100644
index 000000000..e171735ba
--- /dev/null
+++ b/webui/vendor/marked/AGENTS.md
@@ -0,0 +1,26 @@
+# Marked Vendor DOX
+
+## Purpose
+
+- Own the vendored Marked markdown parser module.
+
+## Ownership
+
+- `marked.esm.js` owns markdown parsing behavior imported by WebUI rendering code.
+
+## Local Contracts
+
+- Do not hand-edit the vendored parser for application behavior.
+- Keep parser updates coordinated with sanitization and message rendering expectations.
+
+## Work Guidance
+
+- Replace with a clean upstream module when updating.
+
+## Verification
+
+- Smoke-test markdown rendering after changes.
+
+## Child DOX Index
+
+No child DOX files.