@llblab/pi-telegram 0.36.0 → 0.36.2

package/BACKLOG.md

@@ -3,7 +3,6 @@
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
 - [ ] `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.
-- [ ] `Unauthorized denial consistency`: Align unauthorized Guest Mode answers and direct private-message replies so both begin with the same denial emoji and apply equivalent explicit bold emphasis to their denial copy through each surface's supported renderer; centralize the copy/style owner and protect both paths with focused regressions without pretending callback popups support rich text.
 - [ ] `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.
   - [ ] Harden the implemented `telegram_bind` installation/invocation kernel with removal operations, stronger cross-process replacement recovery, and bounded diagnostics while preserving lifecycle cancellation, worker-isolated methods, explicit staged replacement, canonical `<agent-dir>/genapps/<app>/<app>.mjs` identity, mandatory named `init`, no manifest/package metadata, non-symlink roots/sources, and fail-closed silent replacement.

package/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
-## Unreleased
+## 0.36.2: Provider-Compatible Controls
+
+- `Provider-Compatible Bind Schema`: Exposes `telegram_bind` through one top-level JSON object schema while retaining runtime enforcement of mutually exclusive install and invocation forms, avoiding providers that reject top-level union schemas before any tool call can run.
+- `Reaction Shortcut Naming`: Removes obsolete reaction-action labels from setup guidance now that queue reaction semantics use their current naming.
+- `Compact Thinking Picker`: Keeps `off` on a distinct full-width row and groups the six ordered reasoning intensities into two three-button rows, reducing menu height without changing thinking-level values or callbacks.
+
+## 0.36.1: Adaptive Control Surfaces
+
+- `Adaptive Button Literal`: Replaces binary JSON-or-CML parsing with one strict-JSON-first matrix grammar over a shared button AST. Named JSON objects and positional CML cells may coexist in one matrix or row, commas are optional only between completed elements, every compression step preserves semantics, and malformed comments reject atomically without registering partial callbacks.
+- `Trusted Release Publication`: Makes tag releases depend on reusable full validation, exact tag/package/lock/changelog identity, npm Trusted Publisher provenance, idempotent existing-version checks, public package and tarball verification, and one workflow-owned GitHub Release path without npm tokens.
+- `Consistent Access Denial`: Centralizes unauthorized copy so Guest Mode and private messages render `🚫 Access denied.` with equivalent explicit bold emphasis through HTML-capable surfaces, while callback popups use the same emoji and plain copy without pretending to support rich text.
+- `Destructive Skip State`: Changes the active queue Skip selector from yellow to red and records the indicator in the UI registry, making deferred prompt removal visually distinct from Priority, Scoped, and other elevated but non-destructive states.
+- `Worker Cancellation Fence`: Makes Generative App workers acknowledge child-process abort handling before parent termination, with a bounded forced fallback for synchronously blocked methods, preventing Linux CI load from orphaning a cancelled process long enough to commit its delayed side effect.
+- `Capability App Routing`: Telegram interaction now prefers an already-advertised capability-owned Generative App for repeated controls before synthesizing one-shot prompt buttons, while the bridge remains generic and neither discovers capability-specific apps nor owns their state or identities.
+- `Hybrid Surface Breadcrumbs`: Generated Control Surface and Generative Apps now cross-route over one logical button matrix and shared JSON/CML runtime notation: ephemeral agent composition stays separate from reusable scripts, while one app view may combine deterministic bound methods with ordinary model-mediated prompts and no third button Skill is introduced.
 
 ## 0.36.0: Generative Apps
 

package/README.md

