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

package/skills/monkey-mini-app/references/looks/glass-island.md

@@ -0,0 +1,90 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Glass Island
+
+Also known as `玻璃岛屿` (sample product copy).
+
+id: `glass-island` · grammar: `poster-dock`
+
+**When:** Personal home, lock-screen style one-shot. Liquid glass islands float on a haze sky; the working set is a soft card below.
+
+**Not:** Launchers, DataGrid, incident walls. Not a 2D mosaic. Not wall-to-wall glass.
+
+**How to copy it:** Liquid glass (SVG displacement + blur), not frost. `backdrop-filter: blur(2px) saturate(160%) url(#mma-liquid)` with feTurbulence→blur→displace (scale ~45, yChannel=B). Light ground is haze-grey + white + a whisper of blue with large floating orbs — not a saturated sky; dark is deep indigo. Sky needs grain + orb edges or the lens bends nothing. Only the island cluster is liquid; the working set is a soft card so the sky still frames the cluster (wall-to-wall glass is why the facade used to look nothing like the prototype). Radius is large (`--radius: 28px`) on the style object. Non-Chromium falls back to frost. Host bakes local theme.css vars into `/app/:id` first paint so the look is not near-white while mma-set-env is in flight.
+
+## Style (inline — Tailwind drops multi-layer shadows)
+
+```tsx
+const GLASS = {
+  "borderRadius": "var(--radius)",
+  "backgroundColor": "color-mix(in oklch, var(--card) 14%, transparent)",
+  "boxShadow": "inset 0 1px 0 card/60, inset 0 -1px 0 card/22, inset 0 0 24px card/14, 0 14px 36px -10px var(--shadow)",
+  "border": "1px solid color-mix(in oklch, var(--card) 28%, transparent)",
+  "backdropFilter": "blur(2px) saturate(160%) url(#mma-liquid)  /* Chromium; frost fallback otherwise */"
+} as const;
+```
+
+## Classes (copy literals)
+
+- `root`: `bg-background relative flex h-full min-h-0 flex-col gap-3 overflow-hidden p-5`
+- `wash`: `pointer-events-none absolute inset-0 (multi-hue soft orbs + grain — see facade)`
+- `cluster`: `relative mx-auto flex h-full min-h-0 w-full max-w-5xl flex-col gap-3`
+- `island`: `liquid glass style object (radius var(--radius), blur+saturate+url(#mma-liquid))`
+- `work`: `soft card surface — NOT liquid glass (keeps sky around the cluster)`
+
+## Palette (optional `theme.css` in the app dir)
+
+This look's identity depends on hue, so it ships a palette. Writing it to `theme.css`
+makes the app use it by default (ThemePop lists it as the row tagged **`本应用`**); the user can still
+pick a host palette. Omit the file to follow the host palette instead.
+
+```css
+/* name: 玻璃岛屿 */
+/* Light: haze grey-blue a step deeper than pure fog, white glass, soft floating orbs that
+   actually read. Dark: deep indigo. Radius large for liquid glass on big panes. */
+:root[data-mode="light"] {
+  --bg: #d5e0ed;
+  --fg: #243044;
+  --surface: #ffffff;
+  --surface-fg: #243044;
+  --border: #c2d0e0;
+  --muted: #c8d5e6;
+  --muted-fg: #5a6b80;
+  --primary: #6b8ab8;
+  --primary-fg: #ffffff;
+  --secondary: #d0dbe8;
+  --secondary-fg: #243044;
+  --accent: #e4ebf4;
+  --accent-fg: #243044;
+  --destructive: #c63f4f;
+  --destructive-fg: #ffffff;
+  --ring: #6b8ab8;
+  --input: #b8c8da;
+  --radius: 28px;
+  --shadow: rgba(60, 85, 120, 0.18);
+}
+:root[data-mode="dark"] {
+  --bg: #0e1128;
+  --fg: #e9edff;
+  --surface: #21264c;
+  --surface-fg: #e9edff;
+  --border: #2e3566;
+  --muted: #1d2046;
+  --muted-fg: #a3b0e6;
+  --primary: #8b94fa;
+  --primary-fg: #12142c;
+  --secondary: #232757;
+  --secondary-fg: #e9edff;
+  --accent: #1d2046;
+  --accent-fg: #e9edff;
+  --destructive: #f97066;
+  --destructive-fg: #20120d;
+  --ring: #8b94fa;
+  --input: #2e3566;
+  --radius: 28px;
+  --shadow: rgba(0, 4, 24, 0.66);
+}
+```
+
+
+Tokens only — no hex in `ui.tsx`. Light and dark must both read. Optional `data-look` on a root is a recipe, not a platform attribute.

