diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7870768
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,68 @@
+\# Project Rules
+
+
+
+\## Code Quality
+
+
+
+\- Prefer readability over cleverness.
+
+\- Keep methods under \~40 lines where practical.
+
+\- Avoid duplicated logic.
+
+\- Follow SOLID principles.
+
+\- Keep files focused on a single responsibility.
+
+
+
+\## Safety
+
+
+
+\- Never commit secrets.
+
+\- Never disable tests to make them pass.
+
+\- Never remove functionality without explaining why.
+
+
+
+\## Testing
+
+
+
+Every change must include:
+
+\- Unit tests where appropriate.
+
+\- Integration tests for API changes.
+
+\- Build verification.
+
+
+
+\## Architecture
+
+
+
+Prefer:
+
+\- Dependency Injection
+
+\- Composition over inheritance
+
+\- Async APIs
+
+\- Immutable models where practical
+
+
+
+\## Documentation
+
+
+
+Update documentation whenever public behaviour changes.
+
diff --git a/docs/specs/ui-overhaul.md b/docs/specs/ui-overhaul.md
index 66ff40c..06025fe 100644
--- a/docs/specs/ui-overhaul.md
+++ b/docs/specs/ui-overhaul.md
@@ -68,6 +68,12 @@ Defined once in `src/index.css`; Tailwind theme references them so `bg-backgroun
 }
 ```
 
+> **Accent is swappable by design.** The accent lives in exactly one token (`--primary`,
+> plus its dark variant). Changing the brand color = editing those two lines. This also
+> makes a **future user-facing accent picker** cheap: store a chosen hue on the user (or
+> in `localStorage`) and write `--primary`/`--ring` at runtime. Decision (2026-06-30):
+> ship with **Indigo `#5b5bf0`**; leave the picker as a documented future enhancement.
+
 ### Proposed palette (for sign-off)
 
 | Token | Light | Dark | Use |