Merge pull request 'release: v1.7.0 — Telegram Mini App embedding enhancements' (#138) from development into master

The stale-invite / welcome-on-redeem notices are raised during boot, so the native
popup fired over the loading splash. Gate both the native popup and the in-app Modal
on the current route's loading cover being gone — the tile splash on the lobby
(splashDone), the plain loading screen elsewhere (app.ready) — so the notice appears
with the settled screen on every build (Telegram and native/web alike).

.gitea/workflows/ci.yaml

@@ -31,7 +31,7 @@ on:
 # unit/integration jobs inherit it. The deploy job overrides it per contour with
 # vars.TEST_DICT_VERSION (the seed for a fresh volume), see deploy/README.md.
 env:
-  DICT_VERSION: v1.2.1
+  DICT_VERSION: v1.3.0
 
 jobs:
   # changes detects which areas a PR/push touched, so the test jobs can skip when
@@ -267,6 +267,7 @@ jobs:
           TELEGRAM_MINIAPP_URL: ${{ vars.TEST_TELEGRAM_MINIAPP_URL }}
           TELEGRAM_GAME_CHANNEL_ID: ${{ vars.TEST_TELEGRAM_GAME_CHANNEL_ID }}
           TELEGRAM_CHAT_ID: ${{ vars.TEST_TELEGRAM_CHAT_ID }}
+          TELEGRAM_SUPPORT_CHAT_ID: ${{ vars.TEST_TELEGRAM_SUPPORT_CHAT_ID }}
           TELEGRAM_BOT_USERNAME: ${{ vars.TEST_TELEGRAM_BOT_USERNAME }}
           # The promo button reuses the UI's Mini App link variable.
           TELEGRAM_BOT_LINK: ${{ vars.TEST_VITE_TELEGRAM_LINK }}

.gitea/workflows/prod-deploy.yaml

@@ -179,6 +179,7 @@ jobs:
       TELEGRAM_MINIAPP_URL: ${{ vars.PROD_TELEGRAM_MINIAPP_URL }}
       TELEGRAM_GAME_CHANNEL_ID: ${{ vars.PROD_TELEGRAM_GAME_CHANNEL_ID }}
       TELEGRAM_CHAT_ID: ${{ vars.PROD_TELEGRAM_CHAT_ID }}
+      TELEGRAM_SUPPORT_CHAT_ID: ${{ vars.PROD_TELEGRAM_SUPPORT_CHAT_ID }}
       TELEGRAM_BOT_USERNAME: ${{ vars.PROD_TELEGRAM_BOT_USERNAME }}
       TELEGRAM_BOT_LINK: ${{ vars.PROD_VITE_TELEGRAM_LINK }}
     steps:
@@ -200,6 +201,7 @@ jobs:
           export TELEGRAM_MINIAPP_URL='$TELEGRAM_MINIAPP_URL'
           export TELEGRAM_GAME_CHANNEL_ID='$TELEGRAM_GAME_CHANNEL_ID'
           export TELEGRAM_CHAT_ID='$TELEGRAM_CHAT_ID'
+          export TELEGRAM_SUPPORT_CHAT_ID='$TELEGRAM_SUPPORT_CHAT_ID'
           export TELEGRAM_PROMO_BOT_TOKEN='$TELEGRAM_PROMO_BOT_TOKEN'
           export TELEGRAM_BOT_USERNAME='$TELEGRAM_BOT_USERNAME'
           export TELEGRAM_BOT_LINK='$TELEGRAM_BOT_LINK'

CLAUDE.md

@@ -1,96 +1,97 @@
 # scrabble-game — project guide
 
-Multiplatform Scrabble game. Read this first every session. The owner drives the
+Multiplatform Scrabble game, **in production** at `https://erudit-game.ru`. Read this
-project **one stage per session** (tariff constraint), so the repository — not
+first every session. The repository — not conversation memory — is the source of
-conversation memory — is the source of continuity. Keep it that way.
+continuity; keep it that way.
 
 ## Sources of truth (read before changing behaviour)
 
-- [`PLAN.md`](PLAN.md) — staged plan + **stage tracker** + per-stage *open
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture, transport, security,
-  details to interview*.
+  the decision record. Always describes the current state.
-- [`PRERELEASE.md`](PRERELEASE.md) — pre-release hardening tracker (phases R1–R7
+- [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md) mirror)
-  before Stage 18); same per-phase *interview + bake-back* discipline as `PLAN.md`.
+  — per-domain user stories. English authoritative.
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture, transport,
+- [`docs/TESTING.md`](docs/TESTING.md) — test layers + the CI gate.
-  security, the decision record. Always describes current state.
-- [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md)
-  mirror) — per-domain user stories. English authoritative.
-- [`docs/TESTING.md`](docs/TESTING.md) — test layers + the per-stage CI gate.
 - [`docs/UI_DESIGN.md`](docs/UI_DESIGN.md) — the `ui` visual/interaction design system.
+- [`deploy/README.md`](deploy/README.md) — the deploy contour + the production
+  rollout / rollback runbook.
 
-## Mandatory per-stage workflow
+## How we work
 
-**Start of a stage**
+- Inspect the relevant code path and the docs above before changing behaviour.
-1. Read `PLAN.md` (the stage's scope + *open details*) and the relevant `docs/`.
+- **Interview the owner on every fork** — do not silently pick borderline decisions;
-2. Analyse what the stage actually requires against the current code.
+  offer options with brief pros/cons.
-3. **Interview the owner** on every open detail and any fork not already fixed
+- Smallest correct diff. Prefer compact code; reuse before adding; do not add deps,
-   in the plan — do not silently pick borderline decisions. Offer options with
+  seams or knobs until they are needed.
-   brief pros/cons.
+- **Update or add tests for every functional change**, at the layers
-4. Only then implement, strictly within the stage's scope.
+  `docs/TESTING.md` calls out.
-
+- **Bake docs in the same PR**: update `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md`
-**End of a stage**
+  (+`_ru`), the affected service `README` and Go Doc comments alongside the change.
-1. Bake every new agreement back into `PLAN.md`, `docs/ARCHITECTURE.md`,
+- Document added packages, types, funcs, consts and vars with Go Doc comments.
-   `docs/FUNCTIONAL.md` (+ `_ru`), the affected service `README`, and Go Doc
-   comments — in the **same** PR. Correct earlier stages' docs/code if a new
-   decision changes them.
-2. Update the stage tracker; add a line under *Refinements logged during
-   implementation* for any plan deviation.
-3. Get CI green, then mark the stage done.
-
-(The `stage-implementation` skill encodes this same loop and can be invoked.)
 
 ## Conventions
 
 - All code, comments, identifiers, commits, docs, filenames in **English**.
-- Chat with the owner follows the user-level `~/.claude/CLAUDE.md` (Russian,
+- Chat with the owner follows the user-level `~/.claude/CLAUDE.md` (Russian, the
-  the agreed persona and translation rules).
+  agreed persona and translation rules).
-- Mirror every point edit of `docs/FUNCTIONAL.md` into `docs/FUNCTIONAL_ru.md`
+- Mirror every point edit of `docs/FUNCTIONAL.md` into `docs/FUNCTIONAL_ru.md` in the
-  in the same patch (translate only the touched paragraphs).
+  same patch (translate only the touched paragraphs).
-- Prefer compact code; do not add deps, seams or knobs until a stage needs them.
-  Reuse before adding. Document added packages/types/funcs with Go Doc comments.
-- Update or add tests for every functional change.
 
-## Branching & CI
+## Branching, CI & production
 
-- **Two long-lived branches** (Stage 16 onward): **`development`** is the
+- **Two long-lived branches**: **`development`** is the integration branch; **`master`**
-  integration branch; **`master`** is the production trunk. Cut `feature/*`
+  is the production trunk. Cut `feature/*` from `development` and PR back into it;
-  branches **from `development`** and PR them back into it. (Stages 0–15 used
+  promote `development → master` via PR when ready to release. Both branches require
-  `master` as the trunk with `feature/* → master`; the genesis Stage 0 commit is
+  one approval + the `CI / gate` check.
-  on `master` by necessity.)
+- A commit to a `feature/*` branch triggers nothing. The single workflow
-- A commit to a `feature/*` branch triggers **nothing**. The single workflow
+  `.gitea/workflows/ci.yaml` runs the full suite (`unit` + `integration` + `ui`) on a
-  `.gitea/workflows/ci.yaml` runs the full suite (`unit` + `integration` + `ui`)
+  PR into `development` or `master`, and the gated **`deploy`** job auto-rolls the
-  on a PR into `development` or `master`, and the gated **`deploy`** job auto-rolls
+  **test contour** on a PR into — or a push to — `development`
-  the **test contour** on a PR into — or a push to — `development`
+  (`docker compose up -d --build` on the runner host + landing/SPA/backend probes). A
-  (`docker compose up -d --build` on the runner host + a `GET /` probe). A PR into
+  PR into `master` is test-only.
-  `master` is test-only.
+- **Production is live on two hosts** (main + the Telegram bot host) and deploys
-- Merge `development → master` only when CI is green; the **prod** deploy is then a
+  **only manually** (`workflow_dispatch`), never automatically:
-  **manual** workflow (Stage 18), never automatic. Secrets/variables are prefixed
+  - **`.gitea/workflows/prod-deploy.yaml`** (`confirm=deploy`, from `master`) builds +
-  `TEST_` / `PROD_` per contour (Gitea 1.26 has no deployment environments).
+    pushes the images to the registry, then SSH-deploys both hosts — rolling per
-- After any push, watch the run to green before declaring a stage done — use the
+    service in dependency order, health-gated, **auto-rollback to the previous tag**;
-  ready-made watcher, never an inline poll loop:
+    a schema migration adds a maintenance window + a consistent `pg_dump`. Four visible
-  `python3 ~/.claude/bin/gitea-ci-watch.py` (background). It reads `$GITEA_URL`
+    jobs: build → deploy-main → deploy-bot → verify.
-  / `$GITEA_TOKEN`; `gitea.iliadenisov.ru` is allow-listed in
+  - **`.gitea/workflows/prod-rollback.yaml`** (`confirm=rollback`) re-deploys a prior
-  `.claude/settings.json`. Remote: `origin git@gitea.iliadenisov.ru:developer/scrabble-game.git`.
+    release (blank `target_version` = the previous deployed version) — image-only,
+    rolling, health-gated.
+  - **Releases are git tags `vX.Y.Z` on `master`**; the deploy stamps `git describe
+    --tags` into the image tag, every binary (`pkg/version` via `-ldflags` → the
+    `service.version` telemetry attribute) and the SPA About screen. Tag the release
+    before deploying.
+  - Hosts are provisioned idempotently by **`deploy/ansible/`**. Per-contour
+    secrets/variables use the `TEST_` / `PROD_` prefix (Gitea 1.26 has no deployment
+    environments). Migrations must be **expand-contract** (backward-compatible) so
+    image rollback stays DB-safe. Full runbook + variable list in `deploy/README.md`.
+- After any push, merge or deploy, **watch the run to green** before declaring done —
+  use the ready-made watcher (run it in the background), never an inline poll loop:
+  `python3 ~/.claude/bin/gitea-ci-watch.py`. It reads `$GITEA_URL` / `$GITEA_TOKEN`;
+  `gitea.iliadenisov.ru` is allow-listed in `.claude/settings.json`. Remote:
+  `origin git@gitea.iliadenisov.ru:developer/scrabble-game.git`.
 
 ## Stack
 
-Go 1.26.3, `go.work` monorepo, module paths `scrabble/<name>`. Dependencies are
+Go 1.26.3, `go.work` monorepo, module paths `scrabble/<name>`. Backend uses `gin` +
-added **when first used** (incremental): backend uses `gin` + `zap` +
+`zap` + `pgx`/`go-jet`/`goose`/OTel. Client↔gateway is Connect-RPC + FlatBuffers
-`pgx`/`go-jet`/`goose`/OTel (added in Stage 1). Client↔gateway is Connect-RPC +
+(h2c); gateway↔backend is REST/JSON + `X-User-ID` plus a gRPC server-stream for live
-FlatBuffers (h2c); gateway↔backend is REST/JSON + `X-User-ID` plus a gRPC
+events. UI is pure HTML5/CSS on plain Svelte + Vite, packaged to native with
-server-stream for live events. UI is pure HTML5/CSS on plain Svelte + Vite,
+Capacitor. No Redis.
-packaged to native with Capacitor. Likely no Redis.
 
 ## Reused engine: `../scrabble-solver` (module `scrabble-solver`, Go 1.26.3)
 
-Embedded **in-process as a library** — there is no per-game container. Public
+Embedded **in-process as a library** (`replace scrabble-solver => ../scrabble-solver`
-API to reuse (do not reimplement):
+in `go.work`; CI checks out the sibling from
+`https://gitea.iliadenisov.ru/.../scrabble-solver.git`). There is no per-game
+container. Public API to reuse (do not reimplement):
 
-- `scrabble.NewSolver(rs, finder)` → `GenerateMoves(b, r, mode)` (ranked,
+- `scrabble.NewSolver(rs, finder)` → `GenerateMoves(b, r, mode)` (ranked, highest
-  highest score first), `ValidatePlay(b, dir, tiles)`, `ScorePlay(...)`;
+  score first), `ValidatePlay(b, dir, tiles)`, `ScorePlay(...)`; `scrabble.Apply(b, m)`;
-  `scrabble.Apply(b, m)`; types `Move/Word/Placement/Direction/Mode`
+  types `Move/Word/Placement/Direction/Mode`
   (`scrabble-solver/scrabble/{solver,move,apply}.go`).
-- `rules.English() / RussianScrabble() / Erudit()`
+- `rules.English() / RussianScrabble() / Erudit()` (`scrabble-solver/rules/rules.go`).
-  (`scrabble-solver/rules/rules.go`).
 - `board.New / Parse / Clone / Transpose`; `rack.New / Add / Remove / Clone`;
   `selfplay.NewBag / Draw / Len` (bag pattern).
 - Load committed dictionaries with `dawg.Load(path)` from
@@ -99,20 +100,17 @@ API to reuse (do not reimplement):
 
 Constraints:
 - Words/tiles are **alphabet-index bytes**, meaningful only with the matching
-  `rules.Ruleset` (`Alphabet.Decode`); blank flag carried separately. **Decode
+  `rules.Ruleset` (`Alphabet.Decode`); the blank flag is carried separately. **Decode
   to real characters before persisting history** (history must be
   dictionary-independent — see `docs/ARCHITECTURE.md` §9.1).
 - The solver's `internal/*` is NOT importable from this sibling module.
 - **GCG is test-only** in the solver (no public writer) — we ship our own.
-- Wiring: add `replace scrabble-solver => ../scrabble-solver` to `go.work` in
+- The solver uses published `github.com/iliadenisov/{alphabet,dafsa}` (no local replace).
-  **Stage 2** (when `internal/engine` first imports it), and make CI check out
-  the solver sibling (`https://gitea.iliadenisov.ru/.../scrabble-solver.git`).
-  It uses published `github.com/iliadenisov/{alphabet,dafsa}` (no local replace).
 
 ## Repository layout
 
 ```
-go.work                      # use the existing modules; grows per stage
+go.work                      # the go.work monorepo
 backend/                     # module scrabble/backend
   cmd/backend/               # main: telemetry -> db+migrate -> cache -> server
   cmd/jetgen/                # dev tool: regenerate go-jet code (throwaway container)
@@ -123,12 +121,14 @@ backend/                     # module scrabble/backend
   internal/session/          # opaque tokens, sessions store, cache, service
   internal/server/           # gin engine, /api/v1 groups, X-User-ID, probes
   internal/inttest/          # //go:build integration Postgres-backed tests
-docs/  .gitea/workflows/  PLAN.md  CLAUDE.md  README.md
+gateway/                     # module scrabble/gateway: Connect-RPC edge, embeds the SPA
-gateway/  ui/  pkg/              # added by their stages
+ui/                          # Svelte + Vite SPA + landing (Node project, not in go.work)
-platform/telegram/               # Telegram side-service, two binaries (Stage 9; split in phase TX): cmd/validator (HMAC, no VPN) + cmd/bot (Bot API; dials gateway over reverse mTLS bot-link)
+pkg/                         # shared: telemetry, version, wire/FlatBuffers, proto, mtls
-loadtest/                        # module scrabble/loadtest: the pre-release stress harness (R2)
+platform/telegram/           # Telegram side-service: cmd/validator (HMAC, no VPN) + cmd/bot (Bot API; dials gateway over reverse mTLS bot-link)
-backend/Dockerfile gateway/Dockerfile platform/telegram/Dockerfile loadtest/Dockerfile  # multi-stage distroless (Stage 16; loadtest R2); gateway/Dockerfile has the `landing` target (R3), platform/telegram/Dockerfile has `validator`+`bot` targets (TX)
+loadtest/                    # module scrabble/loadtest: the load/stress harness
-deploy/                          # docker-compose (per-service limits, R7) + caddy + landing + otelcol (OTLP + docker_stats per-container metrics) + prometheus/tempo/grafana + postgres_exporter
+docs/  .gitea/workflows/  CLAUDE.md  README.md
+backend/Dockerfile gateway/Dockerfile platform/telegram/Dockerfile loadtest/Dockerfile  # multi-stage distroless; gateway/Dockerfile has the `landing` target, platform/telegram/Dockerfile has `validator`+`bot` targets
+deploy/                      # docker-compose (+ prod overlay + bot host) + ansible provisioning + caddy + landing + otelcol (OTLP + docker_stats) + prometheus/tempo/grafana + node_exporter + postgres_exporter; prod-deploy.sh
 ```
 
 ## Build & test
@@ -138,20 +138,19 @@ go build ./backend/...          # per module ('./...' from the root won't span t
 go vet ./backend/...
 gofmt -l .                      # must print nothing
 go test -count=1 ./backend/...
-go build ./platform/telegram/... && go test ./platform/telegram/...  # Telegram validator + bot (Stage 9; split in TX)
+go build ./platform/telegram/... && go test ./platform/telegram/...  # Telegram validator + bot
 go run ./backend/cmd/backend    # /healthz, /readyz on :8080
 
-cd ui && pnpm install && pnpm check && pnpm test:unit && pnpm build  # the UI (Stage 7+)
+cd ui && pnpm install && pnpm check && pnpm test:unit && pnpm build  # the UI
 pnpm start                      # UI mock mode: lobby -> game, no backend
 
-docker build -f backend/Dockerfile -t scrabble-backend .   # images (Stage 16); gateway embeds the SPA
+docker build --build-arg DICT_VERSION=v1.3.0 -f backend/Dockerfile -t scrabble-backend .  # DICT_VERSION required (no default); gateway embeds the SPA
 docker build -f gateway/Dockerfile --target gateway -t scrabble-gateway .
-docker build -f gateway/Dockerfile --target landing -t scrabble-landing .  # static landing (R3)
+docker build -f gateway/Dockerfile --target landing -t scrabble-landing .  # static landing
 docker compose -f deploy/docker-compose.yml config         # validate the full contour
 ```
 
-The `ui` module is a Node project (pnpm), **not** in `go.work`; it is the `ui` job
+The `ui` module is a Node project (pnpm), **not** in `go.work`; it is the `ui` job of
-of the single `.gitea/workflows/ci.yaml` (Stage 16 folded the former go-unit /
+the single `.gitea/workflows/ci.yaml`. Committed edge codegen under `ui/src/gen/`
-integration / ui-test workflows into it). Committed edge codegen under `ui/src/gen/`
 (regenerate with `pnpm codegen`); pnpm build-script approval lives in
 `ui/pnpm-workspace.yaml` (`allowBuilds: esbuild: true`).

PRERELEASE.md

@@ -1,632 +0,0 @@
-# Pre-release plan — hardening before Stage 18
-
-Living tracker for the pre-release hardening pass that runs **before Stage 18** (the
-prod cutover). Same discipline as [`PLAN.md`](PLAN.md): one phase per session,
-**interview the owner on the open details** at the start of each phase, bake every
-decision back into `PLAN.md` / `docs/` / the affected `README`s / Go Doc comments in
-the **same** PR, get CI green, then mark the phase done. Phases run as
-`feature/* → development` PRs (the Stage 16 branch model); the owner approves+merges.
-
-**Why now:** the system is feature-complete through Stage 17 and the test contour is
-green, but there is **no prod data yet** — schema, wire labels and the dictionary
-layout can still change for free. These phases spend that one-time freedom and harden
-the edge before prod. Each phase maps back to the owner's raw pre-release TODO list
-(numbers in the tracker).
-
-## Phase tracker
-
-| # | Phase | Raw TODOs | Status |
-|---|-------|-----------|--------|
-| R1 | Schema & naming reset | 1 + 10 | **done** |
-| R2 | Stress harness + contour observability + early run | 9a | **done** |
-| R3 | Edge hardening | 2 + 8 + 3 | **done** |
-| R4 | Push enrichment + kill the last poll | 4 + 5 | **done** |
-| R5 | Bundle slimming | 6 | **done** |
-| R6 | Refactor + docs reconciliation + de-staging | 7 | **done** |
-| R7 | Final stress run + tuning | 9b | **done** |
-| UI | Tab-bar navigation redesign (drop the hamburger) | owner ad-hoc | **done** |
-| MW | "Multiple words per turn" rule for Russian games (engine v1.1.0) | owner ad-hoc | **done** |
-| MW2 | Single-word rule connectivity fix: the word must run along its own line through an existing tile (perpendicular-only contact no longer connects); single-tile direction picks the best legal word (engine v1.1.1) | owner ad-hoc | **done** |
-| MW3 | Graceful replay degradation: a game whose journalled move became illegal under MW2 is closed as a draw (`end_reason='aborted'`) on open instead of erroring, with an impersonal organizer note in the history + GCG (migration `00002`) | owner ad-hoc | **done** |
-| OW | Open auto-match: enter the game at once and wait inside it (robot after 90–180 s) | owner ad-hoc | **done** |
-| DA | Dictionary admin: online release-archive upload → word-diff preview → install/activate; versioned dict volume; active version persisted in DB; resident label = release tag | owner ad-hoc | **done** |
-| AB | Manual account block (admin suspension): permanent/temporary with an editable en+ru reason picklist; a block forfeits the player's active games + cancels their open ones; a backend gate refuses a blocked account with **403 `account_blocked`**; the UI shows a terminal blocked screen and stops all push/poll; manual unblock; temporary blocks self-expire (migration `00003`) | owner ad-hoc | **done** |
-| AI | Honest AI opponent in quick game: an explicit 🤖 AI / 👤 random selector (AI default); the robot is seated and moves at once; 7-day inactivity loss (the per-turn timeout reused); chat/nudge disabled, no statistics; the opponent is shown as 🤖 everywhere | owner ad-hoc | **done** |
-| AD | Advertising banner ("ad network"): server-driven weighted campaigns (percent weight + validity window; the perpetual default fills the remainder up to 100%), bilingual messages shown by bot (`service_language`); eligibility = free account + empty hint wallet + no `no_banner` role (guests included); the resolved feed rides `profile.get` with a `notify` `banner` re-poll on eligibility change; `/_gm/banners` admin + global display timings; client smooth-weighted-round-robin rotation + fade-out/gap/fade-in UX. A single `app.load` bootstrap aggregator was considered and **deferred** (see ARCHITECTURE §10). | owner ad-hoc | **done** (PR1 backend+admin, PR2 UI rotation) |
-| GL | Simultaneous quick-game cap (10): grey "New Game" + a lobby notice at the cap; backend gate on quick enqueue + invitation creation (409 `game_limit_reached`), accepting invitations exempt; `at_game_limit` rides `games.list` | owner ad-hoc | **done** |
-| CR | In-game chat read receipts: per-message `unread_seats` bitmask (migration `00008`); a per-viewer unread **dot** in the lobby + game header (a nudge counts and clears when its recipient moves); reading = opening the move history (the 💬 fade-blinks twice) or the chat, acked (`chat.read`) only when unread; `chat_read_duration` + `chat_unread_messages` metrics + tracing + the **Scrabble — Messages** Grafana dashboard (follow-up PR); a message to a disguised robot opponent is born read; admin unread-only filter / read column / per-seat read card | owner ad-hoc | **done** |
-| BX | Asymmetric per-user block + in-game controls: a block now silently suppresses everything **from** the blocked user (chat, nudge, friend requests, invitations are kept but never delivered/surfaced, born-read) while they notice nothing, **without** deleting the friendship (unblock restores it); auto-match excludes a block-related pair (either direction); in-game opponent card gains a ✖️ **block** control (mirroring 🤝, red "Block?" confirm, mutual-hide, struck name + hidden chat composer when blocked); optimistic apply + `user_blocked`/`user_unblocked` event confirm + rollback; admin user card gains **blocks / blocked-by / friends** cross-linked lists. Blocking a disguised-robot opponent is recorded per-game in a separate **`robot_blocks`** table (migration `00011`), keyed on game+seat with the seen name — never the shared robot account — so the matchmaker keeps giving robots; it shows in the blocked list and re-marks the in-game card | owner ad-hoc | **done** |
-| FM | First-move tile draw (official rules): each seated player draws a tile, the one closest to "A" leads (a blank beats every letter), ties re-drawing until a single leader; **honest per-draw `crypto/rand` entropy**, not the bag seed, so the **record** (`game_setup_draws`, migration `00013`) — not a seed — is the only account of the outcome, kept for future **tournaments** (designed as a discrete per-tile "player N draws" step). Friend/AI draws at create; **auto-match draws at *open*** against a synthetic `uuid.Nil` opponent whose draw rows are back-filled on join, so the opener's seat is fixed up front and the existing open-game pre-move is preserved (no reseating, no play-gating). Admin `/_gm/games/:id` gains the recorded draw list + a simple **step-by-step board replay** (`ReplayTimeline`). | owner ad-hoc | **done** |
-| SB | Single Telegram bot + per-user variant preferences: the two per-language bots collapse into **one** (drop `accounts.service_language`, `supported_languages`, the `*_EN`/`*_RU` env vars and game-language push routing — the single bot renders in the recipient's `preferred_language`); New Game variant gating moves to a profile **`variant_preferences`** set (default Erudit only, Erudit-first, server-enforced on the caller's auto-match/vs-AI/invitation-create paths, an invited friend may accept any variant); env vars collapse to unsuffixed `TELEGRAM_BOT_TOKEN`/`TELEGRAM_GAME_CHANNEL_ID`/`VITE_TELEGRAM_LINK`/`VITE_TELEGRAM_GAME_CHANNEL_NAME` and `GATEWAY_DEFAULT_SUPPORTED_LANGUAGES` is removed; wire drops `service_language`/`supported_languages` (Session, ValidateInitDataResponse) + the push `language` routing field and adds `variant_preferences` to Profile/UpdateProfile. | owner ad-hoc | **done** |
-| DV | Dictionary version hygiene: CI + image/compose seed track the current release (`v1.2.1`); a **seed-drift guard** records the flat dir's seed in an authoritative `.seed_version` marker so a bumped build seed on a live volume is ignored (it can't relabel live bytes — which would mis-serve the dictionary + void games pinned to the prior label); `DICT_VERSION` is the fresh-volume seed only, a live contour migrates through the admin console | owner ad-hoc | **done** |
-| TX | Telegram egress off the main host: split the connector into a home **validator** (Mini App / Login-Widget HMAC, no VPN, no Bot API — so game login no longer depends on Telegram being reachable) and a remote **bot** (Bot API long-poll + `sendMessage`) that holds **no inbound port** and dials the gateway over a reverse **mTLS bot-link** (`pkg/proto/botlink/v1`); the gateway funnels out-of-app push (fire-and-forget, at-most-once) and the backend admin broadcasts (a relay that awaits the bot's ack) down the link. The bot is Telegram-rate-limited; **one bot now**, with seams (a bot registry + `owns_updates` + command ids) for N later; **no webhook** (rejected: one URL per token, adds inbound + a static address). The **unified test contour** runs the split (the bot keeps its VPN sidecar and dials the gateway by its internal name; certs from `deploy/gen-certs.sh`). The **prod** wiring — the bot on a separate host (no VPN), the gateway bot-link port published, `PROD_` certs, an SSH deploy of both hosts together — is **built in Stage 18** (the two-host registry rollout; first cutover pending the `erudit-game.ru` DNS). | owner ad-hoc | **done** (code + test contour; prod wiring built — Stage 18) |
-| AG | Anti-abuse IP ban + honeypot/honeytoken (prod-only): a fail2ban-style in-memory `ratelimit.Banlist` keyed by client IP, fed by sustained rate-limiter rejections (the IP-keyed public/email/admin classes — the user class stays the soft-flag's concern), a **honeypot** decoy path (the contour caddy tags `/.env`, `/.git`, `/wp-*`, … with `X-Scrabble-Honeypot` and routes them to the gateway), and a **honeytoken** (`GATEWAY_HONEYTOKEN`, a planted bearer). The `abuseGuard` edge middleware refuses a banned IP with **429** before any work — closing the R3 gap that the static SPA/landing was outside the token bucket. Off by default — it keys by the real client IP the shared-NAT test contour does not expose (detection still logs there); enabled in prod via `GATEWAY_ABUSE_BAN_ENABLED`. Operators see + lift bans on the console **Throttled** page; the gateway syncs its active set to the backend (`/api/v1/internal/bans/sync`, `internal/banview`) every 30 s and applies operator unbans. | owner ad-hoc | **done** (code + test contour; ban on in prod via Stage 18 — machinery built, cutover pending DNS) |
-| CM | Channel-chat moderation + promo bot: a second standalone bot in the bot container answers `/start` with a localized message + a **URL** button into the **main** bot's Mini App (`?startapp`; a `web_app` button would sign initData with the promo token, which the main validator rejects). The **main** bot gates write access in a channel's linked discussion chat. The chat **allows sending by default** and the bot only restricts (Telegram intersects the chat default with the per-user permission, so a per-user grant cannot exceed a deny-by-default group): it **mutes** a member who is not registered or is admin-suspended or holding a new **`chat_muted`** role, and **un-mutes** an eligible one it had muted, for a member currently in the chat (a `getChatMember` guard, since bots cannot list members). Eligibility = `registered AND NOT suspended AND NOT chat_muted` (the game suspension dominates), resolved once in the backend and reached two ways: the bot's `ResolveChatEligibility` on a `chat_member` event over the existing mTLS bot-link, and a backend `chat_access_changed` event → gateway → `ChatGate` command (emitted on block/unblock, a `chat_muted` change, a first registration, or a temporary-block expiry via a sweeper; idempotent). No schema change — `chat_muted` reuses `account_roles`. | owner ad-hoc | **done** |
-| → | Stage 18 — prod contour deploy | — | see [`PLAN.md`](PLAN.md) |
-
-## Key findings (these reshaped the raw list — read before starting a phase)
-
-- **R1 (TODO 1 + 10) is one cheap moment, now.** Squashing the 12 goose migrations is
-  safe precisely because there is no prod data and the contour DB is wiped. Folding the
-  new variant labels (`scrabble_ru`/`scrabble_en`/`erudit_ru`) into that single baseline
-  makes the rename need **no data migration and no back-compat mapping**. Today's labels
-  (`english`/`russian_scrabble`/`erudit`) are persisted in `games.variant`,
-  `game_invitations.variant`, in `pkg/fbs` and the UI — ~100 files, but a mechanical sweep
-  on a clean DB.
-- **R4 (TODO 4 + 5): the app is already push-first.** Game state refreshes on
-  `your_turn`/`opponent_moved`, the lobby on `notify`, chat on `chat_message`. The **only**
-  genuine periodic server poll is `lobby.poll` (matchmaking, 2.5 s,
-  `ui/src/screens/NewGame.svelte`). What remains is killing that one poll **and** enriching
-  push events to carry payloads so the UI stops re-fetching after each signal.
-- **R3 (TODO 2): identity forgery is already mitigated.** Identity is always derived from
-  the session (`Authorization: Bearer` → `X-User-ID`); the client cannot inject identity,
-  the backend re-validates resource ownership, Telegram initData is HMAC-checked. The real
-  gaps are a missing **request-body size limit** (cheap DoS) and **invisible rate-limit
-  rejections** (no log/metric/admin view — that is TODO 8). Static landing serving is **not**
-  covered by the gateway token bucket (it only guards `Execute`).
-- **R6 (TODO 7) scale:** ~431 `Stage N` references across ~104 files (incl. the file name
-  `backend/internal/inttest/stage6_test.go`). Code is the source of truth; `docs/` describe
-  current state; `PLAN.md` keeps the decision history.
-
-## Locked decisions (owner interview)
-
-- **Stress test (TODO 9):** **early + final** runs. Driver = **edge protocol** (Connect/FB
-  through the gateway, moves generated by the solver) **plus a separate gateway-hammer**
-  saturation test. Pacing = **realistic (under limits) + saturation (ramp to the knee)**.
-  Resource metrics = **add cAdvisor + postgres_exporter to the contour** (today only
-  Go-runtime metrics exist). The harness stays in the repo for repeats.
-- **Push (TODO 4 + 5):** **both** — kill `lobby.poll` (use the existing `match_found`, keep
-  poll as the ws-down fallback) **and** enrich push events with payloads.
-- **Refactor (TODO 7):** **hygiene + structural changes by a reviewed list** —
-  behaviour-preserving, test-gated, contentious items surfaced to the owner before applying.
-- **Landing (TODO 3):** **separate static container** behind the project caddy
-  (`/` → landing, `/app/` + `/telegram/` → gateway); drop `landing.html` from the gateway
-  `go:embed`.
-- **Rate-abuse (TODO 8):** metric + Grafana + admin view **plus a conservative auto-flag** —
-  a *soft, reversible* "suspected high-rate" marker for operator review, tunable threshold,
-  **no auto-ban**.
-- **Anti-abuse IP ban (AG, owner ad-hoc):** a honeypot was considered and rejected as a *DDoS*
-  defence — it detects/deceives but does not shed volumetric load, cannot cover the real
-  endpoints, and a tarpit backfires under flood; volumetric L3/L4 is an upstream/CDN concern,
-  out of scope. The effective layer is a **temporary IP ban** (fail2ban-style) that the honeypot
-  and honeytoken merely *feed*. This does **not** reverse the TODO-8 "no auto-ban": that decision
-  governs the **account** soft-flag (still never a gate); the IP ban is a separate, IP-keyed,
-  **prod-only** layer with an **operator unban** in the console. Decisions: banlist lives in the
-  existing `ratelimit` package (smallest surface); the decoy path list is a **single source of
-  truth in the caddy** (it tags requests with a header — the gateway keeps no second list);
-  bans are in-memory + single-instance (like `ratewatch`), auto-expiring, **plus** an admin
-  console view + manual unban over a bidirectional 30 s sync (operator control = owner's choice).
-  An active-bans Grafana **gauge** was trimmed (the console view + the `gateway_abuse_banned_total`
-  counter cover it) to keep the diff focused.
-- **Open auto-match (owner ad-hoc):** a quick game **enters a real game at once and waits inside
-  it** (status `open`, the opponent seat empty); a second human searching the same variant+rule
-  joins it, or a robot fills it after a **90 s + random 0–90 s** wait, pushing the in-app
-  **opponent_joined** event. While open, the starter may move on their turn but resign, chat and
-  nudge are disabled, and the lobby + opponent card read "searching for opponent". Matchmaking is
-  now **DB-backed open games** — the in-memory pool, `lobby.poll` and `lobby.cancel` are gone. The
-  schema is edited in the baseline (no prod data); `game_players.account_id` is nullable for the
-  empty seat.
-- **Telegram egress off-host (TX, owner ad-hoc):** the driver is **removing VPN/Telegram
-  traffic from the main host** (OPSEC / one fewer analysis vector), not only notification
-  resilience. Login is local HMAC, so it stays up regardless of the bot — confirmed in the
-  code and made structural by the split. **Unified topology in code** (validator + bot, the
-  bot dialing the gateway) in **both** contours, differing only in deployment; the test bot
-  keeps its VPN sidecar. Transport = a **reverse gRPC bidi stream, mTLS, bot-dials-gateway**
-  (no inbound/static IP on the bot), reusing the push-stream pattern; **webhook rejected**
-  (one URL per token, adds inbound + a static address). Delivery **at-most-once** (a dropped
-  nudge beats a duplicate). **One bot now**, seams (registry + `owns_updates` + command ids)
-  for N later. **Cert rotation** by a scheduled CI job from a long-lived CA. **Prod deploy by
-  SSH** (pull excluded), the bot rolled **together** with the main app (the bot-link protocol
-  kept back-compatible by one version as the non-atomic-two-host-deploy safety net). The bot
-  is monitored **from the gateway** (connection + ack metrics). The bot-host token-at-rest is
-  **accepted**.
-
-## Phases
-
-Each phase: read this tracker + the relevant `docs/`, **interview the owner on the open
-details below**, implement within scope, then update the tracker + docs/code and get CI
-green before marking it done.
-
-### R1 — Schema & naming reset *(TODO 1 + 10)* — first
-Squash `backend/internal/postgres/migrations/00001..00012` into one `00001_baseline.sql`
-(method: `pg_dump --schema-only` from a fully-migrated DB → wrap as the goose baseline →
-prove a fresh migrate yields a schema identical to the 12-migration chain via the
-integration suite → delete the old files; keep goose). Bake the new variant labels into the
-baseline. Propagate `scrabble_ru`/`scrabble_en`/`erudit_ru` through the backend
-(`engine.Variant`/`ParseVariant`, `registry.dictFiles`, the CHECK values), the wire
-(`pkg/fbs` `variant:string`, regenerate FB) and the UI (`lib/model.ts` union, `variants.ts`,
-fixtures, premium/alphabet keys, tests); i18n display keys stay display-only. Tidy
-`../scrabble-dictionary` to a single source→dawg build point and align the dawg artifact
-names to the new labels (crosses into `../scrabble-solver`'s committed fixtures — keep them
-byte-identical). After merge, **wipe the contour DB** (drop the volume) so it re-provisions
-on the next deploy.
-- Critical files: `backend/internal/postgres/migrations/`,
-  `backend/internal/engine/{engine,registry}.go`, `pkg/fbs/scrabble.fbs`,
-  `ui/src/lib/{model,variants}.ts`, `../scrabble-dictionary/{Makefile,cmd/builddict,…}`.
-- Open details to interview: the exact dawg filename scheme; whether the dict-repo tidy is
-  one PR or split; how to script the contour DB wipe in the deploy.
-
-### R2 — Stress harness + contour observability + early run *(TODO 9, part 1)*
-Build the reusable load harness as a new `loadtest` module in `go.work` (reuses `pkg/fbs`,
-`connect-go`, and `scrabble-solver` for legal-move generation): a seeder that inserts
-**1000 guest + 10000 durable** accounts with pre-created sessions (token hashes) directly in
-the DB and hands the plaintext tokens to the client; a driver that runs N virtual users,
-each in 3–5 concurrent 2–4-player games, exercising submit-play / pass / exchange / nudge /
-chat / check-word / draft-move / profile-save through the **edge protocol**, in
-**realistic** (under rate limits) and **saturation** (ramp) modes; plus a separate
-**gateway-hammer** that deliberately exceeds limits to verify the limiter holds and measure
-its cost. Add **cAdvisor + postgres_exporter** to `deploy/docker-compose.yml` and a Grafana
-resource dashboard. Run the **early pass** against the freshly-wiped contour; produce a
-**trip report** (logic/concurrency bugs + a resource baseline) that feeds R3 and R6.
-- Critical files: new `loadtest/`, `deploy/docker-compose.yml`, `deploy/observability/*`,
-  `docs/TESTING.md`.
-- Open details: the scale ramp steps; the move-selection policy (a mid-ranked solver move
-  for realistic game progress); run duration; the pass/fail bar.
-
-### R3 — Edge hardening *(TODO 2 + 8 + 3)*
-Add a **request-body size cap** at the gateway h2c mux / `Execute` (e.g. ~1 MB). Add
-**rate-limit observability**: a `gateway_rate_limited_total{class}` counter + a structured
-log per rejection; an **aggregate** Grafana panel (request rate + rejection rate — spikes
-visible without per-user label cardinality, honouring the Stage 12/17 discipline); an
-**admin-console view** of recently throttled users/IPs (in-memory ring buffer, single-
-instance, reset-on-restart, like the `active_users` gauge). Add the **conservative
-auto-flag**: when a user is *sustained*-throttled past a tunable threshold, set a soft,
-reversible `account.flagged_high_rate_at` marker (baked into the R1 baseline) surfaced in the
-admin user list/detail — **no auto-ban**; the operator clears it. Split the **landing** into
-its own static container (`deploy/` + a Caddyfile route `/` → landing) and drop
-`landing.html` from the gateway `go:embed`.
-- Critical files: `gateway/internal/connectsrv/server.go`, `gateway/internal/ratelimit/`,
-  `gateway/internal/connectsrv/metrics.go`, `backend/internal/adminconsole/`,
-  `deploy/caddy/Caddyfile`, `deploy/docker-compose.yml`, `gateway/internal/webui/`.
-- Open details: the auto-flag threshold/window + whether the marker is persisted vs
-  in-memory; the landing image base (caddy vs nginx).
-
-### R4 — Push enrichment + kill the last poll *(TODO 4 + 5)*
-Replace `lobby.poll` with the existing `match_found` push (keep the poll as a ws-down
-fallback). Enrich `your_turn`/`opponent_moved`/`notify` to carry the state payload so the UI
-renders from the event without a follow-up `game.state` (removes the lobby↔game nav latency
-the owner noticed). Wire-contract change: `pkg/fbs` event payloads → backend `notify` emit →
-UI stream consumers (`ui/src/lib/app.svelte.ts`), with the per-game cache as the landing
-spot; regenerate FB.
-- Critical files: `pkg/fbs/scrabble.fbs`, `backend/internal/notify/events.go`,
-  `ui/src/lib/{app.svelte,transport}.ts`, `ui/src/screens/NewGame.svelte`.
-- Open details: which events carry full vs delta payloads; the fallback-poll cadence when the
-  stream is down.
-
-### R5 — Bundle slimming *(TODO 6)* — done
-Analysed the bundle against the 100 KB-gzip budget; **no code slimming was warranted**, and the
-budget metric was retargeted to measure the app correctly. The build already minifies +
-tree-shakes; the dominant cost is the Connect/FlatBuffers transport runtime + generated bindings
-+ the Svelte runtime (≈⅔ of `main`'s source is third-party/generated) — irreducible within scope.
-**Lazy-loading was rejected**: `bundle-size.mjs` sums every emitted chunk, so code-splitting yields
-no total-size win and adds request latency (+N gateway fetches on first navigation to a split
-screen). i18n lazy-load was skipped (the catalogs are a sliver of a Svelte-runtime-dominated shared
-chunk, and `en` must stay bundled as the `MessageKey` type source + fallback). Instead,
-`bundle-size.mjs` now measures **per HTML entry**, with three independent gates on the natural chunk
-boundaries — **app entry ≤ 100 KB, the Svelte+i18n shared chunk ≤ 30 KB, the landing's own chunk
-≤ 5 KB** — since the app's real payload is its entry chunk plus the shared chunk (≈97 KB), while the
-landing (≈24 KB) is reported separately and kept minimal. Same CLI + exit-code contract, so the CI
-step is unchanged.
-- Critical files: `ui/scripts/bundle-size.mjs`; no app code changed.
-
-### R6 — Refactor + docs reconciliation + de-staging *(TODO 7)* — done
-Behaviour-preserving only. Three separable, separately-committed passes: (a) mechanical
-**de-staging** — remove `Stage N`/`TODO-N` references from code, comments and service
-READMEs (rename `stage6_test.go`); (b) **docs↔code reconciliation** — reconcile
-`docs/ARCHITECTURE.md` / `docs/FUNCTIONAL.md`(+`_ru`) against the code-as-truth, fixing drift
-and Go Doc comments; (c) **structural changes by a reviewed list** — surface a list of
-proposed optimizations / test-suite consolidations to the owner, apply only the approved,
-behaviour-preserving, test-gated ones. The full suite + the final stress run (R7) are the
-regression gate. Incorporates the early-run (R2) bug fixes not already shipped.
-- Open details: the structural-changes list itself (owner-approved before applying); the test
-  consolidation targets.
-
-### R7 — Final stress run + tuning *(TODO 9, part 2)* — done
-Re-run the R2 harness against the final, refactored system on a clean contour; analyse
-resource consumption across **all** components (gateway, backend, Postgres, the
-metrics/observability stack, docker log volume) and agree the tuning (pool sizes, rate
-limits, cache TTLs, container limits, GOMAXPROCS, log levels). Apply the agreed tuning; record
-the methodology + results in the repo.
-
-→ **Stage 18** (prod contour) then proceeds per [`PLAN.md`](PLAN.md).
-
-## Sequencing rationale
-
-`R1` first (cheapest now; everything builds on the final schema/naming and the stress test
-must run against it). `R2` builds the harness and runs the **early** pass to surface bugs and
-a resource baseline that feed `R3` and `R6`. `R3`/`R4`/`R5` harden and improve the system.
-`R6` (de-stage + reconcile + structural) runs near the end so it sweeps settled code once and
-benefits from all accumulated bug knowledge. `R7` validates the final system and tunes it.
-Then Stage 18.
-
-## Regression-safety discipline (cross-cutting)
-
-- Every phase is a `feature/* → development` PR; CI (`unit` + `integration` + `ui` behind the
-  `CI / gate` check) must be green before the owner merges; watch the post-merge contour
-  deploy with `gitea-ci-watch.py`.
-- `R6` structural changes are behaviour-preserving, test-gated, and split from the mechanical
-  sweeps; contentious items are owner-approved first.
-- The two stress runs (`R2` early, `R7` final) are the system-level regression gate.
-
-## Verification (per phase)
-
-- `go build ./<module>/...`, `go vet`, `gofmt -l .` clean, `go test -count=1 ./<module>/...`;
-  UI: `pnpm check && pnpm test:unit && pnpm build`; the integration suite
-  (`-tags integration`) for DB/schema changes; `docker compose config` for deploy changes;
-  green CI on the PR + a healthy contour deploy.
-- `R1`: prove the squashed baseline yields a schema identical to the 12-migration chain
-  (integration suite on a fresh DB) **before** deleting the old files.
-- `R2`/`R7`: the harness runs end-to-end against the contour; the trip report lists concrete
-  defects + a resource profile from the Grafana cAdvisor/postgres_exporter panels.
-
-## Refinements logged during implementation
-
-- **R1** (interview + implementation):
-  - **Variant labels** `english`/`russian_scrabble`/`erudit` → **`scrabble_en`/`scrabble_ru`/`erudit_ru`**
-    across the backend (`engine.Variant.String`/`ParseVariant`; the `games`/`game_invitations` `variant`
-    CHECK in the baseline; GCG `#lexicon` and the `variant` metric attribute both flow from `String`),
-    the wire (`pkg/fbs` `variant` is a `string` field — values change with **no FlatBuffers regen**) and
-    the UI (`model.ts` union, `variants.ts` records, `codec`/`premiums`/mocks/tests, the admin
-    `dictionary.gohtml`). **Kept:** the Go enum identifiers (`VariantEnglish`…, internal) and the i18n
-    display keys (`new.english`/`new.russian`/`new.erudit`, display-only). `complaints.variant` stays
-    free-text (no CHECK, as before).
-  - **dawg filenames kept descriptive** (`en_sowpods`/`ru_scrabble`/`ru_erudit`) — only the registry's
-    `Variant` key carries the rename, so `registry.go`, the published `scrabble-solver` fixtures and the
-    dictionary release artifact are untouched (decouples the three repos).
-  - **Migrations squashed** 12 → one hand-written `00001_baseline.sql`. Verified by a
-    `pg_dump --schema-only` diff (the chain vs the baseline are **identical** but for the two intended
-    variant-CHECK values) plus the green integration suite. **No data migration** (no production data).
-  - **Done (cross-repo + contour):** the **`scrabble-dictionary` tidy** merged (PR #2) and was re-cut as
-    the **byte-identical `v1.0.1`** release for clean provenance (the backend stays on `v1.0.0` — same
-    bytes, no rewire; the backend pulls a version-pinned release artifact, not master). Post-merge the
-    contour `backend` schema was wiped (`DROP SCHEMA backend CASCADE` + restart, not a volume drop) and
-    re-migrated to the baseline — verified the new variant CHECK (`scrabble_en/scrabble_ru/erudit_ru`),
-    `games`=0 and a clean boot.
-
-- **R2** (interview + implementation):
-  - **Locked decisions:** game assembly via **invitations** (real path, no robots; not direct game-row
-    inserts); **moderate** ramp **50 → 200 → 500** at 10 min/step; **diagnostic** pass bar (no SLO gate);
-    run as a **one-shot container on `scrabble-internal`** in this PR.
-  - **Harness** = new `scrabble/loadtest` module (`use ./loadtest` + a `replace scrabble/gateway` for the
-    dot-free edge-proto import). It seeds 1000 guest + 10000 durable accounts + sessions **directly in
-    Postgres** (token hash mirrors `backend/internal/session`), drives players over the **edge protocol**,
-    generates **mid-ranked legal moves locally** with the embedded `scrabble-solver` by replaying
-    `game.history` (the edge carries no board — mirrors `engine.ReplayBoard` via the public API), and a
-    **gateway-hammer**. Compact CLI (`run` / `cleanup`), distroless Dockerfile (DAWGs baked), Go unit tests.
-  - **Adding the module broke the other images' builds** — backend/gateway/telegram Dockerfiles reduce the
-    workspace but still referenced `./loadtest` (not in their context); each now also
-    `-dropuse=./loadtest` (backend/telegram additionally `-dropreplace` the gateway replace). Caught by the
-    first deploy run; verified by building all four images.
-  - **Harness payload fixes found by the smoke pass:** the draft DTO's `rack_order` is a string (was sent
-    as `[]` → `bad_request`); the display-name validator forbids digits/colons, so the cleanup marker
-    became a letters-only `Zzloadtest` so `profile.update` resends the seeded name. `chat_not_your_turn` /
-    `nudge_own_turn` are **by-design** turn gates, correctly exercised.
-  - **Observability:** added **cAdvisor + postgres_exporter** + the **Scrabble — Resources** dashboard +
-    two Prometheus jobs. **Finding:** cAdvisor yields only the root cgroup on the contour host (separate
-    XFS `/var/lib/docker` breaks its layer-ID resolution — the existing galaxy deploy has the same limit),
-    so per-container CPU/RSS for the early pass was captured via `docker stats`. **R7:** adopt the otelcol
-    `docker_stats` receiver (already the contrib image) for per-container metrics in Grafana.
-  - **Early run (2026-06-09):** ramped clean to 500 players, no crash/deadlock, cleanup removed all 11000
-    accounts. 1.2 M edge calls, 48 870 plays, 2 798 games finished; the per-user limiter held under the
-    hammer (99.97 % rejected, p99 2 ms). **Top finding:** ~14 % `transport_error` on `game.state` at 500
-    players, under CPU saturation (backend/gateway/Postgres each ~1 core) and amplified by the harness's
-    single shared `http2.Transport`; the harness itself peaked at 86 % of a core on the same host, so the
-    figures are pessimistic. Full trip report in [`../loadtest/REPORT.md`](../loadtest/REPORT.md);
-    it feeds R3 (h2c `MaxConcurrentStreams`/timeouts, body-size cap), R6 and R7 (per-player transports,
-    separate hardware, pool/limit sizing).
-  - **CI:** `./loadtest/...` added to the path filter + vet/build/test; `go.work.sum` carries the new deps.
-
-- **R3** (interview + implementation):
-  - **Locked decisions:** the flag column lands by **editing the R1 baseline** (+ a contour schema
-    wipe after merge — no migration chain accrues before prod); auto-flag defaults **1000 rejected /
-    10 min** (`BACKEND_HIGHRATE_FLAG_THRESHOLD`/`_WINDOW`, rolling window, set-once, operator clears,
-    no auto-ban); landing image = **caddy:2-alpine**; throttle data flows **gateway → backend** (a
-    30 s per-key summary POST to the new `/api/v1/internal/ratelimit/report`, the existing trusted
-    direction) with the episode window + flag rule in the backend (`internal/ratewatch`); rejection
-    logging = **Warn summary per key per window + Debug per rejection** — a deliberate deviation from
-    the phase's "structured log per rejection" (the R2 hammer would have logged ~522k lines in
-    minutes); all three R2-report tails included (explicit h2c sizing, the session-resolve failure
-    cause at Warn, reviving the admin limiter).
-  - **Body cap:** `GATEWAY_MAX_BODY_BYTES` (default 1 MiB) as both the Connect per-message read limit
-    and an `http.MaxBytesReader` wrap of the public mux; an oversized Execute is `resource_exhausted`.
-  - **Dead config found:** `AdminPerMinute`/`AdminBurst` were never wired — the gateway `/_gm` mount is
-    now 429-guarded per IP ahead of its Basic-Auth. The caddy-fronted contour path stays unlimited
-    (stock caddy has no limiter) — an accepted gap, recorded in `docs/ARCHITECTURE.md` §12.
-  - **Landing split:** a `landing` target in `gateway/Dockerfile` (the UI build stage is shared;
-    identical compose build args keep it one cached build); the gateway drops `landing.html` from the
-    embed and 308-redirects `/` → `/app/`; the contour caddy routes `/app/`, `/telegram/` and the
-    Connect path to the gateway and the catch-all to the landing container; the CI deploy probe now
-    checks both `/` (landing) and `/app/` (gateway).
-  - **Observability:** `gateway_rate_limited_total{class}` (user/public/email/admin, aggregate-only)
-    + a rate-vs-rejections panel on the Edge/UX dashboard; the admin console gains the **Throttled**
-    page (the in-memory episode window, reset-on-restart like `active_users`, plus the flagged-account
-    queue) and the flag badge / clear action on the user list / card.
-  - The jet regen also restored the previously missing `game_drafts`/`game_hidden` generated models
-    (their tables were added after the last jetgen run; no behaviour change).
-
-- **R4** (interview + implementation):
-  - **Locked decisions:** **delta-first**, not full snapshots — an event carries only the new move and
-    the UI applies it to its per-game cache, keyed on `move_count` (idempotent + gap-safe: a gap or the
-    actor's own move falls back to a `game.state` + `game.history` refetch). `match_found` /
-    `game_started` carry the recipient's **initial `StateView`** (instant lobby→game); the fallback
-    refetch stays the existing two calls (no merged endpoint); the matchmaking poll runs **only while
-    the stream is down** (2.5 s); **all** UI-state-changing events carry their payload (incl. lobby `notify`).
-  - **Enriched events** (`pkg/fbs` trailing fields — backward-compatible, no FB regen of *values*, only
-    the schema): `opponent_moved` (+`move`/`game`/`bag_len`), `your_turn` (+`move_count`), `match_found`
-    (+`state`), `game_over` (+`game`), `notify` (+`account`/`invitation`/`state`). The pre-R4
-    `opponent_moved` scalars (`seat`/`action`/`score`/`total`) stay for wire back-compat, now redundant
-    with `move`/`game` — slated for the R6 de-stage.
-  - **Encoding placement:** the `notify` package keeps ownership of the FlatBuffers encoding (a new
-    `encode.go` mirrors the gateway transcode but reads wire-agnostic `notify.*` input structs +
-    `engine.MoveRecord`); the game/lobby/social services map their domain types to those structs, so the
-    wire schema stays out of the domain. **Flagged for R6:** this partly duplicates the gateway encoders
-    (different source types) — a candidate consolidation.
-  - **Actor self-fetch killed too** (beyond literal "push"): the `submit_play`/`pass`/`exchange`/`resign`
-    **response** (`MoveResult`) now returns the actor's refilled rack + bag size, so the mover renders the
-    next turn from the response — `Game.svelte`'s `commit`/`pass`/`exchange`/`resign` drop their `await load()`.
-  - **`match_found` enrichment** needs a per-seat initial state: `lobby.GameCreator` gained `InitialState`,
-    and `game.Service.InitialState` builds the `notify.PlayerState` (rack re-encoded to wire indices, the
-    variant alphabet embedded for a first-seen variant).
-  - **UI:** a pure `lib/gamedelta.ts` reducer (`applyMoveDelta` / `applyGameOver` / `seedInitialState`,
-    unit-tested) advances the cache; `app.svelte` seeds it on `match_found` / `game_started`; `Game.svelte`
-    applies the delta (falling back to `load()` while composing, on a gap, or on its own move's new rack);
-    `NewGame.svelte` polls only when `app.streamAlive` is false and guards its teardown so a push-delivered
-    match is not cancelled.
-  - **notify (friends/invitations) scope:** the backend carries the full account / invitation payload on the
-    wire (per "all events → push"); the UI seeds the game cache from `game_started` but keeps its lightweight
-    **authoritative** badge refresh (`refreshNotifications`, on the rare `notify` event + on foreground) rather
-    than adding client-side friend/invitation caches — the per-move hot path is fully de-fetched, which was the
-    goal. Deeper lobby-cache consumption is an easy follow-up.
-  - **No schema change** (no migration); the contour needs no DB wipe. Tests: `notify` FB round-trips +
-    `emitMove` delta + the `gamedelta` reducer; the e2e mock now emits the enriched delta.
-
-- **R5** (interview + implementation):
-  - **No code slimming — by analysis.** A gzip measure + sourcemap attribution of the real `dist` showed
-    the app bundle is already minified + tree-shaken and dominated by the Connect/FlatBuffers transport
-    runtime + generated FB/PB bindings (≈⅔ of `main`'s source) and the Svelte runtime — all
-    third-party/generated, irreducible within R5's scope. App-authored code carries no hand-trimmable fat.
-  - **Lazy-load rejected** (screens *and* i18n): `bundle-size.mjs` sums every emitted chunk, so
-    code-splitting moves bytes between chunks for **zero total-size win** while adding request latency (+N
-    gateway fetches on first navigation to a split screen). i18n lazy-load additionally buys ≤3 KB (en-only
-    users) at the cost of an async `t()`, and `en` must stay bundled (it is the `MessageKey` type source +
-    fallback). **Chunk-collapsing rejected** too — keeping the near-static Svelte runtime in its own
-    cacheable chunk is the recommended practice (an app deploy then re-busts only `main`, not the runtime),
-    and HTTP/2 makes the extra preload request negligible.
-  - **Metric retargeted to the app.** The two-entry build (`index.html` app + `landing.html`) makes Rollup
-    hoist the code shared by both (Svelte runtime + i18n + `aboutContent`) into one preloaded chunk, so the
-    app actually loads its entry chunk **+ the shared chunk** (≈74 + ≈23 = **≈97 KB**), never `landing.js`
-    (≈1.6 KB). The old script summed all three chunks (98.8 KB), over-counting the app by `landing.js`.
-    `bundle-size.mjs` now parses each built HTML for the JS it eagerly loads and gates three parts
-    independently — **app entry ≤ 100 KB, shared (Svelte+i18n) ≤ 30 KB, landing-own ≤ 5 KB** — reporting the
-    app total (≈97) and landing total (≈24.5). Same CLI + exit-code contract, so the CI step is unchanged.
-  - **No app/source/build change** (`App.svelte`, `lib/i18n/`, `vite.config.ts` untouched); no schema
-    change, no contour wipe. The stale "~82 KB" figure was corrected in `bundle-size.mjs` and `ui/README.md`.
-
-- **R6** (interview + implementation):
-  - **Locked decisions:** apply **both** wire/code structural changes (**B** + **A**) and **only C1+C2** of
-    the test consolidation (not C3/C5); strip the `*(Stage N)*` tags from **all current-state docs**
-    (ARCHITECTURE / FUNCTIONAL+`_ru` / TESTING / UI_DESIGN), keeping PLAN.md / PRERELEASE.md / CLAUDE.md as
-    history; **split `stage6_test.go`** by domain. The `h2cMaxConcurrentStreams` sizing stays an **R7**
-    concern (tuning, not behaviour-preserving); the R2 early run forced no code fix, so nothing was carried in.
-  - **(a) De-staging:** removed the `Stage N` / `TODO-N` / `(RN)` references across code, comments, service
-    READMEs and the current-state docs, rewording narratives to present tense (no technical content lost).
-    Renamed the only stage-named identifiers (`registerStage8`→`registerSocialOps`,
-    `registerStage11`→`registerLinkOps`) and split `stage6_test.go` (`TestEmailLoginFlow`→`email_test.go`;
-    `TestGuestAutoMatchLeavesNoStats`+`provisionGuest`→`account_test.go`). De-staged the `.fbs`/`.proto`
-    comments and regenerated: only the `.proto`-derived Go docstrings (`*_grpc.pb.go`, `push.pb.go`) changed —
-    flatc strips schema comments, so the FB Go/TS bindings were untouched.
-  - **(b) Reconciliation:** the docs were accurate (each R-phase baked its own); the one drift was a stale
-    "guest-reaping deferred (TODO-3)" note in `ARCHITECTURE.md` §3 — guest reaping is implemented, so the
-    note was replaced with the current behaviour (FUNCTIONAL/TESTING already described it).
-  - **(c) B — dead `opponent_moved` scalars:** removed `seat/action/score/total` from `OpponentMovedEvent`
-    (`pkg/fbs/scrabble.fbs` + the `notify` emit + the round-trip test); regenerated FB Go + TS. No reader
-    used them (the UI codec/mock take `move`/`game`/`bag_len`; the gateway forwards the payload verbatim).
-    A pre-release wire-slot renumber — free with no prod data, no DB change.
-  - **(c) A — shared FB builders:** new `scrabble/pkg/wire` holds the single definition of the nested wire
-    tables (GameView / MoveRecord / StateView / AccountRef / Invitation) shared by the backend `notify`
-    encoder and the gateway `transcode`; both map their own source types to neutral `wire.*` structs and
-    delegate. **Honest tradeoff:** the verbose `Start/Add/End` + reverse-prepend boilerplate is now written
-    once, but the field *set* is still mapped per side, and the new package makes the change net **+~145 LOC**
-    — a single-source / anti-drift win for the fiddly mechanics rather than a line-count cut. Behaviour-
-    preserving: the two sides' field sets were verified identical and the round-trip tests pass unchanged.
-  - **(c) C1+C2 — inttest fixtures:** moved the cross-file service/game fixtures (`newGameService` was used by
-    10 files) into `backend/internal/inttest/helpers.go`; single-file helpers stay local. Pure relocation.
-  - **No schema change → no contour DB wipe.** Regression gate: the full unit + integration + UI suites plus
-    the R7 stress run.
-
-- **R7** (interview + implementation):
-  - **Locked decisions:** run the harness **same-host** (one-shot container on `scrabble-internal`, capped
-    `--cpus=3` so the contour keeps spare cores); **apply container limits + `GOMAXPROCS` now** (not just a
-    prod recommendation); **replace cAdvisor with the otelcol `docker_stats` receiver** (it resolved only the
-    root cgroup on this host); keep rate-limit / h2c knobs **compiled-in** (change values only if the data
-    demands — it did not).
-  - **Harness refinements (pre-run):** each virtual player builds its **own `edge.Client`** (its own h2c
-    connection for its Subscribe stream + Execute calls) instead of all players sharing one `http2.Transport` —
-    the R2 `transport_error` artifact; and `playTurn` now reports a **finished** game so the player drops it
-    from rotation. Effect, measured: `game.state` `transport_error` 14 % (R2) → **2.49 %**; `game_finished` on
-    chat ≈ 3 900 → **35**.
-  - **Observability:** added the `docker_stats` receiver to `otelcol` (`api_version: "1.44"` — the daemon's
-    minimum is 1.40; the receiver defaults to 1.25 and crash-looped until pinned), mounted the docker socket
-    read-only with `group_add` (the contrib image runs as UID 10001), dropped the cAdvisor service + its
-    Prometheus job, and retargeted the **Scrabble — Resources** dashboard to the docker_stats metric names
-    (`container_cpu_utilization`/100 == cores). Cross-checked against `docker stats` within sampling error.
-  - **Profile (final run, 500 players, limits in force):** the **gateway is the binding constraint** — with
-    one connection per player it bursts into its 2-core cap (the residual 2.49 % `transport_error`); backend
-    ~0.85 core and postgres ~1.4 cores had headroom; **tempo reached its 1 GiB cap**; the backend pool sat at
-    its `MaxOpenConns=25` cap (28 backends); docker logs were unbounded (~14 MiB / 30 min on the backend at
-    info). Full write-up in [`../loadtest/REPORT.md`](../loadtest/REPORT.md). *(Superseded in part: a
-    later pass modelling the `game.evaluate` hot path traced the gateway's CPU appetite to
-    **gateway→backend connection churn** — the default 2-idle-connection HTTP transport — not proxying
-    work. Pooling the connections cut peak gateway CPU ~7× (~1.75 → ~0.26 cores at 500 players) and
-    removed the ephemeral-port-exhaustion cliff behind the residual `transport_error`, so the gateway is
-    no longer the binding constraint — postgres is. The 3-core gateway cap below is now generous headroom.)*
-  - **Round-2 tuning (owner-agreed, all in `deploy/docker-compose.yml`, no code change):** gateway **2 → 3
-    cores + `GOMAXPROCS=3`**; tempo memory **1 → 2 GiB**; backend `MAX_OPEN_CONNS` **25 → 40**; a json-file
-    **log-rotation** default (10m × 3) applied contour-wide via a YAML anchor (level stays info).
-    backend/postgres kept at 2 cores / 512 MiB (headroom is cheap on the shared host).
-  - **Validation:** the same gradual ramp on the tuned contour cut `game.state` `transport_error` to **0.72 %**
-    (gateway ~2 cores, now under the 3-core cap, no throttle; tempo ~1.27 GiB, under 2 GiB). A separate
-    **burst** run (a single 100 → 500 jump) pegged the gateway at 3 cores (≈296 % sustained, 9.27 % error),
-    confirming it is **connection-CPU-bound** — a true arrival spike is a **horizontal-scaling** lever, not
-    more cores per node (recorded in the prod-sizing recommendation).
-  - **No schema change → no contour DB wipe.** Bake-back: `loadtest/REPORT.md`, `loadtest/README.md`,
-    `docs/TESTING.md`, the telemetry/observability section of `docs/ARCHITECTURE.md`, the repo-layout line in `CLAUDE.md`.
-
-- **UI — Tab-bar navigation redesign** (owner ad-hoc, not on the raw TODO list): drop the hamburger
-  `Menu.svelte` everywhere (it fought the Telegram-fullscreen layout, where it had to be re-centred).
-  - **Locked decisions (interview):** the in-Settings sub-nav is a **bottom TabBar with the active tab
-    highlighted** (icon-only); **Export GCG** moves to the left slot of the move-history header (free in a
-    finished game, where 🏁 *leave* does not apply); the lobby **⚙️ badge counts incoming friend requests
-    only** (invitations keep their own lobby section); unread chat is badged on **the score bar and the 💬**.
-  - **What shipped:** a ⚙️ **Settings hub** (`screens/SettingsHub.svelte`) over the existing
-    Settings/Profile/Friends/About bodies and an in-game **comms hub** (`game/CommsHub.svelte`) over
-    chat + dictionary, both with in-place tabs and a fixed back target; the game's menu items relocate into
-    the open move history (🏁 leave / 📤 export + 💬 comms header) and the player cards (🤝 add-friend); a
-    shared **TapConfirm** (`components/TapConfirm.svelte`, `lib/tapconfirm.ts`) — tap → fading ✅ → tap —
-    replaces the Skip/Hint press-and-hold popovers and drives the add-friend confirm. Fixed the move-history
-    "jump" bug (the slid board is now inert and the stage can't scroll, so a swipe up genuinely closes it).
-    `Menu.svelte` + `HoldConfirm.svelte` removed.
-  - **No schema/wire change → no contour DB wipe.** Bake-back: `docs/UI_DESIGN.md`, `docs/FUNCTIONAL.md`
-    (+`_ru`). Regression gate: UI `check` + unit (`tapconfirm`) + build + bundle budget + e2e (Chromium &
-    WebKit), all green.
-
-- **UI — Merge Exchange/Pass; drop the dead Tournaments tab** (owner ad-hoc, not on the raw TODO
-  list): the lobby's 🏆 *Tournaments* tab was an inert `lobby.soon` toast — removed (the lobby is back
-  to three tabs, matching `docs/FUNCTIONAL.md`). In-game the separate 🥺 *Skip* (pass) tab folds into
-  the 🔄 tab, now **Exchange/Pass**, whose dialog passes when no tile is selected and exchanges when
-  tiles are.
-  - **Decision — a pass is NOT an exchange of zero (verified against the rules + GCG):** the merge is
-    **UI-only**. Pass and exchange stay distinct game actions end-to-end — wire (`GameActionRequest` vs
-    `ExchangeRequest`), engine (`ActionPass` vs `ActionExchange`), and the GCG Poslfit dialect (a pass is
-    a bare `-`, an exchange is `-TILES`). The engine forbids a zero-tile exchange (`ErrNothingToExchange`)
-    and allows an exchange only with a full rack left in the bag (`ErrNotEnoughTilesToExchange`), while a
-    pass is always legal — collapsing them would lose a real distinction. The dialog dispatches the
-    existing `gateway.pass` / `gateway.exchange`.
-  - **What shipped:** `Lobby.svelte` (tab removed); `Game.svelte` (one 🔄 Exchange/Pass tab no longer
-    gated on an empty bag; the dialog disables tile selection while the bag is below a full rack
-    (`bagLen >= RACK_SIZE`), its confirm button reading **Pass without exchanging** / **Exchange N**);
-    i18n (`game.draw` → Exchange/Pass, new `game.passNoExchange`, dropped `game.skip` /
-    `lobby.tournaments` / `lobby.soon`). No backend/wire/history/GCG change.
-  - **No schema/wire change → no contour DB wipe.** Bake-back: `docs/UI_DESIGN.md`, `docs/FUNCTIONAL.md`
-    (+`_ru`). Regression gate: UI `check` + unit + build + bundle budget + e2e (Chromium & WebKit).
-
-- **AI — Honest AI opponent in quick game** (owner ad-hoc, not on the raw TODO list): a second quick-game
-  opponent the player *knowingly* chooses, distinct from the disguised robot of the random/open path
-  (which is kept as-is). New Game's quick-game mode replaces the "auto-match" subtitle with a two-button
-  selector **🤖 AI / 👤 Random player** (the `.seg`/`.opt` segmented style, AI the default); for AI the
-  move-clock line reads "Loss after 7 days of inactivity" and the "searching" hint is hidden.
-  - **Locked decisions (interview):** AI move is **event-driven** (the robot replies the instant the
-    player's move commits; the 30 s driver is the fallback); AI games **do not touch `account_stats`**
-    (practice, like guests); the **Stage 5 strength logic is reused unchanged** (`playToWin` 40 % from the
-    seed + margin band); **no per-move timeout — a 7-day inactivity loss** instead; the 7-day line lives on
-    the New Game screen (the in-game screen has no move-clock line); chat + nudge **disabled**, word-check
-    kept, add-friend never drawn, opponent shown as **🤖** everywhere.
-  - **The 7-day rule reuses the existing per-turn timeout:** an AI game is created with
-    `turn_timeout_secs = AIInactivityTimeout` (7 days) and the existing timeout sweeper resigns the overdue
-    seat — since the robot moves at once, only the human is ever on the clock, so the per-turn timeout *is*
-    the abandon rule (no new column, no new sweeper).
-  - **One game flag drives everything:** `games.vs_ai` (edited into the R1 baseline — pre-release, so a
-    contour DB wipe after merge). It is set **only** on AI-started games, so a robot-filled random game keeps
-    `vs_ai=false` and the disguised opponent is never revealed; the UI derives 🤖 / the gates **from the flag,
-    never from the opponent account**. New backend path `Matchmaker.StartVsAI` (picks a pooled robot via the
-    existing `Pick`, creates an **active** seated game via `game.Service.Create`, random seat order) — the AI
-    request never enters the open pool, so the open-game reaper never touches it. The robot driver gains a
-    `vs_ai` branch (no sleep, no proactive nudge, zero delay) and a focused `DriveGame`/`TriggerMove` fast
-    path wired from the game service's after-create/after-commit hook (`SetAITrigger`, a func value so the
-    game package never imports the robot package). Chat/nudge gated by a new `social` `VsAI` check
-    (`ErrGameVsAI` → 409 `ai_game`); statistics skipped in `commit` when `vs_ai`.
-  - **Wire:** `EnqueueRequest` += `vs_ai`, `GameView` += `vs_ai` (trailing FB fields, regenerated Go + TS),
-    threaded through the backend DTO, the gateway transcode and the `pkg/wire` + `notify` builders.
-  - **Tests:** `lobby` unit (StartVsAI seats a robot + flags the game; empty pool leaves no game); backend
-    integration (`ai_game_test.go`: active+seated+vs_ai+7-day clock, robot moves immediately, stats skipped,
-    7-day timeout resigns the human, chat/nudge rejected); UI codec round-trip (`vs_ai` on enqueue + game
-    view); e2e (an AI game shows 🤖, no "searching", chat disabled, the dictionary still works) + the
-    existing quick-match e2e updated to pick **Random player** (the default is now AI).
-  - **Schema/wire change → a contour DB wipe** after merge (`DROP SCHEMA backend CASCADE` + restart, the
-    R1/R3 pattern). Bake-back: `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (+`_ru`), `docs/UI_DESIGN.md`,
-    `backend/README.md`, Go Doc comments.
-  - **Post-review refinements (owner, same PR):** (1) the **GCG export labels the robot seat "AI"** rather
-    than its human-like pool name (`ExportGCG` overrides the name via `accounts.IsRobot`; the in-app 🤖 is
-    unchanged); (2) honest-AI games **emit no `your_turn`** — the robot replies instantly, so the signal
-    would arrive with the move and be pointless; `opponent_moved` still advances the UI; (3) the **admin
-    console surfaces the AI flag** — a **🤖 column** in `/games` and an "AI game" line on the game card
-    (`GameRow`/`GameDetailView` gain `VsAI`); (4) `games_started_total` / `games_abandoned_total` gain a
-    **`vs_ai`** attribute and the Grafana *Game domain* dashboard splits started/abandoned into **human**
-    and **AI** panels.
-  - **Follow-up (separate PR — strategy deviation):** the robot now plays **≈20%** of opening/midgame moves
-    *against* its per-game `playToWin` intent (toward the opposite margin band — a winning robot eases off, a
-    losing one surges ahead), tapering linearly to **0 over the last 14 bag tiles** and **0 once the bag is
-    empty**, so the endgame follows the chosen strategy strictly while earlier outcomes can swing the human's
-    way. Deterministic from the seed (`mix(seed,"deviate",moveCount)`), applied to **both** robot paths via
-    the shared `selectMove`; the per-game intent (and the admin card) is unchanged. Tests: `robot` unit
-    (taper bounds + monotonicity, never-in-endgame, determinism, ~20% distribution). Bake-back:
-    `docs/ARCHITECTURE.md` §7, `docs/FUNCTIONAL.md` (+`_ru`), `backend/README.md`, `PLAN.md` Stage 5.
-
-- **GL — Simultaneous quick-game cap** (owner ad-hoc, not on the raw TODO list): a player may hold at
-  most **10** active quick games; at the cap the lobby greys **New Game** and shows a plain notice
-  "Вы достигли лимита одновременных партий", both clearing automatically when an active game finishes.
-  - **Locked decisions (interview):** what counts = active **+** open (searching) quick games, **including
-    AI** (`vs_ai`); friend games (invitation-linked) **never** count. The backend gate refuses **all** new-game
-    creation at the cap — `lobby/enqueue` **and** `invitations` — with **409 `game_limit_reached`**; **accepting**
-    an invitation is never gated, so friend games are capped "from the other end". Delivery = a boolean
-    **`at_game_limit`** on the existing `games.list` (no per-event payload: a turn change does not move the count,
-    and the lobby already re-fetches `games.list` on entry + every game event); the first uncached lobby frame
-    defaults the button **enabled** (the backend gate is the authority).
-  - **What shipped:** `game.MaxActiveQuickGames` + `Store/Service.CountActiveQuickGames` (active/open seats, no
-    `game_invitations` row; hidden games still count → a dedicated count, not a filter over the lobby list);
-    `Server.atGameLimit`/`ensureUnderGameLimit` gating `handleEnqueue` + `handleCreateInvitation`;
-    `gameListDTO.at_game_limit`; the FB `GameList` trailing `at_game_limit` (regenerated Go + TS) threaded through
-    the gateway transcode + UI codec; `lib/model` + `lobbycache` snapshot + `Lobby.svelte` (disabled tab + a muted
-    `.limit` notice); i18n `lobby.limitReached` (en authoritative + ru).
-  - **Caveat (logged):** the gate is a pre-check, not transaction-atomic — concurrent creates from one account could
-    momentarily exceed by 1–2 (harmless soft cap; the UI disables the button regardless). Strict atomicity was judged
-    a disproportionate diff across the two create paths.
-  - **No schema change → no contour DB wipe** (only a trailing FB field, no migration). Tests: backend integration
-    (`game_limit_test.go`: count rule + HTTP gate 409 + accept bypass), server unit (error mapping), gateway
-    transcode round-trip, UI codec + lobbycache unit, e2e (`gamelimit.spec.ts`). Bake-back: `docs/FUNCTIONAL.md`
-    (+`_ru`), `docs/ARCHITECTURE.md` §8, `docs/UI_DESIGN.md`, `backend/README.md`.
-
-- **CM — Channel-chat moderation + promo bot** (owner ad-hoc, not on the raw TODO list):
-  - **Locked decisions (interview):** the promo bot is a **goroutine in `cmd/bot`** (its own token, no
-    bot-link); the moderated chat's default-no-send is configured by a **human** in the group settings (the
-    bot only grants, never `setChatPermissions`); a non-eligible joiner is **left muted silently**; a
-    temporary-suspension expiry is handled by a **backend sweeper** that emits the re-evaluate event; and a new
-    **`chat_muted` role** is a chat-only mute with the **game suspension dominating**
-    (`eligible = registered AND NOT suspended AND NOT chat_muted`).
-  - **Bot API reality (verified against the docs):** a cross-bot Mini App launch must be a **URL button** to the
-    main bot's `t.me/<bot>?startapp` link — a `web_app` button signs initData with the *sending* bot's token,
-    which the main validator rejects — so the promo button reuses the UI's `VITE_TELEGRAM_LINK`. `chat_member`
-    updates arrive **only** when the bot is a chat **admin** with the "Ban users" right (the client label for the
-    Bot API `can_restrict_members`) and `chat_member` is in `allowed_updates`; bots cannot list members but can
-    `getChatMember` a single user, which is the membership guard on the block/unblock path.
-  - **Wire:** `pkg/proto/botlink/v1` gains a `ChatGateCommand` in the `Command` oneof and a unary
-    `ResolveChatEligibility`; the backend gains `notify.KindChatAccessChanged` (no payload, infra-only — never an
-    out-of-app message) and an internal `POST /api/v1/internal/chat-access` resolver; the gateway resolves the
-    join (by external_id) and the event (by user_id) through it and pushes the chat-gate command fire-and-forget
-    (at-most-once, recovered by the next moderation action or a re-join).
-  - **No schema change → no contour DB wipe:** `chat_muted` is a new `account.KnownRoles` entry (the
-    `account_roles` table is data-driven). The suspension-expiry sweeper is a new `account.SuspensionSweeper`
-    (a 1-minute window, idempotent) started in `cmd/backend`, alongside the guest reaper.
-  - **Deploy:** new `TEST_`/`PROD_` `TELEGRAM_PROMO_BOT_TOKEN` (secret), `TELEGRAM_BOT_USERNAME` and
-    `TELEGRAM_CHAT_ID` (variables); the promo link reuses the existing `*_VITE_TELEGRAM_LINK` variable as
-    `TELEGRAM_BOT_LINK`. The bot must be promoted to admin in the real discussion group, and the group default
-    set to no-send, as part of the Stage 18 prod cutover (the test contour exercises the code path).
-  - **Bake-back:** `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (+`_ru`), `platform/telegram/README.md`,
-    `backend/README.md`, Go Doc comments. Tests: backend resolver truth table + publish on block/unblock/role +
-    the sweeper window (unit + integration); gateway hub `ResolveChatEligibility` + the chat-gate command; bot
-    `chat_member` grant + `ApplyChatGate` getChatMember-guard; promo `/start` localization + URL button; config
-    parsing.
-  - **Post-contour-test fixes (same PR):** a live test drove three corrections. (1) **Strategy
-    inversion (the key one)** — the original "group default no-send, bot grants the eligible" cannot
-    work: Telegram intersects the chat default with each user's permission, so a per-user grant never
-    exceeds a deny-by-default group (the bot set `can_send=true` yet the user still could not write).
-    The group now **allows sending by default** and the bot only **restricts** — it mutes an ineligible
-    member (unregistered / admin-suspended / `chat_muted`) and un-mutes an eligible one it had muted,
-    acting only when the current state differs (idempotent; the bot's own change is skipped by matching
-    the actor id to the bot). A present member in a default-allow group can appear as `restricted` with
-    `is_member`, so the gate reads both. (2) **Join-before-register** — a user who joins before
-    registering is covered by no `chat_member` event, so `ProvisionTelegram` now reports first contact
-    and the Telegram auth handler emits `chat_access_changed` on it. (3) **Observability** — a startup
-    self-check logs whether the bot is an admin-with-restrict in the chat (it caught a misconfigured
-    `TELEGRAM_CHAT_ID` set to a channel id, not the discussion-group id); the per-event trace is at
-    Debug, the actual mute/unmute and warnings at Info.

README.md

@@ -22,9 +22,8 @@ supports English Scrabble, Russian Scrabble and Эрудит.
   security, cross-service contracts.
 - [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md) (+ [`_ru`](docs/FUNCTIONAL_ru.md)) —
   per-domain user stories.
-- [`docs/TESTING.md`](docs/TESTING.md) — test layers and the per-stage CI gate.
+- [`docs/TESTING.md`](docs/TESTING.md) — test layers and the CI gate.
-- [`PLAN.md`](PLAN.md) — the staged implementation plan and stage tracker.
+- [`CLAUDE.md`](CLAUDE.md) — project guide and development workflow.
-- [`CLAUDE.md`](CLAUDE.md) — project guide and the mandatory per-stage workflow.
 
 ## Build & test
 
@@ -90,7 +89,7 @@ observability stack (OTel Collector → Prometheus + Tempo → Grafana) + a fron
 services build from multi-stage distroless `*/Dockerfile`.
 
 ```sh
-docker build -f backend/Dockerfile -t scrabble-backend .   # pulls the DAWG release artifact
+docker build --build-arg DICT_VERSION=v1.3.0 -f backend/Dockerfile -t scrabble-backend .  # DICT_VERSION required; pulls that DAWG release artifact
 docker build -f gateway/Dockerfile -t scrabble-gateway .   # node stage builds + embeds the UI
 docker compose -f deploy/docker-compose.yml config         # validate (needs the TEST_/PROD_ env)
 ```

backend/Dockerfile

@@ -7,12 +7,14 @@
 # (GOPRIVATE), so the build stage needs git and network.
 #
 # Build from the repository root so go.work, go.work.sum, pkg/ and backend/ are all
-# in the Docker context:
+# in the Docker context. DICT_VERSION has no default — the caller supplies the
-#   docker build -f backend/Dockerfile -t scrabble-backend .
+# scrabble-dictionary release tag (compose/CI pass it; see deploy/README.md
+# "Bumping the dictionary version"):
+#   docker build --build-arg DICT_VERSION=v1.3.0 -f backend/Dockerfile -t scrabble-backend .
 
 # --- dictionary artifact -----------------------------------------------------
 FROM alpine:3.20 AS dawg
-ARG DICT_VERSION=v1.2.1
+ARG DICT_VERSION
 RUN apk add --no-cache curl tar
 RUN mkdir -p /dawg \
  && curl -fsSL -o /tmp/dawg.tar.gz \
@@ -42,7 +44,7 @@ FROM gcr.io/distroless/static-debian12:nonroot
 # Re-declare the build arg in this stage so it labels the seed dictionary. One
 # DICT_VERSION drives both the artifact the dawg stage downloads and the version
 # label the binary pins, so the resident version equals the release tag.
-ARG DICT_VERSION=v1.2.1
+ARG DICT_VERSION
 COPY --from=build /out/backend /usr/local/bin/backend
 # Own the seed dictionary as the nonroot runtime user (UID 65532): a named volume
 # mounted at /opt/dawg inherits this ownership on first use, so the admin console

backend/README.md

@@ -228,7 +228,7 @@ internal/banview/    # gateway active-ban mirror: the console's Active IP bans p
 ```sh
 docker run -d --name scrabble-pg -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:17-alpine
 # DAWGs: extract the dictionary release artifact (or point at a local scrabble-solver/dawg):
-mkdir -p /tmp/dawg && curl -fsSL https://gitea.iliadenisov.ru/developer/scrabble-dictionary/releases/download/v1.2.1/scrabble-dawg-v1.2.1.tar.gz | tar xz -C /tmp/dawg
+mkdir -p /tmp/dawg && curl -fsSL https://gitea.iliadenisov.ru/developer/scrabble-dictionary/releases/download/v1.3.0/scrabble-dawg-v1.3.0.tar.gz | tar xz -C /tmp/dawg
 BACKEND_POSTGRES_DSN='postgres://postgres:dev@localhost:5432/postgres?search_path=backend&sslmode=disable' \
   BACKEND_DICT_DIR=/tmp/dawg \
   GOPRIVATE='gitea.iliadenisov.ru/*' \

backend/cmd/backend/main.go

@@ -3,8 +3,8 @@
 // loads the dictionaries into the engine registry, warms the session cache,
 // constructs the game domain and starts its turn-timeout sweeper, constructs the
 // lobby and social domains, then serves the HTTP listener with the infrastructure
-// probes and the /api/v1 route-group skeleton. Domain HTTP endpoints are added
+// probes and the /api/v1 route group, behind which the domains expose their HTTP
-// with the gateway in a later stage described in PLAN.md.
+// endpoints to the gateway.
 package main
 
 import (

backend/internal/account/account.go

@@ -119,6 +119,16 @@ func (s *Store) ProvisionByIdentity(ctx context.Context, kind, externalID string
 	return s.provision(ctx, kind, externalID, provisionSeed{})
 }
 
+// ProvisionEmail returns the account owning the email identity externalID, creating
+// it (unconfirmed) on first contact with browserTZ — the client's detected "±HH:MM"
+// UTC offset — seeded into its time zone. Like ProvisionByIdentity it is race-safe
+// and leaves an existing account untouched, so a returning user's saved zone is never
+// overwritten. The email account is created here (the code-request step), not at the
+// later login, so this is where its zone is seeded.
+func (s *Store) ProvisionEmail(ctx context.Context, externalID, browserTZ string) (Account, error) {
+	return s.provision(ctx, KindEmail, externalID, provisionSeed{timeZone: seedZone(browserTZ)})
+}
+
 // ProvisionRobot provisions (or finds) the durable account backing a robot pool
 // member: a KindRobot identity carrying displayName, with chat blocked but friend
 // requests NOT blocked — a request to a robot is accepted as pending and, since the
@@ -160,7 +170,7 @@ func (s *Store) ProvisionRobot(ctx context.Context, externalID, displayName stri
 // is never overwritten. The created flag lets the auth handler re-evaluate moderated-
 // chat write access on first registration — the path of a user who joined the chat
 // before registering, whom no chat_member event covers.
-func (s *Store) ProvisionTelegram(ctx context.Context, externalID, languageCode, username, firstName string) (Account, bool, error) {
+func (s *Store) ProvisionTelegram(ctx context.Context, externalID, languageCode, username, firstName, browserTZ string) (Account, bool, error) {
 	// Pre-check whether the identity already exists so the caller can act on first
 	// contact. A race with a concurrent create only over- or under-reports created for
 	// that one call, which the idempotent chat-access re-evaluation tolerates.
@@ -169,7 +179,9 @@ func (s *Store) ProvisionTelegram(ctx context.Context, externalID, languageCode,
 	if err != nil && !created {
 		return Account{}, false, err
 	}
-	acc, err := s.provision(ctx, KindTelegram, externalID, telegramSeed(languageCode, username, firstName))
+	seed := telegramSeed(languageCode, username, firstName)
+	seed.timeZone = seedZone(browserTZ)
+	acc, err := s.provision(ctx, KindTelegram, externalID, seed)
 	return acc, created, err
 }
 
@@ -197,20 +209,33 @@ func (s *Store) provision(ctx context.Context, kind, externalID string, seed pro
 }
 
 // provisionSeed carries the optional create-time profile seed for a brand-new
-// account (Telegram first contact). Empty fields fall back to the accounts table
+// account (first contact). Empty fields fall back to the accounts table defaults,
-// defaults, so an unknown language keeps the 'en' default and an empty name keeps
+// so an unknown language keeps the 'en' default, an empty name keeps the ” default
-// the ” default.
+// and an empty time zone keeps the 'UTC' default.
 type provisionSeed struct {
 	preferredLanguage string
 	displayName       string
+	timeZone          string
+}
+
+// seedZone returns browserTZ when it is a well-formed zone to persist at account
+// creation (a "±HH:MM" offset or a loadable IANA name), else "" so the new account
+// falls back to the accounts table's 'UTC' default. The client reports the device's
+// detected offset deterministically; a bad value is dropped rather than guessed at.
+func seedZone(browserTZ string) string {
+	if validZone(browserTZ) {
+		return browserTZ
+	}
+	return ""
 }
 
 // telegramSeed derives the create-time seed from Telegram launch fields: a
 // supported preferred language from languageCode (an ISO-639 code, possibly
-// region-tagged like "ru-RU"), and a display name sanitized from firstName or,
+// region-tagged like "ru-RU"), and a display name. The name precedence is the real
-// failing that, username (sanitizeDisplayName strips disallowed characters to the
+// name (firstName, sanitized to the editable format) → the @username taken verbatim
-// editable format). When neither yields any letters, it falls back to a generated
+// (already a valid handle, only trimmed and length-capped, never character-stripped)
-// placeholder in the seeded language (placeholderDisplayName).
+// → a generated placeholder in the seeded language (placeholderDisplayName), reached
+// only when firstName has no usable letters and no username is set.
 func telegramSeed(languageCode, username, firstName string) provisionSeed {
 	var seed provisionSeed
 	if lang, _, _ := strings.Cut(strings.ToLower(strings.TrimSpace(languageCode)), "-"); lang == "en" || lang == "ru" {
@@ -218,7 +243,13 @@ func telegramSeed(languageCode, username, firstName string) provisionSeed {
 	}
 	name := sanitizeDisplayName(firstName)
 	if name == "" {
-		name = sanitizeDisplayName(username)
+		// The real name yielded nothing usable: fall back to the @username verbatim
+		// (Telegram guarantees a valid handle), only trimmed and capped to the column
+		// width — never character-stripped like the real name.
+		name = strings.TrimSpace(username)
+		if r := []rune(name); len(r) > maxDisplayName {
+			name = strings.TrimRight(string(r[:maxDisplayName]), " ")
+		}
 	}
 	if name == "" {
 		name = placeholderDisplayName(seed.preferredLanguage)
@@ -361,16 +392,22 @@ func (s *Store) create(ctx context.Context, kind, externalID string, seed provis
 
 	var created Account
 	err = withTx(ctx, s.db, func(tx *sql.Tx) error {
-		// Seed the new row's display name and language (Telegram first contact); an
+		// Seed the new row's display name, language and time zone (first contact); an
-		// empty seed reproduces the table defaults ('' and 'en') the other callers
+		// empty seed reproduces the table defaults ('', 'en' and 'UTC') the other callers
-		// relied on, so their behaviour is unchanged.
+		// relied on, so their behaviour is unchanged. time_zone is written explicitly (the
+		// detected offset, or 'UTC' equal to the column default) so a seeded zone lands at
+		// creation while an unseeded one stays UTC.
 		lang := seed.preferredLanguage
 		if lang == "" {
 			lang = "en"
 		}
+		tz := seed.timeZone
+		if tz == "" {
+			tz = "UTC"
+		}
 		insertAccount := table.Accounts.
-			INSERT(table.Accounts.AccountID, table.Accounts.DisplayName, table.Accounts.PreferredLanguage).
+			INSERT(table.Accounts.AccountID, table.Accounts.DisplayName, table.Accounts.PreferredLanguage, table.Accounts.TimeZone).
-			VALUES(accountID, seed.displayName, lang).
+			VALUES(accountID, seed.displayName, lang, tz).
 			RETURNING(table.Accounts.AllColumns)
 
 		var row model.Accounts
@@ -409,15 +446,21 @@ const guestDisplayName = "Guest"
 // ProvisionGuest creates a fresh ephemeral guest account: a durable row carrying
 // no identity, flagged is_guest, so it can hold a session and a game seat (both
 // foreign-key the accounts table) while being excluded from statistics, friends
-// and history. Guests are not reused — each bootstrap mints a new account.
+// and history. Guests are not reused — each bootstrap mints a new account. browserTZ
-func (s *Store) ProvisionGuest(ctx context.Context) (Account, error) {
+// (the client's detected "±HH:MM" UTC offset) seeds the guest's time zone, falling
+// back to the 'UTC' default when empty or malformed.
+func (s *Store) ProvisionGuest(ctx context.Context, browserTZ string) (Account, error) {
 	accountID, err := uuid.NewV7()
 	if err != nil {
 		return Account{}, fmt.Errorf("account: new guest id: %w", err)
 	}
+	tz := seedZone(browserTZ)
+	if tz == "" {
+		tz = "UTC"
+	}
 	stmt := table.Accounts.
-		INSERT(table.Accounts.AccountID, table.Accounts.DisplayName, table.Accounts.IsGuest).
+		INSERT(table.Accounts.AccountID, table.Accounts.DisplayName, table.Accounts.IsGuest, table.Accounts.TimeZone).
-		VALUES(accountID, guestDisplayName, true).
+		VALUES(accountID, guestDisplayName, true, tz).
 		RETURNING(table.Accounts.AllColumns)
 
 	var row model.Accounts

backend/internal/account/email.go

@@ -131,13 +131,15 @@ func (s *EmailService) ConfirmCode(ctx context.Context, accountID uuid.UUID, ema
 // the unauthenticated email-login entry point and, unlike RequestCode,
 // does not refuse an already-confirmed email — that is the ordinary returning-user
 // login. The code is mailed to the address, so only its real owner can complete
-// the login. It returns the target account id for the subsequent LoginWithCode.
+// the login. On first contact browserTZ (the client's detected "±HH:MM" UTC offset)
-func (s *EmailService) RequestLoginCode(ctx context.Context, email string) (uuid.UUID, error) {
+// seeds the new account's time zone. It returns the target account id for the
+// subsequent LoginWithCode.
+func (s *EmailService) RequestLoginCode(ctx context.Context, email, browserTZ string) (uuid.UUID, error) {
 	addr, err := normalizeEmail(email)
 	if err != nil {
 		return uuid.UUID{}, err
 	}
-	acc, err := s.store.ProvisionByIdentity(ctx, KindEmail, addr)
+	acc, err := s.store.ProvisionEmail(ctx, addr, browserTZ)
 	if err != nil {
 		return uuid.UUID{}, err
 	}

backend/internal/account/profile.go

@@ -101,6 +101,66 @@ func validateVariantPreferences(prefs []string) ([]string, error) {
 	return out, nil
 }
 
+// variantSeedPrefix marks a Telegram start-param payload that seeds a brand-new
+// account's variant preferences (e.g. "verudit_ru-scrabble_en"): the prefix, then the
+// canonical variant labels joined by "-". It is deliberately distinct from the routing
+// deep links (g/i/f; see platform/telegram .../deeplink) so the client's start-param
+// router falls through to the lobby for it.
+const variantSeedPrefix = "v"
+
+// SeedVariantsFromStartParam decodes a promo deep-link start-param into the variant
+// preference set to seed onto a brand-new account: the variantSeedPrefix followed by
+// the canonical variant labels joined by "-" (e.g. "verudit_ru-scrabble_en"). It
+// returns nil for any payload that is not a variant-seed link or that fails validation
+// against the known variants, so a malformed, empty or unrelated start-param simply
+// leaves the account on its default preferences rather than failing the login.
+func SeedVariantsFromStartParam(startParam string) []string {
+	if !strings.HasPrefix(startParam, variantSeedPrefix) {
+		return nil
+	}
+	body := strings.TrimPrefix(startParam, variantSeedPrefix)
+	if body == "" {
+		return nil
+	}
+	prefs, err := validateVariantPreferences(strings.Split(body, "-"))
+	if err != nil {
+		return nil
+	}
+	return prefs
+}
+
+// SetVariantPreferences overwrites only the variant-preference set of the account,
+// cleaning it to a deduplicated, canonically ordered subset of the known variants
+// (rejecting an empty or unknown set with ErrInvalidProfile) and bumping updated_at; it
+// reports ErrNotFound when no account matches id. It is the narrow counterpart to
+// UpdateProfile used to seed a promo-onboarded account's variants at first contact
+// without disturbing its other profile fields.
+func (s *Store) SetVariantPreferences(ctx context.Context, id uuid.UUID, prefs []string) (Account, error) {
+	clean, err := validateVariantPreferences(prefs)
+	if err != nil {
+		return Account{}, err
+	}
+	stmt := table.Accounts.UPDATE(
+		table.Accounts.VariantPreferences, table.Accounts.UpdatedAt,
+	).SET(
+		// clean is validated against the closed knownVariants set; bind as a text[]
+		// parameter (lib/pq encodes the array, the cast pins the column type), mirroring
+		// UpdateProfile.
+		postgres.Raw("#variant_prefs::text[]", map[string]interface{}{"#variant_prefs": pq.StringArray(clean)}),
+		postgres.TimestampzT(time.Now().UTC()),
+	).WHERE(table.Accounts.AccountID.EQ(postgres.UUID(id))).
+		RETURNING(table.Accounts.AllColumns)
+
+	var row model.Accounts
+	if err := stmt.QueryContext(ctx, s.db, &row); err != nil {
+		if errors.Is(err, qrm.ErrNoRows) {
+			return Account{}, ErrNotFound
+		}
+		return Account{}, fmt.Errorf("account: set variant preferences %s: %w", id, err)
+	}
+	return modelToAccount(row), nil
+}
+
 // UpdateProfile validates and overwrites the editable fields of the account, then
 // returns the stored row. It reports ErrInvalidProfile for a bad language,
 // timezone or display name and ErrNotFound when no account matches id.

backend/internal/account/provision_test.go

@@ -9,8 +9,9 @@ import (
 
 // TestTelegramSeed covers the pure mapping from Telegram launch fields to the
 // create-time account seed: supported-language detection (bare and region-tagged),
-// the first-name / username display-name precedence, and the sanitization that
+// the real-name → @username (verbatim) → placeholder display-name precedence, and
-// strips disallowed characters (emoji, digits, punctuation) to the editable format.
+// the sanitization of the real name (emoji, digits, punctuation stripped to the
+// editable format). The username, when used, is kept verbatim.
 func TestTelegramSeed(t *testing.T) {
 	cases := map[string]struct {
 		languageCode, username, firstName string
@@ -28,6 +29,7 @@ func TestTelegramSeed(t *testing.T) {
 		"punct to space":      {"en", "user", "John❤Doe", "en", "John Doe"},
 		"digits dropped":      {"ru", "user", "Маша123", "ru", "Маша"},
 		"garbage to username": {"en", "good", "123!@#", "en", "good"},
+		"username verbatim":   {"en", "co_ol99", "🎮🎮", "en", "co_ol99"},
 	}
 	for name, tc := range cases {
 		t.Run(name, func(t *testing.T) {
@@ -52,7 +54,7 @@ func TestTelegramSeedPlaceholder(t *testing.T) {
 		"en empty":                  {"en", "", "", `^Player-\d{5}$`},
 		"ru empty":                  {"ru", "", "", `^Игрок-\d{5}$`},
 		"default en":                {"fr", "", "", `^Player-\d{5}$`},
-		"both garbage": {"ru", "123", "!!!", `^Игрок-\d{5}$`},
+		"name garbage, no username": {"ru", "", "!!!", `^Игрок-\d{5}$`},
 	}
 	for name, tc := range cases {
 		t.Run(name, func(t *testing.T) {

backend/internal/account/variant_seed_test.go

@@ -0,0 +1,37 @@
+package account
+
+import (
+	"slices"
+	"testing"
+)
+
+// TestSeedVariantsFromStartParam covers decoding a promo deep-link start-param into the
+// variant-preference set to seed: a valid "v"-prefixed, "-"-joined label list is cleaned
+// to the canonical order and deduplicated, while anything that is not a variant-seed link
+// or that names an unknown variant yields nil (leaving the account on its defaults).
+func TestSeedVariantsFromStartParam(t *testing.T) {
+	tests := []struct {
+		name  string
+		param string
+		want  []string
+	}{
+		{"english promo", "verudit_ru-scrabble_en", []string{"erudit_ru", "scrabble_en"}},
+		{"single variant", "vscrabble_en", []string{"scrabble_en"}},
+		{"canonical order regardless of payload order", "vscrabble_en-erudit_ru", []string{"erudit_ru", "scrabble_en"}},
+		{"deduplicated", "verudit_ru-erudit_ru", []string{"erudit_ru"}},
+		{"empty", "", nil},
+		{"prefix only", "v", nil},
+		{"routing game link is not a seed", "g0190abcd", nil},
+		{"friend code link is not a seed", "f123456", nil},
+		{"unknown variant rejected", "vscrabble_de", nil},
+		{"one unknown label rejects the whole set", "verudit_ru-scrabble_de", nil},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := SeedVariantsFromStartParam(tc.param)
+			if !slices.Equal(got, tc.want) {
+				t.Errorf("SeedVariantsFromStartParam(%q) = %v, want %v", tc.param, got, tc.want)
+			}
+		})
+	}
+}

backend/internal/adminconsole/templates/pages/feedback_detail.gohtml

@@ -7,8 +7,9 @@
 <li><b>From</b> <a href="/_gm/users/{{.AccountID}}">{{.SenderName}}</a> ({{.Source}})</li>
 <li><b>Channel</b> {{.Channel}}</li>
 <li><b>Interface language</b> {{.InterfaceLanguage}}</li>
+<li><b>App version</b> {{if .Version}}<code>{{.Version}}</code>{{else}}<span class="note">unknown</span>{{end}}</li>
 <li><b>IP</b> {{if .IP}}<code>{{.IP}}</code>{{else}}<span class="note">none</span>{{end}}</li>
-<li><b>Filed</b> {{.CreatedAt}}</li>
+<li><b>Filed</b> {{.CreatedAt}} UTC &middot; browser {{if .CreatedAtBrowser}}{{.CreatedAtBrowser}} ({{.BrowserTZ}}){{else}}<span class="note">N/A</span>{{end}} &middot; user {{if .CreatedAtUser}}{{.CreatedAtUser}} ({{.UserTZ}}){{else}}<span class="note">N/A</span>{{end}}</li>
 <li><b>State</b> {{if .Archived}}archived{{else if .Read}}read{{else}}<span class="warn">unread</span>{{end}}</li>
 {{if .Banned}}<li><b>Feedback</b> <span class="warn">sender is banned from feedback</span></li>{{end}}
 </ul>

backend/internal/adminconsole/views.go

@@ -554,5 +554,17 @@ type FeedbackDetailView struct {
 	ReplyBody         string
 	RepliedAt         string
 	CreatedAt         string
+	// Version is the client app build the report was sent from (empty for rows that predate it).
+	Version string
+	// The Filed time is shown in three zones so the operator can tell what is certainly known from
+	// what is merely defaulted. CreatedAt is the authoritative UTC time. CreatedAtBrowser is that
+	// instant in the client's UTC offset detected at submit (BrowserTZ its "±HH:MM" label), empty
+	// when the client reported none (an older build). CreatedAtUser is that instant in the sender's
+	// saved profile zone (UserTZ its label), empty when the account has no zone beyond the UTC
+	// default — the template then shows "N/A" so the missing datum is explicit.
+	CreatedAtBrowser string
+	BrowserTZ        string
+	CreatedAtUser    string
+	UserTZ           string
 	Banned           bool
 }

backend/internal/engine/decode.go

@@ -21,7 +21,7 @@ const (
 	// ActionResign abandons the game.
 	ActionResign
 	// ActionTimeout is the auto-resignation a missed turn becomes; recorded by
-	// the game domain in a later stage, never produced by the engine itself.
+	// the game domain, never produced by the engine itself.
 	ActionTimeout
 )
 

backend/internal/engine/engine.go

@@ -10,7 +10,7 @@
 // characters (see decode.go and docs/ARCHITECTURE.md §9.1), so archived games
 // replay independently of any dictionary. Second, the engine owns rules and
 // scoring only: turn scheduling, the 24-hour timeout, persistence and transport
-// belong to the game domain in a later stage.
+// belong to the game domain.
 package engine
 
 import (

backend/internal/engine/registry.go

@@ -31,7 +31,7 @@ type entry struct {
 // Registry holds the dictionaries resident in memory, addressed by variant and
 // dictionary version, and the solvers built over them. Several versions of a
 // variant may be resident at once; a game pins the version it started on. The
-// admin reload flow (a later stage) registers a new version through Load.
+// admin reload flow registers a new version through Load.
 // Registry is safe for concurrent use.
 type Registry struct {
 	mu      sync.RWMutex

backend/internal/feedback/service.go

@@ -72,7 +72,7 @@ func (svc *Service) SetNotifier(p notify.Publisher) {
 // validates the body (non-empty, within the rune limit) and the optional
 // attachment (size and extension allow-list). senderIP is the gateway-forwarded
 // client IP (validated); channel is the submitting platform.
-func (svc *Service) Submit(ctx context.Context, accountID uuid.UUID, body string, attachment []byte, attachmentName, channel, senderIP string) error {
+func (svc *Service) Submit(ctx context.Context, accountID uuid.UUID, body string, attachment []byte, attachmentName, channel, version, browserTZ, senderIP string) error {
 	acc, err := svc.accounts.GetByID(ctx, accountID)
 	if err != nil {
 		return err
@@ -112,9 +112,10 @@ func (svc *Service) Submit(ctx context.Context, accountID uuid.UUID, body string
 		attachmentName = "" // a name without bytes carries no attachment
 	}
 	ch := normalizeChannel(channel)
-	// Snapshot the sender's interface language at submit time (acc is already loaded
+	// Snapshot the sender's interface language, the client app version and the client's
-	// for the guest check) so the operator later sees the state as it was.
+	// detected UTC offset at submit time (acc is already loaded for the guest check) so the
-	_, err = svc.store.Insert(ctx, accountID, body, attachment, attachmentName, ch, acc.PreferredLanguage, parseIP(senderIP))
+	// operator later sees the state as it was.
+	_, err = svc.store.Insert(ctx, accountID, body, attachment, attachmentName, ch, acc.PreferredLanguage, version, browserTZ, parseIP(senderIP))
 	return err
 }
 

backend/internal/feedback/store.go

@@ -34,10 +34,10 @@ func NewStore(db *sql.DB) *Store {
 
 // Insert stores one feedback message from accountID and returns its id. attachment
 // is the raw file bytes (nil for none); attachmentName, ip and a non-default
-// channel are stored as given. lang (the sender's interface language) is a snapshot
+// channel are stored as given. lang (interface language), version (client app build) and
-// taken now, so the operator later sees the state at submit time. created_at defaults
+// browserTZ (the client's detected "±HH:MM" UTC offset) are snapshots taken now, so the operator
-// to now() in the database.
+// later sees the state at submit time. created_at defaults to now() in the database.
-func (s *Store) Insert(ctx context.Context, accountID uuid.UUID, body string, attachment []byte, attachmentName, channel, lang string, ip *string) (uuid.UUID, error) {
+func (s *Store) Insert(ctx context.Context, accountID uuid.UUID, body string, attachment []byte, attachmentName, channel, lang, version, browserTZ string, ip *string) (uuid.UUID, error) {
 	id, err := uuid.NewV7()
 	if err != nil {
 		return uuid.Nil, fmt.Errorf("feedback: new message id: %w", err)
@@ -48,9 +48,9 @@ func (s *Store) Insert(ctx context.Context, accountID uuid.UUID, body string, at
 	}
 	if _, err := s.db.ExecContext(ctx,
 		`INSERT INTO backend.feedback_messages
-		   (message_id, account_id, body, attachment, attachment_name, channel, lang, sender_ip)
+		   (message_id, account_id, body, attachment, attachment_name, channel, lang, app_version, browser_tz, sender_ip)
-		 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+		 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`,
-		id, accountID, body, att, nullStr(attachmentName), channel, nullStr(lang), ip); err != nil {
+		id, accountID, body, att, nullStr(attachmentName), channel, nullStr(lang), nullStr(version), nullStr(browserTZ), ip); err != nil {
 		return uuid.Nil, fmt.Errorf("feedback: insert: %w", err)
 	}
 	return id, nil
@@ -229,6 +229,14 @@ type AdminMessage struct {
 	Channel    string
 	// Lang is the sender's interface language, snapshotted at submit time.
 	Lang string
+	// Version is the client app build the report was sent from, snapshotted at submit time.
+	Version string
+	// BrowserTZ is the client's detected "±HH:MM" UTC offset at submit time, snapshotted so the
+	// filed time can be shown in the sender's browser-local zone even before they save a profile.
+	BrowserTZ string
+	// TimeZone is the sender account's stored zone ("±HH:MM" offset, IANA name, or ""), for
+	// rendering CreatedAt in the sender's own configured time alongside UTC.
+	TimeZone       string
 	SenderIP       string
 	HasAttachment  bool
 	AttachmentName string
@@ -343,7 +351,7 @@ func (s *Store) AdminGet(ctx context.Context, id uuid.UUID) (AdminMessage, error
 	var m AdminMessage
 	var repliedAt sql.NullTime
 	q := `SELECT m.message_id, m.account_id, a.display_name, ` + feedbackSource + ` AS source, m.body, m.channel,
-		COALESCE(m.lang, ''),
+		COALESCE(m.lang, ''), COALESCE(m.app_version, ''), COALESCE(m.browser_tz, ''), a.time_zone,
 		COALESCE(m.sender_ip, ''), (m.attachment IS NOT NULL), COALESCE(m.attachment_name, ''),
 		(m.read_at IS NOT NULL), (m.archived_at IS NOT NULL), (m.reply_body IS NOT NULL),
 		COALESCE(m.reply_body, ''), m.replied_at, m.created_at
@@ -352,7 +360,7 @@ func (s *Store) AdminGet(ctx context.Context, id uuid.UUID) (AdminMessage, error
 	WHERE m.message_id = $1`
 	err := s.db.QueryRowContext(ctx, q, id).Scan(
 		&m.ID, &m.AccountID, &m.SenderName, &m.Source, &m.Body, &m.Channel,
-		&m.Lang,
+		&m.Lang, &m.Version, &m.BrowserTZ, &m.TimeZone,
 		&m.SenderIP, &m.HasAttachment, &m.AttachmentName,
 		&m.Read, &m.Archived, &m.Replied, &m.ReplyBody, &repliedAt, &m.CreatedAt)
 	if errors.Is(err, sql.ErrNoRows) {

backend/internal/game/doc.go

@@ -16,5 +16,5 @@
 // word-check tool with complaint capture, per-player game state, history and GCG
 // export, and the per-game turn-timeout sweeper that auto-resigns an overdue
 // player (honouring their daily away window). The HTTP surface that fronts these
-// operations is added with the gateway in a later stage.
+// operations is exposed to the gateway.
 package game

backend/internal/game/types.go

@@ -105,7 +105,7 @@ const MaxActiveQuickGames = 10
 const aiPlayerName = "AI"
 
 // CreateParams describes a new game. Seats lists the seated accounts in turn
-// order (seat 0 moves first); lobby/matchmaking assembles it in a later stage.
+// order (seat 0 moves first); lobby/matchmaking assembles it.
 type CreateParams struct {
 	Variant        engine.Variant
 	Seats          []uuid.UUID

backend/internal/inttest/account_test.go

@@ -110,15 +110,15 @@ func identityConfirmed(t *testing.T, kind, externalID string) bool {
 }
 
 // TestProvisionTelegramSeedsNewAccountOnly checks that Telegram first contact
-// seeds the new account's language and display name from the launch fields,
+// seeds the new account's language, display name and time zone from the launch
-// defaults the in-app-only flag on, and never overwrites an existing account on a
+// fields / detected offset, defaults the in-app-only flag on, and never overwrites
-// later login (language seeding).
+// an existing account on a later login (language and zone seeding).
 func TestProvisionTelegramSeedsNewAccountOnly(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
 	ext := "tg-" + uuid.NewString()
 
-	acc, created, err := store.ProvisionTelegram(ctx, ext, "ru-RU", "thehandle", "Иван")
+	acc, created, err := store.ProvisionTelegram(ctx, ext, "ru-RU", "thehandle", "Иван", "+03:00")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
@@ -131,12 +131,15 @@ func TestProvisionTelegramSeedsNewAccountOnly(t *testing.T) {
 	if acc.DisplayName != "Иван" {
 		t.Errorf("DisplayName = %q, want Иван", acc.DisplayName)
 	}
+	if acc.TimeZone != "+03:00" {
+		t.Errorf("TimeZone = %q, want the seeded +03:00", acc.TimeZone)
+	}
 	if !acc.NotificationsInAppOnly {
 		t.Error("NotificationsInAppOnly should default to true")
 	}
 
 	// A later login with different fields returns the same account, unchanged.
-	again, created, err := store.ProvisionTelegram(ctx, ext, "en", "other", "Other")
+	again, created, err := store.ProvisionTelegram(ctx, ext, "en", "other", "Other", "+09:00")
 	if err != nil {
 		t.Fatalf("re-provision telegram: %v", err)
 	}
@@ -146,8 +149,53 @@ func TestProvisionTelegramSeedsNewAccountOnly(t *testing.T) {
 	if again.ID != acc.ID {
 		t.Errorf("re-provision id = %s, want %s", again.ID, acc.ID)
 	}
-	if again.PreferredLanguage != "ru" || again.DisplayName != "Иван" {
+	if again.PreferredLanguage != "ru" || again.DisplayName != "Иван" || again.TimeZone != "+03:00" {
-		t.Errorf("existing account overwritten: lang=%q name=%q", again.PreferredLanguage, again.DisplayName)
+		t.Errorf("existing account overwritten: lang=%q name=%q tz=%q", again.PreferredLanguage, again.DisplayName, again.TimeZone)
+	}
+}
+
+// TestProvisionSeedsTimeZone checks the create-time time-zone seed across paths: a
+// valid detected offset is stored verbatim (even "+00:00", which is deliberately
+// distinct from the unset "UTC" default), a guest is seeded the same way, and a
+// missing or malformed offset falls back to the "UTC" column default rather than
+// being guessed at.
+func TestProvisionSeedsTimeZone(t *testing.T) {
+	ctx := context.Background()
+	store := account.NewStore(testDB)
+
+	// A detected zero offset is written as "+00:00" — we record that the zone was
+	// detected (and equals UTC), distinct from the "UTC" default meaning "unknown".
+	utcDetected, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Zero", "+00:00")
+	if err != nil {
+		t.Fatalf("provision telegram +00:00: %v", err)
+	}
+	if utcDetected.TimeZone != "+00:00" {
+		t.Errorf("TimeZone = %q, want the seeded +00:00", utcDetected.TimeZone)
+	}
+
+	// A malformed offset is dropped: the account keeps the UTC default.
+	bad, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Bad", "not-a-zone")
+	if err != nil {
+		t.Fatalf("provision telegram bad tz: %v", err)
+	}
+	if bad.TimeZone != "UTC" {
+		t.Errorf("TimeZone = %q, want UTC fallback for a malformed offset", bad.TimeZone)
+	}
+
+	// A guest is seeded its detected offset; an empty one keeps the UTC default.
+	guest, err := store.ProvisionGuest(ctx, "-05:30")
+	if err != nil {
+		t.Fatalf("provision guest: %v", err)
+	}
+	if guest.TimeZone != "-05:30" {
+		t.Errorf("guest TimeZone = %q, want the seeded -05:30", guest.TimeZone)
+	}
+	plainGuest, err := store.ProvisionGuest(ctx, "")
+	if err != nil {
+		t.Fatalf("provision plain guest: %v", err)
+	}
+	if plainGuest.TimeZone != "UTC" {
+		t.Errorf("plain guest TimeZone = %q, want UTC default", plainGuest.TimeZone)
 	}
 }
 
@@ -156,7 +204,7 @@ func TestProvisionTelegramSeedsNewAccountOnly(t *testing.T) {
 // language CHECK.
 func TestProvisionTelegramUnknownLanguageDefaults(t *testing.T) {
 	ctx := context.Background()
-	acc, _, err := account.NewStore(testDB).ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "fr", "", "")
+	acc, _, err := account.NewStore(testDB).ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "fr", "", "", "")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
@@ -172,7 +220,7 @@ func TestProvisionTelegramUnknownLanguageDefaults(t *testing.T) {
 func TestHighRateFlagRoundTrip(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
-	acc, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player")
+	acc, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player", "")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
@@ -228,7 +276,7 @@ func TestIdentityExternalID(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
 	ext := "tg-" + uuid.NewString()
-	acc, _, err := store.ProvisionTelegram(ctx, ext, "en", "", "Tg User")
+	acc, _, err := store.ProvisionTelegram(ctx, ext, "en", "", "Tg User", "")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
@@ -253,7 +301,7 @@ func TestIdentityExternalID(t *testing.T) {
 func TestNotificationsInAppOnlyRoundTrip(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
-	acc, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player")
+	acc, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player", "")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}

backend/internal/inttest/admin_test.go

@@ -222,7 +222,7 @@ func TestConsoleGameDetailRobotSchedule(t *testing.T) {
 func TestConsoleThrottledViewAndFlagClear(t *testing.T) {
 	ctx := context.Background()
 	accounts := account.NewStore(testDB)
-	acc, _, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Throttled Player")
+	acc, _, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Throttled Player", "")
 	if err != nil {
 		t.Fatalf("provision: %v", err)
 	}

backend/internal/inttest/chat_access_test.go

@@ -55,7 +55,7 @@ func TestChatAccessResolver(t *testing.T) {
 	srv := server.New(":0", server.Deps{Logger: zaptest.NewLogger(t), DB: testDB, Accounts: accounts})
 
 	ext := "tg-" + uuid.NewString()
-	acc, _, err := accounts.ProvisionTelegram(ctx, ext, "en", "", "Chatter")
+	acc, _, err := accounts.ProvisionTelegram(ctx, ext, "en", "", "Chatter", "")
 	if err != nil {
 		t.Fatalf("provision: %v", err)
 	}

backend/internal/inttest/email_test.go

@@ -62,7 +62,7 @@ func TestEmailConfirmFlow(t *testing.T) {
 }
 
 // TestEmailAlreadyTakenByAnotherAccount refuses to bind an email confirmed by a
-// different account (merge is a later stage).
+// different account (combining two accounts is the separate link/merge flow).
 func TestEmailAlreadyTakenByAnotherAccount(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
@@ -206,7 +206,7 @@ func TestEmailLoginFlow(t *testing.T) {
 	svc := account.NewEmailService(account.NewStore(testDB), mailer)
 	email := "login-" + uuid.NewString() + "@example.com"
 
-	accountID, err := svc.RequestLoginCode(ctx, email)
+	accountID, err := svc.RequestLoginCode(ctx, email, "+02:00")
 	if err != nil {
 		t.Fatalf("request login code: %v", err)
 	}
@@ -225,12 +225,15 @@ func TestEmailLoginFlow(t *testing.T) {
 	if acc.IsGuest {
 		t.Error("an email account must be durable, not a guest")
 	}
+	if acc.TimeZone != "+02:00" {
+		t.Errorf("TimeZone = %q, want the +02:00 seeded at the request step", acc.TimeZone)
+	}
 	if !identityConfirmed(t, account.KindEmail, email) {
 		t.Error("the email identity must be confirmed after login")
 	}
 
 	// A second login for the same email is the returning user: same account.
-	if _, err := svc.RequestLoginCode(ctx, email); err != nil {
+	if _, err := svc.RequestLoginCode(ctx, email, ""); err != nil {
 		t.Fatalf("second request: %v", err)
 	}
 	acc2, err := svc.LoginWithCode(ctx, email, sixDigit.FindString(mailer.lastBody))

backend/internal/inttest/feedback_test.go

@@ -38,7 +38,7 @@ func latestFeedbackID(t *testing.T, svc *feedback.Service, acc uuid.UUID) uuid.U
 func TestFeedbackGuestRejected(t *testing.T) {
 	svc := newFeedbackService()
 	guest := provisionGuest(t)
-	if err := svc.Submit(context.Background(), guest, "hi", nil, "", "web", "1.2.3.4"); !errors.Is(err, feedback.ErrGuestForbidden) {
+	if err := svc.Submit(context.Background(), guest, "hi", nil, "", "web", "v1", "+05:00", "1.2.3.4"); !errors.Is(err, feedback.ErrGuestForbidden) {
 		t.Fatalf("guest submit err = %v, want ErrGuestForbidden", err)
 	}
 }
@@ -48,11 +48,11 @@ func TestFeedbackSubmitGateAndReplyLifecycle(t *testing.T) {
 	svc := newFeedbackService()
 	acc := provisionAccount(t)
 
-	if err := svc.Submit(ctx, acc, "  please fix the board  ", []byte("PNGDATA"), "shot.png", "ios", "9.9.9.9"); err != nil {
+	if err := svc.Submit(ctx, acc, "  please fix the board  ", []byte("PNGDATA"), "shot.png", "ios", "v1.2.0", "+03:00", "9.9.9.9"); err != nil {
 		t.Fatalf("submit: %v", err)
 	}
 	// Anti-spam gate: a second message is refused while the first is unreviewed.
-	if err := svc.Submit(ctx, acc, "again", nil, "", "web", ""); !errors.Is(err, feedback.ErrPendingReview) {
+	if err := svc.Submit(ctx, acc, "again", nil, "", "web", "", "", ""); !errors.Is(err, feedback.ErrPendingReview) {
 		t.Fatalf("second submit err = %v, want ErrPendingReview", err)
 	}
 	if st, err := svc.State(ctx, acc); err != nil {
@@ -69,7 +69,7 @@ func TestFeedbackSubmitGateAndReplyLifecycle(t *testing.T) {
 	if m.Body != "please fix the board" { // trimmed
 		t.Fatalf("body = %q, want trimmed", m.Body)
 	}
-	if !m.HasAttachment || m.AttachmentName != "shot.png" || m.Channel != "ios" || m.SenderIP != "9.9.9.9" {
+	if !m.HasAttachment || m.AttachmentName != "shot.png" || m.Channel != "ios" || m.SenderIP != "9.9.9.9" || m.Version != "v1.2.0" || m.BrowserTZ != "+03:00" {
 		t.Fatalf("admin message = %+v", m)
 	}
 	if name, data, ok, err := svc.Attachment(ctx, id); err != nil || !ok || name != "shot.png" || string(data) != "PNGDATA" {
@@ -116,7 +116,7 @@ func TestFeedbackReplyHiddenAfterNewMessage(t *testing.T) {
 	acc := provisionAccount(t)
 
 	// msg1, replied → the player can send again and currently sees the reply.
-	if err := svc.Submit(ctx, acc, "first", nil, "", "web", ""); err != nil {
+	if err := svc.Submit(ctx, acc, "first", nil, "", "web", "", "", ""); err != nil {
 		t.Fatalf("submit msg1: %v", err)
 	}
 	if err := svc.Reply(ctx, latestFeedbackID(t, svc, acc), "the answer"); err != nil {
@@ -130,7 +130,7 @@ func TestFeedbackReplyHiddenAfterNewMessage(t *testing.T) {
 
 	// Sending a new message immediately drops the previous reply (it now belongs to an
 	// older message), even though it is well within the one-week window.
-	if err := svc.Submit(ctx, acc, "second", nil, "", "web", ""); err != nil {
+	if err := svc.Submit(ctx, acc, "second", nil, "", "web", "", "", ""); err != nil {
 		t.Fatalf("submit msg2: %v", err)
 	}
 	st, err := svc.State(ctx, acc)
@@ -154,7 +154,7 @@ func TestFeedbackSnapshotsLanguage(t *testing.T) {
 		t.Fatalf("set language: %v", err)
 	}
 	// A message snapshots the sender's interface language at submit time.
-	if err := svc.Submit(ctx, acc, "from telegram", nil, "", "telegram", ""); err != nil {
+	if err := svc.Submit(ctx, acc, "from telegram", nil, "", "telegram", "", "", ""); err != nil {
 		t.Fatalf("submit: %v", err)
 	}
 	id := latestFeedbackID(t, svc, acc)
@@ -184,7 +184,7 @@ func TestFeedbackBanRole(t *testing.T) {
 	if err := accounts.GrantRole(ctx, acc, account.RoleFeedbackBanned); err != nil {
 		t.Fatalf("grant role: %v", err)
 	}
-	if err := svc.Submit(ctx, acc, "hi", nil, "", "web", ""); !errors.Is(err, feedback.ErrBanned) {
+	if err := svc.Submit(ctx, acc, "hi", nil, "", "web", "", "", ""); !errors.Is(err, feedback.ErrBanned) {
 		t.Fatalf("banned submit err = %v, want ErrBanned", err)
 	}
 	if st, err := svc.State(ctx, acc); err != nil {
@@ -196,7 +196,7 @@ func TestFeedbackBanRole(t *testing.T) {
 	if err := accounts.RevokeRole(ctx, acc, account.RoleFeedbackBanned); err != nil {
 		t.Fatalf("revoke role: %v", err)
 	}
-	if err := svc.Submit(ctx, acc, "hi again", nil, "", "web", ""); err != nil {
+	if err := svc.Submit(ctx, acc, "hi again", nil, "", "web", "", "", ""); err != nil {
 		t.Fatalf("submit after unban: %v", err)
 	}
 }
@@ -219,7 +219,7 @@ func TestFeedbackValidation(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			acc := provisionAccount(t) // fresh account so the pending gate never fires first
-			if err := svc.Submit(ctx, acc, tt.body, tt.attachment, tt.attachmentName, "web", ""); !errors.Is(err, tt.want) {
+			if err := svc.Submit(ctx, acc, tt.body, tt.attachment, tt.attachmentName, "web", "", "", ""); !errors.Is(err, tt.want) {
 				t.Fatalf("submit err = %v, want %v", err, tt.want)
 			}
 		})
@@ -231,7 +231,7 @@ func TestFeedbackAdminLifecycle(t *testing.T) {
 	svc := newFeedbackService()
 	acc := provisionAccount(t)
 
-	if err := svc.Submit(ctx, acc, "first report", nil, "", "web", ""); err != nil {
+	if err := svc.Submit(ctx, acc, "first report", nil, "", "web", "", "", ""); err != nil {
 		t.Fatalf("submit: %v", err)
 	}
 	id := latestFeedbackID(t, svc, acc)
@@ -276,7 +276,7 @@ func TestFeedbackDeleteAllByAccount(t *testing.T) {
 	svc := newFeedbackService()
 	acc := provisionAccount(t)
 
-	if err := svc.Submit(ctx, acc, "one", nil, "", "web", ""); err != nil {
+	if err := svc.Submit(ctx, acc, "one", nil, "", "web", "", "", ""); err != nil {
 		t.Fatalf("submit: %v", err)
 	}
 	if err := svc.DeleteAllByAccount(ctx, acc); err != nil {
@@ -286,7 +286,7 @@ func TestFeedbackDeleteAllByAccount(t *testing.T) {
 	if has, err := svc.ReplyUnread(ctx, acc); err != nil || has {
 		t.Fatalf("reply unread after delete-all = %v (err %v)", has, err)
 	}
-	if err := svc.Submit(ctx, acc, "fresh", nil, "", "web", ""); err != nil {
+	if err := svc.Submit(ctx, acc, "fresh", nil, "", "web", "", "", ""); err != nil {
 		t.Fatalf("submit after delete-all: %v", err)
 	}
 }

backend/internal/inttest/helpers.go

@@ -120,7 +120,7 @@ func provisionAccount(t *testing.T) uuid.UUID {
 // provisionGuest creates a fresh ephemeral guest account and returns its id.
 func provisionGuest(t *testing.T) uuid.UUID {
 	t.Helper()
-	acc, err := account.NewStore(testDB).ProvisionGuest(context.Background())
+	acc, err := account.NewStore(testDB).ProvisionGuest(context.Background(), "")
 	if err != nil {
 		t.Fatalf("provision guest: %v", err)
 	}

backend/internal/inttest/promo_variant_test.go

@@ -0,0 +1,80 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap/zaptest"
+
+	"scrabble/backend/internal/account"
+	"scrabble/backend/internal/server"
+	"scrabble/backend/internal/session"
+)
+
+// TestTelegramAuthSeedsPromoVariantForNewUserOnly drives the sessions/telegram endpoint
+// to confirm a promo deep-link start-param seeds a brand-new account's variant
+// preferences (English Scrabble alongside the default Erudit), that a new account with no
+// such payload keeps the Erudit-only default, and that an existing account is never
+// re-seeded on a later login (the new-user-only contract).
+func TestTelegramAuthSeedsPromoVariantForNewUserOnly(t *testing.T) {
+	srv := server.New(":0", server.Deps{
+		Logger:   zaptest.NewLogger(t),
+		DB:       testDB,
+		Accounts: account.NewStore(testDB),
+		Sessions: session.NewService(session.NewStore(testDB), session.NewCache()),
+		Notifier: &captureNotifier{},
+	})
+	h := srv.Handler()
+
+	post := func(ext, startParam string) {
+		body := `{"external_id":"` + ext + `","language_code":"en","first_name":"Promo"`
+		if startParam != "" {
+			body += `,"start_param":"` + startParam + `"`
+		}
+		body += `}`
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/internal/sessions/telegram", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		h.ServeHTTP(rec, req)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("telegram auth = %d: %s", rec.Code, rec.Body.String())
+		}
+	}
+	store := account.NewStore(testDB)
+	reload := func(ext string) []string {
+		acc, err := store.AccountByIdentity(context.Background(), account.KindTelegram, ext)
+		if err != nil {
+			t.Fatalf("lookup %s: %v", ext, err)
+		}
+		return acc.VariantPreferences
+	}
+
+	// A brand-new account reached through a promo deep-link is seeded with English
+	// Scrabble alongside the default Erudit.
+	promoExt := "tg-" + uuid.NewString()
+	post(promoExt, "verudit_ru-scrabble_en")
+	if got, want := reload(promoExt), []string{"erudit_ru", "scrabble_en"}; !slices.Equal(got, want) {
+		t.Errorf("promo new account variants = %v, want %v", got, want)
+	}
+
+	// A brand-new account with no promo payload keeps the Erudit-only default.
+	plainExt := "tg-" + uuid.NewString()
+	post(plainExt, "")
+	if got, want := reload(plainExt), []string{"erudit_ru"}; !slices.Equal(got, want) {
+		t.Errorf("plain new account variants = %v, want %v", got, want)
+	}
+
+	// A later login of the promo account, even via a different payload, must not re-seed:
+	// the seed is first-contact only.
+	post(promoExt, "vscrabble_ru")
+	if got, want := reload(promoExt), []string{"erudit_ru", "scrabble_en"}; !slices.Equal(got, want) {
+		t.Errorf("existing account re-seeded = %v, want unchanged %v", got, want)
+	}
+}

backend/internal/inttest/suspension_gate_test.go

@@ -38,7 +38,7 @@ func TestSuspensionGate(t *testing.T) {
 		Accounts: accounts,
 	})
 
-	acc, _, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "ru", "", "Blocked")
+	acc, _, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "ru", "", "Blocked", "")
 	if err != nil {
 		t.Fatalf("provision: %v", err)
 	}

backend/internal/inttest/userlist_test.go

@@ -18,7 +18,7 @@ func TestUserListFilter(t *testing.T) {
 	st := account.NewStore(testDB)
 	uniq := uuid.NewString()
 
-	human, _, err := st.ProvisionTelegram(ctx, "tg-"+uniq, "en", "", "Zzqxhuman")
+	human, _, err := st.ProvisionTelegram(ctx, "tg-"+uniq, "en", "", "Zzqxhuman", "")
 	if err != nil {
 		t.Fatalf("provision human: %v", err)
 	}
@@ -26,7 +26,7 @@ func TestUserListFilter(t *testing.T) {
 	if err != nil {
 		t.Fatalf("provision robot: %v", err)
 	}
-	guest, err := st.ProvisionGuest(ctx)
+	guest, err := st.ProvisionGuest(ctx, "")
 	if err != nil {
 		t.Fatalf("provision guest: %v", err)
 	}

backend/internal/postgres/migrations/00002_default_ad_tips.sql

@@ -0,0 +1,64 @@
+-- Replace the default (house) ad campaign's single seed tip with the curated,
+-- language-agnostic Scrabble tip set (one bilingual row per tip; the client picks the
+-- column for the viewer's language). Data-only — the ad_messages schema is unchanged, so
+-- a backend image rollback stays DB-safe. The default campaign is the fixed house id seeded
+-- in 00001; ON DELETE CASCADE is irrelevant here (we only touch its messages).
+
+-- +goose Up
+DELETE FROM backend.ad_messages WHERE campaign_id = '00000000-0000-0000-0000-0000000000ad';
+INSERT INTO backend.ad_messages (message_id, campaign_id, "position", body_en, body_ru) VALUES
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 0, 'Keep a balanced rack — a slight edge of consonants over vowels.', 'Держи на руках баланс — с лёгким перевесом согласных над гласными.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 1, 'Your "leave" (the tiles you keep) sets up your next turn — value it.', '«Остаток» (что оставляешь на руках) готовит следующий ход — цени его.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 2, 'Shed duplicate tiles — repeats clog your options.', 'Сбрасывай дубли фишек — повторы забивают возможности.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 3, 'A slightly consonant-heavy rack builds full-rack plays more easily.', 'Лёгкий перевес согласных проще складывается в выкладку всех фишек.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 4, 'Play several tiles per turn to keep your rack cycling.', 'Выкладывай по нескольку фишек за ход, чтобы рука обновлялась.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 5, 'Don''t hoard hard-to-place duplicates or a lone high-value tile.', 'Не копи труднопристраиваемые дубли или одинокую дорогую фишку.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 6, 'Using all your rack tiles in one move scores a large bonus — chase it.', 'Выкладка всех фишек с рук за ход даёт крупный бонус — стремись к ней.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 7, 'Learn common prefixes and suffixes — they extend words to use every tile.', 'Учи частые приставки и суффиксы — они растягивают слово на все фишки.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 8, '"Fish": play few tiles to keep a near-complete rack when you''re ahead.', '«Рыбачь»: сыграй мало фишек, сохранив почти всю руку, когда ведёшь.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 9, 'Don''t hoard high-value tiles — play them in good time, not at the very end.', 'Не копи дорогие фишки — играй их вовремя, а не под самый конец.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 10, 'Don''t hold a high-value tile waiting for a rare partner — usually a loss.', 'Не держи дорогую фишку ради редкого партнёра — обычно это проигрыш.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 11, 'Land your priciest tile on a premium square for a big single score.', 'Сажай самую дорогую фишку на бонусную клетку ради крупных очков.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 12, 'High-value tiles shine in parallel plays through short words.', 'Дорогие фишки сильны в параллельных выкладках через короткие слова.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 13, 'Stuck with an unplayable high-value tile late? Exchange it.', 'Завис с неиграбельной дорогой фишкой под конец? Обменяй её.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 14, 'The blanks are the most valuable tiles in the bag — guard them.', 'Пустышки — самые ценные фишки в мешке; береги их.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 15, 'Save a blank for a full-rack play or a key premium square.', 'Береги пустышку для выкладки всех фишек или важной бонусной клетки.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 16, 'Don''t spend a blank cheaply — hold it for a much bigger gain.', 'Не трать пустышку по мелочи — придержи ради куда большей выгоды.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 17, 'Put high-value tiles on letter-bonus or word-bonus squares.', 'Клади дорогие фишки на бонус буквы или слова.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 18, 'Stack bonuses — a letter bonus under a word bonus multiplies both.', 'Совмещай бонусы — бонус буквы под бонусом слова умножает оба.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 19, 'Parallel plays can earn nearly half your points — look for them.', 'Параллельные выкладки могут давать почти половину очков — ищи их.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 20, 'A hook adds one tile to an existing word to make a new one.', '«Крючок» — одна фишка к готовому слову, образующая новое.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 21, 'Hooks work at the front or the back of a word.', 'Крючки работают спереди и сзади слова.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 22, 'Short words are the keys to tight parallel plays — memorize them.', 'Короткие слова — ключ к плотным параллелям; выучи их.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 23, 'Your opening word crosses the centre — keep it compact, don''t open up.', 'Первое слово идёт через центр — держи компактным, не раскрывайся.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 24, 'It''s not only your score — limit your opponent''s options too.', 'Это не только твои очки — ограничивай и возможности соперника.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 25, 'Denying a big reply often beats squeezing a few more points yourself.', 'Закрыть крупный ответ часто важнее, чем добрать пару своих очков.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 26, 'When ahead, keep the board tight and closed; avoid open lanes.', 'Ведёшь — держи доску плотной и закрытой, не открывай линии.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 27, 'When behind, open the board up to create high-scoring chances.', 'Отстаёшь — раскрывай доску ради шансов на крупный ход.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 28, 'Don''t leave a word-bonus square open right beside your word.', 'Не оставляй клетку бонуса слова открытой рядом со своим словом.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 29, 'Block a hot square even with a weak word to deny a big play.', 'Закрывай опасную клетку даже слабым словом, чтобы срубить крупный ход.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 30, 'Know words that take no hooks — use them to seal off lines.', 'Знай слова, не берущие крючков — ими запирай линии.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 31, 'Track the tiles played to judge what is still left in the bag.', 'Считай сыгранные фишки — так поймёшь, что осталось в мешке.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 32, 'Exchange when your rack is unbalanced or can only score low.', 'Меняй фишки, когда рука несбалансированна или тянет мало.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 33, 'A good exchange beats a bad play — a clean rack is worth a turn.', 'Хороший обмен лучше плохого хода — чистая рука стоит хода.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 34, 'Swap away a surplus of vowels or consonants to rebalance.', 'Сбрасывай в обмен избыток гласных или согласных, чтобы выровняться.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 35, 'Rare high-value tiles are gone once seen — note them as they appear.', 'Редкие дорогие фишки исчезают, едва мелькнув — отмечай их.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 36, 'Once the bag is empty, deduce your opponent''s remaining tiles.', 'Когда мешок пуст, вычисли оставшиеся фишки соперника.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 37, 'Shed high-value tiles before the bag empties — don''t get stuck with them.', 'Сбрось дорогие фишки до опустения мешка — не зависай с ними.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 38, 'Unplayed tiles count against you at the end — try to go out first.', 'Несыгранные фишки минусуют очки в конце — старайся выйти первым.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 39, 'Going out first adds your opponent''s leftover tiles to your score.', 'Кто вышел первым, добирает очки за оставшиеся фишки соперника.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 40, 'Sometimes leaving one tile in the bag buys you an extra turn.', 'Иногда оставить одну фишку в мешке — это лишний ход.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 41, 'In the endgame, block the exact squares your opponent needs.', 'В эндшпиле блокируй именно те клетки, что нужны сопернику.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 42, 'Shuffle your rack to spot new patterns.', 'Перемешивай фишки на руках — так замечаешь новые сочетания.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 43, 'Separate prefix, suffix and middle tiles to anagram faster.', 'Разнеси приставку, суффикс и середину — анаграммы решаются быстрее.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 44, 'Value board position and future turns over raw points this turn.', 'Цени позицию и будущие ходы выше сиюминутных очков.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 45, 'Early game build position; midgame maximize score; endgame defend.', 'В начале — позиция, в середине — очки, в конце — защита.'),
+    (gen_random_uuid(), '00000000-0000-0000-0000-0000000000ad', 46, 'Learn the short-word lists first — they pay off in every game.', 'Сначала учи списки коротких слов — окупаются в каждой партии.');
+
+-- +goose Down
+-- Restore the original single house tip seeded by the baseline.
+DELETE FROM backend.ad_messages WHERE campaign_id = '00000000-0000-0000-0000-0000000000ad';
+INSERT INTO backend.ad_messages (message_id, campaign_id, "position", body_en, body_ru)
+VALUES ('00000000-0000-0000-0000-0000000000a1', '00000000-0000-0000-0000-0000000000ad', 0,
+    'Tip: a play using all 7 tiles earns a +50 bonus.',
+    'Совет: ход всеми 7 фишками приносит бонус +50 очков.');

backend/internal/postgres/migrations/00003_feedback_app_version.sql

@@ -0,0 +1,10 @@
+-- Capture the client app version (the build a report was sent from) with each feedback
+-- message, so the operator console can show which version a player was on. Nullable, so the
+-- rows that predate this keep working — additive and backward-compatible, so a backend image
+-- rollback stays DB-safe (older code simply ignores the column).
+
+-- +goose Up
+ALTER TABLE backend.feedback_messages ADD COLUMN app_version text;
+
+-- +goose Down
+ALTER TABLE backend.feedback_messages DROP COLUMN app_version;

backend/internal/postgres/migrations/00004_feedback_browser_tz.sql

@@ -0,0 +1,11 @@
+-- Capture the client's detected UTC offset ("±HH:MM") with each feedback message, so the
+-- operator console can show the filed time in the sender's browser-local zone even before that
+-- player has ever saved a profile (the account zone defaults to UTC until then). Nullable, so the
+-- rows that predate this keep working — additive and backward-compatible, so a backend image
+-- rollback stays DB-safe (older code simply ignores the column).
+
+-- +goose Up
+ALTER TABLE backend.feedback_messages ADD COLUMN browser_tz text;
+
+-- +goose Down
+ALTER TABLE backend.feedback_messages DROP COLUMN browser_tz;

backend/internal/server/handlers_admin_console.go

@@ -1198,6 +1198,17 @@ func fmtTime(t time.Time) string {
 	return t.UTC().Format("2006-01-02 15:04")
 }
 
+// fmtTimeIn formats a timestamp in the given zone — a "±HH:MM" offset or an IANA name, resolved
+// by account.ResolveZone (falling back to UTC when empty or unknown) — or "" when zero. Used to
+// show a time in a user's local zone beside UTC; the offset form is what the profile editor and
+// the feedback browser-tz snapshot store, so it must not go through time.LoadLocation alone.
+func fmtTimeIn(t time.Time, tz string) string {
+	if t.IsZero() {
+		return ""
+	}
+	return t.In(account.ResolveZone(tz)).Format("2006-01-02 15:04")
+}
+
 // fmtTimePtr formats an optional timestamp for display, or "" when nil.
 func fmtTimePtr(t *time.Time) string {
 	if t == nil {

backend/internal/server/handlers_admin_feedback.go

@@ -77,6 +77,17 @@ func (s *Server) consoleFeedbackDetail(c *gin.Context) {
 		s.consoleError(c, err)
 		return
 	}
+	// Filed time in three zones so the operator can tell what is certainly known from what is
+	// merely defaulted: always UTC; the client's offset detected at submit (when the build
+	// reported one); and the sender's saved profile zone (when set beyond the UTC default). An
+	// empty rendered time makes the template show "N/A" for that line.
+	browserCreated, userCreated := "", ""
+	if m.BrowserTZ != "" {
+		browserCreated = fmtTimeIn(m.CreatedAt, m.BrowserTZ)
+	}
+	if m.TimeZone != "" && m.TimeZone != "UTC" {
+		userCreated = fmtTimeIn(m.CreatedAt, m.TimeZone)
+	}
 	view := adminconsole.FeedbackDetailView{
 		ID: m.ID.String(), AccountID: m.AccountID.String(), SenderName: m.SenderName,
 		Source: m.Source, Channel: m.Channel, InterfaceLanguage: m.Lang,
@@ -84,6 +95,9 @@ func (s *Server) consoleFeedbackDetail(c *gin.Context) {
 		HasAttachment: m.HasAttachment, AttachmentName: m.AttachmentName, IsImage: feedback.IsImage(m.AttachmentName),
 		Read: m.Read, Archived: m.Archived, Replied: m.Replied, ReplyBody: m.ReplyBody,
 		RepliedAt: fmtTime(m.RepliedAt), CreatedAt: fmtTime(m.CreatedAt),
+		Version:          m.Version,
+		CreatedAtBrowser: browserCreated, BrowserTZ: m.BrowserTZ,
+		CreatedAtUser: userCreated, UserTZ: m.TimeZone,
 	}
 	if banned, err := s.accounts.HasRole(ctx, m.AccountID, account.RoleFeedbackBanned); err == nil {
 		view.Banned = banned

backend/internal/server/handlers_auth.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
+	"go.uber.org/zap"
 
 	"scrabble/backend/internal/account"
 )
@@ -18,12 +19,17 @@ import (
 
 // telegramAuthRequest carries the identity the connector extracted from a
 // validated initData payload. Username, FirstName and LanguageCode seed a
-// brand-new account's display name and language (first contact only).
+// brand-new account's display name and language; BrowserTZ (the client's detected
+// "±HH:MM" UTC offset) seeds its time zone; StartParam is the validated launch
+// deep-link payload, which may seed the new account's variant preferences (first
+// contact only).
 type telegramAuthRequest struct {
 	ExternalID   string `json:"external_id"`
 	Username     string `json:"username"`
 	FirstName    string `json:"first_name"`
 	LanguageCode string `json:"language_code"`
+	BrowserTZ    string `json:"browser_tz"`
+	StartParam   string `json:"start_param"`
 }
 
 // handleTelegramAuth provisions (or finds) the account bound to a Telegram
@@ -35,7 +41,7 @@ func (s *Server) handleTelegramAuth(c *gin.Context) {
 		abortBadRequest(c, "external_id is required")
 		return
 	}
-	acc, created, err := s.accounts.ProvisionTelegram(c.Request.Context(), req.ExternalID, req.LanguageCode, req.Username, req.FirstName)
+	acc, created, err := s.accounts.ProvisionTelegram(c.Request.Context(), req.ExternalID, req.LanguageCode, req.Username, req.FirstName, req.BrowserTZ)
 	if err != nil {
 		s.abortErr(c, err)
 		return
@@ -45,6 +51,16 @@ func (s *Server) handleTelegramAuth(c *gin.Context) {
 		// joined the chat before registering is granted on the spot (no chat_member
 		// event fires on registration).
 		s.publishChatAccessChange(acc.ID)
+		// A promo deep-link may seed this brand-new account's variant preferences (e.g.
+		// English Scrabble alongside the default Erudit). Best-effort: an absent or
+		// malformed payload leaves the account on its defaults, and a write failure must
+		// not block the session mint.
+		if seed := account.SeedVariantsFromStartParam(req.StartParam); len(seed) > 0 {
+			if _, err := s.accounts.SetVariantPreferences(c.Request.Context(), acc.ID, seed); err != nil {
+				s.log.Warn("telegram: seed variant preferences failed",
+					zap.String("account", acc.ID.String()), zap.Error(err))
+			}
+		}
 	}
 	s.mintSession(c, acc)
 }
@@ -97,9 +113,21 @@ func (s *Server) handlePushTarget(c *gin.Context) {
 	})
 }
 
-// handleGuestAuth provisions a fresh ephemeral guest account and mints a session.
+// guestAuthRequest carries the guest bootstrap's optional time-zone seed: BrowserTZ
+// (the client's detected "±HH:MM" UTC offset) is written to the new guest account's
+// time zone, so robot timing is anchored to the player's zone from the first game.
+type guestAuthRequest struct {
+	BrowserTZ string `json:"browser_tz"`
+}
+
+// handleGuestAuth provisions a fresh ephemeral guest account and mints a session,
+// seeding its time zone from the optional detected browser offset.
 func (s *Server) handleGuestAuth(c *gin.Context) {
-	acc, err := s.accounts.ProvisionGuest(c.Request.Context())
+	// The body is optional: an absent or malformed one simply yields no time-zone seed
+	// (the account keeps the UTC default), so a bind error must not fail the bootstrap.
+	var req guestAuthRequest
+	_ = c.ShouldBindJSON(&req)
+	acc, err := s.accounts.ProvisionGuest(c.Request.Context(), req.BrowserTZ)
 	if err != nil {
 		s.abortErr(c, err)
 		return
@@ -107,9 +135,12 @@ func (s *Server) handleGuestAuth(c *gin.Context) {
 	s.mintSession(c, acc)
 }
 
-// emailRequest is an email-login code request.
+// emailRequest is an email-login code request. BrowserTZ (the client's detected
+// "±HH:MM" UTC offset) seeds the time zone of an account provisioned here on first
+// contact (the email account is created at the request step, not at login).
 type emailRequest struct {
 	Email     string `json:"email"`
+	BrowserTZ string `json:"browser_tz"`
 }
 
 // handleEmailRequest issues a login confirm-code to the email. It always reports
@@ -121,7 +152,7 @@ func (s *Server) handleEmailRequest(c *gin.Context) {
 		abortBadRequest(c, "email is required")
 		return
 	}
-	if _, err := s.emails.RequestLoginCode(c.Request.Context(), req.Email); err != nil {
+	if _, err := s.emails.RequestLoginCode(c.Request.Context(), req.Email, req.BrowserTZ); err != nil {
 		s.abortErr(c, err)
 		return
 	}

backend/internal/server/handlers_feedback.go

@@ -16,6 +16,12 @@ type feedbackSubmitRequest struct {
 	Attachment     string `json:"attachment"`
 	AttachmentName string `json:"attachment_name"`
 	Channel        string `json:"channel"`
+	// Version is the client's app version (pkg/version / the SPA build), snapshotted so the
+	// operator sees which build a report came from.
+	Version string `json:"version"`
+	// BrowserTZ is the client's detected UTC offset ("±HH:MM") at submit, so the operator can
+	// see the filed time in the sender's local zone even before they save a profile.
+	BrowserTZ string `json:"browser_tz"`
 }
 
 // feedbackReplyDTO is the operator's reply shown back to the player.
@@ -61,7 +67,7 @@ func (s *Server) handleFeedbackSubmit(c *gin.Context) {
 		}
 		attachment = data
 	}
-	if err := s.feedback.Submit(c.Request.Context(), uid, req.Body, attachment, req.AttachmentName, req.Channel, clientIP(c)); err != nil {
+	if err := s.feedback.Submit(c.Request.Context(), uid, req.Body, attachment, req.AttachmentName, req.Channel, req.Version, req.BrowserTZ, clientIP(c)); err != nil {
 		s.abortErr(c, err)
 		return
 	}

backend/internal/server/server.go

@@ -1,10 +1,10 @@
 // Package server wires the backend's HTTP listener: the gin engine, its route
 // groups, the per-request telemetry middleware and the start/stop lifecycle.
 //
-// The /api/v1 route groups (public, user, internal, admin) are created here so
+// The /api/v1 route groups (public, user, internal, admin) attach their endpoints
-// later stages attach their endpoints to a stable structure; the /user group
+// to a stable structure; the /user group requires the X-User-ID identity header.
-// requires the X-User-ID identity header. The probes /healthz (liveness) and
+// The probes /healthz (liveness) and /readyz (database + session-cache readiness)
-// /readyz (database + session-cache readiness) are unauthenticated.
+// are unauthenticated.
 package server
 
 import (
@@ -245,7 +245,7 @@ func (s *Server) Invitations() *lobby.InvitationService { return s.invitations }
 func (s *Server) Emails() *account.EmailService { return s.emails }
 
 // Handler returns the underlying HTTP handler. It lets tests drive the server
-// without binding a socket and lets later stages compose the backend behind
+// without binding a socket and lets callers compose the backend behind
 // another listener.
 func (s *Server) Handler() http.Handler { return s.http.Handler }
 

backend/internal/session/service.go

@@ -8,8 +8,7 @@ import (
 )
 
 // Service mints, resolves, and revokes sessions over the store and the
-// write-through cache. The gateway is its only caller (from a later stage); the
+// write-through cache. The gateway is its only caller.
-// HTTP surface is wired then.
 type Service struct {
 	store *Store
 	cache *Cache

backend/internal/social/social.go

@@ -3,8 +3,8 @@
 // in as a message kind. It owns the friendships, blocks and chat_messages tables,
 // reads the account-level block toggles through account.Store, and gates chat and
 // nudge on game state through a GameReader so it never imports the engine. The
-// live delivery of chat and nudges (push / in-app stream) belongs to the gateway
+// live delivery of chat and nudges (push / in-app stream) belongs to the gateway;
-// in a later stage; this package only persists and reads them.
+// this package only persists and reads them.
 package social
 
 import (

deploy/.env.example

@@ -16,7 +16,7 @@ POSTGRES_PASSWORD=change-me            # required
 # the active version lives in the DB. On a live volume a changed value is ignored (the
 # recorded .seed_version marker wins — the seed-drift guard); change a running
 # contour's dictionary through /_gm/dictionary (ARCHITECTURE.md §5).
-DICT_VERSION=v1.2.1
+DICT_VERSION=v1.3.0
 
 # --- Logging ----------------------------------------------------------------
 LOG_LEVEL=info
@@ -47,9 +47,11 @@ AWG_CONF=                              # required; AmneziaWG sidecar config (the
 TELEGRAM_BOT_TOKEN=                    # required
 TELEGRAM_GAME_CHANNEL_ID=
 TELEGRAM_CHAT_ID=                      # moderated discussion chat (channel's linked group); empty disables gating
+TELEGRAM_SUPPORT_CHAT_ID=              # private forum supergroup for the support relay (topic per user); empty disables it
 TELEGRAM_PROMO_BOT_TOKEN=             # optional standalone promo bot token; empty disables it
 TELEGRAM_BOT_USERNAME=               # main bot @username without the @ (promo message); required when the promo token is set
 TELEGRAM_BOT_LINK=                    # main bot Mini App link for the promo button (reuse VITE_TELEGRAM_LINK); required when the promo token is set
+TELEGRAM_PROMO_START_PARAM=           # promo button startapp payload — a variant-seed deep link (default verudit_ru-scrabble_en) adding English Scrabble for new users; empty forwards the user's /start payload
 TELEGRAM_MINIAPP_URL=                  # required
 TELEGRAM_TEST_ENV=false
 TELEGRAM_API_BASE_URL=

deploy/README.md

@@ -80,7 +80,7 @@ without it Docker's resolver handles `otelcol`, `gateway` and `api.telegram.org`
 | --- | --- | --- | --- |
 | `POSTGRES_DB` | variable | `scrabble` | Database name. |
 | `POSTGRES_USER` | variable | `scrabble` | Database user. |
-| `DICT_VERSION` | variable | `v1.2.1` | `scrabble-dictionary` release tag baked into the backend image as the **seed for a fresh volume** (build-arg). A live contour changes dictionary through the admin console, not this; on a seeded volume a changed value is ignored (the recorded `.seed_version` marker wins — the seed-drift guard, ARCHITECTURE.md §5). Set per contour as `TEST_`/`PROD_DICT_VERSION`. |
+| `DICT_VERSION` | variable | `v1.3.0` | `scrabble-dictionary` release tag baked into the backend image as the **seed for a fresh volume** (build-arg). A live contour changes dictionary through the admin console, not this; on a seeded volume a changed value is ignored (the recorded `.seed_version` marker wins — the seed-drift guard, ARCHITECTURE.md §5). Set per contour as `TEST_`/`PROD_DICT_VERSION`. |
 | `LOG_LEVEL` | variable | `info` | Shared log level for backend / gateway / validator / bot (`debug\|info\|warn\|error`). |
 | `CADDY_SITE_ADDRESS` | variable | `:80` | Caddy site address. Test: `:80` (host caddy terminates TLS). Prod: a domain, so caddy does its own ACME. |
 | `GM_BASICAUTH_USER` | variable | `gm` | Username for the `/_gm` Basic-Auth. |
@@ -117,6 +117,28 @@ collector's / gateway's internal IP is fine (connected route), but its `AWG_CONF
 which resolves `otelcol`, `gateway` and `api.telegram.org`. `GATEWAY_ADMIN_*` is
 intentionally **unset** — caddy owns `/_gm` in the contour.
 
+## Bumping the dictionary version
+
+The dictionary ships as a versioned **release artifact** (`scrabble-dawg-vX.Y.Z.tar.gz`) from
+[`scrabble-dictionary`](https://gitea.iliadenisov.ru/developer/scrabble-dictionary). The tag is
+a build-time input with **no default** in the images, so it is set in exactly two places to
+move the whole stack — change both to a new release:
+
+1. **CI tests** — `.gitea/workflows/ci.yaml` `env.DICT_VERSION` (the unit/integration jobs
+   download that dawg).
+2. **Deploy seed** — the Gitea repo variables `TEST_DICT_VERSION` / `PROD_DICT_VERSION` (the tag
+   the deploy bakes into a **fresh** volume's image; the deploy job feeds it to `compose` as
+   `DICT_VERSION`).
+
+For local builds set `DICT_VERSION` in `deploy/.env` (template: `.env.example`); a bare
+`docker build` needs `--build-arg DICT_VERSION=vX.Y.Z`. The Dockerfiles and `compose` carry no
+default — a missing value fails loudly instead of baking a stale tag.
+
+Bumping the seed is a **no-op on a live volume** (the `.seed_version` marker wins — the
+seed-drift guard). A running contour/prod moves to a new release **through the admin console**
+`/_gm/dictionary` (upload the tarball, preview the per-variant diff, confirm); in-flight games
+keep their pinned version, new games use the new one (ARCHITECTURE.md §5).
+
 ## Production rollout
 
 Prod runs on **two hosts** (main = full stack + ACME on the domain; tg = the bot only,
@@ -128,7 +150,9 @@ Re-run `ansible/` after a host resize — it is idempotent.
 workflow manually (Gitea → Actions → prod-deploy → run from `master`, input
 `confirm=deploy`). It builds + pushes the images to the registry, ships the
 compose/config/certs/env over SSH, deploys the main host with `prod-deploy.sh` (rolling,
-health-gated, **auto-rollback to the previous tag**), then the bot host, then probes the
+health-gated, **auto-rollback to the previous tag**; caddy is force-recreated on its roll so
+a bind-mounted `Caddyfile` change applies — its image is pinned and admin is off, so neither a
+new tag nor a hot reload would pick it up), then the bot host, then probes the
 public site. After `master` is green this workflow is the **only** thing that touches
 prod — nothing auto-deploys there. It runs four visible jobs: **build → deploy-main →
 deploy-bot → verify** (the per-service rolling shows in the deploy-main log).

deploy/ansible/README.md

@@ -1,4 +1,4 @@
-# Prod host provisioning (Stage 18)
+# Prod host provisioning
 
 Idempotent Ansible that prepares the two production hosts. It installs Docker, a
 non-sudo `deploy` service account, SSH hardening, a default-deny firewall,

deploy/ansible/site.yml

@@ -1,5 +1,5 @@
 ---
-# Stage 18 host provisioning. Idempotent: safe to re-run after a host resize.
+# Production host provisioning. Idempotent: safe to re-run after a host resize.
 # Prepares hosts only (docker, hardening, service account, firewall); the
 # application is deployed separately by .gitea/workflows/prod-deploy.yaml.
 

deploy/caddy/Caddyfile

@@ -21,6 +21,18 @@
 }
 
 {$CADDY_SITE_ADDRESS::80} {
+	# HTTP/3 is advertised by default whenever this caddy terminates TLS (prod:
+	# CADDY_SITE_ADDRESS is the domain). But UDP/443 is never reachable — the prod
+	# compose maps only "443:443" (TCP) and ufw opens 443/tcp — so a client that cached
+	# the `Alt-Svc: h3` advert (sticky for ma=2592000s) stalls on the dead QUIC path
+	# before falling back to h2, which surfaced as the Telegram Mini App intermittently
+	# hanging on load. `Alt-Svc: clear` actively drops any cached alternative and pins
+	# clients to h2/h1; it is applied site-wide so every route is covered. In the test
+	# contour this caddy serves plain :80 (no h3 to advertise) and the host caddy
+	# re-stamps its own Alt-Svc, so the live test fix lives in the host caddy — here it
+	# is the prod fix. Background + alternatives (incl. serving h3 for real): docs/EDGE_HTTP3.md.
+	header Alt-Svc clear
+
 	# Operator surfaces under /_gm: a single shared Basic-Auth, then route.
 	@gm path /_gm /_gm/*
 	handle @gm {

deploy/docker-compose.bot.yml

@@ -23,9 +23,15 @@ services:
       TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:?set TELEGRAM_BOT_TOKEN}
       TELEGRAM_GAME_CHANNEL_ID: ${TELEGRAM_GAME_CHANNEL_ID:-}
       TELEGRAM_CHAT_ID: ${TELEGRAM_CHAT_ID:-}
+      # Support relay: a private forum supergroup the bot relays direct user messages
+      # into (one topic per user). 0/unset disables it; the bot needs admin there with
+      # the manage-topics and delete-messages rights.
+      TELEGRAM_SUPPORT_CHAT_ID: ${TELEGRAM_SUPPORT_CHAT_ID:-}
+      TELEGRAM_SUPPORT_STATE_DIR: /data
       TELEGRAM_PROMO_BOT_TOKEN: ${TELEGRAM_PROMO_BOT_TOKEN:-}
       TELEGRAM_BOT_USERNAME: ${TELEGRAM_BOT_USERNAME:-}
       TELEGRAM_BOT_LINK: ${TELEGRAM_BOT_LINK:-}
+      TELEGRAM_PROMO_START_PARAM: ${TELEGRAM_PROMO_START_PARAM:-}
       TELEGRAM_MINIAPP_URL: ${TELEGRAM_MINIAPP_URL:?set TELEGRAM_MINIAPP_URL}
       # Real Bot API in prod (the test contour pins TELEGRAM_TEST_ENV=true instead).
       TELEGRAM_TEST_ENV: "false"
@@ -46,8 +52,13 @@ services:
       GOMAXPROCS: "1"
     volumes:
       - ${SCRABBLE_CONFIG_DIR:-.}/certs:/certs:ro
+      # Support relay state (topic mapping, block list); survives redeploys.
+      - bot-state:/data
     deploy:
       resources:
         limits:
           cpus: "1.0"
           memory: 256M
+
+volumes:
+  bot-state:

deploy/docker-compose.prod.yml

@@ -3,7 +3,7 @@
 #
 # It (1) publishes caddy 80/443 — there is no host caddy in prod, so the contour caddy
 # owns the edge and does its own ACME on CADDY_SITE_ADDRESS — and the gateway bot-link
-# :9443 the remote bot dials in over mTLS; and (2) retunes the R7 limits down for the
+# :9443 the remote bot dials in over mTLS; and (2) retunes the baseline limits down for the
 # 2 vCPU / 1.9 GiB host (GOMAXPROCS=2, smaller memory caps, shorter Prometheus
 # retention). The contour launches deliberately undersized at zero players; the added
 # node_exporter + Grafana watch host memory so it can be resized at Selectel when
@@ -29,7 +29,7 @@ services:
     ports:
       - "9443:9443"
     environment:
-      # 2 vCPU host: align the Go scheduler with the cgroup quota (R7's 3 needs 3 cores).
+      # 2 vCPU host: align the Go scheduler with the cgroup quota (the baseline's 3-core gateway needs 3 cores).
       GOMAXPROCS: "2"
     deploy:
       resources:

deploy/docker-compose.yml

@@ -25,9 +25,9 @@
 #     backend admin relay reaches the gateway at `gateway:9092` (plaintext).
 name: scrabble
 
-# Bound every container's json-file logs. R7 measured the backend emitting a
+# Bound every container's json-file logs. The backend emits a per-request latency
-# per-request latency line at info (~14 MiB / 30 min under the 500-player stress
+# line at info (~14 MiB / 30 min under the 500-player peak); without rotation the
-# peak); without rotation the volume grows unbounded. 10 MiB x 3 files caps each
+# volume grows unbounded. 10 MiB x 3 files caps each
 # container at 30 MiB. Applied to every service via the *default-logging alias.
 x-logging: &default-logging
   driver: json-file
@@ -52,8 +52,8 @@ services:
       retries: 30
     volumes:
       - postgres-data:/var/lib/postgresql/data
-    # R7 starting limits: 512M leaves headroom over the default 128 MB shared_buffers +
+    # 512M leaves headroom over the default 128 MB shared_buffers + per-connection
-    # per-connection memory (R2 peaked at 28 backends / 69 MiB RSS); tighten after the run.
+    # memory (the load harness peaked at 28 backends / 69 MiB RSS).
     deploy:
       resources:
         limits:
@@ -68,9 +68,11 @@ services:
       context: ..
       dockerfile: backend/Dockerfile
       args:
-        # Seed dictionary for a FRESH volume; the per-contour value comes from the
+        # Seed dictionary for a FRESH volume; required (no default) so the release tag is
-        # deploy env (Gitea TEST_/PROD_DICT_VERSION). See the volume note below.
+        # set in exactly one place per context — the deploy env (Gitea TEST_/PROD_DICT_VERSION)
-        DICT_VERSION: ${DICT_VERSION:-v1.2.1}
+        # or .env for local builds. See the volume note below + deploy/README.md "Bumping the
+        # dictionary version".
+        DICT_VERSION: ${DICT_VERSION:?set DICT_VERSION — the scrabble-dictionary release tag, e.g. in deploy/.env}
         # Build version stamped into the binary (git tag; see pkg/version).
         VERSION: ${APP_VERSION:-dev}
     restart: unless-stopped
@@ -81,8 +83,8 @@ services:
     environment:
       # search_path=backend matches the migrations (00001 creates the schema).
       BACKEND_POSTGRES_DSN: postgres://${POSTGRES_USER:-scrabble}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-scrabble}?sslmode=disable&search_path=backend
-      # R7 tuned: the pool sat at its 25-conn cap (28 backends total) at 500 players;
+      # The pool caps at 25 conns (~28 backends) around 500 players; 40 gives headroom
-      # 40 gives headroom for bursts. Postgres (2 cores / 512 MiB) handles it.
+      # for bursts. Postgres (2 cores / 512 MiB) handles it.
       BACKEND_POSTGRES_MAX_OPEN_CONNS: "40"
       BACKEND_HTTP_ADDR: ":8080"
       BACKEND_GRPC_ADDR: ":9090"
@@ -111,8 +113,8 @@ services:
       - dawg-data:/opt/dawg
     # No container healthcheck: the distroless image has no shell/wget. Readiness
     # is covered by the CI post-deploy probe (GET / through caddy).
-    # R7 starting limits (generous over the R2 ~1-core / <=100 MiB peak); tightened to
+    # Generous over the ~1-core / <=100 MiB measured peak; the prod overlay trims these
-    # the agreed prod values after the final stress run. deploy.resources.limits is
+    # to the launch-host values. deploy.resources.limits is
     # honoured by `docker compose up` (Compose v2), not only by swarm.
     deploy:
       resources:
@@ -175,7 +177,7 @@ services:
     # deploy/gen-certs.sh for the test contour; supplied from PROD_ secrets in prod.
     volumes:
       - ${SCRABBLE_CONFIG_DIR:-.}/certs:/certs:ro
-    # R7 tuned: the gateway holds one h2c connection per player, so at 500 players it
+    # The gateway holds one h2c connection per player, so at 500 players it
     # bursts into a 2-core cap (~2.49% transport_error on game.state); 3 cores absorbs
     # the bursts. Per-connection overhead is the realistic prod cost — size for it.
     deploy:
@@ -290,6 +292,11 @@ services:
       # only restricts (mutes the ineligible) — and the bot must be an admin there with the
       # "Ban users" right; chat_member updates are delivered only to a chat admin.
       TELEGRAM_CHAT_ID: ${TELEGRAM_CHAT_ID:-}
+      # The private forum supergroup the bot relays direct user messages into (one topic
+      # per user) and reads operator replies from. Empty disables the support relay; when
+      # set the bot must be an admin there with the manage-topics and delete-messages rights.
+      TELEGRAM_SUPPORT_CHAT_ID: ${TELEGRAM_SUPPORT_CHAT_ID:-}
+      TELEGRAM_SUPPORT_STATE_DIR: /data
       # The optional standalone promo bot (its own token) answering /start with a button
       # into the main bot's app. Empty disables it; when set it needs the main bot's
       # @username and the Mini App link (reused from the UI's VITE_TELEGRAM_LINK).
@@ -323,6 +330,8 @@ services:
       GOMAXPROCS: "1"
     volumes:
       - ${SCRABBLE_CONFIG_DIR:-.}/certs:/certs:ro
+      # Support relay state (topic mapping, block list); survives redeploys.
+      - bot-state:/data
     deploy:
       resources:
         limits:
@@ -402,8 +411,8 @@ services:
     volumes:
       - ${SCRABBLE_CONFIG_DIR:-.}/tempo/tempo.yaml:/etc/tempo/tempo.yaml:ro
       - tempo-data:/var/tempo
-    # R7 tuned: tempo reached the 1 GiB cap during the final run (446 MiB in R2);
+    # Tempo reached the 1 GiB cap under sustained load (446 MiB in earlier runs);
-    # raised to 2 GiB for headroom against OOM under sustained tracing load.
+    # raised to 2 GiB for headroom against OOM.
     deploy:
       resources:
         limits:
@@ -494,3 +503,4 @@ volumes:
   prometheus-data:
   tempo-data:
   grafana-data:
+  bot-state:

deploy/grafana/dashboards/resources.json

@@ -36,7 +36,21 @@
       "type": "stat",
       "title": "Database size",
       "gridPos": { "h": 5, "w": 6, "x": 18, "y": 0 },
-      "fieldConfig": { "defaults": { "unit": "bytes" }, "overrides": [] },
+      "fieldConfig": {
+        "defaults": {
+          "unit": "bytes",
+          "color": { "mode": "thresholds" },
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "yellow", "value": 8589934592 },
+              { "color": "red", "value": 17179869184 }
+            ]
+          }
+        },
+        "overrides": []
+      },
       "datasource": { "type": "prometheus", "uid": "prometheus" },
       "targets": [{ "refId": "A", "expr": "max(pg_database_size_bytes{datname=\"scrabble\"})" }]
     },

deploy/prod-deploy.sh

@@ -74,7 +74,13 @@ health_running() { # health_running <container>: running, not restarting, stable
 roll() { # roll <service> <health-cmd...>
   local svc="$1"; shift
   echo ">>> rolling $svc -> $TAG"
-  dc up -d --no-build --no-deps "$svc" || return 1
+  # caddy's image is pinned (caddy:2-alpine, no $TAG) and its Caddyfile is bind-mounted, so a
+  # config-only change leaves the compose definition unchanged: `up -d` treats the container as
+  # current and does not recreate it, and admin is off so there is no hot reload — the new
+  # Caddyfile would never load. Force a recreate for caddy so config changes always apply; every
+  # other service already recreates on its new $TAG image.
+  local recreate=(); [ "$svc" = caddy ] && recreate=(--force-recreate)
+  dc up -d --no-build --no-deps "${recreate[@]}" "$svc" || return 1
   "$@" || { echo "!!! $svc failed health check"; return 1; }
   echo "<<< $svc healthy"
 }

docs/ARCHITECTURE.md

@@ -2,10 +2,8 @@
 
 Source of truth for the platform architecture, transport, security model and
 cross-service contracts. User-visible behaviour per domain lives in
-[`FUNCTIONAL.md`](FUNCTIONAL.md); the staged build order lives in
+[`FUNCTIONAL.md`](FUNCTIONAL.md). This document always describes the **current**
-[`../PLAN.md`](../PLAN.md). This document always describes the **current**
+design, not the history of how it was reached.
-design, not the history of how it was reached. Sections describing
-not-yet-implemented components are marked *(planned)*.
 
 ## 1. Overview
 
@@ -44,7 +42,12 @@ Three executables plus per-platform side-services:
   users, a weighted fair rotation — §10),
   and a client **board-style** setting (bonus-label
   mode). The visual/interaction design system is documented in
-  [`UI_DESIGN.md`](UI_DESIGN.md).
+  [`UI_DESIGN.md`](UI_DESIGN.md). Inside the Telegram Mini App the client additionally
+  tracks Telegram's live theme switch (`themeChanged`), fits the full device safe-area
+  insets (the bottom/home-indicator strip taking the bottom bar's colour), exposes
+  Telegram's native **Settings** button into the in-app settings, and syncs the
+  device-independent display preferences (theme, reduce-motion, board labels — **not** the
+  interface language) across the user's Telegram devices via **CloudStorage**.
 - **`platform/telegram`** — the Telegram side-service (module
   `scrabble/platform/telegram`), split into two binaries that share the bot token
   (**one bot**, one optional game channel, §3):
@@ -154,13 +157,19 @@ arrive from a platform rather than completing a mandatory registration).
 - **Single bot.** The platform side-service runs **one bot** (one token + one optional
   game channel), split into a home **validator** and a remote **bot** that share the
   token. `ValidateInitData` (the validator) validates `initData` against that single
-  token and returns only the Telegram user identity — there is no per-bot "service
+  token, **rejects a bot user** (the signed `is_bot` flag), and returns only the Telegram
+  user identity — there is no per-bot "service
   language" and no supported-languages set on the wire. The bot's chat messages and
   out-of-app push are
   rendered in the recipient's **interface language** (`preferred_language`, en/ru), not in
   any bot-scoped language, and the friend-invite **share link** (and its caption) point at
   that one bot. First Telegram contact seeds the new account's `preferred_language` from the
-  launch `language_code` (§4); the interface language is otherwise edited in Settings.
+  launch `language_code` (§4), but the **interface language follows the device** — the system
+  guess, or an explicit Settings choice saved locally — and the bot never dictates the UI.
+  `preferred_language` is then **reconciled to the active interface locale on every session
+  adopt** (not only on a Settings change; a no-op for guests and when already equal), so the
+  server-rendered language surfaces — this push and the ad banner — always match the UI rather
+  than stranding a user who never opened Settings on the creation-time seed.
 - **Variant preferences (New Game gating).** Which variants a player may be matched into is a
   per-user **profile** setting — `variant_preferences`, a set of `engine.Variant` labels
   (`scrabble_en`, `scrabble_ru`, `erudit_ru`) edited on the Settings/Profile screen. New
@@ -201,7 +210,7 @@ arrive from a platform rather than completing a mandatory registration).
 > recipient's interface language (`preferred_language`), with no per-bot routing. New
 > Game variant gating moved off the login language onto a per-user profile setting
 > `variant_preferences` (default Erudit only, server-enforced on the caller's create
-> paths; an invited friend may still accept any variant). The per-bot env vars and
+> paths; an invited friend may still accept any variant, and a Telegram **promo deep-link** seeds extra variants — e.g. English Scrabble — onto a brand-new account via the validated `start_param`). The per-bot env vars and
 > `GATEWAY_DEFAULT_SUPPORTED_LANGUAGES` were removed; the wire dropped
 > `service_language`/`supported_languages` and the push `language` routing field, and
 > gained `variant_preferences` on Profile/UpdateProfile.
@@ -642,7 +651,7 @@ in either direction (the enqueue excludes the caller's `BlockedWith` set);
   **floats games with any unread entry to the top** of the your-turn and opponent-turn
   sections (the finished section keeps its activity order). On each clear the publish-to-read
   latency is recorded; the read time itself is not retained.
-- **Profile**: `preferred_language` (en/ru, edited in Settings), display name, email
+- **Profile**: `preferred_language` (en/ru; tracks the interface language — §4), display name, email
   (confirm-code binding, see §4), **timezone**, the daily **away window**, the
   **variant preferences** (`variant_preferences`, the matchable-variant set that gates New
   Game — §3, defaulting to Erudit only, at least one enforced) and the
@@ -651,7 +660,11 @@ in either direction (the enqueue excludes the caller's `BlockedWith` set);
   separators (no leading/trailing/adjacent separators, ≤ 32 runes); the timezone is a
   fixed `±HH:MM` **UTC offset** (or a legacy IANA name) resolved by `account.ResolveZone`
   for the sweeper and the robot's sleep (a fixed offset trades DST for a simple
-  picker); the away window is at most **12 h** (midnight-wrap aware). Linked platform
+  picker), and is **seeded at account creation** from the client's detected offset — sent
+  on the Telegram / guest / email first-contact request — so the robot's sleep and the
+  away-window sweeper are anchored to the player's real zone from the first game rather
+  than the `UTC` default (an undetected or malformed offset keeps the default); the away
+  window is at most **12 h** (midnight-wrap aware). Linked platform
   accounts and merge are covered in §4.
 
 ## 9. Persistence
@@ -965,7 +978,7 @@ edits take effect on the next `profile.get` (open/reconnect/foreground), not mid
 | Concern | Enforced by |
 | --- | --- |
 | Public rate limiting / anti-abuse | gateway (per-IP public/email/admin classes, per-user authenticated class; a request body cap of `GATEWAY_MAX_BODY_BYTES`; rejections are metered, summarised to the backend and surfaced in the admin console with a conservative reversible auto-flag — §11). In prod a **temporary IP ban** (`GATEWAY_ABUSE_BAN_ENABLED`) blocks an IP that sustains rejections or trips a **honeypot** decoy path / **honeytoken**, refused with 429 before any work; operators lift bans from the console. Off in the shared-NAT test contour, where the client IP is not real (§11) |
-| Telegram initData validation (bot-token HMAC) | the Telegram **validator**; the gateway delegates it over gRPC, so the bot token (the HMAC secret) lives only in the validator and the bot, never in the gateway |
+| Telegram initData validation (bot-token HMAC) | the Telegram **validator**; the gateway delegates it over gRPC, so the bot token (the HMAC secret) lives only in the validator and the bot, never in the gateway. The validator also **rejects a bot principal** (the signed `is_bot` flag) before any account is provisioned |
 | Session minting; email-code / guest validation | gateway (with backend) |
 | Session → `user_id` resolution, `X-User-ID` injection | gateway |
 | Authorisation, ownership, state transitions | backend (`X-User-ID` is the sole identity input) |
@@ -1033,8 +1046,9 @@ a dedicated redeem sub-limit or a longer code is the hardening step if abuse app
 Single public origin, path-routed. The Vite build has two entries: a lightweight
 **landing page** and the game **SPA**. The gateway **embeds** the SPA build
 (`go:embed`, baked in by a node stage in `gateway/Dockerfile`) and serves it at
-`/app/` (web) and `/telegram/` (the Telegram Mini App; outside Telegram that path
+`/app/` (web) and `/telegram/` (the Telegram Mini App; on that path without sign-in data
-redirects to the root — the client-side guard); a stray hit on the gateway's `/`
+— no `initData` — the client renders a compact, shareable launch-diagnostic screen instead
+of redirecting away); a stray hit on the gateway's `/`
 308-redirects to `/app/`. The **landing** ships in its own static container: the
 `landing` target of `gateway/Dockerfile` (caddy:2-alpine + the same Vite build,
 `deploy/landing/Caddyfile`) serves it at `/`, so stray public traffic is absorbed by
@@ -1091,7 +1105,10 @@ Two contours, two secret/variable prefixes (`TEST_` / `PROD_`):
   the **main host** runs the full stack (`docker-compose.yml` + `docker-compose.prod.yml`),
   the **bot host** runs only the bot (`docker-compose.bot.yml`, no VPN — native Bot API
   egress, telemetry off). There is no host caddy, so the contour caddy terminates TLS —
-  `CADDY_SITE_ADDRESS` is the domain and caddy does its own ACME. The gateway **publishes**
+  `CADDY_SITE_ADDRESS` is the domain and caddy does its own ACME. Caddy advertises HTTP/3 by default, but UDP/443 is not exposed (the
+  compose maps only TCP and ufw opens 443/tcp), so the edge emits `Alt-Svc: clear` to keep
+  clients on h2/h1 rather than stall on a dead QUIC path — see [`EDGE_HTTP3.md`](EDGE_HTTP3.md).
+  The gateway **publishes**
   the bot-link `:9443`; the remote bot dials it over mTLS (certs from `PROD_BOTLINK_*`,
   ServerName `gateway`, so TLS validation is independent of the public dial address), holds
   no inbound port, and login is unaffected if that host or the link is down.
@@ -1107,7 +1124,7 @@ Two contours, two secret/variable prefixes (`TEST_` / `PROD_`):
   **`prod-rollback`** workflow re-deploys any prior release tag (blank input = the previous
   deployed version, tracked on the host) over the same rolling, health-gated path — image-only,
   no DB migration. The main host is
-  intentionally **launch-sized** (2 vCPU / 1.9 GiB): the prod overlay trims the R7 limits
+  intentionally **launch-sized** (2 vCPU / 1.9 GiB): the prod overlay trims the baseline limits
   (`GOMAXPROCS=2`, smaller caps, 7d Prometheus retention) and a **node_exporter** feeds
   host-memory metrics to Grafana so it can be resized reactively as players arrive.
   `GATEWAY_ABUSE_BAN_ENABLED=true` in prod (the per-IP ban is meaningful only with real
@@ -1151,9 +1168,11 @@ Two contours, two secret/variable prefixes (`TEST_` / `PROD_`):
 
 Players reach the operators through a **Feedback** screen (Settings → Info, registered accounts
 only). A message (≤1024 runes) plus an optional single attachment is stored in
-`feedback_messages`; the sender's IP (gateway-forwarded, as for chat) and the submitting
+`feedback_messages`; the sender's IP (gateway-forwarded, as for chat), the submitting
-**channel** (telegram/ios/android/web, client-reported and validated) are recorded. The domain
+**channel** (telegram/ios/android/web, client-reported and validated), the **client app version**
-is `internal/feedback` (store + service), modelled on the admin chat-moderation surface.
+(`__APP_VERSION__`, the build a report was sent from), the client's **detected UTC offset** at
+submit (`browser_tz`, `±HH:MM`) and a snapshot of the sender's interface language are recorded. The domain is `internal/feedback` (store + service), modelled on the admin
+chat-moderation surface.
 
 **Anti-spam.** A player with an unreviewed message (`read_at IS NULL`) cannot submit another; the
 gate is server-side. Because the operator must act before the next message, this is itself the
@@ -1161,8 +1180,11 @@ rate limit — there is no separate per-user feedback limiter.
 
 **Operator review** happens in the server-rendered console (`/_gm/feedback`): an
 unread / read / archived queue with per-user search (the `/users` glob masks), a detail card
-(user content rendered as auto-escaped `html/template` text), and the read / reply / archive /
+(user content rendered as auto-escaped `html/template` text; it shows the channel, interface
-delete / delete-all actions — each marks the message read; merely opening the detail does not.
+language and app version, and the filed time in three zones — UTC, the browser offset detected at
+submit, and the sender's saved profile zone, each `N/A` when not known), and the read /
+reply / archive / delete / delete-all actions — each marks the message read; merely opening the
+detail does not.
 The attachment is served from `/_gm/feedback/:id/attachment` with `X-Content-Type-Options:
 nosniff`: images inline (loaded only via `<img>`, which never executes — a renamed non-image is
 inert), everything else as an `application/octet-stream` download. The UI gates the attachment by
@@ -1184,3 +1206,27 @@ blocks **only** feedback submission (unlike a suspension, the whole-account bloc
 granted from the feedback section (the delete-with-block checkbox) and granted/revoked from the
 `/users` console card. Roles are validated against a known set in Go, so adding one needs no
 migration.
+
+**Telegram support relay.** Separate from the in-app Feedback above, the bot offers a direct
+support channel for users who message it on Telegram. Any message other than `/start` is relayed
+into a private **forum supergroup** (`TELEGRAM_SUPPORT_CHAT_ID`): a user's first message opens a
+dedicated **forum topic** whose first message is an info card (the name is a tappable profile
+mention via a `text_mention` entity — which also keeps a name beginning with `/` from being read as
+a command — plus @username, language, premium, id) carrying a Block/Unblock toggle and a Clear
+button; every message is then
+copied into that topic (`copyMessage`, so any content — text, media, voice, files — carries over).
+Any **administrator** of the support chat who writes in a user's topic has their message copied
+back to that user; non-admins and the bot's own posts are ignored (the loop guard). Block drops the
+user's incoming messages (the topic stays); Clear deletes the relayed messages, keeping the info
+card; a topic the operators delete is reopened on the next message. State (user→topic map, block
+list, relayed message ids) is a small JSON file on a writable volume — the bot host has no database
+and cannot reach Postgres. The relay is **bot-local**: it touches neither the backend, the gateway,
+nor `feedback_messages`. The bot must be an administrator in the forum group with the manage-topics
+and delete-messages rights.
+
+> **Decision (2026-06-23) — bot-local support relay over forum topics.** The direct Telegram
+> support channel lives entirely in the bot (no backend, no bot-link command), because the bot host
+> has no database. One forum **topic per user** (not a reply-to-header thread) gives native per-user
+> separation and survives message deletion; the topic id, not a fragile header message, anchors the
+> mapping. Operators are the support chat's administrators (no separate owner id); messages relay
+> both ways with `copyMessage`. State persists as JSON on a dedicated volume.

docs/EDGE_HTTP3.md

@@ -0,0 +1,111 @@
+# Edge HTTP/3 (`Alt-Svc`) policy
+
+## TL;DR
+
+The edge **advertises HTTP/3 but does not actually serve it** (UDP/443 is not exposed),
+so we suppress the advert with `Alt-Svc: clear`. Advertising QUIC on `:443/udp` while
+that port is unreachable makes clients — notably the Telegram Mini App webview — stall
+on a dead QUIC connection before falling back to h2, which shows up as the app "hanging
+on load".
+
+## Symptom
+
+Opening the Mini App intermittently hangs on load: from a barely-noticeable pause to
+several seconds, sometimes a blank window that never finishes downloading `index.html`.
+Intermittent, worse after the first successful visit, reproduced on both the test
+contour and prod.
+
+## Root cause
+
+Caddy enables HTTP/3 by default on any TLS listener and emits
+`Alt-Svc: h3=":443"; ma=2592000` — telling every client "reach me over QUIC/UDP 443"
+and to cache that for 30 days. But UDP/443 is **never reachable end to end**:
+
+- **Test contour**: the host caddy publishes only `:443/tcp` (`docker port caddy` shows
+  no `udp`); QUIC packets from the internet are dropped.
+- **Prod**: `deploy/docker-compose.prod.yml` maps `"443:443"` (Docker = **TCP only**)
+  and `deploy/ansible/roles/main/tasks/main.yml` opens 443 `proto: tcp`. UDP/443 is
+  dropped at both the publish and the firewall.
+
+Caddy *does* bind `udp/443` inside the container and h3 works container-to-container
+(verified `http=3 code=200`), so the listener is healthy — it is simply not exposed.
+
+A client that cached the advert tries QUIC first on later opens, gets no response, and
+waits for the QUIC attempt to time out before falling back to TCP/h2. That wait is the
+stall. The very first visit (no cached `Alt-Svc`) uses h2 and is fast.
+
+The h2/TCP serving path itself is healthy: 30 fresh-TLS requests through the full path
+(host caddy -> contour caddy -> gateway) measured TTFB ~9.5 ms, total ~9.8 ms, no tail;
+`index.html` is ~1 KB.
+
+## Fix in place (option A — suppress the advert)
+
+Emit `Alt-Svc: clear`, which actively drops any cached alternative (better than merely
+deleting the header, which leaves the sticky 30-day cache in place):
+
+- **Prod / repo**: `deploy/caddy/Caddyfile` — a site-level `header Alt-Svc clear` (this
+  caddy terminates TLS in prod).
+- **Test contour**: the host caddy terminates TLS, so the fix lives there (homelab
+  config, outside this repo): `header Alt-Svc clear` on the `scrabble.*` site. The
+  in-compose caddy serves plain `:80` in test and never advertises h3, so the repo
+  directive is a harmless no-op there (the host caddy re-stamps the header).
+
+`header Alt-Svc clear` overrides Caddy's auto-advert (verified) and is site-scoped.
+
+### Verify
+
+The runner/prod host shell cannot reach the Docker bridge IPs directly, so probe from a
+container on the relevant network, using `--resolve` to hit the TLS-terminating caddy by
+its bridge IP (this also bypasses the public-IP NAT hairpin):
+
+```sh
+# <edge-ip> = the TLS-terminating caddy's IP on its network (docker inspect ... )
+docker run --rm --network edge curlimages/curl:latest -sS -D - -o /dev/null \
+  --resolve <host>:443:<edge-ip> https://<host>/telegram/ | grep -iE '^HTTP|^alt-svc'
+# expect: HTTP/2 200, and NO `alt-svc: h3=...` (the header is absent or `alt-svc: clear`)
+```
+
+## If it recurs — alternatives to try
+
+So we do not re-derive the diagnosis from scratch:
+
+1. **Re-confirm the advert is actually suppressed** with the verify command above. A
+   redeploy or a Caddy upgrade could regress it, or a client may still hold a cached
+   `h3` entry that has not yet been replaced by a `clear` (it needs one successful h2
+   response to receive the `clear`).
+2. **Option B — serve HTTP/3 for real** instead of suppressing it. Worth it only if we
+   actually want QUIC (the benefit is marginal for a ~1 KB shell plus hash-immutable
+   cached assets, and it adds UDP/QUIC attack surface):
+   - Publish UDP: add `"443:443/udp"` next to the TCP map in
+     `deploy/docker-compose.prod.yml` (and publish udp/443 on the test host caddy too).
+   - Open the firewall: add a `443 proto: udp` rule in
+     `deploy/ansible/roles/main/tasks/main.yml`.
+   - Drop the `header Alt-Svc clear` so Caddy advertises h3 again.
+   - Verify with an h3 client from inside the network:
+     `docker run --rm --network edge ymuski/curl-http3 curl --http3-only ...` should
+     return `http=3 code=200`.
+3. **Look past the edge** if the advert is suppressed and stalls persist. The h2 path is
+   fast server-side, so a remaining stall is most likely the client network / RTT / the
+   provider, not our stack. Re-run the timing loop (below) to confirm the server is
+   still <~10 ms TTFB before chasing the client side.
+
+## How this was diagnosed (method, to repeat)
+
+- The runner/prod host shell cannot reach the Docker bridge subnets, so all probing runs
+  from a throwaway container on the target network (`docker run --network <net>
+  curlimages/curl`), using `--resolve <host>:443:<edge-ip>` to bypass the public-IP NAT
+  hairpin and exercise the real TLS path.
+- Compare a fresh-connection timing loop (worst case, full TLS each time) against a
+  keepalive batch to separate handshake cost from serving cost:
+
+  ```sh
+  docker run --rm --network edge curlimages/curl:latest sh -c '
+    for i in $(seq 1 30); do
+      curl -sS -o /dev/null --resolve <host>:443:<edge-ip> \
+        -w "http=%{http_version} code=%{http_code} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" \
+        https://<host>/telegram/
+    done'
+  ```
+
+- `docker port <caddy>` shows whether `udp/443` is actually published; the response
+  `Alt-Svc` header shows what the edge advertises. The two disagreeing is the bug.

docs/FUNCTIONAL.md

@@ -30,7 +30,8 @@ A player arrives from a platform (Telegram first), via email login, or as an
 ephemeral guest. The gateway validates the credential once and mints a thin
 session token; the backend resolves it to an internal `user_id`. A **Telegram Mini
 App** launch authenticates from the platform's signed `initData`, themes the UI to
-the Telegram colours, and — on first contact — seeds the new account's interface
+the Telegram colours (re-theming live if you switch Telegram's light/dark mode) and fits
+the device safe-area, and — on first contact — seeds the new account's interface
 language from the Telegram client. If a launch cannot reach the backend (for example during a
 deployment), the Mini App retries quietly and then shows a small "couldn't load" screen with a
 **Retry** button, rather than dropping to the web sign-in, which has no place inside Telegram.
@@ -213,6 +214,9 @@ block **overrides but does not delete** an existing friendship (so you may block
 they keep seeing you as one); active games are never interrupted — you can finish them, with
 the blocked opponent's chat composer hidden (only the log remains). Blocking from a game card
 mirrors the block in **Settings → Friends**; **unblock** and **unfriend** live there only.
+On Settings → Friends each friend is a one-line row whose right-hand kebab (⋮) slides open
+**block 🚫** and **remove ✖️** icon actions, and each action is gated by a confirmation
+that names the friend (*Block this player?* / *Remove from friends?*).
 Blocking an **auto-match opponent who is secretly a robot** behaves the same in that game
 (struck name, hidden composer) and lists the blocked opponent under the name you saw, but is
 recorded only against that game — the disguise holds, the shared robot is never globally
@@ -241,16 +245,21 @@ also clears the moment its recipient **takes their move**.
 Edit the display name (letters joined by a single space / "." / "_" separator, with an
 optional trailing "." or a trailing run of up to five digits, up to 32 characters and at most
 5 special characters — the "." / "_" punctuation, spaces and digits aside), the timezone
-(chosen as a UTC offset), the
+(chosen as a UTC offset, and pre-filled from your device's detected offset when the account
+is first created — so robot games are timed correctly before you ever open this form), the
 daily away window (on a 10-minute grid, at most 12 hours, wrapping midnight) and the
 block toggles. The profile form is edited inline (no separate edit mode). Linking
 an email or Telegram and merging accounts are covered under "Accounts, linking &
-merge".
+merge". Inside the Telegram Mini App, Telegram's own ⋮ menu also offers a **Settings**
+entry that opens this screen, and your display preferences (theme, board-label style and
+reduce-motion — not the interface language, which follows your account) sync across your
+Telegram devices.
 
 **Preferences (which variants you can be matched into).** A profile setting picks the game
 variants — Erudite, Russian Scrabble and English Scrabble, shown **Erudite-first** — you allow
-yourself to be matched into; a **new account starts with Erudite only**, and you must keep **at
+yourself to be matched into; a **new account starts with Erudite only** — unless it was created
-least one** selected. This list is exactly what **New Game** offers when you start a game
+through the **promo bot's deep link**, which also enables **English Scrabble** — and you must keep
+**at least one** selected. This list is exactly what **New Game** offers when you start a game
 (auto-match, an AI game, or a friend invitation you create) — a variant you have not enabled is
 not offered, and the server refuses it. It does not restrict games you are **invited** to: an
 invited friend may accept an invitation in **any** variant, and you can always open and play
@@ -268,6 +277,15 @@ marked read once the screen shows it and disappears a week later. A badge on the
 unanswered reply. Guests cannot send feedback (the entry is hidden). A player the operator has
 barred from feedback (a role, not a full account block) sees the send control disabled.
 
+### Telegram support chat
+A user can also reach the operators straight from the Telegram bot: anything they send the bot
+other than `/start` — text, a photo, a voice message, a file — is forwarded into the operators'
+private support group, grouped into a per-user thread. The user sees no automatic reply; an
+operator answers from that thread and the bot delivers the answer back as an ordinary bot message,
+so to the user it is a quiet one-to-one conversation. Operators can block a user (the bot then
+silently ignores their messages) or clear a thread's messages. This is independent of the in-app
+Feedback above — it serves people who write to the bot directly rather than through the app.
+
 ### History & statistics
 Finished games are archived in a dictionary-independent form and exportable to
 GCG; the export is offered **only once a game is finished**, and never for an
@@ -346,7 +364,9 @@ over-grant cannot be reversed there.
 The console works a **feedback** queue too (`/_gm/feedback`): the messages players sent, filtered
 **unread / read / archived** with per-user search, each shown with its sender, source, channel
 (with the bot language — en/ru — for a Telegram message), the sender's interface
-language, IP and any attachment. The operator can mark a message read, **reply** to the player (delivered
+language, the **app version** it was sent from, IP, the filed time (in three zones — UTC, the
+browser zone detected at submit, and the sender's saved zone, each shown `N/A` when not known) and
+any attachment. The operator can mark a message read, **reply** to the player (delivered
 in-app), archive it, delete it, or delete every message from that player — and, alongside a delete,
 **bar the player from feedback** (a `feedback_banned` role, distinct from a full account block: it
 stops only feedback submission). Roles are listed and granted/revoked on the user card. Opening a

docs/FUNCTIONAL_ru.md

@@ -31,7 +31,9 @@ top-1 подсказку, безлимитную проверку слова с
 эфемерный гость. Gateway один раз валидирует доступ и выдаёт тонкий
 session-токен; backend сопоставляет его с внутренним `user_id`. Запуск **Telegram
 Mini App** авторизует по подписанным `initData` платформы, перекрашивает интерфейс
-в цвета Telegram и — при первом контакте — задаёт язык интерфейса нового аккаунта по
+в цвета Telegram (перекрашиваясь вживую при смене светлой/тёмной темы Telegram) и
+вписывается в безопасные зоны экрана (safe-area), а — при первом контакте — задаёт язык
+интерфейса нового аккаунта по
 языку Telegram-клиента. Если запуск не может достучаться до бэкенда (например, во время
 деплоя), Mini App тихо повторяет попытки, а затем показывает небольшой экран «не удалось
 загрузить» с кнопкой **Повторить**, вместо того чтобы сбрасывать на веб-вход, которому внутри
@@ -218,6 +220,9 @@ _Вход сейчас только через провайдера, поэто
 заблокированного соперника «подвал» чата скрыт (остаётся только лог). Блокировка с карточки в
 партии повторяет блокировку в **Настройках → Друзья**; **разблокировка** и **удаление из друзей**
 есть только там.
+В **Настройках → Друзья** каждый друг — однострочник, чей правый кебаб (⋮) выдвигает
+иконки-действия **заблокировать 🚫** и **удалить ✖️**, и каждое действие подтверждается
+диалогом с именем друга (*Заблокировать?* / *Удалить из друзей?*).
 Блокировка **авто-матч соперника, который втайне робот**, в этой партии ведёт себя так же
 (зачёркнутое имя, скрытый «подвал») и в списке заблокированных показывается под тем именем,
 которое ты видел, но записывается только для этой партии — маскировка сохраняется, общий
@@ -248,15 +253,21 @@ _Вход сейчас только через провайдера, поэто
 Редактирование отображаемого имени (буквы, разделённые одиночным пробелом / «.» /
 «_», с необязательной завершающей «.» или хвостом до пяти цифр, до 32 символов и не
 более 5 спецсимволов — пунктуации «.» / «_», пробелы и цифры не в счёт), таймзоны (выбор смещения от
-UTC), суточного окна отсутствия (away; сетка по 10 минут, не более 12 часов, с
+UTC; при создании аккаунта она подставляется из определённого смещения устройства — чтобы
-переходом через полночь) и переключателей блокировок. Форма профиля редактируется
+игры с роботом таймились правильно ещё до открытия этой формы), суточного окна отсутствия
+(away; сетка по 10 минут, не более 12 часов, с переходом через полночь) и переключателей блокировок. Форма профиля редактируется
 сразу (без отдельного режима редактирования). Привязка email и Telegram, а также
-слияние аккаунтов вынесены в раздел «Аккаунты, привязка и слияние».
+слияние аккаунтов вынесены в раздел «Аккаунты, привязка и слияние». Внутри Telegram
+Mini App пункт **Settings** в системном меню «⋮» Telegram также открывает этот экран, а
+ваши настройки отображения (тема, стиль подписей клеток и reduce-motion — кроме языка
+интерфейса, который следует за аккаунтом) синхронизируются между вашими устройствами в
+Telegram.
 
 **Предпочтения (в какие варианты тебя можно подбирать).** Настройка профиля задаёт варианты
 игры — Эрудит, русский Scrabble и английский Scrabble, показанные **сначала Эрудит**, — в
-которые ты разрешаешь себя подбирать; **новый аккаунт стартует только с Эрудитом**, и нужно
+которые ты разрешаешь себя подбирать; **новый аккаунт стартует только с Эрудитом** — если только
-оставить выбранным **хотя бы один**. Именно этот список предлагает **Новая игра**, когда ты
+он не создан по **диплинку промо-бота**, который дополнительно включает **английский Scrabble**, —
+и нужно оставить выбранным **хотя бы один**. Именно этот список предлагает **Новая игра**, когда ты
 запускаешь партию (авто-подбор, игра с ИИ или приглашение друга, которое ты создаёшь), — не
 включённый вариант не предлагается, и сервер его отклоняет. На партии, в которые тебя
 **приглашают**, это не влияет: приглашённый друг может принять приглашение в **любом** варианте,
@@ -274,6 +285,15 @@ UTC), суточного окна отсутствия (away; сетка по 10
 ответе. Гость отправлять обратную связь не может (пункт скрыт). Игрок, которому оператор запретил
 обратную связь (роль, а не полная блокировка аккаунта), видит кнопку отправки недоступной.
 
+### Чат поддержки в Telegram
+С операторами можно поговорить и прямо из Telegram-бота: всё, что пользователь присылает боту,
+кроме `/start` — текст, фото, голосовое, файл, — пересылается в закрытую группу поддержки операторов
+и собирается в отдельную ветку на пользователя. Пользователь не получает автоответа; оператор
+отвечает из этой ветки, и бот доставляет ответ обратно обычным сообщением — для пользователя это
+тихий диалог один на один. Операторы могут заблокировать пользователя (тогда бот молча игнорирует
+его сообщения) или очистить сообщения ветки. Это независимо от встроенной «Обратной связи» выше —
+канал для тех, кто пишет боту напрямую, а не через приложение.
+
 ### История и статистика
 Завершённые партии архивируются в независимом от словаря виде и экспортируются
 в GCG; экспорт доступен **только после завершения партии** и никогда — для
@@ -356,7 +376,8 @@ high-rate флага. С карточки пользователя операт
 Консоль ведёт и очередь **обратной связи** (`/_gm/feedback`): присланные игроками сообщения с фильтром
 **непрочитанные / прочитанные / архив** и поиском по пользователю, каждое — с отправителем, источником,
 каналом (и языком бота — en/ru — для сообщения из Telegram), языком интерфейса отправителя,
-IP и вложением. Оператор может пометить сообщение прочитанным, **ответить** игроку (доставка
+**версией приложения**, с которой отправлено, IP, временем подачи (в трёх зонах — UTC, зоне браузера
+на момент отправки и сохранённой зоне отправителя, каждая — «N/A», если неизвестна) и вложением. Оператор может пометить сообщение прочитанным, **ответить** игроку (доставка
 в приложение), отправить в архив, удалить или удалить все сообщения этого игрока — и вместе с удалением
 **запретить игроку обратную связь** (роль `feedback_banned`, отличная от полной блокировки аккаунта:
 останавливает только отправку обратной связи). Роли перечислены и выдаются/снимаются на карточке

docs/TESTING.md

@@ -121,7 +121,7 @@ tests or touching CI.
   Postgres-backed `inttest` drives the **guest reaper** end to end (an abandoned guest is
   reaped; a too-young guest, a seated guest and a durable account are kept).
 - **Load test & resource baseline** — a reusable `loadtest/` module
-  (`scrabble/loadtest`) is the pre-release stress harness. It **seeds** a large account
+  (`scrabble/loadtest`) is the stress/load harness. It **seeds** a large account
   population with pre-created sessions directly in Postgres (token hashes matching
   `backend/internal/session`), **drives** virtual players through the edge protocol —
   real games assembled via invitations, **mid-ranked** legal moves generated locally by
@@ -154,13 +154,12 @@ tests or touching CI.
 - No network or real platform calls in unit tests; validate platform
   credentials behind an interface seam and test with fixtures.
 
-## Per-stage CI gate
+## CI gate
 
-Every completed stage is exercised on `gitea.iliadenisov.ru` before it is marked
+Every change is exercised on `gitea.iliadenisov.ru` before it is merged:
-done in [`../PLAN.md`](../PLAN.md):
 
-1. Commit the stage on its `feature/*` branch.
+1. Commit the change on its `feature/*` branch.
 2. Push to `origin`.
 3. Watch the run to completion — never hand-roll a poll loop:
    `python3 ~/.claude/bin/gitea-ci-watch.py` (launch in the background).
-4. Only after every workflow that fired is green may the stage be marked done.
+4. Only after every workflow that fired is green may the change be merged.

docs/UI_DESIGN.md

@@ -8,7 +8,13 @@ emoji glyphs. Tokens are CSS custom properties (`ui/src/app.css`), light/dark vi
 `prefers-color-scheme` or an explicit Settings choice, and **Telegram-themed**:
 on a Telegram Mini App launch — the app is served under `/telegram/` and detects the
 launch by `Telegram.WebApp.initData` — the SDK's `themeParams` override the tokens at
-runtime; opened outside Telegram, the `/telegram/` path redirects to the site root.
+runtime; on that path without sign-in data (no `initData` — outside Telegram, or a Mini App
+launch that delivered none, as seen on some Android clients) the app renders a compact,
+shareable launch-diagnostic screen (`screens/TelegramLaunchError.svelte`) rather than
+redirecting to the site root. `telegram-web-app.js` is loaded **dynamically with a timeout**,
+only on a Telegram entry — not a render-blocking `<script>` in the shared `index.html` shell —
+so a network that blocks `telegram.org` cannot hang the page; `/app/` (web) and the native build
+never load it.
 
 ## Layout shell (`components/Screen.svelte`)
 
@@ -91,14 +97,16 @@ dismisses as soon as the lobby is ready. The pure layout and timing live in `lib
   which leaks into the Telegram Desktop webview and otherwise fights it) and the Settings
   theme switcher is hidden; the nav bar takes Telegram's background and `setHeaderColor` /
   `setBackgroundColor` / `setBottomBarColor` paint Telegram's own chrome to match; the
-  native header **BackButton** drives back-navigation (the app's chevron is hidden in
+  app's **own back chevron** (Header) drives back-navigation on every platform — the native
-  Telegram); **HapticFeedback** fires on tile placement / commit / error; on **mobile**
+  Telegram BackButton is not used, as it does not render reliably in the windowed Mini App;
-  clients the app enters **immersive fullscreen** on launch (`requestFullscreen`, Bot API
+  **HapticFeedback** fires on tile placement / commit / error; the app calls `expand()` for the
-  8.0+) like Telegram's own Mini Apps, while desktop keeps the bot's full-size window;
+  bot's full-size (max-height) window but **never `requestFullscreen`** — immersive fullscreen hid
-  **closing confirmation** is enabled while a game is open **on mobile only** (on desktop
+  the native header (and its BackButton) and the Android system swipe-back then minimised the app,
-  closing is deliberate and the "changes may not be saved" dialog is just noise — move drafts
+  so it stays windowed with Telegram's thin native header (close) above the app's own header; move
-  auto-save); **vertical swipes** (swipe-to-minimise)
+  drafts auto-save, so there is **no closing-confirmation guard**; a hidden **debug panel** (ten
-  are disabled so they don't fight tile drag or the board scroll; **external links** (the word-check
+  quick taps on the header title) shows and shares a privacy-safe client diagnostic snapshot for
+  support; **vertical swipes** (swipe-to-minimise) are disabled so they don't fight tile drag or
+  the board scroll; **external links** (the word-check
   dictionary lookup, the rules link, operator-reply links) open through `Telegram.WebApp.openLink`
   so Telegram shows them in its in-app browser instead of the WebView's "open this link?"
   confirmation a plain `target=_blank` triggers; and a live stream dropped
@@ -109,7 +117,10 @@ dismisses as soon as the lobby is ready. The pure layout and timing live in `lib
 ## Tiles & board
 
 - **Tiles**: the letter sits in the **top-left** corner (offset a touch more than the
-  value), the point value bottom-right; blanks show no value.
+  value), the point value bottom-right; blanks show no value. In **Erudit** the blank is the
+  "звёздочка" (star) chip: an unplaced blank shows the star (`✻`, U+273B) centred on the rack
+  tile, and a placed blank carries it in the value corner; the Scrabble variants leave the
+  blank unmarked (`usesStarBlank` in `lib/variants.ts`).
 - **Board zoom** (`Board.svelte`): a two-state zoom (full 15×15 ↔ ~9 cells) by **growing
   the board's width** inside a fixed-size viewport (a real layout change → native scroll
   that works consistently across browsers; no `transform`, which broke scrolling

gateway/internal/backendclient/api.go

@@ -184,8 +184,10 @@ type ChatResp struct {
 }
 
 // TelegramAuth provisions/finds the Telegram account and mints a session, seeding a
-// brand-new account's display name and language from the validated launch fields.
+// brand-new account's display name and language from the validated launch fields, its
-func (c *Client) TelegramAuth(ctx context.Context, externalID, languageCode, username, firstName string) (SessionResp, error) {
+// time zone from browserTz (the client's detected "±HH:MM" UTC offset) and, from the
+// validated launch deep-link startParam, its variant preferences (first contact only).
+func (c *Client) TelegramAuth(ctx context.Context, externalID, languageCode, username, firstName, browserTz, startParam string) (SessionResp, error) {
 	var out SessionResp
 	err := c.do(ctx, http.MethodPost, "/api/v1/internal/sessions/telegram", "", "",
 		map[string]string{
@@ -193,6 +195,8 @@ func (c *Client) TelegramAuth(ctx context.Context, externalID, languageCode, use
 			"language_code": languageCode,
 			"username":      username,
 			"first_name":    firstName,
+			"browser_tz":    browserTz,
+			"start_param":   startParam,
 		}, &out)
 	return out, err
 }
@@ -243,17 +247,21 @@ func (c *Client) ChatAccessByUser(ctx context.Context, userID string) (ChatAcces
 	return out, err
 }
 
-// GuestAuth provisions a guest account and mints a session.
+// GuestAuth provisions a guest account and mints a session, seeding its time zone
-func (c *Client) GuestAuth(ctx context.Context) (SessionResp, error) {
+// from browserTz (the client's detected "±HH:MM" UTC offset).
+func (c *Client) GuestAuth(ctx context.Context, browserTz string) (SessionResp, error) {
 	var out SessionResp
-	err := c.do(ctx, http.MethodPost, "/api/v1/internal/sessions/guest", "", "", struct{}{}, &out)
+	err := c.do(ctx, http.MethodPost, "/api/v1/internal/sessions/guest", "", "",
+		map[string]string{"browser_tz": browserTz}, &out)
 	return out, err
 }
 
-// EmailRequest asks the backend to mail a login code.
+// EmailRequest asks the backend to mail a login code, provisioning the account on
-func (c *Client) EmailRequest(ctx context.Context, email string) error {
+// first contact; browserTz (the client's detected "±HH:MM" UTC offset) seeds the new
+// account's time zone, since the email account is created here, not at login.
+func (c *Client) EmailRequest(ctx context.Context, email, browserTz string) error {
 	return c.do(ctx, http.MethodPost, "/api/v1/internal/sessions/email/request", "", "",
-		map[string]string{"email": email}, nil)
+		map[string]string{"email": email, "browser_tz": browserTz}, nil)
 }
 
 // EmailLogin verifies a login code and mints a session.

gateway/internal/backendclient/api_feedback.go

@@ -27,12 +27,14 @@ type FeedbackUnreadResp struct {
 
 // FeedbackSubmit posts a feedback message. The attachment bytes are base64-encoded
 // into the JSON body for the internal hop; clientIP rides X-Forwarded-For.
-func (c *Client) FeedbackSubmit(ctx context.Context, userID, body string, attachment []byte, attachmentName, channel, clientIP string) error {
+func (c *Client) FeedbackSubmit(ctx context.Context, userID, body string, attachment []byte, attachmentName, channel, version, browserTz, clientIP string) error {
 	payload := map[string]string{
 		"body":            body,
 		"attachment":      "",
 		"attachment_name": attachmentName,
 		"channel":         channel,
+		"version":         version,
+		"browser_tz":      browserTz,
 	}
 	if len(attachment) > 0 {
 		payload["attachment"] = base64.StdEncoding.EncodeToString(attachment)

gateway/internal/transcode/transcode.go

@@ -9,6 +9,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"net/url"
 
 	"scrabble/gateway/internal/backendclient"
 	"scrabble/gateway/internal/connector"
@@ -154,11 +155,19 @@ func DomainCode(err error) (string, bool) {
 func authTelegramHandler(backend *backendclient.Client, tg TelegramValidator) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		in := fb.GetRootAsTelegramLoginRequest(req.Payload, 0)
-		user, err := tg.ValidateInitData(ctx, string(in.InitData()))
+		initData := string(in.InitData())
+		user, err := tg.ValidateInitData(ctx, initData)
 		if err != nil {
 			return nil, err
 		}
-		sess, err := backend.TelegramAuth(ctx, user.ExternalID, user.LanguageCode, user.Username, user.FirstName)
+		// start_param rides inside the signed initData validated just above, so the launch
+		// deep-link payload can be trusted here without a separate wire field; the backend
+		// uses it to seed a brand-new account's variant preferences.
+		startParam := ""
+		if q, perr := url.ParseQuery(initData); perr == nil {
+			startParam = q.Get("start_param")
+		}
+		sess, err := backend.TelegramAuth(ctx, user.ExternalID, user.LanguageCode, user.Username, user.FirstName, string(in.BrowserTz()), startParam)
 		if err != nil {
 			return nil, err
 		}
@@ -167,8 +176,15 @@ func authTelegramHandler(backend *backendclient.Client, tg TelegramValidator) Ha
 }
 
 func authGuestHandler(backend *backendclient.Client) Handler {
-	return func(ctx context.Context, _ Request) ([]byte, error) {
+	return func(ctx context.Context, req Request) ([]byte, error) {
-		sess, err := backend.GuestAuth(ctx)
+		// The guest bootstrap historically carried no payload; the detected zone is
+		// optional, so an absent or empty one simply yields no time-zone seed (rather
+		// than panicking in GetRootAs* on a zero-length buffer).
+		var browserTz string
+		if len(req.Payload) > 0 {
+			browserTz = string(fb.GetRootAsGuestLoginRequest(req.Payload, 0).BrowserTz())
+		}
+		sess, err := backend.GuestAuth(ctx, browserTz)
 		if err != nil {
 			return nil, err
 		}
@@ -179,7 +195,7 @@ func authGuestHandler(backend *backendclient.Client) Handler {
 func authEmailRequestHandler(backend *backendclient.Client) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		in := fb.GetRootAsEmailRequestRequest(req.Payload, 0)
-		if err := backend.EmailRequest(ctx, string(in.Email())); err != nil {
+		if err := backend.EmailRequest(ctx, string(in.Email()), string(in.BrowserTz())); err != nil {
 			return nil, err
 		}
 		return encodeAck(true), nil
@@ -499,7 +515,7 @@ func hideGameHandler(backend *backendclient.Client) Handler {
 func feedbackSubmitHandler(backend *backendclient.Client) Handler {
 	return func(ctx context.Context, req Request) ([]byte, error) {
 		in := fb.GetRootAsFeedbackSubmitRequest(req.Payload, 0)
-		if err := backend.FeedbackSubmit(ctx, req.UserID, string(in.Body()), in.AttachmentBytes(), string(in.AttachmentName()), string(in.Channel()), req.ClientIP); err != nil {
+		if err := backend.FeedbackSubmit(ctx, req.UserID, string(in.Body()), in.AttachmentBytes(), string(in.AttachmentName()), string(in.Channel()), string(in.Version()), string(in.BrowserTz()), req.ClientIP); err != nil {
 			return nil, err
 		}
 		return encodeAck(true), nil

gateway/internal/transcode/transcode_telegram_test.go

@@ -54,7 +54,7 @@ func TestTelegramAuthForwardsSeedFields(t *testing.T) {
 		t.Fatal("auth.telegram not registered")
 	}
 
-	payload, err := op.Handler(context.Background(), transcode.Request{Payload: telegramLoginPayload("init")})
+	payload, err := op.Handler(context.Background(), transcode.Request{Payload: telegramLoginPayload("start_param=verudit_ru-scrabble_en&query_id=abc")})
 	if err != nil {
 		t.Fatalf("handler: %v", err)
 	}
@@ -66,6 +66,11 @@ func TestTelegramAuthForwardsSeedFields(t *testing.T) {
 	if gotBody["external_id"] != "42" || gotBody["language_code"] != "ru" || gotBody["first_name"] != "Иван" {
 		t.Errorf("forwarded body = %+v, want external_id=42 language_code=ru first_name=Иван", gotBody)
 	}
+	// start_param is parsed out of the validated initData and forwarded so the backend can
+	// seed the new account's variant preferences from a promo deep link.
+	if gotBody["start_param"] != "verudit_ru-scrabble_en" {
+		t.Errorf("forwarded start_param = %q, want verudit_ru-scrabble_en", gotBody["start_param"])
+	}
 }
 
 func TestTelegramAuthInvalidInitData(t *testing.T) {

loadtest/Dockerfile

@@ -12,7 +12,8 @@
 
 # --- dictionary artifact -----------------------------------------------------
 FROM alpine:3.20 AS dawg
-ARG DICT_VERSION=v1.2.1
+# Required, no default: the build caller supplies the scrabble-dictionary release tag.
+ARG DICT_VERSION
 RUN apk add --no-cache curl tar
 RUN mkdir -p /dawg \
  && curl -fsSL -o /tmp/dawg.tar.gz \

loadtest/README.md

@@ -1,6 +1,6 @@
 # loadtest — stress harness
 
-Reusable load harness for the pre-release stress pass. It
+Reusable load/stress harness. It
 seeds a large account population with pre-created sessions, drives virtual players
 through the **gateway edge protocol** in realistic games, hammers the rate limiter,
 and prints a trip-report summary. It stays in the repo for repeats.
@@ -35,8 +35,8 @@ The harness reaches Postgres and the gateway directly, so run it as a one-shot
 container on the contour's docker network (this bypasses the host→gateway hairpin):
 
 ```sh
-# from the repo root
+# from the repo root (DICT_VERSION has no default — pass the scrabble-dictionary release tag)
-docker build -f loadtest/Dockerfile -t scrabble-loadtest .
+docker build --build-arg DICT_VERSION=v1.3.0 -f loadtest/Dockerfile -t scrabble-loadtest .
 
 docker run --rm --cpus=3 --name scrabble-loadtest --network scrabble-internal \
   -e POSTGRES_PASSWORD="$TEST_POSTGRES_PASSWORD" \
@@ -107,6 +107,6 @@ gateway→backend connection-pool fix, and the revised sizing — are written up
 
 The harness shares the host CPU with the contour, so its own `scrabble-loadtest`
 container series is read alongside the system under test; capping it with `--cpus`
-keeps the contour's quota. Per-player transports (R7) removed the shared-transport
+keeps the contour's quota. Per-player transports removed the shared-transport
-artifact that inflated R2's `transport_error`, so the figures reflect the system. A
+artifact that previously inflated `transport_error`, so the figures reflect the system. A
 fully isolated ceiling on separate hardware remains future work.

loadtest/cmd/loadtest/main.go

@@ -129,7 +129,7 @@ func cmdRun(ctx context.Context, log *slog.Logger, args []string) error {
 		drv.Hammer(ctx, pool.Durables[0], scenario.HammerConfig{Workers: *hammerWorkers, Duration: *hammerDur})
 	}
 
-	fmt.Println("\n==== R2 load-test report ====")
+	fmt.Println("\n==== load-test report ====")
 	fmt.Println(rec.Summary())
 
 	if *doCleanup {

pkg/fbs/scrabble.fbs

@@ -99,24 +99,33 @@ table MoveRecord {
 // --- auth (unauthenticated) ---
 
 // TelegramLoginRequest carries the platform launch data; the gateway validates
-// its HMAC before forwarding the extracted identity to the backend.
+// its HMAC before forwarding the extracted identity to the backend. browser_tz is
+// the client's detected UTC offset ("±HH:MM"), seeded into a brand-new account's
+// time zone so the robot's sleep window and the turn-timeout away window are
+// anchored to the player's real zone from first contact (first contact only).
 table TelegramLoginRequest {
   init_data:string;
+  browser_tz:string;
 }
 
 // GuestLoginRequest bootstraps an ephemeral guest session. locale is an optional
-// preferred-language hint.
+// preferred-language hint; browser_tz is the detected UTC offset seeded into the
+// guest account's time zone (see TelegramLoginRequest.browser_tz).
 table GuestLoginRequest {
   locale:string;
+  browser_tz:string;
 }
 
-// EmailRequestRequest asks the backend to send a login confirm-code to email.
+// EmailRequestRequest asks the backend to send a login confirm-code to email. It
+// also provisions the account on first contact, so browser_tz (the detected UTC
+// offset) is seeded into its time zone here, not at the later login step.
 table EmailRequestRequest {
   email:string;
+  browser_tz:string;
 }
 
-// EmailLoginRequest logs in (or provisions) the account owning email, verifying
+// EmailLoginRequest logs in to the account owning email (provisioned at the
-// the confirm-code.
+// request step), verifying the confirm-code.
 table EmailLoginRequest {
   email:string;
   code:string;
@@ -383,6 +392,8 @@ table FeedbackSubmitRequest {
   attachment:[ubyte];
   attachment_name:string;
   channel:string;
+  version:string;
+  browser_tz:string;
 }
 
 // FeedbackReply is the operator's answer shown back to the player.

pkg/fbs/scrabblefb/EmailRequestRequest.go

@@ -49,12 +49,23 @@ func (rcv *EmailRequestRequest) Email() []byte {
 	return nil
 }
 
+func (rcv *EmailRequestRequest) BrowserTz() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
 func EmailRequestRequestStart(builder *flatbuffers.Builder) {
-	builder.StartObject(1)
+	builder.StartObject(2)
 }
 func EmailRequestRequestAddEmail(builder *flatbuffers.Builder, email flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(email), 0)
 }
+func EmailRequestRequestAddBrowserTz(builder *flatbuffers.Builder, browserTz flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(browserTz), 0)
+}
 func EmailRequestRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/FeedbackSubmitRequest.go

@@ -99,8 +99,24 @@ func (rcv *FeedbackSubmitRequest) Channel() []byte {
 	return nil
 }
 
+func (rcv *FeedbackSubmitRequest) Version() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(12))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *FeedbackSubmitRequest) BrowserTz() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(14))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
 func FeedbackSubmitRequestStart(builder *flatbuffers.Builder) {
-	builder.StartObject(4)
+	builder.StartObject(6)
 }
 func FeedbackSubmitRequestAddBody(builder *flatbuffers.Builder, body flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(body), 0)
@@ -117,6 +133,12 @@ func FeedbackSubmitRequestAddAttachmentName(builder *flatbuffers.Builder, attach
 func FeedbackSubmitRequestAddChannel(builder *flatbuffers.Builder, channel flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(3, flatbuffers.UOffsetT(channel), 0)
 }
+func FeedbackSubmitRequestAddVersion(builder *flatbuffers.Builder, version flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(4, flatbuffers.UOffsetT(version), 0)
+}
+func FeedbackSubmitRequestAddBrowserTz(builder *flatbuffers.Builder, browserTz flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(5, flatbuffers.UOffsetT(browserTz), 0)
+}
 func FeedbackSubmitRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/GuestLoginRequest.go

@@ -49,12 +49,23 @@ func (rcv *GuestLoginRequest) Locale() []byte {
 	return nil
 }
 
+func (rcv *GuestLoginRequest) BrowserTz() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
 func GuestLoginRequestStart(builder *flatbuffers.Builder) {
-	builder.StartObject(1)
+	builder.StartObject(2)
 }
 func GuestLoginRequestAddLocale(builder *flatbuffers.Builder, locale flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(locale), 0)
 }
+func GuestLoginRequestAddBrowserTz(builder *flatbuffers.Builder, browserTz flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(browserTz), 0)
+}
 func GuestLoginRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/TelegramLoginRequest.go

@@ -49,12 +49,23 @@ func (rcv *TelegramLoginRequest) InitData() []byte {
 	return nil
 }
 
+func (rcv *TelegramLoginRequest) BrowserTz() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
 func TelegramLoginRequestStart(builder *flatbuffers.Builder) {
-	builder.StartObject(1)
+	builder.StartObject(2)
 }
 func TelegramLoginRequestAddInitData(builder *flatbuffers.Builder, initData flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(initData), 0)
 }
+func TelegramLoginRequestAddBrowserTz(builder *flatbuffers.Builder, browserTz flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(browserTz), 0)
+}
 func TelegramLoginRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

platform/telegram/Dockerfile

@@ -24,6 +24,11 @@ ARG VERSION=dev
 RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-X scrabble/pkg/version.Version=${VERSION}" -o /out/validator ./platform/telegram/cmd/validator
 RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "-X scrabble/pkg/version.Version=${VERSION}" -o /out/bot ./platform/telegram/cmd/bot
 
+# The bot's support relay writes its JSON state under /data. Stage an empty directory
+# owned by the distroless nonroot UID so a fresh named volume mounted there inherits
+# writable ownership (Docker copies the image dir's mode/owner into an empty volume).
+RUN mkdir -p /out/data
+
 # --- validator (home) --------------------------------------------------------
 FROM gcr.io/distroless/static-debian12:nonroot AS validator
 COPY --from=build /out/validator /usr/local/bin/validator
@@ -32,4 +37,5 @@ ENTRYPOINT ["/usr/local/bin/validator"]
 # --- bot (remote) ------------------------------------------------------------
 FROM gcr.io/distroless/static-debian12:nonroot AS bot
 COPY --from=build /out/bot /usr/local/bin/bot
+COPY --from=build --chown=65532:65532 /out/data /data
 ENTRYPOINT ["/usr/local/bin/bot"]

platform/telegram/README.md

@@ -38,10 +38,17 @@ Telegram identity to an account from a browser. Both map a rejection to gRPC
   operator-chosen for broadcasts) with a Mini App launch button and sends it. It replies
   with an `Ack` per command (`delivered` mirrors the former connector semantics —
   false when the kind is not rendered out-of-app or the user never started the bot).
-- **Bot chat.** `/start <payload>` (and the chat menu button) reply with a Mini App
+- **Bot chat.** `/start <payload>` (and the chat menu button) reply with a localized
-  launch button; a deep-link payload routes the launch to a game / invitation / friend
+  welcome and a Mini App launch button; a deep-link payload routes the launch to a game /
-  code. This is **self-contained** — the bot never calls back into the game, so `/start`
+  invitation / friend code. The welcome is **Russian or English** by the sender's reported
-  onboarding works even when the game is down.
+  Telegram language (`Message.from.language_code`, which the Bot API carries on the message
+  itself — no separate user-update event — English fallback) and links the game channel and
+  discussion chat by their public `@username`, **resolved once at startup** from
+  `TELEGRAM_GAME_CHANNEL_ID` / `TELEGRAM_CHAT_ID` via `getChat` (a chat that is unset,
+  private, or unreadable degrades that link to a generic noun — "the channel" / "our
+  chat" — rather than a dangling "@"). This is otherwise **self-contained**
+  — the bot never calls back into the game, so `/start` onboarding works even when the game
+  is down.
 - **Moderated-chat gating.** When `TELEGRAM_CHAT_ID` names a channel's linked discussion
   group, the bot gates who may write there. The group **allows sending by default** (a
   human setting) and the bot only **restricts** — Telegram intersects the chat default with
@@ -56,13 +63,32 @@ Telegram identity to an account from a browser. Both map a rejection to gRPC
   `getChatMember`, since bots cannot list members). The bot must be an **administrator** there
   with the **"Ban users"** right (the Bot API `can_restrict_members`), and it subscribes to
   `chat_member` updates, which Telegram delivers only to a chat admin.
+- **Support relay (optional).** When `TELEGRAM_SUPPORT_CHAT_ID` names a private **forum
+  supergroup**, the bot runs a direct support channel for users who message it. A user's first
+  non-`/start` message opens a dedicated **forum topic** whose first message is an info card (the
+  name is a tappable profile mention via a `text_mention` entity — which also stops a name starting
+  with `/` from rendering as a command — plus @username, language, premium, id) with a **Block/Unblock** toggle
+  and a **Clear** button; each message is then copied into that topic (`copyMessage`, so any content
+  — text, media, voice, files — carries over). Any **administrator** of the support chat who writes
+  in a user's topic has it copied back to that user; the bot's own posts and non-admins are ignored
+  (the loop guard). **Block** drops a user's incoming messages (the topic stays); **Clear** deletes
+  the relayed messages, keeping the info card; a topic the operators delete is reopened on the next
+  message. State (user→topic map, block list, relayed ids) is a JSON file under
+  `TELEGRAM_SUPPORT_STATE_DIR` on a persistent volume — the bot host has no database. The bot must
+  be an **administrator** in the group with the **manage-topics** and **delete-messages** rights.
+  The relay is bot-local (no backend, no bot-link) and the user gets no automatic reply.
 - **Promo bot (optional).** When `TELEGRAM_PROMO_BOT_TOKEN` is set, the container also
   runs a **second, standalone** bot whose only job is to answer `/start` with a localized
   message and a button that opens the **main** bot's Mini App. The button is a **URL** to
   the main bot's direct link (`TELEGRAM_BOT_LINK`, the same link the UI uses) with
   `?startapp` — a `web_app` button would launch under the promo bot's identity (its token
   would sign the initData), which the main bot's validator rejects. It is fully
-  self-contained: no bot-link, no gateway, no game.
+  self-contained: no bot-link, no gateway, no game. Its `?startapp` payload
+  (`TELEGRAM_PROMO_START_PARAM`, default `verudit_ru-scrabble_en`) is a variant-seed deep
+  link the backend decodes to seed a brand-new user's variant preferences (English Scrabble
+  alongside the default Erudit). The message body also renders the bot's `@username` as that
+  same deep link (an HTML `text_link`), so tapping the mention — not just the button — opens
+  the seeded Mini App rather than the bot profile.
 - **Rate limiting.** Outbound sends are throttled (`TELEGRAM_SEND_RATE_PER_SECOND`,
   default 25) to respect the Bot API flood limits.
 
@@ -125,9 +151,12 @@ Bot (`cmd/bot`):
 | `TELEGRAM_BOTLINK_TLS_CERT` / `_KEY` / `_CA` | — (required) | the bot client cert, its key, and the CA that signs the gateway server cert |
 | `TELEGRAM_GAME_CHANNEL_ID` | — | the bot's game channel chat id for `SendToGameChannel` |
 | `TELEGRAM_CHAT_ID` | — | the moderated discussion chat id (a channel's linked group); empty disables chat gating |
+| `TELEGRAM_SUPPORT_CHAT_ID` | — | the support relay's forum supergroup id (topic per user); empty disables the relay |
+| `TELEGRAM_SUPPORT_STATE_DIR` | `/data` | directory for the support relay's JSON state (a writable volume) |
 | `TELEGRAM_PROMO_BOT_TOKEN` | — | the optional standalone promo bot's token; empty disables it |
 | `TELEGRAM_BOT_USERNAME` | — | the main bot's @username without the @ (promo message); required when the promo bot runs |
 | `TELEGRAM_BOT_LINK` | — | the main bot's Mini App link for the promo button (the UI's `VITE_TELEGRAM_LINK`); required when the promo bot runs |
+| `TELEGRAM_PROMO_START_PARAM` | `verudit_ru-scrabble_en` | the promo button's `startapp` payload — a variant-seed deep link the backend decodes to seed a brand-new user's variant preferences; empty forwards the user's own `/start` payload |
 | `TELEGRAM_OWNS_UPDATES` | `true` | run the exclusive `getUpdates` long-poll (one bot per token) |
 | `TELEGRAM_SEND_RATE_PER_SECOND` | `25` | outbound Bot API send cap (0 disables) |
 | `TELEGRAM_INSTANCE_ID` | hostname | bot identity reported to the gateway |
@@ -152,7 +181,7 @@ targets, `validator` and `bot`. In the test contour (`deploy/docker-compose.yml`
 for Telegram egress and dials the gateway bot-link by its internal name. The bot-link
 mTLS material is generated by `deploy/gen-certs.sh`. In prod the bot runs on a separate
 host with native Telegram access and dials the gateway's published bot-link port with
-`PROD_` certificates (the deferred final stage — see `PRERELEASE.md`).
+`PROD_` certificates in production.
 
 A real end-to-end Telegram smoke needs a BotFather bot, its token, a public HTTPS Mini
 App origin, and the bot container; the unit tests cover the wire format, templates,

platform/telegram/cmd/bot/main.go

@@ -10,6 +10,7 @@ import (
 	"context"
 	"log"
 	"os/signal"
+	"path/filepath"
 	"sync"
 	"syscall"
 	"time"
@@ -23,6 +24,7 @@ import (
 	"scrabble/platform/telegram/internal/botlink"
 	"scrabble/platform/telegram/internal/config"
 	"scrabble/platform/telegram/internal/promobot"
+	"scrabble/platform/telegram/internal/support"
 )
 
 // telemetryShutdownTimeout bounds the OpenTelemetry flush during process exit.
@@ -65,6 +67,19 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error {
 		logger.Warn("telemetry: start runtime metrics", zap.Error(err))
 	}
 
+	// The support relay keeps its per-user state in a JSON file on a writable volume
+	// (the bot host has no database). A corrupt file is logged and the relay starts
+	// empty rather than crash-looping the bot.
+	var supportStore *support.Store
+	if cfg.SupportChatID != 0 {
+		statePath := filepath.Join(cfg.SupportStateDir, "support.json")
+		supportStore, err = support.Open(statePath)
+		if err != nil {
+			logger.Warn("support: state load failed, starting empty", zap.String("path", statePath), zap.Error(err))
+			supportStore = support.New(statePath)
+		}
+	}
+
 	b, err := bot.New(bot.Config{
 		Token:             cfg.Token,
 		APIBaseURL:        cfg.APIBaseURL,
@@ -72,6 +87,9 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error {
 		MiniAppURL:        cfg.MiniAppURL,
 		SendRatePerSecond: cfg.SendRatePerSecond,
 		ChatID:            cfg.ChatID,
+		GameChannelID:     cfg.GameChannelID,
+		SupportChatID:     cfg.SupportChatID,
+		SupportStore:      supportStore,
 	}, logger)
 	if err != nil {
 		return err
@@ -113,6 +131,7 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error {
 			TestEnv:           cfg.TestEnv,
 			BotUsername:       cfg.BotUsername,
 			BotLinkURL:        cfg.BotLinkURL,
+			StartParam:        cfg.PromoStartParam,
 			SendRatePerSecond: cfg.SendRatePerSecond,
 		}, logger)
 		if err != nil {
@@ -127,6 +146,7 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error {
 		zap.Bool("owns_updates", cfg.OwnsUpdates),
 		zap.Bool("test_env", cfg.TestEnv),
 		zap.Bool("chat_gating", cfg.ChatID != 0),
+		zap.Bool("support_relay", cfg.SupportChatID != 0),
 		zap.Bool("promo_bot", promo != nil))
 
 	var wg sync.WaitGroup

platform/telegram/internal/bot/bot.go

@@ -15,6 +15,8 @@ import (
 	"github.com/go-telegram/bot/models"
 	"go.uber.org/zap"
 	"golang.org/x/time/rate"
+
+	"scrabble/platform/telegram/internal/support"
 )
 
 // Config configures the bot wrapper.
@@ -33,8 +35,20 @@ type Config struct {
 	SendRatePerSecond int
 	// ChatID is the moderated discussion chat the bot gates write access in; 0
 	// disables chat gating (and the chat_member long-poll subscription). Gating needs
-	// the bot to be an administrator there with the restrict-members right.
+	// the bot to be an administrator there with the restrict-members right. Its public
+	// @username is also resolved at startup for the /start welcome's discussion link.
 	ChatID int64
+	// GameChannelID is the game channel whose public @username the /start welcome links
+	// to (resolved from this id via getChat at startup); 0 omits that follow link.
+	GameChannelID int64
+	// SupportChatID is the private forum supergroup the bot relays direct user messages
+	// into (one topic per user) and reads operator replies from; 0 disables the support
+	// relay. The bot must be an administrator there with the manage-topics and
+	// delete-messages rights.
+	SupportChatID int64
+	// SupportStore persists the support relay's state (topic mapping, block list,
+	// relayed message ids); required when SupportChatID is set, ignored otherwise.
+	SupportStore *support.Store
 }
 
 // EligibilityResolver answers whether the Telegram user identified by externalID
@@ -54,12 +68,29 @@ type Bot struct {
 	limiter *rate.Limiter
 	// chatID is the moderated discussion chat (0 disables gating).
 	chatID int64
+	// channelID is the game channel (0 omits its welcome follow link).
+	channelID int64
+	// channelUsername and chatUsername are the public @usernames (without the leading
+	// @) of the game channel and the discussion chat, resolved once at startup
+	// (resolveWelcomeHandles) for the /start welcome's follow links; "" when unresolved.
+	channelUsername string
+	chatUsername    string
 	// botID is the bot's own Telegram user id (resolved at startup); it skips the
-	// chat_member updates the bot's own restrict actions generate — the grant loop guard.
+	// chat_member updates the bot's own restrict actions generate — the grant loop guard —
+	// and the bot's own relayed copies in the support chat.
 	botID int64
 	// eligibility resolves a joining user's chat write eligibility; nil leaves a
 	// joiner muted (fail-closed) until it is wired.
 	eligibility EligibilityResolver
+	// supportChatID is the support relay's forum supergroup (0 disables the relay).
+	supportChatID int64
+	// support persists the support relay's per-user state; nil when the relay is off.
+	support *support.Store
+	// supportLocks serialises per-user topic creation so a burst of a new user's
+	// messages opens exactly one topic.
+	supportLocks *keyedMutex
+	// admins caches the support chat's administrator ids (who may reply and act).
+	admins *adminCache
 }
 
 // New builds the bot wrapper, registering the /start handler and a default handler
@@ -69,7 +100,14 @@ func New(cfg Config, log *zap.Logger) (*Bot, error) {
 	if log == nil {
 		log = zap.NewNop()
 	}
-	t := &Bot{miniAppURL: cfg.MiniAppURL, log: log, chatID: cfg.ChatID}
+	t := &Bot{
+		miniAppURL:    cfg.MiniAppURL,
+		log:           log,
+		chatID:        cfg.ChatID,
+		channelID:     cfg.GameChannelID,
+		supportChatID: cfg.SupportChatID,
+		support:       cfg.SupportStore,
+	}
 	if cfg.SendRatePerSecond > 0 {
 		t.limiter = rate.NewLimiter(rate.Limit(cfg.SendRatePerSecond), cfg.SendRatePerSecond)
 	}
@@ -78,15 +116,26 @@ func New(cfg Config, log *zap.Logger) (*Bot, error) {
 		tgbot.WithDefaultHandler(t.handleUpdate),
 		tgbot.WithMessageTextHandler("/start", tgbot.MatchTypePrefix, t.handleStart),
 	}
+	if t.supportEnabled() {
+		t.supportLocks = newKeyedMutex()
+		t.admins = &adminCache{}
+		// The info-card buttons are callback_query updates; route them to the support
+		// callback handler by their "sup:" data prefix.
+		opts = append(opts, tgbot.WithCallbackQueryDataHandler(supportCallbackPrefix, tgbot.MatchTypePrefix, t.handleSupportCallback))
+	}
+	// Allowed updates default to "all except chat_member". Specify an explicit set only
+	// when we need chat_member (moderated chat) — and then re-add callback_query (which
+	// the explicit set would otherwise drop) when the support relay needs it.
 	if cfg.ChatID != 0 {
-		// chat_member updates are off by default; subscribe explicitly (alongside
+		allowed := tgbot.AllowedUpdates{
-		// messages) so the bot sees joins in the moderated chat. The bot must also be an
-		// administrator there for Telegram to deliver them.
-		opts = append(opts, tgbot.WithAllowedUpdates(tgbot.AllowedUpdates{
 			models.AllowedUpdateMessage,
 			models.AllowedUpdateMyChatMember,
 			models.AllowedUpdateChatMember,
-		}))
+		}
+		if t.supportEnabled() {
+			allowed = append(allowed, models.AllowedUpdateCallbackQuery)
+		}
+		opts = append(opts, tgbot.WithAllowedUpdates(allowed))
 	}
 	if cfg.TestEnv {
 		// Route to the Bot API test environment (.../bot<token>/test/METHOD).
@@ -123,9 +172,46 @@ func (t *Bot) Run(ctx context.Context) {
 	if t.chatID != 0 {
 		t.logChatAdminStatus(ctx)
 	}
+	if t.supportEnabled() {
+		t.initSupport(ctx)
+	}
+	t.resolveWelcomeHandles(ctx)
 	t.api.Start(ctx)
 }
 
+// resolveWelcomeHandles resolves, once at startup, the public @usernames of the game
+// channel and the discussion chat from their configured ids (getChat), caching them for
+// the /start welcome's follow links. It runs before the update loop, so the handles are
+// set before any /start is handled; a chat that is unset, private (no public username)
+// or unreadable simply leaves its handle empty and the welcome omits that follow link.
+func (t *Bot) resolveWelcomeHandles(ctx context.Context) {
+	t.channelUsername = t.resolveUsername(ctx, t.channelID, "game channel")
+	t.chatUsername = t.resolveUsername(ctx, t.chatID, "discussion chat")
+}
+
+// resolveUsername returns the public @username (without the leading @) of the chat with
+// the given id, or "" when id is 0, the chat has no public username, or getChat fails —
+// logging the reason, since a missing handle silently drops a welcome follow link.
+func (t *Bot) resolveUsername(ctx context.Context, id int64, label string) string {
+	if id == 0 {
+		return ""
+	}
+	chat, err := t.api.GetChat(ctx, &tgbot.GetChatParams{ChatID: id})
+	if err != nil {
+		t.log.Warn("welcome: getChat failed; follow link omitted",
+			zap.String("chat", label), zap.Int64("id", id), zap.Error(err))
+		return ""
+	}
+	if chat.Username == "" {
+		t.log.Warn("welcome: chat has no public @username; follow link omitted",
+			zap.String("chat", label), zap.Int64("id", id))
+		return ""
+	}
+	t.log.Info("welcome: resolved follow link",
+		zap.String("chat", label), zap.String("username", chat.Username))
+	return chat.Username
+}
+
 // logChatAdminStatus checks, at startup, whether the bot can actually gate the
 // moderated chat — it must be an administrator there with the restrict-members
 // ("Ban users") right, or Telegram delivers no chat_member updates and restricts
@@ -198,11 +284,19 @@ func (t *Bot) handleStart(ctx context.Context, api *tgbot.Bot, update *models.Up
 	if update.Message.Chat.Type != models.ChatTypePrivate {
 		return
 	}
+	// The sender's Telegram language rides on the message itself (Message.from.language_code
+	// in the Bot API — there is no separate user-update event); fall back to English when it
+	// is absent.
+	lang := ""
+	if update.Message.From != nil {
+		lang = update.Message.From.LanguageCode
+	}
+	text, button := startText(lang, t.channelUsername, t.chatUsername)
 	startParam := startPayload(update.Message.Text)
 	if _, err := api.SendMessage(ctx, &tgbot.SendMessageParams{
 		ChatID:      update.Message.Chat.ID,
-		Text:        "Tap to open Scrabble.",
+		Text:        text,
-		ReplyMarkup: t.launchMarkup("Open Scrabble", startParam),
+		ReplyMarkup: t.launchMarkup(button, startParam),
 	}); err != nil {
 		t.log.Warn("reply to start failed", zap.Error(err))
 	}
@@ -252,6 +346,19 @@ func (t *Bot) handleUpdate(ctx context.Context, api *tgbot.Bot, update *models.U
 		t.handleChatMember(ctx, update.ChatMember)
 		return
 	}
+	// Support relay (when enabled): a non-/start message — /start has its own handler —
+	// is either an operator's reply in the support chat or a user's direct message to
+	// relay. Everything else falls through to the Mini App launch reply.
+	if t.supportEnabled() && update.Message != nil {
+		switch {
+		case update.Message.Chat.ID == t.supportChatID:
+			t.handleSupportGroupMessage(ctx, update.Message)
+			return
+		case update.Message.Chat.Type == models.ChatTypePrivate:
+			t.handleSupportUserMessage(ctx, update.Message)
+			return
+		}
+	}
 	t.handleStart(ctx, api, update)
 }
 

platform/telegram/internal/bot/bot_test.go

@@ -29,6 +29,10 @@ func (f *fakeBotAPI) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		f.text = r.FormValue("text")
 		f.replyMarkup = r.FormValue("reply_markup")
 		io.WriteString(w, `{"ok":true,"result":{"message_id":1}}`)
+	case strings.HasSuffix(r.URL.Path, "/getChat"):
+		// Echo the requested id into the username so a resolver test can tell the
+		// channel lookup from the chat lookup.
+		io.WriteString(w, `{"ok":true,"result":{"id":-100,"type":"channel","username":"u`+r.FormValue("chat_id")+`"}}`)
 	default:
 		io.WriteString(w, `{"ok":true,"result":true}`)
 	}
@@ -105,7 +109,7 @@ func TestTestEnvironmentRoutesGetMe(t *testing.T) {
 }
 
 func TestHandleStartRepliesPrivateOnly(t *testing.T) {
-	t.Run("private replies", func(t *testing.T) {
+	t.Run("private replies in english by default", func(t *testing.T) {
 		api := &fakeBotAPI{}
 		b := newTestBot(t, api)
 		b.handleStart(context.Background(), b.api, &models.Update{Message: &models.Message{
@@ -114,6 +118,35 @@ func TestHandleStartRepliesPrivateOnly(t *testing.T) {
 		if api.chatID != "42" || !strings.Contains(api.replyMarkup, "web_app") {
 			t.Errorf("private /start: chat=%q markup=%q, want a web_app reply", api.chatID, api.replyMarkup)
 		}
+		// No reported language -> English welcome + English button.
+		if !strings.Contains(api.text, "Hi!") {
+			t.Errorf("text = %q, want the English welcome", api.text)
+		}
+		if !strings.Contains(api.replyMarkup, "Open") {
+			t.Errorf("reply_markup = %q, want the English button", api.replyMarkup)
+		}
+	})
+	t.Run("uses the sender's reported language", func(t *testing.T) {
+		api := &fakeBotAPI{}
+		b := newTestBot(t, api)
+		b.handleStart(context.Background(), b.api, &models.Update{Message: &models.Message{
+			Chat: models.Chat{ID: 42, Type: models.ChatTypePrivate}, Text: "/start",
+			From: &models.User{ID: 7, LanguageCode: "ru"},
+		}})
+		if !strings.Contains(api.text, "Привет!") {
+			t.Errorf("text = %q, want the Russian welcome for a ru sender", api.text)
+		}
+	})
+	t.Run("embeds resolved follow handles", func(t *testing.T) {
+		api := &fakeBotAPI{}
+		b := newTestBot(t, api)
+		b.channelUsername, b.chatUsername = "erudit", "erudite_chat"
+		b.handleStart(context.Background(), b.api, &models.Update{Message: &models.Message{
+			Chat: models.Chat{ID: 42, Type: models.ChatTypePrivate}, Text: "/start",
+		}})
+		if !strings.Contains(api.text, "@erudit") || !strings.Contains(api.text, "@erudite_chat") {
+			t.Errorf("text = %q, want the follow handles", api.text)
+		}
 	})
 	t.Run("group ignored", func(t *testing.T) {
 		api := &fakeBotAPI{}
@@ -127,6 +160,26 @@ func TestHandleStartRepliesPrivateOnly(t *testing.T) {
 	})
 }
 
+func TestResolveWelcomeHandles(t *testing.T) {
+	api := &fakeBotAPI{}
+	b := newTestBot(t, api)
+	b.channelID, b.chatID = 111, 222
+	b.resolveWelcomeHandles(context.Background())
+	// The fake echoes the requested id into the username, so each lookup is independent.
+	if b.channelUsername != "u111" {
+		t.Errorf("channelUsername = %q, want u111", b.channelUsername)
+	}
+	if b.chatUsername != "u222" {
+		t.Errorf("chatUsername = %q, want u222", b.chatUsername)
+	}
+	// An unset id resolves to no handle (and makes no getChat call).
+	b.channelID = 0
+	b.resolveWelcomeHandles(context.Background())
+	if b.channelUsername != "" {
+		t.Errorf("channelUsername = %q, want empty for id 0", b.channelUsername)
+	}
+}
+
 func TestStartPayload(t *testing.T) {
 	cases := map[string]string{
 		"/start g123":  "g123",

platform/telegram/internal/bot/support.go

@@ -0,0 +1,484 @@
+package bot
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+	"unicode/utf16"
+
+	tgbot "github.com/go-telegram/bot"
+	"github.com/go-telegram/bot/models"
+	"go.uber.org/zap"
+
+	"scrabble/platform/telegram/internal/support"
+)
+
+// Support relay: the bot forwards a user's direct messages into a per-user forum
+// topic in the operators' private support chat, and relays operator replies in that
+// topic back to the user. The info card opening each topic carries a Block/Unblock
+// toggle and a Clear button. State (topic mapping, block list, relayed message ids)
+// lives in a small JSON file via internal/support.
+const (
+	// supportCallbackPrefix namespaces the info-card button callbacks
+	// ("sup:<action>:<userID>").
+	supportCallbackPrefix = "sup:"
+	supportActionBlock    = "block"
+	supportActionUnblock  = "unblock"
+	supportActionClear    = "clear"
+	// supportAdminTTL is how long the support chat's administrator set is cached.
+	supportAdminTTL = time.Minute
+	// supportTopicNameMax bounds the forum topic name (the Telegram limit is 128).
+	supportTopicNameMax = 128
+	// supportDeleteBatch is the maximum message ids per deleteMessages call (the
+	// Telegram limit is 100).
+	supportDeleteBatch = 100
+)
+
+// supportEnabled reports whether the support relay is configured.
+func (t *Bot) supportEnabled() bool {
+	return t.supportChatID != 0 && t.support != nil
+}
+
+// initSupport prepares the support relay at startup: it resolves the bot's own user
+// id (getMe) for the loop guard, unless the chat-gating self-check already did, and
+// logs readiness. The loop guard also tests From.IsBot, so an unresolved id is not
+// fatal.
+func (t *Bot) initSupport(ctx context.Context) {
+	if t.botID == 0 {
+		if me, err := t.api.GetMe(ctx); err != nil {
+			t.log.Warn("support: getMe failed; relying on is_bot for the loop guard", zap.Error(err))
+		} else {
+			t.botID = me.ID
+		}
+	}
+	t.log.Info("support relay ready", zap.Int64("support_chat_id", t.supportChatID))
+}
+
+// keyedMutex serialises work per int64 key (here, per user id) so two concurrent
+// updates from the same user — the go-telegram/bot library runs handlers in
+// goroutines — cannot both open a forum topic.
+type keyedMutex struct {
+	mu sync.Mutex
+	m  map[int64]*sync.Mutex
+}
+
+func newKeyedMutex() *keyedMutex { return &keyedMutex{m: map[int64]*sync.Mutex{}} }
+
+// lock acquires the per-key mutex and returns its unlock function.
+func (k *keyedMutex) lock(key int64) func() {
+	k.mu.Lock()
+	mu, ok := k.m[key]
+	if !ok {
+		mu = &sync.Mutex{}
+		k.m[key] = mu
+	}
+	k.mu.Unlock()
+	mu.Lock()
+	return mu.Unlock
+}
+
+// adminCache caches the support chat's administrator ids for a short TTL, so the bot
+// does not call getChatAdministrators on every operator action.
+type adminCache struct {
+	mu        sync.Mutex
+	ids       map[int64]bool
+	fetchedAt time.Time
+}
+
+// isSupportAdmin reports whether userID administers the support chat, refreshing the
+// cache when stale. On a refresh failure it falls back to the last known set
+// (fail-closed when nothing is cached yet).
+func (t *Bot) isSupportAdmin(ctx context.Context, userID int64) bool {
+	t.admins.mu.Lock()
+	if t.admins.ids != nil && time.Since(t.admins.fetchedAt) < supportAdminTTL {
+		ok := t.admins.ids[userID]
+		t.admins.mu.Unlock()
+		return ok
+	}
+	t.admins.mu.Unlock()
+
+	members, err := t.api.GetChatAdministrators(ctx, &tgbot.GetChatAdministratorsParams{ChatID: t.supportChatID})
+	if err != nil {
+		t.log.Warn("support: getChatAdministrators failed; using cached admin set", zap.Error(err))
+		t.admins.mu.Lock()
+		defer t.admins.mu.Unlock()
+		return t.admins.ids[userID] // a nil map yields false (fail-closed)
+	}
+	ids := make(map[int64]bool, len(members))
+	for _, m := range members {
+		if u := chatMemberUser(m); u != nil {
+			ids[u.ID] = true
+		}
+	}
+	t.admins.mu.Lock()
+	t.admins.ids = ids
+	t.admins.fetchedAt = time.Now()
+	t.admins.mu.Unlock()
+	return ids[userID]
+}
+
+// handleSupportUserMessage relays a user's direct message into their forum topic in
+// the support chat, opening the topic (and its info card) on first contact. A blocked
+// user's message is dropped silently, and the user receives no reply — operators
+// answer from the topic.
+func (t *Bot) handleSupportUserMessage(ctx context.Context, m *models.Message) {
+	if m.From == nil || m.From.IsBot {
+		return
+	}
+	uid := m.From.ID
+	unlock := t.supportLocks.lock(uid)
+	defer unlock()
+
+	rec, _ := t.support.Get(uid)
+	if rec.Blocked {
+		return
+	}
+	topicID, err := t.ensureTopic(ctx, m.From, rec)
+	if err != nil {
+		t.log.Warn("support: ensure topic failed", zap.Int64("user_id", uid), zap.Error(err))
+		return
+	}
+
+	newID, err := t.copyToTopic(ctx, m.Chat.ID, m.ID, topicID)
+	if err != nil && isTopicMissingErr(err) {
+		// Backstop: the topic vanished between the liveness probe and the copy.
+		t.log.Info("support: topic gone on copy, reopening", zap.Int64("user_id", uid), zap.Int("topic_id", topicID))
+		if topicID, err = t.openSupportTopic(ctx, m.From); err == nil {
+			newID, err = t.copyToTopic(ctx, m.Chat.ID, m.ID, topicID)
+		}
+	}
+	if err != nil {
+		t.log.Warn("support: relay to topic failed", zap.Int64("user_id", uid), zap.Error(err))
+		return
+	}
+	if err := t.support.AppendMsg(uid, newID); err != nil {
+		t.log.Warn("support: persist relayed id failed", zap.Int64("user_id", uid), zap.Error(err))
+	}
+}
+
+// handleSupportGroupMessage relays an operator's reply in a user's topic back to that
+// user. It ignores the bot's own posts (the loop guard), messages outside a topic,
+// unknown topics, and non-administrators. The operator's message is tracked too, so a
+// later clear removes it.
+func (t *Bot) handleSupportGroupMessage(ctx context.Context, m *models.Message) {
+	if m.From == nil || m.From.IsBot {
+		return // the bot's own relayed copies (and other bots) — never loop them back
+	}
+	if t.botID != 0 && m.From.ID == t.botID {
+		return
+	}
+	if m.MessageThreadID == 0 {
+		return // the chat's general area, not a user's topic
+	}
+	uid, ok := t.support.ByTopic(m.MessageThreadID)
+	if !ok {
+		return
+	}
+	if !t.isSupportAdmin(ctx, m.From.ID) {
+		return // only operators reach the user
+	}
+	if err := t.support.AppendMsg(uid, m.ID); err != nil {
+		t.log.Warn("support: persist operator msg id failed", zap.Int64("user_id", uid), zap.Error(err))
+	}
+	if _, err := t.copyToUser(ctx, m.ID, uid); err != nil {
+		t.log.Warn("support: relay reply to user failed", zap.Int64("user_id", uid), zap.Error(err))
+	}
+}
+
+// handleSupportCallback handles the info-card buttons (block/unblock/clear). Only
+// support-chat administrators may act; others get a denial. It always answers the
+// callback query so the client's spinner clears.
+func (t *Bot) handleSupportCallback(ctx context.Context, _ *tgbot.Bot, update *models.Update) {
+	cq := update.CallbackQuery
+	if cq == nil {
+		return
+	}
+	action, uid, ok := parseSupportCallback(cq.Data)
+	if !ok {
+		t.answerSupportCallback(ctx, cq.ID, "")
+		return
+	}
+	if !t.isSupportAdmin(ctx, cq.From.ID) {
+		t.answerSupportCallback(ctx, cq.ID, "Недостаточно прав")
+		return
+	}
+	switch action {
+	case supportActionBlock:
+		t.setSupportBlocked(ctx, cq, uid, true)
+	case supportActionUnblock:
+		t.setSupportBlocked(ctx, cq, uid, false)
+	case supportActionClear:
+		t.clearSupportTopic(ctx, cq, uid)
+	default:
+		t.answerSupportCallback(ctx, cq.ID, "")
+	}
+}
+
+// setSupportBlocked sets the user's block state, flips the info-card toggle to match,
+// and answers the callback. Blocking does not delete the topic — it stays.
+func (t *Bot) setSupportBlocked(ctx context.Context, cq *models.CallbackQuery, uid int64, blocked bool) {
+	if err := t.support.SetBlocked(uid, blocked); err != nil {
+		t.log.Warn("support: set blocked failed", zap.Int64("user_id", uid), zap.Error(err))
+		t.answerSupportCallback(ctx, cq.ID, "Ошибка")
+		return
+	}
+	if rec, ok := t.support.Get(uid); ok && rec.HeaderMsgID != 0 {
+		if _, err := t.api.EditMessageReplyMarkup(ctx, &tgbot.EditMessageReplyMarkupParams{
+			ChatID:      t.supportChatID,
+			MessageID:   rec.HeaderMsgID,
+			ReplyMarkup: supportCardMarkup(uid, blocked),
+		}); err != nil {
+			t.log.Debug("support: update card markup failed", zap.Error(err))
+		}
+	}
+	msg := "Разблокирован"
+	if blocked {
+		msg = "Заблокирован"
+	}
+	t.answerSupportCallback(ctx, cq.ID, msg)
+}
+
+// clearSupportTopic deletes the messages relayed into the user's topic (keeping the
+// info card) and answers the callback.
+func (t *Bot) clearSupportTopic(ctx context.Context, cq *models.CallbackQuery, uid int64) {
+	ids, err := t.support.ClearMsgs(uid)
+	if err != nil {
+		t.log.Warn("support: clear failed", zap.Int64("user_id", uid), zap.Error(err))
+		t.answerSupportCallback(ctx, cq.ID, "Ошибка")
+		return
+	}
+	t.deleteSupportMessages(ctx, ids)
+	t.answerSupportCallback(ctx, cq.ID, "Очищено")
+}
+
+// ensureTopic returns a live forum-topic id for the user, opening a fresh topic (and
+// info card) when none exists or the previous one was deleted. Telegram silently
+// routes a copy aimed at a deleted topic into the chat's General topic (no error), so
+// the bot cannot rely on copyMessage failing; instead it probes the info card —
+// re-applying the card's reply markup is a no-op that errors only when the card (hence
+// the topic) is gone — and reopens on that signal. The probe also keeps the card's
+// block button in sync with the stored state.
+func (t *Bot) ensureTopic(ctx context.Context, u *models.User, rec support.User) (int, error) {
+	if rec.TopicID == 0 || rec.HeaderMsgID == 0 {
+		return t.openSupportTopic(ctx, u)
+	}
+	_, err := t.api.EditMessageReplyMarkup(ctx, &tgbot.EditMessageReplyMarkupParams{
+		ChatID:      t.supportChatID,
+		MessageID:   rec.HeaderMsgID,
+		ReplyMarkup: supportCardMarkup(u.ID, rec.Blocked),
+	})
+	if isCardMissingErr(err) {
+		t.log.Info("support: topic gone, reopening", zap.Int64("user_id", u.ID), zap.Int("topic_id", rec.TopicID))
+		return t.openSupportTopic(ctx, u)
+	}
+	// Any other outcome (success, or a benign "message is not modified") means the
+	// topic is alive; reuse it.
+	return rec.TopicID, nil
+}
+
+// openSupportTopic creates a forum topic for the user and posts its info card with
+// the block/clear buttons, persisting both. It returns the new topic id. A failure to
+// persist is logged but not fatal: the in-memory mapping still lets the relay proceed.
+func (t *Bot) openSupportTopic(ctx context.Context, u *models.User) (int, error) {
+	topic, err := t.api.CreateForumTopic(ctx, &tgbot.CreateForumTopicParams{
+		ChatID: t.supportChatID,
+		Name:   supportTopicName(u),
+	})
+	if err != nil {
+		return 0, fmt.Errorf("create forum topic: %w", err)
+	}
+	headerID := 0
+	cardText, cardEntities := supportCard(u)
+	header, err := t.api.SendMessage(ctx, &tgbot.SendMessageParams{
+		ChatID:          t.supportChatID,
+		MessageThreadID: topic.MessageThreadID,
+		Text:            cardText,
+		Entities:        cardEntities,
+		ReplyMarkup:     supportCardMarkup(u.ID, false),
+	})
+	if err != nil {
+		t.log.Warn("support: post info card failed (topic opened without it)", zap.Error(err))
+	} else {
+		headerID = header.ID
+	}
+	if err := t.support.SetTopic(u.ID, topic.MessageThreadID, headerID, u.FirstName, u.LastName, u.Username); err != nil {
+		t.log.Warn("support: persist topic state failed (kept in memory)", zap.Int64("user_id", u.ID), zap.Error(err))
+	}
+	return topic.MessageThreadID, nil
+}
+
+// copyToTopic copies a message into the user's forum topic and returns the new
+// message id.
+func (t *Bot) copyToTopic(ctx context.Context, fromChatID int64, messageID, topicID int) (int, error) {
+	if err := t.throttle(ctx); err != nil {
+		return 0, err
+	}
+	res, err := t.api.CopyMessage(ctx, &tgbot.CopyMessageParams{
+		ChatID:          t.supportChatID,
+		MessageThreadID: topicID,
+		FromChatID:      fromChatID,
+		MessageID:       messageID,
+	})
+	if err != nil {
+		return 0, err
+	}
+	return res.ID, nil
+}
+
+// copyToUser copies a support-chat message to the user's private chat and returns the
+// new message id.
+func (t *Bot) copyToUser(ctx context.Context, messageID int, userID int64) (int, error) {
+	if err := t.throttle(ctx); err != nil {
+		return 0, err
+	}
+	res, err := t.api.CopyMessage(ctx, &tgbot.CopyMessageParams{
+		ChatID:     userID,
+		FromChatID: t.supportChatID,
+		MessageID:  messageID,
+	})
+	if err != nil {
+		return 0, err
+	}
+	return res.ID, nil
+}
+
+// deleteSupportMessages best-effort deletes the given support-chat messages in
+// batches; individual failures (for example a message already removed) are ignored.
+func (t *Bot) deleteSupportMessages(ctx context.Context, ids []int) {
+	for start := 0; start < len(ids); start += supportDeleteBatch {
+		end := min(start+supportDeleteBatch, len(ids))
+		if _, err := t.api.DeleteMessages(ctx, &tgbot.DeleteMessagesParams{
+			ChatID:     t.supportChatID,
+			MessageIDs: ids[start:end],
+		}); err != nil {
+			t.log.Debug("support: delete batch failed", zap.Error(err))
+		}
+	}
+}
+
+// answerSupportCallback answers a callback query, logging a failure at debug (the
+// only effect of a miss is a lingering client spinner).
+func (t *Bot) answerSupportCallback(ctx context.Context, id, text string) {
+	if _, err := t.api.AnswerCallbackQuery(ctx, &tgbot.AnswerCallbackQueryParams{
+		CallbackQueryID: id,
+		Text:            text,
+	}); err != nil {
+		t.log.Debug("support: answer callback failed", zap.Error(err))
+	}
+}
+
+// parseSupportCallback parses "sup:<action>:<userID>" callback data.
+func parseSupportCallback(data string) (action string, userID int64, ok bool) {
+	rest, found := strings.CutPrefix(data, supportCallbackPrefix)
+	if !found {
+		return "", 0, false
+	}
+	action, idStr, found := strings.Cut(rest, ":")
+	if !found {
+		return "", 0, false
+	}
+	userID, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil {
+		return "", 0, false
+	}
+	return action, userID, true
+}
+
+// supportCardMarkup builds the info-card buttons: a Block/Unblock toggle reflecting
+// the current state, and a Clear button.
+func supportCardMarkup(userID int64, blocked bool) *models.InlineKeyboardMarkup {
+	toggleText, toggleAction := "Заблокировать", supportActionBlock
+	if blocked {
+		toggleText, toggleAction = "Разблокировать", supportActionUnblock
+	}
+	return &models.InlineKeyboardMarkup{
+		InlineKeyboard: [][]models.InlineKeyboardButton{{
+			{Text: toggleText, CallbackData: fmt.Sprintf("%s%s:%d", supportCallbackPrefix, toggleAction, userID)},
+			{Text: "Очистить", CallbackData: fmt.Sprintf("%s%s:%d", supportCallbackPrefix, supportActionClear, userID)},
+		}},
+	}
+}
+
+// supportTopicName builds the forum topic title for a user: full name and @username,
+// trimmed to the Telegram length limit.
+func supportTopicName(u *models.User) string {
+	name := strings.TrimSpace(u.FirstName + " " + u.LastName)
+	if name == "" {
+		name = "user " + strconv.FormatInt(u.ID, 10)
+	}
+	if u.Username != "" {
+		name += " @" + u.Username
+	}
+	if r := []rune(name); len(r) > supportTopicNameMax {
+		return string(r[:supportTopicNameMax])
+	}
+	return name
+}
+
+// supportCard renders the topic info card describing the user and the message
+// entities for it. The display name is covered by a text_mention entity: it links to
+// the user's profile (the reliable way to mention a user who has no public username —
+// the bot has seen them, since they messaged it) and, because the name sits inside an
+// entity, Telegram does not auto-detect a leading "/" as a bot command or a stray
+// "@handle" inside the name as a mention. The remaining lines are plain text; a public
+// @username, when present, is left for Telegram to auto-link. Entity offsets are in
+// UTF-16 code units, as the Bot API requires; the name is at offset 0.
+func supportCard(u *models.User) (string, []models.MessageEntity) {
+	name := strings.TrimSpace(u.FirstName + " " + u.LastName)
+	if name == "" {
+		name = "user " + strconv.FormatInt(u.ID, 10)
+	}
+	username := "—"
+	if u.Username != "" {
+		username = "@" + u.Username
+	}
+	lang := u.LanguageCode
+	if lang == "" {
+		lang = "—"
+	}
+	premium := "нет"
+	if u.IsPremium {
+		premium = "да"
+	}
+	var b strings.Builder
+	b.WriteString(name)
+	fmt.Fprintf(&b, "\nUsername: %s", username)
+	fmt.Fprintf(&b, "\nID: %d", u.ID)
+	fmt.Fprintf(&b, "\nЯзык: %s · Premium: %s", lang, premium)
+	entities := []models.MessageEntity{{
+		Type:   models.MessageEntityTypeTextMention,
+		Offset: 0,
+		Length: len(utf16.Encode([]rune(name))),
+		User:   &models.User{ID: u.ID},
+	}}
+	return b.String(), entities
+}
+
+// isCardMissingErr reports whether err means the info-card message no longer exists
+// (the operators deleted the topic), as opposed to a benign "message is not modified"
+// no-op when the card is still there.
+func isCardMissingErr(err error) bool {
+	if err == nil {
+		return false
+	}
+	s := strings.ToLower(err.Error())
+	return strings.Contains(s, "message to edit not found") ||
+		strings.Contains(s, "message can't be edited") ||
+		strings.Contains(s, "message_id_invalid")
+}
+
+// isTopicMissingErr reports whether err is Telegram's deleted/absent forum-topic
+// error, signalling the topic must be reopened.
+func isTopicMissingErr(err error) bool {
+	if err == nil {
+		return false
+	}
+	s := strings.ToLower(err.Error())
+	return strings.Contains(s, "thread not found") ||
+		strings.Contains(s, "thread_not_found") ||
+		strings.Contains(s, "topic deleted") ||
+		strings.Contains(s, "topic_deleted")
+}

platform/telegram/internal/bot/support_test.go

@@ -0,0 +1,473 @@
+package bot
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/go-telegram/bot/models"
+	"go.uber.org/zap"
+
+	"scrabble/platform/telegram/internal/support"
+)
+
+const supportChatID = -1001000000000
+
+// copyRec records one copyMessage call.
+type copyRec struct {
+	chatID, fromChatID, threadID, messageID string
+}
+
+// supportAPI is a fake Bot API for the support-relay handlers: it answers the
+// methods they call with incrementing ids and records the requests for assertions.
+type supportAPI struct {
+	mu           sync.Mutex
+	adminIDs     []int64
+	nextThread   int
+	nextMsg      int
+	topicsOpened int
+	copies       []copyRec
+	headerThread string // message_thread_id of the last header sendMessage
+	deleted      [][]int
+	editedMsgIDs []string
+	answers      []string
+	// editErr, when set, makes editMessageReplyMarkup return that Telegram error
+	// description (simulating a deleted info card / topic).
+	editErr string
+}
+
+func newSupportAPI(adminIDs ...int64) *supportAPI {
+	return &supportAPI{adminIDs: adminIDs, nextThread: 1000, nextMsg: 5000}
+}
+
+func (s *supportAPI) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	path := r.URL.Path
+	switch {
+	case strings.HasSuffix(path, "/getMe"):
+		io.WriteString(w, `{"ok":true,"result":{"id":1,"is_bot":true,"first_name":"bot","username":"b"}}`)
+	case strings.HasSuffix(path, "/createForumTopic"):
+		s.topicsOpened++
+		tid := s.nextThread
+		s.nextThread++
+		fmt.Fprintf(w, `{"ok":true,"result":{"message_thread_id":%d,"name":%q}}`, tid, r.FormValue("name"))
+	case strings.HasSuffix(path, "/sendMessage"):
+		s.headerThread = r.FormValue("message_thread_id")
+		mid := s.nextMsg
+		s.nextMsg++
+		fmt.Fprintf(w, `{"ok":true,"result":{"message_id":%d}}`, mid)
+	case strings.HasSuffix(path, "/copyMessage"):
+		s.copies = append(s.copies, copyRec{
+			chatID:     r.FormValue("chat_id"),
+			fromChatID: r.FormValue("from_chat_id"),
+			threadID:   r.FormValue("message_thread_id"),
+			messageID:  r.FormValue("message_id"),
+		})
+		mid := s.nextMsg
+		s.nextMsg++
+		fmt.Fprintf(w, `{"ok":true,"result":{"message_id":%d}}`, mid)
+	case strings.HasSuffix(path, "/deleteMessages"):
+		var ids []int
+		_ = json.Unmarshal([]byte(r.FormValue("message_ids")), &ids)
+		s.deleted = append(s.deleted, ids)
+		io.WriteString(w, `{"ok":true,"result":true}`)
+	case strings.HasSuffix(path, "/editMessageReplyMarkup"):
+		if s.editErr != "" {
+			fmt.Fprintf(w, `{"ok":false,"error_code":400,"description":%q}`, s.editErr)
+			return
+		}
+		s.editedMsgIDs = append(s.editedMsgIDs, r.FormValue("message_id"))
+		io.WriteString(w, `{"ok":true,"result":{"message_id":1}}`)
+	case strings.HasSuffix(path, "/answerCallbackQuery"):
+		s.answers = append(s.answers, r.FormValue("text"))
+		io.WriteString(w, `{"ok":true,"result":true}`)
+	case strings.HasSuffix(path, "/getChatAdministrators"):
+		var b strings.Builder
+		b.WriteString(`{"ok":true,"result":[`)
+		for i, id := range s.adminIDs {
+			if i > 0 {
+				b.WriteString(",")
+			}
+			fmt.Fprintf(&b, `{"status":"administrator","user":{"id":%d,"is_bot":false}}`, id)
+		}
+		b.WriteString(`]}`)
+		io.WriteString(w, b.String())
+	default:
+		io.WriteString(w, `{"ok":true,"result":true}`)
+	}
+}
+
+func (s *supportAPI) copyCount() int {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return len(s.copies)
+}
+
+// newSupportBot builds a support-enabled bot against the fake API and returns it with
+// its backing store.
+func newSupportBot(t *testing.T, api http.Handler) (*Bot, *support.Store) {
+	t.Helper()
+	srv := httptest.NewServer(api)
+	t.Cleanup(srv.Close)
+	st := support.New(filepath.Join(t.TempDir(), "support.json"))
+	b, err := New(Config{
+		Token:         "123:ABC",
+		APIBaseURL:    srv.URL,
+		MiniAppURL:    "https://example.com/telegram/",
+		SupportChatID: supportChatID,
+		SupportStore:  st,
+	}, zap.NewNop())
+	if err != nil {
+		t.Fatalf("new support bot: %v", err)
+	}
+	return b, st
+}
+
+// userMsg builds a private direct message from the given user.
+func userMsg(userID int64, text string) *models.Message {
+	return &models.Message{
+		ID:   int(userID)*10 + 1,
+		Chat: models.Chat{ID: userID, Type: models.ChatTypePrivate},
+		From: &models.User{ID: userID, FirstName: "Ann", Username: "annlee", LanguageCode: "ru"},
+		Text: text,
+	}
+}
+
+func TestSupportFirstContactOpensTopicAndRelays(t *testing.T) {
+	api := newSupportAPI()
+	b, st := newSupportBot(t, api)
+
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "hello"))
+
+	if api.topicsOpened != 1 {
+		t.Fatalf("topics opened = %d, want 1", api.topicsOpened)
+	}
+	rec, ok := st.Get(7)
+	if !ok || rec.TopicID != 1000 || rec.HeaderMsgID != 5000 {
+		t.Fatalf("store = %+v ok=%v, want topic 1000 / header 5000", rec, ok)
+	}
+	if api.headerThread != "1000" {
+		t.Errorf("header posted to thread %q, want 1000", api.headerThread)
+	}
+	if len(api.copies) != 1 {
+		t.Fatalf("copies = %d, want 1", len(api.copies))
+	}
+	c := api.copies[0]
+	if c.threadID != "1000" || c.fromChatID != "7" || c.chatID != fmt.Sprint(supportChatID) {
+		t.Errorf("copy = %+v, want thread 1000 from 7 into the support chat", c)
+	}
+	if len(rec.RelayedMsgIDs) != 1 {
+		t.Errorf("relayed ids = %v, want 1 tracked", rec.RelayedMsgIDs)
+	}
+}
+
+func TestSupportSubsequentReusesTopic(t *testing.T) {
+	api := newSupportAPI()
+	b, st := newSupportBot(t, api)
+
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "first"))
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "second"))
+
+	if api.topicsOpened != 1 {
+		t.Errorf("topics opened = %d, want 1 (topic reused)", api.topicsOpened)
+	}
+	if len(api.copies) != 2 {
+		t.Errorf("copies = %d, want 2", len(api.copies))
+	}
+	rec, _ := st.Get(7)
+	if len(rec.RelayedMsgIDs) != 2 {
+		t.Errorf("relayed ids = %v, want 2", rec.RelayedMsgIDs)
+	}
+}
+
+// TestSupportTopicRecreatedWhenDeleted covers the case the operator hit in prod:
+// after they delete a user's whole topic, Telegram routes a copy aimed at it into
+// General with no error, so the bot must proactively detect the dead topic (the card
+// probe fails) and reopen it instead of silently losing the message to General.
+func TestSupportTopicRecreatedWhenDeleted(t *testing.T) {
+	api := newSupportAPI()
+	api.editErr = "message to edit not found" // the operators deleted the topic + its card
+	b, st := newSupportBot(t, api)
+	// Seed a topic that has since been deleted in Telegram.
+	if err := st.SetTopic(7, 999, 4999, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "still there?"))
+
+	if api.topicsOpened != 1 {
+		t.Fatalf("topics opened = %d, want 1 (reopened after deletion)", api.topicsOpened)
+	}
+	rec, _ := st.Get(7)
+	if rec.TopicID != 1000 || rec.HeaderMsgID != 5000 {
+		t.Errorf("store = topic %d / header %d, want the reopened 1000 / 5000", rec.TopicID, rec.HeaderMsgID)
+	}
+	if len(api.copies) != 1 || api.copies[0].threadID != "1000" {
+		t.Errorf("relay copies = %+v, want one into the reopened topic 1000", api.copies)
+	}
+	if _, ok := st.ByTopic(999); ok {
+		t.Error("stale topic 999 still indexed after reopen")
+	}
+}
+
+func TestSupportBlockedUserDropped(t *testing.T) {
+	api := newSupportAPI()
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+	if err := st.SetBlocked(7, true); err != nil {
+		t.Fatalf("block: %v", err)
+	}
+
+	b.handleSupportUserMessage(context.Background(), userMsg(7, "hello?"))
+
+	if api.copyCount() != 0 {
+		t.Errorf("a blocked user's message was relayed (%d copies)", api.copyCount())
+	}
+	if api.topicsOpened != 0 {
+		t.Errorf("a blocked user opened a topic (%d)", api.topicsOpened)
+	}
+}
+
+// supportGroupMsg builds an operator message inside a topic of the support chat.
+func supportGroupMsg(fromID int64, threadID int, isBot bool) *models.Message {
+	return &models.Message{
+		ID:              700 + threadID,
+		Chat:            models.Chat{ID: supportChatID, Type: models.ChatTypeSupergroup},
+		From:            &models.User{ID: fromID, IsBot: isBot},
+		MessageThreadID: threadID,
+		Text:            "operator reply",
+	}
+}
+
+func TestSupportOperatorReplyRelayed(t *testing.T) {
+	api := newSupportAPI(50) // user 50 is an admin
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+
+	b.handleSupportGroupMessage(context.Background(), supportGroupMsg(50, 1000, false))
+
+	if len(api.copies) != 1 {
+		t.Fatalf("copies = %d, want 1 (reply relayed to user)", len(api.copies))
+	}
+	if api.copies[0].chatID != "7" || api.copies[0].fromChatID != fmt.Sprint(supportChatID) {
+		t.Errorf("copy = %+v, want from the support chat to user 7", api.copies[0])
+	}
+	rec, _ := st.Get(7)
+	if len(rec.RelayedMsgIDs) != 1 {
+		t.Errorf("operator message not tracked for clear: %v", rec.RelayedMsgIDs)
+	}
+}
+
+func TestSupportGroupMessageIgnored(t *testing.T) {
+	cases := []struct {
+		name   string
+		msg    *models.Message
+		admins []int64
+	}{
+		{"bot's own copy (loop guard)", supportGroupMsg(1, 1000, true), []int64{50}},
+		{"non-admin sender", supportGroupMsg(999, 1000, false), []int64{50}},
+		{"outside any topic", supportGroupMsg(50, 0, false), []int64{50}},
+		{"unknown topic", supportGroupMsg(50, 4242, false), []int64{50}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			api := newSupportAPI(tc.admins...)
+			b, st := newSupportBot(t, api)
+			if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+				t.Fatalf("seed topic: %v", err)
+			}
+			b.handleSupportGroupMessage(context.Background(), tc.msg)
+			if api.copyCount() != 0 {
+				t.Errorf("message relayed (%d copies); it should be ignored", api.copyCount())
+			}
+		})
+	}
+}
+
+// supportCallback builds a callback-query update for the given data and presser.
+func supportCallback(data string, fromID int64) *models.Update {
+	return &models.Update{CallbackQuery: &models.CallbackQuery{
+		ID:   "cb1",
+		From: models.User{ID: fromID},
+		Data: data,
+	}}
+}
+
+func TestSupportCallbackBlockToggle(t *testing.T) {
+	api := newSupportAPI(50)
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:block:7", 50))
+	if !st.Blocked(7) {
+		t.Error("user not blocked after sup:block")
+	}
+	if len(api.editedMsgIDs) != 1 || api.editedMsgIDs[0] != "5000" {
+		t.Errorf("edited markup msg ids = %v, want [5000]", api.editedMsgIDs)
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:unblock:7", 50))
+	if st.Blocked(7) {
+		t.Error("user still blocked after sup:unblock")
+	}
+	if len(api.answers) != 2 || api.answers[0] != "Заблокирован" || api.answers[1] != "Разблокирован" {
+		t.Errorf("answers = %v, want [Заблокирован Разблокирован]", api.answers)
+	}
+}
+
+func TestSupportCallbackNonAdminDenied(t *testing.T) {
+	api := newSupportAPI(50)
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:block:7", 999))
+
+	if st.Blocked(7) {
+		t.Error("a non-admin managed to block the user")
+	}
+	if len(api.answers) != 1 || api.answers[0] != "Недостаточно прав" {
+		t.Errorf("answers = %v, want a permission denial", api.answers)
+	}
+}
+
+func TestSupportCallbackClearDeletesTracked(t *testing.T) {
+	api := newSupportAPI(50)
+	b, st := newSupportBot(t, api)
+	if err := st.SetTopic(7, 1000, 5000, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("seed topic: %v", err)
+	}
+	for _, id := range []int{501, 502, 503} {
+		if err := st.AppendMsg(7, id); err != nil {
+			t.Fatalf("append: %v", err)
+		}
+	}
+
+	b.handleSupportCallback(context.Background(), b.api, supportCallback("sup:clear:7", 50))
+
+	if len(api.deleted) != 1 || len(api.deleted[0]) != 3 {
+		t.Fatalf("deleted batches = %v, want one batch of 3", api.deleted)
+	}
+	rec, _ := st.Get(7)
+	if len(rec.RelayedMsgIDs) != 0 {
+		t.Errorf("relayed ids after clear = %v, want empty", rec.RelayedMsgIDs)
+	}
+	if rec.HeaderMsgID != 5000 {
+		t.Errorf("clear disturbed the header (%d)", rec.HeaderMsgID)
+	}
+}
+
+func TestParseSupportCallback(t *testing.T) {
+	cases := []struct {
+		data       string
+		wantAction string
+		wantUID    int64
+		wantOK     bool
+	}{
+		{"sup:block:7", "block", 7, true},
+		{"sup:clear:-100", "clear", -100, true},
+		{"sup:unblock:42", "unblock", 42, true},
+		{"block:7", "", 0, false},
+		{"sup:block", "", 0, false},
+		{"sup:block:notanumber", "", 0, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.data, func(t *testing.T) {
+			action, uid, ok := parseSupportCallback(tc.data)
+			if action != tc.wantAction || uid != tc.wantUID || ok != tc.wantOK {
+				t.Errorf("parseSupportCallback(%q) = %q,%d,%v; want %q,%d,%v",
+					tc.data, action, uid, ok, tc.wantAction, tc.wantUID, tc.wantOK)
+			}
+		})
+	}
+}
+
+func TestSupportCard(t *testing.T) {
+	t.Run("name is a plain-text mention, not a command", func(t *testing.T) {
+		u := &models.User{ID: 7, FirstName: "/start", Username: "ann", LanguageCode: "ru", IsPremium: true}
+		text, ents := supportCard(u)
+		// The name is rendered verbatim (no HTML, no escaping) at the start of the card.
+		if !strings.HasPrefix(text, "/start\n") {
+			t.Errorf("card = %q, want it to start with the raw name", text)
+		}
+		// A text_mention entity covers exactly the name with the user id — this both
+		// suppresses the "/start" command auto-detection and links the profile.
+		if len(ents) != 1 {
+			t.Fatalf("entities = %d, want 1", len(ents))
+		}
+		e := ents[0]
+		if e.Type != models.MessageEntityTypeTextMention || e.Offset != 0 || e.Length != len("/start") {
+			t.Errorf("entity = %+v, want a text_mention over the name", e)
+		}
+		if e.User == nil || e.User.ID != 7 {
+			t.Errorf("entity user = %+v, want id 7", e.User)
+		}
+		if strings.Contains(text, "tg://") || strings.Contains(text, "<") {
+			t.Errorf("card = %q, want no tg:// link and no HTML", text)
+		}
+		if !strings.Contains(text, "Premium: да") || !strings.Contains(text, "@ann") {
+			t.Errorf("card = %q, want premium + @username", text)
+		}
+	})
+
+	t.Run("entity length is UTF-16, not runes", func(t *testing.T) {
+		// "😀A" is 2 runes but 3 UTF-16 code units (the emoji is a surrogate pair).
+		u := &models.User{ID: 9, FirstName: "😀A"}
+		_, ents := supportCard(u)
+		if len(ents) != 1 || ents[0].Length != 3 {
+			t.Fatalf("entity = %+v, want length 3 UTF-16 units", ents)
+		}
+	})
+
+	t.Run("nameless user falls back to an id label", func(t *testing.T) {
+		u := &models.User{ID: 42}
+		text, ents := supportCard(u)
+		if !strings.HasPrefix(text, "user 42") {
+			t.Errorf("card = %q, want the id fallback name", text)
+		}
+		if ents[0].Length != len("user 42") {
+			t.Errorf("entity length = %d, want it over the fallback name", ents[0].Length)
+		}
+	})
+}
+
+func TestSupportTopicName(t *testing.T) {
+	if got := supportTopicName(&models.User{ID: 7, FirstName: "Ann", LastName: "Lee", Username: "annlee"}); got != "Ann Lee @annlee" {
+		t.Errorf("topic name = %q, want %q", got, "Ann Lee @annlee")
+	}
+	if got := supportTopicName(&models.User{ID: 7}); got != "user 7" {
+		t.Errorf("nameless topic = %q, want %q", got, "user 7")
+	}
+	long := strings.Repeat("x", 200)
+	if got := supportTopicName(&models.User{ID: 7, FirstName: long}); len([]rune(got)) != supportTopicNameMax {
+		t.Errorf("topic name length = %d, want %d (trimmed)", len([]rune(got)), supportTopicNameMax)
+	}
+}
+
+func TestSupportDisabledFallsThrough(t *testing.T) {
+	// With no SupportChatID the relay is off and supportEnabled is false.
+	srv := httptest.NewServer(&supportAPI{nextThread: 1000, nextMsg: 5000})
+	t.Cleanup(srv.Close)
+	b, err := New(Config{Token: "123:ABC", APIBaseURL: srv.URL, MiniAppURL: "https://example.com/"}, zap.NewNop())
+	if err != nil {
+		t.Fatalf("new bot: %v", err)
+	}
+	if b.supportEnabled() {
+		t.Error("supportEnabled() = true without a SupportChatID")
+	}
+}

platform/telegram/internal/bot/welcome.go

@@ -0,0 +1,60 @@
+package bot
+
+import "strings"
+
+// startText returns the localized /start welcome body and the launch-button label.
+// Russian is used when lang (the IETF language tag the Telegram client reports on the
+// message's sender) starts with "ru", English otherwise and when it is absent — so a
+// user with no reported language still gets a sensible message. channel and chat are
+// the resolved public @usernames (without the leading @) of the game channel and the
+// discussion chat; when either is empty its follow link degrades to a generic noun
+// (e.g. "the channel" / "our chat") rather than rendering a dangling "@", since the
+// bot's own info screen still lists the real links.
+func startText(lang, channel, chat string) (text, button string) {
+	if strings.HasPrefix(strings.ToLower(lang), "ru") {
+		return ruWelcome(channel, chat), "Открыть «Эрудит»"
+	}
+	return enWelcome(channel, chat), "Open “Erudite”"
+}
+
+// ruWelcome builds the Russian welcome. A known handle is named as "@<username>"; an
+// unresolved one degrades to a plain noun.
+func ruWelcome(channel, chat string) string {
+	ch := "канал"
+	if channel != "" {
+		ch = "@" + channel
+	}
+	ct := "чате"
+	if chat != "" {
+		ct = "@" + chat
+	}
+	return strings.Join([]string{
+		"Привет! 👋",
+		"Здесь можно сражаться в «Эрудит» со случайными игроками или в компании друзей.",
+		"Подписывайтесь на " + ch + ", чтобы быть в курсе последних игровых событий и вовремя " +
+			"получать важные уведомления. Игроки могут обсуждать игру и просто общаться в нашем " +
+			ct + "! 💬",
+		"Ни слова больше.\nПервая партия сама себя не сыграет 😊",
+	}, "\n\n")
+}
+
+// enWelcome builds the English welcome (the fallback for any non-Russian or missing
+// language). A known handle is named as "@<username>"; an unresolved one degrades to a
+// plain noun.
+func enWelcome(channel, chat string) string {
+	ch := "the channel"
+	if channel != "" {
+		ch = "@" + channel
+	}
+	ct := "group chat"
+	if chat != "" {
+		ct = "@" + chat
+	}
+	return strings.Join([]string{
+		"Hi! 👋",
+		"Play Scrabble against random players — or with a group of friends.",
+		"Follow " + ch + " to stay up to date with the latest game events and receive important " +
+			"notifications in time. Players can discuss the game and simply chat in our " + ct + "! 💬",
+		"Okay, no more talking.\nFirst game won't play itself 😊",
+	}, "\n\n")
+}

platform/telegram/internal/bot/welcome_test.go

@@ -0,0 +1,73 @@
+package bot
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestStartTextLocalizesByLanguage(t *testing.T) {
+	cases := []struct {
+		name       string
+		lang       string
+		wantButton string
+		wantSubstr string // a phrase unique to the chosen language body
+	}{
+		{"russian", "ru", "Открыть «Эрудит»", "Привет!"},
+		{"russian region tag", "ru-RU", "Открыть «Эрудит»", "Первая партия"},
+		{"english", "en", "Open “Erudite”", "Hi!"},
+		{"other language falls back to english", "de", "Open “Erudite”", "Hi!"},
+		{"absent language falls back to english", "", "Open “Erudite”", "no more talking"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			text, button := startText(tc.lang, "erudit", "erudite_chat")
+			if button != tc.wantButton {
+				t.Errorf("button = %q, want %q", button, tc.wantButton)
+			}
+			if !strings.Contains(text, tc.wantSubstr) {
+				t.Errorf("text %q does not contain %q", text, tc.wantSubstr)
+			}
+		})
+	}
+}
+
+func TestStartTextEmbedsFollowHandles(t *testing.T) {
+	for _, lang := range []string{"ru", "en"} {
+		text, _ := startText(lang, "erudit", "erudite_chat")
+		if !strings.Contains(text, "@erudit") || !strings.Contains(text, "@erudite_chat") {
+			t.Errorf("lang %q: follow paragraph missing the handles: %q", lang, text)
+		}
+	}
+}
+
+func TestStartTextFallsBackToGenericWhenHandleMissing(t *testing.T) {
+	// An unresolved handle degrades to a generic noun rather than a dangling "@" — and
+	// only that slot degrades; a resolved sibling still shows its "@username".
+	t.Run("both missing leaves no @", func(t *testing.T) {
+		for _, lang := range []string{"ru", "en"} {
+			text, _ := startText(lang, "", "")
+			if strings.Contains(text, "@") {
+				t.Errorf("lang %q: text shows a dangling @: %q", lang, text)
+			}
+		}
+		// The generic nouns are present in each language.
+		ru, _ := startText("ru", "", "")
+		if !strings.Contains(ru, "на канал") || !strings.Contains(ru, "в нашем чате") {
+			t.Errorf("russian generic fallback missing: %q", ru)
+		}
+		en, _ := startText("en", "", "")
+		if !strings.Contains(en, "Follow the channel") || !strings.Contains(en, "in our group chat") {
+			t.Errorf("english generic fallback missing: %q", en)
+		}
+	})
+	t.Run("only the missing slot degrades", func(t *testing.T) {
+		// Channel resolved, chat missing: the channel keeps its @handle, the chat is generic.
+		en, _ := startText("en", "erudit", "")
+		if !strings.Contains(en, "@erudit") || strings.Contains(en, "@erudite") {
+			t.Errorf("channel handle not shown / chat handle leaked: %q", en)
+		}
+		if !strings.Contains(en, "in our group chat") {
+			t.Errorf("chat slot did not degrade to a generic noun: %q", en)
+		}
+	})
+}

platform/telegram/internal/config/config.go

@@ -42,6 +42,16 @@ type BotConfig struct {
 	// (TELEGRAM_CHAT_ID, optional; 0 disables chat gating). The bot must be an admin
 	// there with the "Ban users" right, and "chat_member" in its allowed updates.
 	ChatID int64
+	// SupportChatID is the chat id of the private forum supergroup the bot relays
+	// direct user messages into — one forum topic per user — and reads operator
+	// replies from (TELEGRAM_SUPPORT_CHAT_ID, optional; 0 disables the support relay).
+	// The bot must be an administrator there with the manage-topics and
+	// delete-messages rights. Distinct from ChatID (the moderated discussion chat).
+	SupportChatID int64
+	// SupportStateDir is the directory holding the support relay's JSON state file
+	// (TELEGRAM_SUPPORT_STATE_DIR, default /data). It must be writable by the
+	// container user (UID 65532) and backed by a persistent volume.
+	SupportStateDir string
 	// PromoBotToken is the API token of the optional standalone promo bot run in this
 	// container — a second bot whose only job is to answer /start with a button that
 	// opens the main bot's Mini App (TELEGRAM_PROMO_BOT_TOKEN, optional; empty disables
@@ -55,6 +65,12 @@ type BotConfig struct {
 	// button appends ?startapp=<payload> to it (TELEGRAM_BOT_LINK; required when the
 	// promo bot runs). It is distinct from the BotLink mTLS dial config below.
 	BotLinkURL string
+	// PromoStartParam is the promo button's launch payload, appended as
+	// ?startapp=<PromoStartParam> (TELEGRAM_PROMO_START_PARAM, default
+	// "verudit_ru-scrabble_en"). It is a variant-seed deep link the backend decodes to
+	// seed a brand-new user's variant preferences; its labels must match the backend's
+	// known variants. Empty falls back to forwarding the user's own /start payload.
+	PromoStartParam string
 	// MiniAppURL is the HTTPS origin of the Mini App registered with BotFather; it is
 	// the base of every launch button (TELEGRAM_MINIAPP_URL, required).
 	MiniAppURL string
@@ -103,6 +119,10 @@ const (
 	defaultValidatorGRPCAddr = ":9091"
 	defaultBotReconnectDelay = 2 * time.Second
 	defaultSendRatePerSecond = 25
+	// defaultPromoStartParam is the promo button's default launch payload: a variant-seed
+	// deep link the backend decodes to add English Scrabble to a brand-new user's variant
+	// preferences alongside the default Erudit. Override with TELEGRAM_PROMO_START_PARAM.
+	defaultPromoStartParam = "verudit_ru-scrabble_en"
 )
 
 // LoadValidator reads the validator configuration from the environment.
@@ -135,6 +155,8 @@ func LoadBot() (BotConfig, error) {
 		PromoBotToken:     os.Getenv("TELEGRAM_PROMO_BOT_TOKEN"),
 		BotUsername:       strings.TrimPrefix(os.Getenv("TELEGRAM_BOT_USERNAME"), "@"),
 		BotLinkURL:        os.Getenv("TELEGRAM_BOT_LINK"),
+		PromoStartParam:   envOr("TELEGRAM_PROMO_START_PARAM", defaultPromoStartParam),
+		SupportStateDir:   envOr("TELEGRAM_SUPPORT_STATE_DIR", "/data"),
 		LogLevel:          envOr("TELEGRAM_LOG_LEVEL", "info"),
 		BotLink: BotLinkClientConfig{
 			GatewayAddr: os.Getenv("TELEGRAM_GATEWAY_ADDR"),
@@ -152,6 +174,9 @@ func LoadBot() (BotConfig, error) {
 	if cfg.ChatID, err = envInt64("TELEGRAM_CHAT_ID", 0); err != nil {
 		return BotConfig{}, err
 	}
+	if cfg.SupportChatID, err = envInt64("TELEGRAM_SUPPORT_CHAT_ID", 0); err != nil {
+		return BotConfig{}, err
+	}
 	if cfg.SendRatePerSecond, err = envInt("TELEGRAM_SEND_RATE_PER_SECOND", defaultSendRatePerSecond); err != nil {
 		return BotConfig{}, err
 	}

platform/telegram/internal/config/config_test.go

@@ -151,6 +151,48 @@ func TestLoadBotChatAndPromo(t *testing.T) {
 	})
 }
 
+// TestLoadBotSupportRelay verifies the support-relay chat id parses, the state
+// directory defaults to /data, and the relay is disabled (chat id 0) by default.
+func TestLoadBotSupportRelay(t *testing.T) {
+	t.Run("parsed", func(t *testing.T) {
+		setBotRequired(t)
+		t.Setenv("TELEGRAM_SUPPORT_CHAT_ID", "-1001234567890")
+		t.Setenv("TELEGRAM_SUPPORT_STATE_DIR", "/srv/state")
+		c, err := LoadBot()
+		if err != nil {
+			t.Fatalf("LoadBot: %v", err)
+		}
+		if c.SupportChatID != -1001234567890 {
+			t.Errorf("SupportChatID = %d, want -1001234567890", c.SupportChatID)
+		}
+		if c.SupportStateDir != "/srv/state" {
+			t.Errorf("SupportStateDir = %q, want /srv/state", c.SupportStateDir)
+		}
+	})
+
+	t.Run("defaults", func(t *testing.T) {
+		setBotRequired(t)
+		c, err := LoadBot()
+		if err != nil {
+			t.Fatalf("LoadBot: %v", err)
+		}
+		if c.SupportChatID != 0 {
+			t.Errorf("SupportChatID = %d, want 0 (relay disabled)", c.SupportChatID)
+		}
+		if c.SupportStateDir != "/data" {
+			t.Errorf("SupportStateDir = %q, want /data", c.SupportStateDir)
+		}
+	})
+
+	t.Run("malformed chat id rejected", func(t *testing.T) {
+		setBotRequired(t)
+		t.Setenv("TELEGRAM_SUPPORT_CHAT_ID", "not-a-number")
+		if _, err := LoadBot(); err == nil {
+			t.Fatal("LoadBot: expected an error for a malformed support chat id, got nil")
+		}
+	})
+}
+
 // TestLoadRejectsUnsupportedExporter verifies an exporter outside the supported set
 // fails validation (the validator path).
 func TestLoadRejectsUnsupportedExporter(t *testing.T) {

platform/telegram/internal/initdata/validator.go

@@ -18,7 +18,8 @@ import (
 )
 
 // ErrInvalidInitData is returned when initData fails HMAC validation, is missing
-// the hash, is malformed, or is older than the freshness window.
+// the hash, is malformed, is older than the freshness window, or identifies a bot
+// user (is_bot), which is denied.
 var ErrInvalidInitData = errors.New("initdata: invalid telegram init data")
 
 // defaultMaxAge bounds how old a validated initData payload may be.
@@ -120,6 +121,7 @@ func parseUser(userJSON string) (User, error) {
 	}
 	var u struct {
 		ID           int64  `json:"id"`
+		IsBot        bool   `json:"is_bot"`
 		Username     string `json:"username"`
 		FirstName    string `json:"first_name"`
 		LanguageCode string `json:"language_code"`
@@ -127,6 +129,12 @@ func parseUser(userJSON string) (User, error) {
 	if err := json.Unmarshal([]byte(userJSON), &u); err != nil || u.ID == 0 {
 		return User{}, ErrInvalidInitData
 	}
+	// Deny bot principals: the HMAC has already proved Telegram signed this payload, so is_bot==true
+	// is Telegram itself attesting the launching user is a bot. A real user opening the Mini App
+	// never carries it, so reject defensively rather than provision an account for a bot.
+	if u.IsBot {
+		return User{}, ErrInvalidInitData
+	}
 	return User{
 		ExternalID:   strconv.FormatInt(u.ID, 10),
 		Username:     u.Username,

platform/telegram/internal/initdata/validator_test.go

@@ -83,3 +83,28 @@ func TestValidateRejects(t *testing.T) {
 		}
 	})
 }
+
+func TestValidateBotUser(t *testing.T) {
+	t.Run("is_bot true is denied", func(t *testing.T) {
+		initData := signInitData(testToken, map[string]string{
+			"auth_date": strconv.FormatInt(time.Now().Unix(), 10),
+			"user":      `{"id":42,"is_bot":true,"first_name":"Robo"}`,
+		})
+		if _, err := NewHMACValidator(testToken).Validate(initData); !errors.Is(err, ErrInvalidInitData) {
+			t.Errorf("err = %v, want ErrInvalidInitData", err)
+		}
+	})
+	t.Run("is_bot false is allowed", func(t *testing.T) {
+		initData := signInitData(testToken, map[string]string{
+			"auth_date": strconv.FormatInt(time.Now().Unix(), 10),
+			"user":      `{"id":42,"is_bot":false,"first_name":"Thomas"}`,
+		})
+		u, err := NewHMACValidator(testToken).Validate(initData)
+		if err != nil {
+			t.Fatalf("validate: %v", err)
+		}
+		if u.ExternalID != "42" || u.FirstName != "Thomas" {
+			t.Errorf("user = %+v, want {42 Thomas}", u)
+		}
+	})
+}

platform/telegram/internal/promobot/promobot.go

@@ -9,7 +9,9 @@
 package promobot
 
 import (
+	"cmp"
 	"context"
+	"html"
 	"net/url"
 	"strings"
 
@@ -33,6 +35,11 @@ type Config struct {
 	// BotLinkURL is the main bot's Mini App direct link; the button appends
 	// ?startapp=<payload> to it.
 	BotLinkURL string
+	// StartParam is the campaign payload appended as ?startapp=<StartParam> to the launch
+	// button — e.g. a variant-seed deep link ("verudit_ru-scrabble_en") the backend
+	// decodes to seed a brand-new user's variant preferences. Empty falls back to
+	// forwarding the user's own /start payload.
+	StartParam string
 	// SendRatePerSecond caps outbound sends to respect the Bot API flood limits; 0
 	// disables the limiter. The burst equals the per-second rate.
 	SendRatePerSecond int
@@ -43,6 +50,7 @@ type Bot struct {
 	api        *tgbot.Bot
 	username   string
 	linkURL    string
+	startParam string
 	log        *zap.Logger
 	limiter    *rate.Limiter
 }
@@ -53,7 +61,7 @@ func New(cfg Config, log *zap.Logger) (*Bot, error) {
 	if log == nil {
 		log = zap.NewNop()
 	}
-	t := &Bot{username: cfg.BotUsername, linkURL: cfg.BotLinkURL, log: log}
+	t := &Bot{username: cfg.BotUsername, linkURL: cfg.BotLinkURL, startParam: cfg.StartParam, log: log}
 	if cfg.SendRatePerSecond > 0 {
 		t.limiter = rate.NewLimiter(rate.Limit(cfg.SendRatePerSecond), cfg.SendRatePerSecond)
 	}
@@ -87,7 +95,8 @@ func (t *Bot) Run(ctx context.Context) {
 }
 
 // handleStart replies to any message (typically /start) with the localized promo text
-// and a button that opens the main bot's Mini App, forwarding any /start payload.
+// and a button that opens the main bot's Mini App at the configured campaign payload
+// (falling back to forwarding any /start payload the user arrived with).
 func (t *Bot) handleStart(ctx context.Context, api *tgbot.Bot, update *models.Update) {
 	if update.Message == nil {
 		return
@@ -104,11 +113,16 @@ func (t *Bot) handleStart(ctx context.Context, api *tgbot.Bot, update *models.Up
 	if update.Message.From != nil {
 		lang = update.Message.From.LanguageCode
 	}
-	text, button := promoText(lang, t.username)
+	// The configured campaign payload (a variant-seed deep link) takes precedence; absent
+	// one, fall back to forwarding any /start payload the user arrived with. The same
+	// payload backs both the inline button and the @username link in the body.
+	param := cmp.Or(t.startParam, startPayload(update.Message.Text))
+	text, button := promoText(lang, t.username, t.launchURL(param))
 	if _, err := api.SendMessage(ctx, &tgbot.SendMessageParams{
 		ChatID:      update.Message.Chat.ID,
 		Text:        text,
-		ReplyMarkup: t.launchMarkup(button, startPayload(update.Message.Text)),
+		ParseMode:   models.ParseModeHTML,
+		ReplyMarkup: t.launchMarkup(button, param),
 	}); err != nil {
 		t.log.Warn("promo: reply to start failed", zap.Error(err))
 	}
@@ -159,11 +173,15 @@ func startPayload(text string) string {
 	return strings.TrimSpace(strings.TrimPrefix(text, cmd))
 }
 
-// promoText returns the localized message body and button label, naming the main bot
+// promoText returns the localized message body and button label. The body names the main
-// (Russian for a "ru" language code, English otherwise).
+// bot as a clickable @username whose link is the Mini App deep link (launchURL, the same
-func promoText(lang, username string) (text, button string) {
+// target as the button), so tapping the mention opens the seeded Mini App rather than the
+// bot profile. The body is sent with ParseMode HTML; only the link carries markup, so the
+// static sentences need no escaping. Russian for a "ru" language code, English otherwise.
+func promoText(lang, username, launchURL string) (text, button string) {
+	mention := `<a href="` + html.EscapeString(launchURL) + `">@` + html.EscapeString(username) + `</a>`
 	if strings.HasPrefix(strings.ToLower(lang), "ru") {
-		return "Откройте @" + username + " и выберите в настройках профиля нужный вариант игры.", "🤩 Хочу играть!"
+		return "Откройте " + mention + " и выберите в настройках профиля нужный вариант игры.", "🤩 Хочу играть!"
 	}
-	return "Open @" + username + " and choose your game variant in the profile settings.", "🤩 I want to play!"
+	return "Open " + mention + " and choose your game variant in the profile settings.", "🤩 I want to play!"
 }

platform/telegram/internal/promobot/promobot_test.go

@@ -13,25 +13,30 @@ import (
 )
 
 func TestPromoTextLocalization(t *testing.T) {
-	en, enBtn := promoText("en", "ScrabbleBot")
+	const url = "https://t.me/bot/app?startapp=verudit_ru-scrabble_en"
-	if !strings.Contains(en, "@ScrabbleBot") || !strings.Contains(en, "profile settings") {
+	// The @username is rendered as a clickable deep link (the same target as the button),
+	// not a plain mention, so tapping it opens the seeded Mini App.
+	wantLink := `<a href="` + url + `">@ScrabbleBot</a>`
+
+	en, enBtn := promoText("en", "ScrabbleBot", url)
+	if !strings.Contains(en, wantLink) || !strings.Contains(en, "profile settings") {
 		t.Errorf("en text = %q", en)
 	}
 	if enBtn != "🤩 I want to play!" {
 		t.Errorf("en button = %q", enBtn)
 	}
 
-	ru, ruBtn := promoText("ru-RU", "ScrabbleBot")
+	ru, ruBtn := promoText("ru-RU", "ScrabbleBot", url)
-	if !strings.Contains(ru, "@ScrabbleBot") || !strings.Contains(ru, "Откройте") {
+	if !strings.Contains(ru, wantLink) || !strings.Contains(ru, "Откройте") {
 		t.Errorf("ru text = %q", ru)
 	}
 	if ruBtn != "🤩 Хочу играть!" {
 		t.Errorf("ru button = %q", ruBtn)
 	}
 
-	// An unknown language falls back to English.
+	// An unknown language falls back to English, still with the linked mention.
-	if got, _ := promoText("de", "B"); !strings.Contains(got, "Open @B") {
+	if got, _ := promoText("de", "B", url); !strings.Contains(got, "Open ") || !strings.Contains(got, `">@B</a>`) {
-		t.Errorf("fallback text = %q, want English", got)
+		t.Errorf("fallback text = %q, want English with a linked mention", got)
 	}
 }
 
@@ -93,8 +98,8 @@ func TestHandleStartReplies(t *testing.T) {
 	if api.chatID != "42" {
 		t.Errorf("chat_id = %q, want 42", api.chatID)
 	}
-	if !strings.Contains(api.text, "@ScrabbleBot") {
+	if !strings.Contains(api.text, `<a href="https://t.me/bot/app?startapp=f99">@ScrabbleBot</a>`) {
-		t.Errorf("text = %q, want the @mention", api.text)
+		t.Errorf("text = %q, want the @mention linked to the startapp deep link", api.text)
 	}
 	if strings.Contains(api.replyMarkup, "web_app") {
 		t.Errorf("reply_markup = %q has a web_app button; want a url button", api.replyMarkup)

platform/telegram/internal/support/store.go

@@ -0,0 +1,227 @@
+// Package support persists the Telegram bot's support-relay state. For each user
+// who direct-messages the bot it records the dedicated forum topic the bot opened
+// in the operators' support chat, whether the user is blocked, and the ids of the
+// messages relayed into that topic — so an operator's "clear" can delete them while
+// keeping the topic's info card. The state is a small JSON file on a writable
+// volume: the bot host has no database.
+//
+// The store is concurrency-safe. The go-telegram/bot library dispatches each update
+// in its own goroutine, so every exported method locks. Mutators update only their
+// own fields (SetTopic never touches Blocked, SetBlocked never touches the relayed
+// ids) so a topic recreate cannot clobber a concurrent block toggle.
+package support
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"sync"
+	"time"
+)
+
+// User is one user's support-relay state.
+type User struct {
+	// UserID is the user's Telegram user id (the private chat id the bot relays to).
+	UserID int64 `json:"user_id"`
+	// TopicID is the forum topic's message_thread_id in the support chat; 0 means no
+	// topic has been created yet.
+	TopicID int `json:"topic_id"`
+	// HeaderMsgID is the info-card message that opens the topic and carries the
+	// block/clear buttons; it is never deleted by a clear.
+	HeaderMsgID int `json:"header_msg_id"`
+	// Blocked reports whether the bot drops this user's incoming messages.
+	Blocked bool `json:"blocked"`
+	// FirstName, LastName and Username snapshot the user's Telegram profile at the
+	// time the topic was created or last refreshed (for the topic name and info card).
+	FirstName string `json:"first_name,omitempty"`
+	LastName  string `json:"last_name,omitempty"`
+	Username  string `json:"username,omitempty"`
+	// RelayedMsgIDs are the ids of the messages posted into the topic after the header
+	// (the user's relayed messages and the operators' replies); a clear deletes them.
+	RelayedMsgIDs []int `json:"relayed_msg_ids,omitempty"`
+	// CreatedAt is when the topic was first opened for this user.
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// Store is the concurrency-safe, JSON-backed support-relay state. The zero value is
+// not usable; build one with Open or New.
+type Store struct {
+	mu      sync.Mutex
+	path    string
+	users   map[int64]*User
+	byTopic map[int]int64 // TopicID -> UserID, for resolving operator replies
+}
+
+// file is the on-disk shape: a flat list of users. A JSON object keyed by user id
+// would force the int64 keys through strings; a list keeps the ids typed.
+type file struct {
+	Users []*User `json:"users"`
+}
+
+// New returns an empty store that persists to path, creating the parent directory
+// when missing. Use it as the fallback when Open reports a corrupt file.
+func New(path string) *Store {
+	_ = os.MkdirAll(filepath.Dir(path), 0o755)
+	return &Store{path: path, users: map[int64]*User{}, byTopic: map[int]int64{}}
+}
+
+// Open loads the store from path. A missing file yields an empty store and no
+// error; an unreadable or malformed file returns an error so the caller can decide
+// whether to start empty.
+func Open(path string) (*Store, error) {
+	s := New(path)
+	b, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return s, nil
+		}
+		return nil, fmt.Errorf("support: read state %s: %w", path, err)
+	}
+	var f file
+	if err := json.Unmarshal(b, &f); err != nil {
+		return nil, fmt.Errorf("support: parse state %s: %w", path, err)
+	}
+	for _, u := range f.Users {
+		if u == nil || u.UserID == 0 {
+			continue
+		}
+		s.users[u.UserID] = u
+		if u.TopicID != 0 {
+			s.byTopic[u.TopicID] = u.UserID
+		}
+	}
+	return s, nil
+}
+
+// Get returns a detached copy of the user's state and whether it exists.
+func (s *Store) Get(userID int64) (User, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	u, ok := s.users[userID]
+	if !ok {
+		return User{}, false
+	}
+	cp := *u
+	cp.RelayedMsgIDs = append([]int(nil), u.RelayedMsgIDs...)
+	return cp, true
+}
+
+// ByTopic returns the user id owning the given forum topic, and whether one is known.
+func (s *Store) ByTopic(topicID int) (int64, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	uid, ok := s.byTopic[topicID]
+	return uid, ok
+}
+
+// Blocked reports whether the user's incoming messages are dropped.
+func (s *Store) Blocked(userID int64) bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if u, ok := s.users[userID]; ok {
+		return u.Blocked
+	}
+	return false
+}
+
+// SetTopic records the forum topic and info-card message opened for the user and
+// refreshes the profile snapshot, creating the record on first contact. It rebuilds
+// the topic index when the topic changes (a recreate) and preserves the block state
+// and the relayed-message ids. It persists the result.
+func (s *Store) SetTopic(userID int64, topicID, headerMsgID int, firstName, lastName, username string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	u, ok := s.users[userID]
+	if !ok {
+		u = &User{UserID: userID, CreatedAt: time.Now().UTC()}
+		s.users[userID] = u
+	} else if u.TopicID != 0 && u.TopicID != topicID {
+		delete(s.byTopic, u.TopicID)
+	}
+	u.TopicID = topicID
+	u.HeaderMsgID = headerMsgID
+	u.FirstName, u.LastName, u.Username = firstName, lastName, username
+	if topicID != 0 {
+		s.byTopic[topicID] = userID
+	}
+	return s.save()
+}
+
+// SetBlocked sets the user's blocked flag, creating a minimal record when none
+// exists, and persists the result.
+func (s *Store) SetBlocked(userID int64, blocked bool) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	u, ok := s.users[userID]
+	if !ok {
+		u = &User{UserID: userID, CreatedAt: time.Now().UTC()}
+		s.users[userID] = u
+	}
+	u.Blocked = blocked
+	return s.save()
+}
+
+// AppendMsg records a message posted into the user's topic (for a later clear) and
+// persists the result. It is a no-op when the user has no record yet.
+func (s *Store) AppendMsg(userID int64, msgID int) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	u, ok := s.users[userID]
+	if !ok {
+		return nil
+	}
+	u.RelayedMsgIDs = append(u.RelayedMsgIDs, msgID)
+	return s.save()
+}
+
+// ClearMsgs empties and returns the user's relayed-message ids (the info card is not
+// among them) and persists the result, so the caller can delete them from the chat.
+func (s *Store) ClearMsgs(userID int64) ([]int, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	u, ok := s.users[userID]
+	if !ok || len(u.RelayedMsgIDs) == 0 {
+		return nil, nil
+	}
+	ids := u.RelayedMsgIDs
+	u.RelayedMsgIDs = nil
+	if err := s.save(); err != nil {
+		// Roll back so the ids are not lost if the write fails.
+		u.RelayedMsgIDs = ids
+		return nil, err
+	}
+	return ids, nil
+}
+
+// save writes the state atomically (temp file in the same directory, then rename).
+// The caller must hold s.mu.
+func (s *Store) save() error {
+	f := file{Users: make([]*User, 0, len(s.users))}
+	for _, u := range s.users {
+		f.Users = append(f.Users, u)
+	}
+	sort.Slice(f.Users, func(i, j int) bool { return f.Users[i].UserID < f.Users[j].UserID })
+	b, err := json.MarshalIndent(f, "", "  ")
+	if err != nil {
+		return fmt.Errorf("support: marshal state: %w", err)
+	}
+	tmp, err := os.CreateTemp(filepath.Dir(s.path), ".support-*.json")
+	if err != nil {
+		return fmt.Errorf("support: create temp state: %w", err)
+	}
+	tmpName := tmp.Name()
+	defer func() { _ = os.Remove(tmpName) }() // no-op once the rename succeeds
+	if _, err := tmp.Write(b); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("support: write temp state: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("support: close temp state: %w", err)
+	}
+	if err := os.Rename(tmpName, s.path); err != nil {
+		return fmt.Errorf("support: replace state %s: %w", s.path, err)
+	}
+	return nil
+}

platform/telegram/internal/support/store_test.go

@@ -0,0 +1,178 @@
+package support
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+// statePath returns a path inside a fresh temp directory for a store file.
+func statePath(t *testing.T) string {
+	t.Helper()
+	return filepath.Join(t.TempDir(), "support.json")
+}
+
+func TestOpenMissingReturnsEmpty(t *testing.T) {
+	s, err := Open(statePath(t))
+	if err != nil {
+		t.Fatalf("Open missing: %v", err)
+	}
+	if _, ok := s.Get(42); ok {
+		t.Error("Get on an empty store returned a record")
+	}
+}
+
+func TestOpenCorruptReturnsError(t *testing.T) {
+	path := statePath(t)
+	if err := os.WriteFile(path, []byte("{not json"), 0o600); err != nil {
+		t.Fatalf("write corrupt: %v", err)
+	}
+	if _, err := Open(path); err == nil {
+		t.Fatal("Open on a corrupt file: expected an error, got nil")
+	}
+}
+
+func TestSetTopicPersistsAndReloads(t *testing.T) {
+	path := statePath(t)
+	s := New(path)
+	if err := s.SetTopic(7, 100, 101, "Ann", "Lee", "annlee"); err != nil {
+		t.Fatalf("SetTopic: %v", err)
+	}
+
+	// In-memory view.
+	got, ok := s.Get(7)
+	if !ok || got.TopicID != 100 || got.HeaderMsgID != 101 || got.Username != "annlee" {
+		t.Fatalf("Get = %+v ok=%v, want topic 100 / header 101 / annlee", got, ok)
+	}
+	if got.CreatedAt.IsZero() {
+		t.Error("CreatedAt not set on first contact")
+	}
+	if uid, ok := s.ByTopic(100); !ok || uid != 7 {
+		t.Errorf("ByTopic(100) = %d ok=%v, want 7/true", uid, ok)
+	}
+
+	// Reloaded from disk.
+	reload, err := Open(path)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	got, ok = reload.Get(7)
+	if !ok || got.TopicID != 100 || got.FirstName != "Ann" {
+		t.Fatalf("reloaded Get = %+v ok=%v, want topic 100 / Ann", got, ok)
+	}
+	if uid, ok := reload.ByTopic(100); !ok || uid != 7 {
+		t.Errorf("reloaded ByTopic(100) = %d ok=%v, want 7/true", uid, ok)
+	}
+}
+
+func TestSetTopicRecreateReindexes(t *testing.T) {
+	s := New(statePath(t))
+	if err := s.SetTopic(7, 100, 101, "Ann", "", ""); err != nil {
+		t.Fatalf("SetTopic: %v", err)
+	}
+	if err := s.SetTopic(7, 200, 201, "Ann", "", ""); err != nil {
+		t.Fatalf("SetTopic recreate: %v", err)
+	}
+	if _, ok := s.ByTopic(100); ok {
+		t.Error("ByTopic(100) still resolves after recreate; the stale topic was not dropped")
+	}
+	if uid, ok := s.ByTopic(200); !ok || uid != 7 {
+		t.Errorf("ByTopic(200) = %d ok=%v, want 7/true", uid, ok)
+	}
+}
+
+// TestBlockSurvivesTopicRecreate is the field-isolation guarantee: a topic recreate
+// (SetTopic) must not clear a block set concurrently from the buttons.
+func TestBlockSurvivesTopicRecreate(t *testing.T) {
+	s := New(statePath(t))
+	if err := s.SetTopic(7, 100, 101, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("SetTopic: %v", err)
+	}
+	if err := s.SetBlocked(7, true); err != nil {
+		t.Fatalf("SetBlocked: %v", err)
+	}
+	if err := s.SetTopic(7, 200, 201, "Ann", "", "annlee"); err != nil {
+		t.Fatalf("SetTopic recreate: %v", err)
+	}
+	if !s.Blocked(7) {
+		t.Error("block was cleared by a topic recreate")
+	}
+}
+
+func TestAppendAndClearMsgs(t *testing.T) {
+	s := New(statePath(t))
+	if err := s.SetTopic(7, 100, 101, "Ann", "", ""); err != nil {
+		t.Fatalf("SetTopic: %v", err)
+	}
+	for _, id := range []int{500, 501, 502} {
+		if err := s.AppendMsg(7, id); err != nil {
+			t.Fatalf("AppendMsg %d: %v", id, err)
+		}
+	}
+	got, _ := s.Get(7)
+	if len(got.RelayedMsgIDs) != 3 {
+		t.Fatalf("RelayedMsgIDs = %v, want 3 ids", got.RelayedMsgIDs)
+	}
+
+	ids, err := s.ClearMsgs(7)
+	if err != nil {
+		t.Fatalf("ClearMsgs: %v", err)
+	}
+	if len(ids) != 3 || ids[0] != 500 || ids[2] != 502 {
+		t.Errorf("ClearMsgs = %v, want [500 501 502]", ids)
+	}
+	got, _ = s.Get(7)
+	if len(got.RelayedMsgIDs) != 0 {
+		t.Errorf("RelayedMsgIDs after clear = %v, want empty", got.RelayedMsgIDs)
+	}
+	if got.HeaderMsgID != 101 || got.TopicID != 100 {
+		t.Errorf("clear disturbed the topic/header: %+v", got)
+	}
+
+	// A second clear is a no-op.
+	if ids, err := s.ClearMsgs(7); err != nil || ids != nil {
+		t.Errorf("second ClearMsgs = %v, %v, want nil, nil", ids, err)
+	}
+}
+
+func TestGetReturnsDetachedCopy(t *testing.T) {
+	s := New(statePath(t))
+	if err := s.SetTopic(7, 100, 101, "Ann", "", ""); err != nil {
+		t.Fatalf("SetTopic: %v", err)
+	}
+	if err := s.AppendMsg(7, 500); err != nil {
+		t.Fatalf("AppendMsg: %v", err)
+	}
+	got, _ := s.Get(7)
+	got.RelayedMsgIDs[0] = 999 // mutate the copy
+	again, _ := s.Get(7)
+	if again.RelayedMsgIDs[0] != 500 {
+		t.Error("Get returned a slice that aliases the store's state")
+	}
+}
+
+// TestConcurrentMutationsSafe exercises the mutex under parallel writers; run with
+// -race to catch data races.
+func TestConcurrentMutationsSafe(t *testing.T) {
+	s := New(statePath(t))
+	if err := s.SetTopic(7, 100, 101, "Ann", "", ""); err != nil {
+		t.Fatalf("SetTopic: %v", err)
+	}
+	var wg sync.WaitGroup
+	for i := range 20 {
+		wg.Add(1)
+		go func(n int) {
+			defer wg.Done()
+			_ = s.AppendMsg(7, 1000+n)
+			_ = s.SetBlocked(7, n%2 == 0)
+			_, _ = s.Get(7)
+			_, _ = s.ByTopic(100)
+		}(i)
+	}
+	wg.Wait()
+	got, ok := s.Get(7)
+	if !ok || len(got.RelayedMsgIDs) != 20 {
+		t.Errorf("after concurrent appends: %d ids, want 20", len(got.RelayedMsgIDs))
+	}
+}

ui/e2e/fixtures.ts

@@ -1,13 +1,13 @@
 import { test as base } from '@playwright/test';
 
 // All e2e specs run hermetically against the mock transport. Neutralise the real
-// telegram-web-app.js (loaded from the CDN in index.html) so the suite never blocks
+// telegram-web-app.js (the app loads it dynamically — see lib/telegram.ts loadTelegramSDK) so the
-// on telegram.org — it is unreachable from the CI runner, and a render-blocking
+// suite never reaches telegram.org, which is unreachable from the CI runner. Specs that exercise
-// <script> to it would hang every page load. Specs that exercise the Telegram launch
+// the Telegram launch inject their own window.Telegram via addInitScript before navigating, so the
-// inject their own window.Telegram via addInitScript before navigating.
+// dynamic load short-circuits on the already-present SDK.
 export const test = base.extend({
   page: async ({ page }, use) => {
-    await page.route('**/telegram-web-app.js', (route) =>
+    await page.route('**/telegram-web-app.js*', (route) =>
       route.fulfill({ status: 200, contentType: 'application/javascript', body: '' }),
     );
     await use(page);

ui/e2e/social.spec.ts

@@ -44,6 +44,60 @@ test('friends: issue a code, accept an incoming request, redeem a code', async (
   await expect(page.locator('.who', { hasText: 'Friend 111111' })).toBeVisible();
 });
 
+test('friends: the row kebab reveals block/remove and an outside tap closes it', async ({ page }) => {
+  await loginLobby(page);
+  await openFriends(page);
+
+  // A friend row slides open on its kebab (like the lobby), exposing two icon actions.
+  const kaya = page.locator('.rowwrap', { hasText: 'Kaya' });
+  await kaya.locator('.kebab').click();
+  await expect(kaya).toHaveClass(/revealed/);
+  await expect(kaya.locator('.acts').getByRole('button', { name: 'Block' })).toBeVisible();
+  await expect(kaya.locator('.acts').getByRole('button', { name: 'Remove' })).toBeVisible();
+
+  // A tap anywhere outside the action buttons collapses the row again.
+  await page.getByRole('heading', { name: 'Your friends' }).click();
+  await expect(kaya).not.toHaveClass(/revealed/);
+});
+
+test('friends: blocking from the list confirms (naming the friend) and moves them to Blocked', async ({ page }) => {
+  await loginLobby(page);
+  await openFriends(page);
+
+  const kaya = page.locator('.rowwrap', { hasText: 'Kaya' });
+  await kaya.locator('.kebab').click();
+  await kaya.locator('.acts').getByRole('button', { name: 'Block' }).click();
+
+  // The confirmation keeps a generic title and names the friend in the body.
+  const dialog = page.getByRole('dialog');
+  await expect(dialog.getByText('Block this player?')).toBeVisible();
+  await expect(dialog.locator('.confirm-name')).toHaveText('Kaya');
+  await dialog.getByRole('button', { name: 'Block' }).click();
+
+  // The block applied: Kaya leaves the friends list and shows under Blocked players.
+  await expect(page.getByText('No friends yet.')).toBeVisible();
+  const blocked = page.locator('.rowwrap', { hasText: 'Kaya' });
+  await expect(blocked.getByRole('button', { name: 'Unblock' })).toBeVisible();
+});
+
+test('friends: removing from the list confirms (naming the friend) and drops them', async ({ page }) => {
+  await loginLobby(page);
+  await openFriends(page);
+
+  const kaya = page.locator('.rowwrap', { hasText: 'Kaya' });
+  await kaya.locator('.kebab').click();
+  await kaya.locator('.acts').getByRole('button', { name: 'Remove' }).click();
+
+  const dialog = page.getByRole('dialog');
+  await expect(dialog.getByText('Remove from friends?')).toBeVisible();
+  await expect(dialog.locator('.confirm-name')).toHaveText('Kaya');
+  await dialog.getByRole('button', { name: 'Remove' }).click();
+
+  // Unfriending just drops the friendship — Kaya is gone and not blocked.
+  await expect(page.getByText('No friends yet.')).toBeVisible();
+  await expect(page.locator('.rowwrap', { hasText: 'Kaya' })).toHaveCount(0);
+});
+
 test('invitations: the lobby shows an invitation and accepting clears it', async ({ page }) => {
   await loginLobby(page);
   await expect(page.getByText('Invitations')).toBeVisible();

ui/e2e/telegram.spec.ts

@@ -107,11 +107,30 @@ test('inside Telegram, a failed launch shows the retry screen, not the web login
   await expect(page.getByRole('button', { name: /guest/i })).toHaveCount(0);
 });
 
-test('outside Telegram, the /telegram/ entry redirects to the site root', async ({ page }) => {
+test('outside Telegram, the /telegram/ entry shows the launch diagnostic, not a redirect', async ({
+  page,
+}) => {
   await page.goto('/telegram/');
 
-  // The guard sends a non-Telegram visitor back to the root, where the normal
+  // The entry no longer bounces a visitor without Telegram sign-in data to the marketing landing;
-  // (guest / email) login is shown.
+  // it shows a compact diagnostic screen (Share + Retry) that helps pinpoint why initData was
-  await expect(page.getByRole('button', { name: /guest/i })).toBeVisible();
+  // absent — notably the Android empty-initData failure.
-  await expect(page).not.toHaveURL(/\/telegram\//);
+  await expect(page.getByRole('button', { name: 'Share' })).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+  // It stays on /telegram/ (no redirect) and never shows the web (guest) login.
+  await expect(page).toHaveURL(/\/telegram\//);
+  await expect(page.getByRole('button', { name: /guest/i })).toHaveCount(0);
+});
+
+test('a blocked telegram-web-app.js does not hang the diagnostic screen', async ({ page }) => {
+  // Simulate a network where telegram.org is unreachable: the SDK fetch fails. Because the SPA
+  // loads the SDK dynamically with a timeout (not a render-blocking <script>), a failed/blocked
+  // fetch must not strand the page — the diagnostic screen still renders, reporting no SDK. (This
+  // route overrides the fixture's empty-body fulfill; the later registration wins.)
+  await page.route('**/telegram-web-app.js*', (route) => route.abort());
+  await page.goto('/telegram/');
+
+  await expect(page.getByRole('button', { name: 'Share' })).toBeVisible();
+  // The diagnostic names the load outcome: a failed fetch reads as sdk-load: error.
+  await expect(page.getByText('sdk-load: error')).toBeVisible();
 });

ui/index.html

@@ -2,9 +2,11 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <!-- Telegram Mini App SDK: defines window.Telegram.WebApp. Harmless outside
+    <!-- The Telegram Mini App SDK (window.Telegram.WebApp) is deliberately NOT loaded here: a
-         Telegram (initData is empty), so it loads on every entry. -->
+         render-blocking <script> to telegram.org hangs the whole page on a network that blocks
-    <script src="https://telegram.org/js/telegram-web-app.js"></script>
+         telegram.org (common where Telegram itself reaches users only over a proxy), stranding even
+         the launch-diagnostic screen. The app loads it dynamically, with a timeout, only on a
+         Telegram entry — see lib/telegram.ts loadTelegramSDK and lib/app.svelte.ts bootstrap. -->
     <!-- user-scalable=no: the board owns zoom; we do not want the browser's pinch
          to fight our two-state zoom. viewport-fit=cover for native (Capacitor). -->
     <meta

ui/src/App.svelte

@@ -2,13 +2,13 @@
   import { onMount } from 'svelte';
   import { cubicOut } from 'svelte/easing';
   import { app, bootstrap } from './lib/app.svelte';
-  import { navigate, router, type RouteName } from './lib/router.svelte';
+  import { router, type RouteName } from './lib/router.svelte';
   import { t } from './lib/i18n/index.svelte';
-  import { insideTelegram, telegramBackButton } from './lib/telegram';
   import Toast from './components/Toast.svelte';
   import Splash from './components/Splash.svelte';
   import StaleInviteModal from './components/StaleInviteModal.svelte';
   import WelcomeRedeemModal from './components/WelcomeRedeemModal.svelte';
+  import DebugPanel from './components/DebugPanel.svelte';
   import Login from './screens/Login.svelte';
   import Lobby from './screens/Lobby.svelte';
   import NewGame from './screens/NewGame.svelte';
@@ -19,6 +19,7 @@
   import Feedback from './screens/Feedback.svelte';
   import Blocked from './screens/Blocked.svelte';
   import BootError from './screens/BootError.svelte';
+  import TelegramLaunchError from './screens/TelegramLaunchError.svelte';
 
   onMount(() => {
     void bootstrap();
@@ -29,19 +30,6 @@
   // another screen is not covered.
   const routeIsLobby = $derived(router.route.name === 'lobby');
 
-  // Inside Telegram, drive its native header back button: show it on any sub-screen
-  // (everything returns to the lobby root), hide it on the lobby/login. The app's own
-  // back chevron is hidden in Telegram (Header.svelte) so only the native one shows.
-  $effect(() => {
-    if (!insideTelegram()) return;
-    const r = router.route;
-    // The chat / check sub-screens step back to their game; every other sub-screen to the lobby.
-    let target = '/';
-    if (r.name === 'gameChat' || r.name === 'gameCheck') target = `/game/${r.params.id}`;
-    else if (r.name === 'feedback') target = '/about'; // back to the Settings → Info tab
-    telegramBackButton(r.name !== 'lobby' && r.name !== 'login', () => navigate(target));
-  });
-
   // Screen transitions: the lobby is the navigation root. Entering a screen from the
   // lobby slides it in from the right (forward); returning to the lobby slides the
   // screen out to the right and reveals the lobby (back). Transitions are local, so
@@ -84,6 +72,11 @@
   {#if !routeIsLobby}
     <div class="splash">{t('common.loading')}</div>
   {/if}
+{:else if app.launchError}
+  <!-- The /telegram/ entry without sign-in data: a compact, shareable diagnostic screen instead
+       of bouncing to the marketing landing (also the probe for the empty-initData failure on
+       some Android clients). -->
+  <TelegramLaunchError />
 {:else if app.bootError}
   <!-- A Mini App launch that failed to authenticate (e.g. the backend was down mid-deploy):
        show the retry screen instead of falling back to the web login. -->
@@ -128,10 +121,14 @@
 <StaleInviteModal />
 <WelcomeRedeemModal />
 
-{#if routeIsLobby && !app.splashDone && !app.blocked && !app.bootError}
+{#if routeIsLobby && !app.splashDone && !app.blocked && !app.bootError && !app.launchError}
   <Splash />
 {/if}
 
+{#if app.debugOpen}
+  <DebugPanel />
+{/if}
+
 <style>
   .splash {
     height: 100%;

ui/src/app.css

@@ -49,6 +49,11 @@
   /* Telegram device safe-area top (the notch); TG's own nav controls sit between it and
      --tg-content-top, so the in-app header aligns to that band, 0 elsewhere. */
   --tg-safe-top: 0px;
+  /* Telegram device safe-area bottom / sides (home indicator; landscape notch), 0 elsewhere —
+     the screen pads its bottom and left/right edges by these so content clears the cut-outs. */
+  --tg-safe-bottom: 0px;
+  --tg-safe-left: 0px;
+  --tg-safe-right: 0px;
   --font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial,
     "Noto Sans", "Liberation Sans", sans-serif;
   --shadow: 0 1px 2px rgba(0, 0, 0, 0.08), 0 6px 16px rgba(0, 0, 0, 0.06);

ui/src/components/DebugPanel.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+  // Hidden on-device debug panel, opened by tapping the header title ten times (Header.svelte) and
+  // closed by tapping anywhere except the Share control. It shows a privacy-safe client diagnostic
+  // snapshot (no secrets, no initData values, no IP) and shares it through the OS share sheet (or a
+  // clipboard copy on desktop) — a support aid for reproducing client-specific issues, e.g. the
+  // Telegram Android presentation quirks. Drawn from the top, just under the app header.
+  import { app, closeDebug } from '../lib/app.svelte';
+  import { connection } from '../lib/connection.svelte';
+  import { shareText } from '../lib/share';
+  import { telegramChromeDiag } from '../lib/telegram';
+
+  const report = [
+    `app: ${__APP_VERSION__}`,
+    `locale: ${app.locale}  theme: ${app.theme}  reduceMotion: ${app.reduceMotion}`,
+    `online: ${connection.online}  streamAlive: ${app.streamAlive}`,
+    `userId: ${app.session?.userId ?? '—'}  guest: ${app.profile?.isGuest ?? '—'}`,
+    telegramChromeDiag(),
+  ].join('\n');
+
+  let label = $state('Share');
+  async function share(e: MouseEvent): Promise<void> {
+    e.stopPropagation(); // a tap on Share shares; it must not also close the panel
+    const r = await shareText(report, `Scrabble debug ${__APP_VERSION__}`);
+    if (r === 'copied') {
+      label = 'Copied';
+      setTimeout(() => (label = 'Share'), 1500);
+    }
+  }
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="overlay" onclick={closeDebug}>
+  <button class="share" onclick={share}>{label}</button>
+  <pre class="body">{report}</pre>
+</div>
+
+<style>
+  .overlay {
+    position: fixed;
+    inset: 0;
+    z-index: 10000;
+    /* Drawn from the top; the content clears the app header (~56px + the device safe-area). */
+    padding: calc(var(--tg-safe-top, 0px) + 56px) 12px 16px;
+    background: rgba(0, 0, 0, 0.82);
+    overflow: auto;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    align-items: flex-start;
+  }
+  .share {
+    flex: 0 0 auto;
+    padding: 7px 16px;
+    border: 1px solid var(--accent);
+    background: var(--accent);
+    color: var(--accent-text);
+    border-radius: var(--radius-sm);
+    font-size: 0.95rem;
+  }
+  .body {
+    margin: 0;
+    width: 100%;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 11px;
+    line-height: 1.45;
+    color: #d6e6ff;
+  }
+</style>

ui/src/components/Header.svelte

@@ -1,17 +1,30 @@
 <script lang="ts">
   import { navigate } from '../lib/router.svelte';
-  import { insideTelegram } from '../lib/telegram';
   import { connection } from '../lib/connection.svelte';
   import { t } from '../lib/i18n/index.svelte';
-  import { app } from '../lib/app.svelte';
+  import { app, openDebug } from '../lib/app.svelte';
   import Spinner from './Spinner.svelte';
   import AdBanner from './AdBanner.svelte';
 
   let { title, back, grow = false }: { title: string; back?: string; grow?: boolean } = $props();
 
-  // Inside Telegram the native header back button (App.svelte) is the back control, so
+  // The app always shows its own back chevron when there is a back target — on every platform, in
-  // the app's own chevron is hidden to avoid two back affordances.
+  // and out of Telegram. The native Telegram BackButton is not used: it does not render reliably in
-  const showBack = $derived(!!back && !insideTelegram());
+  // the windowed Mini App (relying on it would lose back navigation there).
+  const showBack = $derived(!!back);
+
+  // Ten quick taps on the title open the hidden debug panel (components/DebugPanel) — a support aid.
+  let titleTaps = 0;
+  let lastTitleTap = 0;
+  function onTitleTap(): void {
+    const now = Date.now();
+    titleTaps = now - lastTitleTap < 400 ? titleTaps + 1 : 1;
+    lastTitleTap = now;
+    if (titleTaps >= 10) {
+      titleTaps = 0;
+      openDebug();
+    }
+  }
 </script>
 
 <header class="nav" class:grow>
@@ -24,7 +37,9 @@
       <span class="spacer"></span>
     {/if}
     {#if connection.online}
-      <h1>{title}</h1>
+      <!-- svelte-ignore a11y_click_events_have_key_events -->
+      <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+      <h1 onclick={onTitleTap}>{title}</h1>
     {:else}
       <h1 class="connecting"><Spinner /> <span>{t('connection.connecting')}</span></h1>
     {/if}
@@ -66,7 +81,7 @@
     display: flex;
     align-items: center;
     gap: var(--gap);
-    padding: 10px var(--pad);
+    padding: 5px var(--pad);
   }
   h1 {
     font-size: 1.05rem;
@@ -124,15 +139,15 @@
        back chevron is hidden), so min-height (the nav-band height) doesn't bind. Without the
        (removed) hamburger that content shrank and the bar sat flush under Telegram's native nav
        band. So **padding-top** is the lever: it drops the title clear of the band — the notch
-       plus a **10px** gap (was 6). A fixed px (not rem/em) gap so the clearance from Telegram's
+       plus an **8px** gap (halved from 16). A fixed px (not rem/em) gap so the clearance from
-       native controls stays constant if the user scales up the font (the title then grows
+       Telegram's native controls stays constant if the user scales up the font (the title then
-       downward and the bar with it). (Owner-tunable: the 10px.) */
+       grows downward and the bar with it). (Owner-tunable: the 8px.) */
     min-height: var(--tg-content-top);
     box-sizing: border-box;
     align-items: center;
     justify-content: center;
-    padding-top: calc(var(--tg-safe-top) + 16px);
+    padding-top: calc(var(--tg-safe-top) + 8px);
-    padding-bottom: 6px;
+    padding-bottom: 3px;
   }
   :global(html.tg-fullscreen) .spacer {
     display: none;

ui/src/components/Screen.svelte

@@ -101,6 +101,12 @@
        bottom input — chat, word-check — stays above an open soft keyboard without the page
        scrolling; falls back to the full height where the var is unset. */
     height: var(--vvh, 100%);
+    /* Clear the landscape notch sides inside Telegram (0 elsewhere). The top inset is owned by the
+       header; the home-indicator (bottom) inset is owned by the bottom bar — the .tabbar paints its
+       own chrome into it, and a screen with no tab bar pads its content (.content:last-child) — so
+       the strip takes the bar's colour rather than the detached content background. */
+    padding-left: var(--tg-safe-left, 0px);
+    padding-right: var(--tg-safe-right, 0px);
   }
   .content {
     flex: 0 1 auto;
@@ -116,7 +122,18 @@
     display: flex;
     flex-direction: column;
   }
+  /* No tab bar → the content is the bottom-most element: pad it by the device home-indicator inset
+     so it clears the cut-out, the strip taking the content's own background. With a tab bar the
+     .tabbar owns that inset instead (and content is not the last child, so this does not apply). */
+  .content:last-child {
+    padding-bottom: var(--tg-safe-bottom, 0px);
+  }
   .tabbar {
     flex: 0 0 auto;
+    /* Extend the bottom bar's chrome (the TabBar's --bg-elev) under the device home indicator
+       inside Telegram (the inset is 0 elsewhere), so the safe-area strip reads as part of the bar
+       instead of the content background showing through. */
+    background: var(--bg-elev);
+    padding-bottom: var(--tg-safe-bottom, 0px);
   }
 </style>

ui/src/components/StaleInviteModal.svelte

@@ -1,8 +1,10 @@
 <script lang="ts">
   import { app, dismissStaleInvite } from '../lib/app.svelte';
+  import { router } from '../lib/router.svelte';
   import { t } from '../lib/i18n/index.svelte';
   import { botUsername } from '../lib/deeplink';
-  import { telegramOpenLink } from '../lib/telegram';
+  import { insideTelegram, telegramDialogsAvailable, telegramOpenLink, telegramShowPopup } from '../lib/telegram';
+  import { BOT_BUTTON_ID, botInfoPopup } from '../lib/nativedialogs';
   import Modal from './Modal.svelte';
 
   // The single bot's @username, for the deep link.
@@ -19,9 +21,30 @@
     }
     dismissStaleInvite();
   }
+
+  // Native path: when the notice fires inside the Mini App with native popups, present Telegram's
+  // own popup instead of the in-app modal. insideTelegram()/dialogs are evaluated at fire time, not
+  // captured at init: this component mounts before bootstrap loads the SDK, so a captured value
+  // would be stale. The popup's "open bot" button opens the bot chat; any other dismissal clears the
+  // notice; the `shown` guard fires it once per notice.
+  // The notice is raised during boot; wait until the loading cover for the current route is gone —
+  // the tile splash on the lobby (splashDone), the plain loading screen elsewhere (app.ready) — so
+  // the native popup never appears over the splash.
+  const ready = $derived(router.route.name === 'lobby' ? app.splashDone : app.ready);
+  let shown = false;
+  $effect(() => {
+    if (app.staleInvite && !shown && ready && insideTelegram() && telegramDialogsAvailable()) {
+      shown = true;
+      void telegramShowPopup(
+        botInfoPopup(t('friends.staleInviteTitle'), t('friends.staleInvite'), username ?? '', t('common.ok')),
+      ).then((id) => (id === BOT_BUTTON_ID ? openBot() : dismissStaleInvite()));
+    } else if (!app.staleInvite) {
+      shown = false;
+    }
+  });
 </script>
 
-{#if app.staleInvite}
+{#if app.staleInvite && ready && !(insideTelegram() && telegramDialogsAvailable())}
   <Modal title={t('friends.staleInviteTitle')} onclose={dismissStaleInvite}>
     <p class="msg">{parts[0]}{#if username}<button type="button" class="bot" onclick={openBot}>@{username}</button>{/if}{parts[1] ?? ''}</p>
     <button class="ok" onclick={dismissStaleInvite}>{t('common.ok')}</button>

ui/src/components/WelcomeRedeemModal.svelte

@@ -1,8 +1,10 @@
 <script lang="ts">
   import { app, dismissWelcomeRedeem } from '../lib/app.svelte';
+  import { router } from '../lib/router.svelte';
   import { t } from '../lib/i18n/index.svelte';
   import { botUsername } from '../lib/deeplink';
-  import { telegramOpenLink } from '../lib/telegram';
+  import { insideTelegram, telegramDialogsAvailable, telegramOpenLink, telegramShowPopup } from '../lib/telegram';
+  import { BOT_BUTTON_ID, botInfoPopup } from '../lib/nativedialogs';
   import Modal from './Modal.svelte';
 
   // The single bot's @username, for the deep link.
@@ -22,9 +24,30 @@
     }
     dismissWelcomeRedeem();
   }
+
+  // Native path: when the greeting fires inside the Mini App with native popups, present Telegram's
+  // own popup instead of the in-app modal. insideTelegram()/dialogs are evaluated at fire time, not
+  // captured at init: this component mounts before bootstrap loads the SDK, so a captured value
+  // would be stale. The popup's "open bot" button opens the bot chat; any other dismissal clears it;
+  // the `shown` guard fires it once per greeting.
+  // The greeting is raised during boot; wait until the loading cover for the current route is gone —
+  // the tile splash on the lobby (splashDone), the plain loading screen elsewhere (app.ready) — so
+  // the native popup never appears over the splash.
+  const ready = $derived(router.route.name === 'lobby' ? app.splashDone : app.ready);
+  let shown = false;
+  $effect(() => {
+    if (app.welcomeRedeem && !shown && ready && insideTelegram() && telegramDialogsAvailable()) {
+      shown = true;
+      void telegramShowPopup(
+        botInfoPopup(t('friends.welcomeRedeemTitle'), t('friends.welcomeRedeem', { name }), username ?? '', t('common.ok')),
+      ).then((id) => (id === BOT_BUTTON_ID ? openBot() : dismissWelcomeRedeem()));
+    } else if (!app.welcomeRedeem) {
+      shown = false;
+    }
+  });
 </script>
 
-{#if app.welcomeRedeem}
+{#if app.welcomeRedeem && ready && !(insideTelegram() && telegramDialogsAvailable())}
   <Modal title={t('friends.welcomeRedeemTitle')} onclose={dismissWelcomeRedeem}>
     <p class="msg">{parts[0]}{#if username}<button type="button" class="bot" onclick={openBot}>@{username}</button>{/if}{parts[1] ?? ''}</p>
     <button class="ok" onclick={dismissWelcomeRedeem}>{t('common.ok')}</button>

ui/src/components/WordTiles.svelte

@@ -1,12 +1,14 @@
 <script lang="ts">
   // A best-move word drawn as a row of game tiles, mirroring the board's placed-tile
   // look (letter top-left, point value bottom-right) at a small fixed size. A blank tile
-  // shows its letter but no value, exactly as on the board. Letters are upper-cased for
+  // shows its letter but no value, exactly as on the board; in Erudit it also carries the
-  // display. The tile values ride on each tile, so this renders without the variant's
+  // blank's star (✻) in the value corner. Letters are upper-cased for display. The tile
-  // alphabet table (which the statistics screen has not cached).
+  // values ride on each tile, so this needs only the variant id (for the star) — not the
-  import type { BestMoveTile } from '../lib/model';
+  // variant's alphabet table, which the statistics screen has not cached.
+  import type { BestMoveTile, Variant } from '../lib/model';
+  import { usesStarBlank, BLANK_STAR } from '../lib/variants';
 
-  let { word }: { word: BestMoveTile[] } = $props();
+  let { word, variant }: { word: BestMoveTile[]; variant: Variant } = $props();
 
   const label = $derived(word.map((t) => t.letter).join('').toUpperCase());
 </script>
@@ -15,7 +17,11 @@
   {#each word as tile, i (i)}
     <span class="tile" class:blank={tile.blank} aria-hidden="true">
       <span class="letter">{tile.letter.toUpperCase()}</span>
-      {#if !tile.blank}<span class="val">{tile.value}</span>{/if}
+      {#if !tile.blank}
+        <span class="val">{tile.value}</span>
+      {:else if usesStarBlank(variant)}
+        <span class="val blankmark">{BLANK_STAR}</span>
+      {/if}
     </span>
   {/each}
 </span>
@@ -50,4 +56,10 @@
     font-size: 7px;
     font-weight: 600;
   }
+  /* A placed Erudit blank ("звёздочка") shows its star where the (absent) point value sits,
+     its ink kept on the value digits' line (mirrors the board tile). */
+  .blankmark {
+    font-size: 8px;
+    bottom: 0;
+  }
 </style>

ui/src/game/Board.svelte

@@ -4,6 +4,7 @@
   import type { Premium } from '../lib/premiums';
   import { valueForLetter } from '../lib/alphabet';
   import type { Variant } from '../lib/model';
+  import { usesStarBlank, BLANK_STAR } from '../lib/variants';
   import { bonusLabel, type BoardLabelMode } from '../lib/boardlabels';
   import type { Locale } from '../lib/i18n/catalog';
 
@@ -254,7 +255,11 @@
           >
             {#if letter}
               <span class="letter">{letter}</span>
-              {#if !blank}<span class="val">{valueForLetter(variant, letter)}</span>{/if}
+              {#if !blank}
+                <span class="val">{valueForLetter(variant, letter)}</span>
+              {:else if usesStarBlank(variant)}
+                <span class="val blankmark">{BLANK_STAR}</span>
+              {/if}
             {:else if r === centre.row && c === centre.col}
               <span class="star">★</span>
             {:else if bl?.kind === 'single'}
@@ -410,6 +415,12 @@
     font-size: 2.4cqw;
     font-weight: 600;
   }
+  /* A placed Erudit blank ("звёздочка") shows its star where the (absent) point value sits,
+     its ink centred on the same line as a neighbouring tile's value digit. */
+  .blankmark {
+    font-size: 2.8cqw;
+    bottom: 0;
+  }
   .star {
     position: absolute;
     inset: 0;