diff --git a/Villager-Jobs-and-AI.md b/Villager-Jobs-and-AI.md
new file mode 100644
index 0000000..fc9236c
--- /dev/null
+++ b/Villager-Jobs-and-AI.md
@@ -0,0 +1,60 @@
+# Villager Jobs & AI
+
+> **Legend**
+> - ✅ Implemented — exists in the current codebase
+> - 🗺️ Planned — design exists but not yet implemented
+
+---
+
+## Jobs
+
+All jobs are assigned automatically based on **priority** (1 = highest) and **distance** (closest target wins within same priority). Jobs are "claimed" to prevent two villagers from taking the same target.
+
+| Job | Trigger | Work Duration | Output |
+|-----|---------|--------------|--------|
+| `chop` ✅ | Tree resource exists on map | 3,000 ms | +2 wood → stockpile |
+| `mine` ✅ | Rock resource exists on map | 5,000 ms | +2 stone → stockpile |
+| `farm` ✅ | Crop at max growth stage | 1,200 ms | Crop yield → stockpile |
+
+**Default priority on spawn:** chop 1 · mine 2 · farm 3  
+**Player can reorder** priorities per villager in the villager panel.
+
+---
+
+## AI Cycle ✅
+
+```
+Idle → find job (priority + distance)
+  → Walking (path to target, energy drains 0.0015/ms ≈ 3/s)
+    → Working (fixed duration, wobble animation)
+      → Depositing (walk to nearest stockpile_zone)
+        → back to Idle
+          └─ if energy < 25 → Sleeping in nearest bed (energy +0.04/ms ≈ 4/s)
+```
+
+---
+
+## Energy System ✅
+
+| State | Energy change | Notes |
+|-------|--------------|-------|
+| Walking | −0.0015 per ms | ≈ −3 per second |
+| Working | no drain | Standing still |
+| Sleeping | +0.04 per ms | ≈ full in ~25 s |
+| Sleep trigger | energy < 25 | Villager seeks nearest free bed |
+| Wake trigger | energy = 100 | Returns to Idle |
+
+Energy bar color: 🟢 > 60 · 🟠 30–60 · 🔴 < 30
+
+---
+
+## Spawn Rules ✅
+
+- One villager spawns per **free bed** (max population = number of beds)
+- Spawn check every **8,000 ms**
+- Movement speed: **75 px/s**
+- 23 possible names (Aldric, Brix, Cora, Dwyn, …)
+
+---
+
+← [[Game Systems Reference]]