@llblab/pi-telegram 0.34.1 → 0.35.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.35.0: Compact Matrix Literal
+
+- `Compact Wire Format`: Adds portable Compact Matrix Literal alongside JSON and attributes: `{value}` copies label to prompt, `{label|prompt}` separates them, top-level cells remain full-width, nested rows preserve horizontal grouping, and atom boundaries trim automatically.
+- `Literal Fidelity`: Preserves non-structural printable Unicode—including brackets, quotes, commas, colons, paths, and spaces—while decoding only `\|`, `\}`, and `\\`; unknown/trailing escapes, empty values, repeated separators, controls, malformed delimiters, empty rows, and deeper nesting fail closed before callback registration.
+- `Renderer-Owned Width`: Removes the artificial parser-level row-width cap because Telegram documents none, while bundled Skills keep five columns as the proven default, admit six through eight only for very short position-bearing labels, and direct wider surfaces toward regrouping. A dedicated portable standard owns grammar, JSON-first routing, conformance, and versioning.
+
 ## 0.34.1: Compact Stateful Control Surfaces
 
 - `Prompt Compression`: Teaches Generated Control Surface to encode the smallest sufficient action delta—such as a coordinate, symbol, identifier, or short verb—when visible conversation establishes unambiguous state, while retaining stable identity when delivery or routing could separate action from context.

package/README.md

@@ -192,7 +192,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, or compact double-quoted attributes; `telegram_buttons` is a plural alias. In a matrix, top-level objects become full-width rows while nested arrays group one to five buttons horizontally. Prefer one array 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, 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}` or `{label|prompt}`, 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,6 +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
 - [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
 - [multi-instance-bus.md](./multi-instance-bus.md) — Optional multi-instance Telegram bus architecture: profile-scoped transport, leader/follower routing, thread targets, instance slots, manual follower registration, and recovery semantics

package/docs/architecture.md

@@ -327,7 +327,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, or double-quoted attributes; `telegram_buttons` aliases the same parser. Each top-level matrix object creates one full-width row, while a nested array groups one to five buttons horizontally; every callback enqueues its configured prompt text as a normal Telegram prompt turn.
+- `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).
 
 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

@@ -0,0 +1,189 @@
+# Compact Matrix Literal
+
+> Status: Portable v1 standard implemented by the `pi-telegram` 0.35.0 release candidate.
+
+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.
+
+CML is transport-neutral. An embedding maps each decoded cell's `key` and `value` to its own domain. The `pi-telegram` profile maps `key` to button label and `value` to button prompt.
+
+## Goals
+
+- 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.
+
+## Non-Goals
+
+- Replacing JSON for arbitrary objects, metadata, styles, 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.
+
+## Data Model
+
+A decoded payload is an ordered non-empty list of non-empty rows:
+
+```text
+Cell = { key: string, value: string }
+Rows = Cell[][]
+```
+
+A top-level cell normalizes to a singleton row. A nested row preserves its compact grouping.
+
+A cell with one atom copies its key into its value:
+
+```text
+{7} == { key: "7", value: "7" }
+```
+
+A cell with two atoms separates key and value with one unescaped vertical bar:
+
+```text
+{🟥|2,5} == { key: "🟥", value: "2,5" }
+```
+
+## Grammar
+
+The normative structural grammar is:
+
+```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-unit+
+atom-unit := ordinary | "\\|" | "\\}" | "\\\\"
+ws       := *(SP | HTAB | CR | LF)
+```
+
+`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.
+
+Examples:
+
+```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\}}
+```
+
+These normalize respectively to one copied singleton cell, one key-value singleton cell, a mixed singleton/compact matrix, one eight-cell row, and `{ key: "A | B", value: "C:\\Games}" }`.
+
+## 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.
+
+Only three escape sequences exist:
+
+```text
+\|  → literal |
+\}  → literal }
+\\  → 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. A second unescaped vertical bar is invalid. When multiline text or additional 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.
+
+## Parsing Contract
+
+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. Rejects a second unescaped vertical bar in a cell.
+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.
+
+Implementations may report diagnostics internally, but an invalid payload must not register or execute any action.
+
+## JSON Coexistence
+
+An embedding that already accepts JSON uses deterministic routing:
+
+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.
+
+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"}`.
+- JSON and double-quoted attributes remain the full-fidelity forms.
+- `selected_style` and future metadata are not represented by CML v1.
+- Invalid CML is stripped with its enclosing recognized action comment and registers no callbacks, matching existing fail-closed action behavior.
+
+Example embedding:
+
+```html
+<!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/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.
+
+## Conformance Classes
+
+A conformance suite covers properties rather than incident-specific strings.
+
+### Accepted
+
+- Singular copied and key-value 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.
+
+### Rejected
+
+- Empty payload, matrix, row, key, or value.
+- Deeper nesting.
+- Missing or mismatched delimiters.
+- A second unescaped separator.
+- Unknown or trailing escapes.
+- Internal control characters.
+- Commas between cells.
+- Trailing garbage.
+- JSON that parses but fails the JSON action schema.
+
+Every rejected case proves zero callback registration.
+
+## Versioning
+
+This document defines CML v1. Compatible embeddings may impose documented host-level byte, cell-count, 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 version discriminator. Metadata fields, styles, and deeper structures require a revised standard rather than permissive v1 parsing.

package/docs/outbound.md

@@ -158,15 +158,17 @@ I can continue.
 <!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
 
 <!-- telegram_buttons [[{"value":"Approve"},{"value":"Reject"}]] -->
+
+<!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
 ```
 
 Rules:
 
