diff --git a/apps/server/drizzle/0001_destinations.sql b/apps/server/drizzle/0001_destinations.sql
index 0b1ae1e..8e60a40 100644
--- a/apps/server/drizzle/0001_destinations.sql
+++ b/apps/server/drizzle/0001_destinations.sql
@@ -1,4 +1,4 @@
--- Chapter 10 — Destinations + Subscriptions migration.
+-- Destinations + Subscriptions migration.
 --
 -- 1. Create `destinations` (named CRUD list).
 -- 2. Backfill destinations from each distinct `subscriptions.destination_chat_id`
diff --git a/apps/server/drizzle/0002_library_filters.sql b/apps/server/drizzle/0002_library_filters.sql
index e964c09..25f79f0 100644
--- a/apps/server/drizzle/0002_library_filters.sql
+++ b/apps/server/drizzle/0002_library_filters.sql
@@ -1,4 +1,4 @@
--- Chapter 11 — Library filters + M:N join.
+-- Library filters + M:N join.
 --
 -- Reusable named filter rules attachable to many subscriptions. The
 -- evaluator UNIONs these with per-sub filters at evaluation time.
diff --git a/apps/server/drizzle/0005_drop_tg_session.sql b/apps/server/drizzle/0005_drop_tg_session.sql
index a4d6c57..c98210e 100644
--- a/apps/server/drizzle/0005_drop_tg_session.sql
+++ b/apps/server/drizzle/0005_drop_tg_session.sql
@@ -2,7 +2,7 @@
 --
 -- Originally created in 0000 as an optional encrypted-at-rest cache for the
 -- gramjs StringSession. The MVP design ended up using `TG_SESSION_STRING`
--- from .env as the source of truth (see PLAN.md "Session storage"). The
+-- from .env as the source of truth. The
 -- table was never written to from app code, and `TG_SESSION_ENCRYPTION_KEY`
 -- — the env knob that would have driven AES around it — was removed in
 -- favour of plain env-only storage.
diff --git a/apps/server/drizzle/0007_filter_mode.sql b/apps/server/drizzle/0007_filter_mode.sql
index a591277..cdba104 100644
--- a/apps/server/drizzle/0007_filter_mode.sql
+++ b/apps/server/drizzle/0007_filter_mode.sql
@@ -1,12 +1,11 @@
--- Per-filter include/exclude mode (Ch 14).
+-- Per-filter include/exclude mode.
 --
 -- 'include' is the legacy AND-pass default — every include filter must match
 -- for the message to forward. 'exclude' inverts the rule for that one row:
 -- a message is rejected when its rule matches.
 --
--- The CHECK keeps hand-written rows honest (mirrors the precedent set by
--- `forward_log.status` and `library_filters.rule_type`). Existing rows
--- back-fill to 'include' via the DEFAULT, preserving prior behavior.
+-- The CHECK keeps hand-written rows honest. Existing rows back-fill to
+-- 'include' via the DEFAULT, preserving prior behavior.
 
 ALTER TABLE `subscription_filters` ADD COLUMN `mode` TEXT NOT NULL DEFAULT 'include' CHECK (`mode` IN ('include', 'exclude'));
 --> statement-breakpoint
diff --git a/apps/server/src/api/auth.ts b/apps/server/src/api/auth.ts
index a467cf4..110cbe9 100644
--- a/apps/server/src/api/auth.ts
+++ b/apps/server/src/api/auth.ts
@@ -1,25 +1,4 @@
-/**
- * Auth primitives for the API server.
- *
- * Single-user model. A successful `POST /api/auth/login` mints a fresh
- * opaque random token (256-bit, base64url), stores it in `web_sessions` with
- * an expiry, and sets a signed cookie carrying that token as the value.
- *
- * The signature exists for tamper detection; the *security* comes from the
- * token being unguessable and existing in the DB. Logout deletes the row,
- * so a leaked cookie can be revoked. Sliding refresh on each authed request
- * keeps the user signed in while limiting damage from a long-unused
- * captured cookie.
- *
- * `requireWebAuthEnv` parallels `tg/client.ts#requireTelegramEnv`. Both
- * `WEB_PASSWORD` and `SESSION_SECRET` stay `.optional()` in `config.ts`
- * so `pnpm db:migrate` and `pnpm tg:login` can run without them; only
- * the server boot path requires them.
- *
- * `verifyPassword` hashes both inputs to a fixed-size SHA-256 digest
- * before `timingSafeEqual` so password length isn't observable as a
- * timing signal and the equal-length precondition is automatic.
- */
+// Opaque 256-bit DB-backed token in a signed cookie (the token is the security; the signature is tamper detection); sliding refresh, server-side revoke.
 import { createHash, timingSafeEqual } from 'node:crypto';
 import type { CookieSerializeOptions } from '@fastify/cookie';
 import type { FastifyReply, FastifyRequest } from 'fastify';
@@ -35,7 +14,6 @@ export interface WebAuth {
   sessionSecret: string;
 }
 
-/** Bot token + admin allowlist for the Telegram Web App sign-in route. */
 export interface TelegramAuth {
   botToken: string;
   adminIds: string[];
@@ -58,10 +36,9 @@ export function requireWebAuthEnv(cfg: Config): WebAuth {
 }
 
 export function verifyPassword(plain: string, expected: string): boolean {
-  // Defensive: refuse to match empty/missing credentials even if upstream
-  // validation lets them through. SHA-256 of '' is a deterministic constant —
-  // without this guard, two empty strings would compare equal and grant entry.
+  // Reject empty: SHA-256('')==SHA-256('') would grant entry.
   if (!plain || !expected) return false;
+  // Hash both first so password length isn't a timing signal.
   const a = createHash('sha256').update(plain).digest();
   const b = createHash('sha256').update(expected).digest();
   return timingSafeEqual(a, b);
@@ -87,11 +64,7 @@ export function clearedCookieOptions(isProd: boolean): CookieSerializeOptions {
   };
 }
 
-/**
- * Read a session token from the incoming signed cookie, or null if absent /
- * tampered. Does NOT verify against the DB — the auth pre-handler does that
- * via `sessionStore.verifyAndRefresh`.
- */
+// Unwraps the signed cookie only; the DB check is verifyAndRefresh.
 export function readSessionToken(request: FastifyRequest): string | null {
   const raw = request.cookies[SESSION_COOKIE_NAME];
   if (!raw) return null;
@@ -102,11 +75,6 @@ export function readSessionToken(request: FastifyRequest): string | null {
   return result.value;
 }
 
-/**
- * Build the Fastify pre-handler that enforces auth on a scoped route plugin.
- * The factory takes the session store so the pre-handler closes over a real
- * DB-backed lookup; tests build their own via `buildTestApp`.
- */
 export function makeRequireAuth(sessionStore: SessionStore) {
   return async function requireAuth(request: FastifyRequest, _reply: FastifyReply): Promise<void> {
     const token = readSessionToken(request);
diff --git a/apps/server/src/api/errorHandler.ts b/apps/server/src/api/errorHandler.ts
index f905215..40b4ded 100644
--- a/apps/server/src/api/errorHandler.ts
+++ b/apps/server/src/api/errorHandler.ts
@@ -1,17 +1,4 @@
-/**
- * Single Fastify error handler.
- *
- * All errors thrown from route handlers, pre-handlers, and Fastify itself
- * pass through here. The mapping:
- *
- *   - `ZodError` (route handler called `schema.parse(body)` and it threw)
- *     → 400 with `{ code: 'validation_error', issues }`
- *   - `AppError` subclasses (`UnauthorizedError`, `NotFoundError`, ...)
- *     → `err.statusCode` with `{ code, message, ...(issues if ValidationError) }`
- *   - anything else → 500 generic; original message NOT echoed (no leaking
- *     of internal details). Logged with `request.log.error({ err })` for
- *     diagnosability.
- */
+// Single Fastify error handler: ZodError → 400, AppError → its statusCode, anything else → generic 500 with the original message never echoed.
 import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify';
 import { ZodError } from 'zod';
 import type { ErrorResponse } from '@tg-feed/shared';
@@ -48,10 +35,7 @@ export function makeErrorHandler(logger: Logger): ApiErrorHandler {
       return;
     }
 
-    // Fastify built-in errors (rate-limit, body too large, malformed JSON,
-    // etc.) carry an HTTP statusCode + a stable code. Pass 4xx through with
-    // their own message — they're already client-safe. 5xx still gets the
-    // generic 500 path below to avoid leaking internals.
+    // Fastify built-in 4xx (rate-limit, body too large, bad JSON) are client-safe; pass through. 5xx falls to the generic path.
     if (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 500) {
       const body: ErrorResponse = {
         error: { code: err.code ?? 'client_error', message: err.message },
diff --git a/apps/server/src/api/routes/_params.ts b/apps/server/src/api/routes/_params.ts
index 10534ad..2166e03 100644
--- a/apps/server/src/api/routes/_params.ts
+++ b/apps/server/src/api/routes/_params.ts
@@ -1,7 +1,4 @@
-/**
- * Shared route param schemas. The single-`id` shape is used by every CRUD
- * route; compound shapes live in their own route files.
- */
+// Shared by every CRUD route; compound param shapes live in their own route files.
 import { z } from 'zod';
 
 export const idParamsSchema = z.object({
diff --git a/apps/server/src/api/routes/auth.ts b/apps/server/src/api/routes/auth.ts
index 5f27d1e..ff5fae3 100644
--- a/apps/server/src/api/routes/auth.ts
+++ b/apps/server/src/api/routes/auth.ts
@@ -1,21 +1,3 @@
-/**
- * Auth routes.
- *
- * Split between two registration functions — `registerLoginRoute` for
- * the unauthenticated `POST /api/auth/login`, and `registerAuthRoutes`
- * for the authed-scope `POST /api/auth/logout` and `GET /api/me`. The
- * factory wires each into the appropriate Fastify scope.
- *
- * Login mints an opaque random token (256-bit, base64url) via the session
- * store and sets it as the signed cookie value. Logout deletes the row, so
- * a leaked cookie is revoked on the server — not just cleared on the
- * client. The login-route rate limit only counts failed attempts so a
- * legitimate user mid-debugging doesn't burn the brute-force bucket.
- *
- * `registerTelegramAuthRoute` is the Mini App counterpart: it verifies a
- * Telegram `initData` payload and, if the embedded user is on the admin
- * allowlist, mints a session via the same store as the password login.
- */
 import type { FastifyInstance, FastifyRequest } from 'fastify';
 import {
   loginRequestSchema,
@@ -48,11 +30,7 @@ export function registerLoginRoute(app: FastifyInstance, deps: RegisterLoginDeps
   app.post(
     '/auth/login',
     {
-      // Rate-limit brute-force on the single-user password. Counted per IP
-      // (trustProxy is enabled at the factory level so we key on the real
-      // client IP behind a reverse proxy). `skipOnError: true` and the
-      // `skipSuccessfulRequests`-equivalent below keep the bucket reserved
-      // for failed attempts only.
+      // Brute-force limit on the password, per real client IP; reset on success below so only failures count.
       config: {
         rateLimit: {
           max: 10,
@@ -69,15 +47,12 @@ export function registerLoginRoute(app: FastifyInstance, deps: RegisterLoginDeps
         );
         throw new UnauthorizedError('invalid password');
       }
-      // Successful login — reset the rate-limit bucket for this IP so a
-      // legitimate operator who logged in mid-debugging doesn't get throttled
-      // moments later. `request.rateLimit()` is provided by @fastify/rate-limit
-      // when the route's `config.rateLimit` is set.
+      // Reset the rate-limit bucket for this IP on success so only failures count.
       try {
         const rl = (request as FastifyRequest & { rateLimit?: () => Promise<unknown> }).rateLimit;
         if (typeof rl === 'function') await rl();
       } catch {
-        // Plugin not loaded (test path with custom server). Safe to ignore.
+        // Plugin not loaded (test path with custom server).
       }
       const token = deps.sessionStore.create();
       reply.setCookie(SESSION_COOKIE_NAME, token, signedCookieOptions(deps.isProd));
@@ -91,11 +66,7 @@ export function registerLoginRoute(app: FastifyInstance, deps: RegisterLoginDeps
 const TELEGRAM_INITDATA_MAX_AGE_SEC = 5 * 60;
 
 export interface RegisterTelegramAuthDeps {
-  /**
-   * Live getter for the bot auth config (token + admin allowlist), resolved
-   * DB-over-env. Read per request so a config change made via Settings → Bot
-   * applies without a restart. Yields null when the bot isn't configured.
-   */
+  // read per request (DB-over-env) so a Settings → Bot change applies without a restart; null when unconfigured
   getTelegramAuth: () => TelegramAuth | null;
   isProd: boolean;
   logger: Logger;
@@ -154,7 +125,7 @@ export function registerTelegramAuthRoute(
         const rl = (request as FastifyRequest & { rateLimit?: () => Promise<unknown> }).rateLimit;
         if (typeof rl === 'function') await rl();
       } catch {
-        // Plugin not loaded (test path with custom server). Safe to ignore.
+        // Plugin not loaded (test path with custom server).
       }
 
       const token = deps.sessionStore.create();
@@ -173,9 +144,7 @@ export interface RegisterAuthDeps {
 
 export function registerAuthRoutes(app: FastifyInstance, deps: RegisterAuthDeps): void {
   app.post('/auth/logout', async (request, reply) => {
-    // Read the token from the signed cookie before clearing it; deleting the
-    // server-side row is what actually invalidates the session (the cookie
-    // bytes are otherwise still valid until they expire client-side).
+    // Deleting the server-side row is what invalidates the session; the cookie bytes stay valid until expiry.
     const token = readSessionToken(request);
     if (token) deps.sessionStore.revoke(token);
     reply.clearCookie(SESSION_COOKIE_NAME, clearedCookieOptions(deps.isProd));
diff --git a/apps/server/src/api/routes/botConfig.ts b/apps/server/src/api/routes/botConfig.ts
index dfb9304..106b918 100644
--- a/apps/server/src/api/routes/botConfig.ts
+++ b/apps/server/src/api/routes/botConfig.ts
@@ -1,22 +1,4 @@
-/**
- * Bot configuration routes — Settings → Bot.
- *
- * GET    /api/config/bot                → masked state (sources, key status, botRunning)
- * PUT    /api/config/bot                → partial save (token / admins / publicUrl)
- * DELETE /api/config/bot                → clear the DB row, env fallback resumes
- * POST   /api/config/bot/resolve-admin  → resolve @username → user (preview, no write)
- *
- * The token is encrypted with `TG_SESSION_ENCRYPTION_KEY` before it touches
- * the DB, so a token write refuses with 412 when no key is configured (admins
- * and public URL are not gated). After any change `reloadBot()` live-swaps the
- * long-polling bot so the new config takes effect without a restart. The GET
- * payload is masked — it never returns the token, only whether one exists and
- * from where.
- *
- * `resolve-admin` turns a `@username` into a user id via the universal chat
- * resolver (rejecting channels/groups); the resolved `{ id, displayName,
- * username }` is then saved into `admins`.
- */
+// Token encrypted with TG_SESSION_ENCRYPTION_KEY (token write 412s without a key); GET is masked, never returns the token.
 import type { FastifyInstance } from 'fastify';
 import {
   type BotAdmin,
@@ -36,22 +18,16 @@ import { BOT_TOKEN_AAD, encryptSecret } from '../../lib/sessionCrypto.js';
 import type { ChatResolver } from '../../tg/chatResolver.js';
 
 export interface RegisterBotConfigRoutesDeps {
-  /** Parsed env config — supplies the env fallbacks behind the masked view. */
+  // Supplies the env fallbacks behind the masked view.
   cfg: Config;
   db: Db;
-  /** Returns the configured 32-byte key, or null when unset. */
+  // 32-byte key, or null when unset.
   getEncryptionKey?: () => Buffer | null;
-  /** Live-swaps the bot so a saved config takes effect immediately. */
   reloadBot?: () => Promise<void>;
-  /** Whether the long-polling bot is currently running. */
   getBotRunning?: () => boolean;
-  /**
-   * Lazy lookup for the universal chat resolver — reused by `resolve-admin`
-   * to turn a `@username` into a user id. Read per request (populated after
-   * Telegram init). When absent, the route returns 503.
-   */
+  // Lazy (populated after Telegram init), read per request; absent → 503.
   getChatResolver?: () => ChatResolver | undefined;
-  /** Telegram lifecycle — picks the right 503 (`initializing` vs `unavailable`). */
+  // Picks the right 503: `initializing` vs `unavailable`.
   getTelegramStatus: () => TelegramStatus;
 }
 
@@ -112,8 +88,7 @@ export function registerBotConfigRoutes(
 
     writeBotConfig(db, patch);
     if (reloadBot) {
-      // Live-swap failures are logged inside `reloadBot`; the row is already
-      // saved, so the next restart picks it up. Don't fail the save.
+      // Row is already saved; don't fail the save on a live-swap error (logged in reloadBot).
       await reloadBot().catch(() => {});
     }
     return info();
@@ -134,8 +109,7 @@ export function registerBotConfigRoutes(
     }
     const body = resolveBotAdminRequestSchema.parse(request.body);
     const resolved = await chatResolver(body.query);
-    // Admins are *users* — a bare positive id. Channels/supergroups resolve to
-    // a `-100…` id and unjoined private invites to null; reject both.
+    // Admins are users (bare positive id); reject `-100…` channels/groups and null invites.
     if (!resolved.chatId || resolved.chatId.startsWith('-')) {
       throw new AppError(
         422,
diff --git a/apps/server/src/api/routes/destinations.ts b/apps/server/src/api/routes/destinations.ts
index efc0b5a..86d919d 100644
--- a/apps/server/src/api/routes/destinations.ts
+++ b/apps/server/src/api/routes/destinations.ts
@@ -1,10 +1,4 @@
-/**
- * Destinations CRUD routes (Chapter 10).
- *
- * Destinations are the named CRUD list subscriptions pick from. Delete is
- * pre-checked for usage in this layer; the FK is `ON DELETE RESTRICT` as a
- * belt-and-suspenders DB-level guard.
- */
+// Delete is usage-checked here; the FK is also ON DELETE RESTRICT as a DB-level guard.
 import { asc, count, eq } from 'drizzle-orm';
 import type { FastifyInstance } from 'fastify';
 import {
@@ -49,36 +43,12 @@ interface DestinationRow {
 
 export interface RegisterDestinationDeps {
   db: Db;
-  /**
-   * Live status getter used to distinguish "Telegram is starting up — try
-   * again in a moment" from "Telegram is not configured at all". Drives
-   * the error code returned when a tg-dep getter yields undefined.
-   */
   getTelegramStatus: () => TelegramStatus;
-  /**
-   * Lazy lookup for the universal "paste-anything" resolver — backs
-   * `POST /destinations/resolve`. Read per request because the boot path
-   * fills it asynchronously after `app.listen()`. When undefined the
-   * route returns 503 with `telegram_initializing` (during the boot
-   * window) or `telegram_unavailable` (steady-state disconnected).
-   */
+  // Lazy getters: filled after app.listen(), so read per request. Undefined → 503.
   getChatResolver?: () => ChatResolver | undefined;
-  /**
-   * Lazy lookup for the `messages.ImportChatInvite` wrapper invoked from
-   * `POST /destinations` when the body carries `inviteHash`. Same
-   * lifecycle as `getChatResolver`.
-   */
   getImportInvite?: () => ImportInviteFn | undefined;
-  /**
-   * Lazy lookup for the best-effort profile-photo fetcher invoked after
-   * the row is inserted. When undefined the row's `iconDataUrl` stays
-   * null and the access monitor's lazy backfill catches it later.
-   */
+  // Undefined leaves iconDataUrl null; the access monitor backfills it later.
   getFetchProfilePhoto?: () => ProfilePhotoFetcher | undefined;
-  /**
-   * Lazy lookup for the forum-topic lister backing `POST /destinations/topics`.
-   * Same lifecycle as `getChatResolver`. When undefined the route returns 503.
-   */
   getListForumTopics?: () => ForumTopicLister | undefined;
 }
 
@@ -146,8 +116,7 @@ export function registerDestinationRoutes(
         throw new UpstreamError('failed to join via invite link', 'invite_join_failed');
       }
       chatId = join.chatId;
-      // We just successfully joined — record access ok now so the access
-      // monitor's first sweep doesn't briefly mis-report.
+      // Just joined — record access ok so the monitor's first sweep doesn't mis-report.
       initialAccessStatus = 'ok';
       accessCheckedAt = new Date();
     } else {
@@ -168,9 +137,7 @@ export function registerDestinationRoutes(
       .returning()
       .all();
     const row = inserted[0]!;
-    // Best-effort: fetch the profile photo and stamp it on the row. The
-    // fetcher already swallows errors and returns null on failure, so we
-    // don't need a try/catch — the response just goes out without an icon.
+    // Best-effort icon: the fetcher swallows errors and returns null.
     let iconDataUrl: string | null = row.iconDataUrl;
     const fetchProfilePhoto = getFetchProfilePhoto?.();
     if (fetchProfilePhoto) {
@@ -244,8 +211,6 @@ export function registerDestinationRoutes(
 }
 
 function listDestinations(db: Db): DestinationRow[] {
-  // One query: destinations LEFT JOIN subscriptions GROUP BY destination,
-  // counting subscription references.
   const rows = db
     .select({
       id: destinations.id,
diff --git a/apps/server/src/api/routes/filters.ts b/apps/server/src/api/routes/filters.ts
index 341fcf3..3c66bda 100644
--- a/apps/server/src/api/routes/filters.ts
+++ b/apps/server/src/api/routes/filters.ts
@@ -1,20 +1,5 @@
-/**
- * Filter routes — catalog + per-subscription filter CRUD.
- *
- * The catalog (`GET /api/filters/catalog`) reflects what's actually
- * registered in the live filter registry — not a hardcoded list. Adding
- * a rule = drop a file + register it in `createDefaultRegistry()`; the
- * catalog endpoint picks it up on next restart.
- *
- * Filter PATCH validates `params` against the EXISTING row's `ruleType`
- * (rule type itself is immutable post-creation; to switch, delete and
- * re-add). The shared schema's `updateSubscriptionFilterRequestSchema`
- * keeps `params` loose (`z.record`); strict per-rule validation happens
- * here in the handler.
- *
- * Cross-sub access (filter id belongs to a different sub than the URL
- * names) returns 404 — prevents id-guessing across subscriptions.
- */
+// ruleType is immutable; PATCH validates params against the existing row's ruleType.
+// Cross-sub filter ids return 404 to block id-guessing across subscriptions.
 import { and, asc, eq } from 'drizzle-orm';
 import type { FastifyInstance } from 'fastify';
 import { z } from 'zod';
diff --git a/apps/server/src/api/routes/forwardLog.ts b/apps/server/src/api/routes/forwardLog.ts
index 7b4f049..63d140e 100644
--- a/apps/server/src/api/routes/forwardLog.ts
+++ b/apps/server/src/api/routes/forwardLog.ts
@@ -1,24 +1,5 @@
-/**
- * Forward log route — paginated activity feed source.
- *
- * Two LEFT JOINs: `forward_log → subscriptions → destinations`. The
- * subscription FK is `ON DELETE SET NULL`, so historic rows for deleted
- * subscriptions survive with `subscriptionId`/`subscriptionTitle`/
- * `sourceHandle`/`destinationName` all `null`. The destination join hops
- * through the subscription's current `destinationId` — `forward_log`
- * doesn't store the destination, so a re-pointed subscription will surface
- * its current destination on historical rows (matches the prior
- * client-side enrichment behavior).
- *
- * Pagination uses the `limit + 1` trick: fetch one row past the asked
- * `limit`, then if the extra row is present `nextOffset = offset + limit`,
- * else `nextOffset = null`. Avoids a separate `COUNT(*)` query while still
- * answering "is there more?".
- *
- * Sort is `desc(createdAt), desc(id)` — albums write N rows in one
- * transaction sharing a `createdAt` ms; sorting by `id` as a tiebreaker
- * makes pagination deterministic across calls.
- */
+// Paginated activity feed. Sub FK is ON DELETE SET NULL, so rows for deleted subs survive with null titles; the dest join hops through the sub's current destinationId, so re-pointing surfaces the new dest on old rows.
+// Pagination is the limit+1 trick (one row past limit → nextOffset, else null), avoiding a COUNT(*). Sort desc(createdAt),desc(id) so albums sharing a createdAt ms paginate deterministically.
 import { desc, eq, sql } from 'drizzle-orm';
 import type { FastifyInstance } from 'fastify';
 import { z } from 'zod';
@@ -55,10 +36,7 @@ export function registerForwardLogRoutes(app: FastifyInstance, deps: RegisterFor
         status: forwardLog.status,
         error: forwardLog.error,
         createdAt: forwardLog.createdAt,
-        // Surface presence-only here; the raw JSON itself is fetched on
-        // demand via the dedicated /:id/raw route so list responses stay
-        // small. SQLite renders the boolean as `1`/`0` which the cast
-        // below normalises for the wire format.
+        // Presence only (raw JSON is fetched via /:id/raw); SQLite returns 1/0.
         hasRawMessage: sql<number>`(${forwardLog.rawMessage} IS NOT NULL)`,
       })
       .from(forwardLog)
@@ -90,10 +68,7 @@ export function registerForwardLogRoutes(app: FastifyInstance, deps: RegisterFor
     return response;
   });
 
-  // Deferred-fetch endpoint for the raw JSON snapshot. Kept off the list
-  // route so a page load doesn't drag tens of KB per row over the wire —
-  // the JSON is only useful when the user clicks "View raw" on a specific
-  // entry, and an album's array is identical across its N rows anyway.
+  // Deferred raw-JSON fetch, off the list route so page loads don't drag tens of KB per row.
   app.get('/forward-log/:id/raw', async (request, reply) => {
     const { id } = rawParamsSchema.parse(request.params);
     const row = db
diff --git a/apps/server/src/api/routes/health.test.ts b/apps/server/src/api/routes/health.test.ts
new file mode 100644
index 0000000..b0239af
--- /dev/null
+++ b/apps/server/src/api/routes/health.test.ts
@@ -0,0 +1,28 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildTestApp, type TestApp } from '../testing.js';
+
+describe('GET /api/health', () => {
+  let testApp: TestApp;
+  beforeEach(async () => {
+    testApp = await buildTestApp();
+  });
+  afterEach(async () => {
+    await testApp.close();
+  });
+
+  it('returns 200 + { status: ok } without authentication', async () => {
+    const res = await testApp.app.inject({ method: 'GET', url: '/api/health' });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ status: 'ok' });
+    // Public route — it must not mint or require a session.
+    expect(res.headers['set-cookie']).toBeUndefined();
+  });
+
+  it('returns 503 + { status: error } when the database is unreachable', async () => {
+    // Drop the underlying SQLite connection so the `select 1` ping throws.
+    testApp.dbHandle.close();
+    const res = await testApp.app.inject({ method: 'GET', url: '/api/health' });
+    expect(res.statusCode).toBe(503);
+    expect(res.json()).toEqual({ status: 'error' });
+  });
+});
diff --git a/apps/server/src/api/routes/health.ts b/apps/server/src/api/routes/health.ts
new file mode 100644
index 0000000..f84142f
--- /dev/null
+++ b/apps/server/src/api/routes/health.ts
@@ -0,0 +1,22 @@
+// Unauthenticated on purpose (container/proxy probe, not the web client); `select 1` gives a real 503 not-ready signal.
+import { sql } from 'drizzle-orm';
+import type { FastifyInstance } from 'fastify';
+import type { Db } from '../../db/client.js';
+import type { Logger } from '../../lib/logger.js';
+
+export interface RegisterHealthDeps {
+  db: Db;
+  logger: Logger;
+}
+
+export function registerHealthRoute(app: FastifyInstance, deps: RegisterHealthDeps): void {
+  app.get('/health', async (_request, reply) => {
+    try {
+      deps.db.get(sql`select 1`);
+    } catch (err) {
+      deps.logger.error({ err }, 'health: database ping failed');
+      return reply.status(503).send({ status: 'error' });
+    }
+    return { status: 'ok' };
+  });
+}
diff --git a/apps/server/src/api/routes/libraryFilters.test.ts b/apps/server/src/api/routes/libraryFilters.test.ts
index 09ff3e4..e214e2c 100644
--- a/apps/server/src/api/routes/libraryFilters.test.ts
+++ b/apps/server/src/api/routes/libraryFilters.test.ts
@@ -74,6 +74,20 @@ describe('library filter routes', () => {
     expect(res.statusCode).toBe(400);
   });
 
+  it('POST /api/library-filters rejects an uncompilable text-regex pattern', async () => {
+    const res = await testApp.app.inject({
+      method: 'POST',
+      url: '/api/library-filters',
+      headers: { cookie },
+      payload: {
+        name: 'bad regex',
+        ruleType: 'text-regex',
+        params: { pattern: '(', flags: '' },
+      },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
   it('GET /api/library-filters carries usageCount via JOIN', async () => {
     const [lib] = testApp.db
       .insert(libraryFilters)
diff --git a/apps/server/src/api/routes/libraryFilters.ts b/apps/server/src/api/routes/libraryFilters.ts
index b9d1fb7..a0841a4 100644
--- a/apps/server/src/api/routes/libraryFilters.ts
+++ b/apps/server/src/api/routes/libraryFilters.ts
@@ -1,16 +1,3 @@
-/**
- * Library filter CRUD routes (Chapter 11).
- *
- * Reusable named filter rules attachable to many subscriptions via the
- * `subscription_library_filters` join table. Delete is pre-checked for
- * usage with a 409 `library_filter_in_use` error; the FK is `ON DELETE
- * RESTRICT` as a belt-and-suspenders DB-level guard.
- *
- * `ruleType` is immutable post-creation (matches the per-sub filter
- * convention from Ch 7); to change it, delete and re-add. PATCH bodies
- * with `params` are revalidated against the existing row's `ruleType`
- * via the matching `filterRuleParamsSchemas` entry.
- */
 import { asc, count, eq } from 'drizzle-orm';
 import type { FastifyInstance } from 'fastify';
 import {
@@ -25,6 +12,7 @@ import type { Db } from '../../db/client.js';
 import { libraryFilters, subscriptionLibraryFilters } from '../../db/schema.js';
 import { countWhere } from '../../lib/dbHelpers.js';
 import { ConflictError, NotFoundError, ValidationError } from '../../lib/errors.js';
+import { assertFilterParamsCompilable } from '../../filters/validateParams.js';
 import { idParamsSchema } from './_params.js';
 
 interface LibraryFilterRow {
@@ -55,6 +43,7 @@ export function registerLibraryFilterRoutes(
 
   app.post('/library-filters', async (request, reply) => {
     const body = createLibraryFilterRequestSchema.parse(request.body);
+    assertFilterParamsCompilable(body.ruleType, body.params);
     const inserted = db
       .insert(libraryFilters)
       .values({
@@ -81,8 +70,7 @@ export function registerLibraryFilterRoutes(
   app.patch('/library-filters/:id', async (request) => {
     const { id } = idParamsSchema.parse(request.params);
     const body = updateLibraryFilterRequestSchema.parse(request.body);
-    // Need existing.ruleType to validate body.params against the matching
-    // params schema — ruleType is immutable post-creation.
+    // ruleType is immutable; needed to pick the params schema for validation.
     const existing = db.select().from(libraryFilters).where(eq(libraryFilters.id, id)).get();
     if (!existing) throw new NotFoundError('library filter');
 
@@ -94,6 +82,7 @@ export function registerLibraryFilterRoutes(
         throw new ValidationError('invalid params for rule type', result.error.issues);
       }
       validatedParams = result.data;
+      assertFilterParamsCompilable(existing.ruleType, validatedParams);
     }
 
     const updated = db
diff --git a/apps/server/src/api/routes/settings.ts b/apps/server/src/api/routes/settings.ts
index 67d5ec5..0483e90 100644
--- a/apps/server/src/api/routes/settings.ts
+++ b/apps/server/src/api/routes/settings.ts
@@ -1,18 +1,4 @@
-/**
- * Settings routes.
- *
- * Wire format is the flat `{ delayMs, albumDebounceMs }`; internally this
- * maps to the `app_settings` row keyed `'global'` whose `value` JSON is the
- * same shape. PUT accepts a partial body (either field optional) and merges
- * into the existing row, so the UI can edit one knob at a time without
- * round-tripping the other.
- *
- * `GET` never 404s. If the row is missing or malformed, fall back to the
- * documented defaults (8 s throttle, 2 s album window) — same defensive
- * read the forwarding pipeline does in `getGlobalDelayMs` /
- * `getAlbumDebounceMs`. Settings always exist with sane defaults from the
- * client's perspective.
- */
+// GET never 404s: a missing/malformed row falls back to the same defaults the forwarding pipeline uses.
 import type { FastifyInstance } from 'fastify';
 import { updateSettingsRequestSchema, type SettingsDto } from '@tg-feed/shared';
 import type { Db } from '../../db/client.js';
@@ -49,10 +35,7 @@ export function registerSettingsRoutes(app: FastifyInstance, deps: RegisterSetti
 
   app.put('/settings', async (request) => {
     const body = updateSettingsRequestSchema.parse(request.body);
-    // Merge: read current values (with defaults for missing/malformed rows),
-    // overlay any fields the client supplied, write the unified row back. The
-    // throttle and digest knobs share this one row, so the merge keeps a
-    // caller that only knows about one of them from clobbering the others.
+    // Throttle and digest knobs share one row; merge so a partial body doesn't clobber the others.
     const digest = getStatsDigestConfig(db);
     const merged = {
       delayMs: body.delayMs ?? getGlobalDelayMs(db),
diff --git a/apps/server/src/api/routes/stream.ts b/apps/server/src/api/routes/stream.ts
index 8749976..e5b29be 100644
--- a/apps/server/src/api/routes/stream.ts
+++ b/apps/server/src/api/routes/stream.ts
@@ -1,42 +1,7 @@
-/**
- * SSE stream — `GET /api/stream`.
- *
- * One persistent text/event-stream per authenticated client. The route
- * subscribes to the in-process `EventBus` and pipes every emitted event to
- * the socket as a single SSE frame; a `: heartbeat` comment frame goes out
- * every 25 s so reverse proxies and Telegram-paranoid networks don't decide
- * the idle connection is dead.
- *
- * Hardening (added during the security pass):
- *   - **Per-session connection cap.** A single authed cookie can hold at
- *     most `MAX_CONNECTIONS_PER_TOKEN` streams open at once; further
- *     attempts get a clean 429. Without the cap a stolen cookie or a
- *     misbehaving extension could open thousands of streams and pin event-
- *     loop time on every bus emit (the bus walks every listener O(N)).
- *   - **Backpressure-aware writes.** `socket.write` returns false when the
- *     OS send buffer fills; if we ignore that, a slow consumer accumulates
- *     unbounded data in node's internal write buffer. We drop events while
- *     backpressured and resume on the next `'drain'`. This loses fidelity
- *     for very slow clients (intentional) but never OOMs the process.
- *
- * Implementation notes:
- *   - `reply.hijack()` tells Fastify "I'm taking over the response — don't
- *     try to call .send() or .end() yourself." After hijack the handler
- *     owns `reply.raw` (the underlying `http.ServerResponse`). We never
- *     return data via `reply.send`; everything goes via `socket.write`.
- *   - The handler resolves immediately after wiring listeners. Without
- *     `hijack` Fastify would call `.end()` on return; with it the
- *     connection stays open until the client disconnects.
- *   - `request.raw.once('close')` fires whether the client gracefully
- *     closes the EventSource, the network drops, or the test aborts via
- *     `AbortController`. That's where the heartbeat interval is cleared
- *     and the bus listener is unsubscribed — no per-client leak.
- *   - `socket.writableEnded` guards the listener and the heartbeat against
- *     a write-after-close race. The actual safety net is the per-listener
- *     try/catch inside the bus, which logs and swallows any thrown errors.
- *   - `X-Accel-Buffering: no` disables nginx response buffering for SSE
- *     (`Cache-Control: no-cache, no-transform` covers most other proxies).
- */
+// GET /api/stream: one text/event-stream per client piping every EventBus event; `: heartbeat` every 25s so proxies don't reap idle connections.
+// Connection cap (429 past MAX_CONNECTIONS_PER_TOKEN): a stolen cookie could otherwise open thousands of streams and pin the O(N) bus walk.
+// Backpressure: drop events while socket.write is false, resume on 'drain' — loses fidelity for slow clients but never OOMs.
+// reply.hijack() stops Fastify calling .end() on return so the connection stays open until close.
 import type { FastifyInstance } from 'fastify';
 import type { EventBus } from '../../events/bus.js';
 import { readSessionToken } from '../auth.js';
@@ -46,21 +11,13 @@ const MAX_CONNECTIONS_PER_TOKEN = 4;
 
 export interface RegisterStreamDeps {
   bus: EventBus;
-  /**
-   * Override the heartbeat interval for tests. Real timers + a small value
-   * (e.g. 50 ms) is more reliable than fake-timer-driven heartbeat tests
-   * because `light-my-request` chunk delivery is `process.nextTick`-driven,
-   * which races with `vi.advanceTimersByTimeAsync`.
-   */
   heartbeatMs?: number;
 }
 
 export function registerStreamRoutes(app: FastifyInstance, deps: RegisterStreamDeps): void {
   const { bus } = deps;
   const heartbeatMs = deps.heartbeatMs ?? SSE_HEARTBEAT_MS;
-  // Per-token open-connection counter. Lives in module scope so each Fastify
-  // factory instance gets its own map (tests build fresh instances per
-  // `beforeEach`, so no cross-test bleed).
+  // Scoped per factory instance so fresh test instances don't bleed across each other.
   const openByToken = new Map<string, number>();
 
   app.get('/stream', (request, reply) => {
@@ -85,13 +42,9 @@ export function registerStreamRoutes(app: FastifyInstance, deps: RegisterStreamD
       Connection: 'keep-alive',
       'X-Accel-Buffering': 'no',
     });
-    // Initial flush so the client sees the stream is live before the first
-    // real event (which may be many seconds away).
+    // Initial flush so the client sees the stream is live before the first real event.
     socket.write(': open\n\n');
 
-    // Backpressure: when `socket.write` returns false, the kernel send
-    // buffer is full and node's internal `writable` buffer would start
-    // growing without bound. Drop events until the socket emits `'drain'`.
     let backpressured = false;
     socket.on('drain', () => {
       backpressured = false;
diff --git a/apps/server/src/api/routes/subscriptions.ts b/apps/server/src/api/routes/subscriptions.ts
index 96319a6..f7a06c0 100644
--- a/apps/server/src/api/routes/subscriptions.ts
+++ b/apps/server/src/api/routes/subscriptions.ts
@@ -1,37 +1,3 @@
-/**
- * Subscription CRUD + resolve routes.
- *
- * `sourceChatId` and `handle` are immutable post-creation (matches the
- * shared schema's `updateSubscriptionRequestSchema`); to change the source
- * channel, delete and recreate.
- *
- * DELETE returns 204 No Content (REST convention). Cascades down to
- * `subscription_filters` and `subscription_library_filters` (Ch 11);
- * `forward_log` rows survive with `subscriptionId` set to NULL via
- * `ON DELETE SET NULL` (Ch 2).
- *
- * The resolve endpoint is preview-only — it never writes to the DB. The
- * UI submits the resolved fields back to POST /subscriptions to commit.
- * Routes that need the gramjs entity resolver gate on its presence and
- * return 503 — `telegram_initializing` while the Telegram subsystem is
- * still bootstrapping (background init in `apps/server/src/index.ts`),
- * `telegram_unavailable` once it's settled in a disconnected state (test
- * mode, missing Telegram env). The web UI keys on the code: the first is
- * a transient retry; the second points the operator at configuration.
- *
- * Library filter attachments are exposed two ways:
- * - bulk-replace via `libraryFilterIds` on POST/PATCH /subscriptions[/:id]
- *   (used by the SubSheet's checkbox group)
- * - granular at POST /:id/library-filters and DELETE /:id/library-filters/:libId
- *   (used by the per-sub Filters view's `+` and `X` buttons)
- *
- * Inline (private) filters work the same way: bulk-replace via
- * `inlineFilters` on POST/PATCH /subscriptions[/:id], plus the granular
- * CRUD at /:id/filters[/:filterId] in `filters.ts`. Both library and
- * inline writes happen inside a single `db.transaction(...)` so a partial
- * failure can't leave the subscription with one set replaced and the other
- * untouched.
- */
 import { and, asc, eq, inArray, sql } from 'drizzle-orm';
 import type { FastifyInstance } from 'fastify';
 import { z } from 'zod';
@@ -56,6 +22,7 @@ import {
   subscriptions,
 } from '../../db/schema.js';
 import type { EventBus } from '../../events/bus.js';
+import { assertFilterParamsCompilable } from '../../filters/validateParams.js';
 import {
   InternalError,
   NotFoundError,
@@ -69,9 +36,6 @@ import type { JoinChannelFn } from '../../tg/joinChannel.js';
 import type { ProfilePhotoFetcher } from '../../tg/profilePhoto.js';
 import { idParamsSchema } from './_params.js';
 
-// `db.transaction(cb)` passes `cb` a tx handle whose query interface matches
-// `Db`'s, but its TS type is the more specific `SQLiteTransaction`. Helpers
-// that need to run under either branch take this union.
 type DbOrTx = Db | Parameters<Parameters<Db['transaction']>[0]>[0];
 
 const libraryFilterAttachmentParamsSchema = z.object({
@@ -82,38 +46,14 @@ const libraryFilterAttachmentParamsSchema = z.object({
 export interface RegisterSubscriptionDeps {
   db: Db;
   bus: EventBus;
-  /**
-   * Live status getter used to distinguish "Telegram is starting up — try
-   * again in a moment" from "Telegram is not configured at all". Drives
-   * the error code returned when a tg-dep getter yields undefined.
-   */
+  // Distinguishes "starting up" from "not configured" for the tg-dep error code.
   getTelegramStatus: () => TelegramStatus;
-  /**
-   * Lazy lookup for the universal "paste-anything" resolver — backs
-   * `POST /subscriptions/resolve`. Read per request because the boot path
-   * fills it asynchronously after `app.listen()`. Accepts any of:
-   * `@username`, `t.me/username`, `t.me/+HASH`, `+HASH`, or numeric chat id.
-   */
+  // Lazy getters: boot fills them asynchronously after `app.listen()`, so read per request.
   getChatResolver?: () => ChatResolver | undefined;
-  /**
-   * Lazy lookup for the `messages.ImportChatInvite` wrapper invoked from
-   * `POST /subscriptions` when the body carries `inviteHash`. Same
-   * lifecycle as `getChatResolver`.
-   */
   getImportInvite?: () => ImportInviteFn | undefined;
-  /**
-   * Lazy lookup for the auto-join helper invoked after a successful
-   * POST /subscriptions insert (chatId path). When the getter yields
-   * undefined the row keeps the default 'ok' status and the access
-   * monitor's first sweep corrects it. The `inviteHash` path bypasses
-   * this — `importInvite` already joined.
-   */
+  // undefined => keep default status; access monitor's first sweep corrects it.
   getJoinChannel?: () => JoinChannelFn | undefined;
-  /**
-   * Lazy lookup for the best-effort profile-photo fetcher invoked after
-   * the row is inserted. When undefined the row's `iconDataUrl` stays
-   * null and the access monitor's lazy backfill catches it later.
-   */
+  // undefined => iconDataUrl stays null; access monitor backfills later.
   getFetchProfilePhoto?: () => ProfilePhotoFetcher | undefined;
 }
 
@@ -156,9 +96,7 @@ export function registerSubscriptionRoutes(
 
   app.post('/subscriptions', async (request, reply) => {
     const body = createSubscriptionRequestSchema.parse(request.body);
-    // `destinationId` is now optional/nullable — only validate when provided.
-    // FK SET NULL would coalesce a bad id silently, so we still 400 up-front
-    // for a missing one to surface a clear UI message.
+    // FK SET NULL would coalesce a bad id silently; 400 up-front for a clear UI message.
     if (body.destinationId !== undefined && body.destinationId !== null) {
       const dest = db
         .select()
@@ -170,13 +108,7 @@ export function registerSubscriptionRoutes(
     if (body.libraryFilterIds && body.libraryFilterIds.length > 0) {
       assertLibraryFiltersExist(db, body.libraryFilterIds);
     }
-    // Source==destination guard. A subscription whose source chat id is also
-    // a destination chat id would forward into itself: the bot's own forwards
-    // would (via the history poller, which bypasses the `incoming:true`
-    // filter on the live listener) be re-ingested and forwarded again on the
-    // next sweep, ad infinitum. Reject up-front; safe to skip when the body
-    // uses an `inviteHash` since we don't know the chat id until after join,
-    // and the post-join shape is checked below.
+    // source==destination = forwarding loop (poller re-ingests own forwards); inviteHash re-checked post-join below.
     if (body.sourceChatId !== undefined) {
       const conflict = db
         .select({ id: destinations.id })
@@ -190,10 +122,7 @@ export function registerSubscriptionRoutes(
       }
     }
 
-    // Resolve the source chat id from either the resolved id (existing flow)
-    // or by joining via invite hash (new flow). The hash path is destructive
-    // and runs *before* the insert so a join failure doesn't leave a
-    // half-baked row behind.
+    // Invite-hash join is destructive; run it before the insert so a failure leaves no half-baked row.
     let sourceChatId: string;
     let preJoined = false;
     if (body.inviteHash) {
@@ -210,11 +139,7 @@ export function registerSubscriptionRoutes(
     } else {
       sourceChatId = body.sourceChatId!;
     }
-    // Re-check post-resolve in case the invite path landed on a chat that is
-    // already a destination. (Same loop-prevention rationale as above.) We
-    // intentionally don't undo the join — at this point the bot has joined
-    // the channel; the operator just can't use it as a subscription with
-    // that destination configuration.
+    // Re-check post-resolve for the loop guard; the join is intentionally not undone.
     {
       const conflict = db
         .select({ id: destinations.id })
@@ -249,12 +174,8 @@ export function registerSubscriptionRoutes(
       }
       return row.id;
     });
-    // For the chatId path: auto-join the source channel so the userbot
-    // starts receiving its events. Done outside the transaction (gramjs
-    // network I/O can't be atomic with SQLite) and before the SSE emit so
-    // the DTO read by the UI carries the post-join status.
+    // Outside the tx (gramjs I/O isn't atomic with SQLite) and before the SSE emit so the DTO carries post-join status.
     if (preJoined) {
-      // Already joined via importInvite; just stamp the access check.
       db.update(subscriptions)
         .set({ sourceAccessStatus: 'ok', sourceAccessCheckedAt: new Date() })
         .where(eq(subscriptions.id, newId))
@@ -269,10 +190,7 @@ export function registerSubscriptionRoutes(
           .run();
       }
     }
-    // Best-effort profile photo fetch. Same reasoning as on the
-    // destination create path: the fetcher swallows errors and returns
-    // null, so failure means the row stays icon-less until the access
-    // monitor's lazy backfill kicks in.
+    // Best-effort; fetcher swallows errors, so the row stays icon-less until backfill.
     const fetchProfilePhoto = getFetchProfilePhoto?.();
     if (fetchProfilePhoto) {
       const iconDataUrl = await fetchProfilePhoto(sourceChatId);
@@ -334,7 +252,6 @@ export function registerSubscriptionRoutes(
     return null;
   });
 
-  /** Granular attach — backs the per-sub view's `+ library filter` action. */
   app.post('/subscriptions/:id/library-filters', async (request, reply) => {
     const { id } = idParamsSchema.parse(request.params);
     const body = attachLibraryFilterRequestSchema.parse(request.body);
@@ -361,7 +278,6 @@ export function registerSubscriptionRoutes(
     return dto;
   });
 
-  /** Granular detach — the design's "X" button on attached library chips. */
   app.delete('/subscriptions/:id/library-filters/:libId', async (request, reply) => {
     const { id, libId } = libraryFilterAttachmentParamsSchema.parse(request.params);
     const result = db
@@ -429,10 +345,7 @@ export function replaceLibraryFilterAttachments(
     .run();
 }
 
-// Bulk-replace the private inline filter set for a subscription. The input
-// array has already been zod-validated as a discriminated union, so each
-// element's `params` is guaranteed to match its `ruleType`. Empty array =
-// drop all (matches `replaceLibraryFilterAttachments` semantics).
+// Empty array = drop all. Inputs are pre-validated as a discriminated union (params match ruleType).
 export function replaceInlineFilters(
   db: DbOrTx,
   subscriptionId: number,
@@ -442,6 +355,7 @@ export function replaceInlineFilters(
     .where(eq(subscriptionFilters.subscriptionId, subscriptionId))
     .run();
   if (inputs.length === 0) return;
+  for (const f of inputs) assertFilterParamsCompilable(f.ruleType, f.params);
   db.insert(subscriptionFilters)
     .values(
       inputs.map((f) => ({
@@ -484,9 +398,7 @@ function loadLibraryFilterIdsBatch(db: Db, subscriptionIds: number[]): Map<numbe
   return result;
 }
 
-// Correlated subqueries reused by listSubscriptions/getSubscription.
-// `filterCount` is the sum of per-sub filter rows (regardless of enabled —
-// same as Ch 7) plus library-filter attachments. Both are cheap on SQLite.
+// filterCount = per-sub filter rows (any enabled state) + library attachments.
 const filterCountSubquery = sql<number>`(
   SELECT COUNT(*) FROM ${subscriptionFilters}
   WHERE ${subscriptionFilters.subscriptionId} = ${subscriptions.id}
diff --git a/apps/server/src/api/routes/system.ts b/apps/server/src/api/routes/system.ts
index de2b715..b2b3d7e 100644
--- a/apps/server/src/api/routes/system.ts
+++ b/apps/server/src/api/routes/system.ts
@@ -1,22 +1,4 @@
-/**
- * System routes.
- *
- * - `GET /system/status`: Surface enough info for the web UI to explain
- *   why some features are unavailable (e.g. Telegram disconnected →
- *   subscribing/forwarding disabled). The status is supplied as a getter
- *   so the health monitor (apps/server/src/tg/healthMonitor.ts) can update
- *   it on each probe and the route always reads the current value.
- *
- * - `POST /system/export`, `POST /system/import`, `POST /system/wipe`:
- *   Settings → Data section. Versioned JSON envelope (`exportFileSchema`)
- *   carries selected sections (subscriptions / destinations / library
- *   filters / app settings) round-trip without ID collisions — IDs are
- *   intentionally omitted and import remaps via natural keys (chatId+name
- *   for destinations, name for library filters, sourceChatId for
- *   subscriptions). Import body limit is bumped to 2 MB on the route
- *   level — large enough for thousands of subscriptions, small enough to
- *   refuse abuse.
- */
+// Import remaps by natural key (destinations: chatId+name; library filters: name; subscriptions: sourceChatId).
 import { eq, inArray } from 'drizzle-orm';
 import type { FastifyInstance } from 'fastify';
 import {
@@ -64,9 +46,6 @@ import {
 import { getStatsDigestConfig } from '../../forwarding/statsDigestConfig.js';
 import { replaceInlineFilters, replaceLibraryFilterAttachments } from './subscriptions.js';
 
-// Read the app version from the root package.json so exports carry a
-// truthful tag. The path goes from this module up four levels:
-// apps/server/src/api/routes → apps/server → repo root.
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
@@ -92,26 +71,10 @@ export interface RegisterSystemRoutesDeps {
   bus: EventBus;
   logger: Logger;
   getTelegramStatus: () => TelegramStatus;
-  /**
-   * Returns the loaded `TG_SESSION_ENCRYPTION_KEY` as a 32-byte Buffer, or
-   * null when not set. Used by import to decide whether to write the
-   * encrypted account blob carried inside `appSettings.telegramAccount`.
-   */
+  // null gates writing the imported account blob.
   getEncryptionKey?: () => Buffer | null;
-  /**
-   * Triggers a live-swap of the gramjs runtime so an imported account row
-   * activates without a process restart. Optional; when absent, the row is
-   * still written but takes effect on next boot.
-   */
+  // Live-swaps gramjs so an imported account activates without restart.
   reloadTelegramSession?: () => Promise<void>;
-  /**
-   * Best-effort Telegram profile-photo fetcher. Import never carries icon
-   * bytes (they're derived data, refetched per host), so after a successful
-   * import we backfill `iconDataUrl` for the rows we just created — mirroring
-   * the inline fetch that POST /subscriptions and POST /destinations already
-   * do. Optional: when absent (Telegram-less boot, tests) imported rows stay
-   * icon-less until the access monitor's 24h sweep catches them.
-   */
   getFetchProfilePhoto?: () => ProfilePhotoFetcher | undefined;
 }
 
@@ -133,10 +96,7 @@ export function registerSystemRoutes(app: FastifyInstance, deps: RegisterSystemR
   app.post(
     '/system/export',
     {
-      // Behind cookie auth and SameSite=strict, but cap nonetheless: a stolen
-      // cookie or compromised browser extension shouldn't be able to grind
-      // out unlimited full-DB dumps. Generous enough that legitimate
-      // back-to-back exports work; tight enough that abuse is bounded.
+      // Cap full-DB dumps against a stolen cookie.
       config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
     },
     async (request): Promise<ExportFile> => {
@@ -158,23 +118,15 @@ export function registerSystemRoutes(app: FastifyInstance, deps: RegisterSystemR
           `unsupported export schemaVersion ${body.data.schemaVersion}`,
         );
       }
-      // v1 files lack `appSettings.telegramAccount`; v2 importers handle
-      // both transparently because the field is `.optional()`.
       const sectionSet = new Set<ExportSection>(body.sections);
       const result = applyImport(db, body.data, sectionSet, body.conflictStrategy, {
         ...(getEncryptionKey !== undefined ? { getEncryptionKey } : {}),
       });
-      // If a telegram account was actually written, kick the live-swap so
-      // the running app picks it up without a restart. Failures are
-      // swallowed — the row is saved either way.
+      // Failures swallowed: the row is saved either way.
       if (result.telegramAccountWritten && reloadTelegramSession) {
         await reloadTelegramSession().catch(() => {});
       }
-      // Backfill profile photos for the rows we just imported. Fire-and-forget:
-      // a large import shouldn't block the HTTP response on hundreds of
-      // sequential Telegram downloads. Icons stream into the UI as they land
-      // via the `subscription.changed` / `destination.changed` SSE events the
-      // backfill emits (the web client invalidates its lists on those).
+      // Fire-and-forget so a big import doesn't block on sequential TG downloads.
       const fetchProfilePhoto = getFetchProfilePhoto?.();
       if (fetchProfilePhoto && result.iconTargets.length > 0) {
         void backfillImportedIcons({
@@ -194,9 +146,7 @@ export function registerSystemRoutes(app: FastifyInstance, deps: RegisterSystemR
   app.post(
     '/system/wipe',
     {
-      // Destructive — cap aggressively. A leaked cookie or stored-XSS
-      // shouldn't be able to nuke the DB in a tight loop. Three calls per
-      // minute is still plenty for a legitimate "clear & re-import" flow.
+      // Destructive — cap aggressively against a leaked cookie.
       config: { rateLimit: { max: 3, timeWindow: '1 minute' } },
     },
     async (request): Promise<WipeResult> => {
@@ -351,9 +301,7 @@ function buildExport(db: Db, sections: Set<ExportSection>): ExportFile {
       statsDigestTime: digest.time,
       statsDigestTimezone: digest.timezone,
     };
-    // v2: include the encrypted Telegram account row when present. The
-    // ciphertext + fingerprint travel as-is — the importing host decides
-    // (via fingerprint match) whether to write the row to its own DB.
+    // Ciphertext + fingerprint travel as-is; importing host decides via fingerprint match.
     const accountRow = db.select().from(telegramAccount).get();
     if (accountRow) {
       settings.telegramAccount = {
@@ -379,7 +327,6 @@ function destKey(chatId: string, name: string): string {
 
 const emptySectionResult = (): ImportSectionResult => ({ created: 0, skipped: 0, replaced: 0 });
 
-/** A subscription/destination row that import created, needing a profile photo. */
 export interface IconBackfillTarget {
   kind: 'subscription' | 'destination';
   id: number;
@@ -388,13 +335,7 @@ export interface IconBackfillTarget {
 
 interface ApplyImportResult {
   body: ImportResult;
-  /** True when a `telegram_account` row was created or replaced. */
   telegramAccountWritten: boolean;
-  /**
-   * Subscription/destination rows this import touched (created or replaced)
-   * that still have a null `iconDataUrl` — fed to `backfillImportedIcons`
-   * after the transaction commits. Empty when nothing needs an icon.
-   */
   iconTargets: IconBackfillTarget[];
 }
 
@@ -413,18 +354,11 @@ function applyImport(
     warnings: [],
   };
   let telegramAccountWritten = false;
-  // IDs of subscription / destination rows this import created or replaced.
-  // After the transaction commits we re-read these and keep only the ones
-  // still missing an icon, so the post-import backfill targets exactly the
-  // rows that need one (created rows always do; replaced rows only when they
-  // were icon-less to begin with).
   const touchedDestIds: number[] = [];
   const touchedSubIds: number[] = [];
 
   db.transaction((tx) => {
-    // Build initial maps from existing rows so subscriptions can resolve
-    // refs even when the user opted out of importing destinations / library
-    // filters in this run (and the records already exist).
+    // Seed from existing rows so subscriptions resolve refs even when those sections weren't imported.
     const destMap = new Map<string, number>();
     for (const d of tx.select().from(destinations).all() as Destination[]) {
       destMap.set(destKey(d.chatId, d.name), d.id);
@@ -477,8 +411,7 @@ function applyImport(
       for (const item of data.libraryFilters) {
         const existingId = libMap.get(item.name);
         if (existingId !== undefined) {
-          // ruleType is immutable post-create; if it changed, surface a
-          // warning and skip this row regardless of strategy.
+          // ruleType is immutable; on mismatch, warn and skip regardless of strategy.
           const existingRow = tx
             .select()
             .from(libraryFilters)
@@ -534,8 +467,6 @@ function applyImport(
             result.subscriptions.skipped += 1;
             continue;
           }
-          // Replace: overwrite mutable fields + bulk-replace filter sets via
-          // the existing helpers (same code path as PATCH /subscriptions/:id).
           tx.update(subscriptions)
             .set({
               sourceTitle: item.sourceTitle,
@@ -579,11 +510,7 @@ function applyImport(
     }
 
     if (sections.has('appSettings') && data.appSettings) {
-      // The throttle/debouncer fields go into `app_settings`. The optional
-      // `telegramAccount` sub-object is split off and routed to its own
-      // table (`telegram_account`) — the wire format embeds it under
-      // `appSettings` so the user can manage both with one checkbox in the
-      // UI, but at rest they live separately.
+      // telegramAccount rides under appSettings on the wire but persists to its own table.
       const { telegramAccount: importedAccount, ...appSettingsValue } = data.appSettings;
       const existing = tx
         .select()
@@ -593,9 +520,7 @@ function applyImport(
       if (existing && strategy === 'skip') {
         result.appSettings.skipped += 1;
       } else {
-        // Merge onto the existing row rather than replacing it: the export
-        // may omit fields (e.g. an older file with no digest schedule), and a
-        // wholesale overwrite would wipe whatever the row already held.
+        // Merge, don't overwrite: an older export may omit fields the row already holds.
         const mergedValue = {
           ...((existing?.value as Record<string, unknown> | undefined) ?? {}),
           ...appSettingsValue,
@@ -626,10 +551,7 @@ function applyImport(
     }
   });
 
-  // Re-read the touched rows (post-commit) and keep only those still missing
-  // an icon. Created rows are always null here; replaced rows pass through
-  // only when they were already icon-less, so we never re-download a photo a
-  // row already has.
+  // Keep only touched rows still missing an icon, so we never re-download.
   const iconTargets: IconBackfillTarget[] = [];
   if (touchedDestIds.length > 0) {
     const rows = db
@@ -667,23 +589,7 @@ function applyImport(
   return { body: result, telegramAccountWritten, iconTargets };
 }
 
-/**
- * Post-import icon backfill. Import envelopes never carry profile-photo bytes
- * (they're derived data — large, and tied to the importing host's session),
- * so freshly imported subscriptions / destinations land with `iconDataUrl =
- * null` and render the lucide fallback. This mirrors the inline fetch that the
- * create routes (POST /subscriptions, POST /destinations) run, but batched and
- * fired after the import response so a big import isn't held hostage to
- * sequential Telegram downloads.
- *
- * Best-effort throughout: `fetchProfilePhoto` already swallows its own errors
- * and returns null (no photo, gramjs error, oversize), so a failure just
- * leaves that one row icon-less for the access monitor's 24h sweep to retry.
- * Each successful stamp emits the same `*.changed` event the access monitor
- * uses, so the web client's SSE listener invalidates its lists and the icon
- * appears without a manual refresh. Fetches are deduped per chatId so a chat
- * used by several rows is downloaded once.
- */
+// Best-effort, deduped per chatId; each stamp emits a *.changed event so the UI refreshes.
 export async function backfillImportedIcons(deps: {
   db: Db;
   bus: EventBus;
@@ -717,12 +623,7 @@ export async function backfillImportedIcons(deps: {
   return stamped;
 }
 
-/**
- * Returns true when the row was actually upserted (caller triggers
- * live-swap). Returns false when the row was skipped (no key, fingerprint
- * mismatch, or strategy=skip with an existing row); the warning array is
- * mutated in place either way.
- */
+// false = skipped: no key, fingerprint mismatch, or skip strategy.
 type DbOrTx = Db | Parameters<Parameters<Db['transaction']>[0]>[0];
 
 function importTelegramAccount(
@@ -817,11 +718,7 @@ function resolveLibraryFilterIds(
   return ids;
 }
 
-// The exported subscription's inline filters are already validated by the
-// `exportFileSchema`'s discriminated union — every entry carries valid
-// per-rule params. Pass them through, but keep the warning hook so a future
-// schema bump or hand-edited file with stray entries gets a clear surface
-// rather than a silent throw.
+// Already validated by exportFileSchema; warning hook retained for future schema drift.
 function importableInlineFilters(
   item: ExportedSubscription,
   _warnings: ImportWarning[],
@@ -840,16 +737,13 @@ function applyWipe(db: Db, sections: Set<WipeSection>): WipeResult {
       deleted.subscriptions = result.changes;
     }
     if (sections.has('libraryFilters')) {
-      // Pre-detach to avoid the FK RESTRICT on `subscription_library_filters
-      // → library_filters` when subscriptions weren't selected for wipe.
+      // Pre-detach to dodge FK RESTRICT on subscription_library_filters → library_filters.
       tx.delete(subscriptionLibraryFilters).run();
       const result = tx.delete(libraryFilters).run();
       deleted.libraryFilters = result.changes;
     }
     if (sections.has('destinations')) {
-      // FK is ON DELETE SET NULL on `subscriptions.destination_id`, so
-      // subscriptions survive — just lose their destination. Order matters
-      // only relative to subscriptions wipe (already done above if selected).
+      // FK is ON DELETE SET NULL on subscriptions.destination_id, so subscriptions survive.
       const result = tx.delete(destinations).run();
       deleted.destinations = result.changes;
     }
diff --git a/apps/server/src/api/routes/telegramAccount.ts b/apps/server/src/api/routes/telegramAccount.ts
index f4a0f66..7774a8a 100644
--- a/apps/server/src/api/routes/telegramAccount.ts
+++ b/apps/server/src/api/routes/telegramAccount.ts
@@ -1,25 +1,4 @@
-/**
- * Telegram account routes — settings-page sign-in / sign-out.
- *
- * GET    /api/tg/account              → current state, source, key status
- * POST   /api/tg/login/start          → send code to a phone, returns sessionId
- * POST   /api/tg/login/verify         → verify code; may signal needsPassword
- * POST   /api/tg/login/password       → 2FA password
- * POST   /api/tg/login/raw            → paste a raw session string (validated)
- * POST   /api/tg/login/cancel         → drop an in-progress login
- * DELETE /api/tg/account              → remove the DB row, env fallback resumes
- *
- * "Save" branches refuse with 412 unless `TG_SESSION_ENCRYPTION_KEY` is
- * configured. The encrypted blob is written to `telegram_account` (single
- * row, id=1) and `reloadTelegramSession()` is called so the gramjs runtime
- * picks up the new credentials without a restart.
- *
- * Each in-progress login session is bound to the caller's web-session cookie
- * token via `readSessionToken(request)`; verify/password/cancel reject if a
- * second authed tab tries to drive someone else's flow. The phone-code and
- * password endpoints are rate-limited per IP — brute-forcing a 5-digit
- * Telegram code via this surface would shadow-ban the operator's phone.
- */
+// Settings-page Telegram sign-in/out. Save needs TG_SESSION_ENCRYPTION_KEY (else 412); login sessions are bound to the caller's cookie token so a second tab can't drive someone else's flow.
 import type { FastifyInstance } from 'fastify';
 import {
   type TelegramAccountInfo,
@@ -43,28 +22,18 @@ import { readSessionToken } from '../auth.js';
 
 export interface RegisterTelegramAccountRoutesDeps {
   db: Db;
-  /** Returns the configured 32-byte key, or null when unset. */
   getEncryptionKey?: () => Buffer | null;
-  /** In-memory store for in-progress sign-ins. */
   loginSessionStore?: LoginSessionStore;
-  /** Triggers the live-swap so a freshly-saved session takes effect immediately. */
   reloadTelegramSession?: () => Promise<void>;
-  /** Lifecycle of the gramjs subsystem (used to compute `present`). */
   getTelegramStatus: () => TelegramStatus;
-  /**
-   * Profile-photo fetcher over the live userbot. Used to fetch the account's
-   * own avatar ("me"); absent when no client is up (tests / disconnected).
-   */
+  // Over the live userbot; absent when no client is up (tests / disconnected).
   getFetchProfilePhoto?: () => ProfilePhotoFetcher | undefined;
 }
 
-// Avatar cache TTL — long enough to avoid re-downloading on every settings
-// poll, short enough that a changed/swapped photo or a transient miss is
-// picked up without a sign-out or restart.
 const AVATAR_TTL_MS = 10 * 60_000;
 const AVATAR_FETCH_TIMEOUT_MS = 2500;
 
-/** Resolves to null after the timeout so a stalled download can't hang the route. */
+// Resolves to null after the timeout so a stalled download can't hang the route.
 function avatarFetchTimeout(): Promise<null> {
   return new Promise<null>((resolve) => {
     const t = setTimeout(() => resolve(null), AVATAR_FETCH_TIMEOUT_MS);
@@ -85,9 +54,7 @@ export function registerTelegramAccountRoutes(
     getFetchProfilePhoto,
   } = deps;
 
-  // The userbot's own avatar, downloaded lazily and cached with a short TTL so
-  // a transient miss or a changed/swapped photo is eventually picked up
-  // without re-downloading on every poll. Cleared outright on sign-in / out.
+  // Userbot's own avatar, lazy + short-TTL cached; cleared on sign-in/out.
   let avatarCache: { key: string; dataUrl: string | null; fetchedAt: number } | null = null;
 
   async function resolveAvatar(base: TelegramAccountInfo): Promise<string | null> {
@@ -102,7 +69,6 @@ export function registerTelegramAccountRoutes(
     if (!fetcher) return avatarCache?.key === key ? avatarCache.dataUrl : null;
     let dataUrl: string | null = null;
     try {
-      // Don't let a hung gramjs download block this frequently-polled route.
       dataUrl = await Promise.race([fetcher('me'), avatarFetchTimeout()]);
     } catch {
       dataUrl = null;
@@ -125,9 +91,7 @@ export function registerTelegramAccountRoutes(
   app.post(
     '/tg/login/start',
     {
-      // Telegram throttles SendCode aggressively per phone number; cap our own
-      // call rate to avoid getting the operator's phone number shadow-banned
-      // when the UI fires repeated start requests.
+      // Cap SendCode rate: repeated starts can shadow-ban the operator's phone.
       config: { rateLimit: { max: 5, timeWindow: '5 minutes' } },
     },
     async (request) => {
@@ -142,9 +106,7 @@ export function registerTelegramAccountRoutes(
   app.post(
     '/tg/login/verify',
     {
-      // Brute-forcing the SMS code via this surface would shadow-ban the
-      // phone — Telegram counts attempts per phone+app, not per IP. Stay
-      // well under the limit; legitimate users only need a handful of tries.
+      // SMS-code brute-force shadow-bans the phone (counted per phone+app, not per IP).
       config: { rateLimit: { max: 8, timeWindow: '5 minutes' } },
     },
     async (request): Promise<TelegramLoginVerifyResponse> => {
@@ -170,8 +132,7 @@ export function registerTelegramAccountRoutes(
   app.post(
     '/tg/login/password',
     {
-      // Same reasoning as `/verify` — 2FA password brute-force is upstream-
-      // rate-limited but the operator pays the bill.
+      // Cap 2FA-password rate; the operator pays for upstream brute-force throttling.
       config: { rateLimit: { max: 8, timeWindow: '5 minutes' } },
     },
     async (request): Promise<TelegramLoginCompleted> => {
@@ -218,9 +179,7 @@ export function registerTelegramAccountRoutes(
     deleteAccount(db);
     avatarCache = null;
     if (reloadTelegramSession) {
-      // Live-swap to env (or degraded) — failures are logged inside
-      // `reloadTelegramSession` and don't block the user. The DB row is
-      // already gone; next boot will pick up the env fallback.
+      // Live-swap to env; failures don't block (row's gone, next boot picks up env).
       await reloadTelegramSession().catch(() => {});
     }
     return { ok: true };
@@ -238,10 +197,7 @@ function buildAccountInfo(deps: {
   const row = getActiveAccount(deps.db);
   const status = deps.getTelegramStatus();
   const connected = status.state === 'connected';
-  // A row whose fingerprint doesn't match the current key (or no key set)
-  // is "stale" — the resolver fell through to env. Report the mismatch
-  // separately so the UI can prompt the operator without claiming the row
-  // is the live account.
+  // Fingerprint mismatch (or no key) = stale row, resolver fell through to env; reported separately so the UI can prompt.
   const rowUsable = row !== null && key !== null && getKeyFingerprint(key) === row.keyFingerprint;
   const source: 'db' | 'env' | null = !connected ? null : rowUsable ? 'db' : 'env';
 
@@ -300,9 +256,7 @@ async function commitLogin(deps: {
     try {
       await deps.reloadTelegramSession();
     } catch {
-      // Live-swap failed; the DB row is still saved. The next process restart
-      // picks it up. The caller rebuilds the account info regardless so the UI
-      // can confirm the save.
+      // Live-swap failed; row is saved, next restart picks it up.
     }
   }
 }
diff --git a/apps/server/src/api/server.ts b/apps/server/src/api/server.ts
index a2c74f4..60c8a78 100644
--- a/apps/server/src/api/server.ts
+++ b/apps/server/src/api/server.ts
@@ -1,23 +1,3 @@
-/**
- * Fastify factory.
- *
- * Pure factory — does NOT call `.listen()`. The boot path in
- * `apps/server/src/index.ts` constructs the app and calls listen; tests
- * construct the app and use `.inject()` directly. Same code, two
- * call sites.
- *
- * Plugin order:
- *   1. `@fastify/cookie` (signed cookies; secret = `webAuth.sessionSecret`)
- *   2. `@fastify/cors` — dev only (allow Vite at :5173). Production is
- *      same-origin via `@fastify/static`, so no CORS surface to expose.
- *   3. `@fastify/static` — serves `apps/web/dist` (no-op until Ch 9/14
- *      bundles a real SPA). The plugin requires the directory to exist;
- *      we `mkdirSync(root, { recursive: true })` on registration so it
- *      doesn't throw before the SPA lands.
- *   4. Custom error handler from `errorHandler.ts`
- *   5. Public scope (just `POST /api/auth/login`)
- *   6. Authed scope (`requireAuth` preHandler + everything else)
- */
 import { createHash } from 'node:crypto';
 import { mkdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
@@ -52,6 +32,7 @@ import { registerBotConfigRoutes } from './routes/botConfig.js';
 import { registerDestinationRoutes } from './routes/destinations.js';
 import { registerFilterRoutes } from './routes/filters.js';
 import { registerForwardLogRoutes } from './routes/forwardLog.js';
+import { registerHealthRoute } from './routes/health.js';
 import { registerLibraryFilterRoutes } from './routes/libraryFilters.js';
 import { registerSettingsRoutes } from './routes/settings.js';
 import { registerStreamRoutes } from './routes/stream.js';
@@ -70,113 +51,27 @@ export interface CreateApiServerDeps {
   logger: Logger;
   filterRegistry: FilterRegistry;
   webAuth: WebAuth;
-  /**
-   * Parsed env config — supplies the env fallbacks behind the bot-config
-   * route's DB-over-env resolver. Optional for tests; defaults to a config
-   * parsed from an empty env (all bot/web vars unset).
-   */
   cfg?: Config;
-  /**
-   * Live getter for the Telegram Web App auth config (bot token + admin
-   * allowlist), resolved DB-over-env. Read per request by
-   * `POST /api/auth/telegram` so a config change made via Settings → Bot
-   * applies without a restart. Read once at boot to decide whether to relax
-   * the CSP `frame-ancestors` for the Mini App. Null/omitted (or a getter
-   * that yields null) = password-only with the strict default CSP.
-   */
+  // Resolved DB-over-env; read per request by POST /api/auth/telegram so config changes apply live. null = password-only.
   getTelegramAuth?: () => TelegramAuth | null;
-  /**
-   * Live-swaps the long-polling bot after a config change. Wired to the
-   * bot-config route's PUT/DELETE. Optional for tests (no swap occurs).
-   */
   reloadBot?: () => Promise<void>;
-  /** Whether the long-polling bot is currently running (for the masked GET). */
   getBotRunning?: () => boolean;
   isProd: boolean;
   bus: EventBus;
-  /** Override the SSE heartbeat interval — primarily for tests. */
   heartbeatMs?: number;
-  /**
-   * Lazy lookup for the universal "paste-anything" resolver used by
-   * `POST /subscriptions/resolve` and `POST /destinations/resolve`. The
-   * boot path in `apps/server/src/index.ts` populates this asynchronously
-   * after `app.listen()` returns, so route handlers must dereference per
-   * request rather than at registration time. Optional for tests and
-   * Telegram-less boots; routes return 503 `telegram_unavailable` (or
-   * `telegram_initializing` while `getTelegramStatus().state ===
-   * 'connecting'`) when the getter yields undefined.
-   */
+  // Lazy: boot populates these after app.listen(), so handlers must deref per request, not at registration.
   getChatResolver?: () => ChatResolver | undefined;
-  /**
-   * Lazy lookup for the `messages.ImportChatInvite` wrapper used by both
-   * subscription and destination create endpoints when the body carries
-   * `inviteHash`. Same lifecycle as `getChatResolver`.
-   */
   getImportInvite?: () => ImportInviteFn | undefined;
-  /**
-   * Lazy lookup for the auto-join helper invoked from POST /subscriptions
-   * after the row is inserted. Same lifecycle as `getChatResolver`; when
-   * undefined, new subscriptions get the default 'ok' status and rely on
-   * the access monitor's first sweep to correct it.
-   */
   getJoinChannel?: () => JoinChannelFn | undefined;
-  /**
-   * Lazy lookup for the best-effort profile-photo fetcher used by both
-   * create endpoints (`POST /subscriptions`, `POST /destinations`) to
-   * populate the new row's `iconDataUrl` immediately. Same lifecycle as
-   * `getChatResolver`; without it new rows stay icon-less until the access
-   * monitor's lazy backfill catches them.
-   */
   getFetchProfilePhoto?: () => ProfilePhotoFetcher | undefined;
-  /**
-   * Lazy lookup for the forum-topic lister backing `POST /destinations/topics`.
-   * Same lifecycle as `getChatResolver`.
-   */
   getListForumTopics?: () => ForumTopicLister | undefined;
-  /**
-   * Live getter for the Telegram subsystem state. Surfaced via
-   * `GET /api/system/status` so the web UI can warn the operator when
-   * Telegram is unavailable. The getter is read on each request, so the
-   * boot path can flip 'connecting' → 'connected' (or the health monitor
-   * can flip 'connected' → 'disconnected') and clients pick up the change
-   * without a restart. Optional for tests; defaults to a generic "not
-   * initialized" reason when absent.
-   */
+  // Read per request so 'connecting' → 'connected' transitions reach clients without a restart.
   getTelegramStatus?: () => TelegramStatus;
-  /**
-   * Returns the loaded `TG_SESSION_ENCRYPTION_KEY` as a 32-byte Buffer, or
-   * null when the env var is not set. Used by the telegram-account routes
-   * to refuse account writes when no key is configured, and by the system
-   * import route to skip encrypted blobs whose fingerprint doesn't match.
-   * Optional — when absent, both paths behave as if the key is unset.
-   */
   getEncryptionKey?: () => Buffer | null;
-  /**
-   * In-memory store for in-progress sign-ins from the Settings page.
-   * Optional — telegram-account routes return 503 when missing (for tests
-   * that don't exercise the login flow).
-   */
   loginSessionStore?: LoginSessionStore;
-  /**
-   * Triggers a live-swap of the gramjs client and dependent runtime
-   * (pipeline, debouncer, monitors, resolvers). Called after a successful
-   * sign-in or sign-out so the running app picks up the new credentials
-   * without a restart. Optional for tests; in tests the routes still write
-   * the row but no swap occurs.
-   */
+  // Live-swaps the gramjs client + dependent runtime after sign-in/out, no restart.
   reloadTelegramSession?: () => Promise<void>;
-  /**
-   * Optional override for the DB-backed session store. Defaults to
-   * `createSessionStore({ db })`. Tests may inject a custom one but the
-   * default is fine for both production and the standard test scaffolding.
-   */
   sessionStore?: SessionStore;
-  /**
-   * Override the directory the SPA is served from (static root, CSP inline
-   * hashes, and the history fallback below). Defaults to the built
-   * `apps/web/dist`. Tests point this at a temp dir to exercise the SPA
-   * fallback without a real web build.
-   */
   webDistRoot?: string;
 }
 
@@ -186,22 +81,12 @@ const DEFAULT_TELEGRAM_STATUS: TelegramStatus = {
   reason: 'Telegram client not initialized',
 };
 
-/**
- * Compute the sha256 hashes of every inline `<script>` tag found in the
- * built `apps/web/dist/index.html` so they can be added to the CSP. This
- * preserves the no-FOUC inline theme-bootstrap script while still pinning a
- * strict `script-src 'self' 'sha256-...'` policy.
- *
- * Tolerant: if the file is missing (dev mode) or contains no inline
- * scripts, returns []. The CSP just allows nothing inline in that case,
- * which is the right default — production deploys MUST have the bundle.
- */
+// sha256 of each inline <script> in built index.html for the CSP; [] when missing (dev) — prod MUST have the bundle.
 function collectInlineScriptHashes(distRoot: string): string[] {
   try {
     const html = readFileSync(path.join(distRoot, 'index.html'), 'utf8');
     const hashes: string[] = [];
-    // Match only inline scripts (no `src=` attribute). Capture the content
-    // between the tags exactly as served — that's what the browser hashes.
+    // Inline scripts only (no src=); capture content exactly as served — that's what the browser hashes.
     const re = /<script(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/gi;
     let match: RegExpExecArray | null;
     while ((match = re.exec(html)) !== null) {
@@ -235,38 +120,24 @@ export async function createApiServer(deps: CreateApiServerDeps): Promise<Fastif
     deps.getTelegramStatus ?? ((): TelegramStatus => DEFAULT_TELEGRAM_STATUS);
   const cfg = deps.cfg ?? parseConfig({});
   const getTelegramAuth = deps.getTelegramAuth ?? ((): TelegramAuth | null => null);
-  // Resolved once at boot — used only to decide the CSP frame-ancestors. The
-  // route itself reads the getter per request, so token/admin changes apply
-  // live; toggling the bot from fully-off to on still needs a restart for the
-  // in-Telegram iframe embedding (the CSP), but the Mini App auth works live.
+  // Only decides CSP frame-ancestors; enabling iframe embedding from fully-off needs a restart, Mini App auth is live.
   const bootTelegramAuth = getTelegramAuth();
   const distRoot = deps.webDistRoot ?? WEB_DIST_ROOT;
 
   const app = Fastify({
     logger: false,
     bodyLimit: BODY_LIMIT_BYTES,
-    // Required for the login rate-limit (and `request.ip` everywhere) to key
-    // on the real client IP behind a reverse proxy / Docker NAT / CDN. Deploys
-    // MUST terminate TLS upstream and forward X-Forwarded-For; see DEPLOY.md.
+    // Keys rate-limit + request.ip on the real client IP behind a proxy; deploys MUST forward X-Forwarded-For (DEPLOY.md).
     trustProxy: true,
   });
 
   await app.register(fastifyCookie, { secret: webAuth.sessionSecret });
 
-  // DB-backed session store. Cookies carry an opaque token; this is the
-  // server-side lookup that actually decides whether a request is authed.
   const sessionStore = deps.sessionStore ?? createSessionStore({ db });
 
-  // Helmet adds standard security headers (X-Content-Type-Options,
-  // X-Frame-Options, Referrer-Policy, etc.). CSP is enabled in production
-  // using the inline-script hash from the built `index.html`. In dev the
-  // hash is unknown (Vite serves an unbuilt index.html with HMR scripts), so
-  // CSP is left off there — same posture as before this change.
+  // CSP only in prod; dev's index.html has unknown HMR inline-script hashes.
   const inlineScriptHashes = isProd ? collectInlineScriptHashes(distRoot) : [];
-  // `index.html` always loads the `telegram-web-app.js` SDK, so `script-src`
-  // always allows telegram.org. `frame-ancestors` lets Telegram Web embed the
-  // console and is enabled only when the Mini App is configured; native
-  // Telegram clients use a webview not subject to it.
+  // frame-ancestors lets Telegram Web embed the console, only when the Mini App is configured.
   const telegramWebApp = !!bootTelegramAuth;
   const frameAncestors = telegramWebApp ? ["'self'", 'https://web.telegram.org'] : ["'none'"];
   await app.register(fastifyHelmet, {
@@ -275,27 +146,20 @@ export async function createApiServer(deps: CreateApiServerDeps): Promise<Fastif
           useDefaults: true,
           directives: {
             defaultSrc: ["'self'"],
-            // `data:` covers profile-photo `<img>`s; inline hashes cover the
-            // theme bootstrap script in `index.html`.
             imgSrc: ["'self'", 'data:'],
             scriptSrc: ["'self'", ...inlineScriptHashes, 'https://telegram.org'],
-            // Vite's CSS pipeline emits some inline styles for runtime
-            // theming; `'unsafe-inline'` for styleSrc is the standard
-            // pragmatic carve-out.
+            // unsafe-inline required: Vite's CSS pipeline emits inline styles for runtime theming.
             styleSrc: ["'self'", "'unsafe-inline'"],
             connectSrc: ["'self'"],
             objectSrc: ["'none'"],
             frameAncestors,
             baseUri: ["'self'"],
-            // `upgrade-insecure-requests` is on by default via `useDefaults`.
           },
         }
       : false,
   });
 
-  // Register rate-limit globally with `global: false` so only routes that opt
-  // in via `config.rateLimit` are throttled. The login route uses this; other
-  // routes (single-user, behind auth cookie) don't need it.
+  // global: false — only routes that opt in via config.rateLimit are throttled (the login route).
   await app.register(fastifyRateLimit, { global: false });
 
   if (!isProd) {
@@ -305,26 +169,17 @@ export async function createApiServer(deps: CreateApiServerDeps): Promise<Fastif
     });
   }
 
-  // Plugin requires `root` to exist; create it if absent so dev/test
-  // environments without a built SPA don't fail registration. Until a real
-  // bundle exists the directory just stays empty.
+  // Plugin requires root to exist; create it so a SPA-less dev/test boot doesn't fail registration.
   mkdirSync(distRoot, { recursive: true });
   await app.register(fastifyStatic, {
     root: distRoot,
     prefix: '/',
-    // Refuse to serve dotfiles even if a stray `.env` / `.git/` ends up in
-    // the build output — default is `'allow'` which would happily serve them.
+    // deny: never serve a stray .env / .git/ that lands in the build (default 'allow' would).
     dotfiles: 'deny',
     index: ['index.html'],
   });
 
-  // SPA history fallback. The web app routes on the client (React Router), so
-  // a hard reload or shared deep link to e.g. /settings reaches the server as
-  // a real `GET /settings` with no matching route. For browser navigations
-  // (GET that accepts HTML, outside `/api`) serve index.html so the SPA boots
-  // and resolves the route client-side. Everything else — API misses, and
-  // asset/XHR requests that don't accept HTML — keeps the JSON 404 so clients
-  // get a real error instead of a surprise HTML body.
+  // SPA history fallback: HTML-accepting GETs outside /api serve index.html so React Router resolves; everything else keeps the JSON 404.
   app.setNotFoundHandler((request, reply) => {
     const accept = request.headers.accept;
     const acceptsHtml = (Array.isArray(accept) ? accept.join(',') : (accept ?? '')).includes(
@@ -343,9 +198,10 @@ export async function createApiServer(deps: CreateApiServerDeps): Promise<Fastif
 
   app.setErrorHandler(makeErrorHandler(logger));
 
-  // Public scope — password login + Telegram Web App sign-in, no `requireAuth`.
+  // Public scope — no requireAuth.
   await app.register(
     async (publicScope) => {
+      registerHealthRoute(publicScope, { db, logger });
       registerLoginRoute(publicScope, { webAuth, isProd, logger, sessionStore });
       registerTelegramAuthRoute(publicScope, {
         getTelegramAuth,
@@ -357,8 +213,7 @@ export async function createApiServer(deps: CreateApiServerDeps): Promise<Fastif
     { prefix: '/api' },
   );
 
-  // Authed scope — Fastify encapsulation scopes the preHandler to the
-  // routes registered inside this plugin only. No per-route opt-in.
+  // Authed scope — encapsulation scopes the preHandler to routes inside this plugin only.
   await app.register(
     async (authedScope) => {
       authedScope.addHook('preHandler', makeRequireAuth(sessionStore));
diff --git a/apps/server/src/api/sessionStore.ts b/apps/server/src/api/sessionStore.ts
index ce08299..7bf1534 100644
--- a/apps/server/src/api/sessionStore.ts
+++ b/apps/server/src/api/sessionStore.ts
@@ -1,47 +1,24 @@
-/**
- * Per-login session token store.
- *
- * Cookie semantics changed (vs. the legacy static-value design):
- *   - The cookie value IS the opaque token. Server signs it with
- *     `@fastify/cookie` HMAC so a tampered cookie fails at unsign.
- *   - `create()` mints a 256-bit random token at login and inserts a row with
- *     a hard expiry.
- *   - `verifyAndRefresh()` is the requireAuth hot path: look up by token,
- *     reject if expired, otherwise bump `lastSeenAt` and slide `expiresAt`
- *     forward by the configured window. Sliding refresh limits damage from
- *     a stolen-but-unused cookie.
- *   - `revoke()` deletes the row — logout becomes immediate and definitive.
- *   - `prune()` purges expired rows; called periodically from boot.
- */
+// Opaque session tokens in an HMAC-signed cookie; sliding 7-day expiry, server-side revoke.
 import { randomBytes } from 'node:crypto';
 import { lt, eq } from 'drizzle-orm';
 import type { Db } from '../db/client.js';
 import { webSessions } from '../db/schema.js';
 
 const TOKEN_BYTES = 32;
-// 7 days hard cap; sliding window refreshes on each authed request, but a
-// completely abandoned cookie still ages out.
+// Hard cap even with sliding refresh, so an abandoned cookie still ages out.
 export const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
 export interface SessionStore {
-  /** Mint a new session. Returns the opaque token to send back in the cookie. */
   create(now?: Date): string;
-  /**
-   * Look up a token; if found and unexpired, slide `expiresAt` forward and
-   * return true. Returns false for missing or expired tokens. Expired rows
-   * are deleted in passing so the caller doesn't have to.
-   */
+  // Slides expiry on hit; deletes expired rows in passing.
   verifyAndRefresh(token: string, now?: Date): boolean;
-  /** Delete a token. Idempotent — returns true if a row was deleted. */
   revoke(token: string): boolean;
-  /** Sweep expired rows. Returns the number of rows deleted. */
   prune(now?: Date): number;
 }
 
 export interface CreateSessionStoreDeps {
   db: Db;
-  /** Override TTL (tests). Defaults to 7 days. */
-  ttlMs?: number;
+  ttlMs?: number; // override for tests
 }
 
 export function createSessionStore(deps: CreateSessionStoreDeps): SessionStore {
@@ -68,7 +45,6 @@ export function createSessionStore(deps: CreateSessionStoreDeps): SessionStore {
       const row = db.select().from(webSessions).where(eq(webSessions.token, token)).get();
       if (!row) return false;
       if (row.expiresAt.getTime() <= now.getTime()) {
-        // Expired — delete lazily so subsequent lookups don't reuse it.
         db.delete(webSessions).where(eq(webSessions.token, token)).run();
         return false;
       }
diff --git a/apps/server/src/api/testing.ts b/apps/server/src/api/testing.ts
index 90160fe..8b1640e 100644
--- a/apps/server/src/api/testing.ts
+++ b/apps/server/src/api/testing.ts
@@ -1,11 +1,4 @@
-/**
- * API test scaffolding.
- *
- * Builds an isolated app instance backed by an in-memory DB and a fixed
- * test `webAuth`. Returns a `loginAndGetCookie()` helper because cookie
- * signing requires the live secret — tests can't fabricate a valid signed
- * cookie without going through the real login route.
- */
+// loginAndGetCookie() goes through the real login route: cookie signing needs the live secret.
 import type { FastifyInstance } from 'fastify';
 import type { TelegramStatus } from '@tg-feed/shared';
 import { type Config } from '../config.js';
@@ -41,48 +34,22 @@ export interface TestApp {
 }
 
 export interface BuildTestAppOptions {
-  /** Override the SSE heartbeat interval (default 25 s — too long for stream tests). */
+  // Default 25 s — too long for stream tests.
   heartbeatMs?: number;
-  /** Stub for the universal chat resolver used by both /resolve endpoints. */
   chatResolver?: ChatResolver;
-  /** Stub for the invite-import hook used by both /create endpoints when `inviteHash` is provided. */
   importInvite?: ImportInviteFn;
-  /** Stub for the auto-join hook fired from POST /api/subscriptions (chatId path). */
   joinChannel?: JoinChannelFn;
-  /** Stub for the best-effort profile photo fetcher fired from both /create endpoints. */
   fetchProfilePhoto?: ProfilePhotoFetcher;
-  /** Stub for the forum-topic lister backing POST /api/destinations/topics. */
   listForumTopics?: ForumTopicLister;
-  /**
-   * Override the Telegram status surfaced via `GET /api/system/status` and
-   * used by routes to choose between `telegram_initializing` (transient,
-   * during boot) and `telegram_unavailable` (steady-state). Defaults to a
-   * disconnected status so tests that omit Telegram stubs see the
-   * configure-style 503.
-   */
+  // Default disconnected, so tests without Telegram stubs see the configure-style 503.
   telegramStatus?: TelegramStatus;
-  /**
-   * Returns the configured `TG_SESSION_ENCRYPTION_KEY` as a 32-byte Buffer,
-   * or null. Used by tests that exercise the export/import telegram-account
-   * flow. Defaults to undefined (key absent).
-   */
+  // Default undefined (key absent).
   getEncryptionKey?: () => Buffer | null;
-  /**
-   * Override the SPA static root. Lets the SPA-history-fallback tests point
-   * the server at a temp dir containing a stub index.html.
-   */
   webDistRoot?: string;
-  /**
-   * Telegram Web App auth config. Default undefined → the
-   * `POST /api/auth/telegram` route reports `telegram_auth_disabled`.
-   * Forwarded as a `getTelegramAuth` getter to the server factory.
-   */
+  // Default undefined → POST /api/auth/telegram reports telegram_auth_disabled.
   telegramAuth?: TelegramAuth | null;
-  /** Parsed env config for the bot-config route's DB-over-env fallbacks. */
   cfg?: Config;
-  /** Stub for the bot live-swap invoked by the bot-config route's PUT/DELETE. */
   reloadBot?: () => Promise<void>;
-  /** Whether the bot is "running" for the masked `GET /api/config/bot`. */
   getBotRunning?: () => boolean;
 }
 
@@ -145,9 +112,7 @@ export async function buildTestApp(options: BuildTestAppOptions = {}): Promise<T
       const setCookie = res.headers['set-cookie'];
       const cookieHeader = Array.isArray(setCookie) ? setCookie[0] : setCookie;
       if (!cookieHeader) throw new Error('login response missing Set-Cookie header');
-      // Pick out just the `name=value` portion before the first `;` —
-      // attributes (Path, HttpOnly, ...) aren't sent back on subsequent
-      // requests; clients just echo the cookie value.
+      // Just the name=value pair; clients echo that, not the attributes.
       return cookieHeader.split(';')[0]!;
     },
     async close() {
@@ -157,10 +122,6 @@ export async function buildTestApp(options: BuildTestAppOptions = {}): Promise<T
   };
 }
 
-/**
- * Insert a destination row and return its id. Most route tests need a
- * destination to attach subscriptions to.
- */
 export function seedDestination(
   db: Db,
   overrides: { name?: string; chatId?: string; note?: string | null } = {},
diff --git a/apps/server/src/bot/bot.ts b/apps/server/src/bot/bot.ts
index 189d146..29312ce 100644
--- a/apps/server/src/bot/bot.ts
+++ b/apps/server/src/bot/bot.ts
@@ -1,53 +1,32 @@
-/**
- * Telegram bot (Bot API via grammy) fronting the web client.
- *
- * Handles `/start`: replies to admins with a button that opens the web client
- * as a Telegram Mini App and installs a persistent chat menu button to the
- * same Mini App; refuses non-admins. In-app authentication is handled
- * separately in `api/routes/auth.ts`.
- *
- * `start()` configures the bot and runs long-polling in the background;
- * `stop()` tears it down. The Web App button requires an `https://` public
- * URL; without one, `/start` replies with a setup hint instead.
- */
 import { Bot, InlineKeyboard, type Context } from 'grammy';
 import type { Logger } from '../lib/logger.js';
 
 export interface TgFeedBot {
-  /** Configure commands + menu button and start long-polling in the background. */
   start(): Promise<void>;
-  /** Stop long-polling and wait for the poll loop to unwind. */
   stop(): Promise<void>;
-  /**
-   * DM `text` (HTML) to every admin; returns how many sends succeeded.
-   * Per-admin failures are logged and swallowed so one unreachable admin can't
-   * block the rest — most commonly a 403 because that admin never opened the
-   * bot, so it can't initiate a chat. A return of 0 means nobody received it.
-   */
+  // DMs `text` (HTML) to each admin, returning the success count; per-admin failures swallowed (often 403: admin never opened the bot).
   notifyAdmins(text: string): Promise<number>;
 }
 
 export interface CreateBotDeps {
   token: string;
   adminIds: string[];
-  /** Public base URL of the web client. Must be https to drive a Mini App. */
+  // Must be https to drive a Mini App.
   publicUrl?: string | undefined;
   logger: Logger;
 }
 
 const MENU_BUTTON_TEXT = 'Open tg-feed';
 
-// Timeout for each await in `stop()` — grammy's `stop()` makes a final
-// `getUpdates` call that has no timeout of its own.
+// Bounds each await in stop(): grammy's final getUpdates call has no timeout of its own.
 const STOP_TIMEOUT_MS = 5000;
 
-/** Whether the update's sender is on the admin allowlist. */
 export function isBotAdmin(adminIds: string[], userId: number | string | undefined): boolean {
   if (userId === undefined) return false;
   return adminIds.includes(String(userId));
 }
 
-/** A Mini App URL is only usable over HTTPS; anything else is rejected by Telegram. */
+// A Mini App URL is only usable over HTTPS; anything else is rejected by Telegram.
 export function resolveWebAppUrl(publicUrl: string | undefined): string | undefined {
   if (!publicUrl) return undefined;
   return publicUrl.startsWith('https://') ? publicUrl : undefined;
@@ -58,12 +37,11 @@ export function createTgFeedBot(deps: CreateBotDeps): TgFeedBot {
   const webAppUrl = resolveWebAppUrl(deps.publicUrl);
   const bot = new Bot(token);
 
-  // Long-poll promise; `stop()` awaits it for teardown. Never rejects — a
-  // polling crash is logged in the `.catch` below.
+  // Never rejects — a polling crash is logged in the `.catch` below.
   let pollLoop: Promise<void> | undefined;
 
   bot.catch((err) => {
-    // Log and swallow per-update handler errors so one bad update doesn't stop polling.
+    // Swallow per-update handler errors so one bad update doesn't stop polling.
     logger.error(
       { err: err.error, update: err.ctx.update.update_id },
       'bot: update handler failed',
@@ -89,7 +67,7 @@ export function createTgFeedBot(deps: CreateBotDeps): TgFeedBot {
 
   return {
     async start() {
-      // Fetch bot info and validate the token; a bad token rejects to the caller.
+      // Validates the token; a bad token rejects to the caller.
       await bot.init();
 
       try {
@@ -116,9 +94,7 @@ export function createTgFeedBot(deps: CreateBotDeps): TgFeedBot {
         );
       }
 
-      // Run long-polling in the background; `bot.start()` resolves only when
-      // the bot stops, so it's not awaited here. `bot.init()` ran above, so
-      // grammy marks the bot running synchronously on this call.
+      // Not awaited: `bot.start()` resolves only when the bot stops.
       pollLoop = bot
         .start({
           onStart: (info) => logger.info({ username: info.username }, 'bot: started long-polling'),
@@ -157,7 +133,7 @@ export function createTgFeedBot(deps: CreateBotDeps): TgFeedBot {
   };
 }
 
-/** Settle with `p`, or reject after `ms` if it hasn't settled. Timer is unref'd. */
+// Reject after `ms` if `p` hasn't settled; timer is unref'd.
 function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
   return new Promise<T>((resolve, reject) => {
     const timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
diff --git a/apps/server/src/bot/botConfig.ts b/apps/server/src/bot/botConfig.ts
index c44b66e..7e2d993 100644
--- a/apps/server/src/bot/botConfig.ts
+++ b/apps/server/src/bot/botConfig.ts
@@ -1,6 +1,3 @@
-/**
- * DB-over-env resolver for the Telegram bot configuration.
- */
 import type { BotAdmin, BotConfigInfo, BotConfigSource } from '@tg-feed/shared';
 import type { TelegramAuth } from '../api/auth.js';
 import type { Config } from '../config.js';
@@ -26,7 +23,6 @@ function dedupe(ids: string[]): string[] {
   return Array.from(new Set(ids.map((s) => s.trim()).filter((s) => s.length > 0)));
 }
 
-/** Resolve the bot token DB→env. Logs (once per call) when it skips a stored row. */
 function resolveBotToken(deps: ResolveBotDeps): {
   token: string | null;
   source: BotConfigSource | null;
@@ -60,10 +56,7 @@ function resolveBotToken(deps: ResolveBotDeps): {
   return { token: null, source: null };
 }
 
-/**
- * Resolve the admin allowlist DB→env. DB entries carry display names (from
- * the `@username` lookup); env entries are raw ids with null names.
- */
+// DB entries carry display names; env entries are raw ids with null names.
 function resolveAdmins(deps: ReadDeps): { admins: BotAdmin[]; source: BotConfigSource | null } {
   const { cfg, db } = deps;
   const stored = readBotConfigRaw(db);
@@ -107,11 +100,7 @@ function resolvePublicUrlWithSource(deps: ReadDeps): {
   return { publicUrl: undefined, source: null };
 }
 
-/**
- * Resolved bot auth (token + admin allowlist), or null when the bot is not
- * configured. Enabled only when a token resolves AND at least one admin id
- * resolves.
- */
+// null unless both a token AND at least one admin id resolve.
 export function resolveTelegramAuth(deps: ResolveBotDeps): TelegramAuth | null {
   const { token } = resolveBotToken(deps);
   if (!token) return null;
@@ -120,16 +109,11 @@ export function resolveTelegramAuth(deps: ResolveBotDeps): TelegramAuth | null {
   return { botToken: token, adminIds };
 }
 
-/** Resolved public URL DB→env (used for the bot's Mini App button). */
 export function resolvePublicUrl(deps: ReadDeps): string | undefined {
   return resolvePublicUrlWithSource(deps).publicUrl;
 }
 
-/**
- * Masked, read-only view for `GET /api/config/bot`. Never logs and never
- * returns the token. `keyFingerprintMismatch` is true when a token is stored
- * but unusable with the current key (key unset or fingerprint differs).
- */
+// Masked view for GET /api/config/bot; never returns the token. keyFingerprintMismatch = token stored but unusable with the current key.
 export function buildBotConfigInfo(deps: {
   cfg: Config;
   db: Db;
diff --git a/apps/server/src/bot/initData.ts b/apps/server/src/bot/initData.ts
index 14e70f3..16d0466 100644
--- a/apps/server/src/bot/initData.ts
+++ b/apps/server/src/bot/initData.ts
@@ -1,23 +1,6 @@
-/**
- * Telegram Web App `initData` verification.
- *
- * When the web client is opened as a Telegram Mini App, Telegram injects a
- * signed `initData` query string into `window.Telegram.WebApp`. The client
- * POSTs it verbatim to `/api/auth/telegram`; this module proves it was
- * minted by Telegram for *our* bot and extracts the calling user.
- *
- * Verification (per https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app):
- *   1. Parse the query string and pull out the `hash` field.
- *   2. Build the data-check-string: the remaining `key=value` pairs sorted
- *      by key, joined with `\n`.
- *   3. secret_key = HMAC-SHA256(key = "WebAppData", data = bot_token)
- *   4. expected  = hex(HMAC-SHA256(key = secret_key, data = data-check-string))
- *   5. constant-time compare `expected` with the supplied `hash`.
- *   6. reject payloads older than `maxAgeSec` via `auth_date`.
- */
+// Verifies Telegram Mini App `initData` was minted for our bot, per https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
 import { createHmac, timingSafeEqual } from 'node:crypto';
 
-/** Subset of the Telegram WebApp `user` object we care about. */
 export interface TelegramWebAppUser {
   id: string;
   firstName: string | null;
@@ -30,9 +13,9 @@ export type VerifyInitDataResult =
   | { ok: false; reason: string };
 
 export interface VerifyInitDataOptions {
-  /** Reject initData whose `auth_date` is older than this many seconds. Default 24h. */
+  // Reject initData older than this many seconds; default 24h.
   maxAgeSec?: number;
-  /** Injectable clock for tests. Defaults to `Date.now()`. */
+  // Injectable clock for tests; defaults to `Date.now()`.
   now?: () => number;
 }
 
@@ -55,8 +38,7 @@ export function verifyTelegramInitData(
   const hash = params.get('hash');
   if (!hash) return { ok: false, reason: 'initData missing hash' };
 
-  // Data-check-string: every field except `hash`, sorted by key, `key=value`
-  // joined by newlines (`signature` stays in — the HMAC base excludes only `hash`).
+  // Data-check-string: every field except `hash` (incl. `signature`), sorted by key, `key=value` joined by `\n`.
   const pairs: string[] = [];
   for (const [key, value] of params) {
     if (key === 'hash') continue;
@@ -94,8 +76,7 @@ export function verifyTelegramInitData(
     if (parsed.id === undefined || parsed.id === null) {
       return { ok: false, reason: 'initData user missing id' };
     }
-    // Telegram ids can exceed JS's safe-integer range, so take the exact
-    // digits from the raw JSON text rather than the (lossy) parsed number.
+    // Telegram ids exceed JS safe-integer range: take exact digits from raw JSON, not the lossy parsed number.
     const idMatch = /"id"\s*:\s*(-?\d+)/.exec(userRaw);
     user = {
       id: idMatch ? idMatch[1]! : String(parsed.id),
diff --git a/apps/server/src/bot/statsDigest.ts b/apps/server/src/bot/statsDigest.ts
index 2da4ca3..e3f5094 100644
--- a/apps/server/src/bot/statsDigest.ts
+++ b/apps/server/src/bot/statsDigest.ts
@@ -1,27 +1,4 @@
-/**
- * Stats-digest scheduler.
- *
- * Once a day or once a week, at a chosen local time, the bot DMs its admins a
- * forwarded/filtered/error summary. Telegram has no wall-clock scheduling
- * primitive and the rest of the app uses fixed-interval pollers, so this is a
- * minute-tick poller that decides on each tick whether the scheduled moment
- * has passed and a digest is still owed.
- *
- * Dedup is by an *occurrence key* — a stable label for "the most recent
- * scheduled time at-or-before now", derived purely from the time zone's
- * wall-clock parts (no epoch/offset/DST math). We send at most once per
- * occurrence and persist the key, which also yields free catch-up: if the
- * server was down across a scheduled time, the next tick after boot still
- * sees an unsent occurrence and sends it.
- *
- * Any change to the schedule (enable/disable, time, day, frequency, zone)
- * re-baselines via a config fingerprint: the current occurrence is marked
- * handled without sending, so editing the schedule never triggers an
- * immediate or backlog blast — the first real send is the next occurrence.
- *
- * The window is [lastSentAt, now): every message is counted in exactly one
- * digest, with no gaps or overlaps.
- */
+// Minute-tick poller (Telegram has no wall-clock scheduler). Dedup + catch-up via an occurrence key derived from wall-clock parts (no DST math); send once per occurrence. Schedule changes re-baseline via config fingerprint so edits never blast. Window is [lastSentAt, now).
 import type { Db } from '../db/client.js';
 import type { Logger } from '../lib/logger.js';
 import { createPoller } from '../lib/poller.js';
@@ -45,19 +22,16 @@ const WEEKDAY_INDEX: Record<string, number> = {
 
 export interface StatsDigestSchedulerDeps {
   db: Db;
-  /** Resolves the current bot; a getter because the ref is swapped on reload. */
+  // Getter because the bot ref is swapped on reload.
   getBot: () => TgFeedBot | undefined;
   logger: Logger;
-  /** Injectable clock (epoch ms) for tests. Defaults to `Date.now`. */
   now?: () => number;
-  /** Tick cadence; defaults to 60s. */
   intervalMs?: number;
 }
 
 export interface StatsDigestScheduler {
   start(): void;
   stop(): void;
-  /** Evaluate the schedule once. Exposed for tests; the poller calls it. */
   runOnce(): Promise<void>;
 }
 
@@ -70,7 +44,6 @@ interface WallClock {
   minute: number;
 }
 
-/** Wall-clock parts of `epochMs` as seen in `timeZone`. */
 function wallClockInZone(epochMs: number, timeZone: string): WallClock {
   const parts = new Intl.DateTimeFormat('en-US', {
     timeZone,
@@ -93,12 +66,7 @@ function wallClockInZone(epochMs: number, timeZone: string): WallClock {
   };
 }
 
-/**
- * Stable key for the most recent scheduled occurrence at-or-before `nowMs`,
- * e.g. `"daily:2026-06-01"` / `"weekly:2026-05-29"`. The date is computed on
- * the zone's wall-clock calendar; we render it via UTC arithmetic purely as an
- * opaque label (no offset needed).
- */
+// Stable label for the most recent scheduled occurrence at-or-before nowMs, e.g. "daily:2026-06-01"; UTC arithmetic is just an opaque renderer.
 export function occurrenceKey(nowMs: number, cfg: StatsDigestConfig): string {
   const wc = wallClockInZone(nowMs, cfg.timezone);
   const [hh, mm] = cfg.time.split(':');
@@ -134,7 +102,6 @@ function escapeHtml(s: string): string {
   return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
-/** Concise HTML body for the bot to DM. */
 export function formatDigest(
   stats: DigestStats,
   sinceMs: number,
@@ -174,8 +141,7 @@ export function createStatsDigestScheduler(deps: StatsDigestSchedulerDeps): Stat
     const state = readStatsDigestState(db);
     const nowMs = now();
 
-    // Schedule changed (or first ever tick) → re-baseline, never send. Record
-    // the current occurrence as handled so the first real send is the next one.
+    // Schedule changed (or first tick) → re-baseline without sending; first real send is the next occurrence.
     if (state.configHash !== hash) {
       writeStatsDigestState(db, {
         lastSentAt: nowMs,
@@ -187,13 +153,12 @@ export function createStatsDigestScheduler(deps: StatsDigestSchedulerDeps): Stat
 
     if (!cfg.enabled) return;
 
-    // Bot down — skip without advancing, so the unsent occurrence is caught up
-    // on a later tick once the bot is back.
+    // Bot down — skip without advancing so the occurrence is caught up later.
     const bot = getBot();
     if (!bot) return;
 
     const key = occurrenceKey(nowMs, cfg);
-    if (key === state.lastKey) return; // already sent for this occurrence
+    if (key === state.lastKey) return;
 
     const since = state.lastSentAt ?? nowMs;
     const stats = getDigestStats(db, since, nowMs);
@@ -211,10 +176,7 @@ export function createStatsDigestScheduler(deps: StatsDigestSchedulerDeps): Stat
       );
     }
 
-    // Advance the occurrence key either way so we attempt at most once per
-    // occurrence (no per-tick retry storm against admins who 403). But only
-    // move the window start when something was actually delivered, so a
-    // fully-undelivered period's counts roll into the next successful digest.
+    // Advance the key either way (at most one attempt per occurrence); move the window start only on delivery so undelivered counts roll forward.
     writeStatsDigestState(db, {
       lastSentAt: delivered > 0 ? nowMs : (state.lastSentAt ?? nowMs),
       lastKey: key,
diff --git a/apps/server/src/bot/testing.ts b/apps/server/src/bot/testing.ts
index 81681f1..8c9c53a 100644
--- a/apps/server/src/bot/testing.ts
+++ b/apps/server/src/bot/testing.ts
@@ -1,13 +1,7 @@
-/**
- * Test helpers for the Telegram Web App auth flow. `signInitData` reproduces
- * Telegram's signing so tests can mint valid `initData` payloads (and, by
- * mutating them, invalid ones).
- */
 import { createHmac } from 'node:crypto';
 
 export const TEST_BOT_TOKEN = '123456:test-bot-token';
 
-/** Build a correctly-signed initData query string from the given fields. */
 export function signInitData(fields: Record<string, string>, token = TEST_BOT_TOKEN): string {
   const dataCheckString = Object.entries(fields)
     .map(([k, v]) => `${k}=${v}`)
diff --git a/apps/server/src/config.ts b/apps/server/src/config.ts
index ea1b9a1..949973f 100644
--- a/apps/server/src/config.ts
+++ b/apps/server/src/config.ts
@@ -1,13 +1,4 @@
-/**
- * Single source of truth for environment configuration.
- *
- * Per docs/AGENTS.md, this is the ONLY module that reads `process.env`.
- * Everything else imports the parsed `config` object.
- *
- * Fields consumed by later chapters are marked optional so the app boots
- * (and migrations run) without filling them in. They tighten to required
- * in the chapter that actually uses them.
- */
+// The only module that reads process.env; everything else imports the parsed `config`. Fields are optional so the app boots (and migrations run) before they're filled in.
 import { z } from 'zod';
 
 const envSchema = z.object({
@@ -19,34 +10,26 @@ const envSchema = z.object({
   // --- Database ---
   DATABASE_PATH: z.string().min(1).default('./data/tg-feed.sqlite'),
 
-  // --- Telegram (Chapter 3) ---
+  // --- Telegram ---
   TG_API_ID: z.coerce.number().int().positive().optional(),
   TG_API_HASH: z.string().min(1).optional(),
   TG_SESSION_STRING: z.string().min(1).optional(),
-  // Base64-encoded 32 random bytes. When set, the settings page can store a
-  // signed-in Telegram account in the DB (encrypted at rest with this key)
-  // and the app prefers that account over `TG_SESSION_STRING`. When unset,
-  // the app falls back to env-only and refuses to write account rows. The
-  // key fingerprint travels in exports so an import on a host with a
-  // different key skips the encrypted blob with a clear warning. Generate:
-  //   node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
+  // base64 32 bytes; when set, DB-stored accounts (encrypted at rest) win over TG_SESSION_STRING, else account writes are refused. Fingerprint travels in exports so a mismatched-key import skips the blob.
+  // Generate: node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
   TG_SESSION_ENCRYPTION_KEY: z
     .string()
     .regex(/^[A-Za-z0-9+/=]+$/, 'expected base64')
     .refine((s) => Buffer.from(s, 'base64').length === 32, 'must decode to 32 bytes')
     .optional(),
 
-  // --- Web auth (Chapter 7) ---
+  // --- Web auth ---
   WEB_PASSWORD: z.string().min(1).optional(),
   SESSION_SECRET: z.string().min(32).optional(),
 
   // --- Telegram Web App bot ---
-  // Bot token from @BotFather. With TG_BOT_ADMIN_IDS set, enables the Telegram
-  // Mini App login and the /start bot (password login stays as a fallback).
+  // @BotFather token; with TG_BOT_ADMIN_IDS set, enables Mini App login + /start bot (password login stays as fallback).
   TG_BOT_TOKEN: z.string().min(1).optional(),
-  // Comma-separated Telegram user ids allowed to use the Mini App / bot, parsed
-  // into a deduped string[] (compared as strings to keep 64-bit ids lossless).
-  // Empty/unset disables Telegram login.
+  // Comma-separated admin user ids → deduped string[]; compared as strings to keep 64-bit ids lossless. Empty disables Telegram login.
   TG_BOT_ADMIN_IDS: z
     .string()
     .optional()
@@ -62,17 +45,14 @@ const envSchema = z.object({
           )
         : [],
     ),
-  // Public HTTPS base URL the web client is served from (e.g.
-  // https://tg-feed.example.com). The bot points its menu / start buttons here.
+  // Public HTTPS base URL the web client is served from; the bot's menu/start buttons point here.
   PUBLIC_URL: z.string().url().optional(),
 });
 
 export type Config = z.infer<typeof envSchema>;
 
 export function parseConfig(env: NodeJS.ProcessEnv = process.env): Config {
-  // dotenv parses `KEY=` as the empty string, but our optional fields use
-  // `.min(N)` / regex constraints that reject `""`. Treat empty strings as
-  // missing so a placeholder line in `.env` doesn't break startup.
+  // Treat empty strings as missing: dotenv parses `KEY=` as "" which our .min/regex optionals reject.
   const cleaned: NodeJS.ProcessEnv = Object.fromEntries(
     Object.entries(env).map(([k, v]) => [k, v === '' ? undefined : v]),
   );
diff --git a/apps/server/src/db/botConfigRepo.ts b/apps/server/src/db/botConfigRepo.ts
index 2632e9c..a0dcd41 100644
--- a/apps/server/src/db/botConfigRepo.ts
+++ b/apps/server/src/db/botConfigRepo.ts
@@ -1,17 +1,4 @@
-/**
- * Repository for the DB-backed bot configuration, stored as JSON in the
- * `app_settings` row keyed `'bot'`. Shape:
- *
- *   { token?: EncryptedEnvelope; admins?: BotAdmin[]; publicUrl?: string }
- *
- * (A legacy `adminIds: string[]` shape from before display-name support is
- * still read and upgraded on the fly.)
- *
- * The token arrives already encrypted; this repo only stores and merges the
- * envelope. Reads are defensive: a missing row or any malformed field yields
- * an absent value, so a hand-edited or partially-written row can't crash the
- * resolver — it just falls back to env.
- */
+// Bot config as JSON in app_settings['bot']. Reads are defensive: a malformed field falls back to env, never throws.
 import { eq } from 'drizzle-orm';
 import type { BotAdmin } from '@tg-feed/shared';
 import type { Db } from './client.js';
@@ -26,10 +13,7 @@ export interface StoredBotConfig {
   publicUrl?: string;
 }
 
-/**
- * Partial update. Per field: `undefined` = leave unchanged, `null` = clear
- * (the resolver then falls back to env), a value = set it.
- */
+// Per field: undefined = unchanged, null = clear (resolver falls back to env), value = set.
 export interface BotConfigPatch {
   token?: EncryptedEnvelope | null;
   admins?: BotAdmin[] | null;
@@ -62,7 +46,7 @@ function asAdmins(value: Record<string, unknown>): BotAdmin[] | undefined {
     }
     return out;
   }
-  // Legacy: an older `adminIds: string[]` shape (pre display-name support).
+  // Legacy adminIds: string[] (pre display-name).
   if (Array.isArray(value.adminIds)) {
     return value.adminIds
       .filter((x): x is string => typeof x === 'string' && /^\d+$/.test(x))
diff --git a/apps/server/src/db/client.ts b/apps/server/src/db/client.ts
index 3403a7e..708dfeb 100644
--- a/apps/server/src/db/client.ts
+++ b/apps/server/src/db/client.ts
@@ -1,9 +1,4 @@
-/**
- * Singleton DB client.
- *
- * App code uses `getDb()`. Tests use `createDb(':memory:')` directly via the
- * helper in `./testing.ts` and never touch the singleton.
- */
+// App code uses getDb(); tests call createDb(':memory:') directly and never touch the singleton.
 import path from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -23,8 +18,7 @@ let cachedProjectRoot: string | undefined;
 function projectRoot(): string {
   if (cachedProjectRoot) return cachedProjectRoot;
   let dir = path.dirname(fileURLToPath(import.meta.url));
-  // Walk up looking for the workspace marker; pnpm-workspace.yaml is a
-  // stable anchor across both `src/` (tsx) and `dist/` (node) layouts.
+  // pnpm-workspace.yaml is a stable anchor across both src/ (tsx) and dist/ (node) layouts.
   while (dir !== path.dirname(dir)) {
     if (existsSync(path.join(dir, 'pnpm-workspace.yaml'))) {
       cachedProjectRoot = dir;
diff --git a/apps/server/src/db/migrate.ts b/apps/server/src/db/migrate.ts
index 100c200..a8fc3d0 100644
--- a/apps/server/src/db/migrate.ts
+++ b/apps/server/src/db/migrate.ts
@@ -1,9 +1,3 @@
-/**
- * Apply pending drizzle migrations to the configured DATABASE_PATH.
- *
- * Invoked via `pnpm db:migrate`. Idempotent — drizzle tracks applied
- * migrations in `__drizzle_migrations__`, so re-running is a no-op.
- */
 import '../lib/loadEnv.js';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -16,13 +10,7 @@ const migrationsFolder = path.resolve(moduleDir, '../../drizzle');
 
 const handle = createDb(config.DATABASE_PATH);
 try {
-  // SQLite table-recreation migrations (the recipe for column drops + FK
-  // changes) require FKs disabled around the rename — otherwise CASCADE
-  // and SET NULL fire when the old table is dropped, wiping referencing
-  // rows. drizzle's migrate() wraps in a transaction where `PRAGMA
-  // foreign_keys` is a no-op, so we have to set it here. The
-  // `foreign_key_check` afterwards verifies the migration left no
-  // orphans before we re-enable enforcement.
+  // FKs off around table-recreation migrations, else CASCADE/SET NULL fire on the old-table drop and wipe referencing rows; migrate()'s transaction makes the PRAGMA a no-op so set it here. foreign_key_check verifies no orphans before re-enabling.
   handle.sqlite.pragma('foreign_keys = OFF');
   try {
     migrate(handle.db, { migrationsFolder });
diff --git a/apps/server/src/db/schema.ts b/apps/server/src/db/schema.ts
index 4797e9f..26487c9 100644
--- a/apps/server/src/db/schema.ts
+++ b/apps/server/src/db/schema.ts
@@ -1,14 +1,4 @@
-/**
- * Drizzle schema for the tg-feed SQLite database.
- *
- * Telegram chat / message IDs are stored as `text` (lossless, opaque) since
- * they're 64-bit identifiers, not numbers we range-query on.
- *
- * Timestamps: `timestamp_ms` (Date in JS, millis in SQLite). Defaults are
- * applied JS-side via `$defaultFn` — all writes go through drizzle.
- *
- * JSON columns use drizzle's `mode: 'json'` for automatic parse/stringify.
- */
+// Telegram 64-bit chat/message IDs stored as text (lossless, opaque, never range-queried).
 import { sql } from 'drizzle-orm';
 import { sqliteTable, text, integer, index, check, primaryKey } from 'drizzle-orm/sqlite-core';
 import {
@@ -23,48 +13,22 @@ import {
 
 export { FORWARD_LOG_STATUSES, type ForwardLogStatus };
 
-/**
- * Named forward target. Subscriptions pick from this list (Chapter 10).
- * Same chat id can appear under multiple names — unique-by-id, not chatId.
- */
 export const destinations = sqliteTable('destinations', {
   id: integer('id').primaryKey({ autoIncrement: true }),
   name: text('name').notNull(),
   chatId: text('chat_id').notNull(),
   note: text('note'),
-  /**
-   * Forum topic to forward into, when `chatId` is a forum supergroup. Holds
-   * the topic's `top_msg_id`; stored as text for consistency with the other
-   * 64-bit ids and converted to a number only at the forward boundary. NULL
-   * means "no explicit topic" — the General topic for a forum, or the only
-   * behaviour for a normal chat.
-   */
+  // forum topic top_msg_id (text for 64-bit parity); NULL = General/none
   topicId: text('topic_id'),
-  /**
-   * Topic title cached at create/edit time so the list and badges render
-   * without a live `channels.GetForumTopics` round-trip. NULL whenever
-   * `topicId` is NULL.
-   */
+  // cached topic title; NULL whenever topicId is NULL
   topicTitle: text('topic_title'),
-  /**
-   * Channel/chat profile photo as a `data:image/jpeg;base64,...` URL, or
-   * NULL when we haven't fetched one yet (the trigger for the access
-   * monitor's lazy backfill). Populated on create when Telegram is
-   * configured and refreshed by the access monitor on the periodic sweep
-   * for rows that are still null.
-   */
+  // data:image/jpeg;base64 URL; NULL until the access monitor's lazy backfill fetches it
   iconDataUrl: text('icon_data_url'),
-  /**
-   * Whether the userbot can currently see/post to this destination. Written
-   * by the access monitor (`apps/server/src/tg/accessMonitor.ts`) on the
-   * periodic sweep. Default 'ok' so existing rows aren't surfaced as broken
-   * before the first sweep runs.
-   */
+  // written by the access monitor's sweep; default 'ok' so unswept rows aren't shown as broken
   accessStatus: text('access_status', { enum: ['ok', 'no_access'] })
     .notNull()
     .default('ok')
     .$type<'ok' | 'no_access'>(),
-  /** Timestamp of the last access check; null until the first sweep runs. */
   accessCheckedAt: integer('access_checked_at', { mode: 'timestamp_ms' }),
   createdAt: integer('created_at', { mode: 'timestamp_ms' })
     .notNull()
@@ -77,56 +41,27 @@ export const subscriptions = sqliteTable(
     id: integer('id').primaryKey({ autoIncrement: true }),
     sourceChatId: text('source_chat_id').notNull(),
     sourceTitle: text('source_title').notNull(),
-    /**
-     * Display handle (`@channel_username`). Populated on create from the
-     * resolve endpoint's response; nullable for legacy rows.
-     */
+    // @channel_username; nullable for legacy rows
     handle: text('handle'),
-    /**
-     * Source channel profile photo as a `data:image/jpeg;base64,...` URL,
-     * or NULL when we haven't fetched one yet. Same lazy-backfill semantics
-     * as `destinations.iconDataUrl` — populated on create and refreshed by
-     * the access monitor for rows that are still null.
-     */
     iconDataUrl: text('icon_data_url'),
-    /**
-     * FK → destinations. Nullable: a subscription can exist without a
-     * destination (created via import where the destination is missing, or
-     * detached by the user). The forwarder skips such rows. ON DELETE SET
-     * NULL so deleting a destination demotes its subscriptions to detached
-     * rather than blocking the delete.
-     */
+    // nullable: subscription may be detached; ON DELETE SET NULL demotes rather than blocks
     destinationId: integer('destination_id').references(() => destinations.id, {
       onDelete: 'set null',
     }),
     enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
-    /**
-     * Timestamp of the last `CHAT_FORWARDS_RESTRICTED` from this source.
-     * Set by the forwarder when Telegram refuses to forward (the channel
-     * has "Restrict Saving Content" enabled). Cleared on the next
-     * successful forward. Surfaced in the API as `forwardingRestrictedAt`
-     * so the UI can render a "noforwards" badge on the subscription.
-     */
+    // set on CHAT_FORWARDS_RESTRICTED (source has "Restrict Saving Content"), cleared on next success
     forwardingRestrictedAt: integer('forwarding_restricted_at', { mode: 'timestamp_ms' }),
-    /**
-     * Whether the userbot can currently read messages from this source
-     * channel. Written on subscription create (after `channels.JoinChannel`)
-     * and on every access-monitor sweep. Default 'ok' so existing rows
-     * aren't surfaced as broken before the first sweep runs.
-     */
     sourceAccessStatus: text('source_access_status', { enum: ['ok', 'no_access'] })
       .notNull()
       .default('ok')
       .$type<'ok' | 'no_access'>(),
-    /** Timestamp of the last access check; null until the first sweep runs. */
     sourceAccessCheckedAt: integer('source_access_checked_at', { mode: 'timestamp_ms' }),
     createdAt: integer('created_at', { mode: 'timestamp_ms' })
       .notNull()
       .$defaultFn(() => new Date()),
   },
   (t) => ({
-    // Listener queries by source_chat_id on every incoming TG message; index
-    // turns the per-event lookup from a full scan into an index probe.
+    // every incoming TG message looks up by source_chat_id
     bySourceChatId: index('idx_subscriptions_source_chat_id').on(t.sourceChatId),
   }),
 );
@@ -141,12 +76,7 @@ export const subscriptionFilters = sqliteTable(
     ruleType: text('rule_type').notNull().$type<FilterRuleType>(),
     params: text('params', { mode: 'json' }).$type<AnyFilterRuleParams>().notNull(),
     enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
-    /**
-     * Per-filter mode (Ch 14). 'include' is the legacy default and matches
-     * the original AND-pass semantics. 'exclude' inverts the rule for that
-     * one row — the filter rejects when its rule matches. SQL CHECK keeps
-     * hand-written rows honest, mirroring the `forward_log.status` precedent.
-     */
+    // 'include' = AND-pass; 'exclude' inverts (reject when the rule matches)
     mode: text('mode').notNull().default('include').$type<FilterMode>(),
   },
   (t) => ({
@@ -158,14 +88,7 @@ export const subscriptionFilters = sqliteTable(
   }),
 );
 
-/**
- * Reusable named filter rules (Chapter 11). Same per-rule params shape as
- * `subscription_filters` but carry a `name` so users can recognise them when
- * attaching across subscriptions. Rule type is constrained both via TS
- * (`$type<FilterRuleType>()`) and a SQL CHECK constraint, mirroring the
- * `forward_log.status` precedent — the TS narrowing alone wouldn't reject
- * a hand-written DB row.
- */
+// Reusable named filter rules; rule type also guarded by a SQL CHECK against hand-written rows.
 export const libraryFilters = sqliteTable(
   'library_filters',
   {
@@ -173,7 +96,6 @@ export const libraryFilters = sqliteTable(
     name: text('name').notNull(),
     ruleType: text('rule_type').notNull().$type<FilterRuleType>(),
     params: text('params', { mode: 'json' }).$type<AnyFilterRuleParams>().notNull(),
-    /** Same semantics as `subscription_filters.mode`. */
     mode: text('mode').notNull().default('include').$type<FilterMode>(),
     createdAt: integer('created_at', { mode: 'timestamp_ms' })
       .notNull()
@@ -191,15 +113,7 @@ export const libraryFilters = sqliteTable(
   }),
 );
 
-/**
- * M:N join — a library filter attached to a subscription. No `enabled`
- * column: detach == off, reattach == on, single source of truth (matches
- * the design's "X to detach" affordance).
- *
- * Composite PK on (subscriptionId, libraryFilterId) gives uniqueness
- * automatically; `idx_subscription_library_filters_lib` accelerates the
- * "where used" lookup the library tab needs for usage badges.
- */
+// M:N join. No `enabled` column: detach == off, reattach == on.
 export const subscriptionLibraryFilters = sqliteTable(
   'subscription_library_filters',
   {
@@ -221,27 +135,12 @@ export const appSettings = sqliteTable('app_settings', {
   value: text('value', { mode: 'json' }).$type<unknown>().notNull(),
 });
 
-/**
- * Single-row table for the Telegram session signed in via the Settings page.
- * Convention: always upserted at id=1 — the table is logically a singleton
- * but uses a normal PK so `onConflictDoUpdate` works without an INSERT/UPDATE
- * branch.
- *
- * `encrypted_session_string` is `base64(iv ‖ tag ‖ ct)` of the raw gramjs
- * `StringSession.save()` value, encrypted with `TG_SESSION_ENCRYPTION_KEY`.
- * `key_fingerprint` is the first 16 hex chars of `sha256(key)` so an
- * exported row can be matched against the importing host's key without
- * exposing either key.
- *
- * Metadata fields (`phone_number`, `display_name`, `username`,
- * `telegram_user_id`) come from `getMe()` after a successful sign-in. They
- * are nullable because the raw-paste flow may produce a session whose
- * `getMe` returns partial data, and because future schema bumps may add
- * fields.
- */
+// Singleton, always upserted at id=1 (normal PK so onConflictDoUpdate has no INSERT/UPDATE branch).
 export const telegramAccount = sqliteTable('telegram_account', {
   id: integer('id').primaryKey(),
+  // base64(iv ‖ tag ‖ ct) of StringSession.save(), encrypted with TG_SESSION_ENCRYPTION_KEY
   encryptedSessionString: text('encrypted_session_string').notNull(),
+  // first 16 hex of sha256(key); matches an exported row against a host key without exposing it
   keyFingerprint: text('key_fingerprint').notNull(),
   phoneNumber: text('phone_number'),
   displayName: text('display_name'),
@@ -266,13 +165,7 @@ export const forwardLog = sqliteTable(
     destMessageId: text('dest_message_id'),
     status: text('status', { enum: FORWARD_LOG_STATUSES }).notNull(),
     error: text('error'),
-    /**
-     * JSON snapshot of the raw gramjs `Message` (captured at the listener /
-     * history poller boundary). For album batches every row stores the same
-     * N-element array; for single-message forwards a plain object. Nullable
-     * for rows written before the column existed (and for `MessageEmpty` /
-     * `MessageService` events that we deliberately drop in `toJsonSafe`).
-     */
+    // raw gramjs Message snapshot; album batches store the same N-element array on every row
     rawMessage: text('raw_message', { mode: 'json' }),
     createdAt: integer('created_at', { mode: 'timestamp_ms' })
       .notNull()
@@ -312,18 +205,8 @@ export type NewTelegramAccount = typeof telegramAccount.$inferInsert;
 export type ForwardLogEntry = typeof forwardLog.$inferSelect;
 export type NewForwardLogEntry = typeof forwardLog.$inferInsert;
 
-/**
- * Per-login session row.
- *
- * Replaces the legacy "static cookie value + signed by SESSION_SECRET" scheme
- * with opaque random tokens, so logout actually invalidates a session and a
- * stolen cookie has a single revocation point. The token in the cookie is the
- * primary-key lookup against this table.
- *
- * `expiresAt` is the hard cap; `lastSeenAt` is updated on each authed request
- * for the sliding-window refresh (limits damage from a leaked cookie that
- * sits unused). A background prune sweeps rows past expiry.
- */
+// Opaque per-login tokens (cookie value is the PK lookup); logout deletes the row to revoke.
+// expiresAt is the hard cap; lastSeenAt drives the sliding-window refresh.
 export const webSessions = sqliteTable(
   'web_sessions',
   {
diff --git a/apps/server/src/db/statsDigestStateRepo.ts b/apps/server/src/db/statsDigestStateRepo.ts
index 29b55cf..f92be10 100644
--- a/apps/server/src/db/statsDigestStateRepo.ts
+++ b/apps/server/src/db/statsDigestStateRepo.ts
@@ -1,11 +1,4 @@
-/**
- * Scheduler state for the stats digest, stored as JSON in the `app_settings`
- * row keyed `'stats_digest_state'`. Kept separate from the user-editable
- * `'global'` settings row so the scheduler's bookkeeping never collides with
- * the Settings PUT merge.
- *
- * Reads are defensive: a missing or malformed row reads as the empty baseline.
- */
+// Stats-digest scheduler state, kept in its own app_settings row so it never collides with the user-editable 'global' Settings merge; missing/malformed reads as the empty baseline.
 import { eq } from 'drizzle-orm';
 import type { Db } from './client.js';
 import { appSettings } from './schema.js';
@@ -13,16 +6,10 @@ import { appSettings } from './schema.js';
 export const STATS_DIGEST_STATE_KEY = 'stats_digest_state';
 
 export interface StatsDigestState {
-  /** Epoch ms of the last send (or baseline). null before the first tick. */
+  // Epoch ms of the last send/baseline.
   lastSentAt: number | null;
-  /** Occurrence key of the last send/baseline. null before the first tick. */
   lastKey: string | null;
-  /**
-   * Fingerprint of the schedule config at the last tick. When it changes
-   * (enable/disable, time, day, frequency, time zone), the scheduler
-   * re-baselines instead of sending — so editing the schedule never fires an
-   * immediate or backlog digest. null before the first tick.
-   */
+  // Schedule-config fingerprint; on change the scheduler re-baselines instead of firing a backlog digest.
   configHash: string | null;
 }
 
diff --git a/apps/server/src/db/telegramAccountRepo.ts b/apps/server/src/db/telegramAccountRepo.ts
index 01902b5..4b7f0d2 100644
--- a/apps/server/src/db/telegramAccountRepo.ts
+++ b/apps/server/src/db/telegramAccountRepo.ts
@@ -1,11 +1,4 @@
-/**
- * Repository for the single-row `telegram_account` table.
- *
- * The row is logically a singleton: every write goes to id=1 via
- * `onConflictDoUpdate`, every read returns the row or null. Callers never
- * see the encryption key here — they pass already-encrypted blobs in and
- * decryption happens at the call site (see `tg/client.ts`).
- */
+// Singleton `telegram_account` row (id=1). Callers pass already-encrypted blobs; no crypto here.
 import { eq } from 'drizzle-orm';
 import type { Db } from './client.js';
 import { telegramAccount, type TelegramAccount } from './schema.js';
@@ -55,7 +48,6 @@ export function upsertAccount(db: Db, payload: UpsertTelegramAccountInput): Tele
     .run();
   const row = getActiveAccount(db);
   if (!row) {
-    // Should be impossible — the upsert above just wrote id=1.
     throw new Error('telegram_account row vanished after upsert');
   }
   return row;
diff --git a/apps/server/src/db/testing.ts b/apps/server/src/db/testing.ts
index 4fe7134..361a013 100644
--- a/apps/server/src/db/testing.ts
+++ b/apps/server/src/db/testing.ts
@@ -1,10 +1,3 @@
-/**
- * Test fixture: an in-memory SQLite DB with all migrations applied.
- *
- * Use per-test via beforeEach/afterEach for clean isolation. Setup is
- * sub-millisecond after the first call (better-sqlite3 keeps native code
- * loaded; migrations are tiny CREATE TABLE statements).
- */
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
@@ -20,9 +13,7 @@ export interface TestDbHandle {
 
 export function createTestDb(): TestDbHandle {
   const handle: DbHandle = createDb(':memory:');
-  // Mirror migrate.ts — disable FKs around migrate() so table-recreation
-  // migrations (column drops, FK changes) don't trigger CASCADE/SET NULL
-  // on rename.
+  // FKs off around migrate() so table-recreation migrations don't trigger CASCADE/SET NULL on rename.
   handle.sqlite.pragma('foreign_keys = OFF');
   try {
     migrate(handle.db, { migrationsFolder });
diff --git a/apps/server/src/events/bus.ts b/apps/server/src/events/bus.ts
index 8906e81..977c1cb 100644
--- a/apps/server/src/events/bus.ts
+++ b/apps/server/src/events/bus.ts
@@ -1,23 +1,5 @@
-/**
- * In-process event bus.
- *
- * Producers (forwarder, filter evaluator, subscription routes) call `emit`
- * with a `StreamEventInput`; the bus stamps `occurredAt` and broadcasts to
- * every subscriber. The SSE route is the only consumer in v1, but the bus
- * stays general so future consumers (metrics, audit log, etc.) can attach
- * without coupling to producers.
- *
- * Implementation choice: a plain `Set<Listener>` instead of
- * `node:events.EventEmitter`. `EventEmitter.emit` rethrows synchronously
- * when a listener throws, which would propagate a buggy SSE write back up
- * into a forwarding-pipeline call site. We catch per-listener errors here,
- * log them, and keep going. `listenerCount()` becomes `set.size` — used by
- * the SSE cleanup test to verify unsubscribe ran on disconnect.
- *
- * Listener iteration snapshots the set first (`[...listeners]`) so a
- * listener that unsubscribes itself during dispatch doesn't mutate the
- * iterator mid-loop.
- */
+// Plain Set, not EventEmitter, so a throwing listener can't rethrow into a forwarding-pipeline call site.
+// Dispatch snapshots the set so a listener unsubscribing itself mid-loop doesn't mutate the iterator.
 import type { StreamEvent, StreamEventInput } from '@tg-feed/shared';
 import type { Logger } from '../lib/logger.js';
 
diff --git a/apps/server/src/filters/evaluate.ts b/apps/server/src/filters/evaluate.ts
index 62457af..c58edaa 100644
--- a/apps/server/src/filters/evaluate.ts
+++ b/apps/server/src/filters/evaluate.ts
@@ -1,24 +1,5 @@
-/**
- * Filter evaluator.
- *
- * Loads enabled filters for a subscription — both per-sub
- * (`subscription_filters` where `enabled=true`) and library filters
- * attached via `subscription_library_filters` — runs each through its
- * registered rule, AND-combines, and on failure writes one `forward_log`
- * row per source message id (status `'filtered'`, reasons joined into
- * the `error` column).
- *
- * Reasons format:
- * - per-sub: `"<ruleType>: <reason>"`
- * - library: `"library:<name>: <ruleType>: <reason>"` so the activity UI
- *   can split on the `library:` prefix and render a Library chip.
- *
- * Fail-open semantics from Ch 6 are preserved across both sources: an
- * unknown ruleType, a zod params parse failure, or a runtime throw inside
- * a rule's `evaluate` skips that single row (with a warning). The
- * remaining rules still gate the message. Empty surviving filter set
- * passes (vacuous AND).
- */
+// AND-combines a subscription's per-sub + library filter rules; fail-open (unknown rule, bad params, or a throw skips that one row with a warning).
+// Reason format: `library:<name>: <ruleType>: <reason>` for library rows (UI splits on the `library:` prefix), else `<ruleType>: <reason>`.
 import { and, asc, eq } from 'drizzle-orm';
 import type { Db } from '../db/client.js';
 import {
@@ -53,12 +34,7 @@ interface PureEvaluation {
   reasons: string[];
 }
 
-/**
- * Row shape consumed by the pure evaluator. `source` distinguishes per-sub
- * vs library; `label` is the library filter name (null for per-sub). `mode`
- * inverts the rule for that one row when set to `'exclude'` — the filter
- * rejects when its rule matches instead of when it doesn't.
- */
+// mode 'exclude' inverts the row: it rejects when the rule matches.
 export interface EvaluatorRow {
   id: number;
   source: 'sub' | 'lib';
@@ -82,9 +58,7 @@ export function createFilterEvaluator(deps: CreateFilterEvaluatorDeps): FilterEv
       if (result.pass) return { pass: true };
 
       const errorText = result.reasons.join('; ');
-      // Denormalize the raw payload onto every filtered row so each row is
-      // independently inspectable in the Activity JSON viewer, mirroring
-      // the sent/failed paths in `forwarder.writeLogs`.
+      // Denormalize the raw payload onto every row so each is independently inspectable.
       const rawMessage = context.rawMessage ?? null;
       const inserted = db
         .insert(forwardLog)
@@ -121,19 +95,7 @@ export function createFilterEvaluator(deps: CreateFilterEvaluatorDeps): FilterEv
   };
 }
 
-/**
- * Load all evaluatable filters for a subscription as a single ordered list.
- *
- * Per-sub filters (where `enabled=true`) and library filters attached via
- * `subscription_library_filters` are loaded with two selects and merged in
- * JS. Library rows come first (`source ASC: 'lib' < 'sub'`), then by id.
- *
- * Two queries instead of a SQL UNION because drizzle's mapped JSON columns
- * (`mode: 'json'` in the schema) flow through cleanly per-table; a raw
- * UNION returns columns as strings and would need manual `JSON.parse`. The
- * cost is one extra round-trip on a hot path — for personal-use volumes
- * (single-digit messages/sec at most) this is comfortably below noise.
- */
+// Two selects merged in JS (library rows first, then by id) rather than a SQL UNION, which would stringify drizzle's JSON columns.
 export function loadEvaluatorRows(db: Db, subscriptionId: number): EvaluatorRow[] {
   const subRows = db
     .select({
@@ -190,10 +152,7 @@ export function loadEvaluatorRows(db: Db, subscriptionId: number): EvaluatorRow[
   return merged;
 }
 
-/**
- * Pure evaluation — no side effects. Exported for unit tests; the public
- * `FilterEvaluator.evaluate` method is what production wiring calls.
- */
+// Pure evaluation, no side effects; the side-effecting wrapper is FilterEvaluator.evaluate.
 export function evaluateFilters(
   rows: readonly EvaluatorRow[],
   registry: FilterRegistry,
@@ -237,9 +196,6 @@ export function evaluateFilters(
       continue;
     }
 
-    // include: row fails when the rule did NOT match; exclude inverts that —
-    // the row fails when the rule DID match. Either way, a failing row
-    // contributes a reason and the message is rejected (AND-combined).
     const blocks = row.mode === 'exclude' ? evaluation.pass : !evaluation.pass;
     if (blocks) {
       const reason =
diff --git a/apps/server/src/filters/index.ts b/apps/server/src/filters/index.ts
index de1007d..6146613 100644
--- a/apps/server/src/filters/index.ts
+++ b/apps/server/src/filters/index.ts
@@ -1,13 +1,3 @@
-/**
- * Filter framework barrel.
- *
- * Adding a new rule:
- *   1. Drop `apps/server/src/filters/rules/<name>.ts` exporting a
- *      `FilterRule<'<name>'>` value.
- *   2. Add a matching schema entry in `packages/shared/src/filters.ts`.
- *   3. Register it in `apps/server/src/filters/rules/index.ts`'s
- *      `createDefaultRegistry()`.
- */
 export type {
   FilterEvaluationResult,
   FilterRule,
diff --git a/apps/server/src/filters/registry.ts b/apps/server/src/filters/registry.ts
index d706f1a..ac95050 100644
--- a/apps/server/src/filters/registry.ts
+++ b/apps/server/src/filters/registry.ts
@@ -1,16 +1,4 @@
-/**
- * Filter rule registry.
- *
- * Factory pattern — `createRegistry()` returns a fresh, empty registry.
- * Production wiring builds one via `createDefaultRegistry()` (in
- * `rules/index.ts`) and registers all v1 rules; tests can build empty or
- * partial registries without import-order side effects.
- *
- * `register` accepts a statically-typed `FilterRule<T>` and stores it as a
- * type-erased `RegisteredFilterRule`. The cast is the boundary: at register
- * time the rule's `T` ↔ params correlation is known; once retrieved by string
- * lookup, the relationship is gone and runtime zod validation takes over.
- */
+// register() type-erases FilterRule<T> to RegisteredFilterRule; the T↔params link is lost on lookup, so runtime zod validates.
 import type { FilterRuleType } from '@tg-feed/shared';
 import type { FilterRule, RegisteredFilterRule } from './types.js';
 
diff --git a/apps/server/src/filters/rules/index.ts b/apps/server/src/filters/rules/index.ts
index f4e054b..5174f68 100644
--- a/apps/server/src/filters/rules/index.ts
+++ b/apps/server/src/filters/rules/index.ts
@@ -1,8 +1,4 @@
-/**
- * Default rule registry — instantiates a fresh registry and registers all
- * v1 rules. Adding a rule = drop a file in this directory and add one
- * `register(...)` line below.
- */
+// Add a rule: drop a file here and add one register(...) line below.
 import { createRegistry, type FilterRegistry } from '../registry.js';
 import { hasMediaRule } from './hasMedia.js';
 import { minLengthRule } from './minLength.js';
diff --git a/apps/server/src/filters/rules/textRegex.test.ts b/apps/server/src/filters/rules/textRegex.test.ts
index 4adf22a..53dfabf 100644
--- a/apps/server/src/filters/rules/textRegex.test.ts
+++ b/apps/server/src/filters/rules/textRegex.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import type { MessageContext } from '../types.js';
-import { textRegexRule } from './textRegex.js';
+import { getCompiledRegex, textRegexRule } from './textRegex.js';
 
 const ctx = (overrides: Partial<MessageContext> = {}): MessageContext => ({
   text: '',
@@ -34,6 +34,12 @@ describe('textRegexRule', () => {
     expect(() => textRegexRule.evaluate(ctx({ text: 'x' }), { pattern: '(', flags: '' })).toThrow();
   });
 
+  it('memoizes compiled RE2 instances by pattern+flags', () => {
+    const a = getCompiledRegex('foo', 'i');
+    expect(getCompiledRegex('foo', 'i')).toBe(a);
+    expect(getCompiledRegex('foo', '')).not.toBe(a);
+  });
+
   it('does not catastrophically backtrack on pathological pattern (RE2 is linear-time)', () => {
     // (a+)+$ on a long run of `a` followed by `b` is the textbook ReDoS case
     // for native RegExp — exponential backtracking. RE2 finishes in linear time.
diff --git a/apps/server/src/filters/rules/textRegex.ts b/apps/server/src/filters/rules/textRegex.ts
index 1652355..447538c 100644
Binary files a/apps/server/src/filters/rules/textRegex.ts and b/apps/server/src/filters/rules/textRegex.ts differ
diff --git a/apps/server/src/filters/types.ts b/apps/server/src/filters/types.ts
index be11b4f..cbff6e9 100644
--- a/apps/server/src/filters/types.ts
+++ b/apps/server/src/filters/types.ts
@@ -1,17 +1,5 @@
-/**
- * Internal filter types.
- *
- * `MessageContext` is the subset of message data filters need — text body,
- * media presence, sender username. The forwarding pipeline's `MatchableEvent`
- * structurally satisfies this, so the listener can hand a matchable event
- * straight to the evaluator without transformation.
- *
- * Rule definitions are statically typed via `FilterRule<T>`, but the
- * registry/evaluator boundary erases the connection between a rule's `type`
- * and its params shape (params come from a JSON column and are runtime-
- * validated by the rule's own zod schema). The type-erased
- * `RegisteredFilterRule` is what the registry stores and exposes.
- */
+// MatchableEvent structurally satisfies MessageContext, so the listener feeds the evaluator without transforming.
+// RegisteredFilterRule is the type-erased form the registry stores: the type->params link is lost across the JSON/zod boundary.
 import type { z } from 'zod';
 import type { FilterRuleParamsFor, FilterRuleType } from '@tg-feed/shared';
 
@@ -19,13 +7,7 @@ export interface MessageContext {
   text: string;
   hasMedia: boolean;
   senderUsername?: string;
-  /**
-   * Carrier for the raw-message JSON snapshot. The filter rules themselves
-   * don't read this — it rides through `evaluate()` only so the rejection
-   * path can persist it on the `forward_log` row alongside the reasons.
-   * Single object for non-albums, array for albums (aligned with the
-   * `sourceMessageIds` the evaluator receives).
-   */
+  // Unread by rules; rides through evaluate() so the rejection path can persist it on forward_log. Array for albums.
   rawMessage?: unknown;
 }
 
diff --git a/apps/server/src/filters/validateParams.test.ts b/apps/server/src/filters/validateParams.test.ts
new file mode 100644
index 0000000..5d30270
--- /dev/null
+++ b/apps/server/src/filters/validateParams.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { ValidationError } from '../lib/errors.js';
+import { assertFilterParamsCompilable } from './validateParams.js';
+
+describe('assertFilterParamsCompilable', () => {
+  it('accepts a valid text-regex pattern', () => {
+    expect(() =>
+      assertFilterParamsCompilable('text-regex', { pattern: 'foo', flags: 'i' }),
+    ).not.toThrow();
+  });
+
+  it('rejects an uncompilable text-regex pattern with ValidationError', () => {
+    expect(() => assertFilterParamsCompilable('text-regex', { pattern: '(', flags: '' })).toThrow(
+      ValidationError,
+    );
+  });
+
+  it('is a no-op for non-regex rule types', () => {
+    expect(() => assertFilterParamsCompilable('text-contains', { value: 'x' })).not.toThrow();
+  });
+});
diff --git a/apps/server/src/filters/validateParams.ts b/apps/server/src/filters/validateParams.ts
new file mode 100644
index 0000000..9eba4f5
--- /dev/null
+++ b/apps/server/src/filters/validateParams.ts
@@ -0,0 +1,17 @@
+import { ValidationError } from '../lib/errors.js';
+import { getCompiledRegex } from './rules/textRegex.js';
+
+// Write-time validation beyond the zod schema: a text-regex pattern must actually compile,
+// so an invalid one is rejected at save time instead of failing open per-message at eval.
+// Assumes params already passed their zod schema (pattern/flags are strings).
+export function assertFilterParamsCompilable(ruleType: string, params: unknown): void {
+  if (ruleType !== 'text-regex') return;
+  const { pattern, flags } = params as { pattern: string; flags?: string };
+  try {
+    getCompiledRegex(pattern, flags ?? '');
+  } catch (err) {
+    throw new ValidationError(
+      `invalid text-regex pattern: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
diff --git a/apps/server/src/forwarding/albumDebouncer.test.ts b/apps/server/src/forwarding/albumDebouncer.test.ts
index ea7ea47..9cacf43 100644
--- a/apps/server/src/forwarding/albumDebouncer.test.ts
+++ b/apps/server/src/forwarding/albumDebouncer.test.ts
@@ -120,19 +120,32 @@ describe('createAlbumDebouncer', () => {
     expect(downstream.jobs[0]?.sourceMessageIds).toEqual(['10', '11', '12']);
   });
 
-  it('keys by sourceChatId so the same groupedId from two different chats does not conflate', async () => {
+  it('keys by subscriptionId so a fan-out source keeps each subscription album separate', async () => {
     const downstream = makeDownstream();
     const debouncer = makeDebouncer({ downstream, filterEvaluator: passEvaluator });
 
-    debouncer.enqueue(raw({ sourceChatId: '-100A', sourceMessageId: '1', groupedId: 'g' }));
-    debouncer.enqueue(raw({ sourceChatId: '-100B', sourceMessageId: '2', groupedId: 'g' }));
+    // Same source + same album (groupedId), two subscriptions → two destinations.
+    debouncer.enqueue(
+      raw({ subscriptionId: 1, destinationChatId: '-100D1', sourceMessageId: '1', groupedId: 'g' }),
+    );
+    debouncer.enqueue(
+      raw({ subscriptionId: 1, destinationChatId: '-100D1', sourceMessageId: '2', groupedId: 'g' }),
+    );
+    debouncer.enqueue(
+      raw({ subscriptionId: 2, destinationChatId: '-100D2', sourceMessageId: '1', groupedId: 'g' }),
+    );
+    debouncer.enqueue(
+      raw({ subscriptionId: 2, destinationChatId: '-100D2', sourceMessageId: '2', groupedId: 'g' }),
+    );
 
     await vi.advanceTimersByTimeAsync(TEST_WINDOW_MS);
 
+    // Two independent batches, one per subscription/destination — not conflated into one.
     expect(downstream.jobs).toHaveLength(2);
-    const bySource = new Map(downstream.jobs.map((j) => [j.sourceChatId, j.sourceMessageIds]));
-    expect(bySource.get('-100A')).toEqual(['1']);
-    expect(bySource.get('-100B')).toEqual(['2']);
+    const byDest = new Map(downstream.jobs.map((j) => [j.destinationChatId, j.sourceMessageIds]));
+    expect(byDest.get('-100D1')).toEqual(['1', '2']);
+    expect(byDest.get('-100D2')).toEqual(['1', '2']);
+    expect(new Set(downstream.jobs.map((j) => j.subscriptionId))).toEqual(new Set([1, 2]));
   });
 
   it('treats a straggler arriving after the window as a new group', async () => {
diff --git a/apps/server/src/forwarding/albumDebouncer.ts b/apps/server/src/forwarding/albumDebouncer.ts
index 10eef5c..b246caf 100644
--- a/apps/server/src/forwarding/albumDebouncer.ts
+++ b/apps/server/src/forwarding/albumDebouncer.ts
@@ -1,31 +1,4 @@
-/**
- * Album / grouped-media debouncer + filter gate.
- *
- * Telegram delivers album members (photos/videos sharing a `groupedId`) as N
- * independent `NewMessage` events arriving milliseconds apart. Without
- * debouncing they would be forwarded as N separate messages — fragmenting the
- * album in the destination and burning N throttle slots.
- *
- * This module sits between the listener (which produces one `RawForwardJob`
- * per event) and the per-destination pipeline (which consumes one
- * `ForwardJob` carrying the full id list). For ungrouped messages the
- * debouncer evaluates filters and either passes the job through or drops it.
- * For grouped messages it buffers by `${sourceChatId}:${groupedId}` for
- * `ALBUM_DEBOUNCE_MS`, picks the caption-bearing member at flush time
- * (longest text; ties broken by lowest message id), and evaluates filters
- * once against that member's content — so an album passes or fails as a
- * unit. Source ids in the emitted `ForwardJob` are sorted ascending and
- * de-duplicated.
- *
- * On filter rejection the evaluator writes one `forward_log` row per source
- * id with `status='filtered'` and the joined reasons in `error`. The
- * debouncer itself never touches `forward_log`.
- *
- * `stop()` cancels pending timers and drops their buffered jobs (matches the
- * pipeline's "ignore enqueue after stop" behavior in `queue.ts`). The
- * listener doesn't persist incoming messages anywhere, so a missed album
- * member at shutdown is no different from any other miss while offline.
- */
+// Albums arrive as N NewMessage events sharing a groupedId; buffer per `${subscriptionId}:${groupedId}` to forward+filter as one (per-sub so a fan-out source keeps each subscription's album separate).
 import type { FilterEvaluator } from '../filters/evaluate.js';
 import type { MessageContext } from '../filters/types.js';
 import type { Logger } from '../lib/logger.js';
@@ -40,12 +13,7 @@ export interface AlbumDebouncerDeps {
   downstream: ForwardingHandle;
   filterEvaluator: FilterEvaluator;
   logger: Logger;
-  /**
-   * Live-reads the debounce window from app_settings on each new album.
-   * Wired up to `getAlbumDebounceMs(db)` in production; tests pass a
-   * constant. Read per-album rather than per-debouncer so the Settings
-   * UI takes effect on the next album without a restart.
-   */
+  // Read per-album so a Settings change to the window takes effect without a restart.
   getWindowMs: () => number;
 }
 
@@ -66,11 +34,7 @@ export function createAlbumDebouncer(deps: AlbumDebouncerDeps): AlbumDebouncer {
     const first = group.jobs[0]!;
     const sourceMessageIds = dedupeAndSort(group.jobs.map((j) => j.sourceMessageId));
     const captionMember = pickCaptionBearingMember(group.jobs);
-    // Build the per-album raw payload as an array aligned with
-    // `sourceMessageIds` (ascending numeric id, deduplicated). Both arrays
-    // are constructed from the same ordering so positions match — the
-    // forwarder stores this array verbatim onto every row of the album so
-    // any row can stand alone in the JSON viewer.
+    // Aligned 1:1 with sourceMessageIds; stored on every album row so any row can stand alone.
     const albumRawMessage = collectAlbumRawMessages(group.jobs, sourceMessageIds);
     const context: MessageContext = {
       ...toContext(captionMember),
@@ -120,7 +84,7 @@ export function createAlbumDebouncer(deps: AlbumDebouncerDeps): AlbumDebouncer {
         return;
       }
 
-      const key = `${raw.sourceChatId}:${raw.groupedId}`;
+      const key = `${raw.subscriptionId}:${raw.groupedId}`;
       const existing = pending.get(key);
       if (existing) {
         existing.jobs.push(raw);
@@ -155,14 +119,7 @@ function toContext(job: RawForwardJob): MessageContext {
   };
 }
 
-/**
- * Map each entry in `sourceMessageIds` (sorted ascending) to the matching
- * job's `rawMessage`. Duplicate ids — possible if the listener and history
- * poller both observe the same album member before the debouncer flushes —
- * collapse to the first occurrence so the array length matches
- * `sourceMessageIds` exactly. Jobs whose `rawMessage` is missing fall back
- * to `null`, keeping array positions stable.
- */
+// Aligned 1:1 with sourceMessageIds; dup ids collapse to first, missing → null.
 function collectAlbumRawMessages(
   jobs: readonly RawForwardJob[],
   sourceMessageIds: readonly string[],
@@ -176,11 +133,7 @@ function collectAlbumRawMessages(
   return sourceMessageIds.map((id) => bySourceId.get(id) ?? null);
 }
 
-/**
- * Telegram puts the caption on a single album member (typically the first by
- * message id). Pick the longest-text member; ties go to the lowest message id
- * for determinism. Falls back to the first job if all members have empty text.
- */
+// Telegram puts the caption on one member: pick longest text, ties to lowest message id.
 function pickCaptionBearingMember(jobs: readonly RawForwardJob[]): RawForwardJob {
   let best = jobs[0]!;
   for (const candidate of jobs.slice(1)) {
diff --git a/apps/server/src/forwarding/floodwait.ts b/apps/server/src/forwarding/floodwait.ts
index 59962b5..de35225 100644
--- a/apps/server/src/forwarding/floodwait.ts
+++ b/apps/server/src/forwarding/floodwait.ts
@@ -1,28 +1,5 @@
-/**
- * Rate-limit detection for forward attempts.
- *
- * gramjs raises three closely-related errors that all carry a numeric
- * `seconds` field and all mean "wait this long before retrying":
- *
- *   - `FloodWaitError`     ← `FLOOD_WAIT_X` (and `FLOOD_PREMIUM_WAIT_X`,
- *                            mapped onto the same class by gramjs)
- *   - `SlowModeWaitError`  ← `SLOWMODE_WAIT_X` — destination chat has slow
- *                            mode enabled and we sent too soon
- *
- * The two are sibling subclasses of `FloodError`. Treating them as one
- * "rate-limit" outcome is correct because the retry logic is identical
- * (sleep `seconds` and retry the same job). We expose `kind` so the log /
- * event stream can distinguish them for diagnostics.
- *
- * gramjs also auto-sleeps any of these errors whose `seconds` is below
- * `floodSleepThreshold` (default 60 sec) inside the request itself — those
- * never reach this guard. This guard only fires for waits longer than the
- * threshold, which is the case worth treating specially.
- *
- * The structural fallback (match by class name) is needed because gramjs
- * errors can cross realm boundaries (workers, dynamic imports) where
- * `instanceof` fails.
- */
+// Only fires for waits above gramjs's floodSleepThreshold (default 60s); shorter ones auto-sleep inside the request.
+// Name-based fallback because gramjs errors cross realm boundaries where instanceof fails.
 import { FloodWaitError, SlowModeWaitError } from 'telegram/errors/index.js';
 
 export { FloodWaitError, SlowModeWaitError };
diff --git a/apps/server/src/forwarding/forwarder.test.ts b/apps/server/src/forwarding/forwarder.test.ts
index 66f36b9..d3d0149 100644
--- a/apps/server/src/forwarding/forwarder.test.ts
+++ b/apps/server/src/forwarding/forwarder.test.ts
@@ -5,7 +5,7 @@ import { createTestDb, type TestDbHandle } from '../db/testing.js';
 import { destinations, forwardLog, subscriptions, type Subscription } from '../db/schema.js';
 import type { EventBus } from '../events/bus.js';
 import { createLogger } from '../lib/logger.js';
-import { createForwarder, type ForwarderClient } from './forwarder.js';
+import { createForwarder, recordForwardFailure, type ForwarderClient } from './forwarder.js';
 import type { ForwardJob } from './types.js';
 
 const logger = createLogger({ silent: true });
@@ -292,6 +292,30 @@ describe('createForwarder', () => {
     });
   });
 
+  it('recordForwardFailure writes a failed row and emits forward.failed (dead-letter)', () => {
+    const sub = seedSubscription(handle);
+    const bus = makeStubBus();
+    recordForwardFailure(
+      { db: handle.db, logger, bus },
+      makeJob(sub, ['7']),
+      'flood_wait_abandoned',
+    );
+
+    const rows = handle.db
+      .select()
+      .from(forwardLog)
+      .where(eq(forwardLog.subscriptionId, sub.id))
+      .all();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      sourceMessageId: '7',
+      status: 'failed',
+      error: 'flood_wait_abandoned',
+      destMessageId: null,
+    });
+    expect(bus.emitted.filter((e) => e.type === 'forward.failed')).toHaveLength(1);
+  });
+
   it('classifies CHAT_FORWARDS_RESTRICTED as a permanent failure with a tagged error message', async () => {
     const sub = seedSubscription(handle);
     const forwardMessages = vi
diff --git a/apps/server/src/forwarding/forwarder.ts b/apps/server/src/forwarding/forwarder.ts
index d9d4dcc..70b3285 100644
--- a/apps/server/src/forwarding/forwarder.ts
+++ b/apps/server/src/forwarding/forwarder.ts
@@ -1,19 +1,3 @@
-/**
- * Single-shot forward + log writer.
- *
- * One call = one `forwardMessages` attempt + N `forward_log` rows (one per
- * source message id in `job.sourceMessageIds`). The worker in `queue.ts`
- * drives looping/retry; this module only knows how to perform one attempt and
- * record what happened.
- *
- * Returning a discriminated `ForwardOutcome` (instead of throwing) keeps the
- * worker loop free of error classification — the worker just switches on
- * `outcome.status`. Rate-limit errors (FLOOD_WAIT and SLOWMODE_WAIT) collapse
- * into one `flood_wait` outcome with a `kind` discriminator: retry semantics
- * are identical, but the diagnostic (log row + emitted event) preserves the
- * distinction. Permanent errors get a `failureKind` tag so the activity feed
- * can surface "this subscription will keep failing" vs "transient hiccup".
- */
 import { eq } from 'drizzle-orm';
 import type { Db } from '../db/client.js';
 import { forwardLog, subscriptions, type ForwardLogStatus } from '../db/schema.js';
@@ -22,15 +6,6 @@ import type { Logger } from '../lib/logger.js';
 import { extractRateLimit, type RateLimitKind } from './floodwait.js';
 import type { ForwardFailureKind, ForwardJob, ForwardOutcome } from './types.js';
 
-/**
- * Minimal structural slice of `TelegramClient.forwardMessages` we depend on.
- * Lets tests pass a `vi.fn()` instead of constructing a real client.
- *
- * `id` is intentionally optional and entries can be null/undefined: gramjs's
- * helper occasionally surfaces non-`Message` Updates entries (e.g. MessageEmpty,
- * service messages) that don't carry a numeric id. The forwarder filters those
- * out before stringifying — see comment at the call site.
- */
 export interface ForwarderClient {
   forwardMessages(
     entity: string,
@@ -47,9 +22,7 @@ export interface CreateForwarderDeps {
 
 export type Forwarder = (job: ForwardJob) => Promise<ForwardOutcome>;
 
-// Map known-permanent Telegram RPC error codes to our taxonomy. The strings
-// are matched against err.message / err.errorMessage (gramjs surfaces the
-// upstream code in there). Anything not on this list stays `transient`.
+// Matched against err.message/err.errorMessage; anything not listed stays `transient`.
 const PERMANENT_FAILURES: Array<{ code: string; kind: ForwardFailureKind }> = [
   { code: 'CHAT_FORWARDS_RESTRICTED', kind: 'permanent_chat_forwards_restricted' },
   { code: 'MESSAGE_ID_INVALID', kind: 'permanent_message_id_invalid' },
@@ -57,8 +30,7 @@ const PERMANENT_FAILURES: Array<{ code: string; kind: ForwardFailureKind }> = [
   { code: 'CHANNEL_PRIVATE', kind: 'permanent_channel_private' },
   { code: 'USER_BANNED_IN_CHANNEL', kind: 'permanent_user_banned_in_channel' },
   { code: 'CHAT_WRITE_FORBIDDEN', kind: 'permanent_chat_write_forbidden' },
-  // Forum topic gone or closed — the destination's `topicId` is stale; retrying
-  // won't help until the user re-points the destination at a live topic.
+  // Stale destination topicId; won't recover until re-pointed at a live topic.
   { code: 'TOPIC_CLOSED', kind: 'permanent_topic_unavailable' },
   { code: 'TOPIC_DELETED', kind: 'permanent_topic_unavailable' },
   { code: 'TOPIC_ID_INVALID', kind: 'permanent_topic_unavailable' },
@@ -95,19 +67,12 @@ export function createForwarder(deps: CreateForwarderDeps): Forwarder {
         fromPeer: job.sourceChatId,
         ...(job.destinationTopicId != null ? { topMsgId: Number(job.destinationTopicId) } : {}),
       });
-      // gramjs's high-level helper sometimes surfaces non-`Message` entries
-      // in the result (MessageEmpty, service updates, occasional null slots
-      // when the server's Updates payload is sparse) — coerce defensively
-      // and drop anything without a numeric id. Without the filter, calling
-      // `.toString()` on `undefined.id` blows up the whole forward outcome
-      // and we log a successful redirect as `failed`.
+      // Drop non-`Message` result entries (MessageEmpty/service/null) with no numeric id, else `.toString()` throws and a success logs as `failed`.
       const destMessageIds = sent
         .filter((m): m is { id: number } => m != null && typeof m.id === 'number')
         .map((m) => m.id.toString());
       if (destMessageIds.length !== job.sourceMessageIds.length) {
-        // Telegram normally returns one id per forwarded message; a mismatch
-        // means the upstream silently dropped some. The tail will be logged
-        // as `sent` with destMessageId=NULL — flag it so it's investigable.
+        // Mismatch = upstream silently dropped some; the tail logs `sent` with destMessageId=NULL.
         logger.warn(
           {
             subscriptionId: job.subscriptionId,
@@ -128,10 +93,7 @@ export function createForwarder(deps: CreateForwarderDeps): Forwarder {
         null,
         rawMessage,
       );
-      // A successful forward proves the channel isn't (currently) restricting
-      // forwards. Clear any sticky badge from a previous CHAT_FORWARDS_RESTRICTED.
-      // The UPDATE is unconditional but cheap — single PK lookup, NULL→NULL
-      // when nothing was set.
+      // Success proves forwards aren't restricted; clear any sticky CHAT_FORWARDS_RESTRICTED badge.
       db.update(subscriptions)
         .set({ forwardingRestrictedAt: null })
         .where(eq(subscriptions.id, job.subscriptionId))
@@ -163,15 +125,11 @@ export function createForwarder(deps: CreateForwarderDeps): Forwarder {
       }
       const failureKind = classifyForwardError(err);
       const errorMessage = err instanceof Error ? err.message : String(err);
-      // Tag permanent failures so the activity feed / log can render them
-      // distinctly. Transient stays a bare message for backwards compatibility
-      // with existing log readers.
+      // Tag permanent failures; transient stays a bare message for existing log readers.
       const errorText =
         failureKind === 'transient' ? errorMessage : `${failureKind}: ${errorMessage}`;
       if (failureKind === 'permanent_chat_forwards_restricted') {
-        // Stamp the sticky badge so the UI can show "noforwards" until
-        // either the channel re-allows forwards (cleared on the next
-        // success) or the user disables / removes the subscription.
+        // Sticky "noforwards" badge, cleared on the next successful forward.
         db.update(subscriptions)
           .set({ forwardingRestrictedAt: new Date() })
           .where(eq(subscriptions.id, job.subscriptionId))
@@ -214,6 +172,42 @@ export function createForwarder(deps: CreateForwarderDeps): Forwarder {
   };
 }
 
+// Record a terminal failure for a job (e.g. a dead-lettered flood_wait): a `failed`
+// forward_log row + a `forward.failed` event, reusing the normal failure surfacing.
+export function recordForwardFailure(
+  deps: Pick<CreateForwarderDeps, 'db' | 'logger' | 'bus'>,
+  job: ForwardJob,
+  errorText: string,
+): void {
+  const { db, logger, bus } = deps;
+  const forwardLogIds = writeLogs(
+    db,
+    job,
+    job.sourceMessageIds.map((sourceId) => ({ sourceMessageId: sourceId, destMessageId: null })),
+    'failed',
+    errorText,
+    job.rawMessage ?? null,
+  );
+  logger.warn(
+    {
+      subscriptionId: job.subscriptionId,
+      destinationChatId: job.destinationChatId,
+      sourceMessageIds: job.sourceMessageIds,
+      error: errorText,
+    },
+    'forward dead-lettered',
+  );
+  bus.emit({
+    type: 'forward.failed',
+    subscriptionId: job.subscriptionId,
+    sourceChatId: job.sourceChatId,
+    destinationChatId: job.destinationChatId,
+    sourceMessageIds: [...job.sourceMessageIds],
+    error: errorText,
+    forwardLogIds,
+  });
+}
+
 function handleRateLimit(
   deps: CreateForwarderDeps,
   job: ForwardJob,
@@ -255,17 +249,10 @@ function handleRateLimit(
   return { status: 'flood_wait', seconds, kind };
 }
 
-// Hard cap on the size of the `raw_message` JSON snapshot persisted per row.
-// `toJsonSafe` already truncates at 64KB (string length, now byte length),
-// but a malicious / pathological gramjs payload could still slip a large
-// nested object through; clamp at the storage boundary as a second wall.
+// Second wall behind `toJsonSafe`'s 64KB truncation in case a large nested payload slips through.
 const RAW_MESSAGE_MAX_BYTES = 128 * 1024;
 
-/**
- * If a snapshot would store more than `RAW_MESSAGE_MAX_BYTES` of JSON, swap
- * it for a small truncation marker so the row still inserts cleanly and the
- * UI surfaces the reason instead of streaming a huge JSON blob.
- */
+// Over-limit snapshots become a truncation marker so the row still inserts.
 function clampRawMessage(value: unknown): unknown {
   if (value === null || value === undefined) return value;
   let encoded: string;
@@ -280,13 +267,7 @@ function clampRawMessage(value: unknown): unknown {
   return { __truncated: true, size: byteLen };
 }
 
-/**
- * Insert N `forward_log` rows in one batch and return the assigned ids in
- * the same order so the caller can attach them to the emitted SSE event.
- * The whole forward batch shares one `rawMessage` snapshot — single object
- * for ordinary messages, array for albums — denormalized onto every row so
- * any row is independently inspectable via `GET /forward-log/:id/raw`.
- */
+// The batch's single rawMessage is denormalized onto every row so any row is inspectable via GET /forward-log/:id/raw.
 function writeLogs(
   db: Db,
   job: ForwardJob,
diff --git a/apps/server/src/forwarding/forwarderClient.ts b/apps/server/src/forwarding/forwarderClient.ts
index 5c4bad9..894366f 100644
--- a/apps/server/src/forwarding/forwarderClient.ts
+++ b/apps/server/src/forwarding/forwarderClient.ts
@@ -1,26 +1,9 @@
-/**
- * Adapts the live gramjs `TelegramClient` to the forwarder's `ForwarderClient`
- * interface, adding forum-topic support the high-level helper lacks.
- *
- * gramjs's `client.forwardMessages` accepts only `{ messages, fromPeer,
- * silent, ... }` — there is no `topMsgId`. To forward into a forum topic we
- * fall back to the raw `messages.ForwardMessages` request, which does carry
- * `topMsgId`. gramjs auto-generates the required `randomId` vector in the
- * request constructor (one per `id`), and `_getResponseMessage` is the same
- * extractor the helper uses to turn the `Updates` result into messages — so
- * the topic path produces the same `{ id }[]` shape the no-topic path does.
- *
- * The no-topic path delegates verbatim to the helper, leaving normal chats
- * (and a forum's General topic, which omits `topMsgId`) on the proven code
- * path.
- */
+// Adapts gramjs TelegramClient to ForwarderClient, adding forum-topic forwarding: client.forwardMessages has no topMsgId, so the topic path drops to the raw messages.ForwardMessages request (which carries it). No-topic forwards delegate to the helper.
 import { Api } from 'telegram';
 import type { TelegramClient } from 'telegram';
 import type { ForwarderClient } from './forwarder.js';
 
-// `_getResponseMessage` is an internal-but-public method on TelegramClient
-// (used by the high-level send/forward helpers). Narrow the surface we touch
-// so the cast stays honest.
+// _getResponseMessage is internal-but-public on TelegramClient; narrow the cast surface.
 interface ResponseMessageClient {
   _getResponseMessage(
     req: unknown,
@@ -48,9 +31,7 @@ export function createForwarderClient(client: TelegramClient): ForwarderClient {
           ...(silent !== undefined ? { silent } : {}),
         });
       }
-      // Raw request path: resolve both peers to input peers (the TL layer
-      // needs concrete `InputPeer`s, exactly as the helper does) and set
-      // `topMsgId` so the forward lands in the chosen forum topic.
+      // Resolve both peers to InputPeers and set topMsgId so the forward lands in the chosen topic.
       const toPeer = await client.getInputEntity(entity);
       const fromPeerResolved = await client.getInputEntity(fromPeer);
       const request = new Api.messages.ForwardMessages({
diff --git a/apps/server/src/forwarding/historyPoller.ts b/apps/server/src/forwarding/historyPoller.ts
index 3c4593f..5e74b2a 100644
--- a/apps/server/src/forwarding/historyPoller.ts
+++ b/apps/server/src/forwarding/historyPoller.ts
@@ -1,29 +1,4 @@
-/**
- * Periodic safety net that catches messages the gramjs listener missed.
- *
- * The listener (`apps/server/src/tg/listener.ts`) consumes the live update
- * stream via gramjs's `NewMessage` handler. In practice that stream silently
- * stops delivering `UpdateNewChannelMessage` for some subscribed channels:
- * gramjs 2.26.x doesn't implement `client.catchUp()` and doesn't refresh
- * per-channel pts, so once a channel's update state drifts the session
- * keeps the connection alive but never dispatches events for it again.
- * Observed in production: a public broadcast channel with 23k+ messages
- * had zero `forward_log` rows ever, while a low-volume personal channel
- * forwarded fine — both verified-member, both in dialogs, both `Message`.
- *
- * This poller calls `messages.getHistory` per subscription on a short cadence
- * with `minId = lastSeen`, then enqueues anything new through the existing
- * forwarding pipeline. The listener still runs; when it works, it gets there
- * first and writes a `forward_log` row before the next poll. The poller's
- * dedup check (`forward_log` row exists?) keeps the duplicate-forward race
- * window down to the brief interval between listener-enqueue and
- * forwarder-log-write — acceptable in practice.
- *
- * State is in-memory (`Map<subscriptionId, lastSeenMessageId>`) and is
- * rebuilt on boot from `MAX(source_message_id)` in `forward_log`. For
- * subscriptions with no forward history we initialise from the current
- * channel top so we don't dump the entire backlog on first run.
- */
+// Safety net for the gramjs bug where the live listener silently stops delivering channel updates: polls getHistory(minId=lastSeen) per sub, dedups against forward_log.
 import { eq, and } from 'drizzle-orm';
 import { Api } from 'telegram';
 import type { TelegramClient } from 'telegram';
@@ -36,7 +11,6 @@ import { extractRateLimit } from './floodwait.js';
 import type { RawForwardingHandle, RawForwardJob } from './types.js';
 
 export const DEFAULT_POLL_INTERVAL_MS = 2 * 60 * 1000;
-/** Cap per-poll batch size. New subs won't dump their entire history. */
 export const POLL_BATCH_LIMIT = 100;
 
 export interface HistoryPollerClient {
@@ -54,7 +28,6 @@ export interface HistoryPollerDeps {
 export interface HistoryPoller {
   start(): void;
   stop(): void;
-  /** Run one sweep across all enabled subscriptions. Exposed for tests. */
   poll(): Promise<void>;
 }
 
@@ -78,10 +51,7 @@ export function createHistoryPoller(deps: HistoryPollerDeps): HistoryPoller {
   const { client, db, logger, forwarding } = deps;
   const intervalMs = deps.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const lastSeen = new Map<number, number>();
-  // Tracks subscriptions whose seed was already established (either from
-  // forward_log or from a successful channel-top probe). Subs not in this set
-  // are seeded lazily on their first sweep — keeps boot fast and avoids
-  // hammering Telegram before the first real poll.
+  // Seeded lazily on first sweep, not at boot, to avoid hammering Telegram up front.
   const seeded = new Set<number>();
   let stopped = false;
   let inFlight: Promise<void> | undefined;
@@ -101,10 +71,7 @@ export function createHistoryPoller(deps: HistoryPollerDeps): HistoryPoller {
   }
 
   function maxLoggedId(subId: number): number | undefined {
-    // `source_message_id` is `text` in SQLite, so a SQL `MAX` would order
-    // lexicographically (`'9' > '10'`). Fetching rows and reducing in JS is
-    // correct numerically and cheap thanks to `idx_forward_log_subscription`
-    // bounding the scan to one subscription's history.
+    // source_message_id is text, so SQL MAX sorts lexicographically ('9' > '10'); reduce numerically in JS.
     const rows = db
       .select({ sourceMessageId: forwardLog.sourceMessageId })
       .from(forwardLog)
@@ -128,7 +95,7 @@ export function createHistoryPoller(deps: HistoryPollerDeps): HistoryPoller {
       logger.debug({ subId: sub.id, lastSeen: fromLog }, 'history poller: seeded from forward_log');
       return;
     }
-    // No history — read current top so we don't backfill the archive.
+    // No history — seed from current top so we don't backfill the archive.
     try {
       const result = (await client.invoke(
         new Api.messages.GetHistory({
@@ -137,9 +104,7 @@ export function createHistoryPoller(deps: HistoryPollerDeps): HistoryPoller {
         }),
       )) as { messages?: RawMessage[] };
       const topId = result.messages?.[0]?.id;
-      // Empty channel (no messages yet): seed at 0 and mark seeded so we don't
-      // re-probe the top every tick. The first real message is picked up by the
-      // next poll's `minId = 0` sweep.
+      // Empty channel: seed at 0 and mark seeded so we don't re-probe the top every tick.
       const seedId = typeof topId === 'number' ? topId : 0;
       lastSeen.set(sub.id, seedId);
       seeded.add(sub.id);
@@ -206,8 +171,7 @@ export function createHistoryPoller(deps: HistoryPollerDeps): HistoryPoller {
         m != null && typeof m.id === 'number' && m.className === 'Message',
     );
     if (messages.length === 0) return;
-    // Telegram returns descending by id; forward chronologically so the
-    // destination order matches the source.
+    // Telegram returns descending; forward ascending so destination order matches source.
     messages.sort((a, b) => a.id - b.id);
 
     let enqueued = 0;
@@ -215,7 +179,7 @@ export function createHistoryPoller(deps: HistoryPollerDeps): HistoryPoller {
     let highest = since;
     for (const msg of messages) {
       if (msg.id <= since) {
-        // `minId` is exclusive on the server side, but be defensive.
+        // minId is server-side exclusive, but be defensive.
         continue;
       }
       const sourceMessageId = String(msg.id);
diff --git a/apps/server/src/forwarding/index.ts b/apps/server/src/forwarding/index.ts
index 1fad66c..f8112e5 100644
--- a/apps/server/src/forwarding/index.ts
+++ b/apps/server/src/forwarding/index.ts
@@ -1,14 +1,8 @@
-/**
- * Public surface of the forwarding pipeline.
- *
- * `createForwardingPipeline` wires the default forwarder + throttle reader
- * against the live gramjs client and DB. Tests build the pipeline directly
- * via `new ForwardingPipeline(...)` with stubs.
- */
+// `createForwardingPipeline` wires the live forwarder; tests build `ForwardingPipeline` with stubs.
 import type { Db } from '../db/client.js';
 import type { EventBus } from '../events/bus.js';
 import type { Logger } from '../lib/logger.js';
-import { createForwarder, type ForwarderClient } from './forwarder.js';
+import { createForwarder, recordForwardFailure, type ForwarderClient } from './forwarder.js';
 import { ForwardingPipeline } from './queue.js';
 import { getGlobalDelayMs } from './throttle.js';
 
@@ -47,5 +41,11 @@ export function createForwardingPipeline(deps: CreatePipelineDeps): ForwardingPi
     forwarder,
     getDelayMs: () => getGlobalDelayMs(deps.db),
     logger: deps.logger,
+    onDeadLetter: (job) =>
+      recordForwardFailure(
+        { db: deps.db, logger: deps.logger, bus: deps.bus },
+        job,
+        'flood_wait_abandoned',
+      ),
   });
 }
diff --git a/apps/server/src/forwarding/queue.test.ts b/apps/server/src/forwarding/queue.test.ts
index 90af084..3b33ba3 100644
--- a/apps/server/src/forwarding/queue.test.ts
+++ b/apps/server/src/forwarding/queue.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createLogger } from '../lib/logger.js';
 import type { Forwarder } from './forwarder.js';
-import { ForwardingPipeline, type SleepFn } from './queue.js';
+import { ForwardingPipeline, MAX_FLOOD_WAIT_ATTEMPTS, type SleepFn } from './queue.js';
 import type { ForwardJob, ForwardOutcome } from './types.js';
 
 const logger = createLogger({ silent: true });
@@ -156,6 +156,42 @@ describe('ForwardingPipeline', () => {
     await pipeline.stop();
   });
 
+  it('dead-letters a job after MAX_FLOOD_WAIT_ATTEMPTS flood_waits and unblocks the FIFO', async () => {
+    const deadLettered: ForwardJob[] = [];
+    const forwarder: Forwarder = vi.fn(async (j): Promise<ForwardOutcome> => {
+      if (j.sourceMessageIds[0] === 'msg-1') {
+        return { status: 'flood_wait', seconds: 30, kind: 'flood_wait' };
+      }
+      return sent();
+    });
+
+    const pipeline = new ForwardingPipeline({
+      forwarder,
+      getDelayMs: () => 1000,
+      logger,
+      sleep: fakeSleep,
+      onDeadLetter: (j) => deadLettered.push(j),
+    });
+
+    pipeline.enqueue(job('-100A', 'msg-1')); // perpetually flooded
+    pipeline.enqueue(job('-100A', 'msg-2')); // stuck behind it
+
+    // First attempt fires immediately; each retry follows a 30s flood backoff.
+    await vi.advanceTimersByTimeAsync(0);
+    for (let i = 0; i <= MAX_FLOOD_WAIT_ATTEMPTS; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+    }
+
+    // msg-1 abandoned exactly once; msg-2 (behind it) then forwards.
+    expect(deadLettered).toHaveLength(1);
+    expect(deadLettered[0]).toMatchObject({ sourceMessageIds: ['msg-1'] });
+    expect(forwarder).toHaveBeenCalledWith(
+      expect.objectContaining({ sourceMessageIds: ['msg-2'] }),
+    );
+
+    await pipeline.stop();
+  });
+
   it('stop() aborts a pending throttle sleep and resolves promptly', async () => {
     const forwarder: Forwarder = vi.fn(async () => sent());
     const pipeline = new ForwardingPipeline({
diff --git a/apps/server/src/forwarding/queue.ts b/apps/server/src/forwarding/queue.ts
index b697a34..55d81ec 100644
--- a/apps/server/src/forwarding/queue.ts
+++ b/apps/server/src/forwarding/queue.ts
@@ -1,26 +1,12 @@
-/**
- * Per-destination FIFO queues with one worker each.
- *
- * Telegram throttles per receiving chat, so the throttling domain == the
- * destination chat. Workers are created lazily on first enqueue for a given
- * destination and run for the lifetime of the pipeline.
- *
- * Worker loop:
- *   1. Wait for a job (sleep on a wakeup promise).
- *   2. Sleep until at least `delayMs` has elapsed since the last successful
- *      attempt for this destination.
- *   3. Hand the job to the forwarder.
- *   4. On `flood_wait`: sleep `seconds * 1000` and retry the SAME job.
- *      On `sent`/`failed`: pop the job and move on.
- *
- * `stop()` aborts in-flight sleeps and waits for the current send to finish.
- */
+// Per-destination FIFO + worker: Telegram throttles per receiving chat, so that's the throttling domain.
 import { setTimeout as nodeSleep } from 'node:timers/promises';
 import type { Logger } from '../lib/logger.js';
 import type { Forwarder } from './forwarder.js';
 import type { ForwardJob, ForwardingHandle } from './types.js';
 
 export const MAX_FLOOD_WAIT_SECONDS = 300;
+// Consecutive flood_waits on one head job before it's dead-lettered (and the FIFO unblocked).
+export const MAX_FLOOD_WAIT_ATTEMPTS = 5;
 
 export type SleepFn = (ms: number, signal: AbortSignal) => Promise<void>;
 
@@ -32,6 +18,8 @@ export interface PipelineDeps {
   getDelayMs: () => number;
   logger: Logger;
   sleep?: SleepFn;
+  // Called when a job is abandoned after MAX_FLOOD_WAIT_ATTEMPTS; records the terminal failure.
+  onDeadLetter?: (job: ForwardJob) => void;
 }
 
 interface WorkerDeps {
@@ -39,6 +27,7 @@ interface WorkerDeps {
   getDelayMs: () => number;
   logger: Logger;
   sleep: SleepFn;
+  onDeadLetter?: (job: ForwardJob) => void;
 }
 
 class DestinationWorker {
@@ -46,6 +35,7 @@ class DestinationWorker {
   private wakeup: () => void = () => {};
   private wakeupPromise: Promise<void>;
   private lastSendAt = 0;
+  private floodWaitCount = 0;
   private loopPromise?: Promise<void>;
 
   constructor(
@@ -99,6 +89,22 @@ class DestinationWorker {
       const outcome = await this.deps.forwarder(job);
 
       if (outcome.status === 'flood_wait') {
+        this.floodWaitCount++;
+        if (this.floodWaitCount > MAX_FLOOD_WAIT_ATTEMPTS) {
+          // Perpetually flooded — abandon the head job so it can't wedge the FIFO forever.
+          this.deps.logger.error(
+            {
+              destinationChatId: this.destinationChatId,
+              sourceMessageIds: job.sourceMessageIds,
+              attempts: this.floodWaitCount,
+            },
+            'flood_wait exceeded max attempts — dead-lettering job',
+          );
+          this.deps.onDeadLetter?.(job);
+          this.queue.shift();
+          this.floodWaitCount = 0;
+          continue;
+        }
         const cappedSeconds = Math.min(outcome.seconds, MAX_FLOOD_WAIT_SECONDS);
         if (outcome.seconds > MAX_FLOOD_WAIT_SECONDS) {
           this.deps.logger.warn(
@@ -116,6 +122,7 @@ class DestinationWorker {
       }
 
       this.queue.shift();
+      this.floodWaitCount = 0;
       this.lastSendAt = Date.now();
     }
     this.deps.logger.debug({ destinationChatId: this.destinationChatId }, 'worker stopped');
@@ -134,6 +141,7 @@ export class ForwardingPipeline implements ForwardingHandle {
       getDelayMs: deps.getDelayMs,
       logger: deps.logger,
       sleep: deps.sleep ?? cancellableSleep,
+      ...(deps.onDeadLetter ? { onDeadLetter: deps.onDeadLetter } : {}),
     };
   }
 
diff --git a/apps/server/src/forwarding/retention.ts b/apps/server/src/forwarding/retention.ts
index 1f8bc46..b733d05 100644
--- a/apps/server/src/forwarding/retention.ts
+++ b/apps/server/src/forwarding/retention.ts
@@ -1,17 +1,4 @@
-/**
- * Forward-log retention.
- *
- * Without periodic pruning, every forwarded message accumulates a row plus a
- * (potentially large) `raw_message` JSON blob in `forward_log`. A subscribed
- * channel can pump thousands of messages a day; over months the file balloons
- * to GBs and read latency degrades.
- *
- * Policy: keep the most recent `maxRows` rows by `(createdAt DESC, id DESC)`,
- * delete everything else. SQLite handles the DELETE…WHERE id NOT IN (SELECT…)
- * pattern fine at this scale; we also add a hard cap on `raw_message` byte
- * length at insert time so a single pathological payload can't dwarf the rest
- * of the column.
- */
+// Keep the most recent maxRows rows by (createdAt DESC, id DESC), delete the rest.
 import { sql } from 'drizzle-orm';
 import type { Db } from '../db/client.js';
 import { forwardLog } from '../db/schema.js';
@@ -22,14 +9,10 @@ export const DEFAULT_FORWARD_LOG_MAX_ROWS = 10_000;
 export interface PruneForwardLogDeps {
   db: Db;
   logger: Logger;
-  /** Hard cap on retained rows. Override via env on the boot path. */
+  // Retained-row cap; defaults to DEFAULT_FORWARD_LOG_MAX_ROWS. Test-only override (prod uses the default).
   maxRows?: number;
 }
 
-/**
- * Returns the number of rows deleted. Idempotent — a fresh DB with fewer
- * than `maxRows` rows is a no-op.
- */
 export function pruneForwardLog(deps: PruneForwardLogDeps): number {
   const { db, logger } = deps;
   const maxRows = deps.maxRows ?? DEFAULT_FORWARD_LOG_MAX_ROWS;
diff --git a/apps/server/src/forwarding/stats.ts b/apps/server/src/forwarding/stats.ts
index 10a2523..c3c89c8 100644
--- a/apps/server/src/forwarding/stats.ts
+++ b/apps/server/src/forwarding/stats.ts
@@ -1,11 +1,4 @@
-/**
- * Aggregate counters over `forward_log`, used by the stats digest.
- *
- * The four buckets map 1:1 to the `status` enum: 'sent' = forwarded,
- * 'filtered' = dropped by a filter, 'failed' = permanent error,
- * 'flood_wait' = transient throttle (shown separately so it isn't
- * double-counted against the later 'sent' row a retry produces).
- */
+// forward_log counters for the stats digest. flood_wait is a transient throttle, counted separately so it isn't double-counted against the 'sent' row a retry later produces.
 import { sql } from 'drizzle-orm';
 import type { Db } from '../db/client.js';
 import { forwardLog } from '../db/schema.js';
@@ -17,11 +10,7 @@ export interface DigestStats {
   floodWait: number;
 }
 
-/**
- * Counts rows by status in the half-open window `[sinceMs, untilMs)`.
- * `created_at` is stored as integer epoch-ms, so we compare against raw
- * numbers rather than `Date` objects.
- */
+// Counts by status over the half-open window [sinceMs, untilMs); created_at is epoch-ms.
 export function getDigestStats(db: Db, sinceMs: number, untilMs: number): DigestStats {
   const rows = db
     .select({ status: forwardLog.status, n: sql<number>`count(*)` })
diff --git a/apps/server/src/forwarding/statsDigestConfig.ts b/apps/server/src/forwarding/statsDigestConfig.ts
index d23ff5b..735b0d7 100644
--- a/apps/server/src/forwarding/statsDigestConfig.ts
+++ b/apps/server/src/forwarding/statsDigestConfig.ts
@@ -1,14 +1,5 @@
-/**
- * Stats-digest config reader.
- *
- * The digest knobs live alongside the throttle knobs in the single
- * `app_settings` row keyed `'global'` (see throttle.ts). The shared
- * `statsDigestSettingsSchema` validates each field with a `.catch(default)`,
- * so a missing row, missing field, or malformed value all read back as the
- * documented default — a hand-edited or partially-written row can never crash
- * the scheduler. The Settings UI mutates the same row and the scheduler reads
- * it on every tick, so changes apply live without a restart.
- */
+// Reads the digest knobs from the 'global' app_settings row on every tick, so changes apply live.
+// `.catch(default)` per field means a hand-edited/partial row can never crash the scheduler.
 import { statsDigestSettingsSchema, type StatsDigestFrequency } from '@tg-feed/shared';
 import type { Db } from '../db/client.js';
 import { readGlobalValue } from './throttle.js';
diff --git a/apps/server/src/forwarding/throttle.ts b/apps/server/src/forwarding/throttle.ts
index 45d494e..547e491 100644
--- a/apps/server/src/forwarding/throttle.ts
+++ b/apps/server/src/forwarding/throttle.ts
@@ -1,17 +1,5 @@
-/**
- * Global app_settings readers.
- *
- * Both pipeline knobs (forward throttle delay + album debounce window) live
- * in the single `app_settings` row keyed `'global'` whose `value` JSON is a
- * `{ delayMs?, albumDebounceMs? }` shape. The Settings UI mutates the same
- * row and the pipeline reads it on every send / album flush, so changes
- * apply live without restart.
- *
- * Defensive defaults: a missing row, missing field, or non-positive number
- * all fall back to the documented defaults. We never want a malformed DB
- * row to disable throttling (would trip Telegram's anti-spam) or set a
- * negative debounce (would break the album setTimeout).
- */
+// Pipeline knobs in the single 'global' app_settings row; read on every send/flush so changes apply live.
+// Missing/non-positive values fall back to defaults so a bad row can't disable throttling (Telegram anti-spam) or break the album setTimeout.
 import { eq } from 'drizzle-orm';
 import type { Db } from '../db/client.js';
 import { appSettings } from '../db/schema.js';
diff --git a/apps/server/src/forwarding/types.ts b/apps/server/src/forwarding/types.ts
index 01d9035..a8be05c 100644
--- a/apps/server/src/forwarding/types.ts
+++ b/apps/server/src/forwarding/types.ts
@@ -1,45 +1,18 @@
-/**
- * Shared types for the forwarding pipeline.
- *
- * Two job shapes flow through the system:
- *
- *   - `RawForwardJob` is what the listener produces — one per `NewMessage` event,
- *     carrying an optional `groupedId` for album members.
- *   - `ForwardJob` is what the pipeline consumes after the album debouncer has
- *     collapsed N raw jobs sharing a `groupedId` into one. Single messages
- *     become 1-element arrays.
- *
- * `ForwardOutcome`'s discriminator drives the worker's retry/advance decision
- * in `queue.ts`.
- */
+// RawForwardJob = one per NewMessage; the album debouncer collapses raw jobs sharing a groupedId into one ForwardJob (singles become 1-element arrays).
 
 export interface RawForwardJob {
   subscriptionId: number;
   sourceChatId: string;
   destinationChatId: string;
-  /**
-   * Forum `top_msg_id` to forward into, or null/undefined for the General
-   * topic / a non-forum chat. Travels alongside `destinationChatId` from the
-   * destinations row to the forwarder, which converts it to `topMsgId`.
-   */
+  // Forum top_msg_id; null/undefined = General / non-forum.
   destinationTopicId?: string | null;
   sourceMessageId: string;
   groupedId?: string;
-  /**
-   * Filter-relevant content carried with the job so the album debouncer can
-   * evaluate filters once per album (using the caption-bearing member) rather
-   * than per source message — albums put the caption only on the first
-   * message, so per-message text filtering would silently fragment them.
-   */
+  // Albums put the caption only on the first member, so filters run once per album, not per message (else they fragment).
   text: string;
   hasMedia: boolean;
   senderUsername?: string;
-  /**
-   * JSON-safe snapshot of the source gramjs `Message` (already passed
-   * through `toJsonSafe` at the capture boundary). Stored verbatim on the
-   * `forward_log` row for later inspection. `null` when capture was skipped
-   * or the encoded payload exceeded the size cap (caller stores `null`).
-   */
+  // JSON-safe snapshot (via toJsonSafe); null when capture was skipped or over the size cap.
   rawMessage?: unknown;
 }
 
@@ -47,16 +20,10 @@ export interface ForwardJob {
   subscriptionId: number;
   sourceChatId: string;
   destinationChatId: string;
-  /** Forum `top_msg_id` to forward into; null/undefined for General / non-forum. */
+  // Forum top_msg_id; null/undefined = General / non-forum.
   destinationTopicId?: string | null;
   sourceMessageIds: string[];
-  /**
-   * Raw message payloads, aligned with `sourceMessageIds`. For an album
-   * (≥2 ids) this is an array of JSON-safe objects sorted to match
-   * `sourceMessageIds`; for a single message it's a plain object. The
-   * forwarder writes the whole value onto every inserted `forward_log`
-   * row of the batch so each row is independently inspectable.
-   */
+  // Album (≥2) = array of JSON-safe objects aligned with sourceMessageIds; single = plain object. Written to every batch row.
   rawMessage?: unknown;
 }
 
diff --git a/apps/server/src/index.ts b/apps/server/src/index.ts
index 5aa0a46..bf98a52 100644
--- a/apps/server/src/index.ts
+++ b/apps/server/src/index.ts
@@ -1,26 +1,4 @@
-/**
- * @tg-feed/server — entrypoint.
- *
- * Boots the API listener first, then brings the gramjs Telegram client up
- * in the background. The forwarding pipeline (NewMessage listener →
- * debouncer → pipeline) and the chat-resolver / invite / join / profile
- * fetcher helpers are attached to a mutable runtime box once the gramjs
- * `client.connect()` finishes. The Fastify factory reads tg-deps via
- * lazy getters, so route handlers pick up the post-init values without
- * re-registration. This eliminates a `pnpm -r --parallel dev` race where
- * Vite's proxy hit ECONNREFUSED before the server reached `app.listen()`.
- *
- * Telegram bring-up is best-effort: if env vars are missing or the connect
- * step fails, the API still serves in a degraded mode (no listener, no
- * forwarder, no entity resolver). `GET /api/system/status` exposes the
- * lifecycle phase ('connecting' / 'connected' / 'disconnected') so the web
- * UI can distinguish "starting up" from "configure your Telegram session".
- *
- * Shutdown order is HTTP-first → wait for in-flight Telegram init → tear
- * down debouncer / pipeline / Telegram / DB. We wait for the init promise
- * to settle because gramjs `client.connect()` doesn't accept an AbortSignal
- * cleanly; cancelling mid-flight risks orphaned sockets.
- */
+// Listen before connecting Telegram: avoids a dev-proxy ECONNREFUSED race; bring-up is best-effort.
 import './lib/loadEnv.js';
 import process from 'node:process';
 import type { TelegramClient } from 'telegram';
@@ -87,25 +65,8 @@ interface TryStartTelegramDeps {
   db: Db;
   bus: EventBus;
   filterEvaluator: FilterEvaluator;
-  /**
-   * Returns true if a SIGINT/SIGTERM landed while we were inside
-   * `client.connect()`. The function bails after connect with the client
-   * disconnected so we don't attach a NewMessage listener that nothing will
-   * tear down.
-   */
   isShuttingDown: () => boolean;
-  /**
-   * Sink for status updates emitted by the health monitor. The boot path
-   * funnels these into `statusRef.current` so `/api/system/status` reflects
-   * runtime liveness changes (connected → disconnected, etc).
-   */
   setStatus: (next: TelegramStatus) => void;
-  /**
-   * Forced session-reload callback. Passed into the health monitor so it
-   * can recover from gramjs getting stuck in a reconnect loop. The function
-   * is `reloadTelegramSession` from `main()`, which coalesces concurrent
-   * calls and atomically swaps the runtime box.
-   */
   requestReload: () => Promise<void>;
 }
 
@@ -138,10 +99,6 @@ async function tryStartTelegram(deps: TryStartTelegramDeps): Promise<TelegramRun
       ),
     ]);
     if (isShuttingDown()) {
-      // SIGINT/SIGTERM landed mid-connect. Bail before we attach the
-      // listener — main()'s shutdown handler awaits this promise so
-      // it'll just see a disconnected status and skip teardown of the
-      // listener / pipeline.
       try {
         await disconnectClient(client);
       } catch (secondaryErr) {
@@ -156,14 +113,7 @@ async function tryStartTelegram(deps: TryStartTelegramDeps): Promise<TelegramRun
       };
     }
     logger.info({ source: tgEnvResult.source }, 'connected to Telegram');
-    // gramjs 2.26.x ships `client.catchUp()` as a TODO stub (see
-    // node_modules/telegram/client/updates.js — empty body) and does not
-    // call `updates.getDifference` automatically on reconnect. As a result
-    // any NewMessage events delivered while the process was offline are
-    // permanently lost. Surface this as a warning so operators don't
-    // assume restarts are transparent. A future change can poll
-    // messages.getHistory per subscription on boot to backfill, gated on a
-    // per-subscription `last_seen_message_id` column.
+    // gramjs 2.26.x catchUp() is a stub: offline updates are lost; history poller is the backstop.
     logger.warn(
       'Telegram catch-up is not available in gramjs 2.26.x; messages delivered while offline will be missed',
     );
@@ -181,11 +131,7 @@ async function tryStartTelegram(deps: TryStartTelegramDeps): Promise<TelegramRun
     });
     attachNewMessageListener(client, db, logger, debouncer);
     await resolveSubscriptionsOnStartup(client, db, logger);
-    // Polling backstop: catches messages the live `NewMessage` stream misses.
-    // gramjs 2.26.x has no working `catchUp()` and silently stops delivering
-    // channel updates once a per-channel pts drifts, so a periodic
-    // `messages.getHistory` sweep is the only way to guarantee we see new
-    // posts from every subscribed channel. See historyPoller.ts for details.
+    // Backstop: gramjs silently stops delivering channel updates once a per-channel pts drifts.
     const historyPoller = createHistoryPoller({
       client,
       db,
@@ -237,8 +183,6 @@ async function tryStartTelegram(deps: TryStartTelegramDeps): Promise<TelegramRun
       try {
         await disconnectClient(client);
       } catch (secondaryErr) {
-        // Already failing the primary path; don't let teardown throw,
-        // but record at debug so post-mortem isn't blind.
         logger.debug({ err: secondaryErr }, 'secondary error during Telegram client teardown');
       }
     }
@@ -246,11 +190,7 @@ async function tryStartTelegram(deps: TryStartTelegramDeps): Promise<TelegramRun
   }
 }
 
-/**
- * Stop and dispose a Telegram runtime in the order that avoids dangling
- * references: monitors first (they hold timers), then the debouncer (timers),
- * then the pipeline (in-flight forwards), then the gramjs client itself.
- */
+// Dispose order matters: monitors/debouncer (timers) → pipeline (in-flight forwards) → gramjs client.
 async function teardownRuntime(runtime: Partial<TelegramRuntime>): Promise<void> {
   if (runtime.dialogsKeepalive) {
     try {
@@ -310,10 +250,6 @@ async function main(): Promise<void> {
   const filterRegistry = createDefaultRegistry();
   const filterEvaluator = createFilterEvaluator({ db, registry: filterRegistry, logger, bus });
 
-  // Mutable runtime box. Populated once Telegram bring-up finishes; the
-  // Fastify routes read these via getter closures (see createApiServer
-  // below) so they always see the current value without needing
-  // re-registration when the background init completes.
   const tgRuntime: Partial<TelegramRuntime> = {};
   const statusRef: { current: TelegramStatus } = {
     current: {
@@ -327,18 +263,13 @@ async function main(): Promise<void> {
     statusRef.current = next;
   };
 
-  // Singleton store for in-progress sign-ins from the Settings page. Holds
-  // temp gramjs clients between HTTP steps; GC sweeps stale entries every
-  // minute. Shut down with the rest of the app on SIGINT/SIGTERM.
   const loginSessionStore = createLoginSessionStore({
     apiId: config.TG_API_ID ?? 0,
     apiHash: config.TG_API_HASH ?? '',
     logger,
   });
 
-  // Live-swap mutex. Coalesces concurrent reload requests so two clicks of
-  // "Sign in" don't race two new clients into the runtime box. Shutdown
-  // awaits the current pending promise (if any) before tearing down.
+  // Mutex: coalesce concurrent reloads so two "Sign in" clicks don't race two clients in.
   let reloadPending: Promise<void> | null = null;
 
   async function reloadTelegramSession(): Promise<void> {
@@ -347,7 +278,6 @@ async function main(): Promise<void> {
     reloadPending = (async () => {
       logger.info('reloading Telegram session');
       const oldRuntime: Partial<TelegramRuntime> = { ...tgRuntime };
-      // Mark transient state so /system/status reflects the swap window.
       setStatus({
         state: 'connecting',
         connected: false,
@@ -361,16 +291,13 @@ async function main(): Promise<void> {
         setStatus,
         requestReload: reloadTelegramSession,
       });
-      // Replace refs in the box. Any unset keys on `next` clear the old
-      // value (so e.g. degraded mode after a sign-out actually drops the
-      // chat resolver).
+      // Clear first so unset keys on `next` actually drop old refs (e.g. resolver after sign-out).
       for (const key of Object.keys(tgRuntime) as (keyof TelegramRuntime)[]) {
         delete tgRuntime[key];
       }
       Object.assign(tgRuntime, next);
       setStatus(next.status);
-      // Tear down old refs after the swap so any in-flight route handler
-      // dereferencing the live getter sees the new value first.
+      // Tear down after the swap so an in-flight handler sees the new value first.
       await teardownRuntime(oldRuntime);
       if (next.status.connected) {
         logger.info('Telegram session reloaded');
@@ -388,9 +315,6 @@ async function main(): Promise<void> {
     }
   }
 
-  // Telegram Web App bot. Held in a mutable `bot` ref + a reload mutex so the
-  // bot-config route can live-swap it (new token / admin ids / public URL)
-  // without a restart.
   let bot: TgFeedBot | undefined;
   let botReloadPending: Promise<void> | null = null;
 
@@ -400,8 +324,7 @@ async function main(): Promise<void> {
     botReloadPending = (async () => {
       const auth = resolveTelegramAuth({ cfg: config, db, logger });
       const publicUrl = resolvePublicUrl({ cfg: config, db });
-      // Stop the old bot FIRST: grammy long-polls and two getUpdates loops on
-      // the same token would 409. A brief no-bot window is acceptable.
+      // Stop the old bot FIRST: two getUpdates loops on the same token 409.
       const old = bot;
       bot = undefined;
       if (old) {
@@ -438,8 +361,6 @@ async function main(): Promise<void> {
     }
   }
 
-  // DB-backed session store. Shared with the Fastify factory so both the
-  // login route and the prune task see the same set of rows.
   const sessionStore = createSessionStore({ db });
 
   const app = await createApiServer({
@@ -467,9 +388,6 @@ async function main(): Promise<void> {
   await app.listen({ host: '0.0.0.0', port: config.PORT });
   logger.info({ port: config.PORT }, 'API listening');
 
-  // Background pruner: keeps `forward_log` bounded and reaps expired web
-  // sessions. One hour cadence is plenty — neither table changes fast enough
-  // to justify aggressive ticking, and a single sweep is cheap.
   const prunePoller = createPoller({
     intervalMs: 60 * 60 * 1000,
     runOnStart: true,
@@ -483,22 +401,14 @@ async function main(): Promise<void> {
   });
   prunePoller.start();
 
-  // Telegram Web App bot — best-effort: a failed start leaves the API serving
-  // (password login still works). Started after `listen()`. `reloadBot`
-  // resolves the config DB-over-env and starts the bot when one is configured.
+  // Best-effort: a failed bot start leaves the API serving (password login still works).
   await reloadBot();
 
-  // Stats digest: a minute-tick scheduler that DMs admins a forwarded/
-  // filtered/error summary on the configured daily/weekly cadence. `getBot`
-  // reads the live `bot` ref so it always sees the current bot across reloads;
-  // when the digest is disabled (the default) every tick is a cheap no-op.
+  // getBot reads the live ref so the scheduler follows bot reloads.
   const statsDigest = createStatsDigestScheduler({ db, getBot: () => bot, logger });
   statsDigest.start();
 
-  // Background Telegram bring-up. Errors are caught inside
-  // tryStartTelegram; the outer .catch is a belt-and-suspenders for any
-  // throw that escapes (e.g. a logger crash). The promise is awaited from
-  // the shutdown handler so we don't tear down half-attached resources.
+  // Awaited from shutdown so we don't tear down half-attached resources.
   const tgInitPromise = (async () => {
     const tg = await tryStartTelegram({
       db,
@@ -509,10 +419,6 @@ async function main(): Promise<void> {
       requestReload: reloadTelegramSession,
     });
     if (shuttingDown) {
-      // Shutdown ran while we were connecting. Tear down what we built
-      // (tryStartTelegram's own early-shutdown branch already handled the
-      // pre-listener case; this path catches a SIGINT that landed *after*
-      // connect returned but before we got here).
       await teardownRuntime(tg);
       return;
     }
@@ -533,16 +439,12 @@ async function main(): Promise<void> {
     try {
       prunePoller.stop();
       statsDigest.stop();
-      // Let any in-flight bot reload settle before stopping the bot, so a
-      // reload triggered moments before SIGTERM can't leave a poll loop running.
+      // Settle an in-flight bot reload first, else it can leave a poll loop running past SIGTERM.
       if (botReloadPending) await botReloadPending.catch(() => {});
       if (bot) await bot.stop();
       await app.close();
-      // gramjs client.connect() doesn't accept an AbortSignal cleanly, so
-      // wait for the in-flight init to settle before tearing down its
-      // outputs. Bounded by Telegram's internal connect timeout.
+      // connect() takes no AbortSignal cleanly; wait for init (and any live-swap) to settle.
       await tgInitPromise.catch(() => {});
-      // Same for any in-flight live-swap.
       if (reloadPending) await reloadPending.catch(() => {});
       await loginSessionStore.shutdown();
       await teardownRuntime(tgRuntime);
diff --git a/apps/server/src/lib/dbHelpers.ts b/apps/server/src/lib/dbHelpers.ts
index f981626..9e06216 100644
--- a/apps/server/src/lib/dbHelpers.ts
+++ b/apps/server/src/lib/dbHelpers.ts
@@ -2,7 +2,6 @@ import { count, type SQL } from 'drizzle-orm';
 import type { SQLiteTable } from 'drizzle-orm/sqlite-core';
 import type { Db } from '../db/client.js';
 
-/** Single-shot row count using drizzle's typed `count()` aggregate. */
 export function countWhere(db: Db, table: SQLiteTable, where: SQL): number {
   const row = db.select({ c: count() }).from(table).where(where).get();
   return Number(row?.c ?? 0);
diff --git a/apps/server/src/lib/errors.ts b/apps/server/src/lib/errors.ts
index 3d573ea..f32cd0d 100644
--- a/apps/server/src/lib/errors.ts
+++ b/apps/server/src/lib/errors.ts
@@ -1,14 +1,4 @@
-/**
- * Typed error hierarchy for HTTP route handlers.
- *
- * Throw these from inside route handlers; the Fastify error handler
- * (`api/errorHandler.ts`) reads `statusCode` + `code` and maps them to
- * the wire-format envelope `{ error: { code, message, issues? } }`.
- *
- * Anything not derived from `AppError` is treated as a 500 by the handler
- * with a generic `internal` message — so do not throw raw `Error` for
- * client-facing failure modes.
- */
+// Throw these from route handlers; api/errorHandler.ts maps them to the wire envelope. A raw Error becomes a generic 500, so never throw one for client-facing failures.
 export class AppError extends Error {
   constructor(
     public readonly statusCode: number,
@@ -47,25 +37,14 @@ export class ConflictError extends AppError {
   }
 }
 
-/**
- * Thrown when an upstream service (Telegram via gramjs) is unreachable or
- * misbehaving. Maps to 503; the `code` is an explicit subtype the web UI
- * keys on for retry / fallback messaging.
- */
+// 503; `code` is a subtype the web UI keys on for retry/fallback messaging.
 export class UpstreamError extends AppError {
   constructor(message: string, code = 'upstream_unavailable') {
     super(503, code, message);
   }
 }
 
-/**
- * Builds the right 503 for a Telegram dep that's currently undefined.
- * `telegram_initializing` (transient, retry) when the lifecycle phase is
- * still 'connecting'; `telegram_unavailable` (configure / re-login) for
- * the steady-state disconnected case. Both subscription and destination
- * routes use the same logic, so it lives here to keep the message and
- * code mapping consistent.
- */
+// telegram_initializing (retry) while 'connecting', else telegram_unavailable (configure/re-login).
 export function telegramUnavailableError(status: { state: string }): UpstreamError {
   if (status.state === 'connecting') {
     return new UpstreamError('Telegram is starting up; retry in a moment', 'telegram_initializing');
@@ -73,12 +52,7 @@ export function telegramUnavailableError(status: { state: string }): UpstreamErr
   return new UpstreamError('Telegram client not configured', 'telegram_unavailable');
 }
 
-/**
- * Thrown for "this shouldn't happen" cases — e.g. a row that exists at
- * INSERT-time disappearing before the immediate follow-up read. Maps to
- * 500; the message is logged but `errorHandler.ts` only echoes the
- * generic envelope, so internal context never leaks to the client.
- */
+// 500 for "shouldn't happen" cases; message is logged but never echoed to the client.
 export class InternalError extends AppError {
   constructor(message: string) {
     super(500, 'internal', message);
diff --git a/apps/server/src/lib/jsonSafe.ts b/apps/server/src/lib/jsonSafe.ts
index a349b46..4f7f6df 100644
--- a/apps/server/src/lib/jsonSafe.ts
+++ b/apps/server/src/lib/jsonSafe.ts
@@ -1,31 +1,4 @@
-/**
- * Best-effort POJO snapshot of a gramjs `Message` (or any TL object) for
- * persistence in `forward_log.raw_message`.
- *
- * gramjs's `TLObject` classes already implement `toJSON()` correctly —
- * `BigInteger` instances stringify, `Buffer`s become base64. Round-tripping
- * through `JSON.stringify` + `JSON.parse` invokes those `toJSON` hooks for
- * us and drops class identity, which is exactly the POJO we want to store.
- * The replacer adds two safety nets that `toJSON` alone doesn't cover:
- *
- *   - **Cycle guard** via WeakSet. gramjs payloads are mostly tree-shaped,
- *     but `fwdFrom.fromId` chains can occasionally re-enter the original
- *     `peerId` graph; without the guard a single weird message blows the
- *     stack and we'd lose the row.
- *   - **Native `BigInt`** — newer Node versions (≥21) sometimes hand back
- *     raw `bigint` from MTProto deserialization where older versions used
- *     `big-integer`. `JSON.stringify` throws on these; coerce to string.
- *
- * After the round-trip we measure the encoded byte length. Pathological
- * payloads (full thumbnail strips, file refs with embedded preview blobs)
- * can balloon past 100KB; cap at `maxBytes` and replace the value with a
- * marker so the row still inserts cleanly and the UI surfaces the reason.
- *
- * Returns `null` for `null`/`undefined`, `MessageEmpty`, and `MessageService`
- * — none of those carry payloads worth viewing, and `MessageService`
- * specifically is filtered out earlier in the pipeline anyway. Callers
- * store the `null` directly.
- */
+// POJO snapshot of a gramjs TL object for forward_log.raw_message. JSON round-trip invokes toJSON and drops class identity; the replacer adds a WeakSet cycle guard (fwdFrom.fromId can re-enter the peerId graph) and coerces native bigint (Node ≥21) since JSON.stringify throws on it. Returns null for null/undefined, MessageEmpty, MessageService.
 
 export interface ToJsonSafeOptions {
   /** Max serialized JSON byte length; over this, value is replaced with a truncation marker. */
@@ -52,17 +25,12 @@ export function toJsonSafe(value: unknown, opts: ToJsonSafeOptions = {}): unknow
       return v;
     });
   } catch {
-    // Last-resort: gramjs surfaced a value we can't round-trip (e.g. a
-    // class with a throwing `toJSON`). Drop it rather than crash the
-    // forward — the row is still valuable without the snapshot.
+    // Unround-trippable value (e.g. a throwing toJSON); drop the snapshot, keep the row.
     return null;
   }
 
   if (encoded === undefined) return null;
-  // `Buffer.byteLength` measures real UTF-8 bytes — `.length` measures UTF-16
-  // code units, which understates multibyte content (a 64KB cap allows ~256KB
-  // of emoji-heavy text through). The comment block at the top of this file
-  // promises "byte length"; honor it literally.
+  // Real UTF-8 bytes, not UTF-16 .length which understates multibyte content.
   const byteLen = Buffer.byteLength(encoded, 'utf8');
   if (byteLen > maxBytes) {
     return { __truncated: true, size: byteLen };
diff --git a/apps/server/src/lib/loadEnv.ts b/apps/server/src/lib/loadEnv.ts
index fda835d..94170bb 100644
--- a/apps/server/src/lib/loadEnv.ts
+++ b/apps/server/src/lib/loadEnv.ts
@@ -1,16 +1,5 @@
-/**
- * Locate and load the workspace `.env` file.
- *
- * `dotenv/config` looks at `process.cwd() + '/.env'` only. In a pnpm
- * monorepo `pnpm -F @tg-feed/server dev` runs with cwd = `apps/server`,
- * which doesn't contain `.env` — so vars from the workspace-root `.env`
- * never load. Walking up from this module's directory finds the closest
- * `.env` regardless of cwd, so dev / migrate / tg:login all see the same
- * config.
- *
- * Import this module instead of `dotenv/config` from any entrypoint that
- * needs env vars before reading `process.env`.
- */
+// Walk up to the workspace-root .env (dotenv/config only checks cwd, which is apps/server under pnpm).
+// Import this instead of dotenv/config from any entrypoint.
 import { config as loadDotenv } from 'dotenv';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
diff --git a/apps/server/src/lib/logger.ts b/apps/server/src/lib/logger.ts
index 2ce3f11..7282988 100644
--- a/apps/server/src/lib/logger.ts
+++ b/apps/server/src/lib/logger.ts
@@ -9,24 +9,14 @@ export interface CreateLoggerOptions {
   silent?: boolean;
 }
 
-/**
- * Belt-and-suspenders redaction list. Existing call sites are audited not to
- * log these, but this guards against future code paths accidentally bundling
- * them into a log object — pino redacts BEFORE the transport sees the record,
- * so they never reach disk / stdout / log shipping.
- *
- * Paths use pino's path notation. `*` matches one level; multi-level wildcards
- * are not supported, so every common shape is enumerated. Cheap at runtime.
- */
+// pino's `*` matches a single level only, so every nesting depth is enumerated by hand.
 const REDACT_PATHS = [
-  // Request/response headers
   'req.headers.cookie',
   'req.headers.authorization',
   'req.headers["set-cookie"]',
   'res.headers["set-cookie"]',
   'headers.cookie',
   'headers.authorization',
-  // Web auth + cookies
   'password',
   '*.password',
   '*.*.password',
@@ -34,7 +24,6 @@ const REDACT_PATHS = [
   '*.cookie',
   'SESSION_SECRET',
   '*.SESSION_SECRET',
-  // Telegram session material
   'sessionString',
   '*.sessionString',
   'TG_SESSION_STRING',
@@ -43,12 +32,10 @@ const REDACT_PATHS = [
   '*.encryptedSessionString',
   'TG_SESSION_ENCRYPTION_KEY',
   '*.TG_SESSION_ENCRYPTION_KEY',
-  // Bot token + Mini App init payload (the latter carries a user-bound HMAC)
   'TG_BOT_TOKEN',
   '*.TG_BOT_TOKEN',
   'initData',
   '*.initData',
-  // Login flow secrets / bearer tokens
   'phoneCode',
   '*.phoneCode',
   'phoneCodeHash',
diff --git a/apps/server/src/lib/poller.ts b/apps/server/src/lib/poller.ts
index b9cdfb4..f187148 100644
--- a/apps/server/src/lib/poller.ts
+++ b/apps/server/src/lib/poller.ts
@@ -1,21 +1,10 @@
-/**
- * Periodic `run` invoker with idempotent start/stop semantics shared across
- * the server's background monitors (history poller, access monitor, health
- * monitor, dialogs keepalive). Each tick fires `run` without awaiting;
- * rejections are caught and logged so one bad iteration never silently
- * breaks the loop.
- *
- * In-flight / dedup handling stays in `run` — sites have materially different
- * needs (Promise coalescing, boolean skip, none) so this utility deliberately
- * stays out of that.
- */
+// Periodic `run` invoker with idempotent start/stop; rejections are caught and logged so one bad tick never breaks the loop. In-flight/dedup deliberately stays in `run` — call sites differ.
 import type { Logger } from './logger.js';
 
 export interface PollerOptions {
   intervalMs: number;
   run: () => Promise<void>;
   logger: Logger;
-  /** Message logged at error level when `run` rejects. */
   errorLogMessage: string;
   /** Invoke `run` immediately on `start()`. Default `true`. */
   runOnStart?: boolean;
diff --git a/apps/server/src/lib/sessionCrypto.ts b/apps/server/src/lib/sessionCrypto.ts
index 2831caf..b996403 100644
--- a/apps/server/src/lib/sessionCrypto.ts
+++ b/apps/server/src/lib/sessionCrypto.ts
@@ -1,31 +1,11 @@
-/**
- * AES-256-GCM helpers for secrets stored at rest — the Telegram session
- * blob in `telegram_account.encrypted_session_string` and the bot token in
- * `app_settings` key `'bot'`.
- *
- * Wire format: `base64(iv(12) || authTag(16) || ciphertext)`.
- * Key: 32 raw bytes, supplied as base64 in `TG_SESSION_ENCRYPTION_KEY`.
- *
- * The fingerprint (first 16 hex chars of `sha256(key)`) lets exports
- * advertise *which* key they were encrypted with so an import on a host
- * with a different key can skip the row instead of attempting (and
- * silently failing on) decryption. 64 bits is enough to detect mismatch
- * with no realistic collision risk; not enough to be a brute-force lever
- * against the underlying 256-bit key.
- *
- * Each blob is bound to a stable AAD label identifying the field it belongs
- * to (`encryptSecret`/`decryptSecret`), so a valid ciphertext can't be
- * swapped between fields (e.g. session string ↔ bot token) without the GCM
- * tag failing. The two session-string wrappers keep the original AAD plus a
- * legacy no-AAD decrypt path for blobs written before AAD binding existed.
- */
+// AES-256-GCM for secrets at rest. Wire: base64(iv(12) ‖ authTag(16) ‖ ciphertext).
+// Per-field AAD binds a ciphertext to its field so it can't be swapped (session string ↔ bot token).
+// 64-bit key fingerprint lets a cross-host import skip rows it can't decrypt; too short to brute-force the key.
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
 import type { Config } from '../config.js';
 
 export interface EncryptedEnvelope {
-  /** base64(iv ‖ authTag ‖ ciphertext) */
   ciphertext: string;
-  /** First 16 hex chars of sha256(key). */
   keyFingerprint: string;
 }
 
@@ -34,17 +14,10 @@ const IV_BYTES = 12;
 const TAG_BYTES = 16;
 const KEY_BYTES = 32;
 
-/** AAD for the Telegram session blob in `telegram_account`. */
 export const TELEGRAM_ACCOUNT_AAD = 'tg-feed/telegram_account/v1';
-/** AAD for the bot token in `app_settings` key `'bot'`. */
 export const BOT_TOKEN_AAD = 'tg-feed/bot_token/v1';
 
-/**
- * Returns the decoded encryption key as a 32-byte Buffer, or null when the
- * env var is not set. Throws if the var is set but malformed — config-time
- * validation in `config.ts` already enforces base64 + length, but this is
- * the second line of defence (and the runtime-typed return).
- */
+// null when unset; throws if malformed — backstop behind config.ts's base64/length check.
 export function loadEncryptionKey(cfg: Config): Buffer | null {
   if (!cfg.TG_SESSION_ENCRYPTION_KEY) return null;
   const buf = Buffer.from(cfg.TG_SESSION_ENCRYPTION_KEY, 'base64');
@@ -60,10 +33,6 @@ export function getKeyFingerprint(key: Buffer): string {
   return createHash('sha256').update(key).digest('hex').slice(0, 16);
 }
 
-/**
- * Encrypt `plain` under `key`, binding the ciphertext to `aad` (a stable
- * label identifying the field). The same `aad` must be supplied to decrypt.
- */
 export function encryptSecret(plain: string, key: Buffer, aad: string): EncryptedEnvelope {
   if (key.length !== KEY_BYTES) {
     throw new Error(`encryption key must be ${KEY_BYTES} bytes`);
@@ -79,10 +48,7 @@ export function encryptSecret(plain: string, key: Buffer, aad: string): Encrypte
   };
 }
 
-/**
- * Low-level GCM open. `aad === null` decrypts without binding (legacy
- * pre-AAD blobs). Throws on a truncated envelope or a tag mismatch.
- */
+// aad === null decrypts without binding (legacy pre-AAD blobs).
 function openEnvelope(envelope: EncryptedEnvelope, key: Buffer, aad: string | null): string {
   if (key.length !== KEY_BYTES) {
     throw new Error(`encryption key must be ${KEY_BYTES} bytes`);
@@ -100,7 +66,6 @@ function openEnvelope(envelope: EncryptedEnvelope, key: Buffer, aad: string | nu
   return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
 }
 
-/** Decrypt a blob produced by `encryptSecret` with the same `aad`. */
 export function decryptSecret(envelope: EncryptedEnvelope, key: Buffer, aad: string): string {
   return openEnvelope(envelope, key, aad);
 }
@@ -110,9 +75,7 @@ export function encryptSessionString(plain: string, key: Buffer): EncryptedEnvel
 }
 
 export function decryptSessionString(envelope: EncryptedEnvelope, key: Buffer): string {
-  // Try with AAD first; fall back to no-AAD so envelopes produced by
-  // pre-v1 versions of this module (no AAD) still decrypt. The legacy
-  // path will be removed once all stored ciphertexts are re-encrypted.
+  // Fall back to no-AAD so pre-v1 (no-AAD) blobs still decrypt.
   try {
     return openEnvelope(envelope, key, TELEGRAM_ACCOUNT_AAD);
   } catch {
diff --git a/apps/server/src/tg/accessMonitor.test.ts b/apps/server/src/tg/accessMonitor.test.ts
index 39cf28f..8fe6c14 100644
--- a/apps/server/src/tg/accessMonitor.test.ts
+++ b/apps/server/src/tg/accessMonitor.test.ts
@@ -418,4 +418,50 @@ describe('createAccessMonitor', () => {
     expect(calls).toBeGreaterThanOrEqual(3);
     monitor.stop();
   });
+
+  it('preserves each target status under threshold for a mixed-status shared chatId', async () => {
+    // Same chat is both the subscription source and a destination, with divergent
+    // persisted statuses — an under-threshold sweep must not clobber either badge.
+    s.dbHandle.db
+      .update(destinations)
+      .set({ chatId: '-1001111111111', accessStatus: 'no_access' })
+      .where(eq(destinations.id, s.destId))
+      .run();
+    s.dbHandle.db
+      .update(subscriptions)
+      .set({ sourceAccessStatus: 'ok' })
+      .where(eq(subscriptions.id, s.subId))
+      .run();
+
+    const client = makeClient(() => Promise.reject(new Error('CHANNEL_PRIVATE')));
+    const monitor = createAccessMonitor({
+      client,
+      db: s.dbHandle.db,
+      bus: s.bus,
+      logger,
+      intervalMs: 100,
+      noAccessFailThreshold: 3, // single sweep stays under the threshold
+    });
+
+    await monitor.probe();
+
+    const subRow = s.dbHandle.db
+      .select()
+      .from(subscriptions)
+      .where(eq(subscriptions.id, s.subId))
+      .get();
+    const destRow = s.dbHandle.db
+      .select()
+      .from(destinations)
+      .where(eq(destinations.id, s.destId))
+      .get();
+    // Each keeps its own prior status; the destination's no_access is NOT cleared to ok.
+    expect(subRow?.sourceAccessStatus).toBe('ok');
+    expect(destRow?.accessStatus).toBe('no_access');
+    // Freshness still bumped on both, and no status change means no events.
+    expect(subRow?.sourceAccessCheckedAt).toBeInstanceOf(Date);
+    expect(destRow?.accessCheckedAt).toBeInstanceOf(Date);
+    expect(s.busEvents).toHaveLength(0);
+    monitor.stop();
+  });
 });
diff --git a/apps/server/src/tg/accessMonitor.ts b/apps/server/src/tg/accessMonitor.ts
index cf58cc1..b3ae90f 100644
--- a/apps/server/src/tg/accessMonitor.ts
+++ b/apps/server/src/tg/accessMonitor.ts
@@ -1,26 +1,4 @@
-/**
- * Periodic check that the userbot still has access to every chat the
- * forwarder cares about — both source channels (subscribed to) and
- * destination chats (forwarded to).
- *
- * The userbot can lose access without any error reaching the app: the
- * channel admin kicks it, deletes the channel, or the account swaps. The
- * symptom is that `NewMessage` stops arriving from that source and/or
- * `forwardMessages` starts failing for that destination — both invisible
- * until something tries to use them. This monitor surfaces the loss
- * proactively by calling `getEntity` on every chat once a day and writing
- * a binary status to the DB so the UI can render a "no access" badge.
- *
- * Probe granularity is per-chat (deduped across subscriptions and
- * destinations) and sequential, mirroring `resolveSubscriptionsOnStartup`'s
- * floodwait-conscious pattern. On a `FloodWaitError` we wait the requested
- * duration once; further waits are deferred to the next 24h tick.
- *
- * Status writes are diffed against the current row value: only transitions
- * emit `subscription.changed` / `destination.changed` events. The
- * `*_checked_at` timestamp is always updated so future UIs can distinguish
- * fresh from stale.
- */
+// Daily getEntity probe of every source/destination chat, persisting a no-access status the UI badges; access loss is otherwise invisible until a forward fails.
 import { setTimeout as sleep } from 'node:timers/promises';
 import { eq } from 'drizzle-orm';
 import type { Api } from 'telegram';
@@ -34,14 +12,9 @@ import type { ProfilePhotoFetcher } from './profilePhoto.js';
 
 export const ACCESS_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 
-// Avoid flapping the "no access" badge on transient Telegram errors (a hostile
-// admin briefly kicking the bot, a one-off CHANNEL_PRIVATE on the wire, etc).
-// We only flip an existing `ok` status to `no_access` after this many
-// consecutive failures; going back to `ok` is always one-shot because access
-// being restored is unambiguous.
+// Consecutive failures before flipping ok→no_access (anti-flap); recovery to ok is one-shot.
 const NO_ACCESS_CONSECUTIVE_FAILS = 3;
 
-// Subset of `TelegramClient` we depend on so tests can pass a stub.
 export interface AccessProbeClient {
   getEntity(entity: string | Api.TypeInputPeer | Api.TypeInputUser): Promise<unknown>;
 }
@@ -51,28 +24,18 @@ export interface AccessMonitorDeps {
   db: Db;
   bus: EventBus;
   logger: Logger;
-  /** Default 24h. Overridable for tests. */
+  // default 24h
   intervalMs?: number;
-  /**
-   * How many consecutive failed probes flip a chat's status from `ok` to
-   * `no_access`. Default 3 — a hostile admin briefly kicking the bot, or a
-   * one-off `CHANNEL_PRIVATE` on the wire, shouldn't stamp the badge for a
-   * full 24h. Tests that want single-probe semantics override to 1.
-   */
+  // consecutive failed probes that flip ok→no_access (default 3)
   noAccessFailThreshold?: number;
-  /**
-   * Lazy backfill: when a row's `icon_data_url` is null and the access
-   * probe came back ok, the monitor calls this to fetch and stamp the
-   * channel/chat profile photo. Optional — when missing (Telegram-less
-   * boot, tests) the monitor only updates the access status columns.
-   */
+  // when set, backfills a row's null icon_data_url on a successful probe
   fetchProfilePhoto?: ProfilePhotoFetcher;
 }
 
 export interface AccessMonitor {
   start(): void;
   stop(): void;
-  /** Run one full sweep immediately. Exposed for tests and shutdown coverage. */
+  // run one full sweep immediately
   probe(): Promise<void>;
 }
 
@@ -100,16 +63,12 @@ export function createAccessMonitor(deps: AccessMonitorDeps): AccessMonitor {
   const failThreshold = deps.noAccessFailThreshold ?? NO_ACCESS_CONSECUTIVE_FAILS;
   let stopped = false;
   let inFlight: Promise<void> | undefined;
-  // Per-chat consecutive-failure counter. Reset on success; flip the persisted
-  // status only after `failThreshold` sweeps in a row. Lives in memory —
-  // survives between sweeps but not restarts, which is fine because the
-  // operator can see the persisted status in the UI either way.
+  // Per-chat consecutive-failure counter; in-memory, resets on success and on restart.
   const failureCounts = new Map<string, number>();
 
   async function probe(): Promise<void> {
     if (stopped) return;
-    // Serialize concurrent probes (interval tick mid-sweep is harmless but
-    // doubles the load). The second caller awaits the first.
+    // Serialize concurrent probes; the second caller awaits the first.
     if (inFlight) {
       await inFlight;
       return;
@@ -129,8 +88,7 @@ export function createAccessMonitor(deps: AccessMonitorDeps): AccessMonitor {
 
     let okCount = 0;
     let noAccessCount = 0;
-    // Group by chatId so a single chat used as both source and destination
-    // (or by multiple subscriptions) is probed once per sweep.
+    // Group by chatId so a chat reused across rows is probed once per sweep.
     const byChatId = new Map<string, Target[]>();
     for (const target of targets) {
       const existing = byChatId.get(target.chatId);
@@ -147,41 +105,41 @@ export function createAccessMonitor(deps: AccessMonitorDeps): AccessMonitor {
         skippedCount++;
         continue;
       }
-      // Hysteresis: a single failed probe doesn't flip the badge. Only after
-      // N consecutive failures does the persisted status move ok → no_access.
-      // Recovery (no_access → ok) is one-shot — the moment we can read the
-      // channel again, clear the badge.
-      let status: 'ok' | 'no_access';
       if (probed === 'no_access') {
         const next = (failureCounts.get(chatId) ?? 0) + 1;
         failureCounts.set(chatId, next);
         if (next < failThreshold) {
-          // Keep the previous persisted status; just bump the freshness ts.
-          // Recovery shortcut: if every target in the group was already
-          // `no_access`, treat as still `no_access` so we don't write `ok`.
-          const wasNoAccess = group.every((t) => t.prevStatus === 'no_access');
-          status = wasNoAccess ? 'no_access' : 'ok';
+          // Under threshold: hold each target's OWN prior status (anti-flap) and just bump
+          // its freshness ts. A single group-wide status would clobber a divergent badge
+          // when the same chatId is both a source and a destination.
           logger.debug(
             { chatId, consecutiveFailures: next },
             'access monitor: probe failed but still under flap threshold',
           );
-        } else {
-          status = 'no_access';
+          for (const target of group) {
+            touchCheckedAt(target);
+            if (target.prevStatus === 'no_access') noAccessCount++;
+            else okCount++;
+          }
+          continue;
         }
-      } else {
+        // Threshold reached: flip the whole group to no_access and reset the counter so the
+        // map doesn't grow unbounded for a chat that never recovers.
         failureCounts.delete(chatId);
-        status = 'ok';
+        for (const target of group) {
+          applyStatus(target, 'no_access');
+        }
+        noAccessCount += group.length;
+        continue;
       }
-      if (status === 'ok') okCount++;
-      else noAccessCount++;
+
+      // Reachable: clear the failure counter, mark every row ok, backfill any missing icons.
+      failureCounts.delete(chatId);
       for (const target of group) {
-        applyStatus(target, status);
+        applyStatus(target, 'ok');
       }
-      // Icon backfill: when this chat is reachable and at least one row in
-      // the group is still icon-less, fetch the profile photo once and
-      // stamp it on every matching row. Skipped on `no_access` because
-      // gramjs would just fail again.
-      if (status === 'ok' && fetchProfilePhoto) {
+      okCount += group.length;
+      if (fetchProfilePhoto) {
         const needsIcon = group.filter((t) => t.iconDataUrl === null);
         if (needsIcon.length > 0) {
           const iconDataUrl = await fetchProfilePhoto(chatId);
@@ -208,9 +166,7 @@ export function createAccessMonitor(deps: AccessMonitorDeps): AccessMonitor {
     } catch (err) {
       const rl = extractRateLimit(err);
       if (rl === null) return 'no_access';
-      // Bounded retry: wait the requested time once. If it floods again
-      // we leave the chat untouched until the next tick — better than
-      // burning CPU on a multi-hour cooldown.
+      // Wait the requested floodwait once; if it floods again, defer to the next tick.
       logger.warn({ chatId, seconds: rl.seconds }, 'access monitor: flood wait, retrying once');
       await sleep(rl.seconds * 1000);
       if (stopped) return 'skip';
@@ -260,6 +216,22 @@ export function createAccessMonitor(deps: AccessMonitorDeps): AccessMonitor {
     }
   }
 
+  // Bump only the freshness timestamp, leaving the access status (and its event) untouched.
+  function touchCheckedAt(target: Target): void {
+    const now = new Date();
+    if (target.kind === 'subscription') {
+      db.update(subscriptions)
+        .set({ sourceAccessCheckedAt: now })
+        .where(eq(subscriptions.id, target.id))
+        .run();
+    } else {
+      db.update(destinations)
+        .set({ accessCheckedAt: now })
+        .where(eq(destinations.id, target.id))
+        .run();
+    }
+  }
+
   function stampIcon(target: Target, iconDataUrl: string): void {
     if (target.kind === 'subscription') {
       db.update(subscriptions).set({ iconDataUrl }).where(eq(subscriptions.id, target.id)).run();
diff --git a/apps/server/src/tg/chatResolver.ts b/apps/server/src/tg/chatResolver.ts
index a0629fe..b474e34 100644
--- a/apps/server/src/tg/chatResolver.ts
+++ b/apps/server/src/tg/chatResolver.ts
@@ -1,15 +1,5 @@
-/**
- * Universal "paste-anything" chat resolver.
- *
- * Backs both `POST /api/subscriptions/resolve` and `POST /api/destinations/resolve`.
- * Accepts any of: `@username`, `t.me/username`, `t.me/+HASH` private invite,
- * `+HASH` raw invite, or a numeric chat id (`-100…` or bare positive).
- *
- * For private invites where the userbot is not yet a member, `chatId`
- * comes back `null` — only `inviteHash` is set, and the create endpoint
- * is expected to call `messages.ImportChatInvite` to actually join and
- * derive the resulting chatId.
- */
+// Paste-anything chat resolver: @username, t.me/username, t.me/+HASH or +HASH invite, or numeric id.
+// Not-yet-joined private invites return chatId=null with inviteHash set; create joins via ImportChatInvite.
 import type { TelegramClient } from 'telegram';
 import { NotFoundError, UpstreamError } from '../lib/errors.js';
 import { entityToResolved, parseInput } from './entityResolver.js';
@@ -21,7 +11,6 @@ export interface ChatResolveResult {
   handle: string | null;
   inviteHash: string | null;
   alreadyMember: boolean;
-  /** True when the resolved chat is a forum supergroup (has topics). */
   isForum: boolean;
 }
 
@@ -64,9 +53,7 @@ export function createChatResolver(client: ChatResolverClient): ChatResolver {
         handle: null,
         inviteHash: parsed.hash,
         alreadyMember: preview.alreadyMember,
-        // The chat isn't joined yet, so its forum status is unknown — the
-        // user sets the topic later via the edit sheet once joined.
-        isForum: false,
+        isForum: false, // unknown until joined; user sets topic later
       };
     }
 
@@ -88,9 +75,7 @@ export function createChatResolver(client: ChatResolverClient): ChatResolver {
       };
     }
 
-    // chatId branch — verify access and pull the title via getEntity. The
-    // input is already in the storage form (`-100xxx` or bare positive),
-    // so we don't need entityToResolved's prefix logic here.
+    // chatId branch: input already in storage form, so skip entityToResolved's prefix logic.
     let entity: unknown;
     try {
       entity = await client.getEntity(parsed.value);
diff --git a/apps/server/src/tg/client.ts b/apps/server/src/tg/client.ts
index f6c3814..2040c2b 100644
--- a/apps/server/src/tg/client.ts
+++ b/apps/server/src/tg/client.ts
@@ -20,15 +20,12 @@ export interface TelegramEnv {
 export interface TelegramEnvResult {
   ok: boolean;
   env?: TelegramEnv;
-  /** Where the session came from when `ok === true`. */
   source?: 'db' | 'env';
-  /** Human-readable reason when `ok === false`; safe to surface in API. */
+  // Safe to surface in the API when ok === false.
   reason?: string;
 }
 
-// Non-throwing variant — used by the server entrypoint to support degraded
-// boot (no Telegram client; API + DB still come up). Callers that genuinely
-// require credentials use `requireTelegramEnv` below.
+// Non-throwing variant supporting degraded boot (no client; API + DB still come up).
 export function readTelegramEnv(cfg: Config): TelegramEnvResult {
   const missing: string[] = [];
   if (cfg.TG_API_ID === undefined) missing.push('TG_API_ID');
@@ -61,17 +58,8 @@ export function requireTelegramEnv(cfg: Config): TelegramEnv {
   return result.env as TelegramEnv;
 }
 
-/**
- * Priority resolver: prefers the DB-stored account when its key fingerprint
- * matches the configured `TG_SESSION_ENCRYPTION_KEY`, then falls back to the
- * env `TG_SESSION_STRING`, then surfaces a degraded-mode reason.
- *
- * A row whose fingerprint *doesn't* match (key rotated, no key configured,
- * or the row was imported from another host) is skipped — the resolver
- * never auto-deletes it. The `/api/tg/account` endpoint reflects the
- * mismatch state so the operator can either restore the original key or
- * sign out + re-add.
- */
+// DB account (when key fingerprint matches) → env TG_SESSION_STRING → degraded reason.
+// A fingerprint mismatch is skipped, never auto-deleted; /api/tg/account surfaces the mismatch.
 export function resolveTelegramEnv(deps: {
   cfg: Config;
   db: Db;
@@ -155,9 +143,7 @@ export interface CreateTelegramClientOptions {
   gramjsLogLevel?: LogLevel;
 }
 
-// gramjs retries connect this many times with exponential backoff before
-// giving up and throwing — the listener's safe-handler catches downstream
-// failures, but `connect()` itself bubbles to the boot path's degraded mode.
+// connect() bubbles to the boot path's degraded mode after this many retries.
 const CONNECTION_RETRIES = 5;
 
 export function createTelegramClient(opts: CreateTelegramClientOptions): TelegramClient {
@@ -165,13 +151,12 @@ export function createTelegramClient(opts: CreateTelegramClientOptions): Telegra
   const client = new TelegramClient(session, opts.apiId, opts.apiHash, {
     connectionRetries: CONNECTION_RETRIES,
   });
-  // gramjs's own logger is loud by default; pin it to warn unless overridden.
+  // gramjs's logger is loud by default; pin to warn unless overridden.
   client.setLogLevel(opts.gramjsLogLevel ?? LogLevel.WARN);
   return client;
 }
 
-// `destroy` alone leaves the auto-reconnect loop running and the process
-// won't exit cleanly on SIGINT. Order matters: disconnect first, then destroy.
+// Order matters: disconnect before destroy, else the reconnect loop keeps the process alive on SIGINT.
 export async function disconnectClient(client: TelegramClient): Promise<void> {
   await client.disconnect();
   await client.destroy();
diff --git a/apps/server/src/tg/dialogsKeepalive.ts b/apps/server/src/tg/dialogsKeepalive.ts
index f2f3134..49845a9 100644
--- a/apps/server/src/tg/dialogsKeepalive.ts
+++ b/apps/server/src/tg/dialogsKeepalive.ts
@@ -1,20 +1,4 @@
-/**
- * Periodic `client.getDialogs` ping that keeps gramjs's update stream alive.
- *
- * The primary fix for "channel updates silently stop" is the `historyPoller`
- * — it actually fetches missed messages. This keepalive is the secondary,
- * cheap signal: gramjs maintainer painor documented in
- * https://github.com/gram-js/gramjs/issues/280 that calling `getEntity` /
- * `getMessages` / `getDialogs` periodically nudges Telegram to keep
- * delivering NewMessage events. Issue
- * https://github.com/gram-js/gramjs/issues/654 reports a 30s-interval
- * `getDialogs` call stabilising the update stream for 24h+.
- *
- * On its own this is unreliable for high-volume channels — that's what the
- * poller is for — but pairing the two narrows the window between a missed
- * post and a poller sweep, and is essentially free (one cheap RPC every
- * 30s).
- */
+// Secondary keepalive to the historyPoller: periodic getDialogs nudges gramjs to keep delivering NewMessage (gram-js/gramjs#280, #654). Unreliable alone, but cheap and narrows the miss window.
 import type { TelegramClient } from 'telegram';
 import type { Logger } from '../lib/logger.js';
 import { createPoller, type Poller } from '../lib/poller.js';
@@ -45,9 +29,7 @@ export function createDialogsKeepalive(deps: DialogsKeepaliveDeps): DialogsKeepa
     try {
       await client.getDialogs({ limit: KEEPALIVE_LIMIT });
     } catch (err) {
-      // Single bad call must not stop the timer — we want to keep retrying
-      // on the next tick. Log at debug to avoid noise on transient errors;
-      // the historyPoller and access monitor will surface persistent issues.
+      // Debug-level: transient failures are expected and the poller/access monitor surface persistent issues.
       logger.debug({ err }, 'dialogs keepalive ping failed');
     } finally {
       inFlight = false;
diff --git a/apps/server/src/tg/entityResolver.test.ts b/apps/server/src/tg/entityResolver.test.ts
index b4340d3..f1838e3 100644
--- a/apps/server/src/tg/entityResolver.test.ts
+++ b/apps/server/src/tg/entityResolver.test.ts
@@ -54,6 +54,27 @@ describe('parseInput', () => {
     });
   });
 
+  it('classifies legacy joinchat/<hash> links as { kind: "invite" }', () => {
+    expect(parseInput('https://t.me/joinchat/AAAAAEHbZQ')).toEqual({
+      kind: 'invite',
+      hash: 'AAAAAEHbZQ',
+    });
+    expect(parseInput('t.me/joinchat/AAAAAEHbZQ')).toEqual({
+      kind: 'invite',
+      hash: 'AAAAAEHbZQ',
+    });
+    expect(parseInput('joinchat/AAAAAEHbZQ')).toEqual({ kind: 'invite', hash: 'AAAAAEHbZQ' });
+    // Trailing path/query after the hash is stripped.
+    expect(parseInput('https://t.me/joinchat/AAAAAEHbZQ/extra?q=1')).toEqual({
+      kind: 'invite',
+      hash: 'AAAAAEHbZQ',
+    });
+  });
+
+  it('rejects a joinchat link with an invalid hash', () => {
+    expect(() => parseInput('t.me/joinchat/abc.def')).toThrow(ValidationError);
+  });
+
   it('classifies numeric ids as { kind: "chatId" }', () => {
     expect(parseInput('-1001234567890')).toEqual({ kind: 'chatId', value: '-1001234567890' });
     expect(parseInput('1234567')).toEqual({ kind: 'chatId', value: '1234567' });
diff --git a/apps/server/src/tg/entityResolver.ts b/apps/server/src/tg/entityResolver.ts
index 217b8f7..95779d4 100644
--- a/apps/server/src/tg/entityResolver.ts
+++ b/apps/server/src/tg/entityResolver.ts
@@ -1,11 +1,4 @@
-/**
- * Input parsing + entity → DTO mapping shared by `chatResolver` and the
- * invite resolver.
- *
- * This module no longer wraps gramjs directly — `chatResolver.ts` does that,
- * dispatching on the `parseInput` discriminator. The two helpers exported
- * here are pure: tests don't need a Telegram stub to exercise them.
- */
+// Pure input-parsing + entity → DTO mapping; no gramjs dependency so tests need no Telegram stub.
 import { UpstreamError, ValidationError } from '../lib/errors.js';
 
 export interface ResolvedEntity {
@@ -14,12 +7,7 @@ export interface ResolvedEntity {
   handle: string | null;
 }
 
-/**
- * Discriminated classification of a paste-the-source-here input. The web UI
- * accepts any of: `@username`, `t.me/username`, `t.me/+HASH` private invite,
- * `+HASH` raw invite, or a numeric chat id (`-100…` channels/supergroups
- * or bare positive ids for users / basic groups).
- */
+// Accepts @username, t.me/username, t.me/+HASH or +HASH invite, or a numeric chat id (-100… channel/supergroup, bare positive for user/basic group).
 export type ParsedInput =
   | { kind: 'handle'; value: string }
   | { kind: 'invite'; hash: string }
@@ -32,11 +20,19 @@ const CHAT_ID_RE = /^-?\d{6,}$/;
 export function parseInput(input: string): ParsedInput {
   let s = input.trim();
   if (!s) throw new ValidationError('input is required');
-  // Strip URL prefix variants.
   s = s.replace(/^https?:\/\//i, '');
   s = s.replace(/^(?:www\.)?(?:t\.me|telegram\.me|telegram\.dog)\//i, '');
-  // Strip trailing path / query (e.g. `t.me/foo/123`, `t.me/foo?x=1`). We do
-  // this before classifying so a paste like `t.me/+HASH/123` still resolves.
+  // Legacy invite form `joinchat/<hash>` — capture the hash before the trailing-path strip
+  // below collapses it to the bare word `joinchat`, which would mis-classify as a handle.
+  const joinchat = s.match(/^joinchat\/([^/?#]+)/i);
+  if (joinchat) {
+    const hash = joinchat[1]!;
+    if (!INVITE_HASH_RE.test(hash)) {
+      throw new ValidationError('expected a Telegram invite hash after `joinchat/`');
+    }
+    return { kind: 'invite', hash };
+  }
+  // Strip trailing path/query before classifying so `t.me/+HASH/123` still resolves.
   s = s.replace(/[/?#].*$/, '');
   if (!s) throw new ValidationError('input is required');
 
@@ -71,9 +67,7 @@ export function entityToResolved(raw: unknown, handle: string): ResolvedEntity {
   const e = raw as MaybeEntity;
   if (!e?.id) throw new UpstreamError(`Telegram returned an unrecognised entity for @${handle}`);
   const idStr = typeof e.id === 'object' ? e.id.toString() : String(e.id);
-  // Channels arrive as positive ids from getEntity; the storage convention
-  // (matching what the listener sees) is the supergroup form prefixed -100.
-  // For users / bots the bare positive id is correct.
+  // getEntity returns positive channel ids; storage convention is the -100 supergroup form (users/bots keep the bare id).
   const sourceChatId = sourceChatIdFor(idStr, raw);
   const fullName = [e.firstName, e.lastName].filter(Boolean).join(' ').trim();
   const sourceTitle = e.title ?? (fullName !== '' ? fullName : handle);
@@ -82,8 +76,7 @@ export function entityToResolved(raw: unknown, handle: string): ResolvedEntity {
 }
 
 function sourceChatIdFor(idStr: string, raw: unknown): string {
-  // gramjs Channel/Chat carry a className; we can't import the class here
-  // without dragging telegram into the type surface, so do a structural check.
+  // Structural className check to avoid dragging telegram into the type surface.
   const className = (raw as { className?: string })?.className ?? '';
   if (className === 'Channel' || className === 'Chat') {
     return idStr.startsWith('-') ? idStr : `-100${idStr}`;
diff --git a/apps/server/src/tg/forumTopics.ts b/apps/server/src/tg/forumTopics.ts
index f895fd6..0a63751 100644
--- a/apps/server/src/tg/forumTopics.ts
+++ b/apps/server/src/tg/forumTopics.ts
@@ -1,17 +1,5 @@
-/**
- * Lists a forum supergroup's topics so the destination UI can offer a picker.
- *
- * Backs `POST /api/destinations/topics`. Calls `channels.GetForumTopics` and
- * maps each live `ForumTopic` to `{ id, title }`; `ForumTopicDeleted` entries
- * are dropped. The General topic (reserved `top_msg_id` 1) is returned like
- * any other — the web layer represents "General" as the null/no-topic choice.
- *
- * Never throws: a non-forum chat, a missing channel, or any gramjs error
- * resolves to `{ isForum: false, topics: [] }` so the picker degrades to
- * "no topic" instead of failing the request. The channel is passed as a raw
- * id string — gramjs resolves entity-likes inside raw requests, matching the
- * history poller's `messages.GetHistory` usage.
- */
+// Lists a forum's topics for the destination picker. Never throws — any error degrades to empty,
+// so a non-forum chat or gramjs failure can't block saving a destination.
 import { Api } from 'telegram';
 import type { TelegramClient } from 'telegram';
 import type { ForumTopic } from '@tg-feed/shared';
@@ -24,12 +12,12 @@ export interface ForumTopicsResult {
 
 export type ForumTopicLister = (chatId: string) => Promise<ForumTopicsResult>;
 
-// Subset of `TelegramClient` we depend on so tests can pass a stub.
+// Subset of `TelegramClient` so tests can pass a stub.
 export interface ForumTopicListerClient {
   invoke: TelegramClient['invoke'];
 }
 
-/** Telegram caps `GetForumTopics` at 100 per page; one page is plenty for a picker. */
+// Telegram caps `GetForumTopics` at 100 per page; one page is plenty.
 const TOPICS_LIMIT = 100;
 
 export function createForumTopicLister(
@@ -43,9 +31,7 @@ export function createForumTopicLister(
         new Api.channels.GetForumTopics({ channel: chatId, limit: TOPICS_LIMIT }),
       )) as { topics?: unknown[] };
     } catch (err) {
-      // `CHANNEL_FORUM_MISSING` (not a forum) is the expected case; anything
-      // else is logged but still degrades to an empty list so the picker
-      // never blocks saving a destination.
+      // `CHANNEL_FORUM_MISSING` (not a forum) is the expected case here.
       logger.debug({ err, chatId }, 'forum topics: GetForumTopics failed');
       return { isForum: false, topics: [] };
     }
diff --git a/apps/server/src/tg/healthMonitor.ts b/apps/server/src/tg/healthMonitor.ts
index d9a1064..c54e49b 100644
--- a/apps/server/src/tg/healthMonitor.ts
+++ b/apps/server/src/tg/healthMonitor.ts
@@ -1,28 +1,6 @@
-/**
- * Periodic Telegram connection health probe + auto-recovery.
- *
- * gramjs's `autoReconnect` papers over short transport hiccups but doesn't
- * detect every failure mode that breaks NewMessage delivery — for example,
- * `AUTH_KEY_UNREGISTERED` (logout from another device), a sender stuck in a
- * half-open state, or a reconnect loop where `_sender.isReconnecting`
- * stays `true` forever and the update loop silently skips every ping
- * (see [updates.js:209]). Without an active probe `TelegramStatus` would
- * stay `connected: true` forever, even when no events are flowing.
- *
- * The monitor calls `updates.getState` on a fixed interval. It's the lightest
- * authenticated request that touches the same update sub-system the listener
- * depends on, so a successful response is reasonable evidence that updates
- * would also flow. On error we publish `connected: false` with the upstream
- * reason; on recovery we publish `connected: true` again.
- *
- * After `RELOAD_THRESHOLD` consecutive failures we additionally invoke the
- * caller-supplied `requestReload()` to force a full client teardown +
- * recreate via the same path the Settings UI uses for re-login. This catches
- * the "process alive, gramjs stuck" failure mode that no amount of internal
- * retry will recover from.
- *
- * The monitor never throws — caller errors propagate via `onStatusChange`.
- */
+// Active probe because gramjs's autoReconnect can sit in a stuck state (e.g. AUTH_KEY_UNREGISTERED,
+// isReconnecting stuck true) that breaks NewMessage delivery while TelegramStatus stays connected:true.
+// updates.getState hits the same update sub-system the listener needs; N failures trigger requestReload().
 import { Api } from 'telegram';
 import type { TelegramStatus } from '@tg-feed/shared';
 import type { Logger } from '../lib/logger.js';
@@ -32,9 +10,6 @@ export const HEALTH_CHECK_INTERVAL_MS = 20_000;
 export const HEALTH_CHECK_PROBE_TIMEOUT_MS = 10_000;
 export const HEALTH_CHECK_RELOAD_THRESHOLD = 3;
 
-/**
- * Minimal slice of TelegramClient used here so tests can pass a stub.
- */
 export interface HealthProbeClient {
   invoke(request: unknown): Promise<unknown>;
 }
@@ -43,12 +18,7 @@ export interface HealthMonitorDeps {
   client: HealthProbeClient;
   logger: Logger;
   onStatusChange: (status: TelegramStatus) => void;
-  /**
-   * Called after `reloadThreshold` consecutive probe failures. Optional —
-   * tests that only assert status emission can omit it. In production this
-   * is wired to `reloadTelegramSession()` from the entrypoint, which
-   * coalesces concurrent reload requests via its own mutex.
-   */
+  // Called after reloadThreshold consecutive failures; coalesces concurrent reloads via its own mutex.
   requestReload?: () => Promise<void>;
   intervalMs?: number;
   probeTimeoutMs?: number;
@@ -58,7 +28,7 @@ export interface HealthMonitorDeps {
 export interface HealthMonitor {
   start(): void;
   stop(): void;
-  /** Run one probe immediately. Exposed for tests. */
+  // Run one probe immediately; exposed for tests.
   probe(): Promise<void>;
 }
 
@@ -86,9 +56,7 @@ export function createHealthMonitor(deps: HealthMonitorDeps): HealthMonitor {
   }
 
   async function probe(): Promise<void> {
-    // Skip probes while a reload is mid-flight: the old client is about to
-    // be torn down, and a successful probe on it would just race with the
-    // swap. The new monitor (created post-reload) will resume probing.
+    // Skip while a reload is mid-flight: a probe on the about-to-be-torn-down client would race the swap.
     if (stopped || reloadInFlight) return;
     try {
       await invokeWithTimeout();
@@ -101,9 +69,7 @@ export function createHealthMonitor(deps: HealthMonitorDeps): HealthMonitor {
     } catch (err) {
       const reason = err instanceof Error ? err.message : 'unknown';
       consecutiveFailures += 1;
-      // First failure after a healthy streak is the most diagnostic signal —
-      // surface as ERROR. Continued failures drop to WARN to avoid log spam,
-      // since the auto-reload below already escalates if it stays broken.
+      // First failure after a healthy streak logs ERROR; continued failures drop to WARN to avoid spam.
       if (lastConnected !== false) {
         logger.error({ err, consecutiveFailures }, 'Telegram health check failed');
       } else {
@@ -113,21 +79,14 @@ export function createHealthMonitor(deps: HealthMonitorDeps): HealthMonitor {
       onStatusChange({ state: 'disconnected', connected: false, reason });
 
       if (requestReload && consecutiveFailures >= reloadThreshold) {
-        // Reset before firing so that if reload completes and the new client
-        // also fails, we don't immediately re-trigger on the very next probe
-        // (the new monitor will start its own counter from 0 anyway). The
-        // `reloadInFlight` gate covers the in-flight window.
+        // Reset before firing so a post-reload failure doesn't immediately re-trigger; reloadInFlight gates the window.
         consecutiveFailures = 0;
         reloadInFlight = true;
         logger.error(
           { threshold: reloadThreshold },
           'Telegram health check exceeded failure threshold — triggering session reload',
         );
-        // Fire-and-forget. `requestReload` has its own coalescing mutex in
-        // the entrypoint, so we can't accidentally stack reloads. The
-        // `.finally` clears `reloadInFlight` even if the swap throws — but
-        // by then `stop()` will have already been called on this monitor as
-        // part of the old runtime teardown, so the flag is moot.
+        // Fire-and-forget; requestReload coalesces so reloads can't stack.
         void requestReload()
           .catch((reloadErr) => {
             logger.error({ err: reloadErr }, 'health-triggered Telegram reload failed');
diff --git a/apps/server/src/tg/inviteResolver.ts b/apps/server/src/tg/inviteResolver.ts
index e66d940..7acf541 100644
--- a/apps/server/src/tg/inviteResolver.ts
+++ b/apps/server/src/tg/inviteResolver.ts
@@ -1,22 +1,4 @@
-/**
- * gramjs wrappers for `messages.CheckChatInvite` (preview) and
- * `messages.ImportChatInvite` (actually join).
- *
- * The check call is non-destructive — we use it from the resolve endpoint
- * to show the user a preview card before they commit. The import call is
- * destructive (joins the chat) — used from the create endpoint after the
- * user confirms.
- *
- * For `ChatInvite` (not yet a member) the preview carries the title but no
- * chatId — only `ImportChatInvite` returns the chat. The resolve flow
- * surfaces `chatId: null` in that case and forwards the raw hash to the
- * create endpoint.
- *
- * Errors are mapped to the typed `AppError` hierarchy for `checkInvite`
- * (so the resolve endpoint propagates 4xx/5xx with stable codes), and
- * coalesced into `'no_access'` for the import path (matching the
- * `joinChannel` pattern — the create endpoint wants a single decision bit).
- */
+// checkInvite = non-destructive preview (ChatInvite carries title but no chatId until joined); createImportInvite joins. Check errors map to typed AppError; import coalesces to 'no_access'.
 import { Api } from 'telegram';
 import type { TelegramClient } from 'telegram';
 import { NotFoundError, UpstreamError } from '../lib/errors.js';
@@ -57,13 +39,7 @@ const NOT_FOUND_PATTERNS = /INVITE_HASH_(EXPIRED|INVALID|EMPTY)/i;
 const PRIVATE_PATTERNS =
   /CHANNEL_PRIVATE|USER_BANNED_IN_CHANNEL|USERS_TOO_MUCH|CHAT_ADMIN_REQUIRED/i;
 
-/**
- * Convert a chat-shaped object (from `ChatInviteAlready.chat`,
- * `ChatInvitePeek.chat`, or an entry in `Updates.chats[]`) into the
- * `-100`-prefixed string the rest of the system uses. Mirrors the rule in
- * `entityResolver.entityToResolved` so invite-derived ids match
- * `-100`-prefixed ids stored elsewhere.
- */
+// Normalize a chat-shaped object to the -100-prefixed id used everywhere else.
 export function chatIdFromInviteChat(chat: unknown): string | null {
   if (!chat || typeof chat !== 'object') return null;
   const c = chat as { id?: { toString: () => string } | number | string; className?: string };
@@ -82,10 +58,7 @@ function chatTitle(chat: unknown): string {
   return c.title ?? '';
 }
 
-// Invite hashes are bearer credentials — anyone with the full string can join
-// the chat (subject to expiry/usage limits). Logs may be shipped to external
-// systems; only the first 6 chars survive so the operator can still correlate
-// without leaking the credential.
+// Invite hashes are bearer credentials; keep only the first 6 chars out of logs.
 function redactInviteHash(hash: string): string {
   if (hash.length <= 6) return '***';
   return `${hash.slice(0, 6)}…`;
@@ -110,7 +83,7 @@ export async function checkInvite(client: InviteClient, hash: string): Promise<I
     return {
       chatId: chatIdFromInviteChat(result.chat),
       title: chatTitle(result.chat),
-      // Peek means we can read but haven't joined as a full participant.
+      // Peek = can read, not a full participant.
       alreadyMember: false,
     };
   }
@@ -139,8 +112,7 @@ export function createImportInvite(client: InviteClient, logger: Logger): Import
     } catch (err) {
       const msg = errorMessage(err).toUpperCase();
       if (/USER_ALREADY_PARTICIPANT/i.test(msg)) {
-        // Already a member — fall back to a check call to fetch the chat
-        // info so the caller still gets a chatId for storage.
+        // Already a member — check call still yields a chatId for storage.
         try {
           const preview = await checkInvite(client, hash);
           return { status: 'ok', chatId: preview.chatId, title: preview.title };
diff --git a/apps/server/src/tg/joinChannel.ts b/apps/server/src/tg/joinChannel.ts
index 38a44ae..86b0792 100644
--- a/apps/server/src/tg/joinChannel.ts
+++ b/apps/server/src/tg/joinChannel.ts
@@ -1,20 +1,4 @@
-/**
- * Auto-join helper used when a new subscription is created.
- *
- * The userbot only receives `NewMessage` events from chats it's a member
- * of. Adding a row to `subscriptions` doesn't change that on Telegram's
- * side, so without an explicit `channels.JoinChannel` invocation new
- * subscriptions to public channels would silently produce no traffic.
- *
- * Outcomes are coalesced into two states ('ok' | 'no_access') so the
- * caller can store a single column. We swallow gramjs errors here — the
- * caller wants to create the subscription regardless; the badge is the UI
- * signal that the operator needs to fix access manually.
- *
- * `JoinChannel` only applies to channels/supergroups (`-100xxx`). For user
- * or bot DMs and basic groups we fall back to a `getEntity` smoke test:
- * if the userbot can resolve the entity, it has access.
- */
+// Auto-join on subscription create: the userbot only gets NewMessage from chats it's a member of, so public channels need an explicit JoinChannel or they produce no traffic. Errors coalesce to 'ok' | 'no_access'; non-channels fall back to a getEntity access probe.
 import { Api } from 'telegram';
 import type { TelegramClient } from 'telegram';
 import type { Logger } from '../lib/logger.js';
@@ -22,17 +6,14 @@ import type { Logger } from '../lib/logger.js';
 export type AccessProbeResult = 'ok' | 'no_access';
 export type JoinChannelFn = (sourceChatId: string) => Promise<AccessProbeResult>;
 
-// Subset of gramjs `TelegramClient` we depend on, so tests can pass a stub
-// without standing up the full client.
+// Subset of gramjs TelegramClient we depend on, so tests can stub it.
 export interface JoinChannelClient {
   getInputEntity: TelegramClient['getInputEntity'];
   getEntity: TelegramClient['getEntity'];
   invoke: TelegramClient['invoke'];
 }
 
-// Errors that mean "userbot can't access this chat" rather than a transient
-// failure. Anything not in this list is logged at warn so unknown error
-// shapes get diagnosed instead of silently classified.
+// "Can't access this chat" errors; anything else is logged at warn, not silently classified.
 const NO_ACCESS_PATTERNS: readonly RegExp[] = [
   /CHANNEL_PRIVATE/i,
   /CHANNEL_INVALID/i,
@@ -52,9 +33,7 @@ function errorMessage(err: unknown): string {
 
 export function createJoinChannel(client: JoinChannelClient, logger: Logger): JoinChannelFn {
   return async (sourceChatId) => {
-    // -100xxx is the supergroup/channel marker. Bot/user DMs and basic
-    // groups can't be joined via channels.JoinChannel; for those we just
-    // verify access exists.
+    // -100xxx = channel/supergroup; DMs and basic groups can't JoinChannel, just probe access.
     const isChannelLike = sourceChatId.startsWith('-100');
     if (!isChannelLike) {
       try {
@@ -77,9 +56,7 @@ export function createJoinChannel(client: JoinChannelClient, logger: Logger): Jo
       return 'no_access';
     }
     if (!(inputPeer instanceof Api.InputPeerChannel)) {
-      // -100xxx that resolved to something other than a channel — caller
-      // passed a misclassified id. No JoinChannel is meaningful; report
-      // no_access so the operator sees the mismatch in the UI.
+      // -100xxx that resolved to a non-channel: misclassified id, surface the mismatch.
       return 'no_access';
     }
 
diff --git a/apps/server/src/tg/listener.test.ts b/apps/server/src/tg/listener.test.ts
index a2f030f..cdc09e8 100644
--- a/apps/server/src/tg/listener.test.ts
+++ b/apps/server/src/tg/listener.test.ts
@@ -132,4 +132,34 @@ describe('attachNewMessageListener', () => {
       sourceMessageId: '42',
     });
   });
+
+  it('fans out to every subscription that shares the same source', async () => {
+    const [dest2] = dbHandle.db
+      .insert(destinations)
+      .values({ name: 'd2', chatId: '-100888' })
+      .returning()
+      .all();
+    dbHandle.db
+      .insert(subscriptions)
+      .values({ sourceChatId: '-100123', sourceTitle: 's2', destinationId: dest2!.id })
+      .run();
+
+    const captured: Partial<CapturedHandler> = {};
+    const enqueued: RawForwardJob[] = [];
+    const forwarding: RawForwardingHandle = {
+      enqueue: (job) => {
+        enqueued.push(job);
+      },
+    };
+    attachNewMessageListener(
+      fakeClient(captured as CapturedHandler),
+      dbHandle.db,
+      logger,
+      forwarding,
+    );
+    await captured.handler!(makeEvent('-100123', 42));
+    expect(enqueued).toHaveLength(2);
+    expect(enqueued.map((j) => j.destinationChatId).sort()).toEqual(['-100888', '-100999']);
+    expect(enqueued.every((j) => j.sourceMessageId === '42')).toBe(true);
+  });
 });
diff --git a/apps/server/src/tg/listener.ts b/apps/server/src/tg/listener.ts
index cfeb83f..4fc97f0 100644
--- a/apps/server/src/tg/listener.ts
+++ b/apps/server/src/tg/listener.ts
@@ -8,7 +8,7 @@ import { toJsonSafe } from '../lib/jsonSafe.js';
 import type { Logger } from '../lib/logger.js';
 import {
   extractMatchableEvent,
-  matchSubscription,
+  matchSubscriptions,
   type ResolvedSubscription,
 } from './messageMatcher.js';
 
@@ -22,9 +22,7 @@ export function attachNewMessageListener(
     const matchable = extractMatchableEvent(event);
     if (!matchable) return;
 
-    // Filter by source_chat_id in the WHERE clause (backed by
-    // idx_subscriptions_source_chat_id) so the DB returns only the rows
-    // that could possibly match — usually 0 or 1, never the full table.
+    // WHERE source_chat_id hits idx_subscriptions_source_chat_id, not a full scan.
     const activeSubs = db
       .select({
         id: subscriptions.id,
@@ -41,9 +39,9 @@ export function attachNewMessageListener(
       .innerJoin(destinations, eq(subscriptions.destinationId, destinations.id))
       .where(and(eq(subscriptions.enabled, true), eq(subscriptions.sourceChatId, matchable.chatId)))
       .all() as ResolvedSubscription[];
-    const matched = matchSubscription(matchable, activeSubs);
+    const matched = matchSubscriptions(matchable, activeSubs);
 
-    if (!matched) {
+    if (matched.length === 0) {
       logger.debug(
         { chatId: matchable.chatId, messageId: matchable.messageId },
         'message has no matching subscription',
@@ -51,42 +49,41 @@ export function attachNewMessageListener(
       return;
     }
 
-    logger.info(
-      {
-        subscriptionId: matched.id,
-        sourceChatId: matched.sourceChatId,
-        messageId: matchable.messageId,
-        hasMedia: !!event.message.media,
-      },
-      'message matched subscription',
-    );
+    // One snapshot of the source message, reused for every fan-out destination.
+    const rawMessage = toJsonSafe(event.message);
+    for (const sub of matched) {
+      logger.info(
+        {
+          subscriptionId: sub.id,
+          sourceChatId: sub.sourceChatId,
+          messageId: matchable.messageId,
+          hasMedia: !!event.message.media,
+        },
+        'message matched subscription',
+      );
 
-    forwarding.enqueue({
-      subscriptionId: matched.id,
-      sourceChatId: matched.sourceChatId,
-      destinationChatId: matched.destinationChatId,
-      destinationTopicId: matched.destinationTopicId,
-      sourceMessageId: matchable.messageId,
-      text: matchable.text,
-      hasMedia: matchable.hasMedia,
-      rawMessage: toJsonSafe(event.message),
-      ...(matchable.groupedId !== undefined ? { groupedId: matchable.groupedId } : {}),
-      ...(matchable.senderUsername !== undefined
-        ? { senderUsername: matchable.senderUsername }
-        : {}),
-    });
+      forwarding.enqueue({
+        subscriptionId: sub.id,
+        sourceChatId: sub.sourceChatId,
+        destinationChatId: sub.destinationChatId,
+        destinationTopicId: sub.destinationTopicId,
+        sourceMessageId: matchable.messageId,
+        text: matchable.text,
+        hasMedia: matchable.hasMedia,
+        rawMessage,
+        ...(matchable.groupedId !== undefined ? { groupedId: matchable.groupedId } : {}),
+        ...(matchable.senderUsername !== undefined
+          ? { senderUsername: matchable.senderUsername }
+          : {}),
+      });
+    }
   };
 
-  // Wrap the handler so a single bad event (DB hiccup, malformed gramjs
-  // payload, downstream throw from `enqueue`) gets logged and dropped
-  // instead of bubbling up into gramjs and potentially destabilising the
-  // whole TG session.
+  // Drop a single bad event rather than let it bubble into gramjs and destabilise the TG session.
   const safeHandler = async (event: NewMessageEvent): Promise<void> => {
     try {
       await handler(event);
     } catch (err) {
-      // Include the error type so DB / gramjs / forwarding failures are
-      // distinguishable in the logs without re-deriving it from the stack.
       logger.error(
         { err, errorType: err instanceof Error ? err.constructor.name : typeof err },
         'listener handler threw; dropping event',
@@ -94,6 +91,6 @@ export function attachNewMessageListener(
     }
   };
 
-  // `incoming: true` filters out events the userbot itself produced.
+  // incoming: true filters out events the userbot itself produced.
   client.addEventHandler(safeHandler, new NewMessage({ incoming: true }));
 }
diff --git a/apps/server/src/tg/loginSession.ts b/apps/server/src/tg/loginSession.ts
index 136b531..7d1469e 100644
--- a/apps/server/src/tg/loginSession.ts
+++ b/apps/server/src/tg/loginSession.ts
@@ -1,19 +1,4 @@
-/**
- * In-memory store for in-progress Telegram sign-ins from the Settings page.
- *
- * gramjs's `client.start()` uses callbacks (phoneNumber/phoneCode/password
- * resolved synchronously inside one promise) which fights HTTP step
- * boundaries — we need to break the flow across multiple requests so the
- * UI can prompt the user, get the code, then return for the next step.
- * The lower-level `Api.auth.SendCode` / `Api.auth.SignIn` / `CheckPassword`
- * triplet maps onto three HTTP calls cleanly.
- *
- * Each pending login holds a temp `TelegramClient` (with an empty
- * `StringSession`) that connects on `start()` and lives until either
- * `verifyCode` / `verifyPassword` / `validateRaw` finalize, `cancel` is
- * called, or the TTL GC sweeps it. The session string is only saved
- * after the final auth.* RPC succeeds.
- */
+// In-memory store for in-progress Telegram sign-ins, split across HTTP steps because gramjs's callback-based start() can't pause for UI prompts.
 import { randomBytes } from 'node:crypto';
 import { Api, TelegramClient } from 'telegram';
 import { computeCheck } from 'telegram/Password.js';
@@ -40,13 +25,7 @@ export interface LoginCompleted {
 }
 
 export interface LoginSessionStore {
-  /**
-   * Begin a phone-code sign-in. `ownerToken` ties this session to the
-   * calling web session so other authed tabs (or anyone who guesses a
-   * sessionId) can't drive someone else's in-progress login. Defaults to
-   * an empty string for raw-paste / legacy callers — those skip binding
-   * because they don't need to cross HTTP boundaries.
-   */
+  // ownerToken binds the session to the calling web session so other tabs can't drive it; empty string (raw-paste/legacy) skips binding.
   start(phoneNumber: string, ownerToken?: string): Promise<{ sessionId: string }>;
   verifyCode(
     sessionId: string,
@@ -71,12 +50,7 @@ interface PendingLogin {
   phoneNumber: string;
   phoneCodeHash: string;
   expiresAt: number;
-  /**
-   * Web-session token (the cookie value) of the caller who created this
-   * login session. Empty string means "no binding" (legacy / raw-paste).
-   * `verifyCode`/`verifyPassword`/`cancel` reject if the caller's token
-   * doesn't match — keeps a second authed tab from hijacking the flow.
-   */
+  // empty string disables owner binding
   ownerToken: string;
 }
 
@@ -99,15 +73,12 @@ export function createLoginSessionStore(deps: CreateLoginSessionStoreDeps): Logi
       }
     }
   }, GC_INTERVAL_MS);
-  // Don't keep the process alive solely for this timer.
   if (typeof gc.unref === 'function') gc.unref();
 
   function generateSessionId(): string {
     return randomBytes(SESSION_ID_BYTES).toString('hex');
   }
 
-  // Owner-binding check: skip when either side has no token (raw-paste /
-  // legacy path), enforce strictly when both sides have one.
   function assertOwner(pending: PendingLogin, ownerToken: string | undefined): void {
     if (pending.ownerToken && ownerToken && pending.ownerToken !== ownerToken) {
       throw new AppError(
@@ -198,13 +169,10 @@ export function createLoginSessionStore(deps: CreateLoginSessionStoreDeps): Logi
         return { done: true, account };
       } catch (err) {
         if (isPasswordNeeded(err)) {
-          // Keep the temp client alive for the follow-up `verifyPassword` call.
-          // Refresh the TTL window so the user has time to enter the 2FA password.
+          // Refresh TTL and keep the client alive for the follow-up verifyPassword.
           pending.expiresAt = Date.now() + ttlMs;
           return { needsPassword: true };
         }
-        // Any other error terminates this attempt — drop the temp client so it
-        // doesn't leak. The caller can `start` again.
         dropSession(sessionId);
         await disconnectSilently(pending.client, logger);
         throw mapGramError(err);
@@ -222,8 +190,7 @@ export function createLoginSessionStore(deps: CreateLoginSessionStoreDeps): Logi
         await disconnectSilently(pending.client, logger);
         return { done: true, account };
       } catch (err) {
-        // Wrong password → keep the session alive so the user can retry; any
-        // other error tears it down.
+        // Wrong password keeps the session alive for retry; anything else tears it down.
         if (isPasswordWrong(err)) {
           pending.expiresAt = Date.now() + ttlMs;
           throw new AppError(401, 'wrong_2fa_password', 'incorrect 2FA password');
@@ -246,11 +213,7 @@ export function createLoginSessionStore(deps: CreateLoginSessionStoreDeps): Logi
       if (!sessionString || sessionString.length < 8) {
         throw new ValidationError('session string is empty or too short');
       }
-      // gramjs's `StringSession` parser throws `Error("Not a valid string")`
-      // when the input doesn't start with the version byte, and its
-      // `BinaryReader` can throw on truncated payloads. Both cases need to
-      // surface as a 400 with a clear code instead of escaping the route as
-      // a generic 500.
+      // StringSession throws on a missing version byte or truncated payload; surface as 400, not a generic 500.
       let session: StringSession;
       try {
         session = new StringSession(sessionString);
@@ -308,9 +271,7 @@ function newTempClient(apiId: number, apiHash: string): TelegramClient {
 
 async function finalize(pending: PendingLogin): Promise<LoginAccountInfo> {
   const me = (await pending.client.getMe()) as Api.User;
-  // gramjs types `session.save()` as `void` even though `StringSession`
-  // returns the encoded string at runtime. Cast through `unknown` to avoid
-  // the strict-overlap warning.
+  // gramjs types session.save() as void though StringSession returns the encoded string at runtime.
   const sessionString = pending.client.session.save() as unknown as string;
   if (typeof sessionString !== 'string' || sessionString.length === 0) {
     throw new AppError(502, 'session_save_failed', 'failed to mint Telegram session');
@@ -355,7 +316,7 @@ function isPasswordWrong(err: unknown): boolean {
 
 function mapGramError(err: unknown): AppError {
   if (err instanceof AppError) return err;
-  // FloodWait — gramjs surfaces the wait time as `seconds`.
+  // gramjs FloodWait surfaces the wait time as `seconds`.
   const seconds = (err as { seconds?: unknown }).seconds;
   if (typeof seconds === 'number' && Number.isFinite(seconds)) {
     return new AppError(
diff --git a/apps/server/src/tg/messageMatcher.test.ts b/apps/server/src/tg/messageMatcher.test.ts
index 3ab785c..3d612eb 100644
--- a/apps/server/src/tg/messageMatcher.test.ts
+++ b/apps/server/src/tg/messageMatcher.test.ts
@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest';
-import { extractMatchableEvent, matchSubscription, type MatchableEvent } from './messageMatcher.js';
+import {
+  extractMatchableEvent,
+  matchSubscriptions,
+  type MatchableEvent,
+} from './messageMatcher.js';
 import type { Subscription } from '../db/schema.js';
 
 function makeSub(overrides: Partial<Subscription>): Subscription {
@@ -26,25 +30,25 @@ const event: MatchableEvent = {
   hasMedia: false,
 };
 
-describe('matchSubscription', () => {
+describe('matchSubscriptions', () => {
   it('returns the matching enabled subscription', () => {
     const subs = [makeSub({ id: 1 })];
-    expect(matchSubscription(event, subs)).toEqual(subs[0]);
+    expect(matchSubscriptions(event, subs)).toEqual(subs);
   });
 
   it('skips disabled subscriptions even on a chat-id match', () => {
     const subs = [makeSub({ id: 1, enabled: false })];
-    expect(matchSubscription(event, subs)).toBeUndefined();
+    expect(matchSubscriptions(event, subs)).toEqual([]);
   });
 
-  it('returns undefined when no subscription matches', () => {
+  it('returns an empty array when no subscription matches', () => {
     const subs = [makeSub({ id: 1, sourceChatId: '-100888' })];
-    expect(matchSubscription(event, subs)).toBeUndefined();
+    expect(matchSubscriptions(event, subs)).toEqual([]);
   });
 
-  it('returns the first enabled subscription when multiple match', () => {
+  it('returns all enabled subscriptions when multiple match (fan-out)', () => {
     const subs = [makeSub({ id: 1, enabled: false }), makeSub({ id: 2 }), makeSub({ id: 3 })];
-    expect(matchSubscription(event, subs)?.id).toBe(2);
+    expect(matchSubscriptions(event, subs).map((s) => s.id)).toEqual([2, 3]);
   });
 });
 
diff --git a/apps/server/src/tg/messageMatcher.ts b/apps/server/src/tg/messageMatcher.ts
index c0257d7..e054687 100644
--- a/apps/server/src/tg/messageMatcher.ts
+++ b/apps/server/src/tg/messageMatcher.ts
@@ -1,12 +1,7 @@
 import type { NewMessageEvent } from 'telegram/events/index.js';
 import type { Subscription } from '../db/schema.js';
 
-/**
- * Subscription with destination chat id (and optional forum topic) resolved
- * via JOIN. The listener needs `destinationChatId` to enqueue forward jobs
- * but the `subscriptions` row only carries a FK now (`destinationId`);
- * `destinationTopicId` rides along so forum destinations route to a topic.
- */
+// Subscription row plus the JOIN-resolved destination chat/topic.
 export type ResolvedSubscription = Subscription & {
   destinationChatId: string;
   destinationTopicId: string | null;
@@ -16,11 +11,9 @@ export interface MatchableEvent {
   chatId: string;
   messageId: string;
   groupedId?: string;
-  /** Body text (or empty string for media-only messages without caption). */
-  text: string;
+  text: string; // empty string for media-only messages
   hasMedia: boolean;
-  /** Lowercased sender username, no leading '@'. Undefined for anonymous channel posts. */
-  senderUsername?: string;
+  senderUsername?: string; // lowercased, no '@'; undefined for anonymous channel posts
 }
 
 export function extractMatchableEvent(event: NewMessageEvent): MatchableEvent | null {
@@ -56,9 +49,10 @@ function extractSenderUsername(message: { sender?: unknown }): string | undefine
   return undefined;
 }
 
-export function matchSubscription<T extends Subscription>(
+// All enabled subscriptions for the event's source chat — a source may fan out to several.
+export function matchSubscriptions<T extends Subscription>(
   event: MatchableEvent,
   subscriptions: readonly T[],
-): T | undefined {
-  return subscriptions.find((s) => s.enabled && s.sourceChatId === event.chatId);
+): T[] {
+  return subscriptions.filter((s) => s.enabled && s.sourceChatId === event.chatId);
 }
diff --git a/apps/server/src/tg/profilePhoto.ts b/apps/server/src/tg/profilePhoto.ts
index c5fca73..40e5109 100644
--- a/apps/server/src/tg/profilePhoto.ts
+++ b/apps/server/src/tg/profilePhoto.ts
@@ -1,18 +1,5 @@
-/**
- * Profile-photo fetcher used at subscription/destination create and as a
- * lazy backfill from the access monitor.
- *
- * Telegram doesn't expose chat photos as public URLs — gramjs has to
- * download the bytes via `client.downloadProfilePhoto`. We encode the
- * small thumbnail as a `data:image/jpeg;base64,...` URL so it can ride
- * inline in the list DTOs and the UI can drop it straight into an `<img>`.
- *
- * The fetcher never throws: any failure (no photo, gramjs error, oversize
- * buffer) returns `null` so callers can store the result without
- * guarding. The 200 KB cap is defensive — small profile photos are
- * typically <30 KB and a sudden jump would suggest a wrong-size variant
- * was returned.
- */
+// Downloads the chat photo (no public URL) as a data: URL. Never throws — any failure returns null.
+// 200 KB cap is defensive: real thumbnails are <30 KB, so a jump implies a wrong-size variant.
 import type { TelegramClient } from 'telegram';
 import type { Logger } from '../lib/logger.js';
 
@@ -20,7 +7,6 @@ export type ProfilePhotoFetcher = (chatId: string) => Promise<string | null>;
 
 const MAX_PHOTO_BYTES = 200 * 1024;
 
-// Subset of `TelegramClient` we depend on so tests can pass a stub.
 export interface ProfilePhotoClient {
   getEntity: TelegramClient['getEntity'];
   downloadProfilePhoto: TelegramClient['downloadProfilePhoto'];
@@ -31,9 +17,7 @@ export function createProfilePhotoFetcher(
   logger: Logger,
 ): ProfilePhotoFetcher {
   return async (chatId) => {
-    // gramjs's `getEntity` is overloaded (single id → Entity, array → Entity[]);
-    // TS resolves the alias to the array form, so we widen to `unknown` here
-    // and let `downloadProfilePhoto`'s `EntityLike` signature accept it.
+    // Widen to unknown: the overloaded getEntity alias resolves to the array form.
     let entity: unknown;
     try {
       entity = await client.getEntity(chatId);
@@ -52,8 +36,7 @@ export function createProfilePhotoFetcher(
       return null;
     }
     if (!buf || typeof buf === 'string' || buf.byteLength === 0) {
-      // gramjs returns an empty Buffer (or nothing) when the entity has
-      // no profile photo — not an error condition, just a null result.
+      // Empty buffer = no profile photo, not an error.
       return null;
     }
     if (buf.byteLength > MAX_PHOTO_BYTES) {
diff --git a/apps/server/src/tg/subscriptions.ts b/apps/server/src/tg/subscriptions.ts
index cb2ef00..5cbc79c 100644
--- a/apps/server/src/tg/subscriptions.ts
+++ b/apps/server/src/tg/subscriptions.ts
@@ -4,44 +4,20 @@ import type { Db } from '../db/client.js';
 import { destinations, subscriptions } from '../db/schema.js';
 import type { Logger } from '../lib/logger.js';
 
-// Minimal surface of TelegramClient we depend on, so tests can pass a stub.
-// `getDialogs` is included so the cache-prime step can hit the same path
-// `getEntity` does, just for every dialog at once.
 export interface TelegramEntityClient {
   getEntity: TelegramClient['getEntity'];
   getDialogs: TelegramClient['getDialogs'];
 }
 
-/**
- * Warm gramjs's per-session entity cache for every chat we'll talk to.
- *
- * Both source and destination chats need a valid `access_hash` in the cache
- * before `forwardMessages` will accept them as `InputPeer`. A fresh
- * `StringSession` (or one rebuilt after a long disconnect) doesn't carry
- * those — the first reference to an unseen chat would fail with
- * `PEER_ID_INVALID`/`CHANNEL_INVALID` until something else (a manual
- * `getEntity`, `getDialogs`, etc.) populates the cache.
- *
- * We make a single `getDialogs` call up front so every chat the userbot is
- * already a member of lands in the cache in one round-trip. The per-target
- * `getEntity` loop afterwards then almost always hits the cache, and the
- * tail of channels we're a member of but haven't dialoged with recently
- * still fall back to the real RPC — but at least the common case (every
- * subscribed source + destination) is primed.
- *
- * Resolves are sequential rather than `Promise.all` because parallel
- * `resolveUsername`/`getFullChannel` calls scale linearly with the number
- * of subscriptions and can easily trip Telegram's per-method rate limit on
- * boot. Boot is fine to take a few extra seconds; a flood-wait isn't.
- */
+// Warm gramjs's entity cache (one getDialogs + a getEntity loop) so forwardMessages has the access_hash
+// each chat needs as an InputPeer; without it the first reference fails PEER_ID_INVALID/CHANNEL_INVALID.
+// Resolves are sequential, not Promise.all, to avoid tripping Telegram's per-method rate limit on boot.
 export async function resolveSubscriptionsOnStartup(
   client: TelegramEntityClient,
   db: Db,
   logger: Logger,
 ): Promise<void> {
-  // Prime the entity cache. A failure here just means the per-target loop
-  // below will pay the per-call resolve cost (and may fail loudly if the
-  // chat genuinely isn't in cache); it's never fatal.
+  // Never fatal: on failure the per-target loop below just pays the per-call resolve cost.
   try {
     await client.getDialogs({ limit: 200 });
     logger.debug('warmed entity cache via getDialogs');
@@ -60,9 +36,7 @@ export async function resolveSubscriptionsOnStartup(
     .where(eq(subscriptions.enabled, true))
     .all();
 
-  // Dedupe — multiple subscriptions can share a destination, and a single
-  // chat could in principle appear as both source and destination. Each
-  // chat only needs to be warmed once per boot.
+  // Dedupe: a chat shared across subscriptions (or as both source and destination) is warmed once.
   const seen = new Set<string>();
   const targets: Array<{ chatId: string; role: 'source' | 'destination'; subscriptionId: number }> =
     [];
diff --git a/apps/web/src/api/authApi.ts b/apps/web/src/api/authApi.ts
index aacb7f3..32aa1b2 100644
--- a/apps/web/src/api/authApi.ts
+++ b/apps/web/src/api/authApi.ts
@@ -18,10 +18,7 @@ export async function login(password: string): Promise<LoginResponse> {
   return loginResponseSchema.parse(res);
 }
 
-/**
- * Sign in with a Telegram Mini App `initData` payload. `silent401` suppresses
- * the global redirect so the LoginPage can fall back to the password form.
- */
+// silent401 suppresses the global redirect so LoginPage can fall back to the password form.
 export async function loginWithTelegram(initData: string): Promise<LoginResponse> {
   const body = telegramAuthRequestSchema.parse({ initData });
   const res = await apiFetch<unknown, typeof body>('/api/auth/telegram', {
diff --git a/apps/web/src/api/client.ts b/apps/web/src/api/client.ts
index 481bdd3..7c57265 100644
--- a/apps/web/src/api/client.ts
+++ b/apps/web/src/api/client.ts
@@ -1,14 +1,4 @@
-/**
- * Tiny fetch wrapper for the JSON API.
- *
- * - Always sends the session cookie (`credentials: 'include'`).
- * - Parses JSON responses and returns the typed body, or throws an
- *   `ApiError` carrying the parsed `ErrorResponse` envelope.
- * - On 401 from any authed call, redirects to /login. The redirect is
- *   global (location.assign) so React Router doesn't have to be in scope.
- *   We skip the redirect for the auth routes themselves so the LoginPage
- *   can show its own error message.
- */
+// JSON fetch wrapper. On 401 from a non-auth route it does a global location.assign('/login') redirect.
 import { errorResponseSchema, type ErrorResponse } from '@tg-feed/shared';
 
 export class ApiError extends Error {
@@ -35,7 +25,7 @@ export class UnauthorizedError extends ApiError {
 
 export interface RequestInitJson<TBody> extends Omit<RequestInit, 'body'> {
   body?: TBody;
-  /** When true, suppress the global 401 → /login redirect. Use for auth routes. */
+  /** Suppress the global 401 → /login redirect. */
   silent401?: boolean;
 }
 
@@ -101,7 +91,6 @@ async function safeParseError(res: Response): Promise<ErrorResponse | undefined>
   }
 }
 
-/** Best-effort user-facing message for an API call failure. */
 export function apiErrorMessage(err: unknown, fallback: string): string {
   if (err instanceof ApiError && err.body?.error.message) return err.body.error.message;
   if (err instanceof Error && err.message) return err.message;
diff --git a/apps/web/src/components/domain/ActivityRow.tsx b/apps/web/src/components/domain/ActivityRow.tsx
index bd7ff0f..45a1223 100644
--- a/apps/web/src/components/domain/ActivityRow.tsx
+++ b/apps/web/src/components/domain/ActivityRow.tsx
@@ -7,34 +7,21 @@ import { useNowTick } from '@/lib/useNowTick';
 import { StatusBadge } from './StatusBadge';
 
 export interface ActivityEvent {
-  /** Stable id for keying — DB row id (`db:<id>`) or live event composite (`live:<sub>:<msg>:<type>`). */
+  // `db:<id>` or live composite `live:<sub>:<msg>:<type>`.
   id: string;
   kind: ForwardLogStatus;
   subscriptionId: number | null;
   subscriptionTitle: string | null;
   sourceHandle: string | null;
   destinationLabel: string | null;
-  /** Receive time (ms epoch) — used to compute relative `ago`. */
-  occurredAt: number;
+  occurredAt: number; // ms epoch
   reasons?: string[];
-  /** FloodWait seconds, when status='flood_wait'. */
   seconds?: number;
-  /** Error string when status='failed'. */
   error?: string | null;
-  /** Album: number of messages forwarded (>1 = album). */
-  destMessageCount?: number;
-  /** Set true on a freshly-arrived live event for the flash animation. */
+  destMessageCount?: number; // >1 = album
   isNew?: boolean;
-  /**
-   * `forward_log` row id for fetching the raw JSON payload. Set on hydrated
-   * rows and on live events whose SSE frame carried `forwardLogIds`.
-   */
   forwardLogId?: number;
-  /**
-   * Whether the row has a stored raw payload — drives visibility of the
-   * "{}" button. Live events default to `true` since capture happens
-   * before the SSE emit.
-   */
+  // Live events default true: capture precedes the SSE emit.
   hasRawMessage?: boolean;
 }
 
@@ -128,9 +115,7 @@ function RelativeTime({ occurredAt }: RelativeTimeProps) {
 }
 
 interface ParsedReason {
-  /** Library filter name when present (the part between `library:` and the next `:`). */
   library: string | null;
-  /** The remainder — typically `<ruleType>: <reason>`. */
   text: string;
 }
 
diff --git a/apps/web/src/components/domain/DestinationOption.tsx b/apps/web/src/components/domain/DestinationOption.tsx
index 714603e..7bc7917 100644
--- a/apps/web/src/components/domain/DestinationOption.tsx
+++ b/apps/web/src/components/domain/DestinationOption.tsx
@@ -4,12 +4,6 @@ import type { DestinationDto } from '@tg-feed/shared';
 import { cn } from '@/lib/cn';
 import { EntityIcon } from '@/components/domain/EntityIcon';
 
-/**
- * Selectable destination radio, shared by the subscription edit sheet and the
- * quick destination-picker sheet. The secondary line carries the chat id, the
- * forum topic (when set — this is what distinguishes two destinations that
- * point at the same forum but different topics), and the note.
- */
 export interface DestinationOptionProps {
   destination: DestinationDto;
   selected: boolean;
diff --git a/apps/web/src/components/domain/EntityIcon.tsx b/apps/web/src/components/domain/EntityIcon.tsx
index 4327ac2..497f842 100644
--- a/apps/web/src/components/domain/EntityIcon.tsx
+++ b/apps/web/src/components/domain/EntityIcon.tsx
@@ -16,18 +16,10 @@ export type EntityIconSize = 'md' | 'sm';
 export type EntityIconVariant = 'default' | 'active';
 
 export interface EntityIconProps {
-  /**
-   * Base64 data URL for the channel/chat profile photo, or null when not
-   * yet fetched. When null, the lucide fallback icon is rendered instead.
-   */
   iconDataUrl: string | null;
   fallback: EntityIconFallback;
   size?: EntityIconSize;
-  /**
-   * `active` flips the surface-2 / muted-text container to accent colors
-   * (used by SubRow when a subscription is expanded). Only applied to the
-   * fallback path — when a photo is present it fills the container.
-   */
+  // `active` paints the fallback container with accent colors; no effect when a photo is present.
   variant?: EntityIconVariant;
   className?: string;
 }
diff --git a/apps/web/src/components/domain/FilterRow.tsx b/apps/web/src/components/domain/FilterRow.tsx
index ea34779..1233cad 100644
--- a/apps/web/src/components/domain/FilterRow.tsx
+++ b/apps/web/src/components/domain/FilterRow.tsx
@@ -11,13 +11,11 @@ import { Toggle } from '@/components/settings/primitives';
 
 export interface FilterRowProps {
   filter: FilterLike & { id: number; enabled?: boolean; name?: string | null };
-  /** Render a "Library" badge + accent icon styling. */
   library?: boolean;
-  /** Toggle handler — only shown when set. */
   onToggle?: () => void;
   onEdit?: () => void;
   onDelete?: () => void;
-  /** Optional label override for the delete button (e.g. "Detach"). */
+  // Delete-button label override, e.g. "Detach".
   deleteLabel?: string;
 }
 
diff --git a/apps/web/src/components/domain/JsonViewSheet.tsx b/apps/web/src/components/domain/JsonViewSheet.tsx
index 8802e69..46e5003 100644
--- a/apps/web/src/components/domain/JsonViewSheet.tsx
+++ b/apps/web/src/components/domain/JsonViewSheet.tsx
@@ -1,18 +1,3 @@
-/**
- * Sheet wrapper that surfaces the raw gramjs JSON for a `forward_log` row.
- *
- * Triggered from `ActivityRow`'s "{}" button. The actual JSON isn't on the
- * list response — the Sheet fetches `GET /forward-log/:id/raw` via
- * `useForwardLogRaw` so we don't bloat hydration. Rendering goes through
- * `react-json-view-lite` for free collapsible nodes — essential for album
- * payloads (JSON array of N nested gramjs `Message` objects).
- *
- * Theming: the library ships its own CSS module classes (which carry the
- * expand/collapse glyphs as `::after` content), and exposes the per-token
- * class names via `defaultStyles`. We spread those defaults and append our
- * own Tailwind colour tokens with `!important` so the palette follows our
- * oklch CSS variables (dark + light theme are handled automatically).
- */
 import { useEffect, useMemo, useState } from 'react';
 import { AlertTriangle, Check, Copy } from 'lucide-react';
 import { JsonView, defaultStyles } from 'react-json-view-lite';
@@ -28,47 +13,25 @@ interface JsonViewSheetProps {
   onOpenChange: (open: boolean) => void;
 }
 
-/**
- * Compose a class string for one of the library's per-token style slots.
- * Keeps the library's structural class (margins, expand-glyph `::after`,
- * etc.) and stacks our coloured token with `!` so Tailwind wins regardless
- * of stylesheet order.
- */
+// Keep the library's structural class, stack our coloured token with `!` so Tailwind wins regardless of stylesheet order.
 function withTone(libraryClass: string, ...tones: string[]): string {
   return [libraryClass, ...tones].filter(Boolean).join(' ');
 }
 
-/**
- * Expand only the root and its immediate children by default — anything
- * deeper stays collapsed behind a `{...}` placeholder. Albums (root is an
- * array of `Message` objects) then surface each member's existence on first
- * paint, but keep their internals folded so the panel doesn't dump
- * hundreds of lines on open. Single-message payloads similarly show the
- * top-level fields but collapse nested objects like `media`, `fwdFrom`.
- *
- * `level === 0` is the root call; children increment from there, so
- * `level < 2` covers root + first nesting level.
- */
+// Root + immediate children only; keeps album payloads from dumping hundreds of lines on open.
 const expandFirstLevelOnly = (level: number): boolean => level < 2;
 
 const jsonViewStyles = {
   ...defaultStyles,
-  // Containers don't need recolouring — they inherit from <pre>.
   container: withTone(defaultStyles.container, 'bg-transparent'),
-  // Keys (object field names).
   label: withTone(defaultStyles.label, '!text-accent'),
   clickableLabel: withTone(defaultStyles.clickableLabel, '!text-accent'),
-  // Value types.
   stringValue: withTone(defaultStyles.stringValue, '!text-success'),
   numberValue: withTone(defaultStyles.numberValue, '!text-warning'),
-  // true / false / null share the danger tone so they stand out from
-  // strings and numbers when skimming a deep payload.
   booleanValue: withTone(defaultStyles.booleanValue, '!text-danger'),
   nullValue: withTone(defaultStyles.nullValue, '!text-danger'),
   undefinedValue: withTone(defaultStyles.undefinedValue, '!text-text-muted', 'italic'),
   otherValue: withTone(defaultStyles.otherValue, '!text-text-muted'),
-  // Structural marks (commas, braces, the "..." collapsed indicator, and
-  // the expand/collapse triangles) all share the muted tone.
   punctuation: withTone(defaultStyles.punctuation, '!text-text-muted'),
   expandIcon: withTone(defaultStyles.expandIcon, '!text-text-muted'),
   collapseIcon: withTone(defaultStyles.collapseIcon, '!text-text-muted'),
@@ -86,7 +49,6 @@ export function JsonViewSheet({ open, forwardLogId, onOpenChange }: JsonViewShee
   }, [copied]);
 
   const raw = query.data?.rawMessage ?? null;
-  // JSON.stringify of potentially-large album payloads (array of gramjs Messages).
   const formatted = useMemo(() => (raw !== null ? JSON.stringify(raw, null, 2) : null), [raw]);
 
   const onCopy = async () => {
@@ -95,8 +57,7 @@ export function JsonViewSheet({ open, forwardLogId, onOpenChange }: JsonViewShee
       await navigator.clipboard.writeText(formatted);
       setCopied(true);
     } catch {
-      // Clipboard API can fail in non-secure contexts — silently ignore;
-      // the user can still select + copy from the rendered tree by hand.
+      // Clipboard API can fail in non-secure contexts; user can still select + copy by hand.
     }
   };
 
@@ -138,8 +99,7 @@ export function JsonViewSheet({ open, forwardLogId, onOpenChange }: JsonViewShee
           />
         </div>
       ) : raw !== null ? (
-        // Edge case: a stored primitive (string/number/null wrapper). The
-        // library only renders objects/arrays — fall back to plain text.
+        // Stored primitive: the library only renders objects/arrays, so fall back to plain text.
         <pre className="font-mono text-[11px] leading-[1.5] text-text whitespace-pre-wrap break-all">
           {JSON.stringify(raw, null, 2)}
         </pre>
diff --git a/apps/web/src/components/domain/Logo.tsx b/apps/web/src/components/domain/Logo.tsx
index cb3f6ac..48af098 100644
--- a/apps/web/src/components/domain/Logo.tsx
+++ b/apps/web/src/components/domain/Logo.tsx
@@ -2,9 +2,6 @@ import type { ReactNode } from 'react';
 import type { LucideIcon } from 'lucide-react';
 import { cn } from '@/lib/cn';
 
-/**
- * Logo glyph — the design's hand-rolled SVG path. Sized by parent.
- */
 export interface LogoProps {
   size?: number;
   className?: string;
@@ -65,7 +62,6 @@ export function LogoBadge({ size = 16, className }: LogoBadgeProps) {
   );
 }
 
-/** Same badge frame as the brand logo, but renders an arbitrary lucide icon. */
 export interface IconBadgeProps {
   icon: LucideIcon;
   size?: number;
diff --git a/apps/web/src/components/domain/RuleForm.tsx b/apps/web/src/components/domain/RuleForm.tsx
index e2dd1c0..91e8b11 100644
--- a/apps/web/src/components/domain/RuleForm.tsx
+++ b/apps/web/src/components/domain/RuleForm.tsx
@@ -1,11 +1,3 @@
-/**
- * Per-rule param form. Matches the design's RuleForm — one input set per
- * rule type. Renders into the FilterSheet below the rule header card.
- *
- * The form is uncontrolled-ish: it reads + writes a single `params` object
- * whose shape is the rule's param schema. The parent owns the params
- * state. Validation happens at submit time via the shared zod schema.
- */
 import { X } from 'lucide-react';
 import { type KeyboardEvent } from 'react';
 import { filterRuleDefaultParams, type FilterMode, type FilterRuleType } from '@tg-feed/shared';
@@ -17,14 +9,9 @@ interface RuleFormProps {
   type: FilterRuleType;
   params: Record<string, unknown>;
   setParams: (next: Record<string, unknown>) => void;
-  /**
-   * `mode` toggle — shown when both `mode` and `setMode` are provided. When
-   * absent, callers (older flows that haven't been updated) get the legacy
-   * include-only behavior implicitly via the server default.
-   */
+  // Shown only with setMode; else server default (include-only) applies.
   mode?: FilterMode;
   setMode?: (next: FilterMode) => void;
-  /** Library filters add a Name field at the top of the form. */
   showName?: boolean;
   name?: string;
   setName?: (next: string) => void;
@@ -128,8 +115,7 @@ export function RuleForm({
             { v: true, l: 'Message has media' },
             { v: false, l: 'Message has NO media' },
           ].map((o) => {
-            // params.required: true=must have, false=must NOT have. Treat
-            // undefined as the default (true).
+            // undefined defaults to required (has media).
             const current = params.required !== false;
             const isThis = current === o.v;
             return (
diff --git a/apps/web/src/components/domain/SubRow.tsx b/apps/web/src/components/domain/SubRow.tsx
index 915cdfa..e498e25 100644
--- a/apps/web/src/components/domain/SubRow.tsx
+++ b/apps/web/src/components/domain/SubRow.tsx
@@ -102,10 +102,7 @@ interface NoForwardsBadgeProps {
 }
 
 function NoForwardsBadge({ at }: NoForwardsBadgeProps) {
-  // Telegram returns CHAT_FORWARDS_RESTRICTED when the source channel has
-  // "Restrict Saving Content" enabled. The forwarder stamps this timestamp;
-  // it stays set until a forward succeeds again. Surfacing it inline tells
-  // the operator their messages aren't reaching the destination.
+  // Set on CHAT_FORWARDS_RESTRICTED; cleared when a forward next succeeds.
   return (
     <span
       className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded text-[10.5px] font-medium bg-warning-soft text-warning border border-warning/30"
@@ -130,10 +127,7 @@ function NoDestinationBadge() {
 }
 
 function NoAccessBadge() {
-  // Set when the userbot couldn't auto-join on subscription create or when
-  // the daily access sweep found `getEntity` failing for this source. Both
-  // mean we won't see new messages from this channel until the operator
-  // re-joins it from a Telegram client.
+  // Userbot not a member: no new messages until it re-joins.
   return (
     <span
       className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded text-[10.5px] font-medium bg-danger-soft text-danger border border-danger/30"
diff --git a/apps/web/src/components/filters/FilterSheetController.tsx b/apps/web/src/components/filters/FilterSheetController.tsx
index 9a99af7..d52c61e 100644
--- a/apps/web/src/components/filters/FilterSheetController.tsx
+++ b/apps/web/src/components/filters/FilterSheetController.tsx
@@ -46,9 +46,7 @@ export function FilterSheetController({
         );
       } else {
         createLibMut.mutate(
-          // The discriminated-union schema is satisfied at runtime because the
-          // server zod validates the same shape; we cast through the same wire
-          // shape here.
+          // Cast safe: server zod validates the same discriminated-union shape.
           {
             name: data.name ?? '',
             ruleType: data.ruleType,
diff --git a/apps/web/src/components/layout/RequireAuth.tsx b/apps/web/src/components/layout/RequireAuth.tsx
index deeab85..d9376f5 100644
--- a/apps/web/src/components/layout/RequireAuth.tsx
+++ b/apps/web/src/components/layout/RequireAuth.tsx
@@ -31,10 +31,8 @@ export function RequireAuth({ children }: RequireAuthProps) {
   }
 
   if (me.isError) {
-    // 401 → redirecting to /login via the effect above; render nothing mid-redirect.
     if (isUnauthorized) return null;
-    // Any other error (network/5xx): `/me` has retry:false + staleTime:Infinity,
-    // so nothing recovers on its own — offer a manual retry instead of a blank screen.
+    // /me won't recover on its own (retry:false + staleTime:Infinity), so offer a manual retry.
     return (
       <div className="grid place-items-center min-h-dvh px-6 text-center">
         <div className="flex flex-col items-center gap-3 text-text-muted">
diff --git a/apps/web/src/components/settings/AppearanceSection.tsx b/apps/web/src/components/settings/AppearanceSection.tsx
index c6eb91b..f48c19f 100644
--- a/apps/web/src/components/settings/AppearanceSection.tsx
+++ b/apps/web/src/components/settings/AppearanceSection.tsx
@@ -1,7 +1,4 @@
-/**
- * Settings → Appearance card. Theme preference (system / light / dark);
- * applies instantly, so there's no Save / Reset footer.
- */
+// Theme applies instantly, so there's no Save / Reset footer.
 import { Monitor, Moon, Palette, Sun } from 'lucide-react';
 import { useThemeContext } from '@/lib/ThemeProvider';
 import { type ThemePreference } from '@/lib/useTheme';
diff --git a/apps/web/src/components/settings/BotSettingsCard.tsx b/apps/web/src/components/settings/BotSettingsCard.tsx
index 12d7708..f56841b 100644
--- a/apps/web/src/components/settings/BotSettingsCard.tsx
+++ b/apps/web/src/components/settings/BotSettingsCard.tsx
@@ -1,27 +1,11 @@
-/**
- * Settings → Bot card.
- *
- * One self-contained card holding every bot-related setting — connection
- * params (token / admins / public URL, stored DB-over-env) and the stats
- * digest schedule — behind a single status header and one Save / Reset.
- *
- * The two halves persist to different endpoints (bot config → /api/config/bot,
- * digest → /api/settings); Save fires only the dirty halves and reports one
- * outcome. "Reset all to .env" clears the DB bot-config row. The digest's time
- * zone is captured from the browser on save (no picker), matching how the
- * scheduler interprets it.
- *
- * Draft state lives in `useBotSettingsDraft`; the connection and digest fields
- * render through the `bot/` sub-components. This card keeps the save
- * orchestration (the two-half Promise.allSettled write + per-half reporting)
- * and the DB-reset / key-mismatch affordances.
- */
+// Bot config + digest persist to different endpoints; Save fires only the dirty halves and reports per-half.
 import { Check, KeyRound, Power } from 'lucide-react';
 import type { UpdateBotConfigRequest, UpdateSettingsRequest } from '@tg-feed/shared';
 import { Button } from '@/components/ui/button';
 import { Spinner } from '@/components/ui/spinner';
 import { useToast } from '@/components/ui/toast';
 import { apiErrorMessage } from '@/api/client';
+import { getTelegramUserId } from '@/lib/telegram';
 import { useBotConfig, useDeleteBotConfig, useUpdateBotConfig } from '@/hooks/useBotConfig';
 import { useSettings, useUpdateSettings } from '@/hooks/useSettings';
 import { CardFooter, CardHeader, SettingsCard, StatusPill } from './primitives';
@@ -96,8 +80,7 @@ export function BotSettingsCard() {
   const dirty = botDirty || digestDirty;
   const busy = updateBot.isPending || updateSettings.isPending || delMut.isPending;
   const keyMissingForToken = tokenDirty && !data.encryptionKeyConfigured;
-  // Each half gates on its own validity, so an invalid Public URL (a bot
-  // field) can't block saving an unrelated digest edit, and vice-versa.
+  // Each half gates on its own validity, so an invalid URL can't block an unrelated digest edit.
   const botSavable = botDirty && urlValid && !keyMissingForToken;
   const digestSavable = digestDirty;
   const canSave = !busy && (botSavable || digestSavable);
@@ -127,8 +110,6 @@ export function BotSettingsCard() {
   );
 
   const save = async () => {
-    // Run the two halves independently so a failure in one doesn't hide a
-    // success in the other, and report per-half so the user knows what landed.
     const jobs: Array<{ half: 'bot' | 'digest'; run: () => Promise<unknown> }> = [];
     if (botSavable) {
       const body: UpdateBotConfigRequest = {};
@@ -150,8 +131,7 @@ export function BotSettingsCard() {
 
     const results = await Promise.allSettled(jobs.map((j) => j.run()));
     const botOk = results.every((r, i) => jobs[i]?.half !== 'bot' || r.status === 'fulfilled');
-    // Only clear the (write-only) token field once the bot write actually
-    // landed, so a failed save doesn't silently drop the typed token.
+    // Clear the write-only token only once the write landed, so a failure doesn't drop it silently.
     if (botOk && tokenDirty) setTokenDraft('');
 
     const failed = jobs.filter((_, i) => results[i]?.status === 'rejected').map((j) => j.half);
@@ -212,6 +192,7 @@ export function BotSettingsCard() {
           admins={admins}
           onRemoveAdmin={(id) => setAdmins((xs) => xs.filter((x) => x.id !== id))}
           onAddAdmin={(admin) => setAdmins((xs) => [...xs, admin])}
+          currentTelegramUserId={getTelegramUserId()}
           urlDraft={urlDraft}
           onUrlChange={setUrlDraft}
           urlValid={urlValid}
diff --git a/apps/web/src/components/settings/DataSection.tsx b/apps/web/src/components/settings/DataSection.tsx
index b893320..f063dd0 100644
--- a/apps/web/src/components/settings/DataSection.tsx
+++ b/apps/web/src/components/settings/DataSection.tsx
@@ -1,16 +1,4 @@
-/**
- * Settings → Data section.
- *
- * Two cards:
- *   1. Import / Export — two buttons that open the `ExportSheet` / `ImportSheet`
- *      flows.
- *   2. Danger zone — a single button that opens the `WipeSheet` flow.
- *
- * Each flow lives in its own file under `./data/`; this entry just renders the
- * cards and mounts the sheets. The whole feature is offline-safe — no Telegram
- * dependencies. Imports never call joinChannel; the access monitor's sweep
- * refreshes status afterwards.
- */
+// Offline-safe: imports never call joinChannel; the access monitor's sweep refreshes status afterwards.
 import { useState } from 'react';
 import { AlertTriangle, Database, Download, Trash, Upload } from 'lucide-react';
 import { Button } from '@/components/ui/button';
diff --git a/apps/web/src/components/settings/ForwardingSection.tsx b/apps/web/src/components/settings/ForwardingSection.tsx
index c695461..ea093a8 100644
--- a/apps/web/src/components/settings/ForwardingSection.tsx
+++ b/apps/web/src/components/settings/ForwardingSection.tsx
@@ -1,11 +1,3 @@
-/**
- * Settings → Forwarding card.
- *
- * Global pipeline knobs stored in the 'global' app_settings row: the inter-send
- * throttle delay and the album-debounce window. Both are number input + range
- * slider; sub-spam-threshold delays surface a warning. Saved together via one
- * Reset / Save, sending only the changed knob.
- */
 import { useEffect, useState } from 'react';
 import { AlertTriangle, Check, Timer } from 'lucide-react';
 import { Button } from '@/components/ui/button';
@@ -48,8 +40,7 @@ export function ForwardingSection() {
   const delayDirty = draft !== data.delayMs;
   const albumDirty = albumDraft !== data.albumDebounceMs;
   const dirty = delayDirty || albumDirty;
-  // A cleared field coerces to 0; block saving a non-positive value (the
-  // server's .positive() schema rejects it) and flag the field instead.
+  // Cleared field coerces to 0; block non-positive (server's .positive() rejects it) and flag instead.
   const delayValid = Number.isInteger(draft) && draft > 0;
   const albumValid = Number.isInteger(albumDraft) && albumDraft > 0;
   const canSave = dirty && delayValid && albumValid && !updateMut.isPending;
diff --git a/apps/web/src/components/settings/TelegramAccountSection.tsx b/apps/web/src/components/settings/TelegramAccountSection.tsx
index 76f58b3..2019ace 100644
--- a/apps/web/src/components/settings/TelegramAccountSection.tsx
+++ b/apps/web/src/components/settings/TelegramAccountSection.tsx
@@ -1,11 +1,3 @@
-/**
- * Settings → Telegram Account Connection card.
- *
- * The userbot (gramjs) account that does the forwarding. A status pill in the
- * header reflects the live Telegram connection; the body + footer switch on
- * state: sign in (phone-code or paste-session), sign out, env-fallback upgrade,
- * or a key-fingerprint-mismatch warning. Sign-in is gated on an encryption key.
- */
 import { useState } from 'react';
 import { AlertTriangle, KeyRound, type LucideIcon, LogIn, LogOut, Plug, User } from 'lucide-react';
 import { Button } from '@/components/ui/button';
@@ -42,8 +34,7 @@ export function TelegramAccountSection() {
       onError: (err) => toast.error(apiErrorMessage(err, 'Sign out failed')),
     });
 
-  // Pick the status pill + body. Order matters: a key mismatch is the most
-  // actionable signal even when the env fallback keeps us connected.
+  // Order matters: key mismatch wins even when the env fallback keeps us connected.
   let pill = <StatusPill tone="down">offline</StatusPill>;
   let body: React.ReactNode;
   let footer: React.ReactNode;
@@ -104,7 +95,6 @@ export function TelegramAccountSection() {
       />
     );
   } else {
-    // Disconnected (state='disconnected' or status missing).
     body = (
       <Banner icon={AlertTriangle} title="Telegram disconnected">
         {tg?.reason ?? 'Telegram client is not available.'} Subscribing and forwarding are
diff --git a/apps/web/src/components/settings/TelegramLoginSheet.tsx b/apps/web/src/components/settings/TelegramLoginSheet.tsx
index 73c7441..ae360df 100644
--- a/apps/web/src/components/settings/TelegramLoginSheet.tsx
+++ b/apps/web/src/components/settings/TelegramLoginSheet.tsx
@@ -1,16 +1,4 @@
-/**
- * Multi-step Telegram sign-in wizard rendered inside a Sheet.
- *
- * Steps:
- *   mode → phone → code → ?2fa → done
- *               ↘ raw         ↗
- *
- * The `sessionId` returned from /login/start is held in component state and
- * passed to subsequent /verify and /password calls so the server can keep
- * the temp client alive across HTTP boundaries. Closing the sheet (or
- * clicking Cancel) fires /login/cancel as a best-effort tear-down so the
- * server doesn't have to wait for the TTL GC.
- */
+// sessionId threads through /verify and /password so the server keeps the temp client alive across HTTP calls; Cancel fires /login/cancel for best-effort teardown.
 import { useEffect, useMemo, useRef, useState } from 'react';
 import {
   AlertTriangle,
@@ -81,7 +69,7 @@ export function TelegramLoginSheet({ open, onClose }: TelegramLoginSheetProps) {
   const isPending =
     start.isPending || verifyCode.isPending || verifyPassword.isPending || loginRaw.isPending;
 
-  // Reset internal state when reopening so a stale step doesn't flash.
+  // Reset on reopen so a stale step doesn't flash.
   useEffect(() => {
     if (open) {
       setState(INITIAL);
@@ -324,8 +312,6 @@ interface PrimaryActionProps {
   onClick: () => void;
 }
 
-// Per-step primary-button config in one place: label (idle/pending), which
-// FlowState field gates the button, and the minimum length to enable it.
 // Passwords aren't trimmed (spaces can be significant); the rest are.
 const STEP_ACTIONS: Record<
   Exclude<Step, 'mode' | 'done'>,
diff --git a/apps/web/src/components/settings/bot/AdminLookup.tsx b/apps/web/src/components/settings/bot/AdminLookup.tsx
index 17157f0..d90f166 100644
--- a/apps/web/src/components/settings/bot/AdminLookup.tsx
+++ b/apps/web/src/components/settings/bot/AdminLookup.tsx
@@ -1,9 +1,3 @@
-/**
- * Admin allowlist lookup: a debounced search that resolves a `@username` /
- * t.me link / numeric id to a Telegram user and offers it for adding to the
- * bot's admin set. Self-contained — owns its own query state and resolve
- * mutation; the resolved entry is handed back to the parent via `onAdd`.
- */
 import { useState } from 'react';
 import { Plus, Search } from 'lucide-react';
 import type { BotAdmin } from '@tg-feed/shared';
diff --git a/apps/web/src/components/settings/bot/ConnectionSection.tsx b/apps/web/src/components/settings/bot/ConnectionSection.tsx
index 3dcabf1..e617322 100644
--- a/apps/web/src/components/settings/bot/ConnectionSection.tsx
+++ b/apps/web/src/components/settings/bot/ConnectionSection.tsx
@@ -1,14 +1,9 @@
-/**
- * The "Connection" panel of the Bot settings card: bot token, admin allowlist
- * and public URL. Presentational — every draft value, setter and the busy flag
- * are owned by the card and passed in; this component only renders the fields
- * and wires the admin add/remove callbacks.
- */
 import { useMemo, type ReactNode } from 'react';
 import { User, X } from 'lucide-react';
 import type { BotAdmin, BotConfigInfo } from '@tg-feed/shared';
 import { Button } from '@/components/ui/button';
 import { Hint, Input } from '@/components/ui/input';
+import { cn } from '@/lib/cn';
 import { FieldHead, PanelSection } from '../primitives';
 import { AdminLookup } from './AdminLookup';
 import { adminLabel } from './utils';
@@ -21,6 +16,7 @@ export interface ConnectionSectionProps {
   admins: BotAdmin[];
   onRemoveAdmin: (id: string) => void;
   onAddAdmin: (admin: BotAdmin) => void;
+  currentTelegramUserId: string | null;
   urlDraft: string;
   onUrlChange: (value: string) => void;
   urlValid: boolean;
@@ -36,6 +32,7 @@ export function ConnectionSection({
   admins,
   onRemoveAdmin,
   onAddAdmin,
+  currentTelegramUserId,
   urlDraft,
   onUrlChange,
   urlValid,
@@ -45,7 +42,6 @@ export function ConnectionSection({
 
   return (
     <PanelSection label="Connection">
-      {/* Bot token */}
       <div>
         <FieldHead label="Bot token" source={data.tokenSource} />
         <Input
@@ -71,47 +67,58 @@ export function ConnectionSection({
         )}
       </div>
 
-      {/* Admins */}
       <div>
         <FieldHead label="Admins" source={data.adminsSource} />
         {admins.length === 0 ? (
           <p className="text-[12px] text-text-muted py-1">No admins yet — look one up below.</p>
         ) : (
           <div className="flex flex-col gap-1.5 mb-2">
-            {admins.map((a) => (
-              <div
-                key={a.id}
-                className="flex items-center gap-2.5 pl-3 pr-1.5 py-2 rounded-lg bg-surface-2 border border-border"
-              >
-                <span className="grid place-items-center w-[26px] h-[26px] rounded-[7px] bg-surface-3 text-text-2 flex-shrink-0">
-                  <User size={13} />
-                </span>
-                <div className="flex flex-col flex-1 min-w-0">
-                  <span className="font-mono text-[13px] font-medium truncate">
-                    {adminLabel(a)}
-                  </span>
-                  <span className="font-mono text-[10.5px] text-text-faint truncate">
-                    {a.displayName && a.username ? `@${a.username} · ${a.id}` : a.id}
+            {admins.map((a) => {
+              const isYou = currentTelegramUserId !== null && a.id === currentTelegramUserId;
+              return (
+                <div
+                  key={a.id}
+                  className={cn(
+                    'flex items-center gap-2.5 pl-3 pr-1.5 py-2 rounded-lg border',
+                    isYou ? 'bg-accent-soft border-accent/40' : 'bg-surface-2 border-border',
+                  )}
+                >
+                  <span className="grid place-items-center w-[26px] h-[26px] rounded-[7px] bg-surface-3 text-text-2 flex-shrink-0">
+                    <User size={13} />
                   </span>
+                  <div className="flex flex-col flex-1 min-w-0">
+                    <span className="flex items-center gap-1.5 min-w-0">
+                      <span className="font-mono text-[13px] font-medium truncate">
+                        {adminLabel(a)}
+                      </span>
+                      {isYou && (
+                        <span className="flex-shrink-0 inline-flex items-center rounded-full bg-accent px-2 py-0.5 text-[10.5px] font-semibold leading-none text-accent-fg">
+                          You
+                        </span>
+                      )}
+                    </span>
+                    <span className="font-mono text-[10.5px] text-text-faint truncate">
+                      {a.displayName && a.username ? `@${a.username} · ${a.id}` : a.id}
+                    </span>
+                  </div>
+                  <Button
+                    variant="ghost"
+                    size="icon-sm"
+                    aria-label={`Remove ${adminLabel(a)}`}
+                    disabled={busy}
+                    onClick={() => onRemoveAdmin(a.id)}
+                  >
+                    <X size={14} />
+                  </Button>
                 </div>
-                <Button
-                  variant="ghost"
-                  size="icon-sm"
-                  aria-label={`Remove ${adminLabel(a)}`}
-                  disabled={busy}
-                  onClick={() => onRemoveAdmin(a.id)}
-                >
-                  <X size={14} />
-                </Button>
-              </div>
-            ))}
+              );
+            })}
           </div>
         )}
         <AdminLookup existingIds={existingAdminIds} disabled={busy} onAdd={onAddAdmin} />
         <Hint>Look up a Telegram user to allow — @username, t.me link, or numeric id.</Hint>
       </div>
 
-      {/* Public URL */}
       <div>
         <FieldHead label="Public URL" source={data.publicUrlSource} />
         <Input
diff --git a/apps/web/src/components/settings/bot/DigestSection.tsx b/apps/web/src/components/settings/bot/DigestSection.tsx
index 346df4f..9ac0708 100644
--- a/apps/web/src/components/settings/bot/DigestSection.tsx
+++ b/apps/web/src/components/settings/bot/DigestSection.tsx
@@ -1,10 +1,3 @@
-/**
- * The "Stats digest" panel of the Bot settings card: an enable toggle plus an
- * inline-sentence schedule (frequency / day / time) and the captured browser
- * time zone. Presentational — drafts and setters are owned by the card. The
- * `botReady` flag drives the "add a token + admin first" warning; the time
- * zone is display-only (captured on save, no picker).
- */
 import { AlertTriangle } from 'lucide-react';
 import type { StatsDigestFrequency } from '@tg-feed/shared';
 import { Hint } from '@/components/ui/input';
@@ -36,7 +29,6 @@ export interface DigestSectionProps {
   time: string;
   onTimeChange: (next: string) => void;
   localTz: string;
-  /** A token + at least one admin are present, so the digest can be delivered. */
   botReady: boolean;
 }
 
diff --git a/apps/web/src/components/settings/bot/useBotSettingsDraft.ts b/apps/web/src/components/settings/bot/useBotSettingsDraft.ts
index d1acee5..b8a36ea 100644
--- a/apps/web/src/components/settings/bot/useBotSettingsDraft.ts
+++ b/apps/web/src/components/settings/bot/useBotSettingsDraft.ts
@@ -1,29 +1,15 @@
-/**
- * Owns the editable drafts behind the Bot settings card — both halves: the
- * bot-connection fields (token / admins / public URL) and the stats-digest
- * schedule. Seeds them from the server payloads and exposes a single
- * `seedFromServer` so the seeding effects and the Reset action share one field
- * list (no drift between "what gets seeded" and "what gets reset").
- *
- * Called unconditionally (before the card's loading/error guards), so the
- * server payloads may be undefined on the first renders; the seeding effects
- * tolerate that exactly as the inline versions did. Dirty derivation and save
- * orchestration stay in the card, next to the mutations they drive — this hook
- * only owns the draft values and their setters.
- */
+// Called before the card's loading/error guards, so server payloads may be undefined on first renders and the seeding effects tolerate that.
 import { useEffect, useMemo, useState, type Dispatch, type SetStateAction } from 'react';
 import type { BotAdmin, BotConfigInfo, SettingsDto, StatsDigestFrequency } from '@tg-feed/shared';
 import { localTimeZone } from './utils';
 
 export interface BotSettingsDraft {
-  // Bot-config drafts.
   tokenDraft: string;
   setTokenDraft: (value: string) => void;
   admins: BotAdmin[];
   setAdmins: Dispatch<SetStateAction<BotAdmin[]>>;
   urlDraft: string;
   setUrlDraft: (value: string) => void;
-  // Digest drafts.
   enabled: boolean;
   setEnabled: (value: boolean) => void;
   frequency: StatsDigestFrequency;
@@ -33,13 +19,9 @@ export interface BotSettingsDraft {
   time: string;
   setTime: (value: string) => void;
 
-  /** Browser time zone the digest time is read in; captured once. */
   localTz: string;
 
-  /**
-   * Re-seed every draft from the latest server payloads (used by Reset). A
-   * no-op until both payloads have loaded, matching the card's guards.
-   */
+  // No-op until both payloads have loaded, matching the card's guards.
   seedFromServer: () => void;
 }
 
@@ -49,18 +31,15 @@ export function useBotSettingsDraft(
 ): BotSettingsDraft {
   const localTz = useMemo(localTimeZone, []);
 
-  // Bot-config drafts.
   const [tokenDraft, setTokenDraft] = useState('');
   const [admins, setAdmins] = useState<BotAdmin[]>([]);
   const [urlDraft, setUrlDraft] = useState('');
-  // Digest drafts.
   const [enabled, setEnabled] = useState(false);
   const [frequency, setFrequency] = useState<StatsDigestFrequency>('daily');
   const [dayOfWeek, setDayOfWeek] = useState(1);
   const [time, setTime] = useState('09:00');
 
-  // Stable keys so the seeding effects only re-run when the underlying server
-  // values actually change (not on every cache reference swap).
+  // Stable keys so seeding re-runs on value changes, not every cache reference swap.
   const adminsJson = JSON.stringify(data?.admins ?? []);
   const urlKey = data?.publicUrl ?? '';
 
diff --git a/apps/web/src/components/settings/bot/utils.ts b/apps/web/src/components/settings/bot/utils.ts
index 0c4dc20..7ad9964 100644
--- a/apps/web/src/components/settings/bot/utils.ts
+++ b/apps/web/src/components/settings/bot/utils.ts
@@ -1,7 +1,3 @@
-/**
- * Small pure helpers shared across the Bot settings card and its sub-pieces
- * (the connection/digest sections, the draft hook, and the admin lookup).
- */
 import type { BotAdmin } from '@tg-feed/shared';
 
 export function isValidUrl(value: string): boolean {
diff --git a/apps/web/src/components/settings/data/ExportSheet.tsx b/apps/web/src/components/settings/data/ExportSheet.tsx
index 52688b9..09ab9d1 100644
--- a/apps/web/src/components/settings/data/ExportSheet.tsx
+++ b/apps/web/src/components/settings/data/ExportSheet.tsx
@@ -1,8 +1,3 @@
-/**
- * Export sheet — section checkboxes that trigger a JSON file download
- * (Blob + anchor click) of the selected sections. Versioned for forward /
- * backward compatibility via the shared `exportFileSchema`.
- */
 import { useState } from 'react';
 import { Download } from 'lucide-react';
 import { EXPORT_SECTIONS, type ExportSection } from '@tg-feed/shared';
diff --git a/apps/web/src/components/settings/data/ImportSheet.tsx b/apps/web/src/components/settings/data/ImportSheet.tsx
index 87c3e3d..b5a2f26 100644
--- a/apps/web/src/components/settings/data/ImportSheet.tsx
+++ b/apps/web/src/components/settings/data/ImportSheet.tsx
@@ -1,10 +1,3 @@
-/**
- * Import sheet — file picker that validates against the shared
- * `exportFileSchema`, shows a preview, and lets the user pick which sections
- * to apply plus a conflict strategy (skip / replace) before POSTing to
- * /api/system/import. Imports never touch Telegram; the access monitor's
- * sweep refreshes channel status afterwards.
- */
 import { useMemo, useRef, useState } from 'react';
 import { AlertTriangle, Check, Upload, X } from 'lucide-react';
 import {
diff --git a/apps/web/src/components/settings/data/WipeSheet.tsx b/apps/web/src/components/settings/data/WipeSheet.tsx
index 02ca1a7..232e4af 100644
--- a/apps/web/src/components/settings/data/WipeSheet.tsx
+++ b/apps/web/src/components/settings/data/WipeSheet.tsx
@@ -1,8 +1,3 @@
-/**
- * Wipe sheet — checkboxes per wipeable section, gated on a typed-in
- * confirmation phrase, then POSTs to /api/system/wipe. Destructive and
- * irreversible, so the confirm button stays disabled until the phrase matches.
- */
 import { useState } from 'react';
 import { Trash } from 'lucide-react';
 import { WIPE_SECTIONS, type WipeSection } from '@tg-feed/shared';
diff --git a/apps/web/src/components/settings/data/shared.ts b/apps/web/src/components/settings/data/shared.ts
index 0417947..ff22a45 100644
--- a/apps/web/src/components/settings/data/shared.ts
+++ b/apps/web/src/components/settings/data/shared.ts
@@ -1,9 +1,3 @@
-/**
- * Shared constants, types, and helpers for the Settings → Data sheets
- * (export / import / wipe). Kept in one module so the section labels and the
- * "which sections does this file carry" logic stay in a single place instead
- * of being re-derived in each sheet.
- */
 import { EXPORT_SECTIONS, type ExportFile, type ExportSection } from '@tg-feed/shared';
 
 export const SECTION_LABELS: Record<ExportSection, string> = {
@@ -29,16 +23,11 @@ export interface ParsedFile {
   fileName: string;
 }
 
-/**
- * Sections actually carried by an export file, in the canonical
- * `EXPORT_SECTIONS` order so checkbox lists and result rows render
- * consistently regardless of the file's key order.
- */
+// Present sections in canonical EXPORT_SECTIONS order, ignoring the file's key order.
 export function presentSections(file: ExportFile): ExportSection[] {
   return EXPORT_SECTIONS.filter((s) => file[s] != null);
 }
 
-/** Return a new Set with `value` toggled in/out — for checkbox selection state. */
 export function toggleInSet<T>(set: Set<T>, value: T): Set<T> {
   const next = new Set(set);
   if (next.has(value)) next.delete(value);
diff --git a/apps/web/src/components/settings/primitives.tsx b/apps/web/src/components/settings/primitives.tsx
index 5770a6c..9eca08c 100644
--- a/apps/web/src/components/settings/primitives.tsx
+++ b/apps/web/src/components/settings/primitives.tsx
@@ -1,12 +1,3 @@
-/**
- * Shared building blocks for the Settings page cards, ported from the design
- * direction (project/styles.css + screen-settings.jsx) onto our Tailwind
- * tokens. Every Settings panel is a self-titled card: a `CardHeader` (icon
- * badge + title + optional status pill / toggle), a body, and an optional
- * `CardFooter` (Reset / Save). Inside the body, `PanelSection` groups related
- * fields under an uppercase label, and `FieldHead` pairs a field label with a
- * `SourceBadge` (database vs .env).
- */
 import type { ReactNode } from 'react';
 import { ChevronDown, Lock, Zap } from 'lucide-react';
 import type { BotConfigSource } from '@tg-feed/shared';
@@ -36,7 +27,6 @@ export interface CardHeaderProps {
   right?: ReactNode;
 }
 
-/** Card header: icon badge + title on the left, an optional pill/toggle on the right. */
 export function CardHeader({ icon, title, right }: CardHeaderProps) {
   return (
     <div className="flex items-center justify-between gap-2.5 px-4 py-3 border-b border-border bg-bg-2">
@@ -56,7 +46,6 @@ export interface CardFooterProps {
   children: ReactNode;
 }
 
-/** Card footer on a tinted bar. `left` is pinned to the start (e.g. a danger reset). */
 export function CardFooter({ left, children }: CardFooterProps) {
   return (
     <div className="flex items-center justify-end gap-2 px-4 py-3 border-t border-border bg-bg-2">
@@ -72,7 +61,6 @@ export interface PanelSectionProps {
   children: ReactNode;
 }
 
-/** A labelled group within a card body; `right` sits opposite the label (e.g. a toggle). */
 export function PanelSection({ label, right, children }: PanelSectionProps) {
   return (
     <div className="flex flex-col gap-3.5">
@@ -92,7 +80,6 @@ export interface FieldHeadProps {
   source?: BotConfigSource | null;
 }
 
-/** Field label paired with its source badge. */
 export function FieldHead({ label, source }: FieldHeadProps) {
   return (
     <div className="flex items-baseline justify-between mb-1.5">
@@ -106,7 +93,6 @@ export interface SourceBadgeProps {
   source: BotConfigSource | null;
 }
 
-/** Small uppercase pill showing where a value resolves from: database / .env / not set. */
 export function SourceBadge({ source }: SourceBadgeProps) {
   if (!source) return <span className="text-[10.5px] text-text-faint">not set</span>;
   const isDb = source === 'db';
@@ -131,7 +117,6 @@ export interface ToggleProps {
   disabled?: boolean;
 }
 
-/** Accessible on/off switch matching the design's `.toggle`. */
 export function Toggle({ checked, onChange, label, disabled }: ToggleProps) {
   return (
     <button
@@ -178,7 +163,6 @@ export interface StatusPillProps {
   children: ReactNode;
 }
 
-/** Rounded status pill with a leading dot, matching the design's `.pill`. */
 export function StatusPill({ tone, children }: StatusPillProps) {
   return (
     <span
@@ -201,7 +185,6 @@ export interface InlineSelectProps<T extends string> {
   ariaLabel?: string;
 }
 
-/** Compact styled native <select> for the inline-sentence digest config. */
 export function InlineSelect<T extends string>({
   value,
   onChange,
diff --git a/apps/web/src/components/sheets/DestSheet.tsx b/apps/web/src/components/sheets/DestSheet.tsx
index 76e09b9..db84e24 100644
--- a/apps/web/src/components/sheets/DestSheet.tsx
+++ b/apps/web/src/components/sheets/DestSheet.tsx
@@ -8,19 +8,17 @@ import { ResolveCard } from '@/components/domain/ResolveCard';
 import { useForumTopics, useResolveDestination } from '@/hooks/useDestinations';
 import { useDebouncedResolve } from '@/hooks/useDebouncedResolve';
 
-// Telegram's General topic has the reserved top_msg_id 1. We represent it as
-// the null/no-topic choice so a forum's General and a normal chat share the
-// "no explicit topic" code path; the API's General entry is filtered out.
+// Telegram's General topic is the reserved top_msg_id 1; we map it to the null/no-topic choice.
 const GENERAL_TOPIC_ID = '1';
 
 export interface DestSheetSubmit {
   name: string;
-  /** Set when the resolver returned a chatId (any input form except not-yet-joined private invite). */
+  // null for a not-yet-joined private invite (only inviteHash set)
   chatId: string | null;
-  /** Set when the input was a `t.me/+HASH` link the userbot hasn't joined — server joins on add. */
+  // set for a t.me/+HASH link the userbot hasn't joined; server joins on add
   inviteHash: string | null;
   note?: string;
-  /** Selected forum topic, or null for the General topic / a non-forum chat. */
+  // null for the General topic or a non-forum chat
   topicId: string | null;
   topicTitle: string | null;
 }
@@ -38,12 +36,9 @@ export function DestSheet({ open, mode, initial, onClose, onSubmit, submitting }
   const isEdit = mode === 'edit';
   const [link, setLink] = useState('');
   const [name, setName] = useState('');
-  // Track manual edits so we can auto-fill from a resolved title without
-  // clobbering anything the user typed first.
+  // Tracks manual edits so the resolved-title auto-fill doesn't clobber user input.
   const [nameTouched, setNameTouched] = useState(false);
   const [note, setNote] = useState('');
-  // Selected forum topic; null == General / no topic. `topicTitle` is cached
-  // alongside so we can persist it without re-deriving from the topics list.
   const [topicId, setTopicId] = useState<string | null>(null);
   const [topicTitle, setTopicTitle] = useState<string | null>(null);
 
@@ -55,7 +50,6 @@ export function DestSheet({ open, mode, initial, onClose, onSubmit, submitting }
     error: resolveErrorRaw,
   } = useResolveDestination();
 
-  // Reset on open / mode change.
   useEffect(() => {
     if (!open) return;
     if (isEdit && initial) {
@@ -77,7 +71,6 @@ export function DestSheet({ open, mode, initial, onClose, onSubmit, submitting }
     }
   }, [open, initial, isEdit, resetResolve]);
 
-  // Debounce resolve in add mode.
   useDebouncedResolve({
     value: link,
     enabled: !isEdit,
@@ -96,17 +89,12 @@ export function DestSheet({ open, mode, initial, onClose, onSubmit, submitting }
   const resolving = !isEdit && resolvePending;
   const resolveError = !isEdit ? resolveErrorRaw : null;
 
-  // Topic picker. Fetch the chat's topics whenever we have a resolved (add
-  // mode) or stored (edit mode) chat id, and show the picker only when the
-  // lister reports a forum. Driving `isForum` off the lister — which calls
-  // channels.GetForumTopics — is authoritative, unlike the resolve-time
-  // `entity.forum` hint which gramjs doesn't reliably populate.
+  // isForum comes from the lister (channels.GetForumTopics), authoritative unlike gramjs's unreliable entity.forum hint.
   const topicChatId = isEdit ? (initial?.chatId ?? null) : (resolved?.chatId ?? null);
   const topicsQuery = useForumTopics(topicChatId, !!topicChatId);
   const isForum = topicsQuery.data?.isForum ?? false;
 
-  // Topics belong to a specific forum, so clear any stale pick when the
-  // resolved chat changes in add mode.
+  // Topics are forum-specific; clear a stale pick when the resolved chat changes.
   useEffect(() => {
     if (isEdit) return;
     setTopicId(null);
diff --git a/apps/web/src/components/sheets/DestinationPickerSheet.tsx b/apps/web/src/components/sheets/DestinationPickerSheet.tsx
index d3410ff..b6085dc 100644
--- a/apps/web/src/components/sheets/DestinationPickerSheet.tsx
+++ b/apps/web/src/components/sheets/DestinationPickerSheet.tsx
@@ -15,11 +15,7 @@ export interface DestinationPickerSheetProps {
   submitting?: boolean;
 }
 
-/**
- * Lightweight "change where this subscription forwards" picker, opened from the
- * Forwards-to card in the expanded subscription row. Just the destination list
- * — for the full edit (filters, etc.) the row still has its Edit button.
- */
+// Destination-only picker; the full edit (filters, etc.) lives behind the row's Edit button.
 export function DestinationPickerSheet({
   open,
   currentDestinationId,
diff --git a/apps/web/src/components/sheets/FilterSheet.tsx b/apps/web/src/components/sheets/FilterSheet.tsx
index 32788d3..7fbd414 100644
--- a/apps/web/src/components/sheets/FilterSheet.tsx
+++ b/apps/web/src/components/sheets/FilterSheet.tsx
@@ -1,14 +1,3 @@
-/**
- * Two-step filter creation/edit sheet.
- *
- * Step 1 (add only) — pick a rule from the catalogue list.
- * Step 2 — fill the params for the picked rule.
- *
- * Used in three modes:
- * - kind='sub' add: attach a per-sub filter (no Name field)
- * - kind='sub' edit: edit per-sub filter params (skip step 1)
- * - kind='library' add/edit: same flow plus a Name field
- */
 import { ChevronLeft } from 'lucide-react';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import {
@@ -34,7 +23,7 @@ export interface FilterSheetSubmit {
   ruleType: FilterRuleType;
   params: Record<string, unknown>;
   mode: FilterMode;
-  /** Name only set when kind='library'. */
+  // Only set when kind='library'.
   name?: string;
 }
 
@@ -43,7 +32,6 @@ export interface FilterSheetProps {
   mode: 'add' | 'edit';
   kind: FilterSheetKind;
   initial?: SubscriptionFilterDto | LibraryFilterDto | null;
-  /** Available rule types from the API catalogue (filtered by support). */
   availableTypes: readonly FilterRuleType[];
   onClose: () => void;
   onSubmit: (data: FilterSheetSubmit) => void;
@@ -65,9 +53,7 @@ export function FilterSheet({
 
   const [step, setStep] = useState<1 | 2>(1);
   const [name, setName] = useState('');
-  // The rule draft (type + params + include/exclude mode) and its validation
-  // are shared with SubSheet's inline-filter editor via this hook. `mode` is
-  // taken by the add/edit prop here, so it's exposed as `filterMode`.
+  // Draft mode aliased to filterMode since `mode` is already the add/edit prop.
   const {
     ruleType: type,
     params,
diff --git a/apps/web/src/components/sheets/SubSheet.tsx b/apps/web/src/components/sheets/SubSheet.tsx
index c7af555..05f6180 100644
--- a/apps/web/src/components/sheets/SubSheet.tsx
+++ b/apps/web/src/components/sheets/SubSheet.tsx
@@ -26,7 +26,6 @@ import { RuleForm } from '@/components/domain/RuleForm';
 import { RuleListItem } from '@/components/domain/RuleListItem';
 
 export interface InlineFilterDraft {
-  /** Stable react key for the lifetime of an unsaved row. */
   clientKey: string;
   ruleType: FilterRuleType;
   params: Record<string, unknown>;
@@ -35,28 +34,14 @@ export interface InlineFilterDraft {
 }
 
 export interface SubSheetSubmit {
-  /**
-   * Resolved chat id when known (public link / username / numeric id, or
-   * already-member private invite). `null` only for `t.me/+HASH` invites
-   * where the userbot isn't a member yet — in that case `inviteHash` is
-   * non-null and the server joins on create to derive the id.
-   */
+  // null only for not-yet-joined t.me/+HASH invites; then inviteHash is set and the server joins on create.
   sourceChatId: string | null;
   inviteHash: string | null;
   sourceTitle: string;
   handle: string | null;
-  /**
-   * Null means "no destination" — subscription is created/saved in a
-   * detached state and won't forward until the user attaches a destination.
-   */
-  destinationId: number | null;
+  destinationId: number | null; // null = detached, won't forward
   libraryFilterIds: number[];
-  /**
-   * Bulk-replace set of private inline filters. Empty array = drop all on
-   * save. Each entry has been validated against
-   * `filterRuleParamsSchemas[ruleType]` so `params` matches the discriminator.
-   */
-  inlineFilters: InlineFilterInput[];
+  inlineFilters: InlineFilterInput[]; // bulk-replace set; [] drops all
 }
 
 export interface SubSheetProps {
@@ -65,7 +50,6 @@ export interface SubSheetProps {
   initial?: SubscriptionDto | null;
   destinations: DestinationDto[];
   library: LibraryFilterDto[];
-  /** Catalog of supported rule types (from `useFilterCatalog`). */
   availableTypes: readonly FilterRuleType[];
   onClose: () => void;
   onSubmit: (data: SubSheetSubmit) => void;
@@ -94,8 +78,7 @@ export function SubSheet({
   const [libIds, setLibIds] = useState<number[]>([]);
   const [inlineFilters, setInlineFilters] = useState<InlineFilterDraft[]>([]);
   const [step, setStep] = useState<SubFilterStep>({ kind: 'list' });
-  // Step-local draft buffer (shared with FilterSheet via useFilterDraft);
-  // committed back into `inlineFilters` only on Save.
+  // Step-local draft buffer; committed into inlineFilters only on Save.
   const {
     ruleType: draftRule,
     params: draftParams,
@@ -117,32 +100,43 @@ export function SubSheet({
     error: resolveErrorRaw,
   } = useResolveSubscription();
 
-  // Pull existing inline filters in edit mode so the user sees and can edit
-  // what they already have. Only enabled when the sheet is open + edit mode.
   const filtersQuery = useSubscriptionFilters(isEdit && open && initial ? initial.id : null);
 
-  // Reset on open / mode change.
   useEffect(() => {
     if (!open) return;
     if (isEdit && initial) {
       setLink(initial.handle ?? `@${initial.sourceTitle}`);
       setDestId(initial.destinationId);
       setLibIds([...initial.libraryFilterIds]);
-      // inlineFilters seeded from filtersQuery.data when it lands (effect below).
       resetResolve();
     } else {
       setLink('');
-      setDestId(destinations[0]?.id ?? null);
+      setDestId(null);
       setLibIds([]);
       setInlineFilters([]);
       resetResolve();
     }
     setStep({ kind: 'list' });
     resetDraft();
-  }, [open, isEdit, initial, destinations, resetResolve, resetDraft]);
+    // `destinations` is intentionally NOT a dep — its ref changes on every background
+    // refetch, and re-running this would wipe the user's in-progress input. The default
+    // destination is seeded once by the effect below.
+  }, [open, isEdit, initial, resetResolve, resetDraft]);
 
-  // Seed inline filters from the server once they land. Ignored on subsequent
-  // refetches so the user's in-progress edits aren't clobbered.
+  // Default the destination to the first available one, once per add-sheet open. Guarded
+  // so a later background refetch of `destinations` can't clobber the user's pick.
+  const [destSeeded, setDestSeeded] = useState(false);
+  useEffect(() => {
+    if (!open) {
+      setDestSeeded(false);
+      return;
+    }
+    if (isEdit || destSeeded || destinations.length === 0) return;
+    setDestId((cur) => cur ?? destinations[0]!.id);
+    setDestSeeded(true);
+  }, [open, isEdit, destSeeded, destinations]);
+
+  // Seed once; later refetches are ignored so in-progress edits aren't clobbered.
   const [seeded, setSeeded] = useState(false);
   useEffect(() => {
     if (!open) {
@@ -164,7 +158,6 @@ export function SubSheet({
     setSeeded(true);
   }, [open, isEdit, seeded, filtersQuery.data]);
 
-  // Debounce resolve in add mode.
   useDebouncedResolve({
     value: link,
     enabled: !isEdit,
@@ -184,10 +177,7 @@ export function SubSheet({
 
   const handleSubmit = () => {
     if (!canSave) return;
-    // Validate each draft against the wire schema at the boundary rather than
-    // casting. Inline-edited drafts are already parsed on commit, but ones
-    // seeded from the server are re-checked here, so a schema drift fails
-    // loudly instead of writing a malformed filter.
+    // Re-validate at the wire boundary so server-seeded drafts fail loudly on schema drift.
     const wireInline: InlineFilterInput[] = inlineFilters.map((d) =>
       inlineFilterInputSchema.parse({
         ruleType: d.ruleType,
@@ -208,9 +198,6 @@ export function SubSheet({
       });
     } else if (resolved) {
       onSubmit({
-        // For not-yet-joined private invites the resolve preview can't
-        // know the chat id; the server joins via importInvite and derives
-        // the id during create. Otherwise we forward the resolved id.
         sourceChatId: resolved.sourceChatId ?? null,
         inviteHash: resolved.inviteHash,
         sourceTitle: resolved.sourceTitle,
@@ -470,9 +457,7 @@ export function SubSheet({
 
 let inlineKeyCounter = 0;
 
-// Stable React key for an unsaved inline-filter row. Prefers a UUID but falls
-// back to a counter on insecure contexts (http:// LAN host, where
-// crypto.randomUUID is undefined) — the key only needs to be unique in-sheet.
+// Counter fallback for insecure contexts where crypto.randomUUID is undefined.
 function newClientKey(): string {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID();
diff --git a/apps/web/src/components/ui/button.tsx b/apps/web/src/components/ui/button.tsx
index 6929134..9ea5b65 100644
--- a/apps/web/src/components/ui/button.tsx
+++ b/apps/web/src/components/ui/button.tsx
@@ -38,11 +38,8 @@ const buttonStyles = cva(
 
 export interface ButtonProps
   extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonStyles> {
-  /** Leading icon, rendered before `children`. Swapped for a spinner while loading. */
   icon?: ReactNode;
-  /** Shows a spinner in the leading slot and disables the button. */
   loading?: boolean;
-  /** Spinner size while loading. */
   spinnerSize?: number;
 }
 
diff --git a/apps/web/src/components/ui/checkbox-card.tsx b/apps/web/src/components/ui/checkbox-card.tsx
index 17d70d0..121bec8 100644
--- a/apps/web/src/components/ui/checkbox-card.tsx
+++ b/apps/web/src/components/ui/checkbox-card.tsx
@@ -8,16 +8,10 @@ export interface CheckboxCardProps {
   label: ReactNode;
   description?: ReactNode;
   disabled?: boolean;
-  /** `danger` paints the selected state destructive (red), for wipe flows. */
   tone?: 'default' | 'danger';
-  /** Extra classes on the description line (e.g. monospace + truncate). */
   descriptionClassName?: string;
 }
 
-/**
- * Clickable card with a square check box + label and optional description.
- * The whole card is the toggle target.
- */
 export function CheckboxCard({
   checked,
   onToggle,
diff --git a/apps/web/src/components/ui/fab.tsx b/apps/web/src/components/ui/fab.tsx
index ec656f1..19339d3 100644
--- a/apps/web/src/components/ui/fab.tsx
+++ b/apps/web/src/components/ui/fab.tsx
@@ -8,11 +8,7 @@ export interface FabProps {
   className?: string | undefined;
 }
 
-/**
- * Floating action button — anchored to the bottom-right of the nearest
- * positioned ancestor (the app's <main>), so it floats above the page
- * content and clears the mobile tab bar.
- */
+// Absolutely positioned: anchors to the nearest positioned ancestor (the app's <main>).
 export function Fab({ onClick, label, children, className }: FabProps) {
   return (
     <button
diff --git a/apps/web/src/components/ui/list-state.tsx b/apps/web/src/components/ui/list-state.tsx
index c18bd97..e623942 100644
--- a/apps/web/src/components/ui/list-state.tsx
+++ b/apps/web/src/components/ui/list-state.tsx
@@ -2,15 +2,12 @@ import type { ReactNode } from 'react';
 import { Spinner } from '@/components/ui/spinner';
 
 export interface ListStateProps {
-  /** Query is loading — shows a centered spinner. */
   pending: boolean;
-  /** Loaded but no rows — shows `empty`. */
   isEmpty: boolean;
   empty: ReactNode;
   children: ReactNode;
 }
 
-/** The loading → empty → list ladder shared by the resource list pages. */
 export function ListState({ pending, isEmpty, empty, children }: ListStateProps) {
   if (pending) {
     return (
diff --git a/apps/web/src/components/ui/sheet.tsx b/apps/web/src/components/ui/sheet.tsx
index a5b7cbd..2146384 100644
--- a/apps/web/src/components/ui/sheet.tsx
+++ b/apps/web/src/components/ui/sheet.tsx
@@ -9,10 +9,6 @@ export interface SheetProps {
   onOpenChange: (open: boolean) => void;
   title: ReactNode;
   description?: ReactNode;
-  /**
-   * Layout: bottom sheet on mobile, centered modal on desktop. Switched by
-   * Tailwind breakpoint at `lg:` — same component, two looks.
-   */
   children: ReactNode;
   footer?: ReactNode;
 }
diff --git a/apps/web/src/components/ui/toast.tsx b/apps/web/src/components/ui/toast.tsx
index b5ede15..785ca22 100644
--- a/apps/web/src/components/ui/toast.tsx
+++ b/apps/web/src/components/ui/toast.tsx
@@ -1,12 +1,3 @@
-/**
- * Tiny toast — top-of-screen, single message at a time.
- *
- * The design's feedback was explicit: floating Add buttons + bottom toast
- * interfered with content access. Toast lives at the top, dismisses after
- * 2.4s. Provider mounts a portal at <body>; pages call `useToast().show(msg)`
- * for confirmations and `useToast().error(msg)` for failures — the two render
- * with distinct icon + color so a failure never looks like a success.
- */
 import { AlertTriangle, Check } from 'lucide-react';
 import {
   createContext,
@@ -28,9 +19,7 @@ interface ToastState {
 }
 
 interface ToastContextValue {
-  /** Success confirmation (green check). */
   show: (message: string) => void;
-  /** Failure (danger triangle + tint). */
   error: (message: string) => void;
 }
 
diff --git a/apps/web/src/hooks/useActivityStream.tsx b/apps/web/src/hooks/useActivityStream.tsx
index 842466a..db53b90 100644
--- a/apps/web/src/hooks/useActivityStream.tsx
+++ b/apps/web/src/hooks/useActivityStream.tsx
@@ -1,26 +1,6 @@
-/**
- * SSE stream singleton.
- *
- * `StreamProvider` opens one EventSource on `/api/stream` for the whole app
- * (mounted in AppShell). All consumers — sidebar/top-bar connection pill,
- * activity page event feed — read from the same source.
- *
- * Forward events are delivered through a subscription (`useForwardEvents`)
- * rather than a "last event" state value: a state slot collapses two events
- * that arrive in the same tick into one (React batches the setter), and any
- * consumer effect keyed on it re-runs — and re-delivers the same event — on
- * unrelated re-renders. A synchronous listener set delivers every event
- * exactly once. Connection state stays a separate context so the layout
- * chrome doesn't re-render on every forward event.
- *
- * EventSource auto-reconnects with browser-controlled backoff. We surface
- * readyState transitions as `'reconnect'` while connecting and `'live'`
- * once OPEN. `subscription.changed`/`destination.changed` events invalidate
- * the relevant queries directly; forward events also schedule a debounced
- * refresh of the forward-log so the persisted history reconciles with the
- * live overlay (otherwise a remount would drop events that only ever lived
- * in component state).
- */
+// One app-wide EventSource on `/api/stream`. Forward events go through a synchronous listener set,
+// not a state slot, so same-tick events aren't coalesced and re-renders don't re-deliver old ones.
+// Connection state is a separate context so layout chrome doesn't re-render per forward event.
 import {
   createContext,
   useCallback,
@@ -46,7 +26,6 @@ const FORWARD_EVENT_TYPES = new Set([
   'forward.filtered',
 ]);
 
-// Coalesce bursts of forward events into a single forward-log refetch.
 const FORWARD_LOG_REFRESH_MS = 3000;
 
 const ConnectionStateContext = createContext<ConnectionState | null>(null);
@@ -79,15 +58,12 @@ export function StreamProvider({ children, url = '/api/stream' }: StreamProvider
 
     es.onopen = () => setState('live');
     es.onerror = () => {
-      // EventSource sets readyState to 0 (CONNECTING) during reconnect or
-      // 2 (CLOSED) on permanent failure. Treat 0 as reconnect, 2 as down.
+      // readyState CLOSED (2) = permanent failure; CONNECTING (0) = reconnecting.
       setState(es.readyState === EventSource.CLOSED ? 'down' : 'reconnect');
     };
 
     const scheduleForwardLogRefresh = (): void => {
-      // Throttle, not debounce: a resettable debounce would never fire on a
-      // sustained stream (each event re-arms it). Arm once and let it run, so
-      // the log refreshes at most once per window but is guaranteed to.
+      // Throttle, not debounce: a resettable debounce would never fire on a sustained stream.
       if (refreshTimer) return;
       refreshTimer = setTimeout(() => {
         refreshTimer = null;
@@ -100,9 +76,7 @@ export function StreamProvider({ children, url = '/api/stream' }: StreamProvider
       try {
         parsed = JSON.parse(raw.data) as StreamEvent;
       } catch (err) {
-        // Malformed payload signals protocol drift between server and client.
-        // Surface it in dev; stay quiet in prod so a server hiccup can't flood
-        // the user's console.
+        // Warn in dev only; a server hiccup shouldn't flood the prod console.
         if (import.meta.env.DEV) {
           console.warn('StreamProvider: failed to parse SSE event', err, raw.data);
         }
@@ -113,10 +87,7 @@ export function StreamProvider({ children, url = '/api/stream' }: StreamProvider
         return;
       }
       if (parsed.type === 'destination.changed') {
-        // The access monitor flips a destination's `accessStatus` when
-        // userbot membership is gained or lost. Both the destinations
-        // list and the subscription rows (which join `accessStatus` for
-        // the destination indicator) must refetch.
+        // Subs join the destination's `accessStatus`, so both lists must refetch.
         qc.invalidateQueries({ queryKey: DESTINATIONS_KEY });
         qc.invalidateQueries({ queryKey: SUBSCRIPTIONS_KEY });
         return;
@@ -127,8 +98,7 @@ export function StreamProvider({ children, url = '/api/stream' }: StreamProvider
       }
     };
 
-    // Server sends named events (`event: <type>`); EventSource needs an
-    // explicit listener per event name. Subscribe to all known types.
+    // Named events (`event: <type>`) need one explicit EventSource listener each.
     const types = [
       'forward.completed',
       'forward.failed',
@@ -140,9 +110,7 @@ export function StreamProvider({ children, url = '/api/stream' }: StreamProvider
     types.forEach((t) => es.addEventListener(t, dispatch));
 
     return () => {
-      // StrictMode mounts effects twice in dev — the first cleanup nulls out
-      // sourceRef before the second one runs, so guard against the redundant
-      // call to keep this idempotent.
+      // Guard the StrictMode double-invoke: first cleanup nulls sourceRef before the second runs.
       if (!sourceRef.current) return;
       if (refreshTimer) clearTimeout(refreshTimer);
       types.forEach((t) => es.removeEventListener(t, dispatch));
@@ -166,12 +134,7 @@ export function useConnectionState(): ConnectionState {
   return ctx;
 }
 
-/**
- * Subscribe to live forward events. The listener fires once per event,
- * synchronously as it arrives — so no event is dropped between renders and
- * unrelated re-renders never re-deliver an old one. Pass a stable callback
- * (e.g. `useCallback`) that reads any changing values through refs.
- */
+// Fires once synchronously per forward event. The handler ref keeps a fresh closure without resubscribing.
 export function useForwardEvents(onEvent: ForwardEventListener): void {
   const subscribe = useContext(ForwardEventsContext);
   if (!subscribe) {
diff --git a/apps/web/src/hooks/useAuth.ts b/apps/web/src/hooks/useAuth.ts
index a262088..762db40 100644
--- a/apps/web/src/hooks/useAuth.ts
+++ b/apps/web/src/hooks/useAuth.ts
@@ -1,12 +1,4 @@
-/**
- * Auth hooks.
- *
- * `useMe` is the source of truth for "is the user logged in". It runs once
- * at app boot via `RequireAuth`; mutations invalidate it after login/logout.
- * staleTime is Infinity because cookie validity doesn't change while the
- * tab is open — if it expires mid-session, the api/client.ts 401-interceptor
- * forces a navigate to /login anyway.
- */
+// useMe is the source of truth for "logged in". staleTime Infinity since cookie validity is stable per tab; a mid-session expiry is caught by the client.ts 401-interceptor.
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { getMe, login, loginWithTelegram, logout } from '@/api/authApi';
 import { UnauthorizedError } from '@/api/client';
@@ -32,7 +24,6 @@ export function useLogin() {
   });
 }
 
-/** Sign in with a Telegram Mini App `initData` payload; invalidates `/me` on success. */
 export function useTelegramLogin() {
   const qc = useQueryClient();
   return useMutation({
diff --git a/apps/web/src/hooks/useBotConfig.ts b/apps/web/src/hooks/useBotConfig.ts
index 5fbbf25..5e89b70 100644
--- a/apps/web/src/hooks/useBotConfig.ts
+++ b/apps/web/src/hooks/useBotConfig.ts
@@ -21,8 +21,7 @@ export function useUpdateBotConfig() {
   const qc = useQueryClient();
   return useMutation<BotConfigInfo, Error, UpdateBotConfigRequest>({
     mutationFn: updateBotConfig,
-    // PUT returns the fresh masked view (post-reload botRunning included), so
-    // seed the cache directly rather than round-tripping a refetch.
+    // PUT returns the fresh masked view, so seed the cache directly instead of refetching.
     onSuccess: (data) => qc.setQueryData(BOT_CONFIG_KEY, data),
   });
 }
@@ -35,7 +34,6 @@ export function useDeleteBotConfig() {
   });
 }
 
-/** Resolve a `@username` / numeric id to a Telegram user for the admin allowlist. */
 export function useResolveBotAdmin() {
   return useMutation<ResolveBotAdminResponse, Error, string>({ mutationFn: resolveBotAdmin });
 }
diff --git a/apps/web/src/hooks/useDebouncedResolve.ts b/apps/web/src/hooks/useDebouncedResolve.ts
index 1b657d7..1dccb18 100644
--- a/apps/web/src/hooks/useDebouncedResolve.ts
+++ b/apps/web/src/hooks/useDebouncedResolve.ts
@@ -1,26 +1,15 @@
 import { useEffect } from 'react';
 
 export interface UseDebouncedResolveOptions {
-  /** Current input value to resolve. */
   value: string;
-  /** When false the hook is inert (e.g. edit mode, where the source is fixed). */
+  // When false the hook is inert (e.g. edit mode, where the source is fixed).
   enabled: boolean;
-  /** Called with the trimmed input once the debounce settles. */
   mutate: (input: string) => void;
-  /** Called to clear any prior result when the input is too short. */
   reset: () => void;
-  /** Minimum trimmed length before a resolve is attempted. */
   minLength?: number;
-  /** Debounce delay in ms after the last change. */
   delayMs?: number;
 }
 
-/**
- * Debounced channel/chat resolution shared by SubSheet and DestSheet. Fires
- * `mutate(trimmed)` `delayMs` after the last change to `value`, but only while
- * `enabled` and the trimmed input is long enough to plausibly be a Telegram
- * link / @username / chat id. Clears any prior result when it's too short.
- */
 export function useDebouncedResolve({
   value,
   enabled,
diff --git a/apps/web/src/hooks/useDestinations.ts b/apps/web/src/hooks/useDestinations.ts
index 561a8fb..662ec90 100644
--- a/apps/web/src/hooks/useDestinations.ts
+++ b/apps/web/src/hooks/useDestinations.ts
@@ -55,11 +55,7 @@ export function useResolveDestination() {
   });
 }
 
-/**
- * Lists a forum chat's topics for the destination picker. Enabled only once
- * we know the chat is a forum (and have its id), so non-forum destinations
- * never trigger the lookup. Keyed by chatId so switching chats refetches.
- */
+// Pass enabled=true only for confirmed forum chats, so non-forum picks never fetch.
 export function useForumTopics(chatId: string | null, enabled: boolean) {
   return useQuery<ListForumTopicsResponse>({
     queryKey: ['forum-topics', chatId],
diff --git a/apps/web/src/hooks/useExportImport.ts b/apps/web/src/hooks/useExportImport.ts
index 43627c3..a6f7f68 100644
--- a/apps/web/src/hooks/useExportImport.ts
+++ b/apps/web/src/hooks/useExportImport.ts
@@ -24,8 +24,6 @@ export function useImportData() {
   return useMutation<ImportResult, Error, ImportRequest>({
     mutationFn: importData,
     onSuccess: () => {
-      // Imports can touch every section; invalidate everything that lists
-      // imported entities so the UI reflects the new state immediately.
       qc.invalidateQueries({ queryKey: SUBSCRIPTIONS_KEY });
       qc.invalidateQueries({ queryKey: DESTINATIONS_KEY });
       qc.invalidateQueries({ queryKey: LIBRARY_FILTERS_KEY });
diff --git a/apps/web/src/hooks/useFilterDraft.ts b/apps/web/src/hooks/useFilterDraft.ts
index 5b69848..f32b64c 100644
--- a/apps/web/src/hooks/useFilterDraft.ts
+++ b/apps/web/src/hooks/useFilterDraft.ts
@@ -1,13 +1,4 @@
-/**
- * Shared rule-draft state for the filter editors.
- *
- * Both the standalone `FilterSheet` and the inline-filter editor inside
- * `SubSheet` drive the same little flow: pick a rule type (which seeds its
- * default params and resets the include/exclude mode), edit the params,
- * validate them against `filterRuleParamsSchemas[ruleType]`, then parse the
- * validated payload on commit. This hook owns that logic so the two sheets
- * don't each hand-roll (and drift on) it; each still renders its own step UI.
- */
+// Shared rule-draft state so FilterSheet and SubSheet's inline editor don't drift.
 import { useCallback, useMemo, useState, type Dispatch, type SetStateAction } from 'react';
 import {
   filterRuleDefaultParams,
@@ -22,15 +13,12 @@ export interface FilterDraft {
   mode: FilterMode;
   setParams: Dispatch<SetStateAction<Record<string, unknown>>>;
   setMode: Dispatch<SetStateAction<FilterMode>>;
-  /** Select a rule type: seeds its default params and resets mode to 'include'. */
+  // Seeds the rule's default params and resets mode to 'include'.
   pickType: (t: FilterRuleType) => void;
-  /** Load an existing filter for editing. */
   load: (rule: FilterRuleType, params: Record<string, unknown>, mode: FilterMode) => void;
-  /** Clear back to the empty draft. */
   reset: () => void;
-  /** True when the current params validate against the rule's schema. */
   valid: boolean;
-  /** Parse + return the validated params. Throws if there's no rule — guard with `valid`. */
+  // Throws if there's no rule — guard with `valid`.
   parseParams: () => Record<string, unknown>;
 }
 
diff --git a/apps/web/src/hooks/useFilterSheetState.ts b/apps/web/src/hooks/useFilterSheetState.ts
index 87b6919..9c824fc 100644
--- a/apps/web/src/hooks/useFilterSheetState.ts
+++ b/apps/web/src/hooks/useFilterSheetState.ts
@@ -1,10 +1,4 @@
-/**
- * Reducer-style hook for the FiltersPage sheet (add/edit, sub/library).
- *
- * Owns the four orthogonal pieces (open?, mode, kind, initial value) as a
- * single object so callers don't manage four `useState` slots and risk
- * leaving the sheet in an inconsistent state.
- */
+// Single-object state for the FiltersPage sheet so callers can't desync open/mode/kind/initial.
 import { useCallback, useState } from 'react';
 import type { LibraryFilterDto, SubscriptionFilterDto } from '@tg-feed/shared';
 
diff --git a/apps/web/src/hooks/useFilters.ts b/apps/web/src/hooks/useFilters.ts
index 5d24461..92f8004 100644
--- a/apps/web/src/hooks/useFilters.ts
+++ b/apps/web/src/hooks/useFilters.ts
@@ -91,8 +91,6 @@ export function useDeleteSubscriptionFilter() {
   });
 }
 
-// --- Library filters ---
-
 export function useLibraryFilters() {
   return useQuery({
     queryKey: LIBRARY_FILTERS_KEY,
diff --git a/apps/web/src/hooks/useForwardLogRaw.ts b/apps/web/src/hooks/useForwardLogRaw.ts
index d7c70a8..17bcb7a 100644
--- a/apps/web/src/hooks/useForwardLogRaw.ts
+++ b/apps/web/src/hooks/useForwardLogRaw.ts
@@ -1,15 +1,7 @@
 import { useQuery } from '@tanstack/react-query';
 import { getForwardLogRaw } from '@/api/forwardLogApi';
 
-/**
- * Fetch the raw JSON snapshot for a single `forward_log` row. Deferred from
- * the list response on purpose — the payload averages ~3KB but can spike to
- * tens of KB for media-heavy messages, so we only pay the cost on click.
- *
- * Caches indefinitely (the row's raw_message is write-once) and pauses
- * itself when `id` is `null`/`undefined` so opening the JSON Sheet without
- * a selected entry doesn't fire a request.
- */
+// Deferred raw-JSON fetch (kept off the list to avoid tens of KB/row); caches forever as raw_message is write-once, pauses while id is null.
 export function useForwardLogRaw(id: number | null | undefined) {
   return useQuery({
     queryKey: ['forward-log', id, 'raw'] as const,
diff --git a/apps/web/src/hooks/useSheetState.ts b/apps/web/src/hooks/useSheetState.ts
index e994081..62c0167 100644
--- a/apps/web/src/hooks/useSheetState.ts
+++ b/apps/web/src/hooks/useSheetState.ts
@@ -1,10 +1,4 @@
-/**
- * Generic add/edit sheet state.
- *
- * Wraps the four-piece (open/mode/initial) shape every CRUD page redeclares
- * with `useState`. Keeps the open/mode/initial trio in a single object so
- * the sheet never lands in an inconsistent state.
- */
+// Generic add/edit sheet state: open/mode/initial as one object so it can't go inconsistent.
 import { useCallback, useState } from 'react';
 
 export type SheetMode = 'add' | 'edit';
diff --git a/apps/web/src/hooks/useSubscriptions.ts b/apps/web/src/hooks/useSubscriptions.ts
index 45ec1c4..98f20ff 100644
--- a/apps/web/src/hooks/useSubscriptions.ts
+++ b/apps/web/src/hooks/useSubscriptions.ts
@@ -14,9 +14,7 @@ import type {
 } from '@tg-feed/shared';
 
 export const SUBSCRIPTIONS_KEY = ['subscriptions'] as const;
-// Mirrors `subscriptionFiltersKey` in useFilters.ts. Duplicated here (rather
-// than imported) to avoid a circular hooks import — both files reference
-// each other's keys for cross-invalidation. Keep these prefixes in sync.
+// Duplicated from useFilters.ts (avoids a circular import); keep in sync with subscriptionFiltersKey.
 const SUB_FILTERS_KEY_PREFIX = ['subscription-filters'] as const;
 
 export function useSubscriptions() {
@@ -33,8 +31,7 @@ export function useCreateSubscription() {
     mutationFn: createSubscription,
     onSuccess: (sub) => {
       qc.invalidateQueries({ queryKey: SUBSCRIPTIONS_KEY });
-      // The new sub may carry inline filters set via the create body;
-      // invalidate so PerSubView's per-sub query reflects them.
+      // The create body may carry inline filters, so refresh the per-sub filter query.
       qc.invalidateQueries({ queryKey: [...SUB_FILTERS_KEY_PREFIX, sub.id] });
     },
   });
diff --git a/apps/web/src/hooks/useSystemStatus.ts b/apps/web/src/hooks/useSystemStatus.ts
index 8b94ee5..13e1697 100644
--- a/apps/web/src/hooks/useSystemStatus.ts
+++ b/apps/web/src/hooks/useSystemStatus.ts
@@ -8,10 +8,7 @@ export function useSystemStatus() {
     queryKey: SYSTEM_STATUS_KEY,
     queryFn: getSystemStatus,
     staleTime: 60_000,
-    // Poll while Telegram is still bringing itself up so the SettingsPage
-    // banner clears within a couple seconds of init finishing, instead of
-    // waiting until the user navigates away and back. Stops polling once
-    // the state lands on `connected` or `disconnected`.
+    // Poll only while connecting so the SettingsPage banner clears without a manual nav.
     refetchInterval: (query) => (query.state.data?.telegram.state === 'connecting' ? 1500 : false),
   });
 }
diff --git a/apps/web/src/lib/ThemeProvider.tsx b/apps/web/src/lib/ThemeProvider.tsx
index 7c141fc..ba870eb 100644
--- a/apps/web/src/lib/ThemeProvider.tsx
+++ b/apps/web/src/lib/ThemeProvider.tsx
@@ -7,11 +7,7 @@ export interface ThemeProviderProps {
   children: ReactNode;
 }
 
-/**
- * Hosts a single theme instance at the app root so the resolved theme is
- * applied (and system changes are tracked) for the whole session — not just
- * while a particular page that happens to read the theme is mounted.
- */
+// Hosts one theme instance at the app root so it tracks system changes for the whole session, not per-page.
 export function ThemeProvider({ children }: ThemeProviderProps) {
   const theme = useTheme();
   return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
diff --git a/apps/web/src/lib/describeFilter.ts b/apps/web/src/lib/describeFilter.ts
index cc27b97..12ee74b 100644
--- a/apps/web/src/lib/describeFilter.ts
+++ b/apps/web/src/lib/describeFilter.ts
@@ -1,18 +1,9 @@
-/**
- * One-line summaries of a filter rule's params, for compact rendering in
- * filter lists. Matches the design's `describeFilter` output verbatim.
- *
- * `FILTER_RULE_META` is the single per-rule registry: label, description,
- * and icon together so adding a new rule means touching one record. Legacy
- * named maps (`FILTER_RULE_LABELS` etc.) are derived from it.
- */
 import { Ban, FileImage, Regex, Ruler, TextCursorInput, User, type LucideIcon } from 'lucide-react';
 import type { FilterMode, FilterRuleType } from '@tg-feed/shared';
 
 export interface FilterLike {
   ruleType: FilterRuleType;
   params: Record<string, unknown>;
-  /** Optional — when 'exclude', the description is prefixed with "Exclude: ". */
   mode?: FilterMode;
 }
 
diff --git a/apps/web/src/lib/formatRelative.ts b/apps/web/src/lib/formatRelative.ts
index 8adb424..6b6190b 100644
--- a/apps/web/src/lib/formatRelative.ts
+++ b/apps/web/src/lib/formatRelative.ts
@@ -1,7 +1,3 @@
-/**
- * "Xs ago" / "Xm ago" / "Xh ago" / "Xd ago" relative formatter.
- * Matches the design's `formatRelative`.
- */
 export function formatRelative(ageSec: number): string {
   if (ageSec < 60) return `${Math.max(1, Math.round(ageSec))}s ago`;
   if (ageSec < 3600) return `${Math.round(ageSec / 60)}m ago`;
diff --git a/apps/web/src/lib/queryClient.ts b/apps/web/src/lib/queryClient.ts
index 066739d..e9d54ab 100644
--- a/apps/web/src/lib/queryClient.ts
+++ b/apps/web/src/lib/queryClient.ts
@@ -9,9 +9,7 @@ export function createQueryClient(): QueryClient {
           if (error instanceof Error && error.name === 'UnauthorizedError') return false;
           return failureCount < 2;
         },
-        // Refetch on focus so a tab left open overnight doesn't display
-        // stale state after the user comes back. SSE invalidates targeted
-        // queries (subscriptions) live; this picks up anything else.
+        // Refetch on focus so a tab left open overnight isn't stale; SSE covers live subscription updates.
         refetchOnWindowFocus: true,
         staleTime: 5_000,
         gcTime: 10 * 60 * 1000,
diff --git a/apps/web/src/lib/telegram.ts b/apps/web/src/lib/telegram.ts
index c4b6e86..298c88a 100644
--- a/apps/web/src/lib/telegram.ts
+++ b/apps/web/src/lib/telegram.ts
@@ -1,19 +1,11 @@
-/**
- * Telegram Mini App helpers.
- *
- * The Telegram SDK script (loaded in index.html) injects
- * `window.Telegram.WebApp` when the page runs inside a Telegram client. These
- * read the signed `initData` string (posted to `/api/auth/telegram`) and the
- * color scheme, and drive the viewport lifecycle. Outside Telegram the global
- * is absent and the getters return null.
- */
+// Telegram Mini App helpers. The SDK injects window.Telegram.WebApp inside a Telegram client; outside it the global is absent and getters return null.
 
 interface TelegramWebApp {
-  /** Signed init payload. Empty string when not launched from Telegram. */
+  // Empty string when not launched from Telegram.
   initData: string;
-  /** Signals to Telegram that the app is ready to be shown. */
+  // UNVERIFIED — cosmetic hints only, never for authorization (use signed initData server-side).
+  initDataUnsafe?: { user?: { id: number } };
   ready: () => void;
-  /** Expands the Mini App to full height. */
   expand: () => void;
   colorScheme?: 'light' | 'dark';
 }
@@ -35,27 +27,23 @@ export function getTelegramWebApp(): TelegramWebApp | null {
   return window.Telegram?.WebApp ?? null;
 }
 
-/**
- * The signed initData string, or null when not running inside Telegram (the
- * SDK leaves `initData` as an empty string outside a Telegram client).
- */
 export function getTelegramInitData(): string | null {
   const webApp = getTelegramWebApp();
   if (!webApp || !webApp.initData) return null;
   return webApp.initData;
 }
 
-/** True when the app is being rendered inside a Telegram client. */
 export function isInsideTelegram(): boolean {
   return getTelegramInitData() !== null;
 }
 
-/**
- * Best-effort detection of a Telegram launch that works BEFORE the (async)
- * SDK script has populated `window.Telegram.WebApp`. Native clients expose
- * `TelegramWebviewProxy`; web clients put the launch params in the URL hash
- * as `tgWebAppData`. Used to decide whether it's worth waiting for the SDK.
- */
+// From unverified initDataUnsafe — cosmetic hints only, never authorization.
+export function getTelegramUserId(): string | null {
+  const id = getTelegramWebApp()?.initDataUnsafe?.user?.id;
+  return typeof id === 'number' ? String(id) : null;
+}
+
+// Detects a launch BEFORE the async SDK populates window.Telegram.WebApp (via TelegramWebviewProxy or the tgWebAppData hash).
 export function detectTelegramLaunch(): boolean {
   if (typeof window === 'undefined') return false;
   if (getTelegramInitData() !== null) return true;
@@ -63,12 +51,7 @@ export function detectTelegramLaunch(): boolean {
   return window.location.hash.includes('tgWebAppData');
 }
 
-/**
- * Resolve the signed initData. Returns it immediately when already present,
- * null when this isn't a Telegram launch, or — when it is a launch but the
- * async SDK hasn't populated it yet — polls every `intervalMs` up to
- * `timeoutMs` before falling back to null.
- */
+// Resolves initData now if present, null if not a launch, else polls up to timeoutMs while the async SDK populates it.
 export function waitForTelegramInitData(timeoutMs = 3000, intervalMs = 50): Promise<string | null> {
   const immediate = getTelegramInitData();
   if (immediate) return Promise.resolve(immediate);
@@ -85,20 +68,13 @@ export function waitForTelegramInitData(timeoutMs = 3000, intervalMs = 50): Prom
   });
 }
 
-/**
- * Telegram's current light/dark scheme, or null when not in Telegram / the
- * SDK isn't loaded. Lets the app's `system` theme preference follow the
- * surrounding Telegram chrome instead of the OS `prefers-color-scheme`.
- */
+// Lets the `system` theme follow Telegram chrome instead of OS prefers-color-scheme.
 export function getTelegramColorScheme(): 'light' | 'dark' | null {
   const scheme = getTelegramWebApp()?.colorScheme;
   return scheme === 'light' || scheme === 'dark' ? scheme : null;
 }
 
-/**
- * Tell Telegram the Mini App is ready and expand it to full height. Safe to
- * call unconditionally — a no-op outside Telegram.
- */
+// No-op outside Telegram, safe to call unconditionally.
 export function initTelegramViewport(): void {
   const webApp = getTelegramWebApp();
   if (!webApp) return;
@@ -106,6 +82,6 @@ export function initTelegramViewport(): void {
     webApp.ready();
     webApp.expand();
   } catch {
-    // SDK present but a call failed (old client). Non-fatal.
+    // Non-fatal: SDK present but a call failed (old client).
   }
 }
diff --git a/apps/web/src/lib/useNowTick.ts b/apps/web/src/lib/useNowTick.ts
index 0ccdbc2..4fad0c3 100644
--- a/apps/web/src/lib/useNowTick.ts
+++ b/apps/web/src/lib/useNowTick.ts
@@ -1,15 +1,4 @@
-/**
- * Single shared "now" tick.
- *
- * Components that render relative timestamps (e.g. "12s ago") subscribe via
- * `useNowTick()` and re-render only when the shared clock advances. The
- * interval is created lazily on the first subscriber and torn down when the
- * last one unsubscribes, so idle screens don't keep a timer alive.
- *
- * Using a module-scoped store rather than a per-component `setInterval`
- * avoids N identical timers when N rows are mounted, and lets a memoized
- * list parent skip re-rendering — only the leaf subscribers update.
- */
+// One shared clock for all relative timestamps; lazy timer avoids N per-row intervals.
 import { useSyncExternalStore } from 'react';
 
 const TICK_MS = 5000;
diff --git a/apps/web/src/lib/useTheme.ts b/apps/web/src/lib/useTheme.ts
index 605ff40..91b3efd 100644
--- a/apps/web/src/lib/useTheme.ts
+++ b/apps/web/src/lib/useTheme.ts
@@ -1,14 +1,4 @@
-/**
- * Theme: System / Light / Dark.
- *
- * The user's *preference* is one of three; the *resolved* theme is one of
- * two ('light' | 'dark') and is what gets written to `<html data-theme>`.
- * When preference is 'system', resolved tracks `prefers-color-scheme` live.
- *
- * Initial resolution happens in an inline script in `index.html` before
- * React mounts (avoids flash-of-wrong-theme). This hook keeps the runtime
- * value in sync with React state and re-applies on changes.
- */
+// Theme preference (system/light/dark) → resolved theme on <html data-theme>; index.html resolves it pre-mount to avoid a flash, this hook keeps it in sync after.
 import { useCallback, useEffect, useState } from 'react';
 import { getTelegramColorScheme, isInsideTelegram } from './telegram';
 
@@ -26,17 +16,13 @@ function readPreference(): ThemePreference {
       return stored as ThemePreference;
     }
   } catch {
-    // localStorage unavailable (e.g., private mode in some browsers).
+    // localStorage unavailable (e.g. private mode)
   }
   return 'system';
 }
 
 function systemTheme(): ResolvedTheme {
-  // Inside Telegram, follow Telegram's color scheme; elsewhere the OS
-  // preference. The Telegram SDK script loads in a plain browser too and
-  // injects `WebApp.colorScheme` (defaulting to 'light'), so only trust it
-  // when we're actually launched from Telegram — otherwise it would override
-  // the OS preference (and diverge from the index.html boot script).
+  // Only trust Telegram's colorScheme when actually launched from Telegram; the SDK injects a 'light' default in plain browsers that would override the OS preference.
   if (isInsideTelegram()) {
     const tg = getTelegramColorScheme();
     if (tg) return tg;
@@ -63,12 +49,11 @@ export function useTheme(): UseThemeResult {
   const [preference, setPreferenceState] = useState<ThemePreference>(readPreference);
   const [resolved, setResolved] = useState<ResolvedTheme>(() => resolve(readPreference()));
 
-  // Apply resolved theme any time it changes.
   useEffect(() => {
     apply(resolved);
   }, [resolved]);
 
-  // Watch the system media query, but only react while preference is 'system'.
+  // Track the system media query only while preference is 'system'.
   useEffect(() => {
     if (preference !== 'system') return;
     const mq = window.matchMedia('(prefers-color-scheme: dark)');
@@ -83,7 +68,7 @@ export function useTheme(): UseThemeResult {
     try {
       localStorage.setItem(THEME_STORAGE_KEY, next);
     } catch {
-      // ignore
+      // localStorage unavailable
     }
   }, []);
 
diff --git a/apps/web/src/pages/ActivityPage.tsx b/apps/web/src/pages/ActivityPage.tsx
index f0ae7e9..38246e1 100644
--- a/apps/web/src/pages/ActivityPage.tsx
+++ b/apps/web/src/pages/ActivityPage.tsx
@@ -1,22 +1,3 @@
-/**
- * Activity feed — hydrate from forward-log, prepend live SSE events.
- *
- * Hydration: `useForwardLog({ limit: 50 })` seeds the in-memory list and is
- * refreshed (debounced) as forward events arrive, so the persisted history
- * stays current. Live SSE events arrive via `useForwardEvents` and get
- * prepended immediately (capped at 200 entries to bound memory), then
- * reconcile with the refreshed log by `forwardLogId`.
- *
- * Enrichment: hydrated rows already have `subscriptionTitle`, `sourceHandle`,
- * and `destinationName` joined server-side via LEFT JOIN. SSE payloads carry
- * IDs only, so they're enriched on the client from the cached
- * `useSubscriptions` and `useDestinations` queries — with a backfill effect
- * for the case where a live event arrives before those queries hydrate.
- *
- * Pause: stops appending new events to the list (the EventSource stays
- * open). Scroll lock + jump-to-live: when the user has scrolled away from
- * the top, prepends don't yank — show a button to jump back.
- */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { AlertTriangle, ArrowDown, Activity as ActivityIcon, Pause, Play } from 'lucide-react';
 import type {
@@ -52,15 +33,10 @@ export function ActivityPage() {
 
   const [events, setEvents] = useState<ActivityEvent[]>([]);
 
-  // Hydrate from forward-log, and re-hydrate when it refetches (the stream
-  // provider refreshes it as forward events land). Keep live events the
-  // fetched log doesn't contain yet; drop those it does — matched by the
-  // forward_log row id the event carried — so a row isn't shown twice.
+  // Re-hydrate on refetch, keeping live events not yet in the log (deduped by forward_log id).
   useEffect(() => {
     if (!forwardLog.data) return;
-    // While paused the feed is frozen — skip re-hydration so a background
-    // log refetch doesn't prepend rows; `paused` is a dep, so it catches up
-    // on resume.
+    // Frozen while paused; `paused` is a dep so it catches up on resume.
     if (paused) return;
     setEvents((prev) => {
       const hydrated = forwardLog.data.items.map((row) => fromForwardLogEntry(row));
@@ -73,11 +49,7 @@ export function ActivityPage() {
     });
   }, [forwardLog.data, paused]);
 
-  // Read sub/dest maps via refs inside the prepend effect — including them
-  // in the dep array would re-run the effect (and re-prepend the same SSE
-  // event) every time `subscription.changed` invalidates the queries and
-  // produces a new Map reference. Backfill enrichment is handled by the
-  // separate effect below.
+  // Maps read via refs, not deps: a new Map reference per query invalidation would re-prepend the same event.
   const subByIdRef = useRef(subById);
   const destByChatIdRef = useRef(destByChatId);
   useEffect(() => {
@@ -85,15 +57,13 @@ export function ActivityPage() {
     destByChatIdRef.current = destByChatId;
   });
 
-  // Pause is read through a ref so the event handler stays stable (subscribes
-  // once) and isn't re-created when `paused` toggles.
+  // Read through a ref so the event handler stays stable across `paused` toggles.
   const pausedRef = useRef(paused);
   useEffect(() => {
     pausedRef.current = paused;
   }, [paused]);
 
-  // Prepend live SSE events as they arrive, deduped against the head in case
-  // the server ever re-emits one.
+  // Prepend live SSE events, deduped in case the server re-emits one.
   const handleForwardEvent = useCallback((event: StreamEvent) => {
     if (pausedRef.current) return;
     const built = fromStreamEvent(event, subByIdRef.current, destByChatIdRef.current);
@@ -104,9 +74,7 @@ export function ActivityPage() {
   }, []);
   useForwardEvents(handleForwardEvent);
 
-  // Backfill events constructed before subs/dests loaded. Returns the same
-  // array reference when nothing needs enrichment, so ActivityRow rows keep
-  // referential equality and don't re-render.
+  // Backfill events built before subs/dests loaded; returns the same array reference when nothing changed.
   useEffect(() => {
     setEvents((prev) => {
       const needsEnrich = prev.some(
@@ -239,8 +207,7 @@ function enrichEvent(event: ActivityEvent, subs: Map<number, SubscriptionDto>):
 }
 
 function fromForwardLogEntry(row: ForwardLogEntryDto): ActivityEvent {
-  // Build optional fields conditionally — under exactOptionalPropertyTypes,
-  // `{ seconds: undefined }` no longer satisfies `seconds?: number`.
+  // Optional fields built conditionally: exactOptionalPropertyTypes rejects `{ seconds: undefined }`.
   const floodWaitSeconds =
     row.status === 'flood_wait' ? parseFloodWaitSeconds(row.error) : undefined;
   return {
@@ -271,19 +238,14 @@ function fromStreamEvent(
   dests: Map<string, DestinationDto>,
 ): ActivityEvent | null {
   const occurredAt = new Date(event.occurredAt).getTime();
-  // `destination.changed` events don't carry a subscription id — the
-  // narrowed switch below filters them out, but the lookup needs a guard
-  // for the type checker.
+  // Guard for the type checker: destination.changed events carry no subscriptionId.
   const subscriptionId = 'subscriptionId' in event ? event.subscriptionId : undefined;
   const sub = subscriptionId !== undefined ? subs.get(subscriptionId) : undefined;
   const subscriptionTitle = sub?.sourceTitle ?? null;
   const sourceHandle = sub?.handle ?? sub?.sourceChatId ?? null;
   const sourceMessageId = 'sourceMessageIds' in event ? (event.sourceMessageIds[0] ?? '?') : '?';
 
-  // The `forward.*` SSE variants now carry the inserted `forward_log`
-  // row ids so we can offer "view raw" on live entries without waiting
-  // for the next hydration. Index 0 is enough — the JSON viewer reads
-  // the same denormalised payload from any row of an album.
+  // Index 0 is enough — the JSON viewer reads the same denormalised payload from any row of an album.
   const forwardLogId = 'forwardLogIds' in event ? (event.forwardLogIds[0] ?? undefined) : undefined;
   const hasRawMessage = forwardLogId != null;
   switch (event.type) {
@@ -337,9 +299,7 @@ function fromStreamEvent(
       };
     }
     case 'forward.filtered': {
-      // forward.filtered doesn't carry destinationChatId — look it up from
-      // subscription instead. `destinationChatId` may be null when the
-      // subscription has been detached.
+      // No destinationChatId on this variant; look it up from the sub (null when detached).
       const destLabel =
         sub && sub.destinationChatId && dests.get(sub.destinationChatId)?.name
           ? dests.get(sub.destinationChatId)!.name
diff --git a/apps/web/src/pages/DestinationsPage.tsx b/apps/web/src/pages/DestinationsPage.tsx
index f213fcd..ae91f95 100644
--- a/apps/web/src/pages/DestinationsPage.tsx
+++ b/apps/web/src/pages/DestinationsPage.tsx
@@ -28,8 +28,6 @@ export function DestinationsPage() {
 
   const submit = (data: DestSheetSubmit) => {
     if (sheet.mode === 'edit' && sheet.initial) {
-      // Edit changes name, note, and forum topic; chatId is locked in the
-      // sheet and inviteHash is never set in edit mode.
       updateMut.mutate(
         {
           id: sheet.initial.id,
@@ -69,8 +67,7 @@ export function DestinationsPage() {
     }
   };
 
-  // Stable across renders so the memoized DestRow rows don't re-render on
-  // every parent render (deleteMut/toast are themselves stable references).
+  // Stable identity so memoized DestRow rows don't re-render on every parent render.
   const handleDelete = useCallback(
     (d: DestinationDto) => {
       deleteMut.mutate(d.id, {
diff --git a/apps/web/src/pages/FiltersPage.tsx b/apps/web/src/pages/FiltersPage.tsx
index 904af25..90db2e5 100644
--- a/apps/web/src/pages/FiltersPage.tsx
+++ b/apps/web/src/pages/FiltersPage.tsx
@@ -38,7 +38,6 @@ export function FiltersPage() {
     [catalog.data],
   );
 
-  // Default to first sub if none in URL.
   useEffect(() => {
     if (view !== 'sub') return;
     if (subId !== null) return;
@@ -48,9 +47,7 @@ export function FiltersPage() {
 
   const sheet = useFilterSheetState();
 
-  // The sub PerSubView actually shows: subId from the URL, or the first sub
-  // until the effect backfills it. Used for the sheet and the FAB so adding a
-  // filter works on the first painted frame, not just after the effect runs.
+  // URL sub, or first sub until the effect backfills it — so the FAB/sheet work on the first frame.
   const effectiveSubId = subId ?? subs.data?.[0]?.id ?? null;
   const showFab = view === 'library' || effectiveSubId !== null;
   const addCurrent = () => {
diff --git a/apps/web/src/pages/LoginPage.tsx b/apps/web/src/pages/LoginPage.tsx
index 4d32534..121bf45 100644
--- a/apps/web/src/pages/LoginPage.tsx
+++ b/apps/web/src/pages/LoginPage.tsx
@@ -27,17 +27,13 @@ export function LoginPage() {
   const [show, setShow] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [tgFailed, setTgFailed] = useState(false);
-  // Resolved Telegram initData: `undefined` while waiting for the async SDK,
-  // `null` when this isn't a Telegram launch, or the signed string.
+  // undefined = waiting for async SDK, null = not a Telegram launch, else the signed string.
   const [initData, setInitData] = useState<string | null | undefined>(() =>
     detectTelegramLaunch() ? undefined : null,
   );
-  // One-shot guard for the auto sign-in; a ref so it survives StrictMode's
-  // double-invoked effects.
+  // One-shot guard; a ref so it survives StrictMode's double-invoked effects.
   const attemptedRef = useRef(false);
 
-  // Resolve initData (waiting briefly for the async SDK on a launch) and signal
-  // the viewport ready.
   useEffect(() => {
     if (initData !== undefined) return;
     let cancelled = false;
@@ -51,19 +47,16 @@ export function LoginPage() {
     };
   }, [initData]);
 
-  // Auto sign-in via Telegram once initData and `/me` resolve; on failure the
-  // password form takes over.
   useEffect(() => {
     if (initData === undefined || me.isPending || me.data?.authenticated) return;
     if (attemptedRef.current) return;
     attemptedRef.current = true;
-    if (initData === null) return; // not a Telegram launch
+    if (initData === null) return;
     tgLogin.mutate(initData, {
       onError: () => setTgFailed(true),
     });
   }, [initData, me.isPending, me.data, tgLogin]);
 
-  // If already authed, bounce to wherever the user came from (or /).
   useEffect(() => {
     if (me.data?.authenticated) {
       const dest = (location.state as LocationState | null)?.from?.pathname ?? '/';
@@ -86,7 +79,6 @@ export function LoginPage() {
     });
   };
 
-  // Avoid a flash of the login form while /me is still resolving.
   if (me.isPending) {
     return (
       <div className="grid place-items-center min-h-dvh text-text-muted">
@@ -99,8 +91,6 @@ export function LoginPage() {
     return <Navigate to="/" replace />;
   }
 
-  // Show the spinner while initData is resolving or the auto sign-in is in
-  // flight; drop to the password form on failure or when not a Telegram launch.
   const awaitingTelegram = initData === undefined || (initData !== null && !tgFailed);
   if (awaitingTelegram) {
     return (
diff --git a/apps/web/src/pages/SettingsPage.tsx b/apps/web/src/pages/SettingsPage.tsx
index 0e06565..3522804 100644
--- a/apps/web/src/pages/SettingsPage.tsx
+++ b/apps/web/src/pages/SettingsPage.tsx
@@ -17,8 +17,6 @@ export function SettingsPage() {
     );
   }
 
-  // Each panel is a self-titled card (header carries its own title + status),
-  // stacked in a centered column.
   return (
     <div className="flex flex-col flex-1 min-h-0">
       <div className="scroll flex-1 min-h-0 px-4.5 pt-4 pb-6">
diff --git a/apps/web/src/pages/SubscriptionsPage.tsx b/apps/web/src/pages/SubscriptionsPage.tsx
index d189d26..8a589f3 100644
--- a/apps/web/src/pages/SubscriptionsPage.tsx
+++ b/apps/web/src/pages/SubscriptionsPage.tsx
@@ -34,14 +34,12 @@ export function SubscriptionsPage() {
   const navigate = useNavigate();
 
   const [openId, setOpenId] = useState<number | null>(null);
-  // Functional updater keeps deps empty so the handler stays stable across
-  // renders — the memoized SubRow only re-renders when its own sub/expanded change.
+  // Functional updater keeps deps empty so the handler stays stable for memoized SubRow.
   const handleToggle = useCallback(
     (id: number) => setOpenId((cur) => (cur === id ? null : id)),
     [],
   );
   const sheet = useSheetState<SubscriptionDto>();
-  // Subscription whose destination is being re-picked via the Forwards-to card.
   const [destPickerSub, setDestPickerSub] = useState<SubscriptionDto | null>(null);
 
   const pickDestination = (destinationId: number | null) => {
@@ -80,9 +78,7 @@ export function SubscriptionsPage() {
     } else {
       createMut.mutate(
         {
-          // Exactly one of sourceChatId / inviteHash is set — the schema
-          // refines this server-side; on the wire we send only the
-          // populated half.
+          // Exactly one of sourceChatId / inviteHash is set (server schema refines this).
           ...(data.inviteHash
             ? { inviteHash: data.inviteHash }
             : { sourceChatId: data.sourceChatId! }),
diff --git a/apps/web/src/test/setup.ts b/apps/web/src/test/setup.ts
index 1eb6798..d8b7404 100644
--- a/apps/web/src/test/setup.ts
+++ b/apps/web/src/test/setup.ts
@@ -2,9 +2,7 @@ import '@testing-library/jest-dom/vitest';
 import { afterEach, beforeEach, vi } from 'vitest';
 import { cleanup } from '@testing-library/react';
 
-// jsdom doesn't implement matchMedia. Reinstall a default before every test so
-// the afterEach restore below can't leave it returning undefined (the theme
-// provider now mounts in every render). Tests that care override the mock.
+// jsdom lacks matchMedia; reinstall per-test so afterEach's restoreAllMocks can't leave it undefined.
 beforeEach(() => {
   window.matchMedia = vi.fn().mockImplementation((query: string) => ({
     matches: false,
diff --git a/compose.yaml b/compose.yaml
index 8b1f7f2..a60f842 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -1,47 +1,18 @@
-# Production compose for tg-feed.
-# Server-side workflow:
-#   mkdir -p data && cp .env.example .env  # edit .env
-#   docker compose pull && docker compose up -d
-# Update:
-#   docker compose pull && docker compose up -d
-# Pin a version: set TG_FEED_VERSION=0.2.0 in .env (or env-export).
+# Example deploy:
+#   cp .env.example .env   # fill it in
+#   docker compose up -d
 
 services:
   tg-feed:
     image: ghcr.io/rzcoder/tg-feed:${TG_FEED_VERSION:-latest}
     container_name: tg-feed
     restart: unless-stopped
-    # Match host UID/GID so files written into ./data are owned by the
-    # invoking user. Override with UID=$(id -u) GID=$(id -g) if your
-    # host user isn't 1000:1000.
-    user: '${UID:-1000}:${GID:-1000}'
-    # Both sides use the same port so a custom PORT in .env Just Works
-    # (compose interpolates PORT from .env-in-cwd; the app reads it from
-    # env_file inside the container).
-    #
-    # Bind to loopback so the shared-password auth surface isn't exposed
-    # publicly when the host has a routable IP. Front with a reverse proxy
-    # (Caddy/nginx/Cloudflare Tunnel) that terminates TLS and forwards to
-    # 127.0.0.1:${PORT}. Override BIND_HOST=0.0.0.0 in `.env` if you really
-    # do want to expose the port directly (e.g. on a LAN-only box).
     ports:
-      - '${BIND_HOST:-127.0.0.1}:${PORT:-3000}:${PORT:-3000}'
+      - '3000:3000'
     env_file:
       - .env
     volumes:
-      - ./data:/app/data
-    # TCP-level liveness — the server has no dedicated /health endpoint,
-    # and every HTTP route requires auth. "Node is listening on the port"
-    # is good enough to drive restart-on-failure.
-    healthcheck:
-      test:
-        [
-          'CMD',
-          'node',
-          '-e',
-          "require('node:net').connect(Number(process.env.PORT||3000)).on('connect', function(){this.end();process.exit(0)}).on('error', () => process.exit(1))",
-        ]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 20s
+      - tg-feed-data:/app/data
+
+volumes:
+  tg-feed-data:
diff --git a/package.json b/package.json
index 62b20bc..0311267 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "tg-feed",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Personal Telegram channel forwarding userbot with web UI for managing subscriptions and filters",
   "private": true,
   "license": "MIT",
diff --git a/packages/shared/src/api.ts b/packages/shared/src/api.ts
index 8327ebe..4cc34c5 100644
--- a/packages/shared/src/api.ts
+++ b/packages/shared/src/api.ts
@@ -1,19 +1,5 @@
-/**
- * HTTP API DTOs and request schemas.
- *
- * Single source of truth for the wire format between server and web.
- * Server validates requests with these zod schemas; web infers TS types
- * from them.
- *
- * Wire format conventions:
- *   - dates serialize as ISO 8601 strings; the server `.toISOString()`s
- *     before responding and the web does `new Date(iso)` if it needs a Date
- *   - list endpoints return `{ items: [...] }` envelopes for forwards-
- *     compatible pagination later
- *   - PATCH bodies are explicit (never `.partial()` of a create schema —
- *     `.default()` calls on field schemas would make Input ≠ Output and
- *     `.partial()` discards that distinction silently)
- */
+// Wire-format source of truth: server validates with these schemas, web infers types.
+// PATCH bodies are explicit (not `.partial()` of create — `.default()` fields make Input ≠ Output).
 import { z } from 'zod';
 import {
   FILTER_RULE_TYPES,
@@ -28,16 +14,12 @@ import {
 } from './filters.js';
 import { FORWARD_LOG_STATUSES } from './forwardLog.js';
 
-// `filterRuleParamsSchemas` re-export keeps a single import surface for
-// consumers that need both the catalog wire types and the per-rule params
-// schemas (form generation in the web UI).
 export { filterRuleParamsSchemas };
 
 // --- Auth -------------------------------------------------------------
 
 export const loginRequestSchema = z.object({
-  // Cap the password length so a multi-MB string can't burn CPU through the
-  // SHA-256 compare. Login is rate-limited but free CPU is still free CPU.
+  // Cap length so a multi-MB string can't burn CPU through the SHA-256 compare.
   password: z.string().min(1).max(256),
 });
 export type LoginRequest = z.infer<typeof loginRequestSchema>;
@@ -47,12 +29,8 @@ export const loginResponseSchema = z.object({
 });
 export type LoginResponse = z.infer<typeof loginResponseSchema>;
 
-// Telegram Web App sign-in. The web client running inside Telegram posts the
-// raw `window.Telegram.WebApp.initData` query string; the server verifies its
-// HMAC against the bot token and checks the embedded user against the admin
-// allowlist. Reuses `loginResponseSchema` for the success body. The 8 KiB cap
-// is generous — real initData payloads are a few hundred bytes — and bounds
-// the HMAC work on this unauthenticated route.
+// Raw `WebApp.initData`; server verifies its HMAC vs bot token + admin allowlist.
+// 8 KiB cap bounds HMAC work on this unauthenticated route (real payloads are ~hundreds of bytes).
 export const telegramAuthRequestSchema = z.object({
   initData: z.string().min(1).max(8192),
 });
@@ -65,23 +43,19 @@ export type MeResponse = z.infer<typeof meResponseSchema>;
 
 // --- Access status (shared by destinations + subscription source) -----
 
-// Whether the userbot can currently see/post to a chat. Written by the
-// access monitor on the periodic sweep and on subscription create. The UI
-// renders 'no_access' as a red "no access" badge.
+// Whether the userbot can currently see/post to a chat; written by the access monitor's sweep.
 export const accessStatusSchema = z.enum(['ok', 'no_access']);
 export type AccessStatus = z.infer<typeof accessStatusSchema>;
 
 // --- Destinations -----------------------------------------------------
 
-// Numeric Telegram chat id; supergroups/channels start with -100. We allow
-// any integer-shaped string (negative or positive) of at least 6 digits.
+// Numeric Telegram chat id; supergroups/channels start with -100.
 export const telegramChatIdSchema = z
   .string()
   .min(1)
   .regex(/^-?\d{6,}$/, 'expected a numeric Telegram chat id');
 
-// Forum topic's `top_msg_id` in storage form — a positive integer string,
-// kept as text for parity with the other Telegram ids.
+// Forum topic `top_msg_id`; text for parity with the other Telegram ids.
 export const forumTopicIdSchema = z
   .string()
   .min(1)
@@ -92,28 +66,14 @@ export const destinationDtoSchema = z.object({
   name: z.string(),
   chatId: z.string(),
   note: z.string().nullable(),
-  /**
-   * Forum topic this destination forwards into, or null for "no explicit
-   * topic" — the General topic on a forum supergroup, or any non-forum
-   * chat. `topicId` is the topic's `top_msg_id`; `topicTitle` is cached at
-   * create/edit time so the UI renders without a live topics lookup.
-   */
+  // topicId = topic's top_msg_id; null = General/no-topic. topicTitle cached at write time.
   topicId: z.string().nullable(),
   topicTitle: z.string().nullable(),
-  /**
-   * Channel/chat profile photo as a `data:image/jpeg;base64,...` URL.
-   * Null when not yet fetched (e.g. fresh migrations, Telegram-less boots,
-   * channels with no photo). The web UI falls back to a lucide icon.
-   */
+  // `data:image/jpeg;base64,...`; null until fetched (UI falls back to a lucide icon).
   iconDataUrl: z.string().nullable(),
   usageCount: z.number().int().nonnegative(),
-  /**
-   * Whether the userbot can currently access this destination. 'ok' until
-   * the periodic sweep proves otherwise. Drives the "no access" badge in
-   * the web UI.
-   */
+  // 'ok' until the periodic sweep proves otherwise.
   accessStatus: accessStatusSchema,
-  /** ISO timestamp of the last access check; null until the first sweep. */
   accessCheckedAt: z.string().nullable(),
   createdAt: z.string(),
 });
@@ -124,26 +84,20 @@ export const destinationListResponseSchema = z.object({
 });
 export type DestinationListResponse = z.infer<typeof destinationListResponseSchema>;
 
-// Telegram private invite hash extracted from `t.me/+HASH`. Same character
-// set as a username plus `-`; length capped well above any real-world
-// invite (typical hashes are ~16 chars, but the format is opaque).
+// Private invite hash from `t.me/+HASH` (opaque format; cap well above real-world ~16 chars).
 export const telegramInviteHashSchema = z
   .string()
   .min(1)
   .max(64)
   .regex(/^[A-Za-z0-9_-]+$/, 'expected a Telegram invite hash');
 
-// Either `chatId` (already-known numeric id; existing flow) or `inviteHash`
-// (private invite — server will call `messages.ImportChatInvite` to join
-// and derive the chatId). Exactly one is required; the refine guards both
-// "neither provided" and "both provided".
+// `inviteHash` path makes the server `ImportChatInvite` to join and derive the chatId.
 export const createDestinationRequestSchema = z
   .object({
     name: z.string().min(1).max(80),
     chatId: telegramChatIdSchema.optional(),
     inviteHash: telegramInviteHashSchema.optional(),
     note: z.string().max(200).optional(),
-    /** Forum topic to forward into; omit or null for the General topic / a non-forum chat. */
     topicId: forumTopicIdSchema.nullable().optional(),
     topicTitle: z.string().max(200).nullable().optional(),
   })
@@ -152,9 +106,7 @@ export const createDestinationRequestSchema = z
   });
 export type CreateDestinationRequest = z.infer<typeof createDestinationRequestSchema>;
 
-// `POST /api/destinations/resolve` — preview only, no DB write. Mirrors
-// the subscription resolve endpoint. The UI debounces input changes and
-// then submits the resolved fields to `POST /api/destinations` to commit.
+// `POST /api/destinations/resolve` — preview only, no DB write.
 export const resolveDestinationRequestSchema = z.object({
   input: z.string().min(1).max(200),
 });
@@ -164,16 +116,11 @@ export const resolveDestinationResponseSchema = z.object({
   /** null only for not-yet-joined private invites — UI should fall back to inviteHash. */
   chatId: z.string().nullable(),
   title: z.string(),
-  /** `@username` when known. */
   handle: z.string().nullable(),
   /** non-null for `t.me/+HASH` inputs; carries to the create endpoint. */
   inviteHash: z.string().nullable(),
   alreadyMember: z.boolean(),
-  /**
-   * Whether the resolved chat is a forum supergroup (has topics). Drives the
-   * topic picker in the Add-destination UI. False for not-yet-joined private
-   * invites — the chat is unknown until the userbot joins.
-   */
+  // False for not-yet-joined private invites — the chat is unknown until the userbot joins.
   isForum: z.boolean(),
 });
 export type ResolveDestinationResponse = z.infer<typeof resolveDestinationResponseSchema>;
@@ -183,7 +130,6 @@ export const updateDestinationRequestSchema = z
     name: z.string().min(1).max(80).optional(),
     chatId: telegramChatIdSchema.optional(),
     note: z.string().max(200).nullable().optional(),
-    /** Re-target the forum topic; null clears it back to General / no topic. */
     topicId: forumTopicIdSchema.nullable().optional(),
     topicTitle: z.string().max(200).nullable().optional(),
   })
@@ -192,22 +138,18 @@ export const updateDestinationRequestSchema = z
   });
 export type UpdateDestinationRequest = z.infer<typeof updateDestinationRequestSchema>;
 
-// `POST /api/destinations/topics` — list a forum supergroup's topics so the
-// UI can offer a picker. Read-only; takes a resolved numeric chat id.
 export const listForumTopicsRequestSchema = z.object({
   chatId: telegramChatIdSchema,
 });
 export type ListForumTopicsRequest = z.infer<typeof listForumTopicsRequestSchema>;
 
 export const forumTopicSchema = z.object({
-  /** The topic's `top_msg_id` in storage form. */
-  id: z.string(),
+  id: z.string(), // top_msg_id
   title: z.string(),
 });
 export type ForumTopic = z.infer<typeof forumTopicSchema>;
 
 export const listForumTopicsResponseSchema = z.object({
-  /** False when the chat isn't a forum — the UI then hides the picker. */
   isForum: z.boolean(),
   topics: z.array(forumTopicSchema),
 });
@@ -219,46 +161,22 @@ export const subscriptionDtoSchema = z.object({
   id: z.number().int(),
   sourceChatId: z.string(),
   sourceTitle: z.string(),
-  /** `@channel` handle, populated by the resolve endpoint at create time. */
   handle: z.string().nullable(),
-  /**
-   * Source channel profile photo as a `data:image/jpeg;base64,...` URL,
-   * or null when not yet fetched. Same lifecycle as `destinationDtoSchema.iconDataUrl`.
-   */
   iconDataUrl: z.string().nullable(),
-  /**
-   * FK to the destination chat. Nullable: a subscription can exist without
-   * a destination (created via Settings → Import when the destination is
-   * missing, or detached by the user). The forwarder skips such rows; the
-   * UI shows a "no destination" badge.
-   */
+  // null = detached: subscription with no destination; forwarder skips it.
   destinationId: z.number().int().nullable(),
-  /** Joined from `destinations` for UI rendering convenience; null when detached. */
   destinationName: z.string().nullable(),
   destinationChatId: z.string().nullable(),
   enabled: z.boolean(),
-  /** Count of own per-sub filters + attached library filters. */
+  // own per-sub filters + attached library filters
   filterCount: z.number().int().nonnegative(),
-  /** Count of forward_log rows with status='sent' for this subscription. */
+  // forward_log rows with status='sent'
   forwardedCount: z.number().int().nonnegative(),
-  /** Library filter ids attached to this subscription (sorted ascending). */
   libraryFilterIds: z.array(z.number().int().positive()),
-  /**
-   * ISO timestamp of the last `CHAT_FORWARDS_RESTRICTED` rejection from
-   * the source channel; null otherwise. Drives the "noforwards" badge in
-   * the web UI. Cleared by the server on the next successful forward.
-   */
+  // last CHAT_FORWARDS_RESTRICTED rejection; cleared on the next successful forward.
   forwardingRestrictedAt: z.string().nullable(),
-  /**
-   * Whether the userbot can currently read messages from the source
-   * channel. Set on subscription create (after `channels.JoinChannel`) and
-   * refreshed by the access monitor's periodic sweep. Drives the "no
-   * access" badge.
-   */
   sourceAccessStatus: accessStatusSchema,
-  /** ISO timestamp of the last access check on the source. */
   sourceAccessCheckedAt: z.string().nullable(),
-  /** Joined from `destinations.access_status`; null when detached. */
   destinationAccessStatus: accessStatusSchema.nullable(),
   createdAt: z.string(),
 });
@@ -269,12 +187,7 @@ export const subscriptionListResponseSchema = z.object({
 });
 export type SubscriptionListResponse = z.infer<typeof subscriptionListResponseSchema>;
 
-// Shape of an inline-filter input shared by `createSubscriptionRequestSchema`
-// (bulk inline-filters at sub-create time) and `createSubscriptionFilterRequestSchema`
-// (granular inline-filter create at `POST /subscriptions/:id/filters`). The
-// discriminated union forces `params` to match `ruleType` in one parse.
-// `mode` is optional in the wire input; the server defaults to 'include'
-// (matches the legacy AND-pass semantics for clients predating the column).
+// Discriminated union forces `params` to match `ruleType`. `mode` optional; server defaults 'include'.
 export const inlineFilterInputSchema = z.discriminatedUnion('ruleType', [
   z.object({
     ruleType: z.literal('text-contains'),
@@ -315,13 +228,7 @@ export const inlineFilterInputSchema = z.discriminatedUnion('ruleType', [
 ]);
 export type InlineFilterInput = z.infer<typeof inlineFilterInputSchema>;
 
-// Hard caps shared by create + patch + export-import. Pick generous values
-// that still bound the fan-out of a single request into the DB:
-//   - 64 chars for a chat id (Telegram ids are <20 chars; allow slack)
-//   - 64 chars for `@handle`
-//   - 255 chars for the human-supplied title (matches a typical DB varchar cap)
-//   - 200 attachments / inline filters per subscription (UI would be unusable
-//     past that; an import file with thousands of attachments is misuse)
+// Generous caps that still bound the DB fan-out of a single create/patch/import request.
 const SOURCE_CHAT_ID_MAX = 64;
 const HANDLE_MAX = 64;
 const SOURCE_TITLE_MAX = 255;
@@ -329,33 +236,15 @@ const PER_SUB_ARRAY_MAX = 200;
 
 export const createSubscriptionRequestSchema = z
   .object({
-    /**
-     * Either `sourceChatId` (resolved up-front via the resolve endpoint or
-     * supplied directly as a numeric id) or `inviteHash` (private invite —
-     * server calls `messages.ImportChatInvite` to join and derive the
-     * resulting chatId). Exactly one is required.
-     */
+    // `inviteHash` path makes the server `ImportChatInvite` to join and derive the chatId.
     sourceChatId: z.string().min(1).max(SOURCE_CHAT_ID_MAX).optional(),
     inviteHash: telegramInviteHashSchema.optional(),
     sourceTitle: z.string().min(1).max(SOURCE_TITLE_MAX),
     handle: z.string().min(1).max(HANDLE_MAX).optional(),
-    /**
-     * Optional. When omitted (or null), the subscription is created in a
-     * detached state — no forwarding until the user attaches a destination.
-     * Used by the import flow when the source's destination is missing.
-     */
+    // null/omitted = created detached: no forwarding until a destination is attached.
     destinationId: z.number().int().positive().nullable().optional(),
     enabled: z.boolean().optional(),
-    /**
-     * Library filter ids to attach at create time. Bulk-replace semantics:
-     * an empty array attaches none; absent field = same as empty.
-     */
     libraryFilterIds: z.array(z.number().int().positive()).max(PER_SUB_ARRAY_MAX).optional(),
-    /**
-     * Private inline filters to materialize on the new subscription. Bulk
-     * semantics: absent or `[]` means none. The discriminated union enforces
-     * per-rule param validity.
-     */
     inlineFilters: z.array(inlineFilterInputSchema).max(PER_SUB_ARRAY_MAX).optional(),
   })
   .refine((b) => (b.sourceChatId ? 1 : 0) + (b.inviteHash ? 1 : 0) === 1, {
@@ -363,29 +252,16 @@ export const createSubscriptionRequestSchema = z
   });
 export type CreateSubscriptionRequest = z.infer<typeof createSubscriptionRequestSchema>;
 
-// `sourceChatId` and `handle` are intentionally immutable — to change the
-// channel, delete and recreate. Other fields are mutable. `.refine` rejects
-// an empty PATCH body so callers don't accidentally no-op.
+// `sourceChatId`/`handle` intentionally immutable — delete and recreate to change the channel.
 export const updateSubscriptionRequestSchema = z
   .object({
     sourceTitle: z.string().min(1).max(SOURCE_TITLE_MAX).optional(),
-    /**
-     * Number to attach/replace; explicit `null` to detach. `undefined`
-     * (omitted) leaves the existing value alone.
-     */
+    // number = attach/replace; null = detach; omitted = leave alone.
     destinationId: z.number().int().positive().nullable().optional(),
     enabled: z.boolean().optional(),
-    /**
-     * Bulk-replace the attached library filter set. Absent = leave alone;
-     * empty array = detach all. Granular attach/detach also available at
-     * `/api/subscriptions/:id/library-filters[/:libId]`.
-     */
+    // Bulk-replace; absent = leave alone, [] = detach all. Granular CRUD on the sub-routes.
     libraryFilterIds: z.array(z.number().int().positive()).max(PER_SUB_ARRAY_MAX).optional(),
-    /**
-     * Bulk-replace the private inline filter set. Absent = leave alone;
-     * empty array = drop all. Granular CRUD also available at
-     * `/api/subscriptions/:id/filters[/:filterId]`.
-     */
+    // Bulk-replace; absent = leave alone, [] = drop all. Granular CRUD on the sub-routes.
     inlineFilters: z.array(inlineFilterInputSchema).max(PER_SUB_ARRAY_MAX).optional(),
   })
   .refine((data) => Object.keys(data).length > 0, {
@@ -393,8 +269,7 @@ export const updateSubscriptionRequestSchema = z
   });
 export type UpdateSubscriptionRequest = z.infer<typeof updateSubscriptionRequestSchema>;
 
-// `POST /api/subscriptions/resolve` — preview only, no DB write. The UI
-// then submits the resolved fields to `POST /api/subscriptions`.
+// `POST /api/subscriptions/resolve` — preview only, no DB write.
 export const resolveSubscriptionRequestSchema = z.object({
   input: z.string().min(1).max(200),
 });
@@ -428,18 +303,10 @@ export const subscriptionFilterListResponseSchema = z.object({
 });
 export type SubscriptionFilterListResponse = z.infer<typeof subscriptionFilterListResponseSchema>;
 
-// `POST /subscriptions/:id/filters` body — same discriminated shape as
-// `inlineFilterInputSchema`, exported under the route-specific name so
-// existing imports keep working.
 export const createSubscriptionFilterRequestSchema = inlineFilterInputSchema;
 export type CreateSubscriptionFilterRequest = z.infer<typeof createSubscriptionFilterRequestSchema>;
 
-// PATCH body — `params` is loose at this layer (`z.record`), and the route
-// handler validates it against the matching `filterRuleParamsSchemas` for
-// the existing row's `ruleType`. Keeping `ruleType` immutable post-create
-// matches the create discriminator (changing rule type = different rule
-// semantics; delete + re-add). `mode` is mutable — flipping include/exclude
-// is exactly the kind of tweak callers do post-create.
+// `params` loose here (z.record); the route validates it against the row's ruleType. ruleType immutable.
 export const updateSubscriptionFilterRequestSchema = z
   .object({
     params: z.record(z.string(), z.unknown()).optional(),
@@ -459,7 +326,7 @@ export const libraryFilterDtoSchema = z.object({
   ruleType: z.enum(FILTER_RULE_TYPES),
   params: z.record(z.string(), z.unknown()),
   mode: filterModeSchema,
-  /** Number of subscriptions this library filter is attached to. */
+  // subscriptions this filter is attached to
   usageCount: z.number().int().nonnegative(),
   createdAt: z.string(),
 });
@@ -470,10 +337,7 @@ export const libraryFilterListResponseSchema = z.object({
 });
 export type LibraryFilterListResponse = z.infer<typeof libraryFilterListResponseSchema>;
 
-// Hand-listed discriminated union (mirrors `createSubscriptionFilterRequestSchema`)
-// — z.discriminatedUnion needs a tuple of literal-typed variants. The
-// extra `name` field is the only structural difference. `mode` is optional;
-// the route defaults to 'include' when absent.
+// Same shape as the subscription-filter union plus `name`. `mode` optional; route defaults 'include'.
 export const createLibraryFilterRequestSchema = z.discriminatedUnion('ruleType', [
   z.object({
     name: z.string().min(1).max(80),
@@ -514,9 +378,7 @@ export const createLibraryFilterRequestSchema = z.discriminatedUnion('ruleType',
 ]);
 export type CreateLibraryFilterRequest = z.infer<typeof createLibraryFilterRequestSchema>;
 
-// `ruleType` is immutable post-creation — same precedent as
-// `subscription_filters`: changing the rule type is delete + re-add. The
-// route handler validates `params` against the existing row's `ruleType`.
+// `ruleType` immutable post-creation; the route validates `params` against the row's ruleType.
 export const updateLibraryFilterRequestSchema = z
   .object({
     name: z.string().min(1).max(80).optional(),
@@ -528,9 +390,7 @@ export const updateLibraryFilterRequestSchema = z
   });
 export type UpdateLibraryFilterRequest = z.infer<typeof updateLibraryFilterRequestSchema>;
 
-// Attach an existing library filter to a subscription. Body just carries
-// the library filter id; the URL captures the subscription. M:N row is
-// idempotent — re-attaching is a no-op (PK violation suppressed).
+// Idempotent: re-attaching is a no-op (PK violation suppressed).
 export const attachLibraryFilterRequestSchema = z.object({
   libraryFilterId: z.number().int().positive(),
 });
@@ -559,7 +419,6 @@ export const statsDigestTimeSchema = z
   .string()
   .regex(/^([01]\d|2[0-3]):[0-5]\d$/, 'expected HH:MM (24-hour)');
 
-/** Whether a string is a time zone the runtime's Intl knows about. */
 export function isValidTimeZone(tz: string): boolean {
   try {
     new Intl.DateTimeFormat('en-US', { timeZone: tz });
@@ -573,22 +432,14 @@ export const statsDigestTimezoneSchema = z.string().min(1).refine(isValidTimeZon
   message: 'invalid IANA time zone',
 });
 
-/**
- * The five stats-digest knobs. `.catch(default)` per field means a missing OR
- * malformed value reads back as the documented default — so this one schema
- * doubles as the server's defensive reader for the (possibly hand-edited) DB
- * row and as the shape that fills older settings payloads. When enabled, the
- * bot DMs admins a forwarded/filtered/error summary once a day or week at
- * `statsDigestTime` on the chosen day, interpreted in `statsDigestTimezone`.
- */
+// Per-field `.catch(default)` makes this double as the defensive reader for a hand-edited DB row.
 export const statsDigestSettingsSchema = z.object({
   statsDigestEnabled: z.boolean().catch(false),
   statsDigestFrequency: statsDigestFrequencySchema.catch('daily'),
-  /** 0 = Sunday … 6 = Saturday. Used only when frequency is 'weekly'. */
+  // 0 = Sunday … 6 = Saturday; used only when frequency is 'weekly'.
   statsDigestDayOfWeek: z.number().int().min(0).max(6).catch(1),
   statsDigestTime: statsDigestTimeSchema.catch('09:00'),
-  /** IANA zone the time is read in. Set automatically by the web (the
-   * operator's browser zone); 'UTC' is only the pre-first-save fallback. */
+  // Set from the operator's browser zone on save; 'UTC' is only the pre-first-save fallback.
   statsDigestTimezone: statsDigestTimezoneSchema.catch('UTC'),
 });
 export type StatsDigestSettings = z.infer<typeof statsDigestSettingsSchema>;
@@ -596,19 +447,13 @@ export type StatsDigestSettings = z.infer<typeof statsDigestSettingsSchema>;
 export const settingsDtoSchema = z
   .object({
     delayMs: z.number().int().positive(),
-    /**
-     * Window (ms) the album debouncer waits for additional members of a
-     * Telegram media group before forwarding. Increase on slow links where
-     * album members arrive >2 s apart and end up fragmented; lower if you
-     * want forwards to happen sooner.
-     */
+    // ms the album debouncer waits for more media-group members; raise on slow links to avoid fragmenting.
     albumDebounceMs: z.number().int().positive(),
   })
   .merge(statsDigestSettingsSchema);
 export type SettingsDto = z.infer<typeof settingsDtoSchema>;
 
-// Every field optional so the client can update one knob without overwriting
-// the others — the server merges into the existing row.
+// Every field optional; the server merges into the existing row.
 export const updateSettingsRequestSchema = z
   .object({
     delayMs: z.number().int().positive().optional(),
@@ -637,12 +482,7 @@ export const forwardLogEntryDtoSchema = z.object({
   status: z.enum(FORWARD_LOG_STATUSES),
   error: z.string().nullable(),
   createdAt: z.string(),
-  /**
-   * Whether the row has a stored JSON snapshot of the raw Telegram message.
-   * Fetch the actual payload via `GET /forward-log/:id/raw` on demand —
-   * the raw JSON is intentionally kept off the list endpoint to keep page
-   * responses small.
-   */
+  // Raw payload fetched on demand via `GET /forward-log/:id/raw`; kept off the list to keep it small.
   hasRawMessage: z.boolean(),
 });
 export type ForwardLogEntryDto = z.infer<typeof forwardLogEntryDtoSchema>;
@@ -653,13 +493,7 @@ export const forwardLogResponseSchema = z.object({
 });
 export type ForwardLogResponse = z.infer<typeof forwardLogResponseSchema>;
 
-/**
- * Response for `GET /forward-log/:id/raw`. `rawMessage` is the JSON snapshot
- * stored at forward time — a plain object for single-message forwards, an
- * array of objects (sorted ascending by source message id) for album
- * batches. `null` for rows that pre-date the feature or for events that
- * deliberately skipped capture (e.g. `MessageEmpty`).
- */
+// rawMessage: single forward = object; album = array sorted ascending by source msg id; null if uncaptured.
 export const forwardLogRawResponseSchema = z.object({
   rawMessage: z.unknown().nullable(),
 });
@@ -682,17 +516,9 @@ export type ForwardLogQuery = z.infer<typeof forwardLogQuerySchema>;
 // --- System status ----------------------------------------------------
 
 export const telegramStatusSchema = z.object({
-  /**
-   * Lifecycle phase. `connecting` covers the boot window before the gramjs
-   * client has finished `client.connect()` (and the listener / monitors are
-   * attached). The web UI uses this to show a neutral "starting up" state
-   * instead of the disconnected alert during normal dev reloads.
-   * `connected: boolean` is kept as a redundant convenience equal to
-   * `state === 'connected'` so existing call sites don't need to be updated.
-   */
+  // `connecting` = boot window before `client.connect()` finishes (UI shows "starting up", not disconnected).
   state: z.enum(['connecting', 'connected', 'disconnected']),
-  connected: z.boolean(),
-  /** Human-readable reason; present when state is 'connecting' or 'disconnected'. */
+  connected: z.boolean(), // redundant convenience for `state === 'connected'`
   reason: z.string().optional(),
 });
 export type TelegramStatus = z.infer<typeof telegramStatusSchema>;
diff --git a/packages/shared/src/botConfig.ts b/packages/shared/src/botConfig.ts
index 9cd0271..1cdc285 100644
--- a/packages/shared/src/botConfig.ts
+++ b/packages/shared/src/botConfig.ts
@@ -1,36 +1,18 @@
-/**
- * Wire-format schemas for the DB-backed bot configuration exposed by
- * `apps/server/src/api/routes/botConfig.ts` and consumed by the Settings
- * page's Bot section.
- *
- * The GET payload is *masked* — it never returns the bot token, only whether
- * one is configured and from where (`db` | `env`). The bot token, admin
- * allowlist and public URL each resolve DB-first with an env fallback, so each
- * carries its own `*Source` field.
- */
+// Wire schemas for the DB-backed bot config (Settings → Bot). GET is masked (never returns the token); token/admins/publicUrl each resolve DB-first with an env fallback, hence the per-field *Source.
 import { z } from 'zod';
 
-/** Source of a resolved field: the DB row wins over env. */
 export const botConfigSourceSchema = z.enum(['db', 'env']);
 export type BotConfigSource = z.infer<typeof botConfigSourceSchema>;
 
-// BotFather tokens are `<bot_id>:<auth_token>` — digits, a colon, then ~35
-// chars of base64url-ish auth. Validate loosely so a future format tweak
-// doesn't reject a working token, but tightly enough to reject pasted junk.
+// BotFather token <bot_id>:<auth>; loose enough to survive a format tweak, tight enough to reject junk.
 export const botTokenSchema = z
   .string()
   .regex(/^\d{5,}:[A-Za-z0-9_-]{30,}$/, 'expected a BotFather token like 12345:ABC...');
 
-// Telegram user ids are 64-bit; keep them as strings so large ids stay
-// lossless (the env parser does the same). Numeric-only, deduped server-side.
+// 64-bit ids kept as strings to stay lossless; deduped server-side.
 export const botAdminIdSchema = z.string().regex(/^\d+$/, 'expected a numeric Telegram user id');
 
-/**
- * An admin allowlist entry. `id` is what actually gates the bot; the display
- * fields are looked up from `@username` (like a channel's title) so the UI
- * can render a name instead of a bare id. They're `null` for admins that come
- * from the env var (raw ids, no lookup) or were added by id directly.
- */
+// display fields are null for env admins (raw ids, no @username lookup).
 export const botAdminSchema = z.object({
   id: botAdminIdSchema,
   displayName: z.string().nullable(),
@@ -39,32 +21,21 @@ export const botAdminSchema = z.object({
 export type BotAdmin = z.infer<typeof botAdminSchema>;
 
 export const botConfigInfoSchema = z.object({
-  /** True when the resolver picked up a token (DB or env). */
   tokenConfigured: z.boolean(),
   tokenSource: botConfigSourceSchema.nullable(),
-  /** Whether `TG_SESSION_ENCRYPTION_KEY` is configured (gates token writes). */
+  // Gates token writes.
   encryptionKeyConfigured: z.boolean(),
-  /**
-   * True when a token is stored in the DB but encrypted with a different
-   * `TG_SESSION_ENCRYPTION_KEY` than the one currently configured. The
-   * resolver falls through to env; the UI surfaces a "key mismatch" hint.
-   */
+  // DB token encrypted under a different key than the current one; resolver falls through to env.
   keyFingerprintMismatch: z.boolean(),
   admins: z.array(botAdminSchema),
   adminsSource: botConfigSourceSchema.nullable(),
   publicUrl: z.string().nullable(),
   publicUrlSource: botConfigSourceSchema.nullable(),
-  /** Whether the long-polling bot is currently running. */
   botRunning: z.boolean(),
 });
 export type BotConfigInfo = z.infer<typeof botConfigInfoSchema>;
 
-/**
- * Partial update. Per field: omitted = leave unchanged, `null` = clear the
- * DB value (fall back to env), a value = set it. At least one field must be
- * present. `admins` carries the full desired list (the UI adds/removes
- * entries client-side, then saves the whole set).
- */
+// Partial update, ≥1 field: omitted = unchanged, null = clear (fall back to env), value = set; `admins` is the full desired list.
 export const updateBotConfigRequestSchema = z
   .object({
     token: botTokenSchema.nullable().optional(),
@@ -78,12 +49,7 @@ export type UpdateBotConfigRequest = z.infer<typeof updateBotConfigRequestSchema
 
 // --- Admin lookup (resolve @username → user) ------------------------------
 
-/**
- * `POST /api/config/bot/resolve-admin` — preview only, no write. Resolves a
- * `@username` / `t.me/username` / numeric user id to a Telegram *user* (the
- * same resolver that backs channel lookup, but rejecting channels/groups).
- * The UI debounces input and then submits the resolved entry into `admins`.
- */
+// resolve-admin: preview only, resolves @username / t.me / id to a Telegram user (rejects channels/groups).
 export const resolveBotAdminRequestSchema = z.object({
   query: z.string().min(1).max(128),
 });
diff --git a/packages/shared/src/events.ts b/packages/shared/src/events.ts
index 8773236..427bdf7 100644
--- a/packages/shared/src/events.ts
+++ b/packages/shared/src/events.ts
@@ -1,18 +1,6 @@
-/**
- * Stream event taxonomy — the wire format for `GET /api/stream` (SSE).
- *
- * The internal event bus (`apps/server/src/events/bus.ts`) accepts a
- * `StreamEventInput` and stamps `occurredAt` to produce the `StreamEvent`
- * that goes on the wire. Per-variant fields live next to the discriminator
- * tag rather than behind `Omit<Union, 'occurredAt'>` because `Omit` doesn't
- * always preserve discriminated-union narrowing across the codebase's TS
- * surface — co-locating keeps narrowing reliable.
- *
- * `forward.filtered` peers `forward_log.status='filtered'` from Ch 6 so the
- * Ch 13 Activity feed can render filtered messages alongside forwarded ones.
- * `subscription.changed` is intentionally narrow: filter mutations do NOT
- * emit events (the Ch 11 filter UI manages its own invalidation).
- */
+// SSE wire format for GET /api/stream; the bus stamps occurredAt onto StreamEventInput.
+// Fields are inlined (not Omit<Union,'occurredAt'>) so discriminated-union narrowing stays reliable.
+// subscription.changed is intentionally narrow: filter mutations don't emit (the filter UI self-invalidates).
 
 export const STREAM_EVENT_TYPES = [
   'forward.started',
@@ -43,11 +31,7 @@ export type StreamEventInput =
       destinationChatId: string;
       sourceMessageIds: string[];
       destMessageIds: string[];
-      /**
-       * Inserted `forward_log` row ids — one per source message id, in the
-       * same order. Lets the Activity UI fetch the persisted raw-message
-       * JSON for a live event without round-tripping through a list refresh.
-       */
+      // forward_log row ids, one per sourceMessageId, same order.
       forwardLogIds: number[];
     }
   | {
diff --git a/packages/shared/src/exportImport.ts b/packages/shared/src/exportImport.ts
index 896ace6..eb834c5 100644
--- a/packages/shared/src/exportImport.ts
+++ b/packages/shared/src/exportImport.ts
@@ -1,14 +1,5 @@
-/**
- * Settings → Data export/import wire format.
- *
- * The export envelope is a versioned JSON document so a future schema bump
- * can keep parsing older files. v1 is the initial format.
- *
- * IDs are intentionally NOT exported — the import remaps via natural keys
- * (`destination = (chatId, name)`, `libraryFilter = name`,
- * `subscription = sourceChatId`) so a file produced on instance A can be
- * applied to instance B without primary-key collisions.
- */
+// Versioned export/import wire format. IDs are NOT exported; import remaps via natural keys
+// (destination=(chatId,name), libraryFilter=name, subscription=sourceChatId) to avoid PK collisions across instances.
 import { z } from 'zod';
 import {
   statsDigestFrequencySchema,
@@ -25,30 +16,18 @@ import {
   textRegexParamsSchema,
 } from './filters.js';
 
-// v2 (2026-05): extended `appSettings` with an optional `telegramAccount`
-// sub-object carrying the encrypted session string + key fingerprint. v1
-// files (no `telegramAccount` field) round-trip unchanged through v2
-// importers; v2 files are rejected by v1 importers via the existing
-// `schemaVersion > EXPORT_SCHEMA_VERSION` guard.
 export const EXPORT_SCHEMA_VERSION = 2;
 
-// --- Section: destinations -------------------------------------------------
-
 export const exportedDestinationSchema = z.object({
   name: z.string().min(1).max(80),
   chatId: z.string().min(1).max(64),
   note: z.string().max(200).nullable().optional(),
-  /** Forum topic routing; null/omitted for General / non-forum chats. */
+  // forum topic; null/omitted = General / non-forum
   topicId: z.string().min(1).max(19).nullable().optional(),
   topicTitle: z.string().max(200).nullable().optional(),
 });
 export type ExportedDestination = z.infer<typeof exportedDestinationSchema>;
 
-// --- Section: library filters ---------------------------------------------
-
-// Library filter shape — same per-rule discriminated union as the create
-// endpoint, with `name` carried at the top level (export-level, not inside
-// the rule discriminator).
 export const exportedLibraryFilterSchema = z.discriminatedUnion('ruleType', [
   z.object({
     name: z.string().min(1).max(80),
@@ -89,11 +68,7 @@ export const exportedLibraryFilterSchema = z.discriminatedUnion('ruleType', [
 ]);
 export type ExportedLibraryFilter = z.infer<typeof exportedLibraryFilterSchema>;
 
-// --- Section: subscriptions -----------------------------------------------
-
-// Inline filter shape inside an exported subscription. Slightly broader than
-// the wire `inlineFilterInputSchema` — `enabled` and `mode` are required so
-// round-trip preserves them losslessly.
+// Broader than inlineFilterInputSchema: enabled/mode required for lossless round-trip.
 export const exportedInlineFilterSchema = z.discriminatedUnion('ruleType', [
   z.object({
     ruleType: z.literal('text-contains'),
@@ -139,12 +114,7 @@ export const exportedSubscriptionSchema = z.object({
   sourceTitle: z.string().min(1).max(255),
   handle: z.string().max(64).nullable(),
   enabled: z.boolean(),
-  /**
-   * Embedded by-natural-key reference to the destination. Null means the
-   * subscription was exported in a detached state (no destination attached).
-   * On import: matched against existing destinations by `(chatId, name)`,
-   * and against the current export envelope's `destinations` section.
-   */
+  // by-natural-key (chatId,name) ref; null = detached export
   destination: z
     .object({
       chatId: z.string().min(1).max(64),
@@ -152,22 +122,11 @@ export const exportedSubscriptionSchema = z.object({
     })
     .nullable(),
   inlineFilters: z.array(exportedInlineFilterSchema).max(200),
-  /** Library filter references by name. Resolved at import time. */
   libraryFilters: z.array(z.object({ name: z.string().min(1).max(80) })).max(200),
 });
 export type ExportedSubscription = z.infer<typeof exportedSubscriptionSchema>;
 
-// --- Section: app settings ------------------------------------------------
-
-/**
- * Encrypted Telegram session as embedded in the appSettings export section.
- * The host that mints this row encrypts the session with its
- * `TG_SESSION_ENCRYPTION_KEY` and stamps the first 16 hex chars of
- * `sha256(key)` as `keyFingerprint`. An importer with a different key
- * detects the mismatch via the fingerprint and skips the row with a
- * `telegram_account_key_mismatch` warning. Without a key configured the
- * importer skips with `telegram_account_no_key`.
- */
+// keyFingerprint = first 16 hex of sha256(TG_SESSION_ENCRYPTION_KEY); importer skips the row on mismatch/no-key.
 export const exportedTelegramAccountSchema = z.object({
   encryptedSessionString: z.string().min(1),
   keyFingerprint: z.string().min(1),
@@ -181,18 +140,8 @@ export type ExportedTelegramAccount = z.infer<typeof exportedTelegramAccountSche
 export const exportedAppSettingsSchema = z.object({
   delayMs: z.number().int().positive(),
   albumDebounceMs: z.number().int().positive(),
-  /**
-   * Optional v2 addition. Older (v1) files don't carry it and just import
-   * the throttle/debouncer fields. v2 importers without a configured
-   * `TG_SESSION_ENCRYPTION_KEY`, or with a key whose fingerprint doesn't
-   * match this row's, emit a warning and skip just the account write.
-   */
   telegramAccount: exportedTelegramAccountSchema.optional(),
-  /**
-   * Optional v3 addition: the stats-digest schedule. Each field is optional
-   * so older files omit them; the importer merges only the present fields
-   * onto the existing `global` row, never clobbering an unspecified one.
-   */
+  // stats-digest schedule; importer merges only present fields onto the global row
   statsDigestEnabled: z.boolean().optional(),
   statsDigestFrequency: statsDigestFrequencySchema.optional(),
   statsDigestDayOfWeek: z.number().int().min(0).max(6).optional(),
@@ -201,8 +150,6 @@ export const exportedAppSettingsSchema = z.object({
 });
 export type ExportedAppSettings = z.infer<typeof exportedAppSettingsSchema>;
 
-// --- Top-level envelope ---------------------------------------------------
-
 export const EXPORT_SECTIONS = [
   'destinations',
   'libraryFilters',
@@ -212,14 +159,10 @@ export const EXPORT_SECTIONS = [
 export type ExportSection = (typeof EXPORT_SECTIONS)[number];
 export const exportSectionSchema = z.enum(EXPORT_SECTIONS);
 
-// Generous upper bound on per-section row counts. Anything beyond ~2k is
-// almost certainly misuse (or attack) — the import endpoint already has a
-// 2 MB body limit, but caps here keep the parser from materializing a 10⁴+
-// element array before the route handler even runs.
+// Caps parser allocation ahead of the route's 2 MB body limit.
 const EXPORT_ARRAY_MAX = 2000;
 
-// Sections are optional — absent means "not exported". This lets the import
-// flow distinguish "user didn't export this" from "user exported nothing".
+// Absent section = "not exported", distinct from an exported-but-empty one.
 export const exportFileSchema = z.object({
   schemaVersion: z.number().int().positive(),
   exportedAt: z.string(),
@@ -231,15 +174,11 @@ export const exportFileSchema = z.object({
 });
 export type ExportFile = z.infer<typeof exportFileSchema>;
 
-// --- API: POST /system/export ---------------------------------------------
-
 export const exportRequestSchema = z.object({
   sections: z.array(exportSectionSchema).min(1),
 });
 export type ExportRequest = z.infer<typeof exportRequestSchema>;
 
-// --- API: POST /system/import ---------------------------------------------
-
 export const importConflictStrategySchema = z.enum(['skip', 'replace']);
 export type ImportConflictStrategy = z.infer<typeof importConflictStrategySchema>;
 
@@ -258,20 +197,13 @@ export const importSectionResultSchema = z.object({
 export type ImportSectionResult = z.infer<typeof importSectionResultSchema>;
 
 export const importWarningSchema = z.object({
-  /**
-   * Coarse category. Frontend can group/colour these; UI doesn't need to
-   * branch per kind beyond presentation. Add new kinds as needed —
-   * unrecognised kinds render with the default style.
-   */
   kind: z.enum([
     'destination_missing',
     'library_filter_missing',
     'inline_filter_invalid',
     'rule_type_mismatch',
     'subscription_skipped',
-    /** v2: importer has no `TG_SESSION_ENCRYPTION_KEY`, account row skipped. */
     'telegram_account_no_key',
-    /** v2: account row encrypted with a different key, skipped. */
     'telegram_account_key_mismatch',
   ]),
   message: z.string(),
@@ -287,8 +219,6 @@ export const importResultSchema = z.object({
 });
 export type ImportResult = z.infer<typeof importResultSchema>;
 
-// --- API: POST /system/wipe -----------------------------------------------
-
 export const WIPE_SECTIONS = ['destinations', 'libraryFilters', 'subscriptions'] as const;
 export type WipeSection = (typeof WIPE_SECTIONS)[number];
 export const wipeSectionSchema = z.enum(WIPE_SECTIONS);
diff --git a/packages/shared/src/filters.ts b/packages/shared/src/filters.ts
index 8aaefe7..5832358 100644
--- a/packages/shared/src/filters.ts
+++ b/packages/shared/src/filters.ts
@@ -1,12 +1,4 @@
-/**
- * Filter rule type defs and zod schemas.
- *
- * The discriminator (`ruleType`) lives in the `subscription_filters.rule_type`
- * DB column, not inside the `params` JSON. Per-rule param schemas describe
- * only the params payload — no `type` field — and the schemas are keyed by
- * rule type via `filterRuleParamsSchemas` so callers can look up the right
- * validator from a row's `ruleType` column.
- */
+// The `ruleType` discriminator lives in the DB column, not in `params`; per-rule schemas cover only params.
 import { z } from 'zod';
 
 export const FILTER_RULE_TYPES = [
@@ -20,10 +12,7 @@ export const FILTER_RULE_TYPES = [
 
 export type FilterRuleType = (typeof FILTER_RULE_TYPES)[number];
 
-// Per-filter mode (orthogonal to rule type). 'include' is the default and
-// matches the historical AND-pass semantics: a message forwards only if
-// every include filter matches. 'exclude' inverts the rule for that one
-// row — the filter rejects the message when its rule does match.
+// 'include' = AND-pass (forward only if every include matches); 'exclude' rejects when the rule matches.
 export const FILTER_MODES = ['include', 'exclude'] as const;
 export const filterModeSchema = z.enum(FILTER_MODES);
 export type FilterMode = z.infer<typeof filterModeSchema>;
@@ -40,8 +29,7 @@ export const textExcludesParamsSchema = z.object({
 });
 export type TextExcludesParams = z.infer<typeof textExcludesParamsSchema>;
 
-// RE2 supports g/i/m/s/u/y but NOT v (no Unicode-set escapes). Reject any
-// other character so a typo doesn't fail open at evaluation time.
+// RE2 allows g/i/m/s/u/y but NOT v; reject others so a typo doesn't fail open at eval time.
 const RE2_FLAGS_PATTERN = /^[gimsuy]*$/;
 
 export const textRegexParamsSchema = z.object({
@@ -63,9 +51,7 @@ export const minLengthParamsSchema = z.object({
 });
 export type MinLengthParams = z.infer<typeof minLengthParamsSchema>;
 
-// Cap usernames at the typical Telegram username length (~32) and the whole
-// array at a reasonable count; the evaluator walks every entry on every
-// matching message, so a 10⁴-element allowlist would slow down forwarding.
+// Cap the array: the evaluator walks every entry on every matching message.
 export const senderAllowlistParamsSchema = z.object({
   usernames: z.array(z.string().min(1).max(64)).min(1).max(100),
 });
@@ -80,9 +66,7 @@ export const filterRuleParamsSchemas = {
   'sender-allowlist': senderAllowlistParamsSchema,
 } as const satisfies Record<FilterRuleType, z.ZodTypeAny>;
 
-// Seed params used by the UI when a new rule of each type is created. Kept
-// next to the schemas so the two stay in sync: every default must parse
-// cleanly against its rule's `filterRuleParamsSchemas` entry.
+// UI seed params for a new rule of each type; every default must parse against its schema.
 export const filterRuleDefaultParams: Record<FilterRuleType, Record<string, unknown>> = {
   'text-contains': { value: '', caseInsensitive: true },
   'text-excludes': { value: '', caseInsensitive: true },
diff --git a/packages/shared/src/forwardLog.ts b/packages/shared/src/forwardLog.ts
index fd878be..6de16aa 100644
--- a/packages/shared/src/forwardLog.ts
+++ b/packages/shared/src/forwardLog.ts
@@ -1,10 +1,3 @@
-/**
- * Forward log status tuple.
- *
- * Lives in shared so the wire DTO (`forwardLogEntryDtoSchema`) and the
- * server's drizzle schema (`forwardLog.status` column) refer to the same
- * literal set. The CHECK constraint on the DB column is defined inline in
- * the server schema and must be updated in lockstep with this tuple.
- */
+// Keep in lockstep with the DB CHECK constraint on forwardLog.status (defined inline in the server schema).
 export const FORWARD_LOG_STATUSES = ['sent', 'filtered', 'flood_wait', 'failed'] as const;
 export type ForwardLogStatus = (typeof FORWARD_LOG_STATUSES)[number];
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 6c659d0..6a8e87f 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1,10 +1,3 @@
-/**
- * @tg-feed/shared — DTOs, zod schemas, and cross-package types.
- *
- * Anything that crosses the network boundary between server and web
- * lives here so both sides import from a single source of truth.
- */
-
 export const SHARED_PACKAGE_VERSION = '0.1.0';
 
 export * from './filters.js';
diff --git a/packages/shared/src/telegramAccount.ts b/packages/shared/src/telegramAccount.ts
index c13fc55..9fc541a 100644
--- a/packages/shared/src/telegramAccount.ts
+++ b/packages/shared/src/telegramAccount.ts
@@ -1,37 +1,19 @@
-/**
- * Wire-format schemas for the in-app Telegram sign-in flow exposed by
- * `apps/server/src/api/routes/telegramAccount.ts` and consumed by the
- * Settings page.
- */
 import { z } from 'zod';
 
-/** Source of the currently-active session. */
 export const telegramAccountSourceSchema = z.enum(['db', 'env']);
 export type TelegramAccountSource = z.infer<typeof telegramAccountSourceSchema>;
 
 export const telegramAccountInfoSchema = z.object({
-  /** True when the resolver successfully picked up a session (DB or env). */
   present: z.boolean(),
   source: telegramAccountSourceSchema.nullable(),
   displayName: z.string().nullable(),
   username: z.string().nullable(),
   phoneNumber: z.string().nullable(),
   telegramUserId: z.string().nullable(),
-  /**
-   * Account profile photo as a `data:image/jpeg;base64,...` URL, fetched
-   * lazily from the live userbot ("me") and cached. null when unavailable —
-   * no photo, not connected, or no live client. Defaulted so payloads
-   * without the field still parse.
-   */
+  // data:image/jpeg;base64 URL; null when unavailable (defaulted so older payloads parse)
   avatarDataUrl: z.string().nullable().default(null),
-  /** Whether `TG_SESSION_ENCRYPTION_KEY` is configured. */
   encryptionKeyConfigured: z.boolean(),
-  /**
-   * True when a row exists in `telegram_account` but its `keyFingerprint`
-   * doesn't match the current key. The resolver falls through to env (or
-   * degraded mode); the UI surfaces a "key mismatch" hint and offers to
-   * sign out + re-add.
-   */
+  // row exists but keyFingerprint != current key; resolver falls through to env/degraded
   keyFingerprintMismatch: z.boolean(),
 });
 export type TelegramAccountInfo = z.infer<typeof telegramAccountInfoSchema>;
@@ -64,9 +46,6 @@ export const telegramLoginVerifyRequestSchema = z.object({
 });
 export type TelegramLoginVerifyRequest = z.infer<typeof telegramLoginVerifyRequestSchema>;
 
-// Discriminated on `done` so the client narrows correctly: either the
-// flow completed (and we return the new account info), or 2FA is needed
-// next.
 export const telegramLoginCompletedSchema = z.object({
   done: z.literal(true),
   account: telegramAccountInfoSchema,
@@ -97,9 +76,7 @@ export type TelegramLoginPasswordResponse = z.infer<typeof telegramLoginPassword
 // --- Login: raw-paste flow ----------------------------------------------
 
 export const telegramLoginRawRequestSchema = z.object({
-  // The gramjs StringSession alphabet is base64-url-ish (`A-Za-z0-9+/=_-`).
-  // Garbage outside this set burns a connection attempt against Telegram for
-  // no reason; reject up-front so the route returns 400 instead of 502.
+  // Reject non-StringSession-alphabet input up-front so the route 400s instead of burning a TG connection (502).
   sessionString: z
     .string()
     .min(8)