diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..e93798ae
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,19 @@
+# Arch Linux Without the Beeps — Agent Guide
+
+## Scope
+These instructions apply to the entire repository unless a more specific `AGENTS.md` is added deeper in the tree.
+
+## Workflow expectations
+- Keep the Docker-based build tooling working; avoid hard-coding host-specific paths or assumptions outside `/workdir`.
+- Prefer small, focused commits that touch only the files needed for a change.
+- When adding new automation scripts, place them under `scripts/` and document any new entry points in `README.md`.
+
+## Coding guidelines
+- Python code should use 4-space indentation, descriptive function names, and avoid unnecessary try/except wrappers around imports.
+- Flask routes live in `app.py`; keep the streaming `/build` endpoint compatible with Server-Sent Events by yielding already-formatted `data:` lines.
+- HTML templates under `templates/` should remain dependency-free (plain Bootstrap/vanilla JS only) so that the GUI keeps working in the minimal container environment.
+
+## Testing and verification
+- For Python changes, run `python -m compileall app.py` to catch syntax errors before opening a PR.
+- When touching Dockerfiles or build scripts, run `docker build -t arch-iso-builder .` (and the GUI variant with `-f Dockerfile.gui`) if the environment allows; otherwise explain the limitation in your summary.
+- Pure documentation or comment-only updates do not require a test run.