Agent Notes

Use this file as a quick orientation guide before editing the repository.

Ground Rules

Keep documentation and code claims aligned with implemented files.
Do not describe settings as editable through the web application. Runtime settings come from config/config.yml or config/config.example.yml, plus environment variables.
Treat data/ and logs/ as runtime output locations. The repository ignores SQLite databases and log files.
Do not add compatibility, migration, or legacy-support behavior unless a task explicitly asks for an implemented change.
UI work should follow the mockups in design/. If documenting UI icons, respect the project policy that icons must be material icons.

Start at app/main.py for HTTP routes, template rendering, API auth dependencies, and admin processing endpoints.
Read app/config.py before changing runtime behavior because settings are Pydantic models loaded at import time by get_settings().
Follow ingestion through app/message_processor.py, then app/attachment_extractor.py, app/dmarc_parser.py, app/known_senders.py, and app/analyzer.py.
Use app/models.py for database table fields and relationships. Tables are created by app.db.init_db() through SQLAlchemy metadata.
Use tests/ for examples of expected parser, extractor, analyzer, storage, homepage, and LLM fallback behavior.

Inspect the code path being documented.
Keep filenames in doc/ lowercase, except README.md.
Prefer links to existing files and commands that are present in this repository.
Validate with lightweight checks appropriate to the change. For docs-only changes, at minimum verify Markdown filenames and run the test suite when the environment has dependencies installed.