@monkey-mini-app/dsh-mini-app 0.1.0 → 0.1.4

package/skills/monkey-mini-app/references/ctx.md

@@ -1,35 +1,98 @@
 # RunContext `ctx`
 
-每个 `api.*` / `onMount` / `onUnmount` 都拿到同一个 `ctx`。
+Every `api.*` method (`defineApp({ api })` keys) receives the same `ctx`.
 
-## 总是可用
+## Always available
 
-| API | 返回 | 说明 |
-|-----|------|------|
-| `ctx.appId` | string | 当前小程序 reverse-DNS id |
-| `ctx.appDir` | string | 当前小程序绝对目录（`runtime/apps/<appId>`） |
-| `ctx.storage.get(key)` | value 或 `null` | `storage/main.storage.json` |
-| `ctx.storage.set(key, value)` | | JSON 可序列化 |
+| API | Returns | Notes |
+|-----|---------|-------|
+| `ctx.appId` | string | Reverse-DNS id of the running mini-app |
+| `ctx.appDir` | string | Absolute directory of this app (`runtime/apps/<appId>`) |
+| `ctx.storage.get(key)` | value or `null` | Backed by `storage/main.storage.json` |
+| `ctx.storage.set(key, value)` | | Value must be JSON-serialisable |
 | `ctx.storage.delete` / `clear` | | |
-| `ctx.storage.table(name)` | 同样 API | `{name}.storage.json`，name=`[A-Za-z0-9_-]` |
-| `ctx.state` | object | 内存，与 defineDashboard.state 同一引用 |
-| `ctx.config` | `{ theme, palette, chatLanguage, hostPort, llm }` | 只含本 Host 配置（设置页 / 顶栏配色可改），**不是** dsh 设置 dump。`theme`=`light`/`dark`；`palette`=`default`/`ocean`/`violet`/`slate`（默认/海蓝/青紫/石墨） |
-| `ctx.credentials` | `Record<string,string>` | 声明过的密钥 |
+| `ctx.storage.table(name)` | same API | Independent table in the same app (`{name}.storage.json`); `name` = `[A-Za-z0-9_-]` |
+| `ctx.storage.bytes()` | number | Bytes this table occupies — for your own "is this getting big" logging |
+| `ctx.state` | object | In-memory; the same reference as `defineApp.state` |
+| `ctx.config` | `{ theme, palette, chatLanguage, hostPort, llm }` | This host's own settings only (settings page / top bar), **not** a dsh settings dump. `theme` = `light`\|`dark`\|`system` (a *preference* — resolve `system` yourself if you need a concrete mode); `palette` = `default`\|`ocean`\|`violet`\|`slate` |
+| `ctx.credentials` | `Record<string,string>` | Secrets **supplied by the host** — a mini-app cannot declare them. `{}` when the host has no credential service: read by key, show a usable empty state when missing, never invent key names |
 | `ctx.log(...args)` | | console |
-| `ctx.signal` | AbortSignal 或 undefined | 当前调用的取消信号（chat 点「停止」时 abort）。长任务在批次/循环间 `if (ctx.signal?.aborted) throw new Error("cancelled")`，`sleep` 也传它 |
-| `ctx.push(method, params)` | | 常为 no-op |
-| `ctx.system.metrics()` | os 快照 | |
+| `ctx.signal` | AbortSignal or undefined | Cancel signal for the current call (aborted when the user hits "stop"). In long jobs check `if (ctx.signal?.aborted) throw new Error("cancelled")` between batches/loops and pass it to `sleep` too |
+| `ctx.push(name, params)` | SSE to this app's UI | Live channel for `useApp().on(name, cb)`. Fire-and-forget, never throws; `params` must be JSON-serialisable. Host keeps the last 200 events **per app**, so a reconnecting or later-opened UI replays them (`Last-Event-ID`) |
+| `ctx.system.metrics()` | os snapshot | |
 
-## Host 能力
+## Typed events
 
