@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: generated-control-surface
+description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request; route reusable deterministic loops toward Generative Apps, omit decorative UI, and preserve domain ownership while fixed transport menus and callbacks remain with their runtime owners.
+---
+
+# Generated Control Surface
+
+Compile a temporary, truthful interface from current state, available capabilities, and user intent. The agent remains the interpreter and authority boundary; the generated surface remains an ephemeral renderer projection, not a second application, hidden daemon, state owner, or direct grant of capability.
+
+## Primitive
+
+```text
+interface = f(state, capabilities, intent)
+
+current evidence + available acts + user intent
+→ compact state projection → contextual controls
+→ next prompt → authorized act → fresh projection
+```
+
+This is late-bound UI rather than a fixed frontend for one backend. Each response is one generated control surface whose renderer may be Telegram, another prompt-button transport, or a numbered fallback. Reinspect mutable reality after actions and regenerate instead of maintaining a parallel UI model.
+
+The primitive belongs to the Surface plane: it projects State, exposes Agency capabilities, and preserves Constitution constraints without absorbing any of those owners. Its reusable competence lives in this Skill so quality depends less on rediscovering interface policy in each turn.
+
+## Scope
+
+Use this Skill only to synthesize a state-derived prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, fixed frontend, runtime-owned control, or installed Generative App stays with that subsystem and does not route here merely because it contains buttons.
+
+This Skill and `generative-apps` share one logical button-matrix and `label + prompt` interaction model while retaining different execution owners. On Telegram, the bridge runtime owns the full JSON/CML action notation: this Skill emits an ephemeral surface from current context, while a Generative App returns reusable views through its script ABI. Shared rendering does not justify a third button Skill or move transport grammar into either interaction Skill.
+
+When a generated surface reveals repeated stable interaction with bounded state and deterministic transitions, load the complementary `generative-apps` Skill and consider compiling that loop. A Generative App may retain ordinary model-mediated prompt buttons beside deterministic bound methods, so only the stable actions need bypass inference. Conversely, keep one-off, interpretive, changing, and context-heavy interaction here when a reusable script would add no concrete latency, token, cost, reliability, or UX value.
+
+On Telegram turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. Load and apply it when a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
+
+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 minimally sufficient for a truthful continuation: reuse unambiguous visible conversational context, but include stable target, state, constraint, or freshness identity whenever omission could change the action.
+- 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.
+
+When a logical grid has no semantic column headings but Markdown table syntax requires a header row, use the grid's first data row as the syntactic header and render each remaining row once beneath it. Do not insert blank, dash-only, duplicate, or invented placeholder headings: they add a false row to the projected topology. Use ordinary semantic headings when the data actually has named columns.
+
+Present compact metadata as stacked key-value rows that reuse status-surface grammar: a short bold label, a colon, and an inline-code value when the value is path-like, numeric, an identifier, or machine state. In Telegram Rich Markdown, use an actual Markdown list or blank paragraph boundaries so soft line breaks cannot collapse several fields into one visual line. Prefer ``- **Path:** `/home/llb` `` and ``- **Entries:** `1–10 of 52` `` over prose fragments joined by a middle dot or other decorative section separator.
+
+## Truth Modes
+
+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, one top-level `telegram_button` comment accepts one JSON object, double-quoted attributes, an adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML whenever the model authors the control and it can express the required surface; fall back to expanded JSON only for multiline prompts, non-positional metadata, or a concrete CML parse/render failure, never merely from implementation habit. Deterministic Generative App scripts may return ordinary JSON because their source payload does not consume model-output tokens; author and operate those adapters through the `generative-apps` Skill rather than growing a parallel app workflow here. A top-level cell becomes one full-width row, while a nested row groups one or more controls horizontally without a parser-level width cap. Prefer one layout comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format.
+
+### Semantic Row Composition
+
+Model the control surface as an ordered ragged sequence of independently sized rows, not as a rectangular matrix to fill. Rectangular grids are one specialization for genuinely spatial or coordinate-bearing state; most interfaces should vary row width according to hierarchy, grouping, label pressure, and action priority.
+
+- Put controls in one compact row only when they are genuine peers that answer the same local question or form one coherent toolbar/navigation group.
+- Use a singleton full-width row for a structurally independent, pinned, primary, summary, or high-consequence action when separation improves comprehension.
+- Vary row widths intentionally—for example `1 → 2 → 4 → 1 → 2`—and never pad a row with empty, duplicate, or no-op controls merely to produce uniform dimensions.
+- Preserve reading order across rows: orientation and structural navigation first, primary content or choices next, secondary controls afterward, and destructive actions visibly separated when present.
+- Use at most two columns when buttons carry words, phrases, icon-plus-text labels, or other text that must be read; move additional peer choices into more semantic rows rather than compressing four or more textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
+
+Treat vertical extent independently from horizontal density. A genuinely spatial surface may retain many rows—such as an `8×16` field—when vertical continuity, coordinates, and one-glance topology matter; do not paginate merely to make its height match its width. For non-spatial collections, however, a tall button wall should yield to semantic grouping, progressive disclosure, or pagination. Keep compact state and instructions above a tall surface, preserve stable coordinates across regeneration, and avoid repeating prose between rows.
+
+Treat symmetry as an evidence claim about the task. Equal rectangular rows imply equal relationships and stable spatial correspondence; do not make that claim merely because the renderer supports a grid. Infer the task's independent, peer, ordered, hierarchical, and spatial relationships first, then let those relationships determine row boundaries and widths. A non-spatial task should be ragged by default, and its asymmetry should remain visible when that best communicates hierarchy or action weight.
+
+### Layout Catalog
+
+Use this catalog as a shape vocabulary, not a fixed menu of demos:
+
+- `1`: One independent full-width action, destination, summary drill-down, or consequence boundary.
+- `2`: One binary or tightly coupled peer decision; neither control is visually subordinated.
+- `1 → 2`: One orienting or primary action followed by a local peer pair.
+- `2 → 1`: One peer mode/filter pair followed by an independent continuation or detail action.
+- `1 → 2 → N×1`: Pinned structural navigation, compact traversal, then a vertical collection of independently readable items.
+- `1 → 2 → 3 → 1`: Ragged staged control where context, local alternatives, denser short peers, and a separated terminal action have different semantic weight.
+- Repeated `2`: Text-bearing choices distributed down the screen instead of compressed across it.
+- `R×C`: A rectangular layout only when rows and columns map to genuine coordinates, repeated dimensions, or another stable spatial topology; keep `C ≤ 8`, while `R` may be substantially larger when preserving vertical continuity is useful.
+
+Adapt a surface by identifying relationships, grouping only genuine peers, ordering groups by task hierarchy, applying label-pressure limits, and then choosing the least regular layout that remains immediately comprehensible. Do not select a catalog shape first and force the task into it.
+
+Preserve the ordinary admission test: proactively offer an interactive surface even when the user did not request buttons when it materially reduces effort or demonstrates an available capability, but do not manufacture decorative interaction.
+
+### Interaction State And Prompt Compression
+
+- Encode the smallest sufficient action delta in repeated controls. When the visible surface and immediately preceding conversation establish one unambiguous state, a coordinate, symbol, identifier, or short verb can be the entire prompt; do not duplicate the same board, form, or selection state into every button payload.
+- Keep compact prompts semantically closed over their context. If delivery may be delayed, reordered, routed elsewhere, or separated from the state projection, add a stable target or state identity rather than copying a large volatile snapshot.
+- Keep trivial interaction state in the visible conversation. When state becomes too large, long-lived, or error-prone for reliable conversational reconstruction, persist a small human-auditable Markdown state artifact at a deterministic task-owned path and render from it. The artifact belongs to the underlying task or domain, not to this Skill as shadow application state.
+- When transition rules are non-trivial or correctness-sensitive, use a small deterministic state-transition owner—script, module, tool, or existing domain API—that validates `current state + admitted action → next state`; let the model compile the surface from its result instead of informally simulating every transition. Do not create code or files for a trivial one-step interaction.
+- Treat repeated clicks against current state, not stale button appearance. If an action is already consumed or unavailable, keep state unchanged and say so briefly. Preserve an occupied or selected button when spatial layout matters, using its label or selected style as the visual state; omit unavailable controls when layout does not matter. Transport-level disabled buttons are optional, not assumed.
+- Preserve tap-ahead on transports where existing controls remain actionable and rapid clicks queue separate turns. In a source-then-destination interaction, persist the source selection but do not regenerate the board, enumerate destinations, or duplicate controls between the two prompts; emit at most a minimal acknowledgement and let the already visible surface carry the destination click. Regenerate after the completed transition, invalid input, or evidence that the transport cannot preserve the intermediate surface.
+- Resolve coordinate selection by current state rather than rigid click parity. Clicking any currently selectable source selects or replaces the source and then waits; acknowledge a replacement tersely without regenerating the surface. Only a click that is not a selectable source becomes a destination attempt when a source is already selected, at which point the domain owner validates the transition. Without a selected source, a non-source coordinate is a no-op.
+
+```html
+<!-- telegram_button {"label":"🔍 Inspect run","prompt":"Inspect Run run:example read-only, summarize its current status and latest material evidence, then regenerate relevant supervision controls."} -->
+<!-- telegram_button [{⬆️ Up|/}[{⬅️ Previous}{➡️ Next}]{📁 etc|/etc}] -->
+```
+
+Button prompts must:
+
+- Preserve the user's language.
+- Name exact targets when visible context does not make them unambiguous.
+- Express one coherent next intent with the shortest sufficient action delta.
+- 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
+
+Treat a user prompt that is exactly a plausible filesystem path—including `/`—as legitimate intent to render that location through a generated filesystem surface. Resolve and freshly inspect it before display. Directory surfaces use one stable navigation layout:
+
+1. Pin `⬆️ Up` as the first full-width row whenever the current path is not filesystem root; its entire prompt is the exact parent path. Omit Up at `/`.
+2. When page traversal exists, place `⬅️ Previous` and `➡️ Next` together in one compact row immediately after Up, omitting either unavailable direction. Page traversal re-inspects the directory and preserves a fixed 10-entry page size; moving Up opens the parent at page one.
+3. Sort entries by semantic category before pagination: visible directories, hidden directories, visible files, then hidden files; sort names alphabetically within each category. Render at most 10 resulting entry buttons as full-width rows after structural navigation. Each label uses the entry name plus a semantic folder/file emoji, and its entire prompt may be the exact target path because this Skill defines path-only prompts as navigation intent.
+4. Keep visible text to two compact status-style rows such as ``**Path:** `/home/llb` `` and ``**Entries:** `1–10 of 52` ``; do not join metadata with a middle dot and do not duplicate entry names as a plain or monospaced directory listing. Omit Refresh by default because resubmitting the current path already requests fresh rendering.
+
+For pi-telegram, emit the complete filesystem control set—Up, compact page traversal, then current-page entries—in one `telegram_button` JSON matrix rather than repeating one hidden comment per button. If prompt buttons are unavailable or fail to render, preserve the same ordering and pagination as an ordinary numbered text fallback, not a monospaced inventory, so free-form path entry remains sufficient. Show a plain or monospaced directory listing instead only when the user explicitly requests it or durable user Knowledge establishes that presentation preference. Never preview credential stores, private keys, browser profiles, cookies, tokens, wallets, or other 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. 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/node_modules/@llblab/pi-telegram/skills/generative-apps/SKILL.md

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

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

