@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-telegram/docs/ui-style.md

@@ -0,0 +1,256 @@
+# 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.
+
+## Emoji Semantics
+
+Use emoji as stable semantic markers, not decoration. Emoji carry transportable meaning across command descriptions, inline menu rows, message headings, status copy, and tests. Before adding a new UI emoji, either reuse one below or extend this registry in the same change.
+
+### Domain Markers
+
+| Emoji | Meaning | Canonical surfaces | Notes |
+| --- | --- | --- | --- |
+| `🧵` | Telegram/Pi thread routing | Thread chooser headings, unbound-thread warnings, thread lifecycle/status copy | Canonical thread marker. Do not add it to every concrete target button; target buttons use `threadName` or slot fallback. |
+| `📡` | Telegram transport / bridge connection | Instance connected notices, polling/transport role, bridge online copy | Transport is not thread identity; use `🧵` for thread concepts. |
+| `📊` | Status / overview | `/status` command description, status cards or status rows | Use for status summaries, not queue priority. |
+| `🤖` | Model selection | `/model`, model menu headings, model status rows | Keep model-control surfaces visually distinct from thinking. |
+| `🧠` | Thinking level | `/thinking`, thinking menu headings, thinking status rows | Use only for reasoning/thinking controls. |
+| `🔢` | Queue list / ordered work | `/queue`, queue menu entrypoints | Queue item rows may also use numeric labels. |
+| `⏱️` | Queue is ticking / current work is active | Inline main-menu Queue row only | Running-clock queue state: the narrow present moment is being worked now. |
+| `⏳` | Queue has waiting prompts | Inline main-menu Queue row only | Hourglass queue state: sand above the neck is future work still waiting. |
+| `⌛` | Queue is empty / standing idle | Inline main-menu Queue row only | Standing hourglass queue state: no future work is waiting above the neck. |
+| `⚙️` | Settings / configuration | Settings menu headings and Settings navigation rows | Extension-injected rows appear before the built-in `⚙️ Settings` row. |
+| `🧩` | Extension-provided surface | Extension command examples, extension section examples | Companion extensions may choose their own emoji, but `🧩` means generic extension/plugin. |
+| `👄` | Voice reply policy | Voice reply settings row and detail card | Not a generic audio attachment marker. |
+| `🕒` | Time injection / wall-clock context | Time injection settings row and detail card | Clock-face marker with hands; not a generic duration/progress marker. |
+| `📌` | Proactive push / pinned behavior | Proactive push settings row and detail card | Not generic active/selected state. |
+| `🔬` | Activity / technical detail | Activity settings row and detail card | Chooses quiet, thinking, tools, or verbose bridge activity; not a generic diagnostics marker. |
+| `🧠` | Model thinking controls | Thinking menus and status rows | Thinking activity quotes omit this icon and their header entirely to minimize chat height. |
+| `📎` | Attachment | Attachment summaries, queue rows for attachment-only turns | Not for thread binding. |
+
+### Command And Control Actions
+
+| Emoji | Meaning | Canonical surfaces | Notes |
+| --- | --- | --- | --- |
+| `🟢` | Start / active / current positive state | `/start`, active row, current selected option, active `On` toggle | In command context it means “open/start menu”; in state context it means selected/active. |
+| `🗜` | Compact session | `/compact`, compact confirmation action | Do not use for generic cleanup/delete. |
+| `⏩` | Force next queued turn | `/next` command and matching menu action | Means skip/advance to next waiting item. |
+| `▶️` | Continue/resume generation | `/continue` command and matching menu action | Means resume/continue current session flow, not force-next. |
+| `⏹️` | Abort current Pi work | `/abort` command description | Stops active work but is not a destructive queue clear by itself. |
+| `🟥` | Stop / abort-and-clear danger | `/stop` command description | Stronger than `⏹️`; use for disruptive stop/clear semantics. |
+| `🆕` | New session / fresh start | Reserved visible extension command example for `/new`-like flows | Same-thread Telegram `/new` is currently blocked by Pi core API; keep this meaning reserved. |
+| `🌀` | Refresh | Queue refresh row and future refresh buttons | Re-fetch/re-render current surface, not transport reconnect. |
+| `↪️` | Reroute to an existing target | Thread chooser buttons that send a captured command/message from one thread to another live thread | Curved arrow means the message arrived here but bends to another target. |
+| `🔁` | Replace/restore mode | Thread replace/restore chooser entrypoints | Opens a second step for moving a Pi instance binding to the current source thread. |
+| `➡️` | Choose replacement target | Thread replace/restore target buttons that select which Pi instance should move to the current thread | Use inside the second replace/restore chooser, not for ordinary reroutes. |
+| `☑️` | Activate / choose this item | Model detail activation action, generated button-only choice heading | Positive selection cue; use `🟢 Active` for already-current state. |
+| `❌` | No / cancel | Confirmation cancel buttons | Use for safe cancellation, not destructive removal. |
+| `🗑` | Delete / defer removal | Destructive confirmations and removal reaction | In the queue menu, reversible Keep/Skip selectors replace immediate deletion. |
+
+### State Indicators And Button Grammars
+
+| Emoji | Meaning | Canonical surfaces | Notes |
+| --- | --- | --- | --- |
+| `🟢` | Current/active/enabled `On` | Current option in vertical lists, active state rows, active `On` toggle | One strong current marker per option list. |
+| `🟡` | Active `Off` or elevated/filter state | Active `Off` toggle, Priority/Scoped active tab | Yellow means intentionally not-normal or off/default-caution, not error. |
+| `🔴` | Active destructive/deferred disposition | Active queue `Skip` selector | Red distinguishes a prompt that will be discarded at dispatch from reversible neutral or elevated state. |
+| `🟣` | Normal/default active tab | Normal priority tab, All/default scope tab, active page picker | Use for neutral active tabs. |
+| `⚫️` | Inactive placeholder | Inactive toggle values and inactive tabs | Keeps row width stable. |
+| `⬆️` | Navigate upward | `⬆️ Main menu`, `⬆️ Back` | Always first row in submenus. |
+
+### Queue Reaction Shortcuts
+
+Queue reactions are shortcut controls for waiting turns. Preserve their semantics across Telegram reactions, queue-menu rows, status previews, and tests. Positive emoji control the Priority/Normal lane; negative emoji control Keep/Skip. These categories are independent, may coexist, and mutate only their own dimension. Crossing lanes appends the prompt at the destination FIFO tail; changing Keep/Skip or changing emoji within one category preserves lane position. Skip wins only when dispatch reaches the prompt.
+
+Queue item detail renders two independent selector rows:
+
+- `🟡 Priority` / `⚫️ Normal` or `⚫️ Priority` / `🟣 Normal` selects the lane.
+- `🟢 Keep` / `⚫️ Skip` or `⚫️ Keep` / `🔴 Skip` selects dispatch disposition.
+
+The menu may clear internal Skip but cannot remove a reaction created by the user through Telegram's Bot API.
+
+| Emoji | Meaning | Canonical surfaces | Notes |
+| --- | --- | --- | --- |
+| `👍` | Promote to priority | Queue reaction shortcut | Normalized from variants like `👍️`. |
+| `⚡` | Promote to priority / fast lane | Queue reaction shortcut, priority fallback badge | Also used as the default priority badge when no specific priority emoji is stored. |
+| `❤` / `❤️` | Promote to priority | Queue reaction shortcut | Normalize display consistently where code normalizes reactions. |
+| `🕊` / `🕊️` | Promote to priority | Queue reaction shortcut | Soft/peaceful promotion gesture. |
+| `🔥` | Promote to priority | Queue reaction shortcut | Urgent/hot promotion gesture. |
+| `👎` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Reversible until the marked turn reaches dispatch; not negative feedback to the agent. |
+| `👻` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Disappear/remove metaphor. |
+| `💔` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Reversible cancel metaphor. |
+| `💩` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Reversible reject metaphor. |
+| `🗑` | Defer removal | Queue reaction shortcut and queue emoji marker | Like Skip, the reaction remains reversible until dispatch reaches the marked turn. |
+
+### Decorative Or Local-Example Emoji
+
+Some emoji are intentionally local examples or decorative variants, not global semantics. Empty-queue rotating messages (`🫙`, `🍃`, `🕳`, `🦗`, `🌙`, `🧘`, `🪐`, `🧺`, `🔭`, `🫧`, `🛸`) are copy flavor only and must not become controls. Example extension icons such as `🧪`, `🔧`, and `🗂` are documentation fixtures for companion extensions, not built-in pi-telegram meanings.
+
+Thread UI rule: when a message heading, chooser, or status line is specifically about Telegram/Pi threads or target thread selection, start the heading with `🧵`. Button labels for concrete thread targets should stay clean (`threadName` or slot fallback) and should not add `🧵` to every target button unless the row would otherwise be ambiguous.
+
+## 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.
+
+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:
+
+- `hidden`
+- `🟢 mirror`
+- `always`
+
+## Generated Prompt Buttons
+
+A button-only assistant reply uses the standard Rich Markdown heading `☑️ **Choose an option:**`: semantic icon first, one space, bold heading text, and a final colon. Assistant-generated prompt buttons use the default app style before selection. After queue admission, edit only the selected button to its agent-configured `selected_style`: `primary` (default/blue), `success` (green), or `danger` (red). Preserve its agent-authored text and emoji, leave other choices at their default style, and always queue the selected prompt regardless of color. The callback acknowledgement remains the compatibility fallback when a client does not render button styles.
+
+## 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.
+- Order setting value descriptions exactly like the chooser: rows top-to-bottom and values in a shared row left-to-right. Keep `(default)` on the actual default wherever it falls; default status never changes order.
+- 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/node_modules/@llblab/pi-telegram/docs/updates.md

