diff --git a/docs/grammy.md b/docs/grammy.md
index c0a2f46d4..7214f40e7 100644
--- a/docs/grammy.md
+++ b/docs/grammy.md
@@ -16,7 +16,7 @@ Updated: 2025-12-07
 - **Single client path:** fetch-based implementation removed; grammY is now the sole Telegram client (send + gateway) with the grammY throttler enabled by default.
 - **Gateway:** `monitorTelegramProvider` builds a grammY `Bot`, wires mention/allowlist gating, media download via `getFile`/`download`, and delivers replies with `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument`. Supports long-poll or webhook via `webhookCallback`.
 - **Proxy:** optional `telegram.proxy` uses `undici.ProxyAgent` through grammY’s `client.baseFetch`.
-- **Webhook helpers:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown and optional `--webhook-url` override.
+- **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `telegram.webhookUrl` is set (otherwise it long-polls).
 - **Sessions:** direct chats map to `main`; groups map to `group:<chatId>`; replies route back to the same surface.
 - **Config knobs:** `telegram.botToken`, `requireMention`, `allowFrom`, `mediaMaxMb`, `proxy`, `webhookSecret`, `webhookUrl`.
 - **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.
@@ -24,4 +24,4 @@ Updated: 2025-12-07
 Open questions
 - Optional grammY plugins (throttler) if we hit Bot API 429s.
 - Add more structured media tests (stickers, voice notes).
-- Expose a `--public-url` flag in CLI for webhook registration convenience (currently `--webhook-url`).
+- Make webhook listen port configurable (currently fixed to 8787 unless wired through the gateway).
diff --git a/docs/remote.md b/docs/remote.md
index 4e1779a82..83f1d2645 100644
--- a/docs/remote.md
+++ b/docs/remote.md
@@ -1,5 +1,5 @@
 ---
-summary: "Remote mode topology using SSH control channels between gateway and mac app"
+summary: "Remote access using SSH tunnels (Gateway WS) and tailnets"
 read_when:
   - Running or troubleshooting remote gateway setups
 ---