docs: rewrite for the unified repo and record the parity gate

The docs still described two standalone projects with separate frontends,
separate parsers and three Vite variants. Rewritten around what the repo now
is, merging both projects' copies rather than keeping one and discarding the
other — deployment-guide.md and system-architecture.md existed in both and
documented different pipelines.

  project-overview.md    goal, scope, constraints, the four datasets, history
  system-architecture.md data flow, canonical schema, routing, how one
                         frontend serves both exam years without branching
  data-pipeline.md       per-dataset Excel formats, the three 2016 layouts,
                         overflow-sheet gotcha, expected row counts
  deployment-guide.md    the single-build workflow, adding a dataset,
                         why no uncompressed database can ship

Records the release gate in plans/reports/parser-parity-result.md: row counts,
all 18 pre-existing per-column non-NULL counts and the deterministic student
samples are identical across all four datasets, against databases decompressed
from the exact bytes the pipeline publishes. The 1,691 recovered
foreign-language scores are documented with the evidence they are real.

Also drops a machine-specific absolute path from a comment in
format_detect_2016.rs. The build-database.js citations there are kept: that
file no longer exists in this repo, but the references explain why several
parsing rules look arbitrary.

docs/deployment-guide.md

@@ -1,52 +1,105 @@
 # Deployment Guide
 
-Deploys to GitHub Pages via `.github/workflows/deploy.yml`. Every push to `main` rebuilds and redeploys all 3 variants.
+Deploys to GitHub Pages via `.github/workflows/deploy-pages.yml`. Every push to
+`main` rebuilds all four datasets and redeploys the whole site.
+
+One-time setup: **Settings → Pages → Source: GitHub Actions**.
 
 ## What the workflow does
 
-1. Checkout, setup Node 20, `npm ci`
-2. `npm run build:db:all` — builds 3 SQLite DBs (main, old, old2)
-3. Gzip each DB at level 9
-4. `npm run build:all` — builds 3 Vite bundles into `dist/`, `dist/old/`, `dist/old2/`
-5. Remove uncompressed `.db` files from `dist/` (only `.gz` ships)
-6. `actions/upload-pages-artifact` + `actions/deploy-pages`
+1. Checkout, Rust toolchain, Node 24, `npm ci`
+2. `npm run build:rust` — one parser binary
+3. `npm run build:db` — builds and gzips all four databases into
+   `.build/public/db/`
+4. `npm run build:site` — one Vite build, then `scripts/assemble-site.js`
+5. `actions/upload-pages-artifact` + `actions/deploy-pages`
 
-Total CI time ≈ 4–6 min (DB build dominates).
+The database build dominates the runtime: roughly 419 MB of Excel is parsed on
+every deploy.
 
 ## Resulting URLs
 
-- `https://<user>.github.io/thptqg2017/`
-- `https://<user>.github.io/thptqg2017/old/`
-- `https://<user>.github.io/thptqg2017/old2/`
+```
+https://<user>.github.io/thptqg/
+https://<user>.github.io/thptqg/2016/
+https://<user>.github.io/thptqg/2017/
+https://<user>.github.io/thptqg/2017-old/
+https://<user>.github.io/thptqg/2017-old2/
+```
+
+`/thptqg/2017/old/` and `/thptqg/2017/old2/` were the pre-flattening URLs. They
+are still served, and the router rewrites them to the flat form with the query
+string intact.
 
 ## Local reproduction
 
 ```bash
 npm ci
-npm run build:db:all
-gzip -kf -9 public/thptqg2017.db public-old/thptqg2017.db public-old2/thptqg2017.db
-npm run build:all
-npx serve dist    # or any static server
+npm run build:rust
+npm run build:db      # all four; pass an id to build just one
+npm run build:site    # vite build + assemble into _site/
+npx serve _site
 ```
 
-## Adding a new variant
+To rebuild a single dataset:
 
