diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7f2b079
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# AGENTS.md — how changes are made in this repo
+
+This file is read by AI agents (via opencode) **and** by human developers. Follow it.
+
+## What this repo is
+The public **homepage** served at `homepage.ffaerber.duckdns.org`. The site is built into a **Docker
+image**, pushed to this Gitea instance's **container registry**, and deployed via the homelab stack
+(`ffaerber/homelab`). This repo holds the website source and its `Dockerfile`/build; it does **not**
+hold the deployment stack itself.
+
+## Golden rules
+- You may edit **any file** in this repo (site source, `Dockerfile`, `.gitea/` workflows).
+- **NEVER push to `main`, and NEVER merge a pull request.** All work goes on a branch and becomes a
+  PR that a human reviews and merges. You do not have merge authority — do not attempt it.
+- **Never print, exfiltrate, or invent secret values.** You may edit config that *references* secrets,
+  but never paste real secret values into comments, PRs, logs, or code.
+- Keep changes **minimal** and match the conventions already in the file you're editing.
+- Do the work on a **branch** — never paste code or diffs into the issue thread.
+- The repo is **public** and the built image is public, so it can be pulled without registry
+  credentials. Do not add anything secret to the image or the source.
+
+## Branches & pull requests
+You start on branch `ai/issue-<N>` (N = the issue number).
+
+**Split independent changes into separate PRs** so each can be reviewed and shipped on its own. For
+each independent change, use its own branch:
+
+```
+git checkout main
+git checkout -b ai/issue-<N>-<short-slug>      # e.g. ai/issue-3-nav, ai/issue-3-styles
+# make just that one change
+git add -A && git commit -m "<what changed>" && git push -u origin HEAD
+```
+
+- Only keep changes together on one branch if they genuinely must ship as a unit.
+- Commit and **push incrementally** as you work, so progress is visible on the branch.
+- **Do not open pull requests yourself** — the automation opens one PR per branch you push, and
+  the maintainer merges them sequentially.
+
+## PR description
+End your reply with a clean pull-request description wrapped EXACTLY between these markers.
+Everything before `BEGIN_PR_DESCRIPTION` is treated as working notes and discarded:
+
+```
+BEGIN_PR_DESCRIPTION
+## Summary
+<1-2 sentences: what changed and why>
+## Changes
+<short bullet list of the changes>
+END_PR_DESCRIPTION
+```
+
+Do not paste full files or large diffs — the review happens in the PR diff.
+
+## Build & deploy
+- The site is packaged by a `Dockerfile` at the repo root (add one when the site source lands).
+- On merge to `main`, CI builds the image and pushes it to the Gitea container registry; the
+  homelab stack then pulls and serves it at `homepage.ffaerber.duckdns.org`.
+- Keep the image small and the build reproducible. Prefer a static-site build served by a minimal
+  web server (e.g. nginx) unless an issue says otherwise.
+
+## When unsure
+If the task is genuinely unclear or missing details you cannot reasonably assume, make **no**
+changes and reply with specific questions instead.