@llblab/pi-kit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.5.0 - 2026-09-05
+
+- `Telegram Native Controls`: Advances the exact Telegram pin to `0.43.0`, bringing in-body button blocks, shared JSON/CML disabled controls, HTML footer fallback, and updated agent Skills while preserving package-owned implementations and the existing resource inventory.
+
 ## 0.4.0 - 2026-09-05
 
 - `Expanded Composition`: Adds exact published pins for Clean Room and opt-in State Flow alongside the portable LLBLAB Skills collection, exposing each package's own declared resources without duplicating source or runtime ownership.

package/README.md

@@ -15,7 +15,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.7.4` | Visible continuation scheduling and bounded worker Skills |
 | [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.3.0` | Opt-in validated state handoffs between agent runs |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.42.4` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.43.0` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.14.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.

package/node_modules/@llblab/pi-telegram/BACKLOG.md

@@ -4,6 +4,7 @@ _This file owns unresolved project work only. Completed behavior belongs in `CHA
 
 - [ ] `Live-thread continuity and recovery`: Make loss and restoration of a live thread truthful and safe without discarding accepted work or deleting a currently owned target; the initial cause of the observed stale-thread API failures remains unproven.
   - [ ] Complete the remaining operator-coordinated live smoke beyond the operator-confirmed successful leader Restore: verify follower Restore, inaccessible callbacks, already-absent chooser cleanup, direct stale-target diagnostics, and preservation of accepted local work/active-turn target. Use disposable test threads. The successful leader flow does not independently prove these failure paths or establish the initial stale-thread failure cause.
+- [ ] `Native in-body controls live smoke`: Extend the operator-confirmed successful current-client smoke (singleton CML and mixed JSON/CML rows between paragraphs, ordinary prompt callbacks, labeled disabled control, separate footer callback, and HTML-mode footer fallback) to an independently identified second client, follower routing, blank disabled cells, and app-method dispatch/revision rejection. Do not infer coverage from the confirmed ordinary-button flow; in-body selection uses callback acknowledgement, not body recoloring.
 - [ ] `Operator-confirmed pairing`: Replace first-contact automatic ownership with an explicit pending request that the trusted Pi interface can allow or reject before `allowedUserId` is persisted or any Telegram prompt executes; retain manual preconfiguration, bound pending-request lifetime and multiplicity, fail closed across session/transport replacement, and cover unauthorized-first-contact races.
 - [ ] `Environment-backed bot tokens`: Let each profile store an exact Pi-native `$ENV_VAR` or `${ENV_VAR}` reference in `telegram.json` instead of copying the resolved secret; preserve the originating alias when `/telegram-setup` prefills from a supported environment variable, resolve only at validation/activation boundaries, fail closed with a redacted named-variable diagnostic when unresolved, retain literal-token compatibility, and cover named profiles, reload, persistence, status, and secret-redaction paths.
 - [ ] [`Inference bypass Generative Apps`](./docs/generative-apps.md): Let the agent install and bind one managed JavaScript app owner for a generated-prompt prefix so deterministic controls can bypass model inference without creating another button grammar.

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.43.0: Native Button Blocks
+
+- `In-Body Controls`: Renders standalone `telegram_button` fences as native button rows between paragraphs using the same singleton/mixed JSON/CML grammar and callback ownership as footer comments. Invalid/incomplete blocks register nothing, previews hide action payloads, literal examples remain inert, and HTML mode moves controls to the footer. In-body clicks acknowledge without recoloring; operator-confirmed current-client smoke passed; cross-client/follower checks remain pending.
+- `Bot API Reference`: Corrects the local `sendRichMessageDraft` table against Bot API 10.3 with generation-stop parameters and draft replacement semantics, updates affected Skill indexes, and checks parity of stop-control documentation across both draft methods. Runtime generation controls are unchanged.
+- `Disabled Controls`: Adds boolean JSON disabled state and the fourth CML button atom (`1`/`true` disables, `0`/`false` enables), including label-only `{Next|||1}` and blank `{|||1}` cells with no prompt or selected style. Disabled buttons stay visible without callback registration, prompt admission, or app invocation; shared keyboard types, Generative Apps, and agent Skills follow the same contract.
+
 ## 0.42.4: Thread Recovery Hotfix
 
 - `Thread Restore`: Retains validated source and chooser identity when callback messages omit thread metadata, hides Restore in threadless/All choosers and explains how to supply a destination, rejects conflicting Restore instead of forwarding to the old target, and treats confirmed already-deleted chooser cleanup as complete without redispatch.

package/node_modules/@llblab/pi-telegram/README.md

@@ -131,7 +131,7 @@ Enable the optional capabilities the bridge needs in the [@BotFather](https://t.
 | Outbound artifacts | Return generated files through `telegram_attach` during active turns or explicit direct delivery. | Agents send real artifacts as files, not pasted blobs. |
 | Voice input | Route audio through configured command-template handlers, programmatic handlers, or STT providers. | Voice notes become usable prompt context. |
 | Voice output | Choose `manual`, `mirror`, or `always`; active automatic turns carry one compact `[voice] delivery: automatic voice` line, while explicit `telegram_voice` remains available. | Voice policy stays dynamic and model-legible without duplicating the full action contract in every prompt. |
-| Buttons | Turn top-level `telegram_button` comments into inline buttons. | Assistant-authored choices become native Telegram interactions. |
+| Buttons | Use `telegram_button` comments for footer buttons or fenced blocks for native button rows between paragraphs. | Assistant-authored choices become native Telegram interactions. |
 | Generative Apps | Install or explicitly replace a reviewed `.mjs` application whose generated JSON button view may mix direct `app::method` actions with ordinary model prompts. | Repeated games, controls, tutors, and adapters compile routine interaction without losing selective model interpretation, explanation, or adaptation. |
 | Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. |
 | Threaded Mode | Run one leader plus visible follower Pi instances through named private-chat threads. | One bot can host a local multi-instance Pi organism without hidden process spawning. |
@@ -222,7 +222,7 @@ Voice notes, audio, images, PDFs, and other media can pass through configured in
 
 ### Buttons And Callbacks
 
-Assistant replies can include top-level hidden `telegram_button` comments containing a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One adaptive matrix may mix named JSON objects with positional CML cells; separators are optional and one trailing comma is tolerated, including inside JSON objects. Top-level cells become full-width rows while nested rows group one or more buttons horizontally without an artificial parser-level width cap; generated surfaces default to five columns and use six to eight only for short position-bearing labels. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style` set to `primary`, `success`, or `danger`; omitting the first atom leaves the existing prompt-as-label fallback in charge, while the optional style still requires a non-empty prompt. It trims atom boundaries, preserves non-structural text literally, and decodes only `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Buttons use `label` plus `prompt`, or the compact `value` key when both are identical. The bridge strips every assistant-authored HTML comment from Telegram previews and final replies regardless of Markdown position or owning extension, while only recognized top-level comments activate buttons or voice; comment-only output sends no text message and the Pi terminal transcript remains unchanged. It renders valid inline buttons and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Button-only replies receive the standard `☑️ **Choose an option:**` heading as automatic visible fallback text. Once a generated prompt button is accepted, only that exact button switches to its optional `selected_style` (`primary` blue by default, `success` green, or `danger` red) without altering its agent-authored label or emoji; every style still queues the selected prompt.
+Assistant replies can place controls between paragraphs using standalone triple-backtick `telegram_button` blocks, or keep them in the footer using top-level hidden `telegram_button` comments. Both wrappers accept singleton cells and mixed JSON/CML matrices. Native in-body rows allow up to eight buttons; HTML compatibility moves these rows to the footer. In-body clicks acknowledge without recoloring the Rich body, while footer selection styles remain unchanged. Hidden comments accept a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One adaptive matrix may mix named JSON objects with positional CML cells; separators are optional and one trailing comma is tolerated, including inside JSON objects. Top-level cells become full-width rows while nested rows group one or more buttons horizontally without an artificial parser-level width cap; generated surfaces default to five columns and use six to eight only for short position-bearing labels. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style` set to `primary`, `success`, or `danger`; omitting the first atom leaves the existing prompt-as-label fallback in charge, while the optional style still requires a non-empty prompt. A fourth atom adds disabled state: `{|Next||1}` or `{|Next||true}` disables, `0` or `false` enables (exact lowercase), and omission stays enabled; the third atom may be empty in this form. JSON uses boolean `disabled`. Disabled controls require no prompt or selected style: `{Next|||1}` shows only a label, while `{|||1}` is a blank disabled cell. Disabled controls remain visible without registering callbacks or invoking prompts/app methods. It trims atom boundaries, preserves non-structural text literally, and decodes only `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Buttons use `label` plus `prompt`, or the compact `value` key when both are identical. The bridge strips every assistant-authored HTML comment from Telegram previews and final replies regardless of Markdown position or owning extension, while only recognized top-level comments activate buttons or voice; comment-only output sends no text message and the Pi terminal transcript remains unchanged. It renders valid inline buttons and routes callbacks back into Pi as queued prompts or extension-owned callback actions. Button-only replies receive the standard `☑️ **Choose an option:**` heading as automatic visible fallback text. Once a generated prompt button is accepted, only that exact button switches to its optional `selected_style` (`primary` blue by default, `success` green, or `danger` red) without altering its agent-authored label or emoji; every style still queues the selected prompt.
 
 ### Threaded Mode And Multi-Instance Bus
 

package/node_modules/@llblab/pi-telegram/docs/README.md

@@ -15,7 +15,7 @@ Living index of project documentation in `/docs`.
 - [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, single-artifact Rich results, voice synthesis provider fallback priority, artifact outputs, and callback routing
-- [compact-matrix-literal.md](./compact-matrix-literal.md) — Adaptive Button Literal / CML v3 standard for strict JSON objects, positional cells, optional element commas, mixed bounded-depth matrices, atomic parsing, and renderer-owned width policy
+- [compact-matrix-literal.md](./compact-matrix-literal.md) — Adaptive Button Literal / CML v4 standard for strict JSON objects, positional cells with disabled state, optional element commas, mixed bounded-depth matrices, atomic parsing, and renderer-owned width policy
 - [generative-apps.md](./generative-apps.md) — Generative Apps runtime and wire contract for managed `.mjs` identity, inference-bypass bindings, persistent state timelines, bounded adapters, replacement, and lifecycle; agent operation lives in the bundled `generative-apps` Skill
 - [callback-namespaces.md](./callback-namespaces.md) — Shared Telegram `callback_data` namespace standard for layered extensions
 - [updates.md](./updates.md) — Update classification and runtime handler registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection

package/node_modules/@llblab/pi-telegram/docs/architecture.md

@@ -80,7 +80,7 @@ The repository uses a **Flat Domain DAG**:
 - `preview` / `replies` / `rendering`: throttled native Rich Markdown draft delivery, native final reply delivery, reply parameters, transport-limit chunking, and remaining Telegram HTML rendering for bridge-owned UI/compatibility surfaces.
 - `delivery`: public extension operational-view delivery, active-turn/instance/aggregate/authorized target policy, logical chunk handles, per-target ordering, runtime generation fencing, and the process-local runtime membrane. Its bridge adapter composes the established UI/compat reply renderer with narrow bus-aware Telegram API and ownership ports; it never exposes bot clients or Pi contexts.
 - `activity`: public normalized Pi lifecycle registration, activity/source identity, assistant segment and reasoning normalization, executed-tool events, non-blocking per-handler queues, delivery contexts, compatibility adapters, and shutdown fencing. The same domain extends assistant-output observation for connected companion projection: eligible completed local/autonomous public segments retain source order and deduplicate event identity. `bindings` assembles observation, authority, sender, and failure-projection ports; routing owns exact delivery authority, outbound composes established transformations and reply delivery, and Bot API domains implement transport. No separate proactive state-machine domain exists.
-- `outbound-markup`: top-level assistant action comment parsing, attribute parsing, voice reply planning, and preview/delivery stripping.
+- `outbound-markup`: top-level assistant action comment/fence parsing, shared JSON/CML grammar, attribute parsing, voice reply planning, and preview/delivery stripping.
 - `outbound`: outbound text transformations, voice/button artifact delivery, and generated callback actions.
 - `generative-apps`: managed deterministic application identity, canonical installation and explicit replacement, content-addressed module loading, state timelines, cross-process transition serialization, bounded executable-plus-argv adaptation, `telegram_bind`, and pre-model-queue `app::method` invocation. It does not own Telegram transport, arbitrary shell execution, or the external application adapted by one Generative App.
 - `outbound-attachments`: `telegram_attach`, queued outbound files, stat/limit checks, ordinary photo/document delivery, and narrow single-artifact Rich Message planning/sending for probe-confirmed photo/video/audio formats. It owns known-failure fallback eligibility and ambiguous-send no-replay classification through structural error contracts without importing Bot API helpers.
@@ -352,12 +352,14 @@ Final delivery attaches reply metadata only where requested. Reply parameters ap
 
 Outbound files staged during an active Telegram turn are delivered after that turn completes. They use `telegram_attach`, are checked atomically per tool call, and use configurable size limits before photo/document upload. When no Telegram turn is active, `telegram_attach` sends files immediately to the paired/default chat, an assigned follower thread, or an explicit `chat_id` plus optional `thread_id`; `telegram_message` provides direct local/TUI Markdown text delivery for explicit user requests and runs the same `telegram_button` markup planner so buttons attach to that text message. Direct local/TUI delivery is singleton-controlled: classic mode requires this Pi instance to own `/telegram-connect`, while Threaded Mode followers must be registered and route through the leader-owned transport. Already accepted active-turn reply/attachment delivery remains session-local.
 
-Assistant-authored final-message actions use hidden top-level comments:
+Assistant-authored final-message actions use hidden top-level comments, with an additional fenced wrapper for in-body buttons:
 
 - `telegram_voice` accepts one positional compact action cell or JSON object and creates one voice artifact through configured outbound handlers, programmatic voice handlers, or registered synthesis providers.
 - `telegram_button` accepts a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal. Named JSON objects and positional cells may coexist, with commas optional only between completed matrix or row elements. Each top-level cell creates one full-width row, while a nested row groups buttons horizontally without an artificial parser-width cap; every callback enqueues its configured prompt text as a normal Telegram prompt turn. The JSON-first grammar, positional trim/escape rules, atomic rejection, and renderer-owned width policy are specified in [Adaptive Button Literal](./compact-matrix-literal.md).
 
-Action recognition remains restricted to top-level column-zero comments so nested examples cannot trigger voice, buttons, or callbacks. The Telegram surface independently strips every complete assistant-authored HTML comment from previews and final delivery regardless of Markdown position or comment owner; an unclosed comment is withheld through the remaining tail, and a comment-only result sends no text message. Pi's terminal transcript and model context remain unchanged.
+Standalone column-zero triple-backtick `telegram_button` blocks reuse the same cell/matrix grammar and callback store, compiling to native Rich Markdown button rows between paragraphs. Rendering validates each complete block before registering any callbacks, escapes label text, preserves disabled cells, and leaves larger enclosing fences literal. Previews hide complete and unfinished action fences. HTML mode projects those controls into the footer. In-body callbacks acknowledge without rewriting the Rich message; selected-style highlighting remains footer-only.
+
+Action recognition remains restricted to top-level column-zero comments and exact-name button fences so nested examples cannot trigger voice, buttons, or callbacks. The Telegram surface independently strips every complete assistant-authored HTML comment from previews and final delivery regardless of Markdown position or comment owner; an unclosed comment is withheld through the remaining tail, and a comment-only result sends no text message. Pi's terminal transcript and model context remain unchanged.
 
 Unknown callback data outside owned prefixes is forwarded as `[callback] <data>` only after built-in and extension handlers decline it.
 

package/node_modules/@llblab/pi-telegram/docs/compact-matrix-literal.md

@@ -1,6 +1,6 @@
 # Adaptive Button Literal
 
-> Status: Portable CML v3 button standard; `pi-telegram` also reuses its positional-cell mechanics for compact voice actions.
+> Status: Portable CML v4 button standard; `pi-telegram` also reuses its positional-cell mechanics for compact voice actions.
 
 Adaptive Button Literal is one bounded-depth matrix grammar over a shared button AST. It accepts strict JSON button objects, positional Compact Matrix Literal (CML) cells, or both in the same matrix and row. Commas between completed matrix or row elements are optional, so producers can progressively compress representation without changing runtime meaning.
 
@@ -8,7 +8,7 @@ Adaptive Button Literal is one bounded-depth matrix grammar over a shared button
 full named JSON → comma-optional adjacency → mixed named/positional cells → compact CML
 ```
 