-| API | 签名 | 返回 | Fallback | 失败 |
-|-----|------|------|----------|------|
-| `http(url)` / `http(url, opts)` | opts：`method?` `headers?` `query?` `body?` `timeout?`（默认 8s）。自动组合 `ctx.signal`（停止即中断） | `{ ok, status, headers, text, json }`。`json` 仅当 Content-Type 含 json 且能 parse，否则 `null`。HTTP 4xx/5xx **不 throw**，看 `ok`/`status`。只允许 http/https | Node `fetch` | `http: timeout` / `http: only http/https` / `http: response too large` / `http: …` |
-| `bash(command)` | string | `{ stdout, stderr, exitCode }` | 本地 `bash -c` 120s/8MB → dsh `shell.run`。给本机命令用，**不要** `curl` | `bash unavailable` |
-| `tool(name, args)` | args **普通对象**，禁止 `{input}` | **string** | dsh tools | `tool: ctx.tools not available` |
-| `mcp(name, args?)` | 不要 `mcp_` 前缀 | string | `tool(name)` 再 `tool("mcp__"+name)`。dsh 登记名是 `mcp__<server>__<tool>`，例如 `ctx.mcp("everything__echo", { message: "hi" })` | 第一次错误 |
-| `llm(prompt, opts?)` | 见下方 **ModelCallOptions** | **string** | dsh `llm.stream` | `llm: no dsh model service` / `llm stream empty` |
-| `agent(goal, opts?)` | **ModelCallOptions** + `onEvent?`（见下） | **string** | dsh one-shot agent（与聊天 session 隔离）；可用工具循环。不要用多次 `ctx.llm` 假装 agent | `agent: … unbound` / `empty result` / `cancelled` |
+`ctx.push("stage", …)` and `useApp().on("stage", …)` are joined by a **string**, and no type can
+cross the seam: `ui.tsx` may not import `main.api.ts` (AGENTS.md → Hard constraints 1), so the
+compiler cannot see that the two names must agree. A typo produces an app that renders perfectly
+and never updates.
+
+Declare the names once in `shared/` — the one tree both sides may import — and let the literal be
+the source of truth:
+
+```ts
+// shared/events.ts  (pure isomorphic: no React, no ctx, no DOM)
+export const EV = {
+  progress: "progress",
+  latest: "latest",
+} as const;
+
+export type Events = {
+  progress: { running: boolean; step: string; done: number; total: number; error?: string };
+  latest: { items: { title: string }[]; digest: { headline: string; bullets: string[] } | null; at: number };
+};
+
+export type Progress = Events["progress"];
+export type Payload = Events["latest"];
+```
+
+```ts
+// api/scan.ts  (or main.api.ts)
+import { EV, type Progress } from "../shared/events";
+const next: Progress = { running: true, step: "fetch", done: 1, total: 3 };
+ctx.push(EV.progress, next);
+```
+
+```tsx
+// ui.tsx
+import { EV, type Progress } from "./shared/events";
+const { on } = useApp();
+useEffect(() => on(EV.progress, (p) => setProgress(p as Progress)), [on]);
+```
+
+Rename `EV.progress` once — both sides move. The `Events` map is the payload contract.
+Worked example: `templates/radar/shared/events.ts`. `mini_app_reload` still notices a leftover
+string literal that nothing pushes (`"stga"`); names that go through `EV.*` are the source of truth.
+
+## Choosing a table
+
+Tables are independent namespaces over the same API: `ctx.storage.table("reads")` gives you a table
+whose keys cannot collide with the default one. There is no `keys()`, no enumeration and no query —
+every method addresses exactly one key. Each table is one JSON file; every `set` rewrites that file,
+so **what shares a table is a real cost**, not just a naming preference:
+
+| Data | Put it in |
+|---|---|
+| A handful of settings (source list, thresholds, UI prefs) | default `ctx.storage` — small, and you read it whole anyway |
+| Anything that **grows**: fetched article bodies, run logs, activity, per-day records, snapshots | its own `ctx.storage.table("reads")` |
+| Both of the above in one app | two tables — otherwise your settings rewrite rides along with every log line |
+
+Large lists should be **one key per row** (`await rows.set(id, row)`), not one giant array under a
+single key. `ctx.storage.bytes()` answers "how big is this table right now". Past roughly 512 KB the
+host surfaces a **panel banner** (writes are never blocked) with the heaviest keys and a copy-paste
+prompt you can hand to an agent to do the split.
+
+## Host capabilities
+
+| API | Signature | Returns | Fallback | Failure |
+|-----|-----------|---------|----------|---------|
+| `http(url)` / `http(url, opts)` | opts: `method?` `headers?` `query?` `body?` `timeout?` (default 8s). Automatically combines `ctx.signal` (stop aborts the request) | `{ ok, status, headers, text, json }`. `json` is set only when Content-Type contains json **and** parsing succeeds, else `null`. HTTP 4xx/5xx **do not throw** — check `ok`/`status`. http/https only | Node `fetch` | `http: timeout` / `http: only http/https` / `http: response too large` / `http: …` |
+| `bash(command)` | string | `{ stdout, stderr, exitCode }` | Local `bash -c`, 120s/8MB → dsh `shell.run`. For machine commands; **do not** shell out to `curl` | `bash unavailable` |
+| `tool(name, args)` | args is a **plain object**, never `{input}` | **string** | dsh tools | error containing `tool:` when the host exposes no tool service |
+| `mcp(name, args?)` | no `mcp_` prefix | string | tries `tool(name)` then `tool("mcp__"+name)`. dsh registers `mcp__<server>__<tool>`, e.g. `ctx.mcp("everything__echo", { message: "hi" })` | first-attempt error |
+| `llm(prompt, opts?)` | see **ModelCallOptions** below | **string** | dsh `llm.stream` | `llm: no dsh model service` / `llm stream empty` |
+| `agent(goal, opts?)` | **ModelCallOptions** + `onEvent?` (below) | **string** | dsh one-shot agent (isolated from the chat session); may loop over tools. Do not fake an agent with repeated `ctx.llm` calls | `agent: … unbound` / `empty result` / `cancelled` |
 
 ```ts
 const r = await ctx.http("https://example.com/api", {
@@ -42,18 +105,19 @@ if (!r.ok) throw new Error("HTTP " + r.status);
 const data = r.json ?? JSON.parse(r.text);
 ```
 
