First commit, phased 1 and 2 created but untested

NOTES.md

@@ -0,0 +1,64 @@
+# NOTES.md — Project Brief (READ FIRST)
+
+## 1. What you are building
+**Emberfall**: a fantasy persistent browser-based game (PBBG). Players register
+an account, create a hero, and spend regenerating **Energy** on actions. The
+world keeps moving while they are offline (energy regenerates, expeditions
+finish). All state lives in a database on the server.
+
+You are the only developer. A human will play-test the result. Working,
+simple, and correct beats ambitious and broken.
+
+## 2. Hard constraints (do not violate)
+1. **Stack is fixed:** Node.js (>= 20), Express, SQLite via `better-sqlite3`,
+   `bcryptjs` for password hashing, `express-session` + `better-sqlite3-session-store`
+   (or `connect-sqlite3`) for sessions, `helmet`, `express-rate-limit`,
+   `zod` for input validation. Tests with the built-in `node:test` runner.
+2. **Frontend is vanilla HTML/CSS/JS.** No React, no build step, no bundler.
+   Static files in `public/`, talking to the JSON API with `fetch`.
+3. **No new dependencies** without logging the reason in `docs/DECISIONS.md`.
+4. **The server is the only source of truth.** The client never sends results,
+   damage, gold, XP, or timestamps. It only sends *intent* ("hunt in zone 2").
+5. **No real-time ticks / cron loops for game logic.** Use *lazy evaluation*:
+   compute energy regen and finished timers when the player next makes a request
+   (see `docs/GAME_DESIGN.md` §Time).
+6. **All SQL uses prepared statements with bound parameters.** Never build SQL
+   with string concatenation.
+7. **Keep files small** (aim < 200 lines). Split by responsibility.
+8. **Game rules live in `src/game/` as pure functions** (no DB, no Express).
+   They take data in and return data out, so they can be unit tested.
+9. **Never store plaintext passwords.** Never log passwords or session secrets.
+10. **Don't touch what isn't in the current step.** No drive-by refactors.
+11. **Re-read NOTES.md and STATUS.md after each phase.** Keep your context fresh.
+
+## 3. How to work (summary — details in docs/WORKFLOW.md)
+1. Open `STATUS.md`. Find the first unchecked step in the lowest-numbered phase.
+2. Read ONLY the docs that step references.
+3. Implement the step in small pieces. Run the app / tests after each piece.
+4. When the step's acceptance criteria pass, tick the box in `STATUS.md`,
+   add a Session Log line, and record any new Known Issues.
+5. Stop and re-read `STATUS.md` before starting the next step.
+
+If a doc is ambiguous or contradicts another doc, pick the simplest option,
+and write it down in `docs/DECISIONS.md`. Do not stall.
+
+## 4. Priority order when things conflict
+Correctness & security > persistence works > game is playable > code tidy > fun extras.
+
+## 5. Glossary
+- **Hero / Character:** the player's in-game avatar. One per account (v1).
+- **Energy:** action currency. Max 100. Regenerates over real time.
+- **Gold:** soft currency. Earned from combat/expeditions, spent in shops.
+- **Expedition:** a timed activity; started now, claimed later.
+- **Zone:** an area with monsters, level range, and loot.
+- **Lazy regen:** computing regen from `energy_updated_at` when needed.
+
+## 6. Out of scope for v1
+Real-money payments, email verification, password reset by email, websockets,
+mobile apps, 3rd-party OAuth, admin web UI. (Stretch goals are in STATUS.md.)
+
+## 7. Definition of "game is playable" (v1 target)
+A new visitor can: register → log in → create a hero → see stats/energy →
+hunt monsters → gain XP/gold/loot → level up → equip items → buy/sell in the
+shop → start and claim an expedition → see the leaderboard → log out → log back
+in and find everything exactly as left (plus offline energy regen).