-- `telegram_button` accepts a JSON object, JSON matrix, or double-quoted HTML-like attributes; `telegram_buttons` is an exact plural alias. Shorthand, body, paired-comment, unquoted-attribute, and single-quoted-attribute forms are rejected.
+- `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}` or `{label|prompt}`, trims both atoms, 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.
-- Prefer one JSON array comment for multiple buttons. Each top-level object becomes one full-width inline-keyboard row in source order; a nested array groups one to five button objects into one horizontal row. Empty rows, rows above five buttons, and deeper nesting are rejected. 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 second unescaped CML separator, and deeper nesting are rejected atomically. 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.
 - 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.

package/docs/public-api.md

@@ -65,7 +65,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, and profile-specific debugging guidance. The regular prompt routes applicable turns to that Skill. `telegram_attach` 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, or double-quoted attributes; `telegram_buttons` is an exact plural alias. Top-level matrix objects become full-width rows, while nested arrays group one to five buttons horizontally. Prefer one array comment for multiple buttons. Use `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, 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}` or `{label|prompt}`, 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/lib/outbound-markup.ts

@@ -205,6 +205,122 @@ export function parseTelegramActionPayload(
   return parseCanonicalTelegramActionAttributes(payload.source);
 }
 
+const TELEGRAM_COMPACT_ACTION_CONTROL_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
+
+function parseTelegramCompactActionPayloadRows(
+  source: string,
+): Record<string, unknown>[][] | undefined {
+  let offset = 0;
+  const isStructuralWhitespace = (character: string | undefined): boolean =>
+    character === " " ||
+    character === "\t" ||
+    character === "\r" ||
+    character === "\n";
+  const skipWhitespace = (): void => {
+    while (isStructuralWhitespace(source[offset])) offset += 1;
+  };
+  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 => {
+    if (source[offset] !== "{") return undefined;
+    offset += 1;
+    const keySource: string[] = [];
+    const valueSource: string[] = [];
+    let hasSeparator = false;
+    while (offset < source.length) {
+      const character = source[offset]!;
+      if (character === "\\") {
+        const escaped = source[offset + 1];
+        if (escaped !== "|" && escaped !== "}" && escaped !== "\\") {
+          return undefined;
+        }
+        if (hasSeparator) valueSource.push(escaped);
+        else keySource.push(escaped);
+        offset += 2;
+        continue;
+      }
+      if (character === "|") {
+        if (hasSeparator) return undefined;
+        hasSeparator = true;
+        offset += 1;
+        continue;
+      }
+      if (character === "}") {
+        offset += 1;
+        const key = normalizeAtom(keySource.join(""));
+        if (!key) return undefined;
+        if (!hasSeparator) return { value: key };
+        const value = normalizeAtom(valueSource.join(""));
+        return value ? { label: key, prompt: value } : undefined;
+      }
+      if (hasSeparator) valueSource.push(character);
+      else keySource.push(character);
+      offset += 1;
+    }
+    return undefined;
+  };
+  const parseRow = (): Record<string, unknown>[] | undefined => {
+    if (source[offset] !== "[") return undefined;
+    offset += 1;
+    const row: Record<string, unknown>[] = [];
+    while (offset < source.length) {
+      skipWhitespace();
+      if (source[offset] === "]") {
+        offset += 1;
+        return row.length > 0 ? row : undefined;
+      }
+      if (source[offset] !== "{") return undefined;
+      const cell = parseCell();
+      if (!cell) return undefined;
+      row.push(cell);
+    }
+    return undefined;
+  };
+  const parseMatrix = (): Record<string, unknown>[][] | undefined => {
+    if (source[offset] !== "[") return undefined;
+    offset += 1;
+    const rows: Record<string, unknown>[][] = [];
+    while (offset < source.length) {
+      skipWhitespace();
+      const character = source[offset];
+      if (character === "]") {
+        offset += 1;
+        return rows.length > 0 ? rows : undefined;
+      }
+      if (character === "{") {
+        const cell = parseCell();
+        if (!cell) return undefined;
+        rows.push([cell]);
+        continue;
+      }
+      if (character === "[") {
+        const row = parseRow();
+        if (!row) return undefined;
+        rows.push(row);
+        continue;
+      }
+      return undefined;
+    }
+    return undefined;
+  };
+
+  skipWhitespace();
+  let rows: Record<string, unknown>[][] | undefined;
+  if (source[offset] === "{") {
+    const cell = parseCell();
+    rows = cell ? [[cell]] : undefined;
+  } else {
+    rows = parseMatrix();
+  }
+  if (!rows) return undefined;
+  skipWhitespace();
+  return offset === source.length ? rows : undefined;
+}
+
 export function parseTelegramActionPayloadRows(
   comment: TelegramTopLevelHtmlComment,
   command: string,
@@ -225,7 +341,6 @@ export function parseTelegramActionPayloadRows(
         if (
           !Array.isArray(entry) ||
           entry.length === 0 ||
-          entry.length > 5 ||
           !entry.every(isTelegramActionPayload)
         ) {
           return undefined;
@@ -234,7 +349,7 @@ export function parseTelegramActionPayloadRows(
       }
       return rows;
     } catch {
-      return undefined;
+      return parseTelegramCompactActionPayloadRows(payload.source);
     }
   }
   if (payload.hasBody) return undefined;

package/package.json

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

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

@@ -118,9 +118,9 @@ 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, or a JSON matrix. A top-level object becomes one full-width row; a nested array groups one to five objects into one compact horizontal row. Prefer one array comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format. Use compact rows only when the controls form one coherent peer group such as Previous/Next, approval alternatives, or view modes; keep ordinary actions full-width.
+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}` or `{label|prompt}`, trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`; use JSON for multiline prompts, styles, or metadata. 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 matrix comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format. Use compact rows only when the controls form one coherent peer group such as Previous/Next, approval alternatives, or view modes; keep ordinary actions full-width.
 
