@llblab/pi-telegram 0.11.1 → 0.12.0

package/docs/command-templates.md

@@ -4,12 +4,14 @@ Command templates are the portable integration format for deterministic local au
 
 **Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
 
-**Scope:** portable synchronous command execution format — shell-free exec, composition/pipes, timeout (30s default), delay-before-start, retry, critical-step branching, output artifact selection, and handler-level fallback. Single JSON standard; no platform lock-in.
+**Scope:** portable synchronous command execution format — shell-free exec, composition/pipes, optional timeout, delay-before-start, bounded retry, failure propagation, recover cleanup, output artifact selection, and handler-level fallback. Single JSON standard; no platform lock-in.
 
 ---
 
 Extensions may choose their own config files, selectors, placeholder sources, and examples, but should preserve this core contract.
 
+Layer boundary: command templates own only the synchronous execution graph. Recipe imports, import-reference expressions, recipe lookup, `async: true`, run ids, state dirs, FIFO controls, and outbox events are host/recipe/async-run configuration layers, not portable command-template syntax.
+
 ## Shape
 
 A command template is either a command-line string or an ordered array of command-template leaves:
@@ -32,13 +34,15 @@ 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.
-- `args`: Optional placeholder-name declarations only. Never stores defaults.
+- `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. Default is `30000`. Long-running agent calls should set this explicitly.
+- `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.
 - `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. When `true`, failure aborts the root composition.
+- `critical`: Optional boolean. Backward-compatible alias for `failure: "root"`.
+- `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.
 
 For object form, write `template` last. Read the node flags first, then the executable content. Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
@@ -63,8 +67,9 @@ 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   |
 
