@llblab/pi-kit 0.4.0 → 0.5.1

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/references/layout-and-state.md

@@ -10,7 +10,7 @@ Model the surface as ordered ragged rows, not a rectangle to fill. Infer indepen
 - A horizontal pair is earned only by genuine peers with unmistakably compact labels and no plausible wrapping or truncation.
 - Three through five columns are for short symbols, coordinates, glyphs, or codes whose position carries meaning.
 - Six through eight columns require single-glyph or similarly minimal position-bearing labels. Never exceed eight columns on a phone surface.
-- Vary row width intentionally; never pad with empty, duplicate, or no-op controls.
+- Vary row width intentionally; never pad for symmetry with empty, duplicate, or no-op controls. A blank disabled cell is appropriate only when it represents a real unavailable position in a spatial grid.
 - Preserve reading order: orientation/navigation, primary content or choices, secondary controls, then separated destructive actions.
 - Rectangular grids require genuine spatial or coordinate correspondence. Vertical continuity may justify many rows; non-spatial button walls should paginate or group.
 
@@ -32,4 +32,6 @@ Keep trivial state in conversation. Persist a small human-auditable artifact whe
 
 Evaluate repeated clicks against current state, not stale button appearance. Preserve tap-ahead when the transport queues each click independently. In source-then-destination interaction, retain the source selection without duplicating the whole surface; regenerate after a completed transition, invalid input, or evidence that the transport cannot preserve the intermediate view.
 
-Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates.
+Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates, using the transport's disabled state without a fabricated prompt. Keep a useful enabled navigation or inspection action.
+
+Place each control group beside the content it governs when in-body blocks are supported; keep global navigation and whole-view actions in the footer. Do not duplicate one action in both positions merely for visibility. Row topology and current-state validation stay the same across compact and named representations and across placements; renderer limits and selection feedback belong to the transport.

package/node_modules/@llblab/pi-telegram/skills/generative-apps/SKILL.md

@@ -29,9 +29,9 @@ Generated Control Surface → current context → model → one ephemeral surfac
 Generative App             → model → reusable program → many evolving surfaces
 ```
 
-Both Skills use the same logical button matrix and `label + prompt` interaction model. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
+Both Skills use the same logical button matrix and `label + prompt` interaction model. An app may place groups beside their related content using the transport's in-body button blocks or keep whole-view controls in the footer; placement does not change binding, disabled state, or method authority. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
 
-An app may mix deterministic `app::method` controls and ordinary prompts in one view. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
+An app may mix deterministic `app::method` controls and ordinary prompts in one view, including one control group. Compact and named cells may coexist under the shared transport grammar; neither representation nor placement creates another action plane. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
 
 The `generated` / `generative` distinction is intentional. Do not rename `generated-control-surface` to a competing generative term.
 
@@ -76,7 +76,7 @@ Another capability remains the authoritative real owner. The app stores validate
 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.
+4. Render one complete next view after each action. Derive disabled controls from current state using the shared transport contract; visible disabled controls neither invoke methods nor enqueue prompts. Revalidate domain preconditions when an enabled control is invoked, because previously rendered views may be stale.
 5. Mix action planes intentionally:
 
 ```text
@@ -107,6 +107,7 @@ Before presenting an app as working:
 - 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 the placements actually used by the app and prove disabled cells invoke nothing. A successful ordinary prompt-button smoke is not evidence of app-method dispatch or stale-revision rejection.
 - 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.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/SKILL.md

@@ -15,7 +15,8 @@ Use Telegram as a mobile companion to the current Pi session. Preserve the exact
 | Attach a requested file to the current turn | `telegram_attach(path)` without targeting |
 | Explicitly send from local/TUI to Telegram | `telegram_message` or `telegram_attach` |
 | Explicitly send to a different live Thread | `telegram_message(thread=...)` |
-| Add prompt buttons or explicit voice | Top-level hidden action comments |
+| Add buttons | Hidden comment for footer; `telegram_button` fence for in-body rows |
+| Add explicit voice | Top-level hidden action comment |
 | Build a repeated deterministic interaction | Follow `generative-apps` |
 
 A connected Telegram session proves capability, not user intent. Use Telegram features on Telegram-originated turns or explicit Telegram delivery requests only. Never call `telegram_message` for the current active target.
@@ -39,7 +40,7 @@ Reply in concise, phone-width Telegram Rich Markdown. Use `$...$` and `$$...$$`
 
 ## Assistant Actions
 
-`telegram_button` and `telegram_voice` are hidden HTML comments, not tools. Emit each complete action comment at column zero, outside lists, quotes, code blocks, and indentation. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position, but only recognized top-level comments activate actions; comment-only output sends no text message.
+`telegram_button` and `telegram_voice` are markup, not tools. Emit action comments at column zero outside lists, quotes, code, and indentation. Comments create footer buttons or voice artifacts. For buttons between paragraphs, use a column-zero triple-backtick `telegram_button` block. Both button wrappers accept the same singleton JSON/CML cell or mixed matrix; the wrapper determines placement. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position; only recognized top-level wrappers activate actions; comment-only output sends no text message.
 
 ### Shared Encoding Rule
 
