@llblab/pi-telegram 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.33.0: Matrix Controls And Pinned Filesystem Navigation
+
+- `Button Matrix`: Extended `telegram_button` and its plural alias from flat arrays to JSON matrices: top-level objects remain full-width rows, while nested arrays intentionally group one to three peer controls horizontally; empty, oversized, or deeper rows fail closed without changing existing object, attribute, or flat-array behavior.
+- `Filesystem Navigation`: Stabilized Generated Control Surface directory layout: parent traversal is pinned as the first full-width row outside root, available Previous/Next controls share the next compact row, ten-entry pages follow as full-width rows, one JSON-matrix action carries the surface, visible text avoids duplicate plain or monospaced inventories unless user preference overrides it, Refresh is omitted by default, and numbered fallback preserves navigation when buttons are unavailable.
+- `Command Rendering`: Replaced the `/next` empty-queue response's leaked HTML tag with native Rich Markdown so Telegram renders emphasis instead of displaying `<b>` literally.
+
+## 0.32.0: Compact Button Arrays And Filesystem Surfaces
+
+- `Button Arrays`: Added JSON-array payloads to the canonical colon-free `telegram_button` action so one hidden comment can declare many ordered button rows; `telegram_buttons` is an exact plural alias, while existing single-object and double-quoted attribute forms remain valid.
+- `Filesystem Surface`: Made bare filesystem paths—including `/`—legitimate Generated Control Surface intents. Directory surfaces resolve fresh metadata, paginate large listings, preserve secret boundaries, and may use exact path-only button prompts with compact semantic file/folder labels.
+
 ## 0.31.0: State-Derived Generated Control Surfaces
 
 - `Generated Control Surface`: Renamed the optional `control-surface` Skill to `generated-control-surface`, aligned its identity with the architectural primitive, and made Telegram routing evaluate it proactively when controls can materially shorten likely feedback without waiting for an explicit button request; decorative UI still resolves to zero controls.

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 either a JSON object or compact double-quoted attributes. Buttons use `label` plus `prompt`, or the compact `value` key when both are identical. The action marker is colon-free for both payload forms. 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, 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 three 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.
 
 ### Threaded Mode And Multi-Instance Bus
 

package/docs/architecture.md

@@ -324,10 +324,10 @@ Final delivery attaches reply metadata only where requested. Reply parameters ap
 
 Outbound files staged during an active Telegram turn are delivered after that turn completes. They use `telegram_attach`, are checked atomically per tool call, and use configurable size limits before photo/document upload. When no Telegram turn is active, `telegram_attach` sends files immediately to the paired/default chat, an assigned follower thread, or an explicit `chat_id` plus optional `thread_id`; `telegram_message` provides direct local/TUI Markdown text delivery for explicit user requests and runs the same `telegram_button` markup planner so buttons attach to that text message. Direct local/TUI delivery is singleton-controlled: classic mode requires this Pi instance to own `/telegram-connect`, while Threaded Mode followers must be registered and route through the leader-owned transport. Already accepted active-turn reply/attachment delivery remains session-local.
 
-Assistant-authored final-message actions use hidden top-level comments. Both actions accept a JSON object or double-quoted HTML-like attributes after one colon-free action marker; colon-prefixed payloads are rejected:
+Assistant-authored final-message actions use hidden top-level comments with colon-free markers; colon-prefixed payloads are rejected:
 
-- `telegram_voice` creates voice reply artifacts through configured outbound handlers, programmatic voice handlers, or registered synthesis providers.
-- `telegram_button` creates inline buttons whose callbacks enqueue the configured prompt text as a normal Telegram prompt turn.
+- `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 three buttons horizontally; every callback enqueues its configured prompt text as a normal Telegram prompt turn.
 
 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. 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. 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, paginates directory entries in fixed pages of ten as full-width rows, 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/outbound.md

@@ -144,7 +144,7 @@ The bridge strips the comment from Telegram text. On `agent_end`, it maps each `
 
 ## Buttons Markup
 
-Assistant replies can include independent button actions in the same two payload forms:
+Assistant replies can include one or many button actions through one colon-free marker:
 
 ```md
 I can continue.
@@ -154,15 +154,19 @@ I can continue.
 <!-- telegram_button label="Show risks" prompt="List the main risks first." selected_style="danger" -->
 
 <!-- telegram_button {"value":"Done"} -->
+
+<!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
+
+<!-- telegram_buttons [[{"value":"Approve"},{"value":"Reject"}]] -->
 ```
 
 Rules:
 
