@llblab/pi-telegram 0.28.0 → 0.29.0

package/AGENTS.md

@@ -42,6 +42,8 @@ Keep each fact in one authoritative layer:
 - `/api/*.ts`: Stable public package membranes documented in `docs/public-api.md`.
 - `/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.
 - `/.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.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.
+- `Model Context Contraction`: Removed the redundant `telegram_help` model tool and its repeated guidance implementation. Compact authority-aware prompts route agents to the bundled Skill, while disconnect/recovery now suppresses and restores only the two delivery tools without affecting foreign tools.
+
 ## 0.28.0: Durable Inbound And Protocol Reconstruction
 
 - `Owned Polling Request`: Only `getUpdates` gets an automatic budget: Telegram long-poll timeout plus 10 seconds. Poller abort settles requests and API retry waits; broad ordinary, media, and follower budgets were removed.

package/README.md

@@ -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. Current releases keep per-turn guidance small and transient, with detailed bridge instructions available on demand through `telegram_help` instead of persisted in every user turn. Disconnecting removes pi-telegram's model tools and prompt 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 `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.
 
 ## Documentation Map
 

package/docs/architecture.md

@@ -47,7 +47,7 @@ A Telegram destination follows a Pi instance, not an immutable Pi session file.
 
 Pi session JSONL and pi-telegram runtime JSONL serve different purposes. Pi session files contain model conversation, tool, usage, branch, and compaction entries. Profile-scoped `logs.jsonl` / `logs.<profile>.jsonl` contain redacted bridge operations from one or more instances and never become model context. Sharing a Telegram profile or working directory does not by itself merge Pi session identities or model histories.
 
-A Telegram prompt is a normal Pi model turn. It inherits the active post-compaction context just like a TUI prompt in the same session; pi-telegram does not promise context isolation or token cost proportional only to the new message. Current prompt guidance uses a small transient system note and the on-demand `telegram_help` tool instead of persisting the former large guidance suffix in every user turn. Existing session files created by older versions may still contain those historical repeated suffixes until session replacement or compaction removes them from active context.
+A Telegram prompt is a normal Pi model turn. It inherits the active post-compaction context just like a TUI prompt in the same session; pi-telegram does not promise context isolation or token cost proportional only to the new message. The bundled `telegram-bridge` Skill owns agent operation, while a small authority-aware system note routes applicable turns to it. Existing session files created by older versions may still contain historical repeated guidance until session replacement or compaction removes it from active context.
 
 The repository uses a **Flat Domain DAG**:
 
@@ -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. Only an exact direct owner or live registered follower exposes the three pi-telegram model tools, their active-tool metadata, and the compact local bridge suffix. Disconnect or authority loss removes those 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 receive a compact pointer to `telegram_help` plus dynamic prompt blocks such as `[voice] delivery: automatic voice`; full voice/button/direct-delivery/Threaded Mode syntax stays in the help tool rather than every system prompt.
+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.
 
 ## In-Flight Model Switching
 

package/docs/outbound.md

@@ -176,8 +176,8 @@ Buttons are built in and do not need a command template because they are pure Te
 The extension injects prompt guidance by context:
 
 - If no bot token is configured, no Telegram bridge suffix is injected.
-- For ordinary local/TUI prompts, the agent only sees compact direct-delivery guidance: use `telegram_attach` or `telegram_message` when the user asks to send something to Telegram, and otherwise answer locally as normal.
-- For Telegram-originated turns, the prompt carries only minimal mobile/reply/file guidance; agents can call `telegram_help()` for full voice/button/direct-delivery/Threaded Mode/formatting/debug details.
+- For ordinary local/TUI prompts, the compact routing note points to the bundled `telegram-bridge` Skill and forbids Telegram use unless explicitly requested.
+- 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.

package/docs/public-api.md

@@ -63,7 +63,7 @@ This command surface is a mobile companion subset, not a raw terminal-command br
 
 - `telegram_attach(paths, chat_id?, thread_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; with `assistant.rendering: "rich"`, exactly one PNG/JPEG, MP4, or MP3 artifact plus non-empty final Markdown can become one reply-anchored Rich Message. HTML mode, multiple/unsupported files, Guest Mode, and voice outputs retain their established paths. Outside Telegram turns the tool sends files directly to the paired/default chat, the registered follower's assigned thread, or an explicit `chat_id` plus optional `thread_id` when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus.
 - `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.
