@llblab/pi-telegram 0.11.2 → 0.12.0

package/docs/{outbound-handlers.md → outbound.md}

@@ -13,7 +13,7 @@ An outbound handler is selected by `type`. Text replies and assistant markup map
 | Source            | Handler                       | Action                  |
 | ----------------- | ----------------------------- | ----------------------- |
 | Final text        | `outboundHandlers[type=text]` | Transform before render |
-| `telegram_voice`  | Voice pipeline                | OGG/Opus `sendVoice`   |
+| `telegram_voice`  | Voice pipeline                | OGG/Opus `sendVoice`    |
 | `telegram_button` | Built-in                      | Attach inline button    |
 
 The voice pipeline is detailed below: configured `type: "voice"` handlers first, then programmatic handlers, then registered synthesis providers.
@@ -60,24 +60,27 @@ Voice replies use one fallback pipeline:
 
 1. configured `outboundHandlers` with `type: "voice"` in `telegram.json` order
 2. programmatic `registerTelegramOutboundHandler("voice", ...)` handlers
-3. registered voice synthesis providers from `@llblab/pi-telegram/lib/voice.ts`
+3. registered voice synthesis providers from `@llblab/pi-telegram/voice`
 
 This makes provider extensions a zero-config convenience without overriding explicit operator-owned `telegram.json` handlers. If several synthesis providers are registered, they are tried in registration order; the first provider that returns a valid `.ogg`/`.opus` artifact handles the reply. Returning `undefined` passes to the next provider, while thrown errors or invalid files are recorded before the next fallback is tried.
 
 ## Voice Synthesis Provider API
 
-Voice replies can be delivered by synthesis providers registered through `@llblab/pi-telegram/lib/voice.ts`:
+Voice replies can be delivered by synthesis providers registered through `@llblab/pi-telegram/voice`:
 
 ```ts
-import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/lib/voice.ts";
-
-const dispose = registerTelegramVoiceSynthesisProvider(async (text, options) => {
-  const audioPath = await synthesizeToOggOpus(text, options);
-  return { audioPath, transcriptText: text };
-});
+import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/voice";
+
+const dispose = registerTelegramVoiceSynthesisProvider(
+  async (text, options) => {
+    const audioPath = await synthesizeToOggOpus(text, options);
+    return { audioPath, transcriptText: text };
+  },
+  { id: "my-extension/tts" },
+);
 ```
 
-Synthesis providers receive the extracted `telegram_voice` text plus optional `lang`/`rate` hints. They own translation, TTS, speech rewriting, transcript choice, and OGG/Opus conversion. The bridge validates that the returned file ends in `.ogg` or `.opus`, sends it through Telegram `sendVoice`, and falls back to planned text if delivery fails before any visible text was delivered. Providers run after configured and programmatic voice handlers in the priority chain above.
+Synthesis providers receive the extracted `telegram_voice` text plus optional `lang`/`rate` hints. Stable registrations pass a durable `id`; omitted ids remain a compatibility path for older providers. Providers own translation, TTS, speech rewriting, transcript choice, and OGG/Opus conversion. The bridge validates that the returned file ends in `.ogg` or `.opus`, sends it through Telegram `sendVoice`, and falls back to planned text if delivery fails before any visible text was delivered. Providers run after configured and programmatic voice handlers in the priority chain above.
 
 ## Voice Markup
 

package/docs/public-api.md