-The compact form is not JSON: `{label|prompt|variant}` assigns meaning by position. The formats share semantics and topology, not syntax.
+The compact form is not JSON: `{label|prompt|selected_style|disabled}` assigns meaning by position. The formats share semantics and topology, not syntax.
 
 ## Goals
 
@@ -23,7 +23,7 @@ The compact form is not JSON: `{label|prompt|variant}` assigns meaning by positi
 Every accepted payload normalizes to a non-empty ordered list of non-empty rows:
 
 ```text
-Cell = { label?: string, prompt?: string, value?: string, selected_style?: string }
+Cell = { label?: string, prompt?: string, value?: string, selected_style?: string, disabled?: boolean }
 Rows = Cell[][]
 ```
 
@@ -58,7 +58,7 @@ A two-atom cell separates label and prompt:
 {Pause|music::pause}
 ```
 
-Only the first label position may be empty. Prompt-only `{|e2}` is equivalent to JSON `{"prompt":"e2"}`: the existing button fallback uses `e2` as both visible text and queued prompt without requiring a separately authored label.
+The first label position may be empty. Prompt-only `{|e2}` is equivalent to JSON `{"prompt":"e2"}`: the existing button fallback uses `e2` as both visible text and queued prompt without requiring a separately authored label.
 
 A three-atom cell adds the selected style and retains the same optional-label form:
 
@@ -67,7 +67,18 @@ A three-atom cell adds the selected style and retains the same optional-label fo
 {|e2|success}
 ```
 
