@llblab/pi-telegram 0.46.0 → 0.47.0

package/dist/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@llblab/pi-telegram",
+  "version": "0.47.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Telegram runtime adapter for Pi",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "telegram",
+    "bot",
+    "extension"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/llblab/pi-telegram.git"
+  },
+  "homepage": "https://github.com/llblab/pi-telegram",
+  "bugs": {
+    "url": "https://github.com/llblab/pi-telegram/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test --test-concurrency=4 --test-reporter=dot tests/*.test.ts",
+    "test:verbose": "node --experimental-strip-types --test --test-reporter=spec tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node scripts/build-dist.mjs",
+    "prepack": "npm run build",
+    "check": "node -e \"await import('./dist/pi-telegram/index.js'); console.log('pi-telegram: extension import ok')\"",
+    "audit": "npm audit --omit=peer",
+    "audit:host": "npm audit",
+    "pack:check": "npm pack --dry-run",
+    "validate": "npm run build && npm run typecheck && npm test && npm run audit && npm run check && npm run pack:check"
+  },
+  "files": [
+    "index.ts",
+    "api/",
+    "lib/",
+    "dist/",
+    "README.md",
+    "AGENTS.md",
+    "BACKLOG.md",
+    "CHANGELOG.md",
+    "docs/",
+    "scripts/",
+    "skills/",
+    "screenshot.png"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./inbound": {
+      "types": "./dist/api/inbound.d.ts",
+      "default": "./dist/api/inbound.js"
+    },
+    "./outbound": {
+      "types": "./dist/api/outbound.d.ts",
+      "default": "./dist/api/outbound.js"
+    },
+    "./delivery": {
+      "types": "./dist/api/delivery.d.ts",
+      "default": "./dist/api/delivery.js"
+    },
+    "./activity": {
+      "types": "./dist/api/activity.d.ts",
+      "default": "./dist/api/activity.js"
+    },
+    "./updates": {
+      "types": "./dist/api/updates.d.ts",
+      "default": "./dist/api/updates.js"
+    },
+    "./commands": {
+      "types": "./dist/api/commands.d.ts",
+      "default": "./dist/api/commands.js"
+    },
+    "./sections": {
+      "types": "./dist/api/sections.d.ts",
+      "default": "./dist/api/sections.js"
+    },
+    "./status": {
+      "types": "./dist/api/status.d.ts",
+      "default": "./dist/api/status.js"
+    },
+    "./voice": {
+      "types": "./dist/api/voice.d.ts",
+      "default": "./dist/api/voice.js"
+    },
+    "./keyboard": {
+      "types": "./dist/api/keyboard.d.ts",
+      "default": "./dist/api/keyboard.js"
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./dist/pi-telegram/index.js"
+    ],
+    "sourceExtensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./dist/skills"
+    ],
+    "sourceSkills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/llblab/pi-telegram/main/screenshot.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.84.4",
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}

package/dist/pi-telegram/index.js

@@ -0,0 +1 @@
+export { default } from "../index.js";

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

