step 9.5: 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:** 9.5 (Final full run of "Definition of playable") — TICKED in STATUS.md
+- **Last completed step:** 9.6 (Update README with real run instructions) — TICKED in STATUS.md
-- **Next step:** Phase 9 — 9.6 (Update README with real run instructions)
+- **Next step:** Phase 9 is complete. Ready to start Stretch Goals (S1–S7) or address Known Issues from STATUS.md.
 - **Updated:** 2026-10-21
 - **Was the last session cut off mid-task?** No
 
@@ -16,6 +16,7 @@
 | `npm run migrate` | applies 001–006 / "nothing to do" |
 | `npm test` | **176 passing, 0 failing** (85 unit + 91 integration incl. 1 e2e) |
 | `npm run seed:dev` | creates demo user "demo"/"demo123", hero "Aldric" (warrior), starter gear |
+| `npm start` + `curl localhost:3000/api/health` | `{"ok":true}` |
 
 ## 3. What exists now (files that matter)
 - `public/game.html` — Dashboard with 3-col grid (stats | action | combat), mobile bottom nav (⚔️ Hunt / 🏕️ Trip / 🎒 Items), tabbed action area.
@@ -35,6 +36,7 @@
 - `src/game/*` — Pure game logic.
 - `tests/integration/*.test.js` — 91 integration tests (incl. e2e-playable.test.js).
 - `tests/unit/*.test.js` — 85 unit tests.
+- `README.md` — Updated with real run instructions, play-through steps, project structure, known issues.
 
 ## 4. Half-finished / fragile things
 - No leaderboard UI yet (Phase 8 API done but no UI).
@@ -85,6 +87,8 @@
 - Inventory sell endpoint (`POST /api/shop/sell`) only accepts `material`-type items.
 - `handleListInventory` in `src/routes/inventory.js` — parameter name must be `res`, not `_res`.
 
-## 7. Next-step briefing (9.6)
+## 7. Next-step briefing
-- **Goal:** Update README with real run instructions.
+- **Phase 9 is complete.** All hardening and polish done.
-- Include: how to install, configure (.env), run migrations, seed dev data, start server, run tests, and basic play-through steps.
+- **Stretch Goals available:** S1 (PvP duels), S2 (Skills/talents), S3 (Guilds), S4 (Player market), S5 (Daily rewards/quests), S6 (In-game chat), S7 (Achievements).
+- **Or address Known Issues:** Issue #2 (`GET /api/zones` missing — major), Issue #5 (equipment not in combat — minor), Issue #3 (`npm run seed` dead script — cosmetic).
+- **Recommended next step:** Fix Known Issue #2 (`GET /api/zones`) since it's a documented API gap and would improve the hunt UI. Then consider S7 (Achievements) as it's a self-contained, low-risk stretch goal that adds meaningful gameplay.

README.md

@@ -5,34 +5,135 @@ regenerating Energy on actions (hunting, expeditions, training), fight monsters,
 collect loot, and climb leaderboards. Progress persists between sessions and
 continues to "happen" while the player is offline (timers, energy regen).
 
-## For the AI agent building this
+**Stack:** Node.js, Express, SQLite (`better-sqlite3`), vanilla HTML/CSS/JS.
-**Start with `NOTES.md`, then `STATUS.md`.** Do not read every doc up front.
-Open only the docs referenced by the step you are working on.
 
-## Doc map
+---
-| File | Read it when... |
+
-|---|---|
+## Quick Start
-| `NOTES.md` | ALWAYS first. Rules, stack, constraints. |
-| `STATUS.md` | ALWAYS second. Pick the next unchecked step. Update it when done. |
-| `docs/WORKFLOW.md` | You are unsure how to work or what "done" means. |
-| `docs/ARCHITECTURE.md` | Creating or moving files; deciding where code goes. |
-| `docs/DATABASE.md` | Touching the database or writing migrations. |
-| `docs/API.md` | Writing or calling any route. |
-| `docs/GAME_DESIGN.md` | Implementing any game mechanic. |
-| `docs/BALANCE.md` | Writing formulas, numbers, loot tables, monsters. |
-| `docs/SECURITY.md` | Auth, input handling, anything user-facing. |
-| `docs/UI_GUIDE.md` | Building pages/CSS/frontend JS. |
-| `docs/CODING_STANDARDS.md` | Style, naming, error handling. |
-| `docs/TESTING.md` | Writing or running tests. |
-| `docs/DECISIONS.md` | Making a choice that deviates from the docs. |
 