-- JSON objects and double-quoted HTML-like attributes are the only accepted payload forms; shorthand, body, paired-comment, unquoted-attribute, and single-quoted-attribute forms are rejected.
-- A colon after `telegram_button` is rejected so both payload forms share one unambiguous action marker.
+- `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.
+- 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.
-- Use one comment per button; this mirrors HTML's singular element model and avoids a nested button DSL.
+- 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 three button objects into one horizontal row. Empty rows, rows above three buttons, and deeper nesting are rejected. 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.
@@ -180,7 +184,7 @@ The extension injects prompt guidance by context:
 - For Telegram-originated turns, the compact note routes the agent to `telegram-bridge`, which owns voice/button/direct-delivery/Threaded Mode/formatting/debug guidance.
 - For Telegram-originated turns, write the full technical answer as normal Markdown.
 - Add `telegram_voice` with either a JSON object or double-quoted attributes when a Telegram-native voice message is useful. A companion summary is optional, no specific summary format is required.
-- Add `telegram_button` with either a JSON object or double-quoted attributes. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` is optional. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
+- Add `telegram_button` with a JSON object, JSON matrix, or double-quoted attributes; `telegram_buttons` is an alias. Prefer one array for multiple controls. Use `label` plus `prompt`, or `value` when they are identical; `selected_style` is optional. A button-only reply may omit parent text because the bridge supplies `☑️ **Choose an option:**` automatically.
 - For ordinary Telegram-turn replies, do not call transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion. For explicit local/TUI direct sends, `telegram_message` may include top-level `telegram_button` comments in its Markdown text because those buttons are attached to that text message.
 - Prefer meaningful visible parent text when it adds context; for a button-only answer, rely on the bridge's automatic `☑️ **Choose an option:**` fallback rather than manufacturing duplicate text.
 

package/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 through the same two payload forms. Use `label` plus `prompt`, or `value` when both strings are identical. Both action names use one colon-free marker; 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, 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 three 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.
 
 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/commands.ts

@@ -1189,7 +1189,7 @@ export async function handleTelegramNextCommand(deps: {
 }): Promise<void> {
   deps.clearPendingModelSwitch();
   if (!deps.hasQueuedItems()) {
-    await deps.sendTextReply("<b>Queue is empty.</b>");
+    await deps.sendTextReply("**Queue is empty.**");
     return;
   }
   if (!deps.isIdle() && deps.hasAbortHandler()) {

package/lib/outbound-buttons.ts

@@ -11,7 +11,7 @@ import type {
   TelegramInlineKeyboardMarkup,
 } from "./keyboard.ts";
 import {
-  parseTelegramActionPayload,
+  parseTelegramActionPayloadRows,
   parseTopLevelTelegramComment,
   replaceTopLevelHtmlComments,
 } from "./outbound-markup.ts";
@@ -163,17 +163,19 @@ export function planTelegramButtonReply(
 ): TelegramButtonReplyPlan {
   const keyboard: TelegramOutboundButtonMarkup["inline_keyboard"] = [];
   const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
-    const command = parseTopLevelTelegramComment(comment, "telegram_button");
+    const command = ["telegram_button", "telegram_buttons"].find((candidate) =>
+      parseTopLevelTelegramComment(comment, candidate),
+    );
     if (!command) return comment.raw;
-    const payload = parseTelegramActionPayload(comment, "telegram_button");
-    const action = payload ? parseTelegramButtonAction(payload) : undefined;
-    if (action) {
-      keyboard.push([
-        {
-          text: action.text,
-          callback_data: deps.registerAction(action),
-        },
-      ]);
+    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) }]
+          : [];
+      });
+      if (row.length > 0) keyboard.push(row);
     }
     return "";
   });

package/lib/outbound-markup.ts

@@ -170,30 +170,76 @@ function parseCanonicalTelegramActionAttributes(
   return Object.keys(attributes).length > 0 ? attributes : undefined;
 }
 