@@ -0,0 +1,266 @@
+# Public API
+
+`pi-telegram` is both a π extension and a small Telegram platform for companion extensions. This document defines the stable public surface. Everything outside this document is implementation detail unless another focused doc explicitly marks it stable.
+
+## Stability Levels
+
+- **Stable:** documented here and covered by compatibility expectations.
+- **Advanced stable:** public for extension authors, but lower-level; prefer higher-level APIs when possible.
+- **Compatibility:** older import/config paths that remain supported but should not be used for new code.
+- **Internal:** exported from source for tests or domain reuse, but not a compatibility promise.
+
+## Package Entrypoints
+
+Preferred public imports:
+
+```ts
+import telegram from "@llblab/pi-telegram";
+import { registerTelegramSection } from "@llblab/pi-telegram/sections";
+import { registerTelegramUpdateHandler } from "@llblab/pi-telegram/updates";
+import { registerTelegramInboundHandler } from "@llblab/pi-telegram/inbound";
+import { registerTelegramOutboundHandler } from "@llblab/pi-telegram/outbound";
+import {
+  registerTelegramVoiceSynthesisProvider,
+  registerTelegramVoiceTranscriptionProvider,
+} from "@llblab/pi-telegram/voice";
+```
+
+`0.12.0` intentionally removes the published `@llblab/pi-telegram/lib/*.ts` compatibility wildcard. Integrations should use the public API domain subpaths above. Package exports point at `/api/*.ts` membranes that re-export only stable companion-extension symbols; implementation modules under `lib/` remain package-private.
+
+## User-Facing API
+
+### π commands
+
+Stable commands inside π:
+
+- `/telegram-setup` — configure/update the bot token.
+- `/telegram-connect` — start polling in the current session and acquire ownership.
+- `/telegram-disconnect` — stop polling and release ownership.
+- `/telegram-status` — show connection, polling, execution, queue, and recent event diagnostics.
+
+### Telegram commands
+
+Stable commands inside the paired Telegram DM:
+
+- `/start` — pair when needed and open the main application menu.
+- `/compact` — open confirmation and compact when idle.
+- `/next` — dispatch the next queued turn, aborting active work first when needed.
+- `/continue` — enqueue a priority `continue` prompt.
+- `/abort` — abort active Telegram-owned work and keep the queue.
+- `/stop` — abort active Telegram-owned work and clear waiting Telegram queue items.
+
+Hidden compatibility shortcuts may open sections directly: `/help`, `/status`, `/model`, `/thinking`, `/queue`, and `/settings`.
+
+### Tools and assistant-authored actions
+
+- `telegram_attach(paths)` is the stable artifact delivery tool for generated files.
+- `telegram_voice` hidden comments request Telegram-native voice delivery.
+- `telegram_button` hidden comments create inline buttons whose taps enqueue prompts.
+
+See [Outbound Handlers](./outbound.md) for exact markup forms.
+
+## Configuration API
+
+Configuration lives in `~/.pi/agent/telegram.json` unless `PI_CODING_AGENT_DIR` changes the agent root.
+
+Stable config keys:
+
+```ts
+interface TelegramConfig {
+  botToken?: string;
+  botUsername?: string; // runtime-managed
+  botId?: number; // runtime-managed
+  allowedUserId?: number;
+  lastUpdateId?: number; // runtime-managed
+  proactivePush?: boolean;
+  inboundHandlers?: TelegramInboundHandlerConfig[];
+  attachmentHandlers?: TelegramInboundHandlerConfig[]; // compatibility alias
+  outboundHandlers?: TelegramOutboundHandlerConfig[];
+  voice?: {
+    replyMode?: "manual" | "mirror" | "always";
+    sendTranscript?: boolean;
+  };
+  time?: {
+    injectionMode?: "hidden" | "always" | "interval";
+    interval?: number;
+  };
+}
+```
+
+Hidden/default semantics are represented by absence:
+
+- Voice Reply `hidden`: no `voice.replyMode` key is persisted.
+- Time Injection `hidden`: no `time.injectionMode` key is persisted; if `time` becomes empty, the whole `time` object may be omitted.
+
+Environment variables are stable only where documented in the README: bot-token bootstrap, proxy behavior, agent root, and inbound/outbound file size limits.
+
+## Programmatic API Matrix
+
+High-level stable APIs:
+
+- `registerTelegramSection()`
+  - Identity: required `id`.
+  - Purpose: managed menu/settings UI surfaces.
+- `registerTelegramVoiceTranscriptionProvider()`
+  - Identity: required stable `id` for new code.
+  - Purpose: STT fallback for voice/audio input.
+- `registerTelegramVoiceSynthesisProvider()`
+  - Identity: required stable `id` for new code.
+  - Purpose: TTS fallback for Telegram voice replies.
+
+Low-level stable buses:
+
+- `registerTelegramUpdateHandler()`
+  - Identity: no id.
+  - Purpose: observe or consume raw Telegram updates before default routing.
+- `registerTelegramInboundHandler()`
+  - Identity: no id.
+  - Purpose: generic Telegram-to-π transforms.
+- `registerTelegramOutboundHandler()`
+  - Identity: no id.
+  - Purpose: generic final-reply transforms or voice command fallbacks.
+
+Advanced stable diagnostics:
+
+- `recordTelegramRuntimeEvent()`
+  - Identity: caller supplies category.
+  - Purpose: surface companion diagnostics in `/telegram-status`.
+
+All registration APIs return a disposer. Companion extensions should call disposers on shutdown and re-register on session start when they recreate runtime state. Low-level bus APIs intentionally avoid ids and run in registration order. High-level provider/UI APIs require stable identity in their public contract so diagnostics, replacement, and cleanup are understandable. Generated voice-provider ids remain a temporary compatibility path where documented.
+
+## Sections
+
+Import from `@llblab/pi-telegram/sections`.
+
+```ts
+const unregister = registerTelegramSection({
+  id: "@scope/my-extension",
+  label: "🧩 My extension",
+  order: 10,
+  render: async (ctx) => ({
+    text: "<b>My extension</b>",
+    parseMode: "html",
+    replyMarkup: {
+      inline_keyboard: [
+        [{ text: "▶️ Run", callback_data: ctx.callbackData("run") }],
+      ],
+    },
+  }),
+  handleCallback: async (ctx) => {
+    if (ctx.action !== "run") return "pass";
+    await ctx.enqueuePrompt("Run my extension workflow.");
+    await ctx.answerCallback("Queued");
+    return "handled";
+  },
+});
+```
+
+Contract:
+
+- `id` is unique per active registry. Duplicate ids are rejected.
+- `ctx.callbackData(action, payload?)` builds compact `section:` callbacks and validates Telegram's 64-byte limit.
+- `ctx.edit()` and `ctx.open()` auto-prepend the correct Back/Main-menu row.
+- Section errors are isolated and surfaced as callback popups/diagnostics.
+
+Full behavior: [Extension Sections](./sections.md).
+
+## Updates
+
+Import from `@llblab/pi-telegram/updates`.
+
+```ts
+const off = registerTelegramUpdateHandler(async (update) => {
+  const data = (update as { callback_query?: { data?: string } }).callback_query
+    ?.data;
+  if (!data?.startsWith("myext:")) return "pass";
+  await handleMyCallback(data);
+  return "consume";
+});
+```
+
+Use this as a low-level escape hatch. Prefer sections for menu-integrated UI.
+
+Full behavior: [Updates](./updates.md).
+
+## Inbound
+
+Import from `@llblab/pi-telegram/inbound`.
+
+```ts
+const off = registerTelegramInboundHandler("document", async ({ file }) => {
+  if (!file?.mimeType?.includes("pdf")) return undefined;
+  return await extractPdfText(file.path);
+});
+```
+
+Priority order:
+
+1. configured `inboundHandlers`
+2. compatibility `attachmentHandlers`
+3. programmatic inbound handlers
+4. voice transcription providers
+5. built-in text-file fallback
+
+Full behavior: [Inbound Handlers](./inbound.md).
+
+## Outbound
+
+Import from `@llblab/pi-telegram/outbound`.
+
+```ts
+const off = registerTelegramOutboundHandler("text", async (text) => {
+  return await rewriteFinalText(text);
+});
+```
+
+Programmatic outbound handlers are fallbacks/transformers behind operator-owned `telegram.json` configuration. Voice delivery priority is configured voice handlers, then programmatic `voice` handlers, then synthesis providers.
+
+Full behavior: [Outbound Handlers](./outbound.md).
+
+## Voice Providers
+
+Import from `@llblab/pi-telegram/voice`.
+
+```ts
+const offStt = registerTelegramVoiceTranscriptionProvider(
+  async (file) => {
+    if (file.kind !== "voice" && file.kind !== "audio") return undefined;
+    return { text: await transcribe(file.path) };
+  },
+  { id: "@scope/my-extension/stt" },
+);
+
+const offTts = registerTelegramVoiceSynthesisProvider(
+  async (text, options) => {
+    const audioPath = await synthesizeOggOpus(text, options);
+    return { audioPath, transcriptText: text };
+  },
+  { id: "@scope/my-extension/tts" },
+);
+```
+
+Stable voice-provider registrations pass a durable `id`. Omitting `id` is a compatibility path for older providers and receives a generated session-local id. Providers return `undefined` to pass. TTS providers must return `.ogg` or `.opus` files for native Telegram voice notes.
+
+Full behavior: [Voice Integration](./voice.md).
+
+## Callback Namespaces
+
+Owned prefixes are reserved by `pi-telegram`: `compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, and `section:`.
+
+Companion extensions should use their own short prefix for raw callbacks or use `ctx.callbackData()` inside sections. Unknown unowned callbacks may be forwarded to π as `[callback] <data>` after built-in handlers decline them.
+
+Full behavior: [Callback Namespaces](./callback-namespaces.md).
+
+## Internal Surface
+
+The following are not stable public contracts unless explicitly documented elsewhere:
+
+- queue/runtime/lifecycle stores and planners
+- menu implementation helpers
+- polling/lock internals
+- Telegram API transport helpers
+- rendering internals
+- command implementation helpers
+- test support functions
+
+They are intentionally not exposed through a `./lib/*.ts` export wildcard in `0.12.0`.

package/docs/{extension-sections.md → sections.md}

@@ -10,7 +10,7 @@
 
 Telegram Extension Sections let ordinary pi extensions add structured UI surfaces to the `pi-telegram` inline application menu. The platform mirrors π's own extensibility model: small, composable extensions that plug into a shared shell without owning transport, polling, authorization, or menu lifecycle.
 
-`pi-telegram` stays the single bot operator. Extensions register typed sections; the bridge handles rendering, callback routing, token mapping, navigation hierarchy, and diagnostics. No second poller, no new loader — just one `registerTelegramSection()` call.
+`pi-telegram` stays the single bot operator. Extensions register typed sections; the bridge handles rendering, callback routing, token mapping, navigation hierarchy, and diagnostics. No second polling loop, no new loader — just one `registerTelegramSection()` call.
 
 ## 2. Contract Layers
 
@@ -39,7 +39,7 @@ The `id` is the owner identity. No separate `owner` field. Used for registry own
 ## 4. Registration Shape
 
 ```ts
-import { registerTelegramSection } from "@llblab/pi-telegram/lib/extension-sections.ts";
+import { registerTelegramSection } from "@llblab/pi-telegram/sections";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 export default function (pi: ExtensionAPI) {
@@ -127,12 +127,12 @@ unregister(); // removes from main menu, settings, and callback routing
 
 Two paths, same registry:
 
-**Typed import (preferred):** Extension imports `registerTelegramSection` from `@llblab/pi-telegram/lib/extension-sections.ts`. The function reads from a `globalThis` registry set by `pi-telegram` at startup.
+**Typed import (preferred):** Extension imports `registerTelegramSection` from `@llblab/pi-telegram/sections`. The function reads from a `globalThis` registry set by `pi-telegram` at startup. In `0.12.0`, package-private `@llblab/pi-telegram/lib/*.ts` deep imports are no longer exported.
 
-**Relative import (local):** When the extension cannot resolve `@llblab/pi-telegram` as an npm package, use a relative path:
+**Relative import (local):** When the extension cannot resolve `@llblab/pi-telegram` as an npm package, use the public API membrane via a relative path:
 
 ```ts
-import { registerTelegramSection } from "../pi-telegram/lib/extension-sections.ts";
+import { registerTelegramSection } from "../pi-telegram/api/sections.ts";
 ```
 
 **GlobalThis bridge (zero-coupling):** `pi-telegram` exposes `__piTelegramSectionRegistry__` on `globalThis`. The typed import is a thin wrapper. Extensions never touch the raw registry.
@@ -187,18 +187,19 @@ section:<token>:<action>:<payload>
 
 Example: `section:0:counter:5`
 
-The token is an implementation detail. Section authors **never** write `section:` strings manually. Use `ctx.callbackData(action, payload?)` which fills in the correct token.
+The token is an implementation detail. Section authors **never** write `section:` strings manually. Use `ctx.callbackData(action, payload?)` which fills in the correct token and rejects callback data above Telegram's 64-byte limit.
 
 ### Routing order
 
-1. Telegram update arrives through the single `pi-telegram` poller
-2. External handlers observe/consume (raw update interception)
+1. Telegram update arrives through the single `pi-telegram` polling loop
+2. Update handlers observe/consume (raw update interception)
 3. Button action store (`tgbtn:*`)
-4. Queue menu callbacks (`queue:*`)
-5. Settings menu callbacks (`settings:*`)
-6. Built-in menu callbacks (`menu:*`, `model:*`, `thinking:*`, `status:*`)
-7. Section callbacks (`section:*`) — dispatched before step 6's full handler
-8. Unknown callbacks fall back to `[callback]` prompt text
+4. Compact confirmation callbacks (`compact:*`)
+5. Queue menu callbacks (`queue:*`)
+6. Settings menu callbacks (`settings:*`)
+7. Built-in menu callbacks (`menu:*`, `model:*`, `thinking:*`, `status:*`)
+8. Section callbacks (`section:*`) — dispatched before step 7's full handler
+9. Unknown callbacks fall back to `[callback]` prompt text
 
 ### Handler return values
 
@@ -221,7 +222,7 @@ If a section is unregistered or a token is unknown, the callback is answered wit
 
 > "This section is no longer available."
 
-Section errors are caught and surfaced as popup text. No unhandled exceptions leak to the poller.
+Section errors are caught and surfaced as popup text. No unhandled exceptions leak to polling.
 
 ## 8. Navigation Hierarchy
 
@@ -298,7 +299,7 @@ Context ports are intentionally narrow. Sections **cannot**:
 
 - Read/write filesystem
 - Access raw process or bot clients
-- Start a second poller
+- Start a second polling loop
 - Mutate session state
 - Send arbitrary Telegram API calls
 
@@ -320,12 +321,15 @@ handleCallback: async (ctx) => {
       text: `<b>Delete ${ctx.payload}?</b>\n\nThis cannot be undone.`,
       parseMode: "html",
       replyMarkup: {
-        inline_keyboard: [[
-          { text: "✅ Yes, delete",
-            callback_data: ctx.callbackData("confirm-delete", ctx.payload) },
-          { text: "❌ Cancel",
-            callback_data: ctx.callbackData("cancel") },
-        ]],
+        inline_keyboard: [
+          [
+            {
+              text: "✅ Yes, delete",
+              callback_data: ctx.callbackData("confirm-delete", ctx.payload),
+            },
+            { text: "❌ Cancel", callback_data: ctx.callbackData("cancel") },
+          ],
+        ],
       },
     });
     return "handled";
@@ -339,7 +343,7 @@ handleCallback: async (ctx) => {
     await ctx.deleteMessage();
     return "handled";
   }
-}
+};
 ```
 
 `ctx.deleteMessage()` removes the dialog from chat after the user makes a choice. Callbacks from chat buttons route through the same `handleCallback` — the same `ctx.callbackData()` works regardless of where the button lives. The extension owns its callback namespace; the bridge owns transport.
@@ -356,7 +360,7 @@ section:0:settings:open          → open settings root
 section:0:<action>:<payload>     → forwarded to handleCallback
 ```
 
-`section:` is listed in `TELEGRAM_OWNED_CALLBACK_PREFIXES` alongside `menu:`, `model:`, `settings:`, `status:`, `tgbtn:`, `thinking:`, `queue:`. Layered extensions must not use this prefix.
+`section:` is listed in `TELEGRAM_OWNED_CALLBACK_PREFIXES` alongside `compact:`, `menu:`, `model:`, `settings:`, `status:`, `tgbtn:`, `thinking:`, `queue:`. Layered extensions must not use this prefix.
 
 ### Inline keyboard layout
 
@@ -378,7 +382,7 @@ The platform inherits from π's own extension model:
 
 - `export default function(pi)` → `registerTelegramSection(section)`
 - `pi.on("shutdown", ...)` → disposer from `registerTelegramSection`
-- Typed imports → typed import from `@llblab/pi-telegram/lib/extension-sections.ts`
+- Typed imports → typed import from `@llblab/pi-telegram/sections`
 - `globalThis` registry → `__piTelegramSectionRegistry__` on `globalThis`
 - Identity from `package.json/name` → same identity rules as Locks Standard
 - Narrow typed context ports → `TelegramSectionContext` / `TelegramSectionCallbackContext`
@@ -419,7 +423,7 @@ Available programmatically via `getTelegramSectionDiagnostics()`. Section runtim
 
 ### Non-goals:
 
-- No second Telegram poller
+- No second Telegram polling loop
 - No new pi extension loader
 - No generic webview system
 - No default filesystem mutation API
@@ -429,8 +433,8 @@ Available programmatically via `getTelegramSectionDiagnostics()`. Section runtim
 ## 14. Relationship to Other Standards
 
 - [Callback Namespaces](./callback-namespaces.md): defines `section:` as pi-telegram-owned prefix. Sections use namespaced callbacks but authors never hand-roll them
-- [External Handlers](./external-handlers.md): raw update interception for direct Telegram update access. Sections are the structured UI layer above
-- [Extension Locks](../docs/locks.md) (external): same identity key rules (`package.json/name` → canonical id)
+- [Updates](./updates.md): raw update interception for direct Telegram update access. Sections are the structured UI layer above
+- [Extension Locks](../docs/locks.md) (polling): same identity key rules (`package.json/name` → canonical id)
 - [Command Templates](./command-templates.md): sections do not execute command templates by default. UI registration + callback routing, not shell execution
 
 ## 15. Demo Extension

package/docs/ui-style.md

@@ -0,0 +1,165 @@
+# UI Style Guide
+
+Small standard for inline buttons, menu rows, state controls, cards, and confirmation dialogs.
+
+## Principles
+
+- Keep UI compact and phone-readable.
+- Put emoji where they help scanning, not everywhere.
+- Use one strong indicator for current selection; avoid emoji noise on every option.
+- Match label casing to control role.
+- Prefer minimal, clear configuration UI over exhaustive explanation.
+- Preserve domain-owned callback prefixes and behavior in the owning module.
+
+## Action Buttons
+
+Action buttons perform an operation.
+
+Rules:
+
+- Use an emoji plus capitalized action text.
+- Prefer direct verb or action noun.
+- Keep labels short.
+
+Examples:
+
+- `🗜 Yes, compact`
+- `❌ No`
+- `🗑 Yes, delete`
+- `☑️ Activate`
+
+## State & Navigation Buttons
+
+State buttons show the current state and navigate to a submenu or detail rather than performing an operation directly.
+
+Rules:
+
+- Use an emoji that reflects the current state.
+- Use Capitalized, descriptive state text.
+- Tapping opens a submenu or returns to the parent list.
+
+Examples:
+
+- `🟢 Active` — model detail, navigates back to model list
+- `📌 Proactive push: On` — settings row, opens the toggle submenu
+- `👄 Voice reply: Mirror` — settings row, opens the option list
+
+## Boolean Toggles
+
+Boolean settings use a horizontal `On` / `Off` pair, like a checkbox stretched across two buttons.
+
+Rules:
+
+- Keep the pair in one row: `On` left, `Off` right.
+- Use Capitalized labels.
+- Always show an indicator on both buttons to avoid horizontal label shift.
+- Mark active `On` with `🟢`.
+- Mark active `Off` with `🟡`.
+- Mark the inactive value with `⚫️`.
+
+Examples:
+
+- `🟢 On` / `⚫️ Off`
+- `⚫️ On` / `🟡 Off`
+
+## Horizontal Tabs
+
+Tabs or small mutually-exclusive scopes use a horizontal row.
+
+Rules:
+
+- Use Capitalized labels.
+- Always show an indicator on every tab to avoid horizontal label shift.
+- Use active tab color to convey semantics:
+  - `🟣` for the default / normal state (All models, Normal priority).
+  - `🟡` for an elevated or filtered state (Scoped models, Priority).
+  - `🟣` for neutral navigation controls (page picker).
+- Mark inactive tabs with `⚫️`.
+
+Examples:
+
+- `🟡 Scoped` / `⚫️ All`
+- `⚫️ Priority` / `🟣 Normal`
+- `1` / `🟣 2` / `3`
+
+## Vertical Option Lists
+
+Vertical option lists choose one value from a potentially longer list, for example model selection, thinking level, voice reply mode, or time injection mode.
+
+Rules:
+
+- Put each option on its own row.
+- Mark only the current value with `🟢`.
+- Leave non-current values without emoji.
+- Use lowercase labels when the option is a value.
+
+Examples:
+
+- `🟢 mirror`
+- `manual`
+- `always`
+
+## Navigation
+
+Inline submenu navigation is hierarchical.
+
+Rules:
+
+- Put the navigation row first.
+- First-level submenus opened from the main inline menu start with `⬆️ Main menu`.
+- Deeper submenus start with `⬆️ Back`.
+- `Main menu` returns to the root inline menu.
+- `Back` returns one level up, never directly to the root unless the parent is the root.
+
+Examples:
+
+- Main menu → Settings: first row is `⬆️ Main menu`.
+- Settings → Voice reply mode: first row is `⬆️ Back`.
+
+## Message Cards
+
+Message cards sent by the bot should start with a strong heading.
+
+Rules:
+
+- Start with a bold heading or, for dialogs, a bold question.
+- Setting detail cards may include an emoji in the heading, then a colon and the current value in `<code>`.
+- Explain what the setting does and what the options mean only as much as needed.
+- Keep descriptions short and clear.
+
+Examples:
+
+```html
+<b>👄 Voice reply mode:</b> <code>mirror</code>
+```
+
+```html
+<b>Queue</b>
+```
+
+## Confirmation Dialogs
+
+Confirmation dialogs protect risky or disruptive actions.
+
+Rules:
+
+- Body text is one bold text-only question.
+- Do not put emoji in the dialog question.
+- Do not add explanatory body copy unless the risk cannot be understood from the question and action labels.
+- Put emoji on the buttons, not in the question.
+- Preserve dialog-specific button order by intent.
+
+Example:
+
+```html
+<b>Compact session?</b>
+```
+
+Buttons:
+
+- `🗜 Yes, compact`
+- `❌ No`
+
+## Callback Ownership
+
+UI style does not change callback ownership. Callback prefixes remain owned by their feature domain and must be listed in callback namespace documentation when they become public collision risks.