tinyhat-local-app-sharing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Tinyhat Visuals

A **Visual** is a visual page you create and share with the user. Use Visuals as a
communication and reporting tool when a chart, dashboard, visual summary,
interactive explanation, or preview would make your answer easier to
understand than text alone.

## Goal

Turn work that benefits from visual storytelling into a clear, polished page
the user can explore, while presenting it as a Visual rather than exposing the
technical machinery used to create or share it.

Call `tinyhat_local_app_sharing` after the page is running on this Computer.
Keep implementation details such as localhost, servers, and port numbers out of
the user-facing message. Present the result as a Visual and explain what the user
will learn or be able to review there.

Good uses include:

- a chart that makes a trend or comparison clear;
- a visual report or status dashboard;
- an interactive table, timeline, map, or model;
- a design, document, or feature preview;
- a small purpose-built page that communicates a result more clearly.
- an owner-requested local admin or development page that the user needs to
  review or operate privately.

Do not create a Visual just to repeat a short answer that is already clear in
text.

## Create a Visual

1. Decide what the Visual should communicate and give it a descriptive,
   user-facing label such as `Weekly revenue report` or `Campaign forecast`.
2. Build and start the page locally. Internally determine its numeric loopback
   port; never pass a hostname or URL to the tool.
3. Create the Visual:

```json
{
  "action": "create",
  "port": 3000,
  "label": "Weekly revenue report",
  "button_label": "Open report",
  "ttl_seconds": 900
}
```

4. Tell the user what the Visual contains and that it is ready. Do not mention
   its port, server, localhost, or the underlying application unless the user
   explicitly asks for technical details.

The tool sends the owner a native Telegram Mini App button. Its default label
is **Open visual**. If the user asks for specific wording, pass it as
`button_label`. Otherwise, use a short content-specific action when it improves
clarity, such as **Open report**, **Open forecast**, or **Review dashboard**.
Never call the shared result an app in user-facing button text. When
`telegram_button_sent` is `true`, do not send a duplicate button. When it is
`false`, send the returned link, expiry, and, for a private Visual, the four-digit
access code yourself.

### Choose access deliberately

Visuals are private by default. With `"access_mode": "code"`, a normal browser
requires the four-digit code, while the assigned owner's valid Telegram
credentials can open the Visual directly. If Telegram credentials are absent or
invalid, the same code form is shown.

Use `"access_mode": "link"` only when the user explicitly asks for a public
Visual or a Visual anyone with the complete link can open:

```json
{
  "action": "create",
  "port": 3000,
  "label": "Public campaign report",
  "ttl_seconds": 900,
  "access_mode": "link"
}
```

A public Visual returns no access code and opens for anyone holding the complete
link, in Telegram or any other browser.

Admin consoles, credential-management pages, session inspectors, and other
potentially sensitive interfaces must use the private `"code"` mode. They are
valid Visuals when the owner asks to review or use that exact page; do not refuse
them merely because they are administrative. Never make one public, and do not
navigate or expose unrelated private sections on the user's behalf.

### Choose encryption deliberately

Ordinary Visuals use normal HTTPS transport and render directly inside Telegram,
including Telegram on iOS. This includes code-protected interactive pages unless
the user asks for browser-to-Computer encryption. Set `"encryption_mode":
"encrypted"` when the user requests that additional protection:

```json
{
  "action": "create",
  "port": 3000,
  "label": "Encrypted financial report",
  "ttl_seconds": 900,
  "encryption_mode": "encrypted"
}
```

The encrypted link contains a Computer-key fingerprint in its URL fragment;
preserve it exactly. Telegram iOS may need to open an encrypted Visual in the
device browser when its embedded WebView lacks the required security feature.

## List or expire Visuals

List active Visuals when the user asks what is currently shared:

```json
{"action": "list"}
```

From tinyhat-ai/tinyhat, MIT.

More from tinyhat-ai/tinyhat