-POST：`ctx.http(url, { method: "POST", body: { a: 1 } })`（对象会 JSON 编码）。RSS/HTML 用 `r.text`。
+POST: `ctx.http(url, { method: "POST", body: { a: 1 } })` (objects are JSON-encoded). For RSS/HTML use `r.text`.
 
-### ModelCallOptions（`llm` / `agent` 共用最小集合）
+### ModelCallOptions (shared minimum for `llm` / `agent`)
 
 ```ts
 type ModelCallOptions = {
-  provider?: string;   // 默认跟 dsh 当前模型；可不传
+  provider?: string;   // defaults to the host's current model; usually omitted
   model?: string;
   system?: string;
-  schema?: object;     // JSON Schema；要对象时用，再 JSON.parse 返回值
-  maxTokens?: number;
-  signal?: AbortSignal; // api 调用里通常已有 ctx.signal，可省略
+  schema?: object;     // JSON Schema — use it when you need an object, then JSON.parse the result
+  maxTokens?: number; // host default 4096 when unset — raise it for wide arrays
+  retryTimes?: number; // attempts IN TOTAL (1 = no retry); llm default 3, agent default 1
+  signal?: AbortSignal; // ctx.signal already exists inside an api call, so this is optional
 };
 
 // llm
@@ -66,23 +130,29 @@ await ctx.agent(goal, opts?: ModelCallOptions & {
   onEvent?: (ev: AgentEvent) => void;
   /**
    * Working dir mode (default "process").
-   * app = 当前小程序目录；process = dsh 启动目录；temp = 临时目录；custom = 配 cwd 绝对路径。
-   * 只传 cwd 路径 ⇒ 视为 custom。cwd + 非 custom 的 cwdType ⇒ 报错。
+   * app = this mini-app's directory; process = host start dir; temp = temp dir; custom = absolute cwd.
+   * Passing only a cwd path implies custom. cwd + a non-custom cwdType is an error.
    */
   cwdType?: "app" | "process" | "temp" | "custom";
-  cwd?: string; // 绝对路径；custom 必填，或单独传
+  cwd?: string; // absolute path; required for custom
 }): Promise<string>
 ```
 
-路由：`opts.provider/model` → dsh 当前 `agent-default-model` → `deepseek-official` / `deepseek-v4-flash`。不必改 `host.json`。
+Routing: `opts.provider/model` → host `agent-default-model` → `deepseek-official` / `deepseek-v4-flash`. No `host.json` edit needed.
 
-### `opts.schema`（llm + agent）
+### `opts.schema` (llm + agent)
 
