@chalky/chalky 0.1.4 → 0.1.6

package/README.md

@@ -21,6 +21,9 @@ MODEL_BASE_URL=https://your-endpoint/v1 MODEL_API_KEY=... MODEL_NAME=your-model
 
 Then open http://127.0.0.1:3000.
 
+To update: `npm update -g @chalky/chalky`, then restart `chalky`. The new version is merged with what your agents
+changed (see `agent/` below).
+
 | Variable | |
 |---|---|
 | `MODEL_BASE_URL` | the endpoint, up to `/v1` |
@@ -34,13 +37,21 @@ Then open http://127.0.0.1:3000.
 
 `~/.chalky` (or `CHALKY_HOME`) holds:
 
-- `app/`: the agents' code, copied from the package on the first run. The agents edit it, and each change is
-  versioned. A newer version of the package doesn't overwrite it.
-- `state/`: conversations, version history, what the apps keep.
-- `workspace/`: the agents' working folder.
+- `agent/`: what the agents are: their prompt, settings and extensions (the page among them). The agents edit it.
+  Each new version of the package is merged into it at the next start, as a version in the history: files only the
+  new version changed are updated, files only your agents changed stay theirs, and both changes go in when they
+  touch different lines. When both changed the same lines, yours stays, the new version waits next to it as
+  `<file>.new`, and agent1 merges the two. Undo an update like any change, in Versions.
+- `built/`: what the agents made for you: the cards on your boards, and the apps they wrote.
+- `data/`: what is kept while running: conversations, what you typed into cards and apps, notes, undo history.
+- `workspace/`: the agents' working folder; `workspace/drops/` holds your files.
+
+`agent/` and `built/` share one version history: each agent turn that changes them is saved, and a rollback puts
+both back. A home from before this layout (`app/`, `state/`) is moved into it on the first start; the old code
+stays in `app-before-reorg/`.
 
 ## MCP servers
 
-Tools from MCP servers go in `~/.chalky/app/mcp.json`, in pi's format (stdio or streamable HTTP; see pi's
+Tools from MCP servers go in `~/.chalky/agent/mcp.json`, in pi's format (stdio or streamable HTTP; see pi's
 `docs/mcp.md`). Type `/mcp` on the page to choose which servers and tools the agents may use. Keep secrets in
 environment variables and refer to them as `${NAME}` in `headers` or `env`.

package/agent/SYSTEM.md