@@ -86,7 +86,7 @@ Enable the optional capabilities the bridge needs in the [@BotFather](https://t.
 
 1. Enable guest mode so the bot can answer mentions and replies in chats where it is not a member.
 2. Enable private-chat Threaded Mode; when it is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Without it, the bridge stays in classic single-owner DM mode.
-3. Make the bot an administrator in any chat where the queue reaction shortcuts (👍 prioritize, 👎 suppress) should work. Reaction updates require admin rights, so the shortcuts silently do nothing in non-admin chats; private chats deliver reactions without admin rights.
+3. Make the bot an administrator in any chat where the queue reaction shortcuts should work. Reaction updates require admin rights, so the shortcuts silently do nothing in non-admin chats; private chats deliver reactions without admin rights.
 
 ## What It Feels Like
 
@@ -220,7 +220,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 using a JSON object, JSON matrix, Compact Matrix Literal (CML), or compact double-quoted attributes; `telegram_buttons` is a plural alias. In JSON and CML matrices, 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}`, or `{label|prompt|selected_style}` with `primary`, `success`, or `danger`; the optional style requires an explicit 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 action marker is colon-free for every payload form. The bridge strips the comments from visible text, renders 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 include top-level hidden `telegram_button` comments using a JSON object, adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or compact double-quoted attributes; `telegram_buttons` is a plural alias. One adaptive matrix may mix named JSON objects with positional CML cells, and commas between completed matrix or row elements are optional while JSON object internals remain strict. 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}`, or `{label|prompt|selected_style}` with `primary`, `success`, or `danger`; the optional style requires an explicit 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 action marker is colon-free for every payload form. The bridge strips the comments from visible text, renders 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/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) — Portable Compact Matrix Literal v1 standard for trimmed key-value cells, minimal escapes, bounded-depth rows, JSON coexistence, and renderer-owned width policy
+- [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
 - [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/docs/architecture.md

@@ -344,7 +344,7 @@ Outbound files staged during an active Telegram turn are delivered after that tu
 Assistant-authored final-message actions use hidden top-level comments with colon-free markers; colon-prefixed payloads are rejected:
 
 - `telegram_voice` accepts a JSON object or double-quoted HTML-like attributes and creates voice reply artifacts through configured outbound handlers, programmatic voice handlers, or registered synthesis providers.
-- `telegram_button` accepts a JSON object, JSON matrix, Compact Matrix Literal, or double-quoted attributes; `telegram_buttons` aliases the same parser. Each top-level matrix cell creates one full-width row, while a nested row groups one or more buttons horizontally without an artificial parser-width cap; every callback enqueues its configured prompt text as a normal Telegram prompt turn. CML's portable grammar, trim/escape rules, JSON-first routing, and renderer-owned width policy are specified in [Compact Matrix Literal](./compact-matrix-literal.md).
+- `telegram_button` accepts a JSON object, adaptive JSON/CML matrix, positional Compact Matrix Literal, or double-quoted attributes; `telegram_buttons` aliases the same parser. 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).
 
 Preview delivery strips top-level action comments before streaming draft Markdown. Comments inside code fences, quotes, lists, or indented examples stay literal.
 

package/docs/compact-matrix-literal.md

@@ -1,94 +1,101 @@
-# Compact Matrix Literal
+# Adaptive Button Literal
 
-> Status: Portable v2 standard implemented by the unreleased `pi-telegram` control-surface parser.
+> Status: Portable CML v3 standard implemented by the unreleased `pi-telegram` control-surface parser.
 
-Compact Matrix Literal (CML) is a bounded-depth text format for ordered key-value cells arranged as singleton or compact rows. It optimizes repeated interactive controls where JSON field names, quotes, and commas dominate the payload.
+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.
 
-CML is transport-neutral. An embedding maps each decoded cell's `key`, `value`, and optional `variant` to its own domain. The `pi-telegram` profile maps them to button label, prompt, and selected style.
-
-## Goals
+```text
+full named JSON → comma-optional adjacency → mixed named/positional cells → compact CML
+```
 
-- Encode common key-value matrices with minimal punctuation.
-- Preserve ordered singleton and compact rows.
-- Preserve non-structural Unicode text literally.
-- Admit deterministic linear-time parsing without evaluation or recovery.
-- Remain deterministic beside an existing JSON form.
-- Fail closed on malformed or deeper structures.
+The compact form is not JSON: `{label|prompt|variant}` assigns meaning by position. The formats share semantics and topology, not syntax.
 
-## Non-Goals
+## Goals
 
-- Replacing JSON for arbitrary objects, multiline values, non-positional metadata, or extensible schemas.
-- Defining callback ownership, application state, rendering policy, or transport behavior.
-- Recovering partial intent from malformed input.
-- Defining one universal visual row-width limit for every renderer.
+- Preserve one ordered button matrix across multiple representation densities.
+- Let producers compress individual cells without converting the whole surface.
+- Preserve valid strict JSON behavior unchanged.
+- Admit deterministic linear-time parsing without evaluation or partial recovery.
+- Keep rendering, callback ownership, and application state outside the notation.
 
 ## Data Model
 
-A decoded payload is an ordered non-empty list of non-empty rows:
+Every accepted payload normalizes to a non-empty ordered list of non-empty rows:
 
 ```text
-Cell = { key: string, value: string, variant?: string }
+Cell = { label?: string, prompt?: string, value?: string, selected_style?: string }
 Rows = Cell[][]
 ```
 
-A top-level cell normalizes to a singleton row. A nested row preserves its compact grouping.
+A top-level cell becomes a singleton row. A nested row preserves horizontal grouping.
 
-A cell with one atom copies its key into its value:
+These representations are semantically equivalent:
 
 ```text
-{7} == { key: "7", value: "7" }
+[[{"label":"Pause","prompt":"music::pause"},{"value":"Next"}],{"value":"Status"}]
+[[{"label":"Pause","prompt":"music::pause"}{"value":"Next"}]{"value":"Status"}]
+[[{"label":"Pause","prompt":"music::pause"},{Next}],{Status}]
+[[{Pause|music::pause}{Next}]{Status}]
 ```
 
-A cell with two atoms separates key and value with one unescaped vertical bar:
+Named JSON objects and positional cells may coexist within the same horizontal row:
 
 ```text
-{🟥|2,5} == { key: "🟥", value: "2,5" }
+[[{"label":"Open","prompt":"/tmp"}{Back|/}]]
 ```
 
-A cell with three atoms adds one optional positional variant. The variant is valid only when the explicit value atom is present:
+## Positional Cells
+
+A one-atom cell copies its value into label and prompt through the existing button contract:
 
 ```text
-{Stop|music-player::stop|danger}
-== { key: "Stop", value: "music-player::stop", variant: "danger" }
+{Next}
 ```
 
-## Grammar
+A two-atom cell separates label and prompt:
+
+```text
+{Pause|music::pause}
+```
 
-The normative structural grammar is:
+A three-atom cell adds the selected style:
 
 ```text
-payload  := cell | matrix
-matrix   := "[" ws element (ws element)* ws "]"
-element  := cell | row
-row      := "[" ws cell (ws cell)* ws "]"
-cell     := "{" atom "}"
-          | "{" atom "|" atom "}"
-          | "{" atom "|" atom "|" atom "}"
-atom     := atom-unit+
-atom-unit := ordinary | "\\|" | "\\}" | "\\\\"
-ws       := *(SP | HTAB | CR | LF)
+{Stop|music::stop|danger}
 ```
 
-`ordinary` is any printable Unicode scalar other than unescaped `|`, unescaped `}`, or `\`. No commas separate elements. A matrix and every nested row must contain at least one element. A row cannot contain another row.
+The style atom is accepted only as `primary`, `success`, or `danger`.
 
-Examples:
+## Adaptive Grammar
+
+The structural grammar is:
 
 ```text
-{Continue}
-{Open|/tmp}
-[{Up|/}[{Prev|page-1}{Next|page-3}]{etc|/etc}]
-[[{1}{2}{3}{4}{5}{6}{7}{8}]]
-{A \| B|C:\\Games\}}
-{Stop|music-player::stop|danger}
+payload         := json-object | matrix | positional-cell
+matrix          := "[" ws element (boundary element)* ws "]"
+element         := cell | row
+row             := "[" ws cell (boundary cell)* ws "]"
+cell            := json-object | positional-cell
+boundary        := ws [","] ws
+positional-cell := "{" atom "}"
+                 | "{" atom "|" atom "}"
+                 | "{" atom "|" atom "|" atom "}"
+atom            := atom-unit+
+atom-unit       := ordinary | "\|" | "\}" | "\\"
+ws              := *(SP | HTAB | CR | LF)
 ```
 
-These normalize respectively to one copied singleton cell, one key-value singleton cell, a mixed singleton/compact matrix, one eight-cell row, `{ key: "A | B", value: "C:\\Games}" }`, and one key-value cell with the `danger` variant.
+`boundary` occurs only after one complete element and before another. It may contain one comma or no comma. Element delimiters make empty adjacency unambiguous. Leading, repeated, and trailing commas are invalid.
+
+A `json-object` is one complete strict JSON object. Its property commas, strings, escaping, nested values, and other internals remain ordinary strict JSON; comma optionality applies only between matrix or row elements.
+
+Rows cannot contain rows. The grammar never recurses beyond one row inside the top-level matrix.
 
 ## Atoms, Whitespace, And Escapes
 
-Leading and trailing whitespace in each decoded key and value is trimmed. Internal ordinary spaces are preserved. CR, LF, HTAB, C0 controls, DEL, and C1 controls that remain inside an atom after trimming are invalid.
+Leading and trailing whitespace in positional atoms is trimmed. Internal ordinary spaces are preserved. CR, LF, HTAB, C0 controls, DEL, and C1 controls remaining inside an atom after trimming are invalid.
 
-Only three escape sequences exist:
+Only three positional-cell escapes exist:
 
 ```text
 \|  → literal |
