@llblab/pi-telegram 0.11.2 → 0.13.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. Section callbacks (`section:*`)
+8. Built-in menu callbacks (`menu:*`, `model:*`, `thinking:*`, `status:*`)
+9. Unknown callbacks fall back to `[callback]` prompt text
 
 ### Handler return values
 
@@ -221,18 +222,18 @@ 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
 
-`ctx.edit()` and `ctx.open()` automatically prepend a Back row. The Back target depends on the navigation level:
+`ctx.edit()` automatically prepends a Back row for menu-bound views. The Back target depends on the navigation level:
 
 - Section root (from main menu): `⬆️ Main menu` → `menu:back`
 - Section sub-view (`ctx.edit()` in handler): `⬆️ Back` → `section:<token>:open`
 - Settings root (from Settings list): `⬆️ Back` → `settings:list`
 - Settings sub-view (`ctx.edit()` in settings handler): `⬆️ Back` → `settings:list`
 
-Section authors do not need to manage the Back button — it is added automatically and deduplicated when already present.
+Section authors do not need to manage the Back button for `ctx.edit()` — it is added automatically and deduplicated when already present. `ctx.open()` sends a standalone chat message and does not prepend a Back row.
 
 ```
 Main menu
@@ -256,7 +257,7 @@ interface TelegramSectionContext {
   answerCallback(text?: string): Promise<void>;
   /** Edit the current message (auto-prepends Back row) */
   edit(view: TelegramSectionView): Promise<void>;
-  /** Send a new message (auto-prepends Back row) */
+  /** Send a standalone chat message without auto-navigation */
   open(view: TelegramSectionView): Promise<void>;
   /** Enqueue a plain-text prompt turn */
   enqueuePrompt(prompt: string): Promise<void>;
@@ -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.

package/docs/{external-handlers.md → updates.md}

@@ -1,10 +1,12 @@
-# External Handlers
+# Updates
 
-`pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other pi extensions cannot open a competing poller against the same bot — the Telegram Bot API uses a per-bot `offset` cursor, and two pollers race each other and lose updates.
+`updates` owns Telegram update classification, default-routing plans, and the public update-handler registry. The internal `polling` domain owns the actual `getUpdates` loop, offsets, and abort/controller state.
+
+`pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other pi extensions cannot open a competing polling connection against the same bot — the Telegram Bot API uses a per-bot `offset` cursor, and two loops race each other and lose updates.
 
 This document describes the registry that lets layered pi extensions running in the same pi process hook into `pi-telegram`'s polling loop and react to inbound Telegram updates **before** `pi-telegram`'s default routing fires.
 
-It is the runtime counterpart to [Callback Namespaces](./callback-namespaces.md): callback namespaces define how to share `callback_data` cleanly; external handlers define how to observe and optionally short-circuit the dispatch of those updates.
+It is the runtime counterpart to [Callback Namespaces](./callback-namespaces.md): callback namespaces define how to share `callback_data` cleanly; update handlers define how to observe and optionally short-circuit the dispatch of those updates.
 
 ## When to use it
 
@@ -16,34 +18,34 @@ Use it when a layered extension needs to:
 
 If the layered extension only needs to read assistant-visible callbacks, the existing `[callback] <data>` fallback documented in [Callback Namespaces](./callback-namespaces.md) is enough.
 
-If the extension needs a durable top-level Telegram menu section with managed rendering, callback routing, authorization, and diagnostics, use the higher-level [Telegram Extension Sections](./extension-sections.md) contract instead of a raw external handler.
+If the extension needs a durable top-level Telegram menu section with managed rendering, callback routing, authorization, and diagnostics, use the higher-level [Telegram Extension Sections](./sections.md) contract instead of a raw update handler.
 
 ## Constraints
 
-- One bot, one pi process, one `getUpdates` poller. This registry does **not** enable running multiple pi instances against the same bot.
-- Interceptors run in the polling loop. They must return quickly; long awaits delay subsequent updates.
-- Interceptor errors are caught and logged silently so polling never breaks. If you need durable error reporting, do it inside your interceptor.
+- One bot, one pi process, one `getUpdates` loop. This registry does **not** enable running multiple pi instances against the same bot.
+- Handlers run in the polling loop. They must return quickly; long awaits delay subsequent updates.
+- Handler errors are caught and logged silently so polling never breaks. If you need durable error reporting, do it inside your handler.
 - The registry lives on `globalThis`. Module instance identity is not required, so layered extensions can reach it without importing `@llblab/pi-telegram`.
 
 ## Verdicts
 
-Each interceptor returns one of:
+Each handler returns one of:
 
 - `"consume"` — `pi-telegram` skips its default routing for this update.
-- `"pass"` or `void` / `undefined` — `pi-telegram` routes the update normally. Other interceptors registered after this one still run for the same update.
+- `"pass"` or `void` / `undefined` — `pi-telegram` routes the update normally. Other handlers registered after this one still run for the same update.
 
-The first interceptor that returns `"consume"` wins; later interceptors are not called for that update.
+The first handler that returns `"consume"` wins; later handlers are not called for that update.
 
-## Registering an interceptor
+## Registering a handler
 
 Two equivalent paths.
 
 ### Typed import (recommended when you can depend on `@llblab/pi-telegram`)
 
 ```ts