package/skills/monkey-mini-app/references/looks/index.md

@@ -0,0 +1,18 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Looks
+
+Recommended visual recipes (colour intent + layout grammar + surface). **Not apps.**
+Pick a facade first. Open a Look only when the user names a style.
+No kit API — copy the class literals. Light and dark are a pair (live fixture + theme.css, not image previews).
+
+| id | name | when | default facade |
+|---|---|---|---|
+| [`glass-island`](./glass-island.md) | Glass Island (`玻璃岛屿`) | Personal home, lock-screen style one-shot. Liquid glass islands float on a haze sky; the working set is a soft card below. | `today` |
+| [`aurora-bento`](./aurora-bento.md) | Aurora Bento (`极光便当`) | Launcher / overview. The page is a 6×3 tessellation, every cell a destination. | `board` |
+| [`desk-split`](./desk-split.md) | Desk Split (`精致分栏`) | CRUD, tickets, contacts, ledgers. Two panes, hairline, dense toolbar. | `sheets` |
+| [`editorial`](./editorial.md) | Editorial (`编辑排版`) | Weekly digest, insights, runbook, help. Type hierarchy, hairline rules, almost no cards. | `radar` |
+| [`tape`](./tape.md) | Tape (`行情带`) | Watch board, quotes, incident strip. Tabular numerals, vertical rules, colour = delta only. | `watch` |
+| [`void`](./void.md) | Void (`黑空`) | Named 'premium / sparse / AI product'. Huge type, one hairline, almost empty. | — |
+| [`signage`](./signage.md) | Signage (`霓虹招牌`) | Named cyberpunk / neon. Display type, chroma wash, caption columns — not glow cards. | — |
+| [`terminal`](./terminal.md) | Terminal (`终端等宽`) | Logs, agent progress, a command well. Mono rows, lamps, colour = state. | `runner`, `chores` |

package/skills/monkey-mini-app/references/looks/signage.md

