@llblab/pi-telegram 0.29.0 → 0.30.0

package/AGENTS.md

@@ -43,7 +43,7 @@ Keep each fact in one authoritative layer:
 - `/lib/*.ts`: Flat, cohesive runtime domains; package-private unless re-exported through `/api`.
 - `/tests/*.test.ts`: Domain-mirrored suites; `tests/integration.test.ts` owns cross-domain runtime flows.
 - `/skills/telegram-bridge`: Stable agent operating protocol for Telegram turns, delivery, actions, Threaded Mode, and diagnosis.
-- `/skills/button-console`: Optional generated-button interface over truthful console evidence; it remains independent from the bridge skill.
+- `/skills/control-surface`: Optional agent-generated cybernetic control surface over truthful domain evidence, workflows, and choices; it remains independent from the bridge skill and owns no parallel state.
 - `/.agents/skills/telegram-bot`: Bot API lookup guidance and vendored `api.md`; keep the reference intact.
 - `/.agents/skills/domain-dag`: Repository architecture guidance and validator.
 

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.30.0: Generated Control Surfaces
+
+- `Generated Control Surface`: Replaced the CLI-bound Button Console with a transport-aware Control Surface Skill that proactively generates truthful contextual controls when they shorten feedback for workflows, stateful systems, navigation, Actor supervision, and decisions while preserving domain ownership, ordinary prompt authority, confirmation boundaries, and stateless regeneration.
+- `Action Markup`: Standardized `telegram_button` and `telegram_voice` on one colon-free action marker for both JSON and attribute payloads. Colon-prefixed forms are rejected instead of remaining a redundant compatibility syntax.
+
 ## 0.29.0: Skill-First Agent Operation
 
 - `Bundled Skills`: Added discoverable `telegram-bridge` and `button-console` Skills through package metadata and source-checkout resource discovery. Stable turn, delivery, action, Threaded Mode, formatting, handler, and diagnosis guidance now lives in the bridge Skill, while Button Console provides optional evidence-backed CLI navigation.

package/README.md

@@ -188,11 +188,11 @@ Inbound files land under `<agent-dir>/tmp/telegram` and default to a 50 MiB limi
 
 ### Voice And Media
 
-Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Explicit `telegram_voice` actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and an optional format-neutral colon after the action name.
+Voice notes, audio, images, PDFs, and other media can pass through configured inbound handlers, programmatic handlers, or registered STT providers. Outbound voice can use configured `outboundHandlers` or registered TTS providers; `pi-telegram` owns reply policy and Telegram transport, while providers own synthesis. Explicit `telegram_voice` actions accept either a JSON object or compact double-quoted attributes, with equivalent `text` and `value` payload keys and one colon-free action marker.
 
 ### 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 optional colon after the action name never changes format detection. 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 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.
 
 ### Threaded Mode And Multi-Instance Bus
 
@@ -257,7 +257,7 @@ Durable inbound admission is a **process-crash recovery** guarantee. Atomic priv
 
 Telegram is a companion surface around a live Pi runtime, not a second runtime. It can compact the current session, but it cannot create, resume, fork, browse, or switch sessions until Pi exposes safe public extension APIs for those operations.
 
-A Telegram prompt is a normal model turn in the active Pi session and therefore inherits that session's active post-compaction context; the bridge does not make token cost proportional only to the new mobile message. The bundled `telegram-bridge` Skill owns agent operation and `button-console` provides optional generated-button CLI navigation. Disconnecting removes pi-telegram's delivery tools and transient routing guidance from later requests until direct ownership or follower registration returns, without changing other active Pi tools. Pi session JSONL contains model history; profile-scoped pi-telegram `logs*.jsonl` contains redacted operational events and is never model context.
+A Telegram prompt is a normal model turn in the active Pi session and therefore inherits that session's active post-compaction context; the bridge does not make token cost proportional only to the new mobile message. The bundled `telegram-bridge` Skill owns agent operation and `control-surface` provides optional evidence-backed controls for workflows, stateful systems, navigation, supervision, and decisions—not only terminal operations. Disconnecting removes pi-telegram's delivery tools and transient routing guidance from later requests until direct ownership or follower registration returns, without changing other active Pi tools. Pi session JSONL contains model history; profile-scoped pi-telegram `logs*.jsonl` contains redacted operational events and is never model context.
 
 ## Documentation Map
 