-软约束「只回 JSON」+ 剥 markdown；**返回仍是 string**，`JSON.parse`。例子 → [llm-json.md](llm-json.md)。提示宜短，约束交给 schema。
+A soft "reply with JSON only" constraint plus fence stripping — **the return value is still a string**, you `JSON.parse` it. Examples → [llm-json.md](llm-json.md). Keep the prompt short: state the task, push the constraints into `schema`.
 
-### `opts.onEvent`（仅 agent）— 过程事件完整形状
+### `opts.onEvent` (agent only) — full event shapes
 
-返回值仍是最终 string；`onEvent` 只观测过程。UI 用 storage 轮询即可：
+The return value is still the final string; `onEvent` only observes the run. To show progress in the UI pass
+`streamTo: "agent"` — the host mirrors every event as `ctx.push("agent", event)`:
+
+```ts
+await ctx.agent(goal, { streamTo: "agent", maxIterations: 12 });
+// UI: on("agent", (ev) => …) — see templates/runner
+```
 
 ```ts
 type AgentEvent =
@@ -91,37 +161,37 @@ type AgentEvent =
   | { type: "tool"; phase: "start" | "end"; name: string; args?: unknown; result?: unknown }
   | { type: "turn"; phase: "start"; turn: number }
   | { type: "turn"; phase: "end"; turn: number; reason?: { kind: string; error?: unknown; reason?: unknown } }
-  // reason.kind 常见：completed | blocked | error | aborted | max-tokens
+  // common reason.kind: completed | blocked | error | aborted | max-tokens
   | { type: "error"; message: string }
   | { type: "done"; text: string };
 
 const trace = [];
-const text = await ctx.agent("根据材料给出洞察", {
+const text = await ctx.agent("Summarise the material into insights", {
   schema: { type: "object", properties: { summary: { type: "string" } }, required: ["summary"] },
   onEvent: (ev) => {
     trace.push(ev);
-    void ctx.storage.set("agentTrace", trace);
+    ctx.push("agentEvent", ev); // live to the UI; do NOT persist per event — that rewrites the
+                                 // whole file once per step, for a buffer nobody reads mid-run
   },
 });
 const insight = JSON.parse(text);
 ```
 
-`ctx.agent` 与用户聊天 session 隔离（ephemeral，跑完 dispose）。
-
+`ctx.agent` is isolated from the user's chat session (ephemeral, disposed when it finishes).
 
-## 列出当前 tool
+## Listing live tools
 
-**仅当 main.api.ts 会调用 `ctx.tool` 时**才调聊天工具 `mini_app_list_ctx_tools`。纯 storage / http / bash / llm 的 app 不要调。
+Call the chat tool `mini_app_list_ctx_tools` **only when `main.api.ts` will actually use `ctx.tool`**. Skip it for storage / http / bash / llm-only apps.
 
-后端也可用 `ctx.listTools()`。不要假设 read/write/bash 一定存在或参数名固定。
+The backend can also call `ctx.listTools()`. Never assume `read` / `write` / `bash` exist or that their parameter names are stable.
 
-## 长耗时任务：必须采样 + 响应取消
+## Long jobs: sample and honour cancellation
 
-多源抓取 × LLM 分析这类任务，**不要全量跑**：
+Multi-source fetch × LLM analysis — **do not run it in full**:
 
-- **采样走通流程**：10 个 RSS 取 2 个有代表性的源（如主站 + 高热度站）；批次只跑 1 批（如最热的 16~24 条）验证全链路；其余用启发式兜底。告诉用户「先跑样例，全量可后续加」。
-- **批次上限**：LLM 分析批次数硬上限（如 `MAX_BATCHES = 2`），避免单次调用跑 10 分钟。
-- **必须响应取消**：循环/批次/sleep 处检查 `ctx.signal`：
+- **Sample the flow end to end**: of 10 RSS feeds take 2 representative sources; of N batches run 1 (e.g. the hottest 16–24 items) to prove the whole path; fall back to heuristics for the rest. Tell the user "sample first, full run is a switch away".
+- **Hard batch cap**: limit LLM batches (e.g. `MAX_BATCHES = 2`) so one call never runs ten minutes.
+- **Always honour cancellation**:
   ```ts
   async function sleep(ms: number, signal?: AbortSignal) {
     return new Promise((resolve) => {
@@ -130,8 +200,8 @@ const insight = JSON.parse(text);
       signal?.addEventListener("abort", () => { clearTimeout(t); resolve(); }, { once: true });
     });
   }
-  // 批次间
+  // between batches
   if (ctx.signal?.aborted) throw new Error("cancelled");
   await sleep(400, ctx.signal);
   ```
