diff --git a/README.md b/README.md
new file mode 100644
index 0000000..55b644d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,136 @@
+# SIEGE PROTOCOL
+
+An inverted tower-defense game. You control the enemies — your tower kills them automatically. Every kill pays out more than it costs. Spend the profit on weapons, upgrades, and armor. Keep the tower alive as long as possible.
+
+**Play online:** [siege-protocol on Gitea](https://git.44r0n.cc/44r0n7/siege-protocol)
+
+---
+
+## How to Play
+
+Open `index.html` in a browser, or serve locally:
+
+```bash
+python3 -m http.server 8080
+# → http://localhost:8080
+```
+
+No build step. No dependencies.
+
+### Controls
+
+| Input | Action |
+|-------|--------|
+| `1` – `0` | Deploy enemy type 1–10 |
+| Mouse scroll | Adjust send quantity |
+| `Space` | Open/close shop |
+| `I` | Open/close inventory |
+| `Esc` / `P` | Pause / unpause |
+
+### The Loop
+
+1. Deploy enemies using credits — each deployment costs credits
+2. Your tower auto-tracks and kills them
+3. Each kill pays a reward (always higher than the deploy cost)
+4. Spend profit in the shop: more weapons, more weapon slots, tower armor/HP, shields
+5. Survive until the tower dies or you go **bankrupt** (no credits, no enemies, can't afford anything)
+
+**Reserve:** A minimum credit floor you set yourself. Keeps you from accidentally spending down to zero with no way back.
+
+---
+
+## Enemies
+
+| # | Name | Cost | Reward | Notes |
+|---|------|------|--------|-------|
+| 1 | GRUNT | 20 | 30 | Baseline. Weak to poison. |
+| 2 | RUNNER | 30 | 44 | Very fast, low HP. Weak to lightning and poison. |
+| 3 | BRUTE | 80 | 112 | High HP, 3 armor. Weak to void/fire/poison. Physical resistant. |
+| 4 | SWARM | 60 | 84 | Spawns 6 tiny units at once. Weak to fire/lightning. |
+| 5 | PHANTOM | 100 | 138 | 30% dodge. Void-touched. Weak to fire. |
+| 6 | ICELING | 90 | 125 | Ice elemental. Immune to ice, weak to fire/lightning. |
+| 7 | SPARKLING | 110 | 148 | Lightning elemental. Immune to lightning, weak to ice/void. |
+| 8 | VENOM | 120 | 160 | Poison immune. Weak to ice/arcane. |
+| 9 | WRAITH | 200 | 265 | Ignores 80% of armor. Weak to arcane (2×). |
+| 10 | TITAN | 350 | 465 | 120 HP, 8 armor. Void weakness (2×). Extremely slow. |
+
+---
+
+## Weapons
+
+| Weapon | Cost | Type | Notes |
+|--------|------|------|-------|
+| CANNON | free | Projectile | Starting weapon. Upgradeable piercing and crit. |
+| FLAMETHROWER | 800 | Cone | Continuous fire cone. Applies burn DoT. |
+| CHAIN LIGHTNING | 1,200 | Chain | Arcs between up to 3 enemies. |
+| MORTAR | 1,500 | AoE | Lobbed shell, group-targeted. Slow reload. |
+| POISON CLOUD | 1,600 | AoE | Lingering gas cloud with DoT. |
+| FREEZE BOMB | 1,800 | AoE | Freezes enemies solid. |
+| VOID CANNON | 2,000 | Projectile | Massive slow shot. Shreds armor. |
+| LASER | 2,000 | Beam | Pierces all enemies in a line. |
+| ARCANE TURRET | 2,200 | Projectile | Rapid bolts. Applies Amplify debuff (+25% damage taken). |
+| MISSILE POD | 2,400 | Homing AoE | Fires at 3 targets simultaneously. |
+
+Up to 8 weapon slots can be unlocked via the shop. Each weapon has its own upgrade tree (damage, fire rate, special stats, element infusion).
+
+---
+
+## Elements
+
+Seven elements with per-enemy resistances and weaknesses:
+
+| Element | Color |
+|---------|-------|
+| 🔥 Fire | Damage over time, strong vs ice/void enemies |
+| ❄️ Ice | Freeze, strong vs lightning/poison |
+| ⚡ Lightning | Arc damage, strong vs fast/swarm enemies |
+| ☠️ Poison | DoT, weak to most elemental enemies |
+| 🌀 Void | Armor bypass, strong vs armored/phantom |
+| ✨ Arcane | Amplify debuff, strong vs void and poison |
+| 💢 Physical | Default element |
+
+Weapons start with a default element. Purchase **Infuse slots** in a weapon's upgrade tree to add up to 3 additional elements.
+
+---
+
+## Tower Upgrades
+
+- **Hull** — max HP (5 tiers, up to +130 HP total)
+- **Plating** — armor (5 tiers, up to +16 armor total)
+- **Servo Motors** — aim speed (6 tiers, near-instant at max)
+- **Scanner** — targeting range (4 tiers)
+- **Weapon Slots** — unlock slots 2–8
+- **Field Repair** — one-time HP restore (repeatable)
+- **Shields** — choose Dome Shield (all-direction) or Directional Shield (rotates to track threats), each with their own upgrade tree
+
+---
+
+## Tech
+
+- HTML5 Canvas, CSS, vanilla JS — no frameworks, no bundler
+- 1600×900 logical resolution, CSS-scaled to fit any viewport
+- High score persisted in `localStorage` (`siegeprotocol_best`)
+- JS modules share globals; script load order in `index.html` is intentional
+
+```
+siege-protocol/
+├── index.html          # entry point
+├── css/
+│   ├── main.css        # game UI
+│   └── dev-console.css
+└── js/
+    ├── defs.js         # enemy/weapon/upgrade definitions
+    ├── state.js        # game state and entity factories
+    ├── main.js         # game loop, init, high score
+    ├── enemies.js      # enemy AI and combat
+    ├── weapons.js      # weapon firing logic
+    ├── shop.js         # shop and upgrade system
+    ├── renderer*.js    # canvas rendering (split by concern)
+    └── ...
+```
+
+---
+
+## License
+
+MIT