@@ -0,0 +1,107 @@
+---
+name: generated-control-surface
+description: Proactively generate truthful prompt-button controls; every active surface emits useful buttons with semantic emoji labels, while stable deterministic loops route to Generative Apps.
+---
+
+# Generated Control Surface
+
+Compile a temporary interface from current evidence, available capabilities, and user intent:
+
+```text
+state + capabilities + intent → projection + likely next actions
+```
+
+The surface projects reality; it does not own domain state, grant authority, or create a shadow application.
+
+## Admission
+
+Proactively use controls whenever a tap can reduce response effort, ambiguity, turnaround time, or supervision cost. On a prompt-button transport, every response produced under this Skill must include at least one useful button; never finish with prose alone. A bounded confirmation or choice should expose 2–6 safe concrete actions.
+
+At workflow handoff, offer a small high-confidence next-action set when the completed step clearly unlocks it. Preserve free-form reply when choices are not exhaustive. When no domain mutation qualifies, offer the most useful truthful continuation—such as inspect details, refine scope, refresh mutable evidence, navigate back, or continue the parent workflow—rather than a decorative control or generic “What next?”.
+
+Every button must advance, inspect, clarify, recover, navigate, or supervise the current intent. Never duplicate visible prose, represent unclear consequences, or repeat a command that introduces no new decision.
+
+## Ownership And Truth
+
+Identify one controlled object, target, and capability owner. Build from one declared truth mode when ambiguity matters:
+
+- **Live:** Freshly inspected mutable state.
+- **Contract:** Stable documented capability.
+- **Conversation:** Choices established in the dialogue.
+- **Adapted:** A labeled subset or transformation.
+
+Never present remembered or inferred state as live. Preserve material identity, ordering, values, warnings, failures, authority, and completeness. Label filtering, truncation, pagination, and unavailable evidence. Refresh affected state after mutation before claiming success or rendering dependent controls.
+
+Use the real capability owner—tool, API, repository, Actor runtime, filesystem, media system, workflow, or conversation. Do not invent parallel state, lifecycle, navigation, or callbacks.
+
+## Surface Contract
+
+A surface is an ordered ragged sequence of rows. Each button carries:
+
+- A short, distinct label.
+- The smallest self-contained next-request prompt.
+- Optional presentation state supported by the transport, including disabled controls when their visible unavailability helps explain current state.
+
+A disabled control is not an action: it needs no prompt or selected style and must not enqueue a prompt or invoke a bound method. Prefer a meaningful label; omit it only for an intentional blank cell in a spatial layout, never as decorative padding. Preserve its label and position when that makes a changing surface easier to understand; otherwise omit irrelevant controls. Explain non-obvious unavailability without relying on color alone. Retain at least one useful enabled action, such as refresh or navigation. Derive disabled state from the same evidence as the view; an old enabled control still requires current domain validation. Use the transport owner's disabled encoding rather than a dummy prompt or no-op callback.
+
+Prompts must name any target, operation, constraint, or freshness identity whose omission could change the action. Reuse visible context only when it remains unambiguous under delayed or reordered clicks. Never encode volatile output that should be freshly inspected.
+
+Every generated human-readable action label must use `emoji + space + text`; emoji-free text labels are invalid. Choose the emoji by action semantics, keep its meaning consistent, and never rely on emoji or color alone. Coordinates, established symbolic controls, and intentionally spatial glyphs already satisfy the marker role through their domain grammar. If prompt buttons are unavailable, preserve the same choices as a numbered list.
+
+## Layout Kernel
+
+- Use one full-width row for an independent, primary, long, or consequential action.
+- Use two columns only for unmistakably short textual peers.
+- Reserve three through eight columns for compact position-bearing glyphs or codes.
+- Preserve hierarchy and reading order; never pad, duplicate, or shorten necessary wording for symmetry.
+- Use Back/Up only for real hierarchy and Refresh only for mutable projections.
+- Prefer 2–6 decision controls. Paginate or group larger non-spatial collections.
+
+For complex grids, navigation collections, or stateful repeated clicks, read [`references/layout-and-state.md`](./references/layout-and-state.md).
+
+Place a control group beside the section it governs when the transport supports in-body blocks; use a footer for whole-answer actions. Placement must not change the matrix or action semantics. Serialize the resulting rows with the active transport contract. This Skill owns admission and composition, not transport syntax.
+
+## Safety
+
+A click is an ordinary user request under the same authority and validation rules as typed text. Never infer permission from the existence of a button.
+
+Classify actions as read-only, ordinary mutation, privileged, destructive, secret-bearing, external, or irreversible. High-impact actions use two stages:
+
+1. Open a confirmation surface naming exact target, effect, and recovery boundary.
+2. Offer a distinct request for the exact operation.
+
+Re-check mutable targets immediately before execution. Never expose secrets, credentials, hidden reasoning, private keys, tokens, cookies, wallet material, or sensitive content in labels, prompts, or projections. Access denial never authorizes privilege escalation.
+
+## Reuse Boundary
+
+Keep one-off, interpretive, changing, and context-heavy interaction here. When state and transitions become stable, repeated, bounded, and deterministic, follow `generative-apps` and compile only the deterministic loop. Existing transport menus, runtime callbacks, and installed apps remain with their owners.
+
+For capability-specific composition guidance, read only the applicable reference:
+
+- Console, filesystem, workflows, Actor Runs, and design choices: [`references/capability-adapters.md`](./references/capability-adapters.md)
+
+## Procedure
+
+1. Identify intent, controlled object, owner, and truth mode.
+2. Inspect only the evidence needed for a truthful projection.
+3. Admit only high-leverage actions and classify their impact.
+4. Arrange semantic rows, then serialize through the transport owner.
+5. Treat the click as a new request, validate authority, act, and refresh reality.
+
+## Failure And Empty States
+
+Show concise failure evidence and emit valid recovery controls such as diagnose, retry, refresh, back, or narrower scope. If a target disappears, return to its nearest valid owner or parent. Empty collections retain the safest useful navigation, inspection, or refinement control rather than degrading to prose-only output.
+
+## Final Check
+
+Before sending:
+
+- At least one useful button is present whenever the transport supports prompt buttons.
+- Every human-readable button label begins with a semantic emoji and one ASCII space.
+- State, actions, owner, and target agree.
+- Live claims are fresh; adaptation and incompleteness are explicit.
+- Every prompt is sufficient and every label follows its semantic emoji rule.
+- Row grouping reflects real hierarchy or peer relationships.
+- High-impact actions require confirmation.
+- No secret or hidden reasoning appears.
+- The surface remains readable on a phone and free-form feedback remains possible.

