Stage 9: Telegram integration (connector side-service, Mini App, out-of-app push)

New platform/telegram connector (own container, bot token only there):
- go-telegram/bot long-poll loop: /start deep-links + Mini App launch button.
- gRPC API pkg/proto/telegram/v1 (Telegram service): ValidateInitData, Notify
  (renders a localized message + deep-link button), SendToUser/SendToGameChannel
  (admin, wired in Stage 10). Generic methods are platform-agnostic (external_id).
- Bot API base override for Telegram's test environment; Dockerfile + compose
  (VPN sidecar, no public ingress); README.

Gateway:
- initData validation relocated from the gateway into the connector; the gateway
  calls ValidateInitData over gRPC (GATEWAY_CONNECTOR_ADDR), drops the bot token,
  and deletes internal/auth.
- Out-of-app push: runPushPump routes events whose recipient has no live in-app
  stream to connector.Notify, gated by /internal/push-target + the in-app-only
  flag (race-free de-dup); HasSubscribers added to the push hub.

Backend:
- Migration 00007 accounts.notifications_in_app_only (default true) + jetgen.
- ProvisionTelegram seeds a new account's language/display name from the launch
  fields; IdentityExternalID reverse lookup; /internal/push-target handler.

UI:
- Telegram Mini App launch: detect initData, apply themeParams, authTelegram,
  route the deep-link start_param (g/i/f); /telegram/ guard redirects outside
  Telegram. Vite relative base + telegram-web-app.js. In-app-only profile toggle;
  share-to-Telegram link for a friend code. Vitest + Playwright coverage.

Wire/docs/CI: fbs Profile/UpdateProfileRequest gain notifications_in_app_only
(Go + TS); go.work uses ./platform/telegram; go-unit.yaml covers it; PLAN,
ARCHITECTURE, FUNCTIONAL (+ru), UI_DESIGN, READMEs updated.

docs/ARCHITECTURE.md

@@ -43,9 +43,15 @@ Three executables plus per-platform side-services:
   a server-driven channel later, §10), and a client **board-style** setting (bonus-label
   mode). The visual/interaction design system is documented in
   [`UI_DESIGN.md`](UI_DESIGN.md).
-- **`platform/<name>`** *(planned)* — per-platform side-services (Telegram bot
-  first): deep-link invites and platform-native push notifications. They talk
-  to `backend` over an internal API.
+- **`platform/telegram`** — the Telegram side-service (the "connector", module
+  `scrabble/platform/telegram`). It is the only component holding the bot token: it
+  runs the Bot API long-poll loop (Mini App launch + `/start` deep-links) and serves
+  a gRPC API (`pkg/proto/telegram/v1`) that `gateway` (Mini App initData validation
+  and out-of-app push) and `backend` (admin messaging — Stage 10) call over the
+  trusted internal network. Its generic delivery methods are **platform-agnostic**
+  (keyed by the identity `external_id`), so a future VK/MAX connector reuses them; only
+  initData validation is Telegram-specific. It runs in its own container, egressing to
+  Telegram through a VPN sidecar.
 
 ```mermaid
 flowchart LR
@@ -55,7 +61,9 @@ flowchart LR
   Gateway -- in-app stream --> Client
   Backend -- pgx --> Postgres[(Postgres)]
   Backend -. embeds .- Solver[[scrabble-solver library]]
-  Telegram[Telegram bot side-service] -- internal API --> Backend
+  Gateway -- gRPC (validate initData, out-of-app push) --> Telegram[Telegram connector]
+  Backend -. admin gRPC, Stage 10 .-> Telegram
+  Telegram -- Bot API (via VPN sidecar) --> TgCloud((Telegram))
 ```
 
 The MVP runs `gateway` and `backend` as single-instance processes inside a
@@ -92,10 +100,12 @@ Platform-native, deliberately simple: **no Ed25519 client keys, no per-request
 signing, no anti-replay crypto** (these were considered and dropped — players
 arrive from a platform rather than completing a mandatory registration).
 
-- The gateway validates the originating credential **once** — the platform's
-  signed launch data (e.g. Telegram `initData` HMAC), an email-code login, or a
-  guest bootstrap — then mints a **thin opaque server session token**
-  (`session_id`).
+- The gateway validates the originating credential **once** — Telegram `initData`
+  (delegated to the connector's `ValidateInitData` RPC, which holds the bot token —
+  the HMAC secret — so it never reaches the gateway), an email-code login, or a guest
+  bootstrap — then mints a **thin opaque server session token** (`session_id`). First
+  Telegram contact seeds the new account's language (from the launch `language_code`)
+  and display name (§4).
 - The client holds `session_id` in memory for the app session (browser/OS
   storage is optional and may be unavailable; losing it means re-login).
 - The gateway caches `session → user_id` and injects `X-User-ID`. Session