@@ -96,104 +103,74 @@ Only three escape sequences exist:
 \\  → literal \
 ```
 
-Unknown escapes and a trailing backslash are invalid. No character is silently dropped.
-
-Every other printable character is literal inside a cell, including:
-
-```text
-{ [ ] " : , / emoji and ordinary spaces
-```
-
-An opening `{` has no structural meaning after a cell has begun. Square brackets are structural only outside a cell. One or two unescaped vertical bars select the two- or three-atom form; a third is invalid. Every selected atom must remain non-empty after trimming. When multiline text or non-positional metadata is needed, the producer uses the embedding's JSON or other full-fidelity form.
-
-## Width Policy
-
-CML Core does not impose a visual row-width maximum. Width is a renderer and interaction-policy concern, not a property of the key-value matrix wire format.
-
-An embedding may enforce a documented host limit. The `pi-telegram` parser does not add an artificial per-row width cap because Telegram Bot API does not document one and existing top-level matrices already admit host-bounded action counts. Its bundled Generated Control Surface Skill owns UX policy: five columns are the proven default for short position-bearing labels, six to eight may be used only when labels remain compact and readable, and wider surfaces should normally be regrouped.
+Every other printable character is literal inside a positional cell, including commas, colons, quotes, square brackets, emoji, and ordinary spaces. A comma inside `{label|prompt}` is data; a comma after the closing `}` is an optional element separator.
 
-## Parsing Contract
+## Deterministic Parsing
 
 A conforming parser:
 
-1. Consumes Unicode text without executing, interpolating, or evaluating it.
-2. Parses exactly one `payload` and rejects trailing non-whitespace input.
-3. Rejects empty atoms, empty matrices, empty rows, and nesting deeper than one row inside the top-level matrix.
-4. Rejects missing, extra, crossed, or mismatched delimiters.
-5. Accepts at most two unescaped vertical bars in a cell and rejects a third.
-6. Decodes only `\|`, `\}`, and `\\`; unknown or trailing escapes fail.
-7. Trims atom boundaries, then rejects empty values and remaining control characters.
-8. Returns no partial rows or cells after any failure.
-9. Runs in linear time over a host-bounded payload and does not recurse beyond the fixed grammar depth.
+1. Attempts strict JSON first for sources beginning with `{` or `[`. Successful JSON is validated only against the existing button matrix schema and never reinterpreted.
+2. If strict JSON parsing fails, parses the original source with the adaptive grammar.
+3. Tries one complete strict JSON object at each cell boundary before positional interpretation.
+4. Accepts at most one optional comma between completed matrix or row elements.
+5. Rejects leading, repeated, trailing, or property-level omitted commas.
+6. Rejects empty atoms, matrices, rows, and nesting deeper than one row.
+7. Decodes only `\|`, `\}`, and `\\` in positional cells.
+8. Consumes exactly one complete payload and rejects trailing content.
+9. Returns no partial rows or cells after any failure.
+10. Runs in linear time over a host-bounded payload with fixed grammar depth.
 
-Implementations may report diagnostics internally, but an invalid payload must not register or execute any action.
+Malformed JSON-looking input receives no generic recovery. It is accepted only if it independently forms a complete valid adaptive literal.
 
-## JSON Coexistence
+## Telegram Profile
 
-An embedding that already accepts JSON uses deterministic routing:
+For `telegram_button` and the exact `telegram_buttons` alias:
 
-1. Attempt strict JSON parsing first for payloads beginning with `{` or `[`.
-2. If JSON parsing succeeds, validate only against the embedding's JSON schema. A JSON shape failure must not fall back to CML.
-3. If JSON parsing fails, attempt CML from the original source.
-4. Accept CML only after complete grammar and embedding validation.
+- JSON `value` keeps its existing label/prompt fallback semantics.
+- Positional `{value}` is equivalent to JSON `{"value":"value"}`.
+- Positional `{label|prompt}` is equivalent to JSON `{"label":"label","prompt":"prompt"}`.
+- Positional `{label|prompt|selected_style}` is equivalent to the corresponding three-field JSON object.
+- 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.
 
-Valid JSON behavior therefore remains unchanged. A malformed JSON-looking source receives no tolerant recovery: it is accepted only when it independently forms a complete valid CML payload.
-
-## `pi-telegram` Profile
-
-For `telegram_button` and its exact `telegram_buttons` alias:
-
-- `Cell.key` becomes the visible button label.
-- `Cell.value` becomes the queued prompt.
-- A top-level cell becomes one full-width inline-keyboard row.
-- A nested row becomes one horizontal row.
-- `{value}` is equivalent to JSON `{"value":"value"}`.
-- `{label|prompt}` is equivalent to JSON `{"label":"label","prompt":"prompt"}`.
-- `{label|prompt|selected_style}` is equivalent to JSON `{"label":"label","prompt":"prompt","selected_style":"selected_style"}`.
-- The third atom is accepted only when the prompt atom is present and its exact value is `primary`, `success`, or `danger`.
-- JSON and double-quoted attributes remain the full-fidelity forms for Generative App script output, multiline values, and other metadata.
-- Invalid CML is stripped with its enclosing recognized action comment and registers no callbacks, matching existing fail-closed action behavior.
-
-Example embedding:
+Example:
 
 ```html
-<!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
+<!-- telegram_button [{⬆️ Up|/},[{⬅️|page-1}{➡️|page-3}],{"label":"📁 etc","prompt":"/etc"}] -->
 ```
 
-The enclosing HTML-comment transport still owns its own delimiter boundary; content containing the comment terminator cannot reach the CML parser and must use another supported delivery representation.
+The enclosing HTML-comment transport owns its own delimiter boundary. Content containing the comment terminator must use another supported representation.
 
-## Conformance Classes
+## Width Policy
+
+The grammar imposes no visual row-width maximum. Renderer and interaction policy own width. The bundled Generated Control Surface Skill defaults to at most five short position-bearing controls per row, permits six to eight only when labels remain compact, and treats eight as the phone-width UX maximum.
 
-A conformance suite covers properties rather than incident-specific strings.
+## Conformance
 
-### Accepted
+Accepted classes include:
 
-- Singular copied, key-value, and key-value-variant cells.
-- Top-level singleton rows.
-- Nested rows at widths one, five, and eight.
-- Mixed singleton and compact rows.
-- Unicode, punctuation, brackets, quotes, commas, colons, and internal spaces.
-- Trimmed atom boundaries.
-- Each defined escape sequence.
-- Structural whitespace between tokens.
-- Semantic equivalence with supported JSON cell forms.
+- Strict JSON objects and matrices.
+- Positional singleton, two-atom, and styled 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.
+- Unicode, defined escapes, structural whitespace, and rows at supported renderer widths.
+- Semantic equivalence across every progressive-compression step.
 
-### Rejected
+Rejected classes include:
 
-- Empty payload, matrix, row, key, or value.
-- Deeper nesting.
-- Missing or mismatched delimiters.
-- A third unescaped separator, an empty positional atom, or a profile-invalid variant.
-- Unknown or trailing escapes.
-- Internal control characters.
-- Commas between cells.
-- Trailing garbage.
-- JSON that parses but fails the JSON action schema.
+- Empty payloads, matrices, rows, labels, prompts, or style atoms.
+- Leading, repeated, or trailing 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.
+- Internal control characters and trailing garbage.
+- Valid JSON that fails the existing JSON action schema.
 
 Every rejected case proves zero callback registration.
 
 ## Versioning
 
-This document defines CML v2. The three-atom cell is the explicit syntactic discriminator from v1: v1 parsers reject it atomically, while v2 parsers cannot reinterpret a valid v1 cell. Compatible embeddings may impose documented host-level byte, cell-count, variant-enum, or width limits without changing the core grammar, but must preserve bounded-depth and fail-closed semantics.
-
-Future versions must not assign new meaning to input rejected by a security or ownership boundary without an explicit syntactic discriminator. Non-positional metadata and deeper structures require a revised standard rather than permissive recovery.
+This document defines CML v3. V3 extends the v2 positional grammar with strict JSON object cells, mixed representation, and optional element-boundary commas. 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.

package/docs/outbound.md

@@ -164,7 +164,7 @@ I can continue.
 
 Rules:
 
-- `telegram_button` accepts a JSON object, JSON matrix, [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted HTML-like attributes; `telegram_buttons` is an exact plural alias. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`. Shorthand, body, paired-comment, unquoted-attribute, and single-quoted-attribute forms are rejected.
+- `telegram_button` accepts a JSON object, adaptive JSON/CML matrix, positional [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted HTML-like attributes; `telegram_buttons` is an exact plural alias. Named JSON objects and positional cells may coexist in one matrix or row, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`. Shorthand, body, paired-comment, unquoted-attribute, and single-quoted-attribute forms are rejected.
 - A colon after either button marker is rejected so every payload form shares one unambiguous action marker.
 - Use `label` plus `prompt`, or the compact `value` key when both strings are identical. Explicit `label` or `prompt` takes precedence over its `value` fallback. 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 remains literal Markdown.

package/docs/public-api.md

@@ -66,7 +66,7 @@ This command surface is a mobile companion subset, not a raw terminal-command br
 - `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 either a JSON object or double-quoted attributes. Equivalent `text` or `value` supplies the spoken payload; explicit `text` takes precedence.
-- `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. One marker accepts a JSON object, JSON matrix, [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted attributes; `telegram_buttons` is an exact plural alias. Top-level matrix 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}`, or `{label|prompt|selected_style}`; the optional third atom requires a 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 inline buttons whose taps enqueue prompts. One marker accepts a JSON object, adaptive JSON/CML matrix, positional [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted attributes; `telegram_buttons` is an exact plural alias. Named JSON objects and positional cells may coexist in one matrix or row, and commas are optional only between completed elements. 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}`, or `{label|prompt|selected_style}`; the optional third atom requires a 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.
 
 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/docs/ui-style.md

@@ -62,6 +62,7 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | --- | --- | --- | --- |
 | `🟢` | Current/active/enabled `On` | Current option in vertical lists, active state rows, active `On` toggle | One strong current marker per option list. |
 | `🟡` | Active `Off` or elevated/filter state | Active `Off` toggle, Priority/Scoped active tab | Yellow means intentionally not-normal or off/default-caution, not error. |
+| `🔴` | Active destructive/deferred disposition | Active queue `Skip` selector | Red distinguishes a prompt that will be discarded at dispatch from reversible neutral or elevated state. |
 | `🟣` | Normal/default active tab | Normal priority tab, All/default scope tab, active page picker | Use for neutral active tabs. |
 | `⚫️` | Inactive placeholder | Inactive toggle values and inactive tabs | Keeps row width stable. |
 | `⬆️` | Navigate upward | `⬆️ Main menu`, `⬆️ Back` | Always first row in submenus. |
@@ -73,7 +74,7 @@ Queue reactions are shortcut controls for waiting turns. Preserve their semantic
 Queue item detail renders two independent selector rows:
 
 - `🟡 Priority` / `⚫️ Normal` or `⚫️ Priority` / `🟣 Normal` selects the lane.
-- `🟢 Keep` / `⚫️ Skip` or `⚫️ Keep` / `🟡 Skip` selects dispatch disposition.
+- `🟢 Keep` / `⚫️ Skip` or `⚫️ Keep` / `🔴 Skip` selects dispatch disposition.
 
 The menu may clear internal Skip but cannot remove a reaction created by the user through Telegram's Bot API.
 
@@ -167,22 +168,23 @@ Examples:
 - `⚫️ Priority` / `🟣 Normal`
 - `1` / `🟣 2` / `3`
 
-## Vertical Option Lists
+## Option Lists
 
-Vertical option lists choose one value from a potentially longer list, for example model selection, thinking level, voice reply mode, or time injection mode.
+Option lists choose one value from a fixed set, for example model selection, thinking level, voice reply mode, or time injection mode.
 
 Rules:
 
-- Put each option on its own row.
+- Put each option on its own row when labels are long, the set may grow, or scanning benefits from full width.
+- A fixed set of short, ordered peer values may use compact rows of up to three buttons.
+- Keep a semantically distinct value such as thinking `off` on its own full-width row before grouped intensity values.
 - Mark only the current value with `🟢`.
 - Leave non-current values without emoji.
 - Use lowercase labels when the option is a value.
 
 Examples:
 
-- `hidden`
-- `🟢 mirror`
-- `always`
+- Vertical: `hidden`, `🟢 mirror`, `always`.
+- Thinking: full-width `off`, then `minimal` / `low` / `🟢 medium`, then `high` / `xhigh` / `max`.
 
 ## Generated Prompt Buttons
 

package/lib/generative-app-worker.mjs

@@ -16,6 +16,7 @@ parentPort.on("message", (message) => {
   if (message?.type !== "abort") return;
   controller.abort();
   for (const child of runningChildren) child.kill();
+  parentPort.postMessage({ type: "abort-ack" });
 });
 
 function runBoundedProcess(input) {

package/lib/generative-apps.ts

@@ -490,7 +490,7 @@ async function executeGenerativeAppWorker(options: {
       if (settled || terminationError) return;
       terminationError = error;
       worker.postMessage({ type: "abort" });
-      const forcedTermination = setTimeout(terminateAndFinish, 50);
+      const forcedTermination = setTimeout(terminateAndFinish, 250);
       forcedTermination.unref?.();
     };
     const abort = (): void => {
@@ -507,9 +507,14 @@ async function executeGenerativeAppWorker(options: {
     }, options.methodTimeoutMs);
     timeout.unref?.();
     options.execution?.signal.addEventListener("abort", abort, { once: true });
-    worker.once("message", (message: { error?: string; ok?: boolean; result?: unknown }) => {
+    worker.on("message", (message: {
+      error?: string;
+      ok?: boolean;
+      result?: unknown;
+      type?: string;
+    }) => {
       if (terminationError) {
-        terminateAndFinish();
+        if (message?.type === "abort-ack") terminateAndFinish();
       } else if (message?.ok === true) {
         finish(undefined, message.result);
         void worker.terminate();
@@ -866,21 +871,14 @@ export function registerTelegramBindTool(
     label: "Telegram Bind",
     description:
       "Install, explicitly replace, or invoke one named method on a managed Generative App; successful output displays directly in the active Telegram turn unless display is false.",
-    parameters: Type.Union([
-      Type.Object({
-        app: Type.String(),
-        script: Type.String(),
-        replace: Type.Optional(Type.Boolean()),
-        display: Type.Optional(Type.Boolean()),
-        argument: Type.Optional(Type.Unknown()),
-      }, { additionalProperties: false }),
-      Type.Object({
-        app: Type.String(),
-        method: Type.String(),
-        display: Type.Optional(Type.Boolean()),
-        argument: Type.Optional(Type.Unknown()),
-      }, { additionalProperties: false }),
-    ]),
+    parameters: Type.Object({
+      app: Type.String(),
+      script: Type.Optional(Type.String()),
+      method: Type.Optional(Type.String()),
+      replace: Type.Optional(Type.Boolean()),
+      display: Type.Optional(Type.Boolean()),
+      argument: Type.Optional(Type.Unknown()),
+    }, { additionalProperties: false }),
     async execute(_toolCallId, params) {
       try {
         const result = await bindGenerativeApp({

package/lib/menu-queue.ts

@@ -192,7 +192,7 @@ function buildTelegramQueueItemSubmenuReplyMarkup(
           callback_data: `queue:skip-set:${chatId}:${replyToMessageId}:keep`,
         },
         {
-          text: isSkipped ? "🟡 Skip" : "⚫️ Skip",
+          text: isSkipped ? "🔴 Skip" : "⚫️ Skip",
           callback_data: `queue:skip-set:${chatId}:${replyToMessageId}:skip`,
         },
       ],

package/lib/menu-thinking.ts

@@ -128,13 +128,14 @@ export function buildThinkingMenuReplyMarkup(
   currentThinkingLevel: ThinkingLevel,
 ): TelegramReplyMarkup {
   const rows = [[{ text: "⬆️ Main menu", callback_data: "menu:back" }]];
+  const levelButtons = THINKING_LEVELS.map((level) => ({
+    text: level === currentThinkingLevel ? `🟢 ${level}` : level,
+    callback_data: `thinking:set:${level}`,
+  }));
   rows.push(
-    ...THINKING_LEVELS.map((level) => [
-      {
-        text: level === currentThinkingLevel ? `🟢 ${level}` : level,
-        callback_data: `thinking:set:${level}`,
-      },
-    ]),
+    levelButtons.slice(0, 1),
+    levelButtons.slice(1, 4),
+    levelButtons.slice(4, 7),
   );
   return { inline_keyboard: rows };
 }

package/lib/outbound-buttons.ts

@@ -183,21 +183,20 @@ export function planTelegramButtonReply(
       parseTopLevelTelegramComment(comment, candidate),
     );
     if (!command) return comment.raw;
-    const payloadRows = parseTelegramActionPayloadRows(comment, command) ?? [];
-    for (const payloadRow of payloadRows) {
-      const row = payloadRow.flatMap((payload) => {
-        const action = parseTelegramButtonAction(payload);
-        return action
-          ? [{
-              text: action.text,
-              callback_data: deps.registerAction({
-                ...action,
-                ...(deps.binding ? { binding: deps.binding } : {}),
-              }),
-            }]
-          : [];
-      });
-      if (row.length > 0) keyboard.push(row);
+    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 } : {}),
+        }),
+      })));
     }
     return "";
   });

package/lib/outbound-markup.ts

@@ -207,7 +207,7 @@ export function parseTelegramActionPayload(
 
 const TELEGRAM_COMPACT_ACTION_CONTROL_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
 
-function parseTelegramCompactActionPayloadRows(
+function parseTelegramAdaptiveActionPayloadRows(
   source: string,
 ): Record<string, unknown>[][] | undefined {
   let offset = 0;
@@ -219,13 +219,20 @@ function parseTelegramCompactActionPayloadRows(
   const skipWhitespace = (): void => {
     while (isStructuralWhitespace(source[offset])) offset += 1;
   };
+  const consumeOptionalSeparator = (): boolean => {
+    skipWhitespace();
+    if (source[offset] !== ",") return true;
+    offset += 1;
+    skipWhitespace();
+    return source[offset] !== "," && source[offset] !== "]";
+  };
   const normalizeAtom = (value: string): string | undefined => {
     const normalized = value.trim();
     return normalized && !TELEGRAM_COMPACT_ACTION_CONTROL_PATTERN.test(normalized)
       ? normalized
       : undefined;
   };
-  const parseCell = (): Record<string, unknown> | undefined => {
+  const parseCompactCell = (): Record<string, unknown> | undefined => {
     if (source[offset] !== "{") return undefined;
     offset += 1;
     const atomSources: string[][] = [[]];
@@ -267,6 +274,54 @@ function parseTelegramCompactActionPayloadRows(
     }
     return undefined;
   };
+  const parseJsonObjectCell = (): Record<string, unknown> | undefined => {
+    if (source[offset] !== "{") return undefined;
+    const start = offset;
+    const stack: string[] = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < source.length; index += 1) {
+      const character = source[index]!;
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (character === "\\") escaped = true;
+        else if (character === '"') inString = false;
+        continue;
+      }
+      if (character === '"') {
+        inString = true;
+        continue;
+      }
+      if (character === "{" || character === "[") {
+        stack.push(character);
+        continue;
+      }
+      if (character !== "}" && character !== "]") continue;
+      const opening = stack.pop();
+      if (
+        (character === "}" && opening !== "{") ||
+        (character === "]" && opening !== "[")
+      ) return undefined;
+      if (stack.length > 0) continue;
+      const candidate = source.slice(start, index + 1);
+      try {
+        const value: unknown = JSON.parse(candidate);
+        if (!isTelegramActionPayload(value)) return undefined;
+        offset = index + 1;
+        return value;
+      } catch {
+        return undefined;
+      }
+    }
+    return undefined;
+  };
+  const parseCell = (): Record<string, unknown> | undefined => {
+    const start = offset;
+    const jsonCell = parseJsonObjectCell();
+    if (jsonCell) return jsonCell;
+    offset = start;
+    return parseCompactCell();
+  };
   const parseRow = (): Record<string, unknown>[] | undefined => {
     if (source[offset] !== "[") return undefined;
     offset += 1;
@@ -281,6 +336,7 @@ function parseTelegramCompactActionPayloadRows(
       const cell = parseCell();
       if (!cell) return undefined;
       row.push(cell);
+      if (!consumeOptionalSeparator()) return undefined;
     }
     return undefined;
   };
@@ -299,15 +355,14 @@ function parseTelegramCompactActionPayloadRows(
         const cell = parseCell();
         if (!cell) return undefined;
         rows.push([cell]);
-        continue;
-      }
-      if (character === "[") {
+      } else if (character === "[") {
         const row = parseRow();
         if (!row) return undefined;
         rows.push(row);
-        continue;
+      } else {
+        return undefined;
       }
-      return undefined;
+      if (!consumeOptionalSeparator()) return undefined;
     }
     return undefined;
   };
@@ -353,7 +408,7 @@ export function parseTelegramActionPayloadRows(
       }
       return rows;
     } catch {
-      return parseTelegramCompactActionPayloadRows(payload.source);
+      return parseTelegramAdaptiveActionPayloadRows(payload.source);
     }
   }
   if (payload.hasBody) return undefined;

package/lib/updates.ts

@@ -886,6 +886,19 @@ export type TelegramMessageOwnershipRecorder = (
   input: TelegramMessageOwnershipRecorderInput,
 ) => void;
 
+interface TelegramUnauthorizedReplyOptions {
+  parseMode?: "HTML";
+  target?: { chatId: number; threadId?: number };
+}
+
+const TELEGRAM_UNAUTHORIZED_DENIAL_COPY = "Access denied.";
+
+function formatTelegramUnauthorizedDenial(format: "plain" | "html"): string {
+  return format === "html"
+    ? `🚫 <b>${TELEGRAM_UNAUTHORIZED_DENIAL_COPY}</b>`
+    : `🚫 ${TELEGRAM_UNAUTHORIZED_DENIAL_COPY}`;
+}
+
 export interface TelegramUpdateRuntimeDeps<
   TContext = unknown,
   TReactionUpdate extends TelegramMessageReactionUpdated =
@@ -927,7 +940,11 @@ export interface TelegramUpdateRuntimeDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
-  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
+  answerGuestQuery: (
+    guestQueryId: string,
+    text?: string,
+    options?: Pick<TelegramUnauthorizedReplyOptions, "parseMode">,
+  ) => Promise<void>;
   handleAuthorizedTelegramCallbackQuery: (
     query: TCallbackQuery,
     ctx: TContext,
@@ -936,7 +953,7 @@ export interface TelegramUpdateRuntimeDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: { chatId: number; threadId?: number } },
+    options?: TelegramUnauthorizedReplyOptions,
   ) => Promise<number | undefined>;
   handleAuthorizedTelegramMessage: (
     message: TMessage,
@@ -996,7 +1013,11 @@ export interface TelegramUpdateRuntimeControllerDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
-  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
+  answerGuestQuery: (
+    guestQueryId: string,
+    text?: string,
+    options?: Pick<TelegramUnauthorizedReplyOptions, "parseMode">,
+  ) => Promise<void>;
   handleAuthorizedTelegramCallbackQuery: (
     query: TCallbackQuery,
     ctx: TContext,
@@ -1005,7 +1026,7 @@ export interface TelegramUpdateRuntimeControllerDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: { chatId: number; threadId?: number } },
+    options?: TelegramUnauthorizedReplyOptions,
   ) => Promise<number | undefined>;
   handleAuthorizedTelegramMessage: (
     message: TMessage,
@@ -1449,7 +1470,7 @@ export async function executeTelegramUpdatePlan<
           assertExecutionCurrent();
           await deps.answerCallbackQuery(
             callbackQueryId,
-            "This bot is not authorized for your account.",
+            formatTelegramUnauthorizedDenial("plain"),
           );
         }
         return;
@@ -1464,7 +1485,8 @@ export async function executeTelegramUpdatePlan<
         assertExecutionCurrent();
         await deps.answerGuestQuery(
           plan.guestMessage.guest_query_id,
-          "🚫 Access denied.",
+          formatTelegramUnauthorizedDenial("html"),
+          { parseMode: "HTML" },
         );
         return;
       }
@@ -1584,8 +1606,8 @@ export async function executeTelegramUpdatePlan<
         await deps.sendTextReply(
           replyTarget.chatId,
           replyTarget.messageId,
-          "This bot is not authorized for your account.",
-          { target: replyTarget },
+          formatTelegramUnauthorizedDenial("html"),
+          { parseMode: "HTML", target: replyTarget },
         );
       }
       return;

package/package.json

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

package/skills/generated-control-surface/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generated-control-surface
-description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request, while omitting decorative UI and preserving domain ownership; fixed transport menus and callbacks remain with their runtime owners.
+description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request; route reusable deterministic loops toward Generative Apps, omit decorative UI, and preserve domain ownership while fixed transport menus and callbacks remain with their runtime owners.
 ---
 
 # Generated Control Surface
@@ -25,7 +25,9 @@ The primitive belongs to the Surface plane: it projects State, exposes Agency ca
 
 Use this Skill only to synthesize a state-derived prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, fixed frontend, runtime-owned control, or installed Generative App stays with that subsystem and does not route here merely because it contains buttons.
 
-When a generated surface reveals a repeated stable interaction with bounded state and deterministic transitions, consider graduating it to the complementary `generative-apps` Skill. Keep one-off, interpretive, changing, and context-heavy interaction here; compile only when bypassing repeated model mediation has concrete latency, token, cost, reliability, or UX value.
+This Skill and `generative-apps` share one logical button-matrix and `label + prompt` interaction model while retaining different execution owners. On Telegram, the bridge runtime owns the full JSON/CML action notation: this Skill emits an ephemeral surface from current context, while a Generative App returns reusable views through its script ABI. Shared rendering does not justify a third button Skill or move transport grammar into either interaction Skill.
+
+When a generated surface reveals repeated stable interaction with bounded state and deterministic transitions, load the complementary `generative-apps` Skill and consider compiling that loop. A Generative App may retain ordinary model-mediated prompt buttons beside deterministic bound methods, so only the stable actions need bypass inference. Conversely, keep one-off, interpretive, changing, and context-heavy interaction here when a reusable script would add no concrete latency, token, cost, reliability, or UX value.
 
 On Telegram turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. Load and apply it when a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
 
@@ -122,7 +124,7 @@ Re-check mutable targets immediately before execution. Access denial never autho
 
 ## Prompt Buttons
 
-Use the transport's canonical prompt-button syntax. For pi-telegram, one top-level `telegram_button` comment accepts one JSON object, double-quoted attributes, a JSON matrix, or Compact Matrix Literal (CML). CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML whenever the model authors the control and it can express the required surface; fall back to expanded JSON only for multiline prompts, non-positional metadata, or a concrete CML parse/render failure, never merely from implementation habit. Deterministic Generative App scripts may return ordinary JSON because their source payload does not consume model-output tokens; author and operate those adapters through the `generative-apps` Skill rather than growing a parallel app workflow here. A top-level cell becomes one full-width row, while a nested row groups one or more controls horizontally without a parser-level width cap. Prefer one layout comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format.
+Use the transport's canonical prompt-button syntax. For pi-telegram, one top-level `telegram_button` comment accepts one JSON object, double-quoted attributes, an adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML whenever the model authors the control and it can express the required surface; fall back to expanded JSON only for multiline prompts, non-positional metadata, or a concrete CML parse/render failure, never merely from implementation habit. Deterministic Generative App scripts may return ordinary JSON because their source payload does not consume model-output tokens; author and operate those adapters through the `generative-apps` Skill rather than growing a parallel app workflow here. A top-level cell becomes one full-width row, while a nested row groups one or more controls horizontally without a parser-level width cap. Prefer one layout comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format.
 
 ### Semantic Row Composition
 

package/skills/generative-apps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generative-apps
-description: Design, author, review, install, replace, invoke, or debug reusable Generative Apps that combine generated button interfaces, deterministic bound methods, and optional model-mediated prompts. Use for standalone applications and bounded view/controller adapters rendered through pi-telegram.
+description: Design, author, review, install, replace, invoke, or debug reusable Generative Apps that combine generated button interfaces, deterministic bound methods, and optional model-mediated prompts. Use for standalone applications and bounded view/controller adapters rendered through pi-telegram; prefer Generated Control Surface when no reusable deterministic program is earned.
 ---
 
 # Generative Apps
@@ -29,6 +29,10 @@ 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.
+
+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.
+
 The `generated` / `generative` distinction is intentional. Do not rename `generated-control-surface` to a competing generative term.
 
 ## Ownership

package/skills/telegram-bridge/SKILL.md

@@ -46,7 +46,9 @@ Use `telegram_attach` outside Telegram turns only when the user explicitly reque
 
 ## Assistant-Authored Actions
 
-On Telegram turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not wait for an explicit button request, and accept zero controls when its admission rules reject decorative or low-value UI.
+Before compiling assistant-authored controls, inspect already-loaded capability guidance for an advertised maintained Generative App or view/controller adapter. When that owner-provided view exists and the current intent concerns repeated interaction, load and follow the bundled `generative-apps` Skill and prefer binding or invoking the existing app over synthesizing one-shot prompt buttons. This is a routing breadcrumb, not permission for the bridge to discover capability-specific apps, own their state, or hard-code their identities.
+
+Otherwise, on Telegram turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not wait for an explicit button request, and accept zero controls when its admission rules reject decorative or low-value UI.
 
 `telegram_button` and `telegram_voice` are hidden top-level HTML comments, not tools. Emit them at column zero, outside lists, quotes, code blocks, and indentation.
 
@@ -60,7 +62,7 @@ Button forms:
 <!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
 ```
 
-- `telegram_button` accepts one JSON object, a JSON matrix, Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML for model-authored controls whenever it can express the required surface; use expanded JSON only for multiline prompts, non-positional metadata, or a concrete parse/render failure fallback, never merely from implementation habit. Deterministic Generative App scripts may use ordinary JSON because their output does not spend model tokens. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`.
+- `telegram_button` accepts one JSON object, an adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML for model-authored controls whenever it can express the required surface; use expanded JSON only for multiline prompts, non-positional metadata, or a concrete parse/render failure fallback, never merely from implementation habit. Deterministic Generative App scripts may use ordinary JSON because their output does not spend model tokens. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`.
 - Use `label` plus a self-contained `prompt`, or non-empty `value` when both are identical.
 - Optional `selected_style` is `primary` (default), `success`, or `danger`; style never suppresses prompt admission.
 - If button comments form the whole reply, the bridge supplies the standard choice heading.