-- `telegram_help()` returns detailed agent-facing guidance for pi-telegram delivery actions, Threaded Mode, formatting, and debugging. The regular prompt only points agents at this tool instead of repeating the full guidance on every turn. `telegram_attach`, `telegram_message`, and `telegram_help` 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.
+- 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.
 

package/index.ts

@@ -39,6 +39,7 @@ import * as Replies from "./lib/replies.ts";
 import * as Routing from "./lib/routing.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Sections from "./lib/sections.ts";
+import * as Skills from "./lib/skills.ts";
 import * as Status from "./lib/status.ts";
 import * as Sync from "./lib/sync.ts";
 import * as TelegramApi from "./lib/telegram-api.ts";
@@ -60,6 +61,7 @@ const telegramBusProtocolIdentity =
 // --- Extension Runtime ---
 
 export default function (pi: Pi.ExtensionAPI) {
+  Skills.registerTelegramSkillDiscovery(pi);
   const piRuntime = Pi.createExtensionApiRuntimePorts(pi);
   const {
     getActiveTools,

package/lib/bindings.ts

@@ -404,9 +404,6 @@ export function registerTelegramCommandsAndTools({
       sendMarkdownReply(chatId, undefined, markdown, options),
     recordRuntimeEvent,
   });
-  Prompts.registerTelegramHelpTool(pi, {
-    getActiveProfileName: configStore.getActiveProfileName,
-  });
   Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: async (ctx, profileName) => {
       const nextProfileName = profileName ?? undefined;

package/lib/prompts.ts

@@ -4,19 +4,16 @@
  * Owns Telegram-specific system prompt suffixes injected into pi agent turns
  */
 
-import { Type } from "@sinclair/typebox";
-
-import { getTelegramDiagnosticsDisplayPaths } from "./paths.ts";
-import type { BeforeAgentStartEvent, ExtensionAPI } from "./pi.ts";
+import type { BeforeAgentStartEvent } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram bridge available. Do not use it from local/TUI prompts unless explicitly asked.`;
+Telegram bridge available. Load the \`telegram-bridge\` Skill for Telegram delivery, actions, Threaded Mode, or diagnosis. Do not use Telegram from local/TUI prompts unless explicitly asked.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram turn note: Call \`telegram_help\` if you need the pi-telegram bridge action contract.`;
+Telegram turn note: Load and follow the \`telegram-bridge\` Skill.`;
 
 export const TELEGRAM_ATTACH_PROMPT_SNIPPET =
   "Queue files for the active Telegram reply; outside Telegram turns, send files directly to Telegram.";
@@ -37,7 +34,6 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
   "telegram_attach",
   "telegram_message",
-  "telegram_help",
 ]);
 const TELEGRAM_MODEL_CONTEXT_MEMORY_KEY = Symbol.for(
   "@llblab/pi-telegram:model-context-suspended-tools",
@@ -135,88 +131,6 @@ export function createTelegramModelContextAvailabilityRuntime(deps: {
   };
 }
 
-function buildTelegramHelpText(profileName?: string): string {
-  const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
-  return `--- TELEGRAM BRIDGE HELP ---
-
-How to understand Telegram turns:
-- \`[telegram|thread:name|from:user|guest:group]\` marks Telegram origin and attributes.
-- \`thread\` is the visible Thread identity in Threaded Mode; it is not a bus role.
-- \`[reply]\` is quoted context only; act on the user's current instruction.
-- \`[attachments]\` are local files; \`[outputs]\` are handler results/transcripts; \`[time]\` is wall-clock context.
-- \`[voice] delivery: automatic voice\` means pi-telegram will synthesize ordinary assistant text for this turn; no \`[voice]\` line means no automatic voice policy.
-
-How to answer Telegram turns:
-- Reply in concise, scannable mobile Telegram Rich Markdown.
-- Use \`$...$\` for inline math and \`$$...$$\` for block math.
-- Real code blocks must stay literal.
-- For generated/requested files, call \`telegram_attach(local_path)\`; do not only mention the path.
-
-Assistant-authored Telegram actions:
-- \`telegram_voice\` and \`telegram_button\` are hidden top-level HTML comments, not Pi tools.
-- Put action comments at column zero, outside code, quotes, lists, and indented examples.
-- Action payloads use either JSON or double-quoted attributes; the colon after the action name is optional and does not affect parsing. Voice accepts equivalent \`text\` or \`value\`: \`<!-- telegram_voice: {"value":"Short summary","lang":"en"} -->\` or \`<!-- telegram_voice text="Short summary" lang="en" -->\`.
-- Keep the complete action in one top-level comment and include non-empty \`text\` or \`value\`; encode line breaks inside JSON strings as \`\\n\`.
-- Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
-- Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
-- Voice reply modes are compact: \`hidden\` emits no automatic context, \`mirror\` emits it for voice/audio input, and \`always\` emits it for every Telegram turn. Explicit \`telegram_voice\` remains available for an intentionally distinct spoken payload.
-- Button payloads use \`label\` plus \`prompt\`, or compact \`value\` when both are identical: \`<!-- telegram_button: {"label":"Continue","prompt":"Continue with the current plan."} -->\` or \`<!-- telegram_button value="Continue" -->\`.
-- Optional \`selected_style\` in either payload form controls the button after queue admission: \`primary\` (default, blue), \`success\` (green), or \`danger\` (red). It never suppresses the prompt.
-- If hidden button comments form the whole reply, the bridge supplies the standard \`☑️ **Choose an option:**\` heading automatically.
-
-Local/TUI direct delivery:
-- Do not send Telegram actions from local/TUI prompts unless explicitly asked.
-- Use \`telegram_attach\` for files and \`telegram_message\` for direct Markdown text.
-- Direct delivery requires this Pi instance to own \`/telegram-connect\` or be registered with the Threaded Mode bus.
-- For explicit targets, pass \`chat_id\` plus optional \`thread_id\`; registered followers default to their assigned Thread target.
-- Do not use \`telegram_message\` for ordinary Telegram-originated replies; answer normally and let the bridge deliver the active turn reply.
-
-Threaded Mode:
-- pi-telegram supports private-chat Threaded Mode when Telegram exposes thread support for the bot.
-- Product/user language is Thread; Bot API primitive names may still say topic.
-- Threaded Mode has one leader transport and visible follower Pi processes joined manually through \`/telegram-connect\`.
-- Thread names are bridge-assigned or preserved identities; do not invent rename prompts or use a rename tool.
-- The \`All\` surface is for routing/control, not hidden Pi process creation.
-
-Configurable handlers:
-- \`telegram.json\` can add no-code \`inboundHandlers\`/\`outboundHandlers\` using command templates before writing an extension.
-- For speech-to-text, configure an \`inboundHandlers\` entry matching \`type: "voice"\` or \`mime: "audio/*"\`; stdout becomes \`[outputs]\` prompt context.
-- If command-template config is not enough, build a companion extension through the public pi-telegram APIs; do not import package-private \`lib/*\` paths.
-
-Debugging pi-telegram:
-- Inspect \`${diagnosticsPaths.state}\` for runtime state, roster, bindings, slots, reservations, and diagnostics.
-- Inspect \`${diagnosticsPaths.logs}\` for redacted runtime event evidence.
-- Use terminal \`telegram-status\` for compact human health; use \`telegram-status --debug\` for the full human-readable diagnostic dump.`;
-}
-
-export function getTelegramHelpText(profileName?: string): string {
-  return buildTelegramHelpText(profileName);
-}
-
-export function registerTelegramHelpTool(
-  pi: ExtensionAPI,
-  options: { getActiveProfileName?: () => string | undefined } = {},
-): void {
-  pi.registerTool({
-    name: "telegram_help",
-    label: "Telegram Help",
-    description:
-      "Read pi-telegram usage guidance for delivery actions, Threaded Mode, handlers, formatting, and debugging.",
-    parameters: Type.Object({}),
-    async execute() {
-      return {
-        content: [
-          {
-            type: "text",
-            text: getTelegramHelpText(options.getActiveProfileName?.()),
-          },
-        ],
-        details: {},
-      };
-    },
-  });
-}
-
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;
   systemPrompt: string;

package/lib/skills.ts

@@ -0,0 +1,21 @@
+/**
+ * Bundled Telegram skill discovery
+ * Zones: pi agent, telegram guidance
+ * Owns source-checkout and installed-package skill path contribution
+ */
+
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI } from "./pi.ts";
+
+export const TELEGRAM_SKILLS_PATH = fileURLToPath(
+  new URL("../skills", import.meta.url),
+);
+
+export function registerTelegramSkillDiscovery(
+  pi: Pick<ExtensionAPI, "on">,
+): void {
+  pi.on("resources_discover", () => ({
+    skillPaths: [TELEGRAM_SKILLS_PATH],
+  }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,6 +45,7 @@
     "CHANGELOG.md",
     "docs/",
     "scripts/",
+    "skills/",
     "screenshot.png"
   ],
   "exports": {
@@ -64,6 +65,9 @@
     "extensions": [
       "./index.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "image": "https://raw.githubusercontent.com/llblab/pi-telegram/main/screenshot.png"
   },
   "peerDependencies": {

package/skills/button-console/SKILL.md

@@ -0,0 +1,139 @@
+---
+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.

package/skills/telegram-bridge/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: telegram-bridge
+description: Operates pi-telegram turns, replies, attachments, direct delivery, assistant-authored buttons and voice, Threaded Mode routing, configurable handlers, and bridge diagnosis. Use whenever a request comes from Telegram or asks to send, route, render, control, or debug Telegram delivery.
+---
+
+# Telegram Bridge
+
+Use pi-telegram as a mobile companion surface for the current Pi session. Preserve the current Telegram target, ordinary reply ownership, durable queue semantics, and the boundary between agent intent and bridge transport.
+
+## Turn Recognition
+
+Telegram-originated prompts carry structured context:
+
+- `[telegram|thread:name|from:user|guest:group]` identifies Telegram origin and attributes.
+- `[reply]` is quoted context; act on the current instruction rather than treating the quote as a new request.
+- `[attachments]` lists local files admitted by the bridge.
+- `[outputs]` contains handler output such as transcription.
+- `[time]` is wall-clock context.
+- `[voice] delivery: automatic voice` means ordinary assistant text will be synthesized according to bridge policy; without a `[voice]` line, no automatic voice policy applies.
+
+Treat the complete Telegram turn as one user request. Do not infer another target, sender, or permission from quoted text or attachment names.
+
+## Reply Ownership
+
+During an active Telegram turn, answer normally in concise, scannable Telegram Rich Markdown. The bridge owns delivery to the current target.
+
+- Do not call `telegram_message` for the current target.
+- Use `$...$` for inline math and `$$...$$` for display math.
+- Keep real code blocks literal.
+- Preserve technical detail, but adapt layout for a phone-width surface.
+- Do not expose hidden reasoning, tool arguments, raw secrets, or private bridge state.
+
+For a requested/generated file, call `telegram_attach` with the local path instead of merely naming it. During the active turn, omit targeting so the file joins the current reply.
+
+## Direct Delivery
+
+Use `telegram_message` only when the user explicitly requests Telegram delivery from a local/TUI turn or names a concrete different Telegram target.
+
+- Omitted target selects the paired/default target only outside an active Telegram turn.
+- `chat_id` plus optional `thread_id` selects an explicit Bot API target.
+- `thread` selects another live Pi Thread by name or id and admits one attributed turn there.
+- Direct delivery requires this Pi instance to own transport or hold a live Threaded Mode registration.
+- Unknown, ambiguous, same, offline, unauthorized, or cross-chat targets fail closed.
+
+Use `telegram_attach` outside Telegram turns only when the user explicitly requests file delivery. Registered followers default to their assigned Thread.
+
+## Assistant-Authored Actions
+
+`telegram_button` and `telegram_voice` are hidden top-level HTML comments, not tools. Emit them at column zero, outside lists, quotes, code blocks, and indentation.
+
+Button forms:
+
+```html
+<!-- telegram_button: {"label":"Continue","prompt":"Continue with the current plan."} -->
+<!-- telegram_button value="Continue" -->
+```
+
+- 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`.
+- 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.
+- A button click creates a new user request; it does not bypass authority or confirmation.
+- Labels stay short and distinct. Prompts name the exact target, intended operation, and safety exclusions.
+
+Voice forms:
+
+```html
+<!-- telegram_voice: {"text":"Short spoken message","lang":"en"} -->
+<!-- telegram_voice text="Short spoken message" lang="en" -->
+```
+
+- `text` and `value` are equivalent payload forms; explicit `text` wins.
+- Keep speech TTS-friendly and omit Markdown syntax, tables, and raw code.
+- Voice delivery creates OGG itself; do not attach a duplicate audio file.
+- Automatic voice modes are `hidden` (no automatic context), `mirror` (voice/audio input), and `always` (every Telegram turn).
+- Explicit voice remains available in every automatic voice mode for an intentionally distinct spoken payload.
+
+This Skill is the canonical operating contract. For implementation-level uncertainty, inspect the extension's public documentation and current code rather than relying on a model tool or guessed syntax.
+
+## Attachments And Secrets
+
+- Inspect only what the request requires.
+- Treat local attachment paths as admitted inputs, not proof that their contents are safe to expose.
+- Never place tokens, private keys, cookies, credentials, wallet material, or sensitive file contents in text or button payloads.
+- Sending a sensitive file requires an explicit user request naming that delivery intent.
+- For generated artifacts, queue the file with `telegram_attach`; do not base64 or paste binary content into chat.
+
+## Threaded Mode
+
+Threaded Mode operates in private chats when Telegram exposes thread support for the bot. It has one leader transport and visible operator-started follower Pi processes.
+
+- `Thread` is the product term; reserve `topic` for Bot API primitives.
+- A Thread follows its assigned live Pi instance and current session.
+- Do not invent hidden followers, launch shadow Pi processes, or expose internal bus roles as user identity.
+- Do not rename Threads through guessed prompts or unsupported tools.
+- The `All` surface is routing/control, not process creation.
+
+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.
+
+## Configurable Handlers And Extensions
+
+Prefer no-code command-template configuration in `telegram.json` before adding a companion extension:
+
+- `inboundHandlers` transforms text/media before queueing.
+- `outboundHandlers` transforms final replies.
+- Voice transcription handlers can match `type: "voice"` or `mime: "audio/*"`; stdout becomes `[outputs]`.
+
+When configuration is insufficient, use documented `@llblab/pi-telegram/*` public API subpaths. Never import package-private `lib/*`, start another polling loop, or bypass bridge ownership with raw Bot API access.
+
+## Safety
+
+- Read-only inspection may proceed when requested.
+- Destructive, privileged, external, credential-bearing, or irreversible operations require explicit authorization under the active engineering contract.
+- A button offering a dangerous action should open a consequence/confirmation screen before execution.
+- Re-check volatile targets immediately before mutation.
+- Report Telegram delivery failures honestly; do not claim a send from a queued comment or failed tool call.
+
+## Diagnosis
+
+Prefer:
+
+1. `telegram-status` for compact health.
+2. `telegram-status --debug` for bounded human-readable diagnostics.
+3. `~/.pi/agent/tmp/telegram/state.json` and `logs.jsonl` for default-profile redacted evidence.
+4. `state.<profile>.json` and `logs.<profile>.jsonl` in the same directory for a named profile.
+
+When `PI_CODING_AGENT_DIR` selects another compatible runtime, resolve the equivalent `tmp/telegram` directory under that agent root. Do not mutate bridge state, ownership files, journals, bindings, or locks to force recovery. Use supported commands and exact current authority.
+
+## Completion Check
+
+Before sending a Telegram response, verify:
+
+- The reply goes through the correct current or explicit target path.
+- Requested files are attached rather than only mentioned.
+- Action comments are top-level and syntactically complete.
+- Buttons carry self-contained prompts and dangerous actions retain confirmation.
+- No secret or hidden reasoning appears in text, actions, or attachments without explicit authorization.
+- Direct delivery is not duplicating the ordinary current-turn reply.