-The prompt and style atoms remain required. The style atom is accepted only as `primary`, `success`, or `danger`.
+In a three-atom cell, the prompt and style remain required; style accepts only `primary`, `success`, or `danger`.
+
+A four-atom cell adds disabled state:
+
+```text
+{Next|||1}
+{|||1}
+{Next|counter::next|success|1}
+{Next|counter::next||0}
+```
+
+The fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling; omitting the fourth position keeps the button enabled. The third atom may be empty in this form to retain the default selected style. Disabled cells may omit the prompt, label, and selected style: `{Next|||1}` is a label-only control and `{|||1}` is a blank disabled cell. Enabled CML cells still require a prompt. Telegram requires a `text` field, so its renderer sends a non-breaking space (`U+00A0`) for a blank disabled cell; the notation itself does not invent a label or action. Client rendering of blank cells requires live verification. JSON uses a boolean `disabled`; other value types are invalid. Disabled cells remain visible in their original row but register no action and carry no callback data.
 
 ## Adaptive Grammar
 
@@ -83,6 +94,8 @@ boundary        := ws [","] ws
 positional-cell := "{" atom "}"
                  | "{" [atom] "|" atom "}"
                  | "{" [atom] "|" atom "|" atom "}"
+                 | "{" [atom] "|" atom "|" [atom] "|" ("0" | "false") "}"
+                 | "{" [atom] "|" [atom] "|" [atom] "|" ("1" | "true") "}"
 atom            := atom-unit+
 atom-unit       := ordinary | "\|" | "\}" | "\\"
 ws              := *(SP | HTAB | CR | LF)
@@ -117,7 +130,7 @@ A conforming parser:
 3. Tries one complete strict JSON object, then bounded trailing-comma recovery, at each cell boundary before positional interpretation.
 4. Keeps JSON-shaped named objects on the JSON path when validation fails instead of exposing their source as positional text.
 5. Accepts at most one comma between elements or immediately before a closing row or matrix delimiter, while rejecting leading, repeated, or property-level omitted commas.
-6. Rejects empty matrices, rows, one-atom cells, prompts, styles, and nesting deeper than one row; only the first label position may be empty in a two- or three-atom button cell.
+6. Rejects empty matrices, rows, one-atom cells, enabled-cell prompts, and nesting deeper than one row. The label may be empty in multi-atom cells; the style may additionally be empty in four-atom cells. Disabled four-atom cells may omit all first three atoms. Rejects unknown styles, invalid disabled values, and more than four button atoms.
 7. Decodes only `\|`, `\}`, and `\\` in positional cells.
 8. Extracts the first complete valid payload from a tolerant comment envelope and ignores unrelated text or isolated unmatched matrix brackets around it.
 9. Returns no partial rows or cells from a balanced malformed candidate.
@@ -127,17 +140,32 @@ Malformed JSON-looking input receives no generic recovery. It is accepted only i
 
 ## Telegram Profiles
 
-For `telegram_button` comments:
+For `telegram_button` hidden comments and fenced blocks:
 
 - JSON `value` keeps its existing label/prompt fallback semantics.
 - Positional `{value}` is equivalent to JSON `{"value":"value"}`; a lone JSON `label` or `prompt` has the same both-fields shorthand semantics.
 - Positional `{|prompt}` is equivalent to JSON `{"prompt":"prompt"}` and therefore uses the prompt as both visible text and queued prompt.
 - Positional `{label|prompt}` is equivalent to JSON `{"label":"label","prompt":"prompt"}`.
 - Positional `{label|prompt|selected_style}` and `{|prompt|selected_style}` are equivalent to their corresponding JSON objects.
+- Positional `{label|prompt|selected_style|1}` is equivalent to JSON `{"label":"label","prompt":"prompt","selected_style":"selected_style","disabled":true}` with a valid selected style; `{|prompt||1}` is equivalent to `{"prompt":"prompt","disabled":true}`. Fourth-position `0` or `false` matches `disabled: false`; `true` is equivalent to `1`.
+- `{label|||1}` matches JSON `{"label":"label","disabled":true}`; `{|||1}` matches `{"disabled":true}`. Disabled cells require no prompt and do not retain action or selected-style semantics.
+- Disabled buttons serialize as `{ text, disabled: {} }`, without `callback_data`; they neither enqueue prompts nor invoke bound app methods. Enabled controls keep existing selection and callback behavior.
 - Top-level cells become full-width rows.
 - Nested rows become horizontal keyboard rows.
 - Invalid payloads are stripped with their recognized action comment and register no callbacks.
 
+The wrapper selects placement without changing cell semantics. A hidden `telegram_button` HTML comment builds the footer keyboard. A standalone column-zero fenced block opened by exactly three backticks plus `telegram_button` renders rows between paragraphs in Native Rich Markdown. A singleton JSON/CML object needs no array in either wrapper. Fenced content must be one complete payload without trailing envelope text. Larger outer fences and ordinary code blocks remain literal examples; unclosed action fences are withheld. Native Rich rows support at most eight buttons and must fit one message chunk; these are renderer constraints, not grammar limits. HTML compatibility places fenced controls in the footer. See [Outbound](./outbound.md) for delivery and callback behavior.
+
+````markdown
+Description.
+
+```telegram_button
+[{Details|Explain this section.}[{Choose|Choose this option.}{Unavailable|||true}]]
+```
+
+Next paragraph.
+````
+
 For `telegram_voice`, one positional cell maps `{text}`, `{text|lang}`, or `{text|lang|rate}` to one voice artifact. JSON object cells remain available for named fields, escaping, and multiline text. Voice comments do not accept matrix or row composition.
 
 Example:
@@ -157,7 +185,7 @@ The grammar imposes no visual row-width maximum. Renderer and interaction policy
 Accepted classes include:
 
 - Strict JSON objects and matrices.
-- Positional singleton, two-atom, prompt-only `{|prompt}`, and styled cells.
+- Positional singleton, two-atom, prompt-only `{|prompt}`, styled, and four-atom disabled-state cells.
 - Matrices and rows with commas, without commas, or a mixture of boundaries.
 - Named JSON and positional cells mixed in one matrix or row.
 - Literal commas inside positional atoms and strict JSON strings.
@@ -166,12 +194,12 @@ Accepted classes include:
 
 Rejected classes include:
 
-- Empty payloads, matrices, rows, one-atom cells, prompts, or style atoms; an empty label is valid only as the first position of a two- or three-atom button cell.
+- Empty payloads, matrices, rows, one-atom cells, enabled-cell prompts, or three-atom styles; disabled four-atom cells may omit the first three atoms but not the disabled flag.
 - Leading or repeated element commas.
 - Missing commas between properties inside a JSON object.
 - Deeper row nesting.
 - Missing, crossed, or mismatched delimiters.