-Resolution order is runtime values → `defaults` → inline default → error.
+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.
 
 ```json
 {
@@ -80,6 +85,8 @@ With runtime values `{ "text": "hello" }`, argv is:
 
 Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
 
+Typed declarations annotate the public tool interface, not the shell command. They may live in `args` or inline placeholders such as `{timeout:int=60000}` and `{mode:enum(check,fix)=check}`. Use metadata-first authoring (`args` plus `defaults`) when long templates should stay visually short; use inline-first authoring when one self-contained `template` property is clearer. They do not sandbox or reinterpret the executable; they only let the host generate narrower input schemas and normalize runtime values before placeholder substitution. Untyped `args` and untyped placeholders continue to work unchanged.
+
 ## Quoting
 
 Placeholder values are not shell-escaped because no shell is used. A value containing spaces remains one argv item when it replaces one split word:
@@ -122,12 +129,12 @@ Composition rules:
 
 - Execute leaves in order when `mode` is omitted or set to `"sequence"`
 - Execute child templates concurrently when `mode` is set to `"parallel"`
-- Parallel composition uses soft-quorum semantics by default: failed non-critical children are reported but do not abort siblings or the next sequence step
-- Non-critical failures are recorded and execution continues, while `critical: true` failures abort the root composition
+- 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
 - Top-level `args` and `defaults` apply to every leaf unless the leaf defines private values
 - Leaf `args` replace inherited `args`; leaf `defaults` merge over inherited defaults; `timeout` and `output` are not inherited into leaves
-- Default `30000` (30s) timeout applies automatically; configure `timeout` only for exceptional long-running commands
+- Timeout is disabled by default; configure a positive `timeout` for bounded commands that should fail closed
 - Each sequence leaf receives the previous leaf's stdout on stdin by default, while the final leaf stdout remains the default composition result
 - Each parallel child receives the same stdin, and child stdout values are joined in stable array order before flowing to the next sequence leaf
 - Parallel branch joins include branch label and status, and tool details include branch metadata plus coverage summary
@@ -231,38 +238,76 @@ Legacy local schemas may accept `pipe` as an alias, but the portable standard is
 
 By default, composition continues on failure: the failed step is logged and the next step executes. This is analogous to `make -k` — the user sees all failures at once and decides what to fix.
 
-## Critical Steps
+## Failure Propagation
+
+By default, failed steps use `failure: "continue"`: record the failure, clear stdout for that step, and continue the current sequence. This preserves the fail-open profile.
+
+Use `failure` when a node should stop more aggressively:
 
-Set `critical: true` on any leaf to abort the entire root composition on failure. One `critical` leaf can halt the whole pipeline.
+- `"continue"`: record the failure and continue the current sequence.
+- `"branch"`: stop the current sequence/subtree and return a failed branch to the nearest parent. In a parallel node, sibling branches keep running and the join becomes degraded. At the root, branch failure is still a tool failure.
+- `"root"`: abort the outermost composition.
 
 ```json
 {
+  "mode": "parallel",
   "template": [
-    { "template": "cargo build" },
-    { "template": "cargo fmt --check" },
-    { "critical": true, "template": "cargo test" }
+    {
+      "label": "agent-a",
+      "failure": "branch",
+      "template": [
+        "agent-a-work {scope}",
+        "agent-a-validate {scope}",
+        "agent-a-push {scope}"
+      ]
+    },
+    {
+      "label": "agent-b",
+      "failure": "branch",
+      "template": [
+        "agent-b-work {scope}",
+        "agent-b-validate {scope}",
+        "agent-b-push {scope}"
+      ]
+    }
   ]
 }
 ```
 
-`build` / `fmt` failures are logged, execution continues. `test` failure aborts the root composition immediately.
+If `agent-a-validate` fails, `agent-a-push` is skipped, `agent-b` can still finish, and the parallel join reports degraded branch coverage.
 
-A `critical` leaf in a nested composition still aborts the outermost root `template: [...]`. There is no per-branch scoping in the current standard.
+`critical: true` remains a backward-compatible alias for `failure: "root"`. Prefer `failure` for new templates because it names the propagation scope directly.
 
 ## Retry
 
-Set `retry: N` on a leaf to attempt execution up to `N` times (including the first). Retries happen immediately on non-zero exit. The first successful attempt stops the retry loop.
+Set `retry: N` to attempt execution up to `N` times including the first. The first successful attempt stops the retry loop.
+
+On leaf commands, retry repeats that command. On sequence or parallel nodes, retry repeats the whole node. A retried group only retries when the group returns a failure, so validator checkpoints normally pair group retry with `failure: "branch"` or `failure: "root"`.
 
 ```json
 {
-  "template": [
-    { "retry": 3, "template": "npm install" },
-    { "retry": 2, "critical": true, "template": "npm test" }
-  ]
+  "failure": "branch",
+  "retry": 3,
+  "template": ["implement {scope}", "npm test", "git diff --check"]
+}
+```
+
+Here the whole group runs again when a validator fails. Without `failure: "branch"`, the failed validator would be logged and the group would continue by default.
+
+## Recover
+
+Set `recover` on a retried node to run cleanup after a failed attempt and before the next attempt. `recover` is another command template: it can be a string command, sequence, or mode tree. Its output is ignored and the next retry receives the original stdin.
+
+```json
+{
+  "failure": "branch",
+  "retry": 3,
+  "recover": "git -C {work_dir} reset --hard HEAD",
+  "template": ["pi -p --tools read,edit,bash {scope_file}", "npm test"]
 }
 ```
 
-`npm install` is retried up to 3 times. `npm test` is retried up to 2 times; if all attempts fail, the critical step aborts the pipeline.
+`recover` is not a fallback success path. It is cleanup between attempts. Practical uses include resetting a worktree, removing temp files, clearing generated output, releasing a local lock, or stopping a helper process before trying the node again. If recovery fails, retries stop and the recovery failure is returned. Recovery uses fail-closed semantics by default; set an explicit `failure` inside a recover template only when a softer cleanup failure is intentional.
 
 ## Delay
 
@@ -290,12 +335,24 @@ string           → leaf command
 string[]         → sequential composition
 { template }     → leaf command object
 { mode, template } → sequence or parallel subtree
-{ mode, args, defaults, delay, retry, critical, output, template } → full node
+{ mode, 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 critical when safety matters. Same contract, growing capability, no dead weight.
+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.
+
+`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.
+
+## Trust Boundary
+
+Command templates avoid shell interpolation by splitting the template into argv first and substituting placeholders per arg. A placeholder value containing spaces remains one argv value, not a shell fragment.
+
+This is not a sandbox. The executable still runs with the same user permissions as the host agent. Shells, interpreter eval modes, destructive filesystem commands, and local scripts remain trusted code. Examples that deserve extra operator attention:
+
+- `bash`, `sh`, `zsh`, or `fish`, especially with `-c`.
+- `node -e`, `python -c`, `ruby -e`, `perl -e`, or similar eval modes.
+- `rm`, `mv`, `cp`, or `rsync` over broad paths or placeholder-derived paths.
 
-`mode: "parallel"` is the synchronous fanout shape. Detached lifecycle, logs, cancellation, and durable state belong to host-specific async job or runtime-envelope standards, not to command templates.
+Hosts may surface lightweight warnings for these obvious high-risk shapes. Warnings should inform review without blocking existing tools, because many trusted local wrappers intentionally use shells or filesystem mutation.
 
 ## Tool Boundary
 

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

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

package/docs/public-api.md

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