@llblab/pi-telegram 0.35.1 → 0.36.0

package/lib/queue.ts

@@ -34,7 +34,17 @@ export type TelegramQueueLane = "control" | "priority" | "default";
 export type TelegramQueueReactionDisposition =
   | { kind: "default" }
   | { kind: "priority"; emoji: string }
-  | { kind: "suppressed"; emoji: string };
+  | { kind: "suppressed"; emoji: string }
+  | {
+      kind: "priority-suppressed";
+      priorityEmoji: string;
+      suppressionEmoji: string;
+    }
+  | {
+      kind: "reaction-transition";
+      priorityEmoji?: string | null;
+      suppressionEmoji?: string | null;
+    };
 
 export interface TelegramQueueAdmissionReceipt {
   queueKind: TelegramQueueItemKind;
@@ -899,7 +909,7 @@ export function applyTelegramQueuePromptReactionDisposition<
   items: TelegramQueueItem<TContext>[],
   messageId: number,
   disposition: TelegramQueueReactionDisposition,
-  priorityLaneOrder?: number,
+  destinationLaneOrder?: number,
   scope?: TelegramQueueMessageScope,
 ): { items: TelegramQueueItem<TContext>[]; changed: boolean } {
   let nextItems = items;
@@ -911,17 +921,38 @@ export function applyTelegramQueuePromptReactionDisposition<
     ) {
       continue;
     }
-    const queueLane: TelegramQueueLane =
-      disposition.kind === "priority" ? "priority" : "default";
-    const laneOrder =
-      disposition.kind === "priority" ? priorityLaneOrder : item.queueOrder;
+    const isPriority = disposition.kind === "reaction-transition"
+      ? disposition.priorityEmoji === undefined
+        ? item.queueLane === "priority"
+        : disposition.priorityEmoji !== null
+      : disposition.kind === "priority" ||
+        disposition.kind === "priority-suppressed";
+    const queueLane: TelegramQueueLane = isPriority ? "priority" : "default";
+    const laneOrder = item.queueLane === queueLane
+      ? item.laneOrder
+      : destinationLaneOrder;
     if (laneOrder === undefined) {
-      throw new Error("Telegram priority reaction order is unavailable.");
+      throw new Error("Telegram destination lane order is unavailable.");
     }
-    const priorityEmoji =
-      disposition.kind === "priority" ? disposition.emoji : undefined;
+    const priorityEmoji = disposition.kind === "reaction-transition"
+      ? disposition.priorityEmoji === undefined
+        ? item.priorityEmoji
+        : disposition.priorityEmoji ?? undefined
+      : disposition.kind === "priority"
+        ? disposition.emoji
+        : disposition.kind === "priority-suppressed"
+          ? disposition.priorityEmoji
+          : undefined;
     const reactionSuppressionEmoji =