-- A third positional separator, unknown style, unknown escape, or trailing backslash.
+- A fourth positional separator, unknown style, invalid disabled flag, unknown escape, or trailing backslash.
 - Internal control characters.
 - Valid JSON that fails the existing JSON action schema.
 
@@ -179,4 +207,4 @@ Every rejected case proves zero callback registration.
 
 ## Versioning
 
-This document defines CML v3. V3 extends the v2 positional grammar with strict JSON object cells, mixed representation, optional element-boundary commas, and prompt-only button cells that preserve the established JSON fallback semantics. It does not make JSON object internals permissive and does not add deeper structures. Future versions must preserve strict-JSON-first routing, bounded depth, atomic rejection, and an explicit discriminator for any new meaning at a security or ownership boundary.
+This document defines CML v4. V4 adds a fourth button atom for disabled state, permits an empty third atom in that form, and makes labels and prompts optional for disabled cells. Existing one-, two-, and three-atom button cells, JSON/CML mixing, optional element-boundary commas, and prompt-only fallback semantics remain unchanged. Voice cells retain their three-atom maximum. JSON object internals and nesting depth remain unchanged. Future versions must preserve strict-JSON-first routing, bounded depth, atomic rejection, and an explicit discriminator for any new meaning at a security or ownership boundary.

package/node_modules/@llblab/pi-telegram/docs/generative-apps.md

@@ -49,7 +49,7 @@ An app name is a unique lowercase ASCII identifier accepted by the runtime's pat
 
 ## Inference-Bypass Syntax
 
-Compact Matrix Literal and full JSON buttons keep their existing `label + prompt` contract. A bound action is encoded entirely in the prompt string:
+Compact Matrix Literal and full JSON buttons keep their existing `label + prompt` contract. App output may use hidden `telegram_button` comments for footer controls or standalone triple-backtick `telegram_button` blocks between paragraphs; both singleton cells and mixed matrices retain the same generation/revision-bound routing. In-body controls acknowledge clicks without recoloring the message; HTML compatibility moves them to the footer. A bound action is encoded entirely in the prompt string:
 
 ```ebnf
 bound-action = app "::" method [ "(" json-value ")" ]
@@ -83,7 +83,7 @@ Equivalent JSON:
 ]
 ```
 
-`app` is not a button property. Both representations normalize to the same prompt string, and routing happens afterward.
+`app` is not a button property. Both representations normalize to the same prompt string, and routing happens afterward. The shared [button grammar](./compact-matrix-literal.md) also supports disabled controls: `{Call|||1}` or JSON `{"label":"Call","disabled":true}`. A disabled cell needs no method prompt or selected style; `{|||1}` is an intentional blank disabled cell. These remain visible but register no callback or bound action. App methods must still validate current state when invoked through an enabled control or another supported entrypoint; disabled presentation is not an authorization boundary.
 
 The double colon is the inference-bypass operator: it routes a generated prompt control to a registered deterministic owner before Pi queue admission. Native extension callbacks retain their existing single-colon grammar:
 

package/node_modules/@llblab/pi-telegram/docs/outbound.md

@@ -155,12 +155,14 @@ I can continue.
 
 Rules:
 
-- The payload may be a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row. Commas are optional between completed elements, and one trailing comma before a closing delimiter is tolerated; JSON object validation likewise tolerates trailing commas but does not invent missing values, property names, or internal separators. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style`; the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`.
+- The payload may be a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row. Commas are optional between completed elements, and one trailing comma before a closing delimiter is tolerated; JSON object validation likewise tolerates trailing commas but does not invent missing values, property names, or internal separators. CML uses `{value}`, `{label|prompt}`, `{|prompt}`, or the corresponding three-atom form with `selected_style`; the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling, permitting an empty style atom in this form: `{|Next||1}`. An omitted fourth position stays enabled. JSON uses boolean `disabled`; legacy attributes accept `disabled="true"` or `disabled="false"`. Invalid disabled values reject the candidate matrix atomically. Disabled cells require no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank, equivalent to JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`. They retain their row and label, serialize as `{ text, disabled: {} }` (non-breaking-space text for a blank cell), and register no callback, prompt, or bound app action. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`.
 - Use `label` plus `prompt`, or the compact `value` key when both strings are identical. If only `label`, only `prompt`, one-field `{value}`, or prompt-only `{|prompt}` is present, that string supplies both visible label and queued prompt. An explicit counterpart takes precedence over `value`. Use JSON with `\n` escapes for multiline prompts.
 - The opening marker must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples; otherwise it does not activate a button action and is still removed from the Telegram surface.
-- Prefer one matrix comment for multiple buttons. Each top-level JSON object or CML cell becomes one full-width inline-keyboard row in source order; a nested row groups one or more buttons horizontally. The parser imposes no artificial per-row width cap; empty rows, malformed cells, unknown/trailing CML escapes, a third unescaped CML separator, empty prompt/style atoms, empty one-atom cells, unknown selected styles, and deeper nesting are rejected atomically. Only the first label position may be empty in a two- or three-atom button cell. Generated surfaces default to five columns and expand to six through eight only for short position-bearing labels. Repeated singular comments remain valid.
+- Prefer one matrix comment for multiple buttons. Each top-level JSON object or CML cell becomes one full-width inline-keyboard row in source order; a nested row groups one or more buttons horizontally. The parser imposes no artificial per-row width cap; empty rows, malformed cells, unknown/trailing CML escapes, a fourth unescaped CML separator, empty enabled-cell prompts or three-atom styles, invalid disabled flags, empty one-atom cells, unknown selected styles, and deeper nesting are rejected atomically. Multi-atom cells may omit the label; four-atom cells may additionally omit the selected style, and disabled cells may omit the prompt. Generated surfaces default to five columns and expand to six through eight only for short position-bearing labels. Repeated singular comments remain valid.
 - Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.
-- After Telegram accepts a generated button callback as a queued prompt, the bridge changes that exact button to its configured selection style without changing agent-authored text or emoji. Set `selected_style` to `primary` (blue), `success` (green), or `danger` (red); omitted or invalid values fall back to `primary`. The style never suppresses queue admission. Other choices stay visually unchanged and remain available; the callback acknowledgement remains the fallback on clients that do not render button styles.
+- Standalone column-zero fences opened by exactly three backticks and `telegram_button` use the same singleton/matrix JSON/CML grammar. Complete valid blocks become native `<tg-button-row>` elements in `InputRichMessage.markdown`, at their original positions. Each row supports at most eight buttons and must fit a Rich Message chunk; validation precedes callback registration for the entire block. Labels are escaped, prompts never enter the native markup, and disabled cells have no callback. Missing closures, trailing payload garbage, and invalid blocks produce no controls. Other language names and enclosing code examples stay literal. Draft previews withhold complete and unfinished action fences without registering actions. HTML compatibility projects fenced rows into the bottom keyboard before comment-authored footer rows; source ordering within each group is retained.
+- In-body controls share prompt/app dispatch, TTL, generation/revision checks, and sent-message target ownership with footer controls. Their acknowledgement is the selection feedback; `selected_style` does not recolor the Rich body. No callback-triggered body rewrite is introduced, preventing a stale click from overwriting newer app output. The operator confirmed the post-reload current-client smoke: singleton CML and mixed JSON/CML in-body rows, their ordinary prompt callbacks, a labeled disabled control, and the separate footer callback work as intended. Client type was not recorded. The operator also confirmed that HTML mode projects the in-body groups into the bottom keyboard as intended. Second-client coverage, follower routing, blank cells, and app-method dispatch/revision rejection remain live-gated. Bot API evidence: `InputRichBlockButtons` / Rich Markdown `tg-button-row` and `RichMessageButton` use ordinary `callback_data` and support disabled controls.
+- After Telegram accepts a generated footer button callback as a queued prompt, the bridge changes that exact button to its configured selection style without changing agent-authored text or emoji. Set `selected_style` to `primary` (blue), `success` (green), or `danger` (red); omitted or invalid values fall back to `primary`. The style never suppresses queue admission. Other choices stay visually unchanged and remain available; the callback acknowledgement remains the fallback on clients that do not render button styles.
 - When generated button markup is the entire assistant reply, the bridge supplies the standard `☑️ **Choose an option:**` heading as visible message text so Telegram has a message to which it can attach the inline keyboard.
 
 Do not emit inline comments after visible text, standalone button actions, or tool calls for ordinary Telegram-turn buttons. The agent writes Markdown plus hidden comments; the bridge strips comments and attaches Telegram `reply_markup` after `agent_end`. For local/TUI-originated direct sends, put the same Markdown and `telegram_button` comments in `telegram_message(text)`.
