Merge pull request 'fix(gateway): allow the native WebView origin via CORS (native stuck-offline)' (#270) from feature/native-cors into development

The packaged native app (Capacitor) serves the bundled SPA from a localhost scheme, so its Connect calls to erudit-game.ru are cross-origin. The gateway had no CORS handling, so the preflight OPTIONS returned 405 with no Access-Control-Allow-Origin and the WebView blocked every RPC — a native build could never reach the gateway and stayed stuck offline (the native online path was never exercised on-device; on-device D was airplane-mode only). Add a CORS middleware that answers the preflight and sets the response headers for the native localhost origins (https/http/capacitor://localhost); web is same-origin and untouched. Fixes the native emulator 'starts offline, can't go online' report.

.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_RUSTORE_* 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_RUSTORE_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_RUSTORE_KEYSTORE_BASE64 secret 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_RUSTORE_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_RUSTORE_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_RUSTORE_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 }}
@@ -366,6 +371,13 @@ jobs:
           SMTP_RELAY_HOST: ${{ vars.SMTP_RELAY_HOST }}
           SMTP_RELAY_PORT: ${{ vars.SMTP_RELAY_PORT }}
           SMTP_RELAY_TLS: ${{ vars.SMTP_RELAY_TLS }}
+          # Direct-rail (Robokassa) sandbox intake on the contour: the test shop's merchant login +
+          # Password1/Password2. IsTest is forced to 1 below so the contour can never take real money
+          # (independent of the shop's own mode). Empty login leaves the direct rail off.
+          ROBOKASSA_MERCHANT_LOGIN: ${{ secrets.TEST_BACKEND_ROBOKASSA_MERCHANT_LOGIN }}
+          ROBOKASSA_PASSWORD1: ${{ secrets.TEST_BACKEND_ROBOKASSA_PASSWORD1 }}
+          ROBOKASSA_PASSWORD2: ${{ secrets.TEST_BACKEND_ROBOKASSA_PASSWORD2 }}
+          ROBOKASSA_TEST: "1"
           SMTP_RELAY_FROM: ${{ vars.TEST_SMTP_RELAY_FROM }}
           # Operator alerts: backend admin emails (new feedback / complaints) + Grafana
           # infra alerts. Distinct senders + recipients; Grafana uses the relay's STARTTLS
@@ -400,6 +412,9 @@ jobs:
           # the VK ID redirect URL is derived from PUBLIC_BASE_URL in the run step below.
           VITE_VK_APP_LINK: ${{ vars.VITE_VK_APP_LINK }}
           VITE_VK_APP_ID: ${{ vars.VITE_VK_APP_ID }}
+          # Rewarded-ad test stub: set TEST_VITE_ADS_STUB=1 to swap real ads for a toast on the
+          # contour (empty = real ads, for capturing the real VK ad result). Prod never sets it.
+          VITE_ADS_STUB: ${{ vars.TEST_VITE_ADS_STUB }}
           # VITE_GATEWAY_URL omitted: the SPA is served same-origin, so it stays the
           # compose ":-" empty default. Other unset vars likewise fall to their defaults.
           POSTGRES_DB: ${{ vars.TEST_POSTGRES_DB }}
@@ -497,6 +512,83 @@ jobs:
           docker logs --tail 50 scrabble-backend || true
           exit 1
 
+      - name: Probe the /offer/ public offer page is served
+        run: |
+          set -u
+          # /offer/ is rendered by the render sidecar: it splices the live catalog price list
+          # (fetched from the backend's internal endpoint) into the committed ui/legal/offer_ru.md.
+          # If the @offer caddy route is missing, the request falls to the landing shell (also 200),
+          # and if the backend fetch fails the sidecar returns 502 — so assert offer-specific content
+          # (the seller INN, §11) AND that the pricing marker was substituted (proves the fetch +
+          # splice ran), never just the status. Data-independent: an empty catalog still substitutes
+          # the marker with nothing, so "pricing_template" must be absent either way.
+          # Full body is needed (the INN is in §11 and the marker check spans the page), so this
+          # 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
+          # /pay/robokassa/result must reach the gateway, not fall to the landing catch-all. An
+          # unsigned probe is rejected downstream, so the gateway answers a 4xx/5xx (never a 200 or
+          # a 404 landing.html), which proves the edge route is wired.
+          out="$(docker run --rm --network edge alpine:3.20 wget -S -q -O /dev/null http://scrabble/pay/robokassa/result 2>&1 || true)"
+          echo "$out" | grep -E "HTTP/" || true
+          if echo "$out" | grep -qE "HTTP/1\.1 (4|5)[0-9][0-9]"; then
+            echo "ok: /pay/ reaches the gateway (non-landing response)"
+          else
+            echo "FAIL: /pay/robokassa/result did not reach the gateway (landing catch-all?)"
+            docker logs --tail 50 scrabble-gateway || true
+            exit 1
+          fi
+
       - name: Probe the /dict edge route reaches the gateway
         run: |
           set -u

.gitea/workflows/prod-deploy.yaml

@@ -99,14 +99,33 @@ jobs:
       GRAFANA_ADMIN_PASSWORD: ${{ secrets.PROD_GRAFANA_ADMIN_PASSWORD }}
       TELEGRAM_BOT_TOKEN: ${{ secrets.PROD_TELEGRAM_BOT_TOKEN }}
       GATEWAY_VK_APP_SECRET: ${{ secrets.GATEWAY_VK_APP_SECRET }}
+      # Robokassa direct-rail (backend BACKEND_ROBOKASSA_*): the prod shop login + the pass phrases
+      # that sign the launch request / verify the Result callback, and the test-mode flag — a var so
+      # go-live is a flag flip, not a secret redeploy ("1" runs test payments against the test
+      # passwords; empty/"0" is live). An empty login leaves the direct rail disabled.
+      ROBOKASSA_MERCHANT_LOGIN: ${{ secrets.PROD_BACKEND_ROBOKASSA_MERCHANT_LOGIN }}
+      ROBOKASSA_PASSWORD1: ${{ secrets.PROD_BACKEND_ROBOKASSA_PASSWORD1 }}
+      ROBOKASSA_PASSWORD2: ${{ secrets.PROD_BACKEND_ROBOKASSA_PASSWORD2 }}
+      ROBOKASSA_TEST: ${{ vars.PROD_BACKEND_ROBOKASSA_TEST }}
       # VK ID web login: the "Web" app id (the gateway reuses it as GATEWAY_VK_ID_APP_ID at
       # runtime) + the app's protected key. Both shared across contours. The redirect URL is
       # 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

@@ -61,9 +61,19 @@ jobs:
       # the SAME env.sh (email / VK login / Grafana alerts survive a rollback). TELEGRAM_MINIAPP_URL
       # and GRAFANA_ROOT_URL are derived from PUBLIC_BASE_URL in deploy/write-prod-env.sh.
       GATEWAY_VK_APP_SECRET: ${{ secrets.GATEWAY_VK_APP_SECRET }}
+      # Robokassa direct-rail: the rollback re-renders the same runtime env (write-prod-env.sh), so
+      # it must carry the same credentials or the direct rail goes dark after a rollback.
+      ROBOKASSA_MERCHANT_LOGIN: ${{ secrets.PROD_BACKEND_ROBOKASSA_MERCHANT_LOGIN }}
+      ROBOKASSA_PASSWORD1: ${{ secrets.PROD_BACKEND_ROBOKASSA_PASSWORD1 }}
+      ROBOKASSA_PASSWORD2: ${{ secrets.PROD_BACKEND_ROBOKASSA_PASSWORD2 }}
+      ROBOKASSA_TEST: ${{ vars.PROD_BACKEND_ROBOKASSA_TEST }}
       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

PLAN.md

@@ -33,16 +33,19 @@ status — without re-deriving decisions.
 | E1 | Trusted platform signal | 1 | DONE |
 | E2 | Currency + benefit core | 1 | DONE |
 | E3 | Wallet UI | 1 | DONE |
-| E4 | Durability (PITR) | 2 | WIP |
-| E5 | Payment intake | 2 | TODO |
-| E6 | Ads | 2 | TODO |
-| E7 | Admin & reports | 2 | TODO |
-| E8 | Guest limits | — | TODO |
+| E4 | Durability (PITR) | 2 | DONE |
+| E5 | Payment intake | 2 | DONE |
+| E6 | Ads | 2 | DONE |
+| E7 | Admin, reports & catalog | 2 | DONE |
+| E8 | Guest limits | — | DONE |
 | E9 | Tournament fee | future | TODO |
+| E10 | Multi-shop direct rail + ИП fiscalization | 2+ | DONE |
+| E11 | Payment availability kill switch + per-account override | 2 | DONE |
 
 **Release 1** = full mechanics with no real money, exercised via `admin_grant` (E0→E1→E2→E3).
 **Release 2** = money (E4→E5→E6→E7). E8 is standalone (game-behaviour change, can run in
-parallel). E9 is future.
+parallel). E9 is future. E10 splits the `direct` rail into per-channel Robokassa shops + ИП
+fiscalization (post-launch, backend-first).
 
 ---
 
@@ -446,8 +449,8 @@ noun agreement). Svelte whitespace/`$state` naming gotchas apply.
 
 ## E4 — Durability (PITR)
 
-**Status:** WIP — repo artifacts landed; **prod arming pending** (owner-coordinated, before
-E5). · **Release 2** · depends on: E0 (schema exists) · mechanics: PAYMENTS §14 (D4).
+**Status:** DONE — armed + restore-drilled on prod (v1.13.0, 2026-07-09). · **Release 2** ·
+depends on: E0 (schema exists) · mechanics: PAYMENTS §14 (D4).
 
 **Goal.** Continuous WAL archiving with point-in-time recovery, armed **before the first
 real money** is accepted (E5 prod). Protects both money and game data.
@@ -479,30 +482,73 @@ real money** is accepted (E5 prod). Protects both money and game data.
   `-n backend`, silently excluding `payments`); manual-restore runbook updated.
 - Full PITR runbook + arming sequence + recorded assessment in `deploy/README.md`.
 
-**Prod arming (SEPARATE — owner-coordinated, before E5; NOT the artifacts PR).** Owner creates
-the Selectel S3 bucket + the `PROD_PGBACKREST_*` secrets/variables (incl. `ARCHIVE_MODE=on`);
-then promote `development → master` → `prod-deploy` (archive_mode on behind the maintenance
-window), `pgbackrest stanza-create` + first base backup + `check`, re-run Ansible with
-`-e pitr_enabled=true`, and run the restore drill on an isolated one-shot target. Exact steps:
-`deploy/README.md` (point-in-time recovery — arming).
+**Prod arming (completed 2026-07-09 with the v1.13.0 release).** Owner created the Selectel S3
+bucket (`erudite`, ru-6) + the `PROD_PGBACKREST_*` secrets/variables (incl. `ARCHIVE_MODE=on`);
+promoted `development → master` → `prod-deploy` (archive_mode on behind the maintenance window),
+then `stanza-create` + first base backup (31.9 MB cluster → 3.7 MB in the repo) + `check`, the
+Ansible `-e pitr_enabled=true` timer, and a restore drill on an isolated one-shot target (data
+intact, then wiped). Exact steps: `deploy/README.md` (point-in-time recovery — arming).
 
 **Tests.** Restore drill on an isolated one-shot instance (base + WAL → target timestamp),
 recorded in `deploy/README.md`. No app-level tests. Local verification: `docker compose config`
 valid + the custom PG image builds (archiving inert on the contour).
 
-**Done-criteria.** Artifacts merged with archiving inert. **Fully done** at arming: WAL
-archiving live on prod PG; a timed restore verified; cost + perf assessment reviewed; runbook
-current in `deploy/README.md`.
+**Done-criteria (met).** WAL archiving live on prod PG (v1.13.0); a restore verified on an
+isolated one-shot target; cost + perf assessment reviewed; runbook current in
+`deploy/README.md`.
 
 **Notes/risks.** The repository **cipher passphrase is unrecoverable if lost** — stored apart
-from the S3 keys. Enabling `archive_mode` restarts postgres (rides the prod-deploy maintenance
-window). Migrations stay expand-contract so image rollback remains DB-safe alongside PITR.
+from the S3 keys. Manual/timer pgBackRest runs use `docker exec -u postgres … --pg1-user=scrabble`
+(docker exec is root; the DB superuser role is `scrabble`, not `postgres`) — the systemd timer
++ the runbook carry this. Enabling `archive_mode` restarts postgres (rode the prod-deploy
+maintenance window). Migrations stay expand-contract so image rollback remains DB-safe with PITR.
 
 ---
 
 ## E5 — Payment intake
 