@@ -0,0 +1,36 @@
+You are an agent in Chalky. You build what the user sees: the page is a workspace where what you build (cards on
+boards, each showing blocks or an app) fills the screen, and the conversation is a side panel. The user says what they want; you put a
+first version on screen that is already complete and polished; then they point at things on it and leave notes, and
+you change exactly that. The user marks up details, not missing basics.
+- Build, don't describe. A first version they can point at beats questions you could answer by building.
+- Your final reply is the only text they read in full: one or two sentences on what changed.
+- The page around your work is the user's: change it only when asked. Build inside the main space.
+
+What follows this: the skills you can load, your working folder (<cwd>: bash runs there), one short section for
+each part of you that has something to say (each comes from an extension), and <paths>: your four folders, the
+host and pi's docs. In README.md files and skills, {agent}/..., {built}/..., {data}/... and {workspace}/... are paths
+in those folders. A section that names a README.md is the short version of its extension: read that file when the
+section says, once (it stays in your conversation). Some tools are loaded only when needed: tool_search finds and
+loads them (card_blocks, viewer_read, screen_see, team_reset, MCP servers' tools). Tools you already have need no
+search.
+Two kinds of change, two places: what the user asks you to make (a card, an app) goes in {built}; a change to how
+Chalky itself works is a change to you, in {agent}.
+
+Your tools:
+- read to look at files and pictures (not cat or sed); bash for ls, grep, find and running things.
+- edit for precise changes: each edits[].oldText must match the file exactly and only once; keep it as small as
+  that allows. Several changes in one file: one edit call with several entries, each matched against the original
+  file, none overlapping. An edit whose newText equals its oldText changes nothing and is refused.
+- write only for new files or complete rewrites.
+- Name files by their full path when you mention them.
+
+Changing yourself: when the work needs it, you can change any part of you, the page included. You are pi
+extensions, one folder each: {agent}/extensions/<name>/. In it, index.ts is `export default function (pi:
+ExtensionAPI) { ... }`, which registers tools (pi.registerTool) and event handlers (pi.on); and as the extension
+needs them, guide.md (its prompt section, found by itself), README.md (the whole of it), browser.js (its part of
+the page, found by itself) and skills/. The page itself is the page extension; this text is {agent}/SYSTEM.md;
+pi's settings (e.g. compaction) are {agent}/settings.json (pi's docs/settings.md). Extensions reach
+shared state and the web server through globalThis.chalky: the host, the fixed core under them (don't edit it).
+Read pi's extension docs (<paths>) before writing or changing an extension. After editing, call the reload tool:
+your extensions load again when your turn ends, and your conversation is kept. A changed page or browser.js shows
+when the page reloads, after your turn.

package/agent/extensions/app/README.md

@@ -0,0 +1,72 @@
+# Making an app (the app extension)
+Everything a usual app needs is here (you don't need the card README). The design skill goes deeper on charts,
+diagrams, game art and one look across cards: load it when the app has any of those.
+
+## Before you write
+The first version is already complete and polished: the user marks up details, not missing basics. So first list,
+in a short message, the 3-5 things that would make this app impressive for this subject: what someone who knows the
+subject would expect to find, and a picture (diagram, chart, animation) wherever one explains faster than text.
+Then build all of them in the first version, not a smaller first cut.
+
+## Write it, show it
+- Write {built}/apps/<name>/index.html (other files next to it), then card_show(card=<id>, app=<name>, about="...").
+  It is served at {page}/built/apps/<name>/. card_show checks it on the board and reports errors and whether it
+  fits its card: fix those and show it again. height=<px>: its height when nothing else sizes it (default 400).
+- about: one or two sentences on what it is for and any decision a later change should respect (its back side).
+- Name what the user may point at: ids or data-name on elements ("habit-Read", not "row3"). A canvas: give the
+  page's window a partAt(x, y) returning {"name", ...} for what is at that spot.
+- The user moves and resizes the card: fill the space (%, flex, grid, an SVG with a viewBox), not fixed px.
+- A pinned card (the user held its label): card_show on it fails. Make a new card (made_from=[it]) or ask.
+- Changing it later: edit the part (the edit tool), not a rewrite. App files show when your turn ends.
+
+## Keep its data
+`import agents from "/app/agents.js"` (a module script). `await agents.load()` gives the saved data ({} at first);
+`agents.save(data)` replaces it after every change (on the server, {data}/app/<name>.json: kept across reloads, the
+same in every browser, readable by you with cat). Other cards showing the same app hear each save:
+`agents.on("app_data", ({app, data}) => { if (app === agents.app) ... })` (the field is `data`). Never localStorage
+(one browser only, invisible to you). To change it yourself: curl -X PUT --data @new.json {page}/app/data/<name>.
+
+## An app that asks an AI (a plan from a goal, a summary, an answer)
+A real agent does it, never a canned sample. While building, spawn one for the card: team_spawn(role, name="planner",
+app=<card id>), its role ending "Answer only with JSON like {...}. Don't use tools." In the app:
+```
+const asked = Date.now() / 1000; agents.send("planner", goal);
+agents.on("message", (ev) => {  // events replay on connect: take only the answer to this question
+  if (ev.agent !== "planner" || ev.role !== "assistant" || ev.tool_calls?.length || ev.ts < asked) return;
+  data.plan = JSON.parse(ev.text.slice(ev.text.indexOf("{"), ev.text.lastIndexOf("}") + 1)); agents.save(data); draw();
+});
+```
+Show that it is thinking while it waits; agents.send is limited per minute. Agents with personalities that talk to
+each other (a debate, a simulation): load the app-agents skill.
+
+## Apps that work together
+Each card is its own page: a click in one never reaches another. One app saves what was picked
+(`agents.save({...data, picked: "Goblet squat"})`); the other hears every app's saves:
+`agents.on("app_data", ({app, data}) => { if (app === "fitflow") show(data.picked) })`, and can read the first one's
+data at start with `fetch("/app/data/fitflow").then((r) => r.json())`.
+
+## Look
+The page is light, glassy and quiet; match it unless the user asks for another look:
+- Transparent background; the system font (`font: inherit` or system-ui); text #1d1d1f, muted rgba(60,60,67,.55),
+  accent #0071e3, danger #e5484d, lines rgba(0,0,0,.06), glass rgba(255,255,255,.7), radius 16px.
+- Show just the thing: no frame or panel around it unless it needs one. Group with flex/grid and gap.
+- Open in a working state (its real data, or a marked example), never an empty shell; `tabular-nums` for digits.
+- Buttons say what happens ("Add habit"); short plain words; status colours always with a word or icon.
+- Ground it in the subject: its real units, terms and conventions (a chess clock shows mm:ss; a kanban card has an
+  owner and a state). Real content, never lorem ipsum.
+- Summary before detail; show state in form (a pill, a chip, a stripe) as well as numbers.
+- Finish every state: empty, loading, error, done. Interactive things look interactive (hover, pressed, visible
+  keyboard focus); a small transition where something changes, never content hidden waiting for an animation.
+- Avoid the generic AI look: cream and terracotta, purple gradients, emoji as markers, the same shadowed card on
+  everything. For a chart, a diagram, a game's art or a restyle, load the design skill.
+
+## Check it works
+card_show covers errors and fit. Then, before telling the user what it does, use it on their page as they would:
+load the test-your-app skill. Say only what you saw working.
+
+## More
+- Calculations (totals, streaks, dates) belong in the page's code, never worked out by you and typed in.
+- Voice input: import /voice/voice.js (read its header), not the browser's speech API.
+- Libraries: put an ES-module build in {agent}/extensions/card/lib/<pkg>/ and import /card/lib/<pkg>/<file>.js.
+- agents.action(name, context) wakes the agent that owns the card (for what truly needs you); the rest of the
+  bridge: the header of {agent}/extensions/app/agents.js.

package/{app/extensions/ui → agent/extensions/app}/agents.js

@@ -1,18 +1,19 @@
-// Bridge from an app ({code}/ui/apps/<name>/, shown by the App component) to the agents. An app imports it:
-//   import agents from "/ui/agents.js";
+// Bridge from an app ({built}/apps/<name>/, shown on a card) to the agents. An app imports it:
+//   import agents from "/app/agents.js";
 //   agents.send(to, text)         a message to an agent, from "app"; its answer comes as a "message" event
 //                                 (role "assistant", no tool_calls). Each one is a model call: limited per minute.
-//   agents.action(name, context)  an action for the agent that owns this app's surface, like a Button
+//   agents.action(name, context)  an action for the agent that owns this app's card, like a Button
 //   agents.on(type, fn)           events as the page gets them, past ones first (replayed on connect), then live:
-//                                 "message" {agent, role, content, tool_calls, ts}: every message of every agent,
-//                                 incl. its ask_agent / tell calls (who talks to whom); "status" {agents}: who is busy
+//                                 "message" {agent, role, content, tool_calls, ts, to, text}: every message of every agent;
+//                                 to and text: its "[to: <name>]" tag ("all" without one) and the words after it;
+//                                 incl. its team_ask / team_tell calls (who talks to whom); "status" {agents}: who is busy
 //   agents.list()                 {name: {role, app, state, doing, queued}}, from the latest "status" event
-//   agents.reset()                empty the memories of this app's agents (spawned with app=<this surface>),
+//   agents.reset()                empty the memories of this app's agents (spawned with app=<this card>),
 //                                 roles kept: a fresh round. Refused (an "error" event) while one is busy.
-//   agents.load()                 this app's saved data ({} at first), from the appdata plugin (on the server)
+//   agents.load()                 this app's saved data ({} at first), kept by the app extension (on the server)
 //   agents.save(data)             replace it; every page and app frame then gets "app_data" {app, data}, so
-//                                 the same app in other surfaces updates (check ev.app === agents.app)
-//   agents.app                    this app's name: its folder in {code}/ui/apps
+//                                 the same app on other cards updates (check ev.app === agents.app)
+//   agents.app                    this app's name: its folder in {built}/apps
 // It opens its own WebSocket to /ws, the page's protocol (the page extension).
 const ws = new WebSocket((location.protocol === "https:" ? "wss://" : "ws://") + location.host + "/ws");
 const open = new Promise((resolve) => ws.addEventListener("open", resolve));
@@ -22,23 +23,28 @@ let status = {};
 ws.onmessage = (e) => {
   const ev = JSON.parse(e.data);
   if (ev.type === "status") status = ev.agents;
+  if (ev.type === "message" && typeof ev.content === "string") {  // an app agent's "[to: <name>] ..." answer, read once here
+    const tag = /^\s*\[to:\s*([^\]]+)\]\s*/i.exec(ev.content);
+    ev.to = tag ? tag[1].trim() : "all";
+    ev.text = tag ? ev.content.slice(tag[0].length) : ev.content;
+  }
   for (const fn of listeners[ev.type] || []) fn(ev);
 };
 
-// In the versions plugin's screenshot (/?shot) the app is only looked at: send nothing, no model calls.
+// In the version extension's screenshot (/?shot) the app is only looked at: send nothing, no model calls.
 const shot = new URLSearchParams(window.top.location.search).has("shot");
 const post = async (obj) => { if (shot) return; await open; ws.send(JSON.stringify(obj)); };
-const app = location.pathname.split("/")[3];  // /ui/apps/<name>/...
-const store = `/ui-api/app-data/${app}`;
-// the surface this app is shown in (the App component's frame sits inside it on the page)
-const surface = () => window.frameElement?.closest("[data-surface]")?.dataset.surface;
+const app = location.pathname.split("/")[3];  // /built/apps/<name>/...
+const store = `/app/data/${app}`;
+// the card this app is shown on (its frame sits inside the card on the page)
+const card = () => window.frameElement?.closest("[data-card]")?.dataset.card;
 
 export default {
   send: (to, text) => post({ type: "app_message", to, text }),
-  action: (name, context = {}) => post({ type: "ui_action", surface: surface(), component: "app", name, context }),
+  action: (name, context = {}) => post({ type: "card_action", card: card(), block: "app", name, context }),
   on: (type, fn) => (listeners[type] ??= []).push(fn),
   list: () => status,
-  reset: () => post({ type: "app_reset", surface: surface() }),
+  reset: () => post({ type: "app_reset", card: card() }),
   app,
   load: async () => (await fetch(store, { cache: "no-store" })).json(),
   save: async (data) => { if (!shot) await fetch(store, { method: "PUT", body: JSON.stringify(data) }); },

package/agent/extensions/app/guide.md

@@ -0,0 +1,5 @@
+# Apps
+An app is a page you write in {built}/apps/<name>/ and show on a card (card_show with app). It keeps what the user
+makes in it (notes, lists, picks) with /app/agents.js (agents.load, agents.save), on the server and shared by every
+card showing it; never localStorage (one browser only, and you can't see it).
+Before writing or changing an app, read README.md: it has all an app needs (showing it, its data, its look, checking it).

package/agent/extensions/app/index.ts

@@ -0,0 +1,66 @@
+// Apps: pages the agents write in built/apps/<name>/ (the host serves them at /built/apps/<name>/), shown on a card
+// (the card extension draws the frame). This extension gives apps what a plain page can't have:
+//   - their data, kept on the server: one JSON value per app in data/app/<name>.json, so it outlives the page, is
+//     the same in every browser, and the agents can read it. Whole value replaced each time: the last save wins
+//     (keep one app's data in one value). The same app on several cards shares it: every save is an "app_data" event;
+//   - agents.js, their bridge to the agents (load, save, send, action, reset, on: read its header);
+//   - the app-agents skill (apps with agents inside, e.g. a simulation's members).
+//   GET /app/data/<name>    the app's data ({} if none yet)        GET /app/agents.js   the bridge
+//   PUT /app/data/<name>    replace it (JSON, at most MAX_BYTES); event "app_data" {app, data}
+//   page messages  app_message {to, text}: to an agent, from "app" (at most MESSAGES_PER_MINUTE, all apps together)
+//                  app_reset {card}: empty the memories of the agents spawned for the app on that card (the team's reset)
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const host = (globalThis as any).chalky;
+const DIR = path.join(host.data, "app");
+const MAX_BYTES = 1024 * 1024;
+const MESSAGES_PER_MINUTE = 30;
+const sent: number[] = host.shared.get("app-sent") ?? [];  // when apps sent messages (on the host: outlives reloads)
+host.shared.set("app-sent", sent);
+const json = (res: any, v: unknown, status = 200) => res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(v));
+
+export default function (pi: ExtensionAPI) {
+  pi.on("resources_discover", () => ({ skillPaths: [path.join(import.meta.dirname, "skills")] }));
+
+  host.routes.set("/app/agents.js", (_req: any, res: any) => host.file(res, path.join(import.meta.dirname, "agents.js")));
+  host.routes.set("/app/data/", (req: any, res: any) => {
+    const name = decodeURIComponent(new URL(req.url, "http://x").pathname.slice("/app/data/".length));
+    if (!/^[\w-]+$/.test(name)) return json(res, { error: "app names are letters, digits, _ and -" }, 400);
+    const p = path.join(DIR, name + ".json");
+    if (req.method === "GET") {
+      if (!fs.existsSync(p)) return json(res, {});
+      return res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" }).end(fs.readFileSync(p));
+    }
+    if (req.method !== "PUT") return res.writeHead(405).end();
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on("data", (c: Buffer) => { size += c.length; if (size <= MAX_BYTES) chunks.push(c); });
+    req.on("end", () => {
+      if (size > MAX_BYTES) return json(res, { error: `over ${MAX_BYTES / 1024} KB` }, 400);
+      let data;
+      try { data = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch (e: any) { return json(res, { error: `not JSON: ${e.message}` }, 400); }
+      fs.mkdirSync(DIR, { recursive: true });
+      fs.writeFileSync(p + ".tmp", JSON.stringify(data));
+      fs.renameSync(p + ".tmp", p);
+      host.broadcast("app_data", { app: name, data });
+      json(res, { saved: true });
+    });
+  });
+
+  host.pageHandlers.set("app", async (msg: any) => {
+    const team = host.api.team, error = (text: string) => host.broadcast("error", { agent: "app", text });
+    if (msg.type === "app_reset" && team) {
+      const names = [...host.agents.values()].filter((x: any) => x.app === msg.card).map((x: any) => x.name);
+      const problem = await team.reset(names);
+      if (problem) error(`reset of ${msg.card}: ${problem}`);
+    } else if (msg.type === "app_message" && team) {
+      const now = Date.now();
+      sent.splice(0, sent.length, ...sent.filter((t) => now - t < 60000));
+      if (!host.agents.has(msg.to)) error(`app message to unknown agent '${msg.to}'`);
+      else if (sent.length >= MESSAGES_PER_MINUTE) error(`app message to ${msg.to} dropped: more than ${MESSAGES_PER_MINUTE} a minute`);
+      else { sent.push(now); team.send("app", msg.to, msg.text ?? ""); }
+    }
+  });
+}

package/{app/extensions/ui/skills/agent-apps → agent/extensions/app/skills/app-agents}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: agent-apps
-description: Build an app whose members are real AI agents (a simulated board meeting, a debate, a negotiation, a panel of experts, game characters), run and shown by the app itself, in turns or all at once. Use when the user wants agents inside what you build, as opposed to agents helping you build it.
+name: app-agents
+description: Build an app whose members are real AI agents (a simulated board meeting, a debate, a negotiation, a panel of experts, game characters), run and shown by the app itself, in turns or all at once. Use when the user wants agents inside what you build, as opposed to agents helping you build it. (One agent that just answers the app's questions: the app README's recipe is enough.)
 ---
 # Apps with real agents inside
 
@@ -8,8 +8,8 @@ description: Build an app whose members are real AI agents (a simulated board me
 |                   | Worker agents                   | App agents                                   |
 |-------------------|---------------------------------|----------------------------------------------|
 | What for          | help you build or fix the app   | are part of the app (a board member, a debater) |
-| Spawn             | `spawn_agent(role)`             | `spawn_agent(role, name, app="<surface>")`    |
-| Who talks to them | you (`tell`, `ask_agent`)       | the app, through `/ui/agents.js`             |
+| Spawn             | `team_spawn(role)`              | `team_spawn(role, name, app="<card>")`       |
+| Who talks to them | you (`team_tell`, `team_ask`)   | the app, through `/app/agents.js`            |
 | Messages panel    | shown                           | hidden: the app shows their talk             |
 | When they run     | while you build                 | each time the user runs the app              |
 
@@ -19,7 +19,7 @@ is what keeps app agents out of the user's messages panel and lets the app reset
 ## Why the app runs the activity, not you
 Your context is large (system prompt plus everything you did while building): each of your model calls
 costs all of it, often 50k tokens or more. If you relay a meeting yourself (ask the chair who's next, ask
-that member, `ui_update` the transcript), every line spoken costs two or three of your calls. The app
+that member, `card_update` the transcript), every line spoken costs two or three of your calls. The app
 can talk to its agents directly, and their contexts are small. So you build, fix, and answer the user;
 at run time you make no calls at all.
 
@@ -28,17 +28,17 @@ at run time you make no calls at all.
    stance and personality. End each role with: "You are a character in <app>. Answer in plain text,
    briefly, starting with [to: <name>] or [to: all]. Don't use tools." App agents have the same tools
    you have; this keeps them in character, fast, and gives the app a "to" to draw.
-2. **Build the UI as an App**: `ui/apps/<name>/index.html` in your code folder (the one your prompt names, with
-   `extensions/` in it), and its scripts, shown with
-   `ui_render("<surface>", [{"id": "root", "component": "App", "src": "<name>/index.html"}])`.
-   An App can import `/ui/agents.js`; the bridge finds the app's surface from the frame it runs in.
-3. **Spawn the members once**, while building: `spawn_agent(role, name=..., app="<surface>")`, the same
-   string as the surface id. In the app, check `agents.list()`: if a member is missing, show that
+2. **Build it as an app**: `{built}/apps/<name>/index.html` and its scripts, shown on a card with
+   `card_show(card="<card>", app="<name>")`.
+   An app can import `/app/agents.js`; the bridge finds the app's card from the frame it runs in.
+3. **Spawn the members once**, while building: `team_spawn(role, name=..., app="<card>")`, the same
+   string as the card id. In the app, check `agents.list()`: if a member is missing, show that
    instead of failing.
-4. **Wire the app with `/ui/agents.js`** (read its header):
+4. **Wire the app with `/app/agents.js`** (read its header: {agent}/extensions/app/agents.js):
    - `send(to, text)`: ask a member. Its answer arrives as a `"message"` event: `agent` is that member,
      `role` is `"assistant"`, and there are no `tool_calls` (its final answer).
-   - `on("message", fn)`: draw each answer as it arrives (speaker, the `[to: …]` target, the text).
+   - `on("message", fn)`: draw each answer as it arrives: `ev.agent` (the speaker), `ev.to` (its target,
+     "all" when it gave none) and `ev.text` (the answer without its `[to: …]` tag; show this, not `ev.content`).
    - `reset()`: a fresh round, members' memories empty and roles kept. Call it before each run if the
      user wants rounds to start fresh.
    - `action(name, context)`: only for what needs you, e.g. "add a member" (you spawn it).
@@ -48,11 +48,11 @@ at run time you make no calls at all.
    - All at once: send to several members together; answers come back in any order, so draw each one
      as it arrives.
    Members only know what you send them: include the transcript so far (or its last lines) each time.
-6. **Check it** with the ui-check skill: one short run, budget 2 or 3 messages (each is a real model call).
+6. **Check it** with the browser-check skill: one short run, budget 2 or 3 messages (each is a real model call).
 
 ## The ask helper (copy into the app)
 ```js
-import agents from "/ui/agents.js";
+import agents from "/app/agents.js";
 const waiting = {};  // member -> resolve() for its next final answer
 agents.on("message", (ev) => {
   if (ev.role === "assistant" && !ev.tool_calls?.length && waiting[ev.agent]) {
@@ -76,7 +76,7 @@ answer from an earlier run must not resolve a new question.
   with play, pause and a scrubber.
 - After a reload, past events replay: rebuild earlier runs from them (only your members' messages).
   A member's `"system"` message means a fresh memory, i.e. a new round began.
-- Don't keep the transcript in the surface's data with `ui_update`: that is you relaying again.
+- Don't keep the transcript in the card's data with `card_update`: that is you relaying again.
 
 ## Limits
 - App messages: at most 30 a minute (each is a model call); more are dropped with an `"error"` event.
@@ -86,6 +86,5 @@ answer from an earlier run must not resolve a new question.
 
 ## Pitfalls
 - Disable Start while a run is going: a double click starts two runs.
-- An answer without a `[to: …]` tag: treat it as to all.
 - If the app shows nothing, the panel won't help (app agents are hidden there): check the app with
-  ui-check, e.g. `eval:` the length of its transcript, and look for `"error"` events.
+  browser-check, e.g. `eval:` the length of its transcript, and look for `"error"` events.

package/agent/extensions/app/skills/test-your-app/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: test-your-app
+description: Test an app you built by using it on the user's page as they would - its main tasks start to finish, a look at it, a reload. Use after card_show, before you tell the user what the app does or that it works.
+---
+# Testing an app you built
+
+Load the interact-with-page skill first: this one only adds what testing needs.
+
+1. Save the app's data: `cat {data}/app/<name>.json > /tmp/<name>.saved.json` (no file: it has saved nothing yet).
+   The test writes the user's real data.
+2. List the user's main tasks, from the app's about and your plan: add, change, remove, filter, the one idea that
+   makes it worth having.
+3. Do each task start to finish through the interface, with the helpers, one or a few steps per page_run, each
+   ending with a read. Never call the app's own functions or set its state yourself: that tests your code, not what
+   the user gets. After each step: did what you expected appear? Any errors in the answer?
+4. Look once: screen_see, and check what reading can't: text cut off or overlapping, things outside their box,
+   colours off the palette, a chart that doesn't match its numbers, empty space. If the user doesn't share their
+   screen, take a browser-check screenshot of {page}/built/apps/<name>/index.html (--shot) and read it.
+5. Reload: `location.reload()` in one page_run, then a read in the next: what was kept?
+6. Fix what you found (edit the part), show it again, and redo the tasks that touched it.
+7. Put the data back: `curl -X PUT --data @/tmp/<name>.saved.json {page}/app/data/<name>` (nothing saved: `--data '{}'`).
+8. Tell the user what you did and what you saw ("added and ticked a habit, reloaded: kept; long names were cut off,
+   now they wrap"), not just "it works".

package/{app/extensions/boards → agent/extensions/board}/browser.js

@@ -1,16 +1,16 @@
-// Browser half of boards: the main space as numbered boards, and the shelf to move between them (above the input).
+// The page side of the board extension: the main space as numbered boards, and the shelf to move between them (above the input).
 // Each board is a container in #top. The one you're on is display: contents (its things sit in the main space as
 // before); the others are laid out but hidden, so apps in them keep running and the shelf can draw them.
-// Any element with data-board="n" that lands in #top (a surface, a frame) is moved into board n's container, and
+// Any element with data-board="n" that lands in #top (a card, a frame) is moved into board n's container, and
 // moved again when its data-board changes (a MutationObserver): no extension needs this one. One on the body (a
 // note's pin, fixed to the window) shows only while its board is shown.
 // Other scripts read the board shown from body[data-board] (new things go there), and get a DOM event "board"
 // {from, to} just before it changes (doodle: the drawing so far becomes a step; frames: count this board's).
 // The shelf: a dot per board (yours is bigger). Hover it and the dots open into thumbnails, with + for a new board;
 // click one to go there. It stays clear of the chat panel: more thumbnails than fit scroll between ‹ and › (grey at
-// the ends; a new board scrolls to the end). Drag a surface by its label onto a thumbnail to move it to that board, where it was ({type: "ui_board"}).
+// the ends; a new board scrolls to the end). Drag a card by its label onto a thumbnail to move it to that board, where it was ({type: "card_board"}).
 //   page messages  board_view {board}: the board this page shows; board_add
-//   GET /boards    {boards, current}        event "boards" {boards, added?, by?}
+//   GET /board     {boards, current}        event "board" {boards, added?, by?}
 const CSS = `
   #top > .board:not(.on) { position: absolute; top: 0; left: 0; right: 0; height: 0; overflow: hidden; padding: inherit;
     box-sizing: border-box; visibility: hidden; pointer-events: none; }
@@ -25,9 +25,6 @@ const CSS = `
   .boards-shelf .slot .x { display: none; position: absolute; top: 3px; right: 3px; width: 16px; height: 16px; border-radius: 50%;
     font-size: 9px; line-height: 16px; text-align: center; color: var(--danger); background: var(--glass-strong); box-shadow: var(--shadow); }
   .boards-shelf.open .slot:hover .x { display: block; }
-  .boards-toast { position: fixed; left: 50%; top: 76px; transform: translateX(-50%);  /* under the palette: clear of the shelf */ z-index: 27; display: flex; gap: 12px;
-    align-items: center; padding: 7px 14px; border-radius: 10px; background: rgba(29, 29, 31, 0.88); color: #fff; font-size: 13px; }
-  .boards-toast button { color: #9cc3f5; font-weight: 600; }
   .boards-shelf .dot { width: 7px; height: 7px; border-radius: 50%; background: rgba(0, 0, 0, 0.22); transition: all 0.15s; }
   .boards-shelf .slot.on .dot { width: 11px; height: 11px; background: var(--text); }
   /* more boards than fit (fit(): clear of the chat panel): the thumbnails scroll inside .view, between ‹ and › */
@@ -41,7 +38,7 @@ const CSS = `
   .boards-shelf .mini { display: none; position: relative; width: 120px; overflow: hidden; border-radius: 6px;
     background: rgba(255, 255, 255, 0.6); border: 1px solid var(--line); }
   .boards-shelf .mini i, .boards-peek .mini i { position: absolute; overflow: hidden; border-radius: 3px; background: rgba(0, 0, 0, 0.08); }
-  /* a surface: a card in its own main colour (light grey when it has none) */
+  /* a card: a tile in its own main colour (light grey when it has none) */
   .boards-shelf .mini i.s, .boards-peek .mini i.s { --accent-of: rgb(200, 203, 210);
     background: color-mix(in srgb, var(--accent-of) 30%, #fff);
     box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--accent-of) 70%, transparent), 0 1px 3px rgba(0, 0, 0, 0.08); }
@@ -93,6 +90,7 @@ export default async function (page) {
 
   // the shelf: ‹ [the thumbnails, scrolling] › +   (+ outside the scrolling part, so it is always there)
   const shelf = Object.assign(document.createElement("div"), { className: "boards-shelf" });
+  shelf.dataset.name = "boards";
   const button = (className, textContent, title, onclick) => Object.assign(document.createElement("button"), { className, textContent, title, onclick });
   const view = Object.assign(document.createElement("div"), { className: "view" });
   const track = Object.assign(document.createElement("div"), { className: "track" });
@@ -100,6 +98,7 @@ export default async function (page) {
   const prev = button("arrow", "‹", "Earlier boards", () => step(-1));
   const next = button("arrow", "›", "Later boards", () => step(1));
   const add = button("add", "+", "New board", () => { adding = true; page.send({ type: "board_add" }); });
+  add.dataset.name = "new-board";
   view.append(track);
   shelf.append(prev, view, next, add);
   document.body.append(shelf);
@@ -171,8 +170,7 @@ export default async function (page) {
   // ✕ on a thumbnail: the board leaves the shelf with a few seconds of Undo, and only then goes from the server
   // (board_remove: its things go with it). Leaving the page in those seconds removes it at once.
   let pending = null;  // {n, was: the board shown when ✕ was clicked, timer}
-  const toast = Object.assign(document.createElement("div"), { className: "boards-toast", hidden: true });
-  document.body.append(toast);
+  let toast = null;  // the notice with Undo (pageApi.notice)
   function removeBoard(n) {
     if (pending) commit();
     const i = boards.indexOf(n);
@@ -180,20 +178,20 @@ export default async function (page) {
     peek.hidden = true;
     if (current === n) show(boards.filter((b) => b !== n)[Math.max(0, i - 1)]);  // the one before it (else after)
     else render();
-    toast.replaceChildren(`Board ${n} removed`, button("", "Undo", "Bring it back", undo));
-    toast.hidden = false;
+    toast?.close();
+    toast = page.notice([`Board ${n} removed`, button("go", "Undo", "Bring it back", undo)], () => pending && commit());  // ✕: removed now
   }
   function commit() {
     clearTimeout(pending.timer);
     page.send({ type: "board_remove", board: pending.n });
     pending = null;
-    toast.hidden = true;
+    toast?.close();
   }
   function undo() {
     clearTimeout(pending.timer);
     const { n, was } = pending;
     pending = null;
-    toast.hidden = true;
+    toast?.close();
     if (was === n) show(n);
     else render();
   }
@@ -202,8 +200,8 @@ export default async function (page) {
   function thumbnails() {
     for (const slot of shelf.querySelectorAll(".slot")) drawBoard(slot.querySelector(".mini"), Number(slot.dataset.n), 120, 68);
   }
-  // board n's things where they are in the main space, scaled down into mini (w x h): a surface is a small card in
-  // its main colour (accentOf), no words. Zoomed to fit what's on the board (not the whole window), so the cards fill it.
+  // board n's things where they are in the main space, scaled down into mini (w x h): a card is a small tile in
+  // its main colour (accentOf), no words. Zoomed to fit what's on the board (not the whole window), so the tiles fill it.
   function drawBoard(mini, n, W, H) {
     const PAD = 12, els = [...container(n).children];
     const rects = els.map((el) => el.getBoundingClientRect());
@@ -212,10 +210,10 @@ export default async function (page) {
     mini.style.height = `${H}px`;
     mini.replaceChildren(...els.map((el, n) => {
       const r = rects[n], i = document.createElement("i");
-      if (el.dataset.surface) {
-        const accent = accentOf(el.querySelector(".surface-body") ?? el);
+      if (el.dataset.card) {
+        const accent = accentOf(el.querySelector(".card-body") ?? el);
         i.className = "s";
-        i.title = el.dataset.surface;
+        i.title = el.dataset.card;
         if (accent) i.style.setProperty("--accent-of", accent);
         if (W > 200) { i.classList.add("detail"); sketch(el, i, k); }  // the big preview: what's inside it
       }
@@ -238,20 +236,20 @@ export default async function (page) {
     peek.style.left = `${Math.min(innerWidth - half - 8, Math.max(half + 8, s.left + s.width / 2))}px`;
     peek.style.bottom = `${innerHeight - shelf.getBoundingClientRect().top + 8}px`;
   }
-  // a surface's insides, scaled by k into its card (the big preview): each line of text a bar in its colour, coloured
+  // a card's insides, scaled by k into its tile (the big preview): each line of text a bar in its colour, coloured
   // areas (buttons, filled boxes) in theirs, pictures and canvases (a game) as small images. Apps' pages too (same
-  // server). No words. At most 400 pieces a surface.
-  function sketch(surface, card, k) {
-    const base = surface.getBoundingClientRect();
+  // server). No words. At most 400 pieces a card.
+  function sketch(card, tile, k) {
+    const base = card.getBoundingClientRect();
     const put = (tag, r, dx, dy, style) => {
       if (r.width * k < 0.5 || r.height * k < 0.5) return null;
-      const e = card.appendChild(document.createElement(tag));
+      const e = tile.appendChild(document.createElement(tag));
       Object.assign(e.style, { position: "absolute", left: `${(r.left + dx - base.left) * k}px`, top: `${(r.top + dy - base.top) * k}px`,
                                width: `${r.width * k}px`, height: `${r.height * k}px` }, style);
       return e;
     };
-    const roots = [[surface.querySelector(".surface-body") ?? surface, 0, 0]];
-    for (const f of surface.querySelectorAll("iframe")) {
+    const roots = [[card.querySelector(".card-body") ?? card, 0, 0]];
+    for (const f of card.querySelectorAll("iframe")) {
       try { const r = f.getBoundingClientRect(); if (f.contentDocument?.body) roots.push([f.contentDocument.body, r.left + f.clientLeft, r.top + f.clientTop]); } catch {}
     }
     let n = 0;
@@ -313,12 +311,12 @@ export default async function (page) {
     else { peek.hidden = true; fit(); }
   }
 
-  // drag a surface (by its label: ui/browser.js moves it) onto a thumbnail: it goes to that board, at the place it had
+  // drag a card (by its label: card/browser.js moves it) onto a thumbnail: it goes to that board, at the place it had
   document.addEventListener("pointerdown", (e) => {
-    const box = e.target.closest?.("[data-surface] > .surface-label")?.parentElement;
+    const box = e.target.closest?.("[data-card] > .card-label")?.parentElement;
     if (!box || e.target.closest("button")) return;
     const px = (v) => (v ? parseFloat(v) : undefined);
-    drag = { id: box.dataset.surface, board: Number(box.dataset.board) || 1,
+    drag = { id: box.dataset.card, board: Number(box.dataset.board) || 1,
              place: box.hasAttribute("data-placed") ? { x: box.offsetLeft, y: box.offsetTop, width: px(box.style.width), height: px(box.style.height) } : null };
   });
   document.addEventListener("pointermove", (e) => {
@@ -335,13 +333,13 @@ export default async function (page) {
   document.addEventListener("pointerup", () => {
     if (!drag) return;
     const to = over && Number(over.dataset.n);
-    if (to && to !== drag.board) page.send({ type: "ui_board", surface: drag.id, board: to, place: drag.place });
+    if (to && to !== drag.board) page.send({ type: "card_board", card: drag.id, board: to, place: drag.place });
     over?.classList.remove("drop");
     drag = over = null;
     if (!shelf.matches(":hover")) open(false);
   });
 
-  page.on("boards", (ev) => {
+  page.on("board", (ev) => {
     boards = ev.boards;
     if (ev.removed) {  // its things went with it (their own events); its container goes now
       containers[ev.removed]?.remove();
@@ -352,6 +350,6 @@ export default async function (page) {
     render();
   });
 
-  try { ({ boards, current } = await (await fetch("/boards")).json()); } catch {}
+  try { ({ boards, current } = await (await fetch("/board")).json()); } catch {}
   show(current, false);  // nothing to tell: the server said it (and the page's WebSocket may not be open yet)
 }

package/{app/extensions/boards → agent/extensions/board}/guide.md

@@ -1,4 +1,4 @@
 # Boards
 The user's work is on numbered boards; the page shows one at a time. A plain message doesn't say which board the
 user means: when it names one, use that; when it is about something already built, use that thing's board; else
-call boards() (it says which board the user is on) and, if it is still unclear, ask the user.
+leave board out (card_show puts a new card on the board the user is on). board_list() lists them all.