update documentation

documentation/deployment.md

@@ -12,19 +12,19 @@ This document describes the production deployment of the lila vocabulary trainer
 
 ### Subdomain Routing
 
-| Subdomain | Service | Container port |
-|---|---|---|
-| `lilastudy.com` | Frontend (nginx serving static files) | 80 |
-| `api.lilastudy.com` | Express API | 3000 |
-| `git.lilastudy.com` | Forgejo (web UI + container registry) | 3000 |
+| Subdomain           | Service                               | Container port |
+| ------------------- | ------------------------------------- | -------------- |
+| `lilastudy.com`     | Frontend (nginx serving static files) | 80             |
+| `api.lilastudy.com` | Express API                           | 3000           |
+| `git.lilastudy.com` | Forgejo (web UI + container registry) | 3000           |
 
 ### Ports Exposed to the Internet
 
-| Port | Service |
-|---|---|
-| 80 | Caddy (HTTP, redirects to HTTPS) |
-| 443 | Caddy (HTTPS) |
-| 2222 | Forgejo SSH (git clone/push) |
+| Port | Service                          |
+| ---- | -------------------------------- |
+| 80   | Caddy (HTTP, redirects to HTTPS) |
+| 443  | Caddy (HTTPS)                    |
+| 2222 | Forgejo SSH (git clone/push)     |
 
 All other services (Postgres, API, frontend) communicate only over the internal Docker network.
 

documentation/game_modes.md

@@ -0,0 +1,83 @@
+# Game Modes
+
+This document describes the planned game modes for lila. Each mode uses the same lobby system and vocabulary data but differs in how answers are submitted, scored, and how a winner is determined.
+
+The first multiplayer mode to implement is TBD. The lobby infrastructure (create, join, WebSocket connection) is mode-agnostic — adding a new mode means adding new game logic, not changing the lobby.
+
+---
+
+## TV Quiz Show
+
+**Type:** Multiplayer
+**Answer model:** Buzzer — first to press gets to answer
+**Rounds:** Fixed (e.g. 10)
+
+A question appears for all players. The first player to buzz in gets to answer. If correct, they score a point. If wrong, other players may get a chance to answer (TBD: whether the question passes to the next buzzer or the round ends). The host or a timer controls the pace.
+
+Key difference from other modes: only one player answers per question. Speed of reaction matters as much as knowledge.
+
+---
+
+## Race to the Top
+
+**Type:** Multiplayer
+**Answer model:** Simultaneous — all players answer independently
+**Rounds:** None — play until target score reached
+
+All players see the same question and answer independently. No fixed round count. The first player to reach a target number of correct answers wins (e.g. 20). Fast-paced and competitive.
+
+Open questions: what happens if two players hit the target on the same question? Tiebreaker by speed? Shared win?
+
+---
+
+## Chain Link
+
+**Type:** Multiplayer
+**Answer model:** Turn-based — one player at a time, in rotation
+**Rounds:** None — play until a player fails
+
+Players answer in a fixed rotation: Player 1, Player 2, Player 3, then back to Player 1. Each player gets one question per turn. The game continues until a player answers incorrectly — that player is out (or the game ends). Last correct answerer wins, or the game simply ends on the first wrong answer.
+
+Key difference from other modes: turn-based, not simultaneous. Pressure builds as you wait for your turn.
+
+Open questions: does the player who answers wrong lose, or does the game just end? If the game continues, does it become elimination?
+
+---
+
+## Elimination Round
+
+**Type:** Multiplayer
+**Answer model:** Simultaneous — all players answer independently
+**Rounds:** Continue until one player remains
+
+All players see the same question and answer simultaneously. Players who answer incorrectly are eliminated. Rounds continue until only one player is left standing.
+
+Open questions: what if everyone gets it wrong in the same round? Reset that round? Eliminate nobody? What if it comes down to two players and both get it wrong repeatedly?
+
+---
+
+## Cooperative Challenge
+
+**Type:** Multiplayer
+**Answer model:** TBD
+**Rounds:** TBD
+
+Players work together rather than competing. Concept not yet defined. Possible ideas: shared team score with a target, each player contributes answers to a collective pool, or players take turns and the team survives as long as the chain doesn't break.
+
+---
+
+## Single Player Extended
+
+**Type:** Singleplayer
+**Answer model:** TBD
+**Rounds:** TBD
+
+An expanded version of the current singleplayer quiz. Concept not yet defined. Possible ideas: longer sessions with increasing difficulty, mixed POS/language rounds, streak bonuses, progress tracking across sessions, or timed challenge mode.
+
+---
+
+## Schema Impact
+
+The `lobbies` table includes a `game_mode` column (varchar) with values like `tv_quiz`, `race_to_top`, `chain_link`, `elimination`. Mode-specific settings (e.g. target score for Race to the Top) can be stored in a `settings` jsonb column if needed.
+
+The singleplayer modes (Single Player Extended) don't require a lobby — they extend the existing singleplayer flow.

