Emberfall/NOTES.md

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.

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).

8. Automated loop mode

This project may be driven by scripts/run-agent-loop.sh, which starts a fresh agent session per step. In that mode: do exactly the one target step named in the prompt, never run commands that block forever, never run git commit/git reset (the loop commits after it verifies npm test, and rolls back on failure), and never delete or weaken tests (the loop rejects runs where the passing-test count drops).