@monkey-mini-app/dsh-mini-app 0.1.1 → 0.1.5

package/lib/index.d.ts

@@ -2,6 +2,8 @@ import { HostConfig, AbsolutePath, AppCallContext, AgentRunOptions, HostCapabili
 
 type DshPluginConfig = {
     runtimeRoot?: string;
+    /** Override skill install dir. Default: ~/.dsh/skills/monkey-mini-app. */
+    skillDest?: string;
 };
 /** Locate runtimeRoot from plugin config only when provided; else bootstrap seed path. */
 declare function resolveRuntimeRoot(config?: DshPluginConfig): AbsolutePath;

package/lib/index.js

@@ -1,4 +1,5 @@
 // src/index.ts
+import path5 from "path";
 import { createHost } from "@monkey-mini-app/host";
 
 // src/apply-config.ts
@@ -215,6 +216,7 @@ function resolveLlmRoute(ctx, opts, hostLlm) {
 }
 
 // src/llm-stream.ts
+import { DEFAULT_LLM_MAX_TOKENS } from "@monkey-mini-app/host";
 function stringifyToolResult(value) {
   if (typeof value === "string") return value;
   try {
@@ -260,7 +262,9 @@ async function collectLlmStream(llmSvc, prompt, route, opts) {
     model: route.model,
     messages: [{ role: "user", content: [{ type: "text", text }] }],
     system,
-    maxTokens: opts?.maxTokens ?? 1024
+    // The host normally supplies this (see DEFAULT_LLM_MAX_TOKENS); the same constant here keeps
+    // a direct capability call from silently falling back to a truncating budget.
+    maxTokens: opts?.maxTokens ?? DEFAULT_LLM_MAX_TOKENS
   };
   const acc = [];
   let sawDelta = false;
@@ -276,7 +280,7 @@ async function collectLlmStream(llmSvc, prompt, route, opts) {
     }
   }
   const out = acc.join("");
-  if (!out) throw new Error("llm stream empty");
+  if (!out) throw new Error("llm: stream empty");
   return coerceSchemaJson(out, opts);
 }
 
@@ -741,7 +745,7 @@ function resolveSkillDir() {
   const here = path2.dirname(fileURLToPath(import.meta.url));
   const candidates = [
     path2.join(here, "..", "skills", "monkey-mini-app"),
-    path2.join(here, "..", "..", "skills", "monkey-mini-app")
+    path2.join(here, "..", "..", "..", "skills", "monkey-mini-app")
   ];
   for (const c of candidates) {
     if (existsSync(path2.join(c, "SKILL.md"))) return c;
@@ -1047,10 +1051,19 @@ var inject = ["tools"];
 async function apply(ctx, config = {}) {
   const hostConfig = loadPluginHostConfig(config);
   const themes = new DshThemeResource(hostConfig.runtimeRoot);
-  const host = createHost(new DshCapabilities(ctx), new DshLifecycle(ctx), {
-    config: hostConfig,
-    themes
-  });
+  const host = createHost(
+    new DshCapabilities(ctx),
+    new DshLifecycle(ctx, config.skillDest ? { skillDest: path5.resolve(config.skillDest) } : {}),
+    {
+      config: hostConfig,
+      themes,
+      about: {
+        adapter: "dsh",
+        packageName,
+        env: process.env.NODE_ENV ?? "production"
+      }
+    }
+  );
   let port;
   try {
     ({ port } = await host.apply(ctx));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monkey-mini-app/dsh-mini-app",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "description": "DeepSeek Harness plugin: mini-app host wiring, panel, and skills",
   "type": "module",
   "main": "./lib/index.js",
@@ -28,10 +28,11 @@
   ],
   "scripts": {
     "build": "rm -rf lib && tsup",
-    "prepare": "rm -rf lib && tsup",
     "test": "vitest run --passWithNoTests",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "pnpm --filter @monkey-mini-app/ui build && node ../../scripts/generate-skill.mjs && rm -rf lib && tsup"
+    "prepack": "node ../../scripts/gen/skill/copy.mjs dsh",
+    "postpack": "node ../../scripts/gen/skill/copy.mjs clean dsh",
+    "prepublishOnly": "pnpm --filter @monkey-mini-app/ui build && pnpm --filter @monkey-mini-app/api build && node ../../scripts/gen/skill/index.mjs && rm -rf lib && tsup"
   },
   "dsh": {
     "bundle": {
@@ -52,13 +53,13 @@
     "monkey-mini-app"
   ],
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-subagent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-subagent": "0.1.2-rc.1",
     "@hono/node-server": "^2.1.1",
-    "@monkey-mini-app/host": "^0.1.0",
-    "@monkey-mini-app/panel": "^0.1.0",
-    "@monkey-mini-app/ui": "^0.1.0",
+    "@monkey-mini-app/host": "workspace:*",
+    "@monkey-mini-app/panel": "workspace:*",
+    "@monkey-mini-app/ui": "workspace:*",
     "esbuild": "^0.28.2",
     "esbuild-wasm": "^0.25.12",
     "hono": "^4.8.0",

package/skills/monkey-mini-app/SKILL.md

@@ -1,21 +1,38 @@
 ---
 name: monkey-mini-app
-description: Create or edit local mini-apps (ui.tsx + main.api.ts). Create with mini_app_register; edit with mini_app_read + mini_app_edit; verify with mini_app_reload; smoke with mini_app_call; open with mini_app_open.
+description: Create or edit local mini-apps (ui.tsx + main.api.ts) — small self-contained web tools that run in the mini-app panel. Typical asks a todo/notepad, an internal utility, a data dashboard, a monitor page, a report, a kanban board, visualising a script's output, or an LLM summary page. Trigger phrases include 做个小程序 / 小工具 / 面板 / 仪表盘 / dashboard / 看板 / 帮我可视化 / mini-app. Create with mini_app_register, change with mini_app_read + mini_app_edit, compile-verify with mini_app_reload, smoke-test with mini_app_call, reveal with mini_app_open. Not for editing host / panel / SDK source, and not for writing the dsh or pi plugin itself.
 ---
 
 # monkey-mini-app
 
-生成或修改本地小程序。本 skill 在 `~/.dsh/skills/monkey-mini-app/`（`references/`、`templates/` 同级）。
+Generate or modify a local mini-app. Reference docs and templates live **next to this SKILL.md** (`references/`, `templates/`) — always open them by relative path; never assume where a given host installed the skill.
 
-**`ctx` / 模型 API 以本 skill 的 [references/ctx.md](references/ctx.md)、[references/llm-json.md](references/llm-json.md) 为准**（含 `llm` / `agent` / `schema` / `onEvent`）。现网样例不要当契约：不要读 `~/.monkey-mini-app/runtime/apps/*/`。
+**Language rule for this skill:** instructions are English; the Chinese in code samples is *product copy* that the end user sees. Mini-app UI text follows the host locale (the samples use Chinese because the shipped host defaults to it) — do not translate user-facing strings when you adapt a template.
 
-## 文件怎么落地
+**`ctx` and the model APIs are defined by [references/ctx.md](references/ctx.md) and [references/llm-json.md](references/llm-json.md)** (incl. `llm` / `agent` / `schema` / `onEvent`). Live apps are not a contract: do not read `~/.monkey-mini-app/runtime/apps/*/`.
 
-Workspace 直接 Write `~/.monkey-mini-app/runtime/**` 会被沙箱拒绝，一律走 `mini_app_*` 工具。
+## How files reach disk
 
-### 新建 app → `mini_app_register`
+Writing `~/.monkey-mini-app/runtime/**` directly is refused by the sandbox — always go through the `mini_app_*` tools (no curl, no bash against `:17880`).
 
-脚手架创建（要 `manifest.json`）。`files` 的 **key 是相对路径**（动态名字），value 是全文；自动建目录。常见还有 `ui.tsx`、`main.api.ts`，按需 `lib/...`、`components/...`（禁止 `..` / 绝对路径）：
+| Goal | Tool | Notes |
+|---|---|---|
+| Inspect an existing app's manifest + absolute dir | `mini_app_get({ appId })` | Call this before editing — beats guessing |
+| List its source files | `mini_app_list_files({ appId })` | Skips `.git` / `storage` |
+| Read one file | `mini_app_read({ appId, path })` | `startLine`/`endLine` or `offset`/`limit`; `numbered: true` for `N\|` line prefixes |
+| **Edit an existing file** (main path) | `mini_app_edit({ appId, path, edits })` | `edits: [{ oldText, newText }]`; each `oldText` must be **unique** in the file. Never rewrite a whole tree to change one line |
+| New file / large rewrite | `mini_app_write({ appId, path, content })` | |
+| Delete one file | `mini_app_delete({ appId, path })` | `manifest.json` cannot be deleted |
+| Create a whole app | `mini_app_register({ appId, files })` | `files` keys are relative paths, values full text; must include `manifest.json` |
+| Validate + compile + warm cache | `mini_app_reload({ appId })` | After every round of edits — see below |
+| **Add a backend npm library** | `mini_app_install({ appId, packages: [{ name: "exceljs" }] })` | Only when `main.api.ts` must `import` a real Node library. Never for `lodash` / `motion` / `axios` / `react`. Not importable from `ui.tsx`. |
+| Smoke-test api methods | `mini_app_call({ appId, method, args })` | Or `calls: [{ method, args }]` for a whole set in one round trip |
+| Show it to the user | `mini_app_open({ appId })` | Returns whether a panel actually received it |
+| **Read runtime errors** | `mini_app_errors({ appId, since? })` | The only way to see a UI that compiled and then crashed |
+| **Ask the rendered view** | `mini_app_view_eval({ appId, code? })` | Run JS in the live DOM — what actually rendered, at what size, with which styles |
+| Confirm the plugin is alive | `mini_app_list()` | |
+
+`mini_app_register` shape (`ui.tsx` + `main.api.ts` are the two entries; add `ui/…` / `api/…` / `shared/…` as needed — `..` and absolute paths are rejected):
 
 ```
 mini_app_register({
@@ -24,147 +41,183 @@ mini_app_register({
     "manifest.json": "...",
     "ui.tsx": "...",
     "main.api.ts": "...",
-    "lib/parse.ts": "...",
-    "components/Card.tsx": "..."
+    "ui/Card.tsx": "...",
+    "api/parse.ts": "...",
+    "shared/format.ts": "..."
   }
 })
 ```
 
-### 改已有文件 → `read` + `edit`（主路径）
+Mutating tools **auto-commit** by default; pass `commit: false` to batch a few edits and let one final `mini_app_reload` close the round. Versioning (`mini_app_history_commit` / `mini_app_history_list` / `mini_app_history_reset` / `mini_app_history_revert`, single branch, revert = forward commit) → [references/history.md](references/history.md).
 
-不要再用 `register` 整树重写来改一行。
+**Deleting a whole app is a user action** in the panel. There is no unregister tool — do not delete the directory, do not curl `DELETE`.
 
-```
-mini_app_list_files({ appId })
-mini_app_read({ appId, path: "ui.tsx" })
-// 可选行窗（1-indexed 闭区间）：startLine/endLine；也可 offset+limit（Pi 风格）
-// mini_app_read({ appId, path: "ui.tsx", startLine: 10, endLine: 40 })
-// mini_app_read({ appId, path: "main.api.ts", offset: 1, limit: 80, numbered: true })
-mini_app_edit({
-  appId,
-  path: "ui.tsx",
-  edits: [{ oldText: "旧片段（须唯一）", newText: "新片段" }],
-  // commit: false   // 多轮小改可先不提交，最后 reload 收口
-})
-```
+### What `mini_app_reload` returns
+
+`{ ok, errors, notices?, compiled, committed, caches }`. The **prefix** of each `errors[i]` names the failing layer — fix that layer, don't shotgun.
+
+**Cache contract (do not second-guess this):** every successful reload drops the in-memory API module, UI bundle, **and app CSS** (`caches.appCss` is always `"dropped"`), and signals open panels to re-fetch. The tool also defaults to `cleanCaches: true` (purges `.autogen/` + on-disk bundles) so a stale Tailwind artifact cannot linger — pass `cleanCaches: false` only when you intentionally want to keep disk caches. Read `caches.views` to know whether a browser actually re-fetched.
 
-- **新建单文件 / 大段重写** → `mini_app_write({ appId, path, content })`
-- **删文件** → `mini_app_delete({ appId, path })`（不能删 `manifest.json`）
-- mutate 默认 **auto-commit**；设 `commit: false` 可攒改动
+Error prefixes:
 
-### 验证 + 预热缓存 → `mini_app_reload`
+| Prefix | Meaning | Next step |
+|---|---|---|
+| `appId must be reverse-DNS` | Bad id shape | Use `com.<you>.<thing>` |
+| `app not registered` | Nothing on disk yet | `mini_app_register` first |
+| `manifest: …` | Missing key / broken JSON | Needs `id` `name` `version` `entry` |
+| `main.api: …` | Backend compile, relative-import resolution, or an undefined name | Read the rest of the message |
+| `ui: …` | UI bundle failed, or an undefined name/component | Usually a disallowed import or a typo'd identifier |
+| `shared: …` | Undefined name in `shared/**` (used by both sides) | Fix in `shared/` |
+| `commit: …` | Compiled fine, auto-commit failed | Commit explicitly with `mini_app_history_commit` |
 
-改完一轮后调用（**替代旧的 `mini_app_validate`**）：校验 + **同步编译** `main.api` 与 UI；成功且工作区有未提交改动会 auto-commit。
+`committed.status` is explicit, because "nothing happened" and "I could not commit" need different follow-ups:
+
+| `status` | Meaning |
+|---|---|
+| `committed` | New commit (`commitId` set) |
+| `clean` | Nothing to commit — `mini_app_edit` already auto-committed it |
+| `skipped` | Compile failed, so no commit was attempted |
+| `failed` | Commit itself errored (`reason`; also in `errors[]`) |
+
+**Compile green is not "it runs".** `errors[]` from an undefined identifier *is* caught now (`"greeting()" is called but never defined or imported`, often with a `did you mean`), and `notices[]` carries lower-confidence findings — read them, they are cheap. What no compile step can see is anything that only fails at render time, so finish the loop:
+
+### Debug loop (this is the part that used to need a human)
 
 ```
-mini_app_reload({ appId })  // { ok, errors, compiled, committed? }
+edit → mini_app_reload → mini_app_open → mini_app_errors → mini_app_view_eval
 ```
 
-然后：
+1. `mini_app_reload` until `ok: true`.
+2. `mini_app_open` — the iframe mounts and streams back anything it throws. `panel: "no-panel-connected"` means no browser is attached: the app is fine, nobody is looking, so tell the user to open the panel.
+3. Give it a moment to render, then `mini_app_errors`. Empty + never opened ≠ clean; the hint says when to re-read.
+4. `mini_app_view_eval({ appId })` (no `code` = the `#root` subtree) to see what actually drew — then ask it anything in JS: did that class apply, which node has no width, is that subtree `display:none`.
 
-1. `mini_app_call({ appId, method, args })` 冒烟（不是 curl / 不是 bash 打 `:17880`）
-2. `mini_app_open({ appId })` —— 弹出侧栏「小程序」并打开该 app
+`mini_app_errors` polls with `since: <lastSeq>`; a reload clears the ring, so errors after a reload are only from the new build. `mini_app_view_eval` needs a live view and says which of `not-open` / `runner-not-booted` / `stuck` it hit when it does not get one → **[references/eval.md](references/eval.md)**.
 
-`mini_app_list` 只需确认插件活着。显式 `mini_app_history_commit` / `_list` / `_reset` / `_revert` 仍可用。
+More symptoms → [references/troubleshoot.md](references/troubleshoot.md).
 
-## 协议
+## Protocol
 
-- UI **禁止** `import` `main.api.ts`
-- UI：`const { call } = useDashboardApi()`，自己管 loading；`useDashboardApi` 从 `@monkeyagent/host` 导入（host 注入，不要自己实现）
-- 后端：`export default defineDashboard({ name, description, api })`
-- `call("foo")` 必须是 `api.foo`
-- 后端 import 只许 `@monkeyagent/dashboard` 和 `./lib` `./components`
-- 抓网：`ctx.http(url)` / `ctx.http(url, { method, headers, query, body, timeout })`；解析写 `./lib`
-- 本机命令才用 `ctx.bash`（`{ stdout, stderr, exitCode }`）
-- **模型**：`ctx.llm(prompt, opts?)` / `ctx.agent(goal, opts?)` → **string**。共用 opts：`provider?` `model?` `system?` `schema?` `maxTokens?` `signal?`；agent 另加 `onEvent?`。结构化 JSON → [llm-json.md](references/llm-json.md)；过程事件与完整签名 → [ctx.md](references/ctx.md)
-- MCP / tool 参数是普通对象，禁止 `{ input: "..." }`；`ctx.tool` / `ctx.agent` / `ctx.llm` 返回值都是 **string**（tool/mcp 经宿主 stringify）
-- 文案给用户看；卡片标题用业务语言（「今日摘要」），不要写 `ctx.bash` / `storage/*.json`
-- **长耗时任务只跑采样** + 必须响应 `ctx.signal` + `scanStatus`/`progress`，见 [ctx.md](references/ctx.md)
+**Two author packages:** `@monkey-mini-app/ui` (UI: `useApp` + components) and `@monkey-mini-app/api` (backend: `defineApp`, host-injected). The UI compiler externalises `react` + the UI package; the backend loader injects `defineApp` only. Any other bare import is a compile error by design.
 
-## UI（@monkey-mini-app/ui）
+**Layout** (enforced, not cosmetic):
 
-**组件库是「参考 / 便利」，不是硬性规范。** 它只是帮你省掉重复造轮子——合适的场景直接用，但**别为了用组件而用**。允许完全自由的发挥：
+```
+manifest.json · ui.tsx · main.api.ts
+ui/        → UI only (components, hooks)      backend may NOT import it
+api/       → backend only (helpers, ctx work)  UI may NOT import it
+shared/    → both — pure code only: no React, no DOM, no ctx, no Node
+```
+
+A trivial app needs none of the three folders. Relative imports may use any subfolder name, but must stay inside the app dir.
+
+- UI may **not** `import` `main.api.ts`
+- UI: `const { call } = useApp()` — you own loading/error state; `useApp` comes from `@monkey-mini-app/ui` (never implement your own)
+- Backend: `export default defineApp({ name, description, api })` (`name` **and** `description` are required; import `defineApp` from `@monkey-mini-app/api` — the host injects the runtime copy, nothing React gets loaded)
+- `call("foo")` must be a key of `api.foo`
+- Backend imports: `@monkey-mini-app/api` + relative paths inside the app dir (no npm, no Node builtins)
+- Fetching: `ctx.http(url)` / `ctx.http(url, { method, headers, query, body, timeout })`; put parsing in `api/`
+- Machine commands only via `ctx.bash` (`{ stdout, stderr, exitCode }`)
+- **Model**: `ctx.llm(prompt, opts?)` / `ctx.agent(goal, opts?)` → **string**. Shared opts: `provider?` `model?` `system?` `schema?` `maxTokens?` `signal?`; `agent` adds `onEvent?` `maxIterations?` `cwdType?` `cwd?`. Structured JSON → [llm-json.md](references/llm-json.md); full signatures and event shapes → [ctx.md](references/ctx.md)
+- MCP / tool args are plain objects — never `{ input: "..." }`; `ctx.tool` / `ctx.agent` / `ctx.llm` all return **string** (the host stringifies tool results)
+- Copy is for the end user; card titles speak business (`「今日摘要」` / "Today's digest"), never `ctx.bash` or `storage/*.json`
+- **Long jobs run sampled only**, must honour `ctx.signal`, and expose `scanStatus`/`progress` — see [ctx.md](references/ctx.md)
+
+## UI (`@monkey-mini-app/ui`)
+
+**The component library is a convenience, not a mandate.** It exists so you stop rebuilding wheels — use it where it fits, but never contort a design to use it. Free-form UI is expected:
 
-- **先判断**：这个 UI 有没有现成组件？**有且合适 → 用**（省 token、风格统一）；**没有、或要独特视觉/交互、或用户明确要「自由发挥」→ 用原生元素（`div`/`span`/`button`/`input`/`table`/`svg`…）+ Tailwind classes 自行实现**，不用迁就组件库去硬凑。
-- **可混用**：骨架（卡片/页头/弹窗）用库组件，细节或视觉特殊处用原生 + Tailwind。
-- **自由发挥的边界**：原生元素 + Tailwind 随意；但 UI 仍**只能** import `react` / `@monkey-mini-app/ui` / `@monkeyagent/host` / 相对 `./lib`（编译器限制，**不能 import 任意 npm 包**）。需要图表/图标/编辑器等能力时从 `@monkey-mini-app/ui` 拿，或自己用 CSS/SVG 实现。
-- **不用管的**：`UiProvider` host 自动包裹；布局用 Tailwind classes（库里没有 Stack/Text 这类布局件）。
+- **Decide first**: is there a component for this that actually fits? **Yes → use it** (fewer tokens, consistent look). **No, or the design needs its own visual/interaction, or the user asked for free play → build it from native elements (`div`/`span`/`button`/`input`/`table`/`svg`…) + Tailwind classes.** Do not bend the design to fit the library.
+- **Mixing is normal**: library components for the skeleton (cards / page header / dialogs), native + Tailwind for the distinctive parts.
+- **Boundary of free play**: native elements and Tailwind are unlimited, but `ui.tsx` may only import `react`, `@monkey-mini-app/ui`, `lodash` / `lodash-es`, `motion` / `motion/react`, and in-app relative paths — never `api/**`, never `../` out of the app dir, never another npm package. Hooks from `react`; components, `useApp`, and `cn` from the SDK.
+- **Not your job**: the theme provider and the app runtime are wrapped by the host; there is no `Stack`/`Text` layout component — use Tailwind classes.
+- Component props list **only their own API**: `className`, `style`, `onClick`, `aria-*` are never repeated (every component takes them). Conversely, **never guess the part names of a compound component** (`Dialog` + `DialogTrigger` + `DialogContent`, not `<Dialog title>`) — read its contract.
 
-下面是「常用姿势」示例，**不是唯一写法**——复杂/特殊 UI 完全可以全手写。
+The snippet below is a common shape, **not the only shape** — complex or bespoke UI may well be fully hand-written.
 
 ```tsx
-import { useEffect, useState } from "react";
-import { Button, Input, Card, CardContent, CardHeader, CardTitle, Textarea } from "@monkey-mini-app/ui";
-import { useDashboardApi } from "@monkeyagent/host";
+import { useState } from "react";
+import { useApp, Button, Input, Card, CardContent, CardHeader, CardTitle } from "@monkey-mini-app/ui";
 
 export default function Ui() {
-  const { call } = useDashboardApi();
+  const { call } = useApp();
   const [draft, setDraft] = useState("");
   ...
   return (
     <Card className="mt-8 w-full">
-      <CardHeader><CardTitle>名称</CardTitle></CardHeader>
+      <CardHeader><CardTitle>Name</CardTitle></CardHeader>
       <CardContent className="flex flex-col gap-3">
-        <Input value={draft} onChange={(e) => setDraft(e.target.value)} placeholder="写一条" />
-        <Button onClick={async () => { await call("add", { title: draft }); }}>添加</Button>
+        <Input value={draft} onChange={(e) => setDraft(e.target.value)} placeholder="Write something" />
+        <Button onClick={async () => { await call("add", { title: draft }); }}>Add</Button>
       </CardContent>
     </Card>
   );
 }
 ```
 
-- **布局用 Tailwind classes**（`flex flex-col gap-3 p-4 grid md:grid-cols-3 w-full space-y-4`），库内没有 Stack/Text 这类布局组件
-- **`UiProvider` 由 host 自动包裹**（locale 跟随 host 设置），不要自己写 Provider
-- 组件清单（props + 类型 + 示例）→ **[references/catalog.md](references/catalog.md)** 与 **[references/contracts/](references/contracts/)**（自动生成，改组件后 `pnpm skill:gen` 再生成）
-- **图标**：`import { Icon } from "@monkey-mini-app/ui"` 后用 `Icon.HelpCircle`（任意 lucide 名都行）；**常用推荐子集 + 何时用** → **[references/icons.md](references/icons.md)**（不要读上千个名，看这份精简的）
-- **空状态插图**：`import { IlluServerStatus } from "@monkey-mini-app/ui"`（`Illu*`，已 token 化跟主题）
-- 组件库已内置 lucide 图标 / recharts / CodeMirror 等依赖——**不要**额外 import 这些 npm 包；从 `@monkey-mini-app/ui` 拿
-
-| 场景 | 组件 |
+- **Layout is Tailwind** (`flex flex-col gap-3 p-4 grid md:grid-cols-3 w-full space-y-4`)
+- **`cn` is already in the kit** — `import { cn } from "@monkey-mini-app/ui"` (`clsx` + `tailwind-merge`). Prefer it over concatenating class strings.
+- **Tailwind is compiled per app from your source** — variants (`hover:` `group-hover:` `md:`), the default palette (`bg-rose-500`) and arbitrary values (`w-[437px]`) all work, so **do not fall back to inline `style` out of caution**. The one trap: class names must be complete literals — `` `bg-${x}-500` `` generates nothing, silently → **[references/styling.md](references/styling.md)**
+- **Colour is tokens, never hex** — the user's palette rewrites token values under `<html>`, a literal breaks dark mode → **[references/theme.md](references/theme.md)** (generated token table). **Do not invent a theme in `ui.tsx`.** Two escape hatches, both rare: a host-global custom palette (`themes/theme-<id>.css`) when the user asks for a named brand — *Custom host theme file*; or an app-local `theme.css` when the **style itself depends on a hue** (a look the app carries, e.g. neon signage) — *App-local palette*. A plain CRUD/table/settings app ships neither.
+- **`lodash` is a platform module** on UI and backend (`import { groupBy, debounce } from "lodash"`). Prefer it over hand-rolled `groupBy` / `uniqBy` / `pick` / `debounce`. Bare `axios` / `ramda` / `dayjs` still fail.
+- **`motion` is a platform module** (UI only — `import { motion, AnimatePresence } from "motion/react"`). Use it for enter/exit/layout, Tailwind `transition` for a one-property hover, and kit `<Reveal delay={i * 60}>` for a staggered entrance. Custom `@keyframes` are allowed — give them your own name, since keyframe names are global inside the app's document and the platform already defines `spin` / `pulse` / `enter` / `exit` / … → **[references/styling.md](references/styling.md)** *Animation*.
+- **Need a library the platform does not ship** (a real file format, a binary protocol, a vendor SDK): `mini_app_install({ appId, packages: [{ name: "exceljs" }] })`, then `import ExcelJS from "exceljs"` in `main.api.ts`. Order of preference: `ctx.http` → `ctx.bash` / `ctx.tool` → install. Backend only — the UI still gets JSON through `call`.
+- **Icons**: `import { Icon } from "@monkey-mini-app/ui"`, then `Icon.HelpCircle` (any lucide name works); **curated subset + when to use** → **[references/icons.md](references/icons.md)** (don't page through a thousand names)
+- **Empty-state illustrations** — exactly these 10, the names are not guessable: `IlluEmpty` `IlluNoData` `IlluSearch` `IlluLoading` `IlluServerStatus` `IlluAccessDenied` `IlluPageNotFound` `IlluDataProcessing` `IlluBugFixing` `IlluCodeReview`
+- Component index (props + types) → **[references/catalog.md](references/catalog.md)** and **[references/contracts/](references/contracts/)** (generated; after changing a component run `pnpm gen:skill`).
+- **Prefer a ready example over writing a widget from memory**: each component contract lists [references/examples/](references/examples/) files, one scenario each (e.g. `data-grid-01` = sort+search+pagination, `data-grid-02` = rich cells via renderers). They import `react` + `@monkey-mini-app/ui` + relatives only, so copy one into `ui/` and edit — do not invent a variant no example shows.
+- The SDK already bundles React / lucide / recharts — **never** import those yourself
+- **Heavy editors load from a CDN on demand** (not npm): `CodeEditor` pulls CodeMirror 6 from `esm.sh`; `CodeBlock` / `DiffViewer` pull shiki; `RichTextEditor` is a local contentEditable editor (no CDN, no dependency). Do not `import` `@codemirror/*` / `shiki` / `@tiptap/*` / `@uiw/react-codemirror` (the last one brings a second React). When the CDN is blocked the components degrade — see [troubleshoot.md](references/troubleshoot.md)
+
+| Need | Components |
 |---|---|
-| 页面骨架 | `AppShell` `PageHeader` `FilterBar` `DetailPanel` |
-| KPI 卡片 | `StatCard` `TrendCard` `StatusBadge` `SeverityChip` |
-| 表格 | `DataGrid` + `ColumnDef`（排序/筛选/分页/CSV 自带） |
-| 日期时间 | `DatePicker` `DateRangePicker` `DateTimePicker` `TimePicker` `DurationInput` `RelativeDatePicker` |
-| 看板/日历/计划 | `Kanban` `EventCalendar` `Gantt` `Timeline` `Stepper` |
-| 树/列表 | `TreeView` `SortableList` `FileTree` |
-| 编辑器 | `CodeEditor` `MarkdownEditor` `RichTextEditor` `CodeBlock` `Markdown` |
-| 检查/日志 | `DiffViewer` `JsonViewer` `LogViewer` `RequestInspector` `Terminal` |
-| 表单扩展 | `SearchInput` `NumberField` `TagInput` `ConfirmDialog` `FileDropzone` `Copyable` `UserPicker` |
-| 图表 | `DonutChart` `StackedBarChart` `Sparkline` `Gauge` `RadarChart` + L1 `Chart` |
-| 基础件 | `Button` `Input` `Select` `Dialog` `Sheet` `Tabs` `Card` `Badge` `Toast` `Empty` … |
-
-## CRUD 骨架（普通记事直接改这段）
+| Page skeleton | `AppShell` `PageHeader` `FilterBar` `DetailPanel` |
+| KPI cards | `StatCard` `TrendCard` `StatusBadge` `SeverityChip` |
+| Tables | `DataGrid` + `ColumnDef` (sorting / filtering / paging / CSV built in) |
+| Date & time | `DatePicker` `DateRangePicker` `DateTimePicker` `TimePicker` `DurationInput` `RelativeDatePicker` |
+| Boards / calendar / plans | `Kanban` `EventCalendar` `Gantt` `Timeline` `Stepper` |
+| Trees / lists | `TreeView` `SortableList` `FileTree` |
+| Editors | `CodeEditor` `MarkdownEditor` `RichTextEditor` `CodeBlock` `Markdown` |
+| Inspect / logs | `DiffViewer` `JsonViewer` `LogViewer` `RequestInspector` `Terminal` |
+| Form extras | `SearchInput` `NumberField` `TagInput` `ConfirmDialog` `FileDropzone` `Copyable` `UserPicker` |
+| Charts | `DonutChart` `StackedBarChart` `Sparkline` `Gauge` `RadarChart` + L1 `Chart` |
+| Primitives | `Button` `Input` `Select` `Dialog` `Sheet` `Tabs` `Card` `Badge` `Toast` `Empty` … |
+
+## CRUD skeleton (edit this for plain local notes)
 
 `manifest.json`:
 
 ```json
 {
   "id": "com.example.foo",
-  "name": "名称",
-  "description": "一句话",
+  "name": "My Mini App",
+  "description": "One line description for the app",
   "version": "0.1.0",
   "entry": "ui.tsx",
-  "theme": { "followsHost": true },
-  "acronym": "MC"
+  "acronym": "MA"
 }
 ```
 
-`acronym`（可选）：双字母缩写，用于 Host 列表的卡片 monogram。不写时按中文名拼音声母自动生成（「备忘录」→ BW），英文名取前两个字母。只有想自定义缩写时才需要填（如品牌名）。
+There is **no theme block**. Colour comes from the host palette unless the app ships its own
+`theme.css` — see [references/theme.md](references/theme.md) → *App-local palette*.
+
+Product strings (`name`, `description`, every label the user sees) follow the **host locale** — the shipped host defaults to Chinese, so the samples are Chinese. Instructions and comments stay English.
+
+`acronym` (optional): two letters used as the monogram on the host's list card. Omit it and the host derives one (pinyin initials for Chinese names, e.g. `备忘录` → BW; first two letters for Latin names). Only set it to override a brand name.
 
 `main.api.ts`:
 
 ```ts
-import { defineDashboard } from "@monkeyagent/dashboard";
+import { defineApp } from "@monkey-mini-app/api";
 
 async function loadItems(ctx) {
   const items = await ctx.storage.get("items");
   return Array.isArray(items) ? items : [];
 }
 
-export default defineDashboard({
-  name: "名称",
-  description: "一句话",
+export default defineApp({
+  name: "My Mini App",
+  description: "One line description for the app",
   api: {
     async list(ctx) {
       return loadItems(ctx);
@@ -187,32 +240,46 @@ export default defineDashboard({
 });
 ```
 
-## 按需再读（不要一次全打开）
+## Read on demand (do not open everything)
 
-| 何时 | 打开 |
+| When | Open |
 |------|------|
-| 组件 props / 类型 / 示例 | [references/catalog.md](references/catalog.md) → [references/contracts/](references/contracts/) |
-| 图标子集（`Icon` 命名空间，何时用） | [references/icons.md](references/icons.md) || `ctx.*` 完整契约（含 agent `onEvent` 事件形状） | [references/ctx.md](references/ctx.md)（用 `ctx.http`，不要 bash curl） |
-| `schema` 结构化 JSON 例子 | [references/llm-json.md](references/llm-json.md) |
-| **真的要用** `ctx.tool` | 先 `mini_app_list_ctx_tools`，再 [references/tools.md](references/tools.md) |
-| 相对 import、`./lib` 解析 | [references/loader.md](references/loader.md) |
-| 人类调试 Host `:17880` / curl | [references/test.md](references/test.md)（≠ `ctx.http`） |
-| 骨架基线 / 最小可运行结构 | `templates/minimal/` |
-| 本地 CRUD + 筛选 + 派生统计 | `templates/todo/` |
-| 联网数据 → 模型摘要（长任务/采样/取消） | `templates/insights/` |
-| 本机指标实时看板（system + bash） | `templates/monitor/` |
-| 编辑/diff/日志/用例表格（复杂组件示例） | `templates/review/` |
-| `ctx.agent` 多步任务 + 过程/取消 | `templates/agentrun/` |
-| 看板/表格双视图 + 编辑 + AI（flagship） | `templates/jira/` |
-| **先把 7 个模板的指引侧重读一遍再选** | [`templates/README.md`](templates/README.md) |
-| 报错 | [references/troubleshoot.md](references/troubleshoot.md) |
-
-普通 storage CRUD **先用上面骨架**，不要为了记笔记去读整份 Todo。模板是风格样板：中文产品文案、`call` 自己管 loading/error、后端可用 TypeScript。
+| Component props / types | [references/catalog.md](references/catalog.md) → [references/contracts/](references/contracts/) |
+| **Which Tailwind classes work / how to colour** | [references/styling.md](references/styling.md) |
+| **What actually rendered (live DOM query)** | [references/eval.md](references/eval.md) — recipes, output format, the four `view` states |
+| **Theme token table + custom host theme file** | [references/theme.md](references/theme.md) (generated — do not hand-edit) |
+| **A runnable starting point for one component** | contract's `## Examples` → [references/examples/](references/examples/) (each file = one scenario: `@title` + `@scenario`; layout/pattern recipes in `examples/<group>.md`) |
+| Icon subset (`Icon` namespace, when to use) | [references/icons.md](references/icons.md) |
+| Full `ctx.*` contract (incl. agent `onEvent` shapes) | [references/ctx.md](references/ctx.md) (use `ctx.http`, not bash curl) |
+| Structured JSON via `schema` | [references/llm-json.md](references/llm-json.md) |
+| **Actually using** `ctx.tool` | `mini_app_list_ctx_tools` first, then [references/tools.md](references/tools.md) |
+| Relative imports, `ui` / `api` / `shared` layout | [references/loader.md](references/loader.md) |
+| Human debugging of host `:17880` / curl | [references/test.md](references/test.md) (≠ `ctx.http`) |
+| Errors | [references/troubleshoot.md](references/troubleshoot.md) |
+| Versioning / rollback | [references/history.md](references/history.md) |
+| **A named visual style** (only if the user asked) | [references/looks/index.md](references/looks/index.md) — recipes, not apps |
+
+**Templates are product facades, cut by interaction loop.** Read [`templates/README.md`](templates/README.md). Lift the pattern — do not paste whole files. Looks are optional; do not open them unless the user named a style.
+
+| Loop | Template |
+|---|---|
+| One `call` / connectivity | `templates/minimal/` |
+| Open → my screen → one record | `templates/today/` |
+| Items move in 2D status | `templates/board/` |
+| Trigger → wait → read (cancel) | `templates/radar/` |
+| File in, grid work (`mini_app_install`) | `templates/sheets/` |
+| The UI *is* the run (`ctx.agent`) | `templates/runner/` |
+| Named buttons, this machine, no model | `templates/chores/` |
+| Numbers move by themselves | `templates/watch/` |
+
+For a plain note **start from the skeleton above**. Product copy follows the host locale.
 
 ## Checklist
 
-- [ ] 新建用 `mini_app_register`；改已有用 `mini_app_read` + `mini_app_edit`（或 `write`）
-- [ ] `mini_app_reload` 编译通过
-- [ ] `mini_app_call` 冒烟通过（不是 curl）
-- [ ] `mini_app_open`
-- [ ] call 键 ⊆ api 键；UI 无 fetch / secrets / llm
+- [ ] New app via `mini_app_register`; edits via `mini_app_get` / `mini_app_list_files` + `mini_app_read` + `mini_app_edit` (or `write`)
+- [ ] Started from the closest template(s), lifted patterns/structure rather than pasting whole files
+- [ ] `mini_app_reload` compiles (located the failure by `errors[i]` prefix) and `notices[]` was read
+- [ ] `mini_app_call` smoke test passes (not curl) — batch with `calls: []` instead of N round trips
+- [ ] `mini_app_open`, then `mini_app_errors` — **compile green ≠ it renders**; do not stop at the build
+- [ ] `mini_app_view_eval` confirms the styling actually applied (no hardcoded hex, no composed class names)
+- [ ] `call` keys ⊆ `api` keys; no fetch / secrets / llm in the UI; compound part names taken from a contract, not memory