-export function parseTelegramActionPayload(
+function getTelegramActionPayloadSource(
   comment: TelegramTopLevelHtmlComment,
   command: string,
-): Record<string, unknown> | undefined {
+): { source: string; hasBody: boolean } | undefined {
   const parsed = parseTopLevelTelegramComment(comment, command);
-  if (!parsed) return undefined;
-  if (parsed.head.trimStart().startsWith(":")) return undefined;
+  if (!parsed || parsed.head.trimStart().startsWith(":")) return undefined;
   const source = [parsed.head, parsed.body]
     .filter((part): part is string => part !== undefined)
     .join("\n")
     .trim();
-  if (!source) return undefined;
-  if (source.startsWith("{")) {
+  return source ? { source, hasBody: parsed.body !== undefined } : undefined;
+}
+
+function isTelegramActionPayload(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function parseTelegramActionPayload(
+  comment: TelegramTopLevelHtmlComment,
+  command: string,
+): Record<string, unknown> | undefined {
+  const payload = getTelegramActionPayloadSource(comment, command);
+  if (!payload) return undefined;
+  if (payload.source.startsWith("{")) {
+    try {
+      const value: unknown = JSON.parse(payload.source);
+      return isTelegramActionPayload(value) ? value : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  if (payload.hasBody) return undefined;
+  return parseCanonicalTelegramActionAttributes(payload.source);
+}
+
+export function parseTelegramActionPayloadRows(
+  comment: TelegramTopLevelHtmlComment,
+  command: string,
+): Record<string, unknown>[][] | undefined {
+  const payload = getTelegramActionPayloadSource(comment, command);
+  if (!payload) return undefined;
+  if (payload.source.startsWith("[") || payload.source.startsWith("{")) {
     try {
-      const value: unknown = JSON.parse(source);
-      return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? (value as Record<string, unknown>)
-        : undefined;
+      const value: unknown = JSON.parse(payload.source);
+      if (isTelegramActionPayload(value)) return [[value]];
+      if (!Array.isArray(value)) return undefined;
+      const rows: Record<string, unknown>[][] = [];
+      for (const entry of value) {
+        if (isTelegramActionPayload(entry)) {
+          rows.push([entry]);
+          continue;
+        }
+        if (
+          !Array.isArray(entry) ||
+          entry.length === 0 ||
+          entry.length > 3 ||
+          !entry.every(isTelegramActionPayload)
+        ) {
+          return undefined;
+        }
+        rows.push(entry);
+      }
+      return rows;
     } catch {
       return undefined;
     }
   }
-  if (parsed.body !== undefined) return undefined;
-  return parseCanonicalTelegramActionAttributes(source);
+  if (payload.hasBody) return undefined;
+  const attributes = parseCanonicalTelegramActionAttributes(payload.source);
+  return attributes ? [[attributes]] : undefined;
 }
 
 export function normalizeMarkdownAfterVoiceExtraction(

package/package.json

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

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

@@ -116,10 +116,11 @@ Re-check mutable targets immediately before execution. Access denial never autho
 
 ## Prompt Buttons
 
-Use the transport's canonical prompt-button syntax. For pi-telegram, emit a top-level hidden comment:
+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 three 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.
 
 ```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"}] -->
 ```
 
 Button prompts must:
@@ -141,7 +142,14 @@ Use normal console programs as the capability owner. Check exit status and stder
 
 ### Filesystem
 
-Resolve paths before listing. Directory navigation may show safe names and metadata without reading contents. Never preview credential stores, private keys, browser profiles, cookies, tokens, wallets, or other secret-bearing files. Use unambiguous paths in prompts and offer safe operations before mutations.
+Treat a user prompt that is exactly a plausible filesystem path—including `/`—as legitimate intent to render that location through a generated filesystem surface. Resolve and freshly inspect it before display. Directory surfaces use one stable navigation layout:
+
+1. Pin `⬆️ Up` as the first full-width row whenever the current path is not filesystem root; its entire prompt is the exact parent path. Omit Up at `/`.
+2. When page traversal exists, place `⬅️ Previous` and `➡️ Next` together in one compact row immediately after Up, omitting either unavailable direction. Page traversal re-inspects the directory and preserves a fixed 10-entry page size; moving Up opens the parent at page one.
+3. Render at most 10 alphabetically ordered entry buttons as full-width rows after structural navigation. Each label uses the entry name plus a semantic folder/file emoji, and its entire prompt may be the exact target path because this Skill defines path-only prompts as navigation intent.
+4. Keep visible text to a compact path and range summary such as `📁 /home/llb · 1–10 of 52`; do not duplicate entry names as a plain or monospaced directory listing. Omit Refresh by default because resubmitting the current path already requests fresh rendering.
+
+For pi-telegram, emit the complete filesystem control set—Up, compact page traversal, then current-page entries—in one `telegram_button` JSON matrix rather than repeating one hidden comment per button. If prompt buttons are unavailable or fail to render, preserve the same ordering and pagination as an ordinary numbered text fallback, not a monospaced inventory, so free-form path entry remains sufficient. Show a plain or monospaced directory listing instead only when the user explicitly requests it or durable user Knowledge establishes that presentation preference. Never preview credential stores, private keys, browser profiles, cookies, tokens, wallets, or other secret-bearing files, and never raise privileges merely to enumerate a path.
 
 ### Workflows And Actor Runs
 

package/skills/telegram-bridge/SKILL.md

@@ -55,9 +55,11 @@ Button forms:
 ```html
 <!-- telegram_button {"label":"Continue","prompt":"Continue with the current plan."} -->
 <!-- telegram_button value="Continue" -->
+<!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
+<!-- telegram_buttons [[{"value":"Approve"},{"value":"Reject"}]] -->
 ```
 
-- Payloads accept JSON after an optional colon or double-quoted attributes; 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, 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 three 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`.
 - 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.