documentation/notes.md

@@ -21,9 +21,14 @@ WARNING! Your credentials are stored unencrypted in '/home/languagedev/.docker/c
 Configure a credential helper to remove this warning. See
 https://docs.docker.com/go/credential-store/
 
+### docker containers on startup?
+
+laptop: verify if docker containers run on startup (they shouldnt)
+
 ### vps setup
 
 - monitoring and logging (eg via chrootkit or rkhunter, logwatch/monit => mails daily with summary)
+<<<<<<< HEAD
 - ~~keep the vps clean (e.g. old docker images/containers)~~ ✅ CI/CD pipeline runs `docker image prune -f` after deploy
 
 ### ~~cd/ci pipeline~~ ✅ RESOLVED
@@ -33,6 +38,8 @@ Forgejo Actions with runner on VPS, Forgejo built-in container registry. See `de
 ### ~~postgres backups~~ ✅ RESOLVED
 
 Daily pg_dump cron job, 7-day retention, dev laptop auto-sync via rsync. See `deployment.md`.
+=======
+>>>>>>> dev
 
 ### try now option
 

documentation/spec.md

@@ -290,6 +290,7 @@ After completing a task: share the code, ask what to refactor and why. The LLM s
 
 ## 11. Post-MVP Ladder
 
+<<<<<<< HEAD
 | Phase             | What it adds                                                                    | Status |
 | ----------------- | ------------------------------------------------------------------------------- | ------ |
 | Auth              | Better Auth (Google + GitHub), embedded in Express API, user rows in DB         | ✅     |
@@ -299,6 +300,17 @@ After completing a task: share the code, ask what to refactor and why. The LLM s
 | Multiplayer Lobby | Room creation, join by code, WebSocket connection                               | ❌     |
 | Multiplayer Game  | Simultaneous answers, server timer, live scores, winner screen                  | ❌     |
 | Hardening (rest)  | Rate limiting, error boundaries, monitoring, accessibility                      | ❌     |
+=======
+| Phase               | What it adds                                                            | Status |
+| ------------------- | ----------------------------------------------------------------------- | ------ |
+| Auth                | Better Auth (Google + GitHub), embedded in Express API, user rows in DB | ✅     |
+| Deployment          | Docker Compose, Caddy, Forgejo, CI/CD, Hetzner VPS                      | ✅     |
+| Hardening (partial) | CI/CD pipeline, DB backups                                              | ✅     |
+| User Stats          | Games played, score history, profile page                               | ❌     |
+| Multiplayer Lobby   | Room creation, join by code, WebSocket connection                       | ❌     |
+| Multiplayer Game    | Simultaneous answers, server timer, live scores, winner screen          | ❌     |
+| Hardening (rest)    | Rate limiting, error boundaries, monitoring, accessibility              | ❌     |
+>>>>>>> dev
 
 ### Future Data Model Extensions (deferred, additive)