-**Status:** TODO · **Release 2** · depends on: E0, E1, E2, E4 · mechanics: PAYMENTS §9, §12.
+**Status:** DONE · **Release 2** · depends on: E0, E1, E2, E4 · mechanics: PAYMENTS §9, §12.
+
+**Delivery & baked decisions.** Shipped as a linear PR stack (owner's choice), Robokassa first.
+Resolved: match the order by a Robokassa **`Shp_order`** custom parameter, not the numeric `InvId`
+(an order id is a uuid); idempotency key = the order id (`provider_payment_id = order_id`); the НПД
+receipt is formed **shop-side in the Robokassa cabinet**, so no `Receipt` parameter is sent; a
+chargeback **never drives the balance negative** (D27 stands, `balances_chips_chk` kept), so E5 is
+**schema-free** (no migration, no contour wipe). Delivered on `feature/payment-intake-robokassa`:
+the offer page (`/offer/`), the order/`fund` engine (idempotent, honours an expired order), the
+`internal/robokassa` adapter, the `POST /wallet/order` + internal Result-callback handlers (a D36
+confirmed-email gate on `direct`), the pending reaper, the `wallet.order` edge wire + the public
+`/pay/*` routes, the Wallet purchase CTA, the contour deploy env (IsTest forced), and the
+`payment_events` dispatcher — an in-app wallet-refresh push (KindNotification `"payment"`) with a
+self-closing provider-return page (the payment opens in a separate window) and a return-focus
+refetch fallback. The **VK Votes rail** is delivered too: the client opens
+`VKWebAppShowOrderBox({item: order_id})`; a two-phase signed server callback (`get_item` → the pack
+title + vote price; a chargeable `order_status_change` → the same `Fund` with source=`vk`, idempotent
+on VK's own order id) is verified at the gateway with the app protected key (`GATEWAY_VK_APP_SECRET`,
+already deployed) and proxied to the backend intake. The **Telegram Stars rail** is delivered on
+`feature/payment-intake-tg-stars`: only the bot reaches Telegram, so the **invoice is minted by the
+bot** — on the `wallet.order` path the gateway sends a new `CreateInvoice` command over the reverse
+bot-link and the bot returns the `createInvoiceLink` (XTR) in its Ack, handed to the client's
+`WebApp.openInvoice`. The bot answers `pre_checkout_query` via a new bot→gateway **`ValidatePreCheckout`**
+unary (backed by the backend: the order must exist, be still creditable and **not already paid** — the
+reusable-invoice double-pay guard — with a matching amount); the decline reason is localised to the
+order account's language. A completed `successful_payment` is persisted to a pure-Go **SQLite outbox**
+(`modernc.org/sqlite`) then forwarded by a new bot→gateway **`ForwardPayment`** unary into the same
+`Fund` (source=`telegram`, idempotent on `telegram_payment_charge_id`, honours an expired order),
+re-driven at startup and every 30 s. The rail is wired by `TELEGRAM_STARS_OUTBOX_DIR` (defaults to the
+bot `/data` volume) but stays **inert until a chip pack carries an XTR price**, so seeding a Stars price
+in the admin is the go-live. Finally **refunds** are delivered on `feature/payment-intake-refunds`: a
+single `Refund` engine (`internal/payments`) reverses a paid order best-effort, exactly once —
+idempotent on `(provider, provider_refund_id)`, revoking the funded chips **floored at 0** (never
+negative, D27), and recording the unrecoverable remainder (chips already spent) as a per-account
+**loss + abuse flag** in the new additive `payments.account_risk` table (read by the E7 report). The
+refund ledger row's chip delta is what was actually reclaimed (the ledger stays reconcilable); the
+full reversal rides in its snapshot; the order stays `paid`. **No rail pushes an unsolicited refund**
+— all are admin-triggered (E7): Robokassa refund API / cabinet (auto-polling deferred — a worker not
+worth it at low chargeback volume), VK via support, Telegram `refundStarPayment`. `failed` events are
+not wired (no rail signals a hard post-charge server decline). The migration is **additive** (a new
+table only), so E5 stays rollback-safe / no contour wipe. That closes E5. Deferred to a later stage:
+hiding the ad banner on a no-ads purchase (a spend-path `NotifyBanner`, with the owner's agreement).
 
 **Goal.** Accept real money on all three rails into the payments domain: order-flow,
 verified provider callbacks, idempotency, the TG bot SQLite outbox, the event dispatcher,
@@ -525,12 +571,14 @@ receipts, and refunds.
 
 **TG bot outbox (`platform/telegram/`).**
 
-- The bot receives `successful_payment` (and `pre_checkout_query`) via Bot API. Add a
-  **SQLite** store on the bot's disk: on receipt, persist → ack the Telegram update → forward
-  to a backend payments-intake endpoint (internal, authenticated over the existing reverse
-  mTLS bot-link) → on backend ack, mark `forwarded`. Retries with backoff; re-drive
-  undelivered on restart. Backend intake dedups by `telegram_payment_charge_id`.
-- Provide the invoice creation path (Stars) from the Mini App via the bot as needed.
+- The bot receives `successful_payment` (and `pre_checkout_query`) via Bot API. A **SQLite**
+  store on the bot's disk (`internal/outbox`): on receipt, persist → forward over the reverse
+  mTLS bot-link to the **gateway** (a `ForwardPayment` unary; the bot cannot dial the backend
+  directly) → the gateway proxies to the backend payments-intake REST → on a durable response,
+  mark `forwarded`. Re-drive undelivered on startup and on a 30 s tick. Backend intake dedups by
+  `telegram_payment_charge_id`.
+- Invoice creation (Stars) is minted by the bot (`createInvoiceLink`, XTR) on the gateway's
+  `CreateInvoice` bot-link command, returned to the Mini App as the `openInvoice` link.
 
 **Events & notifications.**
 
@@ -542,9 +590,13 @@ receipts, and refunds.
 **Receipts (§12).** Robokassa self-employed НПД receipt on payment (provider config); VK
 handles Votes tax itself; TG Stars — no receipt.
 
-**Refunds (§9).** ToS non-refundable; admin manual refund (ties to `accountdelete`); external
-`refunded` events honoured — best-effort benefit revoke (never negative; record loss + abuse
-flag if spent), ledger `refund` row. Ledger export-ready (reconciliation not built).
+**Refunds (§9).** ToS non-refundable. **All refunds are admin-triggered** (E7): no rail pushes an
+unsolicited refund — Robokassa refund API / cabinet (auto-polling deferred as a low-value worker),
+VK via support, Telegram `refundStarPayment`. One `Refund` engine reverses a paid order best-effort,
+exactly once (idempotent on `(provider, provider_refund_id)`): revoke floored at 0 (never negative),
+unrecoverable remainder → per-account loss + abuse flag (`payments.account_risk`), a `refund` ledger
+row (chip delta = revoked, full reversal in the snapshot). `failed` events are not wired (no rail
+signals a hard post-charge server decline). Ledger export-ready (reconciliation not built).
 
 **Tests.**
 
@@ -569,9 +621,42 @@ force-recreate when the Caddyfile changes.
 
 ## E6 — Ads
 
-**Status:** TODO · **Release 2** · depends on: E2 (chips), E5 (rewarded credits via intake) ·
+**Status:** DONE · **Release 2** · depends on: E2 (chips), E5 (rewarded credits via intake) ·
 mechanics: PAYMENTS §10.
 
+**Delivery & baked decisions.** Shipped as a linear PR stack (owner's choice): **rewarded first**,
+then interstitial. Baked: the interstitial cooldowns already exist in `payments.config` (E0) and the
+per-origin banner suppression is already done (E2 `AdFree`), so E6 is the two ad DISPLAY paths + the
+rewarded credit. **VK reality (checked live in the VK docs via Playwright):** VK Mini App ads
+(`VKWebAppShowNativeAds`, both `reward` and `interstitial`) expose **only a client-side `data.result`
+boolean** — no server verify, no signature. So **D29 is amended**: rewarded is **client-attested**,
+guarded by a server **daily + hourly cap** (config `reward_daily_cap` / `reward_hourly_cap`, default
+50 / 10) that is both anti-abuse and an economic conversion lever (limits free chips so players buy);
+the cooldown state for the interstitial is **client-mirrored** (owner's pick). Delivered on
+`feature/ads-rewarded` (the **rewarded** slice): the ads-network abstraction (`ui/src/lib/ads.ts`, VK
+impl) + the VK bridge (`vkRewardedReady` / `vkShowRewarded`), the backend `CreditReward` (VK-only,
+order-less, idempotent on a client nonce, floored by the caps, payout from config
+`rewarded_payout_chips` default 0 = off), the `wallet.reward` edge op returning the updated wallet
+(with `reward_chips` gating the "watch for chips" CTA), and a **contour test stub** (`VITE_ADS_STUB` →
+a toast instead of a real ad; prod always real). A temporary diagnostic confirmed on the contour that
+VK returns **only `{result:true}`** (no token/signature) — client-attested is final, no hardening
+possible; the diagnostic is removed. The slice also **corrects the VK-iOS freeze to purchase-only**
+(rewarded on VK-iOS earns chips, which the old blanket "spend freeze" then blocked from spending —
+Apple forbids only *buying* in-app values, not spending or earning them; `vkFrozen()` now gates only
+`CreateOrder`, not `spendableSources`, so VK-wallet chips spend on VK-iOS). Delivered on
+`feature/ads-interstitial` (the **interstitial + D31** slice): the post-move fullscreen interstitial
+as a **client-mirrored** gate — the backend `adsFor` puts the config cooldowns + a `suppressed` flag
+(the no-ads / `no_banner` gate, same as the banner) on the profile (`Profile.ads`), and
+`ui/src/lib/ads.ts` `maybeShowInterstitial` self-gates on the last-shown time per kind in
+`localStorage`, showing a VK interstitial (`vkShowInterstitial`) after a **confirmed play or a hint
+only** (never a pass / exchange / resign), VK-only, offline banner-only, with the same `VITE_ADS_STUB`
+toast on the contour. The slice also lands **D31 step 1 (contract-code)**: the domain no longer reads
+or writes the deprecated `accounts.hint_balance` / `paid_account` columns — the `Account` fields, the
+dead `account.SpendHint`, `account.GrantHints` and the admin **grant-hints** action are removed, and
+the in-game hint display now comes wholly from the payments benefit (`HintsAvailable`). The **columns
+stay** (no migration → image rollback is DB-safe); a later contract-PR does the `DROP` once E6 is
+stable on prod.
+
 **Goal.** VK video ads: the post-move interstitial (frequency-gated) and the rewarded video
 (credits chips via server verify), plus extending the existing banner suppression to
 per-origin.
@@ -586,8 +671,9 @@ per-origin.
 - **Interstitial** (post-move fullscreen), configurable server values (from `payments`
   config): global per-user cooldown across all games (default 5 min); `vs_ai` 30 min; a hint
   application triggers a post-move interstitial independently with its own 1-min cooldown;
-  offline banner-only; respect VK's own frequency caps. Cooldown state tracked server-side
-  (per user) or client-mirrored from a server value — pick and document at implementation.
+  offline banner-only; respect VK's own frequency caps. Cooldown state is **client-mirrored**
+  (the chosen option): the server sends the cooldowns + `suppressed` on the profile and the
+  client self-gates on a per-kind last-shown time in `localStorage` — no per-move round-trip.
 - **Banner suppression:** extend `ads.Eligible` (`backend/internal/ads/ads.go` :107) to gate
   on the **origin benefit applicable in the current context** (E2 interface) instead of the
   single legacy flag. No-ads suppresses banner + interstitial; rewarded never suppressed.
@@ -610,75 +696,177 @@ it tunes without a store release.
 
 ---
 
-## E7 — Admin & reports
+## E7 — Admin, reports & catalog
 
-**Status:** TODO · **Release 2** · depends on: E2 (ledger/grant), E5 (payments/refunds) ·
-mechanics: PAYMENTS §11.
+**Status:** DONE · **Release 2** · depends on: E2 (ledger/grant/spend), E5 (payments/refunds),
+E6 (D31 retired the legacy `hint_balance`/`paid_account`) · mechanics: PAYMENTS §11, §12, D32.
 
-**Goal.** The admin console financial surface: per-user report, admin grant UI, manual
-refund UI, ledger export.
+**Delivery & baked decisions (this planning round).** A linear PR stack into `development`.
 
-**Work (`/_gm`, `backend/internal/server/handlers_admin_console.go` + `adminconsole/`).**
+- **Archived product = the existing `product.active` flag** (no new column, no migration):
+  `active=false` **is** "archived". Its three behaviours already hold — hidden from the user
+  storefront (`store_catalog.go` filters `active`), an **in-flight external payment still
+  credits** (the `fund` credit path resolves the order and never re-checks `active`; only order
+  *creation* / chip *spend* require `active`), and a product with any order/ledger row **cannot
+  be hard-deleted** (FK `orders→product` / `ledger→product` are RESTRICT). The admin toggle is
+  labelled **Archive / Unarchive**.
+- **Delete vs archive:** the editor offers a hard **Delete** only for a product with **no
+  orders and no ledger rows** (never transacted — the FK is the DB backstop); a transacted
+  product is **archive-only**.
+- **Admin grant = raw atoms + by-product.** Keep the quick raw-atom grant (N hints / no-ads
+  days / forever) AND add grant-by-product: pick a defined product (including archived "reward"
+  bundles) and grant its atoms. Both write an `admin_grant` ledger row; by-product records
+  `product_id` + the snapshot. **Both refuse any set containing `chips`** (admin never grants
+  currency) **or `tournament`** (no credit target until E9) — an explicit refusal, never a
+  silent no-op.
+- **Manual refund = full order only** for now (the E5 `Refund` engine takes an amount; partial
+  is a later add if needed).
+- **Tournament stays atom-only (E0); its entry economy is E9.** The catalog editor can compose
+  products carrying the `tournament` atom (archived templates for E9), but granting/spending a
+  `tournament` atom is refused until E9 designs the storage (recurring types, each its own
+  benefit + price) — see E9. Adding a `benefits.tournament` counter now was rejected: the model
+  is multi-type, so a single column would be wrong and force a second DB break.
+- The admin grant **no longer mirrors `grant-hints`** (E6/D31 removed that action); it is a
+  fresh action on `payments.Grant`.
 
-- **Per-user financial panel** on the existing user card (`consoleUserDetail` :343,
-  `UserDetailView`): segment balances, payments, spends, grants, refunds, full history —
-  read from the append-only ledger + materialized cache.
-- **Admin grant** action (mirror the existing `POST /_gm/users/:id/grant-hints`): grant
-  concrete values (no-ads days / hints), **origin picker**, **never chips**; writes an
-  `admin_grant` ledger row (E2 `Grant`).
-- **Manual refund** action: admin-initiated refund of a specific order (ties to the refund
-  path); records a `refund` ledger row; best-effort benefit revoke.
-- **Ledger export**: CSV/JSON export of the ledger for tax reporting + future Robokassa
-  reconciliation (export-ready schema; reconciliation itself not built).
+**Goal.** The admin console financial surface — per-user report, admin grant, manual refund,
+ledger export — plus the **configurable product catalog editor** (D32).
+
+**Work (`/_gm`, `handlers_admin_console.go` + `adminconsole/`, `internal/payments/`).**
+
+- **Per-user financial panel** on the user card (`consoleUserDetail`, `UserDetailView`): segment
+  chip balances `(account, source)`, benefits `(account, origin)` (hints, no-ads until/forever),
+  and the full append-only ledger (fund/spend/admin_grant/refund — amount, origin, product,
+  provider, snapshot) from the ledger + materialized cache. Replaces the retired
+  `PaidAccount`/`HintBalance` fields with the segmented view.
+- **Catalog editor** (`/_gm/catalog`): list every product (active + archived) with its atoms and
+  per-method/currency prices; create/edit (title, atom items `atom_type→quantity`, price rows
+  `method+currency→amount`); **Archive/Unarchive** (`active`); **Delete** (never-transacted
+  only). Enforce the projection's shape: a **pack** (carries `chips`) needs a money price per
+  method; a **value** (no `chips`) needs a single `CHIP` price. A `tournament`-bearing product is
+  allowed in composition but cannot be activated for sale until E9.
+- **Admin grant** action: raw atoms (hints / no-ads days / forever) and by-product (a value
+  product, incl. archived); **origin picker**; refuses `chips`/`tournament`; `admin_grant` ledger
+  row (+ `product_id`/snapshot for by-product) via `payments.Grant`.
+- **Manual refund** action: refund a specific paid order **in full** — a `refund` ledger row +
+  best-effort floor-0 benefit revoke (E5 `Refund`).
+- **Ledger export**: CSV/JSON for tax + future Robokassa reconciliation (export-ready;
+  reconciliation itself not built).
 - Auth unchanged: gateway Basic-Auth in front of `/_gm` + backend same-origin CSRF on POSTs.
 
 **Tests.**
 
-- unit: report view assembly; grant refuses chips; export shape.
-- integration: grant/refund write correct ledger rows; report reflects balances+history.
+- unit: panel view assembly; catalog pack/value shape projection; grant refuses chips + tournament;
+  editor validation (pack⇒money price, value⇒CHIP price); export shape.
+- integration: grant (raw + by-product) writes the right `admin_grant` row + benefit; refund writes
+  a `refund` row + floor-0 revoke; catalog CRUD round-trips (create→edit→archive→delete-if-clean);
+  delete refused on a transacted product; panel reflects balances + benefits + history.
 
-**Done-criteria.** An operator can see a user's full financial picture, grant concrete
-values (origin-picked, never chips), issue a manual refund, and export the ledger.
+**Done-criteria.** An operator can: see a user's full financial picture; create/edit/archive
+products + prices and delete only never-transacted ones; grant concrete values raw or by-product
+(origin-picked, never chips/tournament); refund an order in full; export the ledger.
 
-**Notes/risks.** `/_gm` per-user detail already surfaces `PaidAccount`/`HintBalance` — replace
-those with the segmented view as the legacy columns retire.
+**PR stack (linear into `development`, all merged).**
+
+1. ~~**Per-user financial panel**~~ (#230) — read-only ledger/segments/benefits on the user card;
+   retired the `PaidAccount`/`HintBalance` display.
+2. ~~**Catalog editor**~~ (#231) — product/atom/price CRUD + archive/unarchive + delete-if-clean +
+   shape validation.
+3. ~~**Admin grant**~~ (#232, + the D31 hint-wallet wire cleanup that surfaced there) — raw +
+   by-product, refuse chips/tournament, origin-picked, `admin_grant` + snapshot.
+4. ~~**Manual refund** (full order via E5 `Refund`) + **ledger CSV export**~~ — `RefundOrderFull`
+   (idempotent, floor-0 revoke) on each fund row; `/_gm/ledger.csv`.
+
+**Notes/risks.** High-blast-radius (money, ledger — append-only, trigger-enforced). No mixed-in
+refactors. The catalog editor becomes the source of truth for products; the contour SQL seeds
+become bootstrap-only.
 
 ---
 
 ## E8 — Guest limits
 
-**Status:** TODO · **standalone** (game-behaviour change; can run in parallel) · depends on:
-none · mechanics: PAYMENTS §6.
+**Status:** DONE · **standalone** (game-behaviour change) · depends on: none · mechanics: PAYMENTS §6.
 
-**Goal.** A registration funnel: cap what a guest can do, enforced **server-side** (today the
-gating is UI-only).
+**Goal.** A registration funnel: cap what a guest can do, enforced **server-side** (today UI-only),
+with configurable per-tier × per-kind limits so the pressure tunes without a release.
 
-**Finding (verified).** The friend/invitation paths do **not** check `is_guest` on the
-server — only the UI hides them: `social/friends.go:50` `SendFriendRequest`,
-`robotfriends.go:41` `RequestInGame`, `friendcodes.go:67` `RedeemFriendCode`,
-`lobby/invitations.go:208` `CreateInvitation`. A guest with a valid `X-User-ID` can call them
-in the UI's stead.
+**Finding (verified).** Two gaps. (a) The friend/invitation paths do **not** check `is_guest` on the
+server — only the UI hides them: `social/friends.go`, `robotfriends.go`, `friendcodes.go`,
+`lobby/invitations.go`. A guest with a valid `X-User-ID` can call them. (b) A **pre-existing** flat
+cap already existed: `game.MaxActiveQuickGames`=10 — a **combined** cap on `active`+`open` quick
+games (vs_ai+random together, friend games excluded), counted by `CountActiveQuickGames`, enforced at
+the handler (`ensureUnderGameLimit`) with **409 `game_limit_reached`**, surfaced as `at_game_limit`.
+E8's per-tier × per-kind config **subsumes and replaces** it (decided: option A).
+
+**Delivery & baked decisions (this planning round).** A linear PR stack; E8 is game-behaviour, no
+payments mixed in.
+
+- **`games.game_kind smallint DEFAULT 0`** (0=unknown — pre-E8 games, never gated; 1=vs_ai; 2=random;
+  3=friends), set on creation (`StartVsAI`=1, `Enqueue`=2, a friend invitation=3). Existing games
+  stay 0 and fall outside the gate.
+- **Limits are per-tier × per-kind**, in a **new single-row `backend.config`** table:
+  `guest_{vs_ai,random,friends}_limit` + `durable_{vs_ai,random,friends}_limit` (smallint,
+  **`-1`=unlimited**), seeded `(1,1,0, 10,10,10)`. A guest is capped at 1 vs_ai + 1 random (friends
+  is moot — the guest gate blocks friend games); a durable account is **10 per kind** — the old flat
+  MaxActiveQuickGames=10, now split per kind. Editable in the admin.
+- **The old flat cap is removed** (option A, owner-agreed): `MaxActiveQuickGames`,
+  `CountActiveQuickGames`, `atGameLimit` deleted; the per-tier/kind config is the single mechanism,
+  enforced at the **same handler gate** (`ensureUnderGameLimit(kind)` for `enqueue`
+  random/vs_ai) plus the durable **friends cap** inside `CreateInvitation`. The gate stays out of the
+  game domain — `game.Service.AtGameLimit(account, kind)` only resolves tier + counts.
+- **A hot in-memory cache** fronts the config (read once on start, invalidated on the admin edit —
+  mirrors the payments read-cache) so a login / game-create never queries it.
+- **"Active" = `open` + `active`** (an open, unmatched random game holds a slot); the limit is on
+  **creation** — an existing game is grandfathered, never interrupted.
+- **Limits ride the wire (forward-compat, no double break):** `Profile.game_limits`
+  (`GameLimits{vs_ai, random, friends}` — the caller's tier resolved server-side) + `GameView.kind`,
+  so the client counts active games **per kind** from its lobby and locks the right start button. On
+  a guest → durable upgrade (register / link) the client **re-fetches the profile** so the new
+  (durable) limits apply. The client picks the lock's message by tier: a **guest** → the login funnel;
+  a **durable** account at its cap → a plain "finish a current game first" notice.
 
 **Work.**
 
-- **Server guest gate** on friend-request / redeem-code / invitation-create: refuse when the
-  caller `is_guest` (add an `ErrGuestForbidden`-style guard, as `feedback` already has).
-- **Active-game limits** for guests: at most **1 random-opponent game + 1 vs_ai** concurrently
-  (enforce on game/invitation creation in `lobby`/`game`; today no such limit exists).
-- Keep the existing UI gating; this adds the server as the source of truth.
+- ~~**PR1 — backend + admin (server-side)** — DONE.~~ The migration (`game_kind` + `backend.config`,
+  seeded `1,1,0 / 10,10,10` + jetgen); `game_kind` set on creation and projected onto `game.Game`;
+  the **guest gate** (`ErrGuestForbidden`, mapped to **403 `guest_forbidden`**) on friend-request /
+  redeem-code / befriend-in-game / invitation-create; the **active-limit enforce** — the old flat
+  `MaxActiveQuickGames` mechanism removed and replaced by `ensureUnderGameLimit(kind)` on `enqueue`
+  (random/vs_ai) plus the durable friends cap in `CreateInvitation`, keyed off
+  `game.Service.AtGameLimit`; the **`internal/gamelimits` config + hot cache** (loaded at boot,
+  invalidated on edit); the admin **kind column** in both game lists (`/_gm/games` + the user card)
+  and a **config editor** (`/_gm/limits`) for the six limits.
+- ~~**PR2 — wire + client** — DONE.~~ `Profile.game_limits` (the caller's tier) + `GameView.kind` (FBS
+  + gateway transcode + client codec, committed regen); the client counts active games per kind from
+  the lobby cache (`gamelimits.ts`) and locks a capped new-game start — an **outline 🔒** button that
+  opens `GameLimitModal` instead of a game, native (Telegram `showPopup`) or the in-app `Modal`
+  elsewhere, with two messages by tier: a **guest** sign-in funnel ("Войдите или создайте учётную
+  запись…", Отмена / Вход→`/settings`) and, for a **durable** account at its cap, a plain notice
+  ("Вы достигли лимита одновременных игр, сначала завершите текущие", ОК). The lock lifts via the
+  existing profile re-fetch after a guest→durable upgrade.
+  - **Decision (owner-agreed): the lobby's old `at_game_limit` New-Game tab-disable + notice is
+    removed.** The `at_game_limit` flag (now the random-kind cap) conflicted with the per-kind lock —
+    it hid the New-Game screen where the lock lives, and wrongly blocked starting an unfulfilled kind.
+    The tab is always enabled; the per-kind lock on the start button is the only gate. The wire field
+    `GameList.at_game_limit` stays (unused by the client) for a later cleanup.
 
 **Tests.**
 
-- integration: guest is refused friend/redeem/invitation server-side; guest blocked from a
-  2nd random / 2nd vs_ai; durable account unaffected.
-- UI: guest sees the funnel (existing hides + any new messaging).
+- integration (PR1, done): `game_kind` persisted per path; guest refused friend/redeem/invitation
+  (domain + HTTP 403); guest blocked from a 2nd vs_ai / 2nd random (+ `at_game_limit`); durable on the
+  higher tier; the durable friends cap + config cache reflecting an admin edit; accept stays exempt.
+- unit (PR1, done): the per-tier/kind limit resolution (`Cap`, `LimitsFor`).
+- unit + UI (PR2, done): the client lock logic (`gamelimits.ts` — count/cap/lock), the codec kind +
+  game_limits roundtrip, the gateway transcode game_limits encode, the popup builders, and a mock e2e
+  (`gamelimit.spec.ts`) — a capped start shows 🔒, opens the modal without navigating, and the lock
+  clears when the profile refetch lifts the cap.
 
-**Done-criteria.** Guests are server-limited to 1 random + 1 vs_ai and cannot friend/invite;
-durable accounts unchanged; regression that this does not break existing durable flows.
+**Done-criteria.** A guest is server-capped (default 1 vs_ai + 1 random, configurable) and cannot
+friend/invite; a durable account is capped at 10 per kind (configurable); the client shows the lock +
+the tier-appropriate modal and the cap lifts on registration; durable flows otherwise unchanged.
 
-**Notes/risks.** This changes existing game behaviour — its own tests, its own PR, no
-mixed-in payments changes. Decide whether a guest may finish an already-started game (limit
-on creation, not mid-game) at implementation and record it here.
+**Notes/risks.** Game-behaviour change — own PRs, own tests, no payments mixed in. The limit is on
+creation (existing games grandfathered). The config cache is single-instance (matching the deploy).
 
 ---
 
@@ -687,11 +875,140 @@ on creation, not mid-game) at implementation and record it here.
 **Status:** TODO · **future** · depends on: E0 (atom provisioned), tournament feature ·
 mechanics: PAYMENTS §5, §7.
 
-**Goal.** Charge a chip entry fee for tournaments. The `tournament` atom + a catalog product
-are provisioned in E0/E7; the spend mechanic reuses E2 (`Spend`). The actual tournament
-feature and its coupling to entry are out of scope until the tournament feature exists.
+**Goal.** A chip entry economy for tournaments. The `tournament` atom is provisioned (E0) and
+E7's catalog editor can compose tournament products; E7 deliberately **defers the entry storage
++ credit/spend** here, to avoid guessing the schema.
 
-**Done-criteria.** Deferred — revisit when tournaments are built.
+**Design to settle here (not before — avoid a double DB break).** Tournaments are expected in
+**several recurring types** (daily / weekly / monthly …), each its **own benefit with its own
+price** — so a single `benefits.tournament` counter is wrong. Model the entry store as
+**per-tournament-type** (e.g. a `tournament_type` catalog + a per-`(account, type)` entry
+balance), design the pricing, then:
+
+- lift E7's **refusal** of granting/spending the `tournament` atom (admin grant by-product +
+  chip spend);
+- add the **spend** (charge an entry) reusing E2 `Spend`;
+- wire the coupling to the actual tournament feature (out of scope until it exists).
+
+**Done-criteria.** Deferred — revisit when tournaments are built; this stage owns the
+tournament-entry storage + pricing design.
+
+---
+
+## E10 — Multi-shop direct rail + ИП fiscalization
+
+**Status:** DONE (merged — the multi-shop PR) · **Release 2+ (post-launch, backend-first)** · depends on: E5 (intake/`Fund`,
+the `robokassa` adapter, the Result callback), E7 (the per-user report — channel breakdown) ·
+mechanics: PAYMENTS §9, §12; decisions D41 (rev), D42–D44.
+
+**Goal.** Split the single Robokassa `direct` rail into **per-channel merchant shops** (web,
+android; ios later) — separate merchant accounts / withdrawal / accounting and a per-channel
+breakdown in the E7 report — while keeping **one `direct` wallet** (D42). Land the wallet/identity
+rules the native apps need (email-only anchor, D43) and revise fiscalization for the owner's move
+to **ИП / 54-ФЗ** (D41 rev). All **additive / contour-safe** and **money-live** → expand-contract
+throughout.
+
+**Locked decisions (owner interview 2026-07-14): D41 (rev), D42, D43, D44.** No wallet-model /
+spend-wall change; the split is merchant-account routing under one `direct` segment. Route the shop
+by the **trusted** `X-Platform` subtype, never a client field; unknown → `web`.
+
+**B1 — Config: one shop → a set of shops.**
+
+- `robokassa.Config` (single) → a **shops registry** keyed by channel (`web`, `android`; `ios`
+  later), each 4 fields (`MerchantLogin`/`Password1`/`Password2`/`IsTest`). New env
+  `BACKEND_ROBOKASSA_WEB_*`, `BACKEND_ROBOKASSA_ANDROID_*`.
+- **Expand-contract, no flag-day:** the legacy `BACKEND_ROBOKASSA_*` seeds the `web` shop; add the
+  new vars; retire the legacy set after the prod rollout sets the split vars. `validate()`: a shop
+  with a login must carry both passwords (mirror the current check), per shop.
+- Config/README + `deploy/.env.example` + the deploy ansible vars.
+
+**B2 — Route the shop by channel (intake).**
+
+- `handleWalletOrder` `SourceDirect` branch: pick the shop by `cxt.Subtype` (`web`/`android`;
+  unknown → `web`). Build the payment request from that shop. The subtype rides the trusted
+  gateway-injected `X-Platform` (`<kind>/<subtype>`, `parsePlatformHeader`) — no spoofable client
+  field. **Verify the gateway emits `direct/android` for the native build**; if it sends a bare
+  `direct/`, add the android subtype (small gateway change).
+- Record the chosen `shop` on the order (feeds B5).
+
+**B3 — Per-shop Result callbacks.**
+
+- The callback must select the right `Password2` → each shop gets its own Result URL:
+  **per-shop public edge routes** (mirror the existing single Robokassa Result route, e.g.
+  `…/result/web`, `…/result/android`), each forwarded to the backend and verified with that shop's
+  config, then the same `Fund` (source stays `direct`). Add the routes to the **Caddyfile
+  `@gateway` matcher** (else they fall to the landing catch-all) **+ a CI probe per route**.
+- Keep the legacy single route alive (shop = `web`) through the expand-contract window until the
+  cabinet Result URLs are cut over.
+
+**B4 — ИП fiscalization (D41 rev) — RESOLVED (owner 2026-07-14): cabinet-side only.** The owner keeps
+Robokassa's cabinet auto-fiscalization (a generic чек is acceptable for the ИП); the optional
+itemized-`Receipt` / `Email` code below is **dropped** — not needed. (Kept for context.)
+
+- **Owner/cabinet:** enable the 54-ФЗ cloud kassa in the Robokassa ЛКК (kassa + ОФД + СНО).
+  Required for ИП regardless of code.
+- **Code (optional, itemized чеки):** send a one-line `Receipt` (pack name, qty 1, `sum`, `tax`
+  per СНО, `payment_object`/`payment_method`) + the customer `Email` (the D36 confirmed anchor) in
+  the payment request; extend the signature to `MerchantLogin:OutSum:InvId:Receipt:Password1`
+  (URL-encode `Receipt`). One line fits the current GET redirect; POST-form only as a URL-length
+  fallback. One feature, all shops. **Sequenced last** — the split (B1–B3, B5, B6) needs no
+  fiscalization. Supersedes the E5 §12 shop-side НПД receipt note.
+
+**B5 — Channel in the report (D44).**
+
+- Additive `shop` column on the order (default `web` / backfill from `origin`); a per-channel
+  breakdown in the E7 per-user report (D40). Expand-contract migration (nullable/defaulted column),
+  **contour-safe** (a schema touch → note the contour `DROP SCHEMA` step in `PRERELEASE.md`).
+
+**B6 — Tests + docs.**
+
+- unit: the `robokassa` shops registry + per-shop `VerifyResult` (right `Password2`);
+  signature-with-`Receipt` (B4); intake shop routing by subtype (web/android/unknown→web).
+- integration: order→per-shop callback→credit (each route), a duplicate credits once, an expired
+  order still honoured; the `shop` recorded + reported.
+- docs: `PAYMENTS.md` (+`_ru`) the multi-shop topology + the ИП/54-ФЗ receipt revision;
+  `deploy/README` + `.env.example` the new vars + the per-shop Result routes + probes;
+  `PRERELEASE.md` the `shop` column contour step.
+
+**Done-criteria.** A `direct/web` order pays through the web shop and `direct/android` through the
+android shop, each verified with its own `Password2`, both crediting one `direct` wallet exactly
+once; the E7 report breaks payments down by channel; the split stays contour-safe (the legacy shop
+still works until the cabinet cutover). B4 (fiscalization) verified when the owner's ИП/ОФД/СНО are
+live.
+
+**Notes/risks.** Edge routes fall through if not in the Caddyfile `@gateway` matcher — add a CI
+probe (field note). The prod rolling deploy skips caddy on config-only changes — force-recreate on a
+Caddyfile change. Money-live: expand-contract only, image rollback DB-safe. Confirm the gateway
+emits `direct/android` for the native build before relying on subtype routing.
+
+---
+
+## E11 — Payment availability kill switch + per-account override
+
+**Status:** DONE · **Release 2** · depends on: E5 (intake/order), E7 (admin console) · mechanics:
+PAYMENTS §9; decisions D45, D46.
+
+**Delivered.** An operator disables purchases live from `/_gm` — a whole rail/channel or one account
+— and the user sees a localized reason on the next purchase attempt. Motivation (owner): real apps
+show broken payments with no explanation; this gives ops a live switch + a clear user message.
+
+- **Rail kill switch** — `payments.rail_status` (per rail `direct:web` / `direct:android` / `vk` /
+  `telegram`): `enabled` + a per-language message, edited on the catalog page. **Fail-open** (no row
+  ⇒ enabled, so payments are never accidentally killed). The intake gate — `CanPurchase` in
+  `handleWalletOrder`, before the order — returns `payment_unavailable` + the localized message;
+  orthogonal to the security gates.
+- **Per-account override** — `payments.account_payment_override` (a row only for non-default; default
+  = no row, cleared by delete): allow / deny / default, edited on the user card. `allow` bypasses
+  **only** the ops rail switch, never the security gates (D46).
+- **Wire** — the message rides an additive `ExecuteResponse.message` (envelope layer,
+  frozen-contract-safe; the gateway forwards a backend domain-error message via `DomainMessage`); the
+  client reads it into `GatewayError.message` and shows it on a `payment_unavailable` buy attempt.
+- **Tests** — the pure gate `PurchaseGate` (unit, TDD); the store + gate + override end-to-end
+  (integration, migration `00016`); the client (svelte-check / vitest). **Docs** — PAYMENTS (+`_ru`),
+  decisions D45 / D46.
+
+**Contour-safe:** additive migration (two new tables, no wipe); the wire add is additive; fail-open,
+so nothing is disabled until an operator acts.
 
 ---
 

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
-(`ui/landing.html`) and the SPA shell (`ui/index.html`). Same design language as the
-[VK loading-screen logo](../vk/README.md): the wooden Erudit «Э» tile (score `8`),
-with the wordmark on the app's dark board green (`ui/src/app.css` tokens).
-
-| 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**.
+The whole shipped icon set is sliced from **one master** — see
+[`brand/`](brand/) for the reference generator, the pinned font and the committed
+outputs, and [`../../docs/ICON_BRANDBOOK.md`](../../docs/ICON_BRANDBOOK.md) for how the
+mark is constructed. The per-platform target map (which file goes where) is in
+[`../../docs/ICONS.md`](../../docs/ICONS.md).
 
 ```sh
-cd assets/icons
-
-# 1. (optional) re-extract the glyphs — only if the font or the wordmark changes:
-#    default font: /usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf
-node build/extract.js [/path/to/font.ttf]      # -> build/glyphs.json
-
-# 2. regenerate everything in ui/public/:
-node build/generate.js
+cd brand
+npm i opentype.js
+node build-set.mjs          # web (ui/public) + Capacitor layers (ui/assets) + vk/ tg/ store/
+node build-android-res.mjs  # Android launcher resources (all densities + monochrome)
 ```
+
+> 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/README.md

@@ -33,11 +33,16 @@ real game seating the caller with an **empty opponent seat** (status `open`) or,
 another player already waits for the same variant and per-turn word rule, seats the
 caller into that open game and starts it — and
 friend-game invitations (invite → accept, starting a 2–4 player game once every
-invitee accepts). A **simultaneous-game cap** (`game.MaxActiveQuickGames` = 10) limits a
-player's active quick games — status `active`/`open`, excluding invitation-linked friend
-games (`game.Service.CountActiveQuickGames`); the server refuses `lobby/enqueue` and
-`invitations` creation with **409 `game_limit_reached`** at the cap (accepting an invitation
-is exempt), and the `games.list` response carries an `at_game_limit` flag for the lobby.
+invitee accepts). **Per-tier, per-kind active-game caps** limit a player's simultaneous
+unfinished games by kind — `vs_ai`, `random` (quick auto-match), `friends` — with separate
+guest and durable-account tiers held in the single-row `backend.config` table (a `-1` means
+unlimited), read through an in-memory cache (`internal/gamelimits`) and tuned live in the admin
+(`/_gm/limits`, no redeploy). Each game is tagged with its `games.game_kind` on creation;
+`game.Service.AtGameLimit` counts the account's `active`/`open` games of a kind against the
+tier's cap. The server refuses `lobby/enqueue` (random/vs_ai) with **409 `game_limit_reached`**
+at the cap, and the `invitations` (friends) path enforces the durable friends cap and refuses a
+**guest** outright (guests cannot use friends); accepting an invitation is exempt. The
+`games.list` response carries an `at_game_limit` flag (the random-kind cap) for the lobby.
 `internal/social` owns the friend graph (request/accept),
 per-user blocks, and per-game chat with nudges folded in as a message kind; chat
 messages are length-capped, content-filtered (no links/emails/phone numbers,
@@ -135,21 +140,38 @@ so `/internal/push-target` returns the recipient's `preferred_language` as the r
 language for out-of-app push; no per-bot routing remains. The console also manages the **advertising banner** (`/_gm/banners` +
 `/_gm/banner-settings`, `internal/ads`): operator campaigns with a percent weight, an optional
 window and bilingual messages, plus the global display timings. `GET /api/v1/user/profile` attaches
-the resolved, weighted campaign feed for an **eligible** viewer (`!paid_account && hint_balance == 0
-&& !no_banner` role, the message language picked by `preferred_language`); changing those inputs
-publishes a `notify` `banner` re-poll signal so the client shows/hides it in place. The shared wire
+the resolved, weighted campaign feed for an **eligible** viewer (no active **no-ads** benefit
+applicable in the current context and no **`no_banner`** role; the message language picked by
+`preferred_language`); changing those inputs
+publishes a `notify` `banner` re-poll signal so the client shows/hides it in place.
+The same gate drives the post-move interstitial config (`Profile.ads`, `adsFor`). The user card
+also carries a **finance panel** (`payments.AccountStatement`): the account's chip balances per
+funding segment, benefits per origin, the recorded refund risk, and the append-only ledger history
+(newest first) — read straight from the payments tables, uncached. The **catalog editor**
+(`/_gm/catalog`, `handlers_admin_catalog.go`) is the source of truth for products (D32): create /
+edit / archive-unarchive (the `product.active` flag) products, their atoms and per-rail prices, and
+hard-delete only a **never-transacted** product (an order/ledger reference forces archive-only,
+backed by the FK); a `tournament`-bearing product is composable but not sellable yet. The user card
+also carries an admin **grant** panel: grant raw benefit atoms (hints / no-ads days / forever) or a
+defined **value product** (a reward bundle, including an archived one), origin-picked; both write an
+`admin_grant` ledger row via `payments.Grant` / `GrantProduct` and **refuse** a chips or `tournament`
+atom (never grant currency; no tournament target yet). Each fund row in the panel carries a **Refund**
+action (`payments.RefundOrderFull`): a full-order refund the operator records after refunding on the
+rail — a `refund` ledger row + a floor-0 chip revoke, idempotent. A **ledger CSV export**
+(`/_gm/ledger.csv`, `payments.LedgerExport`) dumps the whole append-only ledger for tax +
+reconciliation. The shared wire
 contracts live in the sibling [`../pkg`](../pkg) module.
 
 **Account linking & merge** (`/api/v1/user/link/*`). `internal/link`
 orchestrates it: an email confirm-code or a gateway-validated Telegram identity is
 attached to the current account, and when the identity already has its own account
-the two are merged in one transaction (`internal/accountmerge`) — stats and the hint
-wallet summed, `paid_account` ORed, identities/games/chat/complaints transferred,
+the two are merged in one transaction (`internal/accountmerge`) — stats summed,
+identities/games/chat/complaints transferred,
 friends/blocks de-duplicated, the secondary kept as a `merged_into` tombstone (so a
 shared finished game's foreign keys hold); a shared **active** game blocks the merge.
 The current account is primary, except a guest initiator whose linked identity has a
 durable owner — then the durable account wins and a fresh session is minted for it.
-The `accounts.paid_account`/`merged_into`/`merged_at` columns back this. This supersedes the
+The `accounts.merged_into`/`merged_at` columns back this. This supersedes the
 former `email.bind.*` edge surface (the `RequestCode`/`ConfirmCode` primitives stay).
 
 Rate-limit observability: the gateway posts its periodic rejection

backend/cmd/backend/main.go

@@ -28,6 +28,7 @@ import (
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/feedback"
 	"scrabble/backend/internal/game"
+	"scrabble/backend/internal/gamelimits"
 	"scrabble/backend/internal/link"
 	"scrabble/backend/internal/lobby"
 	"scrabble/backend/internal/notify"
@@ -156,6 +157,17 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	logger.Info("active dictionary version", zap.String("version", games.ActiveVersion()))
 	games.SetNotifier(hub)
 	games.SetMetrics(tel.MeterProvider().Meter("scrabble/backend/game"))
+
+	// Active-game limit config: the per-tier, per-kind caps in backend.config, read once into an
+	// in-memory cache at boot and refreshed when the admin edits them. A boot-time load fails fast if
+	// the single config row is missing; the game domain reads the cache on every new-game gate.
+	gameLimits := gamelimits.NewService(gamelimits.NewStore(db))
+	if err := gameLimits.Load(ctx); err != nil {
+		return fmt.Errorf("load game-limit config: %w", err)
+	}
+	games.SetGameLimits(gameLimits)
+	logger.Info("game-limit config loaded")
+
 	go games.RunSweeper(ctx, cfg.Game.TimeoutSweepInterval)
 	logger.Info("game turn-timeout sweeper started",
 		zap.Duration("interval", cfg.Game.TimeoutSweepInterval))
@@ -271,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.
@@ -305,9 +324,11 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 		BanView:       banView,
 		Ads:           adsSvc,
 		Payments:      paymentsSvc,
+		GameLimits:    gameLimits,
 		Notifier:      hub,
 		ExportSignKey: cfg.ExportSignKey,
 		Renderer:      renderer,
+		Robokassa:     cfg.Robokassa,
 	})
 	pushSrv := pushgrpc.NewServer(cfg.GRPCAddr, hub, logger)
 
@@ -316,6 +337,13 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	logger.Info("servers starting",
 		zap.String("http_addr", cfg.HTTPAddr),
 		zap.String("grpc_addr", cfg.GRPCAddr))
+	// Sweep expired pending payment orders on a cadence (cosmetic hygiene; a late valid callback
+	// still credits). Runs until ctx is cancelled.
+	go runOrderReaper(ctx, paymentsSvc, logger)
+	// Deliver pending payment_events to connected clients as an in-app wallet-refresh push (the
+	// credit already landed in the ledger; a return-focus poll is the client-side fallback).
+	go runPaymentDispatcher(ctx, paymentsSvc, hub, logger)
+
 	errc := make(chan error, 2)
 	go func() { errc <- pushSrv.Run(ctx) }()
 	go func() { errc <- srv.Run(ctx) }()
@@ -325,6 +353,52 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	return err
 }
 
+// runOrderReaper periodically expires pending payment orders past their configured lifetime, until
+// ctx is cancelled. Expiry is cosmetic: a later valid provider callback still credits an expired
+// order.
+func runOrderReaper(ctx context.Context, p *payments.Service, log *zap.Logger) {
+	t := time.NewTicker(5 * time.Minute)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			if n, err := p.ExpireOrders(ctx); err != nil {
+				log.Warn("order reaper: sweep failed", zap.Error(err))
+			} else if n > 0 {
+				log.Info("order reaper: expired pending orders", zap.Int("count", n))
+			}
+		}
+	}
+}
+
+// runPaymentDispatcher delivers pending payment_events to connected clients as a wallet-refresh
+// signal (KindNotification / "payment"), marking each delivered, until ctx is cancelled. The credit
+// already committed to the ledger; this is only the in-app push so an open wallet updates in place.
+func runPaymentDispatcher(ctx context.Context, p *payments.Service, pub notify.Publisher, log *zap.Logger) {
+	t := time.NewTicker(3 * time.Second)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			evs, err := p.UndispatchedEvents(ctx, 50)
+			if err != nil {
+				log.Warn("payment dispatcher: read failed", zap.Error(err))
+				continue
+			}
+			for _, e := range evs {
+				pub.Publish(notify.Notification(e.AccountID, notify.NotifyPayment))
+				if err := p.MarkEventDispatched(ctx, e.EventID); err != nil {
+					log.Warn("payment dispatcher: mark failed", zap.String("event", e.EventID.String()), zap.Error(err))
+				}
+			}
+		}
+	}
+}
+
 // newMailer builds the confirm-code mailer: an SMTP relay when a host is
 // configured, otherwise the development log mailer (the code is logged, not sent).
 func newMailer(cfg account.SMTPConfig, logger *zap.Logger) account.Mailer {

backend/internal/account/account.go

@@ -43,9 +43,7 @@ var ErrNotFound = errors.New("account: not found")
 // local-time window (in TimeZone) during which the player is asleep, so the
 // turn-timeout sweeper does not auto-resign them inside it. (The robot opponent's
 // own sleep is anchored to its human opponent's timezone with a per-game drift,
-// computed in internal/robot, not from a robot account's away window.) HintBalance
-// is the player's wallet of purchasable hints, spent after a game's per-seat
-// allowance.
+// computed in internal/robot, not from a robot account's away window.)
 type Account struct {
 	ID                  uuid.UUID
 	DisplayName         string
@@ -53,7 +51,6 @@ type Account struct {
 	TimeZone            string
 	AwayStart           time.Time
 	AwayEnd             time.Time
-	HintBalance         int
 	BlockChat           bool
 	BlockFriendRequests bool
 	// VariantPreferences is the set of game variants (engine.Variant stable labels:
@@ -69,10 +66,6 @@ type Account struct {
 	// true (the default): the platform side-service skips out-of-app push for the
 	// account.
 	NotificationsInAppOnly bool
-	// PaidAccount marks a lifetime one-time-payment account. It is a service field
-	// (no purchase flow yet); an account linking & merge ORs it so a paid status is
-	// never lost when accounts are consolidated.
-	PaidAccount bool
 	// MergedInto is the primary account a retired (merged) secondary points at, or
 	// uuid.Nil for a live account. A tombstone keeps the row so the no-cascade
 	// foreign keys of a shared finished game stay valid.
@@ -393,6 +386,21 @@ func (s *Store) Identities(ctx context.Context, accountID uuid.UUID) ([]Identity
 	return out, nil
 }
 
+// HasConfirmedEmail reports whether the account owns a confirmed email identity — the direct-rail
+// recovery anchor a first purchase requires (D36).
+func (s *Store) HasConfirmedEmail(ctx context.Context, accountID uuid.UUID) (bool, error) {
+	ids, err := s.Identities(ctx, accountID)
+	if err != nil {
+		return false, err
+	}
+	for _, id := range ids {
+		if id.Kind == "email" && id.Confirmed {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
 // ListAccounts returns accounts for the admin user list, newest first, paginated
 // by limit and offset.
 func (s *Store) ListAccounts(ctx context.Context, limit, offset int) ([]Account, error) {
@@ -548,52 +556,6 @@ func (s *Store) ProvisionGuest(ctx context.Context, browserTZ string) (Account,
 	return modelToAccount(row), nil
 }
 
-// SpendHint atomically decrements the account's hint wallet by one, returning
-// true when a hint was spent and false when the balance was already empty. The
-// guarded UPDATE keeps it safe under concurrent spends across the player's games.
-func (s *Store) SpendHint(ctx context.Context, id uuid.UUID) (bool, error) {
-	stmt := table.Accounts.
-		UPDATE(table.Accounts.HintBalance, table.Accounts.UpdatedAt).
-		SET(table.Accounts.HintBalance.SUB(postgres.Int(1)), postgres.TimestampzT(time.Now().UTC())).
-		WHERE(
-			table.Accounts.AccountID.EQ(postgres.UUID(id)).
-				AND(table.Accounts.HintBalance.GT(postgres.Int(0))),
-		)
-	res, err := stmt.ExecContext(ctx, s.db)
-	if err != nil {
-		return false, fmt.Errorf("account: spend hint %s: %w", id, err)
-	}
-	n, err := res.RowsAffected()
-	if err != nil {
-		return false, fmt.Errorf("account: spend hint rows %s: %w", id, err)
-	}
-	return n > 0, nil
-}
-
-// GrantHints adds n hints to the account's wallet and returns the new balance. n must be
-// positive: the additive update can only raise the balance, never lower it, so it enforces the
-// admin console's raise-only rule by construction and stays correct under a concurrent SpendHint.
-// It returns ErrNotFound when no account matches.
-func (s *Store) GrantHints(ctx context.Context, id uuid.UUID, n int) (int, error) {
-	if n <= 0 {
-		return 0, fmt.Errorf("account: grant hints %s: n must be positive, got %d", id, n)
-	}
-	stmt := table.Accounts.
-		UPDATE(table.Accounts.HintBalance, table.Accounts.UpdatedAt).
-		SET(table.Accounts.HintBalance.ADD(postgres.Int(int64(n))), postgres.TimestampzT(time.Now().UTC())).
-		WHERE(table.Accounts.AccountID.EQ(postgres.UUID(id))).
-		RETURNING(table.Accounts.HintBalance)
-
-	var row model.Accounts
-	if err := stmt.QueryContext(ctx, s.db, &row); err != nil {
-		if errors.Is(err, qrm.ErrNoRows) {
-			return 0, ErrNotFound
-		}
-		return 0, fmt.Errorf("account: grant hints %s: %w", id, err)
-	}
-	return int(row.HintBalance), nil
-}
-
 // FlagHighRate stamps the soft "suspected high-rate" marker with at, only when
 // the account is not already flagged — the first sustained episode wins, and a
 // re-flag after an operator clear starts a fresh timestamp. An infra marker, not
@@ -649,12 +611,10 @@ func modelToAccount(row model.Accounts) Account {
 		TimeZone:               row.TimeZone,
 		AwayStart:              row.AwayStart,
 		AwayEnd:                row.AwayEnd,
-		HintBalance:            int(row.HintBalance),
 		BlockChat:              row.BlockChat,
 		BlockFriendRequests:    row.BlockFriendRequests,
 		IsGuest:                row.IsGuest,
 		NotificationsInAppOnly: row.NotificationsInAppOnly,
-		PaidAccount:            row.PaidAccount,
 		MergedInto:             mergedInto,
 		FlaggedHighRateAt:      flaggedHighRateAt,
 		CreatedAt:              row.CreatedAt,

backend/internal/adminconsole/templates/layout.gohtml

@@ -15,12 +15,14 @@
     <a href="/_gm/"{{if eq .ActiveNav "dashboard"}} class="active"{{end}}>Dashboard</a>
     <a href="/_gm/users"{{if eq .ActiveNav "users"}} class="active"{{end}}>Users</a>
     <a href="/_gm/games"{{if eq .ActiveNav "games"}} class="active"{{end}}>Games</a>
+    <a href="/_gm/limits"{{if eq .ActiveNav "limits"}} class="active"{{end}}>Limits</a>
     <a href="/_gm/complaints"{{if eq .ActiveNav "complaints"}} class="active"{{end}}>Complaints</a>
     <a href="/_gm/feedback"{{if eq .ActiveNav "feedback"}} class="active"{{end}}>Feedback</a>
     <a href="/_gm/messages"{{if eq .ActiveNav "messages"}} class="active"{{end}}>Messages</a>
     <a href="/_gm/throttled"{{if eq .ActiveNav "throttled"}} class="active"{{end}}>Throttled</a>
     <a href="/_gm/reasons"{{if eq .ActiveNav "reasons"}} class="active"{{end}}>Reasons</a>
     <a href="/_gm/banners"{{if eq .ActiveNav "banners"}} class="active"{{end}}>Banners</a>
+    <a href="/_gm/catalog"{{if eq .ActiveNav "catalog"}} class="active"{{end}}>Catalog</a>
     <a href="/_gm/dictionary"{{if eq .ActiveNav "dictionary"}} class="active"{{end}}>Dictionary</a>
     <a href="/_gm/broadcast"{{if eq .ActiveNav "broadcast"}} class="active"{{end}}>Broadcast</a>
     <a href="/_gm/grafana/">Grafana ↗</a>

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

@@ -0,0 +1,66 @@
+{{define "content" -}}
+<h1>Product catalog</h1>
+{{with .Data}}
+<p class="note">A <strong>pack</strong> funds chips (a money price per rail — RUB via direct, VOTE via vk, XTR via telegram); a <strong>value</strong> buys benefits with chips (a CHIP price). Archived products are hidden from players but still credit an in-flight payment and can be granted. A product with transactions can only be archived, not deleted. Amounts are in minor units (RUB kopecks; VOTE/XTR/CHIP whole). The <code>tournament</code> atom is not sellable yet — keep such a product archived.</p>
+<section class="panel"><h2>Add product</h2>
+<form class="form col" method="post" action="/_gm/catalog">
+<label>Title <input type="text" name="title" maxlength="120" required></label>
+<fieldset><legend>Atoms (quantity; blank = none)</legend>
+<label>Chips <input type="number" name="chips" min="0"></label>
+<label>Hints <input type="number" name="hints" min="0"></label>
+<label>No-ads days <input type="number" name="noads" min="0"></label>
+<label>Tournament <input type="number" name="tournament" min="0"></label>
+</fieldset>
+<fieldset><legend>Prices (minor units; blank = none)</legend>
+<label>RUB — direct (kopecks) <input type="number" name="price_rub" min="0"></label>
+<label>VOTE — vk <input type="number" name="price_vote" min="0"></label>
+<label>XTR — telegram <input type="number" name="price_star" min="0"></label>
+<label>CHIP — value <input type="number" name="price_chip" min="0"></label>
+</fieldset>
+<label><input type="checkbox" name="active" value="true"> Active (on sale)</label>
+<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>Payment availability (kill switch)</h2>
+<p class="note">Turn purchases off on a rail/channel and show the user a localized reason on their next attempt. Unchecked = off; an empty message shows a built-in &ldquo;temporarily unavailable&rdquo;. Fail-open: a rail you never touch stays on. A per-user &ldquo;allow&rdquo; override (on a user card) bypasses this switch.</p>
+{{range .Rails}}
+<form class="form col" method="post" action="/_gm/catalog/rail-status">
+<input type="hidden" name="rail" value="{{.Rail}}">
+<label><input type="checkbox" name="enabled" {{if .Enabled}}checked{{end}}> <code>{{.Rail}}</code> &mdash; purchases enabled</label>
+<label>Message RU <input type="text" name="message_ru" maxlength="200" value="{{.MessageRU}}"></label>
+<label>Message EN <input type="text" name="message_en" maxlength="200" value="{{.MessageEN}}"></label>
+<div><button type="submit">Save</button></div>
+</form>
+{{end}}
+</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>
+{{range .Products}}
+<tr>
+<td><a href="/_gm/catalog/{{.ID}}">{{.Title}}</a></td>
+<td>{{if .Active}}<span class="ok">active</span>{{else}}<span class="warn">archived</span>{{end}}{{if .Transacted}} <span class="pill">transacted</span>{{end}}</td>
+<td>{{range .Atoms}}<code>{{.Atom}}×{{.Quantity}}</code> {{end}}</td>
+<td>{{range .Prices}}<code>{{.Currency}}{{if .Method}}/{{.Method}}{{end}} {{.Amount}}</code> {{end}}</td>
+<td class="row-actions">
+<form class="form" method="post" action="/_gm/catalog/{{.ID}}/archive"><input type="hidden" name="active" value="{{if .Active}}false{{else}}true{{end}}"><button type="submit">{{if .Active}}Archive{{else}}Unarchive{{end}}</button></form>
+{{if not .Transacted}}<form class="form" method="post" action="/_gm/catalog/{{.ID}}/delete" onsubmit="return confirm('Delete this product? It has never been transacted, so this is safe and permanent.')"><button type="submit">Delete</button></form>{{end}}
+</td>
+</tr>
+{{else}}<tr><td colspan="5"><span class="note">no products</span></td></tr>{{end}}
+</tbody>
+</table>
+</section>
+{{end}}
+{{- end}}

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

@@ -8,6 +8,7 @@
 <li><b>Dictionary</b> {{.DictVersion}}</li>
 <li><b>Status</b> {{.Status}}{{if .EndReason}} ({{.EndReason}}){{end}}</li>
 <li><b>AI game</b> {{if .VsAI}}🤖 yes{{else}}no{{end}}</li>
+<li><b>Word rule</b> {{if .MultipleWordsPerTurn}}multiple words per turn{{else}}single word per turn{{end}}</li>
 <li><b>Players</b> {{.Players}}</li>
 <li><b>To move</b> seat {{.ToMove}}</li>
 <li><b>Moves</b> {{.MoveCount}}</li>

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

@@ -8,11 +8,11 @@
 <a href="/_gm/games?status=finished"{{if eq .Status "finished"}} class="active"{{end}}>finished</a>
 </nav>
 <table class="list">
-<thead><tr><th>Game</th><th>Variant</th><th>Status</th><th>🤖</th><th class="num">Players</th><th>Updated</th></tr></thead>
+<thead><tr><th>Game</th><th>Variant</th><th>Kind</th><th>Status</th><th>🤖</th><th class="num">Players</th><th>Updated</th></tr></thead>
 <tbody>
 {{range .Items}}
-<tr><td><a href="/_gm/games/{{.ID}}">{{.ID}}</a></td><td>{{.Variant}}</td><td>{{.Status}}</td><td>{{if .VsAI}}🤖{{end}}</td><td class="num">{{.Players}}</td><td>{{.UpdatedAt}}</td></tr>
-{{else}}<tr><td colspan="6"><span class="note">no games</span></td></tr>{{end}}
+<tr><td><a href="/_gm/games/{{.ID}}">{{.ID}}</a></td><td>{{.Variant}}</td><td>{{.Kind}}</td><td>{{.Status}}</td><td>{{if .VsAI}}🤖{{end}}</td><td class="num">{{.Players}}</td><td>{{.UpdatedAt}}</td></tr>
+{{else}}<tr><td colspan="7"><span class="note">no games</span></td></tr>{{end}}
 </tbody>
 </table>
 <nav class="pager">

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

@@ -0,0 +1,19 @@
+{{define "content" -}}
+<h1>Active-game limits</h1>
+{{with .Data}}
+<p class="note">Per-tier, per-kind caps on a player's simultaneous unfinished games. <strong>-1</strong> = unlimited, <strong>0</strong> = the kind is blocked, a positive number caps concurrent games of that kind. Guests are additionally blocked from friend games outright. Changes apply immediately (no redeploy); games already in progress are never affected.</p>
+<section class="panel">
+<form class="form col" method="post" action="/_gm/limits">
+<h2>Guest</h2>
+<label>vs AI <input type="number" name="guest_vs_ai" min="-1" value="{{.GuestVsAI}}" required></label>
+<label>Random <input type="number" name="guest_random" min="-1" value="{{.GuestRandom}}" required></label>
+<label>Friends <input type="number" name="guest_friends" min="-1" value="{{.GuestFriends}}" required></label>
+<h2>Durable account</h2>
+<label>vs AI <input type="number" name="durable_vs_ai" min="-1" value="{{.DurableVsAI}}" required></label>
+<label>Random <input type="number" name="durable_random" min="-1" value="{{.DurableRandom}}" required></label>
+<label>Friends <input type="number" name="durable_friends" min="-1" value="{{.DurableFriends}}" required></label>
+<div><button type="submit">Save</button></div>
+</form>
+</section>
+{{end}}
+{{- end}}

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

@@ -0,0 +1,25 @@
+{{define "content" -}}
+{{with .Data}}
+<p class="note"><a href="/_gm/catalog">← all products</a></p>
+<h1>{{.Title}} {{if .Active}}<span class="ok">active</span>{{else}}<span class="warn">archived</span>{{end}}{{if .Transacted}} <span class="pill">transacted</span>{{end}}</h1>
+<section class="panel"><h2>Edit</h2>
+<p class="note">A zero quantity / blank price removes that atom / price. Amounts are in minor units. Saving revalidates the sellable shape when the product is active. Archive / unarchive from the <a href="/_gm/catalog">catalog list</a>.</p>
+<form class="form col" method="post" action="/_gm/catalog/{{.ID}}">
+<label>Title <input type="text" name="title" value="{{.Title}}" maxlength="120" required></label>
+<fieldset><legend>Atoms (quantity; 0 = none)</legend>
+<label>Chips <input type="number" name="chips" min="0" value="{{.Chips}}"></label>
+<label>Hints <input type="number" name="hints" min="0" value="{{.Hints}}"></label>
+<label>No-ads days <input type="number" name="noads" min="0" value="{{.NoAds}}"></label>
+<label>Tournament <input type="number" name="tournament" min="0" value="{{.Tournament}}"></label>
+</fieldset>
+<fieldset><legend>Prices (minor units; 0 = none)</legend>
+<label>RUB — direct (kopecks) <input type="number" name="price_rub" min="0" value="{{.PriceRUB}}"></label>
+<label>VOTE — vk <input type="number" name="price_vote" min="0" value="{{.PriceVote}}"></label>
+<label>XTR — telegram <input type="number" name="price_star" min="0" value="{{.PriceStar}}"></label>
+<label>CHIP — value <input type="number" name="price_chip" min="0" value="{{.PriceChip}}"></label>
+</fieldset>
+<div><button type="submit">Save</button></div>
+</form>
+</section>
+{{end}}
+{{- end}}

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

@@ -10,8 +10,6 @@
 <li><b>Timezone</b> {{.TimeZone}}</li>
 <li><b>Guest</b> {{if .Guest}}yes{{else}}no{{end}}</li>
 <li><b>Push</b> {{if .NotificationsInAppOnly}}in-app only{{else}}out-of-app{{end}}</li>
-<li><b>Paid</b> {{if .PaidAccount}}yes{{else}}no{{end}}</li>
-<li><b>Hint wallet</b> {{.HintBalance}}</li>
 {{if .MergedInto}}<li><b>Merged into</b> {{.MergedInto}}</li>{{end}}
 {{if .FlaggedHighRateAt}}<li><b>High-rate flag</b> <span class="warn">{{.FlaggedHighRateAt}}</span></li>{{end}}
 <li><b>Created</b> {{.CreatedAt}}</li>
@@ -21,10 +19,6 @@
 <button type="submit">Clear high-rate flag</button>
 </form>
 {{end}}
-<form class="form" method="post" action="/_gm/users/{{.ID}}/grant-hints">
-<label>Add hints <input type="number" name="amount" min="1" max="{{.HintGrantMax}}" value="1"></label>
-<button type="submit">Grant</button>
-</form>
 </section>
 <section class="panel"><h2>Statistics</h2>
 {{if .HasStats}}
@@ -69,6 +63,61 @@
 <div><button type="submit">{{if .Suspension.Blocked}}Re-block{{else}}Block{{end}}</button></div>
 </form>
 </section>
+<section class="panel"><h2>Finance</h2>
+{{if .Finance.Present}}
+{{if or .Finance.Segments .Finance.Benefits .Finance.Abuse .Finance.Loss}}
+<ul class="kv">
+{{range .Finance.Segments}}<li><b>Chips ({{.Source}})</b> {{.Chips}}</li>{{end}}
+{{range .Finance.Benefits}}<li><b>Benefits ({{.Origin}})</b> {{.Hints}} hints{{if .Forever}} · no-ads forever{{else if .AdsUntil}} · no-ads until {{.AdsUntil}} (UTC){{end}}</li>{{end}}
+{{if or .Finance.Abuse .Finance.Loss}}<li><b>Refund risk</b> <span class="warn">{{if .Finance.Abuse}}abuse-flagged{{end}}{{if .Finance.Loss}} · loss {{.Finance.Loss}} chips{{end}}</span></li>{{end}}
+</ul>
+{{else}}<p class="note">no balances or benefits</p>{{end}}
+<h3>Payment override</h3>
+<form class="form" method="post" action="/_gm/users/{{.ID}}/purchase-override">
+<label>Purchases for this account
+<select name="override">
+<option value="default" {{if eq .PurchaseOverride "default"}}selected{{end}}>Default (follow the rail switch)</option>
+<option value="allow" {{if eq .PurchaseOverride "allow"}}selected{{end}}>Always allow (bypasses the rail switch only, not security)</option>
+<option value="deny" {{if eq .PurchaseOverride "deny"}}selected{{end}}>Always deny</option>
+</select></label>
+<div><button type="submit">Save</button></div>
+</form>
+<h3>Ledger</h3>
+{{$uid := .ID}}
+{{if .Finance.Ledger}}
+<table class="list">
+<thead><tr><th>Time</th><th>Kind</th><th>Source</th><th>Origin</th><th>Chips</th><th>Order</th><th>Provider</th><th>Shop</th><th>Detail</th><th></th></tr></thead>
+<tbody>
+{{range .Finance.Ledger}}
+<tr><td>{{.At}}</td><td>{{.Kind}}</td><td>{{.Source}}</td><td>{{.Origin}}</td><td>{{.ChipsDelta}}</td><td>{{if .Order}}<code>{{.Order}}</code>{{end}}</td><td>{{.Provider}}</td><td>{{.Shop}}</td><td>{{if .Snapshot}}<code>{{.Snapshot}}</code>{{end}}</td>
+<td>{{if and (eq .Kind "fund") .Order}}<form class="form" method="post" action="/_gm/users/{{$uid}}/refund" onsubmit="return confirm('Refund this order in full? Record the money refund on the rail first; this revokes the chips (floored at 0).')"><input type="hidden" name="order_id" value="{{.Order}}"><button type="submit">Refund</button></form>{{end}}</td></tr>
+{{end}}
+</tbody>
+</table>
+<p class="note"><a href="/_gm/ledger.csv">Export the full ledger (CSV)</a> — all accounts, for tax + reconciliation.</p>
+{{else}}<p class="note">no ledger entries</p>{{end}}
+{{else}}<p class="note">payments not enabled</p>{{end}}
+</section>
+<section class="panel"><h2>Grant benefits</h2>
+{{if .Grant.Present}}
+<p class="note">A zero-price admin sale of a value — <strong>never chips</strong>. The origin is your compliance choice. The by-product grant applies a defined bundle, including an archived reward product.</p>
+<form class="form col" method="post" action="/_gm/users/{{.ID}}/grant">
+<label>Origin <select name="origin">{{range .Grant.Origins}}<option value="{{.}}">{{.}}</option>{{end}}</select></label>
+<label>Hints <input type="number" name="hints" min="0" value="0"></label>
+<label>No-ads days <input type="number" name="noads" min="0" value="0"></label>
+<label><input type="checkbox" name="forever" value="true"> No-ads forever</label>
+<div><button type="submit">Grant</button></div>
+</form>
+{{if .Grant.Products}}
+<h3>Grant a product</h3>
+<form class="form col" method="post" action="/_gm/users/{{.ID}}/grant-product">
+<label>Origin <select name="origin">{{range .Grant.Origins}}<option value="{{.}}">{{.}}</option>{{end}}</select></label>
+<label>Product <select name="product_id">{{range .Grant.Products}}<option value="{{.ID}}">{{.Title}} ({{.Summary}}){{if .Archived}} — archived{{end}}</option>{{end}}</select></label>
+<div><button type="submit">Grant product</button></div>
+</form>
+{{else}}<p class="note">no grantable products — create a value product in the <a href="/_gm/catalog">catalog</a></p>{{end}}
+{{else}}<p class="note">payments not enabled</p>{{end}}
+</section>
 <section class="panel"><h2>Roles</h2>
 {{$id := .ID}}
 {{if .Roles}}
@@ -172,11 +221,11 @@
 {{end}}
 <section class="panel"><h2>Games</h2>
 <table class="list">
-<thead><tr><th>Game</th><th>Variant</th><th>Status</th><th class="num">Players</th><th>Updated</th></tr></thead>
+<thead><tr><th>Game</th><th>Variant</th><th>Kind</th><th>Status</th><th class="num">Players</th><th>Updated</th></tr></thead>
 <tbody>
 {{range .Games}}
-<tr><td><a href="/_gm/games/{{.ID}}">{{.ID}}</a></td><td>{{.Variant}}</td><td>{{.Status}}</td><td class="num">{{.Players}}</td><td>{{.UpdatedAt}}</td></tr>
-{{else}}<tr><td colspan="5"><span class="note">no games</span></td></tr>{{end}}
+<tr><td><a href="/_gm/games/{{.ID}}">{{.ID}}</a></td><td>{{.Variant}}</td><td>{{.Kind}}</td><td>{{.Status}}</td><td class="num">{{.Players}}</td><td>{{.UpdatedAt}}</td></tr>
+{{else}}<tr><td colspan="6"><span class="note">no games</span></td></tr>{{end}}
 </tbody>
 </table>
 </section>

backend/internal/adminconsole/views.go

@@ -149,7 +149,6 @@ type UserDetailView struct {
 	TimeZone               string
 	Guest                  bool
 	NotificationsInAppOnly bool
-	PaidAccount            bool
 	// MergedInto is the primary account id when this account has been retired by a
 	// merge, or empty for a live account.
 	MergedInto string
@@ -165,10 +164,6 @@ type UserDetailView struct {
 	// FlaggedHighRateAt is the pre-formatted soft high-rate marker timestamp,
 	// empty for an unflagged account; the card shows it with the Clear action.
 	FlaggedHighRateAt string
-	HintBalance       int
-	// HintGrantMax is the per-grant cap the operator's "add hints" form enforces (it mirrors the
-	// server's maxHintGrant), passed through so the policy value lives in one place.
-	HintGrantMax int
 	CreatedAt         string
 	HasStats          bool
 	Stats             StatsRow
@@ -200,6 +195,59 @@ type UserDetailView struct {
 	Blocks    []RelationRow
 	BlockedBy []RelationRow
 	Friends   []RelationRow
+	// Finance is the account's payments picture (balances, benefits, refund risk, ledger). Present
+	// is false when the payments domain is unwired.
+	Finance FinanceView
+	// PurchaseOverride is the account's per-account purchase override ("default"/"allow"/"deny"),
+	// shown in and edited from the user card's payment-override control.
+	PurchaseOverride string
+	// Grant is the admin-grant panel (origin picker + grantable products). Present is false when the
+	// payments domain is unwired.
+	Grant GrantFormView
+}
+
+// FinanceView is the account's payments picture on the user card: chip balances per funding
+// segment, benefits per origin, the recorded refund risk, and the append-only ledger history
+// (newest first). Present is false when the payments domain is unwired.
+type FinanceView struct {
+	Present  bool
+	Segments []SegmentRow
+	Benefits []BenefitRow
+	// Abuse is the refund abuse flag; Loss is the unrecoverable chip loss from floor-0 refunds.
+	Abuse  bool
+	Loss   int
+	Ledger []LedgerRow
+}
+
+// SegmentRow is one funding segment's chip balance.
+type SegmentRow struct {
+	Source string
+	Chips  int
+}
+
+// BenefitRow is one origin's benefit: the hint wallet, the ad-free expiry (pre-formatted, empty
+// when none) and the lifetime ad-free flag.
+type BenefitRow struct {
+	Origin   string
+	Hints    int
+	AdsUntil string
+	Forever  bool
+}
+
+// LedgerRow is one append-only ledger entry: its kind, funding source / benefit origin, signed chip
+// delta, the product / order / provider / direct-rail shop it references (empty when none), the raw
+// snapshot JSON and the pre-formatted time.
+type LedgerRow struct {
+	Kind       string
+	Source     string
+	Origin     string
+	ChipsDelta int
+	Product    string
+	Order      string
+	Provider   string
+	Shop       string
+	Snapshot   string
+	At         string
 }
 
 // RelationRow is one cross-linked account in the user card's blocks / blocked-by / friends
@@ -268,6 +316,8 @@ type GameRow struct {
 	UpdatedAt string
 	// VsAI marks an honest-AI game (rendered as 🤖 in the list's AI column).
 	VsAI bool
+	// Kind is the game's origin tag label: vs_ai / random / friends / unknown.
+	Kind string
 }
 
 // GamesView is the paginated games list, optionally filtered by status.
@@ -277,6 +327,17 @@ type GamesView struct {
 	Pager  Pager
 }
 
+// GameLimitsView is the per-tier, per-kind active-game limit form: each field is a cap where -1
+// is unlimited, 0 blocks the kind, and a positive value caps concurrent games of that kind.
+type GameLimitsView struct {
+	GuestVsAI      int
+	GuestRandom    int
+	GuestFriends   int
+	DurableVsAI    int
+	DurableRandom  int
+	DurableFriends int
+}
+
 // GameDetailView is one game with its seats.
 type GameDetailView struct {
 	ID          string
@@ -292,6 +353,10 @@ type GameDetailView struct {
 	FinishedAt  string
 	// VsAI marks an honest-AI game (shown as a 🤖 flag in the summary).
 	VsAI bool
+	// MultipleWordsPerTurn is the game's cross-word rule: true = standard Scrabble (every cross-word
+	// is validated and scored), false = the single-word rule (only the main word along the play
+	// direction counts). Shown in the summary so an operator can tell the rule at a glance.
+	MultipleWordsPerTurn bool
 	Seats                []SeatRow
 	// HasRobot is true when any seat is a robot, gating the robot-target caption;
 	// RobotTargetPct is the configured global play-to-win rate, in percent.
@@ -612,3 +677,90 @@ type FeedbackDetailView struct {
 	UserTZ           string
 	Banned           bool
 }
+
+// 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
+	// Rails is the per-rail operational kill-switch state (enabled + per-language off-message), shown
+	// in and edited from the page's payment-availability form.
+	Rails []RailStatusRow
+}
+
+// RailStatusRow is one payment rail's operational availability in the kill-switch editor: the rail
+// key, whether purchases are enabled, and the operator's per-language off-message shown to the user.
+type RailStatusRow struct {
+	Rail      string
+	Enabled   bool
+	MessageRU string
+	MessageEN string
+}
+
+// ProductRow is one product in the catalog list: its composition, prices, the archived flag
+// (Active) and the transacted flag (which forbids a hard delete).
+type ProductRow struct {
+	ID         string
+	Title      string
+	Active     bool
+	Atoms      []AtomRow
+	Prices     []PriceRow
+	Transacted bool
+}
+
+// AtomRow is one atom line of a product row.
+type AtomRow struct {
+	Atom     string
+	Quantity int
+}
+
+// PriceRow is one price of a product: the method ("" for a value's CHIP price), the currency, and
+// the amount in that currency's minor units.
+type PriceRow struct {
+	Method   string
+	Currency string
+	Amount   int64
+}
+
+// ProductFormView is the product edit form, pre-filled from the current composition. Atom quantities
+// and prices are flattened to the fixed fields the form offers (0 = absent); Transacted disables the
+// delete action.
+type ProductFormView struct {
+	ID         string
+	Title      string
+	Active     bool
+	Chips      int
+	Hints      int
+	NoAds      int
+	Tournament int
+	PriceRUB   int64
+	PriceVote  int64
+	PriceStar  int64
+	PriceChip  int64
+	Transacted bool
+}
+
+// GrantFormView is the admin-grant panel on the user card: the origin picker and the grantable
+// products (value bundles — hints / no-ads days — including archived ones; chips and tournament
+// products are excluded). Present is false when the payments domain is unwired.
+type GrantFormView struct {
+	Present  bool
+	Origins  []string
+	Products []GrantProductOption
+}
+
+// GrantProductOption is one grantable product in the by-product picker: its id, title, an atom
+// summary, and whether it is archived (the common case for a non-public reward bundle).
+type GrantProductOption struct {
+	ID       string
+	Title    string
+	Summary  string
+	Archived bool
+}

backend/internal/config/config.go

@@ -14,6 +14,7 @@ import (
 	"scrabble/backend/internal/lobby"
 	"scrabble/backend/internal/postgres"
 	"scrabble/backend/internal/ratewatch"
+	"scrabble/backend/internal/robokassa"
 	"scrabble/backend/internal/robot"
 	"scrabble/backend/internal/telemetry"
 )
@@ -64,6 +65,9 @@ type Config struct {
 	// RendererURL is the base URL of the internal image-render sidecar (e.g.
 	// http://renderer:8090). Empty disables the PNG export artifact.
 	RendererURL string
+	// Robokassa configures the direct-rail (RUB) payment provider — one merchant shop per channel
+	// (D42). An empty set leaves the direct order and Result-callback endpoints unregistered.
+	Robokassa robokassa.Shops
 }
 
 // Defaults applied when the corresponding environment variable is unset.
@@ -153,6 +157,21 @@ func Load() (Config, error) {
 		AdminTo:   os.Getenv("BACKEND_ADMIN_EMAIL"),
 	}
 
+	// Robokassa direct rail: one merchant shop per channel (D42). The legacy single-shop vars seed
+	// the web channel so existing deploys keep working; the per-channel vars add the rest. A shop
+	// with no MerchantLogin is dropped (the rail stays dormant when none is configured).
+	shops := robokassa.Shops{}
+	web := robokassaShop("BACKEND_ROBOKASSA_WEB")
+	if web.MerchantLogin == "" {
+		web = robokassaShop("BACKEND_ROBOKASSA") // legacy single-shop credentials seed the web channel
+	}
+	if web.MerchantLogin != "" {
+		shops[robokassa.ChannelWeb] = web
+	}
+	if android := robokassaShop("BACKEND_ROBOKASSA_ANDROID"); android.MerchantLogin != "" {
+		shops[robokassa.ChannelAndroid] = android
+	}
+
 	c := Config{
 		HTTPAddr:          envOr("BACKEND_HTTP_ADDR", defaultHTTPAddr),
 		GRPCAddr:          envOr("BACKEND_GRPC_ADDR", defaultGRPCAddr),
@@ -170,6 +189,7 @@ func Load() (Config, error) {
 		GuestRetention:    guestRetention,
 		ExportSignKey:     os.Getenv("BACKEND_EXPORT_SIGN_KEY"),
 		RendererURL:       os.Getenv("BACKEND_RENDERER_URL"),
+		Robokassa:         shops,
 	}
 	if err := c.validate(); err != nil {
 		return Config{}, err
@@ -222,6 +242,11 @@ func (c Config) validate() error {
 			return fmt.Errorf("config: BACKEND_PUBLIC_BASE_URL %q must be an absolute URL (scheme://host)", c.PublicBaseURL)
 		}
 	}
+	for channel, shop := range c.Robokassa {
+		if shop.Password1 == "" || shop.Password2 == "" {
+			return fmt.Errorf("config: robokassa shop %q: password1 and password2 must be set when its merchant login is", channel)
+		}
+	}
 	return nil
 }
 
@@ -261,3 +286,15 @@ func envDuration(key string, fallback time.Duration) (time.Duration, error) {
 	}
 	return d, nil
 }
+
+// robokassaShop reads a Robokassa shop's four credentials from the environment under prefix (e.g.
+// "BACKEND_ROBOKASSA_WEB" → _MERCHANT_LOGIN / _PASSWORD1 / _PASSWORD2 / _TEST). A missing
+// MerchantLogin yields a zero Config the caller drops.
+func robokassaShop(prefix string) robokassa.Config {
+	return robokassa.Config{
+		MerchantLogin: os.Getenv(prefix + "_MERCHANT_LOGIN"),
+		Password1:     os.Getenv(prefix + "_PASSWORD1"),
+		Password2:     os.Getenv(prefix + "_PASSWORD2"),
+		IsTest:        os.Getenv(prefix+"_TEST") == "1",
+	}
+}

backend/internal/game/eventwire.go

@@ -52,6 +52,7 @@ func gameSummary(g Game, names []string) notify.GameSummary {
 		TurnTimeoutSecs:      int(g.TurnTimeout.Seconds()),
 		MultipleWordsPerTurn: g.MultipleWordsPerTurn,
 		VsAI:                 g.VsAI,
+		Kind:                 int(g.Kind),
 		MoveCount:            g.MoveCount,
 		EndReason:            g.EndReason,
 		Seats:                seats,
@@ -74,7 +75,6 @@ func playerState(v StateView, names []string, includeAlphabet bool) (notify.Play
 		Rack:           rack,
 		BagLen:         v.BagLen,
 		HintsRemaining: v.HintsRemaining,
-		WalletBalance:  v.WalletBalance,
 	}
 	if includeAlphabet {
 		tab, err := engine.AlphabetTable(v.Game.Variant)

backend/internal/game/helpers_test.go

@@ -55,16 +55,16 @@ func TestPayloadExchangeRoundTrip(t *testing.T) {
 }
 
 func TestHintsRemaining(t *testing.T) {
-	cases := []struct{ allowance, used, wallet, want int }{
-		{1, 0, 3, 4},
-		{1, 1, 3, 3},
-		{1, 2, 3, 3}, // used past allowance clamps to 0
-		{0, 0, 5, 5},
-		{2, 1, 0, 1},
+	cases := []struct{ allowance, used, want int }{
+		{1, 0, 1},
+		{1, 1, 0},
+		{1, 2, 0}, // used past allowance clamps to 0
+		{3, 1, 2},
+		{0, 0, 0},
 	}
 	for _, c := range cases {
-		if got := hintsRemaining(c.allowance, c.used, c.wallet); got != c.want {
-			t.Errorf("hintsRemaining(%d,%d,%d) = %d, want %d", c.allowance, c.used, c.wallet, got, c.want)
+		if got := hintsRemaining(c.allowance, c.used); got != c.want {
+			t.Errorf("hintsRemaining(%d,%d) = %d, want %d", c.allowance, c.used, got, c.want)
 		}
 	}
 }

backend/internal/game/service.go

@@ -17,6 +17,7 @@ import (
 
 	"scrabble/backend/internal/account"
 	"scrabble/backend/internal/engine"
+	"scrabble/backend/internal/gamelimits"
 	"scrabble/backend/internal/notify"
 	"scrabble/backend/internal/payments"
 	"scrabble/backend/internal/session"
@@ -57,6 +58,9 @@ type Service struct {
 	// nil, only the free per-game allowance is served (no purchased hints). vs_ai hints are
 	// wallet-free and never touch it.
 	hintWallet HintWallet
+	// limits is the per-tier active-game cap config (cached). Set by SetGameLimits during wiring;
+	// when nil, no active-game limit is enforced (a game is always creatable).
+	limits *gamelimits.Service
 	// clearNudges, when set, marks the actor's pending nudges in a game read once they
 	// have committed a move (a nudge answered by moving stops counting as unread). It is
 	// best-effort and kept as a func so the game package never imports the social package.
@@ -126,6 +130,37 @@ func (svc *Service) SetHintWallet(w HintWallet) {
 	svc.hintWallet = w
 }
 
+// SetGameLimits installs the active-game limit config (cached), enabling the per-tier caps. When
+// unset (nil), a game is always creatable.
+func (svc *Service) SetGameLimits(l *gamelimits.Service) {
+	svc.limits = l
+}
+
+// AtGameLimit reports whether accountID has reached its tier's active-game cap for kind — the
+// per-tier, per-kind limits held in backend.config, read from the in-memory cache. It resolves
+// the caller's tier (guest vs durable) from the account, then counts its open+active games of that
+// kind. It reports false (not at the limit) when the limits config is not wired, the account is nil,
+// or the resolved cap is gamelimits.Unlimited. It backs the new-game gate (the handler aborts 409
+// game_limit_reached) and the lobby's at-limit flag.
+func (svc *Service) AtGameLimit(ctx context.Context, accountID uuid.UUID, kind gamelimits.Kind) (bool, error) {
+	if svc.limits == nil || accountID == uuid.Nil {
+		return false, nil
+	}
+	acc, err := svc.accounts.GetByID(ctx, accountID)
+	if err != nil {
+		return false, err
+	}
+	limit := svc.limits.LimitsFor(acc.IsGuest).Cap(kind)
+	if limit == gamelimits.Unlimited {
+		return false, nil
+	}
+	n, err := svc.store.CountActiveByKind(ctx, accountID, kind)
+	if err != nil {
+		return false, err
+	}
+	return n >= limit, nil
+}
+
 // walletContext resolves the payments gate inputs for an account on the current request: the
 // trusted execution context (from the session platform carried on ctx; absent ⇒ untrusted) and
 // the account's present identity sources (which chip/benefit segments are awake, §6).
@@ -338,6 +373,7 @@ func (svc *Service) Create(ctx context.Context, params CreateParams) (Game, erro
 		dropoutTiles:         params.DropoutTiles.String(),
 		multipleWordsPerTurn: params.MultipleWordsPerTurn,
 		vsAI:                 params.VsAI,
+		kind:                 params.Kind,
 	}
 	if err := svc.store.CreateGame(ctx, ins, seats, seeding.draws); err != nil {
 		return Game{}, err
@@ -401,6 +437,7 @@ func (svc *Service) OpenOrJoin(ctx context.Context, accountID uuid.UUID, params
 		multipleWordsPerTurn: params.MultipleWordsPerTurn,
 		status:               StatusOpen,
 		openDeadline:         &deadline,
+		kind:                 gamelimits.KindRandom,
 	}
 	// Decide the first move now by the official draw, with the not-yet-arrived opponent as a
 	// synthetic placeholder (uuid.Nil): the draw fixes who sits at seat 0 — and so moves
@@ -1207,7 +1244,7 @@ func (svc *Service) Hint(ctx context.Context, gameID, accountID uuid.UUID) (Hint
 		return HintResult{}, err
 	}
 	used++
-	return HintResult{Move: move, HintsRemaining: hintsRemaining(pre.HintsPerPlayer, used, walletAfter), WalletBalance: walletAfter}, nil
+	return HintResult{Move: move, HintsRemaining: hintsRemaining(pre.HintsPerPlayer, used), WalletBalance: walletAfter}, nil
 }
 
 // Candidates returns the to-move player's legal plays for a seated player on
@@ -1272,10 +1309,6 @@ func (svc *Service) GameState(ctx context.Context, gameID, accountID uuid.UUID)
 	if !ok {
 		return StateView{}, ErrNotAPlayer
 	}
-	acc, err := svc.accounts.GetByID(ctx, accountID)
-	if err != nil {
-		return StateView{}, err
-	}
 
 	unlock := svc.locks.lock(gameID)
 	defer unlock()
@@ -1294,8 +1327,9 @@ func (svc *Service) GameState(ctx context.Context, gameID, accountID uuid.UUID)
 		Seat:   seat,
 		Rack:   g.Hand(seat),
 		BagLen: g.BagLen(),
-		HintsRemaining: hintsRemaining(pre.HintsPerPlayer, pre.Seats[seat].HintsUsed, acc.HintBalance),
-		WalletBalance:  acc.HintBalance,
+		// HintsRemaining is the per-seat allowance only; the purchasable wallet lives on the profile
+		// (payments) and the client adds it (lib/hints.hintsLeft).
+		HintsRemaining: hintsRemaining(pre.HintsPerPlayer, pre.Seats[seat].HintsUsed),
 		// vs_ai idle-hint gate (seconds left; 0 for a human game / first move / not your turn).
 		HintUnlockLeftSeconds: hintUnlockLeftSeconds(pre, seat, svc.clock()),
 	}, nil
@@ -1389,14 +1423,6 @@ func (svc *Service) ListForLobby(ctx context.Context, accountID uuid.UUID) ([]Ga
 	return kept, nil
 }
 
-// CountActiveQuickGames reports how many in-progress quick games the account holds —
-// the count the simultaneous-game limit (MaxActiveQuickGames) is checked against. It
-// counts active and still-open quick games (including honest-AI ones) and excludes
-// friend games created by invitation and finished games. See Store.CountActiveQuickGames.
-func (svc *Service) CountActiveQuickGames(ctx context.Context, accountID uuid.UUID) (int, error) {
-	return svc.store.CountActiveQuickGames(ctx, accountID)
-}
-
 // HideGame hides a finished game from accountID's own lobby (it stays visible to the other
 // players); it is irreversible by design. Only a player of a finished game may hide it
 // (ErrNotAPlayer / ErrGameActive otherwise); hiding an already-hidden game is a no-op.
@@ -1776,10 +1802,10 @@ func (svc *Service) DictBytes(variant engine.Variant, version string) ([]byte, e
 	return svc.registry.DictBytes(variant, version)
 }
 
-// hintsRemaining is a player's remaining hint budget: the unspent per-game
-// allowance plus the profile wallet.
-func hintsRemaining(allowance, used, wallet int) int {
-	return max(0, allowance-used) + wallet
+// hintsRemaining is the unspent per-game hint allowance. The purchasable wallet is separate,
+// carried on the profile (payments), and the client adds it (lib/hints.hintsLeft).
+func hintsRemaining(allowance, used int) int {
+	return max(0, allowance-used)
 }
 
 // allowedTimeout reports whether d is one of the offered move clocks.

backend/internal/game/store.go

@@ -15,6 +15,7 @@ import (
 
 	"scrabble/backend/internal/account"
 	"scrabble/backend/internal/engine"
+	"scrabble/backend/internal/gamelimits"
 	"scrabble/backend/internal/postgres/jet/backend/model"
 	"scrabble/backend/internal/postgres/jet/backend/table"
 )
@@ -45,6 +46,8 @@ type gameInsert struct {
 	multipleWordsPerTurn bool
 	// vsAI marks an honest-AI game (games.vs_ai).
 	vsAI bool
+	// kind tags the game's origin (games.game_kind) for the active-game limits.
+	kind gamelimits.Kind
 	// status is the lifecycle state to create the game in: StatusActive for a normal
 	// seated game, StatusOpen for an auto-match game still awaiting an opponent. An
 	// empty string defaults to StatusActive.
@@ -138,6 +141,20 @@ func (s *Store) CreateGame(ctx context.Context, ins gameInsert, seats []seatInse
 	})
 }
 
+// CountActiveByKind counts the account's active (open or in-progress) games of the given kind — the
+// per-tier active-game limit is checked against it before a new game of that kind is created.
+func (s *Store) CountActiveByKind(ctx context.Context, accountID uuid.UUID, kind gamelimits.Kind) (int, error) {
+	var n int
+	if err := s.db.QueryRowContext(ctx,
+		`SELECT count(*) FROM backend.games g
+		   JOIN backend.game_players p ON p.game_id = g.game_id
+		  WHERE p.account_id = $1 AND g.game_kind = $2 AND g.status IN ('open', 'active')`,
+		accountID, int16(kind)).Scan(&n); err != nil {
+		return 0, fmt.Errorf("game: count active by kind %s: %w", accountID, err)
+	}
+	return n, nil
+}
+
 // insertGameTx inserts the games row and one game_players row per seat (seat 0
 // first) on tx, stamping each seat's display-name snapshot. A seat whose account id is
 // uuid.Nil is written with a NULL account_id (and an empty snapshot) — the still-empty
@@ -155,9 +172,9 @@ func insertGameTx(ctx context.Context, tx *sql.Tx, ins gameInsert, seats []seatI
 		table.Games.GameID, table.Games.Variant, table.Games.DictVersion, table.Games.Seed,
 		table.Games.Status, table.Games.Players, table.Games.TurnTimeoutSecs,
 		table.Games.HintsAllowed, table.Games.HintsPerPlayer, table.Games.OpenDeadlineAt,
-		table.Games.DropoutTiles, table.Games.MultipleWordsPerTurn, table.Games.VsAi,
+		table.Games.DropoutTiles, table.Games.MultipleWordsPerTurn, table.Games.VsAi, table.Games.GameKind,
 	).VALUES(ins.id, ins.variant, ins.dictVersion, ins.seed, status, ins.players,
-		ins.turnTimeoutSecs, ins.hintsAllowed, ins.hintsPerPlayer, deadline, ins.dropoutTiles, ins.multipleWordsPerTurn, ins.vsAI)
+		ins.turnTimeoutSecs, ins.hintsAllowed, ins.hintsPerPlayer, deadline, ins.dropoutTiles, ins.multipleWordsPerTurn, ins.vsAI, int16(ins.kind))
 	if _, err := gi.ExecContext(ctx, tx); err != nil {
 		return fmt.Errorf("insert game: %w", err)
 	}
@@ -501,28 +518,6 @@ func (s *Store) ListGamesForAccount(ctx context.Context, accountID uuid.UUID) ([
 	return out, nil
 }
 
-// CountActiveQuickGames counts the account's in-progress quick games — the ones the
-// simultaneous-game limit (MaxActiveQuickGames) is checked against. It includes both
-// active and still-open (awaiting-opponent) games, the honest-AI ones among them, and
-// excludes friend games (those linked to a game_invitations row) and finished games.
-// A hidden game still occupies a slot, so this is a dedicated count rather than a
-// filter over ListGamesForAccount (which drops hidden games). Joining on the account's
-// own seat counts each game once (an open game's empty opponent seat has no account).
-func (s *Store) CountActiveQuickGames(ctx context.Context, accountID uuid.UUID) (int, error) {
-	// The status literals are game.StatusActive / game.StatusOpen, matching the
-	// games.status CHECK in the baseline migration.
-	const q = `
-SELECT COUNT(*) FROM backend.games g
-JOIN backend.game_players gp ON gp.game_id = g.game_id
-LEFT JOIN backend.game_invitations gi ON gi.game_id = g.game_id
-WHERE gp.account_id = $1 AND g.status IN ('active', 'open') AND gi.game_id IS NULL`
-	var n int
-	if err := s.db.QueryRowContext(ctx, q, accountID).Scan(&n); err != nil {
-		return 0, fmt.Errorf("game: count active quick games: %w", err)
-	}
-	return n, nil
-}
-
 // HideGame hides a game from the account's own lobby list (idempotent). The caller validates the
 // game is finished and the account is a player.
 func (s *Store) HideGame(ctx context.Context, accountID, gameID uuid.UUID) error {
@@ -1361,6 +1356,7 @@ func projectGame(g model.Games, seats []model.GamePlayers) (Game, error) {
 	}
 	out.MultipleWordsPerTurn = g.MultipleWordsPerTurn
 	out.VsAI = g.VsAi
+	out.Kind = gamelimits.Kind(g.GameKind)
 	if g.EndReason != nil {
 		out.EndReason = *g.EndReason
 	}

backend/internal/game/types.go

@@ -7,6 +7,7 @@ import (
 	"github.com/google/uuid"
 
 	"scrabble/backend/internal/engine"
+	"scrabble/backend/internal/gamelimits"
 )
 
 // Status values persisted in the games.status column.
@@ -94,15 +95,6 @@ const DefaultTurnTimeout = 24 * time.Hour
 // one of AllowedTurnTimeouts (never offered in the creation UI).
 const AIInactivityTimeout = 7 * 24 * time.Hour
 
-// MaxActiveQuickGames is the cap on a player's simultaneous quick games (human
-// auto-match and honest-AI), counting both in-progress (StatusActive) and
-// still-open, awaiting-opponent (StatusOpen) games. Friend games created by
-// invitation are not counted. At the cap the backend refuses to create a new game
-// of any kind — quick or by invitation — and the lobby disables "New Game";
-// accepting an incoming invitation is always allowed. See
-// Store.CountActiveQuickGames.
-const MaxActiveQuickGames = 10
-
 // aiPlayerName labels the robot seat in an honest-AI game's GCG export, so a downloaded
 // game file shows a clean "AI" rather than the robot's human-like pool name (the in-app
 // UI shows 🤖 from the game's vs_ai flag).
@@ -125,6 +117,10 @@ type CreateParams struct {
 	// robot is seated at once, the move clock is AIInactivityTimeout, and chat/nudge
 	// and finish-time statistics are suppressed. Set by the lobby's AI-match path.
 	VsAI bool
+	// Kind tags the game's origin (games.game_kind) for the active-game limits: vs_ai / random /
+	// friends. The lobby sets it; a zero (unknown) kind is never gated. The active-game limit itself
+	// is enforced at the new-game handler (Server.ensureUnderGameLimit), not here.
+	Kind gamelimits.Kind
 }
 
 // Game is the persisted state of a match: the games row joined with its seats.
@@ -151,6 +147,9 @@ type Game struct {
 	// VsAI is true for an honest-AI game (games.vs_ai): the opponent is a robot the
 	// player knowingly chose, shown as 🤖, with chat/nudge disabled and no statistics.
 	VsAI bool
+	// Kind is the game's origin tag (games.game_kind) for the active-game limits: vs_ai / random /
+	// friends, or unknown for an untagged game. Read-only projection; set once on creation.
+	Kind gamelimits.Kind
 }
 
 // Seat is one player's standing in a game.
@@ -211,10 +210,9 @@ type MoveResult struct {
 	BagLen int
 }
 
-// HintResult is a revealed hint and the requesting player's remaining hint
-// budget (per-seat allowance plus profile wallet) after spending one. WalletBalance is
-// the global wallet alone, so the client can keep its live wallet authoritative and
-// re-derive the per-game allowance (HintsRemaining - WalletBalance).
+// HintResult is a revealed hint with the per-seat allowance remaining (HintsRemaining) and the
+// purchasable hint wallet after spending one (WalletBalance, from payments). The client adopts
+// WalletBalance into the profile so the badge stays live across games (lib/hints).
 type HintResult struct {
 	Move           engine.MoveRecord
 	HintsRemaining int
@@ -241,9 +239,6 @@ type StateView struct {
 	Rack           []string
 	BagLen         int
 	HintsRemaining int
-	// WalletBalance is the player's global hint-wallet balance alone (HintsRemaining folds
-	// it in with the per-game allowance), so the client keeps the wallet live across games.
-	WalletBalance int
 	// HintUnlockLeftSeconds is, for a vs_ai game on the requesting player's turn, the seconds left
 	// until the idle hint unlocks (the robot's last move plus the idle window, from the server clock);
 	// 0 for the human's first move, when it is not their turn, or a non-vs_ai game. The vs_ai hint is

backend/internal/gamelimits/gamelimits.go

@@ -0,0 +1,149 @@
+// Package gamelimits holds the per-tier, per-kind active-game caps (a guest funnel) with a hot
+// in-memory cache over the single-row backend.config, so a login or a game-create never queries it.
+package gamelimits
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"sync"
+
+	"github.com/go-jet/jet/v2/postgres"
+
+	"scrabble/backend/internal/postgres/jet/backend/model"
+	"scrabble/backend/internal/postgres/jet/backend/table"
+)
+
+// Kind is a game's kind, mirroring backend.games.game_kind. 0 (unknown) is an untagged game, never gated.
+type Kind int16
+
+const (
+	KindUnknown Kind = 0
+	KindVsAI    Kind = 1
+	KindRandom  Kind = 2
+	KindFriends Kind = 3
+)
+
+// String returns the kind's label for admin game lists and logs.
+func (k Kind) String() string {
+	switch k {
+	case KindVsAI:
+		return "vs_ai"
+	case KindRandom:
+		return "random"
+	case KindFriends:
+		return "friends"
+	default:
+		return "unknown"
+	}
+}
+
+// Unlimited is the limit sentinel meaning no cap.
+const Unlimited = -1
+
+// Limits is a tier's active-game caps per kind (-1 = unlimited).
+type Limits struct {
+	VsAI    int
+	Random  int
+	Friends int
+}
+
+// Cap returns the limit for kind; the unknown kind is never capped.
+func (l Limits) Cap(kind Kind) int {
+	switch kind {
+	case KindVsAI:
+		return l.VsAI
+	case KindRandom:
+		return l.Random
+	case KindFriends:
+		return l.Friends
+	default:
+		return Unlimited
+	}
+}
+
+// Config is the per-tier limit config (the single backend.config row).
+type Config struct {
+	Guest   Limits
+	Durable Limits
+}
+
+// Store reads and writes the single-row backend.config.
+type Store struct{ db *sql.DB }
+
+// NewStore constructs a Store over db.
+func NewStore(db *sql.DB) *Store { return &Store{db: db} }
+
+func (s *Store) load(ctx context.Context) (Config, error) {
+	var c model.Config
+	if err := postgres.SELECT(table.Config.AllColumns).FROM(table.Config).LIMIT(1).
+		QueryContext(ctx, s.db, &c); err != nil {
+		return Config{}, fmt.Errorf("gamelimits: load config: %w", err)
+	}
+	return Config{
+		Guest:   Limits{VsAI: int(c.GuestVsAiLimit), Random: int(c.GuestRandomLimit), Friends: int(c.GuestFriendsLimit)},
+		Durable: Limits{VsAI: int(c.DurableVsAiLimit), Random: int(c.DurableRandomLimit), Friends: int(c.DurableFriendsLimit)},
+	}, nil
+}
+
+func (s *Store) save(ctx context.Context, c Config) error {
+	if _, err := s.db.ExecContext(ctx,
+		`UPDATE backend.config SET guest_vs_ai_limit=$1, guest_random_limit=$2, guest_friends_limit=$3,
+		   durable_vs_ai_limit=$4, durable_random_limit=$5, durable_friends_limit=$6 WHERE only_row`,
+		c.Guest.VsAI, c.Guest.Random, c.Guest.Friends, c.Durable.VsAI, c.Durable.Random, c.Durable.Friends); err != nil {
+		return fmt.Errorf("gamelimits: save config: %w", err)
+	}
+	return nil
+}
+
+// Service fronts the config with an in-memory cache (single-instance, matching the deploy). Load
+// once at startup; Update after an admin edit refreshes it in place.
+type Service struct {
+	store *Store
+	mu    sync.RWMutex
+	cfg   Config
+}
+
+// NewService constructs a Service over store. Call Load before serving.
+func NewService(store *Store) *Service { return &Service{store: store} }
+
+// Load reads the config into the cache. Call once at startup.
+func (s *Service) Load(ctx context.Context) error {
+	c, err := s.store.load(ctx)
+	if err != nil {
+		return err
+	}
+	s.set(c)
+	return nil
+}
+
+func (s *Service) set(c Config) {
+	s.mu.Lock()
+	s.cfg = c
+	s.mu.Unlock()
+}
+
+// Get returns the cached config.
+func (s *Service) Get() Config {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.cfg
+}
+
+// LimitsFor returns the cached limits for the account tier (guest or durable).
+func (s *Service) LimitsFor(isGuest bool) Limits {
+	c := s.Get()
+	if isGuest {
+		return c.Guest
+	}
+	return c.Durable
+}
+
+// Update saves the config and refreshes the cache in place (the admin edit).
+func (s *Service) Update(ctx context.Context, c Config) error {
+	if err := s.store.save(ctx, c); err != nil {
+		return err
+	}
+	s.set(c)
+	return nil
+}

backend/internal/gamelimits/gamelimits_test.go

@@ -0,0 +1,44 @@
+package gamelimits
+
+import "testing"
+
+// TestLimitsCap checks Cap maps each kind to its field and leaves the unknown kind uncapped, so a
+// untagged game (game_kind 0) is never gated.
+func TestLimitsCap(t *testing.T) {
+	l := Limits{VsAI: 1, Random: 2, Friends: 3}
+	for _, tc := range []struct {
+		kind Kind
+		want int
+	}{
+		{KindVsAI, 1},
+		{KindRandom, 2},
+		{KindFriends, 3},
+		{KindUnknown, Unlimited},
+		{Kind(99), Unlimited},
+	} {
+		if got := l.Cap(tc.kind); got != tc.want {
+			t.Errorf("Cap(%d) = %d, want %d", tc.kind, got, tc.want)
+		}
+	}
+}
+
+// TestServiceLimitsForTier checks LimitsFor selects the guest or durable tier from the cached config.
+func TestServiceLimitsForTier(t *testing.T) {
+	svc := NewService(nil)
+	svc.set(Config{
+		Guest:   Limits{VsAI: 1, Random: 1, Friends: 0},
+		Durable: Limits{VsAI: 10, Random: 10, Friends: 10},
+	})
+
+	if got := svc.LimitsFor(true); got != (Limits{VsAI: 1, Random: 1, Friends: 0}) {
+		t.Errorf("guest limits = %+v, want {1 1 0}", got)
+	}
+	if got := svc.LimitsFor(false); got != (Limits{VsAI: 10, Random: 10, Friends: 10}) {
+		t.Errorf("durable limits = %+v, want {10 10 10}", got)
+	}
+	// The unlimited sentinel resolves through the tier too.
+	svc.set(Config{Durable: Limits{VsAI: Unlimited, Random: Unlimited, Friends: Unlimited}})
+	if got := svc.LimitsFor(false).Cap(KindVsAI); got != Unlimited {
+		t.Errorf("durable vs_ai cap = %d, want unlimited (-1)", got)
+	}
+}

backend/internal/inttest/admin_grant_test.go

@@ -0,0 +1,79 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/payments"
+)
+
+// benefitFor returns the account's benefit on the given origin from its statement.
+func benefitFor(t *testing.T, pay *payments.Service, id uuid.UUID, origin payments.Source) payments.OriginBenefit {
+	t.Helper()
+	stmt, err := pay.AccountStatement(context.Background(), id)
+	if err != nil {
+		t.Fatalf("statement: %v", err)
+	}
+	for _, b := range stmt.Benefits {
+		if b.Origin == origin {
+			return b
+		}
+	}
+	return payments.OriginBenefit{}
+}
+
+// TestConsoleAdminGrant drives the admin grant: a raw benefit grant, a by-product grant of a reward
+// bundle, and a refusal to grant a chips pack; the create is CSRF-guarded.
+func TestConsoleAdminGrant(t *testing.T) {
+	ctx := context.Background()
+	srv, _, pay := bannerServer(t)
+	h := srv.Handler()
+	id := provisionAccount(t)
+	const origin = "http://admin.test"
+	base := "http://admin.test/_gm/users/" + id.String()
+
+	// CSRF: a grant without the origin header is refused.
+	if code, _ := consoleDo(h, http.MethodPost, base+"/grant", "origin=direct&hints=1", ""); code != http.StatusForbidden {
+		t.Fatalf("grant without origin = %d, want 403", code)
+	}
+
+	// Raw grant: 5 hints + 30 no-ads days to the direct origin.
+	if code, body := consoleDo(h, http.MethodPost, base+"/grant", "origin=direct&hints=5&noads=30", origin); code != http.StatusOK || !strings.Contains(body, "Granted") {
+		t.Fatalf("raw grant = %d, has 'Granted' = %v", code, strings.Contains(body, "Granted"))
+	}
+	if b := benefitFor(t, pay, id, payments.SourceDirect); b.Hints != 5 || b.AdsPaidUntil.IsZero() {
+		t.Fatalf("after raw grant: hints=%d adsUntil-zero=%v, want 5 hints + a no-ads term", b.Hints, b.AdsPaidUntil.IsZero())
+	}
+
+	// By-product grant: an archived reward bundle (3 hints) to vk.
+	reward, err := pay.CreateProduct(ctx, payments.ProductInput{
+		Title: "reward-3-hints", Atoms: []payments.AtomLine{{Atom: "hints", Quantity: 3}},
+	}, false)
+	if err != nil {
+		t.Fatalf("create reward: %v", err)
+	}
+	if code, body := consoleDo(h, http.MethodPost, base+"/grant-product", "origin=vk&product_id="+reward.String(), origin); code != http.StatusOK || !strings.Contains(body, "Granted") {
+		t.Fatalf("product grant = %d, has 'Granted' = %v", code, strings.Contains(body, "Granted"))
+	}
+	if b := benefitFor(t, pay, id, payments.SourceVK); b.Hints != 3 {
+		t.Fatalf("after product grant: vk hints=%d, want 3", b.Hints)
+	}
+
+	// A chips pack cannot be granted.
+	pack, err := pay.CreateProduct(ctx, payments.ProductInput{
+		Title: "grant-pack", Atoms: []payments.AtomLine{{Atom: "chips", Quantity: 100}},
+		Prices: []payments.PriceLine{{Method: "direct", Currency: payments.CurrencyRUB, Amount: 14900}},
+	}, true)
+	if err != nil {
+		t.Fatalf("create pack: %v", err)
+	}
+	if code, body := consoleDo(h, http.MethodPost, base+"/grant-product", "origin=direct&product_id="+pack.String(), origin); code != http.StatusOK || !strings.Contains(body, "cannot grant chips") {
+		t.Fatalf("chips grant = %d, has 'cannot grant chips' = %v", code, strings.Contains(body, "cannot grant chips"))
+	}
+}

backend/internal/inttest/admin_refund_test.go

@@ -0,0 +1,77 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+
+	"scrabble/backend/internal/payments"
+)
+
+// TestConsoleRefundAndExport drives the manual refund and the ledger CSV export: a funded order is
+// refunded in full (chips revoked, a refund row), the refund is idempotent, and the export carries
+// the fund + refund rows; the refund POST is CSRF-guarded.
+func TestConsoleRefundAndExport(t *testing.T) {
+	ctx := context.Background()
+	srv, _, pay := bannerServer(t)
+	h := srv.Handler()
+	id := provisionAccount(t)
+	const origin = "http://admin.test"
+	base := "http://admin.test/_gm/users/" + id.String()
+
+	// Fund a pack: 100 chips + a fund ledger row.
+	prod := seedPackProduct(t, 100, methodPrice{method: "direct", currency: "RUB", amount: 14900})
+	res, err := pay.CreateOrder(ctx, id, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("order: %v", err)
+	}
+	paid, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	if _, err := pay.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), paid); err != nil {
+		t.Fatalf("fund: %v", err)
+	}
+
+	// CSRF: a refund without the origin header is refused.
+	if code, _ := consoleDo(h, http.MethodPost, base+"/refund", "order_id="+res.OrderID.String(), ""); code != http.StatusForbidden {
+		t.Fatalf("refund without origin = %d, want 403", code)
+	}
+
+	// Refund the order in full → 100 chips revoked (none spent).
+	if code, body := consoleDo(h, http.MethodPost, base+"/refund", "order_id="+res.OrderID.String(), origin); code != http.StatusOK || !strings.Contains(body, "revoked 100 chips") {
+		t.Fatalf("refund = %d, has 'revoked 100 chips' = %v", code, strings.Contains(body, "revoked 100 chips"))
+	}
+	stmt, err := pay.AccountStatement(ctx, id)
+	if err != nil {
+		t.Fatalf("statement: %v", err)
+	}
+	for _, sg := range stmt.Segments {
+		if sg.Source == payments.SourceDirect && sg.Chips != 0 {
+			t.Errorf("after refund: direct chips = %d, want 0", sg.Chips)
+		}
+	}
+	kinds := map[string]int{}
+	for _, e := range stmt.Ledger {
+		kinds[e.Kind]++
+	}
+	if kinds["fund"] != 1 || kinds["refund"] != 1 {
+		t.Errorf("ledger kinds = %v, want one fund + one refund", kinds)
+	}
+
+	// A second refund of the same order is idempotent.
+	if code, body := consoleDo(h, http.MethodPost, base+"/refund", "order_id="+res.OrderID.String(), origin); code != http.StatusOK || !strings.Contains(body, "Already refunded") {
+		t.Fatalf("second refund = %d, has 'Already refunded' = %v", code, strings.Contains(body, "Already refunded"))
+	}
+
+	// Export the whole ledger as CSV: the header, this account, and its fund + refund rows.
+	code, body := consoleDo(h, http.MethodGet, "http://admin.test/_gm/ledger.csv", "", "")
+	if code != http.StatusOK {
+		t.Fatalf("export = %d, want 200", code)
+	}
+	for _, want := range []string{"created_at,account_id,kind", id.String(), ",fund,", ",refund,"} {
+		if !strings.Contains(body, want) {
+			t.Errorf("ledger CSV missing %q", want)
+		}
+	}
+}

backend/internal/inttest/admin_test.go

@@ -4,7 +4,6 @@ package inttest
 
 import (
 	"context"
-	"errors"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -280,76 +279,6 @@ func TestConsoleThrottledViewAndFlagClear(t *testing.T) {
 	}
 }
 
-// TestConsoleGrantHints drives the admin hint-wallet grant end to end: the card shows the form,
-// the action is CSRF-guarded, a same-origin grant adds to the wallet, a second grant adds again
-// (rather than replacing), the inclusive per-grant cap is accepted, and an out-of-range or
-// non-numeric amount is refused without changing the balance.
-func TestConsoleGrantHints(t *testing.T) {
-	ctx := context.Background()
-	accounts := account.NewStore(testDB)
-	id := provisionAccount(t)
-	srv := server.New(":0", server.Deps{
-		Logger: zap.NewNop(), Accounts: accounts, Games: newGameService(), Registry: testRegistry, DictDir: dictDir(),
-	})
-	h := srv.Handler()
-	base := "http://admin.test/_gm/users/" + id.String()
-
-	if code, body := consoleDo(h, http.MethodGet, base, "", ""); code != http.StatusOK || !strings.Contains(body, "Add hints") {
-		t.Fatalf("user card = %d, has grant form = %v", code, strings.Contains(body, "Add hints"))
-	}
-	// The grant POST is CSRF-guarded like every console action.
-	if code, _ := consoleDo(h, http.MethodPost, base+"/grant-hints", "amount=5", ""); code != http.StatusForbidden {
-		t.Fatalf("grant without origin = %d, want 403", code)
-	}
-	// A same-origin grant adds to the wallet.
-	if code, body := consoleDo(h, http.MethodPost, base+"/grant-hints", "amount=5", "http://admin.test"); code != http.StatusOK || !strings.Contains(body, "now 5") {
-		t.Fatalf("grant 5 = %d, body has 'now 5' = %v", code, strings.Contains(body, "now 5"))
-	}
-	if acc, err := accounts.GetByID(ctx, id); err != nil || acc.HintBalance != 5 {
-		t.Fatalf("after grant 5: balance=%d err=%v, want 5", acc.HintBalance, err)
-	}
-	// A second grant adds again rather than replacing.
-	if code, body := consoleDo(h, http.MethodPost, base+"/grant-hints", "amount=3", "http://admin.test"); code != http.StatusOK || !strings.Contains(body, "now 8") {
-		t.Fatalf("grant 3 = %d, body has 'now 8' = %v", code, strings.Contains(body, "now 8"))
-	}
-	// An out-of-range or non-numeric amount is refused; the balance is left untouched.
-	for _, bad := range []string{"0", "-1", "101", "x", ""} {
-		if code, body := consoleDo(h, http.MethodPost, base+"/grant-hints", "amount="+bad, "http://admin.test"); code != http.StatusOK || !strings.Contains(body, "Invalid amount") {
-			t.Fatalf("grant %q = %d, has 'Invalid amount' = %v", bad, code, strings.Contains(body, "Invalid amount"))
-		}
-	}
-	if acc, err := accounts.GetByID(ctx, id); err != nil || acc.HintBalance != 8 {
-		t.Fatalf("after invalid grants: balance=%d err=%v, want 8", acc.HintBalance, err)
-	}
-	// The inclusive per-grant cap (100) is accepted.
-	if code, _ := consoleDo(h, http.MethodPost, base+"/grant-hints", "amount=100", "http://admin.test"); code != http.StatusOK {
-		t.Fatalf("grant 100 = %d, want 200", code)
-	}
-	if acc, err := accounts.GetByID(ctx, id); err != nil || acc.HintBalance != 108 {
-		t.Fatalf("after grant 100: balance=%d err=%v, want 108", acc.HintBalance, err)
-	}
-}
-
-// TestGrantHintsStore covers the wallet store method directly: an additive grant raises the
-// balance, a non-positive grant is rejected, and an unknown account yields ErrNotFound.
-func TestGrantHintsStore(t *testing.T) {
-	ctx := context.Background()
-	accounts := account.NewStore(testDB)
-	id := provisionAccount(t)
-	if bal, err := accounts.GrantHints(ctx, id, 4); err != nil || bal != 4 {
-		t.Fatalf("grant 4 = (%d, %v), want (4, nil)", bal, err)
-	}
-	if bal, err := accounts.GrantHints(ctx, id, 6); err != nil || bal != 10 {
-		t.Fatalf("grant 6 = (%d, %v), want (10, nil)", bal, err)
-	}
-	if _, err := accounts.GrantHints(ctx, id, 0); err == nil {
-		t.Error("grant 0 should be rejected (non-positive)")
-	}
-	if _, err := accounts.GrantHints(ctx, uuid.New(), 1); !errors.Is(err, account.ErrNotFound) {
-		t.Errorf("grant unknown account = %v, want ErrNotFound", err)
-	}
-}
-
 // consoleDo issues a request to h, optionally with an Origin header, and returns
 // the status and body. Form bodies are sent as application/x-www-form-urlencoded.
 func consoleDo(h http.Handler, method, target, body, origin string) (int, string) {

backend/internal/inttest/banner_console_test.go

@@ -191,7 +191,7 @@ func TestBannerMessageOwnership(t *testing.T) {
 	}
 }
 
-// profileBanner is the banner block of the profile.get JSON response.
+// profileBanner is the banner (and interstitial-ad) block of the profile.get JSON response.
 type profileBanner struct {
 	Banner *struct {
 		Campaigns []struct {
@@ -203,6 +203,12 @@ type profileBanner struct {
 			HoldMs int `json:"hold_ms"`
 		} `json:"timings"`
 	} `json:"banner"`
+	Ads *struct {
+		CooldownGlobalS int  `json:"cooldown_global_s"`
+		CooldownVsAiS   int  `json:"cooldown_vs_ai_s"`
+		CooldownHintS   int  `json:"cooldown_hint_s"`
+		Suppressed      bool `json:"suppressed"`
+	} `json:"ads"`
 }
 
 // TestBannerProfileEligibility checks the profile.get banner block follows
@@ -283,6 +289,81 @@ func TestBannerProfileEligibility(t *testing.T) {
 	}
 }
 
+// TestProfileAdsConfig checks the profile.get interstitial-ad block: the seeded config cooldowns are
+// carried through, and Suppressed follows the same no-ads / no_banner gate as the banner (the client
+// self-gates VK-only + online on top). The no_banner role is context-independent; the no-ads benefit
+// applies only in a trusted context where its segment is present.
+func TestProfileAdsConfig(t *testing.T) {
+	ctx := context.Background()
+	srv, _, pay := bannerServer(t)
+	accounts := account.NewStore(testDB)
+	id := provisionAccount(t)
+
+	get := func() profileBanner {
+		t.Helper()
+		rec := userGet(t, srv, "/api/v1/user/profile", id)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("profile = %d, want 200", rec.Code)
+		}
+		var p profileBanner
+		if err := json.Unmarshal(rec.Body.Bytes(), &p); err != nil {
+			t.Fatalf("decode profile: %v", err)
+		}
+		return p
+	}
+	getTG := func() profileBanner {
+		t.Helper()
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/user/profile", nil)
+		req.Header.Set("X-User-ID", id.String())
+		req.Header.Set("X-Platform", "telegram/android")
+		srv.Handler().ServeHTTP(rec, req)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("profile = %d, want 200", rec.Code)
+		}
+		var p profileBanner
+		if err := json.Unmarshal(rec.Body.Bytes(), &p); err != nil {
+			t.Fatalf("decode profile: %v", err)
+		}
+		return p
+	}
+
+	// A free account: the ads block carries the seeded config cooldowns and is not suppressed.
+	p := get()
+	if p.Ads == nil {
+		t.Fatal("free account: no ads block")
+	}
+	if p.Ads.CooldownGlobalS != 300 || p.Ads.CooldownVsAiS != 1800 || p.Ads.CooldownHintS != 60 {
+		t.Fatalf("cooldowns = %d/%d/%d, want 300/1800/60", p.Ads.CooldownGlobalS, p.Ads.CooldownVsAiS, p.Ads.CooldownHintS)
+	}
+	if p.Ads.Suppressed {
+		t.Fatal("free account: interstitials must not be suppressed")
+	}
+
+	// The no_banner role suppresses interstitials too (context-independent).
+	if err := accounts.GrantRole(ctx, id, account.RoleNoBanner); err != nil {
+		t.Fatalf("grant role: %v", err)
+	}
+	if p := get(); p.Ads == nil || !p.Ads.Suppressed {
+		t.Fatalf("no_banner role: ads=%v, want suppressed", p.Ads)
+	}
+	if err := accounts.RevokeRole(ctx, id, account.RoleNoBanner); err != nil {
+		t.Fatalf("revoke role: %v", err)
+	}
+
+	// An active no-ads benefit suppresses interstitials in a trusted context; an untrusted context
+	// does not apply it (fail-closed to eligible, as for the banner).
+	if err := pay.Grant(ctx, id, payments.SourceTelegram, 0, 30, false); err != nil {
+		t.Fatalf("grant no-ads: %v", err)
+	}
+	if p := getTG(); p.Ads == nil || !p.Ads.Suppressed {
+		t.Fatalf("no-ads benefit (trusted): ads=%v, want suppressed", p.Ads)
+	}
+	if p := get(); p.Ads == nil || p.Ads.Suppressed {
+		t.Fatalf("no-ads benefit (untrusted): ads=%v, want NOT suppressed", p.Ads)
+	}
+}
+
 // TestBannerSurvivesProfileUpdate guards that a profile update (e.g. a language switch) returns the
 // banner block too, so the client's profile keeps the banner instead of losing it until reload.
 func TestBannerSurvivesProfileUpdate(t *testing.T) {
@@ -440,10 +521,4 @@ func TestBannerUrgentBypassesEligibility(t *testing.T) {
 	if err := accounts.RevokeRole(ctx, id, account.RoleNoBanner); err != nil {
 		t.Fatalf("revoke role: %v", err)
 	}
-
-	// A non-empty hint wallet no longer suppresses it either.
-	if _, err := accounts.GrantHints(ctx, id, 5); err != nil {
-		t.Fatalf("grant hints: %v", err)
-	}
-	assertUrgentOnly("hints", get())
 }

backend/internal/inttest/catalog_editor_test.go

@@ -0,0 +1,153 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/payments"
+)
+
+// 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(), true)
+	if err != nil {
+		t.Fatalf("admin catalog: %v", err)
+	}
+	for _, p := range all {
+		if p.Title == title {
+			return p
+		}
+	}
+	t.Fatalf("product %q not found", title)
+	return payments.AdminProduct{}
+}
+
+// TestConsoleCatalogEditor drives the catalog editor end to end: create is CSRF-guarded; a value and
+// a pack are created and edited; an invalid active product is refused; archive hides it; a
+// never-transacted product deletes; a transacted product is refused deletion (archive only).
+func TestConsoleCatalogEditor(t *testing.T) {
+	ctx := context.Background()
+	srv, _, pay := bannerServer(t)
+	h := srv.Handler()
+	const origin = "http://admin.test"
+	const catalog = "http://admin.test/_gm/catalog"
+
+	// CSRF: a create without the origin header is refused.
+	if code, _ := consoleDo(h, http.MethodPost, catalog, "title=x&hints=1&price_chip=10&active=true", ""); code != http.StatusForbidden {
+		t.Fatalf("create without origin = %d, want 403", code)
+	}
+
+	// Create a value product: 5 hints for 50 chips, active.
+	if code, body := consoleDo(h, http.MethodPost, catalog, "title=cat-hints-5&hints=5&price_chip=50&active=true", origin); code != http.StatusOK || !strings.Contains(body, "Created") {
+		t.Fatalf("create value = %d, has 'Created' = %v", code, strings.Contains(body, "Created"))
+	}
+	val := productByTitle(t, pay, "cat-hints-5")
+	if !val.Active || len(val.Atoms) != 1 || val.Atoms[0].Atom != "hints" || val.Atoms[0].Quantity != 5 {
+		t.Fatalf("created value = %+v", val)
+	}
+
+	// An invalid active pack (chips, no money price) is refused.
+	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, true); err != nil {
+		t.Fatalf("catalog: %v", err)
+	}
+
+	// Edit the value: raise to 8 hints.
+	base := catalog + "/" + val.ID.String()
+	if code, _ := consoleDo(h, http.MethodPost, base, "title=cat-hints-8&hints=8&price_chip=50&active=true", origin); code != http.StatusOK {
+		t.Fatalf("edit = %d", code)
+	}
+	if got := productByTitle(t, pay, "cat-hints-8"); len(got.Atoms) != 1 || got.Atoms[0].Quantity != 8 {
+		t.Fatalf("after edit atoms = %+v, want 8 hints", got.Atoms)
+	}
+
+	// Archive it → hidden from the storefront (the user Catalog filters active).
+	if code, _ := consoleDo(h, http.MethodPost, base+"/archive", "active=false", origin); code != http.StatusOK {
+		t.Fatalf("archive = %d", code)
+	}
+	if productByTitle(t, pay, "cat-hints-8").Active {
+		t.Error("product still active after archive")
+	}
+
+	// Delete the never-transacted product.
+	if code, body := consoleDo(h, http.MethodPost, base+"/delete", "", origin); code != http.StatusOK || !strings.Contains(body, "Deleted") {
+		t.Fatalf("delete clean = %d, has 'Deleted' = %v", code, strings.Contains(body, "Deleted"))
+	}
+
+	// A transacted product cannot be deleted — only archived.
+	if code, _ := consoleDo(h, http.MethodPost, catalog, "title=cat-pack&chips=100&price_rub=14900&active=true", origin); code != http.StatusOK {
+		t.Fatal("create pack failed")
+	}
+	pack := productByTitle(t, pay, "cat-pack")
+	if _, err := pay.CreateOrder(ctx, uuid.New(), payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, pack.ID, "robokassa"); err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	if code, body := consoleDo(h, http.MethodPost, catalog+"/"+pack.ID.String()+"/delete", "", origin); code != http.StatusOK || !strings.Contains(body, "Cannot delete") {
+		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/game_limit_test.go

@@ -5,6 +5,7 @@ package inttest
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
@@ -18,59 +19,119 @@ import (
 	"scrabble/backend/internal/account"
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/game"
+	"scrabble/backend/internal/gamelimits"
+	"scrabble/backend/internal/lobby"
 	"scrabble/backend/internal/server"
+	"scrabble/backend/internal/social"
 )
 
-// The game-limit suite covers the simultaneous quick-game cap (game.MaxActiveQuickGames):
-// the counting rule (Store/Service.CountActiveQuickGames) and the HTTP gate that refuses a
-// new game once the cap is reached, while accepting an incoming invitation stays allowed.
+// The game-limit suite covers the per-tier, per-kind active-game caps (backend.config): the
+// game_kind tag persisted per creation path, the tier resolution + counting rule
+// (game.Service.AtGameLimit), the HTTP gate + lobby at_game_limit flag, the guest gate on friend
+// actions, and the config hot-cache reflecting an admin edit. Accepting an invitation stays exempt.
 
-// TestCountActiveQuickGames checks the count includes active and open quick games (the
-// honest-AI ones among them) and excludes finished games, friend games (created by
-// invitation) and games the account is not seated in.
-func TestCountActiveQuickGames(t *testing.T) {
+// newGameLimits builds a gamelimits service over the shared pool and loads the seeded config
+// (guest 1/1/0, durable 10/10/10).
+func newGameLimits(t *testing.T) *gamelimits.Service {
+	t.Helper()
+	gl := gamelimits.NewService(gamelimits.NewStore(testDB))
+	if err := gl.Load(context.Background()); err != nil {
+		t.Fatalf("load game limits: %v", err)
+	}
+	return gl
+}
+
+// restoreDefaultLimits resets the single config row to the migration seed on cleanup, so a test that
+// edited it never leaks its values into another (the row is a shared singleton).
+func restoreDefaultLimits(t *testing.T, gl *gamelimits.Service) {
+	t.Helper()
+	t.Cleanup(func() {
+		_ = gl.Update(context.Background(), gamelimits.Config{
+			Guest:   gamelimits.Limits{VsAI: 1, Random: 1, Friends: 0},
+			Durable: gamelimits.Limits{VsAI: 10, Random: 10, Friends: 10},
+		})
+	})
+}
+
+// gameKind reads a game's persisted game_kind tag.
+func gameKind(t *testing.T, gameID uuid.UUID) int16 {
+	t.Helper()
+	var k int16
+	if err := testDB.QueryRowContext(context.Background(),
+		`SELECT game_kind FROM backend.games WHERE game_id=$1`, gameID).Scan(&k); err != nil {
+		t.Fatalf("read game_kind: %v", err)
+	}
+	return k
+}
+
+// mustCreateKind creates an active game seating the accounts, tagged with kind, and returns its id.
+func mustCreateKind(t *testing.T, games *game.Service, seats []uuid.UUID, kind gamelimits.Kind) uuid.UUID {
+	t.Helper()
+	g, err := games.Create(context.Background(), game.CreateParams{
+		Variant: engine.VariantEnglish, Seats: seats, TurnTimeout: 24 * time.Hour, Kind: kind,
+	})
+	if err != nil {
+		t.Fatalf("create game (kind=%d): %v", kind, err)
+	}
+	return g.ID
+}
+
+// startFriendGameID has inviter invite invitee to a friend game and the invitee accept, returning
+// the started game's id.
+func startFriendGameID(t *testing.T, inv *lobby.InvitationService, inviter, invitee uuid.UUID) uuid.UUID {
+	t.Helper()
+	ctx := context.Background()
+	invitation, err := inv.CreateInvitation(ctx, inviter, []uuid.UUID{invitee}, englishInvite())
+	if err != nil {
+		t.Fatalf("create invitation: %v", err)
+	}
+	got, err := inv.RespondInvitation(ctx, invitation.ID, invitee, true)
+	if err != nil {
+		t.Fatalf("accept invitation: %v", err)
+	}
+	if got.GameID == nil {
+		t.Fatal("accepted invitation has no game id")
+	}
+	return *got.GameID
+}
+
+// TestGameKindPersisted checks each creation path stamps the right game_kind: random (auto-match)
+// =2, vs_ai =1, friend (by invitation) =3.
+func TestGameKindPersisted(t *testing.T) {
 	ctx := context.Background()
 	clearOpenGames(t)
 	games := newGameService()
-	human := provisionAccount(t)
-	opp := provisionAccount(t)
+	inv := newInvitationService()
+	human, opp := provisionAccount(t), provisionAccount(t)
 
-	if n := mustCount(t, games, human); n != 0 {
-		t.Fatalf("fresh account count = %d, want 0", n)
+	rnd, _, err := games.OpenOrJoin(ctx, human, game.CreateParams{Variant: engine.VariantEnglish, TurnTimeout: 24 * time.Hour}, time.Now().Add(time.Minute), nil)
+	if err != nil {
+		t.Fatalf("open random game: %v", err)
+	}
+	if k := gameKind(t, rnd.ID); k != int16(gamelimits.KindRandom) {
+		t.Errorf("random game_kind = %d, want %d", k, gamelimits.KindRandom)
 	}
 
-	// An open (awaiting-opponent) quick game counts.
-	if _, _, err := games.OpenOrJoin(ctx, human, game.CreateParams{
-		Variant: engine.VariantEnglish, TurnTimeout: 24 * time.Hour,
-	}, time.Now().Add(time.Minute), nil); err != nil {
-		t.Fatalf("open quick game: %v", err)
+	ai := mustCreateKind(t, games, []uuid.UUID{human, opp}, gamelimits.KindVsAI)
+	if k := gameKind(t, ai); k != int16(gamelimits.KindVsAI) {
+		t.Errorf("vs_ai game_kind = %d, want %d", k, gamelimits.KindVsAI)
 	}
-	// An active quick game and an honest-AI quick game both count (neither has an invitation row).
-	mustCreateQuick(t, games, []uuid.UUID{human, opp}, false, 1)
-	mustCreateQuick(t, games, []uuid.UUID{human, opp}, true, 2)
 
-	// A finished quick game does NOT count.
-	fin := mustCreateQuick(t, games, []uuid.UUID{human, opp}, false, 3)
-	if _, err := testDB.ExecContext(ctx, `UPDATE backend.games SET status='finished' WHERE game_id=$1`, fin); err != nil {
-		t.Fatalf("finish game: %v", err)
-	}
-	// A game the human is not seated in does NOT count.
-	mustCreateQuick(t, games, []uuid.UUID{opp, provisionAccount(t)}, false, 4)
-	// A friend game (created by invitation) does NOT count, even though it is active.
-	startFriendGame(t, human)
-
-	if n := mustCount(t, games, human); n != 3 {
-		t.Fatalf("active quick count = %d, want 3 (active + AI + open)", n)
+	friend := startFriendGameID(t, inv, human, opp)
+	if k := gameKind(t, friend); k != int16(gamelimits.KindFriends) {
+		t.Errorf("friend game_kind = %d, want %d", k, gamelimits.KindFriends)
 	}
 }
 
-// TestGameLimitGate drives the cap through the assembled HTTP server: under the cap the lobby
-// reports at_game_limit false; at the cap it flips to true and both new-game endpoints (quick
-// enqueue and invitation creation) are refused with 409 game_limit_reached, while accepting an
-// incoming invitation is still allowed.
-func TestGameLimitGate(t *testing.T) {
+// TestGuestActiveGameLimitHTTP drives the guest random cap through the assembled server: the first
+// auto-match opens a game, the lobby then flags at_game_limit, and a second enqueue is refused 409
+// game_limit_reached. It also checks the guest vs_ai and friends caps resolve at the domain level.
+func TestGuestActiveGameLimitHTTP(t *testing.T) {
 	ctx := context.Background()
+	clearOpenGames(t)
+	gl := newGameLimits(t)
 	games := newGameService()
+	games.SetGameLimits(gl)
 	srv := server.New(":0", server.Deps{
 		Logger:      zaptest.NewLogger(t),
 		DB:          testDB,
@@ -78,88 +139,110 @@ func TestGameLimitGate(t *testing.T) {
 		Games:       games,
 		Matchmaker:  newMatchmaker(t, newRobotService(t, newGameService()), time.Minute, 0),
 		Invitations: newInvitationService(),
+		GameLimits:  gl,
 	})
 
-	human := provisionAccount(t)
+	guest := provisionGuest(t)
+	if gamesListAtLimit(t, srv, guest) {
+		t.Fatal("a fresh guest must be under the random game limit")
+	}
+	// The first auto-match opens a random game (guest random cap = 1).
+	if rec := userPost(t, srv, "/api/v1/user/lobby/enqueue", guest, `{"variant":"erudit_ru"}`); rec.Code != http.StatusOK {
+		t.Fatalf("first enqueue = %d (%s), want 200", rec.Code, rec.Body.String())
+	}
+	// At the cap: the lobby flags it and a second enqueue is refused with the stable code.
+	if !gamesListAtLimit(t, srv, guest) {
+		t.Fatal("after one random game the guest must be at the limit")
+	}
+	if rec := userPost(t, srv, "/api/v1/user/lobby/enqueue", guest, `{"variant":"erudit_ru"}`); rec.Code != http.StatusConflict || errorCode(t, rec) != "game_limit_reached" {
+		t.Fatalf("second enqueue = (%d, %q), want (409, game_limit_reached)", rec.Code, errorCode(t, rec))
+	}
+
+	// A guest is refused the friends flow outright at the HTTP edge (403 guest_forbidden).
 	opp := provisionAccount(t)
-
-	// Under the cap: the lobby reports the player is not limited.
-	if gamesListAtLimit(t, srv, human) {
-		t.Fatal("a fresh account must be under the game limit")
-	}
-
-	// Reach the cap with active quick games seating the human (no invitation row → quick).
-	for i := 0; i < game.MaxActiveQuickGames; i++ {
-		mustCreateQuick(t, games, []uuid.UUID{human, opp}, false, int64(i+1))
-	}
-
-	// At the cap: the lobby flags it and both create paths are refused with the stable code.
-	if !gamesListAtLimit(t, srv, human) {
-		t.Fatalf("at %d games at_game_limit must be true", game.MaxActiveQuickGames)
-	}
-	// erudit_ru is in the default variant preferences, so the variant gate passes and the
-	// game-limit gate is what fires here.
-	if rec := userPost(t, srv, "/api/v1/user/lobby/enqueue", human, `{"variant":"erudit_ru"}`); rec.Code != http.StatusConflict || errorCode(t, rec) != "game_limit_reached" {
-		t.Fatalf("enqueue at limit = (%d, %q), want (409, game_limit_reached)", rec.Code, errorCode(t, rec))
-	}
 	invBody := fmt.Sprintf(`{"variant":"erudit_ru","invitee_ids":[%q]}`, opp.String())
-	if rec := userPost(t, srv, "/api/v1/user/invitations", human, invBody); rec.Code != http.StatusConflict || errorCode(t, rec) != "game_limit_reached" {
-		t.Fatalf("invitation at limit = (%d, %q), want (409, game_limit_reached)", rec.Code, errorCode(t, rec))
+	if rec := userPost(t, srv, "/api/v1/user/invitations", guest, invBody); rec.Code != http.StatusForbidden || errorCode(t, rec) != "guest_forbidden" {
+		t.Fatalf("guest invitation = (%d, %q), want (403, guest_forbidden)", rec.Code, errorCode(t, rec))
 	}
 
-	// Accepting an incoming invitation is never blocked, even at the cap: another player invites
-	// the capped human, who accepts over HTTP and the game starts (friend games do not count).
-	inviter := provisionAccount(t)
-	inv := newInvitationService()
-	invitation, err := inv.CreateInvitation(ctx, inviter, []uuid.UUID{human}, englishInvite())
-	if err != nil {
-		t.Fatalf("create invitation: %v", err)
+	// The guest vs_ai cap is 1: one vs_ai game puts the guest at the vs_ai limit.
+	mustCreateKind(t, games, []uuid.UUID{guest, opp}, gamelimits.KindVsAI)
+	if at, err := games.AtGameLimit(ctx, guest, gamelimits.KindVsAI); err != nil || !at {
+		t.Fatalf("guest vs_ai at-limit = (%v, %v), want (true, nil)", at, err)
 	}
-	if rec := userPost(t, srv, "/api/v1/user/invitations/"+invitation.ID.String()+"/accept", human, ""); rec.Code != http.StatusOK {
-		t.Fatalf("accept at limit = %d (%s), want 200 — accept must bypass the cap", rec.Code, rec.Body.String())
+	// The guest friends cap is 0: a guest is always at the friends limit (the 403 gate blocks first).
+	if at, err := games.AtGameLimit(ctx, guest, gamelimits.KindFriends); err != nil || !at {
+		t.Fatalf("guest friends at-limit = (%v, %v), want (true, nil)", at, err)
 	}
 }
 
-// mustCount returns the account's active-quick-game count, failing on error.
-func mustCount(t *testing.T, games *game.Service, id uuid.UUID) int {
-	t.Helper()
-	n, err := games.CountActiveQuickGames(context.Background(), id)
-	if err != nil {
-		t.Fatalf("count active quick games: %v", err)
-	}
-	return n
-}
-
-// mustCreateQuick creates an active quick game (no invitation) seating the given accounts and
-// returns its id; vsAI flags an honest-AI game (the service then applies the 7-day clock).
-func mustCreateQuick(t *testing.T, games *game.Service, seats []uuid.UUID, vsAI bool, seed int64) uuid.UUID {
-	t.Helper()
-	p := game.CreateParams{Variant: engine.VariantEnglish, Seats: seats, TurnTimeout: 24 * time.Hour, Seed: seed}
-	if vsAI {
-		p.VsAI = true
-		p.TurnTimeout = 0 // the service applies the 7-day AI inactivity clock for vs_ai games
-	}
-	g, err := games.Create(context.Background(), p)
-	if err != nil {
-		t.Fatalf("create quick game (vsAI=%v): %v", vsAI, err)
-	}
-	return g.ID
-}
-
-// startFriendGame has a fresh inviter invite the given account to a friend game and the invitee
-// accept it, so the (active) friend game exists with its game_invitations row.
-func startFriendGame(t *testing.T, invitee uuid.UUID) {
-	t.Helper()
+// TestDurableTierHigherLimit checks a durable account resolves the durable tier, not the guest one:
+// one random game leaves it well under the durable cap (10).
+func TestDurableTierHigherLimit(t *testing.T) {
 	ctx := context.Background()
+	gl := newGameLimits(t)
+	games := newGameService()
+	games.SetGameLimits(gl)
+	durable, opp := provisionAccount(t), provisionAccount(t)
+
+	mustCreateKind(t, games, []uuid.UUID{durable, opp}, gamelimits.KindRandom)
+	if at, err := games.AtGameLimit(ctx, durable, gamelimits.KindRandom); err != nil || at {
+		t.Fatalf("durable random at-limit after one game = (%v, %v), want (false, nil)", at, err)
+	}
+}
+
+// TestGuestForbiddenFriendActions checks a guest is refused every friend action server-side (the UI
+// hides them; this is the source of truth): creating an invitation, sending a friend request, and
+// redeeming a friend code.
+func TestGuestForbiddenFriendActions(t *testing.T) {
+	ctx := context.Background()
+	guest := provisionGuest(t)
+	other := provisionAccount(t)
+
 	inv := newInvitationService()
+	if _, err := inv.CreateInvitation(ctx, guest, []uuid.UUID{other}, englishInvite()); !errors.Is(err, lobby.ErrGuestForbidden) {
+		t.Fatalf("guest CreateInvitation err = %v, want ErrGuestForbidden", err)
+	}
+
+	soc := newSocialService()
+	if err := soc.SendFriendRequest(ctx, guest, other); !errors.Is(err, social.ErrGuestForbidden) {
+		t.Fatalf("guest SendFriendRequest err = %v, want ErrGuestForbidden", err)
+	}
+	if _, err := soc.RedeemFriendCode(ctx, guest, "000000"); !errors.Is(err, social.ErrGuestForbidden) {
+		t.Fatalf("guest RedeemFriendCode err = %v, want ErrGuestForbidden", err)
+	}
+}
+
+// TestDurableFriendsCapAndConfigCache lowers the durable friends cap to 1 through the service (the
+// admin-edit path), checks a durable inviter is refused a second friend game with 409, and that
+// accepting an incoming invitation is still exempt from the cap.
+func TestDurableFriendsCapAndConfigCache(t *testing.T) {
+	ctx := context.Background()
+	gl := newGameLimits(t)
+	restoreDefaultLimits(t, gl)
+	cfg := gl.Get()
+	cfg.Durable.Friends = 1
+	if err := gl.Update(ctx, cfg); err != nil {
+		t.Fatalf("update durable friends cap: %v", err)
+	}
+	games := newGameService()
+	games.SetGameLimits(gl)
+	inv := lobby.NewInvitationService(lobby.NewStore(testDB), games, account.NewStore(testDB), newSocialService())
+
 	inviter := provisionAccount(t)
-	invitation, err := inv.CreateInvitation(ctx, inviter, []uuid.UUID{invitee}, englishInvite())
-	if err != nil {
-		t.Fatalf("create invitation: %v", err)
+	d2, d3 := provisionAccount(t), provisionAccount(t)
+
+	// The inviter's first friend game reaches the (lowered) cap of 1.
+	startFriendGameID(t, inv, inviter, d2)
+	if at, err := games.AtGameLimit(ctx, inviter, gamelimits.KindFriends); err != nil || !at {
+		t.Fatalf("inviter friends at-limit = (%v, %v), want (true, nil)", at, err)
 	}
-	if _, err := inv.RespondInvitation(ctx, invitation.ID, invitee, true); err != nil {
-		t.Fatalf("accept invitation: %v", err)
+	// A second invitation is refused: the cache reflects the edit.
+	if _, err := inv.CreateInvitation(ctx, inviter, []uuid.UUID{d3}, englishInvite()); !errors.Is(err, game.ErrGameLimitReached) {
+		t.Fatalf("second invitation err = %v, want ErrGameLimitReached", err)
 	}
+	// Accept stays exempt: someone else invites the capped inviter, who accepts and the game starts.
+	startFriendGameID(t, inv, d3, inviter)
 }
 
 // gamesListAtLimit fetches /api/v1/user/games and returns its at_game_limit flag.

backend/internal/inttest/game_test.go

@@ -424,13 +424,13 @@ func TestHintPolicy(t *testing.T) {
 		t.Fatalf("first hint: %v", err)
 	}
 	// The allowance is spent before the wallet: with an empty wallet, the state now reports no
-	// hints left and a zero wallet, so the per-game allowance (HintsRemaining-WalletBalance) is 0.
+	// per-game allowance left (HintsRemaining is the allowance alone; the wallet lives on the profile).
 	st, err := svc.GameState(ctx, g.ID, seats[0])
 	if err != nil {
 		t.Fatalf("state: %v", err)
 	}
-	if st.HintsRemaining != 0 || st.WalletBalance != 0 {
-		t.Errorf("after allowance hint: hints=%d wallet=%d, want 0/0", st.HintsRemaining, st.WalletBalance)
+	if st.HintsRemaining != 0 {
+		t.Errorf("after allowance hint: hints=%d, want 0", st.HintsRemaining)
 	}
 	if _, err := svc.Hint(ctx, g.ID, seats[0]); !errors.Is(err, game.ErrNoHintsLeft) {
 		t.Fatalf("second hint = %v, want ErrNoHintsLeft", err)
@@ -444,9 +444,10 @@ func TestHintPolicy(t *testing.T) {
 	if err != nil {
 		t.Fatalf("wallet hint: %v", err)
 	}
-	// The allowance stays exhausted; the wallet dropped 2->1, and WalletBalance carries it alone.
-	if res.HintsRemaining != 1 || res.WalletBalance != 1 {
-		t.Errorf("wallet hint: hints=%d wallet=%d, want 1/1", res.HintsRemaining, res.WalletBalance)
+	// The allowance stays exhausted (HintsRemaining is the allowance alone, so 0); the wallet dropped
+	// 2->1 and WalletBalance carries it (the client adopts it into the profile).
+	if res.HintsRemaining != 0 || res.WalletBalance != 1 {
+		t.Errorf("wallet hint: hints=%d wallet=%d, want 0/1", res.HintsRemaining, res.WalletBalance)
 	}
 	// game_players.hints_used counts BOTH hints (1 allowance + 1 wallet) — the per-game total
 	// that feeds the player's lifetime hint statistics, not just the allowance.

backend/internal/inttest/payment_availability_test.go

@@ -0,0 +1,83 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/payments"
+)
+
+// TestPaymentAvailabilityKillSwitch exercises the per-rail kill switch + the per-account override
+// end-to-end against Postgres: fail-open, a disabled rail with a localized message, per-rail
+// granularity, and the allow/deny/default overrides.
+func TestPaymentAvailabilityKillSwitch(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+
+	// Fail-open: an untouched rail is enabled.
+	if ok, _, err := svc.CanPurchase(ctx, acc, payments.RailDirectWeb, "en"); err != nil || !ok {
+		t.Fatalf("fail-open: CanPurchase = %v/%v, want true", ok, err)
+	}
+
+	// Disable the web rail with a per-language message → blocked with that message, localized.
+	if err := svc.SetRailStatus(ctx, payments.RailDirectWeb, payments.RailAvailability{MessageRU: "Чиним", MessageEN: "Fixing"}); err != nil {
+		t.Fatalf("set rail status: %v", err)
+	}
+	if ok, reason, err := svc.CanPurchase(ctx, acc, payments.RailDirectWeb, "ru"); err != nil || ok || reason != "Чиним" {
+		t.Fatalf("disabled rail (ru): CanPurchase = %v/%q/%v, want false/Чиним", ok, reason, err)
+	}
+	if ok, reason, _ := svc.CanPurchase(ctx, acc, payments.RailDirectWeb, "en"); ok || reason != "Fixing" {
+		t.Fatalf("disabled rail (en): = %v/%q, want false/Fixing", ok, reason)
+	}
+	// Per-rail granularity: another rail stays enabled.
+	if ok, _, _ := svc.CanPurchase(ctx, acc, payments.RailDirectAndroid, "en"); !ok {
+		t.Fatalf("android rail should stay enabled")
+	}
+
+	// A per-account "allow" override bypasses the disabled rail.
+	if err := svc.SetPurchaseOverride(ctx, acc, payments.OverrideAllow); err != nil {
+		t.Fatalf("set override allow: %v", err)
+	}
+	if ok, _, _ := svc.CanPurchase(ctx, acc, payments.RailDirectWeb, "en"); !ok {
+		t.Fatalf("allow override should bypass the disabled rail")
+	}
+	if ov, err := svc.PurchaseOverrideFor(ctx, acc); err != nil || ov != payments.OverrideAllow {
+		t.Fatalf("PurchaseOverrideFor = %v/%v, want allow", ov, err)
+	}
+
+	// A "deny" override blocks even an enabled rail.
+	if err := svc.SetPurchaseOverride(ctx, acc, payments.OverrideDeny); err != nil {
+		t.Fatalf("set override deny: %v", err)
+	}
+	if ok, reason, _ := svc.CanPurchase(ctx, acc, payments.RailDirectAndroid, "en"); ok || reason == "" {
+		t.Fatalf("deny override should block the enabled android rail with a reason, got %v/%q", ok, reason)
+	}
+
+	// Clearing the override (default) restores rail-driven behaviour.
+	if err := svc.SetPurchaseOverride(ctx, acc, payments.OverrideDefault); err != nil {
+		t.Fatalf("clear override: %v", err)
+	}
+	if ov, _ := svc.PurchaseOverrideFor(ctx, acc); ov != payments.OverrideDefault {
+		t.Fatalf("after clear, override = %v, want default", ov)
+	}
+	if ok, _, _ := svc.CanPurchase(ctx, acc, payments.RailDirectAndroid, "en"); !ok {
+		t.Fatalf("after clearing override, android rail should be enabled again")
+	}
+
+	// RailStatuses reflects the stored web-rail change and fills the rest fail-open.
+	all, err := svc.RailStatuses(ctx)
+	if err != nil {
+		t.Fatalf("rail statuses: %v", err)
+	}
+	if all[payments.RailDirectWeb].Enabled {
+		t.Fatalf("web rail should read disabled")
+	}
+	if !all[payments.RailVK].Enabled {
+		t.Fatalf("untouched vk rail should read enabled")
+	}
+}

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/inttest/payments_intake_test.go

@@ -0,0 +1,563 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"testing"
+
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/payments"
+)
+
+// orderStatus reads an order's status.
+func orderStatus(t *testing.T, orderID uuid.UUID) string {
+	t.Helper()
+	var status string
+	if err := testDB.QueryRowContext(context.Background(),
+		`SELECT status FROM payments.orders WHERE order_id=$1`, orderID).Scan(&status); err != nil {
+		t.Fatalf("read order status: %v", err)
+	}
+	return status
+}
+
+// readRisk reads an account's payment-risk row (abuse flag + accumulated loss), or (false, 0) when
+// none exists.
+func readRisk(t *testing.T, acc uuid.UUID) (abuse bool, loss int64) {
+	t.Helper()
+	err := testDB.QueryRowContext(context.Background(),
+		`SELECT abuse, loss_chips FROM payments.account_risk WHERE account_id=$1`, acc).Scan(&abuse, &loss)
+	if errors.Is(err, sql.ErrNoRows) {
+		return false, 0
+	}
+	if err != nil {
+		t.Fatalf("read risk: %v", err)
+	}
+	return abuse, loss
+}
+
+// TestPaymentsOrderFundCreditsOnce verifies the intake path over Postgres: creating an order then
+// funding it credits the funded segment exactly once, and a replayed callback (the same order)
+// credits nothing more — the ledger idempotency index holds.
+func TestPaymentsOrderFundCreditsOnce(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	prod := seedPackProduct(t, 100, methodPrice{method: "direct", currency: "RUB", amount: 14900}) // 149.00 RUB funds 100 chips
+
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	if res.Amount.Minor() != 14900 || res.Amount.Currency() != payments.CurrencyRUB {
+		t.Fatalf("order amount = %s, want 149.00 RUB", res.Amount)
+	}
+	if orderStatus(t, res.OrderID) != "pending" {
+		t.Errorf("new order status = %s, want pending", orderStatus(t, res.OrderID))
+	}
+
+	paid, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	out, err := svc.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), paid)
+	if err != nil {
+		t.Fatalf("fund: %v", err)
+	}
+	if out.AlreadyCredited || out.Chips != 100 || out.Source != payments.SourceDirect {
+		t.Fatalf("fund outcome = %+v, want 100 chips to direct, not already-credited", out)
+	}
+	if got := readBalance(t, acc, "direct"); got != 100 {
+		t.Errorf("balance after fund = %d, want 100", got)
+	}
+	if ledgerRows(t, acc, "fund") != 1 {
+		t.Errorf("fund ledger rows = %d, want 1", ledgerRows(t, acc, "fund"))
+	}
+	if orderStatus(t, res.OrderID) != "paid" {
+		t.Errorf("order status after fund = %s, want paid", orderStatus(t, res.OrderID))
+	}
+
+	// A replayed callback for the same order is rejected by the unique index: no second credit.
+	out2, err := svc.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), paid)
+	if err != nil {
+		t.Fatalf("duplicate fund: %v", err)
+	}
+	if !out2.AlreadyCredited {
+		t.Error("duplicate callback not flagged AlreadyCredited")
+	}
+	if got := readBalance(t, acc, "direct"); got != 100 {
+		t.Errorf("balance after duplicate = %d, want 100 (credited once)", got)
+	}
+	if ledgerRows(t, acc, "fund") != 1 {
+		t.Error("duplicate callback wrote a second fund ledger row")
+	}
+}
+
+// TestPaymentsVKOrderFundCredits exercises the VK Votes rail over Postgres: a VK order prices the
+// pack in votes; the get_item lookup returns its title and vote price; a chargeable
+// order_status_change credits the vk segment exactly once (idempotent on VK's own order id).
+func TestPaymentsVKOrderFundCredits(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	prod := seedPackProduct(t, 200, methodPrice{method: "vk", currency: "VOTE", amount: 30})
+
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("vk", "web"), []payments.Source{payments.SourceVK}, prod, "vk")
+	if err != nil {
+		t.Fatalf("create vk order: %v", err)
+	}
+	if res.Amount.Currency() != payments.CurrencyVote || res.Amount.Minor() != 30 {
+		t.Fatalf("vk order amount = %s, want 30 VOTE", res.Amount)
+	}
+
+	// get_item phase: title + vote price.
+	title, amount, err := svc.OrderItem(ctx, res.OrderID)
+	if err != nil {
+		t.Fatalf("order item: %v", err)
+	}
+	if title == "" || amount.Minor() != 30 || amount.Currency() != payments.CurrencyVote {
+		t.Errorf("order item = %q / %s, want a title + 30 VOTE", title, amount)
+	}
+
+	// order_status_change phase: VK's own order id is the idempotency key.
+	paid, _ := payments.MoneyFromMinor(30, payments.CurrencyVote)
+	out, err := svc.Fund(ctx, res.OrderID, "vk", "vk-order-777", paid)
+	if err != nil {
+		t.Fatalf("vk fund: %v", err)
+	}
+	if out.AlreadyCredited || out.Chips != 200 || out.Source != payments.SourceVK {
+		t.Fatalf("vk fund outcome = %+v, want 200 chips credited to vk", out)
+	}
+	if got := readBalance(t, acc, "vk"); got != 200 {
+		t.Errorf("vk balance after fund = %d, want 200", got)
+	}
+
+	// A duplicate VK callback (same VK order id) credits nothing more.
+	out2, err := svc.Fund(ctx, res.OrderID, "vk", "vk-order-777", paid)
+	if err != nil {
+		t.Fatalf("duplicate vk fund: %v", err)
+	}
+	if !out2.AlreadyCredited {
+		t.Error("duplicate VK callback not flagged AlreadyCredited")
+	}
+	if got := readBalance(t, acc, "vk"); got != 200 {
+		t.Errorf("vk balance after duplicate = %d, want 200 (credited once)", got)
+	}
+}
+
+// TestPaymentsTelegramStarsRail exercises the Telegram Stars rail over Postgres: an order prices the
+// pack in whole stars (XTR); a pre_checkout on the pending order is approved; the forwarded payment
+// credits the telegram segment exactly once (idempotent on the Telegram charge id); and a
+// pre_checkout after the order is paid is declined (a reusable invoice link paid twice).
+func TestPaymentsTelegramStarsRail(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	prod := seedPackProduct(t, 50, methodPrice{method: "telegram", currency: "XTR", amount: 40}) // 40 stars fund 50 chips
+
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("telegram", "android"), []payments.Source{payments.SourceTelegram}, prod, "telegram")
+	if err != nil {
+		t.Fatalf("create telegram order: %v", err)
+	}
+	if res.Amount.Currency() != payments.CurrencyStar || res.Amount.Minor() != 40 {
+		t.Fatalf("telegram order amount = %s, want 40 XTR", res.Amount)
+	}
+
+	// pre_checkout on the pending order: approved, and it reports the account for reason localisation.
+	starAmt, _ := payments.MoneyFromMinor(40, payments.CurrencyStar)
+	pc, err := svc.ValidatePreCheckout(ctx, res.OrderID, starAmt)
+	if err != nil {
+		t.Fatalf("pre_checkout: %v", err)
+	}
+	if !pc.OK || pc.AccountID != acc {
+		t.Fatalf("pre_checkout = %+v, want approved for account %s", pc, acc)
+	}
+
+	// The forwarded successful_payment credits once, idempotent on the Telegram charge id.
+	out, err := svc.Fund(ctx, res.OrderID, "telegram", "tg-charge-1", starAmt)
+	if err != nil {
+		t.Fatalf("telegram fund: %v", err)
+	}
+	if out.AlreadyCredited || out.Chips != 50 || out.Source != payments.SourceTelegram {
+		t.Fatalf("telegram fund outcome = %+v, want 50 chips credited to telegram", out)
+	}
+	if got := readBalance(t, acc, "telegram"); got != 50 {
+		t.Errorf("telegram balance after fund = %d, want 50", got)
+	}
+
+	// A retried forward (same charge id, e.g. a lost ack) credits nothing more.
+	out2, err := svc.Fund(ctx, res.OrderID, "telegram", "tg-charge-1", starAmt)
+	if err != nil {
+		t.Fatalf("duplicate telegram fund: %v", err)
+	}
+	if !out2.AlreadyCredited {
+		t.Error("retried forward not flagged AlreadyCredited")
+	}
+	if got := readBalance(t, acc, "telegram"); got != 50 {
+		t.Errorf("telegram balance after retry = %d, want 50 (credited once)", got)
+	}
+
+	// pre_checkout after the order is paid: declined (the reusable-link double-pay guard).
+	pc2, err := svc.ValidatePreCheckout(ctx, res.OrderID, starAmt)
+	if err != nil {
+		t.Fatalf("pre_checkout after paid: %v", err)
+	}
+	if pc2.OK || pc2.Reason != payments.PreCheckoutAlreadyPaid {
+		t.Errorf("pre_checkout after paid = %+v, want a decline with already_paid", pc2)
+	}
+}
+
+// TestPaymentsTelegramPreCheckoutDeclines covers the pre_checkout decline reasons: an unknown order
+// and an amount that no longer matches.
+func TestPaymentsTelegramPreCheckoutDeclines(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	starAmt, _ := payments.MoneyFromMinor(40, payments.CurrencyStar)
+
+	// An unknown order id declines as gone, with no account to localise against.
+	pc, err := svc.ValidatePreCheckout(ctx, uuid.New(), starAmt)
+	if err != nil {
+		t.Fatalf("pre_checkout unknown: %v", err)
+	}
+	if pc.OK || pc.Reason != payments.PreCheckoutGone || pc.AccountID != (uuid.UUID{}) {
+		t.Errorf("pre_checkout unknown = %+v, want a gone decline with no account", pc)
+	}
+
+	// A pending order validated at the wrong amount declines as price-changed.
+	acc := uuid.New()
+	prod := seedPackProduct(t, 100, methodPrice{method: "telegram", currency: "XTR", amount: 80})
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("telegram", "android"), []payments.Source{payments.SourceTelegram}, prod, "telegram")
+	if err != nil {
+		t.Fatalf("create telegram order: %v", err)
+	}
+	wrong, _ := payments.MoneyFromMinor(40, payments.CurrencyStar)
+	pc2, err := svc.ValidatePreCheckout(ctx, res.OrderID, wrong)
+	if err != nil {
+		t.Fatalf("pre_checkout mismatch: %v", err)
+	}
+	if pc2.OK || pc2.Reason != payments.PreCheckoutPriceChanged {
+		t.Errorf("pre_checkout mismatch = %+v, want a price_changed decline", pc2)
+	}
+}
+
+// setRewardConfig sets the rewarded payout and caps on the shared config row, restoring the defaults
+// after the test (the row is a singleton shared across the sequential suite).
+func setRewardConfig(t *testing.T, payout, dailyCap, hourlyCap int) {
+	t.Helper()
+	if _, err := testDB.ExecContext(context.Background(),
+		`UPDATE payments.config SET rewarded_payout_chips=$1, reward_daily_cap=$2, reward_hourly_cap=$3`,
+		payout, dailyCap, hourlyCap); err != nil {
+		t.Fatalf("set reward config: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = testDB.ExecContext(context.Background(),
+			`UPDATE payments.config SET rewarded_payout_chips=0, reward_daily_cap=50, reward_hourly_cap=10`)
+	})
+}
+
+// TestPaymentsRewardCredit exercises the rewarded-video credit: a watched view credits the VK segment
+// the configured payout, a retried view (same nonce) credits once, and the hourly cap blocks the
+// third distinct view.
+func TestPaymentsRewardCredit(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	setRewardConfig(t, 5, 5, 2) // 5 chips/view, daily 5, hourly 2
+	vk := payments.NewContext("vk", "web")
+	present := []payments.Source{payments.SourceVK}
+
+	out, err := svc.CreditReward(ctx, acc, vk, present, "n1")
+	if err != nil {
+		t.Fatalf("credit: %v", err)
+	}
+	if out.Chips != 5 || out.Capped {
+		t.Fatalf("reward outcome = %+v, want 5 chips, not capped", out)
+	}
+	if got := readBalance(t, acc, "vk"); got != 5 {
+		t.Errorf("vk balance = %d, want 5", got)
+	}
+
+	// A retried view (same nonce) credits nothing more.
+	out2, err := svc.CreditReward(ctx, acc, vk, present, "n1")
+	if err != nil {
+		t.Fatalf("retry: %v", err)
+	}
+	if !out2.AlreadyCredited {
+		t.Error("retried view not flagged AlreadyCredited")
+	}
+	if got := readBalance(t, acc, "vk"); got != 5 {
+		t.Errorf("vk balance after retry = %d, want 5 (credited once)", got)
+	}
+
+	// A second distinct view credits again (2 total).
+	if _, err := svc.CreditReward(ctx, acc, vk, present, "n2"); err != nil {
+		t.Fatalf("credit 2: %v", err)
+	}
+	if got := readBalance(t, acc, "vk"); got != 10 {
+		t.Errorf("vk balance = %d, want 10", got)
+	}
+
+	// The third distinct view hits the hourly cap (2) — capped, no credit.
+	out3, err := svc.CreditReward(ctx, acc, vk, present, "n3")
+	if err != nil {
+		t.Fatalf("credit 3: %v", err)
+	}
+	if !out3.Capped {
+		t.Error("third view not capped (hourly cap 2)")
+	}
+	if got := readBalance(t, acc, "vk"); got != 10 {
+		t.Errorf("vk balance after cap = %d, want 10 (capped view credited nothing)", got)
+	}
+}
+
+// TestPaymentsRewardDisabledAndContext verifies rewarded is inert when unconfigured (0 payout) and
+// refused outside a VK context (rewarded is VK-only, D28).
+func TestPaymentsRewardDisabledAndContext(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	setRewardConfig(t, 0, 50, 10) // payout 0 = disabled
+
+	vk := payments.NewContext("vk", "web")
+	out, err := svc.CreditReward(ctx, acc, vk, []payments.Source{payments.SourceVK}, "d1")
+	if err != nil {
+		t.Fatalf("credit (disabled): %v", err)
+	}
+	if out.Chips != 0 || out.Capped || out.AlreadyCredited {
+		t.Fatalf("disabled reward outcome = %+v, want 0 chips, not capped", out)
+	}
+
+	// A direct (non-VK) context is refused — rewarded is VK-only.
+	direct := payments.NewContext("direct", "web")
+	if _, err := svc.CreditReward(ctx, acc, direct, []payments.Source{payments.SourceDirect}, "d2"); !errors.Is(err, payments.ErrUntrusted) {
+		t.Fatalf("direct-context reward = %v, want ErrUntrusted", err)
+	}
+}
+
+// TestPaymentsFundAmountMismatch verifies a callback whose paid amount does not match the order is
+// refused and credits nothing (§9: verify the amount after matching by order id).
+func TestPaymentsFundAmountMismatch(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	prod := seedPackProduct(t, 100, methodPrice{method: "direct", currency: "RUB", amount: 14900})
+
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	underpaid, _ := payments.MoneyFromMinor(100, payments.CurrencyRUB)
+	if _, err := svc.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), underpaid); !errors.Is(err, payments.ErrAmountMismatch) {
+		t.Fatalf("fund = %v, want ErrAmountMismatch", err)
+	}
+	if got := readBalance(t, acc, "direct"); got != 0 {
+		t.Errorf("balance = %d, want 0 (nothing credited on mismatch)", got)
+	}
+	if ledgerRows(t, acc, "fund") != 0 {
+		t.Error("fund ledger row written on an amount mismatch")
+	}
+}
+
+// TestPaymentsEventDispatchDrain verifies the payment_events dispatcher queue: a recorded event is
+// returned as undispatched until marked, then drops out (so the dispatcher delivers it once).
+func TestPaymentsEventDispatchDrain(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	if err := svc.RecordPaymentEvent(ctx, acc, nil, "succeeded", []byte(`{"chips":10,"source":"direct"}`)); err != nil {
+		t.Fatalf("record event: %v", err)
+	}
+
+	// testDB is shared, so filter the queue to our account.
+	find := func() *payments.PaymentEvent {
+		evs, err := svc.UndispatchedEvents(ctx, 100)
+		if err != nil {
+			t.Fatalf("undispatched: %v", err)
+		}
+		for i := range evs {
+			if evs[i].AccountID == acc {
+				return &evs[i]
+			}
+		}
+		return nil
+	}
+
+	mine := find()
+	if mine == nil {
+		t.Fatal("recorded event not in the undispatched queue")
+	}
+	if mine.Type != "succeeded" {
+		t.Errorf("event type = %s, want succeeded", mine.Type)
+	}
+	if err := svc.MarkEventDispatched(ctx, mine.EventID); err != nil {
+		t.Fatalf("mark dispatched: %v", err)
+	}
+	if find() != nil {
+		t.Error("event still undispatched after MarkEventDispatched")
+	}
+}
+
+// TestPaymentsExpiredOrderStillCredits verifies an expired pending order is still honoured by a
+// later valid callback (§9/D23: expiry is cosmetic, the money is real).
+func TestPaymentsExpiredOrderStillCredits(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	prod := seedPackProduct(t, 100, methodPrice{method: "direct", currency: "RUB", amount: 14900})
+
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	// Age the order well past the configured TTL, then sweep it to expired.
+	if _, err := testDB.ExecContext(ctx,
+		`UPDATE payments.orders SET created_at = now() - interval '1 day' WHERE order_id=$1`, res.OrderID); err != nil {
+		t.Fatalf("age order: %v", err)
+	}
+	if n, err := svc.ExpireOrders(ctx); err != nil || n < 1 {
+		t.Fatalf("expire orders = %d (err %v), want at least 1", n, err)
+	}
+	if orderStatus(t, res.OrderID) != "expired" {
+		t.Fatalf("order status = %s, want expired before the late callback", orderStatus(t, res.OrderID))
+	}
+
+	paid, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	out, err := svc.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), paid)
+	if err != nil {
+		t.Fatalf("fund after expiry: %v", err)
+	}
+	if out.AlreadyCredited || out.Chips != 100 {
+		t.Fatalf("fund outcome = %+v, want a fresh 100-chip credit", out)
+	}
+	if got := readBalance(t, acc, "direct"); got != 100 {
+		t.Errorf("balance = %d, want 100 (expired order honoured)", got)
+	}
+	if orderStatus(t, res.OrderID) != "paid" {
+		t.Errorf("order status = %s, want paid after the honoured callback", orderStatus(t, res.OrderID))
+	}
+}
+
+// fundedOrder creates and funds an order for chips in the direct rail, returning its id and account.
+func fundedOrder(t *testing.T, svc *payments.Service, chips int, priceMinor int64) (uuid.UUID, uuid.UUID) {
+	t.Helper()
+	ctx := context.Background()
+	acc := uuid.New()
+	prod := seedPackProduct(t, chips, methodPrice{method: "direct", currency: "RUB", amount: priceMinor})
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	paid, _ := payments.MoneyFromMinor(priceMinor, payments.CurrencyRUB)
+	if _, err := svc.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), paid); err != nil {
+		t.Fatalf("fund: %v", err)
+	}
+	return res.OrderID, acc
+}
+
+// TestPaymentsRefundFull reverses a fully-unspent order: all chips are clawed back, no loss/abuse.
+func TestPaymentsRefundFull(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	orderID, acc := fundedOrder(t, svc, 100, 14900)
+
+	refunded, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	out, err := svc.Refund(ctx, orderID, "robokassa", "rk-refund-1", refunded)
+	if err != nil {
+		t.Fatalf("refund: %v", err)
+	}
+	if out.AlreadyRefunded || out.Revoked != 100 || out.Loss != 0 || out.Source != payments.SourceDirect {
+		t.Fatalf("refund outcome = %+v, want 100 revoked, 0 loss", out)
+	}
+	if got := readBalance(t, acc, "direct"); got != 0 {
+		t.Errorf("balance after refund = %d, want 0", got)
+	}
+	if ledgerRows(t, acc, "refund") != 1 {
+		t.Errorf("refund ledger rows = %d, want 1", ledgerRows(t, acc, "refund"))
+	}
+	if abuse, loss := readRisk(t, acc); abuse || loss != 0 {
+		t.Errorf("risk = (%v, %d), want (false, 0) — nothing was spent", abuse, loss)
+	}
+	// The order stays 'paid' — the refund lives in the ledger, not in the order status.
+	if orderStatus(t, orderID) != "paid" {
+		t.Errorf("order status = %s, want paid (refund is ledger-only)", orderStatus(t, orderID))
+	}
+}
+
+// TestPaymentsRefundAfterSpend reverses an order whose chips were partly spent: the reversal floors
+// at 0 (never negative), and the unrecoverable remainder is recorded as a loss + abuse flag.
+func TestPaymentsRefundAfterSpend(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	orderID, acc := fundedOrder(t, svc, 100, 14900)
+
+	// Simulate 70 chips already spent, leaving 30 in the funded segment.
+	if _, err := testDB.ExecContext(ctx,
+		`UPDATE payments.balances SET chips = 30 WHERE account_id = $1 AND source = 'direct'`, acc); err != nil {
+		t.Fatalf("simulate spend: %v", err)
+	}
+
+	refunded, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	out, err := svc.Refund(ctx, orderID, "robokassa", "rk-refund-2", refunded)
+	if err != nil {
+		t.Fatalf("refund: %v", err)
+	}
+	if out.Revoked != 30 || out.Loss != 70 {
+		t.Fatalf("refund outcome = %+v, want 30 revoked / 70 loss", out)
+	}
+	if got := readBalance(t, acc, "direct"); got != 0 {
+		t.Errorf("balance after refund = %d, want 0 (floored, never negative)", got)
+	}
+	if abuse, loss := readRisk(t, acc); !abuse || loss != 70 {
+		t.Errorf("risk = (%v, %d), want (true, 70)", abuse, loss)
+	}
+}
+
+// TestPaymentsRefundIdempotent verifies a replayed refund (same provider refund id) reverses nothing
+// more — the ledger idempotency index holds.
+func TestPaymentsRefundIdempotent(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	orderID, acc := fundedOrder(t, svc, 100, 14900)
+	refunded, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+
+	if _, err := svc.Refund(ctx, orderID, "robokassa", "rk-refund-dup", refunded); err != nil {
+		t.Fatalf("first refund: %v", err)
+	}
+	// Re-credit the segment to prove the duplicate does not revoke again.
+	if _, err := testDB.ExecContext(ctx,
+		`UPDATE payments.balances SET chips = 100 WHERE account_id = $1 AND source = 'direct'`, acc); err != nil {
+		t.Fatalf("re-credit: %v", err)
+	}
+	out2, err := svc.Refund(ctx, orderID, "robokassa", "rk-refund-dup", refunded)
+	if err != nil {
+		t.Fatalf("duplicate refund: %v", err)
+	}
+	if !out2.AlreadyRefunded {
+		t.Error("duplicate refund not flagged AlreadyRefunded")
+	}
+	if got := readBalance(t, acc, "direct"); got != 100 {
+		t.Errorf("balance after duplicate refund = %d, want 100 (not revoked twice)", got)
+	}
+	if ledgerRows(t, acc, "refund") != 1 {
+		t.Errorf("refund ledger rows = %d, want 1 (duplicate wrote none)", ledgerRows(t, acc, "refund"))
+	}
+}
+
+// TestPaymentsRefundUnpaidOrder refuses to refund an order that was never funded.
+func TestPaymentsRefundUnpaidOrder(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	prod := seedPackProduct(t, 100, methodPrice{method: "direct", currency: "RUB", amount: 14900})
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	refunded, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	if _, err := svc.Refund(ctx, res.OrderID, "robokassa", "rk-refund-x", refunded); !errors.Is(err, payments.ErrOrderNotPaid) {
+		t.Fatalf("refund of a pending order = %v, want ErrOrderNotPaid", err)
+	}
+	if abuse, loss := readRisk(t, acc); abuse || loss != 0 {
+		t.Errorf("risk = (%v, %d), want (false, 0) — no reversal on an unpaid order", abuse, loss)
+	}
+}

backend/internal/inttest/payments_statement_test.go

@@ -0,0 +1,101 @@
+//go:build integration
+
+package inttest
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/payments"
+)
+
+// TestAccountStatement checks the admin financial statement: a funded pack shows as a chip segment
+// + a fund ledger row, an admin grant as a benefit + an admin_grant row, the ledger is newest-first,
+// and a clean account carries no refund risk.
+func TestAccountStatement(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+
+	// A funded pack: 100 chips to the direct segment + a fund ledger row.
+	prod := seedPackProduct(t, 100, methodPrice{method: "direct", currency: "RUB", amount: 14900})
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	paid, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	if _, err := svc.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), paid); err != nil {
+		t.Fatalf("fund: %v", err)
+	}
+	// An admin grant: 5 hints to the direct origin + an admin_grant ledger row.
+	if err := svc.Grant(ctx, acc, payments.SourceDirect, 5, 0, false); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+
+	stmt, err := svc.AccountStatement(ctx, acc)
+	if err != nil {
+		t.Fatalf("statement: %v", err)
+	}
+
+	if len(stmt.Segments) != 1 || stmt.Segments[0].Source != payments.SourceDirect || stmt.Segments[0].Chips != 100 {
+		t.Fatalf("segments = %+v, want 100 chips on direct", stmt.Segments)
+	}
+	if len(stmt.Benefits) != 1 || stmt.Benefits[0].Origin != payments.SourceDirect || stmt.Benefits[0].Hints != 5 {
+		t.Fatalf("benefits = %+v, want 5 hints on direct", stmt.Benefits)
+	}
+	if len(stmt.Ledger) != 2 {
+		t.Fatalf("ledger rows = %d, want 2 (fund + admin_grant)", len(stmt.Ledger))
+	}
+	// Newest-first ordering (the grant is the later write).
+	if stmt.Ledger[0].CreatedAt.Before(stmt.Ledger[1].CreatedAt) {
+		t.Error("ledger is not newest-first")
+	}
+	kinds := map[string]int{}
+	for _, e := range stmt.Ledger {
+		kinds[e.Kind]++
+		if e.Kind == "fund" && e.ChipsDelta != 100 {
+			t.Errorf("fund chips delta = %d, want 100", e.ChipsDelta)
+		}
+	}
+	if kinds["fund"] != 1 || kinds["admin_grant"] != 1 {
+		t.Fatalf("ledger kinds = %v, want one fund + one admin_grant", kinds)
+	}
+	if stmt.Risk.Present {
+		t.Errorf("risk = %+v, want none for a clean account", stmt.Risk)
+	}
+}
+
+// TestConsoleFinancePanel checks the user card renders the finance panel: a funded pack + an admin
+// grant surface as the segment balance, the benefit and the ledger rows.
+func TestConsoleFinancePanel(t *testing.T) {
+	ctx := context.Background()
+	srv, _, pay := bannerServer(t)
+	id := provisionAccount(t)
+
+	prod := seedPackProduct(t, 100, methodPrice{method: "direct", currency: "RUB", amount: 14900})
+	res, err := pay.CreateOrder(ctx, id, payments.NewContext("direct", "web"), []payments.Source{payments.SourceDirect}, prod, "robokassa")
+	if err != nil {
+		t.Fatalf("create order: %v", err)
+	}
+	paid, _ := payments.MoneyFromMinor(14900, payments.CurrencyRUB)
+	if _, err := pay.Fund(ctx, res.OrderID, "robokassa", res.OrderID.String(), paid); err != nil {
+		t.Fatalf("fund: %v", err)
+	}
+	if err := pay.Grant(ctx, id, payments.SourceDirect, 5, 0, false); err != nil {
+		t.Fatalf("grant: %v", err)
+	}
+
+	code, body := consoleDo(srv.Handler(), http.MethodGet, "http://admin.test/_gm/users/"+id.String(), "", "")
+	if code != http.StatusOK {
+		t.Fatalf("user card = %d, want 200", code)
+	}
+	for _, want := range []string{"Finance", "Chips (direct)", "Benefits (direct)", "5 hints", "admin_grant", "fund"} {
+		if !strings.Contains(body, want) {
+			t.Errorf("finance panel missing %q", want)
+		}
+	}
+}

backend/internal/lobby/invitations.go

@@ -15,6 +15,7 @@ import (
 	"scrabble/backend/internal/account"
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/game"
+	"scrabble/backend/internal/gamelimits"
 	"scrabble/backend/internal/notify"
 	"scrabble/backend/internal/postgres/jet/backend/model"
 	"scrabble/backend/internal/postgres/jet/backend/table"
@@ -218,6 +219,20 @@ func (svc *InvitationService) CreateInvitation(ctx context.Context, inviterID uu
 	if !slices.Contains(game.AllowedTurnTimeouts, settings.TurnTimeout) {
 		return Invitation{}, fmt.Errorf("%w: turn timeout %s not allowed", ErrInvalidInvitation, settings.TurnTimeout)
 	}
+	// A guest cannot invite: friend games are a durable-account feature. The UI hides the flow;
+	// this is the server source of truth.
+	if acc, err := svc.accounts.GetByID(ctx, inviterID); err != nil {
+		return Invitation{}, err
+	} else if acc.IsGuest {
+		return Invitation{}, ErrGuestForbidden
+	}
+	// A durable inviter is still capped: refuse a new friend game once the per-tier friends limit is
+	// reached. The guest branch above short-circuits before here, so this is the durable cap.
+	if atLimit, err := svc.games.AtGameLimit(ctx, inviterID, gamelimits.KindFriends); err != nil {
+		return Invitation{}, err
+	} else if atLimit {
+		return Invitation{}, game.ErrGameLimitReached
+	}
 	seen := map[uuid.UUID]bool{inviterID: true}
 	// suppressed collects invitees who have blocked the inviter: the invitation is still
 	// created and persisted for them, but they are never notified and never see it (their
@@ -336,6 +351,7 @@ func (svc *InvitationService) startGame(ctx context.Context, invitationID uuid.U
 		HintsPerPlayer:       inv.Settings.HintsPerPlayer,
 		DropoutTiles:         inv.Settings.DropoutTiles,
 		MultipleWordsPerTurn: inv.Settings.MultipleWordsPerTurn,
+		Kind:                 gamelimits.KindFriends,
 	})
 	if err != nil {
 		return err

backend/internal/lobby/lobby.go

@@ -15,17 +15,22 @@ import (
 
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/game"
+	"scrabble/backend/internal/gamelimits"
 	"scrabble/backend/internal/notify"
 )
 
 // GameCreator is the slice of the game domain the lobby needs: starting a seated
-// game and reading a player's initial view of it. game.Service satisfies it.
+// game, reading a player's initial view of it, and testing a caller's active-game
+// cap. game.Service satisfies it.
 type GameCreator interface {
 	Create(ctx context.Context, params game.CreateParams) (game.Game, error)
 	// InitialState returns a seated player's full initial view of a started game, used
 	// to enrich the game_started event so the client renders the new game without a
 	// follow-up fetch.
 	InitialState(ctx context.Context, gameID, accountID uuid.UUID) (notify.PlayerState, error)
+	// AtGameLimit reports whether accountID has reached its tier's active-game cap for kind. The
+	// invitation path uses it to enforce the friends limit before opening one.
+	AtGameLimit(ctx context.Context, accountID uuid.UUID, kind gamelimits.Kind) (bool, error)
 }
 
 // RobotProvider supplies a robot account to substitute for a missing human in
@@ -62,6 +67,9 @@ var (
 	// ErrInvalidInvitation is returned for a malformed invitation (bad player
 	// count, duplicate or self invitee, or unacceptable settings).
 	ErrInvalidInvitation = errors.New("lobby: invalid invitation")
+	// ErrGuestForbidden is returned when a guest attempts a durable-only action (invite a
+	// friend); the friend flow is gated to durable accounts.
+	ErrGuestForbidden = errors.New("lobby: guests cannot invite")
 	// ErrInvitationBlocked is returned when a block stands between the inviter and
 	// an invitee.
 	ErrInvitationBlocked = errors.New("lobby: invitation blocked between accounts")

backend/internal/lobby/matchmaker.go

@@ -10,6 +10,7 @@ import (
 
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/game"
+	"scrabble/backend/internal/gamelimits"
 	"scrabble/backend/internal/notify"
 )
 
@@ -141,6 +142,7 @@ func (m *Matchmaker) StartVsAI(ctx context.Context, accountID uuid.UUID, variant
 	if rand.IntN(2) == 1 {
 		params.Seats = []uuid.UUID{robotID, accountID}
 	}
+	params.Kind = gamelimits.KindVsAI
 	g, err := m.games.Create(ctx, params)
 	if err != nil {
 		return EnqueueResult{}, err

backend/internal/notify/encode.go

@@ -37,6 +37,7 @@ func toWireGame(g GameSummary) wire.GameView {
 		TurnTimeoutSecs:      g.TurnTimeoutSecs,
 		MultipleWordsPerTurn: g.MultipleWordsPerTurn,
 		VsAI:                 g.VsAI,
+		Kind:                 g.Kind,
 		MoveCount:            g.MoveCount,
 		EndReason:            g.EndReason,
 		Seats:                seats,
@@ -83,7 +84,6 @@ func buildStateView(b *flatbuffers.Builder, s PlayerState) flatbuffers.UOffsetT
 		Rack:           s.Rack,
 		BagLen:         s.BagLen,
 		HintsRemaining: s.HintsRemaining,
-		WalletBalance:  s.WalletBalance,
 		Alphabet:       alphabet,
 	})
 }

backend/internal/notify/notify.go

@@ -73,6 +73,10 @@ const (
 	// (e.g. an email was confirmed via the one-tap deeplink opened in another browser),
 	// so it re-fetches profile.get. It carries no payload. In-app only.
 	NotifyProfile = "profile"
+	// NotifyPayment tells the client that the viewer's wallet changed from a payment-intake event
+	// (a credit or a refund), so it re-fetches the wallet in place. It carries no payload. In-app
+	// only; the payment_events dispatcher emits it after the crediting transaction commits.
+	NotifyPayment = "payment"
 	// NotifyUserBlocked confirms to the blocker that a per-user block took effect,
 	// carrying the blocked account, so every one of the blocker's sessions updates the
 	// in-game block/add-friend controls and the struck name in place. It is delivered

backend/internal/notify/notify_test.go

@@ -115,7 +115,7 @@ func TestGameOverPayloadRoundTrips(t *testing.T) {
 func TestOpponentMovedPayloadRoundTrips(t *testing.T) {
 	uid, gid := uuid.New(), uuid.New()
 	move := engine.MoveRecord{Player: 1, Action: engine.ActionPlay, Words: []string{"STOOL"}, Score: 24, Total: 130}
-	summary := notify.GameSummary{ID: gid.String(), MoveCount: 9, ToMove: 0, Seats: []notify.SeatStanding{{Seat: 1, Score: 130}}}
+	summary := notify.GameSummary{ID: gid.String(), MoveCount: 9, ToMove: 0, Kind: 2, Seats: []notify.SeatStanding{{Seat: 1, Score: 130}}}
 	in := notify.OpponentMoved(uid, gid, move, summary, 42)
 	if in.Kind != notify.KindOpponentMoved {
 		t.Fatalf("kind = %q", in.Kind)
@@ -132,7 +132,7 @@ func TestOpponentMovedPayloadRoundTrips(t *testing.T) {
 	if m == nil || m.Player() != 1 || string(m.Action()) != "play" || m.Total() != 130 {
 		t.Fatalf("move wrong: %+v", m)
 	}
-	if g := ev.Game(nil); g == nil || g.MoveCount() != 9 || g.ToMove() != 0 {
+	if g := ev.Game(nil); g == nil || g.MoveCount() != 9 || g.ToMove() != 0 || g.Kind() != 2 {
 		t.Fatalf("game summary wrong: %+v", ev.Game(nil))
 	}
 }

backend/internal/notify/payload.go

@@ -35,6 +35,9 @@ type GameSummary struct {
 	EndReason        string
 	Seats            []SeatStanding
 	LastActivityUnix int64
+	// Kind is the game's origin for the active-game limits (0 unknown, 1 vs_ai, 2 random, 3 friends);
+	// it rides live events so a lobby patch keeps the per-kind count correct.
+	Kind int
 }
 
 // AlphabetLetter is one variant alphabet entry (a display-only row) embedded in an
@@ -56,7 +59,6 @@ type PlayerState struct {
 	Rack           []int
 	BagLen         int
 	HintsRemaining int
-	WalletBalance  int
 	Alphabet       []AlphabetLetter
 }
 

backend/internal/payments/availability.go

@@ -0,0 +1,107 @@
+package payments
+
+import "slices"
+
+// PurchaseOverride is a per-account purchase override that forces purchases allowed or denied for
+// one account regardless of the operational rail switch, or is absent (OverrideDefault) when the
+// account follows the rail switch. The zero value is OverrideDefault, so a missing override row maps
+// to it. OverrideAllow bypasses ONLY the operational rail switch — never the security / compliance
+// gates (trusted platform, the D36 email anchor, the VK-iOS spend freeze, the min client version),
+// which CreateOrder enforces separately.
+type PurchaseOverride int
+
+const (
+	// OverrideDefault follows the rail switch (no override row for the account).
+	OverrideDefault PurchaseOverride = iota
+	// OverrideAllow always allows the purchase, bypassing only the operational rail switch.
+	OverrideAllow
+	// OverrideDeny always denies the purchase for the account.
+	OverrideDeny
+)
+
+// RailAvailability is a payment rail's operational availability: whether purchases are enabled and,
+// when disabled, the operator's explanation in each language, shown to the user on a purchase
+// attempt. A rail with no status row is treated as enabled (fail-open — see the store), so the
+// zero value is never used as a live "enabled" default.
+type RailAvailability struct {
+	Enabled   bool
+	MessageRU string
+	MessageEN string
+}
+
+// PurchaseGate decides whether an account may open a purchase order on a rail, from the per-account
+// override and the rail's operational availability. It is the operational layer only — the caller
+// still enforces the security gates. On a block it returns a reason localized to lang ("ru", else
+// English). Fail-open: OverrideDefault on an enabled rail allows.
+func PurchaseGate(override PurchaseOverride, rail RailAvailability, lang string) (ok bool, reason string) {
+	switch override {
+	case OverrideAllow:
+		return true, "" // bypasses only the ops switch; the security gates still apply upstream
+	case OverrideDeny:
+		return false, defaultUnavailable(lang) // a per-account block — a neutral reason
+	default: // OverrideDefault — follow the rail switch
+		if rail.Enabled {
+			return true, ""
+		}
+		return false, railMessage(rail, lang)
+	}
+}
+
+// railMessage returns the operator's rail-off message in lang, falling back to the other language
+// and then to the built-in default when the operator left both blank.
+func railMessage(rail RailAvailability, lang string) string {
+	if lang == "ru" {
+		if rail.MessageRU != "" {
+			return rail.MessageRU
+		}
+		if rail.MessageEN != "" {
+			return rail.MessageEN
+		}
+	} else {
+		if rail.MessageEN != "" {
+			return rail.MessageEN
+		}
+		if rail.MessageRU != "" {
+			return rail.MessageRU
+		}
+	}
+	return defaultUnavailable(lang)
+}
+
+// defaultUnavailable is the built-in localized "payments unavailable" reason used when the operator
+// set no custom message, and for a per-account deny.
+func defaultUnavailable(lang string) string {
+	if lang == "ru" {
+		return "Оплата временно недоступна. Попробуйте позже."
+	}
+	return "Payments are temporarily unavailable. Please try again later."
+}
+
+// Rail keys name the operational payment rails the kill switch and the per-account override key on.
+// The direct rail is split per channel (D42); vk and telegram are single-rail.
+const (
+	RailDirectWeb     = "direct:web"
+	RailDirectAndroid = "direct:android"
+	RailVK            = "vk"
+	RailTelegram      = "telegram"
+)
+
+// KnownRails is the fixed set of rail keys, for the admin editor and for validation.
+var KnownRails = []string{RailDirectWeb, RailDirectAndroid, RailVK, RailTelegram}
+
+// RailKey maps a payment context to its operational rail key: the direct rail by channel subtype
+// (android, else web), or the store rail's own name (vk / telegram).
+func RailKey(kind Source, subtype string) string {
+	if kind == SourceDirect {
+		if subtype == "android" {
+			return RailDirectAndroid
+		}
+		return RailDirectWeb
+	}
+	return string(kind)
+}
+
+// isKnownRail reports whether rail is one of the fixed rail keys.
+func isKnownRail(rail string) bool {
+	return slices.Contains(KnownRails, rail)
+}

backend/internal/payments/availability_test.go

@@ -0,0 +1,40 @@
+package payments
+
+import "testing"
+
+func TestPurchaseGate(t *testing.T) {
+	on := RailAvailability{Enabled: true}
+	offMsg := RailAvailability{Enabled: false, MessageRU: "Чиним", MessageEN: "Fixing"}
+	offNoMsg := RailAvailability{Enabled: false}
+
+	// OverrideDefault follows the rail switch.
+	if ok, _ := PurchaseGate(OverrideDefault, on, "en"); !ok {
+		t.Error("default + enabled rail should allow")
+	}
+	if ok, r := PurchaseGate(OverrideDefault, offMsg, "ru"); ok || r != "Чиним" {
+		t.Errorf("default + off rail (ru) = %v/%q, want false/Чиним", ok, r)
+	}
+	if ok, r := PurchaseGate(OverrideDefault, offMsg, "en"); ok || r != "Fixing" {
+		t.Errorf("default + off rail (en) = %v/%q, want false/Fixing", ok, r)
+	}
+
+	// Off rail with no custom message → the built-in default, localized (not the English default in ru).
+	if ok, r := PurchaseGate(OverrideDefault, offNoMsg, "ru"); ok || r != defaultUnavailable("ru") {
+		t.Errorf("default + off no-msg (ru) = %v/%q, want false + the ru default", ok, r)
+	}
+
+	// OverrideAllow bypasses the ops switch even when the rail is off.
+	if ok, r := PurchaseGate(OverrideAllow, offMsg, "en"); !ok || r != "" {
+		t.Errorf("allow + off rail = %v/%q, want true/empty (bypasses the ops switch)", ok, r)
+	}
+
+	// OverrideDeny blocks even when the rail is on, with a non-empty reason.
+	if ok, r := PurchaseGate(OverrideDeny, on, "en"); ok || r == "" {
+		t.Errorf("deny + on rail = %v/%q, want false + a reason", ok, r)
+	}
+
+	// The message falls back to the other language when only one is set.
+	if _, r := PurchaseGate(OverrideDefault, RailAvailability{MessageEN: "OnlyEN"}, "ru"); r != "OnlyEN" {
+		t.Errorf("off rail ru with only EN msg = %q, want OnlyEN (fallback)", r)
+	}
+}

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

@@ -0,0 +1,259 @@
+package payments
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math"
+	"slices"
+	"strings"
+
+	"github.com/google/uuid"
+)
+
+// AdminProduct is one catalog product for the admin editor: its full composition, every price, the
+// archived flag (Active), and whether it has ever been transacted — which forbids a hard delete
+// (orders / ledger rows reference it, and the ledger is append-only).
+type AdminProduct struct {
+	ID         uuid.UUID
+	Title      string
+	Active     bool
+	Atoms      []AtomLine
+	Prices     []PriceLine
+	Transacted bool
+}
+
+// AtomLine is one atom of a product: the atom type and its positive quantity.
+type AtomLine struct {
+	Atom     string
+	Quantity int
+}
+
+// PriceLine is one price of a product: the payment method ("" for a value's CHIP price, which is
+// stored with a NULL method), the currency, and the amount in that currency's minor units.
+type PriceLine struct {
+	Method   string
+	Currency Currency
+	Amount   int64
+}
+
+// ProductInput is the editable content of a product: its title, atom composition and prices.
+type ProductInput struct {
+	Title  string
+	Atoms  []AtomLine
+	Prices []PriceLine
+}
+
+// knownAtoms is the fixed atom set, mirroring the catalog_atom seed / CHECK.
+var knownAtoms = map[string]bool{atomChips: true, "hints": true, "noads_days": true, "tournament": true}
+
+// validCurrency reports whether c is one of the four catalog currencies.
+func validCurrency(c Currency) bool {
+	switch c {
+	case CurrencyRUB, CurrencyVote, CurrencyStar, CurrencyChip:
+		return true
+	}
+	return false
+}
+
+// validateProduct checks a product's composition and prices. When sellable is true (the product is
+// or is becoming active) it also enforces the storefront shape: a pack (the chips atom ⇒ a money
+// price per method and no CHIP price, chips-only) or a value (no chips ⇒ a single CHIP price and no
+// money price). The tournament atom is never sellable (its economy is the tournament stage), so an
+// active product may not carry it; an archived draft may (a template for later) and skips the shape
+// check.
+func validateProduct(in ProductInput, sellable bool) error {
+	if strings.TrimSpace(in.Title) == "" {
+		return errors.New("product title is required")
+	}
+	if len(in.Atoms) == 0 {
+		return errors.New("product needs at least one atom")
+	}
+	seen := map[string]bool{}
+	hasChips, hasTournament, hasBenefit := false, false, false
+	for _, a := range in.Atoms {
+		if !knownAtoms[a.Atom] {
+			return fmt.Errorf("unknown atom %q", a.Atom)
+		}
+		if seen[a.Atom] {
+			return fmt.Errorf("duplicate atom %q", a.Atom)
+		}
+		seen[a.Atom] = true
+		if a.Quantity <= 0 {
+			return fmt.Errorf("atom %q quantity must be positive", a.Atom)
+		}
+		switch a.Atom {
+		case atomChips:
+			hasChips = true
+		case "tournament":
+			hasTournament = true
+		default:
+			hasBenefit = true
+		}
+	}
+
+	priceSeen := map[string]bool{}
+	hasChipPrice, hasMoneyPrice := false, false
+	for _, p := range in.Prices {
+		if p.Method != "" && p.Method != string(SourceVK) && p.Method != string(SourceTelegram) && p.Method != string(SourceDirect) {
+			return fmt.Errorf("invalid price method %q", p.Method)
+		}
+		if !validCurrency(p.Currency) {
+			return fmt.Errorf("invalid currency %q", p.Currency)
+		}
+		if p.Amount < 0 {
+			return errors.New("price amount must be non-negative")
+		}
+		if p.Currency == CurrencyChip && p.Method != "" {
+			return errors.New("a CHIP price must have no method")
+		}
+		if p.Currency != CurrencyChip && p.Method == "" {
+			return fmt.Errorf("a %s price needs a payment method", p.Currency)
+		}
+		key := p.Method + "|" + string(p.Currency)
+		if priceSeen[key] {
+			return fmt.Errorf("duplicate price (%s, %s)", p.Method, p.Currency)
+		}
+		priceSeen[key] = true
+		if p.Currency == CurrencyChip {
+			hasChipPrice = true
+		} else {
+			hasMoneyPrice = true
+		}
+	}
+
+	if !sellable {
+		return nil // an archived draft may be incomplete
+	}
+	if hasTournament {
+		return errors.New("a product carrying the tournament atom cannot be sold yet")
+	}
+	if hasChips {
+		if hasBenefit {
+			return errors.New("a chip pack must contain only the chips atom")
+		}
+		if !hasMoneyPrice || hasChipPrice {
+			return errors.New("a chip pack needs a money price per method and no CHIP price")
+		}
+	} else {
+		if !hasChipPrice || hasMoneyPrice {
+			return errors.New("a value needs a single CHIP price and no money price")
+		}
+	}
+	return nil
+}
+
+// AdminCatalog lists products with their composition, prices and whether each has been transacted,
+// for the admin editor. includeInactive adds the archived products to the active ones (the console's
+// active/all toggle); with it false only active products are returned. Read uncached, straight from
+// 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
+// product created active must satisfy the sellable shape.
+func (s *Service) CreateProduct(ctx context.Context, in ProductInput, active bool) (uuid.UUID, error) {
+	if err := validateProduct(in, active); err != nil {
+		return uuid.Nil, err
+	}
+	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
+// satisfy the sellable shape.
+func (s *Service) UpdateProduct(ctx context.Context, id uuid.UUID, in ProductInput) (err error) {
+	active, err := s.store.productActive(ctx, id)
+	if err != nil {
+		return err
+	}
+	if err := validateProduct(in, active); err != nil {
+		return err
+	}
+	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
+// sellable shape, so a draft or a tournament product cannot be put on sale.
+func (s *Service) SetProductActive(ctx context.Context, id uuid.UUID, active bool) error {
+	if active {
+		in, err := s.store.productInput(ctx, id)
+		if err != nil {
+			return err
+		}
+		if err := validateProduct(in, true); err != nil {
+			return err
+		}
+	}
+	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 {
+	if err := s.store.deleteProduct(ctx, id); err != nil {
+		return err
+	}
+	s.markOfferStale()
+	return nil
+}

backend/internal/payments/catalog_admin_test.go

@@ -0,0 +1,47 @@
+package payments
+
+import "testing"
+
+func TestValidateProduct(t *testing.T) {
+	pack := ProductInput{
+		Title:  "100 chips",
+		Atoms:  []AtomLine{{Atom: "chips", Quantity: 100}},
+		Prices: []PriceLine{{Method: "direct", Currency: CurrencyRUB, Amount: 14900}},
+	}
+	value := ProductInput{
+		Title:  "5 hints",
+		Atoms:  []AtomLine{{Atom: "hints", Quantity: 5}},
+		Prices: []PriceLine{{Method: "", Currency: CurrencyChip, Amount: 50}},
+	}
+
+	tests := []struct {
+		name     string
+		in       ProductInput
+		sellable bool
+		wantErr  bool
+	}{
+		{"valid pack", pack, true, false},
+		{"valid value", value, true, false},
+		{"pack with a benefit atom", ProductInput{Title: "x", Atoms: []AtomLine{{"chips", 100}, {"hints", 5}}, Prices: pack.Prices}, true, true},
+		{"pack without money price", ProductInput{Title: "x", Atoms: pack.Atoms, Prices: value.Prices}, true, true},
+		{"value without chip price", ProductInput{Title: "x", Atoms: value.Atoms, Prices: pack.Prices}, true, true},
+		{"tournament sellable is refused", ProductInput{Title: "cup", Atoms: []AtomLine{{"tournament", 1}}, Prices: value.Prices}, true, true},
+		{"tournament draft is allowed", ProductInput{Title: "cup", Atoms: []AtomLine{{"tournament", 1}}}, false, false},
+		{"unknown atom", ProductInput{Title: "x", Atoms: []AtomLine{{"gold", 1}}}, false, true},
+		{"duplicate atom", ProductInput{Title: "x", Atoms: []AtomLine{{"hints", 1}, {"hints", 2}}}, false, true},
+		{"non-positive quantity", ProductInput{Title: "x", Atoms: []AtomLine{{"hints", 0}}}, false, true},
+		{"chip price with a method", ProductInput{Title: "x", Atoms: value.Atoms, Prices: []PriceLine{{Method: "direct", Currency: CurrencyChip, Amount: 50}}}, true, true},
+		{"money price without a method", ProductInput{Title: "x", Atoms: pack.Atoms, Prices: []PriceLine{{Method: "", Currency: CurrencyRUB, Amount: 149}}}, true, true},
+		{"duplicate price", ProductInput{Title: "x", Atoms: pack.Atoms, Prices: []PriceLine{{Method: "direct", Currency: CurrencyRUB, Amount: 1}, {Method: "direct", Currency: CurrencyRUB, Amount: 2}}}, true, true},
+		{"empty title", ProductInput{Title: " ", Atoms: value.Atoms, Prices: value.Prices}, true, true},
+		{"no atoms", ProductInput{Title: "x", Prices: value.Prices}, true, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateProduct(tt.in, tt.sellable)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("validateProduct = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}

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/gate.go

@@ -89,8 +89,10 @@ func NewContext(kind, subtype string) Context {
 // every spend/purchase and the application of any foreign origin.
 func (c Context) Trusted() bool { return c.Kind.Valid() }
 
-// vkFrozen reports whether this is the VK-iOS spend freeze: VK context on the trusted iOS
-// subtype. A previously bought benefit still applies there, but no spend or purchase is possible.
+// vkFrozen reports whether this is the VK-iOS purchase freeze: VK context on the trusted iOS
+// subtype. Apple's ToS forbids only BUYING in-app values there, so a purchase (money -> chips) is
+// refused; earning chips (rewarded ads) and SPENDING chips already in the VK wallet — earned or
+// bought on the same account elsewhere (e.g. VK Android) — are legal and stay allowed.
 func (c Context) vkFrozen() bool { return c.Kind == SourceVK && c.Subtype == SubtypeIOS }
 
 // spendPriority is the fixed draw order when several segments are spendable in one context
@@ -103,11 +105,12 @@ func has(present []Source, s Source) bool {
 }
 
 // spendableSources returns the chip segments that may be SPENT in the context, in draw-priority
-// order, restricted to the sources the account actually has (present). It is empty when the
-// platform is untrusted (fail-closed) or VK-iOS (frozen): inside VK/TG only the same-named
-// segment is spendable; on web/native all attached segments are, drained direct→vk→tg.
+// order, restricted to the sources the account actually has (present). It is empty only when the
+// platform is untrusted (fail-closed); VK-iOS is NOT excluded — the freeze is purchase-only, so
+// spending VK-wallet chips there is allowed. Inside VK/TG only the same-named segment is spendable;
+// on web/native all attached segments are, drained direct→vk→tg.
 func spendableSources(c Context, present []Source) []Source {
-	if !c.Trusted() || c.vkFrozen() {
+	if !c.Trusted() {
 		return nil
 	}
 	switch c.Kind {
@@ -128,10 +131,10 @@ func spendableSources(c Context, present []Source) []Source {
 }
 
 // applicableOrigins returns the benefit origins that APPLY in the context, in draw-priority
-// order, restricted to present sources. It differs from spendableSources in one way: VK-iOS is
-// NOT excluded — a benefit bought earlier still applies while spending is frozen. Inside VK/TG
-// only the same-named origin applies (a foreign, e.g. direct, origin never activates inside a
-// store — the compliance wall); on web/native direct+vk+tg all apply, drained direct→vk→tg.
+// order, restricted to present sources. It mirrors spendableSources (both gate only on a trusted
+// platform now that the VK-iOS freeze is purchase-only). Inside VK/TG only the same-named origin
+// applies (a foreign, e.g. direct, origin never activates inside a store — the compliance wall);
+// on web/native direct+vk+tg all apply, drained direct→vk→tg.
 func applicableOrigins(c Context, present []Source) []Source {
 	if !c.Trusted() {
 		return nil

backend/internal/payments/gate_test.go

@@ -16,7 +16,8 @@ func TestSpendableSources(t *testing.T) {
 		want    []Source
 	}{
 		{"vk android, vk present", Context{Kind: SourceVK, Subtype: "android"}, allPresent, []Source{SourceVK}},
-		{"vk ios frozen", Context{Kind: SourceVK, Subtype: SubtypeIOS}, allPresent, nil},
+		// VK-iOS spends its own vk segment: the freeze is purchase-only, spending is allowed.
+		{"vk ios spends vk", Context{Kind: SourceVK, Subtype: SubtypeIOS}, allPresent, []Source{SourceVK}},
 		{"vk android, vk absent", Context{Kind: SourceVK, Subtype: "android"}, []Source{SourceDirect}, nil},
 		{"telegram", Context{Kind: SourceTelegram, Subtype: "web"}, allPresent, []Source{SourceTelegram}},
 		{"telegram, tg absent", Context{Kind: SourceTelegram}, []Source{SourceVK}, nil},
@@ -41,8 +42,8 @@ func TestApplicableOrigins(t *testing.T) {
 		present []Source
 		want    []Source
 	}{
-		// A benefit still APPLIES on VK-iOS while spending is frozen.
-		{"vk ios still applies", Context{Kind: SourceVK, Subtype: SubtypeIOS}, allPresent, []Source{SourceVK}},
+		// A vk-origin benefit applies on VK-iOS (spending is allowed there — the freeze is purchase-only).
+		{"vk ios applies", Context{Kind: SourceVK, Subtype: SubtypeIOS}, allPresent, []Source{SourceVK}},
 		{"vk android", Context{Kind: SourceVK, Subtype: "android"}, allPresent, []Source{SourceVK}},
 		{"telegram", Context{Kind: SourceTelegram}, allPresent, []Source{SourceTelegram}},
 		{"direct all, priority", Context{Kind: SourceDirect}, allPresent, []Source{SourceDirect, SourceVK, SourceTelegram}},

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/payments.go

@@ -147,12 +147,13 @@ func (m Money) Cmp(o Money) (int, error) {
 	}
 }
 
-// String renders the amount as "<value> <currency>", with the currency's
-// fractional digits and no floating point (e.g. "149.50 RUB", "250 XTR").
-func (m Money) String() string {
+// Major renders the amount as a decimal string without the currency, with the currency's
+// fractional digits and no floating point (e.g. "149.50", "250") — the form a provider's amount
+// field (Robokassa OutSum) takes.
+func (m Money) Major() string {
 	scale := m.currency.minorPerUnit()
 	if scale == 1 {
-		return fmt.Sprintf("%d %s", m.minor, m.currency)
+		return fmt.Sprintf("%d", m.minor)
 	}
 	neg := m.minor < 0
 	abs := m.minor
@@ -167,5 +168,10 @@ func (m Money) String() string {
 	if neg {
 		sign = "-"
 	}
-	return fmt.Sprintf("%s%d.%0*d %s", sign, abs/scale, width, abs%scale, m.currency)
+	return fmt.Sprintf("%s%d.%0*d", sign, abs/scale, width, abs%scale)
+}
+
+// String renders the amount as "<value> <currency>" (e.g. "149.50 RUB", "250 XTR").
+func (m Money) String() string {
+	return m.Major() + " " + string(m.currency)
 }

backend/internal/payments/refund_admin.go

@@ -0,0 +1,41 @@
+package payments
+
+import (
+	"context"
+
+	"github.com/google/uuid"
+)
+
+// providerAdmin tags an operator-initiated refund in the ledger, distinct from a rail's own refund
+// (robokassa / vk / telegram). The refund idempotency key (providerAdmin, order id) allows exactly
+// one manual full refund per order.
+const providerAdmin = "admin"
+
+// RefundOrderFull refunds a paid order in full at the operator's request: it revokes the funded
+// chips best-effort (floored at 0, never negative — D27), records a refund ledger row, and is
+// idempotent (a second call reports AlreadyRefunded). The operator performs the actual money refund
+// on the rail (Robokassa cabinet / VK support / Telegram refundStarPayment); this records it.
+func (s *Service) RefundOrderFull(ctx context.Context, orderID uuid.UUID) (RefundOutcome, error) {
+	o, err := s.store.orderByID(ctx, orderID)
+	if err != nil {
+		return RefundOutcome{}, err
+	}
+	refunded, err := MoneyFromMinor(o.expectedAmount, Currency(o.currency))
+	if err != nil {
+		return RefundOutcome{}, err
+	}
+	return s.store.refund(ctx, orderID, providerAdmin, orderID.String(), refunded, s.clock())
+}
+
+// LedgerExportRow is one append-only ledger row for the tax / reconciliation export, carrying the
+// account it belongs to alongside the entry fields.
+type LedgerExportRow struct {
+	AccountID string
+	LedgerEntry
+}
+
+// LedgerExport reads the entire append-only ledger (all accounts, newest first) for a CSV/JSON
+// export — tax reporting and future rail reconciliation. Uncached, admin-only.
+func (s *Service) LedgerExport(ctx context.Context) ([]LedgerExportRow, error) {
+	return s.store.allLedger(ctx)
+}

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.
@@ -156,6 +164,41 @@ func (s *Service) Grant(ctx context.Context, accountID uuid.UUID, origin Source,
 	return s.store.grant(ctx, accountID, origin, d, snapshot, s.clock())
 }
 
+// GrantProduct grants a product's benefit atoms (hints, no-ads days) to an origin as a zero-price
+// admin sale, recording the source product on the ledger row (auditable to it). It refuses a
+// product carrying the chips atom (never granted — D16) or the tournament atom (no credit target
+// yet), and one whose atoms yield no grantable benefit.
+func (s *Service) GrantProduct(ctx context.Context, accountID uuid.UUID, origin Source, productID uuid.UUID) error {
+	if !origin.Valid() {
+		return fmt.Errorf("payments: invalid grant origin %q", origin)
+	}
+	in, err := s.store.productInput(ctx, productID)
+	if err != nil {
+		return err
+	}
+	var d benefitDelta
+	for _, a := range in.Atoms {
+		switch a.Atom {
+		case "hints":
+			d.hintsAdd += a.Quantity
+		case "noads_days":
+			d.noAdsDays += a.Quantity
+		case atomChips:
+			return ErrCannotGrantChips
+		case "tournament":
+			return ErrCannotGrantTournament
+		}
+	}
+	if d.zero() {
+		return ErrNothingToGrant
+	}
+	snapshot, err := marshalGrantProduct(productID, in.Title, d)
+	if err != nil {
+		return err
+	}
+	return s.store.grantProduct(ctx, accountID, origin, productID, d, snapshot, s.clock())
+}
+
 // MergeTx merges the secondary account's segments and benefits into the primary inside the
 // caller's transaction (the account-merge flow). The caller invalidates the affected caches
 // after committing (Invalidate).
@@ -244,3 +287,20 @@ func marshalGrant(d benefitDelta) ([]byte, error) {
 	}
 	return b, nil
 }
+
+// marshalGrantProduct builds the snapshot for an admin grant-by-product: the source product and the
+// benefit atoms it granted (price 0).
+func marshalGrantProduct(productID uuid.UUID, title string, d benefitDelta) ([]byte, error) {
+	atoms := map[string]int{}
+	if d.hintsAdd > 0 {
+		atoms["hints"] = d.hintsAdd
+	}
+	if d.noAdsDays > 0 {
+		atoms["noads_days"] = d.noAdsDays
+	}
+	b, err := json.Marshal(purchaseSnapshot{ProductID: productID.String(), Title: title, Atoms: atoms, PriceChips: 0})
+	if err != nil {
+		return nil, fmt.Errorf("payments: marshal product grant snapshot: %w", err)
+	}
+	return b, nil
+}

backend/internal/payments/service_availability.go

@@ -0,0 +1,63 @@
+package payments
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/google/uuid"
+)
+
+// CanPurchase reports whether an account may open a purchase order on rail, combining the account's
+// per-account override with the rail's operational switch (PurchaseGate). It is the operational
+// availability layer only — the caller still enforces the security gates (trusted platform, the D36
+// email anchor, the VK-iOS spend freeze, the min client version). On a block, reason is localized to
+// lang for the user; err is only a store failure.
+func (s *Service) CanPurchase(ctx context.Context, accountID uuid.UUID, rail, lang string) (ok bool, reason string, err error) {
+	ov, err := s.store.purchaseOverride(ctx, accountID)
+	if err != nil {
+		return false, "", err
+	}
+	avail, err := s.store.railAvailability(ctx, rail)
+	if err != nil {
+		return false, "", err
+	}
+	ok, reason = PurchaseGate(ov, avail, lang)
+	return ok, reason, nil
+}
+
+// RailStatuses returns every known rail's operational status for the admin editor, filling a rail
+// with no stored row with the fail-open enabled default so the editor always shows one row per rail.
+func (s *Service) RailStatuses(ctx context.Context) (map[string]RailAvailability, error) {
+	stored, err := s.store.allRailStatus(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := make(map[string]RailAvailability, len(KnownRails))
+	for _, rail := range KnownRails {
+		if a, ok := stored[rail]; ok {
+			out[rail] = a
+		} else {
+			out[rail] = RailAvailability{Enabled: true}
+		}
+	}
+	return out, nil
+}
+
+// SetRailStatus upserts a rail's operational status from the admin editor. It rejects an unknown rail
+// key so a typo cannot create a dead row.
+func (s *Service) SetRailStatus(ctx context.Context, rail string, a RailAvailability) error {
+	if !isKnownRail(rail) {
+		return fmt.Errorf("payments: unknown rail %q", rail)
+	}
+	return s.store.setRailStatus(ctx, rail, a, s.clock())
+}
+
+// PurchaseOverrideFor returns an account's purchase override (OverrideDefault when none is set).
+func (s *Service) PurchaseOverrideFor(ctx context.Context, accountID uuid.UUID) (PurchaseOverride, error) {
+	return s.store.purchaseOverride(ctx, accountID)
+}
+
+// SetPurchaseOverride sets or clears an account's purchase override (OverrideDefault deletes the row).
+func (s *Service) SetPurchaseOverride(ctx context.Context, accountID uuid.UUID, ov PurchaseOverride) error {
+	return s.store.setPurchaseOverride(ctx, accountID, ov, s.clock())
+}

backend/internal/payments/service_intake.go

@@ -0,0 +1,227 @@
+package payments
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/google/uuid"
+)
+
+// OrderResult is what CreateOrder returns to the transport: the created order id and the details a
+// provider launch payload needs — the amount to charge and a human title for the payment.
+type OrderResult struct {
+	OrderID uuid.UUID
+	Amount  Money
+	Title   string
+}
+
+// CreateOrder opens a pending order to fund a chip pack in the execution context's payment method,
+// tagged with the provider that will settle it. It gate-checks the context (trusted, not the
+// VK-iOS spend freeze) and that the method's funding segment is attached, prices the pack in the
+// method's currency, then writes the order. The caller enforces any account-level precondition
+// (e.g. the direct email anchor, D36) before calling — payments holds no cross-schema identity
+// knowledge.
+func (s *Service) CreateOrder(ctx context.Context, accountID uuid.UUID, cxt Context, present []Source, productID uuid.UUID, provider string) (OrderResult, error) {
+	if !cxt.Trusted() || cxt.vkFrozen() {
+		return OrderResult{}, ErrUntrusted
+	}
+	method := cxt.Kind
+	if !has(present, method) {
+		return OrderResult{}, ErrUntrusted // the funding segment is not attached to the account
+	}
+	pack, err := s.store.loadPackForOrder(ctx, productID, method)
+	if err != nil {
+		return OrderResult{}, err
+	}
+	orderID, err := uuid.NewV7()
+	if err != nil {
+		return OrderResult{}, fmt.Errorf("payments: order id: %w", err)
+	}
+	o := newOrder{
+		orderID:   orderID,
+		accountID: accountID,
+		platform:  string(method),
+		productID: productID,
+		amount:    pack.price,
+		origin:    method,
+		provider:  provider,
+		shop:      directShop(cxt),
+	}
+	if err := s.store.createOrder(ctx, o, s.clock()); err != nil {
+		return OrderResult{}, err
+	}
+	return OrderResult{OrderID: orderID, Amount: pack.price, Title: pack.title}, nil
+}
+
+// directShop returns the merchant shop (channel) a direct order is issued through — the trusted
+// platform subtype for the direct rail ("web"/"android"), or "" for any other rail (the per-shop
+// split is direct-only; D42/D44). Recorded on the order for the admin per-channel breakdown.
+func directShop(cxt Context) string {
+	if cxt.Kind == SourceDirect {
+		return cxt.Subtype
+	}
+	return ""
+}
+
+// OrderItem returns a pending order's human title and the amount it charges, in the order's own
+// currency — the details a provider's item-lookup phase needs (VK's get_item). It reads the order
+// and the pack title, honouring the pack even if it was later deactivated (mirrors Fund).
+func (s *Service) OrderItem(ctx context.Context, orderID uuid.UUID) (title string, amount Money, err error) {
+	ord, err := s.store.orderByID(ctx, orderID)
+	if err != nil {
+		return "", Money{}, err
+	}
+	_, title, err = s.store.packForCredit(ctx, ord.productID)
+	if err != nil {
+		return "", Money{}, err
+	}
+	amount, err = MoneyFromMinor(ord.expectedAmount, Currency(ord.currency))
+	if err != nil {
+		return "", Money{}, err
+	}
+	return title, amount, nil
+}
+
+// Fund credits a paid order into its funded segment exactly once, from a verified provider callback
+// — the single writer for every rail. It matches the order, verifies the paid amount, appends the
+// fund ledger row (idempotent on (provider, provider_payment_id)), credits the balance and marks
+// the order paid. A duplicate callback returns AlreadyCredited without a second credit; a valid
+// callback is honoured even on an expired order (§9/D23).
+func (s *Service) Fund(ctx context.Context, orderID uuid.UUID, provider, providerPaymentID string, paid Money) (FundOutcome, error) {
+	return s.store.fund(ctx, orderID, provider, providerPaymentID, paid, s.clock())
+}
+
+// Refund reverses a paid order's credit best-effort, exactly once — for an external refund or an
+// admin-initiated one (E7). It revokes the funded chips floored at 0 (never negative, D27), records
+// any unrecoverable remainder as a per-account loss and abuse flag, and appends a refund ledger row
+// idempotent on (provider, providerRefundID) — distinct from the fund's payment id. A duplicate
+// refund returns AlreadyRefunded. The caller records the refunded payment event and performs any
+// provider-side money-back (the rails have no unsolicited refund push: Robokassa via its refund API
+// / cabinet, VK via support, Telegram via refundStarPayment — all admin-triggered).
+func (s *Service) Refund(ctx context.Context, orderID uuid.UUID, provider, providerRefundID string, refunded Money) (RefundOutcome, error) {
+	return s.store.refund(ctx, orderID, provider, providerRefundID, refunded, s.clock())
+}
+
+// Pre-checkout decline reason codes. They are language-neutral: the transport layer localises them
+// to the order account's preferred language before showing the payer (the reason is displayed in the
+// Telegram payment sheet).
+const (
+	// PreCheckoutGone means no order matches — an unknown or stale invoice payload.
+	PreCheckoutGone = "order_gone"
+	// PreCheckoutAlreadyPaid means the order is already paid (a reusable invoice link paid twice).
+	PreCheckoutAlreadyPaid = "already_paid"
+	// PreCheckoutPriceChanged means the amount or currency no longer matches the order.
+	PreCheckoutPriceChanged = "price_changed"
+)
+
+// PreCheckoutOutcome is the pre-charge validation of a Telegram Stars order. OK approves the charge;
+// otherwise Reason is a decline reason code the transport localises. AccountID is the order's account
+// (for localising the reason to its preferred language); it is the zero UUID when the order is unknown.
+type PreCheckoutOutcome struct {
+	OK        bool
+	Reason    string
+	AccountID uuid.UUID
+}
+
+// ValidatePreCheckout answers whether a Stars pre_checkout_query for orderID paying amount may be
+// approved, before any star is charged. It approves an order that exists, is not already paid (a
+// reusable invoice link paid a second time is refused here) and whose expected amount and currency
+// match the invoice. A pending or honoured-expired order is approved — a late credit is honoured
+// (§9/D23). A missing order or a mismatch is a clean decline with a reason code, not an error.
+func (s *Service) ValidatePreCheckout(ctx context.Context, orderID uuid.UUID, amount Money) (PreCheckoutOutcome, error) {
+	ord, err := s.store.orderByID(ctx, orderID)
+	if errors.Is(err, ErrOrderNotFound) {
+		return PreCheckoutOutcome{OK: false, Reason: PreCheckoutGone}, nil
+	}
+	if err != nil {
+		return PreCheckoutOutcome{}, err
+	}
+	if ord.status == "paid" {
+		return PreCheckoutOutcome{OK: false, Reason: PreCheckoutAlreadyPaid, AccountID: ord.accountID}, nil
+	}
+	if amount.Currency() != Currency(ord.currency) || amount.Minor() != ord.expectedAmount {
+		return PreCheckoutOutcome{OK: false, Reason: PreCheckoutPriceChanged, AccountID: ord.accountID}, nil
+	}
+	return PreCheckoutOutcome{OK: true, AccountID: ord.accountID}, nil
+}
+
+// providerVKAds tags a rewarded-video credit from the VK ads network in the ledger (distinct from
+// the "vk" Votes-purchase provider), so the daily cap counts only ad credits and the report separates
+// them.
+const providerVKAds = "vk_ads"
+
+// InterstitialCooldowns reports the post-move interstitial-ad cooldowns (seconds): global, vs_ai and
+// the independent hint-triggered one. The client mirrors them and self-gates (client-mirrored, D30).
+func (s *Service) InterstitialCooldowns(ctx context.Context) (global, vsAi, hint int, err error) {
+	return s.store.interstitialCooldowns(ctx)
+}
+
+// RewardPayout reports the chips a rewarded-video view earns in the caller's context — the config
+// payout in a trusted VK context with the VK segment attached, and 0 everywhere else (rewarded is
+// VK-only, D28). The client uses it to gate the "watch for chips" button.
+func (s *Service) RewardPayout(ctx context.Context, cxt Context, present []Source) (int, error) {
+	if cxt.Kind != SourceVK || !cxt.Trusted() || !has(present, SourceVK) {
+		return 0, nil
+	}
+	payout, _, _, err := s.store.rewardConfig(ctx)
+	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
+// client nonce and order-less. It credits nothing when rewarded is unconfigured (0 payout) or the
+// daily cap is reached. Rewarded video is VK-only (D28) and is an ad view — not a purchase — so the
+// VK-iOS purchase freeze does not apply; it requires a trusted VK context with the VK segment
+// attached.
+func (s *Service) CreditReward(ctx context.Context, accountID uuid.UUID, cxt Context, present []Source, nonce string) (RewardOutcome, error) {
+	if cxt.Kind != SourceVK || !cxt.Trusted() || !has(present, SourceVK) {
+		return RewardOutcome{}, ErrUntrusted
+	}
+	return s.store.creditReward(ctx, accountID, SourceVK, providerVKAds, nonce, s.clock())
+}
+
+// ExpireOrders marks pending orders older than the configured lifetime as expired, returning how
+// many were swept. It backs the periodic pending reaper; expiry is cosmetic (a late valid callback
+// still credits — see Fund).
+func (s *Service) ExpireOrders(ctx context.Context) (int, error) {
+	ttl, err := s.store.orderTTL(ctx)
+	if err != nil {
+		return 0, err
+	}
+	return s.store.expirePending(ctx, ttl, s.clock())
+}
+
+// RecordPaymentEvent appends a payment lifecycle event (succeeded/failed/refunded) for the
+// dispatcher to deliver to the user (live stream, botlink or email).
+func (s *Service) RecordPaymentEvent(ctx context.Context, accountID uuid.UUID, orderID *uuid.UUID, eventType string, payload []byte) error {
+	return s.store.insertPaymentEvent(ctx, accountID, orderID, eventType, payload, s.clock())
+}
+
+// UndispatchedEvents returns up to limit payment events awaiting delivery. The dispatcher drains
+// them and marks each delivered via MarkEventDispatched.
+func (s *Service) UndispatchedEvents(ctx context.Context, limit int) ([]PaymentEvent, error) {
+	return s.store.undispatchedEvents(ctx, limit)
+}
+
+// MarkEventDispatched stamps a payment event as delivered so it is not re-sent.
+func (s *Service) MarkEventDispatched(ctx context.Context, eventID uuid.UUID) error {
+	return s.store.markEventDispatched(ctx, eventID, s.clock())
+}

backend/internal/payments/service_intake_test.go

@@ -0,0 +1,42 @@
+package payments
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// gateOnlyService builds a Service with a fixed clock and no store, usable only for the CreateOrder
+// gate rejections that return before any store access.
+func gateOnlyService() *Service {
+	return &Service{clock: func() time.Time { return time.Unix(0, 0).UTC() }}
+}
+
+// TestCreateOrderGateRejections checks that CreateOrder fails closed — before touching the store —
+// on an untrusted platform, the VK-iOS spend freeze, and a method whose funding segment the account
+// does not hold.
+func TestCreateOrderGateRejections(t *testing.T) {
+	ctx := context.Background()
+	acc, prod := uuid.New(), uuid.New()
+	present := []Source{SourceDirect, SourceVK}
+
+	cases := []struct {
+		name string
+		cxt  Context
+	}{
+		{"untrusted context", Context{}},
+		{"vk-ios purchase freeze", Context{Kind: SourceVK, Subtype: SubtypeIOS}},
+		{"method segment not attached", Context{Kind: SourceTelegram}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := gateOnlyService().CreateOrder(ctx, acc, tc.cxt, present, prod, "robokassa")
+			if !errors.Is(err, ErrUntrusted) {
+				t.Fatalf("CreateOrder(%s) = %v, want ErrUntrusted", tc.name, err)
+			}
+		})
+	}
+}

backend/internal/payments/statement.go

@@ -0,0 +1,65 @@
+package payments
+
+import (
+	"context"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// Statement is an account's full financial picture for the admin console: chip balances per funding
+// segment, benefits per origin, the recorded refund risk, and the append-only ledger history
+// (newest first). Read straight from the materialized tables + the ledger, uncached — an admin-only,
+// rare view, not a hot path.
+type Statement struct {
+	Segments []SegmentChips
+	Benefits []OriginBenefit
+	Risk     RiskInfo
+	Ledger   []LedgerEntry
+}
+
+// SegmentChips is one funding segment's chip balance.
+type SegmentChips struct {
+	Source Source
+	Chips  int
+}
+
+// OriginBenefit is one origin's benefit state: the hint wallet, the ad-free term (zero AdsPaidUntil
+// when none) and the lifetime ad-free flag.
+type OriginBenefit struct {
+	Origin       Source
+	Hints        int
+	AdsPaidUntil time.Time
+	AdsForever   bool
+}
+
+// RiskInfo is the account's recorded refund risk: whether it is abuse-flagged and the unrecoverable
+// chip loss accumulated by floor-0 refunds. Present is false when the account has no risk row.
+type RiskInfo struct {
+	Present   bool
+	Abuse     bool
+	LossChips int
+}
+
+// LedgerEntry is one append-only ledger row projected for the report. The string ids are empty when
+// the column is NULL; Shop is the direct-rail merchant channel the referenced order used (empty for
+// other rails or order-less rows); Snapshot is the raw purchase/refund JSON (empty when none).
+type LedgerEntry struct {
+	Kind              string
+	Source            string
+	Origin            string
+	ChipsDelta        int
+	ProductID         string
+	OrderID           string
+	Provider          string
+	ProviderPaymentID string
+	Shop              string
+	Snapshot          string
+	CreatedAt         time.Time
+}
+
+// AccountStatement assembles the account's financial picture (segments, benefits, risk, full ledger
+// history) for the admin console, straight from the materialized tables and the ledger (uncached).
+func (s *Service) AccountStatement(ctx context.Context, accountID uuid.UUID) (Statement, error) {
+	return s.store.accountStatement(ctx, accountID)
+}

backend/internal/payments/store_availability.go

@@ -0,0 +1,96 @@
+package payments
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// railAvailability reads a rail's operational availability. A missing row is fail-open: enabled with
+// no message, so payments stay on unless an operator explicitly disabled the rail.
+func (s *Store) railAvailability(ctx context.Context, rail string) (RailAvailability, error) {
+	var a RailAvailability
+	err := s.db.QueryRowContext(ctx,
+		`SELECT enabled, message_ru, message_en FROM payments.rail_status WHERE rail = $1`, rail).
+		Scan(&a.Enabled, &a.MessageRU, &a.MessageEN)
+	if errors.Is(err, sql.ErrNoRows) {
+		return RailAvailability{Enabled: true}, nil
+	}
+	if err != nil {
+		return RailAvailability{}, fmt.Errorf("payments: read rail status %q: %w", rail, err)
+	}
+	return a, nil
+}
+
+// allRailStatus reads every stored rail-status row for the admin editor, keyed by rail. Rails with
+// no row are absent (the caller fills them with the fail-open enabled default).
+func (s *Store) allRailStatus(ctx context.Context) (map[string]RailAvailability, error) {
+	rows, err := s.db.QueryContext(ctx,
+		`SELECT rail, enabled, message_ru, message_en FROM payments.rail_status`)
+	if err != nil {
+		return nil, fmt.Errorf("payments: read rail statuses: %w", err)
+	}
+	defer rows.Close()
+	out := make(map[string]RailAvailability)
+	for rows.Next() {
+		var rail string
+		var a RailAvailability
+		if err := rows.Scan(&rail, &a.Enabled, &a.MessageRU, &a.MessageEN); err != nil {
+			return nil, fmt.Errorf("payments: scan rail status: %w", err)
+		}
+		out[rail] = a
+	}
+	return out, rows.Err()
+}
+
+// setRailStatus upserts a rail's operational status (admin).
+func (s *Store) setRailStatus(ctx context.Context, rail string, a RailAvailability, now time.Time) error {
+	if _, err := s.db.ExecContext(ctx,
+		`INSERT INTO payments.rail_status (rail, enabled, message_ru, message_en, updated_at)
+		 VALUES ($1, $2, $3, $4, $5)
+		 ON CONFLICT (rail) DO UPDATE SET enabled = $2, message_ru = $3, message_en = $4, updated_at = $5`,
+		rail, a.Enabled, a.MessageRU, a.MessageEN, now); err != nil {
+		return fmt.Errorf("payments: set rail status %q: %w", rail, err)
+	}
+	return nil
+}
+
+// purchaseOverride reads an account's purchase override; a missing row is OverrideDefault.
+func (s *Store) purchaseOverride(ctx context.Context, accountID uuid.UUID) (PurchaseOverride, error) {
+	var allow bool
+	err := s.db.QueryRowContext(ctx,
+		`SELECT allow FROM payments.account_payment_override WHERE account_id = $1`, accountID).Scan(&allow)
+	if errors.Is(err, sql.ErrNoRows) {
+		return OverrideDefault, nil
+	}
+	if err != nil {
+		return OverrideDefault, fmt.Errorf("payments: read purchase override %s: %w", accountID, err)
+	}
+	if allow {
+		return OverrideAllow, nil
+	}
+	return OverrideDeny, nil
+}
+
+// setPurchaseOverride upserts an account's override, or deletes the row for OverrideDefault (the
+// default state is the absence of a row).
+func (s *Store) setPurchaseOverride(ctx context.Context, accountID uuid.UUID, ov PurchaseOverride, now time.Time) error {
+	if ov == OverrideDefault {
+		if _, err := s.db.ExecContext(ctx,
+			`DELETE FROM payments.account_payment_override WHERE account_id = $1`, accountID); err != nil {
+			return fmt.Errorf("payments: clear purchase override %s: %w", accountID, err)
+		}
+		return nil
+	}
+	if _, err := s.db.ExecContext(ctx,
+		`INSERT INTO payments.account_payment_override (account_id, allow, updated_at) VALUES ($1, $2, $3)
+		 ON CONFLICT (account_id) DO UPDATE SET allow = $2, updated_at = $3`,
+		accountID, ov == OverrideAllow, now); err != nil {
+		return fmt.Errorf("payments: set purchase override %s: %w", accountID, err)
+	}
+	return nil
+}

backend/internal/payments/store_catalog_admin.go

@@ -0,0 +1,224 @@
+package payments
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/go-jet/jet/v2/postgres"
+	"github.com/go-jet/jet/v2/qrm"
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/postgres/jet/payments/model"
+	"scrabble/backend/internal/postgres/jet/payments/table"
+)
+
+// ErrProductTransacted is returned when a hard delete is attempted on a product an order or ledger
+// 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 products with their atoms, prices and transacted flag. includeInactive adds the
+// 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)
+	}
+	out := make([]AdminProduct, 0, len(prods))
+	for _, p := range prods {
+		atoms, prices, err := s.productComposition(ctx, p.ProductID)
+		if err != nil {
+			return nil, err
+		}
+		transacted, err := s.productTransacted(ctx, p.ProductID)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, AdminProduct{
+			ID: p.ProductID, Title: p.Title, Active: p.Active,
+			Atoms: atoms, Prices: prices, Transacted: transacted,
+		})
+	}
+	return out, nil
+}
+
+// productComposition reads one product's atom lines and price rows.
+func (s *Store) productComposition(ctx context.Context, id uuid.UUID) ([]AtomLine, []PriceLine, error) {
+	var items []model.ProductItem
+	if err := postgres.SELECT(table.ProductItem.AllColumns).
+		FROM(table.ProductItem).
+		WHERE(table.ProductItem.ProductID.EQ(postgres.UUID(id))).
+		ORDER_BY(table.ProductItem.AtomType.ASC()).
+		QueryContext(ctx, s.db, &items); err != nil {
+		return nil, nil, fmt.Errorf("payments: load items %s: %w", id, err)
+	}
+	atoms := make([]AtomLine, len(items))
+	for i, it := range items {
+		atoms[i] = AtomLine{Atom: it.AtomType, Quantity: int(it.Quantity)}
+	}
+	var prs []model.ProductPrice
+	if err := postgres.SELECT(table.ProductPrice.AllColumns).
+		FROM(table.ProductPrice).
+		WHERE(table.ProductPrice.ProductID.EQ(postgres.UUID(id))).
+		QueryContext(ctx, s.db, &prs); err != nil {
+		return nil, nil, fmt.Errorf("payments: load prices %s: %w", id, err)
+	}
+	prices := make([]PriceLine, len(prs))
+	for i, pr := range prs {
+		method := ""
+		if pr.Method != nil {
+			method = *pr.Method
+		}
+		prices[i] = PriceLine{Method: method, Currency: Currency(pr.Currency), Amount: pr.Amount}
+	}
+	return atoms, prices, nil
+}
+
+// productTransacted reports whether any order or ledger row references the product.
+func (s *Store) productTransacted(ctx context.Context, id uuid.UUID) (bool, error) {
+	var yes bool
+	if err := s.db.QueryRowContext(ctx,
+		`SELECT EXISTS(SELECT 1 FROM payments.orders WHERE product_id=$1)
+		     OR EXISTS(SELECT 1 FROM payments.ledger WHERE product_id=$1)`, id).Scan(&yes); err != nil {
+		return false, fmt.Errorf("payments: product transacted %s: %w", id, err)
+	}
+	return yes, nil
+}
+
+// productActive reads a product's archived flag, ErrProductNotFound when it is missing.
+func (s *Store) productActive(ctx context.Context, id uuid.UUID) (bool, error) {
+	var p model.Product
+	err := postgres.SELECT(table.Product.Active).FROM(table.Product).
+		WHERE(table.Product.ProductID.EQ(postgres.UUID(id))).LIMIT(1).
+		QueryContext(ctx, s.db, &p)
+	if errors.Is(err, qrm.ErrNoRows) {
+		return false, ErrProductNotFound
+	}
+	if err != nil {
+		return false, fmt.Errorf("payments: product active %s: %w", id, err)
+	}
+	return p.Active, nil
+}
+
+// productInput reads a product's current editable content (title, atoms, prices).
+func (s *Store) productInput(ctx context.Context, id uuid.UUID) (ProductInput, error) {
+	var p model.Product
+	err := postgres.SELECT(table.Product.AllColumns).FROM(table.Product).
+		WHERE(table.Product.ProductID.EQ(postgres.UUID(id))).LIMIT(1).
+		QueryContext(ctx, s.db, &p)
+	if errors.Is(err, qrm.ErrNoRows) {
+		return ProductInput{}, ErrProductNotFound
+	}
+	if err != nil {
+		return ProductInput{}, fmt.Errorf("payments: product input %s: %w", id, err)
+	}
+	atoms, prices, err := s.productComposition(ctx, id)
+	if err != nil {
+		return ProductInput{}, err
+	}
+	return ProductInput{Title: p.Title, Atoms: atoms, Prices: prices}, nil
+}
+
+// createProduct inserts a product with its atoms and prices in one transaction, returning its id.
+func (s *Store) createProduct(ctx context.Context, in ProductInput, active bool, now time.Time) (uuid.UUID, error) {
+	id := uuid.New()
+	if err := withTx(ctx, s.db, func(tx *sql.Tx) error {
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO payments.product (product_id, title, active, created_at, updated_at) VALUES ($1,$2,$3,$4,$4)`,
+			id, in.Title, active, now); err != nil {
+			return fmt.Errorf("insert product: %w", err)
+		}
+		return insertComposition(ctx, tx, id, in)
+	}); err != nil {
+		return uuid.Nil, fmt.Errorf("payments: create product: %w", err)
+	}
+	return id, nil
+}
+
+// updateProduct replaces a product's title, atoms and prices in one transaction (active unchanged).
+func (s *Store) updateProduct(ctx context.Context, id uuid.UUID, in ProductInput, now time.Time) error {
+	return withTx(ctx, s.db, func(tx *sql.Tx) error {
+		res, err := tx.ExecContext(ctx,
+			`UPDATE payments.product SET title=$2, updated_at=$3 WHERE product_id=$1`, id, in.Title, now)
+		if err != nil {
+			return fmt.Errorf("payments: update product %s: %w", id, err)
+		}
+		if n, _ := res.RowsAffected(); n == 0 {
+			return ErrProductNotFound
+		}
+		if _, err := tx.ExecContext(ctx, `DELETE FROM payments.product_item WHERE product_id=$1`, id); err != nil {
+			return fmt.Errorf("payments: clear items %s: %w", id, err)
+		}
+		if _, err := tx.ExecContext(ctx, `DELETE FROM payments.product_price WHERE product_id=$1`, id); err != nil {
+			return fmt.Errorf("payments: clear prices %s: %w", id, err)
+		}
+		return insertComposition(ctx, tx, id, in)
+	})
+}
+
+// insertComposition inserts a product's atom items and price rows inside tx (a value's CHIP price
+// carries a NULL method).
+func insertComposition(ctx context.Context, tx *sql.Tx, id uuid.UUID, in ProductInput) error {
+	for _, a := range in.Atoms {
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO payments.product_item (product_id, atom_type, quantity) VALUES ($1,$2,$3)`,
+			id, a.Atom, a.Quantity); err != nil {
+			return fmt.Errorf("insert item %s: %w", a.Atom, err)
+		}
+	}
+	for _, p := range in.Prices {
+		var method any
+		if p.Method != "" {
+			method = p.Method
+		}
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO payments.product_price (product_id, method, currency, amount) VALUES ($1,$2,$3,$4)`,
+			id, method, string(p.Currency), p.Amount); err != nil {
+			return fmt.Errorf("insert price %s: %w", p.Currency, err)
+		}
+	}
+	return nil
+}
+
+// setProductActive flips the archived flag.
+func (s *Store) setProductActive(ctx context.Context, id uuid.UUID, active bool, now time.Time) error {
+	res, err := s.db.ExecContext(ctx,
+		`UPDATE payments.product SET active=$2, updated_at=$3 WHERE product_id=$1`, id, active, now)
+	if err != nil {
+		return fmt.Errorf("payments: set product active %s: %w", id, err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return ErrProductNotFound
+	}
+	return nil
+}
+
+// deleteProduct hard-deletes a never-transacted product (its items/prices cascade); a transacted
+// product is refused with ErrProductTransacted.
+func (s *Store) deleteProduct(ctx context.Context, id uuid.UUID) error {
+	transacted, err := s.productTransacted(ctx, id)
+	if err != nil {
+		return err
+	}
+	if transacted {
+		return ErrProductTransacted
+	}
+	res, err := s.db.ExecContext(ctx, `DELETE FROM payments.product WHERE product_id=$1`, id)
+	if err != nil {
+		return fmt.Errorf("payments: delete product %s: %w", id, err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return ErrProductNotFound
+	}
+	return nil
+}