docs(adr): write ADRs for existing architectural decisions

Add five ADRs in docs/adr/ for decisions already in production:
- 0008: Transport layer — dual PeerJS + Gun.js with auto-fallback
- 0009: Database — Dexie.js with versioned migrations
- 0010: PWA / offline-first strategy
- 0011: Tag-only question classification (companion to ADR-0007)
- 0012: Vitest vmForks pool for ESM / fake-indexeddb compatibility

Update README: add Documentation section with links to user guides and
API docs, add docs.yml to CI/CD workflow table, add npm run docs to the
scripts table, add API docs badge.

Closes #82
Part of epic #75

Author: morbeo

README.md

@@ -4,13 +4,15 @@ Bar trivia PWA with WebRTC multiplayer, Reveal.js slides, and buzzer gameplay.
 No backend — runs entirely in the browser.
 
 **Live:** https://morbeo.github.io/viktorani/
+**API docs:** [![API Docs](https://img.shields.io/badge/docs-API-blue)](https://morbeo.github.io/viktorani/api/)
 
 ---
 
 ## Contents
 
 - [Tech stack](#tech-stack)
 - [Getting started](#getting-started)
+- [Documentation](#documentation)
 - [Project structure](#project-structure)
 - [Multiplayer](#multiplayer)
 - [Data storage](#data-storage)
@@ -51,6 +53,7 @@ npm run dev
 | ----------------------- | ---------------------------------------------- |
 | `npm run dev`           | Start dev server at `localhost:5173`           |
 | `npm run build`         | Type-check + production build → `dist/`        |
+| `npm run docs`          | Generate API docs → `docs/api/` (gitignored)   |
 | `npm run lint`          | ESLint across all `*.ts` / `*.tsx` files       |
 | `npm run typecheck`     | Type-check app and test files (both tsconfigs) |
 | `npm run test`          | Run unit tests once via Vitest                 |
@@ -65,6 +68,24 @@ npm run dev
 
 ---
 
+## Documentation
+
+| Document | Description |
+| -------- | ----------- |
+| [Host guide](docs/user-guide/host.md) | Setting up and running a trivia night |
+| [Player guide](docs/user-guide/player.md) | Joining a game and buzzing in |
+| [API docs](https://morbeo.github.io/viktorani/api/) | Generated TypeDoc — transport, DB, hooks |
+| [Architecture decisions](docs/adr/) | ADRs for all major technical decisions |
+
+To generate API docs locally:
+
+```bash
+npm run docs
+# Output: docs/api/ (gitignored — generated at build time)
+```
+
+---
+
 ## Project structure
 
 ```
@@ -105,6 +126,10 @@ src/
 │   └── timer/            # Timer hook and component tests
 └── App.tsx               # HashRouter + all routes
 
+docs/
+├── adr/                  # Architecture Decision Records
+└── user-guide/           # Host and player guides
+
 public/
 ├── favicon.svg           # SVG favicon (source of truth)
 ├── icon-192.png          # PWA icon — generate from favicon.svg (see Favicon section)
@@ -153,12 +178,13 @@ restore or share your question bank.
 
 ### Workflows
 
-| Workflow        | Trigger                   | Purpose                                                                |
-| --------------- | ------------------------- | ---------------------------------------------------------------------- |
-| `ci.yml`        | PRs to `master`           | PR title lint + type-check, lint, test, build — both required to merge |
-| `deploy.yml`    | push to `master` + manual | Type-check → lint → test → build → deploy to GitHub Pages              |
-| `release.yml`   | push of `v*` tags         | Build tarball → generate release notes → publish GitHub Release        |
-| `automerge.yml` | `CI` workflow completes   | Auto-merge Dependabot patch/minor PRs when CI passes                   |
+| Workflow        | Trigger                        | Purpose                                                                |
+| --------------- | ------------------------------ | ---------------------------------------------------------------------- |
+| `ci.yml`        | PRs to `master`                | PR title lint + type-check, lint, test, build — both required to merge |
+| `deploy.yml`    | push to `master` + manual      | Type-check → lint → test → build → deploy to GitHub Pages              |
+| `docs.yml`      | push to `master` (src/ changes) | Generate TypeDoc → publish to `gh-pages` under `/api/`                |
+| `release.yml`   | push of `v*` tags              | Build tarball → generate release notes → publish GitHub Release        |
+| `automerge.yml` | `CI` workflow completes        | Auto-merge Dependabot patch/minor PRs when CI passes                   |
 
 All workflows set `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to opt into the Node 24 runner ahead of the June 2026 forced migration.
 
@@ -179,7 +205,7 @@ Force pushes and branch deletion are blocked. To apply or re-apply protection:
 bash scripts/protect-master.sh
 ```
 
-> **Note:** `scripts/` is gitignored. Add scripts explicitly with `git add --force scripts/`.
+> **Note:** `scripts/` is gitignored. Add scripts explicitly with `git add --force scripts/`
 
 ### Dependabot
 

docs/adr/0008-transport-dual-peerjs-gun.md

@@ -0,0 +1,71 @@
+# ADR-0008 — Transport layer: dual PeerJS + Gun.js with auto-fallback
+
+**Date:** 2026-04-10
+**Status:** Accepted
+
+## Context
+
+Viktorani is a fully static PWA with no backend (ADR-0001). Real-time communication
+between the GameMaster and players is required for the buzzer, score updates, timer
+broadcasts, and question-navigation events. The transport layer must work in bar
+environments where network conditions are unpredictable.
+
+Two broad options exist for browser-to-browser real-time communication without a
+custom server: WebRTC (with a signalling layer) and relay-based pub/sub.
+
+**Constraints:**
+- Zero server maintenance — no custom signalling or relay server to run.
+- Must work behind restrictive NATs (common in pubs and venues).
+- Latency must be low enough for fair buzzer ordering (< 100 ms typical round-trip).
+- The passphrase displayed on the QR code must provide confidentiality.
+
+## Decision
+
+We implement two transport classes behind a common `ITransport` interface:
+
+1. **`PeerJSTransport`** — WebRTC data channels via the PeerJS cloud signalling service.
+   The host registers a deterministic PeerJS ID (`vkt-<roomId>`); players connect to it.
+   All data flows peer-to-peer with DTLS encryption from the browser.
+
+2. **`GunTransport`** — Decentralised graph database relay via public Gun.js peers.
+   Events are symmetrically encrypted with SEA (`SEA.work(passphrase, roomId)`) before
+   being written to the Gun graph. All peers subscribe to the same namespace and decrypt
+   on receive.
+
+`TransportManager` exposes three modes:
+- `'peer'` — PeerJS only.
+- `'gun'` — Gun.js only.
+- `'auto'` — Try PeerJS; if it times out after 8 seconds, fall back to Gun.js.
+
+The default mode is `'auto'`.
+
+## Alternatives considered
+
+**PeerJS only:** Simpler implementation and lower latency. Rejected as the sole option
+because the PeerJS cloud service has had availability incidents, and WebRTC peer
+connections are blocked by some corporate/venue NATs.
+
+**Gun.js only:** More reliable connectivity (relay-based, firewall-friendly). Rejected
+as the sole option because Gun.js relay peers are public infrastructure with variable
+latency, and the relay-hop model adds ~50–150 ms round-trip compared to PeerJS's
+direct data channel.
+
+**Socket.IO / Pusher / Ably:** Managed WebSocket services. Rejected because they
+require an account, API keys, and introduce per-message costs or strict rate limits.
+They also contradict the zero-server-maintenance constraint.
+
+**WebSockets with a self-hosted relay:** Maximum control and performance. Rejected
+because it requires running a server, which contradicts ADR-0001.
+
+## Consequences
+
+- Hosts can manually override the transport mode per-game if one option is known to
+  work better at their venue.
+- The 8-second PeerJS timeout is a trade-off: short enough not to delay game start
+  noticeably, long enough to distinguish a slow connection from a broken one.
+- Gun.js relay peers are third-party infrastructure. If both public relay servers are
+  unavailable, Gun.js transport will fail. The passphrase-based SEA encryption means
+  relay operators cannot read game events.
+- The `ITransport` interface makes it straightforward to add future transports
+  (e.g. self-hosted WebSocket, BroadcastChannel for same-device testing) without
+  changing consumers.

docs/adr/0009-dexie-versioned-migrations.md

@@ -0,0 +1,65 @@
+# ADR-0009 — Database: Dexie.js with versioned migrations
+
+**Date:** 2026-04-10
+**Status:** Accepted
+
+## Context
+
+All application data — questions, games, rounds, players, scores, buzz events — must
+be stored locally in the browser. The project has no backend (ADR-0001), so
+server-side databases are out of scope. The storage layer must support:
+
+- Structured, queryable data (not just key-value blobs).
+- Versioned schema migrations that run automatically on upgrade.
+- React integration without excessive boilerplate.
+- A test-friendly API (mockable in Vitest without a real browser).
+
+IndexedDB is the only browser API that provides a full transactional database.
+The question is which abstraction to use on top of it.
+
+## Decision
+
+We use **Dexie.js** as the IndexedDB abstraction, with all schema definitions
+and migrations in a single `ViktoraniDB` class in `src/db/index.ts`.
+
+Schema evolution uses Dexie's versioned `.version(n).stores({...}).upgrade(tx => ...)`
+pattern. Each version declares the full index set for every table (Dexie requires this)
+and an optional upgrade callback for data migrations. Versions are append-only —
+past versions are never modified.
+
+All React components access the database via `dexie-react-hooks` (`useLiveQuery`)
+or via async helpers imported from `src/db/`. The database is exposed as a
+module-level singleton (`export const db = new ViktoraniDB()`).
+
+For testing, `fake-indexeddb` polyfills the IndexedDB API in the Vitest environment
+(see ADR-0010).
+
+## Alternatives considered
+
+**Raw IndexedDB API:** Maximum control; no dependency. Rejected because the raw API
+is callback-based, verbose, and difficult to use with React's asynchronous rendering
+model. Schema migration code would be substantial to write and maintain.
+
+**localForage:** A simple key-value store on top of IndexedDB. Rejected because it
+does not support indexes or queries — storing structured data like questions with tag
+filtering and sort-by-difficulty would require loading all records into memory.
+
+**PouchDB:** A CouchDB-compatible database with sync capabilities. Rejected because
+sync is not needed (the transport layer handles real-time state), and PouchDB's
+document model and revision history add unnecessary overhead for this use case.
+
+**SQLite via WASM (e.g. wa-sqlite, sql.js):** Full SQL in the browser. Rejected
+because the WASM bundle size (~1 MB) is disproportionate for a trivia app; browser
+support is still maturing; and Dexie covers all required query patterns.
+
+## Consequences
+
+- Schema changes require a new version number. Forgetting to increment the version
+  causes Dexie to throw on open, which surfaces the mistake immediately in development.
+- All tables must be declared in every version's `.stores()` call, even if unchanged.
+  This is verbose but ensures the index set is always explicit.
+- The `upgrade()` callback receives a Dexie transaction; long-running migrations
+  (e.g. backfilling many rows) block the database open. This is acceptable for the
+  current data volumes (hundreds of questions, not millions).
+- `fake-indexeddb` supports Dexie out of the box, making unit tests fast and
+  deterministic without a browser.

docs/adr/0010-pwa-offline-first.md

@@ -0,0 +1,69 @@
+# ADR-0010 — PWA / offline-first strategy
+
+**Date:** 2026-04-10
+**Status:** Accepted
+
+## Context
+
+Viktorani is designed for bar and pub environments where Wi-Fi is unreliable and
+mobile data is often congested. The host device must be able to run the GM view
+without any internet connection once the app is loaded. Players who have visited
+the site before should also be able to load the join page without connectivity.
+
+Additionally, the app should be installable as a home-screen icon on the host's
+tablet or laptop, behaving like a native app (no browser chrome, standalone window).
+
+## Decision
+
+We build Viktorani as a **Progressive Web App (PWA)** using `vite-plugin-pwa`,
+which generates a service worker and a Web App Manifest automatically from Vite's
+build output.
+
+**Service worker strategy:** `GenerateSW` with a `workbox` `StaleWhileRevalidate`
+strategy for all assets. On first visit, all build artifacts are cached. On subsequent
+visits, the cached version is served immediately while the new version is fetched in
+the background. On next reload, the updated version is active.
+
+**Manifest:** Declares `display: standalone`, a 192×192 and 512×512 PNG icon set,
+and a `start_url` of `/viktorani/` (matching the GitHub Pages subpath).
+
+**Offline capability scope:**
+- The GM can run a full game offline: questions, navigation, buzzer logic, and scoring
+  all work without any network request.
+- The real-time transport (PeerJS / Gun.js) requires internet for initial connection.
+  Once the game is in progress, PeerJS direct data channels survive brief connectivity
+  drops; Gun.js buffers events and replays on reconnect.
+- Player devices need internet for the initial page load; after caching they can
+  reload offline but will not receive transport events without connectivity.
+
+**Peer conflict:** `vite-plugin-pwa` declares a peer dependency on a specific Vite
+major version. With Vite 8, this peer constraint is satisfied via an npm `overrides`
+block in `package.json` rather than downgrading Vite.
+
+## Alternatives considered
+
+**No service worker (plain static site):** Simpler build. Rejected because offline
+operation is a primary design requirement — bar Wi-Fi is notoriously unreliable.
+
+**Manual service worker:** Full control over caching strategy. Rejected because
+Workbox (used by `vite-plugin-pwa`) handles cache versioning, update detection, and
+the `skipWaiting` / `clientsClaim` lifecycle correctly out of the box. Writing this
+manually would be substantial and error-prone.
+
+**Capacitor / Electron (native wrapper):** True offline native app. Rejected because
+it would require a build and distribution pipeline (App Store, DMG/EXE) that
+contradicts the zero-cost, zero-maintenance deployment goal. A PWA achieves
+install-to-home-screen on iOS/Android/desktop without any store submission.
+
+## Consequences
+
+- The host must load the app at least once on a network-connected device before
+  going offline. This is a reasonable requirement for a planned event.
+- Service worker updates are silent (StaleWhileRevalidate). If the host wants to
+  pick up a new version immediately, they need to close all tabs and reopen, or
+  use the browser's "Update" prompt if one appears.
+- The `display: standalone` manifest requires `HashRouter` instead of `BrowserRouter`
+  because GitHub Pages cannot serve arbitrary deep paths (see ADR-0004).
+- PWA install prompts behave differently across browsers and OS versions. Chrome on
+  Android and Edge on desktop show an install prompt; Safari on iOS requires the user
+  to manually "Add to Home Screen" from the share sheet.

docs/adr/0011-tag-only-classification.md

@@ -0,0 +1,53 @@
+# ADR-0011 — Tag-only question classification
+
+**Date:** 2026-04-10
+**Status:** Accepted
+
+## Context
+
+See ADR-0007, which documents the decision to remove the `Category` type and make
+tags the sole question classifier. This ADR records the consequences and implementation
+details that were deferred from ADR-0007.
+
+The original system had:
+- **Categories** — a single required classifier per question (e.g. "Geography").
+- **Tags** — an optional multi-value set for additional labels.
+
+Both were colour-coded and managed in separate Settings panels. The duplication
+created authoring friction (which label goes where?) and made filtering inconsistent.
+
+## Decision
+
+Remove the `Category` type entirely. Tags are the sole classifier. The filtering UI
+upgrades from a single-select category dropdown to a **tri-state per-tag** model:
+
+- **None** (default) — tag is not used as a filter criterion.
+- **Include** — question must have this tag (conjunctive AND across multiple includes).
+- **Exclude** — question must not have this tag (conjunctive AND across multiple excludes).
+
+Includes and excludes compose: "must have `History` AND must not have `Hard`" is a
+valid filter state.
+
+The DB is migrated from v2 to v3 (see `src/db/index.ts`) with a Dexie upgrade step
+that strips `categoryId` from all existing `questions` records and drops the
+`categories` table. The snapshot format is bumped to v2 (categories field dropped);
+v1 imports remain supported with categories silently ignored.
+
+## Alternatives considered
+
+See ADR-0007 for the full alternatives analysis.
+
+## Consequences
+
+- `Question.categoryId` is removed from the TypeScript schema and all DB indexes.
+  Existing data is migrated automatically on first open after the upgrade.
+- The `ManageCategories` settings panel is deleted. Tag management is consolidated
+  into the expanded `ManageTags` panel.
+- Snapshot v2 does not include a `categories` field. Importing a v1 backup on a
+  v3+ database silently discards the categories array and strips `categoryId` from
+  imported questions.
+- Tri-state tag filtering is more expressive than the old single-select dropdown
+  but requires users to understand include vs. exclude semantics. The UI communicates
+  this via colour coding (green = include, red = exclude, grey = none).
+- Search index no longer includes `_categoryName`. Tag names are already indexed by
+  Fuse.js, so coverage is equivalent.