package/dist/skills/generated-control-surface/references/capability-adapters.md

@@ -0,0 +1,27 @@
+# Capability Adapters
+
+Read only the section matching the current controlled capability.
+
+## Console And System
+
+Use the real console program as capability owner. Check exit status and stderr before rendering success. Preserve complete output when reasonably sized; otherwise label pagination, filtering, ranking, or head/tail adaptation. Process, service, package, permission, shutdown, disk, and deletion mutations retain required confirmation.
+
+## Filesystem
+
+A prompt that is exactly a plausible filesystem path, including `/`, may request a generated filesystem surface. Resolve and freshly inspect it before display.
+
+1. Pin `⬆️ Up` first whenever the path is not root; its prompt is the exact parent path.
+2. If paginated, place available `⬅️ Previous` and `➡️ Next` together after Up. Re-inspect on traversal and use a stable 10-entry page.
+3. Sort visible directories, hidden directories, visible files, then hidden files; alphabetize within each category.
+4. Render at most 10 entries as full-width rows. Labels use the exact entry name plus semantic folder/file emoji; prompts may be exact paths because path-only prompts mean navigation here.
+5. Show compact Path and Entries metadata. Do not duplicate entries as a text inventory or add Refresh when resubmitting the path already refreshes.
+
+Preserve the same ordering and pagination in a numbered fallback. Show a plain directory listing only when explicitly requested or established preference requires it. Never preview credential stores, keys, browser profiles, cookies, tokens, wallets, or secret-bearing files, and never raise privileges merely to enumerate a path.
+
+## Workflows And Actor Runs
+
+Keep exact workflow, Recipe, Run, artifact, or task identity visible. Inspect, pause, continue, redirect, retry, or stop only through the owning runtime contract. Never simulate lifecycle state, bypass Control semantics, or treat a button as execution authority.
+
+## Decisions And Design
+
+Controls may represent conversational alternatives without live inspection. State the decision and material trade-offs in visible text. Each prompt records the selected intent; it does not silently execute downstream consequences.

package/dist/skills/generated-control-surface/references/layout-and-state.md

@@ -0,0 +1,37 @@
+# Complex Layout And Interaction State
+
+Read this reference only for complex grids, navigation collections, or repeated stateful clicks.
+
+## Semantic Rows
+
+Model the surface as ordered ragged rows, not a rectangle to fill. Infer independent, peer, ordered, hierarchical, and spatial relationships before choosing row boundaries.
+
+- Non-spatial controls default to one full-width row each.
+- 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 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.
+
+Useful shapes include `1`, `2`, `1 → 2`, `2 → 1`, `1 → 2 → N×1`, repeated `2`, and true `R×C`. Treat these as vocabulary, never templates to impose.
+
+## Metadata And Collections
+
+Use compact stacked key-value rows for path-like, numeric, identifier, or machine state, for example `- **Path:** /...` and `- **Entries:** 1–10 of 52`. Do not join unrelated metadata with decorative separators or duplicate button labels as a plain inventory.
+
+When a Markdown grid has no semantic column headings, use its first data row as the syntactic header and render remaining rows once. Never invent blank, dash-only, or duplicate headings that add false topology.
+
+Navigation collections may expose up to 12 scannable entries; paginate or categorize larger sets. Keep stable ordering and coordinates across regeneration.
+
+## Interaction State
+
+Encode the smallest sufficient action delta when visible context establishes one unambiguous state. Add stable target or state identity when delivery may be delayed, reordered, routed elsewhere, or detached from the projection.
+
+Keep trivial state in conversation. Persist a small human-auditable artifact when state becomes too large or long-lived for reliable reconstruction. Use a deterministic state-transition owner when rules become correctness-sensitive.
+
+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, 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/dist/skills/generative-apps/SKILL.md

