diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..0356864
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,69 @@
+# MeatSlicer: A Butcher's Descent
+
+**Clear, harvest, descend.**
+
+MeatSlicer is an endless top-down arena roguelite. You are the Butcher, descending floor by floor through an infinite meat-locker hell: clear rooms of flesh-hungry horrors, draft mutations, stack grotesque passive items into a broken build, kill the boss, take the stairs. The descent never ends — the only question is how deep you get before you're butchered, and whether your score becomes the new best cut.
+
+## Documentation index
+
+| Doc | Contents |
+|---|---|
+| [Gameplay Guide](gameplay.md) | Core loop, controls, player stats, rooms & floors, pickups, leveling, scoring, pressure/difficulty systems, HUD |
+| [Weapons](weapons.md) | All 16 weapons with exact stats, drop tiers, and damage math |
+| [Items](items.md) | All 46 passive items, stacking/tier rules, proc numbers, synergies |
+| [Perks](perks.md) | All 23 Mutation Draft perks, XP curve, draft mechanics |
+| [Enemies](enemies.md) | All 6 enemy types, elites, drops, wave and scaling formulas |
+| [Bosses](bosses.md) | All 9 bosses: rotation, scaling, full attack patterns, counters |
+
+### Quick numbers
+
+- **16 weapons** (1 infinite-ammo sidearm + 15 special weapons across 4 tiers)
+- **46 passive items** (stacking, tier cap IX)
+- **23 perks** (draft 1 of 3 per level-up)
+- **6 enemy types** (+ elite variants)
+- **9 bosses** (fixed rotation, one per floor)
+- **∞ floors** (permadeath, endless descent, high-score chase)
+
+## Running the game
+
+### Browser (quickest)
+
+```
+play.bat
+```
+
+Serves the game locally at <http://localhost:8123> and opens it. Close the minimized server window to stop.
+
+### Electron (desktop app)
+
+```
+npm install
+npm start
+```
+
+### Build a distributable
+
+```
+npm run dist
+```
+
+Packages a Windows zip via electron-builder into `dist/`.
+
+### Tests
+
+```
+npm test
+```
+
+Runs the smoke test (`test/smoke.js`).
+
+## Tech overview
+
+- **Stack:** plain JavaScript + HTML5 canvas, no framework. Electron wrapper for desktop.
+- **Entry:** `index.html` loads `js/main.js` and the game modules directly (no bundler).
+- **Code layout** (`js/`): `main` (loop, screens), `state` (global state), `rooms` (floor gen), `player`, `input`, `weapons`, `bullets`, `items`, `perks`, `pickups`, `enemies`, `bosses`, `hud`, `sprites`, `particles`, `audio`, `sfx`, `sfxbank`, `utils`.
+- **Persistence:** `localStorage` only (best score, volumes, auto-draft setting).
+
+## The fantasy in one paragraph
+
+Rooms lock behind you. The meat waves come in threes. Elites gleam gold and drop the good stuff. The Pressure gauge climbs the longer you stay flawless, and every boss — saw, crown, mother, flenser, choir, father, auger, scald — cycles back around, deeper and meaner, until the meat finally wins. Take the meat. Take the stairs.
diff --git a/docs/bosses.md b/docs/bosses.md
new file mode 100644
index 0000000..4c43a86
--- /dev/null
+++ b/docs/bosses.md
@@ -0,0 +1,186 @@
+# Bosses
+
+All **9 bosses** in MeatSlicer, their rotation, scaling, and complete attack patterns. Pulled from `js/bosses.js`.
+
+---
+
+## Boss rotation
+
+Bosses rotate in a fixed 9-boss cycle. The boss you fight depends only on the floor number: `boss index = (floor − 1) mod 9`.
+
+| Floor | Boss | Cycle | Tier |
+|---|---|---|---|
+| 1 | Bone Saw | 0 | 0 |
+| 2 | Gore Crown | 0 | 0 |
+| 3 | Knife Floor Crawl | 0 | 0 |
+| 4 | Veal Mother | 1 | 0 |
+| 5 | The Flenser | 1 | 0 |
+| 6 | Hook Choir | 1 | 0 |
+| 7 | Plate Father | 2 | 0 |
+| 8 | Auger Prime | 2 | 0 |
+| 9 | The Scald | 2 | 0 |
+| 10 | Bone Saw | 3 | 1 |
+| 11 | Gore Crown | 3 | 1 |
+| … | *(cycle repeats; tier rises every 3 floors)* | | |
+
+- **Cycle** = `floor((floor − 1) / 3)` — how many 3-floor brackets deep you are.
+- **Tier** = `cycle − debutCycle` (min 0) — the boss's personal difficulty level. Each boss debuts at tier 0 and gains a tier every time its bracket comes around again. Higher tiers unlock extra attacks noted in each entry.
+
+### Shared boss rules
+
+- **Contact damage:** 2 (never scales).
+- **Enrage:** below 35% max HP — ×1.35 speed, faster attack cooldowns, and denser bullet patterns. One-time enrage howl.
+- **HP scaling:** `base × (1 + 0.30 × (floor − 1)) × (1 + 0.05 × power score) × pressure`
+- **Speed scaling:** `base × (1 + 0.10 × cycle + 0.01 × power score) × pressure`
+- **Telegraphed attacks** (red zones, knife circles, sweep beams) deal 1 damage on their ticks, separate from contact damage.
+
+### Boss rewards
+
+Killing a boss grants **500 + floor × 100** score, clears all hostile bullets/telegraphs/minions, and spawns:
+
+- **1 item pedestal** (left of room center)
+- **1 weapon drop** rolled at **floor + 2** (right of center)
+- **Stairs Down** (below center)
+
+> *"[NAME] DESTROYED — take the meat, take the stairs"*
+
+---
+
+## 1. Bone Saw
+
+**Debut:** Floor 1 · **Base HP:** 520 · **Base speed:** 60 · **Hitbox:** 45
+
+The opener: a lumbering circular saw that chases at 3× its base speed and mixes projectile fans with a telegraphed charge.
+
+**Attacks:**
+
+- **Saw fling** (45% of attack choices): fan of 6 saws (10 when enraged), speed 240, damage 1, 3.2 s life, spread 0.28 rad around your direction.
+- **Charge** (55%): aims for 0.6 s (locked direction), then dashes at **430 × speed mult** for 0.85 s, trailing blood. Slamming into a wall ends the charge with a screen shake. Cooldown ~3.2 s between attack rolls (2.2 s enraged).
+
+**Tier scaling:** none beyond stats and enrage — the simplest boss. Strafe the charge, punish the recovery.
+
+## 2. Gore Crown
+
+**Debut:** Floor 2 · **Base HP:** 600 · **Base speed:** 42 · **Hitbox:** 48
+
+Slow, relentless summoner-king with radial bullet patterns.
+
+**Attacks:**
+
+- **Gore volleys** (every 2nd attack, from cycle 1): aimed fan of `3 + min(cycle, 4)` bullets, speed 260, damage 1.
+- **Ring attacks** (alternating): ring of `12 + cycle × 4` bullets (18 + cycle × 4 enraged; both cap at 40), speed 170, 4 s life. Tier 3+: rings rotate into spirals. Tier 2+: every 3rd attack is a **double ring** with an offset second ring.
+- **Summon** (every `max(7 − cycle × 0.5, 3.5)` s, 5 s enraged): calls `min(2 + cycle, 5)` minions away from you — 60% Runners / 40% Minis, with Splitters (tier 1+, 30%) and Exploders (tier 2+, 25%) mixed in.
+
+Attack cooldown: `max(2.4 − cycle × 0.15, 1.2)` s (1.6 s base enraged). Kill summons before the arena clogs.
+
+## 3. Knife Floor Crawl
+
+**Debut:** Floor 3 · **Base HP:** 560 · **Base speed:** 75 · **Hitbox:** 45
+
+Fast hunter that litters the floor with knife telegraphs and chains dashes.
+
+**Attacks:**
+
+- **Knife telegraphs:** places `min(3 + cycle, 6)` circle traps; the first is centered on you (tier 1+: it *tracks* you at 140 px/s for 0.4 s before locking). Warning time `max(0.7 − cycle × 0.05, 0.45)` s. On expiry they hit for 1 damage, then **linger for 1.1 s**, ticking every 0.4 s for 1 damage each.
+- **Cleaver volley** (tier 2+): fan of `3 + min(cycle − 1, 3)` cleavers, speed 300, 2.5 s life.
+- **Dash** (chance `min(0.3 + cycle × 0.08, 0.6)` per attack): dashes at 320 × speed mult for 0.5 s, leaving a knife telegraph at the endpoint (tier 1+). Tier 4+: chains a second dash.
+
+Attack cooldown: `max(2.6 − cycle × 0.15, 1.3)` s. Keep moving diagonally; never backtrack across lingering knives.
+
+## 4. Veal Mother
+
+**Debut:** Floor 4 · **Base HP:** 640 · **Base speed:** 34 · **Hitbox:** 52
+
+Broodmother with a one-time damage shield and steady summons.
+
+**Brood Shield (key mechanic):** the first time she drops below 50% HP, she spawns **2 elite Splitter escorts**. While any escort lives, she takes only **35% damage** and moves at half speed. Kill the escorts — "BROOD SHIELD BROKEN / the mother is exposed" — then burn her down.
+
+**Attacks:**
+
+- **Escorts alive:** ring of `10 + min(tier, 3) × 2` syringes, speed 175, every 1.6 s.
+- **Escorts dead:** aimed fan of 5 homing syringes (9 at tier 3+), speed 190, homing 1.2, every 3.4 s (2.4 s enraged).
+- **Summon** (every 5.5 s, 3.8 s enraged): `min(3 + tier, 6)` Minis, plus Splitters (tier 1+, 30%) and Exploders (tier 2+, 20%).
+
+## 5. The Flenser
+
+**Debut:** Floor 5 · **Base HP:** 460 · **Base speed:** 96 · **Hitbox:** 40
+
+The fastest boss — a blink assassin that teleports behind you.
+
+**Attack loop** (every 2.4 s, 1.5 s enraged):
+
+1. **Fade:** turns invulnerable and invisible over 0.35 s.
+2. **Gone:** repositions *behind you* (90–140 px away) for 0.5 s (0.3 s enraged). Drops a knife telegraph at its new position (radius 38); tier 1+: also one at its old position (radius 30).
+3. **Strike:** reappears firing a 7-cleaver volley at you (speed 330, spread 0.16 rad; tier 2+: a second offset wave at speed 295), then dashes *away* at 380 × speed mult.
+
+Tier 3+: blinks **twice** per loop. Never stand still during its fade — the strike always comes from behind your current aim direction.
+
+## 6. Hook Choir
+
+**Debut:** Floor 6 · **Base HP:** 580 · **Base speed:** 46 · **Hitbox:** 50
+
+Slow chanter surrounded by orbiting harpoon hooks that periodically fling outward.
+
+**Attacks:**
+
+- **Orbiting hooks:** inner ring of `4 + min(tier, 3)` hooks (radius 70, spin 1.9; 2.65 enraged). Tier 1+: outer ring of `4 + min(tier, 2)` hooks (radius 110, counter-spin −1.6). Hooks damage on contact (damage 1) and live 20 s; rings respawn 1.2 s after being released.
+- **Wind & release** (every 4 s, 2.8 s enraged): 0.7 s wind-up expands all hooks to radius 170 spinning 1.75× faster, then releases them **tangentially at speed 300**. Tier 3+: released hooks home (0.8).
+- **Volley** (every 2.8 s): 3 aimed harpoons, speed 260.
+
+The release is the dangerous moment — the hooks leave along the tangent, so sidestep radially (toward/away from the boss), not along the ring.
+
+## 7. Plate Father
+
+**Debut:** Floor 7 · **Base HP:** 700 · **Base speed:** 38 · **Hitbox:** 54
+
+Armored juggernaut with breakable plating.
+
+**Armor plates (key mechanic):** starts with **4 plates** and takes only **25% damage**. Every 6% of max HP in damage taken breaks one plate (0.45 s stun, "PLATE BROKEN"). With all 4 gone: "ARMOR BREACHED" — full damage. Effectively ~24% of his HP is spent under 75% reduction.
+
+**Attacks** (alternating, every 3 s / 2 s enraged):
+
+- **Projectile walls:** ring of 20 gore bullets, speed 150, with a `3`-bullet gap (tier 1+: gap of 2). Tier 2+: a second, slower ring (speed 125) with its own offset gap. Slip through the gap.
+- **Tallow Stomp:** winds up 0.7 s, then erupts a ring of 6 fire hazards at radius 120 (tier 3+: a second ring at 200). Hazards: 3.5 s life, 1 damage per 0.45 s tick.
+
+## 8. Auger Prime
+
+**Debut:** Floor 8 · **Base HP:** 600 · **Base speed:** 52 · **Hitbox:** 48
+
+Drill titan whose signature is a rotating beam sweep.
+
+**Attack loop** (every 3.6 s, 2.4 s enraged):
+
+1. Locks onto your position and **spools** for 0.8 s (0.5 s enraged), stationary.
+2. **Sweep:** fires `1` rotating beam (tier 1+: 2 arms, tier 3+: 3 arms), length 420, width 26, sweeping for 2.2 s at 1.15 rad/s (tier 2+: 1.65 rad/s) in a random direction. Beam ticks check every 0.5 s — touching the line deals 1 damage.
+3. Also launches 3 aimed saws (speed 150, accelerating +260, **bounce once** off walls, 2.6 s life).
+
+Stay outside the beam's radius or circle against the spin direction; the boss is stationary and punishable during the whole 2.2 s sweep.
+
+## 9. The Scald
+
+**Debut:** Floor 9 · **Base HP:** 620 · **Base speed:** 40 · **Hitbox:** 50
+
+Area-denial boiler that floods the arena with acid.
+
+**Attacks** (every 2.8 s, 1.9 s enraged):
+
+- **Acid pools:** telegraphs `3 + min(tier, 2)` pools (tier 2+: 7), radius 46 (tier 1+: 58), one always centered on you. After a 0.6 s warning they become acid hazards for 5 s (7 s enraged), ticking 1 damage every 0.4 s. Up to 14 active at once — floor space is the real resource in this fight.
+- **Steam burst** (every 3rd attack): ring of 16 steam bolts, speed 220 decelerating (−60), 3.4 s life. Tier 3+: a second, slower ring (speed 155, 4.2 s life).
+
+Keep to the edges, rotate with the room, and never let pools cut off your only escape lane.
+
+---
+
+## Boss cheat sheet
+
+| Boss | Core threat | Counter |
+|---|---|---|
+| Bone Saw | Telegraphed charge | Sidestep, punish wall crashes |
+| Gore Crown | Rings + summons | Kill adds fast; weave ring gaps |
+| Knife Floor Crawl | Lingering knife zones | Never retrace your steps |
+| Veal Mother | 65% damage reduction shield | Focus the Splitter escorts first |
+| The Flenser | Backstab blink | Move when it fades; watch your six |
+| Hook Choir | Orbital hook release | Dodge radially on release |
+| Plate Father | 75% damage reduction | Grind plates; use wall-ring gaps |
+| Auger Prime | Rotating beam sweep | Circle the spin; punish the stationary sweep |
+| The Scald | Acid floor denial | Rotate along edges; keep lanes open |
diff --git a/docs/enemies.md b/docs/enemies.md
new file mode 100644
index 0000000..30b6177
--- /dev/null
+++ b/docs/enemies.md
@@ -0,0 +1,153 @@
+# Enemies
+
+All **6 enemy types** in MeatSlicer, plus elites, drops, and the exact difficulty-scaling formulas. Pulled from `js/enemies.js` and `js/rooms.js`.
+
+---
+
+## Enemy roster
+
+### Shambler
+
+| Stat | Value |
+|---|---|
+| Base HP | 26 |
+| Base speed | 55 |
+| Contact damage | 1 |
+| Hitbox radius | 18 |
+| XP | 1 |
+| First appears | Floor 1 (spawn weight 40) |
+
+The basic chaser. Shuffles toward you with a sinusoidal wobble. Individually harmless, dangerous in the packed waves of later floors.
+
+### Runner
+
+| Stat | Value |
+|---|---|
+| Base HP | 12 |
+| Base speed | 236 |
+| Contact damage | 1 |
+| Hitbox radius | 15 |
+| XP | 1 |
+| First appears | Floor 1 (spawn weight 25) |
+
+Extremely fast, fragile chaser — over 4× the Shambler's speed. They arrive first and force you to keep moving.
+
+### Spitter
+
+| Stat | Value |
+|---|---|
+| Base HP | 20 |
+| Base speed | 60 |
+| Contact damage | 1 |
+| Hitbox radius | 18 |
+| XP | 2 |
+| First appears | Floor 2 (spawn weight 18) |
+
+Ranged kiter. Holds 190–250 px away from you — approaches if you're farther than 250 px, retreats if you're closer than 190 px. Fires a gore bolt (speed 220, damage 1, 3 s life) when within 420 px, every **1.9 s**. Elite Spitters fire a 3-shot fan (0.25 rad spread) every **1.1 s**.
+
+### Splitter
+
+| Stat | Value |
+|---|---|
+| Base HP | 30 |
+| Base speed | 70 |
+| Contact damage | 1 |
+| Hitbox radius | 21 |
+| XP | 1 |
+| First appears | Floor 2 (spawn weight 16) |
+
+Chaser that **splits into 2 Minis on death** (non-elite Splitters only). Slightly tankier than a Shambler. Explosions and AoE that kill the Minis with the parent are valuable here.
+
+### Mini
+
+| Stat | Value |
+|---|---|
+| Base HP | 6 |
+| Base speed | 120 |
+| Contact damage | 1 |
+| Hitbox radius | 10 |
+| XP | 1 |
+| First appears | Only from Splitter deaths and boss summons |
+
+Tiny, quick chaser with a small hitbox. Never spawns directly from room waves.
+
+### Exploder
+
+| Stat | Value |
+|---|---|
+| Base HP | 14 |
+| Base speed | 110 |
+| Contact damage | 2 |
+| Hitbox radius | 16 |
+| XP | 2 |
+| First appears | Floor 3 (spawn weight 14) |
+
+Suicide bomber. Charges at you; within 56 px its **0.5 s fuse** lights (it flashes). When the fuse ends — or when it's killed by anything — it detonates: radius 70 (fuse) / 60 (killed), **2 damage**. The blast only hurts *you*, not other enemies. Kill them at range or bait the fuse and back off.
+
+---
+
+## Spawn weights
+
+| Enemy | Floor 1 | Floor 2 | Floor 3+ |
+|---|---|---|---|
+| Shambler | 40 | 40 | 40 |
+| Runner | 25 | 25 | 25 |
+| Spitter | — | 18 | 18 |
+| Splitter | — | 16 | 16 |
+| Exploder | — | — | 14 |
+
+Weights stay flat once unlocked; floors get harder through stat scaling and wave size, not new mixes.
+
+## Elites
+
+Any wave-spawned enemy can roll as an **elite** (gold ring, HP bar pip):
+
+- Chance: `min(0.03 + floor × 0.02, 0.20)` — 5% on floor 1, capping at 20% from floor 9.
+- **HP ×2.6**, speed ×0.9, contact damage **+1**, radius ×1.45, XP ×3.
+- Drops: 3× XP plus 3–5 bonus gems, **18% + luck×10% chance of an item pedestal drop**, otherwise 60% + luck×20% chance of ammo.
+
+## Drops
+
+| Kill | XP | Other drops |
+|---|---|---|
+| Normal enemy | Its XP value | Ammo: 7% + luck×4% · Heart: 2.2% + luck×3% |
+| Elite | 3× XP + 3–5 bonus | Item: 18% + luck×10% · else ammo: 60% + luck×20% |
+
+Your on-kill items (Volatile Bile, Bloodlust, Vampire Dentures, Dead Man's Switch) trigger off every kill — see [items.md](items.md).
+
+---
+
+## Difficulty scaling
+
+Every enemy's stats are computed at **spawn time** from three factors: floor, your power score, and pressure.
+
+**Power score** = `(your level − 1) × 0.5 + (sum of all your item tiers)`
+
+**HP:**
+```
+base HP × (1 + 0.22 × (floor − 1)) × (1 + 0.05 × power) × (elite ? 2.6 : 1) × pressure
+```
+
+**Speed:**
+```
+base speed × (1 + 0.04 × (floor − 1) + 0.01 × power) × (elite ? 0.9 : 1) × rand(0.9, 1.1) × pressure
+```
+
+**Contact damage:** flat per type (elites +1) — it **never scales with floor**. What kills you late-game is volume, speed, and HP pools, not bigger hit numbers.
+
+**Pressure** (see [gameplay.md](gameplay.md#pressure-dynamic-difficulty)) ranges 0.75–1.60 and multiplies both HP and speed. Playing flawlessly pushes it up; getting hit pulls it down.
+
+### Example: Floor 10 Shambler
+
+Level 8 player (3.5 power) with 8 item tiers (8 power) → power 11.5, pressure 1.2:
+
+```
+HP:  26 × (1 + 0.22×9) × (1 + 0.05×11.5) × 1.2  =  26 × 2.98 × 1.575 × 1.2  ≈ 146
+Spd: 55 × (1 + 0.04×9 + 0.01×11.5) × 1.2          ≈ 55 × 1.475 × 1.2          ≈ 97
+```
+
+vs. 26 HP / 55 speed on floor 1. Build damage accordingly.
+
+## Wave sizes
+
+Combat rooms spawn `3 + ceil(floor × 1.4)` enemies in wave 1, plus a second wave (×0.7) from floor 2 and a third (×0.5) from floor 4. Full table in [gameplay.md](gameplay.md#waves-per-combat-room). Hard cap: 72 enemies alive at once.
diff --git a/docs/gameplay.md b/docs/gameplay.md
new file mode 100644
index 0000000..85a96d2
--- /dev/null
+++ b/docs/gameplay.md
@@ -0,0 +1,268 @@
+# Gameplay Guide
+
+Everything about how a run of **MeatSlicer: A Butcher's Descent** works: the loop, controls, player mechanics, drops, scoring, and difficulty scaling.
+
+See also: [Weapons](weapons.md) · [Items](items.md) · [Perks](perks.md) · [Enemies](enemies.md) · [Bosses](bosses.md)
+
+---
+
+## Core Game Loop
+
+MeatSlicer is an **endless arena roguelite**. There is no final floor and no victory screen — the goal is to descend as deep as you can and maximize your score before you die. Death is permanent (permadeath); only your high score persists.
+
+A run looks like this:
+
+1. **Enter a floor.** Each floor is a small map of rooms (see *Floor Generation*).
+2. **Clear combat rooms.** Doors lock until every wave of enemies in the room is dead.
+3. **Find the item room.** A free passive item (plus a 35% chance of a weapon).
+4. **Kill the floor boss.** The boss room is always the farthest room from the start.
+5. **Take the loot, take the stairs.** Bosses drop an item pedestal, a weapon, and the stairs down. Walk onto the stairs to descend.
+6. Repeat, deeper and harder, until you are butchered.
+
+### Score
+
+Score is display-only (it buys nothing) and determines your saved best:
+
+| Source | Score |
+|---|---|
+| Normal enemy kill | +10 |
+| Elite enemy kill | +40 |
+| Boss kill | +500 (plus drop bonus below) |
+| Boss defeated bonus | 500 + floor × 100 |
+| Combat room cleared | +50 |
+| Descending to next floor | +250 |
+| XP gained | +1 per XP (rounded) |
+| Heart picked up at full HP | +25 |
+| Ammo picked up with nothing to refill | +15 (+2 per wasted unit otherwise) |
+| Duplicate item at tier cap (IX) | +150 |
+
+Your best score is saved in `localStorage` as `meatslicer_best` and shown on the title screen and game-over screen ("NEW BEST CUT" when beaten).
+
+---
+
+## Controls
+
+### In-game
+
+| Input | Action |
+|---|---|
+| **W / A / S / D** or **Arrow keys** | Move |
+| **Mouse** | Aim |
+| **Left mouse button (hold)** | Fire |
+| **Left mouse release** | Fire charged beam (Spinal Tap only) |
+| **R** | Swap between Bone Popper and holstered special weapon |
+| **P / Escape** | Pause / resume |
+| **T** | Toggle Auto-Draft (auto-pick random perk on level-up) |
+| **M** | Mute / unmute |
+| **N** | Next music track |
+
+### Perk draft screen (level-up)
+
+| Input | Action |
+|---|---|
+| **1 / 2 / 3** | Choose perk 1, 2, or 3 |
+| **Click a card** | Choose that perk |
+| **4 / Space** | Random Cut — pick a random perk of the three |
+| **R** | Reroll the three choices (costs 1 reroll token) |
+| **T** | Enable Auto-Draft |
+
+### Pause screen (jukebox)
+
+| Input | Action |
+|---|---|
+| **- / =** | SFX volume down / up |
+| **, / .** | Music volume down / up |
+| **[ / ]** or **Left / Right arrows** | Previous / next music track |
+| **Click arrows** | Cycle music tracks |
+
+### Menus
+
+| Input | Action |
+|---|---|
+| **Enter / Space / Click** | Start run (title), restart after death |
+
+Right-click is disabled (context menu suppressed). There is **no dash, no interact key** — pickups are collected by walking over them.
+
+---
+
+## The Player
+
+### Base stats
+
+| Stat | Value |
+|---|---|
+| Max HP | 6 (shown as 3 hearts, 2 HP per heart) |
+| Hitbox radius | 20 px |
+| Move speed | 178 px/s |
+| Crit chance | 5% |
+| Crit damage | ×2.0 |
+| Post-hit invulnerability | 0.9 s |
+| Room-entry protection | 1.0 s of invulnerability on entering any room |
+| Starting weapon | Bone Popper (infinite ammo sidearm) |
+| Starting level | 1 (0 XP) |
+
+### Damage, armor, and shields
+
+- Every hit taken deals a **minimum of 1 damage** (`max(1, round(dmg))`).
+- **Armor** gives a chance to completely ignore a hit: block chance = `armor / (1 + armor)`, capped at 75%. A blocked hit shows "BLOCKED" and grants only 0.2 s of invulnerability.
+- **Shield hearts** (cyan pips) absorb damage before real HP. They come from the Bone Plate item and Shield Heart perk, and are refilled to full at the start of each floor. Losing your last shield pip triggers a "SHIELD DOWN" warning.
+- Getting hit knocks you back 14 px, shakes the screen, and flashes a red vignette.
+
+### Healing
+
+- Hearts restore 2 HP (1 heart) each.
+- Healing past max HP normally goes to waste (converted to +25 score for heart pickups) — unless you have the **Second Stomach** item, which converts overflow healing into shield HP.
+- Other healing sources: Vampire Dentures (kill procs), Hemophage (hit procs), Worm Gut / Bone Knit (post-combat heals).
+
+---
+
+## Floors & Rooms
+
+### Floor generation
+
+- Room count: `min(5 + floor, 9)` — Floor 1 has 6 rooms, Floor 4 onward always has 9.
+- Layout is a random walk from a start room, with ~50% branch chance per step.
+- The **farthest room** from the start becomes the **boss room**.
+- The **second-farthest room** (distance ≥ 2) becomes the **item room**.
+- Everything else is a combat room. Adjacent rooms are connected by doors.
+
+### Room types
+
+| Room | Contents | Cleared when… |
+|---|---|---|
+| **Start** | Nothing | Always cleared |
+| **Combat** | 1–3 waves of enemies | All waves dead |
+| **Item** | 1 item pedestal + 35% chance of a weapon | Immediately (no fight) |
+| **Boss** | Floor boss | Boss dies |
+
+Doors in combat and boss rooms **lock** until the room is cleared. Re-entering an uncleared room restarts its remaining waves.
+
+### Waves per combat room
+
+```
+base = 3 + ceil(floor × 1.4)      wave 1: always
+floor ≥ 2:  + wave 2 of ceil(base × 0.7)
+floor ≥ 4:  + wave 3 of ceil(base × 0.5)
+```
+
+Waves spawn 0.9 s apart, up to a hard cap of 72 simultaneous enemies.
+
+| Floor | Wave sizes |
+|---|---|
+| 1 | 5 |
+| 2 | 6 / 5 |
+| 3 | 8 / 6 |
+| 4 | 9 / 7 / 5 |
+| 6 | 12 / 9 / 6 |
+| 9 | 16 / 12 / 8 |
+
+### Combat room rewards
+
+Clearing a combat room drops:
+
+- **XP gems** worth `irand(3, 5 + floor)` total
+- **Ammo** at `24% + luck × 30%` chance
+- **Heart** at `10% + luck × 30%` chance
+
+---
+
+## Pickups
+
+| Pickup | Effect |
+|---|---|
+| **XP Gem** (small, value 1 / big, value 5) | Grants XP × your `xpMul`. Fills the level bar; each level-up opens the Mutation Draft. |
+| **Heart** | Heals 2 HP. At full HP: +25 score instead. |
+| **Ammo** | Refills carried special weapons (current + holstered) by a fraction of their capacity × `ammoPickupMul`, up to 150% capacity. Overflow becomes score. |
+| **Weapon** | Equips on walk-over. Your old special weapon drops with its remaining ammo (Bone Popper is never dropped). |
+| **Item** (on pedestal) | Grants/upgrades a passive item. Hovering near a pedestal shows its name. |
+| **Stairs Down** | Appears after every boss kill. Walk over to descend. |
+
+### Pickup behavior
+
+- **Magnet radius:** `46 × magnet` px (46 px base) — gems, hearts, and ammo fly to you.
+- **Pickups land 0.6 s after spawning** before they can be collected.
+- Only gems, hearts, and ammo are magnetized; weapons, items, and stairs require walking over them.
+
+### Kill drops
+
+| Source | Drops |
+|---|---|
+| Normal enemy | XP gems (enemy's XP value) · 7% + luck×4% ammo · 2.2% + luck×3% heart |
+| Elite enemy | 3× XP + 3–5 bonus gems · 18% + luck×10% **item** · else 60% + luck×20% ammo |
+| Boss | 1 item pedestal + 1 weapon (rolled at floor + 2) + stairs |
+
+**Luck** is a player stat (Lucky Coin, Crow Bait, Scavenger perk) that scales most drop chances as shown above.
+
+---
+
+## Leveling & Mutation Draft
+
+- XP needed for the next level: `8 + level × 4` (level 1→2 needs 12 XP, then 16, 20, 24…).
+- Each level-up queues a **Mutation Draft**: choose 1 of 3 random perks. Multiple queued drafts resolve one after another.
+- **Rerolls** (from the Reroll Rib item) let you re-draw the three choices with R.
+- **Auto-Draft** (T) skips the screen and picks randomly — the setting persists between sessions.
+
+---
+
+## Pressure (Dynamic Difficulty)
+
+The **PRESSURE** meter on the HUD is a run-long adaptive difficulty multiplier applied to enemy and boss **HP and speed at spawn time**:
+
+- Range: **0.75 – 1.60** (starts at 1.00).
+- **+0.01** for every room cleared **without taking damage** (flawless streak).
+- Taking damage **relieves** pressure, scaled by how big the hit was, how low your HP is, and how many recent hits you've taken.
+- Decays passively at 0.02/s while below 35% HP, or 0.008/s if you stall in a room for 90+ seconds.
+- Only affects enemies spawned *after* the change — living enemies keep their stats.
+
+In short: playing flawlessly slowly raises the heat; getting hurt cools things down.
+
+### Streak
+
+The HUD also tracks your **streak** of consecutive rooms cleared without damage. It is purely cosmetic bragging rights — its only mechanical effect is feeding the pressure gain above.
+
+---
+
+## Difficulty Scaling (summary)
+
+Enemy stats scale with floor number, your **power score**, and pressure:
+
+- **Power score** = `(level − 1) × 0.5 + (sum of all item tiers)`.
+- Enemy HP: `base × (1 + 0.22 × (floor−1)) × (1 + 0.05 × power) × pressure` (elites ×2.6 more).
+- Enemy speed: `base × (1 + 0.04 × (floor−1) + 0.01 × power) × pressure` (±10% random).
+- Enemy **contact damage does not scale** with floor — only elites get +1.
+- Bosses scale the same way but with 30% HP per floor instead of 22%.
+
+Full formulas are in [enemies.md](enemies.md) and [bosses.md](bosses.md).
+
+---
+
+## HUD Reference
+
+- **Top-left — BUTCHER // VITALS:** level, hearts (red) and shield hearts (cyan), XP bar, active weapon + ammo (red when below 25%), holstered weapon with `[R]` swap hint.
+- **Item tray** (below vitals): up to 24 item icons with tier numerals I–IX.
+- **Top-right — SECTOR MAP:** minimap. White = current room, red = boss, gold = item, gray = cleared, maroon = uncleared. Includes floor number.
+- **Bottom-right — RUN DATA:** floor, kills, score, PRESSURE %, STREAK, pressure bar.
+- **Bottom-center:** boss HP bar (during boss fights).
+- **Top-center:** toast notifications (pickups, floor intros, boss events).
+
+### Screens
+
+| Screen | What it offers |
+|---|---|
+| **Title** | INITIATE DESCENT, control reference, best score |
+| **Pause** | Jukebox (track cycling), SFX/music volume, resume/swap/auto/mute hints |
+| **Mutation Draft** | 3 perk cards, random cut, reroll, auto-draft |
+| **Game Over ("BUTCHERED")** | Floor, kills, score, NEW BEST CUT tag, restart |
+
+---
+
+## Persistence
+
+Stored in `localStorage` between sessions:
+
+- `meatslicer_best` — high score
+- `meatslicer_sfx_volume` (default 0.45)
+- `meatslicer_music_volume` (default 0.55)
+- `meatslicer_autoperk` — auto-draft toggle
+
+Nothing else carries over: no unlocks, no meta-currency, no saved runs. Every descent starts fresh with a Bone Popper and 6 HP.
diff --git a/docs/items.md b/docs/items.md
new file mode 100644
index 0000000..45b1571
--- /dev/null
+++ b/docs/items.md
@@ -0,0 +1,169 @@
+# Items
+
+All **46 passive items** in MeatSlicer, with exact effects pulled from `js/items.js` and the proc logic in `js/enemies.js` / `js/player.js`.
+
+---
+
+## How items work
+
+- Items are **passive and permanent** for the run. Pick one up and its effect applies immediately.
+- **Duplicates upgrade the tier** (shown as Roman numerals **I–IX** on the pedestal and in your item tray). Each duplicate re-applies the item's effect — multiplicative stats compound, additive stats stack linearly.
+- **Tier cap is 9.** Picking up a duplicate at tier IX instead grants +150 score and 5 XP gems with a "MAX" toast.
+- There is **no rarity system**. Item rolls use a "smart roll": 50% chance to upgrade an item you already own (below cap), 50% chance of any item from the full pool — so builds naturally specialize over a run.
+
+### Where items come from
+
+| Source | Chance |
+|---|---|
+| Item room pedestal | Guaranteed (1 per floor) |
+| Boss kill | Guaranteed (1 pedestal) |
+| Elite enemy kill | 18% + luck × 10% |
+
+---
+
+## Damage & Fire Rate
+
+| Item | Description | Effect per tier |
+|---|---|---|
+| **Hollow Points** | +25% damage | `dmgMul ×1.25` |
+| **Marrow Glut** | +20% damage, −10% fire rate | `dmgMul ×1.20`, `rateMul ×0.90` |
+| **Bloat Rounds** | +25% attack size, +10% damage | `sizeMul ×1.25`, `dmgMul ×1.10` |
+| **Twitch Fibers** | +20% fire rate | `rateMul ×1.20` |
+| **Grafted Trigger** | +18% fire rate | `rateMul ×1.18` |
+
+Note: attack size (`sizeMul`) also enlarges melee arcs, blast radii, acid pools, and projectile hitboxes — Bloat Rounds is secretly an AoE item.
+
+## Shot Modifiers
+
+| Item | Description | Effect per tier |
+|---|---|---|
+| **Scalpel** | +25% shot speed | `shotSpeedMul ×1.25` |
+| **Lead Marrow** | +25% range | `rangeMul ×1.25` |
+| **Piercing Gaze** | Shots pierce +1 enemy | `pierce +1` |
+| **Ricochet Ribs** | Shots bounce +1 time | `bounce +1` (wall bounces) |
+| **Split Tongue** | Twin parallel shot | `split +1` — extra parallel shots per volley |
+| **Hydra Maw** | Fires 2 extra angled shots | `fan +1` — extra angled shots (±0.16 rad per level) |
+| **Homing Tumor** | Shots seek flesh (stronger per tier) | `homing +1` — homing strength `1.6 + homing × 0.7` |
+| **Backstabber** | +1 rear shot | `rear +1` — fires backward too |
+| **Splinter Bone** | Shots shatter into +2 shards on hit | `splinter +2` — on-hit shards dealing 40% of the hit's damage each |
+
+## On-Hit Procs
+
+All of these trigger from your weapon hits (orbital knives proc at half chance). Chances stack additively across tiers and are rolled per hit.
+
+| Item | Description | Exact effect per tier |
+|---|---|---|
+| **Flayer Kiss** | Hits inflict heavy bleeding | `bleed +0.20` — every hit applies 2.2 s bleed at `hit damage × bleed × 0.45` DPS |
+| **Ember Jar** | 20% chance to ignite | `+0.20` chance — burn for 1.8 s at `5 × dmgMul` DPS |
+| **Acid Gland** | Hits may leave acid pools | `+0.12` chance (cap 65%) — pool radius 18 × sizeMul, 2.5 s, `5 × dmgMul` DPS |
+| **Hook Rounds** | Hits pull enemies toward you | `+0.18` chance (cap 80%) — yanks the enemy toward you at speed 170 |
+| **Sledge Rounds** | More knockback, hits may stun | `knockbackMul ×1.35`, `+0.08` stun chance (cap 75%) — 0.35 s stun, non-bosses only |
+| **Chain Sinew** | Hits arc to +1 nearby enemy | `chain +1` — arcs to up to 6 nearby enemies within 180 px for 35% of the hit's damage each |
+| **Mortar Bone** | Every sixth hit erupts | `mortar +1` — every `max(2, 7 − mortar)` hits, AoE blast: radius `42 + mortar × 5`, 55% of the hit's damage |
+
+## On-Kill Effects
+
+| Item | Description | Exact effect per tier |
+|---|---|---|
+| **Vampire Dentures** | Kills may heal you | `lifestealChance +0.04` — on kill, `chance × 3` (cap 90%) to heal 1 HP (2 for elites, 4 for bosses) |
+| **Volatile Bile** | Kills explode (bigger per tier) | `explodeOnKill +1` — kill explosions: radius `60 + 15/tier`, damage `(10 + 8/tier) × dmgMul` |
+| **Bloodlust** | Kills may drop bonus XP | `+0.12` chance per kill to drop bonus XP equal to the enemy's XP value |
+| **Dead Man's Switch** | Kills trigger a fire-rate frenzy | `frenzy +0.12` — any kill grants `1 + frenzy` fire rate for 3 s |
+
+## Survivability
+
+| Item | Description | Exact effect per tier |
+|---|---|---|
+| **Iron Stomach** | +½ heart container, heal ½ heart | `maxHp +1`, heal 1 |
+| **Ghoul Heart** | +2 max HP, heal 2 | `maxHp +2`, heal 2 |
+| **Twin Hearts** | +1 max heart, heal 1 heart | `maxHp +2`, heal 2 (identical to Ghoul Heart) |
+| **Bone Plate** | +½ shield heart each floor | `shieldPerk +1`, `shieldHp +1` — shields refill every floor |
+| **Second Stomach** | +½ heart and excess healing shields | `maxHp +1`, heal 1, `overShield +1` — overflow healing becomes shield HP |
+| **Tanned Hide** | +8% chance to ignore damage | `armor +0.087` — block chance `armor / (1 + armor)`, cap 75% |
+| **Dead Man's Clock** | +0.25s hurt immunity | `invBonus +0.25` — post-hit invulnerability 0.9 s → 1.15 s at tier I |
+| **Worm Gut** | Heal ½ heart after combat rooms | `roomHeal +1` — guaranteed 1 HP heal after each combat room clear |
+| **Spine Cage** | Contact attackers take damage | `thorns +8` — melee attackers take `8 × dmgMul` when they hurt you |
+| **Spite Well** | Taking damage releases a blood nova | `retaliate +10` — on hit taken: nova radius 85 × √sizeMul, damage `10 × dmgMul` |
+
+## Criticals
+
+| Item | Description | Effect per tier |
+|---|---|---|
+| **Bloodshot Eye** | +6% critical chance | `crit +0.06` (base 5%) |
+| **Hollow Needle** | +50% critical damage | `critMul +0.50` (base ×2.0) |
+
+## Utility
+
+| Item | Description | Exact effect per tier |
+|---|---|---|
+| **Orbital Knives** | +1 circling knife | `orbitals +1` — each knife orbits you, dealing `12 × dmgMul × orbDmgMul` on contact (0.35 s cooldown per enemy, half proc chance) |
+| **Orbit Crown** | +25% orbital speed and damage | `orbSpeedMul ×1.25`, `orbDmgMul ×1.25` |
+| **Lucky Coin** | Better drops | `luck +0.2` |
+| **Crow Bait** | +25% drop luck | `luck +0.25` |
+| **Magnet Maw** | +60% pickup radius | `magnet ×1.6` — magnet radius 46 × magnet px |
+| **Gorging Leech** | +20% XP gained | `xpMul ×1.20` |
+| **Reroll Rib** | +1 perk reroll each level | `rerollPerLevel +1` and +1 reroll immediately |
+| **Brass Magazine** | 15% less ammo use, +20% ammo found | `ammoEff ×1.15`, `ammoPickupMul ×1.20` |
+| **Hollow Bones** | +12% move speed | `speedMul ×1.12` (178 → ~199 px/s at tier I) |
+
+---
+
+## Complete item index (A–Z)
+
+| # | Item | Category |
+|---|---|---|
+| 1 | Acid Gland | On-hit proc |
+| 2 | Backstabber | Shot modifier |
+| 3 | Bloodlust | On-kill |
+| 4 | Bloodshot Eye | Criticals |
+| 5 | Bloat Rounds | Damage |
+| 6 | Bone Plate | Survivability |
+| 7 | Brass Magazine | Utility |
+| 8 | Chain Sinew | On-hit proc |
+| 9 | Crow Bait | Utility |
+| 10 | Dead Man's Clock | Survivability |
+| 11 | Dead Man's Switch | On-kill |
+| 12 | Ember Jar | On-hit proc |
+| 13 | Flayer Kiss | On-hit proc |
+| 14 | Ghoul Heart | Survivability |
+| 15 | Gorging Leech | Utility |
+| 16 | Grafted Trigger | Fire rate |
+| 17 | Hollow Bones | Utility |
+| 18 | Hollow Needle | Criticals |
+| 19 | Hollow Points | Damage |
+| 20 | Homing Tumor | Shot modifier |
+| 21 | Hook Rounds | On-hit proc |
+| 22 | Hydra Maw | Shot modifier |
+| 23 | Iron Stomach | Survivability |
+| 24 | Lead Marrow | Shot modifier |
+| 25 | Lucky Coin | Utility |
+| 26 | Magnet Maw | Utility |
+| 27 | Marrow Glut | Damage |
+| 28 | Mortar Bone | On-hit proc |
+| 29 | Orbit Crown | Utility |
+| 30 | Orbital Knives | Utility |
+| 31 | Piercing Gaze | Shot modifier |
+| 32 | Reroll Rib | Utility |
+| 33 | Ricochet Ribs | Shot modifier |
+| 34 | Scalpel | Shot modifier |
+| 35 | Second Stomach | Survivability |
+| 36 | Sledge Rounds | On-hit proc |
+| 37 | Spine Cage | Survivability |
+| 38 | Spite Well | Survivability |
+| 39 | Splinter Bone | Shot modifier |
+| 40 | Split Tongue | Shot modifier |
+| 41 | Tanned Hide | Survivability |
+| 42 | Twin Hearts | Survivability |
+| 43 | Twitch Fibers | Fire rate |
+| 44 | Vampire Dentures | On-kill |
+| 45 | Volatile Bile | On-kill |
+| 46 | Worm Gut | Survivability |
+
+## Synergy notes
+
+- **Second Stomach** turns *every* healing source into shield generation: Worm Gut, Bone Knit, Vampire Dentures, Hemophage, and hearts at full HP.
+- **On-hit procs scale with hit frequency** — pair Flayer Kiss / Ember Jar / Chain Sinew with the Ribcage Repeater, Bile Blunderbuss, or Cauterizer.
+- **Split Tongue / Hydra Maw / Backstabber** multiply projectile count, which multiplies proc rolls per second — the core of most broken builds.
+- **Piercing Gaze + Ricochet Ribs** feed the slam/saw/beam "inert" bonus (+6% each) on The Tenderizer, Red Right Hand, and Spinal Tap, while also powering Swarm Jar maggots.
+- **Volatile Bile** chains: explosions can kill, which triggers more explosions (and frenzy, and lifesteal procs).
+- **Bone Plate + Shield Heart** (perk) stack into a large shield that refills free every floor.
diff --git a/docs/perks.md b/docs/perks.md
new file mode 100644
index 0000000..365329a
--- /dev/null
+++ b/docs/perks.md
@@ -0,0 +1,110 @@
+# Perks
+
+All **23 perks** in MeatSlicer, with exact effects pulled from `js/perks.js`. Perks are chosen through the **Mutation Draft** each time you level up, and last for the rest of the run.
+
+---
+
+## The Mutation Draft
+
+- Gaining a level queues a draft. When it opens, you're offered **3 random perks** from the full pool — all 23 perks are equally weighted; there is no rarity system.
+- Choose with **1 / 2 / 3**, by **clicking a card**, or press **4 / Space** for a "Random Cut".
+- Press **R** to **reroll** all three choices (costs 1 reroll token). Rerolls come from the **Reroll Rib** item, which also grants +1 reroll every level-up.
+- Press **T** to toggle **Auto-Draft**: future level-ups instantly pick a random perk without pausing the game. The setting persists between sessions.
+- Level-ups queue: gain two levels at once and two drafts resolve back-to-back.
+
+### XP curve
+
+XP needed for the next level: **`8 + level × 4`**
+
+| Level-up | XP needed | Cumulative |
+|---|---|---|
+| 1 → 2 | 12 | 12 |
+| 2 → 3 | 16 | 28 |
+| 3 → 4 | 20 | 48 |
+| 4 → 5 | 24 | 72 |
+| 5 → 6 | 28 | 100 |
+| 10 → 11 | 48 | 300 |
+
+XP comes from gems dropped by kills, room clears, and bosses, scaled by your `xpMul` (Gorging Leech item, Bloodrush perk).
+
+---
+
+## Offensive perks
+
+| Perk | Description | Exact effect |
+|---|---|---|
+| **Sharpened** | +4% damage | `dmgMul ×1.04` |
+| **Adrenal Surge** | +3.5% fire rate | `rateMul ×1.035` |
+| **Deadeye** | +5% shot speed | `shotSpeedMul ×1.05` |
+| **Long Bone** | +5% range | `rangeMul ×1.05` |
+| **Bone Splitter** | +2% critical chance | `crit +0.02` (base 5%) |
+| **Cold Precision** | +15% critical damage | `critMul +0.15` (base ×2.0) |
+| **Heavy Hand** | +20% knockback | `knockbackMul ×1.20` |
+
+## On-hit status perks
+
+| Perk | Description | Exact effect |
+|---|---|---|
+| **Flensing Edge** | Hits inflict light bleeding | `bleed +0.08` — 2.2 s bleed at `hit damage × bleed × 0.45` DPS |
+| **Ember Hands** | 8% chance to ignite | `igniteChance +0.08` — 1.8 s burn at `5 × dmgMul` DPS |
+| **Chill Bile** | 10% chance to slow | `slowOnHit +0.10` — 1.5 s slow (halved move speed) |
+
+## Defensive perks
+
+| Perk | Description | Exact effect |
+|---|---|---|
+| **Big Heart** | +½ max heart, heal ½ heart | `maxHp +1`, heal 1 |
+| **Shield Heart** | +½ shield heart at the start of each floor | `shieldPerk +1`, `shieldHp +1` — refills every floor transition |
+| **Thick Hide** | +4% chance to ignore damage | `armor +1/24 (≈0.0417)` — block chance `armor / (1 + armor)`, cap 75% |
+| **Second Wind** | +0.15s hurt immunity | `invBonus +0.15` — post-hit invulnerability 0.9 s → 1.05 s |
+| **Spite Flesh** | Contact attackers take damage | `thorns +4` — melee attackers take `4 × dmgMul` |
+| **Bone Knit** | 3% chance to heal ½ heart after combat rooms | `roomHealChance +0.03` (cap 90%) |
+
+## Mobility & utility perks
+
+| Perk | Description | Exact effect |
+|---|---|---|
+| **Quickening** | +3% move speed | `speedMul ×1.03` |
+| **Sinew Weave** | +3% move speed and range | `speedMul ×1.03`, `rangeMul ×1.03` |
+| **Magnet Bile** | +10% pickup radius | `magnet ×1.10` |
+| **Carrion Sense** | +8% pickup radius and pull speed | `magnet ×1.08`, `magnetPull ×1.08` *(note: pull speed is not currently wired into pickup movement — the radius half works)* |
+| **Scavenger** | +4% drop luck | `luck +0.04` |
+| **Bloodrush** | +5% XP gain, bonus crystal chance | `xpMul ×1.05` |
+| **Scrap Feed** | 5% less ammo consumed | `ammoEff ×1.05` |
+
+---
+
+## Complete perk index (A–Z)
+
+| # | Perk | Category |
+|---|---|---|
+| 1 | Adrenal Surge | Offensive |
+| 2 | Big Heart | Defensive |
+| 3 | Bloodrush | Utility |
+| 4 | Bone Knit | Defensive |
+| 5 | Bone Splitter | Offensive |
+| 6 | Carrion Sense | Utility |
+| 7 | Chill Bile | On-hit |
+| 8 | Cold Precision | Offensive |
+| 9 | Deadeye | Offensive |
+| 10 | Ember Hands | On-hit |
+| 11 | Flensing Edge | On-hit |
+| 12 | Heavy Hand | Offensive |
+| 13 | Long Bone | Offensive |
+| 14 | Magnet Bile | Utility |
+| 15 | Quickening | Mobility |
+| 16 | Scavenger | Utility |
+| 17 | Scrap Feed | Utility |
+| 18 | Second Wind | Defensive |
+| 19 | Sharpened | Offensive |
+| 20 | Shield Heart | Defensive |
+| 21 | Sinew Weave | Mobility |
+| 22 | Spite Flesh | Defensive |
+| 23 | Thick Hide | Defensive |
+
+## Drafting advice
+
+- **Perks are small, items are big.** A perk is worth ~0.5 power score; an item tier is worth 1.0. Perks smooth out a build; items define it.
+- **Shield Heart** is one of the strongest defensive picks — it's a free refilling shield pip every floor, and it stacks with Bone Plate.
+- **Scavenger / Bloodrush / Magnet Bile** early compound over a long run; **Sharpened / Adrenal Surge** scale whatever your weapon already does well.
+- With **Auto-Draft** on, perks become a no-attention background bonus — good for speedrunning floors, bad if you're fishing for a specific build.
diff --git a/docs/weapons.md b/docs/weapons.md
new file mode 100644
index 0000000..97b212d
--- /dev/null
+++ b/docs/weapons.md
@@ -0,0 +1,333 @@
+# Weapons
+
+All 16 weapons in MeatSlicer, with exact stats pulled from `js/weapons.js`.
+
+Weapons have **no upgrade levels** — their stats are fixed. All scaling comes from [passive items](items.md) and [perks](perks.md).
+
+---
+
+## How weapons work
+
+- You always carry the **Bone Popper** (infinite ammo sidearm) plus **one special weapon** in a holster slot.
+- Press **R** to swap between them. Holstered weapons keep their remaining ammo.
+- Picking up a new special weapon drops your current one (with its remaining ammo) so you can swap back.
+- When a special weapon runs dry, you automatically fall back to the Bone Popper.
+- Special weapons consume ammo per shot: `1 / ammoEff` units per shot (so Brass Magazine's +15% `ammoEff` stretches every magazine).
+
+### Where weapons come from
+
+| Source | Roll |
+|---|---|
+| Boss kill (guaranteed) | Rolled at **floor + 2** — better tiers, earlier |
+| Item room | 35% chance alongside the item, rolled at current floor |
+| Starting loadout | Bone Popper only |
+
+### Drop weights by tier
+
+| Tier | Weight |
+|---|---|
+| 0 (Common) | `max(20, 60 − floor × 5)` |
+| 1 (Uncommon) | `30 + floor × 2` |
+| 2 (Rare) | `10 + floor × 3` |
+| 3 (Legendary) | `min(4 + floor × 2, 22)` |
+
+Higher floors shift weight toward higher tiers. Tier 3 caps at weight 22.
+
+### Shared firing mechanics
+
+- **Volley system:** items that grant `split`, `fan`, or `rear` shots add extra projectiles to *every* projectile weapon — parallel shots (±0.035 rad), angled shots (±0.16 rad per level), and backward shots respectively.
+- **Damage:** `weapon dmg × dmgMul` (× `critMul` on crits — 5% base chance, ×2.0 base).
+- **Projectile lifetime (range):** `weapon range × rangeMul`, in seconds.
+- **Homing:** homing projectiles steer toward the nearest enemy within 320 px. Strength is `1.6 + homing × 0.7` for normal weapons with Homing Tumor; stronger bases for Eye Ballista and Swarm Jar (see below).
+
+---
+
+## Tier −1 — Starter
+
+### Bone Popper
+
+> *Trusty bone-shard sidearm*
+
+| Stat | Value |
+|---|---|
+| Damage | 8 |
+| Fire interval | 0.60 s |
+| Projectile speed | 540 |
+| Range (lifetime) | 0.45 s |
+| Ammo | **Infinite** |
+| Behavior | Single bullet |
+| Recoil (punch) | 0.42 |
+
+Your eternal fallback. Never runs dry, never holstered — swapping with R always brings it back.
+
+---
+
+## Tier 0 — Common
+
+### Ribcage Repeater
+
+> *Rattles off rib slivers*
+
+| Stat | Value |
+|---|---|
+| Damage | 6 |
+| Fire interval | 0.09 s (very fast) |
+| Projectile speed | 560 |
+| Spread | 0.10 rad |
+| Range | 0.42 s |
+| Ammo | 140 |
+| Recoil | 0.18 |
+
+Rapid-fire bullet hose. Low per-shot damage, excellent proc-per-second carrier for on-hit item effects.
+
+### Marrow Scatter
+
+> *A devastating close blast of jagged bone*
+
+| Stat | Value |
+|---|---|
+| Damage | 11 **per pellet** |
+| Pellets | 6 |
+| Fire interval | 0.58 s |
+| Projectile speed | 500 |
+| Spread | 0.55 rad (wide) |
+| Range | 0.38 s (short) |
+| Ammo | 42 |
+| Recoil | 0.92 (heavy) |
+
+Shotgun. Up to 66 damage per trigger pull at point blank before multipliers, but the short lifetime makes it strictly close-range.
+
+### Cleaver Cadence
+
+> *It always comes back*
+
+| Stat | Value |
+|---|---|
+| Damage | 15 |
+| Fire interval | 0.38 s |
+| Projectile speed | 400 (returns at up to 520) |
+| Range | 1.10 s |
+| Ammo | 34 |
+| Recoil | 0.42 |
+
+Boomerang: flies out while decelerating for 0.45 s, then accelerates back to you (caught within 20 px). **Always pierces** — it can hit enemies on both the outbound and return trip.
+
+---
+
+## Tier 1 — Uncommon
+
+### Sawblade Launcher
+
+> *Bouncing, hungry steel*
+
+| Stat | Value |
+|---|---|
+| Damage | 13 |
+| Fire interval | 0.34 s |
+| Projectile speed | 360 |
+| Wall bounces | 5 (plus bounces from Ricochet Ribs) |
+| Range | 0.60 s |
+| Ammo | 26 |
+| Recoil | 0.45 |
+
+Spinning ricochet blades. Deadly in cramped rooms where blades ping off walls into packs.
+
+### Bile Blunderbuss
+
+> *A brutal corrosive torrent; pools linger*
+
+| Stat | Value |
+|---|---|
+| Damage | 7 |
+| Fire interval | 0.12 s (rapid, hold to spray) |
+| Projectiles per shot | 2 |
+| Projectile speed | 340 |
+| Spread | 0.32 rad |
+| Range | 0.36 s |
+| Pierce | 2 (+ item pierce) |
+| Ammo | 70 |
+| Recoil | 0.34 |
+
+Corrosive cone spray. On hit: **slows for 1.6 s** and 45% chance to leave an **acid pool** (radius 24 × sizeMul, 3.5 s life, DPS = bullet damage × 1.5). Projectiles that expire mid-flight have a separate 35% chance to drop a pool.
+
+### Hemophage
+
+> *Drinks what it touches*
+
+| Stat | Value |
+|---|---|
+| Damage | 8 |
+| Fire interval | 0.19 s |
+| Projectile speed | 480 |
+| Range | 0.45 s |
+| Lifesteal | 12.5% chance per hit to heal 1 HP |
+| Ammo | 44 |
+| Recoil | 0.35 |
+
+The only weapon with built-in lifesteal. Healing only procs while you're below max HP.
+
+### Eye Ballista
+
+> *The eyes follow. They always follow*
+
+| Stat | Value |
+|---|---|
+| Damage | 10 |
+| Fire interval | 0.30 s |
+| Projectile speed | 320 |
+| Range | 0.62 s |
+| Homing | 6 + homing × 0.7 (strongest base homing) |
+| Ammo | 32 |
+| Recoil | 0.40 |
+
+Aggressively seeking projectiles. Aim roughly, let the eyes do the rest.
+
+---
+
+## Tier 2 — Rare
+
+### Gut Hook
+
+> *Impales and drags the catch*
+
+| Stat | Value |
+|---|---|
+| Damage | 48 (+ 50% = 24 bonus when the drag ends) |
+| Fire interval | 0.85 s (slow) |
+| Projectile speed | 720 (fastest projectile) |
+| Range | 0.60 s |
+| Ammo | 14 |
+| Recoil | 0.95 |
+
+Harpoon that pierces everything and **drags the first non-boss enemy it hits** along its flight path. When the projectile expires, the dragged enemy takes 50% of the bullet's damage again. Excellent for yanking a priority target out of a pack.
+
+### The Cauterizer
+
+> *Incinerates anything brave enough to get close*
+
+| Stat | Value |
+|---|---|
+| Damage | 4.5 per flame tick |
+| Fire interval | 0.05 s (20 ticks/sec, hold to spray) |
+| Projectiles per shot | 2 |
+| Projectile speed | 310 |
+| Spread | 0.34 rad |
+| Range | 0.36 s (very short) |
+| Pierce | 2 (+ item pierce) |
+| Ammo | 110 |
+| Recoil | 0.32 |
+
+Flamethrower. Hits **ignite for 2.2 s** with burn DPS = bullet damage × 2 (9 DPS base). Melt hordes that get close; useless at range.
+
+### Flesh Masher
+
+> *Lobs ground-meat bombs*
+
+| Stat | Value |
+|---|---|
+| Damage | 34 (area of effect) |
+| Fire interval | 0.75 s |
+| Behavior | Lobbed to cursor, explodes on arrival |
+| Blast radius | 85 × rangeMul × √sizeMul |
+| Ammo | 14 |
+| Recoil | 0.90 |
+
+Grenade lobber. Flight time auto-computed from distance (clamped 0.12–0.8 s). The blast damages and knocks back everything in radius. Arcs over the chaos — no line of sight needed.
+
+### Trap Queen
+
+> *Bear traps. For bears. And worse*
+
+| Stat | Value |
+|---|---|
+| Damage | 10 per trap trigger |
+| Fire interval | 0.55 s |
+| Behavior | Lobbed; leaves a trap where it lands |
+| Trap life | 12 s × rangeMul |
+| Trap radius | 16 × sizeMul |
+| Ammo | 12 (refills at 75% rate — `ammoWeight: 0.75`) |
+| Recoil | 0.65 |
+
+Area denial. Traps persist on the floor and damage any enemy that steps on them — pre-lay them along doorways and kiting paths.
+
+### The Tenderizer
+
+> *A room-shaking close-range meat paste*
+
+| Stat | Value |
+|---|---|
+| Damage | 60 (instant area hit) |
+| Fire interval | 0.58 s |
+| Range | 46 × rangeMul × √shotSpeedMul from player |
+| Blast radius | 70 × rangeMul × √sizeMul |
+| Ammo | 26 |
+| Recoil | 1.00 (max), screen shake 5 |
+
+Point-blank slam — no projectile, an instant circular blast in front of you. Bonus "inert" damage scaling: +6% per point of pierce + bounce + homing you own.
+
+### Red Right Hand
+
+> *A chainsaw that liquefies anything in reach*
+
+| Stat | Value |
+|---|---|
+| Damage | 7 per tick (ticks scale with fire rate) |
+| Damage interval | 0.10 s |
+| Reach | 30 × rangeMul × √shotSpeedMul from player |
+| Arc radius | 34 × √sizeMul |
+| Ammo | 160 (drains 18/sec while held, ÷ ammoEff) |
+| Recoil | 0.38 |
+
+Continuous melee chainsaw — hold LMB and walk into things. Damage scales with `dmgMul × rateMul`, plus the same +6%-per-pierce/bounce/homing inert bonus as the Tenderizer. Sparks fly, ammo drains.
+
+---
+
+## Tier 3 — Legendary
+
+### Spinal Tap
+
+> *Charge it. Delete a line of meat*
+
+| Stat | Value |
+|---|---|
+| Damage | 95 (× 0.4–1.0 by charge) |
+| Charge time | 0.85 s (minimum 40% charge = 0.34 s to fire) |
+| Beam length | 900 × rangeMul |
+| Beam width | 14 × √sizeMul |
+| Ammo | 9 |
+| Recoil | 1.00, screen shake 8 |
+
+**Hold LMB to charge, release to fire** an instant hitscan beam that deletes everything in a line. Damage scales `0.4 + 0.6 × charge fraction` — full charge is 2.5× a hasty snap shot. A ring around your character shows charge state (blue = full). Charge rate scales with `rateMul × √shotSpeedMul`.
+
+### Swarm Jar
+
+> *A jar of friends. They are hungry*
+
+| Stat | Value |
+|---|---|
+| Damage | 9 per maggot |
+| Fire interval | 0.80 s |
+| Maggots per jar | 6 (+ split + fan bonuses) |
+| Maggot speed / life | 260 / 2.2 s × rangeMul |
+| Maggot homing | 8 + homing × 0.7 (strongest in game) |
+| Ammo | 7 (refills at 80% rate — `ammoWeight: 0.8`) |
+| Recoil | 0.70 |
+
+Lobs a jar that shatters into a pack of homing maggots. Maggots **inherit your pierce and bounce stats** and relentlessly chase enemies for their full lifetime. Throw and forget.
+
+---
+
+## Damage math reference
+
+```
+bullet damage  = weapon dmg × dmgMul × (critMul if crit)
+fire interval  = weapon interval / (rateMul × frenzyMul)
+proj speed     = weapon spd × shotSpeedMul
+proj lifetime  = weapon range × rangeMul
+ammo per shot  = 1 / ammoEff
+knockback      = 90 × knockbackMul
+```
+
+- Crit: base 5% chance, ×2.0 damage. Raised by Bloodshot Eye / Hollow Needle (items) and Bone Splitter / Cold Precision (perks).
+- Frenzy: from Dead Man's Switch — kills grant `1 + frenzy` fire rate for 3 s.
+- Slam/saw/beam weapons (Tenderizer, Red Right Hand, Spinal Tap) get an extra `1 + (pierce + bounce + homing) × 0.06` multiplier instead of firing extra projectiles.