@@ -0,0 +1,74 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Signage
+
+Also known as `霓虹招牌` (sample product copy).
+
+id: `signage` · grammar: `display-type`
+
+**When:** Named cyberpunk / neon. Display type, chroma wash, caption columns — not glow cards.
+
+**Not:** A dark dashboard with extra shadow. Opt-in only.
+
+
+## Classes (copy literals)
+
+- `root`: `relative h-full min-h-0 overflow-hidden bg-background p-6`
+- `wash`: `pointer-events-none absolute inset-0 bg-[radial-gradient(420px_180px_at_90%_10%,color-mix(in_oklch,var(--primary)_28%,transparent),transparent_62%)]`
+- `display`: `text-4xl font-bold tracking-tight leading-[0.95]`
+
+## Palette (optional `theme.css` in the app dir)
+
+This look's identity depends on hue, so it ships a palette. Writing it to `theme.css`
+makes the app use it by default (ThemePop lists it as the row tagged **`本应用`**); the user can still
+pick a host palette. Omit the file to follow the host palette instead.
+
+```css
+/* name: 霓虹招牌 */
+/* Look-owned palette: the chroma IS the style. ui.tsx still never contains a hex. */
+:root[data-mode="light"] {
+  --bg: #f6effa;
+  --fg: #1a1020;
+  --surface: #ffffff;
+  --surface-fg: #1a1020;
+  --border: #e2d3ea;
+  --muted: #efe4f5;
+  --muted-fg: #5f4a6b;
+  --primary: #b3128a;
+  --primary-fg: #ffffff;
+  --secondary: #efe4f5;
+  --secondary-fg: #1a1020;
+  --accent: #f6e9fb;
+  --accent-fg: #1a1020;
+  --destructive: #c02626;
+  --destructive-fg: #ffffff;
+  --ring: #b3128a;
+  --input: #e2d3ea;
+  --radius: 14px;
+  --shadow: rgba(60, 20, 70, 0.12);
+}
+:root[data-mode="dark"] {
+  --bg: #0a0614;
+  --fg: #f6ecff;
+  --surface: #150b26;
+  --surface-fg: #f6ecff;
+  --border: #2e1b45;
+  --muted: #1c1030;
+  --muted-fg: #a98fc4;
+  --primary: #ff2ea6;
+  --primary-fg: #12031a;
+  --secondary: #1c1030;
+  --secondary-fg: #f6ecff;
+  --accent: #241036;
+  --accent-fg: #f6ecff;
+  --destructive: #ff5c5c;
+  --destructive-fg: #12031a;
+  --ring: #ff2ea6;
+  --input: #2e1b45;
+  --radius: 14px;
+  --shadow: rgba(0, 0, 0, 0.6);
+}
+```
+
+
+Tokens only — no hex in `ui.tsx`. Light and dark must both read. Optional `data-look` on a root is a recipe, not a platform attribute.

package/skills/monkey-mini-app/references/looks/tape.md

@@ -0,0 +1,22 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Tape
+
+Also known as `行情带` (sample product copy).
+
+id: `tape` · grammar: `numeral-strip`
+
+**When:** Watch board, quotes, incident strip. Tabular numerals, vertical rules, colour = delta only.
+
+**Not:** Homes, forms. No graph-paper grid, no card chrome.
+
+
+## Classes (copy literals)
+
+- `root`: `h-full min-h-0 bg-background font-mono`
+- `nums`: `grid grid-cols-4 divide-x divide-border`
+- `num`: `px-4 py-5 text-3xl font-medium tracking-tight tabular-nums`
+
+This look follows the host palette on purpose — no `theme.css`.
+
+Tokens only — no hex in `ui.tsx`. Light and dark must both read. Optional `data-look` on a root is a recipe, not a platform attribute.

package/skills/monkey-mini-app/references/looks/terminal.md

