@llblab/pi-telegram 0.11.2 → 0.13.0

package/docs/command-templates.md

@@ -33,14 +33,14 @@ There is no portable `command` field. The command is derived from `template`: af
 Common object fields:
 
 - `label`: Optional human label for diagnostics and parallel branch reports.
-- `mode`: Optional execution mode for array templates. Default is `"sequence"`; `"parallel"` runs children concurrently.
+- `parallel`: Optional boolean execution flag for array templates. Default is sequential execution; `true` runs children concurrently when the host execution layer supports branch fanout.
+- `when`: Optional boolean or condition string. Falsy values skip the node. String forms may reference a flag name, `!flag`, or a placeholder expression such as `{flag?yes:}`.
 - `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. Defaults belong in `defaults` or inline placeholder defaults; hosts may normalize interactive shorthand such as `timeout:int=60000` before persistence.
 - `defaults`: Placeholder default values by name.
-- `timeout`: Optional execution timeout in milliseconds. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely.
-- `delay`: Optional wait in milliseconds before starting this node. Default is no delay.
+- `timeout`: Optional execution timeout in milliseconds, as a number or placeholder-resolved string. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely.
+- `delay`: Optional wait in milliseconds before starting this node, as a number or placeholder-resolved string. Default is no delay.
 - `output`: Optional result selector. Default is `"stdout"`; runtime values such as `"ogg"` are valid.
-- `retry`: Optional max attempts including the first. Default is `1`.
-- `critical`: Optional boolean. Backward-compatible alias for `failure: "root"`.
+- `retry`: Optional max attempts including the first, as a number or placeholder-resolved string. Default is `1`.
 - `failure`: Optional failure propagation scope: `continue`, `branch`, or `root`. Default is `continue`.
 - `recover`: Optional command template run between failed retry attempts. Recovery output is ignored; recovery failure stops retries.
 - `template`: Required command string or ordered composition array.
@@ -68,6 +68,8 @@ Supported forms:
 | `{name}`         | Required value from runtime values or `defaults` |
 | `{name=default}` | Inline default when no value is provided         |
 | `{items[index]}` | Array item selected by literal or repeat index   |
+| `{value??fallback}` | Fallback when the value is absent or falsy    |
+| `{flag?yes:no}`  | Conditional text selected by flag truthiness     |
 
 Resolution order is runtime values → `defaults` → inline default → error. Default values that are themselves a single placeholder, such as `{prompt}` resolving to `{prompts[index]}`, are resolved recursively with a small depth guard. A repeat node may set `repeat` to `{items.length}` when an array arg should determine fanout width.
 
@@ -127,8 +129,8 @@ template="echo 'literal words' {text}"
 
 Composition rules:
 
-- Execute leaves in order when `mode` is omitted or set to `"sequence"`
-- Execute child templates concurrently when `mode` is set to `"parallel"`
+- Execute leaves in order by default
+- Execute child templates concurrently when `parallel` is `true`
 - Parallel composition uses soft-quorum semantics by default: failed children are reported as degraded branches unless failure propagation escalates
 - Non-critical failures are recorded and execution continues, while `failure: "branch"` stops the current branch and `failure: "root"` aborts the root composition
 - Treat the whole composition as one handler for selector matching and fallback
@@ -163,7 +165,7 @@ Composition rules:
 
 ```json
 {
-  "mode": "parallel",
+  "parallel": true,
   "repeat": 8,
   "template": "render page{_(index+1)}.html --prev page{_(prev+1)}.html --next page{_(next+1)}.html --zero page{_index}.html"
 }