@@ -0,0 +1,115 @@
+---
+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; prefer Generated Control Surface when no reusable deterministic program is earned.
+---
+
+# 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
+```
+
+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, 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.
+
+## 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. 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
+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.
+- Treat `refreshAfterMs` validation, output-only `refresh`, scheduling after a successful hinted explicit `telegram_bind` delivery, same-handle rescheduling after a current-surface bound action, Delivery edit-failure classification, known unavailable-message invalidation with bounded classified diagnostics, session/runtime live-surface cancellation, and exact direct classic/leader/authenticated-follower target retention as implemented. The Bot API has no ordinary private-message deletion update; `deleted_business_messages` is limited to connected business accounts. Do not claim removal, voice output, proactive deletion-update invalidation, 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 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.
+
+Stop and return to ordinary model interaction when the workflow cannot be represented safely as reviewed bounded methods plus explicit model prompts.

package/dist/skills/show-me/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: show-me
+description: Explain completed work, proposed changes, system structure, or ideas through truthful contextual Markdown, concise diagrams, code-shape sketches, and focused HTML artifacts. Use when the user asks to show what happened, what changed, or how something works, especially on a phone-width Telegram surface.
+---
+
+Help the user understand the current topic. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear without making the underlying claim less true.
+
+### Output Selection
+
+- Infer the subject from the conversation and honor an explicitly requested format. With plain `show me`, choose the form that best explains the subject.
+- Markdown in the reply is a complete output format for both chat and terminal surfaces. Use headings, emphasis, lists, and focused code blocks to explain outcomes, comparisons, and reasoning; add a diagram when relationships need one.
+- `Show me markdown` requests a rendered Markdown reply. Create a Markdown file only when the user asks for a saved document or file artifact.
+- `Show me html` requests a focused HTML file. Prefer an accessible, art-directed interactive infographic when timelines, comparisons, layers, or progressive disclosure clarify the subject; otherwise stay static. Preserve truthful labels and reduced motion. Save and deliver the artifact through the active environment; open it locally when requested.
+
+### Surface Routing
+
+- Infer whether the active surface is Telegram, a terminal, or another client. Keep the explanation portable and use surface-specific delivery only when the context or user request authorizes it.
+- For Telegram output, read [`references/telegram-surfaces.md`](./references/telegram-surfaces.md) before selecting Markdown or HTML. Keep the immediate reply useful even when an attached artifact is the deeper view.
+- When asked what changed or happened in current work, inspect the retained diff, status, and validation evidence when available. Separate this task from pre-existing changes and distinguish repository state from released or live behavior.
+
+### Truth And State
+
+- Label material claims as `live`, `released`, `locally implemented`, `proposed`, or `unverified` when the distinction affects interpretation. Omit redundant labels when the state is already unambiguous.
+- Preserve the exact mechanism, owner, and boundary when simplifying technical behavior. A friendly label may supplement the implementation term but must not replace it when that would merge distinct timers, states, stages, or authorities.
+- Make a visual diff correspond to the actual changed symbol or contract. Show unchanged neighboring behavior when omission could imply that it changed too.
+- Do not infer that an affordance is clickable, interactive, rendered, or client-visible from source or markup shape alone. Distinguish designed or expected behavior from behavior verified through the relevant renderer, transport, runtime, and client.
+- Treat a mockup, diagram, or rendered artifact as explanatory evidence, not runtime proof. State the unverified boundary when the user could reasonably mistake one for the other.
+
+A compact state line is enough when provenance matters:
+
+```text
+State: locally implemented · validated · not released · not live
+```
+
+### Visual Forms
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├─ commands/
+│  └─ parses user actions
+├─ sessions/
+│  └─ owns session state
+└─ transport/
+   └─ sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├─ commands/
++│  └─ show-me.ts
++│     └─ expands the slash command
+ ├─ sessions/
+-└─ transport.ts
++└─ transport/
++   ├─ client.ts
++   └─ stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```
+
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, use a focused HTML artifact — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. When practical, render representative narrow and wide viewports and report what was actually inspected.
+
+### Text Rendering
+
+- Adapt the view to the available width in both terminal and chat surfaces. Use shallow trees with `├─`, `└─`, and `│`, a space before labels, and a three-column nesting step for file hierarchy; use indentation for call trees and pseudocode.
+- Keep labels concise and in the user's language. Express status with words; use text glyphs with predictable monospace width for aligned diagram structure.
+- For changes, use a compact fenced `diff` block in Telegram or the terminal. Show the changed lines and only the surrounding context needed to understand them.
+- In trees, place comments and explanations as child nodes one level below the item they describe. Keep the item's own line for its label.
+- Use prose lists for independent statuses and split larger views into meaningful sections.
+
+### Guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point. Prefer one primary visual and a few decision-relevant takeaways; add another form only when it explains a different necessary relationship.
+
+Use source paths, symbol names, or validation evidence when they materially anchor a claim, not as decoration. Report the strongest state the evidence supports and no stronger.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/dist/skills/show-me/references/telegram-surfaces.md