@@ -0,0 +1,88 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Terminal
+
+Also known as `终端等宽` (sample product copy).
+
+id: `terminal` · grammar: `mono-well`
+
+**When:** Logs, agent progress, a command well. Mono rows, lamps, colour = state.
+
+**Not:** Long-form reading.
+
+**How to copy it:** Phosphor-on-black CRT is the identity (green #3dff6e on #060904 in dark; a paper well with deep green ink in light). The Terminal block defaults to hard zinc-950 — override it with `bg-card text-card-foreground` (the app-side Tailwind theme has no `--color-surface`; use card tokens) or a host swap washes the well out (templates ship this look's theme.css for that reason). Scanlines + vignette sell the CRT; they live on an aria-hidden pointer-events-none overlay so they never eat clicks. Radius squared (8px): rounds read as a chat app, not a console. Colour = state, nothing else.
+
+## Style (inline — Tailwind drops multi-layer shadows)
+
+```tsx
+const GLASS = {
+  "well": {
+    "className": "rounded-lg border bg-card text-card-foreground",
+    "textShadow": "0 0 6px color-mix(in oklch, var(--primary) 65%, transparent)",
+    "overlay": "repeating-linear-gradient(0deg, foreground 7% hairlines every 3px) + radial corner vignette"
+  }
+} as const;
+```
+
+## Classes (copy literals)
+
+- `root`: `flex h-full min-h-0 flex-col bg-background`
+- `well`: `min-h-0 flex-1 overflow-auto`
+
+## Palette (optional `theme.css` in the app dir)
+
+This look's identity depends on hue, so it ships a palette. Writing it to `theme.css`
+makes the app use it by default (ThemePop lists it as the row tagged **`本应用`**); the user can still
+pick a host palette. Omit the file to follow the host palette instead.
+
+```css
+/* name: 终端等宽 */
+/* Look-owned palette: phosphor-on-black CRT is the identity — a host palette would turn the
+   well pink. Light mode is a paper well with deep green ink; dark is near-black with green
+   phosphor (#3dff6e). Radius is squared: rounds read as "chat app", not as a console. */
+:root[data-mode="light"] {
+  --bg: #ecefe4;
+  --fg: #12290f;
+  --surface: #f7faf1;
+  --surface-fg: #12290f;
+  --border: #ccd5c0;
+  --muted: #dfe6d4;
+  --muted-fg: #4c5f44;
+  --primary: #157a24;
+  --primary-fg: #ffffff;
+  --secondary: #dfe6d4;
+  --secondary-fg: #12290f;
+  --accent: #e2ecd6;
+  --accent-fg: #12290f;
+  --destructive: #b42318;
+  --destructive-fg: #ffffff;
+  --ring: #157a24;
+  --input: #ccd5c0;
+  --radius: 8px;
+  --shadow: rgba(20, 40, 25, 0.12);
+}
+:root[data-mode="dark"] {
+  --bg: #0a0d08;
+  --fg: #3dff6e;
+  --surface: #060904;
+  --surface-fg: #3dff6e;
+  --border: #1d2a18;
+  --muted: #10180d;
+  --muted-fg: #5f8a55;
+  --primary: #3dff6e;
+  --primary-fg: #0a0d08;
+  --secondary: #10180d;
+  --secondary-fg: #3dff6e;
+  --accent: #12200f;
+  --accent-fg: #3dff6e;
+  --destructive: #ff5341;
+  --destructive-fg: #0a0d08;
+  --ring: #3dff6e;
+  --input: #1d2a18;
+  --radius: 8px;
+  --shadow: rgba(0, 0, 0, 0.55);
+}
+```
+
+
+Tokens only — no hex in `ui.tsx`. Light and dark must both read. Optional `data-look` on a root is a recipe, not a platform attribute.

package/skills/monkey-mini-app/references/looks/void.md

@@ -0,0 +1,22 @@
+<!-- generated by scripts/gen/skill — do not edit -->
+
+# Void
+
+Also known as `黑空` (sample product copy).
+
+id: `void` · grammar: `sparse-hero`
+
+**When:** Named 'premium / sparse / AI product'. Huge type, one hairline, almost empty.
+
+**Not:** Dense tables, watch boards. Opt-in only.
+
+
+## Classes (copy literals)
+
+- `root`: `flex h-full min-h-0 flex-col justify-center px-8 py-10`
+- `display`: `max-w-[12ch] text-4xl font-medium tracking-tight`
+- `hair`: `mt-6 h-px w-28 bg-linear-to-r from-foreground to-transparent`
+
+This look follows the host palette on purpose — no `theme.css`.
+
+Tokens only — no hex in `ui.tsx`. Light and dark must both read. Optional `data-look` on a root is a recipe, not a platform attribute.

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

@@ -0,0 +1,189 @@
+# Styling a mini-app
+
+Two things are decided for you and cannot be changed: **Tailwind is compiled per app at
+reload time**, and **colours come from theme tokens**. Everything below follows from that.
+
+**Reload ↔ CSS contract:** every `mini_app_reload` drops the in-memory app CSS memo
+(`caches.appCss: "dropped"`). The tool also defaults to `cleanCaches: true`, which deletes
+`.autogen/ui.css` so a stale sheet cannot survive on disk either. You do not need a second
+"clear CSS" step — if a class is missing after a green reload, the class was never in source
+(dynamic string) or the panel never re-fetched (`caches.views`).
+
+## Tailwind is real JIT over your own source — not a fixed safelist
+
+The host runs Tailwind v4 against the app directory on every compile
+(`@import "tailwindcss" source(none)` + `@source` globs over your `.ts`/`.tsx`), and serves
+the result as the app's own stylesheet next to the shared base. So the answer to "is this
+class available?" is:
+
+| You write | Works? | Why |
+|---|---|---|
+| `hover:bg-muted` `group-hover:opacity-100` `focus-visible:ring-2` | ✅ | variants are generated from your source |
+| `md:grid-cols-3` `dark:border` | ✅ | responsive + the host's `dark` class |
+| `bg-rose-500` `text-emerald-300` | ✅ | the default palette is emitted with the sheet |
+| `w-[437px]` `grid-cols-[1fr_auto]` `top-[7px]` | ✅ | arbitrary values are compiled like any other class |
+| `bg-card text-muted-foreground` | ✅ | semantic tokens → [theme.md](theme.md) |
+| `` className={`bg-${c}-500`} `` | ❌ **silently** | see below |
+
+**The one real trap: class names must appear as complete literals in your source.**
+Tailwind reads source text, it does not evaluate your template strings. A composed name
+produces no CSS and no error — the element just renders unstyled, which is how "my class
+did not work" usually turns out to be a build-time string problem.
+
+```tsx
+// ✗ no CSS is generated for the composed names
+<span className={`bg-${tone}-100 text-${tone}-700`} />
+
+// ✓ literal, one branch per case
+const map = {
+  ok: "bg-emerald-100 text-emerald-700",
+  warn: "bg-amber-100 text-amber-700",
+  bad: "bg-rose-100 text-rose-700",
+} as const;
+<span className={map[tone]} />
+```
+
+Because of this, **do not fall back to inline `style` "to be safe"**. That is strictly
+worse: you lose variants, dark mode, and the theme tokens, and you gain nothing — arbitrary
+values and variants already compile.
+
+## Colour: tokens, not literals
+
+Never hardcode hex. The user picks a palette in the panel and the host rewrites the token
+values under `<html>`; a literal colour sits outside that system and looks broken in dark
+mode. Full table → **[theme.md](theme.md)** (generated from the real stylesheet).
+
+```tsx
+// ✗ follows no palette
+<div style={{ background: "#0b1220", color: "#e2e8f0" }}>
+
+// ✓ adapts to mode and palette
+<div className="bg-card text-card-foreground">
+```
+
+Raw `var(--token)` is correct only where a utility cannot reach: SVG `fill`/`stroke`,
+gradients, `color-mix()`, or a colour you hand to a chart component.
+
+```tsx
+<svg><path fill="var(--primary)" /></svg>
+```
+
+The accent colour for SVG is `--primary`; `Illu*` illustrations already map themselves.
+
+## Layout
+
+There is no `Stack` / `Text` / `Box` component — layout is Tailwind classes on plain
+elements or on a component's `className` (every component takes `className` and `style`).
+
+```tsx
+<div className="flex flex-col gap-3 p-4 w-full">
+  <div className="grid grid-cols-1 md:grid-cols-3 gap-4">…</div>
+</div>
+```
+
+The iframe fills its panel and the app scrolls inside it, so size against the viewport
+(`h-full`, `min-h-0`, `overflow-auto`) rather than a fixed pixel height.
+
+## Custom host theme (only when the user asks)
+
+Do **not** put hex in `ui.tsx`. If the user wants a named / branded palette, write a
+**host-global** file — contract and skeleton are generated in [theme.md](theme.md)
+(*Custom host theme file*). `mini_app_edit` cannot write it (outside the app dir).
+
+Light and dark are a **pair**, not two independent palettes. Worked example:
+`docs/assets/themes/theme-crimson.css` (same hue family, not an invert).
+
+1. **One hue family, two densities.** Do not invert (`#f7f2f1` → a cold `#080d0e`).
+2. **Contrast first.** `fg` on `bg`, `surface-fg` on `surface`, `primary-fg` on `primary`,
+   `muted-fg` on both `muted` and `bg` must all read.
+3. **Dark is not dimmer light.** Drop `bg` / `surface` to a near-black of the same hue;
+   **lift** `primary` chroma (`crimson` light `#c0392b` → dark `#ff5c4d`). `primary-fg`
+   flips with the new primary.
+4. **Elevation.** `surface` a step above `bg`; `border` visible on both; `shadow` stronger in dark.
+5. **Destructive stays a distinct red** even if the brand hue is already red.
+6. **Monochrome / graphite.** `primary` is a mid grey, not blue. Do not ship only
+   `#000` / `#fff` — `muted` / `border` / `surface` need room.
+7. **No second accent hue** unless asked. `accent` is a wash of `primary`.
+8. **Verify both modes** in the panel theme pop after writing. A file that only looks right in dark has failed.
+
+## Animation
+
+The platform ships [motion](https://motion.dev) in the iframe — one build at
+`/mma/vendors/motion.js`, sharing the same React as the kit. It is not an npm install and
+not a kit re-export; you write the package name you already know:
+
+```tsx
+import { motion, AnimatePresence } from "motion/react";
+```
+
+Pick by how much you actually need:
+
+| You want | Use |
+|---|---|
+| A hover / press / colour change on one property | Tailwind `transition duration-200 ease-out` — no motion |
+| A card or row **entering** (fade + rise, staggered) | `<Reveal delay={i * 60}>` from the kit |
+| Exit animation, or a list where rows come and go | `AnimatePresence` + `motion.div` with `initial` / `animate` / `exit` |
+| Something that moves to a new position (layout shift) | `motion.div layout` |
+| A looping decorative effect (shimmer, pulse) | Tailwind `animate-pulse` / `animate-spin` first; `motion` `animate={{ … , transition: { repeat: Infinity } }}` if that is not enough |
+
+```tsx
+// rows that leave without popping out of existence
+<AnimatePresence initial={false}>
+  {items.map((it, i) => (
+    <motion.div
+      key={it.id}
+      initial={{ opacity: 0, y: 8 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, y: -8 }}
+      transition={{ delay: i * 0.04 }}
+    >
+      <Card>{it.title}</Card>
+    </motion.div>
+  ))}
+</AnimatePresence>
+```
+
+Rules that keep this from breaking:
+
+- **Keyframe names are global inside one app document.** Each mini-app runs in its own
+  iframe, so your keyframes cannot affect another app — but two of *your* components can
+  fight over one name, and whichever mounts last wins for both. That is a real, silent bug:
+  one dashboard declared `@keyframes soft-pulse` twice with different opacity values, and
+  whichever panel opened later changed the other's animation.
+- **Prefer a name the platform does not already use.** The host's own sheet defines
+  `spin`, `ping`, `pulse`, `enter`, `exit`, `accordion-down`, `accordion-up`,
+  `scroll-fade-reveal-*`, `tw-shimmer` and `mma-dot`. Declaring one of those overrides it
+  for the whole app. The reload check reports a clash as a **notice** and the app still
+  loads — overriding deliberately is allowed, being unaware of it is what gets you.
+- **Don't mix** an injected `animation` with `animate-in` / `fill-mode-both` on the same
+  element — they fight over `opacity`.
+- `motion` is **UI only**. `main.api.ts` has no React, so `import … from "motion"` there
+  fails with `BACKEND_IMPORT`.
+- Respect the OS setting: `useReducedMotion()` from `motion/react` before animating
+  position. (Kit `Reveal` already does this.)
+- Colour still comes from tokens. Animate `opacity` / `transform`, and use theme vars
+  (`var(--primary)`) rather than hex inside a keyframe. → [theme.md](theme.md)
+- Do not `mini_app_install` `motion` or `framer-motion` — the host rejects them, because a
+  second copy means a second React.
+
+```tsx
+/* ✓ your own name, so nothing else in this document is sharing it */
+<style>{`@keyframes ledger-row-in { from { opacity: 0; transform: translateY(6px) } }`}</style>
+
+/* ✗ silently redefines Tailwind's spin for every animate-spin in the app */
+<style>{`@keyframes spin { to { transform: rotate(360deg) } }`}</style>
+```
+
+## What is actually on disk
+
+`.autogen/` inside an app holds the generated Tailwind output. It is overwritten on the
+next compile — never edit it, and never import from it.
+
+## Checklist
+
+- [ ] every class name is a complete literal in the source (no `` `bg-${x}-500` ``)
+- [ ] no hex / rgb literals for themeable colour — tokens only
+- [ ] sized against the viewport, not a fixed height
+- [ ] animations use `motion` / kit `Reveal`, or a Tailwind transition — and any custom
+      `@keyframes` has a name the platform sheet does not already define → *Animation*
+- [ ] ask the live view what won: `mini_app_view_eval({ appId, code: 'const cs = getComputedStyle(mma.$(".your-class")); return { color: cs.color, bg: cs.backgroundColor };' })` → [eval.md](eval.md)

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

@@ -1,22 +1,22 @@
-# Host 冒烟调试（人类用）
+# Host smoke debugging
 
-这是 **Host `:17880` 调试**，不是小程序里的 `ctx.http`。
+This is **host `:17880` debugging**, not `ctx.http` inside a mini-app.
 
-冒烟请用聊天工具 **`mini_app_call({ appId, method, args })`**，不要 bash/curl。
+For smoke tests use the chat tool **`mini_app_call({ appId, method, args })`** — not bash, not curl.
 
-Base: `http://127.0.0.1:17880`（插件 apply 时已 listen，打开小程序面板会预热）。仅在人类调试时用 curl。
+Base: `http://127.0.0.1:17880` (the host listens when the plugin applies; opening the mini-app panel warms it). Use curl only when a human is debugging.
 
-| 方法 | 路径 | Body | 结果 |
+| Method | Path | Body | Result |
 |------|------|------|------|
 | GET | `/api/apps` | | `{ apps: [{ id, name, version }] }` |
 | GET | `/api/ctx-tools` | | `{ count, tools: [{ name, description, schema }] }` |
-| POST | `/api/call` | `{ appId, method, args }` | `{ ok: true, value }` 或 `{ ok: false, error }` |
+| POST | `/api/call` | `{ appId, method, args }` | `{ ok: true, value }` or `{ ok: false, error }` |
 | GET | `/app/:id` | | runner HTML |
-| GET | `/api/app/:id/ui/entry.js` | | per-app UI bundle（编译缓存） |
-| GET | `/ui.css` | | @monkey-mini-app/ui 全局样式 |
+| GET | `/api/app/:id/ui/entry.js` | | Per-app UI bundle (compile cache) |
+| GET | `/ui.css` | | Component-library global CSS (injected by the host; never import it from an app) |
 | DELETE | `/api/app/:id` | | `{ ok, appId }` |
-| GET/POST | `/api/host-config` | POST `{ hostPort, theme, palette, … }` | Host 设置 |
-| GET/POST | `/api/llm-config` | POST `{ provider, model }` | 写入 `runtime/llm.json` |
+| GET/POST | `/api/host-config` | POST `{ hostPort, theme, palette, … }` | Host settings |
+| GET/POST | `/api/llm-config` | POST `{ provider, model }` | Writes `runtime/llm.json` |
 
 ```bash
 curl -s http://127.0.0.1:17880/api/apps
@@ -25,6 +25,6 @@ curl -s http://127.0.0.1:17880/api/call \
   -d '{"appId":"com.example.todo","method":"list","args":{"filter":"all"}}'
 ```
 
-CORS 已开。改 `main.api.ts` 后直接再 curl，不必开浏览器。
+CORS is open. After editing `main.api.ts` just curl again — no browser needed.
 
-小程序后端抓外网 API：用 `ctx.http`，见 [ctx.md](ctx.md)。
+To fetch an external API from a mini-app backend, use `ctx.http` — see [ctx.md](ctx.md).