@@ -198,7 +200,7 @@ Parallel nodes use the same object shape. Flags come first and `template` stays
   "template": [
     "prepare {out_dir}",
     {
-      "mode": "parallel",
+      "parallel": true,
       "template": [
         {
           "label": "gpt-5.5",
@@ -232,7 +234,7 @@ exit: 1
 stderr: provider balance exhausted
 ```
 
-Legacy local schemas may accept `pipe` as an alias, but the portable standard is `template: [...]`.
+Use `template: [...]` for ordered composition. Older local `pipe` aliases are not part of the 0.13.0 command-template standard.
 
 ## Fail-Open Default Policy
 
@@ -250,7 +252,7 @@ Use `failure` when a node should stop more aggressively:
 
 ```json
 {
-  "mode": "parallel",
+  "parallel": true,
   "template": [
     {
       "label": "agent-a",
@@ -276,7 +278,7 @@ Use `failure` when a node should stop more aggressively:
 
 If `agent-a-validate` fails, `agent-a-push` is skipped, `agent-b` can still finish, and the parallel join reports degraded branch coverage.
 
-`critical: true` remains a backward-compatible alias for `failure: "root"`. Prefer `failure` for new templates because it names the propagation scope directly.
+Use `failure: "root"` to abort the root composition. Older local `critical: true` shapes are not part of the 0.13.0 command-template standard.
 
 ## Retry
 
@@ -334,13 +336,13 @@ The standard uses a single `template` field that grows with the user's needs:
 string           → leaf command
 string[]         → sequential composition
 { template }     → leaf command object
-{ mode, template } → sequence or parallel subtree
-{ mode, args, defaults, delay, retry, failure, recover, output, template } → full node
+{ parallel, template } → parallel subtree
+{ parallel, when, args, defaults, delay, retry, failure, recover, output, template } → full node
 ```
 
-Start with a string. Add composition when needed. Add `mode: "parallel"` when independent work can run concurrently. Add delay when launch pacing matters. Add retry when flaky. Add `failure` when propagation scope matters. Add `recover` when a retried node needs cleanup before another attempt. Same contract, growing capability, no dead weight.
+Start with a string. Add composition when needed. Add `parallel: true` when independent work can run concurrently. Add `when` for conditional nodes. Add delay when launch pacing matters. Add retry when flaky. Add `failure` when propagation scope matters. Add `recover` when a retried node needs cleanup before another attempt. Same contract, growing capability, no dead weight.
 
-`mode: "parallel"` is the synchronous fanout shape. Saved JSON recipes and detached lifecycle concerns such as logs, cancellation, and durable state belong to host-specific recipe/async-run standards, not to command templates.
+`parallel: true` is the synchronous fanout shape. Saved JSON recipes and detached lifecycle concerns such as logs, cancellation, and durable state belong to host-specific recipe/async-run standards, not to command templates.
 
 ## Trust Boundary
 

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

@@ -49,7 +49,7 @@ Legacy `telegram.json` files may still define `attachmentHandlers` for media/fil
 
 At runtime, `attachmentHandlers` is appended after `inboundHandlers`. Existing configs continue to work, while new configs should use `inboundHandlers`.
 
-Handlers match by optional `type`, `mime`, or `match`. `mime` and `type` are independent selectors: if `mime` is present, `type` is not required. Wildcards such as `audio/*` or `text/*` are accepted. Each matching handler must provide `template`; a string is one command, and an array is ordered composition. Top-level `args` and `defaults` apply to composed steps unless a step defines private values. The command-template default timeout applies automatically. Legacy configs may still use `pipe` as a local alias.
+Handlers match by optional `type`, `mime`, or `match`. `mime` and `type` are independent selectors: if `mime` is present, `type` is not required. Wildcards such as `audio/*` or `text/*` are accepted. Each matching handler must provide `template`; a string is one command, and an array is ordered composition. Top-level `args` and `defaults` apply to composed steps unless a step defines private values. The command-template default timeout applies automatically. Use `template: [...]` for composition; the old local `pipe` alias is removed in 0.13.0.
 
 `defaults` may provide additional placeholder values such as `{lang}` or `{model}`. `args` is only a string-array declaration of supported placeholders; defaults belong in `defaults` or inline placeholders such as `{lang=ru}`. Examples prefer explicit flag-style CLIs such as `--file {file}` and `--lang {lang=ru}` for readability, but positional forms such as `/path/to/stt {file} {lang=ru} {model=voxtral-mini-latest}` are equally valid when the target script supports them.
 
@@ -88,9 +88,9 @@ If a matching handler fails with a non-zero exit code, the runtime records diagn
 
 ## Programmatic Inbound Handlers And STT Fallbacks
 
-Extensions can register programmatic inbound handlers with `registerTelegramInboundHandler(kind, handler)` from `@llblab/pi-telegram/lib/inbound-handlers.ts`. This is the code-level counterpart to configured `inboundHandlers`; use it for extension-owned transformations that are not voice-specific.
+Extensions can register programmatic inbound handlers with `registerTelegramInboundHandler(kind, handler)` from `@llblab/pi-telegram/inbound`. This is the code-level counterpart to configured `inboundHandlers`; use it for extension-owned transformations that are not voice-specific.
 
-Voice extensions can register STT providers with `registerTelegramVoiceTranscriptionProvider()` from `@llblab/pi-telegram/lib/voice.ts`. This is the zero-config extension path for voice/audio input: an extension such as `pi-xai-voice` can transcribe Telegram voice notes without requiring the operator to write an `inboundHandlers` command template.
+Voice extensions can register STT providers with `registerTelegramVoiceTranscriptionProvider()` from `@llblab/pi-telegram/voice`. This is the zero-config extension path for voice/audio input: a companion extension can transcribe Telegram voice notes without requiring the operator to write an `inboundHandlers` command template.
 
 Priority stays explicit and predictable:
 
@@ -101,14 +101,17 @@ Priority stays explicit and predictable:
 5. built-in text-file fallback for text attachments
 
 ```ts
-import { registerTelegramInboundHandler } from "@llblab/pi-telegram/lib/inbound-handlers.ts";
-import { registerTelegramVoiceTranscriptionProvider } from "@llblab/pi-telegram/lib/voice.ts";
-
-const disposeInbound = registerTelegramInboundHandler("document", async ({ file }) => {
-  if (!file?.mimeType?.includes("pdf")) return undefined;
-  const text = await extractPdf(file.path);
-  return text || undefined;
-});
+import { registerTelegramInboundHandler } from "@llblab/pi-telegram/inbound";
+import { registerTelegramVoiceTranscriptionProvider } from "@llblab/pi-telegram/voice";
+
+const disposeInbound = registerTelegramInboundHandler(
+  "document",
+  async ({ file }) => {
+    if (!file?.mimeType?.includes("pdf")) return undefined;
+    const text = await extractPdf(file.path);
+    return text || undefined;
+  },
+);
 
 const dispose = registerTelegramVoiceTranscriptionProvider(
   async (file) => {

package/docs/locks.md

@@ -58,13 +58,13 @@ During a user-initiated start/connect event, an extension should:
 1. Read its lock entry
 2. If `pid` is stale, replace the entry
 3. If `pid` and `cwd` match the current pi instance, refresh or keep the entry
-4. If a live external owner exists, ask interactively whether to move singleton ownership here
+4. If a live polling owner exists, ask interactively whether to move singleton ownership here
 
 ## Acquisition timing
 
 Lock writes must be caused by an explicit user-initiated runtime event, such as a start/connect command or a confirmed takeover prompt.
 
-Extension initialization and session-start hooks may read `locks.json`, update local status, install ownership watchers, and resume local work when the existing lock already points at the current `pid`/`cwd`. After a full process restart, a session-start hook may replace a stale lock from the same `cwd` to restore explicitly requested ownership. They must not create ownership from an inactive lock, take over a live external owner, or replace a stale lock from another directory by themselves. Such locks should stay visible as state until the user runs the start/connect command. Session replacement should suspend local runtime work and ownership watchers without releasing the lock, so the next session in the same `pid`/`cwd` can resume from explicit ownership.
+Extension initialization and session-start hooks may read `locks.json`, update local status, install ownership watchers, and resume local work when the existing lock already points at the current `pid`/`cwd`. After a full process restart, a session-start hook may replace a stale lock from the same `cwd` to restore explicitly requested ownership. They must not create ownership from an inactive lock, take over a live polling owner, or replace a stale lock from another directory by themselves. Such locks should stay visible as state until the user runs the start/connect command. Session replacement should suspend local runtime work and ownership watchers without releasing the lock, so the next session in the same `pid`/`cwd` can resume from explicit ownership.
 
 ## Optional fields
 
@@ -105,7 +105,7 @@ Extensions may prefix those states with their own compact name, such as `wakeup
 Start/connect commands should make singleton moves easy:
 
 1. If no live owner exists, take ownership without an extra prompt
-2. If a live external owner exists, ask whether to move singleton ownership to this pi instance
+2. If a live polling owner exists, ask whether to move singleton ownership to this pi instance
 3. On confirmation, write the current `{ "pid": ..., "cwd": ... }` to this extension's key in `locks.json`
 4. The previous owner must notice that `locks.json` no longer points at its own `pid`/`cwd` and stop local runtime work without deleting the new lock
 

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

@@ -13,12 +13,12 @@ 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.
 
-Configured text handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. Legacy configs may still use `pipe`, but `template: [...]` is the preferred standard shape.
+Configured text handlers provide `template`. A string is one command; an array is ordered composition. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values. The command-template default timeout applies automatically. Use `template: [...]` for composition; the old local `pipe` alias is removed in 0.13.0.
 
 ## Text Handler Config
 
@@ -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,420 @@
+# 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. See [Public API Smoke Examples](#public-api-smoke-examples) below for minimal companion-extension patterns that avoid implementation imports.
+
+## 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()` auto-prepends the correct Back/Main-menu row. `ctx.open()` sends a standalone chat message without auto-navigation.
+- 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 getTelegramVoiceSendTranscript(getCurrentTelegramConfigView())
+      ? { audioPath, transcriptText: text }
+      : { audioPath };
+  },
+  { 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. `voice.sendTranscript` is the bridge-owned transcript preference; providers that expose captions should gate `transcriptText` with `getTelegramVoiceSendTranscript(config)` instead of defining a second reply-policy toggle.
+
+Full behavior: [Voice Integration](./voice.md).
+
+## Public API Smoke Examples
+
+Minimal companion-extension examples that import only stable `@llblab/pi-telegram/*` public membranes. Copy one into an extension `index.ts`, load it beside `pi-telegram`, and verify that it starts without importing any `@llblab/pi-telegram/lib/*` implementation path.
+
+### Extension Sections
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTelegramSection } from "@llblab/pi-telegram/sections";
+
+export default function demoSection(pi: ExtensionAPI) {
+  let unregister: (() => void) | undefined;
+  pi.on("session_start", async () => {
+    unregister?.();
+    unregister = registerTelegramSection({
+      id: "demo-section/status",
+      label: "🧩 Demo section",
+      order: 50,
+      render: () => ({
+        text: "<b>Demo section</b>\n\nThis section was rendered by a companion extension.",
+        replyMarkup: { inline_keyboard: [] },
+      }),
+    });
+  });
+  pi.on("session_shutdown", async () => {
+    unregister?.();
+    unregister = undefined;
+  });
+}
+```
+
+### Raw Update Handler
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTelegramUpdateHandler } from "@llblab/pi-telegram/updates";
+
+export default function demoUpdates(pi: ExtensionAPI) {
+  let unregister: (() => void) | undefined;
+  pi.on("session_start", async () => {
+    unregister?.();
+    unregister = registerTelegramUpdateHandler((update) => {
+      if (!update || typeof update !== "object") return "pass";
+      return "pass";
+    });
+  });
+  pi.on("session_shutdown", async () => {
+    unregister?.();
+    unregister = undefined;
+  });
+}
+```
+
+### Inbound Handler
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTelegramInboundHandler } from "@llblab/pi-telegram/inbound";
+
+export default function demoInbound(pi: ExtensionAPI) {
+  let unregister: (() => void) | undefined;
+  pi.on("session_start", async () => {
+    unregister?.();
+    unregister = registerTelegramInboundHandler("text/*", async (file) => {
+      if (!file.path.endsWith(".demo.txt")) return undefined;
+      return `Demo inbound handler saw ${file.fileName ?? file.path}`;
+    });
+  });
+  pi.on("session_shutdown", async () => {
+    unregister?.();
+    unregister = undefined;
+  });
+}
+```
+
+### Outbound Handler
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTelegramOutboundHandler } from "@llblab/pi-telegram/outbound";
+
+export default function demoOutbound(pi: ExtensionAPI) {
+  let unregister: (() => void) | undefined;
+  pi.on("session_start", async () => {
+    unregister?.();
+    unregister = registerTelegramOutboundHandler("text", async (text) => {
+      if (!text.includes("[demo-outbound]")) return undefined;
+      return text.replace("[demo-outbound]", "Demo outbound handler:");
+    });
+  });
+  pi.on("session_shutdown", async () => {
+    unregister?.();
+    unregister = undefined;
+  });
+}
+```
+
+### Voice Providers
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  getTelegramVoiceSendTranscript,
+  registerTelegramVoiceSynthesisProvider,
+  registerTelegramVoiceTranscriptionProvider,
+} from "@llblab/pi-telegram/voice";
+
+export default function demoVoice(pi: ExtensionAPI) {
+  let unregisterTts: (() => void) | undefined;
+  let unregisterStt: (() => void) | undefined;
+  let currentConfig: { voice?: { sendTranscript?: boolean } } = {};
+  pi.on("session_start", async () => {
+    unregisterTts?.();
+    unregisterStt?.();
+    unregisterTts = registerTelegramVoiceSynthesisProvider(
+      async (text) => {
+        const audioPath = await synthesizeDemoOgg(text);
+        return getTelegramVoiceSendTranscript(currentConfig)
+          ? { audioPath, transcriptText: text }
+          : { audioPath };
+      },
+      { id: "demo-voice/tts" },
+    );
+    unregisterStt = registerTelegramVoiceTranscriptionProvider(
+      async (file) => {
+        if (file.kind !== "voice" && file.kind !== "audio") return undefined;
+        return { text: `Demo transcript for ${file.fileName ?? file.path}` };
+      },
+      { id: "demo-voice/stt" },
+    );
+  });
+  pi.on("session_shutdown", async () => {
+    unregisterTts?.();
+    unregisterStt?.();
+    unregisterTts = undefined;
+    unregisterStt = undefined;
+  });
+}
+
+async function synthesizeDemoOgg(_text: string): Promise<string> {
+  throw new Error("Replace synthesizeDemoOgg with a real OGG/Opus generator.");
+}
+```
+
+### Smoke Checklist
+
+- The extension imports only `@llblab/pi-telegram/sections`, `/updates`, `/inbound`, `/outbound`, `/voice`, or `/keyboard`.
+- It does not import `@llblab/pi-telegram/lib/*`.
+- It registers on `session_start` and disposes on `session_shutdown`.
+- Stable high-level registrations use durable ids.
+- Failures are visible during manual testing through `/telegram-status` or extension-owned logging.
+
+## 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`.