@@ -318,7 +328,8 @@ requires (there is no DM surface; chat is per-game).
   keys are application-generated **UUIDv7**.
 - Tables: `accounts` (durable internal accounts; Stage 3 added the away-window
   columns `away_start`/`away_end` and the hint wallet `hint_balance`; Stage 6's
-  migration `00005` added the `is_guest` flag for ephemeral guest rows),
+  migration `00005` added the `is_guest` flag for ephemeral guest rows; Stage 9's
+  migration `00007` added the `notifications_in_app_only` out-of-app push toggle),
   `identities` (platform/email/robot identities, unique `(kind, external_id)`;
   Stage 5's migration `00004` admits the `robot` kind),
   `sessions` (revoke-only opaque-token hashes), the Stage 3 game tables
@@ -387,9 +398,16 @@ the backend and forwarded verbatim. A client that is not currently streaming fal
 back to the matchmaker's `Poll` for match-found and, for the lobby **notification
 badge** (incoming friend requests + open invitations), the client polls on lobby
 open and on focus as well as re-polling on the `notify` event — covering a push
-missed while the app was hidden. Out-of-app platform push (your-turn, nudge) is
-wired in Stage 9; session-revocation events and cursor-based stream resume are
-deferred (single-instance MVP).
+missed while the app was hidden. **Out-of-app platform push** (Stage 9) is a fallback
+the **gateway** routes from the same firehose: for an event whose recipient has **no
+live in-app stream** it resolves the backend `/internal/push-target` (their Telegram
+`external_id`, language, and the `notifications_in_app_only` flag) and asks the
+**Telegram connector** to deliver a localized message with a Mini App deep-link
+button — only when the recipient has a Telegram identity and has not confined
+notifications to the app, so the two channels never duplicate. The out-of-app set is
+your-turn, nudge, match-found and the invitation / friend-request notify sub-kinds;
+the connector renders the message and skips the rest. Session-revocation events and
+cursor-based stream resume stay deferred (single-instance MVP).
 
 A separate **announcements channel** feeds the client's one-line banner (UI_DESIGN.md).
 It is a client-side **mock** rotation today; a server-driven source (operational notices,
@@ -417,11 +435,12 @@ promotions) is future work and would deliver short markdown messages (text + lin
 | Concern | Enforced by |
 | --- | --- |
 | Public rate limiting / anti-abuse | gateway |
-| Platform credential validation, session minting | gateway |
+| Telegram initData validation (bot-token HMAC) | the Telegram connector; the gateway delegates it over gRPC, so the bot token lives only in the connector |
+| Session minting; email-code / guest validation | gateway (with backend) |
 | Session → `user_id` resolution, `X-User-ID` injection | gateway |
 | Authorisation, ownership, state transitions | backend (`X-User-ID` is the sole identity input) |
 | Admin authentication | gateway validates HTTP Basic Auth (`GATEWAY_ADMIN_*`), then reverse-proxies to backend admin endpoints |
-| backend ↔ gateway trust | the network (only gateway may reach backend) |
+| backend ↔ gateway ↔ connector trust | the network (only gateway may reach backend; the connector serves unauthenticated gRPC on the internal segment) |
 
 This is an explicit, accepted MVP risk: compromise of the gateway↔backend
 network segment defeats backend authentication. Mitigated by network isolation;
@@ -438,10 +457,15 @@ a dedicated redeem sub-limit or a longer code is the hardening step if abuse app
 
 ## 13. Deployment (informational)
 
-Single public origin, path-routed: the UI, the gateway public surface and the
-admin surface share one host that terminates TLS. MVP runs one `gateway`, one
-`backend`, one Postgres. Docker/compose environments are introduced when there
-is something to deploy.
+Single public origin, path-routed: a mini-landing at the root, the **Telegram Mini
+App under `/telegram/`** (the gateway serves the static UI build; outside Telegram
+that path redirects to the root), the gateway public surface and the admin surface
+share one host that terminates TLS. The **Telegram connector** runs as a separate
+container with **no public ingress** — it long-polls Telegram and egresses through a
+VPN sidecar, answering only internal gRPC. MVP runs one `gateway`, one `backend`, one
+Postgres, plus the connector. The connector's Docker/compose ships now
+(`platform/telegram/deploy`, mirroring `../15-puzzle`); the full multi-service deploy
+is Stage 12.
 
 ## 14. CI & branches