-Treat the five-wide matrix as an interaction primitive when spatial position carries meaning and acting through the surface communicates better than prose. Five-wide rows are proven usable with short, distinct labels; use fewer columns or full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose. Preserve the ordinary admission test: proactively offer an interactive surface even when the user did not request buttons when it materially reduces effort or demonstrates an available capability, but do not manufacture decorative interaction.
+Treat a matrix as an interaction primitive when spatial position carries meaning and acting through the surface communicates better than prose. Five columns are proven usable with short, distinct labels and remain the default maximum. Six through eight columns may be used only for very short position-bearing labels whose grouping materially improves the interaction; regroup wider surfaces and use fewer columns or full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose. Preserve the ordinary admission test: proactively offer an interactive surface even when the user did not request buttons when it materially reduces effort or demonstrates an available capability, but do not manufacture decorative interaction.
 
 ### Interaction State And Prompt Compression
 
@@ -132,7 +132,7 @@ Treat the five-wide matrix as an interaction primitive when spatial position car
 
 ```html
 <!-- telegram_button {"label":"🔍 Inspect run","prompt":"Inspect Run run:example read-only, summarize its current status and latest material evidence, then regenerate relevant supervision controls."} -->
-<!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
+<!-- telegram_button [{⬆️ Up|/}[{⬅️ Previous}{➡️ Next}]{📁 etc|/etc}] -->
 ```
 
 Button prompts must:

package/skills/telegram-bridge/SKILL.md

@@ -57,9 +57,10 @@ Button forms:
 <!-- telegram_button value="Continue" -->
 <!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
 <!-- telegram_buttons [[{"value":"Approve"},{"value":"Reject"}]] -->
+<!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
 ```
 
-- `telegram_button` accepts one JSON object, a JSON matrix, or double-quoted attributes; `telegram_buttons` is an exact plural alias. In a matrix, each top-level object becomes a full-width row and each nested array groups one to five buttons into one horizontal row. Prefer one array comment for multiple buttons. Keep the complete action in one top-level comment and encode JSON line breaks as `\n`.
+- `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}` or `{label|prompt}`, trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. 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.