step 5.1: done

HANDOFF.md

@@ -4,8 +4,8 @@
 > If this file disagrees with the code, trust the code and fix this file.
 
 ## 1. Where we are
-- **Last completed step:** 4.5 (hunt UI — zones endpoint, combat-log endpoint, zone cards, hunt button, result panel, combat log replay)
-- **Next step:** 5.1 — inventory migration (`004_inventory.sql`)
+- **Last completed step:** 5.1 (inventory migration verified — already existed from step 4.4 review, applies clean)
+- **Next step:** 5.2 — inventory/equipment services + routes (list, equip, unequip, slots)
 - **Updated:** 2026-10-20
 - **Was the last session cut off mid-task?** No
 
@@ -27,13 +27,14 @@
 - `src/routes/zones.js` — `GET /api/zones`.
 - `src/routes/combatLog.js` — `GET /api/combat-log`.
 - `src/db/migrations/003_content.sql` — also SEEDS zones/monsters/items/loot (INSERT OR IGNORE).
+- `src/db/migrations/004_inventory.sql` — inventory table, FK constraints, partial unique index for equipped slots.
 - `tests/integration/zones-log.test.js` — 5 integration tests for zones + combat-log endpoints.
 - `public/game.html` — dashboard with stats panel, zone list, combat log, result panel.
 - `public/js/game.js` — full hunt UI: load zones, hunt handler, result display, combat log replay, toast notifications, energy sync.
 - `public/css/main.css` — zone cards, combat log entries, result panel, toast styles.
 
 ## 4. Half-finished / fragile things
-- No inventory/equipment system yet (Phase 5).
+- No inventory/equipment system yet (Phase 5 steps 5.2–5.4).
 - HP never regenerates naturally; only level-up restores it.
 - No restart-persistence test for sessions.
 - `npm run seed` script in package.json points to nonexistent `scripts/seed.js`.
@@ -50,11 +51,12 @@
 - Node.js `fetch` doesn't persist cookies across calls — extract `Set-Cookie` header and pass manually in integration tests.
 - Express query params are strings, not numbers — use `zod.coerce.number()` for numeric query params.
 
-## 7. Next-step briefing (5.1)
-- **Goal:** Create `004_inventory.sql` migration (inventory table + starting items for new heroes).
-- **Docs:** DATABASE.md, GAME_DESIGN.md §Items.
-- **Files:** `src/db/migrations/004_inventory.sql`.
-- **Schema:** `inventory` table (`id, character_id, item_id, quantity, equipped_slot NULL, acquired_at`), FK constraints. Starting items: class-appropriate common weapon (auto-equipped) + 2 Minor Healing Potions on character creation.
+## 7. Next-step briefing (5.2)
+- **Goal:** Services + routes for inventory management: list inventory, equip, unequip. Slots: weapon, armor, trinket. Equipment modifies derived stats via `calcDerived()`.
+- **Docs:** DATABASE.md (§004_inventory), GAME_DESIGN.md §Items, BALANCE.md.
+- **Files to create:** `src/services/inventoryService.js`, `src/routes/inventory.js`.
+- **Key rules:** one equipped item per slot (enforced by partial unique index in DB); equipping an item moves the previous one in that slot to unequipped; stackable items merge (quantity); non-stackable get one row per drop.
+- **Tests:** at least one happy-path + one failure-path test.
 
 ## 8. Open Known Issues
 STATUS.md issues 1–6 (balance, dangling `seed` script, restart test, equipment-in-combat, HP regen, zone min_level balance).