| 1 | # Backend Helpers DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own shared Python framework utilities used by agents, APIs, tools, plugins, WebSockets, persistence, and runtime services. |
| 6 | - Keep cross-cutting behavior stable and tested. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Helper modules provide reusable services; feature-specific route handlers belong in `api/`, tool behavior in `tools/`, and plugin-local logic inside plugin directories. |
| 11 | - Security, auth, settings, file access, plugin discovery, extension dispatch, notifications, state snapshots, scheduler, tunnel, and WebSocket primitives live here. |
| 12 | |
| 13 | ## Local Contracts |
| 14 | |
| 15 | - Preserve public helper APIs used by core code and plugins unless all callers, docs, and tests are updated. |
| 16 | - Use structured parsers and serializers for YAML, JSON, paths, and URLs instead of ad hoc string handling. |
| 17 | - Keep path handling constrained to intended roots for user files, uploads, downloads, projects, and workdirs. |
| 18 | - Project metadata defaults must remain backwards-compatible; missing `include_agents_md` is treated as enabled, project instruction file content is injected with an explicit source path, and active-project AGENTS.md path-chain guidance is assembled into prompt protocol without duplicating the project root AGENTS.md. |
| 19 | - Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values. |
| 20 | - Use `RepairableException` for errors an agent may be able to fix. |
| 21 | - 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. |
| 22 | - 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. |
| 23 | - When a helper module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change. |
| 24 | - Do not leave stale file-level DOX after helper deletion or rename. |
| 25 | |
| 26 | ## Work Guidance |
| 27 | |
| 28 | - Prefer cohesive helper modules over adding unrelated utilities to large files. |
| 29 | - Keep imports acyclic where possible; defer imports inside functions only when needed to avoid startup cycles. |
| 30 | - For changes touching auth, CSRF, files, plugins, tunnels, WebSockets, or model calls, read the caller and tests before editing. |
| 31 | - During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed helper behavior is described there. |
| 32 | |
| 33 | ## Verification |
| 34 | |
| 35 | - Run targeted tests for changed helper modules. |
| 36 | - Run security regression tests for auth, CSRF, filesystem, WebSocket, tunnel, upload, or image-serving changes. |
| 37 | - Check file-level documentation coverage with a script or shell loop that verifies each `helpers/*.py` has a matching `helpers/*.py.dox.md`. |
| 38 | |
| 39 | ## Child DOX Index |
| 40 | |
| 41 | No child DOX files. |