-- **异步进度**：长任务提供 `scanStatus`/`progress` 类方法（写入 storage），UI 轮询；`scan` 本身 fire-and-forget 立即返回「已启动」。
+- **Async progress**: `ctx.push(name, payload)` from the background job; the UI fetches one snapshot on mount (`runStatus`) and then applies pushed events — do **not** `setInterval` a status method. Keep writing the snapshot to storage as well, so an app opened cold still shows the last state. Buffer is 200/app: if the UI sees an `app:gap` (`onAny` receives `{ name: "*", data: { gap: true } }`), refetch the snapshot.

package/skills/monkey-mini-app/references/eval.md

@@ -0,0 +1,115 @@
+# Asking the rendered view (`mini_app_view_eval`)
+
+`mini_app_errors` tells you an app crashed. This tells you **what it drew** — which is the
+question left over once the build is green and the panel shows something, just not the thing
+you meant.
+
+You send JavaScript; it runs inside the app's rendered iframe; you get text back. Nothing is
+pre-decided about what to look at, so there is no "the tool doesn't support that" case.
+
+## When to ask, and when not to
+
+| Situation | Do this instead |
+|---|---|
+| It compiled and the panel is blank / errored | `mini_app_errors` — cheaper, and a crash is already reported to you |
+| "Did this Tailwind class / theme token actually apply?" | ask the view (below) |
+| "Is this node zero-size / hidden / not in the tree?" | ask the view |
+| "Is this centred? Does it look good?" | **do not ask the view** — there are no pixels here. Describe the change and let the user judge |
+| Backend returned the wrong thing | `mini_app_call` — no browser involved |
+
+It needs a **live iframe**: `mini_app_open({ appId })` first. If nothing is rendering the app
+you get `view: "not-open"`, not an empty answer.
+
+Every query runs on a budget: `timeoutMs` (default 1500, capped at 8000), echoed back as
+`budgetMs` so a near-miss is visible. If it expires, the host asks your view a trivial question
+and the answer decides what you're told: `pending` means the page is healthy and your expression
+is still running — raise `timeoutMs` or split the click-wait-assert into separate calls;
+`stuck` means even the probe went unanswered, i.e. the main thread is genuinely blocked.
+
+## The three names you get
+
+```js
+mma.$(sel, root?)     // Element | null
+mma.$$(sel, root?)    // Array<Element>  — a real array, so .map() / .filter() / [0] work
+mma.selector(el)      // a CSS string you can hand straight back to mma.$()
+```
+
+Everything else is standard DOM (`textContent`, `dataset`, `getBoundingClientRect`,
+`classList`, `closest`, `children`). Host-side data is one same-origin `fetch` away:
+
+```js
+const r = await fetch("/api/app/com.example.todo/errors");
+return (await r.json()).errors.map((e) => e.message);
+```
+
+`code` is an **async function body**, so it must `return`. Omit it for the default, which is
+`return mma.$("#root")` — a shallow tree, and the cheapest way to see what you drew.
+
+## Recipes
+
+```js
+// 1. Did the class land? (compare the two colours, do not eyeball the name)
+const el = mma.$("button.btn");
+const cs = getComputedStyle(el);
+return { class: el.className, bg: cs.backgroundColor, color: cs.color };
+
+// 2. Which nodes rendered to nothing? (a class that never compiled, or a false condition)
+return mma.$$("#root *").filter((n) => n.getBoundingClientRect().width === 0 && n.children.length === 0)
+  .map((n) => mma.selector(n) + " " + n.className);
+
+// 3. Something is off-screen — find it by geometry, not by guessing the layout
+return mma.$$("#root *").filter((n) => { const b = n.getBoundingClientRect();
+  return b.right > innerWidth + 1 || b.bottom > innerHeight + 1; }).map(mma.selector);
+
+// 4. Walk deeper than the default 2 levels: return the node itself
+return mma.$(".toolbar");
+
+// 5. Is a hidden branch the reason?
+return mma.$$(".notes").map((n) => ({ sel: mma.selector(n), display: getComputedStyle(n).display }));
+```
+
+Pattern: **`$$` to find, `selector` to name, `$` to go back in.** A list of elements comes
+back as one line each without children — that is a locator, and it is deliberately cheap;
+return one of those nodes to see its subtree.
+
+## Reading the answer
+
+```
+# 6 lines shown of 6 in subtree · 1 query hit · depth 2 · coords: viewport px (scrolls with page) · viewport 1024x768 · 0.3KB · 4ms
+div#root.panel.flex  x=16 y=64 w=380 h=812  (2 children)
+  h2.title  x=16 y=64 w=200 h=24  "Panel"
+  aside.notes  x=16 y=564 w=380 h=212  (1 child)  display:none
+    +2 deeper levels not shown — return that node to go on
+```
+
+* Containers report `(N children)`, never their whole text — a panel's text is the page.
+* `x= y= w= h=` are **viewport pixels** (they move with scroll), stated in the header.
+* `display:none` / `visibility:hidden` / `opacity:0` / `detached` are flags, not bugs. An
+  element with no box has no geometry to complain about.
+* The header states how much you got. If it says `STOPPED by bytes`, the rest is missing.
+
+## When it fails, `view` says whose fault it is
+
+| `view` | Meaning | Next step |
+|---|---|---|
+| `live` + `ok: false` | your JavaScript failed — `error.kind` is `syntax` or `runtime`, with `line`/`source`/`caret` into **your** code | fix the query |
+| `not-open` | nothing is rendering this app | `mini_app_open`, then retry |
+| `runner-not-booted` | the iframe exists but its script never ran | the bundle or the page is broken → `mini_app_errors`, then `mini_app_open` |
+| `stuck` | the script ran and then stopped answering | the main thread is blocked (an app loop, or one of yours) — **no tool fixes this**: ask the user to reload the tab |
+
+The distinction between the last three matters: only `not-open` is fixed by opening, and only
+`stuck` means something is running that never ends — which needs a human, not another tool call.
+
+## Limits, stated plainly
+
+* **A synchronous infinite loop freezes more than the query.** The executor never gets the
+  thread back, so nothing can interrupt it — and the wedged iframe blocks the whole panel
+  page with it, which means no tool call can recover it. If you send a loop that does not
+  terminate, tell the user to reload the tab. Prefer `mma.$$` + `.filter` / `.map` over
+  hand-rolled walks; they are shorter and they terminate.
+* The reply is capped at `min(maxBytes, 6144)` — about 1.5 k tokens. If you need more, ask a
+  narrower question rather than raising the cap; four small queries beat one big dump.
+* Not a screenshot. No pixels, no "is this pretty", no cross-origin frames (an `<iframe>` in
+  your app is a different document — its subtree is reported as one node).
+* It reads the **live** DOM, so an app that loads data on mount answers differently before and
+  after its fetch settles. If a query comes back emptier than expected, ask again.