-import { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
+import { registerTelegramUpdateHandler } from "@llblab/pi-telegram/updates";
 
-const off = onTelegramExternalUpdate(async (update) => {
+const off = registerTelegramUpdateHandler(async (update) => {
   const cb = (update as { callback_query?: { id?: string; data?: string } })
     .callback_query;
   if (!cb?.data?.startsWith("myext:")) return "pass";
@@ -57,7 +59,7 @@ off();
 
 ### Zero-coupling globalThis lookup
 
-When the layered extension prefers no `import` from `@llblab/pi-telegram`, so load order between the two extensions does not matter and either can be installed first, it must implement the **full v1 registry contract**, not just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on whatever object it finds at `globalThis.__piTelegramExternalHandlerRegistry__`, so a partial object would silently break the first update.
+When the layered extension prefers no `import` from `@llblab/pi-telegram`, so load order between the two extensions does not matter and either can be installed first, it must implement the **full v1 registry contract**, not just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on whatever object it finds at `globalThis.__piTelegramUpdateHandlerRegistry__`, so a partial object would silently break the first update.
 
 pi-telegram defensively re-creates the registry if the object on `globalThis` is missing `add` or `dispatch`, validated as `version === 1`, `typeof add === "function"`, and `typeof dispatch === "function"`. Handlers registered against a malformed object are dropped — make sure your bootstrap implements all three fields.
 
@@ -67,21 +69,21 @@ type PiTelegramVerdict =
   | "pass"
   | void
   | Promise<"consume" | "pass" | void>;
-type PiTelegramInterceptor = (update: unknown) => PiTelegramVerdict;
+type PiTelegramUpdateHandler = (update: unknown) => PiTelegramVerdict;
 
-interface PiTelegramExternalHandlerRegistry {
+interface PiTelegramUpdateHandlerRegistry {
   readonly version: 1;
-  add: (handler: PiTelegramInterceptor) => () => void;
+  add: (handler: PiTelegramUpdateHandler) => () => void;
   // Required: pi-telegram's polling loop calls this on every update.
   dispatch: (update: unknown) => Promise<"consume" | "pass">;
 }
 
-const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
+const REGISTRY_KEY = "__piTelegramUpdateHandlerRegistry__";
 
-function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
+function getOrCreateRegistry(): PiTelegramUpdateHandlerRegistry {
   const g = globalThis as Record<string, unknown>;
   const existing = g[REGISTRY_KEY] as
-    | PiTelegramExternalHandlerRegistry
+    | PiTelegramUpdateHandlerRegistry
     | undefined;
   if (
     existing &&
@@ -91,8 +93,8 @@ function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
   ) {
     return existing;
   }
-  const handlers = new Set<PiTelegramInterceptor>();
-  const registry: PiTelegramExternalHandlerRegistry = {
+  const handlers = new Set<PiTelegramUpdateHandler>();
+  const registry: PiTelegramUpdateHandlerRegistry = {
     version: 1,
     add(handler) {
       handlers.add(handler);
@@ -104,7 +106,7 @@ function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
           const result = await handler(update);
           if (result === "consume") return "consume";
         } catch {
-          // Never break polling because of an interceptor error.
+          // Never break polling because of a handler error.
         }
       }
       return "pass";
@@ -120,32 +122,32 @@ const off = getOrCreateRegistry().add((update) => {
 });
 ```
 
-The registry object on `globalThis.__piTelegramExternalHandlerRegistry__` is versioned (`version: 1`) and stable across pi-telegram releases; future breaking changes will use a new schema version and a new key.
+The registry object on `globalThis.__piTelegramUpdateHandlerRegistry__` is versioned (`version: 1`) and stable across pi-telegram releases; future breaking changes will use a new schema version and a new key.
 
 ## Interaction with built-in routing
 
-`pi-telegram` invokes registered interceptors first, then routes the update through its own handlers: commands, app menu, queue menu, model menu, default prompt routing, and callback namespace fallback. If any interceptor returns `"consume"`, `pi-telegram` skips the rest of routing for that update.
+`pi-telegram` invokes registered handlers first, then routes the update through its own handlers: commands, app menu, queue menu, model menu, default prompt routing, and callback namespace fallback. If any handler returns `"consume"`, `pi-telegram` skips the rest of routing for that update.
 
 This means:
 
 - Extensions can claim callback namespaces that `pi-telegram` would otherwise forward as `[callback] <data>` text.
 - Extensions can observe updates by always returning `"pass"`.
-- Extensions must not consume updates that belong to `pi-telegram`'s own prefixes (`tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`) unless they are deliberately replacing that behavior.
+- Extensions must not consume updates that belong to `pi-telegram`'s own prefixes (`compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, `section:`) unless they are deliberately replacing that behavior.
 
 ## Ownership semantics
 
-The interceptor registry is ownership-agnostic and does not interact with the `locks.json` singleton lock documented in [Locks](./locks.md). When the locked polling runtime stops `pi-telegram`'s poller, for example after ownership is moved to another pi process, interceptors stop receiving updates because no updates are being fetched. They are not unregistered.
+The handler registry is ownership-agnostic and does not interact with the `locks.json` singleton lock documented in [Locks](./locks.md). When the locked polling runtime stops `pi-telegram`'s `getUpdates` loop, for example after ownership is moved to another pi process, handlers stop receiving updates because no updates are being fetched. They are not unregistered.
 
-If a layered extension needs to react to ownership changes, it should observe `pi-telegram` lifecycle events through the standard pi extension hooks rather than through the interceptor registry.
+If a layered extension needs to react to ownership changes, it should observe `pi-telegram` lifecycle events through the standard pi extension hooks rather than through the handler registry.
 
 ## Not a multiplexer
 
-This registry does not multiplex one bot across multiple pi processes, and it does not bypass Telegram's single-poller-per-bot constraint. To run multiple pi instances on Telegram, give each instance its own bot and its own `~/.pi/agent` directory; the registry is for layered extensions inside **one** pi process.
+This registry does not multiplex one bot across multiple pi processes, and it does not bypass Telegram's single-polling-connection-per-bot constraint. To run multiple pi instances on Telegram, give each instance its own bot and its own `~/.pi/agent` directory; the registry is for layered extensions inside **one** pi process.
 
 ## Relationship to extension sections
 
-External handlers are the raw update primitive. Extension sections are the structured Telegram UI layer above that primitive.
+Update handlers are the raw update primitive. Extension sections are the structured Telegram UI layer above that primitive.
 
-Use external handlers for immediate update interception, custom callback namespaces, out-of-band Promise resolution, and update types that should not become a Telegram menu surface.
+Use update handlers for immediate update interception, custom callback namespaces, out-of-band Promise resolution, and update types that should not become a Telegram menu surface.
 
 Use extension sections when the desired behavior is a menu-integrated UI: `render(ctx)`, managed callback dispatch, safe runtime ports, stale-callback handling, and diagnostics owned by `pi-telegram`.

package/docs/voice.md

@@ -1,6 +1,6 @@
 # Voice Integration
 
-Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by voice provider extensions. In `0.11.0`, this is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot poller.
+Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by voice provider extensions. This is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot polling loop.
 
 ## Overview
 
@@ -29,7 +29,7 @@ Inbound handlers match `kind: "voice"` or `mime: "audio/*"` to run a transcripti
 
 The transcription output becomes the raw text of the prompt.
 
-Voice provider extensions can also register STT backends with `registerTelegramVoiceTranscriptionProvider()` from `@llblab/pi-telegram/lib/voice.ts`. Inbound command-template handlers and programmatic inbound handlers remain the stronger generic paths and run first; if no matching handler produces output for a voice/audio file, registered transcription providers are tried as fallback in registration order. The first provider that returns non-empty text wins; providers that return `undefined` pass to the next provider, and provider failures are recorded before trying the next provider. This lets a full voice extension provide both TTS and STT without requiring `telegram.json` handler templates, while still preserving operator-configured inbound handlers as the stronger choice.
+Voice provider extensions can also register STT backends with `registerTelegramVoiceTranscriptionProvider()` from `@llblab/pi-telegram/voice`. Inbound command-template handlers and programmatic inbound handlers remain the stronger generic paths and run first; if no matching handler produces output for a voice/audio file, registered transcription providers are tried as fallback in registration order. The first provider that returns non-empty text wins; providers that return `undefined` pass to the next provider, and provider failures are recorded before trying the next provider. This lets a full voice extension provide both TTS and STT without requiring `telegram.json` handler templates, while still preserving operator-configured inbound handlers as the stronger choice.
 
 ## Voice Reply Policy
 
@@ -67,33 +67,33 @@ The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode
 
 ## Outbound Voice Synthesis Provider Registration
 
-Voice synthesis provider extensions (such as `pi-xai-voice`) register themselves through `registerTelegramVoiceSynthesisProvider()`. The bridge only provides the registration seam and the actual delivery to Telegram. **The provider is fully responsible for**:
+Voice synthesis provider extensions register themselves through `registerTelegramVoiceSynthesisProvider()`. The bridge only provides the registration seam and the actual delivery to Telegram. **The provider is fully responsible for**:
 
 - Text optimisation / speech-style rewriting
 - Adding speech tags (when desired)
 - Running TTS + ffmpeg conversion to OGG/Opus
-- Deciding whether to return `transcriptText` at all (based on the user's "Send Transcript" toggle)
+- Deciding whether to return `transcriptText` at all based on the bridge-owned `voice.sendTranscript` preference when the provider has access to the current Telegram config
 - `transcriptText` (when returned) is attached by the bridge as the voice message **caption** only. Separate transcript messages are no longer sent.
 
 The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`. When a provider returns `transcriptText`, the bridge attaches it as the voice caption.
 
 Providers can implement `getVoicePromptContribution(view)` to inject voice-specific instructions into voice-tagged prompts (for example: "Reply only with the spoken text"). The bridge appends the first non-empty provider contribution when `mirror` or `always` mode tags the turn.
 
-See the TSDoc on `registerTelegramVoiceSynthesisProvider` and `TelegramVoiceSynthesisProviderResult` in `lib/voice.ts` for the exact interface.
+Import provider APIs from `@llblab/pi-telegram/voice`; see the TSDoc on `registerTelegramVoiceSynthesisProvider` and `TelegramVoiceSynthesisProviderResult` there for the exact interface.
 
 The provider receives the raw agent text plus optional `{ lang?, rate? }`.
 
 It must return one of:
 
 - `string` — path to a ready `.ogg` or `.opus` file
-- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. A provider UI can expose a "Send Transcript" toggle by returning `transcriptText` only when that toggle is enabled.
+- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. Providers should treat pi-telegram's `voice.sendTranscript` as the bridge-owned transcript preference instead of inventing a second reply-policy UI.
 - `undefined` — skip this text block
 
 **Important:** Providers are fully responsible for producing a clean, TTS-optimised native voice file. The bridge may also run configured outbound voice command templates for users who prefer process-boundary handlers instead of provider extensions.
 
 **File format:** Telegram `sendVoice` requires **OGG/Opus** to display the message as a native voice note (waveform, inline playback). MP3 and other formats are accepted by the API but render as regular audio attachments (music note icon, filename visible). **Providers and outbound voice handlers must return `.ogg` or `.opus` files.** Returning non-OGG files causes the bridge to throw and fall back to text delivery.
 
-Registration returns a disposer function for cleanup. Extensions should call it on shutdown or re-register safely on session start when their runtime is recreated.
+Registration returns a disposer function for cleanup. Stable provider registrations pass a durable `id` in options; omitted ids remain a compatibility path for older providers and receive generated session-local ids. Extensions should call disposers on shutdown or re-register safely on session start when their runtime is recreated.
 
 ## Outbound Voice Handlers
 
@@ -124,26 +124,34 @@ Priority for outbound voice delivery is: configured `outboundHandlers` with `typ
 When the user's "Send Transcript" toggle is ON, return the clean spoken text as `transcriptText`. The bridge attaches it as the caption on the voice message. When the toggle is OFF, return only the audio path (no `transcriptText`).
 
 ```typescript
-import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/lib/voice.ts";
-
-registerTelegramVoiceSynthesisProvider(async (text, options) => {
-  const rewritten = rewriteWithSpeechTags(text);
-  const audioPath = await myTTS(rewritten, { language: options?.lang });
-  const sendTranscript = getUserSendTranscriptPreference(); // from your UI + telegram.json
-  return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
-});
+import {
+  getTelegramVoiceSendTranscript,
+  registerTelegramVoiceSynthesisProvider,
+} from "@llblab/pi-telegram/voice";
+
+registerTelegramVoiceSynthesisProvider(
+  async (text, options) => {
+    const rewritten = rewriteWithSpeechTags(text);
+    const audioPath = await myTTS(rewritten, { language: options?.lang });
+    const sendTranscript = getTelegramVoiceSendTranscript(
+      getCurrentTelegramConfigView(),
+    );
+    return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
+  },
+  { id: "my-voice-provider/tts" },
+);
 ```
 
-The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
+`getCurrentTelegramConfigView()` represents whatever current `TelegramConfig` view your extension already owns or receives; pi-telegram does not require providers to read config directly. The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
 
 ### Surfacing provider diagnostics
 
 Voice provider extensions can record runtime events that appear in `/telegram-status` alongside pi-telegram's own events:
 
 ```typescript
-import { recordTelegramRuntimeEvent } from "@llblab/pi-telegram/lib/outbound-handlers.ts";
+import { recordTelegramRuntimeEvent } from "@llblab/pi-telegram/outbound";
 
-recordTelegramRuntimeEvent("xai-voice", new Error("TTS failed"), {
+recordTelegramRuntimeEvent("voice-provider", new Error("TTS failed"), {
   phase: "tts",
   text: text.slice(0, 50),
 });
@@ -155,7 +163,7 @@ recordTelegramRuntimeEvent("xai-voice", new Error("TTS failed"), {
 
 Voice provider extensions can register a Voice Extension Section (settings UI) via `registerTelegramSection`. The section can expose provider-specific controls such as TTS voice, language, speech style, transcript behavior, or STT/TTS enablement. Reply mode is a core pi-telegram setting and belongs in the built-in Settings menu.
 
-**Note on resume:** Because the previous automatic persistent re-registration system has been removed, extensions are responsible for re-registering their Voice Extension Section on `session_start` if they want the menu to survive a `pi resume`. See `registerTelegramSection` in `lib/extension-sections.ts`.
+**Note on resume:** Because the previous automatic persistent re-registration system has been removed, extensions are responsible for re-registering their Voice Extension Section on `session_start` if they want the menu to survive a `pi resume`. See `registerTelegramSection` from `@llblab/pi-telegram/sections`.
 
 ## Prompt Guidance