Merge pull request 'release: v1.20.0 — offline-UX, catalog order + admin toggles, reward-config admin' (#263) from development into master

The "watch for chips" rewarded payout and its per-day / per-hour caps live in the
shared payments.config row and had no admin surface — they could only be changed by
SQL, contrary to D32 (the rewarded rate is meant to be admin-configurable). Add a
"Rewarded ads" form on the /_gm/catalog page: RewardConfig / SetRewardConfig on the
service (non-negative validated), a setRewardConfig store writer (the singleton
config row), the consoleSetReward handler + POST /_gm/catalog/reward route, and the
form pre-filled from the current config. No migration — the columns already exist.

The reward rate is a config value, not a sellable catalog atom (so a "no-ads forever"
style product is still out of scope by D32/D33).

Test: an integration test sets the config, checks the page pre-fill, and refuses a
negative value.

.claude/CLAUDE.md

@@ -0,0 +1,242 @@
+# Agent field notes — scrabble-game
+
+Non-obvious, hard-won project knowledge that is **not** in the main docs (`CLAUDE.md`, `docs/*`,
+`deploy/README.md`). Kept in the repo so it travels with a clone to any host. These are working
+memory, not a spec — **verify any named file / flag / function against the current code before acting
+on it**, and prefer the authoritative docs where they overlap. Add to this file as new gotchas turn up.
+
+## Codegen & build
+
+- **jetgen churns everything.** `backend/cmd/jetgen` regenerates go-jet code for *all* tables and may
+  reorder output. After running it, revert the churn on tables you did not touch and commit only your
+  table's change.
+- **flatc is version-pinned** (`pkg/Makefile`, `REQUIRED_FLATC = 23.5.26`, hard-checked). A different
+  flatc silently churns the generated wire code and can flip wire defaults. Never regenerate FBS with
+  another flatc version.
+- **gopls lags codegen.** Right after an FBS/jet regen, gopls shows phantom "undefined" errors. Trust
+  `go build` / `go test`, not the editor squiggles.
+- **go-jet type mapping:** SQL `numeric` → `float64`, `interval` → `string`. Never store money as
+  `numeric` (float precision loss) — use **bigint minor units + a `Money` type**; store durations as
+  **int seconds**, not `interval`.
+- **`go mod tidy` chokes on dot-free local module paths** (`scrabble/...`). Hand-edit `go.mod` when a
+  bump is needed. The solver (`../scrabble-solver`) is consumed via `go.work` replace locally, but a
+  prod bump goes through a solver **PR → master + a published tag**, not a local replace.
+- **Run the whole CI suite locally before pushing** — unit + integration (`//go:build integration`,
+  Postgres) + the UI job + codegen check. Do not lean on CI to catch what a local run would.
+- **CI runner shares this host's `/tmp` as a different user.** In workflow steps, write artifacts to
+  `${GITHUB_WORKSPACE}`, never a fixed `/tmp/...` path (cross-user permission failures otherwise).
+- **pnpm corepack pre-flight flakes.** `pnpm exec` / `pnpm check` occasionally abort on a corepack
+  pre-flight. Dodge it by invoking the tool directly: `node_modules/.bin/<tool>`.
+
+## Native Android build (Capacitor)
+
+The native Android app is a Capacitor 8 wrapper of the `ui` SPA, scaffolded under
+`ui/` (a Node project outside `go.work`). Hard-won bring-up facts — verify against current code:
+
+- **Capacitor 8 needs JDK 21, not 17.** `@capacitor/android` compiles at `VERSION_21`; a JDK 17 Gradle
+  run dies with `error: invalid source release: 21`. Install sudo-free via the Homebrew **formula**
+  `brew install openjdk@21` (the `temurin@21` **cask** wants sudo for a system `.pkg`, unusable
+  non-interactively) + a user symlink into `~/Library/Java/JavaVirtualMachines/` so
+  `/usr/libexec/java_home -v 21` finds it. JDK 17 stays fine for `sdkmanager`/`avdmanager`.
+- **Cap 8 SDK pins:** compileSdk/targetSdk **36**, minSdk **24**, Gradle **8.14.3**, AGP **8.13.0**
+  (`ui/android/variables.gradle`). Install `platforms;android-36` — Android Studio's newer
+  `android-36.1` does NOT satisfy compileSdk 36.
+- **SDK is Android Studio's** at `~/Library/Android/sdk` (no `cmdline-tools` by default → `brew install
+  --cask android-commandlinetools`, then `sdkmanager`/`avdmanager --sdk_root=$HOME/Library/Android/sdk`).
+  Gradle finds it via **`ANDROID_HOME`** (`local.properties` is gitignored, machine-specific).
+- **Build recipe:** `cd ui && pnpm build && node_modules/.bin/cap sync android`; then `cd ui/android &&
+  ANDROID_HOME=~/Library/Android/sdk JAVA_HOME=$(/usr/libexec/java_home -v 21) ./gradlew assembleDebug`
+  → `ui/android/app/build/outputs/apk/debug/app-debug.apk`. Prefer the local `ui/node_modules/.bin/cap`
+  (dodges the corepack flake).
+- **Emulator smoke:** existing AVDs `Pixel_10` / `Pixel_4_Android_10_API_29` / `Pixel_Android_9`;
+  `emulator -avd <name>`, `adb install -r <apk>`, `adb shell monkey -p ru.eruditgame.app -c
+  android.intent.category.LAUNCHER 1`, `adb exec-out screencap -p > x.png`. The boot wait needs `sleep`
+  → run it as a **background** Bash task (foreground `sleep` is blocked). Browsers/WebView are cached, so a
+  full offline vs_ai turn is drivable via `adb shell input tap` (tap through the first-run coachmark tour —
+  each tap advances one step — then Hint places a suggested word; commit → the robot replies).
+- **Android 15+ edge-to-edge safe-area (WebView-version-dependent, bit me on API 37).** targetSdk 36 forces
+  edge-to-edge — the WebView draws behind the status bar (top) and the gesture-nav home indicator (bottom).
+  On Android **WebView < 140**, `env(safe-area-inset-*)` wrongly reports **0**, so chrome relying on it draws
+  under the bars and is untappable: the top nav under the clock, and the game's bottom action bar's **centre**
+  button (Hint) under the home-indicator pill (side buttons still work; `navigation_mode`=2 is gesture nav).
+  Fix is CSS-only, in TWO parts: (1) Capacitor 8's **SystemBars** plugin (built into `@capacitor/core`,
+  `insetsHandling:'css'` default — no dep, no config) injects correct `--safe-area-inset-*`; consume them as
+  `--tg-safe-*: var(--safe-area-inset-*, env(safe-area-inset-*, 0px))` (`ui/src/app.css`) — fixes any consumer
+  that ALREADY applies the token (the bottom bars: `Game.svelte`/`Screen.svelte` `--tg-safe-bottom`).
+  (2) But a consumer that never applied the top inset on the native path is NOT fixed by the token alone — the
+  **header's** top inset was Telegram-fullscreen-scoped only, so the native header sat under the status bar on
+  EVERY WebView; it needed its own `.bar { padding-top: calc(var(--safe-area-inset-top, 0px) + 5px) }`
+  (`Header.svelte`, native-only via the plugin var; tg-fullscreen still overrides via specificity). **Measure
+  per element, don't eyeball** — a centred title at y=11 under a 54px bar reads as "fine" in a screenshot but
+  is overlapping; an emulator WebView auto-updated to ≥140 (Chrome 149) also hides the `env()`=0 half (so the
+  BOTTOM looks fine there while the user's < 140 device overlaps). **Inspect a live debug WebView** over CDP:
+  `adb forward tcp:9222 localabstract:$(adb shell cat /proc/net/unix | grep -o 'webview_devtools_remote_[0-9]*'
+  | head -1)`, then Playwright `chromium.connectOverCDP('http://localhost:9222')` → `page.evaluate` (read each
+  element's `getBoundingClientRect().top`, and `--safe-area-inset-*` vs `env(...)`).
+- **`sharp` is whitelisted** in `ui/pnpm-workspace.yaml` (`allowBuilds: sharp: true`) — `@capacitor/assets`
+  uses it for `pnpm android:assets` (launcher icon/splash); else pnpm 11 raises `ERR_PNPM_IGNORED_BUILDS`.
+- **Bundled offline dicts come from the `scrabble-dictionary` release** (`scrabble-dawg-<DICT_VERSION>.tar.gz`,
+  keyed on the `DICT_VERSION` Gitea var — the same source the backend image + CI `curl`), NOT
+  `scrabble-solver/dawg` (those are the solver's pinned test fixtures).
+
+## Wire / schema evolution (client ↔ gateway ↔ backend)
+
+- **FBS is additive-only.** Add **trailing** fields ("added trailing — backward-compatible"). Never
+  delete or reorder a mid-table field — **deprecate** it (`(deprecated)`); deleting shifts field IDs
+  and breaks older readers.
+- **Retiring a domain field must also retire the WIRE field it fed** — by deprecation, not deletion,
+  and do not just zero it: a dead `0` the client dutifully syncs will clobber the real value.
+- **The gateway transcodes FBS ↔ backend JSON DTOs in lockstep.** A wire change usually means editing
+  both the FBS schema and the backend DTO.
+- **Seat display name is built in two places** — `game.Service` live events **and** the server REST
+  DTOs. Change both or they drift.
+- **A per-viewer flag is computed only in the per-viewer REST DTO**; the client seeds it from REST,
+  then bumps it from the live event. Don't expect it on the shared broadcast.
+
+## UI / Svelte 5
+
+- **Never name a `$state` variable `state`.** `svelte-check` then misreads `$state` as a store
+  subscription. Rename (e.g. `view`).
+- **Svelte trims literal edge whitespace** in markup. To keep a separator space, emit an expression:
+  `{' : '}`.
+- **No global `.btn` / `.ghost` button classes.** Style buttons per-component with scoped CSS + design
+  tokens (mirror `NewGame`'s `.invite`).
+- **A `$state` proxy fails structured-clone** when persisted to IndexedDB. Snapshot at the call site
+  with `$state.snapshot(...)` before storing.
+
+## Platform / WebView quirks (Telegram, VK, iOS, native, old Android)
+
+- **Telegram `showPopup` eats the user-activation.** Share / clipboard called from inside a
+  `showPopup` callback fail (no gesture). Use your own `Modal` for gesture-gated Web APIs.
+- **iOS Telegram `<a download blob:>` navigates away** and strands the SPA. Deliver files by **Web
+  Share on mobile**, and only use a `<a download>` Blob path on **desktop**.
+- **Android TG/VK WebViews** lack `navigator.share` and ignore `<a download>`. Deliver a
+  client-generated file by **copying it to the clipboard**.
+- **VK Android WebView ignores `target=_blank`.** Open external links through `lib/links.ts`
+  (routes to `vk.com/away.php`). Verify on-device.
+- **Per-platform file-delivery last hop differs** (TG / VK / plain browser) — there is a delivery
+  matrix; do not re-litigate it without new on-device facts.
+- **Old Android System WebView floor ≈ Chrome 67.** The bundle targets **es2019** (esbuild lowers
+  syntax), a conditional `core-js` polyfill loads only on old engines, and `index.html` has a boot
+  gate (BigInt / Proxy are the hard block → the unsupported-engine screen). There's also a `vmin`
+  glyph fallback for old rendering.
+- **iOS WKWebView overscroll and Telegram swipe-to-close are not reproducible in Playwright.** Verify
+  those live on the deployed contour, not in the e2e.
+- **Telegram Desktop Mini App shows a persistent bottom-right loader** — that's the long-lived
+  Subscribe stream, cosmetic, deliberately left as-is.
+
+## Testing
+
+- **UI test layers:** vitest (node env, pure logic, **no jsdom**) + Playwright **mock** e2e. The mock
+  e2e **bypasses the codec**, so wire/codec bugs need **codec unit tests**, not e2e coverage.
+- **Mock overlay blocks e2e.** The cold-load overlay must be instant under the mock build or it
+  intercepts Playwright taps.
+- **Mock tile pools lack a blank `'?'`.** The seeded game `G1` hard-codes one; flip `G1`'s variant to
+  eyeball per-variant tiles.
+- **Durable Playwright MCP servers** (chromium + webkit) exist for UI inspection (there's a
+  plugin-config gotcha in wiring them).
+- **The `playwright test` runner can't *fetch* browsers in this sandbox** — `playwright install` dies
+  with `EBADF` against the Playwright CDN (blocked network), even with the sandbox off. Run the e2e in
+  **CI** (the `ui` job installs chromium+webkit), or drive a state live through the **Playwright MCP**
+  browser against a local `vite --mode mock` server for visual verification. **But if chromium/webkit are
+  already cached** in `~/Library/Caches/ms-playwright/`, `playwright test` runs locally fine (only the CDN
+  fetch is blocked) — the native offline-first e2e was run green locally this way (chromium + webkit),
+  its dawgs from the sibling `../../scrabble-solver/dawg` via the webServer's `bundle-dicts.mjs` fallback.
+- **A native (Capacitor) e2e must inject `window.androidBridge`, NOT `window.Capacitor.getPlatform`.**
+  `@capacitor/core` (pulled in during boot by `initNativeShell`'s dynamic `@capacitor/app` import)
+  **replaces** any pre-set `window.Capacitor` with its own shim and derives the platform from
+  `window.androidBridge` (android) / `window.webkit.messageHandlers` (ios) — so a bare injected
+  `Capacitor.getPlatform: () => 'android'` is clobbered to `web` and the boot falls to `/login`. Inject
+  `window.androidBridge = { postMessage(){} }` in an `addInitScript` (see `e2e/native.spec.ts` `simulateNative`);
+  `initNativeShell` is written to tolerate the stub bridge (`try/catch` round the `@capacitor/app` addListener).
+- **`docker run -p ...` boot tests fail from the shell** (published ports unreachable in this env).
+  Use **testcontainers** for container-backed tests.
+- **Distroless images run as UID 65532 (nonroot).** Bind-mounted TLS keys must be **0644** (not 0600)
+  or the service crash-loops on start.
+
+## Deploy / test contour (operational)
+
+- **The TEST contour runs on THIS dev host.** Inspect it via `docker` / Prometheus. A host-side
+  `curl` to caddy **hangs** (NAT hairpin) — don't debug the edge that way.
+- **The contour's client IP is the home-router SNAT address**, not the real external IP. Correct in
+  prod, not a bug — which is why the IP ban / blocklist are **prod-only**.
+- **The contour is one shared env, last-deploy-wins.** Keep a multi-PR batch a **linear stack** (one
+  PR, one deploy) so deploys don't clobber each other.
+- **A schema/wire PR breaks the contour** until a `DROP SCHEMA` + backend restart. Note such a
+  prerelease step in `PRERELEASE.md`.
+- **A contour DB wipe resets the account but not the client's stored locale**; the reconciler then
+  syncs the stale locale, masking a fresh TG `language_code` seed. Clear client prefs too when testing
+  locale.
+- **`DNS=` in `TEST_AWG_CONF` pins the VPN netns to 1.1.1.1** → internal names go NXDOMAIN → the
+  bot-link silently dies. Diagnose from inside the netns.
+- **Swap one contour service to a local image** without deploy secrets via a busybox-in-the-netns
+  socket-inspect trick (single-service recreate).
+- **A rolling deploy did NOT recreate caddy on a config-only change.** Force `--force-recreate` for
+  caddy; don't trust "deploy green" for an edge-config change.
+- **A new gateway edge route MUST be added to the Caddyfile `@gateway` matcher** or it falls through
+  to the landing catch-all. Add a CI probe for the route.
+- **Prod caddy logs warnings only, no access log.** Trace a request via the backend "http request"
+  telemetry log or Tempo, not caddy.
+- **Confirm a release is live without SSH** by grepping the served SPA: `__APP_VERSION__` inside
+  `/assets/main-*.js`.
+- **"App hangs on load" was a dead HTTP/3 advert:** caddy sent `Alt-Svc: h3` with no UDP/443 open;
+  clients cache it ~30 days. Fix with `Alt-Svc: clear`.
+- **Config-poison deploy loop:** a crash-looping config-mounted service + a missing bind source
+  produces a root-owned directory that then fails deploys. Break it by removing the root-owned dir.
+- **Maintenance-window contract** (planned-deploy 503): a marker header, `/_gm` exempt, the flag spans
+  the whole roll, the SPA overlay reloads on recovery. Don't break these invariants.
+- **A new dictionary goes live via a `/_gm/dictionary` upload, NOT a redeploy.** In-flight games keep
+  their pinned version. The **owner** does the upload.
+- **Renderer deploy job flakes** on the skia-canvas GitHub binary download when its lockfile changes —
+  re-run, it's not your code.
+
+## Repo workflow
+
+- **PR-based, zero issues.** Work is tracked via PRs + `PRERELEASE.md`. "заведи задачу" means *do it*
+  / add a plan line — not file a tracker issue.
+- **`tea` CLI for all Gitea ops** (PRs, secrets, variables, dispatch). `gh` does **not** work here. The
+  agent **cannot self-approve** a PR but **can merge** it after the owner approves. Watch the
+  stale-mergeable trap (re-check mergeability right before merging).
+- **Watch every push/merge/deploy to green** with `python3 ~/.claude/bin/gitea-ci-watch.py`, launched
+  **bare** under a background task. It polls run-level conclusions; its `ALL GREEN` already covers the
+  gated deploy job. Pass `--no-runs 600` when the runner is busy. A **merge** is the most-forgotten
+  case — watch the post-merge runs too.
+- **After a merge, switch to the merged-into branch** (`development`/`master`), pull, and prune the
+  local feature branch.
+- **The contour deploy probe checks the backend `/readyz`**; a PR deploy builds the PR's own code; a
+  wedged contour can be recovered by recreating the host container set.
+
+## Domain semantics (not obvious from the code)
+
+- **Account deletion must NOT delete any user messages** — including feedback / support. Interview the
+  owner on every deletion point before wiring it.
+- **`account.time_zone` is `NOT NULL DEFAULT 'UTC'`, seeded from a detected ±HH:MM offset.** An email
+  account row is created at the **code-request** step, not at confirmation.
+- **The robot has two distinct time windows:** a **sleep window** (~00:00–07:00, gates its moves and
+  nudges) vs the **player away window** (turn-timeout only). "окно отсутствия" in dialogue = the
+  **sleep** window.
+
+## Production topology
+
+- **Two prod hosts.** `main` — full stack + ACME/edge (Selectel); `tg` — Telegram bot only (vdsina).
+  SSH aliases `scrabble-main-ops` / `scrabble-tg-ops`. Deploy is **manual dispatch only**, rolling +
+  health-gated + auto-rollback. Hosts are provisioned by `deploy/ansible/` (inventory + vars there —
+  the source of truth for IPs/roles).
+- **The agent has targeted root SSH** to the hosts (and may run the prod Ansible). Surface every
+  owner-side step **before** a deploy, not after.
+
+## Feature-area pointers (state lives in the linked docs/plans, not here)
+
+- **Monetization** — «Фишка» currency, per-platform wallets, ads. Agreements in
+  `docs/PAYMENTS_DECISIONS_ru.md`; a phased plan (E0–E9). go-jet money rule above applies.
+- **PITR** — pgBackRest → Selectel S3 (encrypted, 30-day), currently **gated off**; runbook in
+  `deploy/README.md`. Gotcha: run pgBackRest via docker-exec **as the `postgres` user** with
+  `--pg1-user=scrabble`.
+- **Offline mode** — the robot brain, move generator/validator/scorer and DAWG reader are **JS ports**
+  of the Go engine, bundled client-side and **parity-pinned** by golden tests. Multi-phase; native
+  offline-first bundles the dictionaries.
+- **VK ID web login** — raw OAuth 2.1 against `id.vk.com`, a **separate VK "Web" app** from the Mini
+  App, server-side confidential code exchange.
+- **Email relay** — Selectel SMTP + confirm / link / unlink / deletion codes + alerts.
+- **Native Android** — Capacitor bundle model, client-version gate, offline-first, RuStore; the
+  design lives in `docs/ARCHITECTURE.md` (§2 gate, §3 identity, §13 native build).

.gitea/workflows/android-build.yaml

@@ -0,0 +1,172 @@
+# Manual signed-APK build for the standalone Android app (RuStore). Runs ONLY from master, ONLY on
+# workflow_dispatch with confirm=build — the same deliberate-manual shape as prod-deploy.yaml, never on
+# a PR. It builds the native-flavoured SPA, bundles the offline dictionaries into the APK assets, and
+# assembles a release APK, uploaded as a run artifact (RuStore upload stays manual for the MVP).
+#
+# Signing degrades gracefully: with the ANDROID_KEYSTORE_* secrets present the APK is signed; without
+# them build.gradle produces an UNSIGNED release APK (so a dry run still proves the whole pipeline).
+# The keystore is a publication prerequisite — see deploy/README.md (Android build/release runbook).
+# The toolchain is self-provisioned here (JDK 21 + a cached Android SDK), so the runner host needs
+# nothing pre-installed.
+name: android-build
+run-name: "android build ${{ github.sha }}"
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm:
+        description: 'Type "build" to confirm an APK build from master.'
+        required: true
+        default: ""
+
+permissions:
+  contents: read
+
+env:
+  NO_COLOR: "1"
+  # The dictionary release, one source of truth (same Gitea variable the backend image + CI use). It
+  # both fetches the DAWGs and labels the bundled files (VITE_DICT_VERSION must equal __DICT_VERSION__).
+  DICT_VERSION: ${{ vars.DICT_VERSION }}
+  VITE_DICT_VERSION: ${{ vars.DICT_VERSION }}
+  # Hide in-app purchases in the RuStore MVP (RuStore, not Google Play — VITE_GP_BUILD stays unset).
+  VITE_PAYMENTS_DISABLED: "1"
+  # The update overlay's store target; empty until publication (the button no-ops, and the version gate
+  # is dormant in the MVP so it never fires). Set the ANDROID_RUSTORE_URL variable when the app is live.
+  VITE_RUSTORE_URL: ${{ vars.ANDROID_RUSTORE_URL }}
+  # Host-executor runner: the Android SDK is pre-installed on the host. Override ANDROID_SDK_DIR if it
+  # lives elsewhere (the default matches deploy/README.md's install path).
+  ANDROID_HOME: ${{ vars.ANDROID_SDK_DIR || '/opt/android-sdk' }}
+  ANDROID_SDK_ROOT: ${{ vars.ANDROID_SDK_DIR || '/opt/android-sdk' }}
+
+jobs:
+  build:
+    if: ${{ github.ref == 'refs/heads/master' && inputs.confirm == 'build' }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Host-executor runner: the Android SDK is pre-installed on the host (JDK 21 comes from setup-java
+      # below). Fail fast + legibly if the runner user cannot read/execute it or a needed package is
+      # missing — this doubles as the runner-access check (deploy/README.md).
+      - name: Verify the host Android SDK
+        run: |
+          sm="$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager"
+          if [ ! -x "$sm" ]; then
+            echo "::error::sdkmanager not found/executable at $sm — set the ANDROID_SDK_DIR variable if the SDK lives elsewhere, or grant the runner user read+exec: sudo chmod -R a+rX \"$ANDROID_HOME\""; exit 1
+          fi
+          for pkg in "platforms/android-36" "build-tools"; do
+            if [ ! -d "$ANDROID_HOME/$pkg" ]; then
+              echo "::error::missing $ANDROID_HOME/$pkg — run: \"$sm\" 'platforms;android-36' 'build-tools;36.0.0'"; exit 1
+            fi
+          done
+          echo "Android SDK OK at $ANDROID_HOME"; "$sm" --version
+
+      - name: Compute version + native build env
+        id: prep
+        env:
+          PUBLIC_BASE_URL: ${{ vars.PROD_PUBLIC_BASE_URL }}
+        run: |
+          # A store release must sit on an exact vMAJOR.MINOR.PATCH tag (G tags before dispatch) so the
+          # versionCode is deterministic and strictly increasing across uploads. Refuse anything else
+          # rather than derive a versionCode from a "-N-gSHA" describe.
+          desc="$(git describe --tags --exact-match 2>/dev/null || true)"
+          case "$desc" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *) echo "::error::HEAD is not on a clean vX.Y.Z tag (git describe --exact-match = '${desc:-none}'); tag the release first"; exit 1 ;;
+          esac
+          v="${desc#v}"
+          IFS=. read -r MA MI PA <<< "$v"
+          # 10# forces base-10 so a zero-padded part is never read as octal.
+          code=$(( 10#$MA * 1000000 + 10#$MI * 1000 + 10#$PA ))
+          # The native SPA talks to the production origin (reuse the prod public base URL); strip any
+          # trailing slash so the Connect endpoint never doubles it.
+          gateway="${PUBLIC_BASE_URL%/}"
+          {
+            echo "tag=$desc"
+            echo "name=$v"
+            echo "code=$code"
+            echo "gateway=$gateway"
+          } >> "$GITHUB_OUTPUT"
+          echo "release $desc -> versionName $v versionCode $code, gateway $gateway"
+
+      # Same release + fetch as the Go/UI jobs in ci.yaml — the bundled dicts come from this tarball,
+      # NOT the scrabble-solver sibling (ui is a Node project outside go.work).
+      - name: Fetch dictionary DAWGs
+        run: |
+          mkdir -p "${GITHUB_WORKSPACE}/dawg"
+          curl -fsSL -o /tmp/dawg.tar.gz "https://gitea.iliadenisov.ru/developer/scrabble-dictionary/releases/download/${DICT_VERSION}/scrabble-dawg-${DICT_VERSION}.tar.gz"
+          tar xzf /tmp/dawg.tar.gz -C "${GITHUB_WORKSPACE}/dawg"
+          ls -la "${GITHUB_WORKSPACE}/dawg"
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install pnpm
+        run: npm install -g pnpm@11.0.9
+
+      - name: Install deps
+        working-directory: ui
+        run: pnpm install --frozen-lockfile
+
+      - name: Build the SPA (native flavour)
+        working-directory: ui
+        env:
+          VITE_GATEWAY_URL: ${{ steps.prep.outputs.gateway }}
+          VITE_APP_VERSION: ${{ steps.prep.outputs.tag }}
+        run: pnpm run build
+
+      # Copy the release DAWGs into dist/dict/<variant>@<version>.dawg for the offline-first bundled tier
+      # (after the build, before cap sync copies dist/ into the native assets).
+      - name: Bundle the dictionaries
+        working-directory: ui
+        env:
+          DICT_DIR: ${{ github.workspace }}/dawg
+        run: node scripts/bundle-dicts.mjs
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+
+      # Local cap binary (dodges the corepack pre-flight flake); syncs dist/ (incl. dict/) + native deps.
+      - name: Sync the native project
+        working-directory: ui
+        run: node_modules/.bin/cap sync android
+
+      - name: Decode the release keystore
+        id: keystore
+        env:
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+        run: |
+          if [ -n "$ANDROID_KEYSTORE_BASE64" ]; then
+            printf '%s' "$ANDROID_KEYSTORE_BASE64" | base64 -d > "${GITHUB_WORKSPACE}/release.jks"
+            echo "file=${GITHUB_WORKSPACE}/release.jks" >> "$GITHUB_OUTPUT"
+            echo "keystore decoded -> signed release build"
+          else
+            echo "file=" >> "$GITHUB_OUTPUT"
+            echo "::warning::ANDROID_KEYSTORE_BASE64 is not set — building an UNSIGNED release APK (not installable/publishable)"
+          fi
+
+      - name: Assemble the release APK
+        working-directory: ui/android
+        env:
+          ANDROID_KEYSTORE_FILE: ${{ steps.keystore.outputs.file }}
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        run: ./gradlew assembleRelease -PversionCode=${{ steps.prep.outputs.code }} -PversionName=${{ steps.prep.outputs.name }} --console=plain
+
+      - name: Upload the APK artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: erudit-${{ steps.prep.outputs.name }}-apk
+          path: ui/android/app/build/outputs/apk/release/*.apk
+          if-no-files-found: error

.gitea/workflows/ci.yaml

@@ -353,6 +353,11 @@ jobs:
           # for the server-side confidential code exchange — a SEPARATE VK app from the Mini
           # App above. One VK ID "Web" app serves every contour -> unprefixed secret.
           GATEWAY_VK_ID_CLIENT_SECRET: ${{ secrets.GATEWAY_VK_ID_CLIENT_SECRET }}
+          # Client-version gate (ARCHITECTURE.md §2): one plain (unprefixed) variable serves every
+          # contour. In the test contour the stamped client version is a commit hash (unparseable ⇒
+          # fail-open), so setting these only enforces on real semver prod builds. Empty ⇒ dormant.
+          GATEWAY_MIN_CLIENT_VERSION: ${{ vars.GATEWAY_MIN_CLIENT_VERSION }}
+          GATEWAY_RECOMMENDED_CLIENT_VERSION: ${{ vars.GATEWAY_RECOMMENDED_CLIENT_VERSION }}
           # Planted honeytoken bearer: presenting it flags the caller (logs + a ban metric on
           # test where the IP ban is off; a 24h IP ban on prod). Per-contour secret; empty = trap off.
           GATEWAY_HONEYTOKEN: ${{ secrets.TEST_GATEWAY_HONEYTOKEN }}
@@ -510,19 +515,64 @@ jobs:
       - name: Probe the /offer/ public offer page is served
         run: |
           set -u
-          # /offer/ is a static page baked into the landing image (rendered from
+          # /offer/ is rendered by the render sidecar: it splices the live catalog price list
-          # ui/legal/offer_ru.md). If the landing Caddyfile stops routing it, the request
+          # (fetched from the backend's internal endpoint) into the committed ui/legal/offer_ru.md.
-          # silently falls through to the landing shell (also 200) — so assert offer-specific
+          # If the @offer caddy route is missing, the request falls to the landing shell (also 200),
-          # content, never just the status.
+          # and if the backend fetch fails the sidecar returns 502 — so assert offer-specific content
-          out="$(docker run --rm --network edge alpine:3.20 wget -q -O - http://scrabble/offer/ 2>&1 || true)"
+          # (the seller INN, §11) AND that the pricing marker was substituted (proves the fetch +
-          if echo "$out" | grep -q "290210610742"; then
+          # splice ran), never just the status. Data-independent: an empty catalog still substitutes
-            echo "ok: /offer/ serves the public offer page"
+          # the marker with nothing, so "pricing_template" must be absent either way.
-          else
+          # Full body is needed (the INN is in §11 and the marker check spans the page), so this
-            echo "FAIL: /offer/ did not serve the offer page (fell through to the landing shell?)"
+          # cannot be a head-only probe like the legal one. Retry with a timeout instead: the offer is
+          # now bilingual (RU + EN, larger), and a single-shot fetch can race the renderer's restart in
+          # the same deploy.
+          ok=
+          for i in $(seq 1 20); do
+            out="$(docker run --rm --network edge alpine:3.20 wget -q -T 10 -O - http://scrabble/offer/ 2>&1 || true)"
+            if echo "$out" | grep -q "290210610742" && ! echo "$out" | grep -q "pricing_template"; then
+              echo "ok: /offer/ serves the rendered offer with the price list spliced in"
+              ok=1
+              break
+            fi
+            sleep 3
+          done
+          if [ -z "$ok" ]; then
+            echo "FAIL: /offer/ did not serve the rendered offer (route fell through, or the price splice failed)"
+            docker logs --tail 50 scrabble-renderer || true
+            docker logs --tail 50 scrabble-backend || true
             docker logs --tail 50 scrabble-landing || true
             exit 1
           fi
 
+      - name: Probe the /privacy/ and /eula/ legal pages are served
+        run: |
+          set -u
+          # /privacy/ and /eula/ are static legal markdown rendered by the render sidecar. If the
+          # @legal caddy route is missing they fall to the landing shell (also 200, canonical
+          # erudit-game.ru/), so assert the page-specific canonical URL — it uniquely identifies the
+          # rendered legal doc reaching the edge, not the landing catch-all. Read only the <head>
+          # (head -c 4096; the canonical link sits in the first bytes): the check is then
+          # size-independent, so the large EULA page does not exceed the timeout while the monitoring
+          # stack is still booting post-deploy and starving the CPU-capped renderer. Retry like the
+          # landing/gateway/backend probe to ride out that window.
+          for route in privacy eula; do
+            ok=
+            for i in $(seq 1 20); do
+              head_out="$(docker run --rm --network edge alpine:3.20 sh -c "wget -q -T 10 -O - http://scrabble/${route}/ 2>/dev/null | head -c 4096" || true)"
+              if printf '%s' "$head_out" | grep -qF "erudit-game.ru/${route}/"; then
+                echo "ok: /${route}/ serves the rendered legal page"
+                ok=1
+                break
+              fi
+              sleep 3
+            done
+            if [ -z "$ok" ]; then
+              echo "FAIL: /${route}/ did not serve the rendered legal page (@legal route missing?)"
+              docker logs --tail 50 scrabble-renderer || true
+              exit 1
+            fi
+          done
+
       - name: Probe the /pay/ callback route reaches the gateway
         run: |
           set -u

.gitea/workflows/prod-deploy.yaml

@@ -112,9 +112,20 @@ jobs:
       # derived from PUBLIC_BASE_URL in deploy/write-prod-env.sh.
       VITE_VK_APP_ID: ${{ vars.VITE_VK_APP_ID }}
       GATEWAY_VK_ID_CLIENT_SECRET: ${{ secrets.GATEWAY_VK_ID_CLIENT_SECRET }}
+      # Client-version gate (ARCHITECTURE.md §2): plain (unprefixed) vars, shared across contours
+      # (empty ⇒ dormant). On prod the stamped client version is a real semver, so the gate enforces
+      # here — set GATEWAY_MIN_CLIENT_VERSION to the release in the same rollout that ships a breaking
+      # wire change; bump GATEWAY_RECOMMENDED_CLIENT_VERSION (≥ min) to nudge upgrades softly.
+      GATEWAY_MIN_CLIENT_VERSION: ${{ vars.GATEWAY_MIN_CLIENT_VERSION }}
+      GATEWAY_RECOMMENDED_CLIENT_VERSION: ${{ vars.GATEWAY_RECOMMENDED_CLIENT_VERSION }}
       # Planted honeytoken bearer: presenting it earns a 24h IP ban + a high-severity alarm.
       # Per-contour secret; empty = trap off. Rendered by deploy/write-prod-env.sh.
       GATEWAY_HONEYTOKEN: ${{ secrets.PROD_GATEWAY_HONEYTOKEN }}
+      # Community IP blocklist (Spamhaus DROP): opt-in. Set _ENABLED=true + _URL (the feed) once
+      # verified; _ALLOW is a comma-separated never-block set (own infra). Empty ⇒ off.
+      GATEWAY_BLOCKLIST_ENABLED: ${{ vars.PROD_GATEWAY_BLOCKLIST_ENABLED }}
+      GATEWAY_BLOCKLIST_URL: ${{ vars.PROD_GATEWAY_BLOCKLIST_URL }}
+      GATEWAY_BLOCKLIST_ALLOW: ${{ vars.PROD_GATEWAY_BLOCKLIST_ALLOW }}
       # Signs the finished-game export download URLs (backend BACKEND_EXPORT_SIGN_KEY).
       EXPORT_SIGN_KEY: ${{ secrets.PROD_EXPORT_SIGN_KEY }}
       # Transactional email via the shared Selectel relay (confirm-codes): one account for

.gitea/workflows/prod-rollback.yaml

@@ -70,6 +70,10 @@ jobs:
       VITE_VK_APP_ID: ${{ vars.VITE_VK_APP_ID }}
       GATEWAY_VK_ID_CLIENT_SECRET: ${{ secrets.GATEWAY_VK_ID_CLIENT_SECRET }}
       GATEWAY_HONEYTOKEN: ${{ secrets.PROD_GATEWAY_HONEYTOKEN }}
+      # Community IP blocklist — rendered on rollback too so a rollback keeps the same edge policy.
+      GATEWAY_BLOCKLIST_ENABLED: ${{ vars.PROD_GATEWAY_BLOCKLIST_ENABLED }}
+      GATEWAY_BLOCKLIST_URL: ${{ vars.PROD_GATEWAY_BLOCKLIST_URL }}
+      GATEWAY_BLOCKLIST_ALLOW: ${{ vars.PROD_GATEWAY_BLOCKLIST_ALLOW }}
       EXPORT_SIGN_KEY: ${{ secrets.PROD_EXPORT_SIGN_KEY }}
       SMTP_RELAY_USER: ${{ secrets.SMTP_RELAY_USER }}
       SMTP_RELAY_PASS: ${{ secrets.SMTP_RELAY_PASS }}

CLAUDE.md

@@ -156,3 +156,11 @@ The `ui` module is a Node project (pnpm), **not** in `go.work`; it is the `ui` j
 the single `.gitea/workflows/ci.yaml`. Committed edge codegen under `ui/src/gen/`
 (regenerate with `pnpm codegen`); pnpm build-script approval lives in
 `ui/pnpm-workspace.yaml` (`allowBuilds: esbuild: true`).
+
+## Agent field notes
+
+Non-obvious, hard-won knowledge the agent has accumulated that is **not** captured in the docs above,
+kept in the repo so it travels with a clone. Verify any named file/flag against current code before
+acting on it.
+
+@.claude/CLAUDE.md

assets/icons/README.md

@@ -1,41 +1,18 @@
-# Erudit — site icons + Open Graph card
+# Icons
 
-The favicon set and the `og:image` link-preview card for the public landing
+The whole shipped icon set is sliced from **one master** — see
-(`ui/landing.html`) and the SPA shell (`ui/index.html`). Same design language as the
+[`brand/`](brand/) for the reference generator, the pinned font and the committed
-[VK loading-screen logo](../vk/README.md): the wooden Erudit «Э» tile (score `8`),
+outputs, and [`../../docs/ICON_BRANDBOOK.md`](../../docs/ICON_BRANDBOOK.md) for how the
-with the wordmark on the app's dark board green (`ui/src/app.css` tokens).
+mark is constructed. The per-platform target map (which file goes where) is in
-
+[`../../docs/ICONS.md`](../../docs/ICONS.md).
-| Output (committed to `ui/public/`) | Purpose |
-|------|---------|
-| `favicon.svg` | Vector favicon, transparent; tile + «Э» only (the score is illegible below ~32 px). |
-| `favicon.ico` | 32×32 PNG-in-ICO fallback (also answers the browsers' blind `/favicon.ico` probe). |
-| `apple-touch-icon.png` | 180×180 opaque full-bleed tile; iOS masks its own corners. |
-| `og-image.png` | 1200×630 card: tile + «Эрудит / Скрэббл — игра в слова». Referenced absolutely as `https://erudit-game.ru/og-image.png`. |
-
-## How it works
-
-`build/extract.js` extracts the needed glyph outlines (tile glyphs + every wordmark
-character) from LiberationSans (Arial-metric, the game's font stack) with their
-advance widths into `build/glyphs.json` (committed). `build/generate.js` composes
-plain SVG from those outlines — no font is needed at generation time — writes
-`favicon.svg` and rasterises the PNG/ICO outputs by screenshotting the SVGs with the
-`ui` package's Playwright chromium (`@playwright/test`); the `.ico` container is
-assembled in-script (a single PNG entry). Raster bytes therefore depend on the
-installed chromium version; the SVG sources are deterministic.
-
-## Regenerate
-
-Requirements: Node ≥ 18, `ui` installed (`pnpm install`, provides Playwright).
-`extract.js` additionally needs `opentype.js` (`npm i opentype.js`); **`generate.js`
-needs no extra packages**.
 
 ```sh
-cd assets/icons
+cd brand
-
+npm i opentype.js
-# 1. (optional) re-extract the glyphs — only if the font or the wordmark changes:
+node build-set.mjs          # web (ui/public) + Capacitor layers (ui/assets) + vk/ tg/ store/
-#    default font: /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf
+node build-android-res.mjs  # Android launcher resources (all densities + monochrome)
-node build/extract.js [/path/to/font.ttf]      # -> build/glyphs.json
-
-# 2. regenerate everything in ui/public/:
-node build/generate.js
 ```
+
+> The earlier `build/` pipeline (LiberationSans glyph outlines → favicon/apple-touch/OG)
+> was replaced by `brand/` when the icon was rebranded onto the Spectral «Э» master.
+> The separate VK loading-screen animation lives in [`../vk/`](../vk/) and is unrelated.

assets/icons/brand/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+package-lock.json

assets/icons/brand/README.md

@@ -0,0 +1,32 @@
+# Erudit icon — brand master
+
+The reference construction of the Erudit app icon. The authoritative, human-readable
+spec lives in [`docs/ICON_BRANDBOOK.md`](../../../docs/ICON_BRANDBOOK.md); this folder
+holds the machine reproduction of exactly what that document describes.
+
+| File | What |
+|------|------|
+| `build-icon.mjs` | reference generator — every dimension is a fraction of the side, matching the brand book |
+| `render-png.mjs` | rasterises an icon SVG to PNG via the `ui` package's Playwright chromium |
+| `Spectral-Bold.ttf` | the «Э» typeface (SIL OFL, `Spectral-OFL.txt`) — pinned so the letter never drifts |
+| `icon-light.svg` / `.png` | the light master (1024) |
+| `icon-dark.svg` / `.png` | the dark master (1024) |
+| `icon-construction.svg` / `.png` | the percent-annotated construction scheme (figure in the brand book) |
+
+## Regenerate
+
+```sh
+cd assets/icons/brand
+npm i opentype.js                       # the only extra dep; render uses ui's chromium
+
+node build-icon.mjs --variant light  > icon-light.svg
+node build-icon.mjs --variant dark   > icon-dark.svg
+node build-icon.mjs --variant light --scheme > icon-construction.svg
+
+node render-png.mjs icon-light.svg  icon-light.png  1024
+node render-png.mjs icon-dark.svg   icon-dark.png   1024
+node render-png.mjs icon-construction.svg icon-construction.png 2048
+```
+
+The SVGs are resolution-free; render at any size. Downstream slicing (favicon / PWA /
+iOS / Android) is a separate step — see [`docs/ICONS.md`](../../../docs/ICONS.md).

assets/icons/brand/Spectral-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2017 The Spectral Project Authors (https://github.com/productiontype/Spectral)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

assets/icons/brand/build-android-res.mjs

@@ -0,0 +1,47 @@
+'use strict';
+// Generate the Android launcher resources from the committed layers, at every
+// density, with NO inset (our layers already fill the 108 dp canvas) and a
+// monochrome (themed) layer. Run build-set.mjs first (it writes the layer PNGs).
+//
+//   npm i opentype.js  # (only build-icon/build-set need it; this reads PNGs)
+//   node build-set.mjs && node build-android-res.mjs
+//
+// Writes ui/android/app/src/main/res/mipmap-*/ic_launcher{,_round,_foreground,
+// _background,_monochrome}.png. The two mipmap-anydpi-v26/*.xml are committed by hand.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(DIR, '..', '..', '..');
+const RES = join(ROOT, 'ui', 'android', 'app', 'src', 'main', 'res');
+const uri = p => 'data:image/png;base64,' + readFileSync(p).toString('base64');
+const BG = uri(join(ROOT, 'ui', 'assets', 'icon-background.png'));
+const FG = uri(join(ROOT, 'ui', 'assets', 'icon-foreground.png'));
+const MONO = uri(join(DIR, 'android-monochrome.png'));
+
+// density: [adaptive-layer px (108 dp), legacy launcher px (48 dp)]
+const D = { ldpi: [81, 36], mdpi: [108, 48], hdpi: [162, 72], xhdpi: [216, 96], xxhdpi: [324, 144], xxxhdpi: [432, 192] };
+
+const pw = await import(join(ROOT, 'ui', 'node_modules', '@playwright', 'test', 'index.js'));
+const { chromium } = pw.default ?? pw;
+const browser = await chromium.launch();
+const page = await browser.newPage({ deviceScaleFactor: 1 });
+const im = (u, s) => `<img src="${u}" width="${s}" height="${s}" style="display:block">`;
+async function shot(html, s, transparent) {
+  await page.setViewportSize({ width: s, height: s });
+  await page.setContent(`<!doctype html><meta charset=utf8><style>*{margin:0;padding:0}#r{width:${s}px;height:${s}px}</style><div id=r>${html}</div>`, { waitUntil: 'networkidle' });
+  return page.locator('#r').screenshot({ omitBackground: !!transparent });
+}
+for (const [d, [fg, lg]] of Object.entries(D)) {
+  const dir = join(RES, `mipmap-${d}`);
+  writeFileSync(join(dir, 'ic_launcher_background.png'), await shot(im(BG, fg), fg, false));
+  writeFileSync(join(dir, 'ic_launcher_foreground.png'), await shot(im(FG, fg), fg, true));
+  writeFileSync(join(dir, 'ic_launcher_monochrome.png'), await shot(im(MONO, fg), fg, true));
+  const comp = `<div style="position:relative;width:${lg}px;height:${lg}px">${im(BG, lg)}<div style="position:absolute;inset:0">${im(FG, lg)}</div></div>`;
+  writeFileSync(join(dir, 'ic_launcher.png'), await shot(comp, lg, false));
+  const round = `<div style="width:${lg}px;height:${lg}px;border-radius:50%;overflow:hidden;position:relative">${im(BG, lg)}<div style="position:absolute;inset:0">${im(FG, lg)}</div></div>`;
+  writeFileSync(join(dir, 'ic_launcher_round.png'), await shot(round, lg, true));
+  console.log('mipmap-' + d, 'ok');
+}
+await browser.close();

assets/icons/brand/build-icon.mjs

@@ -0,0 +1,159 @@
+'use strict';
+// Erudit app-icon — the reference generator. Every dimension below is a FRACTION
+// of the icon side, so this file reads the same as docs/ICON_BRANDBOOK.md and the
+// icon reproduces at any resolution. Emits one variant/layer's SVG to stdout.
+//
+//   node build-icon.mjs --variant light|dark [--layer full|background|foreground] [--scheme] > icon.svg
+//
+// Layers (for Android adaptive icons):
+//   full        the standalone master (rounded tile + mark) — iOS / PWA / favicon
+//   background  wood + grain + light/shadow, full-bleed square (the OS applies the mask)
+//   foreground  only «Э» + ✻, transparent, re-placed for the round mask (see FG_* below)
+//
+// Deps: opentype.js (npm i opentype.js). Font: ./Spectral-Bold.ttf (OFL, bundled).
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import opentype from 'opentype.js';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const has = f => args.includes('--' + f);
+const val = (f, d) => { const i = args.indexOf('--' + f); return i >= 0 ? args[i + 1] : d; };
+
+// ---- the design, in fractions of the side ----
+const S = 1024;                       // reference side (the icon is resolution-free)
+const RADIUS   = 0.17;                // tile corner radius (full master)
+const STAR_BULB = 0.22;               // spoke-end (and hub) radius, as fraction of star radius
+const STAR_SPOKES = 6;
+const GRAIN_COLS = 6, GRAIN_W = 1 / 32, GRAIN_SHIFT = 1 / 16, GRAIN_TILT = 4;
+const SHEEN = 0.15;                   // white, transparent bottom-left -> this alpha top-right
+const SHADE = 0.15;                   // black, this alpha bottom-left -> transparent top-right
+
+// The mark, placed for the standalone master (bottom-right biased, full-bleed):
+const MASTER = { lh: 0.6055, lc: [0.4814, 0.4922], sd: 0.1729, sc: [0.7881, 0.7881] };
+// The mark, placed for the Android foreground layer (centred-ish inside the 61% safe
+// zone, nudged right 8% / down 3% for optical balance under the round mask; smaller ✻):
+const FOREGROUND = { lh: 0.5391, lc: [0.5234, 0.4951], sd: 0.1318, sc: [0.7627, 0.7266] };
+
+const PALETTE = {
+  light: { wood: '#e6b053', ink: '#5a3a12', grain: '#d8a54e' },
+  dark:  { wood: '#4a3316', ink: '#f2d9a0', grain: '#432e14' },
+};
+
+// Layers:
+//   full        rounded tile + master mark        (favicon.svg — browser rounds nothing)
+//   flat        square tile + master mark          (apple-touch, PWA "any" — OS rounds)
+//   background  square tile, no mark               (Android adaptive background)
+//   foreground  mark only, transparent             (Android adaptive foreground)
+//   maskable    square tile + foreground mark       (PWA maskable — safe-zone aware)
+//   monochrome  foreground mark only, flat colour  (Android 13+ themed layer)
+const LAYERS = ['full', 'flat', 'background', 'foreground', 'maskable', 'monochrome'];
+const variant = val('variant', 'light');
+const layer = val('layer', 'full');
+const P = PALETTE[variant];
+if (!P) { console.error(`unknown --variant ${variant} (light|dark)`); process.exit(1); }
+if (!LAYERS.includes(layer)) { console.error(`unknown --layer ${layer} (${LAYERS.join('|')})`); process.exit(1); }
+
+const usesForegroundPlacement = ['foreground', 'maskable', 'monochrome'].includes(layer);
+const drawBg = ['full', 'flat', 'background', 'maskable'].includes(layer);
+const drawMark = layer !== 'background';
+const MARK = usesForegroundPlacement ? FOREGROUND : MASTER;
+const inkColour = layer === 'monochrome' ? val('mono', '#ffffff') : P.ink;
+const RX = layer === 'full' ? RADIUS * S : 0;   // only the standalone master keeps rounded corners
+const font = opentype.parse(readFileSync(join(DIR, 'Spectral-Bold.ttf')).buffer);
+
+// «Э» outline scaled so its ink bounding box is MARK.lh of the side, box centred on MARK.lc.
+function letterSvg() {
+  const g = font.charToGlyph('Э');
+  const h0 = (() => { const b = g.getPath(0, 0, 1000).getBoundingBox(); return b.y2 - b.y1; })();
+  const scale = (MARK.lh * S) / h0;
+  const p = g.getPath(0, 0, 1000 * scale);
+  const bb = p.getBoundingBox();
+  const w = bb.x2 - bb.x1, h = bb.y2 - bb.y1;
+  const tx = MARK.lc[0] * S - (bb.x1 + w / 2);
+  const ty = MARK.lc[1] * S - (bb.y1 + h / 2);
+  return { svg: `<path transform="translate(${tx.toFixed(2)} ${ty.toFixed(2)})" d="${p.toPathData(2)}" fill="${inkColour}"/>`,
+           box: { x: bb.x1 + tx, y: bb.y1 + ty, w, h } };
+}
+
+// Teardrop-spoked asterisk ✻: each spoke tapers to a point at the centre and ends
+// in a round bulb; a central disc equal to the bulb fuses them.
+function starPath() {
+  const cx = MARK.sc[0] * S, cy = MARK.sc[1] * S, Rout = MARK.sd * S / 2;
+  const rb = Rout * STAR_BULB, R = Rout - rb;
+  const L = Math.sqrt(R * R - rb * rb), theta = Math.asin(rb / R);
+  const rot = (v, t) => [v[0] * Math.cos(t) - v[1] * Math.sin(t), v[0] * Math.sin(t) + v[1] * Math.cos(t)];
+  let d = '';
+  for (let k = 0; k < STAR_SPOKES; k++) {
+    const a = -Math.PI / 2 + k * 2 * Math.PI / STAR_SPOKES;
+    const u = [Math.cos(a), Math.sin(a)];
+    const d1 = rot(u, theta), d2 = rot(u, -theta);
+    const T1 = [cx + L * d1[0], cy + L * d1[1]], T2 = [cx + L * d2[0], cy + L * d2[1]];
+    d += `M${cx.toFixed(2)} ${cy.toFixed(2)} L${T1[0].toFixed(2)} ${T1[1].toFixed(2)} A${rb.toFixed(2)} ${rb.toFixed(2)} 0 1 0 ${T2[0].toFixed(2)} ${T2[1].toFixed(2)} Z `;
+  }
+  d += `M${cx} ${cy} m${-rb} 0 a${rb} ${rb} 0 1 0 ${2 * rb} 0 a${rb} ${rb} 0 1 0 ${-2 * rb} 0 Z`;
+  return `<path d="${d}" fill="${inkColour}"/>`;
+}
+
+function grain() {
+  const colW = S / GRAIN_COLS, sw = GRAIN_W * S, shift = GRAIN_SHIFT * S;
+  const yTop = -0.2 * S, yBot = 1.2 * S, cy = S / 2;
+  let s = '';
+  for (let i = 1; i <= GRAIN_COLS; i++) {
+    const xr = i * colW - shift, x = xr - sw, cx = xr - sw / 2;
+    s += `<rect x="${x.toFixed(2)}" y="${yTop.toFixed(2)}" width="${sw.toFixed(2)}" height="${(yBot - yTop).toFixed(2)}" fill="${P.grain}" transform="rotate(${GRAIN_TILT} ${cx.toFixed(2)} ${cy.toFixed(2)})"/>`;
+  }
+  return `<g clip-path="url(#tile)">${s}</g>`;
+}
+
+let body = '';
+const L = letterSvg();
+if (drawBg) {                           // tile + grain + light/shadow (the background)
+  body += `<rect width="${S}" height="${S}" rx="${RX}" fill="${P.wood}"/>`
+    + `<defs><clipPath id="tile"><rect width="${S}" height="${S}" rx="${RX}"/></clipPath>`
+    +   `<linearGradient id="sheen" gradientUnits="userSpaceOnUse" x1="0" y1="${S}" x2="${S}" y2="0"><stop offset="0" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#fff" stop-opacity="${SHEEN}"/></linearGradient>`
+    +   `<linearGradient id="shade" gradientUnits="userSpaceOnUse" x1="0" y1="${S}" x2="${S}" y2="0"><stop offset="0" stop-color="#000" stop-opacity="${SHADE}"/><stop offset="1" stop-color="#000" stop-opacity="0"/></linearGradient>`
+    + `</defs>`
+    + grain()
+    + `<rect width="${S}" height="${S}" fill="url(#sheen)" clip-path="url(#tile)"/>`
+    + `<rect width="${S}" height="${S}" fill="url(#shade)" clip-path="url(#tile)"/>`;
+}
+if (drawMark) body += L.svg + starPath();   // the mark
+if (has('scheme')) body += scheme(L);
+
+process.stdout.write(`<svg xmlns="http://www.w3.org/2000/svg" width="${S}" height="${S}" viewBox="0 0 ${S} ${S}">${body}</svg>\n`);
+
+// Percent-based construction overlay for the brand book (full master only).
+function scheme(L) {
+  const pc = n => (100 * n / S).toFixed(1) + '%';
+  const GC = '#0f172a', BX = '#d81b60', AC = '#0d9488';
+  const halo = 'paint-order="stroke" stroke="#fff" stroke-width="4"';
+  const cx = MARK.sc[0] * S, cy = MARK.sc[1] * S, sd = MARK.sd * S;
+  let g = `<g font-family="'Helvetica Neue',Arial,sans-serif">`;
+  for (let f = 1; f <= 3; f++) {
+    const p = f * S / 4;
+    g += `<line x1="${p}" y1="0" x2="${p}" y2="${S}" stroke="${GC}" stroke-opacity="0.18" stroke-width="1.2"/>`;
+    g += `<line x1="0" y1="${p}" x2="${S}" y2="${p}" stroke="${GC}" stroke-opacity="0.18" stroke-width="1.2"/>`;
+    g += `<text x="${p + 4}" y="20" font-size="17" font-weight="700" fill="${GC}" ${halo}>${f * 25}%</text>`;
+    g += `<text x="4" y="${p - 4}" font-size="17" font-weight="700" fill="${GC}" ${halo}>${f * 25}%</text>`;
+  }
+  g += `<line x1="${0.14 * S}" y1="${0.86 * S}" x2="${0.86 * S}" y2="${0.14 * S}" stroke="${AC}" stroke-width="3" stroke-dasharray="3 8" stroke-linecap="round"/>`;
+  g += `<circle cx="${0.86 * S}" cy="${0.14 * S}" r="6" fill="${AC}"/><circle cx="${0.14 * S}" cy="${0.86 * S}" r="6" fill="${AC}"/>`;
+  g += `<text x="${0.86 * S - 6}" y="${0.14 * S - 12}" text-anchor="end" font-size="18" font-weight="700" fill="${AC}" ${halo}>light: white 0%→15%</text>`;
+  g += `<text x="${0.14 * S + 10}" y="${0.86 * S + 26}" font-size="18" font-weight="700" fill="${AC}" ${halo}>shadow: black 15%→0%</text>`;
+  const { x, y, w, h } = L.box;
+  g += `<rect x="${x.toFixed(1)}" y="${y.toFixed(1)}" width="${w.toFixed(1)}" height="${h.toFixed(1)}" fill="none" stroke="${BX}" stroke-width="2.5"/>`;
+  g += `<line x1="${MARK.lc[0] * S}" y1="${MARK.lc[1] * S - 16}" x2="${MARK.lc[0] * S}" y2="${MARK.lc[1] * S + 16}" stroke="${BX}" stroke-width="2.5"/><line x1="${MARK.lc[0] * S - 16}" y1="${MARK.lc[1] * S}" x2="${MARK.lc[0] * S + 16}" y2="${MARK.lc[1] * S}" stroke="${BX}" stroke-width="2.5"/>`;
+  g += `<text x="${x.toFixed(1)}" y="${(y - 10).toFixed(1)}" font-size="19" font-weight="700" fill="${BX}" ${halo}>«Э» Spectral Bold · box H ${pc(h)} · W ${pc(w)}</text>`;
+  g += `<text x="${x.toFixed(1)}" y="${(y + h + 24).toFixed(1)}" font-size="18" font-weight="700" fill="${BX}" ${halo}>box center ${pc(MARK.lc[0] * S)} / ${pc(MARK.lc[1] * S)}</text>`;
+  g += `<rect x="${cx - sd / 2}" y="${cy - sd / 2}" width="${sd}" height="${sd}" fill="none" stroke="${BX}" stroke-width="2.5"/>`;
+  g += `<line x1="${cx}" y1="${cy - 14}" x2="${cx}" y2="${cy + 14}" stroke="${BX}" stroke-width="2.5"/><line x1="${cx - 14}" y1="${cy}" x2="${cx + 14}" y2="${cy}" stroke="${BX}" stroke-width="2.5"/>`;
+  g += `<text x="${(cx + sd / 2).toFixed(1)}" y="${(cy - sd / 2 - 10).toFixed(1)}" text-anchor="end" font-size="18" font-weight="700" fill="${BX}" ${halo}>✻ Ø ${pc(sd)} · center ${pc(cx)} / ${pc(cy)}</text>`;
+  g += `<text x="${RX + 14}" y="${RX - 6}" font-size="17" font-weight="700" fill="${GC}" ${halo}>corner r = 17%</text>`;
+  g += `<path d="M4 ${RX} A ${RX} ${RX} 0 0 1 ${RX} 4" fill="none" stroke="${GC}" stroke-width="2" stroke-dasharray="5 5"/>`;
+  g += `<rect x="${0.03 * S}" y="${S - 96}" width="${0.94 * S}" height="74" rx="12" fill="#0f172a" fill-opacity="0.82"/>`;
+  g += `<text x="${0.055 * S}" y="${S - 64}" font-size="18" font-weight="600" fill="#fff">Wood grain: 6 equal columns; a vertical stripe on each column's right edge,</text>`;
+  g += `<text x="${0.055 * S}" y="${S - 40}" font-size="18" font-weight="600" fill="#fff">width 1/32 of side; the whole set shifted left 1/16; every stripe tilted 4°.</text>`;
+  return g + `</g>`;
+}

assets/icons/brand/build-set.mjs

@@ -0,0 +1,105 @@
+'use strict';
+// Slice the whole shipped icon set from the brand master (build-icon.mjs). Renders
+// with the ui package's Playwright chromium. See docs/ICONS.md for the target map.
+//
+//   npm i opentype.js && node build-set.mjs
+//
+// Writes: ui/public/* (web), ui/assets/* (Capacitor layers), ./vk/* and ./store/*
+// (manual-upload art). Wiring (manifest, html, Android res) is done separately.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const UI = join(DIR, '..', '..', '..', 'ui');
+const PUB = join(UI, 'public'), ASSETS = join(UI, 'assets');
+const VK = join(DIR, 'vk'), STORE = join(DIR, 'store'), TG = join(DIR, 'tg');
+[VK, STORE, TG].forEach(d => mkdirSync(d, { recursive: true }));
+
+// one SVG string for a variant+layer from the reference generator
+const svgFor = (variant, layer) =>
+  execFileSync('node', [join(DIR, 'build-icon.mjs'), '--variant', variant, '--layer', layer], { encoding: 'utf8' });
+
+const pw = await import(join(UI, 'node_modules', '@playwright', 'test', 'index.js'));
+const { chromium } = pw.default ?? pw;
+const browser = await chromium.launch();
+const page = await browser.newPage();
+
+async function pngFromSvg(svg, size, transparent) {
+  await page.setViewportSize({ width: size, height: size });
+  await page.setContent(`<!doctype html><meta charset=utf8><style>*{margin:0;padding:0}svg{display:block;width:${size}px;height:${size}px}</style>${svg}`, { waitUntil: 'networkidle' });
+  return page.locator('svg').screenshot({ omitBackground: !!transparent });
+}
+async function shootHtml(html, w, h) {
+  await page.setViewportSize({ width: w, height: h });
+  await page.setContent(html, { waitUntil: 'networkidle' });
+  return page.screenshot();
+}
+function icoFromPNG(png, sizePx) {
+  const h = Buffer.alloc(22);
+  h.writeUInt16LE(0, 0); h.writeUInt16LE(1, 2); h.writeUInt16LE(1, 4);
+  h.writeUInt8(sizePx, 6); h.writeUInt8(sizePx, 7);
+  h.writeUInt16LE(1, 10); h.writeUInt16LE(32, 12);
+  h.writeUInt32LE(png.length, 14); h.writeUInt32LE(22, 18);
+  return Buffer.concat([h, png]);
+}
+const write = (p, buf) => { writeFileSync(p, buf); console.log('wrote', p.replace(join(DIR, '..', '..', '..'), '.'), buf.length, 'b'); };
+
+// ---- pre-render the SVG sources we need ----
+const S = {
+  fullLight: svgFor('light', 'full'), fullDark: svgFor('dark', 'full'),
+  flatLight: svgFor('light', 'flat'), flatDark: svgFor('dark', 'flat'),
+  maskLight: svgFor('light', 'maskable'), maskDark: svgFor('dark', 'maskable'),
+  bgLight: svgFor('light', 'background'), fgLight: svgFor('light', 'foreground'),
+  monoLight: svgFor('light', 'monochrome'),
+};
+
+// ---- favicon.svg: light + dark in one file, toggled by prefers-color-scheme ----
+const inner = svg => svg.replace(/^<svg[^>]*>/, '').replace(/<\/svg>\s*$/, '');
+const faviconSvg =
+  `<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024">`
+  + `<style>.d{display:none}@media(prefers-color-scheme:dark){.l{display:none}.d{display:inline}}</style>`
+  + `<g class="l">${inner(S.fullLight)}</g><g class="d">${inner(S.fullDark)}</g></svg>\n`;
+write(join(PUB, 'favicon.svg'), Buffer.from(faviconSvg));
+
+// ---- web rasters ----
+write(join(PUB, 'favicon.ico'), icoFromPNG(await pngFromSvg(S.flatLight, 32, false), 32));
+write(join(PUB, 'apple-touch-icon.png'), await pngFromSvg(S.flatLight, 180, false));
+write(join(PUB, 'icon-192.png'), await pngFromSvg(S.flatLight, 192, false));
+write(join(PUB, 'icon-512.png'), await pngFromSvg(S.flatLight, 512, false));
+write(join(PUB, 'icon-192-dark.png'), await pngFromSvg(S.flatDark, 192, false));
+write(join(PUB, 'icon-512-dark.png'), await pngFromSvg(S.flatDark, 512, false));
+write(join(PUB, 'icon-maskable-512.png'), await pngFromSvg(S.maskLight, 512, false));
+write(join(PUB, 'icon-maskable-512-dark.png'), await pngFromSvg(S.maskDark, 512, false));
+
+// ---- Capacitor layers (ui/assets) ----
+write(join(ASSETS, 'icon.png'), await pngFromSvg(S.flatLight, 1024, false));          // legacy single
+write(join(ASSETS, 'icon-foreground.png'), await pngFromSvg(S.fgLight, 1024, true));   // adaptive fg
+write(join(ASSETS, 'icon-background.png'), await pngFromSvg(S.bgLight, 1024, false));  // adaptive bg
+write(join(DIR, 'android-monochrome.png'), await pngFromSvg(S.monoLight, 1024, true)); // themed layer (wired manually)
+
+// ---- VK (no rounding — flat light) ----
+for (const px of [576, 278, 150, 32]) write(join(VK, `vk-${px}.png`), await pngFromSvg(S.flatLight, px, false));
+
+// ---- Telegram bot: square, no rounding (TG crops the avatar to a circle) ----
+write(join(TG, 'tg-512.png'), await pngFromSvg(S.flatLight, 512, false));   // bot avatar + Mini App icon
+
+// ---- store art ----
+write(join(STORE, 'rustore-512.png'), await pngFromSvg(S.flatLight, 512, false));
+
+// ---- wordmark banner (board-green bg + master tile + «Эрудит» / Игра в слова) ----
+const b64 = readFileSync(join(DIR, 'Spectral-Bold.ttf')).toString('base64');
+const banner = (w, h, tile, t1, t2, gap, pad) => `<!doctype html><meta charset=utf8><style>
+@font-face{font-family:Spectral;src:url(data:font/ttf;base64,${b64});font-weight:700}
+*{margin:0;padding:0;box-sizing:border-box}
+body{width:${w}px;height:${h}px;background:#2a3330;display:flex;align-items:center;gap:${gap}px;padding:0 ${pad}px;font-family:Spectral}
+.tile{width:${tile}px;height:${tile}px;flex:none}.tile svg{width:${tile}px;height:${tile}px;display:block}
+.wm{color:#e7ece8;text-align:center}.t1{font-weight:700;font-size:${t1}px;line-height:1.02;letter-spacing:-2px}
+.t2{font-weight:700;font-size:${t2}px;line-height:1.1;color:#cdd6cf;margin-top:6px}
+</style><div class=tile>${S.fullLight}</div><div class=wm><div class=t1>«Эрудит»</div><div class=t2>Игра в слова</div></div>`;
+write(join(PUB, 'og-image.png'), await shootHtml(banner(1200, 630, 300, 150, 74, 64, 96), 1200, 630));
+write(join(TG, 'tg-demo-640x360.png'), await shootHtml(banner(640, 360, 150, 72, 38, 30, 44), 640, 360));
+
+await browser.close();
+console.log('done');

assets/icons/brand/icon-dark-android-background.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><rect width="1024" height="1024" rx="0" fill="#4a3316"/><defs><clipPath id="tile"><rect width="1024" height="1024" rx="0"/></clipPath><linearGradient id="sheen" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#fff" stop-opacity="0.15"/></linearGradient><linearGradient id="shade" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#000" stop-opacity="0.15"/><stop offset="1" stop-color="#000" stop-opacity="0"/></linearGradient></defs><g clip-path="url(#tile)"><rect x="74.67" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 90.67 512.00)"/><rect x="245.33" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 261.33 512.00)"/><rect x="416.00" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 432.00 512.00)"/><rect x="586.67" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 602.67 512.00)"/><rect x="757.33" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 773.33 512.00)"/><rect x="928.00" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 944.00 512.00)"/></g><rect width="1024" height="1024" fill="url(#sheen)" clip-path="url(#tile)"/><rect width="1024" height="1024" fill="url(#shade)" clip-path="url(#tile)"/></svg>

assets/icons/brand/icon-dark-android-foreground.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><path transform="translate(237.62 774.88)" d="M250.04-34.91Q326.35-34.91 368.57-91.33Q410.78-147.75 410.78-243.55Q410.78-249.23 410.78-254.91L254.10-254.91L208.64-185.91L195.65-185.91L195.65-368.57L208.64-368.57L254.10-299.56L407.53-299.56Q396.98-392.92 351.52-447.72Q306.06-502.52 241.11-502.52Q217.57-502.52 198.90-498.46Q180.22-494.40 162.36-482.22L83.62-354.77L69-354.77L77.93-505.76Q112.84-522.81 154.25-533.37Q195.65-543.92 259.78-543.92Q319.86-543.92 371.41-523.22Q422.96-502.52 460.71-465.58Q498.46-428.64 519.57-378.31Q540.67-327.98 540.67-267.90Q540.67-188.34 504.55-125.83Q468.42-63.32 405.10-27.60Q341.78 8.12 259.78 8.12Q200.52 8.12 150.59-3.25Q100.67-14.61 67.38-34.10L56.02-171.29L69.82-171.29L142.88-63.32Q165.61-50.33 191.59-42.62Q217.57-34.91 250.04-34.91" fill="#f2d9a0"/><path d="M781.00 744.04 L795.25 695.59 A14.85 14.85 0 1 0 766.76 695.59 Z M781.00 744.04 L830.08 732.15 A14.85 14.85 0 1 0 815.84 707.48 Z M781.00 744.04 L815.84 780.60 A14.85 14.85 0 1 0 830.08 755.93 Z M781.00 744.04 L766.76 792.49 A14.85 14.85 0 1 0 795.25 792.49 Z M781.00 744.04 L731.93 755.93 A14.85 14.85 0 1 0 746.17 780.60 Z M781.00 744.04 L746.17 707.48 A14.85 14.85 0 1 0 731.93 732.15 Z M781.0048 744.0384 m-14.845952 0 a14.845952 14.845952 0 1 0 29.691904 0 a14.845952 14.845952 0 1 0 -29.691904 0 Z" fill="#f2d9a0"/></svg>

assets/icons/brand/icon-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><rect width="1024" height="1024" rx="174.08" fill="#4a3316"/><defs><clipPath id="tile"><rect width="1024" height="1024" rx="174.08"/></clipPath><linearGradient id="sheen" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#fff" stop-opacity="0.15"/></linearGradient><linearGradient id="shade" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#000" stop-opacity="0.15"/><stop offset="1" stop-color="#000" stop-opacity="0"/></linearGradient></defs><g clip-path="url(#tile)"><rect x="74.67" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 90.67 512.00)"/><rect x="245.33" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 261.33 512.00)"/><rect x="416.00" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 432.00 512.00)"/><rect x="586.67" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 602.67 512.00)"/><rect x="757.33" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 773.33 512.00)"/><rect x="928.00" y="-204.80" width="32.00" height="1433.60" fill="#432e14" transform="rotate(4 944.00 512.00)"/></g><rect width="1024" height="1024" fill="url(#sheen)" clip-path="url(#tile)"/><rect width="1024" height="1024" fill="url(#shade)" clip-path="url(#tile)"/><path transform="translate(157.86 804.91)" d="M280.84-39.21Q366.55-39.21 413.96-102.58Q461.38-165.95 461.38-273.54Q461.38-279.93 461.38-286.31L285.40-286.31L234.34-208.80L219.75-208.80L219.75-413.96L234.34-413.96L285.40-336.46L457.73-336.46Q445.88-441.32 394.81-502.86Q343.75-564.41 270.81-564.41Q244.37-564.41 223.39-559.85Q202.42-555.29 182.36-541.62L93.92-398.46L77.50-398.46L87.53-568.06Q126.74-587.21 173.24-599.06Q219.75-610.91 291.78-610.91Q359.25-610.91 417.15-587.66Q475.05-564.41 517.45-522.92Q559.85-481.44 583.56-424.90Q607.27-368.37 607.27-300.90Q607.27-211.54 566.69-141.33Q526.12-71.12 454.99-31Q383.87 9.12 291.78 9.12Q225.22 9.12 169.14-3.65Q113.06-16.41 75.68-38.30L62.92-192.39L78.42-192.39L160.48-71.12Q186.01-56.53 215.19-47.87Q244.37-39.21 280.84-39.21" fill="#f2d9a0"/><path d="M807.01 807.01 L825.70 743.46 A19.48 19.48 0 1 0 788.33 743.46 Z M807.01 807.01 L871.40 791.42 A19.48 19.48 0 1 0 852.71 759.05 Z M807.01 807.01 L852.71 854.97 A19.48 19.48 0 1 0 871.40 822.61 Z M807.01 807.01 L788.33 870.57 A19.48 19.48 0 1 0 825.70 870.57 Z M807.01 807.01 L742.63 822.61 A19.48 19.48 0 1 0 761.32 854.97 Z M807.01 807.01 L761.32 759.05 A19.48 19.48 0 1 0 742.63 791.42 Z M807.0144 807.0144 m-19.475456 0 a19.475456 19.475456 0 1 0 38.950912 0 a19.475456 19.475456 0 1 0 -38.950912 0 Z" fill="#f2d9a0"/></svg>

assets/icons/brand/icon-light-android-background.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><rect width="1024" height="1024" rx="0" fill="#e6b053"/><defs><clipPath id="tile"><rect width="1024" height="1024" rx="0"/></clipPath><linearGradient id="sheen" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#fff" stop-opacity="0.15"/></linearGradient><linearGradient id="shade" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#000" stop-opacity="0.15"/><stop offset="1" stop-color="#000" stop-opacity="0"/></linearGradient></defs><g clip-path="url(#tile)"><rect x="74.67" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 90.67 512.00)"/><rect x="245.33" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 261.33 512.00)"/><rect x="416.00" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 432.00 512.00)"/><rect x="586.67" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 602.67 512.00)"/><rect x="757.33" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 773.33 512.00)"/><rect x="928.00" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 944.00 512.00)"/></g><rect width="1024" height="1024" fill="url(#sheen)" clip-path="url(#tile)"/><rect width="1024" height="1024" fill="url(#shade)" clip-path="url(#tile)"/></svg>

assets/icons/brand/icon-light-android-foreground.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><path transform="translate(237.62 774.88)" d="M250.04-34.91Q326.35-34.91 368.57-91.33Q410.78-147.75 410.78-243.55Q410.78-249.23 410.78-254.91L254.10-254.91L208.64-185.91L195.65-185.91L195.65-368.57L208.64-368.57L254.10-299.56L407.53-299.56Q396.98-392.92 351.52-447.72Q306.06-502.52 241.11-502.52Q217.57-502.52 198.90-498.46Q180.22-494.40 162.36-482.22L83.62-354.77L69-354.77L77.93-505.76Q112.84-522.81 154.25-533.37Q195.65-543.92 259.78-543.92Q319.86-543.92 371.41-523.22Q422.96-502.52 460.71-465.58Q498.46-428.64 519.57-378.31Q540.67-327.98 540.67-267.90Q540.67-188.34 504.55-125.83Q468.42-63.32 405.10-27.60Q341.78 8.12 259.78 8.12Q200.52 8.12 150.59-3.25Q100.67-14.61 67.38-34.10L56.02-171.29L69.82-171.29L142.88-63.32Q165.61-50.33 191.59-42.62Q217.57-34.91 250.04-34.91" fill="#5a3a12"/><path d="M781.00 744.04 L795.25 695.59 A14.85 14.85 0 1 0 766.76 695.59 Z M781.00 744.04 L830.08 732.15 A14.85 14.85 0 1 0 815.84 707.48 Z M781.00 744.04 L815.84 780.60 A14.85 14.85 0 1 0 830.08 755.93 Z M781.00 744.04 L766.76 792.49 A14.85 14.85 0 1 0 795.25 792.49 Z M781.00 744.04 L731.93 755.93 A14.85 14.85 0 1 0 746.17 780.60 Z M781.00 744.04 L746.17 707.48 A14.85 14.85 0 1 0 731.93 732.15 Z M781.0048 744.0384 m-14.845952 0 a14.845952 14.845952 0 1 0 29.691904 0 a14.845952 14.845952 0 1 0 -29.691904 0 Z" fill="#5a3a12"/></svg>

assets/icons/brand/icon-light.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024"><rect width="1024" height="1024" rx="174.08" fill="#e6b053"/><defs><clipPath id="tile"><rect width="1024" height="1024" rx="174.08"/></clipPath><linearGradient id="sheen" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#fff" stop-opacity="0.15"/></linearGradient><linearGradient id="shade" gradientUnits="userSpaceOnUse" x1="0" y1="1024" x2="1024" y2="0"><stop offset="0" stop-color="#000" stop-opacity="0.15"/><stop offset="1" stop-color="#000" stop-opacity="0"/></linearGradient></defs><g clip-path="url(#tile)"><rect x="74.67" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 90.67 512.00)"/><rect x="245.33" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 261.33 512.00)"/><rect x="416.00" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 432.00 512.00)"/><rect x="586.67" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 602.67 512.00)"/><rect x="757.33" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 773.33 512.00)"/><rect x="928.00" y="-204.80" width="32.00" height="1433.60" fill="#d8a54e" transform="rotate(4 944.00 512.00)"/></g><rect width="1024" height="1024" fill="url(#sheen)" clip-path="url(#tile)"/><rect width="1024" height="1024" fill="url(#shade)" clip-path="url(#tile)"/><path transform="translate(157.86 804.91)" d="M280.84-39.21Q366.55-39.21 413.96-102.58Q461.38-165.95 461.38-273.54Q461.38-279.93 461.38-286.31L285.40-286.31L234.34-208.80L219.75-208.80L219.75-413.96L234.34-413.96L285.40-336.46L457.73-336.46Q445.88-441.32 394.81-502.86Q343.75-564.41 270.81-564.41Q244.37-564.41 223.39-559.85Q202.42-555.29 182.36-541.62L93.92-398.46L77.50-398.46L87.53-568.06Q126.74-587.21 173.24-599.06Q219.75-610.91 291.78-610.91Q359.25-610.91 417.15-587.66Q475.05-564.41 517.45-522.92Q559.85-481.44 583.56-424.90Q607.27-368.37 607.27-300.90Q607.27-211.54 566.69-141.33Q526.12-71.12 454.99-31Q383.87 9.12 291.78 9.12Q225.22 9.12 169.14-3.65Q113.06-16.41 75.68-38.30L62.92-192.39L78.42-192.39L160.48-71.12Q186.01-56.53 215.19-47.87Q244.37-39.21 280.84-39.21" fill="#5a3a12"/><path d="M807.01 807.01 L825.70 743.46 A19.48 19.48 0 1 0 788.33 743.46 Z M807.01 807.01 L871.40 791.42 A19.48 19.48 0 1 0 852.71 759.05 Z M807.01 807.01 L852.71 854.97 A19.48 19.48 0 1 0 871.40 822.61 Z M807.01 807.01 L788.33 870.57 A19.48 19.48 0 1 0 825.70 870.57 Z M807.01 807.01 L742.63 822.61 A19.48 19.48 0 1 0 761.32 854.97 Z M807.01 807.01 L761.32 759.05 A19.48 19.48 0 1 0 742.63 791.42 Z M807.0144 807.0144 m-19.475456 0 a19.475456 19.475456 0 1 0 38.950912 0 a19.475456 19.475456 0 1 0 -38.950912 0 Z" fill="#5a3a12"/></svg>

assets/icons/brand/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "erudit-icon-brand",
+  "private": true,
+  "type": "module",
+  "description": "Reference generator for the Erudit app-icon set (see docs/ICON_BRANDBOOK.md).",
+  "scripts": {
+    "build": "node build-set.mjs && node build-android-res.mjs"
+  },
+  "dependencies": {
+    "opentype.js": "^1.3.4"
+  }
+}

assets/icons/brand/render-png.mjs

@@ -0,0 +1,21 @@
+'use strict';
+// Rasterise an icon SVG to PNG at a given size, using the `ui` package's cached
+// Playwright chromium (no extra install). Usage:
+//   node render-png.mjs <in.svg> <out.png> [size=1024]
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const pw = await import(join(DIR, '..', '..', '..', 'ui', 'node_modules', '@playwright', 'test', 'index.js'));
+const { chromium } = pw.default ?? pw;
+
+const [, , svgPath, pngPath, size] = process.argv;
+const S = Number(size) || 1024;
+const svg = readFileSync(svgPath, 'utf8');
+const b = await chromium.launch();
+const pg = await b.newPage({ viewport: { width: S, height: S }, deviceScaleFactor: 1 });
+await pg.setContent(`<!doctype html><meta charset=utf8><style>*{margin:0;padding:0}</style>${svg}`, { waitUntil: 'networkidle' });
+writeFileSync(pngPath, await pg.locator('svg').screenshot({ omitBackground: true }));
+await b.close();
+console.log('wrote', pngPath, S + 'px');

assets/icons/build/extract.js

@@ -1,78 +0,0 @@
-'use strict';
-// Extract the glyph outlines the site icons and the og-image wordmark need from a
-// grotesque font (LiberationSans = Arial-metric, matching the game's system-ui/Arial
-// stack) and emit cubic-bezier contours per character, baseline at y=0, y-down,
-// plus the advance width so generate.js can lay out words without the font.
-// Same outline conversion as ../../vk/build/extract.js, generalised to a char set.
-const opentype = require('opentype.js');
-const fs = require('fs');
-
-const FONT = process.argv[2] || '/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf';
-const b = fs.readFileSync(FONT);
-const font = opentype.parse(b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength));
-const FS = 1000; // em scale
-
-// The tile glyphs («Э», «8») + every character of the og-image wordmark lines
-// («Эрудит», «Скрэббл — игра в слова»). The space carries only an advance.
-const CHARS = [...new Set('Э8рудитСкэббл—игра в слова')];
-
-function glyphData(ch) {
-  const g = font.charToGlyph(ch);
-  const p = g.getPath(0, 0, FS); // baseline at y=0, y-down
-  const contours = [];
-  let cur = null, prev = null;
-  for (const c of p.commands) {
-    if (c.type === 'M') {
-      if (cur) contours.push(cur);
-      cur = [{ v: [c.x, c.y], i: [c.x, c.y], o: [c.x, c.y] }];
-      prev = { x: c.x, y: c.y };
-    } else if (c.type === 'L') {
-      cur.push({ v: [c.x, c.y], i: [c.x, c.y], o: [c.x, c.y] });
-      prev = { x: c.x, y: c.y };
-    } else if (c.type === 'C') {
-      cur[cur.length - 1].o = [c.x1, c.y1];
-      cur.push({ v: [c.x, c.y], i: [c.x2, c.y2], o: [c.x, c.y] });
-      prev = { x: c.x, y: c.y };
-    } else if (c.type === 'Q') {
-      const c1 = [prev.x + 2 / 3 * (c.x1 - prev.x), prev.y + 2 / 3 * (c.y1 - prev.y)];
-      const c2 = [c.x + 2 / 3 * (c.x1 - c.x), c.y + 2 / 3 * (c.y1 - c.y)];
-      cur[cur.length - 1].o = c1;
-      cur.push({ v: [c.x, c.y], i: c2, o: [c.x, c.y] });
-      prev = { x: c.x, y: c.y };
-    } else if (c.type === 'Z') {
-      if (cur && cur.length > 1) {
-        const last = cur[cur.length - 1], first = cur[0];
-        if (Math.hypot(last.v[0] - first.v[0], last.v[1] - first.v[1]) < 1e-3) {
-          first.i = last.i; // fold the duplicate closing point into the first
-          cur.pop();
-        }
-      }
-      if (cur) { contours.push(cur); cur = null; }
-    }
-  }
-  if (cur) contours.push(cur);
-
-  let minx = Infinity, miny = Infinity, maxx = -Infinity, maxy = -Infinity;
-  const out = contours.map(ct => {
-    const v = [], i = [], o = [];
-    ct.forEach(pt => {
-      v.push(pt.v);
-      i.push([pt.i[0] - pt.v[0], pt.i[1] - pt.v[1]]);
-      o.push([pt.o[0] - pt.v[0], pt.o[1] - pt.v[1]]);
-      minx = Math.min(minx, pt.v[0]); maxx = Math.max(maxx, pt.v[0]);
-      miny = Math.min(miny, pt.v[1]); maxy = Math.max(maxy, pt.v[1]);
-    });
-    return { i, o, v, c: true };
-  });
-  const bbox = out.length
-    ? { x: minx, y: miny, w: maxx - minx, h: maxy - miny }
-    : { x: 0, y: 0, w: 0, h: 0 }; // the space has no outline
-  return { adv: g.advanceWidth * (FS / font.unitsPerEm), bbox, contours: out };
-}
-
-const glyphs = {};
-for (const ch of CHARS) glyphs[ch] = glyphData(ch);
-
-const out = __dirname + '/glyphs.json';
-fs.writeFileSync(out, JSON.stringify({ em: FS, glyphs }));
-console.log('wrote', out, fs.statSync(out).size, 'bytes;', CHARS.length, 'glyphs:', CHARS.join(''));

assets/icons/build/generate.js

@@ -1,128 +0,0 @@
-'use strict';
-// Site icons + the Open Graph card for the public landing, drawn from the same
-// design as ../../vk (the wooden Erudit tile: face «Э», score «8») and the app's
-// board palette (ui/src/app.css). Everything is composed as SVG from the committed
-// glyph outlines (build/extract.js -> glyphs.json), so no font is needed at build
-// time; the PNG/ICO rasters are screenshots taken with the ui package's Playwright
-// chromium (@playwright/test re-exports the browser API). Outputs go straight to
-// ui/public/:
-//   favicon.svg          96 viewBox, transparent, tile + «Э» (the score is illegible small)
-//   favicon.ico          32x32 PNG-in-ICO render of the same
-//   apple-touch-icon.png 180x180 opaque full-bleed tile (iOS masks its own corners)
-//   og-image.png         1200x630 card: tile + wordmark on the board green
-const fs = require('fs');
-const path = require('path');
-
-const G = JSON.parse(fs.readFileSync(path.join(__dirname, 'glyphs.json'), 'utf8'));
-const UI = path.resolve(__dirname, '../../../ui');
-const OUT = path.join(UI, 'public');
-
-// ---- palette (vk loader tile + app.css board tokens) ------------------------
-const FACE = '#D9B978', BORDER = '#B49559', GLYPH = '#1A1A1A';
-const BOARD_DARK = '#2a3330', TEXT = '#e7ece8', TEXT_MUTED = '#cdd6cf';
-
-// ---- glyph outlines -> SVG path data ----------------------------------------
-const r2 = n => Math.round(n * 100) / 100;
-// pathD renders one glyph's contours scaled by sc and translated by (tx, ty).
-function pathD(g, sc, tx, ty) {
-  const pt = (v, d) => `${r2(v[0] * sc + tx + d[0] * sc)} ${r2(v[1] * sc + ty + d[1] * sc)}`;
-  const Z = [0, 0];
-  return g.contours.map(ct => {
-    const n = ct.v.length;
-    let d = `M${pt(ct.v[0], Z)}`;
-    for (let k = 1; k <= n; k++) {
-      const a = k - 1, b = k % n;
-      d += `C${pt(ct.v[a], ct.o[a])} ${pt(ct.v[b], ct.i[b])} ${pt(ct.v[b], Z)}`;
-    }
-    return d + 'Z';
-  }).join('');
-}
-// glyphAt centres a glyph's bbox at (cx, cy) with the given pixel cap height, the
-// same placement rule as the vk loader's glyph(). stroke fattens it slightly.
-function glyphAt(ch, capPx, cx, cy, stroke, colour) {
-  const g = G.glyphs[ch], sc = capPx / g.bbox.h;
-  const d = pathD(g, sc, cx - (g.bbox.x + g.bbox.w / 2) * sc, cy - (g.bbox.y + g.bbox.h / 2) * sc);
-  return `<path d="${d}" fill="${colour}" stroke="${colour}" stroke-width="${r2(stroke)}"/>`;
-}
-// textLine lays out a string on a baseline from the per-glyph advances; capPx sets
-// the capital height (measured on «Э»). Returns the combined path + the width.
-function textLine(str, capPx, x, y, colour) {
-  const sc = capPx / G.glyphs['Э'].bbox.h;
-  let d = '', w = 0;
-  for (const ch of str) {
-    const g = G.glyphs[ch];
-    if (g.contours.length) d += pathD(g, sc, x + w, y);
-    w += g.adv * sc;
-  }
-  return { svg: `<path d="${d}" fill="${colour}"/>`, width: w };
-}
-// tile draws the rounded wooden tile centred at (cx, cy): size px wide/high, with
-// the vk loader's corner (6/52) and rim proportions, «Э» and optionally the «8».
-function tile(cx, cy, size, withScore) {
-  const h = size / 2, rx = size * (6 / 52), rim = size * (1.8 / 52);
-  let s = `<rect x="${r2(cx - h + rim / 2)}" y="${r2(cy - h + rim / 2)}" width="${r2(size - rim)}" height="${r2(size - rim)}" rx="${r2(rx)}" fill="${FACE}" stroke="${BORDER}" stroke-width="${r2(rim)}"/>`;
-  s += glyphAt('Э', size * (32 / 52), cx, cy - size * (1 / 52), size * (1 / 52), GLYPH);
-  if (withScore) s += glyphAt('8', size * (8.5 / 52), cx + size * (19.5 / 52), cy + size * (18.5 / 52), size * (0.5 / 52), GLYPH);
-  return s;
-}
-const svg = (w, h, body) => `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${body}</svg>`;
-
-// ---- favicon.svg (the committed vector master) -------------------------------
-const favicon = svg(96, 96, tile(48, 48, 88, false)) + '\n';
-
-// ---- apple-touch-icon: opaque full bleed, iOS applies its own corner mask ----
-const appleTouch = svg(180, 180,
-  `<rect width="180" height="180" fill="${FACE}"/>` +
-  `<rect x="8" y="8" width="164" height="164" rx="18" fill="none" stroke="${BORDER}" stroke-width="4"/>` +
-  glyphAt('Э', 100, 90, 88, 3, GLYPH) +
-  glyphAt('8', 26, 146, 142, 1.5, GLYPH));
-
-// ---- og-image: tile + wordmark, centred as one group on the board green ------
-function ogImage() {
-  const W = 1200, H = 630, tileSize = 340, gap = 84;
-  const l1 = textLine('Эрудит', 112, 0, 0, TEXT);
-  const l2 = textLine('Скрэббл — игра в слова', 44, 0, 0, TEXT_MUTED);
-  const textW = Math.max(l1.width, l2.width);
-  const left = (W - (tileSize + gap + textW)) / 2;
-  const tx = left + tileSize + gap;
-  // Two baselines around the vertical centre; the tile centre sits between them.
-  const b1 = 295, b2 = 408;
-  const body =
-    `<rect width="${W}" height="${H}" fill="${BOARD_DARK}"/>` +
-    tile(left + tileSize / 2, H / 2, tileSize, true) +
-    textLine('Эрудит', 112, tx, b1, TEXT).svg +
-    textLine('Скрэббл — игра в слова', 44, tx, b2, TEXT_MUTED).svg;
-  console.log(`og-image: text ${Math.round(textW)}px wide, group left ${Math.round(left)}px`);
-  return svg(W, H, body);
-}
-
-// ---- rasterisation (Playwright chromium from ui/node_modules) ----------------
-async function shoot(page, markup, w, h, transparent) {
-  await page.setViewportSize({ width: w, height: h });
-  await page.setContent(`<body style="margin:0">${markup}</body>`);
-  return page.screenshot({ omitBackground: transparent });
-}
-// icoFromPNG wraps one PNG as a single-entry .ico (ICONDIR + ICONDIRENTRY + PNG).
-function icoFromPNG(png, sizePx) {
-  const h = Buffer.alloc(22);
-  h.writeUInt16LE(0, 0); h.writeUInt16LE(1, 2); h.writeUInt16LE(1, 4); // icon, 1 image
-  h.writeUInt8(sizePx, 6); h.writeUInt8(sizePx, 7);                    // 32x32
-  h.writeUInt16LE(1, 10); h.writeUInt16LE(32, 12);                     // planes, 32bpp
-  h.writeUInt32LE(png.length, 14); h.writeUInt32LE(22, 18);            // size, offset
-  return Buffer.concat([h, png]);
-}
-
-(async () => {
-  fs.writeFileSync(path.join(OUT, 'favicon.svg'), favicon);
-  const { chromium } = require(path.join(UI, 'node_modules', '@playwright/test'));
-  const browser = await chromium.launch();
-  const page = await browser.newPage();
-  const fav32 = await shoot(page, svg(32, 32, tile(16, 16, 29.33, false)), 32, 32, true);
-  fs.writeFileSync(path.join(OUT, 'favicon.ico'), icoFromPNG(fav32, 32));
-  fs.writeFileSync(path.join(OUT, 'apple-touch-icon.png'), await shoot(page, appleTouch, 180, 180, false));
-  fs.writeFileSync(path.join(OUT, 'og-image.png'), await shoot(page, ogImage(), 1200, 630, false));
-  await browser.close();
-  for (const f of ['favicon.svg', 'favicon.ico', 'apple-touch-icon.png', 'og-image.png']) {
-    console.log('wrote', path.join(OUT, f), fs.statSync(path.join(OUT, f)).size, 'bytes');
-  }
-})();

backend/cmd/backend/main.go

@@ -283,6 +283,13 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	}
 	logger.Info("payments domain ready")
 
+	// Warm the public-offer price list cache so /offer/ serves the current catalog from the first
+	// request; it is reprojected lazily thereafter on any catalog edit. Non-fatal — a transient
+	// failure here only defers the projection to the first read.
+	if _, err := paymentsSvc.OfferPricing(ctx); err != nil {
+		logger.Warn("offer pricing warm failed; will project on first request", zap.Error(err))
+	}
+
 	// Wire the payments surface into the domains that consume it: the online-game hint wallet
 	// and the account-merge wallet fold. Done after the reachability check so a broken payments
 	// schema fails boot before anything depends on it.

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

@@ -21,7 +21,17 @@
 <div><button type="submit">Add</button></div>
 </form>
 </section>
+<section class="panel"><h2>Rewarded ads (watch for chips)</h2>
+<p class="note">The chips a player earns per rewarded-video view (VK only), plus the per-day and per-hour caps that bound free chips — <strong>0 payout turns rewarded off</strong>. This is the shared reward config, not a product.</p>
+<form class="form col" method="post" action="/_gm/catalog/reward">
+<label>Chips per view <input type="number" name="reward_payout" min="0" value="{{.RewardPayout}}"></label>
+<label>Daily cap <input type="number" name="reward_daily" min="0" value="{{.RewardDailyCap}}"></label>
+<label>Hourly cap <input type="number" name="reward_hourly" min="0" value="{{.RewardHourlyCap}}"></label>
+<div><button type="submit">Save</button></div>
+</form>
+</section>
 <section class="panel"><h2>Products</h2>
+<p class="note">Showing {{if .ShowAll}}<strong>all</strong> products (active + archived) — <a href="/_gm/catalog">active only</a>{{else}}<strong>active</strong> products — <a href="/_gm/catalog?all=1">show all (incl. archived)</a>{{end}}.</p>
 <table class="list">
 <thead><tr><th>Title</th><th>Status</th><th>Atoms</th><th>Prices</th><th></th></tr></thead>
 <tbody>

backend/internal/adminconsole/views.go

@@ -677,6 +677,15 @@ type FeedbackDetailView struct {
 // CatalogView is the product-catalog list page.
 type CatalogView struct {
 	Products []ProductRow
+	// ShowAll reports whether archived products are listed alongside active ones (the active/all
+	// toggle); it drives the toggle link and the list heading.
+	ShowAll bool
+	// RewardPayout / RewardDailyCap / RewardHourlyCap are the rewarded-video config (chips earned per
+	// view and the per-day / per-hour anti-abuse caps), shown in and edited from the page's
+	// rewarded-ads form. A 0 payout means rewarded is inert.
+	RewardPayout    int
+	RewardDailyCap  int
+	RewardHourlyCap int
 }
 
 // ProductRow is one product in the catalog list: its composition, prices, the archived flag

backend/internal/inttest/catalog_editor_test.go

@@ -16,7 +16,7 @@ import (
 // productByTitle finds a catalog product by its (unique in the test) title.
 func productByTitle(t *testing.T, pay *payments.Service, title string) payments.AdminProduct {
 	t.Helper()
-	all, err := pay.AdminCatalog(context.Background())
+	all, err := pay.AdminCatalog(context.Background(), true)
 	if err != nil {
 		t.Fatalf("admin catalog: %v", err)
 	}
@@ -57,7 +57,7 @@ func TestConsoleCatalogEditor(t *testing.T) {
 	if code, body := consoleDo(h, http.MethodPost, catalog, "title=cat-bad&chips=100&active=true", origin); code != http.StatusOK || !strings.Contains(body, "Invalid product") {
 		t.Fatalf("bad pack = %d, has 'Invalid product' = %v", code, strings.Contains(body, "Invalid product"))
 	}
-	if _, err := pay.AdminCatalog(ctx); err != nil {
+	if _, err := pay.AdminCatalog(ctx, true); err != nil {
 		t.Fatalf("catalog: %v", err)
 	}
 
@@ -95,3 +95,59 @@ func TestConsoleCatalogEditor(t *testing.T) {
 		t.Fatalf("delete transacted = %d, has 'Cannot delete' = %v", code, strings.Contains(body, "Cannot delete"))
 	}
 }
+
+// TestConsoleCatalogActiveToggle checks the catalog console lists only active products by default and
+// includes the archived ones under ?all=1 (the active/all toggle).
+func TestConsoleCatalogActiveToggle(t *testing.T) {
+	srv, _, _ := bannerServer(t)
+	h := srv.Handler()
+	const origin = "http://admin.test"
+	const catalog = "http://admin.test/_gm/catalog"
+
+	// An active value and an archived one (created without the active flag).
+	if code, _ := consoleDo(h, http.MethodPost, catalog, "title=toggle-active&hints=5&price_chip=50&active=true", origin); code != http.StatusOK {
+		t.Fatal("create active failed")
+	}
+	if code, _ := consoleDo(h, http.MethodPost, catalog, "title=toggle-archived&hints=9&price_chip=90", origin); code != http.StatusOK {
+		t.Fatal("create archived failed")
+	}
+
+	// Default view: active only.
+	if _, body := consoleDo(h, http.MethodGet, catalog, "", ""); !strings.Contains(body, "toggle-active") || strings.Contains(body, "toggle-archived") {
+		t.Errorf("default view: active listed=%v, archived listed=%v (want true/false)",
+			strings.Contains(body, "toggle-active"), strings.Contains(body, "toggle-archived"))
+	}
+
+	// ?all=1: active and archived.
+	if _, body := consoleDo(h, http.MethodGet, catalog+"?all=1", "", ""); !strings.Contains(body, "toggle-active") || !strings.Contains(body, "toggle-archived") {
+		t.Errorf("all view: active listed=%v, archived listed=%v (want true/true)",
+			strings.Contains(body, "toggle-active"), strings.Contains(body, "toggle-archived"))
+	}
+}
+
+// TestConsoleRewardConfig checks the rewarded-ads config form on the catalog page: a POST updates the
+// payout and caps, the page pre-fills the current values, and a negative value is refused.
+func TestConsoleRewardConfig(t *testing.T) {
+	srv, _, pay := bannerServer(t)
+	h := srv.Handler()
+	const origin = "http://admin.test"
+	const reward = "http://admin.test/_gm/catalog/reward"
+
+	// Set the payout and caps.
+	if code, body := consoleDo(h, http.MethodPost, reward, "reward_payout=7&reward_daily=40&reward_hourly=9", origin); code != http.StatusOK || !strings.Contains(body, "Saved") {
+		t.Fatalf("set reward = %d, has 'Saved' = %v", code, strings.Contains(body, "Saved"))
+	}
+	if payout, daily, hourly, err := pay.RewardConfig(context.Background()); err != nil || payout != 7 || daily != 40 || hourly != 9 {
+		t.Fatalf("reward config = %d/%d/%d (err %v), want 7/40/9", payout, daily, hourly, err)
+	}
+
+	// The catalog page renders the form pre-filled with the current payout.
+	if _, body := consoleDo(h, http.MethodGet, "http://admin.test/_gm/catalog", "", ""); !strings.Contains(body, "reward_payout") || !strings.Contains(body, `value="7"`) {
+		t.Error("catalog page did not render the reward form with the current payout")
+	}
+
+	// A negative value is refused (the service validates non-negativity).
+	if code, body := consoleDo(h, http.MethodPost, reward, "reward_payout=-1", origin); code != http.StatusOK || !strings.Contains(body, "non-negative") {
+		t.Errorf("negative payout = %d, has 'non-negative' = %v", code, strings.Contains(body, "non-negative"))
+	}
+}

backend/internal/inttest/payments_catalog_test.go

@@ -4,6 +4,7 @@ package inttest
 
 import (
 	"context"
+	"strings"
 	"testing"
 
 	"github.com/google/uuid"
@@ -111,3 +112,44 @@ func TestPaymentsCatalogExcludesDeactivated(t *testing.T) {
 		t.Error("deactivated product must not appear in the storefront")
 	}
 }
+
+// TestOfferPricingReflectsCatalogEdits verifies the public-offer price list (§4.4) is projected from
+// the live catalog and its cache is invalidated on a catalog mutation: a newly created pack appears
+// with its per-rail prices, and archiving it through the service drops it from the next read.
+func TestOfferPricingReflectsCatalogEdits(t *testing.T) {
+	svc := newPaymentsService()
+	ctx := context.Background()
+	title := "OfferTest " + uuid.NewString()
+	id, err := svc.CreateProduct(ctx, payments.ProductInput{
+		Title: title,
+		Atoms: []payments.AtomLine{{Atom: "chips", Quantity: 50}},
+		Prices: []payments.PriceLine{
+			{Method: "direct", Currency: payments.CurrencyRUB, Amount: 20000},
+			{Method: "vk", Currency: payments.CurrencyVote, Amount: 30},
+			{Method: "telegram", Currency: payments.CurrencyStar, Amount: 100},
+		},
+	}, true)
+	if err != nil {
+		t.Fatalf("create pack: %v", err)
+	}
+
+	md, err := svc.OfferPricing(ctx)
+	if err != nil {
+		t.Fatalf("offer pricing: %v", err)
+	}
+	if row := "| " + title + " | 200.00 | 30 | 100 |"; !strings.Contains(md, row) {
+		t.Fatalf("offer pricing missing the new pack row %q\n%s", row, md)
+	}
+
+	// Archiving through the service marks the cache stale; the next read must reproject without it.
+	if err := svc.SetProductActive(ctx, id, false); err != nil {
+		t.Fatalf("archive: %v", err)
+	}
+	md, err = svc.OfferPricing(ctx)
+	if err != nil {
+		t.Fatalf("offer pricing after archive: %v", err)
+	}
+	if strings.Contains(md, title) {
+		t.Errorf("archived pack must drop from the offer pricing:\n%s", md)
+	}
+}

backend/internal/payments/catalog.go

@@ -38,6 +38,11 @@ const atomChips = "chips"
 // method are omitted (misconfigured or unavailable there). An untrusted context (empty Kind) has
 // no method, so only values show; buying is gated server-side regardless.
 func projectCatalog(entries []catalogEntry, cxt Context) CatalogView {
+	// Present products in the canonical listing order shared with the offer and the admin console
+	// (packs first by rouble price, then values grouped hints → no-ads → combo and by chip price); the
+	// client renders them as received. Ordered in place — the caller passes a fresh loadCatalog result
+	// it does not reuse.
+	sortCatalogEntries(entries)
 	var out CatalogView
 	for _, e := range entries {
 		isPack := false

backend/internal/payments/catalog_admin.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"math"
+	"slices"
 	"strings"
 
 	"github.com/google/uuid"
@@ -141,10 +143,60 @@ func validateProduct(in ProductInput, sellable bool) error {
 	return nil
 }
 
-// AdminCatalog lists every product (active and archived) with its composition, prices and whether it
+// AdminCatalog lists products with their composition, prices and whether each has been transacted,
-// has been transacted, for the admin editor. Read uncached, straight from the catalog tables.
+// for the admin editor. includeInactive adds the archived products to the active ones (the console's
-func (s *Service) AdminCatalog(ctx context.Context) ([]AdminProduct, error) {
+// active/all toggle); with it false only active products are returned. Read uncached, straight from
-	return s.store.adminCatalog(ctx)
+// the catalog tables.
+func (s *Service) AdminCatalog(ctx context.Context, includeInactive bool) ([]AdminProduct, error) {
+	return s.store.adminCatalog(ctx, includeInactive)
+}
+
+// SortAdminCatalog orders an admin catalog list in place the same way the public offer lists products
+// ([projectOfferPricing]): chip packs first, ascending by rouble price; then chip-priced values,
+// grouped (hints only, no-ads only, no-ads + hints, tournament) and ascending by chip price within a
+// group. It is stable, so equal-keyed products keep their incoming order, and it keys archived
+// products the same as active ones (the admin list shows both).
+func SortAdminCatalog(products []AdminProduct) {
+	slices.SortStableFunc(products, func(a, b AdminProduct) int {
+		return compareCatalogRank(adminRank(a), adminRank(b))
+	})
+}
+
+// adminIsPack reports whether the product is a chip pack (it carries the chips atom).
+func adminIsPack(p AdminProduct) bool {
+	for _, a := range p.Atoms {
+		if a.Atom == atomChips {
+			return true
+		}
+	}
+	return false
+}
+
+// adminValueGroup ranks a chip-priced value into the shared listing groups (see [valueGroup]).
+func adminValueGroup(p AdminProduct) int {
+	hasHints, hasNoAds, hasTournament := false, false, false
+	for _, a := range p.Atoms {
+		switch a.Atom {
+		case "hints":
+			hasHints = true
+		case "noads_days":
+			hasNoAds = true
+		case "tournament":
+			hasTournament = true
+		}
+	}
+	return valueGroup(hasHints, hasNoAds, hasTournament)
+}
+
+// adminPriceAmount returns the minor-unit amount of the product's price for the method and currency,
+// or math.MaxInt64 when it carries no such price (so a misconfigured product sorts last, not first).
+func adminPriceAmount(p AdminProduct, method string, cur Currency) int64 {
+	for _, pr := range p.Prices {
+		if pr.Method == method && pr.Currency == cur {
+			return pr.Amount
+		}
+	}
+	return math.MaxInt64
 }
 
 // CreateProduct validates and inserts a new product with its atoms and prices, returning its id. A
@@ -153,7 +205,11 @@ func (s *Service) CreateProduct(ctx context.Context, in ProductInput, active boo
 	if err := validateProduct(in, active); err != nil {
 		return uuid.Nil, err
 	}
-	return s.store.createProduct(ctx, in, active, s.clock())
+	id, err := s.store.createProduct(ctx, in, active, s.clock())
+	if err == nil {
+		s.markOfferStale()
+	}
+	return id, err
 }
 
 // UpdateProduct validates and replaces a product's title, atoms and prices. An active product must
@@ -166,7 +222,11 @@ func (s *Service) UpdateProduct(ctx context.Context, id uuid.UUID, in ProductInp
 	if err := validateProduct(in, active); err != nil {
 		return err
 	}
-	return s.store.updateProduct(ctx, id, in, s.clock())
+	if err := s.store.updateProduct(ctx, id, in, s.clock()); err != nil {
+		return err
+	}
+	s.markOfferStale()
+	return nil
 }
 
 // SetProductActive archives (active=false) or unarchives a product. Unarchiving revalidates the
@@ -181,11 +241,19 @@ func (s *Service) SetProductActive(ctx context.Context, id uuid.UUID, active boo
 			return err
 		}
 	}
-	return s.store.setProductActive(ctx, id, active, s.clock())
+	if err := s.store.setProductActive(ctx, id, active, s.clock()); err != nil {
+		return err
+	}
+	s.markOfferStale()
+	return nil
 }
 
 // DeleteProduct hard-deletes a product only when it has never been transacted (no order or ledger
 // row references it); otherwise it returns ErrProductTransacted and the caller archives instead.
 func (s *Service) DeleteProduct(ctx context.Context, id uuid.UUID) error {
-	return s.store.deleteProduct(ctx, id)
+	if err := s.store.deleteProduct(ctx, id); err != nil {
+		return err
+	}
+	s.markOfferStale()
+	return nil
 }

backend/internal/payments/catalog_order.go

@@ -0,0 +1,61 @@
+package payments
+
+import (
+	"cmp"
+	"slices"
+)
+
+// catalogRank is the canonical listing key for a catalog product: whether it is a chip pack, its
+// value subgroup (see [valueGroup]; unused for a pack) and the minor-unit amount its section sorts by
+// (a pack's direct rouble price, a value's chip price; math.MaxInt64 when absent, so a misconfigured
+// row sorts last rather than leading).
+type catalogRank struct {
+	pack   bool
+	group  int
+	amount int64
+}
+
+// compareCatalogRank is the single canonical product order, shared by the storefront ([projectCatalog]),
+// the public offer ([projectOfferPricing]) and the admin catalog ([SortAdminCatalog]): chip packs
+// first, ascending by rouble price; then chip-priced values grouped hints → no-ads → combo →
+// tournament and, within a group, ascending by chip price. A pack's group is unused (all packs share
+// one section). Callers use it through [entryRank] / [adminRank], which build the key from each
+// product shape, so the subgroup and ordering rules live in exactly one place.
+func compareCatalogRank(a, b catalogRank) int {
+	if a.pack != b.pack {
+		if a.pack {
+			return -1 // packs (sales) before values (chip exchange)
+		}
+		return 1
+	}
+	if !a.pack {
+		if d := cmp.Compare(a.group, b.group); d != 0 {
+			return d
+		}
+	}
+	return cmp.Compare(a.amount, b.amount)
+}
+
+// entryRank builds the canonical rank of a storefront / offer catalog entry.
+func entryRank(e catalogEntry) catalogRank {
+	if isPackEntry(e) {
+		return catalogRank{pack: true, amount: offerSortAmount(e, string(SourceDirect), CurrencyRUB)}
+	}
+	return catalogRank{group: offerValueGroup(e), amount: offerSortAmount(e, "", CurrencyChip)}
+}
+
+// adminRank builds the canonical rank of an admin catalog product.
+func adminRank(p AdminProduct) catalogRank {
+	if adminIsPack(p) {
+		return catalogRank{pack: true, amount: adminPriceAmount(p, string(SourceDirect), CurrencyRUB)}
+	}
+	return catalogRank{group: adminValueGroup(p), amount: adminPriceAmount(p, "", CurrencyChip)}
+}
+
+// sortCatalogEntries orders storefront / offer entries in place into the canonical listing order
+// ([compareCatalogRank]). Stable, so equal-keyed products keep their incoming (creation) order.
+func sortCatalogEntries(entries []catalogEntry) {
+	slices.SortStableFunc(entries, func(a, b catalogEntry) int {
+		return compareCatalogRank(entryRank(a), entryRank(b))
+	})
+}

backend/internal/payments/catalog_test.go

@@ -134,3 +134,97 @@ func TestProjectCatalog_Empty(t *testing.T) {
 		t.Errorf("empty catalog projected %d products, want 0", len(got.Products))
 	}
 }
+
+// TestProjectCatalog_CanonicalOrder checks the storefront lists products in the shared canonical order
+// (compareCatalogRank): chip packs first ascending by rouble price, then chip-priced values grouped
+// hints → no-ads → combo and ascending by chip price — the same order as the offer and the admin
+// console, regardless of catalog creation order.
+func TestProjectCatalog_CanonicalOrder(t *testing.T) {
+	pack := func(title string, rub int64) catalogEntry {
+		return catalogEntry{
+			id:     uuid.New(),
+			title:  title,
+			atoms:  []atomQty{{atomType: atomChips, quantity: 1}},
+			prices: []priceRow{{method: "direct", currency: CurrencyRUB, amount: rub}},
+		}
+	}
+	value := func(title string, chips int64, atoms ...string) catalogEntry {
+		e := catalogEntry{id: uuid.New(), title: title, prices: []priceRow{{method: "", currency: CurrencyChip, amount: chips}}}
+		for _, a := range atoms {
+			e.atoms = append(e.atoms, atomQty{atomType: a, quantity: 1})
+		}
+		return e
+	}
+	// Deliberately shuffled on input; the projection must impose the canonical order.
+	entries := []catalogEntry{
+		pack("packDear", 30000),
+		value("bundle", 500, "hints", "noads_days"),
+		pack("packCheap", 10000),
+		value("adsOnly", 150, "noads_days"),
+		value("hintsBig", 200, "hints"),
+		value("hintsSmall", 50, "hints"),
+	}
+	got := projectCatalog(entries, Context{Kind: SourceDirect})
+	want := []string{"packCheap", "packDear", "hintsSmall", "hintsBig", "adsOnly", "bundle"}
+	if len(got.Products) != len(want) {
+		t.Fatalf("projected %d products, want %d", len(got.Products), len(want))
+	}
+	for i, p := range got.Products {
+		if p.Title != want[i] {
+			t.Fatalf("order[%d] = %q, want %q (full: %v)", i, p.Title, want[i], productTitles(got.Products))
+		}
+	}
+}
+
+// productTitles extracts the projected product titles for a failure message.
+func productTitles(products []CatalogProduct) []string {
+	out := make([]string, len(products))
+	for i, p := range products {
+		out[i] = p.Title
+	}
+	return out
+}
+
+// TestSortAdminCatalog checks the admin list is ordered like the public offer: chip packs first,
+// ascending by rouble price; then values, grouped (hints only -> no-ads only -> no-ads + hints) and
+// ascending by chip price within a group. Stable and applied to active + archived alike.
+func TestSortAdminCatalog(t *testing.T) {
+	pack := func(title string, rub int64) AdminProduct {
+		return AdminProduct{
+			Title:  title,
+			Atoms:  []AtomLine{{Atom: atomChips, Quantity: 1}},
+			Prices: []PriceLine{{Method: string(SourceDirect), Currency: CurrencyRUB, Amount: rub}},
+		}
+	}
+	value := func(title string, chips int64, atoms ...string) AdminProduct {
+		p := AdminProduct{Title: title, Prices: []PriceLine{{Currency: CurrencyChip, Amount: chips}}}
+		for _, a := range atoms {
+			p.Atoms = append(p.Atoms, AtomLine{Atom: a, Quantity: 1})
+		}
+		return p
+	}
+	products := []AdminProduct{
+		pack("packDear", 30000),
+		value("bundle", 500, "hints", "noads_days"),
+		pack("packCheap", 10000),
+		value("adsOnly", 150, "noads_days"),
+		value("hintsBig", 200, "hints"),
+		value("hintsSmall", 50, "hints"),
+	}
+	SortAdminCatalog(products)
+	want := []string{"packCheap", "packDear", "hintsSmall", "hintsBig", "adsOnly", "bundle"}
+	for i, p := range products {
+		if p.Title != want[i] {
+			t.Fatalf("order[%d] = %q, want %q (full: %v)", i, p.Title, want[i], titles(products))
+		}
+	}
+}
+
+// titles extracts the product titles for a failure message.
+func titles(products []AdminProduct) []string {
+	out := make([]string, len(products))
+	for i, p := range products {
+		out[i] = p.Title
+	}
+	return out
+}

backend/internal/payments/offer.go

@@ -0,0 +1,210 @@
+package payments
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"slices"
+	"strings"
+)
+
+// pricingMarker is the token the owner-edited offer markdown (ui/legal/offer_ru.md, §4.4) carries
+// where the price list belongs. The render sidecar replaces it with the markdown [Service.OfferPricing]
+// returns before rendering the /offer/ page; the backend only produces the tables, never the marker.
+const pricingMarker = "<#pricing_template#>"
+
+// OfferPricing returns the public-offer price list (§4.4) as two markdown tables projected from the
+// active catalog: first the chip packs (funding chips with money, priced per rail — roubles / VK
+// votes / Telegram Stars), then the chip-priced values (what a player exchanges chips for). The
+// result is cached in memory and reprojected only after a catalog mutation (see [Service.markOfferStale]),
+// so a steady-state read issues no query — only the first read after an edit reprojects. The render
+// sidecar fetches it and splices it into the offer markdown at the pricing marker.
+func (s *Service) OfferPricing(ctx context.Context) (string, error) {
+	s.offerMu.Lock()
+	defer s.offerMu.Unlock()
+	if s.offerFresh {
+		return s.offerMD, nil
+	}
+	md, err := s.buildOfferPricing(ctx)
+	if err != nil {
+		return "", err
+	}
+	s.offerMD = md
+	s.offerFresh = true
+	return md, nil
+}
+
+// markOfferStale marks the cached offer price list for reprojection on the next [Service.OfferPricing]
+// read. Every catalog mutation calls it; it takes no I/O, so it never fails the mutation that triggers it.
+func (s *Service) markOfferStale() {
+	s.offerMu.Lock()
+	s.offerFresh = false
+	s.offerMu.Unlock()
+}
+
+// buildOfferPricing loads the active catalog and projects it into the offer tables.
+func (s *Service) buildOfferPricing(ctx context.Context) (string, error) {
+	entries, err := s.store.loadCatalog(ctx)
+	if err != nil {
+		return "", err
+	}
+	return projectOfferPricing(entries), nil
+}
+
+// projectOfferPricing renders the active catalog into the two offer tables. A chip pack (it carries
+// the chips atom) lists its per-rail money price; a value (no chips atom) lists its uniform chip
+// price. Packs are ordered by ascending rouble price; values are grouped by what they grant (hints
+// only, then no-ads only, then no-ads + hints, then tournament — see [offerValueGroup]) and, within
+// each group, ordered by ascending chip price. Price columns are right-aligned. An empty section is
+// omitted. Amounts are rendered through [Money] so no floating point ever reaches the page (roubles
+// show kopecks as "200.00", whole-unit rails as integers); a missing rail price shows an em dash.
+func projectOfferPricing(entries []catalogEntry) string {
+	// Order the whole catalog once by the shared canonical rank, then split it into the two offer
+	// tables (packs first, then the chip-exchange values); each keeps that order. Sort a copy so the
+	// caller's slice is left untouched.
+	sorted := slices.Clone(entries)
+	sortCatalogEntries(sorted)
+	var packs, values []catalogEntry
+	for _, e := range sorted {
+		if isPackEntry(e) {
+			packs = append(packs, e)
+		} else {
+			values = append(values, e)
+		}
+	}
+
+	var b strings.Builder
+	if len(packs) > 0 {
+		b.WriteString("Приобретение внутриигровой валюты «Фишка»:\n\n")
+		b.WriteString("| Наименование | Рубли | Голоса в VK | Stars в Telegram |\n")
+		b.WriteString("| --- | ---: | ---: | ---: |\n")
+		for _, e := range packs {
+			fmt.Fprintf(&b, "| %s | %s | %s | %s |\n",
+				offerCell(e.title),
+				offerPrice(e, string(SourceDirect), CurrencyRUB),
+				offerPrice(e, string(SourceVK), CurrencyVote),
+				offerPrice(e, string(SourceTelegram), CurrencyStar),
+			)
+		}
+	}
+	if len(values) > 0 {
+		if len(packs) > 0 {
+			b.WriteString("\n")
+		}
+		b.WriteString("Использование внутриигровой валюты «Фишка»:\n\n")
+		b.WriteString("| Наименование | «Фишки» |\n")
+		b.WriteString("| --- | ---: |\n")
+		for _, e := range values {
+			fmt.Fprintf(&b, "| %s | %s |\n", offerCell(e.title), offerPrice(e, "", CurrencyChip))
+		}
+	}
+	return strings.TrimRight(b.String(), "\n")
+}
+
+// offerValueGroup ranks a chip-priced value into the usage groups (see [valueGroup]).
+func offerValueGroup(e catalogEntry) int {
+	hasHints, hasNoAds, hasTournament := false, false, false
+	for _, a := range e.atoms {
+		switch a.atomType {
+		case "hints":
+			hasHints = true
+		case "noads_days":
+			hasNoAds = true
+		case "tournament":
+			hasTournament = true
+		}
+	}
+	return valueGroup(hasHints, hasNoAds, hasTournament)
+}
+
+// valueGroup ranks a chip-priced value into the listing groups shared by the public offer and the
+// admin catalog, in listing order: hints only (0), no-ads only (1), no-ads + hints (2), then anything
+// carrying the tournament atom (3). Tournament products are not sellable yet (validateProduct forbids
+// an active one), so group 3 is empty today; the rank reserves their place for when the tournament
+// economy lands. A value with no recognised benefit atom sorts after the known groups (defensive —
+// the catalog shape forbids it).
+func valueGroup(hasHints, hasNoAds, hasTournament bool) int {
+	switch {
+	case hasTournament:
+		return 3
+	case hasHints && hasNoAds:
+		return 2
+	case hasNoAds:
+		return 1
+	case hasHints:
+		return 0
+	default:
+		return 4
+	}
+}
+
+// offerSortAmount returns the entry's price in the given method and currency for ordering, or
+// math.MaxInt64 when it carries no such price, so a misconfigured row sorts last rather than leading.
+func offerSortAmount(e catalogEntry, method string, cur Currency) int64 {
+	if amt, ok := offerAmount(e, method, cur); ok {
+		return amt
+	}
+	return math.MaxInt64
+}
+
+// isPackEntry reports whether the catalog entry is a chip pack — it carries the chips atom (funds
+// chips with money) rather than being a chip-priced value.
+func isPackEntry(e catalogEntry) bool {
+	for _, a := range e.atoms {
+		if a.atomType == atomChips {
+			return true
+		}
+	}
+	return false
+}
+
+// offerPrice formats the entry's price for the given payment method and currency as a major-unit
+// string, or an em dash when the entry carries no such price.
+func offerPrice(e catalogEntry, method string, cur Currency) string {
+	amt, ok := offerAmount(e, method, cur)
+	if !ok {
+		return "—"
+	}
+	m, err := MoneyFromMinor(amt, cur)
+	if err != nil {
+		return "—"
+	}
+	return m.Major()
+}
+
+// offerAmount returns the raw minor-unit amount of the entry's price for the payment method and
+// currency, and whether such a price exists.
+func offerAmount(e catalogEntry, method string, cur Currency) (int64, bool) {
+	for _, pr := range e.prices {
+		if pr.method == method && pr.currency == cur {
+			return pr.amount, true
+		}
+	}
+	return 0, false
+}
+
+// offerCellReplacer neutralises every metacharacter of an admin-entered title so it renders as
+// literal text in the public offer. The title is operator input (the /_gm catalog editor) that flows
+// into a markdown table cell and then through marked into the /offer/ HTML, which is deliberately not
+// sanitised — so escaping here is the trust boundary. It covers HTML (no tag or entity reaches the
+// page), the markdown table pipe and the row newline, and the link brackets (a title must never
+// become a "javascript:" link). marked passes the entities through unchanged, so the reader sees the
+// exact title. NewReplacer scans once and never re-scans its own output, so "&" → "&amp;" does not
+// double-escape the entities the other rules emit.
+var offerCellReplacer = strings.NewReplacer(
+	"&", "&amp;",
+	"<", "&lt;",
+	">", "&gt;",
+	`"`, "&quot;",
+	"'", "&#39;",
+	"|", `\|`,
+	"[", `\[`,
+	"]", `\]`,
+	"\n", " ",
+)
+
+// offerCell escapes an admin-entered title for safe, literal rendering in a markdown table cell of
+// the public offer (see [offerCellReplacer]).
+func offerCell(s string) string {
+	return offerCellReplacer.Replace(s)
+}

backend/internal/payments/offer_test.go

@@ -0,0 +1,137 @@
+package payments
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+// TestProjectOfferPricing checks the happy path: a chip pack priced on every rail and a chip-priced
+// value render into the two tables, pack table first, money formatted through Money.
+func TestProjectOfferPricing(t *testing.T) {
+	entries := []catalogEntry{
+		{
+			id:    uuid.New(),
+			title: "50 «Фишек»",
+			atoms: []atomQty{{atomType: atomChips, quantity: 50}},
+			prices: []priceRow{
+				{method: string(SourceDirect), currency: CurrencyRUB, amount: 20000},
+				{method: string(SourceVK), currency: CurrencyVote, amount: 30},
+				{method: string(SourceTelegram), currency: CurrencyStar, amount: 100},
+			},
+		},
+		{
+			id:     uuid.New(),
+			title:  "200 подсказок",
+			atoms:  []atomQty{{atomType: "hints", quantity: 200}},
+			prices: []priceRow{{method: "", currency: CurrencyChip, amount: 50}},
+		},
+	}
+	md := projectOfferPricing(entries)
+	for _, want := range []string{
+		"| Наименование | Рубли | Голоса в VK | Stars в Telegram |",
+		"| --- | ---: | ---: | ---: |", // price columns right-aligned
+		"| 50 «Фишек» | 200.00 | 30 | 100 |",
+		"| Наименование | «Фишки» |",
+		"| --- | ---: |",
+		"| 200 подсказок | 50 |",
+	} {
+		if !strings.Contains(md, want) {
+			t.Errorf("projection missing %q\n---\n%s", want, md)
+		}
+	}
+	if strings.Index(md, "Приобретение") > strings.Index(md, "Использование") {
+		t.Errorf("the pack table must precede the values table:\n%s", md)
+	}
+}
+
+// TestProjectOfferPricingOrdering checks packs sort by ascending rouble price, and values sort by
+// group (hints only → no-ads only → no-ads + hints) then ascending chip price within a group.
+func TestProjectOfferPricingOrdering(t *testing.T) {
+	pack := func(title string, rub int64) catalogEntry {
+		return catalogEntry{
+			id:     uuid.New(),
+			title:  title,
+			atoms:  []atomQty{{atomType: atomChips, quantity: 1}},
+			prices: []priceRow{{method: string(SourceDirect), currency: CurrencyRUB, amount: rub}},
+		}
+	}
+	value := func(title string, chips int64, atoms ...string) catalogEntry {
+		e := catalogEntry{id: uuid.New(), title: title, prices: []priceRow{{method: "", currency: CurrencyChip, amount: chips}}}
+		for _, a := range atoms {
+			e.atoms = append(e.atoms, atomQty{atomType: a, quantity: 1})
+		}
+		return e
+	}
+	// Deliberately out of order on input.
+	entries := []catalogEntry{
+		pack("packDear", 30000),
+		pack("packCheap", 10000),
+		value("bundle", 500, "hints", "noads_days"),
+		value("adsOnly", 150, "noads_days"),
+		value("hintsBig", 200, "hints"),
+		value("hintsSmall", 50, "hints"),
+	}
+	md := projectOfferPricing(entries)
+	order := []string{"packCheap", "packDear", "hintsSmall", "hintsBig", "adsOnly", "bundle"}
+	last := -1
+	for _, title := range order {
+		i := strings.Index(md, "| "+title+" |")
+		if i < 0 {
+			t.Fatalf("row %q missing:\n%s", title, md)
+		}
+		if i < last {
+			t.Errorf("row %q out of order (want sequence %v):\n%s", title, order, md)
+		}
+		last = i
+	}
+}
+
+// TestProjectOfferPricingMissingRailAndEscaping checks a pack missing a rail shows an em dash and a
+// title carrying a pipe is escaped so the table layout survives.
+func TestProjectOfferPricingMissingRailAndEscaping(t *testing.T) {
+	entries := []catalogEntry{{
+		id:    uuid.New(),
+		title: "Bonus | pack",
+		atoms: []atomQty{{atomType: atomChips, quantity: 10}},
+		// A roubles price only — no VK, no Telegram.
+		prices: []priceRow{{method: string(SourceDirect), currency: CurrencyRUB, amount: 9900}},
+	}}
+	md := projectOfferPricing(entries)
+	if want := `| Bonus \| pack | 99.00 | — | — |`; !strings.Contains(md, want) {
+		t.Errorf("want row %q in:\n%s", want, md)
+	}
+}
+
+// TestProjectOfferPricingEscapesHTMLAndLinks checks an admin title carrying HTML or a markdown link
+// is neutralised so it cannot inject markup into the public offer: the tag becomes entities and the
+// link brackets are escaped (so no "javascript:" anchor forms). The raw metacharacters must not
+// survive into the projected markdown.
+func TestProjectOfferPricingEscapesHTMLAndLinks(t *testing.T) {
+	entries := []catalogEntry{{
+		id:     uuid.New(),
+		title:  `<script>alert(1)</script> [x](javascript:alert(2)) & "q"`,
+		atoms:  []atomQty{{atomType: "hints", quantity: 1}},
+		prices: []priceRow{{method: "", currency: CurrencyChip, amount: 5}},
+	}}
+	md := projectOfferPricing(entries)
+	for _, bad := range []string{"<script>", "</script>", "[x]", `& "q"`} {
+		if strings.Contains(md, bad) {
+			t.Errorf("unescaped %q survived into the projection:\n%s", bad, md)
+		}
+	}
+	for _, want := range []string{"&lt;script&gt;", `\[x\]`, "&amp;", "&quot;q&quot;"} {
+		if !strings.Contains(md, want) {
+			t.Errorf("want escaped %q in:\n%s", want, md)
+		}
+	}
+}
+
+// TestProjectOfferPricingEmpty checks an empty catalog projects to the empty string (no stray table
+// headers), so the offer's pricing marker is replaced with nothing.
+func TestProjectOfferPricingEmpty(t *testing.T) {
+	if got := projectOfferPricing(nil); got != "" {
+		t.Errorf("empty catalog must project to empty string, got %q", got)
+	}
+}

backend/internal/payments/service.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"encoding/json"
 	"fmt"
+	"sync"
 	"time"
 
 	"github.com/google/uuid"
@@ -19,6 +20,13 @@ import (
 type Service struct {
 	store *Store
 	clock func() time.Time
+
+	// offerMu guards the cached public-offer price list (§4.4). offerMD holds the projected
+	// markdown tables and offerFresh whether they are current; a catalog mutation clears offerFresh
+	// (markOfferStale) and the next OfferPricing read reprojects, so a served render issues no query.
+	offerMu    sync.Mutex
+	offerMD    string
+	offerFresh bool
 }
 
 // NewService constructs a Service over store with a wall-clock time source.

backend/internal/payments/service_intake.go

@@ -157,6 +157,22 @@ func (s *Service) RewardPayout(ctx context.Context, cxt Context, present []Sourc
 	return payout, err
 }
 
+// RewardConfig reads the rewarded-video config for the admin editor: the payout (chips per view) and
+// the per-day and per-hour caps.
+func (s *Service) RewardConfig(ctx context.Context) (payout, dailyCap, hourlyCap int, err error) {
+	return s.store.rewardConfig(ctx)
+}
+
+// SetRewardConfig updates the rewarded-video config (the payout and the two caps). All three must be
+// non-negative; a 0 payout leaves rewarded inert. It is not a catalog product, so it does not mark the
+// offer stale.
+func (s *Service) SetRewardConfig(ctx context.Context, payout, dailyCap, hourlyCap int) error {
+	if payout < 0 || dailyCap < 0 || hourlyCap < 0 {
+		return errors.New("payments: reward payout and caps must be non-negative")
+	}
+	return s.store.setRewardConfig(ctx, payout, dailyCap, hourlyCap)
+}
+
 // CreditReward credits a rewarded-video view's chips to the VK segment, client-attested (VK Mini App
 // ads expose no server verify — the client's watch result is trusted for an honest user; a forger who
 // skips the ad and calls the endpoint is bounded by the config daily cap). It is idempotent on the

backend/internal/payments/store_catalog_admin.go

@@ -19,11 +19,17 @@ import (
 // row references — it must be archived instead, to keep the append-only ledger resolvable.
 var ErrProductTransacted = errors.New("payments: product has transactions; archive instead of delete")
 
-// adminCatalog lists every product (active and archived) with its atoms, prices and transacted flag.
+// adminCatalog lists products with their atoms, prices and transacted flag. includeInactive adds the
-func (s *Store) adminCatalog(ctx context.Context) ([]AdminProduct, error) {
+// archived products to the active ones; with it false only active products are returned.
+func (s *Store) adminCatalog(ctx context.Context, includeInactive bool) ([]AdminProduct, error) {
+	where := table.Product.Active.IS_TRUE()
+	if includeInactive {
+		where = postgres.Bool(true)
+	}
 	var prods []model.Product
 	if err := postgres.SELECT(table.Product.AllColumns).
 		FROM(table.Product).
+		WHERE(where).
 		ORDER_BY(table.Product.CreatedAt.ASC()).
 		QueryContext(ctx, s.db, &prods); err != nil {
 		return nil, fmt.Errorf("payments: admin list products: %w", err)

backend/internal/payments/store_intake.go

@@ -413,6 +413,18 @@ func (s *Store) rewardConfig(ctx context.Context) (payout, dailyCap, hourlyCap i
 	return int(cfg.RewardedPayoutChips), int(cfg.RewardDailyCap), int(cfg.RewardHourlyCap), nil
 }
 
+// setRewardConfig updates the rewarded payout and the per-day and per-hour caps on the singleton
+// config row (no WHERE — the table holds exactly one row). Non-negativity is validated by the caller
+// and also enforced by the config CHECK constraints.
+func (s *Store) setRewardConfig(ctx context.Context, payout, dailyCap, hourlyCap int) error {
+	if _, err := s.db.ExecContext(ctx,
+		`UPDATE payments.config SET rewarded_payout_chips=$1, reward_daily_cap=$2, reward_hourly_cap=$3`,
+		payout, dailyCap, hourlyCap); err != nil {
+		return fmt.Errorf("payments: set reward config: %w", err)
+	}
+	return nil
+}
+
 // creditReward credits a rewarded-video view's chips to the funded segment, client-attested (VK Mini
 // App ads expose no server verify). It reads the payout and daily cap from config: a 0 payout
 // (unconfigured) or a reached cap credits nothing. It is idempotent on the client nonce (dedup on the

backend/internal/server/handlers.go

@@ -74,6 +74,9 @@ func (s *Server) registerRoutes() {
 		u.POST("/wallet/buy", s.handleWalletBuy)
 		// A rewarded-video credit (VK ads): client-attested + a config daily cap.
 		u.POST("/wallet/reward", s.handleWalletReward)
+		// The public-offer price list (§4.4) as markdown, for the render sidecar that serves the
+		// /offer/ page. Internal (off the edge allow-list); called by the renderer, not the gateway.
+		s.internal.GET("/offer/pricing", s.handleOfferPricing)
 	}
 	if s.payments != nil {
 		// The money order endpoint dispatches by rail (direct → Robokassa, vk → VK); an

backend/internal/server/handlers_admin_catalog.go

@@ -33,21 +33,45 @@ var priceFields = []struct {
 	{"price_chip", "", payments.CurrencyChip},
 }
 
-// consoleCatalog lists every product (active and archived) with its composition, prices, transacted
+// consoleCatalog lists the catalog products with their composition, prices, transacted flag, and the
-// flag, and the inline create form.
+// inline create form. It shows active products by default; ?all=1 also lists the archived ones (the
+// active/all toggle).
 func (s *Server) consoleCatalog(c *gin.Context) {
-	products, err := s.payments.AdminCatalog(c.Request.Context())
+	showAll := c.Query("all") == "1"
+	products, err := s.payments.AdminCatalog(c.Request.Context(), showAll)
 	if err != nil {
 		s.consoleError(c, err)
 		return
 	}
-	var view adminconsole.CatalogView
+	// Order the list like the public offer: sales (chip packs) first, then the chip-exchange values,
+	// grouped and price-sorted the same way, so the console mirrors what a buyer sees.
+	payments.SortAdminCatalog(products)
+	payout, daily, hourly, err := s.payments.RewardConfig(c.Request.Context())
+	if err != nil {
+		s.consoleError(c, err)
+		return
+	}
+	view := adminconsole.CatalogView{ShowAll: showAll, RewardPayout: payout, RewardDailyCap: daily, RewardHourlyCap: hourly}
 	for _, p := range products {
 		view.Products = append(view.Products, catalogRow(p))
 	}
 	s.renderConsole(c, "catalog", "catalog", "Catalog", view)
 }
 
+// consoleSetReward updates the rewarded-video config (chips per view plus the per-day and per-hour
+// caps) from the catalog page's rewarded-ads form. A blank field reads as 0; a negative value is
+// refused by the service.
+func (s *Server) consoleSetReward(c *gin.Context) {
+	payout, _ := strconv.Atoi(strings.TrimSpace(c.PostForm("reward_payout")))
+	daily, _ := strconv.Atoi(strings.TrimSpace(c.PostForm("reward_daily")))
+	hourly, _ := strconv.Atoi(strings.TrimSpace(c.PostForm("reward_hourly")))
+	if err := s.payments.SetRewardConfig(c.Request.Context(), payout, daily, hourly); err != nil {
+		s.renderConsoleMessage(c, "Update failed", err.Error(), catalogBack)
+		return
+	}
+	s.renderConsoleMessage(c, "Saved", "the rewarded-ads config was updated", catalogBack)
+}
+
 // catalogRow projects a product into its list row.
 func catalogRow(p payments.AdminProduct) adminconsole.ProductRow {
 	row := adminconsole.ProductRow{ID: p.ID.String(), Title: p.Title, Active: p.Active, Transacted: p.Transacted}
@@ -66,7 +90,7 @@ func (s *Server) consoleCatalogDetail(c *gin.Context) {
 	if !ok {
 		return
 	}
-	products, err := s.payments.AdminCatalog(c.Request.Context())
+	products, err := s.payments.AdminCatalog(c.Request.Context(), true) // include archived: the detail form edits any product
 	if err != nil {
 		s.consoleError(c, err)
 		return
@@ -239,7 +263,7 @@ func (s *Server) consoleGrantProduct(c *gin.Context) {
 // bundles, including archived ones — chips and tournament products are excluded).
 func (s *Server) grantForm(ctx context.Context) adminconsole.GrantFormView {
 	fv := adminconsole.GrantFormView{Present: true, Origins: []string{"direct", "vk", "telegram"}}
-	products, err := s.payments.AdminCatalog(ctx)
+	products, err := s.payments.AdminCatalog(ctx, true)
 	if err != nil {
 		return fv
 	}

backend/internal/server/handlers_admin_console.go

@@ -112,6 +112,7 @@ func (s *Server) registerConsole(router *gin.Engine) {
 	if s.payments != nil {
 		gm.GET("/catalog", s.consoleCatalog)
 		gm.POST("/catalog", s.consoleCreateProduct)
+		gm.POST("/catalog/reward", s.consoleSetReward)
 		gm.GET("/catalog/:id", s.consoleCatalogDetail)
 		gm.POST("/catalog/:id", s.consoleUpdateProduct)
 		gm.POST("/catalog/:id/archive", s.consoleArchiveProduct)

backend/internal/server/handlers_wallet.go

@@ -112,6 +112,22 @@ func (s *Server) handleWalletCatalog(c *gin.Context) {
 	c.JSON(http.StatusOK, catalogDTOFrom(view))
 }
 
+// handleOfferPricing serves the public-offer price list (§4.4) as markdown — the two catalog tables
+// projected from the active products. The render sidecar fetches it and splices it into the offer
+// markdown before rendering the /offer/ page. Internal, non-public: the /api/v1/internal group is
+// off the edge allow-list, and the value is served from the payments cache (no per-request query in
+// the steady state). Called by the renderer, not the gateway.
+func (s *Server) handleOfferPricing(c *gin.Context) {
+	md, err := s.payments.OfferPricing(c.Request.Context())
+	if err != nil {
+		s.log.Error("offer pricing projection failed", zap.Error(err))
+		c.String(http.StatusInternalServerError, "offer pricing unavailable")
+		return
+	}
+	c.Header("Content-Type", "text/markdown; charset=utf-8")
+	c.String(http.StatusOK, md)
+}
+
 // handleWallet returns the caller's wallet — the segments and benefits visible in the current
 // trusted execution context, plus the rewarded-video payout available here (0 outside VK or when
 // unconfigured), which gates the client's "watch for chips" button.

deploy/.env.example

@@ -86,7 +86,7 @@ GM_BASICAUTH_HASH=                     # required; `caddy hash-password` bcrypt
 
 # --- UI build args (baked into the gateway image) ---------------------------
 VITE_TELEGRAM_BOT_ID=
-VITE_TELEGRAM_LINK=                                 # friend-invite Mini App link (full URL, e.g. https://t.me/<bot>/<app>)
+VITE_TELEGRAM_LINK=                                 # friend-invite Mini App link (full URL, e.g. https://telegram.me/<bot>/<app>)
 VITE_TELEGRAM_GAME_CHANNEL_NAME=                    # landing "Play in Telegram" link, the bot's game channel
 VITE_VK_APP_LINK=                                   # landing "Play on VK" link (full URL, https://vk.com/app<id>)
 VITE_VK_APP_ID=                                     # VK ID "Web" app id (client_id) for VK web-login linking; also the gateway's GATEWAY_VK_ID_APP_ID
@@ -115,6 +115,13 @@ TELEGRAM_MINIAPP_URL=                  # required; deploy derives it as PUBLIC_B
 TELEGRAM_TEST_ENV=false
 TELEGRAM_API_BASE_URL=
 
+# --- Client-version gate (ARCHITECTURE.md §2) -------------------------------
+# The hard minimum + the soft recommended client build. Empty ⇒ dormant. Plain (unprefixed) Gitea
+# variables, shared across contours; in the test contour the stamped client version is a commit hash
+# (unparseable ⇒ fail-open), so these only enforce on real semver prod builds. Recommended must be ≥ min.
+GATEWAY_MIN_CLIENT_VERSION=
+GATEWAY_RECOMMENDED_CLIENT_VERSION=
+
 # --- VK Mini App ------------------------------------------------------------
 # The VK app's "protected key" (client_secret): the gateway verifies the Mini App
 # launch-parameter signature in-process under it (a pure offline HMAC, no VK API call).

deploy/README.md

@@ -107,14 +107,19 @@ without it Docker's resolver handles `otelcol`, `gateway` and `api.telegram.org`
 | `TELEGRAM_TEST_ENV` | _pinned_ | `false` | `true` routes the bot through Telegram's test environment (`.../bot<token>/test/METHOD`). **The CI test contour pins this to `true` in `ci.yaml`** (the contour is the test environment) — it is not a Gitea variable. Set it in `.env` for a local run; prod leaves it `false`. |
 | `TELEGRAM_API_BASE_URL` | variable | _(empty)_ | Override the Bot API host (a mock/self-hosted server); empty = `https://api.telegram.org`. |
 | `VITE_TELEGRAM_BOT_ID` | variable | _(empty)_ | UI build-arg: numeric bot id for the web Login Widget. |
-| `VITE_TELEGRAM_LINK` | variable | _(empty)_ | UI build-arg: friend-invite Mini App link (full URL, `https://t.me/<bot>/<app>` — `<app>` is the Mini App short name from BotFather). |
+| `VITE_TELEGRAM_LINK` | variable | _(empty)_ | UI build-arg: friend-invite Mini App link (full URL, `https://telegram.me/<bot>/<app>` — `<app>` is the Mini App short name from BotFather). |
-| `VITE_TELEGRAM_GAME_CHANNEL_NAME` | variable | _(empty)_ | UI build-arg: the landing "Play in Telegram" link, the bot's game channel (e.g. `https://t.me/Erudit_Game`). |
+| `VITE_TELEGRAM_GAME_CHANNEL_NAME` | variable | _(empty)_ | UI build-arg: the landing "Play in Telegram" link, the bot's game channel (e.g. `https://telegram.me/Erudit_Game`). |
 | `VITE_VK_APP_LINK` | variable (shared) | _(empty)_ | UI build-arg: the landing "Play on VK" link, the VK Mini App (full URL, `https://vk.com/app<id>`). One VK Mini App for all contours. |
 | `VITE_VK_APP_ID` | variable (shared) | _(empty)_ | VK ID "Web" app id (`client_id`) for VK web-login linking. Baked into the SPA authorize URL and reused as the gateway's `GATEWAY_VK_ID_APP_ID`. Empty disables the `link.vk.*` ops. One VK ID "Web" app for all contours. |
 | `VITE_VK_ID_REDIRECT_URL` | derived | _(empty)_ | VK ID trusted redirect URL — must match the app's registered redirect exactly. The deploy derives `PUBLIC_BASE_URL + /app/` (used by the SPA and as the gateway's exchange `redirect_uri`); set it only for a local run. |
 | `GATEWAY_VK_APP_SECRET` | secret (shared) | _(empty)_ | The VK Mini App's protected key (`client_secret`): the gateway verifies the launch-parameter signature in-process under it (offline HMAC, no VK API call). Empty disables the VK auth path (`auth.vk`). One VK Mini App for all contours. |
 | `GATEWAY_VK_ID_CLIENT_SECRET` | secret (shared) | _(empty)_ | The VK ID "Web" app's protected key (`client_secret`) for the gateway's server-side confidential code exchange. A SEPARATE VK app from `GATEWAY_VK_APP_SECRET` (the Mini App). One VK ID "Web" app for all contours. |
 | `GATEWAY_HONEYTOKEN` | secret | _(empty)_ | Planted honeytoken bearer value: presenting it earns a 24h IP ban + a high-severity alarm where the IP ban is on (prod), or logs + a `gateway_abuse_banned_total{reason="honeytoken"}` metric (test, ban off). Plant the value somewhere an attacker would find it; empty disables the trap. Per-contour `TEST_`/`PROD_GATEWAY_HONEYTOKEN`. |
+| `GATEWAY_BLOCKLIST_ENABLED` | variable | `false` | Enable the community IP blocklist at the edge (prod-only, same real-client-IP reason as the ban). Requires `GATEWAY_BLOCKLIST_URL`. Opt-in via `PROD_GATEWAY_BLOCKLIST_ENABLED` after verifying the feed. |
+| `GATEWAY_BLOCKLIST_URL` | variable | _(empty)_ | The curated CIDR feed to fetch (Spamhaus DROP). Required when enabled; refreshed every few hours and dropped fail-open once stale (48h). `PROD_GATEWAY_BLOCKLIST_URL`. |
+| `GATEWAY_BLOCKLIST_ALLOW` | variable | _(empty)_ | Comma-separated never-block set (CIDRs / bare IPs — own infra, monitoring) the feed can never block. `PROD_GATEWAY_BLOCKLIST_ALLOW`. |
+| `GATEWAY_MIN_CLIENT_VERSION` | variable | _(empty)_ | **Hard** tier of the client-version gate (ARCHITECTURE.md §2). Minimum client build the gateway will serve. Empty ⇒ **dormant** (every build served, the web default). Set it to the release `vMAJOR.MINOR.PATCH` in the **same** rollout that ships an incompatible wire change, so an older bundled APK is turned away with an *update required* signal instead of failing blind — the client then degrades to an offline "Update / Play offline" notice, not a hard lockout. Validated at load; a non-empty unparseable value fails startup. |
+| `GATEWAY_RECOMMENDED_CLIENT_VERSION` | variable | _(empty)_ | **Soft** tier of the client-version gate (ARCHITECTURE.md §2). A build at or above `GATEWAY_MIN_CLIENT_VERSION` but **below** this is served normally, but every gated `Execute` response carries an additive `X-Update-Recommended: 1` header ⇒ the client shows a dismissable *update available* nudge (play continues). Empty ⇒ off. Validated at load: unparseable, or **below** `GATEWAY_MIN_CLIENT_VERSION`, fails startup. Bump it (ahead of `MIN`) to nudge upgrades before a hard cut-over. |
 | `VITE_GATEWAY_URL` | variable | _(empty)_ | UI build-arg: gateway origin; empty = same-origin (the usual single-origin deploy). |
 | `SMTP_RELAY_HOST` | variable (shared) | _(empty)_ | Selectel SMTP relay host for confirm-code email. Empty leaves the backend on the log mailer (email disabled) — the contour still boots. One relay for every contour (limit 100 msgs / 5 min). |
 | `SMTP_RELAY_PORT` | variable (shared) | `465` | Relay port. No client certificate is needed (the server cert is validated against the system roots). |
@@ -233,6 +238,32 @@ redeploy the matching old tag. This dump is a belt-and-braces net for a bad migr
 **point-in-time recovery** (below) is the primary recovery path once armed, and the only one
 that survives losing the host.
 
+## Android app build & release (RuStore)
+
+The standalone Android app is built by a **manual** workflow, never automatically, and is separate from the
+web/prod rollout — a signed APK uploaded to RuStore by hand. The build/release runbook follows.
+
+- **Trigger:** `Actions → android-build → Run workflow` from **`master`**, input `confirm=build` (mirrors
+  `prod-deploy`). **Tag the release first** (`git tag vX.Y.Z` on `master`) — the workflow refuses anything
+  but a clean `vMAJOR.MINOR.PATCH` and derives `versionCode = MA*1_000_000 + MI*1_000 + PA`,
+  `versionName = MA.MI.PA`. Watch it green with `python3 ~/.claude/bin/gitea-ci-watch.py`.
+- **Output:** a `release APK` run artifact — **signed** when the signing secrets are present, an
+  **unsigned** release APK otherwise (a dry run still proves the pipeline).
+- **Runner (host-executor):** JDK 21 comes from `setup-java`; the **Android SDK is host-provisioned** —
+  install it once (`sdkmanager 'platform-tools' 'platforms;android-36' 'build-tools;36.0.0'`) and grant the
+  `runner` user read+exec (`sudo chmod -R a+rX /opt/android-sdk`). Override the path with the
+  `ANDROID_SDK_DIR` variable. The workflow's `Verify the host Android SDK` step fails fast with the fix if
+  the SDK is missing or unreadable.
+- **Release keystore** (create once, **back up off-host** — losing it means the app can never be updated):
+  `keytool -genkeypair -v -keystore erudit-release.jks -alias erudit -keyalg RSA -keysize 4096 -validity 10000`,
+  then set the Gitea **secrets** `ANDROID_KEYSTORE_BASE64` (`base64 -w0 erudit-release.jks`),
+  `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS`, `ANDROID_KEY_PASSWORD`. Set the `ANDROID_RUSTORE_URL`
+  variable to the store listing once published (empty until then — the in-app update button no-ops).
+- **Wire-break discipline:** the prod deploy that ships an incompatible wire change **also** bumps
+  `GATEWAY_MIN_CLIENT_VERSION` to that release (see Optional variables), so an old installed APK is turned
+  away cleanly instead of failing blind.
+- **Upload:** download the artifact and upload it to RuStore by hand (no automated RuStore-API upload in the MVP).
+
 ## Point-in-time recovery (PITR)
 
 The main host archives Postgres continuously with **pgBackRest** to **Selectel S3**

deploy/caddy/Caddyfile

@@ -107,6 +107,16 @@
 		}
 	}
 
+	# The public legal pages are rendered by the render sidecar: the offer (with the live catalog
+	# price list from the backend spliced into ui/legal/offer_ru.md), the privacy policy and the EULA
+	# (both static markdown). Only these paths are exposed here — the sidecar's /render stays off this
+	# allow-list, internal-only. Kept disjoint from the landing/app paths so the catch-all below never
+	# shadows them.
+	@legal path /offer /offer/* /privacy /privacy/* /eula /eula/*
+	handle @legal {
+		reverse_proxy renderer:8090
+	}
+
 	# Everything else — the public landing at / and any stray path — is static.
 	handle {
 		reverse_proxy landing:80

deploy/docker-compose.bot.yml

@@ -3,8 +3,10 @@
 #   docker compose -f docker-compose.bot.yml up -d
 #
 # The bot egresses to the Bot API directly (no VPN sidecar) and dials the main host's
-# published bot-link :9443 over mTLS. It exports no telemetry — otelcol lives on the
+# published bot-link :9443 over mTLS. It exports no OTLP telemetry — otelcol lives on the
-# main host and is unreachable from here — so observe it via `docker logs` on this host.
+# main host and is unreachable from here — but it reports its Bot API health up the bot-link,
+# which the gateway turns into metrics + alerts on the main host (docs/ARCHITECTURE.md); `docker
+# logs` on this host is the local detail view.
 # Values come from the prod-deploy workflow (PROD_ secrets/variables); BOT_IMAGE is the
 # pushed registry tag and BOTLINK_GATEWAY_ADDR is the main host's <ip>:9443.
 name: scrabble-bot
@@ -50,7 +52,8 @@ services:
       TELEGRAM_BOTLINK_TLS_CA: /certs/ca.crt
       TELEGRAM_LOG_LEVEL: ${LOG_LEVEL:-info}
       TELEGRAM_SERVICE_NAME: scrabble-telegram-bot
-      # No telemetry export: otelcol is on the main host, unreachable from here.
+      # No OTLP export: otelcol is on the main host, unreachable from here. Bot API health rides the
+      # bot-link instead (the gateway exposes it as metrics); see docs/ARCHITECTURE.md.
       TELEGRAM_OTEL_TRACES_EXPORTER: none
       TELEGRAM_OTEL_METRICS_EXPORTER: none
       GOMAXPROCS: "1"

deploy/docker-compose.yml

@@ -84,6 +84,9 @@ services:
     logging: *default-logging
     environment:
       RENDERER_PORT: "8090"
+      # The offer page (GET /offer/) fetches the live catalog price list from the backend's internal
+      # endpoint and splices it into the committed offer markdown. Backend down ⇒ /offer/ returns 502.
+      RENDERER_BACKEND_URL: http://backend:8080
     healthcheck:
       test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8090/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
       interval: 10s
@@ -219,6 +222,12 @@ services:
       GATEWAY_HTTP_ADDR: ":8081"
       GATEWAY_BACKEND_HTTP_URL: http://backend:8080
       GATEWAY_BACKEND_GRPC_ADDR: backend:9090
+      # Client-version gate (ARCHITECTURE.md §2): the hard minimum + the soft recommended client build.
+      # Empty ⇒ dormant. Plain (unprefixed) — the same value serves every contour; in the test contour
+      # the stamped client version is a commit hash (unparseable ⇒ fail-open), so the gate only bites
+      # real semver builds in prod. Validated at gateway start (recommended must be ≥ min).
+      GATEWAY_MIN_CLIENT_VERSION: ${GATEWAY_MIN_CLIENT_VERSION:-}
+      GATEWAY_RECOMMENDED_CLIENT_VERSION: ${GATEWAY_RECOMMENDED_CLIENT_VERSION:-}
       # Telegram auth validates against the home validator (plaintext, internal).
       GATEWAY_VALIDATOR_ADDR: validator:9091
       # VK Mini App auth verifies the launch-parameter signature in-process under the VK
@@ -251,6 +260,12 @@ services:
       # secret; empty (unset secret) leaves the trap off.
       GATEWAY_ABUSE_BAN_ENABLED: ${GATEWAY_ABUSE_BAN_ENABLED:-false}
       GATEWAY_HONEYTOKEN: ${GATEWAY_HONEYTOKEN:-}
+      # Community IP blocklist (Spamhaus DROP): prod-only, off unless the real client IP is visible
+      # (the shared-NAT test contour would self-block). Enabled + fed the feed URL + allowlist by the
+      # prod deploy (write-prod-env.sh); the refresh/staleness windows use the built-in defaults.
+      GATEWAY_BLOCKLIST_ENABLED: ${GATEWAY_BLOCKLIST_ENABLED:-false}
+      GATEWAY_BLOCKLIST_URL: ${GATEWAY_BLOCKLIST_URL:-}
+      GATEWAY_BLOCKLIST_ALLOW: ${GATEWAY_BLOCKLIST_ALLOW:-}
       GATEWAY_LOG_LEVEL: ${LOG_LEVEL:-info}
       GATEWAY_SERVICE_NAME: scrabble-gateway
       GATEWAY_OTEL_TRACES_EXPORTER: otlp

deploy/grafana/dashboards/bot.json

@@ -0,0 +1,45 @@
+{
+  "uid": "scrabble-bot",
+  "title": "Scrabble — Telegram bot",
+  "tags": ["scrabble"],
+  "timezone": "",
+  "schemaVersion": 39,
+  "version": 1,
+  "refresh": "30s",
+  "time": { "from": "now-6h", "to": "now" },
+  "panels": [
+    {
+      "type": "stat",
+      "title": "Bot connected",
+      "description": "botlink_connected_bots: bots currently holding the gateway bot-link (1 = healthy).",
+      "gridPos": { "h": 5, "w": 6, "x": 0, "y": 0 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(botlink_connected_bots)" }]
+    },
+    {
+      "type": "stat",
+      "title": "Last Bot API OK (age)",
+      "description": "Seconds since the bot's most recent successful Bot API call. Grows unbounded if the bot wedges.",
+      "gridPos": { "h": 5, "w": 6, "x": 6, "y": 0 },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "time() - max(bot_tg_last_ok_unix)" }]
+    },
+    {
+      "type": "timeseries",
+      "title": "Bot API errors/s by kind",
+      "description": "bot_tg_errors_total by kind: connect (getUpdates), api (other sends), rate_limited (429). 429 should stay ~0.",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "sum by (kind) (rate(bot_tg_errors_total[5m]))", "legendFormat": "{{kind}}" }]
+    },
+    {
+      "type": "timeseries",
+      "title": "Bot-link commands/s by result",
+      "description": "botlink_commands_total by result: delivered / not_delivered / dropped / error. Sustained not_delivered or error means gateway sends are failing to reach Telegram.",
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 5 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "sum by (result) (rate(botlink_commands_total[5m]))", "legendFormat": "{{result}}" }]
+    }
+  ]
+}

deploy/grafana/dashboards/service-overview.json

@@ -53,6 +53,31 @@
       "fieldConfig": { "defaults": { "unit": "bytes" }, "overrides": [] },
       "datasource": { "type": "prometheus", "uid": "prometheus" },
       "targets": [{ "refId": "A", "expr": "sum(go_memory_used) by (service_name)", "legendFormat": "{{service_name}}" }]
+    },
+    {
+      "type": "stat",
+      "title": "Blocklist entries",
+      "description": "CIDR ranges in the active community IP blocklist feed (0 when disabled or not yet fetched).",
+      "gridPos": { "h": 5, "w": 6, "x": 0, "y": 13 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(gateway_blocklist_entries)" }]
+    },
+    {
+      "type": "stat",
+      "title": "Blocklist feed age",
+      "description": "Seconds since the community IP blocklist feed was last successfully fetched. Grows if the fetch is failing; the feed is dropped fail-open once stale.",
+      "gridPos": { "h": 5, "w": 6, "x": 6, "y": 13 },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(gateway_blocklist_age_seconds)" }]
+    },
+    {
+      "type": "timeseries",
+      "title": "Blocklist blocks/s",
+      "description": "Requests refused at the edge by the community IP blocklist (gateway_blocklist_blocked_total).",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 13 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "sum(rate(gateway_blocklist_blocked_total[5m]))" }]
     }
   ]
 }

deploy/grafana/provisioning/alerting/rules.yaml

@@ -108,6 +108,32 @@ groups:
         labels: { severity: critical }
         annotations: { summary: 'Edge TLS cert has under 20 days left — Caddy ACME renewal may have failed.' }
 
+      # The community IP blocklist feed has not refreshed in over a day (the gateway re-fetches every
+      # few hours). Absent/NaN-safe: the age gauge appears only once a feed has loaded, so a disabled
+      # or never-fetched blocklist stays quiet. The feed itself is dropped (fail-open) at its
+      # max-staleness window; this warns well before that so the operator can fix the fetch.
+      - uid: blocklist_stale
+        title: IP blocklist feed not refreshing
+        condition: C
+        for: 15m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 300, to: 0 }
+            datasourceUid: prometheus
+            model: { refId: A, expr: gateway_blocklist_age_seconds, instant: true }
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: gt, params: [86400] }
+        labels: { severity: warning }
+        annotations: { summary: 'The community IP blocklist feed has not refreshed in over 24h — the fetch is failing; it will be dropped (fail-open) once stale. Check the gateway blocklist refresher logs and the feed URL.' }
+
   - orgId: 1
     name: scrabble-host
     folder: Alerts
@@ -277,3 +303,91 @@ groups:
                 - evaluator: { type: gt, params: [1800] }
         labels: { severity: critical }
         annotations: { summary: 'No WAL archived for over 30 minutes while pg_wal keeps growing — archiving is genuinely stalled; the PITR recovery point is frozen and pg_wal will fill the disk. Run `docker exec scrabble-postgres pgbackrest --stanza=scrabble --pg1-user=scrabble check`.' }
+
+  # Remote Telegram bot health. The bot runs on its own host and exports no telemetry of its own; the
+  # gateway observes it through the bot-link (botlink_connected_bots) and the health it reports over
+  # that stream (bot_tg_*). All absent/NaN-safe: before a bot ever connects the metrics are absent, so
+  # noDataState OK keeps them quiet on a fresh contour. The alert email does NOT go through the bot, so
+  # a bot-down alert is deliverable.
+  - orgId: 1
+    name: scrabble-bot
+    folder: Alerts
+    interval: 1m
+    rules:
+      - uid: bot_disconnected
+        title: Telegram bot disconnected
+        condition: C
+        for: 5m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 300, to: 0 }
+            datasourceUid: prometheus
+            model: { refId: A, expr: botlink_connected_bots, instant: true }
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: lt, params: [1] }
+        labels: { severity: critical }
+        annotations: { summary: 'No Telegram bot is connected to the gateway bot-link — out-of-app push and admin sends are down. Check the bot host.' }
+
+      # Positive liveness: a bot is connected but its last successful Bot API call is over 5 minutes
+      # old — the getUpdates long-poll returns every ~minute even when idle, so a stale stamp means the
+      # bot is wedged (no errors, no traffic). Guarded by "and connected" so a mere disconnect (owned by
+      # bot_disconnected) does not double-fire.
+      - uid: bot_tg_stale
+        title: Telegram bot not reaching the Bot API
+        condition: C
+        for: 5m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 600, to: 0 }
+            datasourceUid: prometheus
+            model:
+              refId: A
+              expr: (time() - bot_tg_last_ok_unix) and on() (botlink_connected_bots >= 1)
+              instant: true
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: gt, params: [300] }
+        labels: { severity: critical }
+        annotations: { summary: 'A connected Telegram bot has not reached the Bot API in over 5 minutes — the update poll is wedged. Check the bot host and Telegram reachability.' }
+
+      # 429s should be ~never once the bot honours Retry-After; any sustained rate-limiting is a symptom
+      # (a send loop, a misbehaving path) worth investigating.
+      - uid: bot_tg_rate_limited
+        title: Telegram bot rate-limited (429)
+        condition: C
+        for: 5m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 900, to: 0 }
+            datasourceUid: prometheus
+            model:
+              refId: A
+              expr: increase(bot_tg_errors_total{kind="rate_limited"}[15m])
+              instant: true
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: gt, params: [0] }
+        labels: { severity: warning }
+        annotations: { summary: 'The Telegram bot is being rate-limited (HTTP 429). It should honour Retry-After, so sustained 429s point to a send loop or a hot path.' }

deploy/landing/Caddyfile

@@ -18,18 +18,9 @@
 	@shell not path /assets/*
 	header @shell Cache-Control "no-cache"
 
-	# The static public offer page, rendered from ui/legal/offer_ru.md at build
+	# The public offer page (/offer/) is no longer served here: the contour caddy routes it to the
-	# time into dist/offer/index.html (vite emit-offer plugin). Served with its own
+	# render sidecar, which splices the live catalog price list into ui/legal/offer_ru.md. This
-	# index so /offer/ resolves to /srv/offer/index.html rather than falling to the
+	# container never sees /offer/, so it carries no offer assets (the vite emit-offer plugin is gone).
-	# landing shell below (whose index is landing.html). A bare /offer redirects in.
-	handle /offer {
-		redir * /offer/ permanent
-	}
-	handle /offer/* {
-		file_server {
-			index index.html
-		}
-	}
 
 	# An unknown path falls back to the landing shell (the gateway's old "/"
 	# behaviour); "/" itself resolves through the index below.

deploy/write-prod-env.sh

@@ -49,6 +49,8 @@ export CADDY_SITE_ADDRESS='$CADDY_SITE_ADDRESS'
 export LOG_LEVEL='${LOG_LEVEL:-info}'
 export DICT_VERSION='$DICT_VERSION'
 export APP_VERSION='$APP_VERSION'
+export GATEWAY_MIN_CLIENT_VERSION='$GATEWAY_MIN_CLIENT_VERSION'
+export GATEWAY_RECOMMENDED_CLIENT_VERSION='$GATEWAY_RECOMMENDED_CLIENT_VERSION'
 export TELEGRAM_BOT_TOKEN='$TELEGRAM_BOT_TOKEN'
 export TELEGRAM_MINIAPP_URL='$TELEGRAM_MINIAPP_URL'
 export GATEWAY_VK_APP_SECRET='$GATEWAY_VK_APP_SECRET'
@@ -77,6 +79,11 @@ export GF_SMTP_ENABLED='$GF_SMTP_ENABLED'
 export PUBLIC_BASE_URL='$PUBLIC_BASE_URL'
 export GATEWAY_HONEYTOKEN='$GATEWAY_HONEYTOKEN'
 export GATEWAY_ABUSE_BAN_ENABLED='true'
+# Community IP blocklist (Spamhaus DROP): opt-in — the operator enables it and sets the feed URL +
+# allowlist via PROD_GATEWAY_BLOCKLIST_* vars once the feed is verified. Unset ⇒ off (safe).
+export GATEWAY_BLOCKLIST_ENABLED='${GATEWAY_BLOCKLIST_ENABLED:-false}'
+export GATEWAY_BLOCKLIST_URL='$GATEWAY_BLOCKLIST_URL'
+export GATEWAY_BLOCKLIST_ALLOW='$GATEWAY_BLOCKLIST_ALLOW'
 # Continuous WAL archiving (pgBackRest -> S3) for point-in-time recovery. The artifact
 # ships disarmed: PGBACKREST_ARCHIVE_MODE defaults off, so archiving stays inert until the
 # operator sets the S3 repository values + secrets, creates the stanza and flips the switch

docs/ARCHITECTURE.md

@@ -100,15 +100,35 @@ dropped). Horizontal scaling is explicit future work.
   auth operations are unauthenticated and return the minted token. A unary
   operation's domain outcome rides back in `ExecuteResponse.result_code` (HTTP
   200); only edge failures (rate limit, missing session, unknown type, internal)
-  surface as Connect error codes. The client treats a connectivity edge failure as
+  surface as Connect error codes. The client treats connectivity as **state, not a per-call toast**,
-  **state, not a per-call toast**: a transport `unavailable` or a `rate_limited` flips a global
+  via a single **net-state machine** — a pure reducer (`ui/src/lib/netstate.ts`) behind a reactive
-  `online` signal that drives a header **"Connecting…"** spinner and softly disables proactive
+  store (`netstate.svelte.ts`); `connection`/`offline` are thin derived shims over it. It has four
-  actions, and the transport **auto-retries with capped exponential backoff** — every op on a
+  states: `online`; `connecting` (a call or probe is failing but still inside the anti-flap window —
-  rate-limit (the gateway rejected it before processing, so it is safe), but only **read-only**
+  the header **"Connecting…"** spinner, chrome stays online); `offlineNoNetwork` (sustained loss — blue
-  ops on `unavailable` (a mutation is never blindly re-sent, to avoid double-applying one whose
+  chrome, a local-only lobby, the transport **kill switch**); and `offlineVersionLocked` (the gateway is
-  response was lost — its button is disabled while offline and the player re-issues it on
+  reachable but the build is below the hard minimum — the *update* notice, the client-version gate below). **Offline is
-  reconnect). A reachability watcher (a lightweight `profile.get` probe) clears the signal when no
+  implicit** — detected from failed calls, a reachability probe, a **live-stream heartbeat watchdog**
-  other traffic is in flight; the live `Subscribe` stream's drop/recovery feeds the same signal.
+  (a silence past ~25 s of the gateway's 10 s keep-alive `heartbeat` means a silently-dead stream — e.g.
+  the radio was cut with no stream error; `ui/src/lib/streamwatchdog.ts`, background-aware) and the OS hint
+  (`navigator` / `@capacitor/network`), **never a user toggle** — with **hysteresis** so a brief blip lives entirely in
+  `connecting` (K consecutive probe failures *or* a debounce window trips `offlineNoNetwork`; the first
+  probe/call success heals back, with a toast). The transport **auto-retries with capped exponential
+  backoff** — every op on a rate-limit (the gateway rejected it before processing, so it is safe), but
+  only **read-only** ops on `unavailable` (a mutation is never blindly re-sent, to avoid double-applying
+  one whose response was lost — its button is disabled while offline and re-issued on reconnect). A
+  reachability watcher (a lightweight `profile.get` probe; a session-less native guest reconciles a
+  server guest instead — that reconcile IS the probe) drives recovery, and the live `Subscribe` stream's
+  drop/recovery feeds the same machine. **Telegram/VK are exempt from the offline-*play* model** —
+  `offlineMode.active` is hard-gated on `offlineCapable()` (false in those mini-apps), so nothing — not
+  even a version lock — puts them in offline mode: no blue chrome, no local lobby, no transport kill
+  switch and no device-local create paths. The machine still tracks reachability there, though: a
+  connection lost **inside an online game** is surfaced on **every platform**, driven off the machine's
+  confirmed-offline state (`netState.offline`, not `offlineMode.active`) — the game screen shows a
+  *connection lost* banner, **freezes** the tray and move controls, and hides the resign, add-friend/block
+  and chat/dictionary controls (a started move stays a draft, re-committed by the player on reconnect), and
+  the word-check tool falls back to the game's pinned on-device dictionary (`ui/src/lib/dict/check.ts`,
+  exact when that dawg is cached, else *unavailable*) with its network-only complaint and external
+  look-up hidden.
   **Edge hardening:** every request body on the public listener is capped at
   `GATEWAY_MAX_BODY_BYTES` (default 1 MiB — far above any legitimate payload), both at the HTTP
   layer (`http.MaxBytesReader`) and as the Connect per-message read limit, so an oversized
@@ -140,6 +160,40 @@ dropped). Horizontal scaling is explicit future work.
   (your-turn, opponent-moved, chat, nudge). The gateway bridges them to the
   client's in-app stream while the app is open. Out-of-app delivery uses
   platform-native push via the platform side-service.
+- **Client-version gate — two tiers** (native long-tail protection): a bundled native install (§13) can be
+  arbitrarily old, so the client stamps its build into an **`X-Client-Version`** request header (the app
+  version from `pkg/version` / `__APP_VERSION__`), read by the gateway **before it decodes the FlatBuffers
+  payload**. The version rides the **outermost stable layer** — an HTTP header, never the FBS payload —
+  because protobuf envelopes and headers are version-tolerant by design while the FBS payload is the layer
+  that breaks. Enforcement is **per-call, not a Hello RPC** (`Execute`/`Subscribe` check it at the top,
+  before registry lookup / auth / decode), so the first online call is already gated. Both tiers **fail
+  open** (an absent or unparseable header passes) and are **dormant** until deliberately configured (both
+  vars empty ⇒ off, web behaviour unchanged).
+  - **Hard (critical) — `GATEWAY_MIN_CLIENT_VERSION`**: `version < min` ⇒ the domain envelope
+    `result_code = "update_required"` (HTTP 200) on `Execute` and `CodeFailedPrecondition` on `Subscribe`;
+    the client makes **zero** successful requests. Its reaction is **graceful, not terminal**: it enters
+    `offlineVersionLocked` (offline mode) and shows a **dismissable notice** — **"Update"** (native → the
+    store listing `VITE_RUSTORE_URL`, web → reload) or **"Play offline"** (dismiss → keep playing local
+    vs_ai / hotseat). The lock is sticky until an actual update on the next launch.
+  - **Soft (recommended) — `GATEWAY_RECOMMENDED_CLIENT_VERSION`**: `min ≤ version < recommended` ⇒ the
+    gateway sets an **additive** `X-Update-Recommended: 1` **response header** on the served `Execute`
+    response (the call still succeeds); a transport interceptor turns it into a **dismissable "update
+    available" nudge** in the lobby — play continues, nothing blocks. `recommended` must be **≥ `min`**
+    (validated at config load); empty ⇒ the soft tier is off.
+- **Frozen wire contract** (so any build, however old, can always recognise "update required"): three
+  things are permanent — (1) the protobuf envelope field numbers in `edge.proto` are never renumbered or
+  reused; (2) the `update_required` sentinel — the `result_code` string **and** the `FailedPrecondition`
+  code — never changes; (3) the FBS schema stays **additive** (append trailing fields; `(deprecated)`, never
+  delete — deleting shifts field IDs and breaks older readers). A breaking wire change happens only *inside*
+  the FBS payload, which is exactly what the gate guards. **Deploy discipline:** the production rollout that
+  ships an incompatible wire change **also** bumps `GATEWAY_MIN_CLIENT_VERSION` to that release, in the same
+  rollout (see [`../deploy/README.md`](../deploy/README.md)).
+- **Gate × offline** (UX rule): offline is the net-state machine's `offlineNoNetwork` / `offlineVersionLocked`
+  (implicit — no toggle) and its kill switch refuses calls, so the hard gate never fires *while already
+  offline* — an old install always plays local vs_ai / hotseat. A hard `update_required` on a
+  **user-initiated online call** degrades to `offlineVersionLocked` + the dismissable notice (above); the
+  silent background guest reconciliation (§3) **swallows** an `update_required` and stays a local guest
+  rather than interrupting local play.
 
 ## 3. Authentication & sessions
 
@@ -224,6 +278,19 @@ arrive from a platform rather than completing a mandatory registration).
   `BACKEND_GUEST_REAP_INTERVAL` sweep, so transient guest rows do not accumulate.
   Platform and email users are auto-provisioned **durable** accounts with an
   identity.
+- **Local guest vs. server guest** (native offline-first, §13). The **native** app splits the local-play
+  identity from the server account. A **local guest** is device-local with **no DB row**: a device-generated
+  id + the localized default name (*Guest* / *Гость*) persisted on the device, existing from the very first
+  launch with no network. It fills the human seat in a local vs_ai game and is the "you" for device-local
+  games; a purely-offline user never consumes a server row. The **server guest** is the durable `is_guest`
+  row above — minted **lazily** via `auth.guest` the first time the app reaches the network, its session
+  cached and reused (exactly one per device, guarded by the cached session so it never double-mints). It
+  unlocks online features (matchmaking, friends). **Reconciliation:** on gaining network with no server
+  session the native app silently `auth.guest`s in the background and adopts it — best-effort, swallowing an
+  `update_required` to stay a local guest rather than interrupting play (the gate × offline rule, §2).
+  **Local games stay device-only** (both local vs_ai and hotseat persist only on the device); an identity
+  transition never migrates them. Web/PWA/Telegram/VK are unchanged — they have no local guest and keep the
+  prior online-session rule.
 
 > **Decision (2026-06-20) — single bot, preference-based variant gating.** The former
 > two-bot model (one bot per service language, with `accounts.service_language`, a
@@ -909,6 +976,26 @@ finished journal on each GET. The only degraded platform is a legacy Telegram cl
 predating `downloadFile`, where the GCG falls back to the old clipboard copy and the
 image option is not offered.
 
+The same sidecar also serves the **public legal pages** — the offer at `/offer/`, the privacy
+policy at `/privacy/` and the EULA at `/eula/` — the edge-exposed routes on it (caddy routes them
+here; its `/render` stays internal). All three reuse the shared `ui/src/lib/offer.ts`
+`renderLegalHtml` (one renderer, no drift) over their owner-edited `ui/legal/*_{ru,en}.md` — each is
+**bilingual (RU + EN)** with a client-side language + theme switcher (default Russian, persisted;
+the offer's EN view transliterates the Russian product names) — baked into the image. `/privacy/`
+and `/eula/` are static; the offer additionally splices in the **live price list** (§4.4) into both
+languages: it
+fetches the two catalog tables as markdown from the backend's internal
+`/api/v1/internal/offer/pricing` at the `<#pricing_template#>` marker, then renders the page. The
+backend projects the tables from the active catalog through `payments.Money` (no float reaches the
+page) and caches them in memory — built at boot, reprojected on any catalog edit — so a served
+render issues no query in the steady state and the page always reflects the current catalog without
+a redeploy. A backend outage degrades `/offer/` to a 502 rather than a stale price list. Packs are
+ordered by ascending rouble price; values are grouped by what they grant — hints only, then no-ads
+only, then no-ads + hints, then (reserved, empty today) products carrying the **tournament** atom,
+which becomes a fourth group once the tournament economy makes them sellable — and ordered by
+ascending chip price within each group. Product titles are admin input, so the projection escapes
+them (HTML entities + markdown metacharacters) before they reach the un-sanitised renderer.
+
 The alphabet-on-the-wire transport does **not** touch this invariant: the live edge
 exchanges alphabet indices, but the persisted journal (and everything derived from it —
 replay, history, GCG) keeps the decoded concrete letters described above, so an archived
@@ -999,6 +1086,20 @@ answering `/start` with a URL button into the **main** bot's Mini App (`?startap
 button would sign initData with the promo token); it is self-contained — no bot-link, no gateway.
 Session-revocation events and cursor-based stream resume stay deferred (single-instance MVP).
 
+Because the bot **exports no telemetry of its own** (the OTel collector is on the main host,
+unreachable from the bot host), it reports its **Bot API health** up the same stream: a periodic
+`Health` message (`platform/telegram/internal/health`) carries delta counts of connect failures (the
+getUpdates long-poll), other API errors and 429s, plus the wall-clock second of its last successful
+Bot API call. The bot observes these **centrally by wrapping the Bot API HTTP client** — one place,
+no per-call-site instrumentation — and there also honours a 429's `Retry-After` (bounded) so it backs
+off rather than hammering (a 429 should therefore stay ~0). The gateway folds each report into its
+own metrics (`bot_tg_errors_total{kind}`, the `bot_tg_last_ok_unix` liveness gauge). The remote bot
+is thus monitored from the main host's Grafana with three layered signals: the **connection gauge**
+(`botlink_connected_bots`) catches a link/host/process outage, the **liveness gauge** catches a
+silently wedged bot (its stamp stays fresh even when idle, since getUpdates returns every poll), and
+**`botlink_commands_total{result}`** catches gateway sends failing to reach Telegram. Alerts route to
+the operator email, which does not depend on the bot.
+
 A separate **advertising-banner** channel feeds the client's one-line strip (UI_DESIGN.md),
 server-driven by `internal/ads`. An operator manages **campaigns** (each one placement order) in
 the admin console (`/_gm/banners`): a campaign has a show **weight** (integer percent 1..100), an
@@ -1057,7 +1158,9 @@ link — misses the event; while an add-email confirmation is pending the client
   `OTEL_EXPORTER_OTLP_*` environment) exports to a collector. The Postgres pool is
   instrumented with otelsql and `otelgrpc` traces the backend↔gateway push stream
   and the gateway↔validator and bot-link calls; the gateway also exports
-  `botlink_connected_bots` and `botlink_commands_total` (by result) for the bot-link. The OTLP **Collector** (OTLP/gRPC → Prometheus
+  `botlink_connected_bots` and `botlink_commands_total` (by result) for the bot-link, plus the remote
+  bot's own Bot API health it relays over the stream — `bot_tg_errors_total` (by kind) and the
+  `bot_tg_last_ok_unix` liveness gauge (see the bot-link section). The OTLP **Collector** (OTLP/gRPC → Prometheus
   metrics + Tempo traces), **Prometheus** (15d), **Tempo** (72h) and **Grafana**
   (provisioned datasources + dashboards, behind the caddy `/_gm/grafana` Basic-Auth)
   are stood up with the deploy (`deploy/`); the default exporter stays
@@ -1174,6 +1277,18 @@ link — misses the event; while an add-email confirmation is pending the client
   (`POST /api/v1/internal/bans/sync`, network-trusted like the rejection report) and applies
   the operator unbans the response returns, so a manual unban takes effect within the sync
   interval.
+- **Community IP blocklist (prod-only):** with `GATEWAY_BLOCKLIST_ENABLED` set, the gateway also
+  refuses a client whose IP is in a curated CIDR feed (Spamhaus DROP, `GATEWAY_BLOCKLIST_URL`) with
+  **403** in the same `abuseGuard`, before the fail2ban list. A background refresher re-fetches the
+  feed every few hours (bounded fetch + size cap) into a sorted-range matcher (`ratelimit.Blocklist`,
+  binary search, IPv4 only — an IPv6 client is never blocked here). It is **fault-tolerant and
+  fail-open**: a failed fetch keeps the last-good feed, and once the feed is older than
+  `GATEWAY_BLOCKLIST_MAX_STALENESS` it is **dropped** rather than block a legitimate client on a
+  frozen list; a `GATEWAY_BLOCKLIST_ALLOW` allowlist (own infra, monitoring) is never blocked. Off by
+  default and prod-only for the same real-client-IP reason as the ban. It is a **separate** static
+  CIDR set, not the per-IP fail2ban store (a bulk CIDR feed cannot expand into per-IP entries).
+  Observability: `gateway_blocklist_blocked_total`, the `gateway_blocklist_entries` size gauge and the
+  `gateway_blocklist_age_seconds` staleness gauge (a Grafana alert warns before the feed is dropped).
 - Unauthenticated `GET /healthz` (liveness) and `GET /readyz` (readiness — the
   database answers a bounded ping and the session cache is warmed).
 - The backend serves a **second listener** — a gRPC server
@@ -1263,7 +1378,9 @@ Single public origin, path-routed. The Vite build has two entries: a lightweight
 `/app/` (web), `/telegram/` (the Telegram Mini App; on that path without sign-in data
 — no `initData` — the client renders a compact, shareable launch-diagnostic screen instead
 of redirecting away) and `/vk/` (the VK Mini App; the client reads the signed `vk_*` launch
-parameters from the URL and the gateway verifies them in-process — §12); a stray hit on the
+parameters from the URL and the gateway verifies them in-process — §12; on that path without a
+signed launch the client renders the same shareable launch-diagnostic screen rather than starting
+a throwaway guest); 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
@@ -1288,13 +1405,18 @@ route (its `directoryIndex` is `index.html`) would otherwise shadow it and serve
 cache-first — the old build's version until a second load. The landing page and the conditional
 polyfill bundle are excluded, and the Connect stream and runtime API POSTs are never precached nor
 intercepted, so the live app is never served stale. This satisfies Chromium's installability requirement (a registered SW, needed
-for install on Android) and powers the opt-in **offline mode** (in progress): a deliberate, device-scoped Settings
+for install on Android) and powers **offline play**. Offline is **implicit** — the net-state machine
-toggle — distinct from the transient gateway-reachability signal — that tints the header blue with
+(§2) detects lost connectivity and tints the header blue with an *Offline* chip; there is **no toggle**
-an *Offline* chip and confines play to on-device `vs_ai` games. The **offline lobby lists only those
+(the old deliberate Settings switch and its cold-start dialog are gone). The **unified lobby** merges the
-device-local games** (reconstructed by replaying the IndexedDB move journal) and its New-vs-AI entry
+device-local games (active — reconstructed by replaying the IndexedDB move journal) with the last-cached
-creates one through the in-browser engine — the same game screen then drives it, the robot replying
+**server games shown greyed** (un-openable, a tap toasts *offline*); the Stats tab is disabled and
-locally; online-only affordances (the Stats tab, the random-opponent option) are disabled
+invitations are hidden while offline. On offline-capable channels (native / plain web) New Game's *with
-or hidden, and New Game's *with friends* becomes the entry to **local pass-and-play (hotseat)**.
+friends* carries an **online/offline segmented control** — online = a friend invite, offline = **local
+pass-and-play (hotseat)** — with the online segment disabled and offline forced when there is no network;
+the online-only Telegram/VK mini-apps skip the segment and show the remote invite alone. A `vs_ai` or
+hotseat create is guarded when
+the chosen variant's dictionary is not available offline. A device-local `vs_ai` game is created through
+the in-browser engine and driven by the same game screen, the robot replying locally.
 A hotseat game is a device-local **2-4 human** game built through the same engine (`hotseat` +
 per-seat/host PIN locks on the record; the seats carry names but no accounts). A **mandatory host
 (referee) PIN** gates the roster at creation and, in-game, the referee overrides — **skip** the
@@ -1322,36 +1444,28 @@ eligible installed PWA (standalone web + confirmed email) **background-preloads*
 — on lobby entry and on a variant-preference change — through the same three-tier loader, retried
 with backoff and honouring the session miss-breaker; the move generator, the loader and the preload
 orchestration stay in lazy chunks. A first-lobby preload failure shows a *poor-connection* notice in
-the ad-banner slot. Flipping the Settings toggle **to** offline runs that same cache-first fetch
+the ad-banner slot. A **cold launch with no network** boots offline-first from the persisted session +
-bounded by a ~5 s UI wait (`raceOfflineReady` + the lazy `dict/offlineready`): it enters offline only
+profile (saved on every online adopt/refresh) — `bootstrap` skips the session adoption and profile fetch
-once every enabled variant is ready, otherwise it stays online with a *needs internet* note while the
+that would otherwise hang, and lands straight in the offline lobby; a native launch with no server
-fetch finishes in the background (the next flip is then instant). A **cold launch already in offline
+session enters as a device-local guest (§3), and any stale pre-redesign offline-preference key is cleared
-mode** boots from the persisted session and
+on boot. Connectivity is **detected, not chosen** (the net-state machine, §2): a cold `navigator.onLine
-profile (the profile is saved on every online adopt/refresh) — `bootstrap` skips the session
+=== false` or a failed cold reachability probe (a bounded `profile.get`) enters offline, and mid-session
-adoption and profile fetch that would otherwise hang with no network, and lands straight in the
+the `navigator` / `@capacitor/network` `online`/`offline` events plus the probe watcher drive it — with
-offline lobby; without a cached profile (an install that was never online) it drops the sticky flag
+**hysteresis** so a brief blip lives in `connecting` and never flips the chrome, and **self-heal** (a
-and boots online instead. Beyond the sticky toggle the app **auto-detects connectivity**: the
+back-online toast) when the network returns. Offline is a real **transport kill switch** (every gateway
-reactive flag carries an *auto* bit, so a self-entered offline (no network) is transient
+call is refused, so no traffic leaks); the reachability probe is the one call exempt from it (it is the
-(session-only, never persisted) and self-heals to online when the network returns, while a deliberate
+return-to-online mechanism). The gateway registers the `.webmanifest` MIME type
-one (the toggle, or the cold-start dialog's *Switch*) persists. At cold start `navigator.onLine ===
-false` enters offline for the session; otherwise a single bounded reachability probe (a `profile.get`,
-~3 s) decides — success boots online, a timeout on an eligible install raises a *No connection* dialog
-(*Switch* = sticky offline, *Wait for network* = boot online with the reachability watcher retrying).
-Mid-session the `window` `online`/`offline` events drive it — `offline` auto-enters, `online`
-re-verifies reachability before returning — backed by a `navigator.onLine` poll because those events
-are unreliable on some platforms (notably iOS PWAs). Offline is a real **transport kill switch**
-(every gateway call is refused, so no traffic leaks); the reachability probe is the one call exempt
-from it (it is the return-to-online mechanism), and the transient reachability watcher is suppressed
-while offline. The gateway registers the `.webmanifest` MIME type
 in-process (the distroless image has no `/etc/mime.types`). Hash-named `/assets/*` are served
 `immutable` (a relaunch is a cache hit, not a re-download); the HTML shells are
 `no-cache` so a new deploy is picked up — both containers apply the same caching. An
 in-compose **caddy** is the contour's edge: it owns a single `/_gm` Basic-Auth and
 routes `/_gm/grafana/*` to **Grafana** (anonymous-admin, so the one shared login gates
 it with no per-user Grafana accounts) and the rest of `/_gm/*` to the backend-rendered
-**admin console**; `/app/`, `/telegram/`, `/vk/` and the Connect path go to the gateway; the
+**admin console**; `/app/`, `/telegram/`, `/vk/` and the Connect path go to the gateway; the public
-catch-all — notably the landing at `/`, plus the static public offer at `/offer/`
+legal pages `/offer/`, `/privacy/` and `/eula/` (rendered by the `renderer` sidecar — the offer with
-(rendered from `ui/legal/offer_ru.md` at build time) — goes to the landing container. The
+the live catalog price list spliced in) go to the render sidecar; and the catch-all — notably the
+landing at `/` — goes to the landing
+container. The
 **Telegram validator** runs as a separate container with **no public ingress**,
 answering only internal gRPC (HMAC, no Telegram egress). The **Telegram bot** holds
 no inbound port either: it dials the gateway's **bot-link** (mTLS) and egresses to
@@ -1423,6 +1537,24 @@ Two contours, two secret/variable prefixes (`TEST_` / `PROD_`):
   client IPs). The `vpn`+`bot` pair is gated to a `telegram-local` compose profile the test
   contour activates; the prod main host omits it.
 
+**Native Android build (Capacitor).** The SPA is also packaged as a standalone **Android app** (Capacitor 8,
+appId `ru.eruditgame.app`, "Эрудит"; minSdk 24, compile/targetSdk 36, JDK 21), first for **RuStore**. It is
+a **bundle** model — the WebView loads the packaged `dist/` from app assets (**no `server.url`**), so there
+is no OTA: updates ship through the store, and the **client-version gate** (§2) turns away a build too old to
+speak the current wire contract. Because the packaged origin is `file://`, the native build talks to an
+**absolute** gateway origin (`VITE_GATEWAY_URL` = the production origin; `lib/origin.ts` centralises how absolute URLs are built), and the service worker is skipped (the bundle is
+the cache). It is **offline-first**:
+`ui/scripts/bundle-dicts.mjs` copies the versioned `scrabble-dictionary` release DAWGs into
+`dist/dict/<variant>@<version>.dawg` (keyed on `VITE_DICT_VERSION`), so a cold first launch with no network
+enters as a **local guest** (§3) and plays local vs_ai / hotseat from the bundled dictionaries. Purchases are
+hidden in the MVP (`VITE_PAYMENTS_DISABLED`). The APK is built by a **manual** `workflow_dispatch` workflow
+(`.gitea/workflows/android-build.yaml`, from `master`, `confirm=build`) that builds the native SPA, bundles
+the dicts, and assembles a **release APK** artifact — signed when the `ANDROID_KEYSTORE_*` secrets are
+present, unsigned otherwise. `versionCode`/`versionName` are deterministic from the release tag `vMA.MI.PA`
+(`versionCode = MA*1_000_000 + MI*1_000 + PA`, `versionName = "MA.MI.PA"`). The runner is a host-executor
+with a host-provisioned Android SDK; RuStore upload is manual. Runbook:
+[`../deploy/README.md`](../deploy/README.md).
+
 ## 14. CI & branches
 
 - **Two long-lived branches**: **`development`** is the integration

docs/FUNCTIONAL.md

@@ -30,7 +30,13 @@ render with arbitrary languages, so detection would make the indexed content
 nondeterministic); a saved 🌐 choice still wins. The page carries a static Russian SEO head
 (title/description, the Open Graph card Telegram/VK link previews use, a canonical link
 pinned to the production origin, JSON-LD, the favicon set and `robots.txt`), while the SPA
-shell is `noindex` — the landing is the only indexable page.
+shell is `noindex` — the landing is the only indexable page. The footer links to the three **legal
+documents** — the **user agreement** (`/eula/`), the **privacy policy** (`/privacy/`) and the
+**public offer** (`/offer/`) — and, beside them, **feedback** (the Telegram bot the documents name as
+the seller's contact). Each is **bilingual (RU/EN)** with a language + theme switcher and is rendered
+from its `ui/legal/*_{ru,en}.md` sources by the render sidecar; the offer additionally splices in its
+**price list** (§4.4) generated from the live product catalog, so the published prices always match
+what is currently on sale — no redeploy to update them.
 
 On the plain web the client is an **installable PWA**: a logged-out player sees an install
 call-to-action under the login form (and at the bottom of Settings) that installs the app to the
@@ -66,7 +72,10 @@ A **VK Mini App** launch works the same way: it authenticates from VK's signed l
 `vk_language` and its display name from the VK profile (read on the client, since VK does not put
 the name in the signed launch). While the theme preference is "auto" the app follows the VK
 client's light/dark scheme, and the layout clears the VK mobile home bar. The same quiet-retry
-"couldn't load" screen applies inside VK.
+"couldn't load" screen applies inside VK. Opening a Mini App link directly in an ordinary browser —
+the `/vk/` entry with no signed VK launch, or `/telegram/` with no Telegram sign-in data — shows a
+compact, shareable diagnostic screen instead of proceeding (as a throwaway guest on VK, or by
+redirecting away on Telegram), so a player who ends up there wrongly can screenshot it for us.
 **Email** sign-in (web) mails a branded six-digit confirmation code — localized
 (en/ru), no images — to the address; entering it signs the player in. A new address
 is provisioned on the first request but only becomes a durable account once the code
@@ -220,7 +229,10 @@ brief warm-up shows on the first open otherwise — and falls back to the server
 local dictionary is unavailable. The dictionary check tool is
 unlimited and offers a complaint on any result; for a word it finds, it also links out to an
 external reference dictionary (gramota.ru for Russian games, scrabblewordfinder.org for
-English) to look it up. Hints are governed per game —
+English) to look it up. While offline in an online game the check runs against the game's own
+dictionary on the device — the same verdict as the server when that dictionary is available,
+otherwise it reads *unavailable offline* — and the complaint and the external look-up, which both
+need the network, are hidden. Hints are governed per game —
 whether they are allowed and how many each player starts with — and draw on a
 personal hint wallet once the per-game allowance is spent. Against the robot
 (**vs_ai**) hints are instead **unlimited and wallet-free**, but idle-gated as an
@@ -273,22 +285,28 @@ add-friend are off. AI games are **practice** — they never count toward a play
 statistics.
 
 ### Offline mode
-An installed web PWA signed in with a confirmed email can switch to a deliberate **offline mode**
+The **web and native apps** play **offline automatically** — there is **no on/off switch**; the
-(Settings → Play mode). Offline, the app never touches the network: the header turns blue with an
+online-only **Telegram and VK mini-apps** never go offline (everything below applies to the web and
-*Offline* chip, the lobby lists only the games stored on the device, and online-only surfaces are
+native apps only). When it cannot reach the
-disabled or hidden (the Stats tab; the *random opponent* option in New Game).
+server the header turns blue with an *Offline* chip and play is confined to games on the device; a
-A New Game against the robot creates a device-local **vs_ai** game — it
+momentary blip is ridden out as a quiet *"Connecting…"* (it never drops you offline), and when the
-plays entirely in the browser with no backend. Local games are kept on the device, visible only in
+connection returns the app goes back online on its own with a brief *back online* toast. Offline, the
-offline mode, and never sync to the account. So a game can be created and played with no connection,
+app never touches the network.
-the app quietly preloads the dictionaries for the player's enabled variants while still online, and
-(once installed) launches from a precached shell even with no network. Switching **to** offline first
-checks that the enabled variants' dictionaries are on the device — if any are missing it fetches them
-and waits briefly, and if they cannot be readied it stays online with a short *needs internet* note
-(the download keeps running in the background, so a later switch is instant). The mode is
-device-scoped and sticky across launches.
 
-Offline, New Game's **with friends** starts a **local pass-and-play** game for 2-4 people sharing one
+The **lobby stays unified**: your device-local games are active, while your server games are still
-device. You first set a **host (leader) password** — a 4-digit PIN entered on a lock-screen-style
+listed but **greyed out** — visible but un-openable until you are back online (a tap explains why).
+Online-only surfaces (the Stats tab) are disabled and invitations are hidden while offline. A New Game
+against the robot creates a device-local **vs_ai** game that plays entirely on the device with no
+backend; local games are kept on the device and never sync to the account, so a game can be created and
+played with no connection. The app quietly preloads the dictionaries for the player's enabled variants
+while still online, and (once installed, or on the native app) launches from bundled/precached data even
+with no network; if a variant's dictionary is not available offline, creating that game is disabled with
+a short note.
+
+New Game's **with friends** offers a choice — **invite a friend** to play online, or a **local
+pass-and-play** game for 2-4 people sharing one device; with no network only pass-and-play is available.
+(In the online-only Telegram/VK mini-apps *with friends* is the friend invite alone — no pass-and-play.)
+In pass-and-play you first set a **host (leader) password** — a 4-digit PIN entered on a lock-screen-style
 keypad; until it is set the player rows stay locked. The app then asks whether you are playing too —
 if so you take the first seat with your profile name. You name each player (2 to 4; add or remove
 rows, where a removal asks for the leader password) and may give any seat its **own optional PIN**.
@@ -301,14 +319,42 @@ pass-and-play game. A game that finishes normally is saved to the offline lobby
 deleting any pass-and-play game — running or finished — from the lobby asks for the leader password,
 so no one can wipe a game the moment they have moved.
 
-The app also **enters offline mode on its own** when it cannot reach the network. On a cold launch
+Going offline and coming back are both **automatic**. On a cold launch with no connection the app
-with no connection it switches to offline for that session; when the device is online but the gateway
+starts straight in the offline lobby; while it is open, losing the network — airplane mode — turns it
-stays silent for a few seconds it asks first — *No connection. Switch to offline mode?*, with
+offline on its own, and restoring the network returns it online by itself. There is no dialog and no
-**Switch** (go offline) or **Wait for network** (keep retrying online). While the app is open, losing
+switch to remember: a brief drop is ridden out quietly and only a sustained loss turns the chrome
-the network — airplane mode — switches to offline automatically, and restoring it returns online by
+offline, so you are never interrupted for a hiccup.
-itself. A self-entered offline is temporary: it reverts to online the moment the network is back, and
+
-the next launch re-checks. A **deliberate** offline — the Settings toggle, or **Switch** in that
+**Losing the connection while inside an online game** is surfaced on **every platform, including the
-dialog — is the player's choice: it is kept, and never undone automatically.
+Telegram/VK mini-apps** — unlike the offline-play mode above, which is web/native only — because an
+online game needs the server for every move. A slim *connection lost* banner appears at the top of the
+board and the play area **freezes**: the rack and the move controls disable, and the resign, the
+add-friend/block and the chat/dictionary controls are hidden, while a move you had started stays on the
+board as a draft. Nothing
+is sent; when the connection returns the banner clears, the controls come back and you commit the move
+yourself. If you were already in the chat or the dictionary when the drop happened you stay there — chat
+becomes read-only (send and nudge disable) and the dictionary keeps checking words against the game's
+on-device dictionary.
+
+### Staying up to date
+When a new client version is required, the app does not lock you out. On the **native** app a
+too-old build shows a notice with **Update** (opens the store) and **Play offline** (dismiss and keep
+playing your on-device games); on the web it offers **Update** (reload) instead. A softer,
+non-blocking **"update available"** banner appears in the lobby when a newer — but not yet
+required — version exists; you can update or dismiss it, and play continues either way.
+
+### Native app (Android)
+The game also ships as a standalone **Android app** (first on **RuStore**), a packaged build of the same
+client. Everything it needs is bundled, so it opens with **no network**: a first launch offline drops you
+straight into the lobby as a **guest** (no sign-in wall) and you can play right away — against the robot, or
+a **pass-and-play** game with friends on one device — using the dictionaries shipped inside the app. When the
+network is available the app quietly establishes a guest in the background and online features (random
+opponents, friends, statistics) light up without interrupting play; local games you started offline stay on
+the device. To keep a durable account you sign in with **email** from Profile (the guest becomes your
+account); Telegram and VK sign-in are not offered in the native app. In-app purchases are hidden in this
+first release. Because an installed app can be far older than the server, a build that is **too old** to talk
+to the current server shows a single, non-dismissable *update* screen whose button opens the store listing —
+this appears only on an online action, never while you are playing offline.
 
 ### Social: friends, block, chat, nudge
 Become friends in two ways: redeem a **one-time code** the other player issues (six
@@ -403,9 +449,11 @@ unanswered reply. Guests cannot send feedback (the entry is hidden). A player th
 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
+A user can also reach the operators straight from the Telegram bot. The `/support` command replies
-other than `/start` — text, a photo, a voice message, a file — is forwarded into the operators'
+with the support desk's working hours and what to include (a description and, when possible,
-private support group, grouped into a per-user thread. The user sees no automatic reply; an
+screenshots). Anything else 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 to a forwarded message; 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
@@ -508,7 +556,8 @@ at any time (games already lost stay lost).
 
 Where the bot manages a channel's **linked discussion chat**, everyone may write by default and the
 bot **mutes** a player who is **not registered** or is **blocked**, un-muting them once they register
-or are unblocked. So an unregistered newcomer who comments is muted (the promo bot points them at the
+or are unblocked. It also clears the automatic pin Telegram puts on each channel post that is
+auto-forwarded into the chat, so only deliberately pinned messages stay pinned. So an unregistered newcomer who comments is muted (the promo bot points them at the
 game to register, after which the bot restores their voice), and a registered, unblocked player simply
 writes. An operator can also **mute a player in the chat only** — a `chat_muted` role on the user card —
 without a full account block; an account block mutes them in the chat regardless. Muting and unmuting

docs/FUNCTIONAL_ru.md

@@ -32,7 +32,13 @@ top-1 подсказку, безлимитную проверку слова с
 главнее. Страница несёт статическую русскую SEO-«шапку» (title/description, карточка
 Open Graph, которую используют превью ссылок в Telegram/VK, канонический адрес
 продакшен-домена, JSON-LD, набор favicon и `robots.txt`), а оболочка SPA помечена
-`noindex` — индексируется только посадочная страница.
+`noindex` — индексируется только посадочная страница. В подвале — ссылки на три **юридических
+документа** — **пользовательское соглашение** (`/eula/`), **политику конфиденциальности**
+(`/privacy/`) и **публичную оферту** (`/offer/`) — и рядом на **обратную связь** (тот самый
+Telegram-бот, который документы указывают как контакт Продавца). Каждый — **двуязычный (RU/EN)** с
+переключателем языка и темы, рендерится из исходников `ui/legal/*_{ru,en}.md` сайдкаром-рендерером;
+оферта дополнительно подставляет **перечень стоимости** (§4.4), формируемый из живого каталога
+товаров, поэтому опубликованные цены всегда совпадают с тем, что сейчас в продаже — без передеплоя.
 
 В обычном вебе клиент — **устанавливаемое PWA**: незалогиненный игрок видит призыв к установке
 под формой входа (и внизу «Настроек»), который в один тап ставит приложение на рабочий стол
@@ -71,7 +77,10 @@ launch-параметрам VK (их проверяет gateway), и при пе
 так как VK не кладёт имя в подписанный запуск). Пока тема в режиме «авто», приложение следует
 светлой/тёмной схеме VK-клиента, а раскладка обходит нижнюю home-bar VK на мобильных. Тот же экран
 тихого повтора «не удалось
-загрузить» действует и внутри VK.
+загрузить» действует и внутри VK. Если открыть ссылку на мини-приложение прямо в обычном браузере —
+вход `/vk/` без подписанного запуска VK или `/telegram/` без данных входа Telegram — показывается
+компактный экран диагностики, которым можно поделиться, вместо того чтобы продолжить (гостем-однодневкой
+на VK или редиректом прочь на Telegram), — чтобы игрок, случайно попавший туда, прислал нам скриншот.
 **Email**-вход (в вебе) отправляет на адрес брендированный шестизначный код подтверждения —
 локализованный (ru/en), без картинок; после ввода игрок входит. Новый адрес заводится при первом
 запросе, но становится постоянным аккаунтом только после подтверждения кода — так брошенная,
@@ -227,7 +236,9 @@ e-mail) либо ввод фразы. Активные игры форфейтя
 короткий прогрев, — и уходит на сервер, если локальный словарь недоступен. Инструмент проверки слова безлимитный и
 предлагает пожаловаться на любой результат; для найденного слова он также даёт ссылку на
 внешний справочный словарь (gramota.ru для русских игр, scrabblewordfinder.org для английских),
-чтобы его посмотреть. Подсказки управляются настройками
+чтобы его посмотреть. В офлайне в онлайн-партии проверка идёт по собственному словарю партии на
+устройстве — тот же вердикт, что и на сервере, если этот словарь доступен, иначе показывается
+*недоступно офлайн*, — а жалоба и внешняя ссылка, которым нужна сеть, скрываются. Подсказки управляются настройками
 партии — разрешены ли они и сколько их у каждого игрока на старте — и расходуют
 личный кошелёк подсказок после исчерпания внутриигрового лимита. Против робота
 (**vs_ai**) подсказки, наоборот, **безлимитны и без кошелька**, но с idle-гейтом как
@@ -278,22 +289,27 @@ e-mail) либо ввод фразы. Активные игры форфейтя
 редкими ходами вопреки плану, затухающими к эндшпилю), а чат, nudge и «добавить в друзья» выключены. Партии с ИИ — это **тренировка**: они не идут в статистику игрока.
 
 ### Офлайн-режим
-Установленный веб-PWA со входом по подтверждённой почте может переключиться в осознанный
+**Веб- и нативное приложения** играют **офлайн автоматически** — никакого переключателя нет; онлайн-только
-**офлайн-режим** (Настройки → Режим игры). В офлайне приложение не обращается к сети: шапка синеет с
+**мини-приложения Telegram и VK** никогда не уходят в офлайн (всё ниже относится только к веб- и нативному
-меткой *Офлайн*, лобби показывает только сохранённые на устройстве игры, а сетевые поверхности
+приложениям). Когда оно не может достучаться
-отключены или скрыты (вкладка Статистика; вариант «случайный соперник» в Новой игре).
+до сервера, шапка синеет с меткой *Офлайн*, а игра ограничивается партиями на устройстве; кратковременный
-Новая игра против робота создаёт локальную **vs_ai**-игру — он ходит
+сбой пережидается как тихое *«Подключение…»* (в офлайн не роняет), а при возврате связи приложение само
-целиком в браузере без бэкенда. Локальные игры хранятся на устройстве, видны только в офлайн-режиме и
+возвращается онлайн с коротким тостом *соединение восстановлено*. В офлайне приложение не обращается к
-никогда не синхронизируются с аккаунтом. Чтобы игру можно было создать и сыграть без связи, приложение
+сети.
-заранее, пока ещё онлайн, подгружает словари включённых игроком вариантов и (после установки)
-запускается из прекешированного шелла даже без сети. Переключение **в** офлайн сначала проверяет, что
-словари включённых вариантов есть на устройстве — если каких-то не хватает, оно их подгружает и недолго
-ждёт, а если подготовить их не удаётся, остаётся онлайн с короткой заметкой *нужен интернет* (загрузка
-продолжается в фоне, так что следующее переключение мгновенно). Режим привязан к устройству и
-сохраняется между запусками.
 
-В офлайне «с друзьями» в Новой игре запускает **локальную игру по очереди (hotseat)** на 2–4 человек
+**Лобби остаётся единым**: локальные игры на устройстве активны, а серверные игры по-прежнему видны, но
-за одним устройством. Сначала задаётся **пароль ведущего** — 4-значный PIN на клавиатуре в стиле
+**затемнены** — их видно, но открыть нельзя, пока не вернётесь онлайн (тап поясняет почему). Сетевые
+поверхности (вкладка Статистика) отключены, а приглашения в офлайне скрыты. Новая игра против робота
+создаёт локальную **vs_ai**-игру, которая идёт целиком на устройстве без бэкенда; локальные игры хранятся
+на устройстве и никогда не синхронизируются с аккаунтом, так что игру можно создать и сыграть без связи.
+Приложение заранее, пока ещё онлайн, подгружает словари включённых игроком вариантов и (после установки
+или в нативном приложении) запускается из вшитых/прекешированных данных даже без сети; если словарь
+варианта недоступен офлайн, создание такой игры отключается с короткой заметкой.
+
+«С друзьями» в Новой игре предлагает выбор — **пригласить друга** для игры онлайн или **локальную игру
+по очереди (hotseat)** на 2–4 человек за одним устройством; без сети доступна только игра по очереди.
+(В онлайн-только мини-приложениях Telegram/VK «с друзьями» — это только приглашение друга, без игры по очереди.)
+В игре по очереди сначала задаётся **пароль ведущего** — 4-значный PIN на клавиатуре в стиле
 экрана блокировки; пока он не задан, строки игроков заблокированы. Затем приложение спрашивает,
 играете ли вы сами — если да, вы занимаете первое место под именем из профиля. Вы называете каждого
 игрока (от 2 до 4; строки можно добавлять и удалять, удаление спрашивает пароль ведущего) и можете
@@ -307,14 +323,42 @@ e-mail) либо ввод фразы. Активные игры форфейтя
 идущей или завершённой — из лобби спрашивает пароль ведущего, чтобы никто не стёр партию сразу после
 своего хода.
 
-Приложение также **само включает офлайн-режим**, когда не может достучаться до сети. При холодном
+Уход в офлайн и возврат — оба **автоматические**. При холодном запуске без связи приложение сразу
-запуске без связи оно переходит в офлайн на текущую сессию; когда устройство онлайн, но шлюз молчит
+стартует в офлайн-лобби; пока оно открыто, потеря сети — режим полёта — сама уводит в офлайн, а
-несколько секунд, оно сперва спрашивает — *Нет связи. Включить офлайн-режим?*, с выбором **Включить**
+восстановление сети само возвращает онлайн. Ни диалога, ни переключателя, который надо помнить:
-(уйти в офлайн) или **Ждать сеть** (продолжить попытки онлайн). Пока приложение открыто, потеря сети —
+кратковременный сбой пережидается тихо, и только устойчивая потеря переводит интерфейс в офлайн, так что
-режим полёта — переключает в офлайн автоматически, а её восстановление само возвращает онлайн.
+вас не прерывают из-за короткой икоты.
-Самостоятельно включённый офлайн временный: он возвращается в онлайн, как только сеть появилась, и
+
-следующий запуск проверяет заново. **Осознанный** офлайн — тумблер в Настройках или **Включить** в том
+**Потеря связи внутри онлайн-партии** показывается на **всех платформах, включая мини-приложения
-диалоге — это выбор игрока: он сохраняется и никогда не отменяется автоматически.
+Telegram/VK** — в отличие от офлайн-режима игры выше, который только для веба и нативного приложения, —
+потому что онлайн-партии сервер нужен на каждый ход. Сверху доски появляется тонкий баннер *связь
+потеряна*, и игровая область **замораживается**: рэк и ходовые кнопки отключаются, а «сдаться»,
+«в друзья»/«заблокировать» и вход в чат/словарь скрываются; начатый ход остаётся на доске черновиком.
+Ничего не отправляется;
+когда связь возвращается, баннер исчезает, кнопки оживают, и ход отправляешь ты сам. Если связь упала,
+когда ты уже был в чате или словаре, ты там и остаёшься — чат становится «только для чтения» (отправка
+и nudge отключаются), а словарь продолжает проверять слова по словарю партии на устройстве.
+
+### Актуальная версия
+Когда требуется новая версия клиента, приложение не блокирует вас наглухо. В **нативном** приложении
+слишком старая сборка показывает уведомление с **Обновить** (открывает магазин) и **Играть офлайн**
+(закрыть и продолжить играть на устройстве); в вебе вместо этого предлагается **Обновить** (перезагрузка).
+Более мягкий, ненавязчивый баннер **«Доступно обновление»** появляется в лобби, когда есть новее — но пока
+не обязательная — версия; его можно обновить или закрыть, игра продолжается в любом случае.
+
+### Нативное приложение (Android)
+Игра также выходит как отдельное **приложение для Android** (сначала в **RuStore**) — упакованная сборка
+того же клиента. Всё необходимое встроено, поэтому оно открывается **без сети**: первый запуск офлайн сразу
+открывает лобби как **гость** (без экрана входа), и можно играть немедленно — против робота или в игру **по
+очереди на одном устройстве** (pass-and-play) с друзьями — используя словари, вшитые в приложение. Когда сеть
+доступна, приложение тихо заводит гостя в фоне, и онлайн-возможности (случайные соперники, друзья,
+статистика) включаются, не прерывая игру; локальные игры, начатые офлайн, остаются на устройстве. Чтобы
+сохранить постоянный аккаунт, вход выполняется по **email** из Профиля (гость становится вашим аккаунтом);
+вход через Telegram и VK в нативном приложении не предлагается. Встроенные покупки в этом первом релизе
+скрыты. Поскольку установленное приложение может быть намного старше сервера, сборка, которая **слишком
+стара** для общения с текущим сервером, показывает единственный несбрасываемый экран *обновления*, кнопка
+которого открывает страницу в магазине — он появляется только при онлайн-действии, никогда во время
+офлайн-игры.
 
 ### Социальное: друзья, блок, чат, nudge
 Подружиться можно двумя способами: погасить **одноразовый код**, который выпускает
@@ -413,9 +457,11 @@ Telegram. На сенсорном устройстве в настройках
 обратную связь (роль, а не полная блокировка аккаунта), видит кнопку отправки недоступной.
 
 ### Чат поддержки в Telegram
-С операторами можно поговорить и прямо из Telegram-бота: всё, что пользователь присылает боту,
+С операторами можно поговорить и прямо из Telegram-бота. Команда `/support` отвечает графиком работы
-кроме `/start` — текст, фото, голосовое, файл, — пересылается в закрытую группу поддержки операторов
+поддержки и напоминанием, что приложить (подробное описание и, по возможности, скриншоты). Всё
-и собирается в отдельную ветку на пользователя. Пользователь не получает автоответа; оператор
+остальное, что пользователь присылает боту, кроме `/start` — текст, фото, голосовое, файл, —
+пересылается в закрытую группу поддержки операторов и собирается в отдельную ветку на пользователя.
+Пользователь не получает автоответа на пересланное сообщение; оператор
 отвечает из этой ветки, и бот доставляет ответ обратно обычным сообщением — для пользователя это
 тихий диалог один на один. Операторы могут заблокировать пользователя (тогда бот молча игнорирует
 его сообщения) или очистить сообщения ветки. Это независимо от встроенной «Обратной связи» выше —
@@ -521,7 +567,9 @@ high-rate флага. С карточки пользователя операт
 
 Там, где бот ведёт **привязанный к каналу чат-обсуждение**, по умолчанию писать может каждый, а бот
 **глушит** игрока, который **не зарегистрирован** или **заблокирован**, и снимает мьют, как только тот
-зарегистрируется или будет разблокирован. То есть незарегистрированного новичка, написавшего в чат,
+зарегистрируется или будет разблокирован. Ещё бот убирает автоматический пин, который Telegram ставит
+на каждый пост канала, авто-форварднутый в чат, — закреплёнными остаются только намеренно закреплённые
+сообщения. То есть незарегистрированного новичка, написавшего в чат,
 бот глушит (промо-бот направляет его в игру зарегистрироваться, после чего бот возвращает голос), а
 зарегистрированный незаблокированный игрок просто пишет. Оператор также может **замьютить игрока только
 в чате** — роль `chat_muted` на карточке пользователя — без полной блокировки аккаунта; блокировка

docs/ICONS.md

@@ -0,0 +1,90 @@
+# Icon & logo asset map
+
+> The whole shipped icon set is sliced from **one master**. This file is the per-platform
+> **target map** (which file goes where, at what size). How the mark itself is constructed
+> — proportions, palette, wood grain, the light/shadow gradients, the «Э» + ✻ placement,
+> all in fractions of the side — is specified in [`ICON_BRANDBOOK.md`](ICON_BRANDBOOK.md).
+> The reference generator, the pinned Spectral font and the committed masters live in
+> [`../assets/icons/brand/`](../assets/icons/brand/).
+
+## The master (one source, six layers)
+
+`brand/build-icon.mjs` emits any `--variant light|dark` in any `--layer`:
+
+| Layer | What | Feeds |
+|---|---|---|
+| `full` | rounded tile + master mark | `favicon.svg` |
+| `flat` | square tile + master mark (OS rounds) | apple-touch, PWA "any", VK, TG, store |
+| `background` | square tile only, full-bleed | Android adaptive background |
+| `foreground` | mark only, transparent, re-placed for the round mask | Android adaptive foreground |
+| `maskable` | square tile + foreground-placed mark | PWA `maskable` |
+| `monochrome` | foreground-placed silhouette, flat colour | Android 13+ themed layer |
+
+`brand/build-set.mjs` renders every raster below; `brand/build-android-res.mjs` renders
+the Android launcher resources.
+
+## Generated targets
+
+### Web — `ui/public/` (via `brand/build-set.mjs`)
+
+| File | Size | Note |
+|---|---|---|
+| `favicon.svg` | vector | **light + dark in one file** via `prefers-color-scheme` |
+| `favicon.ico` | 32×32 | PNG-in-ICO; answers the blind `/favicon.ico` probe |
+| `apple-touch-icon.png` | 180×180 | opaque full-bleed (iOS masks its own corners) |
+| `icon-192.png` / `icon-512.png` | 192 / 512 | PWA `any`, light |
+| `icon-192-dark.png` / `icon-512-dark.png` | 192 / 512 | dark variants (generated; see PWA note) |
+| `icon-maskable-512.png` | 512×512 | PWA `maskable`, light |
+| `icon-maskable-512-dark.png` | 512×512 | dark variant (generated; see PWA note) |
+| `og-image.png` | 1200×630 | board-green card: master tile + «Эрудит» / Игра в слова |
+
+### PWA — `ui/public/manifest.webmanifest`
+
+Referenced icons are the **light** set (`icon-192`, `icon-512` = `any`;
+`icon-maskable-512` = `maskable`). The manifest has **no reliable way to pick an icon by
+colour scheme**, so the dark PNGs are **generated but not referenced** — theming the
+in-browser tab is handled by `favicon.svg` instead. Wire the dark files in only if a
+concrete installer target is known to honour them.
+
+### Android — `ui/android/app/src/main/res/` (via `brand/build-android-res.mjs`)
+
+Capacitor layer inputs are `ui/assets/{icon,icon-foreground,icon-background}.png`. The
+resources are **hand-generated from the layers**, not `capacitor-assets` — our layers
+already fill the 108 dp canvas (foreground inside the 61 % safe zone, background
+full-bleed), so they must be placed with **no inset**, and we add the **monochrome**
+themed layer, neither of which `capacitor-assets` does. Per density mdpi→xxxhdpi (+ldpi):
+
+- `mipmap-*/ic_launcher.png` / `ic_launcher_round.png` — legacy square / round (composite)
+- `mipmap-*/ic_launcher_foreground.png` + `ic_launcher_background.png` — adaptive layers
+- `mipmap-*/ic_launcher_monochrome.png` — themed layer
+- `mipmap-anydpi-v26/ic_launcher.xml` + `ic_launcher_round.xml` — **no `<inset>`**, with
+  `<background>` + `<foreground>` + `<monochrome>` (committed by hand)
+
+### iOS / iPhone / iPad — FUTURE
+
+No iOS shell today. When one exists, `flat` (opaque, no alpha, no rounded corners; the OS
+masks) drives the asset catalog — a single 1024×1024 marketing icon (Xcode derives the
+rest), plus light/dark/tinted where the catalog supports it.
+
+### VK / Telegram / store — manual upload (`brand/{vk,tg,store}/`)
+
+Square, **no rounding** (each platform crops/rounds itself), light `flat`:
+
+| Folder | Files | Use |
+|---|---|---|
+| `vk/` | `vk-576/278/150/32.png` | VK community / app icons |
+| `tg/` | `tg-512.png` | Telegram bot avatar + Mini App icon (512, square; TG crops circular) |
+| `tg/` | `tg-demo-640x360.png` | BotFather `/newapp` demo banner (tile + wordmark) |
+| `store/` | `rustore-512.png` | RuStore app icon |
+| RuStore | screenshots / feature graphic | per the RuStore listing spec (uploaded by hand) |
+| Google Play (future) | icon / feature graphic | 512×512 / 1024×500 |
+| App Store (future) | marketing icon / screenshots | 1024×1024 / per device class |
+
+## Regenerate
+
+```sh
+cd assets/icons/brand
+npm i                        # opentype.js (rasterisation reuses the ui package's chromium)
+node build-set.mjs           # web (ui/public) + Capacitor layers (ui/assets) + vk/ tg/ store/ + og
+node build-android-res.mjs   # Android launcher resources (all densities + monochrome)
+```

docs/ICON_BRANDBOOK.md

@@ -0,0 +1,166 @@
+# Erudit app-icon — brand book
+
+The single source of truth for **how the Erudit icon is constructed**. It is written to
+be reproducible *from words alone*: a designer with this document and the Spectral font
+can rebuild the icon exactly, at any size, without pixel-matching anything.
+
+Two rules make that possible:
+
+1. **The icon is a square.** Every size and position below is a **fraction of the
+   square's side** (equivalently, a percentage). Nothing is in pixels. Draw the square
+   at whatever resolution you need and scale each value to it.
+2. **The origin is the top-left corner.** `x` grows right, `y` grows down. So "center
+   `48.1% / 49.2%`" means a point `0.481·side` from the left and `0.492·side` from the top.
+
+The companion generator in [`../assets/icons/brand/`](../assets/icons/brand/) is the
+machine version of this exact spec (`build-icon.mjs`, where each constant is the same
+fraction printed here). The `docs/ICONS.md` map covers the *opposite* concern — which
+files/sizes we slice this master into for each platform.
+
+## Anatomy
+
+![Construction scheme](../assets/icons/brand/icon-construction.png)
+
+Bottom-to-top the icon is six layers: **tile → wood grain → light sheen → shadow →
+letter «Э» → star ✻**. The letter and star are always drawn last, at full ink colour;
+the grain and the two gradients only ever touch the background.
+
+## Palette
+
+The icon ships as a **light** and a **dark** variant (a matched pair — the light tile
+carries dark ink, the dark tile carries light ink). Each variant uses four colours.
+
+| Role | Light | Dark |
+|------|-------|------|
+| **Tile** — the wooden body | `#e6b053` | `#4a3316` |
+| **Ink** — the «Э» and the ✻ | `#5a3a12` | `#f2d9a0` |
+| **Grain** — the vertical stripes | `#d8a54e` | `#432e14` |
+| **Sheen** — diagonal light | white, α 0 → 15 % | white, α 0 → 15 % |
+| **Shadow** — diagonal dark | black, α 15 → 0 % | black, α 15 → 0 % |
+
+The grain colour is intentionally close to the tile — a hair darker — so the stripes
+read as wood texture, not as stripes.
+
+## 1 — Tile
+
+A **square with rounded corners**, corner radius **17 %** of the side, filled with the
+**Tile** colour. This is the whole background; there is no separate outer frame or
+border. Corners are baked at 17 %; platform masks (iOS/Android) may round further on top.
+
+## 2 — Wood grain
+
+Subtle vertical planks over the tile:
+
+- Divide the width into **6 equal columns** (each `1/6` of the side wide).
+- On the **right edge of each column**, draw one **vertical stripe**, width **`1/32` of
+  the side** (≈ 3.1 %), running the full height.
+- Move the **whole set of six stripes left** by **`1/16` of the side** (= two stripe
+  widths).
+- **Tilt every stripe 4°** (clockwise, about its own centre).
+- Draw the stripes **past the top and bottom edges** so the tilt leaves no empty corners,
+  then **clip the whole set to the tile** (so the rounded corners stay clean).
+- Colour: **Grain**.
+
+## 3 — Light sheen · 4 — Shadow
+
+Two linear gradients along the **same diagonal**, from the **bottom-left corner to the
+top-right corner**, each clipped to the tile and sitting **above the grain, below the
+letter**:
+
+- **Sheen** — white. Fully transparent at the bottom-left, rising to **15 % opacity** at
+  the top-right. Brightens the top-right.
+- **Shadow** — black. **15 % opacity** at the bottom-left, fading to transparent at the
+  top-right. Deepens the bottom-left.
+
+Together they give the tile a lit-from-the-top-right, resting-in-shadow-at-the-bottom-left
+sense of depth. Both percentages are a tuning knob (`--sheen`, `--shade`).
+
+## 5 — The letter «Э»
+
+- Typeface: **Spectral, Bold** (SIL OFL; pinned in the brand folder).
+- Glyph: the Cyrillic capital **«Э»** (U+042D).
+- Size: scale the glyph so its **ink bounding box is 60.5 % of the side tall** (its width
+  then follows the font — about 53.2 %).
+- Position: place the **center of that bounding box** at **48.1 % / 49.2 %** (just up and
+  left of the icon center).
+- Colour: **Ink**.
+
+## 6 — The star ✻
+
+A **six-spoke teardrop asterisk** (the "score" mark that replaces a tile's point number):
+
+- Each spoke tapers to a **point at the center** and ends in a **round bulb**; a central
+  disc equal to a bulb fuses the six spokes.
+- Outer diameter: **17.3 % of the side**.
+- Bulb radius (and the central disc): **22 % of the star's radius**.
+- Position: center at **78.8 % / 78.8 %** — tucked to the lower-right of the «Э», like a
+  subscript, with a clear gap from the letter.
+- Colour: **Ink**.
+
+Spectral has no ✻ glyph, so the star is **drawn geometrically**, not set as type. The exact
+construction is in `build-icon.mjs` (`starPath`).
+
+## Composition intent
+
+The «Э» and the ✻ are treated as **one group**. Its combined bounding box measures
+about **65.9 % × 68.6 %** of the side, and it is placed so its **bottom-right corner sits
+at 87.5 % / 87.5 %** of the icon (the lower-right corner of an inner `12.5 % … 87.5 %`
+safe square). That is what pushes the composition down-and-right and leaves the star room
+in the corner. When re-deriving positions, this is the anchor to preserve.
+
+> This bottom-right bias suits a **full-bleed** icon (iOS / PWA / favicon, which show
+> almost the whole square). Android crops more, so it uses a **separate two-layer build**
+> — see the next section. The master itself is never moved for Android.
+
+## Android adaptive icon (two layers)
+
+Android icons are **108×108 dp** and the OS applies its own mask (circle, squircle,
+rounded square…). Only the **inner 66 dp = 61 % of the side, centred** is guaranteed
+visible under every mask; the outer ~1/6 ring is used for the mask and motion effects.
+So Android is **not** the full-bleed master — it is built as two layers:
+
+- **Background** — the tile with wood grain and the light/shadow gradients, **full-bleed
+  and square** (no rounded corners; the OS supplies the shape). It fills the whole 108 dp
+  layer, so the sacrificial outer ring is just more wood.
+- **Foreground** — **only the «Э» + ✻**, transparent, **re-placed** to sit safely inside
+  the mask:
+  - «Э»: box height **53.9 %**, box center **52.3 % / 49.5 %**.
+  - ✻: outer diameter **13.2 %** (smaller than the master's), center **76.3 % / 72.7 %**,
+    tucked closer to the letter.
+  - The mark is centred, then nudged **right 8 % / down 3 %** so it reads optically
+    centred under the round mask, and the whole group fits within the **61 % safe zone**.
+
+Everything else (palette, grain, gradients, star construction) is identical to the master.
+
+## Variants in use
+
+The **light** variant is the primary icon (launcher, favicon, apple-touch, PWA). The
+**dark** variant is shipped in addition wherever the platform can pick by appearance
+(e.g. an SVG favicon via `prefers-color-scheme`). Where a platform allows only one icon,
+use **light**.
+
+## Reproduce
+
+```sh
+cd assets/icons/brand
+npm i opentype.js
+# full master (iOS / PWA / favicon), either variant:
+node build-icon.mjs --variant light --layer full        > icon-light.svg
+# Android adaptive layers:
+node build-icon.mjs --variant light --layer background   > icon-light-android-background.svg
+node build-icon.mjs --variant light --layer foreground   > icon-light-android-foreground.svg
+# the construction figure:
+node build-icon.mjs --variant light --scheme             > icon-construction.svg
+node render-png.mjs  icon-light.svg  icon-light.png  1024   # any size
+```
+
+`--layer` is `full` (default), `background`, or `foreground`. All outputs are committed
+alongside the generator in [`../assets/icons/brand/`](../assets/icons/brand/).
+
+## Masters
+
+| | Light | Dark |
+|-|-------|------|
+| **Full** (iOS / PWA / favicon) | ![light](../assets/icons/brand/icon-light.png) | ![dark](../assets/icons/brand/icon-dark.png) |
+| **Android background** | ![lbg](../assets/icons/brand/icon-light-android-background.png) | ![dbg](../assets/icons/brand/icon-dark-android-background.png) |
+| **Android foreground** | ![lfg](../assets/icons/brand/icon-light-android-foreground.png) | ![dfg](../assets/icons/brand/icon-dark-android-foreground.png) |

docs/PAYMENTS_DECISIONS_ru.md

@@ -201,7 +201,9 @@ web+PWA / native Android+iOS через Capacitor). Владелец (самоз
   начисления): Фишки, подсказки, дни-без-рекламы, участие-в-турнире. **Продукт = набор
   атомов + цена** (по одной ценности или комбо). «Пакет Фишек» — цена **per-метод**
   (мультивалютная: Голоса/Stars/руб — один продукт, D2). «Ценность за Фишки» — цена в
-  Фишках (единая). Курсы покупки Фишек и Фишки за rewarded — тоже в каталоге.
+  Фишках (единая). Курсы покупки Фишек и Фишки за rewarded — тоже в каталоге. (Ставка
+  rewarded + дневной/часовой потолки — строка общего конфига `payments.config`, правится в
+  секции «Rewarded ads» на странице каталога админки; это не продаваемый продукт-атом.)
 - **D33. Стекинг «без рекламы»:** `paid_until[origin] += срок` от `max(now, текущий
   конец)` (остаток не теряется, «плюсуются» как в документе). «Навсегда» — отдельный
   вечный флаг (перекрывает сроки). Бонусы «(+50)» — маркетинговая пометка владельца;

docs/TESTING.md

@@ -17,21 +17,43 @@ tests or touching CI.
 - **UI** — Vitest (unit) + Playwright
   (e2e), mirroring the chosen plain-Svelte + Vite toolchain. Vitest covers
   the FlatBuffers codecs (friend list, invitation, stats), the win-rate
-  derivation and the GCG share/copy/download choice, plus Playwright specs against the
+  derivation, the GCG share/copy/download choice and the **net-state reducer**
+  (`netstate.test.ts` — every transition of the connectivity/version machine, the anti-flap
+  hysteresis, the two-tier version decision and all 12 offline edge cases as pure assertions),
+  plus Playwright specs against the
   mock for the friends screen (code issue/redeem, accept a request), the lobby
   invitations section, the stats screen, profile editing, and the export chooser's
   finished-only visibility + its signed-URL download flow (route-intercepted). The
   **offline mode** spec (`e2e/offline.spec.ts`) plays a full device-local `vs_ai` game
-  end-to-end: it forces the installed-PWA display mode, enters offline through the
+  end-to-end: offline is **implicit** now (no toggle), so it drives the mock's `__net` hook to
-  Settings toggle (whose readiness check fetches the enabled variants' dawgs), then creates
+  auto-detect offline (asserting the toast, the greyed-from-cache server games and the disabled
-  and plays a local game with a **pinned bag seed** (`window.__mock.setLocalSeed`, so the
+  Stats tab), self-heals back online, then creates and plays a local game with a **pinned bag seed** (`window.__mock.setLocalSeed`, so the
   rack is deterministic and the human can tap out a precomputed opening), asserting the
   robot's real reply and the IndexedDB replay after a reload. A local game needs a real
   dictionary, so the mock's `fetchDict` serves the per-variant dawgs from the preview
   build's `/e2edict/`, copied in by `scripts/e2e-dict.mjs` from `E2E_DICT_DIR` — the `ui`
   CI job fetches the `scrabble-dictionary` release like the Go jobs; locally it defaults to
   the sibling `scrabble-solver/dawg`. These dawgs are never committed and never enter the
-  production build.
+  production build. The **native offline-first** spec (`e2e/native.spec.ts`) injects
+  `window.androidBridge` (so `@capacitor/core` resolves the platform to `android` — a bare
+  `Capacitor.getPlatform` stub is clobbered by the core shim), then asserts a no-session cold boot lands
+  in the **offline guest lobby** (not `/login`), plays a local vs_ai move from the **bundled** dawg tier
+  (`playwright.config.ts` bundles the dicts into `dist-e2e/dict/`), starts a hotseat game, and drives
+  `window.__native.reconcile()` to prove online lights up — the device-local game stays listed in the
+  **unified lobby** — and Profile hides the Telegram/VK link buttons.
+  The **version-gate** spec (`e2e/update.spec.ts`) drives the `__update` hook to prove both tiers — the
+  hard *Update / Play offline* notice (and that "Play offline" drops into the offline lobby) and the soft
+  dismissable *update available* nudge in the lobby; `retry.test.ts` covers the `FailedPrecondition →
+  update_required` mapping.
+- **Client-version gate** (Go, two tiers) — `gateway/internal/clientver` unit-tests the `v?MAJOR.MINOR.PATCH`
+  parse (with/without `v`, a `-N-gSHA` suffix, `dev`/empty ⇒ !ok) and ordering. `connectsrv`'s server tests
+  assert the **hard** tier — a too-old `Execute` returns `result_code = "update_required"` (and the op
+  handler never ran), a too-old `Subscribe` returns `FailedPrecondition`, and an absent header / empty min /
+  unparseable header / equal version all pass (fail-open) — and the **soft** tier (`TestExecuteUpdateRecommended`):
+  a served build in `min ≤ v < recommended` carries the `X-Update-Recommended: 1` response header, while a
+  too-old, up-to-date, absent/garbled, or dormant-tier request does not. `config` tests reject a non-empty
+  unparseable `GATEWAY_MIN_CLIENT_VERSION` / `GATEWAY_RECOMMENDED_CLIENT_VERSION`, and a recommended below the
+  minimum.
 - **Render sidecar** — `renderer/` (Node + skia-canvas executing the shared
   `ui/src/lib/gameimage.ts`) carries a `node --test` smoke: the committed fixture (a
   real self-played 35-move game) must rasterize to a plausible PNG
@@ -175,6 +197,16 @@ tests or touching CI.
   `inttest` drives the **feedback lifecycle** end to end: the guest / ban / pending gates, the reply
   read + one-week visibility window, the account-role grant/revoke, and the admin queue filters with
   delete / delete-all. The admin-console render test renders the feedback list + detail pages.
+- **Native Android (manual on-device smoke)** — the packaged APK is verified by hand on a device /
+  emulator before release (the automated e2e covers the offline-first logic; WebView-specific chrome and
+  store behaviour are not reproducible in Playwright). Checklist: installs and cold-launches; in
+  **airplane mode** the cold launch lands in the **guest lobby**; play a local **vs_ai** move and a
+  **2-player hotseat** game with no network; the hardware **Back** button navigates then exits at the
+  root; a share / export link resolves to `erudit-game.ru` (not `file://`); turning the **network on**
+  lights up online play (a server guest is established); Profile offers **email** sign-in but no
+  Telegram / VK link; and with `GATEWAY_MIN_CLIENT_VERSION` bumped above the build, an online action
+  raises the terminal **update** overlay. Measure native chrome (safe-area / edge-to-edge) by CDP, not by
+  eyeballing a screenshot — an emulator WebView may be newer than a user's device (see `.claude/CLAUDE.md`).
 
 ## Principles
 

gateway/Dockerfile

@@ -42,10 +42,15 @@ ENV VITE_TELEGRAM_BOT_ID=$VITE_TELEGRAM_BOT_ID \
     VITE_APP_VERSION=$VITE_APP_VERSION \
     VITE_ADS_STUB=$VITE_ADS_STUB
 
-# Install with the lockfile first (the workspace file carries pnpm's build-script
+# Install with the lockfile first, then build. Committed src/gen/ means no codegen here.
-# approval for esbuild), then build. Committed src/gen/ means no codegen here.
+# --ignore-scripts: the Vite build needs no dependency build script — esbuild's platform binary
+# ships as an optional dependency (only its CLI-shim postinstall is skipped, which Vite does not use),
+# and core-js-bundle's prebuilt file is read directly. It notably skips sharp's native build (a
+# `pnpm android:assets` tool via @capacitor/assets, unused here), which would otherwise fail on this
+# Alpine/musl stage with no prebuilt binary and no compiler. The workspace allowBuilds stay for local
+# installs (where android:assets does need sharp built).
 COPY ui/package.json ui/pnpm-lock.yaml ui/pnpm-workspace.yaml ./
-RUN pnpm install --frozen-lockfile
+RUN pnpm install --frozen-lockfile --ignore-scripts
 COPY ui ./
 RUN pnpm build
 

gateway/README.md

@@ -121,7 +121,8 @@ web code exchange via `internal/vkid`, and both forward the trusted `external_id
 Rate-limit defaults (built-in): public 30/min·IP (burst 10), authenticated
 300/min·user (burst 80, sized for multi-device play), admin
 60/min·IP (burst 20, guarding the `/_gm` mount ahead of its Basic-Auth),
-email-code 5/10 min·IP (burst 2).
+email-code 5/10 min·IP (burst 4, covering request + a mistyped code + the
+correct one; defence-in-depth over the backend's per-code 5-attempt/15-min cap).
 
 Every rejection increments `gateway_rate_limited_total{class}`
 (`user`/`public`/`email`/`admin`) and logs one Debug line; a reporter drains the

gateway/cmd/gateway/blocklist.go

@@ -0,0 +1,86 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+
+	"scrabble/gateway/internal/config"
+	"scrabble/gateway/internal/ratelimit"
+)
+
+const (
+	// blocklistFetchTimeout bounds one feed fetch.
+	blocklistFetchTimeout = 30 * time.Second
+	// maxBlocklistBytes caps the fetched feed (Spamhaus DROP is well under 1 MiB; the cap stops a
+	// hostile or misconfigured URL from streaming unbounded data into memory).
+	maxBlocklistBytes = 8 << 20
+)
+
+// parseAllowlist parses the never-block entries (CIDRs or bare IPs, a bare IP read as a /32) into
+// networks. A malformed entry is a fatal config error — the operator must fix it, not silently lose
+// a protected range.
+func parseAllowlist(entries []string) ([]*net.IPNet, error) {
+	out := make([]*net.IPNet, 0, len(entries))
+	for _, e := range entries {
+		s := strings.TrimSpace(e)
+		if s == "" {
+			continue
+		}
+		if !strings.Contains(s, "/") {
+			s += "/32"
+		}
+		_, n, err := net.ParseCIDR(s)
+		if err != nil {
+			return nil, fmt.Errorf("gateway: GATEWAY_BLOCKLIST_ALLOW: %q: %w", e, err)
+		}
+		out = append(out, n)
+	}
+	return out, nil
+}
+
+// runBlocklistRefresher keeps the community IP blocklist feed current: it fetches immediately, then
+// every cfg.Refresh, and applies each outcome through ratelimit.ApplyRefresh (keep-last-good on a
+// transient failure; drop the feed once it goes stale, fail-open). It returns when ctx is cancelled.
+func runBlocklistRefresher(ctx context.Context, bl *ratelimit.Blocklist, cfg config.BlocklistConfig, log *zap.Logger) {
+	client := &http.Client{Timeout: blocklistFetchTimeout}
+	for {
+		cidrs, err := fetchBlocklist(ctx, client, cfg.URL)
+		switch ratelimit.ApplyRefresh(bl, cidrs, err, time.Now(), cfg.MaxStaleness) {
+		case ratelimit.RefreshUpdated:
+			log.Info("blocklist refreshed", zap.String("url", cfg.URL), zap.Int("entries", bl.Len()))
+		case ratelimit.RefreshKept:
+			log.Warn("blocklist refresh failed; keeping the last-good feed", zap.Error(err))
+		case ratelimit.RefreshDropped:
+			log.Warn("blocklist refresh failed and the feed is stale; dropped it (fail-open)", zap.Error(err))
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(cfg.Refresh):
+		}
+	}
+}
+
+// fetchBlocklist GETs the feed and parses it, bounded by the fetch timeout and the size cap.
+func fetchBlocklist(ctx context.Context, client *http.Client, url string) ([]*net.IPNet, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("gateway: blocklist fetch %s: status %d", url, resp.StatusCode)
+	}
+	return ratelimit.ParseDROP(io.LimitReader(resp.Body, maxBlocklistBytes))
+}

gateway/cmd/gateway/main.go

@@ -129,6 +129,11 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 		Window:    cfg.Abuse.BanWindow,
 		Duration:  cfg.Abuse.BanDuration,
 	})
+	allow, err := parseAllowlist(cfg.Blocklist.Allow)
+	if err != nil {
+		return err
+	}
+	blocklist := ratelimit.NewBlocklist(cfg.Blocklist.Enabled, allow)
 	hub := push.NewHub(0)
 
 	var validator transcode.TelegramValidator
@@ -216,21 +221,24 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	}
 	registry := transcode.NewRegistry(backend, validator, regOpts...)
 	edge := connectsrv.NewServer(connectsrv.Deps{
-		Registry:     registry,
+		Registry:                 registry,
-		Sessions:     sessions,
+		Sessions:                 sessions,
-		Backend:      backend,
+		Backend:                  backend,
-		Limiter:      limiter,
+		Limiter:                  limiter,
-		Tracker:      tracker,
+		Tracker:                  tracker,
-		Banlist:      banlist,
+		Banlist:                  banlist,
-		Honeytoken:   cfg.Abuse.Honeytoken,
+		Blocklist:                blocklist,
-		VKAppSecret:  cfg.VKAppSecret,
+		Honeytoken:               cfg.Abuse.Honeytoken,
-		Hub:          hub,
+		VKAppSecret:              cfg.VKAppSecret,
-		RateLimit:    cfg.RateLimit,
+		Hub:                      hub,
-		Heartbeat:    cfg.PushHeartbeatInterval,
+		RateLimit:                cfg.RateLimit,
-		Logger:       logger,
+		Heartbeat:                cfg.PushHeartbeatInterval,
-		AdminProxy:   adminProxy,
+		Logger:                   logger,
-		Meter:        tel.MeterProvider().Meter("scrabble/gateway/edge"),
+		AdminProxy:               adminProxy,
-		MaxBodyBytes: cfg.MaxBodyBytes,
+		Meter:                    tel.MeterProvider().Meter("scrabble/gateway/edge"),
+		MaxBodyBytes:             cfg.MaxBodyBytes,
+		MinClientVersion:         cfg.MinClientVersion,
+		RecommendedClientVersion: cfg.RecommendedClientVersion,
 	})
 
 	// Bridge the backend push stream into the fan-out hub (and the out-of-app
@@ -243,6 +251,10 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	if cfg.Abuse.BanEnabled {
 		go runBanSync(ctx, banlist, backend, logger)
 	}
+	// When the edge blocklist is enabled (prod), keep the community feed refreshed.
+	if cfg.Blocklist.Enabled {
+		go runBlocklistRefresher(ctx, blocklist, cfg.Blocklist, logger)
+	}
 
 	public := &http.Server{Addr: cfg.HTTPAddr, Handler: edge.HTTPHandler(), ReadHeaderTimeout: readHeaderTimeout}
 	servers := []*namedServer{{name: "public", srv: public}}

gateway/internal/botlink/hub.go

@@ -76,6 +76,11 @@ type Hub struct {
 
 	connected metric.Int64UpDownCounter
 	commands  metric.Int64Counter
+	// tgErrors counts the remote bot's Bot API failures it reports over the stream, by kind
+	// (connect / api / rate_limited). lastOK holds the wall-clock second of the bot's most recent
+	// successful Bot API call, read by the bot_tg_last_ok_unix observable gauge for a staleness alert.
+	tgErrors metric.Int64Counter
+	lastOK   atomic.Int64
 }
 
 // link is one connected bot's outbound queue and identity.
@@ -103,6 +108,19 @@ func NewHub(log *zap.Logger, meter metric.Meter, resolve EligibilityResolver) *H
 			metric.WithDescription("Number of Telegram bots currently connected to the gateway bot-link."))
 		h.commands, _ = meter.Int64Counter("botlink_commands_total",
 			metric.WithDescription("Bot-link send commands by result (delivered, not_delivered, dropped, error)."))
+		h.tgErrors, _ = meter.Int64Counter("bot_tg_errors_total",
+			metric.WithDescription("Telegram Bot API failures the remote bot reports over the bot-link, by kind (connect, api, rate_limited)."))
+		// The bot's last successful Bot API second, reported over the stream. An observable gauge
+		// reads the atomic on each collection; it observes nothing until a bot has reported, so a
+		// never-connected gateway shows no data (the connected-bots alert covers that case).
+		_, _ = meter.Int64ObservableGauge("bot_tg_last_ok_unix",
+			metric.WithDescription("Unix second of the remote bot's most recent successful Bot API call (0/absent until reported)."),
+			metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
+				if v := h.lastOK.Load(); v > 0 {
+					o.Observe(v)
+				}
+				return nil
+			}))
 	}
 	return h
 }
@@ -149,6 +167,36 @@ func (h *Hub) Link(stream grpc.BidiStreamingServer[botlinkv1.FromBot, botlinkv1.
 		if ack := msg.GetAck(); ack != nil {
 			h.resolve(ack)
 		}
+		if hb := msg.GetHealth(); hb != nil {
+			h.recordHealth(hb)
+		}
+	}
+}
+
+// recordHealth folds one bot Health report into the gateway's cumulative Bot API metrics: the three
+// delta counters are added under their kind label, and the last-ok stamp (an absolute wall-clock
+// second) advances the liveness gauge (monotonically — a stale reordered report cannot rewind it).
+func (h *Hub) recordHealth(hb *botlinkv1.Health) {
+	if h.tgErrors != nil {
+		ctx := context.Background()
+		if v := hb.GetConnectFailures(); v > 0 {
+			h.tgErrors.Add(ctx, int64(v), metric.WithAttributes(attribute.String("kind", "connect")))
+		}
+		if v := hb.GetApiErrors(); v > 0 {
+			h.tgErrors.Add(ctx, int64(v), metric.WithAttributes(attribute.String("kind", "api")))
+		}
+		if v := hb.GetRateLimited(); v > 0 {
+			h.tgErrors.Add(ctx, int64(v), metric.WithAttributes(attribute.String("kind", "rate_limited")))
+		}
+	}
+	for {
+		cur := h.lastOK.Load()
+		if hb.GetLastOkUnix() <= cur {
+			break
+		}
+		if h.lastOK.CompareAndSwap(cur, hb.GetLastOkUnix()) {
+			break
+		}
 	}
 }
 

gateway/internal/botlink/hub_test.go

@@ -233,3 +233,21 @@ func TestRelayServerNoBot(t *testing.T) {
 		t.Fatal("expected an error with no bot connected")
 	}
 }
+
+// TestRecordHealthLastOKMonotonic checks a bot Health report advances the last-ok liveness stamp but
+// a stale or reordered report (an earlier second) never rewinds it.
+func TestRecordHealthLastOKMonotonic(t *testing.T) {
+	hub := NewHub(nil, nil, nil)
+	hub.recordHealth(&botlinkv1.Health{LastOkUnix: 100})
+	if got := hub.lastOK.Load(); got != 100 {
+		t.Fatalf("lastOK = %d, want 100", got)
+	}
+	hub.recordHealth(&botlinkv1.Health{LastOkUnix: 90}) // reordered/stale — must not rewind
+	if got := hub.lastOK.Load(); got != 100 {
+		t.Errorf("lastOK rewound to %d, want 100", got)
+	}
+	hub.recordHealth(&botlinkv1.Health{LastOkUnix: 150})
+	if got := hub.lastOK.Load(); got != 150 {
+		t.Errorf("lastOK = %d, want 150", got)
+	}
+}

gateway/internal/clientver/clientver.go

@@ -0,0 +1,57 @@
+// Package clientver parses and compares the leading MAJOR.MINOR.PATCH of a client
+// version string so the edge can turn away a build too old to speak the current wire
+// contract. It is deliberately dependency-free and tolerant: the version rides an HTTP
+// header (X-Client-Version) that a build stamps from `git describe --tags`, so any
+// `-N-gSHA` or `+meta` suffix is ignored, and anything unparseable is reported as such
+// (the caller fails open — an absent or garbled header is never treated as too old).
+package clientver
+
+import (
+	"strconv"
+	"strings"
+)
+
+// Version is a parsed semantic version triple. Only MAJOR.MINOR.PATCH participate in the
+// ordering; any pre-release or build suffix is dropped at parse time.
+type Version struct {
+	Major, Minor, Patch int
+}
+
+// Parse extracts the leading MAJOR.MINOR.PATCH from s, tolerating an optional leading
+// "v" and any `-N-gSHA` or `+meta` suffix (as produced by `git describe --tags`). It
+// reports ok=false when s has fewer than three numeric components or any component is not
+// an integer, so the caller can distinguish a real version from a dev/empty string.
+func Parse(s string) (Version, bool) {
+	s = strings.TrimPrefix(strings.TrimSpace(s), "v")
+	if i := strings.IndexAny(s, "-+"); i >= 0 {
+		s = s[:i]
+	}
+	p := strings.SplitN(s, ".", 4)
+	if len(p) < 3 {
+		return Version{}, false
+	}
+	var v Version
+	var err error
+	if v.Major, err = strconv.Atoi(p[0]); err != nil {
+		return Version{}, false
+	}
+	if v.Minor, err = strconv.Atoi(p[1]); err != nil {
+		return Version{}, false
+	}
+	if v.Patch, err = strconv.Atoi(p[2]); err != nil {
+		return Version{}, false
+	}
+	return v, true
+}
+
+// Less reports whether a orders before b by MAJOR, then MINOR, then PATCH. Equal versions
+// are not Less than each other, so a client exactly at the minimum passes the gate.
+func Less(a, b Version) bool {
+	if a.Major != b.Major {
+		return a.Major < b.Major
+	}
+	if a.Minor != b.Minor {
+		return a.Minor < b.Minor
+	}
+	return a.Patch < b.Patch
+}

gateway/internal/clientver/clientver_test.go

@@ -0,0 +1,63 @@
+package clientver
+
+import "testing"
+
+// TestParse covers the version strings the edge actually sees: a plain and a "v"-prefixed
+// triple, a `git describe --tags` suffix, build metadata, surrounding space, and the
+// non-version strings (dev/empty/too-few/non-numeric) that must report ok=false so the
+// gate fails open.
+func TestParse(t *testing.T) {
+	tests := []struct {
+		name  string
+		in    string
+		want  Version
+		wantK bool
+	}{
+		{"plain", "1.16.0", Version{1, 16, 0}, true},
+		{"v-prefixed", "v1.16.0", Version{1, 16, 0}, true},
+		{"git describe suffix", "v1.16.0-3-gabc1234", Version{1, 16, 0}, true},
+		{"build metadata", "1.16.0+ci42", Version{1, 16, 0}, true},
+		{"surrounding space", "  v2.0.1 ", Version{2, 0, 1}, true},
+		{"extra component ignored", "v1.16.0.4", Version{1, 16, 0}, true},
+		{"dev", "dev", Version{}, false},
+		{"empty", "", Version{}, false},
+		{"too few components", "1.16", Version{}, false},
+		{"non-numeric patch", "1.16.x", Version{}, false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, ok := Parse(tc.in)
+			if ok != tc.wantK {
+				t.Fatalf("Parse(%q) ok = %v, want %v", tc.in, ok, tc.wantK)
+			}
+			if ok && got != tc.want {
+				t.Errorf("Parse(%q) = %+v, want %+v", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestLess covers the ordering by MAJOR, then MINOR, then PATCH, and that an equal version
+// is not Less (a client exactly at the minimum passes the gate).
+func TestLess(t *testing.T) {
+	tests := []struct {
+		name string
+		a, b Version
+		want bool
+	}{
+		{"equal", Version{1, 16, 0}, Version{1, 16, 0}, false},
+		{"major less", Version{1, 9, 9}, Version{2, 0, 0}, true},
+		{"major greater", Version{2, 0, 0}, Version{1, 9, 9}, false},
+		{"minor less", Version{1, 16, 5}, Version{1, 17, 0}, true},
+		{"minor greater", Version{1, 17, 0}, Version{1, 16, 9}, false},
+		{"patch less", Version{1, 16, 0}, Version{1, 16, 1}, true},
+		{"patch greater", Version{1, 16, 2}, Version{1, 16, 1}, false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := Less(tc.a, tc.b); got != tc.want {
+				t.Errorf("Less(%+v, %+v) = %v, want %v", tc.a, tc.b, got, tc.want)
+			}
+		})
+	}
+}

gateway/internal/config/config.go

@@ -6,8 +6,10 @@ import (
 	"fmt"
 	"os"
 	"strconv"
+	"strings"
 	"time"
 
+	"scrabble/gateway/internal/clientver"
 	pkgtel "scrabble/pkg/telemetry"
 )
 
@@ -53,10 +55,22 @@ type Config struct {
 	// MaxBodyBytes caps one inbound request body on the public listener and one
 	// Connect message read; oversized requests are refused without buffering.
 	MaxBodyBytes int
+	// MinClientVersion, when non-empty, is the lowest client version (MAJOR.MINOR.PATCH)
+	// the edge serves. A client reporting an older X-Client-Version is turned away with an
+	// "update required" signal before its payload is decoded. Empty leaves the gate dormant
+	// (every client is served) — the default for web-only deployments.
+	MinClientVersion string
+	// RecommendedClientVersion, when non-empty, is the version below which a served client is nudged
+	// to update — a non-blocking "update available" signal (the X-Update-Recommended response header)
+	// on gated responses; the call still succeeds. It must be at least MinClientVersion. Empty leaves
+	// the soft tier off (the default); it does not affect the hard MinClientVersion gate.
+	RecommendedClientVersion string
 	// RateLimit configures the in-memory anti-abuse limiter.
 	RateLimit RateLimitConfig
 	// Abuse configures the temporary IP ban and the honeytoken (prod-only).
 	Abuse AbuseConfig
+	// Blocklist configures the community IP blocklist (Spamhaus DROP) enforced at the edge (prod-only).
+	Blocklist BlocklistConfig
 	// Telemetry configures the OpenTelemetry providers (shared bootstrap).
 	Telemetry pkgtel.Config
 }
@@ -151,7 +165,12 @@ func DefaultRateLimit() RateLimitConfig {
 		// because multi-device play tripped the old 120/40.
 		UserPerMinute: 300, UserBurst: 80,
 		AdminPerMinute: 60, AdminBurst: 20,
-		EmailPer10Min: 5, EmailBurst: 2,
+		// Email-code path (per IP), defence-in-depth over the backend's own per-code guards
+		// (a 5-attempt cap + 15-min TTL + per-recipient send throttle). Burst 4 so the honest flow
+		// — request a code, mistype once or twice, then enter the right one — is not throttled
+		// mid-login: a request + wrong-code + right-code sequence exhausted the old burst of 2 and
+		// tripped the limit on the correct code, which the client mis-read as going offline.
+		EmailPer10Min: 5, EmailBurst: 4,
 	}
 }
 
@@ -166,6 +185,42 @@ func DefaultAbuse() AbuseConfig {
 	}
 }
 
+// BlocklistConfig configures the community IP blocklist (a curated CIDR feed such as Spamhaus DROP)
+// enforced at the edge alongside the fail2ban ban. Disabled by default and prod-only, for the same
+// reason as the ban: it is only safe where the real client IP is visible (not behind the shared-NAT
+// test contour). Only IPv4 is matched.
+type BlocklistConfig struct {
+	// Enabled turns edge blocklisting on. Off by default (prod-only).
+	Enabled bool
+	// URL is the CIDR feed to fetch (e.g. the Spamhaus DROP list). Required when Enabled; the
+	// operator sets it explicitly so no feed URL is assumed.
+	URL string
+	// Refresh is how often the feed is re-fetched.
+	Refresh time.Duration
+	// MaxStaleness is how long a stale feed (no successful refresh) is tolerated before it is dropped
+	// (fail-open — a legitimate client is never blocked on a frozen feed).
+	MaxStaleness time.Duration
+	// Allow is the never-block set: CIDRs or bare IPs (own infrastructure, monitoring, known-good) that
+	// the feed can never block. Parsed at startup.
+	Allow []string
+}
+
+// Blocklist defaults; the feed URL has no default (the operator sets it).
+const (
+	defaultBlocklistRefresh      = 6 * time.Hour
+	defaultBlocklistMaxStaleness = 48 * time.Hour
+)
+
+// DefaultBlocklist returns the built-in blocklist settings: disabled (prod-only), no feed URL, and
+// the agreed refresh / staleness windows.
+func DefaultBlocklist() BlocklistConfig {
+	return BlocklistConfig{
+		Enabled:      false,
+		Refresh:      defaultBlocklistRefresh,
+		MaxStaleness: defaultBlocklistMaxStaleness,
+	}
+}
+
 // VKIDConfig holds the VK ID web-login credentials for the confidential
 // authorization-code exchange. AppID is the VK "Web" app's client id; ClientSecret is
 // its protected key; RedirectURI must exactly match the trusted redirect URL registered
@@ -187,14 +242,16 @@ func (c VKIDConfig) Enabled() bool {
 func Load() (Config, error) {
 	var err error
 	c := Config{
-		HTTPAddr:        envOr("GATEWAY_HTTP_ADDR", defaultHTTPAddr),
+		HTTPAddr:                 envOr("GATEWAY_HTTP_ADDR", defaultHTTPAddr),
-		LogLevel:        envOr("GATEWAY_LOG_LEVEL", defaultLogLevel),
+		LogLevel:                 envOr("GATEWAY_LOG_LEVEL", defaultLogLevel),
-		BackendHTTPURL:  envOr("GATEWAY_BACKEND_HTTP_URL", defaultBackendHTTPURL),
+		BackendHTTPURL:           envOr("GATEWAY_BACKEND_HTTP_URL", defaultBackendHTTPURL),
-		BackendGRPCAddr: envOr("GATEWAY_BACKEND_GRPC_ADDR", defaultBackendGRPCAddr),
+		BackendGRPCAddr:          envOr("GATEWAY_BACKEND_GRPC_ADDR", defaultBackendGRPCAddr),
-		AdminUser:       os.Getenv("GATEWAY_ADMIN_USER"),
+		AdminUser:                os.Getenv("GATEWAY_ADMIN_USER"),
-		AdminPassword:   os.Getenv("GATEWAY_ADMIN_PASSWORD"),
+		AdminPassword:            os.Getenv("GATEWAY_ADMIN_PASSWORD"),
-		ValidatorAddr:   os.Getenv("GATEWAY_VALIDATOR_ADDR"),
+		ValidatorAddr:            os.Getenv("GATEWAY_VALIDATOR_ADDR"),
-		VKAppSecret:     os.Getenv("GATEWAY_VK_APP_SECRET"),
+		VKAppSecret:              os.Getenv("GATEWAY_VK_APP_SECRET"),
+		MinClientVersion:         os.Getenv("GATEWAY_MIN_CLIENT_VERSION"),
+		RecommendedClientVersion: os.Getenv("GATEWAY_RECOMMENDED_CLIENT_VERSION"),
 		VKID: VKIDConfig{
 			AppID:        os.Getenv("GATEWAY_VK_ID_APP_ID"),
 			ClientSecret: os.Getenv("GATEWAY_VK_ID_CLIENT_SECRET"),
@@ -203,6 +260,7 @@ func Load() (Config, error) {
 		SessionCacheMax: defaultSessionCacheMax,
 		RateLimit:       DefaultRateLimit(),
 		Abuse:           DefaultAbuse(),
+		Blocklist:       DefaultBlocklist(),
 		BotLink: BotLinkConfig{
 			Addr:      os.Getenv("GATEWAY_BOTLINK_ADDR"),
 			RelayAddr: os.Getenv("GATEWAY_BOTLINK_RELAY_ADDR"),
@@ -244,6 +302,17 @@ func Load() (Config, error) {
 	if c.Abuse.BanDuration, err = envDuration("GATEWAY_ABUSE_BAN_DURATION", c.Abuse.BanDuration); err != nil {
 		return Config{}, err
 	}
+	if c.Blocklist.Enabled, err = envBool("GATEWAY_BLOCKLIST_ENABLED", c.Blocklist.Enabled); err != nil {
+		return Config{}, err
+	}
+	c.Blocklist.URL = os.Getenv("GATEWAY_BLOCKLIST_URL")
+	if c.Blocklist.Refresh, err = envDuration("GATEWAY_BLOCKLIST_REFRESH", c.Blocklist.Refresh); err != nil {
+		return Config{}, err
+	}
+	if c.Blocklist.MaxStaleness, err = envDuration("GATEWAY_BLOCKLIST_MAX_STALENESS", c.Blocklist.MaxStaleness); err != nil {
+		return Config{}, err
+	}
+	c.Blocklist.Allow = splitList(os.Getenv("GATEWAY_BLOCKLIST_ALLOW"))
 	if c.BotLink.SendTimeout, err = envDuration("GATEWAY_BOTLINK_SEND_TIMEOUT", defaultBotLinkSendTimeout); err != nil {
 		return Config{}, err
 	}
@@ -281,9 +350,29 @@ func (c Config) validate() error {
 	if c.MaxBodyBytes <= 0 {
 		return fmt.Errorf("config: GATEWAY_MAX_BODY_BYTES must be positive")
 	}
+	if c.MinClientVersion != "" {
+		if _, ok := clientver.Parse(c.MinClientVersion); !ok {
+			return fmt.Errorf("config: GATEWAY_MIN_CLIENT_VERSION %q is not a MAJOR.MINOR.PATCH version", c.MinClientVersion)
+		}
+	}
+	if c.RecommendedClientVersion != "" {
+		rec, ok := clientver.Parse(c.RecommendedClientVersion)
+		if !ok {
+			return fmt.Errorf("config: GATEWAY_RECOMMENDED_CLIENT_VERSION %q is not a MAJOR.MINOR.PATCH version", c.RecommendedClientVersion)
+		}
+		// The soft tier must sit at or above the hard minimum: a recommended below the minimum is a
+		// misconfiguration (every client below min is already turned away). An empty/unparseable
+		// minimum imposes no lower bound, so the recommended may stand alone.
+		if min, ok := clientver.Parse(c.MinClientVersion); ok && clientver.Less(rec, min) {
+			return fmt.Errorf("config: GATEWAY_RECOMMENDED_CLIENT_VERSION %q must be >= GATEWAY_MIN_CLIENT_VERSION %q", c.RecommendedClientVersion, c.MinClientVersion)
+		}
+	}
 	if c.Abuse.BanEnabled && (c.Abuse.BanThreshold <= 0 || c.Abuse.BanWindow <= 0 || c.Abuse.BanDuration <= 0) {
 		return fmt.Errorf("config: GATEWAY_ABUSE_BAN_THRESHOLD/_WINDOW/_DURATION must be positive when GATEWAY_ABUSE_BAN_ENABLED")
 	}
+	if c.Blocklist.Enabled && (c.Blocklist.URL == "" || c.Blocklist.Refresh <= 0 || c.Blocklist.MaxStaleness <= 0) {
+		return fmt.Errorf("config: GATEWAY_BLOCKLIST_URL must be set and _REFRESH/_MAX_STALENESS positive when GATEWAY_BLOCKLIST_ENABLED")
+	}
 	if c.BotLink.Addr != "" {
 		if c.BotLink.CertFile == "" || c.BotLink.KeyFile == "" || c.BotLink.CAFile == "" {
 			return fmt.Errorf("config: GATEWAY_BOTLINK_ADDR requires GATEWAY_BOTLINK_TLS_CERT, _KEY and _CA")
@@ -304,6 +393,21 @@ func envOr(key, fallback string) string {
 	return fallback
 }
 
+// splitList splits a comma-separated environment value into trimmed, non-empty items.
+func splitList(v string) []string {
+	if v == "" {
+		return nil
+	}
+	parts := strings.Split(v, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
 // envBool parses the environment variable named key as a bool, returning fallback
 // when it is unset and an error when it is set but malformed.
 func envBool(key string, fallback bool) (bool, error) {

gateway/internal/config/config_test.go

@@ -47,6 +47,65 @@ func TestLoadMaxBodyBytes(t *testing.T) {
 	}
 }
 
+// TestLoadMinClientVersion verifies the client-version gate config: dormant (empty) by
+// default, a parseable version accepted, and an unparseable one rejected.
+func TestLoadMinClientVersion(t *testing.T) {
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if c.MinClientVersion != "" {
+		t.Errorf("MinClientVersion = %q, want empty (gate dormant)", c.MinClientVersion)
+	}
+	t.Setenv("GATEWAY_MIN_CLIENT_VERSION", "v1.16.0")
+	if c, err = Load(); err != nil {
+		t.Fatalf("Load with a valid min version: %v", err)
+	}
+	if c.MinClientVersion != "v1.16.0" {
+		t.Errorf("MinClientVersion = %q, want %q", c.MinClientVersion, "v1.16.0")
+	}
+	t.Setenv("GATEWAY_MIN_CLIENT_VERSION", "dev")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for an unparseable GATEWAY_MIN_CLIENT_VERSION, got nil")
+	}
+}
+
+// TestLoadRecommendedClientVersion verifies the soft-tier config: dormant (empty) by default, a
+// parseable version accepted (standing alone with no minimum, or at/above one), an unparseable one
+// rejected, and a recommended below the minimum rejected.
+func TestLoadRecommendedClientVersion(t *testing.T) {
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if c.RecommendedClientVersion != "" {
+		t.Errorf("RecommendedClientVersion = %q, want empty (soft tier dormant)", c.RecommendedClientVersion)
+	}
+	// Stands alone with no minimum configured.
+	t.Setenv("GATEWAY_RECOMMENDED_CLIENT_VERSION", "v1.20.0")
+	if c, err = Load(); err != nil {
+		t.Fatalf("Load with a valid recommended version (no min): %v", err)
+	}
+	if c.RecommendedClientVersion != "v1.20.0" {
+		t.Errorf("RecommendedClientVersion = %q, want %q", c.RecommendedClientVersion, "v1.20.0")
+	}
+	// At or above the minimum is accepted.
+	t.Setenv("GATEWAY_MIN_CLIENT_VERSION", "v1.16.0")
+	if _, err = Load(); err != nil {
+		t.Fatalf("Load with recommended >= min: %v", err)
+	}
+	// Below the minimum is rejected.
+	t.Setenv("GATEWAY_RECOMMENDED_CLIENT_VERSION", "v1.10.0")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for a recommended version below the minimum, got nil")
+	}
+	// Unparseable is rejected.
+	t.Setenv("GATEWAY_RECOMMENDED_CLIENT_VERSION", "dev")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for an unparseable GATEWAY_RECOMMENDED_CLIENT_VERSION, got nil")
+	}
+}
+
 // TestLoadAbuseDefaults verifies the anti-abuse ban defaults: disabled (prod-only),
 // the agreed thresholds, and no honeytoken.
 func TestLoadAbuseDefaults(t *testing.T) {

gateway/internal/connectsrv/abuse_test.go

@@ -2,6 +2,7 @@ package connectsrv_test
 
 import (
 	"context"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -24,7 +25,7 @@ const honeypotHeader = "X-Scrabble-Honeypot"
 
 // guardedEdge wires an edge with an explicit banlist and honeytoken over a fake
 // backend, returning the front URL, a Connect client and a cleanup func.
-func guardedEdge(t *testing.T, bl *ratelimit.Banlist, honeytoken string, limits config.RateLimitConfig, backendHandler http.HandlerFunc) (string, edgev1connect.GatewayClient, func()) {
+func guardedEdge(t *testing.T, bl *ratelimit.Banlist, block *ratelimit.Blocklist, honeytoken string, limits config.RateLimitConfig, backendHandler http.HandlerFunc) (string, edgev1connect.GatewayClient, func()) {
 	t.Helper()
 	backendSrv := httptest.NewServer(backendHandler)
 	backend, err := backendclient.New(backendSrv.URL, "localhost:9090", 2*time.Second)
@@ -36,6 +37,7 @@ func guardedEdge(t *testing.T, bl *ratelimit.Banlist, honeytoken string, limits
 		Sessions:   session.NewCache(backend, time.Minute, 100),
 		Limiter:    ratelimit.New(),
 		Banlist:    bl,
+		Blocklist:  block,
 		Honeytoken: honeytoken,
 		Hub:        push.NewHub(0),
 		RateLimit:  limits,
@@ -69,7 +71,7 @@ func enabledBanlist(threshold int) *ratelimit.Banlist {
 func TestAbuseGuardBlocksBannedIP(t *testing.T) {
 	bl := enabledBanlist(100)
 	bl.BanNow("127.0.0.1", ratelimit.ReasonTripwire)
-	url, _, cleanup := guardedEdge(t, bl, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
+	url, _, cleanup := guardedEdge(t, bl, nil, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
 	defer cleanup()
 
 	resp, err := noRedirect().Get(url + "/")
@@ -86,7 +88,7 @@ func TestAbuseGuardBlocksBannedIP(t *testing.T) {
 // and bans the client IP, so the next request is blocked.
 func TestHoneypotHeaderTrips(t *testing.T) {
 	bl := enabledBanlist(100)
-	url, _, cleanup := guardedEdge(t, bl, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
+	url, _, cleanup := guardedEdge(t, bl, nil, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
 		t.Error("backend must not be called for a honeypot hit")
 	})
 	defer cleanup()
@@ -118,7 +120,7 @@ func TestHoneypotHeaderTrips(t *testing.T) {
 // banlist still 404s the decoy (detection/logging) but bans nothing.
 func TestHoneypotDetectsWithoutBanWhenDisabled(t *testing.T) {
 	bl := ratelimit.NewBanlist(ratelimit.BanConfig{}) // disabled
-	url, _, cleanup := guardedEdge(t, bl, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
+	url, _, cleanup := guardedEdge(t, bl, nil, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
 	defer cleanup()
 
 	req, _ := http.NewRequest(http.MethodGet, url+"/.env", nil)
@@ -150,7 +152,7 @@ func TestPublicRejectionStrikesBan(t *testing.T) {
 	bl := enabledBanlist(1)
 	limits := config.DefaultRateLimit()
 	limits.PublicPerMinute, limits.PublicBurst = 1, 1
-	_, client, cleanup := guardedEdge(t, bl, "", limits, func(w http.ResponseWriter, r *http.Request) {
+	_, client, cleanup := guardedEdge(t, bl, nil, "", limits, func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(`{"token":"tok","user_id":"u-1","is_guest":true,"display_name":"Guest"}`))
 	})
 	defer cleanup()
@@ -173,7 +175,7 @@ func TestUserRejectionDoesNotBan(t *testing.T) {
 	bl := enabledBanlist(1)
 	limits := config.DefaultRateLimit()
 	limits.UserPerMinute, limits.UserBurst = 1, 1
-	_, client, cleanup := guardedEdge(t, bl, "", limits, func(w http.ResponseWriter, r *http.Request) {
+	_, client, cleanup := guardedEdge(t, bl, nil, "", limits, func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
 		case "/api/v1/internal/sessions/resolve":
 			_, _ = w.Write([]byte(`{"user_id":"u-1","is_guest":false}`))
@@ -202,7 +204,7 @@ func TestUserRejectionDoesNotBan(t *testing.T) {
 // caller and returns the ordinary invalid-session error without a backend call.
 func TestHoneytokenBansAndRejects(t *testing.T) {
 	bl := enabledBanlist(100)
-	_, client, cleanup := guardedEdge(t, bl, "s3cr3t-trap", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
+	_, client, cleanup := guardedEdge(t, bl, nil, "s3cr3t-trap", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
 		t.Error("backend must not be called for the honeytoken")
 	})
 	defer cleanup()
@@ -217,3 +219,25 @@ func TestHoneytokenBansAndRejects(t *testing.T) {
 		t.Fatal("the honeytoken must ban the caller")
 	}
 }
+
+// TestAbuseGuardBlocksBlocklistedIP verifies a client IP in the community blocklist feed is refused
+// with 403 at the HTTP layer, before any handler runs.
+func TestAbuseGuardBlocksBlocklistedIP(t *testing.T) {
+	block := ratelimit.NewBlocklist(true, nil)
+	_, feed, err := net.ParseCIDR("127.0.0.0/8")
+	if err != nil {
+		t.Fatal(err)
+	}
+	block.SetCIDRs([]*net.IPNet{feed}, time.Now())
+	url, _, cleanup := guardedEdge(t, nil, block, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
+	defer cleanup()
+
+	resp, err := noRedirect().Get(url + "/")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("blocklisted GET / = %d, want 403", resp.StatusCode)
+	}
+}

gateway/internal/connectsrv/errors.go

@@ -12,6 +12,7 @@ var (
 	errInternal       = errors.New("internal error")
 	errMissingToken   = errors.New("missing session token")
 	errInvalidSession = errors.New("invalid or expired session")
+	errUpdateRequired = errors.New("client too old, update required")
 )
 
 // errUnknownMessageType reports an unregistered message type.

gateway/internal/connectsrv/metrics.go

@@ -7,6 +7,8 @@ import (
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/metric"
 	"go.opentelemetry.io/otel/metric/noop"
+
+	"scrabble/gateway/internal/ratelimit"
 )
 
 // meterName scopes the gateway edge's OpenTelemetry instruments.
@@ -27,6 +29,7 @@ type serverMetrics struct {
 	edge        metric.Float64Histogram
 	rateLimited metric.Int64Counter
 	banned      metric.Int64Counter
+	blocklisted metric.Int64Counter
 	active      *activeUsers
 	// Client-reported local move-preview adoption (see localEvalMetricsHandler).
 	localColdStart metric.Int64Counter
@@ -40,7 +43,7 @@ type serverMetrics struct {
 // falling back to a no-op histogram on the (rare) construction error. The
 // active_users gauge is registered as an observable callback over the in-memory
 // tracker.
-func newServerMetrics(meter metric.Meter) *serverMetrics {
+func newServerMetrics(meter metric.Meter, bl *ratelimit.Blocklist) *serverMetrics {
 	if meter == nil {
 		meter = noop.NewMeterProvider().Meter(meterName)
 	}
@@ -68,6 +71,8 @@ func newServerMetrics(meter metric.Meter) *serverMetrics {
 	}
 	m := &serverMetrics{
 		edge: h, rateLimited: c, banned: b, active: newActiveUsers(),
+		blocklisted: counterOf(meter, "gateway_blocklist_blocked_total",
+			"Requests refused at the edge by the community IP blocklist (Spamhaus DROP)."),
 		localColdStart: counterOf(meter, "local_eval_cold_start_total", "App cold starts reported by clients — the denominator for local-move-preview adoption."),
 		localDictLoad:  counterOf(meter, "local_eval_dict_load_total", "Client dictionary loads for the local move preview, by result (fetched, cache_hit or miss)."),
 		localPreview:   counterOf(meter, "local_eval_preview_total", "Client move previews, by path (local on-device, or network fallback)."),
@@ -90,6 +95,25 @@ func newServerMetrics(meter metric.Meter) *serverMetrics {
 			return nil
 		}, gauge)
 	}
+
+	// Community blocklist status: the feed size and how stale it is, for the dashboard and the
+	// "feed not refreshing" alert. Age is observed only once a feed has loaded, so a disabled or
+	// never-fetched blocklist reports no age (and entries 0).
+	if bl != nil {
+		entries, e1 := meter.Int64ObservableGauge("gateway_blocklist_entries",
+			metric.WithDescription("CIDR ranges in the active community IP blocklist feed."))
+		age, e2 := meter.Float64ObservableGauge("gateway_blocklist_age_seconds",
+			metric.WithDescription("Seconds since the community IP blocklist feed was last successfully fetched (absent until the first fetch)."))
+		if e1 == nil && e2 == nil {
+			_, _ = meter.RegisterCallback(func(_ context.Context, o metric.Observer) error {
+				o.ObserveInt64(entries, int64(bl.Len()))
+				if last := bl.LastFetch(); !last.IsZero() {
+					o.ObserveFloat64(age, time.Since(last).Seconds())
+				}
+				return nil
+			}, entries, age)
+		}
+	}
 	return m
 }
 
@@ -118,6 +142,11 @@ func (m *serverMetrics) recordBan(ctx context.Context, reason string) {
 	m.banned.Add(ctx, 1, metric.WithAttributes(attribute.String("reason", reason)))
 }
 
+// recordBlocklistBlock counts one request refused by the community IP blocklist.
+func (m *serverMetrics) recordBlocklistBlock(ctx context.Context) {
+	m.blocklisted.Add(ctx, 1)
+}
+
 // recordUnsupportedEngine counts one client turned away by the unsupported-engine boot screen,
 // labelled by reason and Chromium major. The caller passes both already reduced to bounded label
 // sets (see normalizeUnsupported) so a spoofed beacon cannot explode the metric cardinality.

gateway/internal/connectsrv/metrics_test.go

@@ -16,7 +16,7 @@ func TestEdgeMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordEdge(ctx, "game.submit_play", "ok", time.Now().Add(-time.Millisecond))
 	m.recordEdge(ctx, "game.submit_play", "ok", time.Now().Add(-time.Millisecond))
@@ -74,7 +74,7 @@ func TestRateLimitedMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordRateLimited(ctx, "user")
 	m.recordRateLimited(ctx, "user")
@@ -112,7 +112,7 @@ func TestBannedMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordBan(ctx, "tripwire")
 	m.recordBan(ctx, "tripwire")
@@ -150,7 +150,7 @@ func TestUnsupportedEngineMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordUnsupportedEngine(ctx, "no_bigint", "66")
 	m.recordUnsupportedEngine(ctx, "no_bigint", "66")

gateway/internal/connectsrv/server.go

@@ -26,6 +26,7 @@ import (
 	"golang.org/x/net/http2/h2c"
 
 	"scrabble/gateway/internal/backendclient"
+	"scrabble/gateway/internal/clientver"
 	"scrabble/gateway/internal/config"
 	"scrabble/gateway/internal/push"
 	"scrabble/gateway/internal/ratelimit"
@@ -46,6 +47,21 @@ const heartbeatKind = "heartbeat"
 // spoofer, so trusting it is safe.
 const honeypotHeader = "X-Scrabble-Honeypot"
 
+// clientVersionHeader carries the client build version (stamped from `git describe --tags`) so
+// the edge can turn away a build too old to speak the current wire contract, before it decodes
+// the payload. resultUpdateRequired is the stable envelope result_code — with the Subscribe
+// counterpart connect.CodeFailedPrecondition — that any build, however old, recognises as
+// "you must update". updateRecommendedHeader is the additive, non-blocking soft-tier signal: set
+// on a served Execute response when the client is at or above the hard minimum but below the
+// recommended version, it nudges an update without failing the call. Headers are the
+// version-tolerant layer, so an old client simply ignores it. All part of the frozen wire
+// contract (docs/ARCHITECTURE.md §2).
+const (
+	clientVersionHeader     = "X-Client-Version"
+	resultUpdateRequired    = "update_required"
+	updateRecommendedHeader = "X-Update-Recommended"
+)
+
 // Limiter classes, the `class` attribute of gateway_rate_limited_total and the
 // class field of the periodic rejection report.
 const (
@@ -77,6 +93,7 @@ type Server struct {
 	limiter     *ratelimit.Limiter
 	tracker     *ratelimit.Tracker
 	banlist     *ratelimit.Banlist
+	blocklist   *ratelimit.Blocklist
 	honeytoken  string
 	vkAppSecret string
 	hub         *push.Hub
@@ -87,6 +104,17 @@ type Server struct {
 
 	maxBodyBytes int
 
+	// minClient is the lowest client version served; gateOn is false when the gate is dormant
+	// (GATEWAY_MIN_CLIENT_VERSION empty or unparseable).
+	minClient clientver.Version
+	gateOn    bool
+
+	// recClient is the version below which a served client is nudged to update (the soft tier);
+	// recOn is false when the soft tier is dormant (GATEWAY_RECOMMENDED_CLIENT_VERSION empty or
+	// unparseable). It is independent of the hard gate.
+	recClient clientver.Version
+	recOn     bool
+
 	publicPolicy ratelimit.Policy
 	userPolicy   ratelimit.Policy
 	emailPolicy  ratelimit.Policy
@@ -109,6 +137,9 @@ type Deps struct {
 	// Banlist enforces temporary IP bans on the hot path; nil selects a disabled
 	// (inert) banlist.
 	Banlist *ratelimit.Banlist
+	// Blocklist enforces the community IP blocklist on the hot path; nil selects a
+	// disabled (inert) blocklist.
+	Blocklist *ratelimit.Blocklist
 	// Honeytoken, when non-empty, is the planted bearer value whose presentation
 	// bans the caller and raises a high-severity alarm.
 	Honeytoken string
@@ -124,6 +155,13 @@ type Deps struct {
 	// MaxBodyBytes caps one inbound request body and one Connect message read;
 	// zero or negative selects config.DefaultMaxBodyBytes.
 	MaxBodyBytes int
+	// MinClientVersion is the lowest client version (MAJOR.MINOR.PATCH) the edge serves; an
+	// older X-Client-Version is turned away with "update required". Empty or unparseable leaves
+	// the gate dormant.
+	MinClientVersion string
+	// RecommendedClientVersion is the version below which a served client is nudged to update (the
+	// non-blocking X-Update-Recommended header). Empty or unparseable leaves the soft tier dormant.
+	RecommendedClientVersion string
 }
 
 // NewServer constructs the edge service.
@@ -148,10 +186,38 @@ func NewServer(d Deps) *Server {
 	if banlist == nil {
 		banlist = ratelimit.NewBanlist(ratelimit.BanConfig{})
 	}
+	blocklist := d.Blocklist
+	if blocklist == nil {
+		blocklist = ratelimit.NewBlocklist(false, nil)
+	}
 	rl := d.RateLimit
 	if rl == (config.RateLimitConfig{}) {
 		rl = config.DefaultRateLimit()
 	}
+	// Parse the minimum client version once. Config.validate already rejects an unparseable
+	// value, so the warn branch only guards a direct (test) construction; an empty value leaves
+	// the gate dormant.
+	var minClient clientver.Version
+	gateOn := false
+	if d.MinClientVersion != "" {
+		if v, ok := clientver.Parse(d.MinClientVersion); ok {
+			minClient, gateOn = v, true
+		} else {
+			log.Warn("ignoring unparseable MinClientVersion; client-version gate disabled", zap.String("value", d.MinClientVersion))
+		}
+	}
+	// Parse the recommended (soft-tier) version once, the same way. Config.validate already rejects an
+	// unparseable value or one below the minimum, so the warn branch only guards a direct (test)
+	// construction; an empty value leaves the soft tier dormant.
+	var recClient clientver.Version
+	recOn := false
+	if d.RecommendedClientVersion != "" {
+		if v, ok := clientver.Parse(d.RecommendedClientVersion); ok {
+			recClient, recOn = v, true
+		} else {
+			log.Warn("ignoring unparseable RecommendedClientVersion; update-recommended tier disabled", zap.String("value", d.RecommendedClientVersion))
+		}
+	}
 	return &Server{
 		registry:     d.Registry,
 		sessions:     d.Sessions,
@@ -160,13 +226,18 @@ func NewServer(d Deps) *Server {
 		limiter:      limiter,
 		tracker:      tracker,
 		banlist:      banlist,
+		blocklist:    blocklist,
 		honeytoken:   d.Honeytoken,
 		hub:          d.Hub,
 		heartbeat:    d.Heartbeat,
 		log:          log,
 		adminProxy:   d.AdminProxy,
-		metrics:      newServerMetrics(d.Meter),
+		metrics:      newServerMetrics(d.Meter, blocklist),
 		maxBodyBytes: maxBody,
+		minClient:    minClient,
+		gateOn:       gateOn,
+		recClient:    recClient,
+		recOn:        recOn,
 		publicPolicy: ratelimit.PerMinute(rl.PublicPerMinute, rl.PublicBurst),
 		userPolicy:   ratelimit.PerMinute(rl.UserPerMinute, rl.UserBurst),
 		emailPolicy:  ratelimit.Per(rl.EmailPer10Min, 10*time.Minute, rl.EmailBurst),
@@ -255,6 +326,13 @@ func (s *Server) abuseGuard(next http.Handler) http.Handler {
 			http.Error(w, "banned", http.StatusTooManyRequests)
 			return
 		}
+		// The community IP blocklist (Spamhaus DROP): a known-bad source is refused before any work.
+		// Counted, not logged per request (a blocked scanner hammers). Inert on a disabled blocklist.
+		if s.blocklist.Blocked(ip) {
+			s.metrics.recordBlocklistBlock(r.Context())
+			http.Error(w, "forbidden", http.StatusForbidden)
+			return
+		}
 		if r.Header.Get(honeypotHeader) != "" {
 			s.log.Warn("honeypot tripwire",
 				zap.String("path", r.URL.Path),
@@ -269,15 +347,71 @@ func (s *Server) abuseGuard(next http.Handler) http.Handler {
 	})
 }
 
+// clientTooOld reports whether the X-Client-Version header names a version below the configured
+// minimum. It fails open: with the gate dormant, or an absent or unparseable header, it returns
+// false. The header is a client-controlled compatibility signal, not an access control (it is
+// trivially spoofable), so a missing or garbled value — an old build predating the header, or a
+// non-browser caller — must never be blocked spuriously.
+func (s *Server) clientTooOld(header string) bool {
+	if !s.gateOn {
+		return false
+	}
+	v, ok := clientver.Parse(header)
+	if !ok {
+		return false
+	}
+	return clientver.Less(v, s.minClient)
+}
+
+// clientUpdateRecommended reports whether the X-Client-Version header names a version in the soft
+// band — at or above the hard minimum but below the recommended version — so a served response can
+// carry the non-blocking X-Update-Recommended nudge. It fails open exactly like clientTooOld: a
+// dormant soft tier, or an absent or unparseable header, returns false. A client below the minimum is
+// turned away by the hard gate and is never nudged, so it is excluded here too (a dormant hard gate
+// leaves minClient at the zero version, which no real version is below, so the band is simply
+// "below recommended").
+func (s *Server) clientUpdateRecommended(header string) bool {
+	if !s.recOn {
+		return false
+	}
+	v, ok := clientver.Parse(header)
+	if !ok {
+		return false
+	}
+	return !clientver.Less(v, s.minClient) && clientver.Less(v, s.recClient)
+}
+
 // Execute runs one unary operation. Domain failures are returned in the envelope
 // (result_code != "ok", HTTP 200); only edge failures (rate limit, missing
 // session, unknown type, internal) become Connect errors.
-func (s *Server) Execute(ctx context.Context, req *connect.Request[edgev1.ExecuteRequest]) (*connect.Response[edgev1.ExecuteResponse], error) {
+func (s *Server) Execute(ctx context.Context, req *connect.Request[edgev1.ExecuteRequest]) (resp *connect.Response[edgev1.ExecuteResponse], err error) {
 	start := time.Now()
 	msgType := req.Msg.GetMessageType()
 	result := "internal"
 	defer func() { s.metrics.recordEdge(ctx, msgType, result, start) }()
 
+	// The soft-tier nudge rides a response header on any served response (the call still succeeds), so a
+	// client at or above the hard minimum but below the recommended version is told an update is
+	// available without being interrupted. A too-old client (turned away below) or a missing/garbled
+	// version yields no nudge.
+	recommend := s.clientUpdateRecommended(req.Header().Get(clientVersionHeader))
+	defer func() {
+		if recommend && resp != nil {
+			resp.Header().Set(updateRecommendedHeader, "1")
+		}
+	}()
+
+	// The version gate rides the outermost stable layer (an HTTP header) and is checked before
+	// the payload is decoded, so a too-old client makes zero successful calls but sees the
+	// recognizable update_required envelope rather than a decode crash (docs/ARCHITECTURE.md §2).
+	if s.clientTooOld(req.Header().Get(clientVersionHeader)) {
+		result = resultUpdateRequired
+		return connect.NewResponse(&edgev1.ExecuteResponse{
+			RequestId:  req.Msg.GetRequestId(),
+			ResultCode: resultUpdateRequired,
+		}), nil
+	}
+
 	op, ok := s.registry.Lookup(msgType)
 	if !ok {
 		result = "unknown_type"
@@ -347,6 +481,11 @@ func (s *Server) Execute(ctx context.Context, req *connect.Request[edgev1.Execut
 // Subscribe streams the authenticated user's live events with a keep-alive
 // heartbeat until the client disconnects.
 func (s *Server) Subscribe(ctx context.Context, req *connect.Request[edgev1.SubscribeRequest], stream *connect.ServerStream[edgev1.Event]) error {
+	// A stream carries no result_code, so a too-old client is refused with the Connect
+	// FailedPrecondition counterpart of the update_required sentinel.
+	if s.clientTooOld(req.Header().Get(clientVersionHeader)) {
+		return connect.NewError(connect.CodeFailedPrecondition, errUpdateRequired)
+	}
 	uid, _, _, err := s.resolve(ctx, req.Header(), peerIP(req.Peer().Addr, req.Header()))
 	if err != nil {
 		return err

gateway/internal/connectsrv/server_test.go

@@ -22,8 +22,13 @@ import (
 )
 
 // newEdge wires a connectsrv.Server over a fake backend and returns a Connect
-// client plus a cleanup func.
+// client plus a cleanup func. The client-version gate is off.
 func newEdge(t *testing.T, backendHandler http.HandlerFunc) (edgev1connect.GatewayClient, func()) {
+	return newEdgeMin(t, "", backendHandler)
+}
+
+// newEdgeMin is newEdge with the client-version gate armed at minVersion (empty leaves it off).
+func newEdgeMin(t *testing.T, minVersion string, backendHandler http.HandlerFunc) (edgev1connect.GatewayClient, func()) {
 	t.Helper()
 	backendSrv := httptest.NewServer(backendHandler)
 	backend, err := backendclient.New(backendSrv.URL, "localhost:9090", 2*time.Second)
@@ -31,12 +36,40 @@ func newEdge(t *testing.T, backendHandler http.HandlerFunc) (edgev1connect.Gatew
 		t.Fatalf("backendclient: %v", err)
 	}
 	edge := connectsrv.NewServer(connectsrv.Deps{
-		Registry:  transcode.NewRegistry(backend, nil),
+		Registry:         transcode.NewRegistry(backend, nil),
-		Sessions:  session.NewCache(backend, time.Minute, 100),
+		Sessions:         session.NewCache(backend, time.Minute, 100),
-		Limiter:   ratelimit.New(),
+		Limiter:          ratelimit.New(),
-		Hub:       push.NewHub(0),
+		Hub:              push.NewHub(0),
-		RateLimit: config.DefaultRateLimit(),
+		RateLimit:        config.DefaultRateLimit(),
-		Heartbeat: 15 * time.Second,
+		Heartbeat:        15 * time.Second,
+		MinClientVersion: minVersion,
+	})
+	edgeSrv := httptest.NewServer(edge.HTTPHandler())
+	client := edgev1connect.NewGatewayClient(http.DefaultClient, edgeSrv.URL)
+	return client, func() {
+		edgeSrv.Close()
+		_ = backend.Close()
+		backendSrv.Close()
+	}
+}
+
+// newEdgeVersions is newEdgeMin with the soft-tier recommended version also armed (empty leaves it off).
+func newEdgeVersions(t *testing.T, minVersion, recommendedVersion string, backendHandler http.HandlerFunc) (edgev1connect.GatewayClient, func()) {
+	t.Helper()
+	backendSrv := httptest.NewServer(backendHandler)
+	backend, err := backendclient.New(backendSrv.URL, "localhost:9090", 2*time.Second)
+	if err != nil {
+		t.Fatalf("backendclient: %v", err)
+	}
+	edge := connectsrv.NewServer(connectsrv.Deps{
+		Registry:                 transcode.NewRegistry(backend, nil),
+		Sessions:                 session.NewCache(backend, time.Minute, 100),
+		Limiter:                  ratelimit.New(),
+		Hub:                      push.NewHub(0),
+		RateLimit:                config.DefaultRateLimit(),
+		Heartbeat:                15 * time.Second,
+		MinClientVersion:         minVersion,
+		RecommendedClientVersion: recommendedVersion,
 	})
 	edgeSrv := httptest.NewServer(edge.HTTPHandler())
 	client := edgev1connect.NewGatewayClient(http.DefaultClient, edgeSrv.URL)
@@ -108,6 +141,132 @@ func TestExecuteGuestGate(t *testing.T) {
 	}
 }
 
+// TestExecuteVersionGate verifies the client-version gate on the unary path: a build older
+// than the configured minimum is turned away with the update_required result code before the
+// registry lookup (an unknown message type is gated too, proving the short-circuit), while an
+// equal, newer, absent, or unparseable version passes; and the gate is dormant when unset.
+func TestExecuteVersionGate(t *testing.T) {
+	// The backend answers auth.guest with a session; a gated call never reaches it.
+	backend := func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"token":"tok","user_id":"u-1","is_guest":true,"display_name":"Guest"}`))
+	}
+	tests := []struct {
+		name    string
+		min     string
+		header  string
+		msgType string
+		want    string
+	}{
+		{"too old is gated before lookup", "v1.16.0", "v1.0.0", "bogus.unknown", "update_required"},
+		{"equal passes", "v1.16.0", "v1.16.0", transcode.MsgAuthGuest, "ok"},
+		{"newer passes", "v1.16.0", "v2.0.0", transcode.MsgAuthGuest, "ok"},
+		{"absent header fails open", "v1.16.0", "", transcode.MsgAuthGuest, "ok"},
+		{"unparseable header fails open", "v1.16.0", "dev", transcode.MsgAuthGuest, "ok"},
+		{"gate dormant when unset", "", "v1.0.0", transcode.MsgAuthGuest, "ok"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			client, cleanup := newEdgeMin(t, tc.min, backend)
+			defer cleanup()
+			req := connect.NewRequest(&edgev1.ExecuteRequest{MessageType: tc.msgType, RequestId: "rq"})
+			if tc.header != "" {
+				req.Header().Set("X-Client-Version", tc.header)
+			}
+			resp, err := client.Execute(context.Background(), req)
+			if err != nil {
+				t.Fatalf("execute: %v", err)
+			}
+			if got := resp.Msg.GetResultCode(); got != tc.want {
+				t.Fatalf("result_code = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestExecuteUpdateRecommended verifies the soft-tier nudge on the unary path: a served client at or
+// above the hard minimum but below the recommended version gets the X-Update-Recommended response
+// header (the call still succeeds); a too-old (hard-gated), up-to-date, absent, or unparseable version
+// and a dormant soft tier get no header.
+func TestExecuteUpdateRecommended(t *testing.T) {
+	backend := func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"token":"tok","user_id":"u-1","is_guest":true,"display_name":"Guest"}`))
+	}
+	tests := []struct {
+		name       string
+		min        string
+		rec        string
+		header     string
+		wantResult string
+		wantHeader bool
+	}{
+		{"soft band is nudged", "v1.16.0", "v1.20.0", "v1.17.0", "ok", true},
+		{"at the minimum is nudged", "v1.16.0", "v1.20.0", "v1.16.0", "ok", true},
+		{"at the recommended is not nudged", "v1.16.0", "v1.20.0", "v1.20.0", "ok", false},
+		{"newer than recommended is not nudged", "v1.16.0", "v1.20.0", "v2.0.0", "ok", false},
+		{"too old is gated, not nudged", "v1.16.0", "v1.20.0", "v1.0.0", "update_required", false},
+		{"absent header, no nudge", "v1.16.0", "v1.20.0", "", "ok", false},
+		{"unparseable header, no nudge", "v1.16.0", "v1.20.0", "dev", "ok", false},
+		{"recommended alone (no min) nudges below it", "", "v1.20.0", "v1.0.0", "ok", true},
+		{"soft tier dormant, no nudge", "v1.16.0", "", "v1.0.0", "update_required", false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			client, cleanup := newEdgeVersions(t, tc.min, tc.rec, backend)
+			defer cleanup()
+			req := connect.NewRequest(&edgev1.ExecuteRequest{MessageType: transcode.MsgAuthGuest, RequestId: "rq"})
+			if tc.header != "" {
+				req.Header().Set("X-Client-Version", tc.header)
+			}
+			resp, err := client.Execute(context.Background(), req)
+			if err != nil {
+				t.Fatalf("execute: %v", err)
+			}
+			if got := resp.Msg.GetResultCode(); got != tc.wantResult {
+				t.Fatalf("result_code = %q, want %q", got, tc.wantResult)
+			}
+			if got := resp.Header().Get("X-Update-Recommended") == "1"; got != tc.wantHeader {
+				t.Fatalf("X-Update-Recommended present = %v, want %v", got, tc.wantHeader)
+			}
+		})
+	}
+}
+
+// TestSubscribeVersionGate verifies the streaming path: a too-old client is refused with
+// FailedPrecondition, while an equal or absent version is admitted and proceeds to auth (which
+// fails Unauthenticated with no session, proving it passed the version gate).
+func TestSubscribeVersionGate(t *testing.T) {
+	noBackend := func(_ http.ResponseWriter, _ *http.Request) {}
+	tests := []struct {
+		name   string
+		min    string
+		header string
+		want   connect.Code
+	}{
+		{"too old refused", "v1.16.0", "v1.0.0", connect.CodeFailedPrecondition},
+		{"equal admitted then auth-gated", "v1.16.0", "v1.16.0", connect.CodeUnauthenticated},
+		{"gate dormant admits", "", "v1.0.0", connect.CodeUnauthenticated},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			client, cleanup := newEdgeMin(t, tc.min, noBackend)
+			defer cleanup()
+			req := connect.NewRequest(&edgev1.SubscribeRequest{})
+			if tc.header != "" {
+				req.Header().Set("X-Client-Version", tc.header)
+			}
+			stream, err := client.Subscribe(context.Background(), req)
+			if err == nil {
+				for stream.Receive() {
+				}
+				err = stream.Err()
+			}
+			if got := connect.CodeOf(err); got != tc.want {
+				t.Fatalf("code = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
 func TestExecuteAuthedRequiresSession(t *testing.T) {
 	client, cleanup := newEdge(t, func(w http.ResponseWriter, r *http.Request) {
 		t.Error("backend must not be called without a session")

gateway/internal/ratelimit/blocklist.go

@@ -0,0 +1,188 @@
+package ratelimit
+
+import (
+	"bufio"
+	"encoding/binary"
+	"fmt"
+	"io"
+	"net"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// ipRange is an inclusive IPv4 range [lo, hi] as uint32 — the form the blocklist matches against.
+type ipRange struct{ lo, hi uint32 }
+
+// Blocklist is a static IPv4 CIDR blocklist (a curated community feed such as Spamhaus DROP) enforced
+// on the hot path alongside the fail2ban [Banlist]. It is refreshed periodically ([ApplyRefresh]); an
+// allowlist (never blocked) protects known-good infrastructure and is checked first. Only IPv4 is
+// matched — an IPv6 client is never blocked here (the fail2ban list and the honeypot still cover it).
+// Disabled by default (prod-only, like the ban): while disabled, Blocked is always false.
+type Blocklist struct {
+	enabled bool
+	allow   []ipRange // sorted, non-overlapping; from config, immutable after construction
+
+	mu        sync.RWMutex
+	ranges    []ipRange // sorted, non-overlapping; the current feed
+	fetchedAt time.Time // last successful SetCIDRs; zero = never loaded
+}
+
+// NewBlocklist builds a Blocklist. enabled gates the whole mechanism; allow is the never-block set
+// (CIDRs / bare IPs already parsed) — a client in it is never blocked even if the feed lists it.
+func NewBlocklist(enabled bool, allow []*net.IPNet) *Blocklist {
+	return &Blocklist{enabled: enabled, allow: toRanges(allow)}
+}
+
+// Blocked reports whether ip (a textual address) is in the current feed and not allowlisted. It is
+// false on a disabled or empty blocklist, and false for any non-IPv4 address.
+func (b *Blocklist) Blocked(ip string) bool {
+	if !b.enabled {
+		return false
+	}
+	v, ok := ipv4ToUint32(ip)
+	if !ok {
+		return false
+	}
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	if len(b.ranges) == 0 || rangesContain(b.allow, v) {
+		return false
+	}
+	return rangesContain(b.ranges, v)
+}
+
+// SetCIDRs swaps in a freshly fetched feed, recording the fetch time. Non-IPv4 CIDRs are ignored.
+func (b *Blocklist) SetCIDRs(cidrs []*net.IPNet, at time.Time) {
+	r := toRanges(cidrs)
+	b.mu.Lock()
+	b.ranges = r
+	b.fetchedAt = at
+	b.mu.Unlock()
+}
+
+// Clear drops the current feed (fail-open) but keeps the last-fetch time, so a staleness gauge keeps
+// climbing. Blocked then returns false until a fresh feed loads.
+func (b *Blocklist) Clear() {
+	b.mu.Lock()
+	b.ranges = nil
+	b.mu.Unlock()
+}
+
+// Len returns the number of ranges currently enforced.
+func (b *Blocklist) Len() int {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return len(b.ranges)
+}
+
+// LastFetch returns the time of the last successful feed load (zero if never).
+func (b *Blocklist) LastFetch() time.Time {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.fetchedAt
+}
+
+// RefreshOutcome is the result of one refresh attempt, for the caller's logging and metrics.
+type RefreshOutcome int
+
+const (
+	// RefreshUpdated: a new feed was fetched and applied.
+	RefreshUpdated RefreshOutcome = iota
+	// RefreshKept: the fetch failed but the last-good feed is still fresh, so it was kept.
+	RefreshKept
+	// RefreshDropped: the fetch failed and the feed went stale, so it was dropped (fail-open).
+	RefreshDropped
+)
+
+// ApplyRefresh updates bl from one fetch outcome: on success it applies the new feed; on failure it
+// keeps the last-good feed unless it is older than maxStaleness, in which case it drops it (fail-open
+// — better to under-block than to block a legitimate client on a frozen feed). now is the wall clock.
+func ApplyRefresh(bl *Blocklist, cidrs []*net.IPNet, fetchErr error, now time.Time, maxStaleness time.Duration) RefreshOutcome {
+	if fetchErr == nil {
+		bl.SetCIDRs(cidrs, now)
+		return RefreshUpdated
+	}
+	last := bl.LastFetch()
+	if last.IsZero() || now.Sub(last) > maxStaleness {
+		bl.Clear()
+		return RefreshDropped
+	}
+	return RefreshKept
+}
+
+// ParseDROP parses a Spamhaus DROP-style feed: one CIDR per line with an optional "; comment" tail,
+// plus blank and comment lines. It returns the IPv4 networks; a bare IP is read as a /32, and
+// non-IPv4 or malformed entries are skipped so one bad line never fails the whole feed.
+func ParseDROP(r io.Reader) ([]*net.IPNet, error) {
+	var out []*net.IPNet
+	sc := bufio.NewScanner(r)
+	sc.Buffer(make([]byte, 0, 64*1024), 1<<20)
+	for sc.Scan() {
+		line := sc.Text()
+		if i := strings.IndexByte(line, ';'); i >= 0 {
+			line = line[:i]
+		}
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if !strings.Contains(line, "/") {
+			line += "/32"
+		}
+		_, ipnet, err := net.ParseCIDR(line)
+		if err != nil || ipnet.IP.To4() == nil {
+			continue
+		}
+		out = append(out, ipnet)
+	}
+	if err := sc.Err(); err != nil {
+		return nil, fmt.Errorf("ratelimit: read blocklist: %w", err)
+	}
+	return out, nil
+}
+
+// toRanges converts IPv4 CIDRs to sorted, uint32 inclusive ranges (the match form); non-IPv4 CIDRs
+// are dropped. Sorting by lo lets [rangesContain] binary-search.
+func toRanges(cidrs []*net.IPNet) []ipRange {
+	out := make([]ipRange, 0, len(cidrs))
+	for _, n := range cidrs {
+		if n == nil {
+			continue
+		}
+		ip4 := n.IP.To4()
+		if ip4 == nil {
+			continue
+		}
+		ones, bits := n.Mask.Size()
+		if bits != 32 {
+			continue
+		}
+		lo := binary.BigEndian.Uint32(ip4)
+		hi := lo | (uint32(0xffffffff) >> uint(ones))
+		out = append(out, ipRange{lo: lo, hi: hi})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].lo < out[j].lo })
+	return out
+}
+
+// rangesContain reports whether v falls in any range of the sorted, non-overlapping slice, via a
+// binary search for the last range whose lo is at most v.
+func rangesContain(ranges []ipRange, v uint32) bool {
+	i := sort.Search(len(ranges), func(i int) bool { return ranges[i].lo > v })
+	return i > 0 && ranges[i-1].hi >= v
+}
+
+// ipv4ToUint32 parses a textual address to a big-endian uint32, reporting whether it was IPv4.
+func ipv4ToUint32(s string) (uint32, bool) {
+	ip := net.ParseIP(s)
+	if ip == nil {
+		return 0, false
+	}
+	ip4 := ip.To4()
+	if ip4 == nil {
+		return 0, false
+	}
+	return binary.BigEndian.Uint32(ip4), true
+}

gateway/internal/ratelimit/blocklist_test.go

@@ -0,0 +1,106 @@
+package ratelimit
+
+import (
+	"errors"
+	"net"
+	"strings"
+	"testing"
+	"time"
+)
+
+// cidrs parses CIDR strings into networks for a test fixture.
+func cidrs(t *testing.T, ss ...string) []*net.IPNet {
+	t.Helper()
+	out := make([]*net.IPNet, 0, len(ss))
+	for _, s := range ss {
+		_, n, err := net.ParseCIDR(s)
+		if err != nil {
+			t.Fatalf("bad cidr %q: %v", s, err)
+		}
+		out = append(out, n)
+	}
+	return out
+}
+
+func TestBlocklistBlocked(t *testing.T) {
+	bl := NewBlocklist(true, cidrs(t, "10.20.30.0/24")) // allowlist
+	bl.SetCIDRs(cidrs(t, "1.2.3.0/24", "203.0.113.5/32", "198.51.100.0/28", "10.20.30.0/24"), time.Now())
+	cases := map[string]bool{
+		"1.2.3.0":       true,  // range start
+		"1.2.3.255":     true,  // range end
+		"1.2.4.0":       false, // just past the /24
+		"203.0.113.5":   true,  // /32 exact
+		"203.0.113.6":   false,
+		"198.51.100.15": true,  // within /28
+		"198.51.100.16": false, // past the /28
+		"9.9.9.9":       false, // not listed
+		"10.20.30.99":   false, // listed BUT allowlisted — never blocked
+		"::1":           false, // IPv6 — never matched here
+		"not-an-ip":     false,
+	}
+	for ip, want := range cases {
+		if got := bl.Blocked(ip); got != want {
+			t.Errorf("Blocked(%q) = %v, want %v", ip, got, want)
+		}
+	}
+}
+
+func TestBlocklistDisabledOrEmpty(t *testing.T) {
+	off := NewBlocklist(false, nil)
+	off.SetCIDRs(cidrs(t, "1.2.3.0/24"), time.Now())
+	if off.Blocked("1.2.3.4") {
+		t.Error("a disabled blocklist must not block")
+	}
+	empty := NewBlocklist(true, nil)
+	if empty.Blocked("1.2.3.4") {
+		t.Error("an empty (never-loaded) blocklist must not block")
+	}
+}
+
+func TestParseDROP(t *testing.T) {
+	in := "; Spamhaus DROP\n" +
+		"1.2.3.0/24 ; SBL1\n" +
+		"  198.51.100.0/28 ; SBL2\n" +
+		"\n" +
+		"203.0.113.5 ; a bare IP -> /32\n" +
+		"2001:db8::/32 ; IPv6 skipped\n" +
+		"garbage line\n"
+	nets, err := ParseDROP(strings.NewReader(in))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(nets) != 3 {
+		t.Fatalf("got %d networks, want 3: %v", len(nets), nets)
+	}
+	bl := NewBlocklist(true, nil)
+	bl.SetCIDRs(nets, time.Now())
+	for ip, want := range map[string]bool{"1.2.3.9": true, "198.51.100.1": true, "203.0.113.5": true, "203.0.113.6": false, "2001:db8::1": false} {
+		if got := bl.Blocked(ip); got != want {
+			t.Errorf("Blocked(%s) = %v, want %v", ip, got, want)
+		}
+	}
+}
+
+func TestApplyRefresh(t *testing.T) {
+	bl := NewBlocklist(true, nil)
+	now := time.Now()
+
+	if o := ApplyRefresh(bl, cidrs(t, "1.2.3.0/24"), nil, now, time.Hour); o != RefreshUpdated {
+		t.Fatalf("success: want RefreshUpdated, got %v", o)
+	}
+	if !bl.Blocked("1.2.3.4") {
+		t.Fatal("a successful refresh must apply the feed")
+	}
+	if o := ApplyRefresh(bl, nil, errors.New("net"), now.Add(30*time.Minute), time.Hour); o != RefreshKept {
+		t.Fatalf("fresh failure: want RefreshKept, got %v", o)
+	}
+	if !bl.Blocked("1.2.3.4") {
+		t.Error("a kept feed must still block")
+	}
+	if o := ApplyRefresh(bl, nil, errors.New("net"), now.Add(2*time.Hour), time.Hour); o != RefreshDropped {
+		t.Fatalf("stale failure: want RefreshDropped, got %v", o)
+	}
+	if bl.Blocked("1.2.3.4") {
+		t.Error("a stale feed must be dropped (fail-open)")
+	}
+}

gateway/internal/ratelimit/ratelimit_test.go

@@ -4,6 +4,7 @@ import (
 	"testing"
 	"time"
 
+	"scrabble/gateway/internal/config"
 	"scrabble/gateway/internal/ratelimit"
 )
 
@@ -44,3 +45,20 @@ func TestPerWindow(t *testing.T) {
 		t.Fatalf("per-window burst = %v, want [true true false]", got)
 	}
 }
+
+// TestEmailBurstAllowsHonestLoginFlow guards the default email-code burst against being
+// tightened back below the honest login sequence: requesting a code, submitting one wrong
+// code, then the correct one are three immediate email-class events from one IP, and all
+// must pass. A burst of 2 denied the correct-code login, which the client mis-read as going
+// offline and could not recover from on the session-less login screen. This is defence in
+// depth over the backend's own per-code attempt cap and code TTL.
+func TestEmailBurstAllowsHonestLoginFlow(t *testing.T) {
+	rl := config.DefaultRateLimit()
+	p := ratelimit.Per(rl.EmailPer10Min, 10*time.Minute, rl.EmailBurst)
+	l := ratelimit.New()
+	for i, want := range []bool{true, true, true} { // request code, wrong code, right code
+		if got := l.Allow("email:198.51.100.7", p); got != want {
+			t.Fatalf("honest email event %d allowed = %v, want %v", i+1, got, want)
+		}
+	}
+}

pkg/proto/botlink/v1/botlink.pb.go

@@ -30,13 +30,14 @@ const (
 )
 
 // FromBot is a message the bot sends to the gateway: the opening Hello, then one
-// Ack per Command.
+// Ack per Command and a periodic Health report.
 type FromBot struct {
 	state protoimpl.MessageState `protogen:"open.v1"`
 	// Types that are valid to be assigned to Msg:
 	//
 	//	*FromBot_Hello
 	//	*FromBot_Ack
+	//	*FromBot_Health
 	Msg           isFromBot_Msg `protobuf_oneof:"msg"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
@@ -97,6 +98,15 @@ func (x *FromBot) GetAck() *Ack {
 	return nil
 }
 
+func (x *FromBot) GetHealth() *Health {
+	if x != nil {
+		if x, ok := x.Msg.(*FromBot_Health); ok {
+			return x.Health
+		}
+	}
+	return nil
+}
+
 type isFromBot_Msg interface {
 	isFromBot_Msg()
 }
@@ -109,10 +119,92 @@ type FromBot_Ack struct {
 	Ack *Ack `protobuf:"bytes,2,opt,name=ack,proto3,oneof"`
 }
 
+type FromBot_Health struct {
+	Health *Health `protobuf:"bytes,3,opt,name=health,proto3,oneof"`
+}
+
 func (*FromBot_Hello) isFromBot_Msg() {}
 
 func (*FromBot_Ack) isFromBot_Msg() {}
 
+func (*FromBot_Health) isFromBot_Msg() {}
+
+// Health is a periodic report the bot pushes up the stream so the gateway can expose the remote
+// bot's Bot-API health as its own metrics — the bot exports no telemetry of its own (otelcol lives
+// on the main host, unreachable from the bot), so the bot-link is its only channel out. The three
+// counters are DELTAS since the previous Health: the gateway adds them to cumulative counters, so a
+// report lost across a reconnect only undercounts, never corrupts. last_ok_unix is the wall-clock
+// second of the bot's most recent successful Bot API response (any call, including the getUpdates
+// long-poll that returns every poll cycle even when idle) — an absolute liveness stamp the gateway
+// surfaces as a gauge, so a silently stalled bot (no errors, no traffic) is still caught.
+type Health struct {
+	state           protoimpl.MessageState `protogen:"open.v1"`
+	ConnectFailures uint64                 `protobuf:"varint,1,opt,name=connect_failures,json=connectFailures,proto3" json:"connect_failures,omitempty"` // getUpdates long-poll failures (transport / 5xx) since the last report
+	ApiErrors       uint64                 `protobuf:"varint,2,opt,name=api_errors,json=apiErrors,proto3" json:"api_errors,omitempty"`                   // other Bot API failures (transport / 5xx) since the last report
+	RateLimited     uint64                 `protobuf:"varint,3,opt,name=rate_limited,json=rateLimited,proto3" json:"rate_limited,omitempty"`             // Bot API 429 responses since the last report (should stay ~0)
+	LastOkUnix      int64                  `protobuf:"varint,4,opt,name=last_ok_unix,json=lastOkUnix,proto3" json:"last_ok_unix,omitempty"`              // unix seconds of the last successful Bot API response (0 = none yet)
+	unknownFields   protoimpl.UnknownFields
+	sizeCache       protoimpl.SizeCache
+}
+
+func (x *Health) Reset() {
+	*x = Health{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Health) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Health) ProtoMessage() {}
+
+func (x *Health) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Health.ProtoReflect.Descriptor instead.
+func (*Health) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *Health) GetConnectFailures() uint64 {
+	if x != nil {
+		return x.ConnectFailures
+	}
+	return 0
+}
+
+func (x *Health) GetApiErrors() uint64 {
+	if x != nil {
+		return x.ApiErrors
+	}
+	return 0
+}
+
+func (x *Health) GetRateLimited() uint64 {
+	if x != nil {
+		return x.RateLimited
+	}
+	return 0
+}
+
+func (x *Health) GetLastOkUnix() int64 {
+	if x != nil {
+		return x.LastOkUnix
+	}
+	return 0
+}
+
 // ToBot is a message the gateway sends to the bot. Only Command is carried today.
 type ToBot struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
@@ -123,7 +215,7 @@ type ToBot struct {
 
 func (x *ToBot) Reset() {
 	*x = ToBot{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -135,7 +227,7 @@ func (x *ToBot) String() string {
 func (*ToBot) ProtoMessage() {}
 
 func (x *ToBot) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -148,7 +240,7 @@ func (x *ToBot) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ToBot.ProtoReflect.Descriptor instead.
 func (*ToBot) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{1}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{2}
 }
 
 func (x *ToBot) GetCommand() *Command {
@@ -171,7 +263,7 @@ type Hello struct {
 
 func (x *Hello) Reset() {
 	*x = Hello{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -183,7 +275,7 @@ func (x *Hello) String() string {
 func (*Hello) ProtoMessage() {}
 
 func (x *Hello) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -196,7 +288,7 @@ func (x *Hello) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Hello.ProtoReflect.Descriptor instead.
 func (*Hello) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{2}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{3}
 }
 
 func (x *Hello) GetInstanceId() string {
@@ -233,7 +325,7 @@ type Command struct {
 
 func (x *Command) Reset() {
 	*x = Command{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -245,7 +337,7 @@ func (x *Command) String() string {
 func (*Command) ProtoMessage() {}
 
 func (x *Command) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -258,7 +350,7 @@ func (x *Command) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Command.ProtoReflect.Descriptor instead.
 func (*Command) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{3}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{4}
 }
 
 func (x *Command) GetCommandId() string {
@@ -372,7 +464,7 @@ type Ack struct {
 
 func (x *Ack) Reset() {
 	*x = Ack{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -384,7 +476,7 @@ func (x *Ack) String() string {
 func (*Ack) ProtoMessage() {}
 
 func (x *Ack) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -397,7 +489,7 @@ func (x *Ack) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Ack.ProtoReflect.Descriptor instead.
 func (*Ack) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{4}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{5}
 }
 
 func (x *Ack) GetCommandId() string {
@@ -445,7 +537,7 @@ type ChatGateCommand struct {
 
 func (x *ChatGateCommand) Reset() {
 	*x = ChatGateCommand{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -457,7 +549,7 @@ func (x *ChatGateCommand) String() string {
 func (*ChatGateCommand) ProtoMessage() {}
 
 func (x *ChatGateCommand) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -470,7 +562,7 @@ func (x *ChatGateCommand) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ChatGateCommand.ProtoReflect.Descriptor instead.
 func (*ChatGateCommand) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{5}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{6}
 }
 
 func (x *ChatGateCommand) GetExternalId() string {
@@ -498,7 +590,7 @@ type ChatEligibilityRequest struct {
 
 func (x *ChatEligibilityRequest) Reset() {
 	*x = ChatEligibilityRequest{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -510,7 +602,7 @@ func (x *ChatEligibilityRequest) String() string {
 func (*ChatEligibilityRequest) ProtoMessage() {}
 
 func (x *ChatEligibilityRequest) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -523,7 +615,7 @@ func (x *ChatEligibilityRequest) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ChatEligibilityRequest.ProtoReflect.Descriptor instead.
 func (*ChatEligibilityRequest) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{6}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{7}
 }
 
 func (x *ChatEligibilityRequest) GetExternalId() string {
@@ -546,7 +638,7 @@ type ChatEligibilityResponse struct {
 
 func (x *ChatEligibilityResponse) Reset() {
 	*x = ChatEligibilityResponse{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -558,7 +650,7 @@ func (x *ChatEligibilityResponse) String() string {
 func (*ChatEligibilityResponse) ProtoMessage() {}
 
 func (x *ChatEligibilityResponse) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -571,7 +663,7 @@ func (x *ChatEligibilityResponse) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ChatEligibilityResponse.ProtoReflect.Descriptor instead.
 func (*ChatEligibilityResponse) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{7}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{8}
 }
 
 func (x *ChatEligibilityResponse) GetRegistered() bool {
@@ -605,7 +697,7 @@ type CreateInvoiceCommand struct {
 
 func (x *CreateInvoiceCommand) Reset() {
 	*x = CreateInvoiceCommand{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -617,7 +709,7 @@ func (x *CreateInvoiceCommand) String() string {
 func (*CreateInvoiceCommand) ProtoMessage() {}
 
 func (x *CreateInvoiceCommand) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -630,7 +722,7 @@ func (x *CreateInvoiceCommand) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use CreateInvoiceCommand.ProtoReflect.Descriptor instead.
 func (*CreateInvoiceCommand) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{8}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{9}
 }
 
 func (x *CreateInvoiceCommand) GetTitle() string {
@@ -674,7 +766,7 @@ type PreCheckoutRequest struct {
 
 func (x *PreCheckoutRequest) Reset() {
 	*x = PreCheckoutRequest{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -686,7 +778,7 @@ func (x *PreCheckoutRequest) String() string {
 func (*PreCheckoutRequest) ProtoMessage() {}
 
 func (x *PreCheckoutRequest) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -699,7 +791,7 @@ func (x *PreCheckoutRequest) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use PreCheckoutRequest.ProtoReflect.Descriptor instead.
 func (*PreCheckoutRequest) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{9}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{10}
 }
 
 func (x *PreCheckoutRequest) GetOrderId() string {
@@ -735,7 +827,7 @@ type PreCheckoutResponse struct {
 
 func (x *PreCheckoutResponse) Reset() {
 	*x = PreCheckoutResponse{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -747,7 +839,7 @@ func (x *PreCheckoutResponse) String() string {
 func (*PreCheckoutResponse) ProtoMessage() {}
 
 func (x *PreCheckoutResponse) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -760,7 +852,7 @@ func (x *PreCheckoutResponse) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use PreCheckoutResponse.ProtoReflect.Descriptor instead.
 func (*PreCheckoutResponse) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{10}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{11}
 }
 
 func (x *PreCheckoutResponse) GetOk() bool {
@@ -792,7 +884,7 @@ type ForwardPaymentRequest struct {
 
 func (x *ForwardPaymentRequest) Reset() {
 	*x = ForwardPaymentRequest{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -804,7 +896,7 @@ func (x *ForwardPaymentRequest) String() string {
 func (*ForwardPaymentRequest) ProtoMessage() {}
 
 func (x *ForwardPaymentRequest) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -817,7 +909,7 @@ func (x *ForwardPaymentRequest) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ForwardPaymentRequest.ProtoReflect.Descriptor instead.
 func (*ForwardPaymentRequest) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{11}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{12}
 }
 
 func (x *ForwardPaymentRequest) GetOrderId() string {
@@ -861,7 +953,7 @@ type ForwardPaymentResponse struct {
 
 func (x *ForwardPaymentResponse) Reset() {
 	*x = ForwardPaymentResponse{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[13]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -873,7 +965,7 @@ func (x *ForwardPaymentResponse) String() string {
 func (*ForwardPaymentResponse) ProtoMessage() {}
 
 func (x *ForwardPaymentResponse) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[13]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -886,7 +978,7 @@ func (x *ForwardPaymentResponse) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ForwardPaymentResponse.ProtoReflect.Descriptor instead.
 func (*ForwardPaymentResponse) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{12}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{13}
 }
 
 func (x *ForwardPaymentResponse) GetCredited() bool {
@@ -900,11 +992,19 @@ var File_botlink_v1_botlink_proto protoreflect.FileDescriptor
 
 const file_botlink_v1_botlink_proto_rawDesc = "" +
 	"\n" +
-	"\x18botlink/v1/botlink.proto\x12\x13scrabble.botlink.v1\x1a\x1atelegram/v1/telegram.proto\"r\n" +
+	"\x18botlink/v1/botlink.proto\x12\x13scrabble.botlink.v1\x1a\x1atelegram/v1/telegram.proto\"\xa9\x01\n" +
 	"\aFromBot\x122\n" +
 	"\x05hello\x18\x01 \x01(\v2\x1a.scrabble.botlink.v1.HelloH\x00R\x05hello\x12,\n" +
-	"\x03ack\x18\x02 \x01(\v2\x18.scrabble.botlink.v1.AckH\x00R\x03ackB\x05\n" +
+	"\x03ack\x18\x02 \x01(\v2\x18.scrabble.botlink.v1.AckH\x00R\x03ack\x125\n" +
-	"\x03msg\"?\n" +
+	"\x06health\x18\x03 \x01(\v2\x1b.scrabble.botlink.v1.HealthH\x00R\x06healthB\x05\n" +
+	"\x03msg\"\x97\x01\n" +
+	"\x06Health\x12)\n" +
+	"\x10connect_failures\x18\x01 \x01(\x04R\x0fconnectFailures\x12\x1d\n" +
+	"\n" +
+	"api_errors\x18\x02 \x01(\x04R\tapiErrors\x12!\n" +
+	"\frate_limited\x18\x03 \x01(\x04R\vrateLimited\x12 \n" +
+	"\flast_ok_unix\x18\x04 \x01(\x03R\n" +
+	"lastOkUnix\"?\n" +
 	"\x05ToBot\x126\n" +
 	"\acommand\x18\x01 \x01(\v2\x1c.scrabble.botlink.v1.CommandR\acommand\"K\n" +
 	"\x05Hello\x12\x1f\n" +
@@ -976,47 +1076,49 @@ func file_botlink_v1_botlink_proto_rawDescGZIP() []byte {
 	return file_botlink_v1_botlink_proto_rawDescData
 }
 
-var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
+var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 14)
 var file_botlink_v1_botlink_proto_goTypes = []any{
 	(*FromBot)(nil),                     // 0: scrabble.botlink.v1.FromBot
-	(*ToBot)(nil),                       // 1: scrabble.botlink.v1.ToBot
+	(*Health)(nil),                      // 1: scrabble.botlink.v1.Health
-	(*Hello)(nil),                       // 2: scrabble.botlink.v1.Hello
+	(*ToBot)(nil),                       // 2: scrabble.botlink.v1.ToBot
-	(*Command)(nil),                     // 3: scrabble.botlink.v1.Command
+	(*Hello)(nil),                       // 3: scrabble.botlink.v1.Hello
-	(*Ack)(nil),                         // 4: scrabble.botlink.v1.Ack
+	(*Command)(nil),                     // 4: scrabble.botlink.v1.Command
-	(*ChatGateCommand)(nil),             // 5: scrabble.botlink.v1.ChatGateCommand
+	(*Ack)(nil),                         // 5: scrabble.botlink.v1.Ack
-	(*ChatEligibilityRequest)(nil),      // 6: scrabble.botlink.v1.ChatEligibilityRequest
+	(*ChatGateCommand)(nil),             // 6: scrabble.botlink.v1.ChatGateCommand
-	(*ChatEligibilityResponse)(nil),     // 7: scrabble.botlink.v1.ChatEligibilityResponse
+	(*ChatEligibilityRequest)(nil),      // 7: scrabble.botlink.v1.ChatEligibilityRequest
-	(*CreateInvoiceCommand)(nil),        // 8: scrabble.botlink.v1.CreateInvoiceCommand
+	(*ChatEligibilityResponse)(nil),     // 8: scrabble.botlink.v1.ChatEligibilityResponse
-	(*PreCheckoutRequest)(nil),          // 9: scrabble.botlink.v1.PreCheckoutRequest
+	(*CreateInvoiceCommand)(nil),        // 9: scrabble.botlink.v1.CreateInvoiceCommand
-	(*PreCheckoutResponse)(nil),         // 10: scrabble.botlink.v1.PreCheckoutResponse
+	(*PreCheckoutRequest)(nil),          // 10: scrabble.botlink.v1.PreCheckoutRequest
-	(*ForwardPaymentRequest)(nil),       // 11: scrabble.botlink.v1.ForwardPaymentRequest
+	(*PreCheckoutResponse)(nil),         // 11: scrabble.botlink.v1.PreCheckoutResponse
-	(*ForwardPaymentResponse)(nil),      // 12: scrabble.botlink.v1.ForwardPaymentResponse
+	(*ForwardPaymentRequest)(nil),       // 12: scrabble.botlink.v1.ForwardPaymentRequest
-	(*v1.NotifyRequest)(nil),            // 13: scrabble.telegram.v1.NotifyRequest
+	(*ForwardPaymentResponse)(nil),      // 13: scrabble.botlink.v1.ForwardPaymentResponse
-	(*v1.SendToUserRequest)(nil),        // 14: scrabble.telegram.v1.SendToUserRequest
+	(*v1.NotifyRequest)(nil),            // 14: scrabble.telegram.v1.NotifyRequest
-	(*v1.SendToGameChannelRequest)(nil), // 15: scrabble.telegram.v1.SendToGameChannelRequest
+	(*v1.SendToUserRequest)(nil),        // 15: scrabble.telegram.v1.SendToUserRequest
+	(*v1.SendToGameChannelRequest)(nil), // 16: scrabble.telegram.v1.SendToGameChannelRequest
 }
 var file_botlink_v1_botlink_proto_depIdxs = []int32{
-	2,  // 0: scrabble.botlink.v1.FromBot.hello:type_name -> scrabble.botlink.v1.Hello
+	3,  // 0: scrabble.botlink.v1.FromBot.hello:type_name -> scrabble.botlink.v1.Hello
-	4,  // 1: scrabble.botlink.v1.FromBot.ack:type_name -> scrabble.botlink.v1.Ack
+	5,  // 1: scrabble.botlink.v1.FromBot.ack:type_name -> scrabble.botlink.v1.Ack
-	3,  // 2: scrabble.botlink.v1.ToBot.command:type_name -> scrabble.botlink.v1.Command
+	1,  // 2: scrabble.botlink.v1.FromBot.health:type_name -> scrabble.botlink.v1.Health
-	13, // 3: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest
+	4,  // 3: scrabble.botlink.v1.ToBot.command:type_name -> scrabble.botlink.v1.Command
-	14, // 4: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest
+	14, // 4: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest
-	15, // 5: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest
+	15, // 5: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest
-	5,  // 6: scrabble.botlink.v1.Command.chat_gate:type_name -> scrabble.botlink.v1.ChatGateCommand
+	16, // 6: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest
-	8,  // 7: scrabble.botlink.v1.Command.create_invoice:type_name -> scrabble.botlink.v1.CreateInvoiceCommand
+	6,  // 7: scrabble.botlink.v1.Command.chat_gate:type_name -> scrabble.botlink.v1.ChatGateCommand
-	0,  // 8: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot
+	9,  // 8: scrabble.botlink.v1.Command.create_invoice:type_name -> scrabble.botlink.v1.CreateInvoiceCommand
-	6,  // 9: scrabble.botlink.v1.BotLink.ResolveChatEligibility:input_type -> scrabble.botlink.v1.ChatEligibilityRequest
+	0,  // 9: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot
-	9,  // 10: scrabble.botlink.v1.BotLink.ValidatePreCheckout:input_type -> scrabble.botlink.v1.PreCheckoutRequest
+	7,  // 10: scrabble.botlink.v1.BotLink.ResolveChatEligibility:input_type -> scrabble.botlink.v1.ChatEligibilityRequest
-	11, // 11: scrabble.botlink.v1.BotLink.ForwardPayment:input_type -> scrabble.botlink.v1.ForwardPaymentRequest
+	10, // 11: scrabble.botlink.v1.BotLink.ValidatePreCheckout:input_type -> scrabble.botlink.v1.PreCheckoutRequest
-	1,  // 12: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot
+	12, // 12: scrabble.botlink.v1.BotLink.ForwardPayment:input_type -> scrabble.botlink.v1.ForwardPaymentRequest
-	7,  // 13: scrabble.botlink.v1.BotLink.ResolveChatEligibility:output_type -> scrabble.botlink.v1.ChatEligibilityResponse
+	2,  // 13: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot
-	10, // 14: scrabble.botlink.v1.BotLink.ValidatePreCheckout:output_type -> scrabble.botlink.v1.PreCheckoutResponse
+	8,  // 14: scrabble.botlink.v1.BotLink.ResolveChatEligibility:output_type -> scrabble.botlink.v1.ChatEligibilityResponse
-	12, // 15: scrabble.botlink.v1.BotLink.ForwardPayment:output_type -> scrabble.botlink.v1.ForwardPaymentResponse
+	11, // 15: scrabble.botlink.v1.BotLink.ValidatePreCheckout:output_type -> scrabble.botlink.v1.PreCheckoutResponse
-	12, // [12:16] is the sub-list for method output_type
+	13, // 16: scrabble.botlink.v1.BotLink.ForwardPayment:output_type -> scrabble.botlink.v1.ForwardPaymentResponse
-	8,  // [8:12] is the sub-list for method input_type
+	13, // [13:17] is the sub-list for method output_type
-	8,  // [8:8] is the sub-list for extension type_name
+	9,  // [9:13] is the sub-list for method input_type
-	8,  // [8:8] is the sub-list for extension extendee
+	9,  // [9:9] is the sub-list for extension type_name
-	0,  // [0:8] is the sub-list for field type_name
+	9,  // [9:9] is the sub-list for extension extendee
+	0,  // [0:9] is the sub-list for field type_name
 }
 
 func init() { file_botlink_v1_botlink_proto_init() }
@@ -1027,8 +1129,9 @@ func file_botlink_v1_botlink_proto_init() {
 	file_botlink_v1_botlink_proto_msgTypes[0].OneofWrappers = []any{
 		(*FromBot_Hello)(nil),
 		(*FromBot_Ack)(nil),
+		(*FromBot_Health)(nil),
 	}
-	file_botlink_v1_botlink_proto_msgTypes[3].OneofWrappers = []any{
+	file_botlink_v1_botlink_proto_msgTypes[4].OneofWrappers = []any{
 		(*Command_Notify)(nil),
 		(*Command_SendToUser)(nil),
 		(*Command_SendToChannel)(nil),
@@ -1041,7 +1144,7 @@ func file_botlink_v1_botlink_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_botlink_v1_botlink_proto_rawDesc), len(file_botlink_v1_botlink_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   13,
+			NumMessages:   14,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

pkg/proto/botlink/v1/botlink.proto

@@ -48,14 +48,30 @@ service BotLink {
 }
 
 // FromBot is a message the bot sends to the gateway: the opening Hello, then one
-// Ack per Command.
+// Ack per Command and a periodic Health report.
 message FromBot {
   oneof msg {
     Hello hello = 1;
     Ack ack = 2;
+    Health health = 3;
   }
 }
 
+// Health is a periodic report the bot pushes up the stream so the gateway can expose the remote
+// bot's Bot-API health as its own metrics — the bot exports no telemetry of its own (otelcol lives
+// on the main host, unreachable from the bot), so the bot-link is its only channel out. The three
+// counters are DELTAS since the previous Health: the gateway adds them to cumulative counters, so a
+// report lost across a reconnect only undercounts, never corrupts. last_ok_unix is the wall-clock
+// second of the bot's most recent successful Bot API response (any call, including the getUpdates
+// long-poll that returns every poll cycle even when idle) — an absolute liveness stamp the gateway
+// surfaces as a gauge, so a silently stalled bot (no errors, no traffic) is still caught.
+message Health {
+  uint64 connect_failures = 1;  // getUpdates long-poll failures (transport / 5xx) since the last report
+  uint64 api_errors = 2;        // other Bot API failures (transport / 5xx) since the last report
+  uint64 rate_limited = 3;      // Bot API 429 responses since the last report (should stay ~0)
+  int64 last_ok_unix = 4;       // unix seconds of the last successful Bot API response (0 = none yet)
+}
+
 // ToBot is a message the gateway sends to the bot. Only Command is carried today.
 message ToBot {
   Command command = 1;

platform/telegram/README.md

@@ -9,8 +9,9 @@ it. See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) §1/§3/§10/§12/
   validation gRPC API the gateway calls during Telegram auth, on the trusted internal
   network with no VPN. Because it needs no Telegram reachability, **game login stays up
   even when the bot or the bot-link is down**.
-- **`cmd/bot`** (remote) — runs the Bot API long-poll (Mini App launch + `/start`
+- **`cmd/bot`** (remote) — runs the Bot API long-poll (Mini App launch, `/start`
-  deep-links) and `sendMessage`, the only component reaching the Telegram Bot API. It
+  deep-links, the `/support` info reply) and `sendMessage`, the only component reaching
+  the Telegram Bot API. It
   holds **no inbound port**: it dials the gateway over a reverse **mTLS bot-link** and
   executes the send commands the gateway pushes, so its egress can run on a host with
   native Telegram access (a VPN sidecar in the test contour, a separate host in prod).
@@ -49,6 +50,13 @@ Telegram identity to an account from a browser. Both map a rejection to gRPC
   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.
+- **Support command.** `/support` replies with a fixed support-desk info message — the
+  operators' working hours and what to include (a description and, when possible,
+  screenshots). Like `/start` it answers only in a private chat and is **Russian or
+  English** by the sender's reported language, and it is listed in the bot's command menu
+  (localized, Russian/English). It is a dedicated command handler, so it intercepts
+  `/support` before the support relay below — the command line itself is not forwarded to
+  operators, while the user's following description still is.
 - **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
@@ -62,7 +70,12 @@ Telegram identity to an account from a browser. Both map a rejection to gRPC
   the bot applies it — but only to a member currently in the chat (it probes one user with
   `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.
+  `chat_member` updates, which Telegram delivers only to a chat admin. The bot also **removes
+  the automatic pin** Telegram places on every channel post auto-forwarded into this linked
+  chat (the `Message.is_automatic_forward` marker): it unpins only that one message
+  (`unpinChatMessage` by id), so a pin set by a human admin — or by the bot for another
+  message — is never touched. This needs the **pin-messages** right (`can_pin_messages`) in
+  addition to "Ban users"; a startup self-check warns when it is missing.
 - **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
@@ -76,7 +89,8 @@ Telegram identity to an account from a browser. Both map a rejection to gRPC
   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.
+  The relay is bot-local (no backend, no bot-link) and a forwarded message gets no automatic
+  reply (the `/support` command above aside).
 - **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