@@ -176,7 +178,7 @@ The extension injects prompt guidance by context:
 - For Telegram-originated turns, the compact note routes the agent to `telegram-bridge`, which owns voice/button/direct-delivery/Threaded Mode/formatting/debug guidance.
 - For Telegram-originated turns, write the full technical answer as normal Markdown.
 - Add `telegram_voice` with positional CML by default or JSON when multiline content, named fields, or escaping requires it. A companion summary is optional, no specific summary format is required.
-- Add `telegram_button` with a JSON object, JSON matrix, or positional CML. Prefer one matrix for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` is optional. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
+- Add `telegram_button` with a JSON object, JSON matrix, or positional CML. Use a hidden comment for footer placement or a standalone triple-backtick `telegram_button` block for placement between paragraphs. Prefer one matrix for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` and boolean `disabled` are optional. Keep at least one useful enabled action on an interactive surface. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
 - For ordinary Telegram-turn replies, do not call transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion. For explicit local/TUI direct sends, `telegram_message` may include top-level `telegram_button` comments in its Markdown text because those buttons are attached to that text message.
 - Prefer meaningful visible parent text when it adds context; for a button-only answer, rely on the bridge's automatic `☑️ **Choose an option:**` fallback rather than manufacturing duplicate text.
 

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -68,7 +68,7 @@ Every assistant-authored HTML comment is transport-private on Telegram: previews
 - `telegram_message(text, chat_id?, thread_id?)` sends a direct Telegram Markdown message when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. During an active Telegram turn, omitted targeting and an explicit target equal to that turn are rejected so the ordinary final-reply path remains the sole current-target response; an explicit different chat/thread target remains allowed for requested cross-target delivery. Outside active turns, paired/default local/TUI delivery remains unchanged. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
 - The bundled `telegram-bridge` Skill owns action syntax, target routing, Threaded Mode, formatting, Generative App operation, and profile-specific debugging guidance. The regular prompt routes applicable turns to that Skill. `telegram_attach`, `telegram_bind`, and `telegram_message` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
 - `telegram_voice` hidden comments request Telegram-native voice delivery through `{text}`, `{text|lang}`, `{text|lang|rate}`, or a JSON object. JSON is the fallback for multiline content, named fields, or escaping; equivalent `text` or `value` supplies the spoken payload, with explicit `text` taking precedence.