-## For the human
 ```bash
-cp .env.example .env
+# 1. Clone & install
+git clone <repo>
+cd Emberfall
 npm install
-npm run migrate
+
-npm run seed
+# 2. Configure
-npm start        # http://localhost:3000
+cp .env.example .env
+# Edit .env — at minimum change SESSION_SECRET to a long random string
+
+# 3. Set up the database
+npm run migrate        # creates tables; safe to run multiple times
+
+# 4. Seed a demo account (development only)
+npm run seed:dev       # creates user "demo" / "demo123" with hero "Aldric"
+
+# 5. Start the server
+npm start              # http://localhost:3000
+
+# 6. Run tests
+npm test               # all unit + integration + e2e tests
+```
+
+### Development
+
+```bash
+npm run dev            # auto-restart on file changes (node --watch)
+```
+
+---
+
+## How to Play
+
+1. **Register** a new account at `http://localhost:3000/register.html`
+   (or log in with `demo` / `demo123` if seeded).
+2. **Create a hero** — choose a class (Warrior, Mage, Rogue). Each class has
+   different base stats and bonuses.
+3. **Hunt monsters** — select a zone, spend 10 energy to fight. Victories award
+   XP, gold, and loot. Defeat costs energy but no more.
+4. **Level up** — earn XP to gain levels and stat points. Allocate points to
+   Strength, Vitality, and Dexterity to become stronger.
+5. **Equip items** — open the Inventory tab to see equipment and consumables.
+   Click to equip weapons, armor, and trinkets. Use potions to heal or restore
+   energy.
+6. **Shop** — buy items from level-gated stock or sell materials for gold
+   (40% of base price).
+7. **Expeditions** — start a timed expedition before leaving. Claim rewards
+   (XP, gold, loot) when you return after the duration elapses. Only one active
+   expedition per hero at a time.
+8. **Leaderboards** — view the top 50 heroes by level, gold, or kills.
+9. **Log out and back in** — everything persists. Your energy continues
+   regenerating while you were offline.
+
+---
+
+## Project Structure
+
+```
+src/
+  app.js              Express app (middleware, routes, error handling)
+  server.js           Entry point (listens on PORT)
+  config/index.js     Environment config (validates required vars)
+  db/index.js         SQLite connection (WAL, FK ON)
+  db/migrations/      Numbered .sql migration files
+  db/seeds/           Seed data (if needed beyond migrations)
+  game/               Pure game logic (combat, energy, leveling, rewards, classes, stats)
+  middleware/          session, requireAuth, error wrapper
+  routes/              Express route handlers (auth, character, hunt, inventory, shop, etc.)
+  services/            Business logic (authService, huntService, inventoryService, etc.)
+  utils/               Helpers (errors, rng, time)
+public/               Static files (HTML, CSS, JS) — the game UI
+scripts/              migrate.js, seed-dev.js
+tests/
+  unit/               Pure function tests (game logic)
+  integration/        API + service tests (boots app on ephemeral port)
+docs/                 Design docs, architecture, API spec, balance numbers, etc.
+```
+
+---
+
+## Available Scripts
+
+| Script | Description |
+|---|---|
+| `npm start` | Start the server on PORT from `.env` |
+| `npm run dev` | Start with auto-restart on file changes |
+| `npm test` | Run all unit + integration + e2e tests |
+| `npm run migrate` | Run pending migrations |
+| `npm run seed:dev` | Create demo account + hero + starter gear (skips in production) |
+
+---
+
+## Testing
+
+```bash
 npm test
 ```