@@ -0,0 +1,43 @@
+# Telegram Explanation Surfaces
+
+Use this reference only when Show Me is responding through Telegram or preparing an artifact for Telegram delivery.
+
+## Selection
+
+- With plain `show me`, prefer a native Markdown reply when one phone-width view can explain the point.
+- Use HTML when spatial comparison, dense state, a timeline, or a visual hierarchy would become harder to understand in narrow Markdown.
+- `Show me markdown` means rendered Markdown in the current reply, not a `.md` attachment, unless the user explicitly asks for a file.
+- `Show me html` means one focused, self-contained `.html` artifact delivered through the active Telegram file path. The surrounding reply should say what the artifact explains and disclose its evidence state.
+- Do not create both formats by habit. The second format must answer a need the first cannot.
+
+## Telegram Markdown
+
+- Design for a phone before a desktop: one governing question, one primary visual, short labels, shallow nesting, and prose that wraps naturally.
+- Prefer compact semantic diffs, call trees, timelines, or state transitions over raw repository diffs. A remote user needs to understand impact before file-level detail.
+- Avoid wide tables, deep trees, side-by-side layouts, and Mermaid when the current Telegram renderer would expose only source text. Move genuinely spatial material to HTML.
+- Put material state near the top: what changed, whether it is local or live, what was validated, and what remains unresolved.
+- Keep source paths and symbol names below the explanation unless they are the explanation.
+- Keep intended Telegram bot-command tokens as plain text rather than inline code. Format Pi/TUI or shell commands as code according to the host contract. Plain source shape does not prove native clickability; claim it only after the active entity-detection and client path is verified.
+- Use explicit Markdown links when a destination matters rather than assuming plain URL auto-detection.
+
+## Telegram HTML
+
+- Produce a single self-contained file with UTF-8 metadata and a viewport declaration. Avoid external assets, scripts, fonts, trackers, or network requirements unless the user explicitly requested them.
+- Build mobile-first for roughly phone-width reading, then let the same document expand cleanly in a system or desktop browser. Text must wrap; diagrams must scroll or reflow without clipping.
+- Use semantic headings, sufficient contrast, non-color status meaning, comfortable touch targets, and no hover-only information.
+- Preserve real labels, values, ordering, and uncertainty. An attractive reconstruction must not invent runtime state or imply that a proposed interaction exists.
+- Include a compact provenance line when state matters, such as `Local patch · validated · not released · not live`.
+- When rendering tools are available, inspect at least one narrow viewport and one wider viewport. Report what was inspected; static source review is not visual proof.
+- Deliver the file through the active Telegram attachment mechanism. Do not expose local paths as if the user could open them remotely.
+
+## Current-Work Evidence
+
+Before explaining “what we did” or “what happened,” use the narrowest available evidence that can support the answer:
+
+1. Inspect retained repository status and diff for the relevant task.
+2. Identify pre-existing or unrelated changes and exclude them from the claimed task result.
+3. Name the actual changed mechanism or contract, not a friendlier neighboring concept.
+4. Separate implementation evidence from validation, release, deployment, runtime, transport, and client evidence.
+5. State unresolved causes or missing live checks instead of filling them with a cleaner story.
+
+A visual is successful when the user can understand the outcome away from a computer without being given a stronger claim than the evidence supports.