gitrgoliveira · Oct 13, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 24, 2026 · Sep 24, 2026
diff --git a/.claude/rules/match-writes.md b/.claude/rules/match-writes.md
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -60,6 +60,7 @@ read the diff. See CONTRIBUTING and CLAUDE.md.
 - [ ] `make go/test` passes (lint + security scan + tests)
 - [ ] New/updated unit tests cover the change
 - [ ] Manual browser verification (for `web-mobile/` or `web/` changes): describe what you exercised
+- [ ] `make e2e` green locally (any `web-mobile/` change)
 - [ ] Screenshots added above (REQUIRED for any UI-affecting change)
 - [ ] Docs updated under `docs/` for any new or changed user-facing feature, flag, command, or behavior (`make docs/build` passes)
 - [ ] Docs screenshots and videos recaptured for any change to what a user sees (`make docs/media SINCE=main`; the changed ones reviewed and copied into `docs/`, or "none changed")

diff --git a/.gitignore b/.gitignore
@@ -68,6 +68,8 @@ Thumbs.db
 !web/package-lock.json
 !scripts/screenshots/package.json
 !scripts/screenshots/package-lock.json
+!scripts/e2e/package.json
+!scripts/e2e/package-lock.json
 # Go testdata fixtures. These are test INPUTS, not build output: the blanket
 # *.json above would silently drop them, and a golden table that never lands
 # fails CI on a checkout that works locally. /**/ matches zero or more
@@ -154,3 +156,7 @@ mp-*/
 
 # Docs capture harness: staged output, compared by eye before it replaces a committed file.
 scripts/screenshots/out/
