# HANDOFF.md — Session Handoff (OVERWRITE at the end of every phase or when context is getting long)

> **Read order for a new session:** `NOTES.md` → `STATUS.md` → this file → then work.
> If this file disagrees with the code, trust the code and fix this file.

## 1. Where we are
- **Last completed step:** 4.4 (hunt endpoint) + a full review/fix pass
- **Next step:** 4.5 — hunt UI (needs `GET /api/zones` first, see STATUS issue 2)
- **Updated:** 2026-10-20
- **Was the last session cut off mid-task?** No

## 2. Verified state (run these first)
| Command | Expected |
|---|---|
| `npm install` | succeeds (better-sqlite3 is a native module; needs Node 20+ and a C++ toolchain if no prebuilt binary) |
| `npm run migrate` | applies 001–004 and 006 / "nothing to do" |
| `npm test` | **93 passing, 0 failing** (69 unit + 24 integration) |

## 3. What exists now (files that matter)
- `src/game/stats.js` — `calcDerived()` is the ONLY derived-stat formula. Also re-exports xpToNext/checkLevelUp (implemented in `leveling.js`).
- `src/game/combat.js` — `resolveCombat(hero, monster, rng)`; both sides attack each round, faster first.
- `src/services/huntService.js` — `hunt(characterId, zoneId, {rng, now})`; ONE transaction; test-injectable.
- `src/services/characterService.js` — `createCharacter`, `getCharacterProfile`, `getCharacterIdForUser`.
- `src/utils/time.js` — `now()/setNow()/resetNow()`; never call `Date.now()` in services.
- `src/middleware/session.js` — real SQLite session store (timer unref'd).
- `src/db/migrations/003_content.sql` — also SEEDS zones/monsters/items/loot (INSERT OR IGNORE). Changing balance = NEW migration, never edit 003.
- `tests/helpers.js` — `setup()/teardown()/cleanup()`: fresh app + temp DB per call. `tests/integration/hunt-service.test.js` shows how to force outcomes with test-only zones.

## 4. Half-finished / fragile things
- No `GET /api/zones` yet; `public/js/game.js` has no hunt UI yet (4.5).
- HP never regenerates naturally; only level-up restores it (Rest/potions in Phases 5–6).
- No restart-persistence test for sessions.

## 5. Decisions & deviations from the docs
- D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).

## 6. Gotchas learned
- `npm test` must be `node --test` with NO path/glob; files must be named `*.test.js`. A shell glob once skipped 17 tests.
- better-sqlite3-session-store ignores `clear:false`; that's why the timer is unref'd.
- Statement caches are per-DB-handle (WeakMap) in huntService; copy that pattern for new services.
- Verify test COUNT, not just "all passing".

## 7. Next-step briefing (4.5)
- **Goal:** zone list + Hunt button + combat log replay + result summary + level-up message on the dashboard.
- **Docs:** API.md §Hunting, UI_GUIDE.md §game.html, GAME_DESIGN.md §Combat.
- **Files:** add `src/routes/zones.js` (+ service fn) and mount in app.js; extend `public/game.html` + `public/js/game.js`; add an integration test for `GET /api/zones`.
- **Watch out for:** use `textContent` (no innerHTML); show energy cost on the button; disable button while request is in flight; re-sync energy from the hunt response (`data.energy`, `data.hpRemaining`, `data.hpMax`).

## 8. Open Known Issues
STATUS.md issues 1–6 (balance, zones endpoint, dangling `seed` script, restart test, equipment-in-combat, HP regen).