package/docs/architecture.md

@@ -324,7 +324,7 @@ 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; an optional colon after the action name is format-neutral and stripped before payload detection:
+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:
 
 - `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.
@@ -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 `button-console` Skill through Pi resource discovery. 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 `control-surface` Skill through Pi resource discovery. The latter generates 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.
 
 ## In-Flight Model Switching
 

package/docs/outbound.md

@@ -135,12 +135,12 @@ Assistant replies can include hidden voice actions in either supported payload f
 ```md
 Full text answer stays here.
 
-<!-- telegram_voice: {"value":"Short spoken companion summary.","lang":"ru","rate":"+30%"} -->
+<!-- telegram_voice {"value":"Short spoken companion summary.","lang":"ru","rate":"+30%"} -->
 
 <!-- telegram_voice text="Short spoken companion summary." lang="ru" rate="+30%" -->
 ```
 
-The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` action to a provider call, generates one file per action, and sends each file as an independent Telegram-native voice message. Equivalent `text` or `value` supplies the spoken payload, with explicit `text` taking precedence when both appear; `lang` and `rate` are optional. The colon after `telegram_voice` is optional for both JSON and attributes and never changes format detection. Use JSON for long or escaped text and encode line breaks inside JSON strings as `\n`. 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.
+The bridge strips the comment from Telegram text. On `agent_end`, it maps each `telegram_voice` action to a provider call, generates one file per action, and sends each file as an independent Telegram-native voice message. Equivalent `text` or `value` supplies the spoken payload, with explicit `text` taking precedence when both appear; `lang` and `rate` are optional. A colon after `telegram_voice` is rejected so both payload forms share one unambiguous action marker. Use JSON for long or escaped text and encode line breaks inside JSON strings as `\n`. 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.
 
 ## Buttons Markup
 
@@ -149,17 +149,17 @@ Assistant replies can include independent button actions in the same two payload
 ```md
 I can continue.
 
-<!-- telegram_button: {"label":"Continue","prompt":"Continue with the current plan.","selected_style":"primary"} -->
+<!-- telegram_button {"label":"Continue","prompt":"Continue with the current plan.","selected_style":"primary"} -->
 
 <!-- telegram_button label="Show risks" prompt="List the main risks first." selected_style="danger" -->
 
-<!-- telegram_button: {"value":"Done"} -->
+<!-- telegram_button {"value":"Done"} -->
 ```
 
 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.
-- The colon after `telegram_button` is optional for both forms and never changes format detection.
+- A colon after `telegram_button` is rejected so both payload forms share 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.

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. The colon after either action name is optional and does not select the format. 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 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.
 
 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