@@ -0,0 +1,149 @@
+---
+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
+
+Before compiling assistant-authored controls, inspect already-loaded capability guidance for an advertised maintained Generative App or view/controller adapter. When that owner-provided view exists and the current intent concerns repeated interaction, load and follow the bundled `generative-apps` Skill and prefer binding or invoking the existing app over synthesizing one-shot prompt buttons. This is a routing breadcrumb, not permission for the bridge to discover capability-specific apps, own their state, or hard-code their identities.
+
+Otherwise, on Telegram turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not wait for an explicit button request, and accept zero controls when its admission rules reject decorative or low-value UI.
+
+`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" -->
+<!-- telegram_button [{"label":"⬆️ Up","prompt":"/"},[{"value":"⬅️ Previous"},{"value":"➡️ Next"}],{"label":"📁 etc","prompt":"/etc"}] -->
+<!-- telegram_buttons [[{"value":"Approve"},{"value":"Reject"}]] -->
+<!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
+```
+
+- `telegram_button` accepts one JSON object, an adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML for model-authored controls whenever it can express the required surface; use expanded JSON only for multiline prompts, non-positional metadata, or a concrete parse/render failure fallback, never merely from implementation habit. Deterministic Generative App scripts may use ordinary JSON because their output does not spend model tokens. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`.
+- Use `label` plus a self-contained `prompt`, or non-empty `value` when both are identical.
+- Optional `selected_style` is `primary` (default), `success`, or `danger`; style never suppresses prompt admission.
+- If button comments form the whole reply, the bridge supplies the standard choice heading.
+- 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.
+
+## Generative Apps
+
+Load and follow the bundled `generative-apps` Skill when work designs, authors, reviews, installs, replaces, invokes, or diagnoses a Generative App. Generative Apps compile stable repeated interaction into generated button views that may mix bound methods executed before Pi queue admission with ordinary model prompts; this bridge Skill continues to own Telegram transport, target authority, delivery, general button syntax, and turn behavior rather than duplicating the application workflow.
+
+## Configurable Handlers And Extensions
+
+Prefer no-code command-template configuration in `telegram.json` before adding a companion extension:
+
+- `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.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@llblab/pi-kit",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Version-pinned distribution of LLBLAB extensions for Pi",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extensions",
+    "kit",
+    "llblab"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/llblab/pi-kit.git"
+  },
+  "homepage": "https://github.com/llblab/pi-kit",
+  "bugs": {
+    "url": "https://github.com/llblab/pi-kit/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "audit": "npm audit --omit=dev",
+    "pack:check": "npm pack --dry-run",
+    "validate": "npm test && npm run audit && npm run pack:check"
+  },
+  "files": [
+    "README.md",
+    "AGENTS.md",
+    "BACKLOG.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@llblab/pi-actors": "0.49.1",
+    "@llblab/pi-codex-usage": "0.9.2",
+    "@llblab/pi-grow-loop": "0.7.1",
+    "@llblab/pi-telegram": "0.36.1"
+  },
+  "bundledDependencies": [
+    "@llblab/pi-actors",
+    "@llblab/pi-codex-usage",
+    "@llblab/pi-grow-loop",
+    "@llblab/pi-telegram"
+  ],
+  "pi": {
+    "extensions": [
+      "./node_modules/@llblab/pi-actors/dist/pi-actors/index.js",
+      "./node_modules/@llblab/pi-codex-usage/index.ts",
+      "./node_modules/@llblab/pi-grow-loop/index.ts",
+      "./node_modules/@llblab/pi-telegram/index.ts"
+    ],
+    "skills": [
+      "./node_modules/@llblab/pi-actors/dist/skills",
+      "./node_modules/@llblab/pi-grow-loop/skills",
+      "./node_modules/@llblab/pi-telegram/skills"
+    ]
+  }
+}