-- `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. One marker accepts a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row; separators are optional and one trailing comma is tolerated at matrix, row, and JSON-object boundaries. Top-level cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, prompt-only `{|prompt}`, or the corresponding three-atom form with `selected_style`; an omitted label uses the existing prompt-as-label fallback, and the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero comments outside code, quotes, lists, and indented examples; do not emit standalone button actions.
+- `telegram_button` hidden comments create footer buttons; standalone column-zero triple-backtick `telegram_button` blocks create button rows between paragraphs in Native Rich Markdown. Both accept the same singleton or mixed JSON/CML matrix and share prompt/app routing. Native rows allow at most eight buttons and must fit one Rich Message chunk; invalid or incomplete blocks register nothing. Drafts hide action fences. HTML compatibility projects fenced controls into the footer. In-body clicks acknowledge without recoloring the Rich body; selected-style highlighting remains footer-only. One marker accepts a JSON object, adaptive JSON/CML matrix, or positional [Compact Matrix Literal](./compact-matrix-literal.md). Named JSON objects and positional cells may coexist in one matrix or row; separators are optional and one trailing comma is tolerated at matrix, row, and JSON-object boundaries. Top-level cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, prompt-only `{|prompt}`, or the corresponding three-atom form with `selected_style`; an omitted label uses the existing prompt-as-label fallback, and the optional third atom requires a non-empty prompt and accepts only `primary`, `success`, or `danger`. A fourth atom accepts `1` or `true` (disabled), and `0` or `false` (enabled), with exact lowercase spelling; an omitted fourth position stays enabled, and the third atom may be empty in this form (`{|Next||1}`). JSON uses boolean `disabled`. Disabled cells need no prompt or selected style: `{Next|||1}` is label-only and `{|||1}` is blank (JSON `{"label":"Next","disabled":true}` and `{"disabled":true}`). The Telegram renderer supplies a non-breaking space only when the label is empty. Disabled cells stay visible but carry `disabled: {}` instead of callback data and register no prompt or bound action; invalid disabled values reject the candidate matrix. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero action wrappers, outside quotes, lists, or enclosing code examples. Ordinary code fences and larger outer fences preserve literal examples; bare JSON/CML in prose never activates.
 
 Prompt guidance is context-aware: local/TUI prompts see only explicit direct-delivery guidance, while Telegram-originated turns receive the full action-comment syntax and phone-width output contract.
 

package/node_modules/@llblab/pi-telegram/index.ts

@@ -245,7 +245,10 @@ export default function (pi: Pi.ExtensionAPI) {
     Config.createTelegramProactivePushChatIdGetter(proactivePushTargetGetter);
   const buttonActionStore = Outbound.createTelegramButtonActionStore();
   const planGenerativeAppOutput =
-    Outbound.createTelegramOutboundReplyPlanner(buttonActionStore);
+    Outbound.createTelegramOutboundReplyPlanner(
+      buttonActionStore,
+      configControls.getAssistantRenderingMode,
+    );
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
       Model.ScopedTelegramModel<ActivePiModel>

package/node_modules/@llblab/pi-telegram/lib/bindings.ts

@@ -518,7 +518,10 @@ export function registerTelegramCommandsAndTools({
   GenerativeApps.registerTelegramBindTool(pi, {
     agentDir,
     getActiveTurn: activeTurnRuntime.get,
-    planOutput: OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
+    planOutput: OutboundHandlers.createTelegramOutboundReplyPlanner(
+      buttonActionStore,
+      Config.createTelegramConfigControls(configStore).getAssistantRenderingMode,
+    ),
     sendMarkdownReply,
     recordRuntimeEvent,
   });
@@ -538,7 +541,10 @@ export function registerTelegramCommandsAndTools({
     routeAgentMessage,
     canSendDirect,
     planMessage:
-      OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
+      OutboundHandlers.createTelegramOutboundReplyPlanner(
+        buttonActionStore,
+        Config.createTelegramConfigControls(configStore).getAssistantRenderingMode,
+      ),
     sendMarkdownMessage: (chatId, markdown, options) =>
       sendMarkdownReply(chatId, undefined, markdown, options),
     recordRuntimeEvent,
@@ -854,7 +860,10 @@ export function registerTelegramLifecycleRuntimeHooks({
     });
   };
   const outboundReplyPlanner =
-    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+    OutboundHandlers.createTelegramOutboundReplyPlanner(
+      buttonActionStore,
+      getAssistantRenderingMode,
+    );
   const voiceReplySenderDeps = {
     execCommand: CommandTemplates.execCommandTemplate,
     sendMultipart: callMultipart,

package/node_modules/@llblab/pi-telegram/lib/keyboard.ts

@@ -9,11 +9,13 @@ export type TelegramInlineKeyboardButtonStyle =
   | "success"
   | "primary";
 
-export interface TelegramInlineKeyboardButton {
+export type TelegramInlineKeyboardButton = {
   text: string;
-  callback_data: string;
   style?: TelegramInlineKeyboardButtonStyle;
-}
+} & (
+  | { callback_data: string; disabled?: never }
+  | { disabled: Record<string, never>; callback_data?: never }
+);
 
 export interface TelegramInlineKeyboardMarkup {
   inline_keyboard: TelegramInlineKeyboardButton[][];

package/node_modules/@llblab/pi-telegram/lib/outbound-buttons.ts

@@ -12,6 +12,8 @@ import type {
 } from "./keyboard.ts";
 import {
   parseTelegramActionPayloadRows,
+  parseTelegramButtonPayloadRows,
+  replaceTelegramButtonFences,
   replaceTopLevelHtmlComments,
 } from "./outbound-markup.ts";
 import {
@@ -34,6 +36,7 @@ export interface TelegramOutboundButtonAction {
   prompt: string;
   binding?: TelegramOutboundButtonBinding;
   selectedStyle?: TelegramInlineKeyboardButtonStyle;
+  disabled?: true;
 }
 
 export interface TelegramOutboundButtonStoredAction extends TelegramOutboundButtonAction {
@@ -115,6 +118,12 @@ function parseTelegramButtonAction(
   const explicitLabel = getTelegramButtonString(payload, "label");
   const explicitPrompt = getTelegramButtonString(payload, "prompt");
   const label = explicitLabel ?? value ?? explicitPrompt;
+  if (payload.disabled !== undefined && typeof payload.disabled !== "boolean") {
+    return undefined;
+  }
+  if (payload.disabled === true) {
+    return { text: label ?? "", prompt: "", disabled: true };
+  }
   const prompt = explicitPrompt ?? value ?? explicitLabel;
   if (!label || !prompt) return undefined;
   const selectedStyle = payload.selected_style;
@@ -159,6 +168,7 @@ export function createTelegramButtonActionStore(
       return {
         text: action.text,
         prompt: action.prompt,
+        ...(action.disabled ? { disabled: true as const } : {}),
         ...(action.binding ? { binding: action.binding } : {}),
         ...(action.selectedStyle
           ? { selectedStyle: action.selectedStyle }
@@ -171,33 +181,75 @@ export function createTelegramButtonActionStore(
 const DEFAULT_TELEGRAM_BUTTON_REPLY_MARKDOWN =
   "☑️ **Choose an option:**";
 
+function escapeTelegramRichButtonText(text: string): string {
+  return text.replace(/[&<>"'`\\*_\[\]{}$~\r\n]/g, (character) =>
+    `&#${character.charCodeAt(0)};`,
+  );
+}
+
+function renderTelegramRichButtonRow(
+  row: TelegramOutboundButtonMarkup["inline_keyboard"][number],
+): string {
+  return `<tg-button-row>${row.map((button) => {
+    const attributes = button.disabled
+      ? 'type="disabled"'
+      : `type="callback_data" data="${escapeTelegramRichButtonText(button.callback_data)}"`;
+    return `<tg-button ${attributes}>${escapeTelegramRichButtonText(button.text)}</tg-button>`;
+  }).join("")}</tg-button-row>`;
+}
+
 export function planTelegramButtonReply(
   markdown: string,
   deps: {
     registerAction: (action: TelegramOutboundButtonAction) => string;
     binding?: TelegramOutboundButtonBinding;
+    rendering?: "rich" | "html";
   },
 ): TelegramButtonReplyPlan {
   const keyboard: TelegramOutboundButtonMarkup["inline_keyboard"] = [];
-  const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+  const buildRows = (
+    payloadRows: Record<string, unknown>[][],
+    rich: boolean,
+  ): TelegramOutboundButtonMarkup["inline_keyboard"] | undefined => {
+    const actions = payloadRows.map((row) => row.map(parseTelegramButtonAction));
+    if (actions.some((row) => row.some((action) => !action))) return undefined;
+    if (rich && actions.some((row) => {
+      const projected = row.map((action) => action!.disabled
+        ? { text: action!.text || "\u00a0", disabled: {} }
+        : { text: action!.text, callback_data: "x".repeat(64) });
+      return row.length > 8 || renderTelegramRichButtonRow(projected).length > 32768;
+    })) return undefined;
+    return actions.map((row) => row.map((action) => action!.disabled
+      ? { text: action!.text || "\u00a0", disabled: {} }
+      : {
+          text: action!.text,
+          callback_data: deps.registerAction({
+            ...action!,
+            ...(deps.binding ? { binding: deps.binding } : {}),
+          }),
+        }));
+  };
+  const withRichButtons = replaceTelegramButtonFences(markdown, (payload, closed) => {
+    if (!closed) return "";
+    const payloadRows = parseTelegramButtonPayloadRows(payload);
+    if (!payloadRows) return "";
+    const rich = deps.rendering !== "html";
+    const rows = buildRows(payloadRows, rich);
+    if (!rows) return "";
+    if (!rich) {
+      keyboard.push(...rows);
+      return "";
+    }
+    return `\n${rows.map(renderTelegramRichButtonRow).join("\n\n")}\n`;
+  });
+  const stripped = replaceTopLevelHtmlComments(withRichButtons, (comment) => {
     const command = "telegram_button";
     const normalizedContent = comment.content.replace(/^\s+/, "").replace(/^!/, "");
     if (!normalizedContent.startsWith(command)) return comment.raw;
     const payloadRows = parseTelegramActionPayloadRows(comment, command);
     if (!payloadRows) return "";
-    const actionRows = payloadRows.map((payloadRow) =>
-      payloadRow.map(parseTelegramButtonAction),
-    );
-    if (actionRows.some((row) => row.some((action) => !action))) return "";
-    for (const actionRow of actionRows) {
-      keyboard.push(actionRow.map((action) => ({
-        text: action!.text,
-        callback_data: deps.registerAction({
-          ...action!,
-          ...(deps.binding ? { binding: deps.binding } : {}),
-        }),
-      })));
-    }
+    const rows = buildRows(payloadRows, false);
+    if (rows) keyboard.push(...rows);
     return "";
   });
   const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(stripped);
@@ -254,7 +306,7 @@ export function markTelegramButtonSelected(
   let matched = false;
   const inlineKeyboard = replyMarkup.inline_keyboard.map((row) =>
     row.map((button) => {
-      if (button.callback_data !== callbackData) return { ...button };
+      if (button.disabled || button.callback_data !== callbackData) return { ...button };
       matched = true;
       return { ...button, style: selectedStyle };
     }),
@@ -277,6 +329,11 @@ export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
     return false;
   }
 
+  if (action.disabled) {
+    await deps.answerCallbackQuery(query.id, "Button action unavailable.");
+    return true;
+  }
+
   const chatId = query.message?.chat?.id;
   const messageId = query.message?.message_id;
   if (typeof chatId !== "number" || typeof messageId !== "number") {

package/node_modules/@llblab/pi-telegram/lib/outbound-markup.ts

@@ -90,6 +90,50 @@ export function collectTopLevelHtmlComments(markdown: string): {
   return { comments };
 }
 
+export function replaceTelegramButtonFences(
+  markdown: string,
+  replace: (payload: string, closed: boolean) => string,
+): string {
+  let result = "";
+  let copied = 0;
+  let offset = 0;
+  let fence: TelegramTopLevelFenceState | undefined;
+  let actionStart: number | undefined;
+  let contentStart = 0;
+  while (offset < markdown.length) {
+    const end = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, end);
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) {
+        if (actionStart !== undefined) {
+          result += markdown.slice(copied, actionStart);
+          result += replace(markdown.slice(contentStart, offset), true) + "\n";
+          copied = end;
+          actionStart = undefined;
+        }
+        fence = undefined;
+      }
+    } else if (line.includes("<!--")) {
+      const close = markdown.indexOf("-->", offset + line.indexOf("<!--") + 4);
+      if (close < 0) break;
+      offset = getMarkdownLineEnd(markdown, close + 3);
+      continue;
+    } else {
+      fence = getTopLevelOpeningFence(line);
+      if (fence && /^```telegram_button[ \t]*$/.test(line)) {
+        actionStart = offset;
+        contentStart = end;
+      }
+    }
+    offset = end;
+  }
+  if (actionStart !== undefined) {
+    result += markdown.slice(copied, actionStart);
+    return result + replace(markdown.slice(contentStart), false);
+  }
+  return result + markdown.slice(copied);
+}
+
 export function replaceTopLevelHtmlComments(
   markdown: string,
   replacer: (comment: TelegramTopLevelHtmlComment) => string,
@@ -275,17 +319,26 @@ type TelegramCompactActionPayloadParser = (
 function parseTelegramButtonCompactActionPayload(
   atoms: readonly string[],
 ): Record<string, unknown> | undefined {
-  const [label, prompt, selectedStyle] = atoms;
+  const [label, prompt, selectedStyle, disabled] = atoms;
   if (atoms.length === 1) return label ? { value: label } : undefined;
-  if (!prompt) return undefined;
+  const isDisabled = disabled === "1" || disabled === "true";
+  if (!prompt && !(atoms.length === 4 && isDisabled)) return undefined;
   const action = label ? { label, prompt } : { prompt };
   if (atoms.length === 2) return action;
   if (
     selectedStyle !== "primary" &&
     selectedStyle !== "success" &&
-    selectedStyle !== "danger"
+    selectedStyle !== "danger" &&
+    !(atoms.length === 4 && selectedStyle === "")
   ) return undefined;
-  return { ...action, selected_style: selectedStyle };
+  if (atoms.length === 4 && !isDisabled && disabled !== "0" && disabled !== "false") {
+    return undefined;
+  }
+  return {
+    ...action,
+    ...(selectedStyle ? { selected_style: selectedStyle } : {}),
+    ...(atoms.length === 4 ? { disabled: isDisabled } : {}),
+  };
 }
 
 function parseTelegramVoiceCompactActionPayload(
@@ -303,7 +356,7 @@ function parseTelegramVoiceCompactActionPayload(
 function parseTelegramAdaptiveActionPayloadRows(
   source: string,
   parseCompactPayload: TelegramCompactActionPayloadParser,
-  options: { allowTrailing?: boolean } = {},
+  options: { allowTrailing?: boolean; maxCompactAtoms?: number } = {},
 ): { rows: Record<string, unknown>[][]; end: number } | undefined {
   let offset = 0;
   const isStructuralWhitespace = (character: string | undefined): boolean =>
@@ -343,7 +396,7 @@ function parseTelegramAdaptiveActionPayloadRows(
         continue;
       }
       if (character === "|") {
-        if (atomSources.length >= 3) return undefined;
+        if (atomSources.length >= (options.maxCompactAtoms ?? 3)) return undefined;
         atomSources.push([]);
         offset += 1;
         continue;
@@ -509,6 +562,16 @@ function isPlausibleTelegramMatrixStart(
   );
 }
 
+export function parseTelegramButtonPayloadRows(
+  source: string,
+): Record<string, unknown>[][] | undefined {
+  return parseTelegramAdaptiveActionPayloadRows(
+    source.trim(),
+    parseTelegramButtonCompactActionPayload,
+    { maxCompactAtoms: 4 },
+  )?.rows;
+}
+
 export function parseTelegramActionPayloadRows(
   comment: TelegramTopLevelHtmlComment,
   command: string,
@@ -533,7 +596,7 @@ export function parseTelegramActionPayloadRows(
     const parsed = parseTelegramAdaptiveActionPayloadRows(
       content.slice(offset),
       parseTelegramButtonCompactActionPayload,
-      { allowTrailing: true },
+      { allowTrailing: true, maxCompactAtoms: 4 },
     );
     if (parsed) return parsed.rows;
     const end = findTelegramStructuredPayloadEnd(content, offset);
@@ -546,8 +609,15 @@ export function parseTelegramActionPayloadRows(
     "prompt",
     "value",
     "selected_style",
+    "disabled",
   ]);
-  return attributes ? [[attributes]] : undefined;
+  if (!attributes) return undefined;
+  return [[{
+    ...attributes,
+    ...(attributes.disabled === "true" || attributes.disabled === "false"
+      ? { disabled: attributes.disabled === "true" }
+      : {}),
+  }]];
 }
 
 export function normalizeMarkdownAfterVoiceExtraction(
@@ -589,7 +659,9 @@ function stripTelegramHtmlCommentBlocks(markdown: string): string {
 }
 
 export function stripTelegramCommentMarkupForPreview(markdown: string): string {
-  const withoutClosedBlocks = stripTelegramHtmlCommentBlocks(markdown);
+  const withoutClosedBlocks = stripTelegramHtmlCommentBlocks(
+    replaceTelegramButtonFences(markdown, () => ""),
+  );
   const openBlockIndex =
     findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const previewMarkdown =

package/node_modules/@llblab/pi-telegram/lib/outbound.ts

@@ -835,6 +835,7 @@ export {
 
 export function createTelegramOutboundReplyPlanner(
   store: Pick<TelegramButtonActionStore, "register">,
+  getRenderingMode: () => "rich" | "html" = () => "rich",
 ): (
   markdown: string,
   options?: { binding?: TelegramOutboundButtonBinding },
@@ -842,6 +843,7 @@ export function createTelegramOutboundReplyPlanner(
   return (markdown, options) => {
     const buttonReply = planTelegramButtonReply(markdown, {
       registerAction: store.register,
+      rendering: getRenderingMode(),
       ...(options?.binding ? { binding: options.binding } : {}),
     });
 

package/node_modules/@llblab/pi-telegram/lib/replies.ts

@@ -532,7 +532,7 @@ function splitTelegramNativeMarkdownCountedBlocks(block: string): string[] {
 function countTelegramNativeMarkdownBlocks(block: string): number {
   if (/^ {0,3}(`{3,}|~{3,})/.test(block)) return 1;
   const lines = block.split("\n").filter((line) => line.trim().length > 0);
-  if (lines.some((line) => /^\s*([-*+] |\d+\. |>|\|)/.test(line))) {
+  if (lines.some((line) => /^\s*([-*+] |\d+\. |>|\||<tg-button-row>)/.test(line))) {
     return Math.max(1, lines.length);
   }
   return 1;

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.42.4",
+  "version": "0.43.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/SKILL.md

@@ -40,7 +40,9 @@ A surface is an ordered ragged sequence of rows. Each button carries:
 
 - A short, distinct label.
 - The smallest self-contained next-request prompt.
-- Optional presentation state supported by the transport.
+- Optional presentation state supported by the transport, including disabled controls when their visible unavailability helps explain current state.
+
+A disabled control is not an action: it needs no prompt or selected style and must not enqueue a prompt or invoke a bound method. Prefer a meaningful label; omit it only for an intentional blank cell in a spatial layout, never as decorative padding. Preserve its label and position when that makes a changing surface easier to understand; otherwise omit irrelevant controls. Explain non-obvious unavailability without relying on color alone. Retain at least one useful enabled action, such as refresh or navigation. Derive disabled state from the same evidence as the view; an old enabled control still requires current domain validation. Use the transport owner's disabled encoding rather than a dummy prompt or no-op callback.
 
 Prompts must name any target, operation, constraint, or freshness identity whose omission could change the action. Reuse visible context only when it remains unambiguous under delayed or reordered clicks. Never encode volatile output that should be freshly inspected.
 
@@ -57,7 +59,7 @@ Every generated human-readable action label must use `emoji + space + text`; emo
 
 For complex grids, navigation collections, or stateful repeated clicks, read [`references/layout-and-state.md`](./references/layout-and-state.md).
 
-Serialize the resulting rows with the active transport contract. This Skill owns admission and composition, not transport syntax.
+Place a control group beside the section it governs when the transport supports in-body blocks; use a footer for whole-answer actions. Placement must not change the matrix or action semantics. Serialize the resulting rows with the active transport contract. This Skill owns admission and composition, not transport syntax.
 
 ## Safety
 

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/references/layout-and-state.md

@@ -10,7 +10,7 @@ Model the surface as ordered ragged rows, not a rectangle to fill. Infer indepen
 - A horizontal pair is earned only by genuine peers with unmistakably compact labels and no plausible wrapping or truncation.
 - Three through five columns are for short symbols, coordinates, glyphs, or codes whose position carries meaning.
 - Six through eight columns require single-glyph or similarly minimal position-bearing labels. Never exceed eight columns on a phone surface.
-- Vary row width intentionally; never pad with empty, duplicate, or no-op controls.
+- Vary row width intentionally; never pad for symmetry with empty, duplicate, or no-op controls. A blank disabled cell is appropriate only when it represents a real unavailable position in a spatial grid.
 - Preserve reading order: orientation/navigation, primary content or choices, secondary controls, then separated destructive actions.
 - Rectangular grids require genuine spatial or coordinate correspondence. Vertical continuity may justify many rows; non-spatial button walls should paginate or group.
 
@@ -32,4 +32,6 @@ Keep trivial state in conversation. Persist a small human-auditable artifact whe
 
 Evaluate repeated clicks against current state, not stale button appearance. Preserve tap-ahead when the transport queues each click independently. In source-then-destination interaction, retain the source selection without duplicating the whole surface; regenerate after a completed transition, invalid input, or evidence that the transport cannot preserve the intermediate view.
 
-Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates.
+Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates, using the transport's disabled state without a fabricated prompt. Keep a useful enabled navigation or inspection action.
+
+Place each control group beside the content it governs when in-body blocks are supported; keep global navigation and whole-view actions in the footer. Do not duplicate one action in both positions merely for visibility. Row topology and current-state validation stay the same across compact and named representations and across placements; renderer limits and selection feedback belong to the transport.

package/node_modules/@llblab/pi-telegram/skills/generative-apps/SKILL.md

@@ -29,9 +29,9 @@ Generated Control Surface → current context → model → one ephemeral surfac
 Generative App             → model → reusable program → many evolving surfaces
 ```
 
-Both Skills use the same logical button matrix and `label + prompt` interaction model. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
+Both Skills use the same logical button matrix and `label + prompt` interaction model. An app may place groups beside their related content using the transport's in-body button blocks or keep whole-view controls in the footer; placement does not change binding, disabled state, or method authority. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
 
-An app may mix deterministic `app::method` controls and ordinary prompts in one view. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
+An app may mix deterministic `app::method` controls and ordinary prompts in one view, including one control group. Compact and named cells may coexist under the shared transport grammar; neither representation nor placement creates another action plane. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
 
 The `generated` / `generative` distinction is intentional. Do not rename `generated-control-surface` to a competing generative term.
 
@@ -76,7 +76,7 @@ Another capability remains the authoritative real owner. The app stores validate
 1. Identify the repeated feedback loop, real state owner, and actions that are truly deterministic.
 2. Choose one stable lowercase app and one self-contained `<app>.mjs` source outside the managed installation directory.
 3. Keep `init` and every exported method small, named, bounded, shell-free, and capability-specific.
-4. Render one complete next view after each action.
+4. Render one complete next view after each action. Derive disabled controls from current state using the shared transport contract; visible disabled controls neither invoke methods nor enqueue prompts. Revalidate domain preconditions when an enabled control is invoked, because previously rendered views may be stale.
 5. Mix action planes intentionally:
 
 ```text
@@ -107,6 +107,7 @@ Before presenting an app as working:
 - Inspect the installed initial view and persisted bounded state.
 - Exercise at least one real bound action and prove it bypasses Pi queue/model admission.
 - Exercise at least one ordinary prompt when the app intentionally uses the model plane.
+- Verify the placements actually used by the app and prove disabled cells invoke nothing. A successful ordinary prompt-button smoke is not evidence of app-method dispatch or stale-revision rejection.
 - Verify replacement rejects stale buttons and failed initialization preserves the prior app.
 - For adapters, prove fresh external status and terminal mutation evidence.
 - Confirm failures are bounded, redacted, and do not silently render success.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/SKILL.md

@@ -15,7 +15,8 @@ Use Telegram as a mobile companion to the current Pi session. Preserve the exact
 | Attach a requested file to the current turn | `telegram_attach(path)` without targeting |
 | Explicitly send from local/TUI to Telegram | `telegram_message` or `telegram_attach` |
 | Explicitly send to a different live Thread | `telegram_message(thread=...)` |
-| Add prompt buttons or explicit voice | Top-level hidden action comments |
+| Add buttons | Hidden comment for footer; `telegram_button` fence for in-body rows |
+| Add explicit voice | Top-level hidden action comment |
 | Build a repeated deterministic interaction | Follow `generative-apps` |
 
 A connected Telegram session proves capability, not user intent. Use Telegram features on Telegram-originated turns or explicit Telegram delivery requests only. Never call `telegram_message` for the current active target.
@@ -39,7 +40,7 @@ Reply in concise, phone-width Telegram Rich Markdown. Use `$...$` and `$$...$$`
 
 ## Assistant Actions
 
-`telegram_button` and `telegram_voice` are hidden HTML comments, not tools. Emit each complete action comment at column zero, outside lists, quotes, code blocks, and indentation. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position, but only recognized top-level comments activate actions; comment-only output sends no text message.
+`telegram_button` and `telegram_voice` are markup, not tools. Emit action comments at column zero outside lists, quotes, code, and indentation. Comments create footer buttons or voice artifacts. For buttons between paragraphs, use a column-zero triple-backtick `telegram_button` block. Both button wrappers accept the same singleton JSON/CML cell or mixed matrix; the wrapper determines placement. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position; only recognized top-level wrappers activate actions; comment-only output sends no text message.
 
 ### Shared Encoding Rule
 
@@ -48,25 +49,35 @@ Choose the least verbose sufficient representation:
 1. Positional CML — default.
 2. JSON — only when multiline content, named fields, or escaping earns it.
 
-CML trims atom boundaries and decodes `\|`, `\}`, and `\\`. Keep one complete action in one comment.
+CML trims atom boundaries and decodes `\|`, `\}`, and `\\`. Keep each payload inside one complete wrapper.
 
 ### Prompt Buttons
 
-Every button has a self-contained prompt and an optional selection style. Use a short distinct `emoji + space + text` label when separate human-readable labeling adds meaning; established coordinates or symbolic tokens may use the prompt itself as visible text. A click creates an ordinary user request; it never grants authority or bypasses confirmation.
+Every enabled button has a self-contained prompt and an optional selection style. Use a short distinct `emoji + space + text` label when separate human-readable labeling adds meaning; established coordinates or symbolic tokens may use the prompt itself as visible text. A click creates an ordinary user request; it never grants authority or bypasses confirmation.
 
 - `{prompt}` uses the same text for label and prompt.
 - `{|prompt}` omits a separately authored label and uses the prompt as both visible text and queued prompt.
 - `{label|prompt}` separates visible label from queued prompt.
 - `{label|prompt|selected_style}` and `{|prompt|selected_style}` accept `primary`, `success`, or `danger`.
+- Fourth-position `1`/`true` disables, `0`/`false` enables; omission means enabled. JSON uses boolean `disabled`. `{|Next||1}` omits label/style; `{Next|||1}` omits prompt/style; `{|||1}` is blank (Telegram receives a non-breaking space). Prefer meaningful labels and retain a useful enabled action. Enabled CML requires a prompt. Disabled controls stay visible but have no callback, queued prompt, or bound-method invocation.
 - Top-level cells form vertical rows; one nested row groups horizontal peers.
-- Prefer one matrix comment for the complete surface.
+- Prefer one matrix per related group. Fenced blocks stay in place in Rich mode; HTML compatibility moves them to the footer. Native rows allow eight buttons. Malformed/oversized/unclosed blocks activate nothing; drafts hide them. Outer code fences and quoted/indented examples remain literal.
+- Both placements share prompt/app routing. In-body clicks acknowledge without recoloring; selected-style highlighting remains footer-only.
+
+A single in-body button (the four-backtick wrapper below makes this a literal example):
+
+````markdown
+```telegram_button
+{📖 Details|Explain this section.}
+```
+````
 
 ```html
 <!-- telegram_button [{▶️ Continue|Continue the current plan.}[{✅ Approve|Approve this.}{❌ Reject|Reject this.}]] -->
 <!-- telegram_button {"label":"💡 Explain","prompt":"Explain this.\nInclude the risks."} -->
 ```
 
-Proactively use `generated-control-surface` whenever controls can materially shorten likely feedback; once active, it must emit useful buttons rather than prose alone. That Skill owns action composition; this Skill owns Telegram serialization and delivery. If buttons form the whole reply, the bridge supplies the standard choice heading.
+Proactively use `generated-control-surface` whenever controls can materially shorten likely feedback; once active, it must emit useful buttons rather than prose alone. That Skill owns action composition; this Skill owns Telegram serialization and delivery. Footer-only replies receive the standard choice heading.
 
 ### Voice
 
@@ -113,6 +124,6 @@ Before replying:
 
 - Use the ordinary path for the current target and direct tools only for explicit other delivery.
 - Attach requested files rather than only mentioning them.
-- Keep action comments top-level, complete, and canonical: CML first, JSON when necessary.
-- Give every button a self-contained prompt; preserve confirmation for dangerous actions.
+- Keep action comments and button fences top-level, complete, and canonical: CML first, JSON when necessary; either syntax may coexist within one matrix.
+- Give every enabled button a self-contained prompt; preserve confirmation for dangerous actions.
 - Expose no secret or hidden reasoning.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.7.4",
     "@llblab/pi-state-flow": "0.3.0",
-    "@llblab/pi-telegram": "0.42.4",
+    "@llblab/pi-telegram": "0.43.0",
     "@llblab/skills": "1.14.0"
   },
   "bundledDependencies": [