@@ -48,25 +49,35 @@ Choose the least verbose sufficient representation:
 1. Positional CML — default.
 2. JSON — only when multiline content, named fields, or escaping earns it.
 
-CML trims atom boundaries and decodes `\|`, `\}`, and `\\`. Keep one complete action in one comment.
+CML trims atom boundaries and decodes `\|`, `\}`, and `\\`. Keep each payload inside one complete wrapper.
 
 ### Prompt Buttons
 
-Every button has a self-contained prompt and an optional selection style. Use a short distinct `emoji + space + text` label when separate human-readable labeling adds meaning; established coordinates or symbolic tokens may use the prompt itself as visible text. A click creates an ordinary user request; it never grants authority or bypasses confirmation.
+Every enabled button has a self-contained prompt and an optional selection style. Use a short distinct `emoji + space + text` label when separate human-readable labeling adds meaning; established coordinates or symbolic tokens may use the prompt itself as visible text. A click creates an ordinary user request; it never grants authority or bypasses confirmation.
 
 - `{prompt}` uses the same text for label and prompt.
 - `{|prompt}` omits a separately authored label and uses the prompt as both visible text and queued prompt.
 - `{label|prompt}` separates visible label from queued prompt.
 - `{label|prompt|selected_style}` and `{|prompt|selected_style}` accept `primary`, `success`, or `danger`.
+- Fourth-position `1`/`true` disables, `0`/`false` enables; omission means enabled. JSON uses boolean `disabled`. `{|Next||1}` omits label/style; `{Next|||1}` omits prompt/style; `{|||1}` is blank (Telegram receives a non-breaking space). Prefer meaningful labels and retain a useful enabled action. Enabled CML requires a prompt. Disabled controls stay visible but have no callback, queued prompt, or bound-method invocation.
 - Top-level cells form vertical rows; one nested row groups horizontal peers.
-- Prefer one matrix comment for the complete surface.
+- Prefer one matrix per related group. Fenced blocks stay in place in Rich mode; HTML compatibility moves them to the footer. Native rows allow eight buttons. Malformed/oversized/unclosed blocks activate nothing; drafts hide them. Outer code fences and quoted/indented examples remain literal.
+- Both placements share prompt/app routing. In-body clicks acknowledge without recoloring; selected-style highlighting remains footer-only.
+
+A single in-body button (the four-backtick wrapper below makes this a literal example):
+
+````markdown
+```telegram_button
+{📖 Details|Explain this section.}
+```
+````
 
 ```html
 <!-- telegram_button [{▶️ Continue|Continue the current plan.}[{✅ Approve|Approve this.}{❌ Reject|Reject this.}]] -->
 <!-- telegram_button {"label":"💡 Explain","prompt":"Explain this.\nInclude the risks."} -->
 ```
 
-Proactively use `generated-control-surface` whenever controls can materially shorten likely feedback; once active, it must emit useful buttons rather than prose alone. That Skill owns action composition; this Skill owns Telegram serialization and delivery. If buttons form the whole reply, the bridge supplies the standard choice heading.
+Proactively use `generated-control-surface` whenever controls can materially shorten likely feedback; once active, it must emit useful buttons rather than prose alone. That Skill owns action composition; this Skill owns Telegram serialization and delivery. Footer-only replies receive the standard choice heading.
 
 ### Voice
 
@@ -113,6 +124,6 @@ Before replying:
 
 - Use the ordinary path for the current target and direct tools only for explicit other delivery.
 - Attach requested files rather than only mentioning them.
-- Keep action comments top-level, complete, and canonical: CML first, JSON when necessary.
-- Give every button a self-contained prompt; preserve confirmation for dangerous actions.
+- Keep action comments and button fences top-level, complete, and canonical: CML first, JSON when necessary; either syntax may coexist within one matrix.
+- Give every enabled button a self-contained prompt; preserve confirmation for dangerous actions.
 - Expose no secret or hidden reasoning.

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/references/diagnosis.md

@@ -13,4 +13,6 @@ These slash commands are registered Pi commands, not shell executables or agent
 
 When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve its equivalent `tmp/telegram` directory.
 
+A `persistent-conflict` polling stop means the bounded competing-`getUpdates` threshold triggered full transport stand-down, not cancellation of accepted local Pi work. The terminal diagnostic distinguishes lost local ownership from a competing client despite an apparently owned lock. Check other profiles, agent directories, installations, or non-Pi clients sharing the bot; after removing the competition, reconnect through the supported Pi command. Do not restart repeatedly or alter lock files to compete for the stream.
+
 Do not mutate ownership files, bridge state, journals, bindings, or locks to force recovery. Use supported commands and preserve exact profile, target, transport, and session authority. Never claim successful delivery without transport evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.7.4",
     "@llblab/pi-state-flow": "0.3.0",
-    "@llblab/pi-telegram": "0.42.4",
+    "@llblab/pi-telegram": "0.43.1",
     "@llblab/skills": "1.14.0"
   },
   "bundledDependencies": [