+
+# E2E journeys (make e2e): per-run screenshots and Playwright's own artifacts.
+# Its node_modules/ is covered by the bare node_modules/ rule above.
+scripts/e2e/output/
diff --git a/AGENTS.md b/AGENTS.md
@@ -23,7 +23,7 @@ Detailed domain rulings (match results and marks, match writes and the offline q
 - **API Documentation:** The OpenAPI specification for the web API is located in `specs/openapi.yaml` and is fully synchronized with the backend implementation.
 - **Mobile App (`mobile-app` command):** A real-time tournament management server serving a Preact/JSX UI from `web-mobile/`. State is file-backed: `tournament-data/tournament.md` (YAML) and `tournament-data/competitions/<id>/config.md` + `participants.csv`. Backend in `internal/mobileapp/` (Gin handlers) and `internal/state/` (store). Real-time updates via SSE. Admin actions require `X-Tournament-Password` header. Run with `make run-mobile`.
 - **Real-Time Updates:** Real-time updates via SSE. Admin actions require `X-Tournament-Password` header. Run with `make run-mobile`.
-- **Admin Auth Modes:** Two startup-selected modes (`internal/mobileapp/auth_source.go`). **File mode** (default) stores the password plaintext in `tournament.md`; a public `POST /api/tournament/reset` resets it without the old password. **Locked mode** (`--lock-password` + `TOURNAMENT_PASSWORD_HASH` env var) compares the header against a bcrypt hash and disables the reset API (`POST /api/tournament/reset` returns 404; the SPA `/reset` page still loads but shows an operator-disabled message). The public `GET /api/auth-config` reports the active mode so the SPA can hide reset UI when locked. Generate hashes with `bracket-creator hash-password`.
+- **Admin Auth Modes:** Two startup-selected modes (`internal/mobileapp/auth_source.go`). **File mode** (default) stores the password plaintext in `tournament.md`; `POST /api/tournament/reset` resets it without the old password, for loopback callers only (403 `reset_local_only` otherwise). **Locked mode** (`--lock-password` + `TOURNAMENT_PASSWORD_HASH` env var) compares the header against a bcrypt hash and disables the reset API (`POST /api/tournament/reset` returns 404; the SPA `/reset` page still loads but shows an operator-disabled message). The public `GET /api/auth-config` reports the active mode so the SPA can hide reset UI when locked. Generate hashes with `bracket-creator hash-password`.
 - **Pool Scoring Rules:**
     - **Individual:** 1. Fights Won, 2. Fights Lost, 3. Hikiwake, 4. Points Scored, 5. Points Lost.
     - **Team:** 1. Team W, 2. Team L, 3. Team T, 4. Individual Winners (IV), 5. Individual Losses (IL), 6. Individual Ties (IT), 7. Points Won (PW), 8. Points Lost (PL).

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -116,7 +116,7 @@ go test -cover ./internal/helper/...
 - **`internal/excel/`**: Excel file lifecycle (`Client`), the from-scratch workbook template (`NewFileFromScratch`), style definitions.
 - **`internal/service/`**: Service layer abstraction over helper logic.
 - **`internal/resources/`**: Embedded file management. Resources flow: `main.go` embeds → `resources.NewResources()` → `cmd.ExecuteWithResources()`.
-- **`internal/mobileapp/`**: Gin HTTP handlers for the tournament app (`mobile-app` command). Routes: `handlers_competition.go` (including `POST /api/competitions/:id/generate-draw` [status `draw-ready`] and `DELETE /api/competitions/:id/draw` to discard the draw; a draw-ready competition is listed on the shiaijo operator views and its FIRST RECORDED result starts it -- a match left running or completed, NEVER a write that clears a result back to scheduled (the engine's result gate, which also discounts the byes a knockout draw resolves at generation time) -- via `engine.MaybeAutoCompletePools`'s `AutoCompleteStarted` outcome, which `tryAutoCompletePools` broadcasts as `competition_started`, so the desk's `POST .../start` is one of two doors, bc-prow ruling), `handlers_match.go`, `handlers_participants.go` (including single participant PUT updates, individual/bulk check-ins `POST /api/competitions/:id/participants/checkin-bulk`), `handlers_tournament.go`, `handlers_swiss.go` (`generate-round`, `standings`), `handlers_decision.go` (kiken/fusenpai/fusensho/daihyosen: `POST /api/competitions/:id/matches/:mid/decision`; `handleBothSidesBarredHikiwake` runs before the endpoint's own `Validate()` -- which otherwise 400s `hikiwake` outright with "use /score for fought/hikiwake" -- as the one carve-out that accepts `decision: "hikiwake"`, no `decisionBy` needed, when both sides of a SCHEDULED pool or league match (`engine.IsPoolMatchID`, league reuses the same `"Pool "`-prefixed ids; Swiss ids never match and are not covered) are already barred; the write records `Status: completed, Decision: "hikiwake"` with no new `CompetitorStatus`. The same both-barred knockout match instead gets `ineligible_competitor` naming both sides and pointing at the earlier withdrawal or the draw), `handlers_eligibility.go` (`/api/competitions/:id/competitor-status`), `handlers_lineup.go` (team lineups), `handlers_schedule.go` (`GET /api/schedule/estimate`, public), `handlers_reset.go` (`POST /api/tournament/reset`, public, for forgotten admin passwords; 404s in locked mode), `handlers_auth_config.go` (`GET /api/auth-config`, public, reports auth mode to the SPA). Real-time push via SSE (`hub.go`) with events: `match_updated`, `competitor_status_updated`, `competition_completed`, `swiss_round_generated`, etc. Auth via `X-Tournament-Password` header (`middleware.go`), with two modes selected at startup by a `PasswordVerifier` (`auth_source.go`): **file mode** (default, plaintext compare against `tournament.md`) or **locked mode** (`--lock-password` flag + `TOURNAMENT_PASSWORD_HASH` env var, bcrypt compare, `POST /api/tournament/reset` returns 404; the SPA `/reset` page still renders an operator-disabled message). Consumer-boundary interfaces live in `deps.go` (NFR-002).
+- **`internal/mobileapp/`**: Gin HTTP handlers for the tournament app (`mobile-app` command). Routes: `handlers_competition.go` (including `POST /api/competitions/:id/generate-draw` [status `draw-ready`] and `DELETE /api/competitions/:id/draw` to discard the draw; a draw-ready competition is listed on the shiaijo operator views and its FIRST RECORDED result starts it -- a match left running or completed, NEVER a write that clears a result back to scheduled (the engine's result gate, which also discounts the byes a knockout draw resolves at generation time) -- via `engine.MaybeAutoCompletePools`'s `AutoCompleteStarted` outcome, which `tryAutoCompletePools` broadcasts as `competition_started`, so the desk's `POST .../start` is one of two doors, bc-prow ruling), `handlers_match.go`, `handlers_participants.go` (including single participant PUT updates, individual/bulk check-ins `POST /api/competitions/:id/participants/checkin-bulk`; self-run mode has no check-in, so the three check-in writes answer 409 `check_in_not_in_self_run` for every caller, and `state.Competition.CheckInApplies` is the one owner the draw, the Swiss field and the estimate ask, never `CheckInEnabled` itself), `handlers_tournament.go`, `handlers_swiss.go` (`generate-round`, `standings`), `handlers_decision.go` (kiken/fusenpai/fusensho/daihyosen: `POST /api/competitions/:id/matches/:mid/decision`; `handleBothSidesBarredHikiwake` runs before the endpoint's own `Validate()` -- which otherwise 400s `hikiwake` outright with "use /score for fought/hikiwake" -- as the one carve-out that accepts `decision: "hikiwake"`, no `decisionBy` needed, when both sides of a SCHEDULED pool or league match (`engine.IsPoolMatchID`, league reuses the same `"Pool "`-prefixed ids; Swiss ids never match and are not covered) are already barred; the write records `Status: completed, Decision: "hikiwake"` with no new `CompetitorStatus`. The same both-barred knockout match instead gets `ineligible_competitor` naming both sides and pointing at the earlier withdrawal or the draw), `handlers_eligibility.go` (`/api/competitions/:id/competitor-status`), `handlers_lineup.go` (team lineups), `handlers_schedule.go` (`GET /api/schedule/estimate`, public), `handlers_reset.go` (`POST /api/tournament/reset`, for forgotten admin passwords; in file mode it answers loopback callers only, judged on `RemoteAddr` and never on forwarded headers, 403 `reset_local_only` otherwise; 404s in locked mode), `handlers_auth_config.go` (`GET /api/auth-config`, public, reports auth mode to the SPA). Real-time push via SSE (`hub.go`) with events: `match_updated`, `competitor_status_updated`, `competition_completed`, `swiss_round_generated`, etc. Auth via `X-Tournament-Password` header (`middleware.go`), with two modes selected at startup by a `PasswordVerifier` (`auth_source.go`): **file mode** (default, plaintext compare against `tournament.md`) or **locked mode** (`--lock-password` flag + `TOURNAMENT_PASSWORD_HASH` env var, bcrypt compare, `POST /api/tournament/reset` returns 404; the SPA `/reset` page still renders an operator-disabled message). Consumer-boundary interfaces live in `deps.go` (NFR-002).
 - **`internal/state/`**: File-backed state store for the mobile app. Tournament and competition config lives in `tournament-data/tournament.md` and `tournament-data/competitions/<id>/config.md` (YAML front-matter). Participants are in `participants.csv` alongside each config.
 - **`internal/engine/`**: Thin adapter that drives `internal/helper` pool/bracket generation from a `state.Competition`. Called by the `POST /api/competitions/:id/start` handler.
 - **`web-mobile/`**: Preact/JSX frontend for the mobile app, served embedded in the binary. Entry point: `web-mobile/index.html`. JS modules in `web-mobile/js/` are grouped by prefix: `admin_*.jsx` (the operator console: setup, participants, pools, scoring, scheduling, lineups, etc.), `viewer_*.jsx` and `display_*.jsx` (public attendee/spectator surfaces), and shared infrastructure (`app.jsx`, `api_client.jsx`, `api_serializers.jsx`, `bracket.jsx`, `data.jsx`, `patch.jsx`, `router.jsx`, `ui.jsx`, `glossary.jsx`). Run `ls web-mobile/js/` for the current set rather than relying on an enumerated list here. Note `admin_participants.jsx` holds the `LinedTextarea` gutter participant paste box; check-in is NOT there, it is owned by `admin_registration_desk.jsx`. CSS in `web-mobile/css/styles.css`. Pre-compiled to `web-mobile/dist/` by esbuild (run automatically as part of `make go/build`).

diff --git a/Makefile b/Makefile
@@ -25,7 +25,7 @@ else
 endif
 
 # Define phony targets
-.PHONY: default help clean local/deps hooks/install go/fmt go/generate go/test go/build go/lint go/sec go/sec-tests go/vuln go/security js/deps js/lint js/sec js/outdated js/security js/check-imports js/validate examples docker/build docker/run pre-commit docs/deps docs/serve docs/open docs/build docs/linkcheck docs/prose docs/clean docs/screenshots docs/videos docs/media run run-mobile esbuild-jsx goreleaser/test release version
+.PHONY: default help clean local/deps hooks/install go/fmt go/generate go/test go/build go/lint go/sec go/sec-tests go/vuln go/security js/deps js/lint js/sec js/outdated js/security js/check-imports js/validate examples docker/build docker/run pre-commit docs/deps docs/serve docs/open docs/build docs/linkcheck docs/prose docs/clean docs/screenshots docs/videos docs/media e2e e2e/deps run run-mobile esbuild-jsx goreleaser/test release version
 
 default: help ## Show help information (default)
 
@@ -377,6 +377,32 @@ docs/media: go/build $(SHOTS_BROWSER_STAMP) ## Regenerate every captured screens
 	@# those would start node and a browser twice over two disjoint halves.
 	@node $(SHOTS_DIR)/run.mjs $(if $(KIND),'KIND=$(KIND)',) $(SHOTS_ARGS)
 
+# Local e2e journeys (scripts/e2e, see its README.md). Like the capture harness
+# above, Playwright lives in its own package.json rather than web-mobile's, and
+# both pin the same Playwright release so they share one downloaded Chromium
+# under ~/.cache/ms-playwright. Deliberately NOT part of go/test and not run in
+# CI: a journey drives the real app through a browser, setup wizard and all.
+E2E_DIR := scripts/e2e
+E2E_DEPS_STAMP := $(E2E_DIR)/node_modules/.package-lock.json
+E2E_BROWSER_STAMP := $(E2E_DIR)/node_modules/.chromium-installed
+
+$(E2E_DEPS_STAMP): $(E2E_DIR)/package.json $(E2E_DIR)/package-lock.json
+	@echo "Installing the e2e harness dependencies..."
+	@npm --prefix $(E2E_DIR) ci --no-audit --no-fund
+	@touch $@
+
+$(E2E_BROWSER_STAMP): $(E2E_DEPS_STAMP)
+	@echo "Downloading the e2e browser..."
+	@cd $(E2E_DIR) && npx playwright install chromium
+	@touch $@
+
+e2e/deps: $(E2E_BROWSER_STAMP) ## Install the e2e harness and its Chromium (once per worktree)
+
+# E2E_ARGS is handed to `playwright test` as is: a spec path, --grep, --headed,
+# --project, ... e.g. make e2e E2E_ARGS='journeys/smoke.spec.mjs --headed'
+e2e: go/build $(E2E_BROWSER_STAMP) ## Run the local e2e journeys (E2E_ARGS= passes a spec, --grep or --headed to playwright)
+	@cd $(E2E_DIR) && npx playwright test $(E2E_ARGS)
+
 run: go/build ## Run the application locally
 	@echo "Running $(BIN_NAME)..."
 	$(BIN_PATH)/$(BIN_NAME) serve

diff --git a/docs/architecture/data-model.md b/docs/architecture/data-model.md
@@ -18,8 +18,12 @@ Inspectability, repairability and diffability matter more here than normalisatio
 * **Repairable.** An organiser can correct a wrong cell by hand, and the app picks it up on reload.
 * **Diffable.** The whole tournament state can be committed to version control or copied to
   a USB stick as a backup. Two copies can then be compared line by line.
-  One exception: `tournament.md` holds the tournament and admin passwords in plain text, so
-  strip or change them before sharing a copy.
+  One exception: `tournament.md` holds the admin password in plain text, so strip or
+  change it before sharing a copy. A `tournament.md` that carries an `admin_password` field
+  may hold another password in plain text there. The app ignores that field and drops it the
+  next time it writes the file; remove it by hand before sharing a copy that still has it.
+  Refer to
+  [Upgrading from an earlier release](../user-guide/organisers/operating-modes.md#upgrading-from-an-earlier-release).
 
 The trade this makes is described honestly in [section 6](#6-how-the-model-maps-onto-rows).
 

diff --git a/docs/architecture/infrastructure-architecture.md b/docs/architecture/infrastructure-architecture.md
@@ -137,7 +137,7 @@ flowchart TB
 
 | Device | What it runs | Notes |
 |---|---|---|
-| Operator console (1 per court) | admin scoring SPA | tablet/desktop surface; authenticates with the tournament password; scores its own shiai-jo |
+| Operator console (1 per court) | admin scoring SPA | tablet/desktop surface; authenticates with the admin password; scores its own shiai-jo |
 | Display screen (1 per court, optional) | public display / scoreboard view | a browser at a display URL; read-only, no auth. **Preferred: drive it from the operator console's own machine** via an HDMI cable to a TV or monitor, so the board survives a Wi-Fi outage (refer to [Keep the court scoreboard alive on the same machine](#keep-the-court-scoreboard-alive-on-the-same-machine-hdmi)). A standalone smart-TV browser or separate mini-PC also works but loses that offline path |
 | Spectator phones | public viewer (mobile-first) | can be on cellular; they don't need venue Wi-Fi when the app is cloud-hosted |