docs: add AGENTS.md and rewrite readme

AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+REST API (Django + django-ninja) for managing the virtual domains, users and aliases that Postfix and Dovecot read
+from the database. Deployed as mxapi.neuf.no.
+
+## Setup and commands
+
+Tools are managed by [mise](https://mise.jdx.dev) (Python, uv, prek) and Python deps by uv.
+
+```sh
+mise install            # Python, uv, prek
+uv sync                 # deps + dev tools
+prek install            # git hooks
+uv run pytest           # tests, must keep 100% coverage
+prek run --all-files    # ruff check, ruff format and file hygiene hooks
+```
+
+## Rules
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages, e.g.
+  `feat: add alias search`, `fix(api): reject unknown domains`, `chore(deps): bump django`.
+- Postfix and Dovecot query the `dpdapi_domain`, `dpdapi_alias` and `dpdapi_user` tables directly. Never rename
+  tables or columns, or change how values are stored (addresses are lowercased, passwords are SHA-512 crypt).
+  `tests/test_schema.py` guards this.
+- Django stays on 5.2 LTS (and Python 3.14) until lynx has MySQL 8.4, which Django 6 requires.
+- [mailadmin](https://git.neuf.no/edb/mailadmin) is the main API client. Don't change URLs, status codes or response fields it relies on;
+  `tests/test_mailadmin_contract.py` replays its calls.
+- Test the API through HTTP in `tests/`, using pytest and the fixtures in `tests/conftest.py`.
+- Keep coverage at 100%; `pytest` fails below it.
+- Production-only deps (`gunicorn`, `mysqlclient`) live in the `prod` dependency group.

README.md

@@ -1,14 +1,18 @@
-# Install
-    apt install python-dev libmysqlclient-dev python-virtualenv
-    python -m venv venv
-    . venv/bin/activate
-    pip install -r requirements.txt
+# django-postfix-dovecot-api
 
-# Deploy
-First you need to have your public key in `/home/gitdeploy/.ssh/authorized_keys` on the server and then you can do:
+REST API for managing the virtual domains, users and aliases that Postfix and Dovecot read from the database.
+Used by [mailadmin](https://git.neuf.no/edb/mailadmin).
 
-    fab deploy
+## Development
 
-# Inspiration:
-- http://modoboa.readthedocs.org/
-- https://github.com/lgunsch/django-vmail
+```sh
+mise install
+uv sync
+prek install
+uv run python manage.py migrate
+uv run python manage.py runserver
+uv run pytest
+```
+
+API docs are served at `/api/docs`. Override settings (database, secret key, Sentry) in
+`dpdapisite/local_settings.py`.