@llblab/pi-telegram 0.12.0 → 0.13.0

package/AGENTS.md

@@ -97,7 +97,7 @@
 
 - Keep comments and user-facing docs in English unless the surrounding file already follows another convention
 - Each project `.ts` file should start with a short multi-line responsibility header comment that explains the file boundary to future maintainers; source-module headers must include `Zones:` tags for cross-cutting responsibility areas
-- Name extracted `/lib` modules and mirrored `/tests` suites by bare domain when the repository already supplies the Telegram scope; prefer `api.ts`, `queue.ts`, `updates.ts`, and `queue.test.ts` over redundant `telegram-*` filename prefixes
+- Name extracted `/lib` modules and mirrored `/tests` suites by bare domain when the repository already supplies the Telegram scope; prefer `queue.ts`, `updates.ts`, and `queue.test.ts` over redundant `telegram-*` filename prefixes. Exception: the concrete Bot API transport domain is named `telegram-api.ts` / `telegram-api.test.ts` to avoid ambiguity with the public `/api/*.ts` package membranes
 - Keep test helpers with the mirrored domain suite by default because test files mirror module-domain boundaries; introduce shared `tests/fixtures` only when multiple domain suites truly reuse the same setup
 - Prefer targeted edits, keeping `index.ts` as the orchestration layer and moving reusable logic into flat `/lib` domain modules when a subsystem becomes large enough to earn extraction
 - Keep composition wiring DRY with small local adapters or owning-domain contracts when repetition appears, but do not hide live mutable session state behind broad facades just to reduce repeated closures
@@ -109,7 +109,7 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 
 - Scheduling and lifecycle: `queue`, `runtime`, `lifecycle`, `locks`
 - Telegram transport and inbound flow: `api`, `polling`, `updates`, `routing`, `media`, `turns`, `inbound`, `config`, `setup`
-- Response surfaces: `preview`, `replies`, `rendering`, `keyboard`, `outbound-attachments`, `outbound`, `voice`, `status`
+- Response surfaces: `preview`, `replies`, `rendering`, `keyboard`, `outbound-markup`, `outbound-attachments`, `outbound`, `voice`, `status`
 - Controls and application menu UI: `commands`, `menu`, `menu-model`, `menu-thinking`, `menu-status`, `menu-queue`, `model`, `prompts`
 - Extension platform: `sections` owns section registry, token mapping, callback dispatch, context building, and its globalThis bridge; `voice` owns the voice-provider registry and its globalThis bridge
 - Pi SDK boundary: `pi` owns direct pi imports and bound extension API ports; `bindings` owns pi-facing command/tool/lifecycle registration wiring extracted from the entrypoint
@@ -119,7 +119,7 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - Keep preview appearance logic in the rendering domain and preview transport/lifecycle logic in the preview domain so richer streaming strategies can evolve without entangling Telegram delivery state with Markdown formatting rules
 - Keep direct `node:*` file-operation dependencies out of `index.ts` when an owning domain exists; the entrypoint should compose ports while domains own local filesystem details such as temp-dir preparation, attachment stats, and turn image reads
 - In `index.ts`, prefer namespace imports for local bridge domains so orchestration reads as domain-scoped calls such as `Queue.*`, `Turns.*`, and `Rendering.*` instead of long flat import lists
-- Keep the local `index.ts` plus `/lib/*.ts` import graph acyclic; `tests/invariants.test.ts` guards this boundary plus shared-bucket bans, empty interface-extension shell regressions, pi SDK centralization, source-only entrypoint Node-runtime/local-adapter/process/direct-pi access avoidance, runtime-domain isolation, structural leaf-domain import isolation, menu/model boundary drift, API/config default coupling, structural update/media coupling to API transport shapes, and attachment coupling to queue/inbound media/API helpers as domains keep evolving
+- Keep the local `index.ts` plus `/lib/*.ts` import graph acyclic; `tests/invariants.test.ts` guards this boundary plus shared-bucket bans, empty interface-extension shell regressions, pi SDK centralization, source-only entrypoint Node-runtime/local-adapter/process/direct-pi access avoidance, runtime-domain isolation, structural leaf-domain import isolation, menu/model boundary drift, Telegram API/config default coupling, structural update/media coupling to Telegram API transport shapes, and attachment coupling to queue/inbound media/Telegram API helpers as domains keep evolving
 - Do not reintroduce shared bucket domains such as `lib/constants.ts`, `lib/types.ts`, `lib/globals.ts`, or broad global-augmentation files; constants, registry keys, state interfaces, and concrete transport shapes should stay in their owning domains, and `index.ts` should not grow new shared magic constants
 - Keep remaining `index.ts` code focused on cross-domain adapter wiring that needs live extension state, pi callbacks, Telegram API ports, or status updates; do not extract one-off closures solely to reduce line count
 - Domain-specific queue planning, preview transport/controller behavior, rendering, Telegram API transport, menu state, and command behavior should stay in their owning domains instead of moving to `/lib/runtime.ts` solely to shrink `index.ts`