package/skills/monkey-mini-app/references/examples/alert/alert-01.tsx

@@ -0,0 +1,17 @@
+/**
+ * @exampleOf Alert
+ * @title Alert
+ * @scenario Inline, non-blocking notice inside a page or panel — title + description, colours follow the semantic theme. Use for 'saved', '2 checks failed'; reach for Toast for transient confirmations and Dialog when the user must acknowledge.
+ */
+import { Alert, AlertDescription, AlertTitle } from "@monkey-mini-app/ui";
+
+export default function Alert01Example() {
+  return (
+    <>
+      <Alert>
+        <AlertTitle>Heads up</AlertTitle>
+        <AlertDescription>Something needs attention.</AlertDescription>
+      </Alert>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/aspect-ratio/aspect-ratio-01.tsx

@@ -0,0 +1,16 @@
+/**
+ * @exampleOf AspectRatio
+ * @title AspectRatio
+ * @scenario A media/skeleton placeholder that must keep a fixed ratio (16/9 here) while its container resizes — prevents layout shift when images or embeds load late.
+ */
+import { AspectRatio } from "@monkey-mini-app/ui";
+
+export default function AspectRatio01Example() {
+  return (
+    <>
+      <div className="w-48">
+        <AspectRatio ratio={16 / 9} className="rounded-lg bg-muted" />
+      </div>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/attachment/attachment-01.tsx

@@ -0,0 +1,19 @@
+/**
+ * @exampleOf Attachment
+ * @title Attachment
+ * @scenario A file chip in a list — icon, name, meta line and a remove affordance; the shape used for uploaded files or chat attachments.
+ */
+import { Attachment, AttachmentContent, AttachmentDescription, AttachmentTitle } from "@monkey-mini-app/ui";
+
+export default function Attachment01Example() {
+  return (
+    <>
+      <Attachment>
+        <AttachmentContent>
+          <AttachmentTitle>report.pdf</AttachmentTitle>
+          <AttachmentDescription>PDF · 120 KB</AttachmentDescription>
+        </AttachmentContent>
+      </Attachment>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/breadcrumb/breadcrumb-01.tsx

@@ -0,0 +1,31 @@
+/**
+ * @exampleOf Breadcrumb
+ * @title Breadcrumb
+ * @scenario Deep-navigation path where the current level is not a link and separators are automatic; use for drill-down pages (org / team / project / run).
+ */
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "@monkey-mini-app/ui";
+
+export default function Breadcrumb01Example() {
+  return (
+    <>
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>
+            <BreadcrumbLink href="#">Home</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbPage>Demo</BreadcrumbPage>
+          </BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/bubble/bubble-01.tsx

@@ -0,0 +1,16 @@
+/**
+ * @exampleOf Bubble
+ * @title Bubble
+ * @scenario One side of a chat transcript — agent vs user bubble without hand-rolling alignment or spacing.
+ */
+import { Bubble, BubbleContent } from "@monkey-mini-app/ui";
+
+export default function Bubble01Example() {
+  return (
+    <>
+      <Bubble>
+        <BubbleContent>Can you rerun login-spec?</BubbleContent>
+      </Bubble>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/button-group/button-group-01.tsx

@@ -0,0 +1,23 @@
+/**
+ * @exampleOf ButtonGroup
+ * @title Button / ButtonGroup
+ * @scenario Related buttons fused into one visual unit (joined borders/radius) — e.g. Save + dropdown Split action; distinct from Toolbar/ToggleGroup because there is no pressed state.
+ */
+import { Button, ButtonGroup } from "@monkey-mini-app/ui";
+
+export default function ButtonGroup01Example() {
+  return (
+    <>
+      <div className="flex flex-wrap gap-2">
+        <Button data-testid="primitive-button">Default</Button>
+        <Button variant="outline">Outline</Button>
+        <Button variant="ghost">Ghost</Button>
+        <Button variant="destructive">Destructive</Button>
+        <ButtonGroup>
+          <Button variant="outline">One</Button>
+          <Button variant="outline">Two</Button>
+        </ButtonGroup>
+      </div>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/card/card-01.tsx

@@ -0,0 +1,19 @@
+/**
+ * @exampleOf Card
+ * @title Card
+ * @scenario The default content container: header (title + description), body, optional footer. Start here for any panel before writing custom borders/padding.
+ */
+import { Card, CardContent, CardHeader, CardTitle } from "@monkey-mini-app/ui";
+
+export default function Card01Example() {
+  return (
+    <>
+      <Card>
+        <CardHeader>
+          <CardTitle>Card</CardTitle>
+        </CardHeader>
+        <CardContent>Interactive container.</CardContent>
+      </Card>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/charts-blocks.md

@@ -0,0 +1,15 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Examples · charts-blocks
+
+Multi-component demos: layout/pattern recipes with no single subject component.
+Copy the whole file into `ui.tsx` (or split it) — imports are `react` + `@monkey-mini-app/ui` only.
+
+| example | what it shows | scenario |
+|---|---|---|
+| [`misc-charts-blocks-01.tsx`](./misc-charts-blocks/misc-charts-blocks-01.tsx) | PageHeader / FilterBar | Page chrome working together: PageHeader (title + description + primary action) with a FilterBar row beneath — the standard screen top for list/monitor pages. |
+| [`misc-charts-blocks-02.tsx`](./misc-charts-blocks/misc-charts-blocks-02.tsx) | StatCard / TrendCard / Sparkline / Gauge / ProgressRing | KPI strip: StatCard for numbers with delta, TrendCard adding a sparkline, plus Sparkline/Gauge/ProgressRing for compact meters in one row. |
+| [`misc-charts-blocks-03.tsx`](./misc-charts-blocks/misc-charts-blocks-03.tsx) | Donut / StackedBar / Radar | Recharts-backed set: DonutChart for share-of-total, StackedBarChart for composition over time, RadarChart for multi-axis scorecards — all fed plain arrays. |
+| [`misc-charts-blocks-04.tsx`](./misc-charts-blocks/misc-charts-blocks-04.tsx) | StatusBadge / SeverityChip / EnvBadge | Status vocabulary in one view: StatusBadge (pass/fail/flaky, lowercase statuses), SeverityChip (P0–P3) and EnvBadge (dev/stg/prd) so triage rows read consistently. |
+| [`misc-charts-blocks-05.tsx`](./misc-charts-blocks/misc-charts-blocks-05.tsx) | ActivityFeed / NotificationCenter / CommentThread / TestStepList | Feed-style blocks: ActivityFeed, NotificationCenter and CommentThread share an items-in / rows-out shape; TestStepList shows pass/fail steps per case. |
+| [`misc-charts-blocks-06.tsx`](./misc-charts-blocks/misc-charts-blocks-06.tsx) | DescriptionList / RequestInspector / Terminal / FileTree / AttachmentGallery | Inspect/debug kit on one screen: DescriptionList for metadata, RequestInspector for a method/url/response, Terminal for command output, FileTree and AttachmentGallery for artifacts. |

package/skills/monkey-mini-app/references/examples/code-block/code-block-01.tsx

@@ -0,0 +1,14 @@
+/**
+ * @exampleOf CodeBlock
+ * @title CodeBlock
+ * @scenario Read-only highlighted source with filename, language badge and copy button (shiki via CDN); use when the code is shown, not edited.
+ */
+import { CodeBlock } from "@monkey-mini-app/ui";
+
+export default function CodeBlock01Example() {
+  return (
+    <>
+      <CodeBlock language="ts" code={`type Run = { id: string }\nexport const run: Run = { id: \"1\" }\n`} />
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/code-editor/code-editor-01.tsx

@@ -0,0 +1,15 @@
+/**
+ * @exampleOf CodeEditor
+ * @title CodeEditor
+ * @scenario Editable source with syntax highlighting and line numbers (CodeMirror 6 via CDN). Reach for it when the user changes config/scripts in-app; degrade to Textarea if the network blocks the CDN.
+ * @hint CodeMirror 6
+ */
+import * as React from "react";
+
+import { CodeEditor } from "@monkey-mini-app/ui";
+
+export default function CodeEditor01Example() {
+  const [code, setCode] = React.useState("export const n = 1\n");
+
+  return <CodeEditor value={code} onChange={setCode} language="ts" />;
+}

package/skills/monkey-mini-app/references/examples/command/command-01.tsx

@@ -0,0 +1,30 @@
+/**
+ * @exampleOf Command
+ * @title Command
+ * @scenario Cmd-K style palette: fuzzy input over grouped actions with an empty state, mounted inline rather than as a dialog.
+ */
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@monkey-mini-app/ui";
+
+export default function Command01Example() {
+  return (
+    <>
+      <Command className="h-40 w-72 rounded-xl border">
+        <CommandInput placeholder="Search…" />
+        <CommandList>
+          <CommandEmpty>No results</CommandEmpty>
+          <CommandGroup>
+            <CommandItem>Open grid</CommandItem>
+            <CommandItem>New run</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    </>
+  );
+}

package/skills/monkey-mini-app/references/examples/confirm-dialog/confirm-dialog-01.tsx

@@ -0,0 +1,33 @@
+/**
+ * @exampleOf ConfirmDialog
+ * @title ConfirmDialog / Toast
+ * @scenario Destructive-action guard — one click opens a yes/no dialog, cancel keeps state; pair with toast for the result. Do not hand-roll a Dialog for confirmations.
+ */
+import * as React from "react";
+
+import { Button, ConfirmDialog, toast } from "@monkey-mini-app/ui";
+
+export default function ConfirmDialog01Example() {
+  const [confirm, setConfirm] = React.useState(false);
+
+  return (
+    <>
+      <div className="flex gap-2">
+        <Button variant="destructive" onClick={() => setConfirm(true)}>
+          Delete
+        </Button>
+        <Button variant="outline" onClick={() => toast.add({ title: "Saved", description: "Run updated." })}>
+          Toast
+        </Button>
+      </div>
+      <ConfirmDialog
+        open={confirm}
+        onOpenChange={setConfirm}
+        title="Delete this run?"
+        description="This cannot be undone."
+        confirmLabel="Delete"
+        onConfirm={() => setConfirm(false)}
+      />
+    </>
+  );
+}