@@ -176,11 +176,11 @@ export function parseTelegramActionPayload(
 ): Record<string, unknown> | undefined {
   const parsed = parseTopLevelTelegramComment(comment, command);
   if (!parsed) return undefined;
+  if (parsed.head.trimStart().startsWith(":")) return undefined;
   const source = [parsed.head, parsed.body]
     .filter((part): part is string => part !== undefined)
     .join("\n")
-    .trim()
-    .replace(/^:\s*/, "");
+    .trim();
   if (!source) return undefined;
   if (source.startsWith("{")) {
     try {

package/package.json

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

package/skills/control-surface/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: control-surface
+description: Generates contextual, evidence-backed prompt-button interfaces as transient control surfaces for workflows, tools, stateful systems, choices, navigation, and operator actions—not only terminals. Use when a user asks the agent to generate buttons or a contextual operating surface through Telegram or another prompt-button transport. Existing transport menus and callback interfaces remain with their runtime owners.
+---
+
+# Control Surface
+
+Generate a temporary, truthful interface that turns the agent's current understanding and available capabilities into useful controls. The agent remains the interpreter, authority boundary, and interface generator; buttons are contextual prompts, not a second application, hidden daemon, or direct grant of capability.
+
+## Concept
+
+```text
+User intent + current evidence → compact state projection → contextual controls
+→ next prompt → authorized act → fresh projection
+```
+
+Each response is one generated control surface. Reinspect mutable reality after actions and regenerate the surface instead of maintaining a parallel UI model.
+
+## Scope
+
+Use this Skill only to synthesize an agent-generated prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, or runtime-owned control stays with that subsystem and does not route here merely because it contains buttons.
+
+A control surface may expose:
+
+- Observation: status, evidence, progress, diagnostics, or summaries.
+- Navigation: files, concepts, projects, artifacts, media, threads, or Actor Runs.
+- Action: safe next operations over tools, workflows, services, or project state.
+- Choice: alternatives, filters, priorities, approvals, or design decisions.
+- Supervision: pause, continue, inspect, redirect, retry, or stop bounded work.
+
+Console programs are one capability source, not the defining boundary. Use the real owner of each capability: a tool, API, repository, Actor runtime, filesystem, media system, documented workflow, or the explicit state of the conversation.
+
+## Core Contract
+
+- Generate controls from current evidence, an explicit contract, or clearly labeled conversational state.
+- Keep domain state with its real owner; never invent a shadow navigation tree, task database, or application session.
+- Make every button prompt self-contained: identify the target, intended result, relevant constraints, and freshness requirement.
+- Treat a click as an ordinary user request subject to the same authority, validation, and safety rules as typed text.
+- Never infer permission for destructive, privileged, credential-bearing, external, or irreversible work merely because a button exists.
+- Do not encode secrets, hidden reasoning, credentials, private keys, tokens, cookies, wallet material, or sensitive content in labels or prompts.
+- Show uncertainty, unavailable state, truncation, filtering, and stale evidence honestly.
+- Prefer a few high-value controls over exhaustive action enumeration.
+
+## Control Admission
+
+Buttons are optional, but bias toward offering them when they materially shorten a likely feedback loop. If the user can approve, reject, refine, prioritize, redirect, inspect, or choose a concrete next step faster by tapping than by composing a reply, proactively expose the smallest useful control set without waiting to be asked for buttons.
+
+Zero buttons remains preferable when controls would only decorate the answer, restate visible prose, solicit generic “What next?” input, expose an unclear consequence, or save negligible effort. A button earns its place by reducing response effort, ambiguity, turnaround time, or supervision cost while preserving an ordinary typed reply as a first-class option.
+
+For status requests, show a compact `Refresh` control and bounded inspect/drill-down controls only when work is active, blocked, stale-sensitive, or otherwise actionable. A completed static status needs no buttons. Do not add destructive shortcuts or actions whose target and consequence are not yet clear.
+
+## Feedback Leverage
+
+Treat feedback compression as the primary reason to make controls more visible and proactive:
+
+- Offer 2–6 high-confidence choices when they cover likely responses without pretending to be exhaustive.
+- Prefer controls for approval gates, bounded alternatives, priority changes, review verdicts, correction direction, and active-work supervision.
+- Put the most likely or highest-leverage response first, while keeping labels neutral enough to avoid steering the decision dishonestly.
+- Include an explicit free-form path in visible text when the listed choices cannot represent the full answer.
+- Regenerate controls after feedback so the next surface reflects the new decision rather than repeating stale options.
+- Omit controls when the user is already expressing a clear command and no immediate follow-up decision is needed.
+
+## Surface Model
+
+A surface normally contains:
+
+1. A short title naming the controlled object or decision.
+2. A compact projection of relevant state, evidence, choices, or output.
+3. Provenance when it matters: target, source, timestamp, run identity, status, or truncation note.
+4. Buttons for likely next intents.
+5. `Back` or `Up` for hierarchy navigation when meaningful.
+6. `Refresh` when the projected state can change.
+
+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.
+
+## Truth Modes
+
+Name the basis of the surface when ambiguity matters:
+
+- Live: freshly inspected mutable state.
+- Contract: stable documented capabilities or choices.
+- Conversation: alternatives or intents established in the current dialogue.
+- Adapted: bounded or transformed output whose omissions are stated.
+
+Do not present remembered or inferred state as live. After a mutation, refresh affected state before claiming success or generating dependent controls.
+
+## Evidence Fidelity
+
+Preserve material identities, values, ordering, warnings, errors, and status. Adaptation may group, translate, label, paginate, rank, or collapse repeated successful detail, but it must not:
+
+- Convert failure into success.
+- Hide material warnings or unavailable evidence.
+- Present a subset as complete.
+- Change identifiers, values, causal order, or authority.
+- Turn a proposal into completed state.
+
+State adaptation explicitly, for example: `Показаны 20 из 184 записей, по размеру`.
+
+## Safety And Confirmation
+
+Classify each action as read-only, ordinary mutation, privileged, destructive, secret-bearing, external, or irreversible.
+
+Use a two-stage flow for high-impact actions:
+
+1. An action button opens a confirmation surface naming the exact target, effect, and recovery boundary.
+2. A distinct confirmation button requests the exact operation.
+
+Re-check mutable targets immediately before execution. Access denial never authorizes automatic privilege escalation. If evidence may expose secrets, stop before display and offer metadata-only or redacted alternatives.
+
+## Prompt Buttons
+
+Use the transport's canonical prompt-button syntax. For pi-telegram, emit a top-level hidden comment:
+
+```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."} -->
+```
+
+Button prompts must:
+
+- Preserve the user's language.
+- Name exact targets where possible.
+- Express one coherent next intent.
+- Carry material safety and scope restrictions.
+- Request fresh inspection when state may have changed.
+- Avoid embedding volatile output that should be rediscovered.
+
+Labels stay short, distinct, and scannable. Emoji are optional semantic markers; do not rely on color alone. If buttons are unavailable, render the same control surface as a numbered choice list.
+
+## Capability Adapters
+
+### Console And System
+
+Use normal console programs as the capability owner. Check exit status and stderr before rendering success. Preserve complete output when reasonably sized; otherwise label pagination, filtering, head/tail, or ranked subsets. High-impact process, service, package, permission, shutdown, disk, and deletion actions require confirmation.
+
+### 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.
+
+### Workflows And Actor Runs
+
+Keep exact workflow, Recipe, Run, artifact, or task identity visible. Controls may inspect, pause, continue, redirect, retry, or stop only through the owning runtime contract. Never simulate lifecycle state, bypass Control semantics, or treat a generated button as direct execution authority.
+
+### Decisions And Design
+
+Buttons may represent explicit alternatives without live system inspection. State the decision being made, preserve meaningful trade-offs in visible text, and ensure each prompt records the selected intent rather than silently executing downstream consequences.
+
+## Action Procedure
+
+1. Identify the controlled object, user goal, and capability owner.
+2. Decide whether the surface needs live, contract, conversational, or adapted evidence.
+3. Inspect only the state required for a truthful projection.
+4. Classify candidate controls by authority and impact.
+5. Render compact state plus context-relevant controls.
+6. On the next turn, interpret the click as a new request and execute only what it authorizes.
+7. Validate the result and regenerate from retained reality.
+
+## Failure And Empty States
+
+- Show concise failure evidence and offer diagnosis, retry, refresh, back, or a narrower action.
+- If a target disappears, return to the nearest valid parent or owner instead of reusing stale controls.
+- If no action is currently valid, say so rather than generating decorative buttons.
+- Mark unsupported, sentinel, inferred, or unreliable values explicitly.
+- Keep safe navigation and refresh controls in empty collections when useful.
+
+## Quality Check
+
+Before sending a surface, verify:
+
+- State and controls share one clear owner and target.
+- Live claims come from current evidence.
+- Complete versus filtered or adapted output is labeled honestly.
+- No secret appears in visible text or button payloads.
+- Every button carries a valid self-contained next intent and measurably shortens likely feedback.
+- The surface preserves free-form feedback when choices are not exhaustive.
+- High-impact operations route through confirmation.
+- Back/Up and Refresh appear only when useful.
+- The surface remains readable on a mobile screen.

package/skills/telegram-bridge/SKILL.md

@@ -51,7 +51,7 @@ Use `telegram_attach` outside Telegram turns only when the user explicitly reque
 Button forms:
 
 ```html
-<!-- telegram_button: {"label":"Continue","prompt":"Continue with the current plan."} -->
+<!-- telegram_button {"label":"Continue","prompt":"Continue with the current plan."} -->
 <!-- telegram_button value="Continue" -->
 ```
 
@@ -65,7 +65,7 @@ Button forms:
 Voice forms:
 
 ```html
-<!-- telegram_voice: {"text":"Short spoken message","lang":"en"} -->
+<!-- telegram_voice {"text":"Short spoken message","lang":"en"} -->
 <!-- telegram_voice text="Short spoken message" lang="en" -->
 ```
 

package/skills/button-console/SKILL.md

@@ -1,139 +0,0 @@
----
-name: button-console
-description: Turns terminal programs, filesystem navigation, system inspection, and operator workflows into contextual agent-generated button interfaces while preserving full or faithfully adapted console output. Use when a user asks for controls, menus, navigation, actions, or an operating-system/CLI interface through Telegram or another prompt-button transport.
----
-
-# Button Console
-
-Build a temporary, truthful button interface over terminal and operating-system capabilities. The agent remains the interpreter and safety boundary; buttons are contextual prompts, not a second shell, static application, or hidden automation daemon.
-
-## Concept
-
-```text
-User intent → narrow inspection/action → console evidence → readable output → contextual buttons → next user intent
-```
-
-Each response is one generated screen. Reinspect current reality and regenerate controls after every action rather than maintaining a parallel navigation model.
-
-## Core Contract
-
-- Inspect reality before rendering entries or controls that depend on current state.
-- Use normal console programs as capability owners.
-- Show complete output when reasonably sized; otherwise adapt it without changing material facts and offer pagination, filtering, raw output, or drill-down.
-- Make every button prompt self-contained: name the exact target, operation, output expectation, and safety restriction.
-- Treat button clicks as ordinary user requests subject to the same authority and validation rules as typed requests.
-- Never infer permission for destructive, privileged, credential-bearing, external, or irreversible work merely because a button exists.
-- Do not read secrets to populate navigation. Names and safe metadata may be listed; contents require justified, explicit authorization.
-- Never place credentials, private keys, tokens, cookies, wallet material, or sensitive file contents in labels or prompts.
-
-## Screen Model
-
-A screen normally contains:
-
-1. A short title naming the current target.
-2. Console output or a faithful adaptation.
-3. Optional provenance such as path, command class, timestamp, exit status, or truncation note.
-4. Buttons for likely next actions.
-5. `Back` or `Up` for hierarchy navigation.
-6. `Refresh` when state may change.
-
-Prefer 4–12 useful buttons. Split larger sets into categories or pages rather than creating a dense button wall.
-
-## Console Fidelity
-
-Complete output preserves ordering, names, identifiers, numeric values, units, warnings, errors, and relevant exit status. Use a code block only when formatting is semantically meaningful; use compact records for simple listings.
-
-Adaptation may:
-
-- Replace columns with labeled records.
-- Normalize human-readable sizes.
-- Group entries by type.
-- Collapse repeated successful lines.
-- Show a bounded head, tail, page, or ranked subset.
-- Translate labels into the user's language.
-
-Adaptation must not:
-
-- Convert failure into success.
-- Omit material warnings.
-- Change identities, values, or ordering claims.
-- Present a filtered subset as complete.
-- Hide truncation, filtering, or an unavailable measurement.
-
-State adaptation explicitly, for example: `Показаны 20 из 184 записей, по размеру`.
-
-## Filesystem Navigation
-
-- Resolve the requested path before listing it.
-- List directories without reading file contents.
-- Include every ordinary entry unless the user requested a filter.
-- Do not silently omit a sensitive-looking entry; show its name when listing is safe, then handle its contents conservatively.
-- Hidden directories default to names and metadata only.
-- Use absolute or otherwise unambiguous paths in button prompts.
-- Keep `Up`, `Home`, and `Refresh` where useful.
-- Offer safe file operations first: metadata, non-sensitive preview, attach/send, or open with an appropriate application.
-
-Never expose credential-file contents through a preview button. This includes `*.keys`, private SSH keys, credential stores, browser profiles, cookies, tokens, and wallets.
-
-## System And Process Controls
-
-Read-only controls may directly request system status, uptime, load, memory, temperatures, disk use, process ranking, service state, network state, application discovery, and bounded redacted logs.
-
-Use a two-stage flow for high-impact actions:
-
-1. An action button opens a confirmation screen naming the exact target and consequences.
-2. A distinct confirmation button requests the exact operation.
-
-This applies to shutdown, reboot, process termination, package removal, file deletion, permission changes, service mutation, disk operations, and similar work. Use danger styling when available. Re-check the target immediately before execution and report resulting console evidence.
-
-## Button Generation
-
-When the transport supports prompt buttons, emit its canonical button action syntax. For pi-telegram this is a top-level hidden `telegram_button` comment:
-
-```html
-<!-- telegram_button: {"label":"📂 Downloads","prompt":"Show the current contents of /home/user/Downloads without reading file contents, then provide contextual navigation buttons."} -->
-```
-
-Button prompts must:
-
-- Use an exact target where possible.
-- Describe one coherent intent.
-- Preserve the user's language.
-- State important exclusions such as not reading secrets.
-- Request fresh state after mutations.
-- Avoid embedding volatile output that should be reinspected.
-
-Labels stay short, distinct, and scannable. Emoji are optional semantic markers; do not rely on color alone. If buttons are unavailable, render the same interface as a numbered choice list.
-
-## Action Procedure
-
-1. Identify the current target and capability.
-2. Classify the action as read-only, ordinary mutation, privileged, destructive, secret-bearing, or external.
-3. Run the narrowest console inspection needed for a truthful screen.
-4. Check exit status and stderr; never build a success menu from failed evidence.
-5. Render complete or explicitly adapted output.
-6. Generate only context-relevant next-action buttons.
-7. On the next turn, reinspect when freshness matters and execute only the newly authorized action.
-8. Report outcome evidence and regenerate the screen from retained reality.
-
-## Failure And Empty States
-
-- On command failure, show the concise error and offer diagnosis, retry, Back, or a narrower action.
-- For an empty directory, say so and retain Up, Home, and Refresh.
-- If a target disappeared, return to its nearest valid parent rather than reusing stale evidence.
-- On access denial, do not escalate privileges automatically.
-- If output may contain secrets, stop before display and offer metadata-only or redacted alternatives.
-- Mark unsupported, sentinel, or obviously invalid sensor values as unreliable instead of reporting them as facts.
-
-## Quality Check
-
-Before sending a screen, verify:
-
-- Displayed state comes from current console evidence.
-- Complete versus filtered output is labeled honestly.
-- No ordinary entry was accidentally omitted.
-- No secret appears in text or button payloads.
-- Every button has a valid self-contained next intent.
-- Destructive actions lead to confirmation rather than immediate execution.
-- Back/Up and Refresh exist when materially useful.
-- The response remains readable on a mobile screen.