-1. Drop source Excel files into a new `data-vN/` folder
-2. Add `public-vN/` to `.gitignore` patterns for the `.db` + `.db.gz`
-3. Copy `scripts/build-database-old.js` → `scripts/build-database-vN.js`; update `SRC_DIR` / `DB_PATH`; adjust parse logic for the new quirks (multi-sheet? blank rows? numeric guard?)
-4. Add variant to `VARIANT_CONFIG` in `vite.config.js`:
-   ```js
-   vN: { base: "/thptqg2017/vN/", publicDir: "public-vN", outDir: "dist/vN" }
-   ```
-5. Add `build:db:vN` and `build:vN` npm scripts; wire them into `build:db:all` and `build:all`
-6. Update `.github/workflows/deploy.yml` — add gzip step + rm step for the new DB
+```bash
+node parser/scripts/build-db.js 2017-old
+```
+
+## Base path
+
+`vite.config.js` sets `base: "/thptqg/"`. If you fork under a different repo
+name, update it to match — assets are referenced absolutely, so a mismatch shows
+up as a blank page with 404s on `/assets/...`.
+
+## Adding a dataset
+
+1. Put the Excel files in `data/<id>/`
+2. Add `parser/configs/<id>.toml` with the parse rules — sheet mode, column
+   indices, SBD validation, header tokens, blank-row stripping. No SQL: the
+   schema is canonical and lives in `parser/src/schema.rs`
+3. Add an entry to `DATASETS` in `src/datasets.js`
+
+Nothing else. The build script, the site assembly and the router all read that
+one list, and the frontend adapts to whichever columns the dataset populates.
+
+## Why no uncompressed database can ship
+
+`build-db.js` runs `gzip -9` **without** `-k`, so the raw file does not survive
+the build. `assemble-site.js` then fails the job if any `.db`, `.db-journal`,
+`.db-wal` or `.db-shm` reached the output.
+
+Both guards exist because the previous pipeline wrote a 100+ MB uncompressed
+database into the source tree and relied on an `rm` step to keep it out of the
+artifact — one missing line away from publishing it.
 
 ## Notes
 
-- **DB gzip is non-cacheable across deploys** — every rebuild produces a new `.db.gz` (not byte-identical due to SQLite page shuffling). First-visit users pay the 47 MB download; subsequent visits hit browser cache until the next deploy.
-- **GitHub Pages file size limit**: individual files ≤ 100 MB. Main gzipped DB is ~47 MB — safe. Uncompressed 159 MB DB would not fit; that's why we ship `.gz` and the frontend decompresses via `DecompressionStream`.
-- **No server-side compression assumption.** The app reads the `.gz` file directly (not `Content-Encoding: gzip`). GH Pages does not reliably gzip on-the-fly for arbitrary paths; shipping pre-gzipped bytes is deterministic.
+- **The gzipped database is not cacheable across deploys.** Every rebuild
+  produces a different `.db.gz`, because SQLite does not lay pages out
+  deterministically. First-visit users pay the full download; later visits hit
+  browser cache until the next deploy.
+- **GitHub Pages caps individual files at 100 MB.** The largest gzipped database
+  is about 48 MB. Uncompressed they run 135–234 MB and would not fit — which is
+  why the browser decompresses via `DecompressionStream`.
+- **No server-side compression is assumed.** The app fetches the `.gz` bytes
+  directly rather than relying on `Content-Encoding: gzip`; Pages does not
+  reliably compress arbitrary paths on the fly.
+- **Total artifact is about 177 MB**, well inside the 1 GB site limit.
 
 ## Rollback
 
-Deploys are stateless snapshots. To rollback, revert the commit on `main` and push — the next workflow rebuilds the older state. There's no state to migrate.
+Deploys are stateless snapshots. Revert the commit on `main` and push; the next
+run rebuilds the older state. There is no data to migrate.
+
+## Troubleshooting
+
+| Symptom | Typical cause |
+| --- | --- |
+| Blank page, 404 on assets | `base` in `vite.config.js` does not match the repo name |
+| `Failed to fetch database: 404` | Dataset id in `src/datasets.js` does not match the file in `db/` |
+| A route 404s | `assemble-site.js` did not run, or the id is missing from `DATASETS` |
+| WASM fails to load | `sql.js.org` unreachable — self-host `sql-wasm.wasm` and update `SQL_WASM_URL` in `use-sqlite.js` |
+| Deploy fails on assembly | An uncompressed database artefact reached the output; the error names the files |
+| Missing rows after a data update | Unknown Excel header — check the per-file row counts the parser prints |