docs: rebuild the documentation site around two readers

The site had drifted from the product. Every screenshot predated the
v0.5.0 UI redesign, the reading experience shipped no search and no
syntax highlighting, and a third of the pages were internal process
artefacts — migration task lists addressed to agentic workers, a
release runbook, a proposal marked "historical".

Reorganise around the only two people who read this: someone getting
the desktop app running for the first time, and someone reading the
source. Five sections replace nine — start / desktop / im / cli /
internals — and the pages that served neither reader are gone.

Site rewrite:

- Palette lifted from the desktop app's 「纸·墨·印」 themes, so the
  site and the product read as one thing. Light mirrors 纯白, dark
  mirrors 墨夜, and dark mode exists at all now.
- Fonts are self-hosted. The old @import from Google Fonts is
  unreachable from mainland China, which left every heading in a
  fallback serif; it also only requested weight 600 while the CSS
  asked for 900, so Latin and CJK in the same heading disagreed.
- Docs were shipped as one 968KB manifest downloaded on every page
  view. Split into a 32KB index plus one lazily imported chunk per
  page; the entry bundle is now 101KB gzipped.
- Add search, syntax highlighting, per-route meta with canonical and
  hreflang, a sitemap, and an error boundary. Replace the 44vh
  mobile sidebar with a drawer.
- Image dimensions are read at build time and written into the tag,
  so lazy images reserve their space instead of collapsing.

Screenshots are recaptured from a real v0.5.0 build against a clean
demo project, with tokens, QR codes and paired accounts redacted.
The previous set is deleted rather than kept alongside.

Routes follow file paths, so the restructure would have broken every
inbound link; 37 old paths redirect, in both languages. The PR policy
gate and CODEOWNERS also hardcoded docs/guide/contributing.md.

Verified: check:docs 78 pages / 323 links / 0 problems, check:policy
127 pass. Walked every route at 1440 and 390 in both themes for
overflow, contrast, keyboard reachability and focus management.

docs/en/im/telegram.md

@@ -1,60 +1,59 @@
+---
+title: Telegram Integration
+nav_title: Telegram
+description: Get a Bot Token from BotFather, paste it into Desktop, and approve permissions with native buttons.
+order: 2
+---
+
 # Telegram Integration
 
-The Telegram adapter connects a BotFather bot to local Desktop sessions. It accepts private chats only; groups are not supported.
+The fastest of the five to set up: ask `@BotFather` for a token, paste it into Desktop, done. Permission requests come back as native buttons. It accepts private chats only; groups are not supported.
 
 ## Create a bot
 
-In Telegram, open the official **@BotFather** account:
+In Telegram, open the official `@BotFather` account and send `/newbot`. Then:
 
-1. Send `/newbot`.
-2. Choose a display name.
-3. Choose a username ending in `_bot`.
-4. Copy the Bot Token returned by BotFather.
+1. Choose a display name, for example `ClaudeCodeHaha Bot`.
+2. Choose a username in Latin letters ending in `_bot`, for example `jiang_cc_hah_bot`.
+3. Copy the **Bot Token** that BotFather returns.
 
-Treat the token as a credential.
+That token is the bot's password. Do not paste it anywhere public.
 
-## Configure Desktop
+## Enter the token in Desktop
 
-Open **Settings → IM Integration → Telegram**:
+1. Open **Settings → IM Adapters** and select the **Telegram** tab.
+2. Paste the value into **Bot Token**.
+3. Select **Save**.
 
-1. Paste the Bot Token.
-2. Generate a six-character pairing code.
-3. Save the configuration.
-4. Send a message to the new bot and provide the pairing code when prompted.
+**Allowed Users** can stay empty. When it is, only paired accounts are accepted. To allowlist a known account directly, enter its numeric Telegram user ID; separate several with commas.
 
-The code expires after 60 minutes, works once, and is rate limited after repeated failures. Bot configuration alone does not authorize all Telegram users.
+## Pair your account
+
+At the top of the page, under **Pairing**, select **Generate Code**. The six-character code takes effect immediately — no separate save.
+
+Send any message to your new bot, then send the code when prompted. Once pairing is confirmed you can talk to Claude Code directly.
+
+Codes are valid for 60 minutes, work once, and are invalidated when a new one is generated. Repeated failures are rate limited; wait a few minutes before retrying.
 
 ## Commands
 
-- `/start` — show help
+- `/start` — show help and available commands
 - `/help` — show available commands
-- `/projects` — list or switch recent projects
-- `/status` — show project, model, run state, and task summary
-- `/clear` — clear context while keeping the project
-- `/new` — start a new session and choose a project
+- `/projects` — list recent projects and switch
+- `/status` — project, model, run state, and task summary
+- `/new` — clear the current binding and choose a project again
+- `/clear` — clear context, keep the project binding
 - `/stop` — stop the current generation
 
-## Permission approval
+## Approval and reply behavior
 
-Telegram presents buttons for:
+A permission request arrives as a message with three buttons: allow once, always allow the matching operation, and deny. The choice is converted to a `permission_response` for the pending Desktop session.
 
-- allow once;
-- always allow the matching operation;
-- deny.
-
-The callback is converted to a `permission_response` for the pending Desktop session.
-
-## Reply behavior
-
-The adapter buffers streaming output:
-
-- a placeholder can be sent during thinking;
-- text deltas are accumulated;
-- completed text is split into platform-sized messages.
+Replies pass through a streaming buffer: a placeholder can be sent while Claude is thinking, text deltas accumulate in place, and completed text is split into platform-sized messages.
 
 ## Development
 
-Packaged Desktop starts the adapter automatically. For source development:
+Packaged Desktop starts the sidecar automatically. Run it by hand only when working from source:
 
 ```bash
 cd adapters
@@ -69,4 +68,16 @@ export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
 export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
 ```
 
-If a sender is rejected, verify that the current pairing code was sent to the correct bot private chat and that the sender is now present in the paired or allowed list.
+## Troubleshooting
+
+**The adapter reports a missing token.** Neither `TELEGRAM_BOT_TOKEN` nor `telegram.botToken` in `~/.claude/adapters.json` took effect. Re-enter the token in Settings and save.
+
+**Settings opens but the bot does nothing.** When running from source, the web app only writes configuration; it does not launch `bun run telegram`. Packaged Desktop starts the sidecar for you.
+
+**A sender is rejected.** Confirm a code was generated, that it is within its 60-minute window, and that it was sent to the correct bot in a private chat.
+
+**Session not restored after a restart.** Verify that `~/.claude/adapter-sessions.json` is writable and that the session still exists in Desktop.
+
+## Source
+
+`adapters/telegram/index.ts`, plus `pairing.ts`, `session-store.ts`, `ws-bridge.ts`, `message-buffer.ts`, and `format.ts` under `adapters/common/`.