-(These scripts are created by the agent in STATUS.md Phase 0.)
+
+Runs all `*.test.js` files via `node --test`. Tests use a shared SQLite file
+in `data/` (WAL mode). In test mode (`NODE_ENV=test`), rate limits are raised
+to avoid false failures.
+
+---
+
+## Known Issues
+
+| # | Description | Severity |
+|---|-------------|----------|
+| 1 | Level-1 heroes win 100% of Meadows fights (target ≈80%). Tune monster stats via a new migration. | minor |
+| 2 | `GET /api/zones` documented in API.md but not implemented. | major |
+| 3 | `npm run seed` script points to nonexistent `scripts/seed.js`. Remove or create the file. | cosmetic |
+| 4 | No test proves sessions survive a server restart. | minor |
+| 5 | Hero equipment bonuses not yet passed into combat resolution. | minor |
+| 6 | Natural HP regeneration not implemented (HP only restores on level-up). | minor |
+
+---
+
+## Architecture Notes
+
+- **Server is the only source of truth.** Clients send intent ("hunt zone 2");
+  the server resolves combat and returns results.
+- **Lazy evaluation.** Energy regen and expedition timers are computed on the
+  next request using stored timestamps — no cron loops or real-time ticks.
+- **All SQL uses prepared statements.** No string concatenation for queries.
+- **Game logic is pure functions** in `src/game/` — no DB, no Express. Fully
+  unit-testable.

STATUS.md

@@ -7,10 +7,10 @@
 > - Keep Session Log entries to one or two lines.
 
 ## Current Focus
-- **Phase:** 9
+- **Phase:** Complete (Phase 9 done)
-- **Step:** 9.6
+- **Step:** Stretch Goals
 - **Blocked?** No
-- **Last verified working command:** `npm test` — 176/176 passing (85 unit + 90 integration + 1 e2e), 2026-10-21 step 9.5
+- **Last verified working command:** `npm test` — 176/176 passing (85 unit + 91 integration + 1 e2e), 2026-10-21 step 9.6
 
 ## Project Health
 | Item | State |
@@ -111,10 +111,10 @@
   *Acceptance:* `npm run seed:dev` creates migrations + demo user + hero + starter gear; safe to re-run; skipped in production.
 - [x] **9.3** Global error pages / friendly UI error toasts. Loading states.
 - [x] **9.4** Mobile-responsive pass (see UI_GUIDE).
-- [ ] **9.5** Final full run of "Definition of playable" from NOTES.md §7. Record results below.
 - [x] **9.5** Final full run of "Definition of playable" from NOTES.md §7. Record results below.
   *Acceptance:* Full playable flow verified via integration test: register → login → create hero → see stats/energy → hunt → gain XP/gold/loot → level up → equip items → buy in shop → start+claim expedition → see leaderboard → log out → log back in → persistence verified.
-- [ ] **9.6** Update README with real run instructions.
+- [x] **9.6** Update README with real run instructions.
+  *Acceptance:* README includes install, configure, migrate, seed, start, test commands; play-through steps; project structure; known issues; architecture notes.
 
 ## Stretch Goals (only after Phase 9)
 - [ ] S1 Async PvP duels (attack another hero's *snapshot*; cooldown; rating).
@@ -160,6 +160,7 @@ Severity: `blocker` / `major` / `minor` / `cosmetic`. Status: `open` / `fixing`
 
 ## Session Log
 _Format:_ `YYYY-MM-DD | step | what changed | result`
+- 2026-10-21 | 9.6 | Rewrote README.md: removed AI-agent meta, added real run instructions (install/configure/migrate/seed/start/test), play-through steps, project structure, known issues table, architecture notes | 176/176 tests pass
 - 2026-10-21 | 9.5 | Created `tests/integration/e2e-playable.test.js` covering full playable flow (register → login → create hero → stats → hunt → level → equip → shop → expedition → leaderboard → logout → login → persistence); fixed `handleListInventory` bug (parameter `_res` vs `res` in `src/routes/inventory.js`); 176/176 tests pass
 - 2026-10-21 | 9.4 | Mobile-responsive pass: game.html 3-col grid (stats | action | combat), mobile bottom nav (⚔️ Hunt / 🏕️ Trip / 🎒 Items), desktop tabs hidden < 700px, game-container padding for nav clearance, mobile stat-row stacking, inventory container stacks < 600px; 175/175 tests pass
 - 2026-10-21 | 8.3 | Created public profile UI: `public/profile.html` + `public/js/profile.js` (fetches GET /api/heroes/:name via ?name=, displays hero name/class/level/gold/stats/equipment; 404 handling, URL-safe names); 5 integration tests | 172/172 tests pass