@@ -153,12 +153,13 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - Unknown callback data not owned by pi-telegram prefixes (`compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `section:`, `settings:`) may be forwarded as `[callback] <data>` after built-in handlers decline it; update-handler extensions should follow `docs/callback-namespaces.md` and must not poll the same bot independently
 - Command templates stay compact and shell-free: no `command` field, no shell execution, inline defaults are allowed as `{name=default}`, `template` may be a string or an ordered composition array, only `args`/`defaults` inherit into leaves, top-level `timeout` wraps composed sequences, stdout pipes to the next step's stdin by default, and multi-step work should use `template: [...]` rather than provider-specific fields; `pipe` is only a legacy local alias
 - Command-template documentation examples should use portable executable placeholders such as `/path/to/stt` and `/path/to/tts`, not host-local skill paths or machine-specific install locations
+- Abstract pi-telegram docs and README examples must not leak real companion-extension identities into generic provider ids, runtime-event categories, or sample code. Use neutral ids such as `@scope/voice-provider/tts` and reserve real companion names for explicit companion-extension lists or case-study references.
 
 ## 9. Extension Sections Conventions
 
 - `Section identity`: use the same identity-key rules as the Extension Locks Standard (`package.json/name` → canonical id); no separate `owner` field
 - `Token mapping`: Telegram's 64-byte `callback_data` limit forces compact numeric tokens (`section:0:action:payload`). Section authors never hand-roll `section:` strings — use `ctx.callbackData(action, payload?)`
-- `Navigation hierarchy`: Back buttons are auto-prepended by `ctx.edit()` / `ctx.open()`. Root views use `⬆️ Main menu` → `menu:back`. Nested views from `handleCallback` use `⬆️ Back` → `section:<token>:open`. Settings views use `⬆️ Back` → `settings:list`
+- `Navigation hierarchy`: Back buttons are auto-prepended by `ctx.edit()` only. Root views use `⬆️ Main menu` → `menu:back`. Nested views from `handleCallback` use `⬆️ Back` → `section:<token>:open`. Settings views use `⬆️ Back` → `settings:list`. `ctx.open()` sends standalone chat messages without auto-navigation
 - `Context ports`: sections receive `TelegramSectionContext` / `TelegramSectionCallbackContext` with `answerCallback`, `edit`, `open`, `enqueuePrompt`, and `callbackData`. No filesystem access, no raw bot clients, no second polling loop
 - `Settings indicators`: use `settings.getLabel()` for dynamic status rows in the Settings submenu (e.g., `🟢`/`⚫️` based on internal state). Called on every Settings list render
 - `Handler fallback`: `section.handleCallback` runs first; if it returns `"pass"` and `settings.handleCallback` exists, the settings handler runs with a fresh context carrying `backCallback="settings:list"`
@@ -168,7 +169,7 @@ The canonical detailed ownership map lives in [`docs/architecture.md`](./docs/ar
 - `Section separators`: extension-injected main-menu rows appear before the **⚙️ Settings** row. Extension settings rows appear before built-in Proactive push controls
 - `Model button format`: use `provider/ModelId` format (e.g., `anthropic/claude-sonnet-4-5`) across model menu buttons and status row. The compact `provider/id` form is canonical
 - `Section domain ownership`: `lib/sections.ts` owns the registry, token mapping, callback dispatch, and context building. `lib/menu.ts` dispatches `section:` callbacks before built-in handling. `lib/menu-status.ts` injects section rows. `lib/menu-settings.ts` injects settings rows and passes `sectionRegistry` through callback deps
-- `Callback routing order`: button actions → queue menu → settings menu → section callbacks → built-in menu handling → `[callback]` fallback. Settings menu callbacks always pass `sectionRegistry` to `updateTelegramSettingsMenuMessage` and `handleTelegramSettingsMenuCallbackAction`
+- `Callback routing order`: button actions → compact confirmations → queue menu → settings menu → section callbacks → built-in menu handling → `[callback]` fallback. Settings menu callbacks always pass `sectionRegistry` to `updateTelegramSettingsMenuMessage` and `handleTelegramSettingsMenuCallbackAction`
 
 ## 9. Pre-Task Preparation Protocol
 

package/BACKLOG.md

@@ -1,3 +1,3 @@
 # Project Backlog
 
-## Open Work
+No open work.

package/CHANGELOG.md

@@ -1,8 +1,30 @@
 # Changelog
 
-## Unreleased
-
-- Nothing yet.
+## 0.13.0: Command Template Standard, Voice Hardening, And Domain Cleanup (2026-05-22)
+
+- `[Architecture]` Extracted outbound assistant-action markup parsing into `lib/outbound-markup.ts` and removed the temporary Voice/Outbound/Queue import-cycle allowance. Impact: project source imports are fully acyclic again while preserving existing voice and outbound helper exports.
+- `[Tests]` Updated the Pi SDK centralization invariant to guard the current `@earendil-works/*` package scope as well as the legacy scope. Impact: new direct SDK imports outside `lib/pi.ts` are caught again.
+- `[Voice Providers]` Generated compatibility ids for STT/TTS providers now use monotonic counters with registry probing, and provider disposers now remove only their own registered instance. Impact: anonymous ids stay collision-safe across stale registry entries/module reloads, and stale disposers cannot delete replacement providers.
+- `[Security]` Telegram temp directories, downloaded inbound files, and `locks.json` writes now use explicit private filesystem modes. Impact: private attachments and local polling ownership metadata are less exposed on permissive-umask or shared hosts.
+- `[Docs]` Clarified that `voice.sendTranscript` is the bridge-owned transcript preference and updated provider examples to gate `transcriptText` with `getTelegramVoiceSendTranscript(config)`. Impact: companion voice providers no longer need to invent duplicate transcript/reply-policy UI.
+- `[Tests]` Added a long-session runtime regression that preserves queued work across `/abort`, explicit `/next`, and in-flight model switching. Impact: the high-risk queue/dispatch path now has coverage for an operator session that chains abort recovery into model-switch continuation.
+- `[Naming]` Renamed the concrete Bot API transport domain from `lib/api.ts` / `tests/api.test.ts` to `lib/telegram-api.ts` / `tests/telegram-api.test.ts`. Impact: the transport owner is clearer and no longer competes conceptually with the public `/api/*.ts` package membranes.
+- `[Status]` `/telegram-status` recent runtime events now include a category summary before the detailed event list. Impact: provider, handler, and transport failure categories are easier to scan during companion-extension diagnostics.
+- `[Tests]` Added a combined `telegram_voice` + `telegram_button` outbound planner smoke regression and corrected the text-group non-contiguous-tail fixture to reflect the widened split-message id gap. Impact: the rendering/markup watchlist now has direct coverage for mixed assistant action markup without changing runtime behavior.
+- `[Audit]` Added fixture lifecycle coverage for STT/TTS provider re-registration across session-start/resume/reload-style boundaries, and scanned the local workspace for removed `@llblab/pi-telegram/lib/*` companion imports. Impact: the remaining hotfix lifecycle and migration audit items are now closed in this environment.
+- `[Refactor]` Split assistant-authored button planning, callback storage, callback handling, and button prompt-turn construction from `lib/outbound.ts` into `lib/outbound-buttons.ts`, with symmetric `tests/outbound-buttons.test.ts` coverage. Impact: the outbound domain is smaller and button behavior now has a direct module-level test peer while existing `lib/outbound.ts` exports remain compatible.
+- `[Tests]` Added symmetric `tests/outbound-markup.test.ts` coverage for `lib/outbound-markup.ts`, including top-level comment collection, fenced-code exclusion, partial-comment stripping, attribute parsing, and multi-voice planning. Impact: assistant action markup has direct module-level regression coverage instead of relying only on umbrella outbound tests.
+- `[Tests]` Added symmetric `tests/menu-status.test.ts` coverage for `lib/menu-status.ts`, including status reply markup rows, voice-active thinking suppression, callback routing, and status message send/update helpers. Impact: status-menu behavior now has a direct module-level regression peer.
+- `[Tests]` Added symmetric `tests/menu-thinking.test.ts` coverage for `lib/menu-thinking.ts`, including reply markup, thinking-level callbacks, invalid/voice/non-reasoning guards, and menu send/update helpers. Impact: thinking-menu behavior now has direct module-level regression coverage.
+- `[Tests]` Added symmetric `tests/setup.test.ts` coverage for `lib/setup.ts`, including token defaults, prompt mode selection, setup success/failure, and prompt-runtime guard cleanup after errors. Impact: `/telegram-setup` prompt behavior now has direct module-level regression coverage.
+- `[Tests]` Added symmetric `tests/menu-settings.test.ts` coverage for `lib/menu-settings.ts`, including built-in settings markup, detail menu active states, settings mutations, and stale-message fallback toggles. Impact: settings-menu behavior now has direct module-level regression coverage.
+- `[Context]` Cleared the completed backlog down to `No open work` and tightened the `lib/outbound.ts` domain header after button/markup extraction. Impact: historical completion notes stay in the changelog, while backlog and domain ownership now reflect current reality.
+- `[Refactor]` Split native Telegram voice delivery from `lib/outbound.ts` into `lib/outbound-voice.ts`, with symmetric `tests/outbound-voice.test.ts` coverage. Impact: outbound voice upload/provider orchestration now has a direct domain owner and `lib/outbound.ts` is reduced to the outbound surface, command handlers, text transforms, artifact composition, and compatibility re-exports.
+- `[Command Templates]` Replaced `pi-telegram`'s command-template implementation with the current `pi-actors` standard as a deliberate breaking 0.x minor change. Impact: templates now use `parallel` and `when`, support string `timeout`/`delay`/`retry`, inherited default references, `{value??fallback}`, `{flag?yes:no}`, and empty-arg filtering; old local `mode`, `critical`, and `pipe` shapes were removed/migrated to `parallel`, `failure`, and `template: [...]`.
+- `[Docs]` Removed real companion-extension identities from abstract voice-provider examples and README guidance, keeping concrete names only in the explicit Companion Extensions list. Impact: pi-telegram documentation now keeps bridge responsibilities separate from third-party companion-extension ownership.
+- `[Docs]` Integrated public API smoke examples for Extension Sections, raw updates, inbound handlers, outbound handlers, and voice providers into `docs/public-api.md` using only stable public membranes. Impact: companion-extension authors get copyable patterns in the canonical public API guide and avoid removed `@llblab/pi-telegram/lib/*` imports.
+- `[Docs]` Updated README release positioning and corrected Extension Sections docs so `ctx.edit()` owns automatic Back-row insertion, `ctx.open()` is documented as a standalone chat-message sender, and section callbacks appear before built-in menu callbacks. Impact: companion extension authors get an accurate public contract.
+- `[Backlog]` Restored concrete near-term follow-up slices for public API migration, provider lifecycle, smoke examples, diagnostics, voice-domain DAG cleanup, section examples, and voice transcript config clarity. Impact: README's open-work link points to actionable development priorities again.
 
 ## 0.12.0: Public API Membranes, Telegram UX Safety, And Extension Interop
 

package/README.md

@@ -4,7 +4,7 @@
 
 **Telegram runtime adapter for π.**
 
-`pi-telegram` turns a private Telegram DM into a session-local operator console for π. It admits work, preserves context, streams readable replies, keeps busy sessions usable through queues, lets other extensions share one bot, and turns assistant-authored intent into native Telegram artifacts. In `0.11.0`, it also becomes a voice-provider platform: companion extensions can supply Telegram transcription and synthesis providers while `pi-telegram` keeps ownership of transport, queueing, and reply policy.
+`pi-telegram` turns a private Telegram DM into a session-local operator console for π. It admits work, preserves context, streams readable replies, keeps busy sessions usable through queues, lets other extensions share one bot, and turns assistant-authored intent into native Telegram artifacts. It is also a voice-provider platform: companion extensions can supply Telegram transcription and synthesis providers while `pi-telegram` keeps ownership of transport, queueing, and reply policy.
 
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
@@ -199,39 +199,9 @@ If `telegram.json` explicitly sets a valid `voice.replyMode`, prompts include co
 
 In `mirror` and `always` modes, the bridge transparently intercepts agent text responses and routes them through the outbound voice pipeline. Configured `outboundHandlers` with `type: "voice"` run first in their configured order; zero-config registered synthesis providers run after them as progressive fallbacks. If several synthesis providers are installed, they are tried in registration order and the first one that returns a valid `.ogg`/`.opus` artifact handles the reply; `undefined`, errors, or invalid output fall through to the next provider. If every voice generator fails, the bridge falls back to sending the text reply instead.
 
-Voice synthesis provider extensions (e.g. `pi-xai-voice`) register a TTS backend at runtime through public API domain subpaths:
-
-```typescript
-import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/voice";
-import { recordTelegramRuntimeEvent } from "@llblab/pi-telegram/outbound";
-
-// Return path only (backward compatible)
-const dispose = registerTelegramVoiceSynthesisProvider(
-  async (text, { lang, rate }) => {
-    const path = await myTTS(text, { language: lang });
-    return path; // must be .ogg or .opus
-  },
-  { id: "pi-xai-voice/tts" },
-);
-
-// Return path + transcript caption
-const dispose2 = registerTelegramVoiceSynthesisProvider(
-  async (text, { lang, rate }) => {
-    const rewritten = rewriteWithSpeechTags(text); // internal TTS optimization
-    const path = await myTTS(rewritten, { language: lang });
-    return { audioPath: path, transcriptText: text };
-  },
-  { id: "pi-xai-voice/tts-with-transcript" },
-);
-
-// Surface diagnostics in /telegram-status
-recordTelegramRuntimeEvent("xai-voice", new Error("TTS complete"), {
-  phase: "tts",
-  durationMs: 1200,
-});
-```
+Voice synthesis provider extensions register TTS backends at runtime through public API domain subpaths. Multiple synthesis providers can be registered; stable provider registrations pass a durable abstract id owned by the companion extension, such as `"@scope/voice-provider/tts"`. The bridge tries configured `type: "voice"` handlers first, then programmatic handlers, then registered synthesis providers in registration order until one succeeds. Providers and handlers receive the text to synthesize and optional `lang`/`rate` hints from `<!-- telegram_voice -->` markup or the automatic interception path. Voice delivery must produce `.ogg` or `.opus` files.
 
-Multiple synthesis providers can be registered; stable provider registrations pass a durable `id`, while omitted ids remain a compatibility path for older providers. The bridge tries configured `type: "voice"` handlers first, then programmatic handlers, then registered synthesis providers in registration order until one succeeds. Providers and handlers receive the text to synthesize and optional `lang`/`rate` hints from `<!-- telegram_voice -->` markup or the automatic interception path. Voice delivery must produce `.ogg` or `.opus` files.
+Provider code examples, transcript-caption behavior, and diagnostics patterns live in [Voice Integration](./docs/voice.md) and [Public API](./docs/public-api.md). The important boundary is: providers own TTS and any private optimization, while pi-telegram owns reply policy, prompt context, fallback ordering, and Telegram transport.
 
 ### Extension interop
 

package/docs/README.md

@@ -5,7 +5,7 @@ Living index of project documentation in `/docs`.
 ## Documents
 
 - [architecture.md](./architecture.md) — Overview of the Telegram bridge runtime, queueing model, rendering pipeline, and interactive controls
-- [public-api.md](./public-api.md) — Stable public API map: package entrypoints, commands, config, assistant markup, extension APIs, and compatibility boundaries
+- [public-api.md](./public-api.md) — Stable public API map: package entrypoints, commands, config, assistant markup, extension APIs, smoke examples, and compatibility boundaries
 - [command-templates.md](./command-templates.md) — Portable command-template standard core
 - [inbound.md](./inbound.md) — Local `pi-telegram` inbound text/media handler bus, programmatic inbound handlers, registered STT provider fallbacks, legacy `attachmentHandlers` compatibility, placeholders, and fallbacks
 - [outbound.md](./outbound.md) — Local `pi-telegram` outbound-handler config, text/voice/button behavior, voice synthesis provider fallback priority, artifact outputs, and callback routing

package/docs/architecture.md

@@ -46,7 +46,8 @@ The repository uses a **Flat Domain DAG**:
 - `sections`: Telegram menu-section registry, opaque section callback tokens, render/callback dispatch, safe section ports, and diagnostics.
 - `keyboard`: shared inline-keyboard reply-markup shape only; feature domains own labels, callback data, and behavior.
 - `preview` / `replies` / `rendering`: streaming preview lifecycle, final reply delivery, reply parameters, Telegram HTML rendering, chunking, and stable preview snapshots.
-- `outbound`: outbound text transformations, assistant-authored action comments, voice/button artifacts, and generated callback actions.
+- `outbound-markup`: top-level assistant action comment parsing, attribute parsing, voice reply planning, and preview/delivery stripping.
+- `outbound`: outbound text transformations, voice/button artifact delivery, and generated callback actions.
 - `outbound-attachments`: `telegram_attach`, queued outbound files, stat/limit checks, and photo/document delivery classification.
 - `status`: status bar/status-message rendering, queue-lane summaries, redacted event ring, and grouped diagnostics.
 - `lifecycle` / `prompts` / `prompt-templates` / `pi`: π hook registration, Telegram prompt guidance, prompt-template discovery/expansion, and centralized direct π SDK imports.

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.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.
 
@@ -90,7 +90,7 @@ If a matching handler fails with a non-zero exit code, the runtime records diagn
 
 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/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.
+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:
 

package/docs/outbound.md

@@ -18,7 +18,7 @@ An outbound handler is selected by `type`. Text replies and assistant markup map
 
 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
 

package/docs/public-api.md

@@ -25,7 +25,7 @@ import {
 } 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.
+`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
 
@@ -159,7 +159,7 @@ 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.
+- `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).
@@ -233,16 +233,170 @@ const offStt = registerTelegramVoiceTranscriptionProvider(
 const offTts = registerTelegramVoiceSynthesisProvider(
   async (text, options) => {
     const audioPath = await synthesizeOggOpus(text, options);
-    return { audioPath, transcriptText: text };
+    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.
+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:`.

package/docs/sections.md

@@ -197,8 +197,8 @@ The token is an implementation detail. Section authors **never** write `section:
 4. Compact confirmation callbacks (`compact:*`)
 5. Queue menu callbacks (`queue:*`)
 6. Settings menu callbacks (`settings:*`)
-7. Built-in menu callbacks (`menu:*`, `model:*`, `thinking:*`, `status:*`)
-8. Section callbacks (`section:*`) — dispatched before step 7's full handler
+7. Section callbacks (`section:*`)
+8. Built-in menu callbacks (`menu:*`, `model:*`, `thinking:*`, `status:*`)
 9. Unknown callbacks fall back to `[callback]` prompt text
 
 ### Handler return values
@@ -226,14 +226,14 @@ Section errors are caught and surfaced as popup text. No unhandled exceptions le
 
 ## 8. Navigation Hierarchy
 
-`ctx.edit()` and `ctx.open()` automatically prepend a Back row. The Back target depends on the navigation level:
+`ctx.edit()` automatically prepends a Back row for menu-bound views. The Back target depends on the navigation level:
 
 - Section root (from main menu): `⬆️ Main menu` → `menu:back`
 - Section sub-view (`ctx.edit()` in handler): `⬆️ Back` → `section:<token>:open`
 - Settings root (from Settings list): `⬆️ Back` → `settings:list`
 - Settings sub-view (`ctx.edit()` in settings handler): `⬆️ Back` → `settings:list`
 
-Section authors do not need to manage the Back button — it is added automatically and deduplicated when already present.
+Section authors do not need to manage the Back button for `ctx.edit()` — it is added automatically and deduplicated when already present. `ctx.open()` sends a standalone chat message and does not prepend a Back row.
 
 ```
 Main menu
@@ -257,7 +257,7 @@ interface TelegramSectionContext {
   answerCallback(text?: string): Promise<void>;
   /** Edit the current message (auto-prepends Back row) */
   edit(view: TelegramSectionView): Promise<void>;
-  /** Send a new message (auto-prepends Back row) */
+  /** Send a standalone chat message without auto-navigation */
   open(view: TelegramSectionView): Promise<void>;
   /** Enqueue a plain-text prompt turn */
   enqueuePrompt(prompt: string): Promise<void>;

package/docs/voice.md

@@ -1,6 +1,6 @@
 # Voice Integration
 
-Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by voice provider extensions. In `0.11.0`, this is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot polling loop.
+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
 
@@ -67,12 +67,12 @@ The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode
 
 ## Outbound Voice Synthesis Provider Registration
 
-Voice synthesis provider extensions (such as `pi-xai-voice`) register themselves through `registerTelegramVoiceSynthesisProvider()`. The bridge only provides the registration seam and the actual delivery to Telegram. **The provider is fully responsible for**:
+Voice synthesis provider extensions register themselves through `registerTelegramVoiceSynthesisProvider()`. The bridge only provides the registration seam and the actual delivery to Telegram. **The provider is fully responsible for**:
 
 - Text optimisation / speech-style rewriting
 - Adding speech tags (when desired)
 - Running TTS + ffmpeg conversion to OGG/Opus
-- Deciding whether to return `transcriptText` at all (based on the user's "Send Transcript" toggle)
+- Deciding whether to return `transcriptText` at all based on the bridge-owned `voice.sendTranscript` preference when the provider has access to the current Telegram config
 - `transcriptText` (when returned) is attached by the bridge as the voice message **caption** only. Separate transcript messages are no longer sent.
 
 The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`. When a provider returns `transcriptText`, the bridge attaches it as the voice caption.
@@ -86,7 +86,7 @@ The provider receives the raw agent text plus optional `{ lang?, rate? }`.
 It must return one of:
 
 - `string` — path to a ready `.ogg` or `.opus` file
-- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. A provider UI can expose a "Send Transcript" toggle by returning `transcriptText` only when that toggle is enabled.
+- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. Providers should treat pi-telegram's `voice.sendTranscript` as the bridge-owned transcript preference instead of inventing a second reply-policy UI.
 - `undefined` — skip this text block
 
 **Important:** Providers are fully responsible for producing a clean, TTS-optimised native voice file. The bridge may also run configured outbound voice command templates for users who prefer process-boundary handlers instead of provider extensions.
@@ -124,20 +124,25 @@ Priority for outbound voice delivery is: configured `outboundHandlers` with `typ
 When the user's "Send Transcript" toggle is ON, return the clean spoken text as `transcriptText`. The bridge attaches it as the caption on the voice message. When the toggle is OFF, return only the audio path (no `transcriptText`).
 
 ```typescript
-import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/voice";
+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 = getUserSendTranscriptPreference(); // from your UI + telegram.json
+    const sendTranscript = getTelegramVoiceSendTranscript(
+      getCurrentTelegramConfigView(),
+    );
     return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
   },
   { id: "my-voice-provider/tts" },
 );
 ```
 
-The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
+`getCurrentTelegramConfigView()` represents whatever current `TelegramConfig` view your extension already owns or receives; pi-telegram does not require providers to read config directly. The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
 
 ### Surfacing provider diagnostics
 
@@ -146,7 +151,7 @@ Voice provider extensions can record runtime events that appear in `/telegram-st
 ```typescript
 import { recordTelegramRuntimeEvent } from "@llblab/pi-telegram/outbound";
 
-recordTelegramRuntimeEvent("xai-voice", new Error("TTS failed"), {
+recordTelegramRuntimeEvent("voice-provider", new Error("TTS failed"), {
   phase: "tts",
   text: text.slice(0, 50),
 });