@@ -0,0 +1,171 @@
+# 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.
+
+The `0.28.0` transport/execution split is specified in [Durable Admission And Recovery](./architecture.md#durable-admission-and-recovery). Polling durably admits and advances batches before the independent worker invokes this registry. The worker binds source ids only after public interception passes, supplies public and built-in handlers with the same optional execution fence, settles late grouping under its exact generation, and publishes durable queue readiness. This document describes the executable public registry contract.
+
+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
+
+Use it when a layered extension needs to:
+
+- Resolve out-of-band state, for example a `tool_call` approval Promise, the moment a Telegram callback arrives, rather than waiting for the next agent turn.
+- Suppress `pi-telegram`'s default routing for callbacks owned by the layered extension, so `pi-telegram` does not also forward them as `[callback] <data>` text.
+- Observe arbitrary update types such as messages, edits, channel posts, or reactions without owning the polling connection.
+
+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](./sections.md) contract instead of a raw update handler.
+
+## Constraints
+
+- One bot profile has one leader-owned `getUpdates` loop. This process-local registry neither creates another transport nor replaces the Threaded Mode leader/follower bus.
+- Handlers run before built-in routing in the independent semantic worker. They must return promptly because a long await delays later handler/routing execution for that source order, but it does not delay `getUpdates` admission or offset persistence. Replacement generations wait for the unsettled handler rather than executing the same update concurrently.
+- Handler errors are caught and logged silently so polling never breaks. If you need durable error reporting, do it inside your handler.
+- Typed handlers receive an optional second `execution` argument with `signal`, `updateId`, `generation`, `isCurrent()`, and `assertCurrent()`. Pass `signal` into cancellable work and call `assertCurrent()` immediately before irreversible effects. The runtime also rejects a verdict returned after cancellation. Legacy one-argument and zero-coupling handlers remain compatible, but any effect they commit while still awaiting is their responsibility; replacement replay still waits for that handler's actual settlement.
+- The registry lives on `globalThis`. Module instance identity is not required, so layered extensions can reach it without importing `@llblab/pi-telegram`.
+
+## Verdicts
+
+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 handlers registered after this one still run for the same update.
+
+The first handler that returns `"consume"` wins; later handlers are not called for that update.
+
+## Registering a handler
+
+Two equivalent paths.
+
+### Typed import (recommended when you can depend on `@llblab/pi-telegram`)
+
+```ts
+import { registerTelegramUpdateHandler } from "@llblab/pi-telegram/updates";
+
+const off = registerTelegramUpdateHandler(async (update, execution) => {
+  const cb = (update as { callback_query?: { id?: string; data?: string } })
+    .callback_query;
+  if (!cb?.data?.startsWith("myext:")) return "pass";
+  await resolveMyApproval(cb, execution?.signal);
+  execution?.assertCurrent();
+  return "consume";
+});
+
+// Later, when your extension shuts down:
+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.__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.
+
+```ts
+type PiTelegramVerdict =
+  | "consume"
+  | "pass"
+  | void
+  | Promise<"consume" | "pass" | void>;
+type PiTelegramUpdateExecutionFence = {
+  readonly generation: number;
+  readonly updateId: number;
+  readonly signal: AbortSignal;
+  isCurrent: () => boolean;
+  assertCurrent: () => void;
+};
+type PiTelegramUpdateHandler = (
+  update: unknown,
+  execution?: PiTelegramUpdateExecutionFence,
+) => PiTelegramVerdict;
+
+interface PiTelegramUpdateHandlerRegistry {
+  readonly version: 1;
+  add: (handler: PiTelegramUpdateHandler) => () => void;
+  // Required: pi-telegram's polling loop calls this on every update.
+  dispatch: (
+    update: unknown,
+    execution?: PiTelegramUpdateExecutionFence,
+  ) => Promise<"consume" | "pass">;
+}
+
+const REGISTRY_KEY = "__piTelegramUpdateHandlerRegistry__";
+
+function getOrCreateRegistry(): PiTelegramUpdateHandlerRegistry {
+  const g = globalThis as Record<string, unknown>;
+  const existing = g[REGISTRY_KEY] as
+    | PiTelegramUpdateHandlerRegistry
+    | undefined;
+  if (
+    existing &&
+    existing.version === 1 &&
+    typeof existing.add === "function" &&
+    typeof existing.dispatch === "function"
+  ) {
+    return existing;
+  }
+  const handlers = new Set<PiTelegramUpdateHandler>();
+  const registry: PiTelegramUpdateHandlerRegistry = {
+    version: 1,
+    add(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    async dispatch(update, execution) {
+      for (const handler of handlers) {
+        execution?.assertCurrent();
+        try {
+          const result = await handler(update, execution);
+          if (result === "consume") return "consume";
+        } catch {
+          // Never break polling because of a handler error.
+        }
+      }
+      return "pass";
+    },
+  };
+  g[REGISTRY_KEY] = registry;
+  return registry;
+}
+
+const off = getOrCreateRegistry().add((update) => {
+  /* … */
+  return "pass";
+});
+```
+
+The registry object on `globalThis.__piTelegramUpdateHandlerRegistry__` is versioned (`version: 1`) and stable across pi-telegram releases; the optional second arguments preserve existing v1 callers and implementations. Internal adapters can capture one stable check with `createTelegramUpdateExecutionFenceGuard(update)` or transfer the hidden binding across an unavoidable clone with `carryTelegramUpdateExecutionFence(source, target)`, while `getTelegramUpdateExecutionFence` and `assertTelegramUpdateExecutionCurrent` serve carriers that retain it. Future breaking changes will use a new schema version and a new key.
+
+## Interaction with built-in routing
+
+`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 (`compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, `section:`) unless they are deliberately replacing that behavior.
+
+## Ownership semantics
+
+The handler registry is ownership-agnostic and does not interact with the extension-local transport owner slots documented in [Architecture](./architecture.md#configuration-and-ownership). When the polling runtime loses its `owners.json` slot and stops `getUpdates`, 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 handler registry.
+
+## Not a transport multiplexer
+
+This registry does not bypass Telegram's single-polling-connection-per-bot constraint and does not route updates between processes. Threaded Mode provides the separate profile-scoped leader/follower bus: the leader owns `getUpdates`, applies its process-local update registry, and then routes retained built-in traffic to the owning instance. The registry remains an in-process extension interception surface only.
+
+## Relationship to extension sections
+
+Update handlers are the raw update primitive. Extension sections are the structured Telegram UI layer above that primitive.
+
+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/node_modules/@llblab/pi-telegram/docs/voice.md

@@ -0,0 +1,217 @@
+# 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. 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
+
+1. **Inbound:** A voice message arrives via Telegram. Inbound handlers transcribe it to text.
+2. **Processing:** The transcription becomes the agent prompt. The bridge tags the turn if it originated from voice.
+3. **Outbound:** If voice replies are enabled, the agent's text response is converted to voice and sent back. No text draft appears in Telegram during generation.
+
+The bridge owns Telegram transport, queue integration, reply-mode policy, preview suppression, fallback text delivery, and Settings UI. Provider extensions own STT/TTS calls, speech rewriting, provider-specific menus, transcript preference, and OGG/Opus conversion.
+
+## Voice Detection
+
+Voice messages arrive as `message.voice` in Telegram updates. The bridge's media processing detects these and sets `kind: "voice"` on the downloaded file. Regular audio files (`message.audio`) get `kind: "audio"`; `mirror` mode treats both voice notes and audio uploads as voice input for reply-policy tagging.
+
+Inbound handlers match `kind: "voice"` or `mime: "audio/*"` to run a transcription command:
+
+```json
+{
+  "inboundHandlers": [
+    {
+      "mime": "audio/*",
+      "template": ["/path/to/stt", "--file={file}", "--mime={mime}"]
+    }
+  ]
+}
+```
+
+The transcription output becomes the raw text of the prompt.
+
+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
+
+The bridge decides **when** to reply with voice from `voice.replyMode` in `TelegramConfig` (stored in `telegram.json`). Missing, invalid, `hidden`, and legacy `manual` values resolve to the silent `hidden` default.
+
+### Modes
+
+- **`hidden` (default):** no `voice.replyMode` is stored and no automatic voice context is added; explicit agent-authored `telegram_voice` actions still work.
+- **`mirror`:** voice/audio input activates automatic voice delivery. Text input follows `hidden` behavior.
+- **`always`:** every Telegram turn activates automatic voice delivery.
+
+**Warning:** In `always` mode, the bridge transparently intercepts ALL text replies and converts them to voice on success. Users will only receive voice messages when voice generation succeeds. If voice generation fails, the bridge falls back to sending the planned text reply.
+
+When a message is received, the bridge resolves the active voice reply mode and tags the turn:
+
+- `voiceReplyPreferred`: `true` when mode is `mirror` and the turn has a voice file
+- `voiceReplyRequired`: `true` when mode is `always`
+
+At `agent_end`, if the turn is voice-tagged and the agent response has no explicit `telegram_voice` markup, the bridge transparently intercepts the text reply and converts it to voice. If the agent uses multiple `telegram_voice` blocks, each becomes a separate voice message. The same reply-mode decision applies to both registered voice synthesis providers and configured outbound voice handlers.
+
+### Preview Suppression
+
+When a turn is voice-tagged, the bridge suppresses text preview streaming during LLM generation. This prevents draft text from appearing in Telegram before the voice message is delivered.
+
+## Voice Provider Extension Surface
+
+A voice extension may combine three public seams:
+
+- `registerTelegramVoiceTranscriptionProvider()` for inbound STT fallback on voice/audio files
+- `registerTelegramVoiceSynthesisProvider()` for outbound TTS/synthesis fallback to Telegram voice messages
+- `registerTelegramSection()` for provider-specific Telegram UI such as voice, language, style, transcript, or provider on/off controls
+
+The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode`) rather than a provider-owned menu.
+
+## Outbound Voice Synthesis Provider Registration
+
+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 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.
+
+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**. 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. 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
+
+Users can also configure `outboundHandlers` with `type: "voice"` in `telegram.json`. This is the command-template path for TTS without a provider extension. Reply modes (`hidden`, `mirror`, `always`) affect these handlers the same way they affect providers: explicit `telegram_voice` blocks and automatic mirror/always interception both produce a voice reply plan, then delivery tries configured outbound voice handlers first and registered synthesis providers as progressive fallbacks.
+
+Voice handlers receive the text on stdin in composed pipelines and can use `{text}`, `{lang}`, `{rate}`, `{mp3}`, and `{ogg}` placeholders. Set `output` to `"ogg"` or another placeholder name when the template writes to a known path:
+
+```json
+{
+  "voice": { "replyMode": "mirror" },
+  "outboundHandlers": [
+    {
+      "type": "voice",
+      "template": [
+        "/path/to/tts --write-media {mp3}",
+        "ffmpeg -y -i {mp3} -c:a libopus -b:a 32k -ar 16000 -ac 1 {ogg}"
+      ],
+      "output": "ogg"
+    }
+  ]
+}
+```
+
+Priority for outbound voice delivery is: configured `outboundHandlers` with `type: "voice"` in their `telegram.json` order, then programmatic `voice` outbound handlers, then registered voice synthesis providers. Provider extensions are the zero-config tail of the same pipeline: they handle voice when no explicit configured handler succeeds, but they do not override operator-configured handlers. If multiple providers are registered, only one handles a given voice reply: the first provider that returns a valid `.ogg`/`.opus` artifact wins. Providers that return `undefined` explicitly pass to the next provider; providers that throw or return invalid output are recorded and the next fallback is tried.
+
+### Provider with transcript caption (controlled by user toggle)
+
+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 {
+  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" },
+);
+```
+
+`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/outbound";
+
+recordTelegramRuntimeEvent("voice-provider", new Error("TTS failed"), {
+  phase: "tts",
+  text: text.slice(0, 50),
+});
+```
+
+`recordTelegramRuntimeEvent` writes to the same event ring that pi-telegram uses. Events are visible via `/telegram-status` in Telegram. Calls are silently dropped if pi-telegram is not loaded.
+
+## Voice Extension Section
+
+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` from `@llblab/pi-telegram/sections`.
+
+## Prompt Guidance
+
+The bridge keeps voice prompt context compact, effective, and policy-owned. `hidden` and text-originated `mirror` turns add no voice line. Voice/audio-originated `mirror` turns and every `always` turn add exactly `[voice] delivery: automatic voice`, describing the current delivery environment without exposing the underlying mode matrix or an instruction list. The marker is appended after `[outputs]` when handler output exists, otherwise after `[attachments]`. Voice inputs also appear in `[attachments]` with their downloaded file names, MIME data, and handler output, so agents can infer concrete voice-file context from attachment metadata.
+
+Voice synthesis providers can supply prompt guidance through `getVoicePromptContribution(view)`, but provider text should stay optional and provider-specific. Reply-mode context belongs to pi-telegram.
+
+## Fallback Behavior
+
+### If voice generation fails
+
+1. The bridge records the failure via `recordRuntimeEvent`
+2. The voice sender throws an error, which the runtime catches
+3. The runtime falls back to sending the planned text reply (outbound markup stripped, `replyMarkup` preserved)
+
+### If no voice synthesis provider is registered
+
+- The voice sender throws because no configured handler or synthesis provider can deliver the voice reply
+- The runtime catches the error and falls back to text delivery
+
+### If the provider returns a non-OGG file
+
+- `ensureTelegramVoiceFileFormat` rejects the file (only `.ogg` and `.opus` are accepted)
+- The voice sender throws and the runtime falls back to text delivery
+- The provider should handle format conversion internally before returning the path
+
+## Telegram Voice Limits
+
+- **Duration:** Up to ~60 minutes per voice message
+- **File size:** Up to 20 MB for voice uploads via `sendVoice`
+- **Format:** OGG Opus is native; MP3 and other formats render as regular audio attachments
+- **Splitting:** The bridge does not split long responses into multiple voice messages. Chunking is the provider's responsibility
+
+## Configuration
+
+### Bridge config (`telegram.json`)
+
+```json
+{
+  "voice": {
+    "replyMode": "mirror"
+  }
+}
+```
+
+Valid modes are `"hidden"`, `"mirror"`, and `"always"`; selecting `hidden` removes the key. Missing, invalid, and legacy `"manual"` values resolve to `hidden` and stay silent in prompt context.
+
+The bridge reads `voice.replyMode` from the config when building a turn.
+
+### Provider config
+
+Provider-specific settings (voice ID, language, speech style, transcript behavior, STT/TTS enablement) are owned by the voice provider extension. Reply mode is owned by pi-telegram's `voice.replyMode` and configured from the built-in pi-telegram Settings menu, not duplicated in provider UIs.