-      disposition.kind === "suppressed" ? disposition.emoji : undefined;
+      disposition.kind === "reaction-transition"
+        ? disposition.suppressionEmoji === undefined
+          ? item.reactionSuppressionEmoji
+          : disposition.suppressionEmoji ?? undefined
+        : disposition.kind === "suppressed"
+          ? disposition.emoji
+          : disposition.kind === "priority-suppressed"
+            ? disposition.suppressionEmoji
+            : undefined;
     if (
       item.queueLane === queueLane &&
       item.laneOrder === laneOrder &&
@@ -1984,7 +2015,6 @@ export interface TelegramSessionShutdownState<TQueueItem> {
   queuedTelegramItems: TQueueItem[];
   nextQueuedTelegramItemOrder: number;
   nextQueuedTelegramControlOrder: number;
-  nextPriorityReactionOrder: number;
   currentTelegramModel: undefined;
   activeTelegramToolExecutions: number;
   pendingTelegramModelSwitch: undefined;
@@ -1996,7 +2026,6 @@ export interface TelegramSessionShutdownState<TQueueItem> {
 export interface TelegramSessionRuntimeCounterState {
   nextQueuedTelegramItemOrder?: number;
   nextQueuedTelegramControlOrder?: number;
-  nextPriorityReactionOrder?: number;
 }
 
 export interface TelegramSessionRuntimeFlagState {
@@ -2104,8 +2133,7 @@ export interface TelegramQueueMutationRuntimeDeps<
   TContext,
 > extends TelegramQueueStore<TContext>, TelegramRuntimeEventRecorderPort {
   ctx: TContext;
-  getNextPriorityReactionOrder?: () => number;
-  incrementNextPriorityReactionOrder?: () => void;
+  allocateLaneOrder?: () => number;
   onItemsDiscarded?: (
     items: readonly TelegramQueueItem<TContext>[],
     ctx: TContext,
@@ -2116,8 +2144,7 @@ export interface TelegramQueueMutationRuntimeDeps<
 export interface TelegramQueueMutationControllerDeps<
   TContext,
 > extends TelegramQueueStore<TContext>, TelegramRuntimeEventRecorderPort {
-  getNextPriorityReactionOrder?: () => number;
-  incrementNextPriorityReactionOrder?: () => void;
+  allocateLaneOrder?: () => number;
   onItemsDiscarded?: (
     items: readonly TelegramQueueItem<TContext>[],
     ctx: TContext,
@@ -2227,7 +2254,6 @@ export function buildTelegramSessionShutdownState<
     queuedTelegramItems: [],
     nextQueuedTelegramItemOrder: 0,
     nextQueuedTelegramControlOrder: 0,
-    nextPriorityReactionOrder: 0,
     currentTelegramModel: undefined,
     activeTelegramToolExecutions: 0,
     pendingTelegramModelSwitch: undefined,
@@ -2492,24 +2518,40 @@ export function applyTelegramQueuePromptReactionDispositionRuntime<TContext>(
   deps: TelegramQueueMutationRuntimeDeps<TContext>,
   scope?: TelegramQueueMessageScope,
 ): boolean {
-  const priorityLaneOrder =
-    disposition.kind === "priority"
-      ? deps.getNextPriorityReactionOrder?.()
-      : undefined;
-  if (disposition.kind === "priority" && priorityLaneOrder === undefined) {
-    return false;
-  }
+  const queuedItems = deps.getQueuedItems();
+  const changesLane = queuedItems.some((item) => {
+    if (
+      !isPendingTelegramTurn(item) ||
+      !isTelegramQueueItemInMessageScope(item, scope) ||
+      !item.sourceMessageIds.includes(messageId)
+    ) {
+      return false;
+    }
+    const queueLane: TelegramQueueLane =
+      disposition.kind === "reaction-transition"
+        ? disposition.priorityEmoji === undefined
+          ? item.queueLane
+          : disposition.priorityEmoji === null
+            ? "default"
+            : "priority"
+        : disposition.kind === "priority" ||
+            disposition.kind === "priority-suppressed"
+          ? "priority"
+          : "default";
+    return item.queueLane !== queueLane;
+  });
+  const destinationLaneOrder = changesLane
+    ? deps.allocateLaneOrder?.()
+    : undefined;
+  if (changesLane && destinationLaneOrder === undefined) return false;
   const { changed, items } = applyTelegramQueuePromptReactionDisposition(
-    deps.getQueuedItems(),
+    queuedItems,
     messageId,
     disposition,
-    priorityLaneOrder,
+    destinationLaneOrder,
     scope,
   );
   if (!changed) return false;
-  if (disposition.kind === "priority") {
-    deps.incrementNextPriorityReactionOrder?.();
-  }
   commitReorderedTelegramQueueItemsRuntime(items, deps);
   return true;
 }
@@ -2931,18 +2973,33 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
           { phase: "transport-generation" },
         );
       }
-      const dispatchableItems: TelegramQueueItem<TContext>[] = [];
-      const suppressedActiveItems: TelegramQueueItem<TContext>[] = [];
-      for (const item of activeItems) {
-        if (
-          item.kind === "prompt" &&
-          item.reactionSuppressionEmoji !== undefined
-        ) {
-          suppressedActiveItems.push(item);
-        } else {
-          dispatchableItems.push(item);
+      const canDispatch = deps.canDispatch(ctx);
+      let nextActiveIndex = 0;
+      if (canDispatch) {
+        while (nextActiveIndex < activeItems.length) {
+          const candidate = activeItems[nextActiveIndex];
+          if (
+            !candidate ||
+            candidate.kind !== "prompt" ||
+            candidate.reactionSuppressionEmoji === undefined
+          ) {
+            break;
+          }
+          if (deps.hasPendingInboundQueueMutationForItem?.(candidate)) {
+            deps.updateStatus(ctx);
+            return;
+          }
+          if (
+            deps.isQueueItemAdmissionReady &&
+            !deps.isQueueItemAdmissionReady(candidate)
+          ) {
+            deps.updateStatus(ctx);
+            return;
+          }
+          nextActiveIndex += 1;
         }
       }
+      const dispatchableItems = activeItems.slice(nextActiveIndex);
       const nextItem = dispatchableItems[0];
       if (
         nextItem &&
@@ -2961,12 +3018,11 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
       }
       const dispatchPlan = planNextTelegramQueueAction(
         dispatchableItems,
-        deps.canDispatch(ctx),
+        canDispatch,
       );
-      if (dispatchPlan.kind !== "none") {
+      if (nextActiveIndex > 0 || dispatchPlan.kind !== "none") {
         deps.setQueuedItems([
           ...dispatchPlan.remainingItems,
-          ...suppressedActiveItems,
           ...protectedInactiveItems,
         ]);
       }

package/lib/routing.ts

@@ -590,6 +590,11 @@ export interface TelegramInboundRouteRuntimeDeps<
     ctx: TContext,
   ) => Promise<boolean>;
   buttonActionStore?: OutboundHandlers.TelegramButtonActionStore;
+  invokeBoundButtonAction?: (
+    action: OutboundHandlers.TelegramOutboundButtonAction,
+    query: TCallbackQuery,
+    ctx: TContext,
+  ) => Promise<false | "new" | "edit">;
   inboundHandlerRuntime: TelegramInboundHandlerRuntime<TContext>;
   threadStore?: Threads.TelegramTopicTargetStore;
   updateStatus: (ctx: TContext, error?: string) => void;
@@ -1566,6 +1571,16 @@ export function createTelegramInboundRouteRuntime<
         {
           resolveAction: deps.buttonActionStore.resolve,
           answerCallbackQuery: deps.answerCallbackQuery,
+          ...(deps.invokeBoundButtonAction
+            ? {
+                invokeBoundAction: (buttonQuery, action, context) =>
+                  deps.invokeBoundButtonAction!(
+                    action,
+                    buttonQuery as TCallbackQuery,
+                    context,
+                  ),
+              }
+            : {}),
           editMessageReplyMarkup: deps.editMessageReplyMarkup
             ? async (chatId, messageId, replyMarkup) => {
                 try {

package/lib/runtime.ts

@@ -10,7 +10,6 @@ const TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS = 250;
 export interface TelegramRuntimeQueueCounters {
   nextQueuedTelegramItemOrder: number;
   nextQueuedTelegramControlOrder: number;
-  nextPriorityReactionOrder: number;
 }
 
 export interface TelegramRuntimeLifecycleFlags {
@@ -34,8 +33,6 @@ export interface TelegramRuntimeQueuePort {
   syncCounters: (counters: Partial<TelegramRuntimeQueueCounters>) => void;
   allocateItemOrder: () => number;
   allocateControlOrder: () => number;
-  getNextPriorityReactionOrder: () => number;
-  incrementNextPriorityReactionOrder: () => void;
 }
 
 export interface TelegramRuntimeLifecyclePort {
@@ -85,7 +82,6 @@ export function createTelegramBridgeRuntimeState(): TelegramBridgeRuntimeState {
   return {
     nextQueuedTelegramItemOrder: 0,
     nextQueuedTelegramControlOrder: 0,
-    nextPriorityReactionOrder: 0,
     activeTelegramToolExecutions: 0,
     telegramTurnDispatchPending: false,
     compactionInProgress: false,
@@ -104,10 +100,6 @@ export function createTelegramBridgeRuntime(
         syncTelegramQueueRuntimeCounters(state, counters),
       allocateItemOrder: () => allocateTelegramQueueItemOrder(state),
       allocateControlOrder: () => allocateTelegramQueueControlOrder(state),
-      getNextPriorityReactionOrder: () =>
-        getNextTelegramPriorityReactionOrder(state),
-      incrementNextPriorityReactionOrder: () =>
-        incrementNextTelegramPriorityReactionOrder(state),
     },
     lifecycle: {
       syncFlags: (flags) => syncTelegramLifecycleRuntimeFlags(state, flags),
@@ -159,9 +151,6 @@ export function syncTelegramQueueRuntimeCounters(
     state.nextQueuedTelegramControlOrder =
       counters.nextQueuedTelegramControlOrder;
   }
-  if (counters.nextPriorityReactionOrder !== undefined) {
-    state.nextPriorityReactionOrder = counters.nextPriorityReactionOrder;
-  }
 }
 
 export function allocateTelegramQueueItemOrder(
@@ -176,18 +165,6 @@ export function allocateTelegramQueueControlOrder(
   return state.nextQueuedTelegramControlOrder++;
 }
 
-export function getNextTelegramPriorityReactionOrder(
-  state: TelegramBridgeRuntimeState,
-): number {
-  return state.nextPriorityReactionOrder;
-}
-
-export function incrementNextTelegramPriorityReactionOrder(
-  state: TelegramBridgeRuntimeState,
-): void {
-  state.nextPriorityReactionOrder += 1;
-}
-
 export function syncTelegramLifecycleRuntimeFlags(
   state: TelegramBridgeRuntimeState,
   flags: Partial<TelegramRuntimeLifecycleFlags>,

package/lib/updates.ts

@@ -133,24 +133,61 @@ export function getTelegramQueueReactionDisposition(
     emojis,
     TELEGRAM_REMOVAL_REACTION_EMOJIS,
   );
-  if (suppressionEmoji) return { kind: "suppressed", emoji: suppressionEmoji };
   const priorityEmoji = getTelegramReactionEmoji(
     emojis,
     TELEGRAM_PRIORITY_REACTION_EMOJIS,
   );
+  if (suppressionEmoji && priorityEmoji) {
+    return {
+      kind: "priority-suppressed",
+      priorityEmoji,
+      suppressionEmoji,
+    };
+  }
+  if (suppressionEmoji) return { kind: "suppressed", emoji: suppressionEmoji };
   if (priorityEmoji) return { kind: "priority", emoji: priorityEmoji };
   return { kind: "default" };
 }
 
-function areTelegramQueueReactionDispositionsEqual(
-  left: TelegramQueueReactionDisposition,
-  right: TelegramQueueReactionDisposition,
-): boolean {
-  return (
-    left.kind === right.kind &&
-    (left.kind === "default" ||
-      (right.kind !== "default" && left.emoji === right.emoji))
+function getTelegramQueueReactionTransition(
+  oldReactions: TelegramReactionType[],
+  newReactions: TelegramReactionType[],
+): TelegramQueueReactionDisposition | undefined {
+  const oldEmojis = collectTelegramReactionEmojis(oldReactions);
+  const newEmojis = collectTelegramReactionEmojis(newReactions);
+  const oldPriorityEmoji = getTelegramReactionEmoji(
+    oldEmojis,
+    TELEGRAM_PRIORITY_REACTION_EMOJIS,
+  );
+  const newPriorityEmoji = getTelegramReactionEmoji(
+    newEmojis,
+    TELEGRAM_PRIORITY_REACTION_EMOJIS,
   );
+  const oldSuppressionEmoji = getTelegramReactionEmoji(
+    oldEmojis,
+    TELEGRAM_REMOVAL_REACTION_EMOJIS,
+  );
+  const newSuppressionEmoji = getTelegramReactionEmoji(
+    newEmojis,
+    TELEGRAM_REMOVAL_REACTION_EMOJIS,
+  );
+  if (
+    oldPriorityEmoji === newPriorityEmoji &&
+    oldSuppressionEmoji === newSuppressionEmoji
+  ) {
+    return undefined;
+  }
+  const transition: Extract<
+    TelegramQueueReactionDisposition,
+    { kind: "reaction-transition" }
+  > = { kind: "reaction-transition" };
+  if (oldPriorityEmoji !== newPriorityEmoji) {
+    transition.priorityEmoji = newPriorityEmoji ?? null;
+  }
+  if (oldSuppressionEmoji !== newSuppressionEmoji) {
+    transition.suppressionEmoji = newSuppressionEmoji ?? null;
+  }
+  return transition;
 }
 
 export function extractDeletedTelegramMessageIds(
@@ -1299,17 +1336,11 @@ export async function handleAuthorizedTelegramReactionUpdate<TContext>(
     typeof reactionUpdate.chat.id === "number"
       ? { chatId: reactionUpdate.chat.id }
       : undefined;
-  const oldDisposition = getTelegramQueueReactionDisposition(
+  const reactionTransition = getTelegramQueueReactionTransition(
     reactionUpdate.old_reaction,
-  );
-  const newDisposition = getTelegramQueueReactionDisposition(
     reactionUpdate.new_reaction,
   );
-  if (
-    areTelegramQueueReactionDispositionsEqual(oldDisposition, newDisposition)
-  ) {
-    return;
-  }
+  if (!reactionTransition) return;
   deps.assertExecutionCurrent?.();
   await deps.flushPendingMediaGroupMessage?.(reactionUpdate.message_id);
   deps.assertExecutionCurrent?.();
@@ -1317,7 +1348,7 @@ export async function handleAuthorizedTelegramReactionUpdate<TContext>(
   deps.assertExecutionCurrent?.();
   deps.applyQueuedTelegramTurnReactionByMessageId(
     reactionUpdate.message_id,
-    newDisposition,
+    reactionTransition,
     deps.ctx,
     reactionScope,
   );

package/package.json

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

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

@@ -23,7 +23,9 @@ The primitive belongs to the Surface plane: it projects State, exposes Agency ca
 
 ## Scope
 
-Use this Skill only to synthesize a state-derived prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, fixed frontend, or runtime-owned control stays with that subsystem and does not route here merely because it contains buttons.
+Use this Skill only to synthesize a state-derived prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, fixed frontend, runtime-owned control, or installed Generative App stays with that subsystem and does not route here merely because it contains buttons.
+
+When a generated surface reveals a repeated stable interaction with bounded state and deterministic transitions, consider graduating it to the complementary `generative-apps` Skill. Keep one-off, interpretive, changing, and context-heavy interaction here; compile only when bypassing repeated model mediation has concrete latency, token, cost, reliability, or UX value.
 
 On Telegram turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. Load and apply it when a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
 
@@ -80,7 +82,9 @@ A surface normally contains:
 
 Prefer 2–6 controls for feedback and decisions; navigation collections may use up to 12 when the additional entries remain scannable. Split larger sets by category or page instead of building a button wall. Do not add navigation controls when the surface is a one-step decision.
 
-Present compact metadata as stacked key-value rows that reuse status-surface grammar: a short bold label, a colon, and an inline-code value when the value is path-like, numeric, an identifier, or machine state. Prefer ``**Path:** `/home/llb` `` and ``**Entries:** `1–10 of 52` `` on separate lines over prose fragments joined by a middle dot or other decorative section separator.
+When a logical grid has no semantic column headings but Markdown table syntax requires a header row, use the grid's first data row as the syntactic header and render each remaining row once beneath it. Do not insert blank, dash-only, duplicate, or invented placeholder headings: they add a false row to the projected topology. Use ordinary semantic headings when the data actually has named columns.
+
+Present compact metadata as stacked key-value rows that reuse status-surface grammar: a short bold label, a colon, and an inline-code value when the value is path-like, numeric, an identifier, or machine state. In Telegram Rich Markdown, use an actual Markdown list or blank paragraph boundaries so soft line breaks cannot collapse several fields into one visual line. Prefer ``- **Path:** `/home/llb` `` and ``- **Entries:** `1–10 of 52` `` over prose fragments joined by a middle dot or other decorative section separator.
 
 ## Truth Modes
 
@@ -118,7 +122,7 @@ Re-check mutable targets immediately before execution. Access denial never autho
 
 ## Prompt Buttons
 
-Use the transport's canonical prompt-button syntax. For pi-telegram, one top-level `telegram_button` comment accepts one JSON object, double-quoted attributes, a JSON matrix, or Compact Matrix Literal (CML). CML uses `{value}` 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.
+Use the transport's canonical prompt-button syntax. For pi-telegram, one top-level `telegram_button` comment accepts one JSON object, double-quoted attributes, a JSON matrix, or Compact Matrix Literal (CML). CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML whenever the model authors the control and it can express the required surface; fall back to expanded JSON only for multiline prompts, non-positional metadata, or a concrete CML parse/render failure, never merely from implementation habit. Deterministic Generative App scripts may return ordinary JSON because their source payload does not consume model-output tokens; author and operate those adapters through the `generative-apps` Skill rather than growing a parallel app workflow here. A top-level cell becomes one full-width row, while a nested row groups one or more controls horizontally without a parser-level width cap. Prefer one layout comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format.
 
 ### Semantic Row Composition
 
@@ -128,7 +132,9 @@ Model the control surface as an ordered ragged sequence of independently sized r
 - 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.
+- 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. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. 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 vertical extent independently from horizontal density. A genuinely spatial surface may retain many rows—such as an `8×16` field—when vertical continuity, coordinates, and one-glance topology matter; do not paginate merely to make its height match its width. For non-spatial collections, however, a tall button wall should yield to semantic grouping, progressive disclosure, or pagination. Keep compact state and instructions above a tall surface, preserve stable coordinates across regeneration, and avoid repeating prose between rows.
 
 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.
 
@@ -143,7 +149,7 @@ Use this catalog as a shape vocabulary, not a fixed menu of demos:
 - `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.
+- `R×C`: A rectangular layout only when rows and columns map to genuine coordinates, repeated dimensions, or another stable spatial topology; keep `C ≤ 8`, while `R` may be substantially larger when preserving vertical continuity is useful.
 
 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.
 
@@ -156,6 +162,8 @@ Preserve the ordinary admission test: proactively offer an interactive surface e
 - Keep trivial interaction state in the visible conversation. When state becomes too large, long-lived, or error-prone for reliable conversational reconstruction, persist a small human-auditable Markdown state artifact at a deterministic task-owned path and render from it. The artifact belongs to the underlying task or domain, not to this Skill as shadow application state.
 - When transition rules are non-trivial or correctness-sensitive, use a small deterministic state-transition owner—script, module, tool, or existing domain API—that validates `current state + admitted action → next state`; let the model compile the surface from its result instead of informally simulating every transition. Do not create code or files for a trivial one-step interaction.
 - Treat repeated clicks against current state, not stale button appearance. If an action is already consumed or unavailable, keep state unchanged and say so briefly. Preserve an occupied or selected button when spatial layout matters, using its label or selected style as the visual state; omit unavailable controls when layout does not matter. Transport-level disabled buttons are optional, not assumed.
+- Preserve tap-ahead on transports where existing controls remain actionable and rapid clicks queue separate turns. In a source-then-destination interaction, persist the source selection but do not regenerate the board, enumerate destinations, or duplicate controls between the two prompts; emit at most a minimal acknowledgement and let the already visible surface carry the destination click. Regenerate after the completed transition, invalid input, or evidence that the transport cannot preserve the intermediate surface.
+- Resolve coordinate selection by current state rather than rigid click parity. Clicking any currently selectable source selects or replaces the source and then waits; acknowledge a replacement tersely without regenerating the surface. Only a click that is not a selectable source becomes a destination attempt when a source is already selected, at which point the domain owner validates the transition. Without a selected source, a non-source coordinate is a no-op.
 
 ```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."} -->

package/skills/generative-apps/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: generative-apps
+description: Design, author, review, install, replace, invoke, or debug reusable Generative Apps that combine generated button interfaces, deterministic bound methods, and optional model-mediated prompts. Use for standalone applications and bounded view/controller adapters rendered through pi-telegram.
+---
+
+# Generative Apps
+
+## Concept
+
+A Generative App is a reusable application authored by the model for a concrete task. It combines persistent state, named methods, textual output, and a generated button interface. The model acts primarily as author/compiler; the installed program then renders evolving views and executes routine transitions without requiring inference on every click.
+
+```text
+intent → model authors app → reusable state + methods + generated views
+```
+
+One surface may deliberately mix two action planes:
+
+```text
+bound method  → deterministic local transition
+ordinary prompt → model interpretation, explanation, teaching, or adaptation
+```
+
+This is broader than one Telegram implementation. Telegram is the first renderer; a future TUI or web renderer may reuse the concept once a second implementation proves the common contract. Keep renderer-specific wire and lifecycle details with the owning runtime.
+
+Generative Apps complement `generated-control-surface`:
+
+```text
+Generated Control Surface → current context → model → one ephemeral surface
+Generative App             → model → reusable program → many evolving surfaces
+```
+
+The `generated` / `generative` distinction is intentional. Do not rename `generated-control-surface` to a competing generative term.
+
+## Ownership
+
+This Skill owns agent operating judgment:
+
+- Whether a Generative App is warranted.
+- Standalone versus adapter selection.
+- Authoring and capability review.
+- Install, replace, invoke, and validation workflow.
+- Safety boundaries and stop decisions.
+
+This Skill also owns the transport-independent concept, vocabulary, application shapes, hybrid action model, and relationship to Generated Control Surface.
+
+[`../../docs/generative-apps.md`](../../docs/generative-apps.md) owns only the concrete `pi-telegram` runtime reference: Telegram wire syntax, managed layout, executable ABI, state timeline, generation/revision fencing, worker execution, locking, installation transactions, callback routing, lifecycle behavior, and current limitations. Do not duplicate those implementation details here.
+
+## When To Use
+
+Use a Generative App when:
+
+- Interaction repeats or contains several stable transitions.
+- State and valid actions fit a small auditable contract.
+- Direct methods materially improve latency, cost, reliability, or UX.
+- Model judgment remains optional rather than required for every action.
+- One clear owner exists for application or external domain state.
+
+Prefer `generated-control-surface` for one-shot, interpretive, rapidly changing, or wholly model-mediated interaction. Do not create decorative apps, generic remote terminals, arbitrary command runners, or deterministic facades over ambiguous high-impact decisions.
+
+## Choose The Shape
+
+### Standalone deterministic application
+
+The app owns a closed state machine such as a game, form, selector, simulation, or compact workflow. Its state must reconstruct the current view and explain the previous transition.
+
+### View/controller adapter
+
+Another capability remains the authoritative real owner. The app stores validated adapter configuration and a last-observed projection only. Re-read the owner before mutation or explicit status; never promote cached view state into domain authority.
+
+## Authoring Workflow
+
+1. Identify the repeated feedback loop, real state owner, and actions that are truly deterministic.
+2. Choose one stable lowercase app and one self-contained `<app>.mjs` source outside the managed installation directory.
+3. Keep `init` and every exported method small, named, bounded, shell-free, and capability-specific.
+4. Render one complete next view after each action.
+5. Mix action planes intentionally:
+
+```text
+app::method(argument) → bounded method without a model turn
+ordinary prompt          → model-mediated interpretation or explanation
+```
+
+6. Review state fields, arguments, process calls, rendered values, secrets, destructive effects, and failure paths.
+7. Install with `telegram_bind({ app, script, argument })`.
+8. Replace the same logical app only with explicit `replace: true`; never create `-v2` identities merely to reload code.
+9. Invoke read-only diagnostics with `telegram_bind({ app, method, argument, display: false })` when agent-side evidence is needed.
+10. Keep the maintained source with its capability owner; managed `genapps/` state is runtime installation, not source ownership.
+
+## Safety Rules
+
+- A direct click authorizes only its exact installed method and validated JSON argument.
+- Use exact executable plus argv through the bounded process port; never expose generic `exec` or shell text.
+- Keep credentials and unrelated private state out of source, state, output, and diagnostics.
+- Route consequences requiring contextual judgment through an ordinary model prompt.
+- Fail closed on unavailable owners, stale actions, malformed state, absent methods, process failures, or uncertain effects.
+- Do not claim automatic refresh, removal, voice output, or other behavior still marked incomplete in the runtime document.
+
+## Validation
+
+Before presenting an app as working:
+
+- Confirm app, source stem, installed identity, and bound prompts agree.
+- Inspect the installed initial view and persisted bounded state.
+- Exercise at least one real bound action and prove it bypasses Pi queue/model admission.
+- Exercise at least one ordinary prompt when the app intentionally uses the model plane.
+- Verify replacement rejects stale buttons and failed initialization preserves the prior app.
+- For adapters, prove fresh external status and terminal mutation evidence.
+- Confirm failures are bounded, redacted, and do not silently render success.
+
+Stop and return to ordinary model interaction when the workflow cannot be represented safely as reviewed bounded methods plus explicit model prompts.

package/skills/telegram-bridge/SKILL.md

@@ -60,7 +60,7 @@ Button forms:
 <!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
 ```
 
-- `telegram_button` accepts one JSON object, a JSON matrix, Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. CML uses `{value}` 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`.
+- `telegram_button` accepts one JSON object, a JSON matrix, Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML for model-authored controls whenever it can express the required surface; use expanded JSON only for multiline prompts, non-positional metadata, or a concrete parse/render failure fallback, never merely from implementation habit. Deterministic Generative App scripts may use ordinary JSON because their output does not spend model tokens. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`.
 - 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.
@@ -102,6 +102,10 @@ Threaded Mode operates in private chats when Telegram exposes thread support for
 
 Cross-Thread delivery must preserve the concrete target and current registration authority. Use ordinary reply delivery for the source turn and `telegram_message(thread=...)` only for an explicitly requested different live Thread.
 
+## Generative Apps
+
+Load and follow the bundled `generative-apps` Skill when work designs, authors, reviews, installs, replaces, invokes, or diagnoses a Generative App. Generative Apps compile stable repeated interaction into generated button views that may mix bound methods executed before Pi queue admission with ordinary model prompts; this bridge Skill continues to own Telegram transport, target authority, delivery, general button syntax, and turn behavior rather than duplicating the application workflow.
+
 ## Configurable Handlers And Extensions
 
 Prefer no-code command-template configuration in `telegram.json` before adding a companion extension: