@llblab/pi-telegram 0.34.1 → 0.35.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.35.1: Semantic Ragged Control Layouts
+
+- `Row Composition`: Teaches Generated Control Surface to model Telegram controls as an ordered ragged sequence of independently sized semantic rows rather than filling a rectangular matrix: compact rows hold genuine peers, singleton rows isolate independent actions, and symmetry is admitted only when equal relationships or real spatial topology provide evidence for it.
+- `Layout Catalog`: Adds an adaptable shape vocabulary for singleton, binary peer, asymmetric staged, navigation-plus-collection, repeated text-pair, and true rectangular surfaces; agents infer task relationships first and must not force work into a preset shape.
+- `Layout Hierarchy`: Limits word-, phrase-, and icon-plus-text controls to two columns and moves additional choices into more semantic rows; denser rows remain reserved for short position-bearing glyphs or codes. Row widths vary intentionally, preserve structural reading order, forbid uniformity padding, and use rectangular grids only when spatial topology carries real meaning.
+
+## 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.
 
@@ -362,7 +362,7 @@ Complete intermediate assistant text blocks from Telegram-originated activity ar
 
 `assistant.activity` is an independent bridge-owned projection over normalized Activity events. Each process reloads the shared file-backed setting at `agent-start` before activity admission, so multi-instance mode cannot continue projecting a stale broader process-local selection. Omitted values resolve to `verbose`, while invalid values fail closed to `quiet`; `thinking` and `tools` select one technical class, while `verbose` enables both. Provider-exposed thinking uses persistent ordinary HTML containing only a standard expandable blockquote with a bounded redacted latest-text window and inline Markdown rendered as Telegram HTML. Completed executed tools use native Rich Messages: each closed `<Tool>: <status>` root details node renders snake-case names as title words while preserving an uppercase two- or three-letter repeated prefix per word, then the native disclosure chevron reveals an open-by-default `arguments` child plus closed retained `update N` and `result`/`error` child details with lowercase monospaced, marker-free summaries and JSON pre blocks; known-safe Rich rejections fall back to the previous HTML disclosure. The projection captures the exact target and transport stamp at activity admission, serializes updates, preserves tool-start order, closes coalescing across assistant/thinking boundaries, bounds retained text/update memory plus edit frames and message/tool size, disables previews and HTTP(S) auto-link recognition inside technical evidence, and never replays a possibly committed send. Session generations own independent queues, so replacement drops queued old work without waiting on an old call. Both proactive prose and active-turn final delivery wait for the admitted activity queue inside their extension-owned delivery tasks, preserving technical-before-semantic ordering without delaying Pi lifecycle completion. Settlement, replacement, disconnect, failure, or stale authority clears only local ownership; already-sent activity messages remain in chat.
 
-Telegram prompt guidance is context- and authority-aware. The package and source-checkout extension both contribute `telegram-bridge` plus the optional `generated-control-surface` Skill through Pi resource discovery. The latter treats `interface = f(state, capabilities, intent)` as a renderer-neutral primitive, compiling transient evidence-backed controls over domain-owned workflows, systems, navigation, supervision, and decisions without creating parallel application state. Repeated controls carry the smallest sufficient action delta when visible conversation is unambiguous; larger or error-prone state moves to a deterministic task-owned Markdown artifact, correctness-sensitive transitions move to a small domain-owned transition implementation, and repeated clicks are adjudicated against current state rather than stale button appearance. Its filesystem adapter reserves the first full-width row for parent traversal outside root, places available Previous/Next controls together in one compact row immediately afterward, orders visible directories, hidden directories, visible files, and hidden files alphabetically within each category before fixed ten-entry pagination, renders path/range metadata as stacked status-style key-value rows instead of middle-dot prose, emits the complete Telegram control set through one JSON-matrix action, suppresses duplicate plain/monospaced listings and default Refresh unless user preference overrides presentation, and retains an ordinary numbered fallback when buttons are unavailable. Only an exact direct owner or live registered follower exposes the two pi-telegram delivery tools, their active-tool metadata, and the compact routing suffix. Disconnect or authority loss removes those tool surfaces for subsequent requests without touching foreign tools; reconnect/recovery restores only the pi-telegram subset that was active before suspension, including across same-process reload. Telegram-originated turns route to the stable Skill contract and retain dynamic blocks such as `[voice] delivery: automatic voice`; the Skill and public documentation own syntax, target routing, Threaded Mode behavior, and diagnostics.
+Telegram prompt guidance is context- and authority-aware. The package and source-checkout extension both contribute `telegram-bridge` plus the optional `generated-control-surface` Skill through Pi resource discovery. The latter treats `interface = f(state, capabilities, intent)` as a renderer-neutral primitive, compiling transient evidence-backed controls over domain-owned workflows, systems, navigation, supervision, and decisions without creating parallel application state. It composes an ordered ragged sequence of independently sized semantic rows rather than filling a rectangular grid: compact rows contain genuine peers, singleton rows isolate structurally independent actions, and rectangular layouts remain reserved for genuinely spatial state. Text-bearing controls use at most two columns and flow into additional rows, while denser rows are reserved for short position-bearing glyphs or codes. Symmetry is treated as an evidence claim about equal relationships or real spatial topology; an abstract layout catalog supplies adaptable singleton, peer, staged, navigational, repeated-pair, and rectangular shapes without forcing tasks into preset grids. Repeated controls carry the smallest sufficient action delta when visible conversation is unambiguous; larger or error-prone state moves to a deterministic task-owned Markdown artifact, correctness-sensitive transitions move to a small domain-owned transition implementation, and repeated clicks are adjudicated against current state rather than stale button appearance. Its filesystem adapter reserves the first full-width row for parent traversal outside root, places available Previous/Next controls together in one compact row immediately afterward, orders visible directories, hidden directories, visible files, and hidden files alphabetically within each category before fixed ten-entry pagination, renders path/range metadata as stacked status-style key-value rows instead of middle-dot prose, emits the complete Telegram control set through one JSON-matrix action, suppresses duplicate plain/monospaced listings and default Refresh unless user preference overrides presentation, and retains an ordinary numbered fallback when buttons are unavailable. Only an exact direct owner or live registered follower exposes the two pi-telegram delivery tools, their active-tool metadata, and the compact routing suffix. Disconnect or authority loss removes those tool surfaces for subsequent requests without touching foreign tools; reconnect/recovery restores only the pi-telegram subset that was active before suspension, including across same-process reload. Telegram-originated turns route to the stable Skill contract and retain dynamic blocks such as `[voice] delivery: automatic voice`; the Skill and public documentation own syntax, target routing, Threaded Mode behavior, and diagnostics.
 
 ## In-Flight Model Switching
 

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.1",
   "private": false,
   "publishConfig": {
     "access": "public"

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

@@ -118,9 +118,36 @@ 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 layout comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format.
 
-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.
+### Semantic Row Composition
+
+Model the control surface as an ordered ragged sequence of independently sized rows, not as a rectangular matrix to fill. Rectangular grids are one specialization for genuinely spatial or coordinate-bearing state; most interfaces should vary row width according to hierarchy, grouping, label pressure, and action priority.
+
+- Put controls in one compact row only when they are genuine peers that answer the same local question or form one coherent toolbar/navigation group.
+- Use a singleton full-width row for a structurally independent, pinned, primary, summary, or high-consequence action when separation improves comprehension.
+- Vary row widths intentionally—for example `1 → 2 → 4 → 1 → 2`—and never pad a row with empty, duplicate, or no-op controls merely to produce uniform dimensions.
+- Preserve reading order across rows: orientation and structural navigation first, primary content or choices next, secondary controls afterward, and destructive actions visibly separated when present.
+- Use at most two columns when buttons carry words, phrases, icon-plus-text labels, or other text that must be read; move additional peer choices into more semantic rows rather than compressing four or more textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
+
+Treat symmetry as an evidence claim about the task. Equal rectangular rows imply equal relationships and stable spatial correspondence; do not make that claim merely because the renderer supports a grid. Infer the task's independent, peer, ordered, hierarchical, and spatial relationships first, then let those relationships determine row boundaries and widths. A non-spatial task should be ragged by default, and its asymmetry should remain visible when that best communicates hierarchy or action weight.
+
+### Layout Catalog
+
+Use this catalog as a shape vocabulary, not a fixed menu of demos:
+
+- `1`: One independent full-width action, destination, summary drill-down, or consequence boundary.
+- `2`: One binary or tightly coupled peer decision; neither control is visually subordinated.
+- `1 → 2`: One orienting or primary action followed by a local peer pair.
+- `2 → 1`: One peer mode/filter pair followed by an independent continuation or detail action.
+- `1 → 2 → N×1`: Pinned structural navigation, compact traversal, then a vertical collection of independently readable items.
+- `1 → 2 → 3 → 1`: Ragged staged control where context, local alternatives, denser short peers, and a separated terminal action have different semantic weight.
+- Repeated `2`: Text-bearing choices distributed down the screen instead of compressed across it.
+- `R×C`: A rectangular layout only when rows and columns map to genuine coordinates, repeated dimensions, or another stable spatial topology.
+
+Adapt a surface by identifying relationships, grouping only genuine peers, ordering groups by task hierarchy, applying label-pressure limits, and then choosing the least regular layout that remains immediately comprehensible. Do not select a catalog shape first and force the task into it.
+
+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 +159,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.