@chalky/chalky 0.1.5 → 0.1.7

package/agent/extensions/page/skills/interact-with-page/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: interact-with-page
+description: Use the page the user has open the way they would, while they watch - read what's on screen, click, type, press keys, drag - in any card, app or part of the page. Use to check what the user sees, show them something, fill something in for them, reproduce what they pointed at, or try something you built.
+---
+# Using the user's page
+
+The page_run tool (load it: tool_search "page_run") runs JavaScript in the page the user has open, as it is right
+now. With card=<id> it runs inside that card's app: `document` is the app's page. The code is the body of an async
+function: `await` works, and you `return` what you want back.
+
+## Act with the helpers
+They act as a person would: your pointer moves to the thing first, what you touch gets an outline with your name,
+and typing goes letter by letter, so the user can follow.
+- `await click(t)`
+- `await type(t, text)`: replaces what the field holds (`{add: true}` adds to it). A dropdown picks the option with
+  that text; a slider, date or colour field is set to that value.
+- `await press(key, t?)`: Enter, Escape, Tab, ArrowDown, "Ctrl+z"... to t, else to what has focus. Enter in a form
+  field submits the form.
+- `await drag(t, dx, dy)` by pixels, or `await drag(t, other)` onto another thing. A draggable thing (a file row)
+  is dragged and dropped as the browser does it, so drop targets get it.
+- `read(t?)`: what's on screen as short lines: headings, controls with their value and state ([selected],
+  [checked], [disabled]), short texts. Only what's in view; `read(null, {all: true})` for the whole page. The
+  conversation (the chat log) is left out: you know it; `read("#log")` if you need it.
+- `await wait(ms)`, `await wait(".row.new")` (until it appears), `await wait(() => condition)`.
+
+t is an element, a CSS selector, or the visible text: a button's words, a field's placeholder or label. Or a spot
+`{x: 600, y: 300}` in window px (screen_see's picture, or an element's getBoundingClientRect()): whatever is on top
+there gets it, as with a real mouse. Use a spot for empty space (`await drag({x: 400, y: 300}, 300, 200)` draws a
+frame there) and for tools that work through a layer over the page (Point: click the tool, then the spot).
+```
+page_run(card="habit-tracker", code=`await type("New habit", "Drink water");
+  await click("Add habit");
+  return read()`)
+```
+Plain DOM code is fine for reading and checking precisely: `getComputedStyle(el)`, `el.scrollWidth > el.clientWidth`
+(text cut off), state the app exposes. For acting, use the helpers: a bare `el.click()` happens at once, and the user
+only sees an outline afterwards.
+
+## Look after each step, cheaply
+One step, or a few, per page_run, ending with a small read: `return read()` or the one value you need. You see what
+happened before you decide the next step. A read is about a hundred tokens; a picture (screen_see) is over a thousand
+and stays in your conversation, so look at a picture when the look matters (layout, colours, clipped or overlapping
+things), not after every step. From bash the same is `curl -X POST --data '{"code": "...", "card": "<id>"}' {page}/page/run`,
+for a loop or a script.
+
+## The user is watching, and can take over
+While you use the page a bar says so, with a Stop button. If the user clicks or types on the page, page_run answers
+"the user took over": stop there, don't retry, and say in a sentence what you were doing. When they press
+"Let <you> continue" you get a message: read the page again first, it may have changed.
+
+## Care
+- It's the live page: clicks really happen and data really changes. Touch only what your task needs, and don't send
+  messages through the chat box.
+- The page's Stop button and rollbacks refuse code: they are the user's.
+- Events from code are not quite real input: hover styles, native dropdown lists, file pickers, and copy and paste
+  don't respond. For those, and for other window sizes, use the browser-check skill
+  (a separate headless browser).
+- Errors the page logs while your code runs come back with the answer: read them.
+- An answer marked "not on the board the user is looking at" ran on a card they can't see right now.

package/agent/extensions/screen/browser.js

@@ -6,18 +6,10 @@
 //   frame()            the screen right now, as a canvas (null when not shared)
 //   picture(full, box) crop a frame to box (window px {x, y, w, h}), upload it (POST /screen/shot): {path, url}
 // An agent can ask to see the screen (its tool screen_see, event screen_ask): if the tab is shared, a picture
-// of the whole window goes back at once; else a card asks "Share / No" first, since the agent's ask is no click
+// of the whole window goes back at once; else a notice asks "Share" (✕: no) first, since the agent's ask is no click
 // (screen_reply {id, shot, window, main}).
 export default async function (page) {
   const area = page.slot("top");
-  const style = document.createElement("style");
-  style.textContent = `
-    .screen-ask { position: fixed; top: 76px; left: 50%; transform: translateX(-50%); z-index: 100; display: flex; align-items: center; gap: 10px;
-                  padding: 8px 8px 8px 14px; border-radius: 14px; background: var(--glass-strong, #fff); border: 1px solid var(--edge, #eee);
-                  box-shadow: 0 8px 30px rgba(0, 0, 0, .12); font-size: 13px; color: var(--text); }
-    .screen-ask button { border: 0; border-radius: 9px; padding: 5px 12px; font: inherit; cursor: pointer; background: var(--line, #eee); color: var(--text); }
-    .screen-ask button.yes { background: var(--accent, #0071e3); color: #fff; }`;
-  document.head.append(style);
 
   let stream = null, video = null;
   async function share() {
@@ -53,24 +45,19 @@ export default async function (page) {
   // ---- an agent asks to see the screen ----
   const asks = {};  // id -> its card, while the agent waits
   async function answer(id) {
-    for (const card of Object.values(asks)) card.remove();  // not in the picture
-    await new Promise((ok) => setTimeout(ok, 300));         // a fresh frame from the shared tab
+    for (const card of Object.values(asks)) card.close();   // not in the picture
+    await new Promise((ok) => setTimeout(ok, 400));         // it has slid away; a fresh frame from the shared tab
     const full = frame();
     const s = full && await picture(full, { x: 0, y: 0, w: innerWidth, h: innerHeight }).catch(() => null);
-    const m = area.getBoundingClientRect();  // window (0, 0) in main-space px (as note/browser.js)
+    const m = area.getBoundingClientRect(), zoom = parseFloat(area.style.zoom) || 1;  // window (0, 0) in main-space px (as note/browser.js)
     page.send({ type: "screen_reply", id, shot: s?.path || null, window: { width: innerWidth, height: innerHeight },
-                main: { x: area.scrollLeft - m.left, y: area.scrollTop - m.top } });
+                main: { x: area.scrollLeft - m.left / zoom, y: area.scrollTop - m.top / zoom }, zoom });
   }
   page.on("screen_ask", ({ id, agent }) => {
     if (shared()) return answer(id);
-    const card = Object.assign(document.createElement("div"), { className: "screen-ask" });
-    const yes = Object.assign(document.createElement("button"), { className: "yes", textContent: "Share" });
-    const no = Object.assign(document.createElement("button"), { textContent: "No" });
-    card.append(`${agent} wants to see your screen`, yes, no);
+    const yes = Object.assign(document.createElement("button"), { className: "go", textContent: "Share" });
     yes.onclick = async () => { await share(); answer(id); };
-    no.onclick = () => page.send({ type: "screen_reply", id, shot: null });
-    asks[id] = card;
-    document.body.append(card);
+    asks[id] = page.notice([`${agent} wants to see your screen`, yes], () => page.send({ type: "screen_reply", id, shot: null }));  // ✕: no
   });
-  page.on("screen_ask_done", ({ id }) => { asks[id]?.remove(); delete asks[id]; });  // answered (here or in another tab), or timed out
+  page.on("screen_ask_done", ({ id }) => { asks[id]?.close(); delete asks[id]; });  // answered (here or in another tab), or timed out
 }

package/agent/extensions/screen/index.ts

@@ -4,8 +4,9 @@
 // (their size, scroll, panels, running apps; browser-check's headless Chrome is a fresh window of its own).
 //   POST /screen/shot       a png (at most MAX_BYTES): saved in data/screen, {path} back
 //   event "screen_ask"      {id, agent} to every open page, when an agent calls screen_see
-//   page message            screen_reply {id, shot, window: {width, height}, main: {x, y}}: the first answers
-//                           (shot null: the user said no; main: window (0, 0) in main-space px)
+//   page message            screen_reply {id, shot, window: {width, height}, main: {x, y}, zoom}: the first answers
+//                           (shot null: the user said no; main: window (0, 0) in main-space px; zoom: the board's,
+//                           window px per main-space px)
 //   event "screen_ask_done" {id} to every page when answered or after ASK_WAIT s, so the asks go away
 //   host.api.screen         isShot(path): whether a path is a picture saved here (others attach pictures by path)
 import fs from "node:fs";
@@ -70,11 +71,12 @@ export default function (pi: ExtensionAPI) {
       if (!reply) return result(`no answer within ${ASK_WAIT} s (the page may not be open, or the user is away): ask them what they see`);
       if (!isShot(reply.shot)) return result("the user didn't share their screen: ask them what they see");
       const png = fs.readFileSync(reply.shot), pw = png.readUInt32BE(16), ph = png.readUInt32BE(20);  // the png's own size (IHDR)
-      const w = reply.window ?? {}, m = reply.main ?? {}, k = w.width ? pw / w.width : 1;
+      const w = reply.window ?? {}, m = reply.main ?? {}, z = Number(reply.zoom) || 1, k = (w.width ? pw / w.width : 1) * z;  // picture px per main px
       const mx = Math.round(m.x ?? 0), my = Math.round(m.y ?? 0);
       return result(`the user's screen right now: their window is ${w.width}x${w.height} px; the picture is the whole window, `
-        + `${pw}x${ph} px (${+k.toFixed(3)} picture px per window px). Window (0, 0) is main-space (${mx}, ${my}): a spot in `
-        + `the picture is main-space x = ${mx} + picture x / ${+k.toFixed(3)}, the same for y (what card_show's place uses).`, reply.shot);
+        + `${pw}x${ph} px${z !== 1 ? `, with the board zoomed to ${Math.round(z * 100)}%` : ""} (${+k.toFixed(3)} picture px per main-space px). `
+        + `Window (0, 0) is main-space (${mx}, ${my}): a spot in the picture is main-space x = ${mx} + picture x / ${+k.toFixed(3)}, `
+        + `the same for y (what card_show's place uses).`, reply.shot);
     },
   });
 }

package/agent/extensions/version/browser.js

@@ -3,6 +3,7 @@
 // with dom-to-image-more, then each same-site app frame's own page pasted in place (the library leaves frames
 // blank), crops to the cards plus a margin, and uploads it: PUT /version/<sha>/shot (the first page wins).
 // Can't be drawn: video, and pictures or frames from other sites (those parts stay blank).
+// Also: when Chalky was updated at this start (GET /version/update), a notice says what changed or why it couldn't.
 const MARGIN = 32;
 let lib;
 const library = () => lib ??= new Promise((ok, no) => {  // loaded once, on the first picture
@@ -14,15 +15,15 @@ const image = (src) => new Promise((ok, no) => Object.assign(new Image(), { onlo
 async function picture() {  // a PNG blob of the cards, or null if there are none
   const top = document.getElementById("top"), cards = [...top.querySelectorAll("[data-card]")];
   if (!cards.length) return null;
-  const domtoimage = await library(), at = top.getBoundingClientRect();
-  const box = (el) => { const r = el.getBoundingClientRect(); return { x: r.left - at.left + top.scrollLeft, y: r.top - at.top + top.scrollTop, w: r.width, h: r.height }; };
+  const domtoimage = await library(), at = top.getBoundingClientRect(), z = parseFloat(top.style.zoom) || 1;  // the board's zoom: drawn at 100%
+  const box = (el) => { const r = el.getBoundingClientRect(); return { x: (r.left - at.left) / z + top.scrollLeft, y: (r.top - at.top) / z + top.scrollTop, w: r.width / z, h: r.height / z }; };
   const all = cards.map(box);
   const x0 = Math.max(0, Math.min(...all.map((b) => b.x)) - MARGIN), y0 = Math.max(0, Math.min(...all.map((b) => b.y)) - MARGIN);
   const x1 = Math.max(...all.map((b) => b.x + b.w)) + MARGIN, y1 = Math.max(...all.map((b) => b.y + b.h)) + MARGIN;
   const width = Math.ceil(x1), height = Math.ceil(y1);  // the whole main space up to the last card; cropped below
   const bgcolor = getComputedStyle(document.body).backgroundColor;
   const page = await image(await domtoimage.toPng(top, { width, height, bgcolor,
-    style: { position: "static", inset: "auto", overflow: "visible", width: `${width}px`, height: `${height}px` } }));
+    style: { position: "static", inset: "auto", overflow: "visible", width: `${width}px`, height: `${height}px`, zoom: "1" } }));
   const canvas = Object.assign(document.createElement("canvas"), { width: Math.ceil(x1 - x0), height: Math.ceil(y1 - y0) });
   const g = canvas.getContext("2d");
   g.drawImage(page, -x0, -y0);
@@ -51,6 +52,14 @@ function shoot(sha) {  // one picture at a time
 export default async function (page) {
   if (new URLSearchParams(location.search).has("shot")) return;  // the old headless view
   page.on("version", (ev) => setTimeout(() => shoot(ev.sha), 2000));  // after the page has redrawn what changed
+  fetch("/version/update").then((r) => r.json()).then((u) => {
+    if (!u) return;
+    const kept = u.conflicts?.length;
+    page.notice(u.error ? [`Chalky couldn't update to ${u.release}, so it runs as before. ${u.error}`]
+      : [`Updated to ${u.release}: ${u.files} file${u.files === 1 ? "" : "s"} changed.`
+        + (kept ? ` ${kept} kept your change; agent1 is merging the update into ${kept === 1 ? "it" : "them"}.` : "")
+        + " To undo it, go back a version in Versions."]);
+  }).catch(() => {});
   try {  // the current version has no picture yet (made while no page was open): take it now
     const current = (await (await fetch("/version")).json()).find((v) => v.current);
     if (current && !current.shot) setTimeout(() => shoot(current.short), 3000);  // once the cards are drawn

package/agent/extensions/version/index.ts

@@ -1,14 +1,21 @@
 // Version history of agent/ and built/ together: what the agents are and what they made, so one rollback puts both
 // back. The repo and the rule for what it keeps (not logins, endpoints or installed packages) are the host's
 // (host.history, server.ts: /recover uses them too); this extension commits, lists and rolls back, one operation at
-// a time. Its first commit is both folders as they were the first time, tagged "original".
-//   - When an agent's turn is over (pi's agent_settled) and either folder changed: commit, author = that agent, message =
-//     its reload reason, else what it was asked (Python: what it first said, often just "done"), else what it said.
+// a time. Its first commit is both folders as they were the first time, tagged "original" (in an installed home,
+// server.ts makes the first one: "Started with Chalky <version>"; it also merges each new release, as a version).
+//   - When an agent's turn is over (pi's agent_settled) and either folder changed: commit, author = that agent. The
+//     message's first line (the label) says what changed, made here from facts, not from what was said: the card
+//     extension's words for the agent's card changes ("showed trip"), then the other changed things named from
+//     their paths (NAMES: "new app planner", "changed extension card"), at most 3, then its reload reason, if any.
+//     The second line: the first line of what it was asked (detail, not shown in the list).
 //     Event "version" to the pages ({agent, sha, message, files, restart: false}: they refresh what changed).
 //   - Pictures for the panel: taken by the open page itself (browser.js here, with dom-to-image-more; no
 //     headless browser), after each new version and, when a page opens, for the current version if it has none.
 //     In data/version/shots/<sha>.png. A version made while no page was open and changed again before one opened: none.
-//   - GET  /version                  commits, newest first ({sha, short, author, date, message, current, shot})
+//   - GET  /version                  the user's versions, newest first ({sha, short, author, date, message, current, shot}):
+//                                    host.history.versions(), so not the releases an update merged in
+//     GET  /version/update          this start's update of Chalky (server.ts's host.update), to the first page that
+//                                    asks (browser.js: a notice); later: null. {release, files, conflicts} or {release, error}
 //     GET  /version/<sha>/shot      that commit's picture (404 if none; HEAD too)
 //     PUT  /version/<sha>/shot      the page's picture (PNG, at most 10 MB; {saved: false} if it has one: the first page wins)
 //     POST /version/<sha>/rollback  that commit's files as a NEW commit (history is never rewritten, so a rollback
@@ -23,12 +30,13 @@ import git from "isomorphic-git";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const host = (globalThis as any).chalky;
-const { repo, kept, stage } = host.history;
+const { repo, stage, restore, versions } = host.history;
 const SHOTS = path.join(host.data, "version", "shots");
 const MAX_SHOT = 10 * 1024 * 1024;
 const who = (name: string) => ({ name, email: `${name}@chalky` });
 
-const shared = host.shared.get("version") ?? { queue: Promise.resolve(), turnFrom: {} as Record<string, number> };
+const shared = host.shared.get("version") ?? { queue: Promise.resolve(), turnFrom: {} as Record<string, number>, cards: {} as Record<string, string[]> };
+shared.cards ??= {};  // (shared state made by an older copy of this file, before a reload)
 host.shared.set("version", shared);
 function queued<T>(fn: () => Promise<T>): Promise<T> {  // history operations one at a time (agents can finish together)
   const run = shared.queue.then(fn);
@@ -49,33 +57,71 @@ if (!shared.creating) shared.creating = queued(async () => {
 
 const head = async () => { await shared.queue; return git.resolveRef({ ...repo, ref: "HEAD" }); };  // after queued work (e.g. the first commit)
 
-async function commit(author: string, message: string) {  // the changed files, or [] if nothing changed
+async function commit(author: string, words: string | ((changed: string[]) => Promise<string>)) {  // the changed files, or [] if nothing changed
   const changed = await stage();
   if (!changed.length) return [];
+  const message = typeof words === "string" ? words : await words(changed);
   let sha: string;
   try { sha = await git.commit({ ...repo, message, author: who(author), disallowEmpty: true }); }
   catch (e: any) { if (e.code === "EmptyCommitError") return []; throw e; }  // nothing really changed
-  host.broadcast("version", { agent: author, sha: sha.slice(0, 7), message, files: changed, restart: false });  // pages take its picture
+  host.broadcast("version", { agent: author, sha: sha.slice(0, 7), message: message.split("\n")[0], files: changed, restart: false });  // pages take its picture
   return changed;
 }
 
+// A version's label: what changed, in words. The things a path is part of (anything else: the path itself):
+const NAMES: [RegExp, string][] = [
+  [/^agent\/extensions\/([^/]+)\//, "extension $1"],
+  [/^agent\/skills\/([^/]+)\//, "skill $1"],
+  [/^agent\/SYSTEM\.md$/, "instructions"],
+  [/^agent\/settings\.json$/, "settings"],
+  [/^built\/apps\/([^/]+)\//, "app $1"],
+  [/^built\/card\.json$/, "cards"],  // left out when the card extension's words say what changed
+  [/^built\/board\.json$/, "boards"],
+  [/^built\//, ""],                  // another file: its path in built/
+];
+function nameOf(p: string) {  // "agent/extensions/card/browser.js" -> "extension card"; "built/notes/a.txt" -> "notes/a.txt"
+  for (const [re, name] of NAMES) {
+    const m = p.match(re);
+    if (m) return name ? m[0].replace(re, name) : p.slice(m[0].length);
+  }
+  return p;
+}
+function describe(files: { path: string, how: "new" | "changed" | "removed" }[], cards: string[], reason?: string) {
+  const hows = new Map<string, Set<string>>();  // thing -> how its files changed
+  for (const f of files) { const t = nameOf(f.path); if (t !== "cards" || !cards.length) hows.set(t, (hows.get(t) ?? new Set()).add(f.how)); }
+  const parts = [...new Set(cards), ...[...hows].map(([t, h]) => `${h.size === 1 ? [...h][0] : "changed"} ${t}`)];
+  const label = parts.length > 3 ? `${parts.slice(0, 3).join("; ")} and ${parts.length - 3} more` : parts.join("; ");
+  return reason ? `${label}: ${reason.split("\n")[0]}` : label;
+}
+
 const textOf = (m: any) => typeof m.content === "string" ? m.content
   : (m.content ?? []).filter((c: any) => c.type === "text").map((c: any) => c.text).join("\n");
 
 export default function (pi: ExtensionAPI) {
-  pi.on("agent_start", (_e, ctx) => { shared.turnFrom[pi.getSessionName()!] = ctx.sessionManager.getEntries().length; });
+  // the card extension's words for each card change, kept per agent while its turn runs (the user's: not an agent's)
+  pi.on("session_start", () => host.api.card?.watch("version", (_id: string, by?: string, what?: string) => {
+    if (what && by) shared.cards[by]?.push(what);
+  }));
+  pi.on("agent_start", (_e, ctx) => {
+    const agent = pi.getSessionName()!;
+    shared.turnFrom[agent] = ctx.sessionManager.getEntries().length;
+    shared.cards[agent] = [];
+  });
   pi.on("agent_settled", (_e, ctx) => {
     const agent = pi.getSessionName()!;
     const turn = ctx.sessionManager.getEntries().slice(shared.turnFrom[agent] ?? 0).filter((e: any) => e.type === "message").map((e: any) => e.message);
     const reason = host.shared.get(`reload-reason ${agent}`);
     host.shared.delete(`reload-reason ${agent}`);
-    let message = "";
-    for (const text of [reason ?? "", ...turn.filter((m: any) => m.role === "user").map(textOf), ...turn.filter((m: any) => m.role === "assistant").map(textOf)]) {
-      const line = text.split("\n").map((l: string) => l.trim()).find((l: string) => l && !/^\[\w+ (from|to) /.test(l));
-      if (line) { message = line; break; }
-    }
+    const cards = shared.cards[agent] ?? [];
+    delete shared.cards[agent];
+    const asked = turn.filter((m: any) => m.role === "user").map(textOf)
+      .flatMap((t: string) => t.split("\n").map((l) => l.trim())).find((l: string) => l && !/^\[\w+ (from|to) /.test(l)) ?? "";
     return queued(async () => {
-      const changed = await commit(agent, message.slice(0, 100) || `changes by ${agent}`);
+      const changed = await commit(agent, async (files) => {
+        const before = new Set(await git.listFiles({ ...repo, ref: "HEAD" }));
+        const label = describe(files.map((p) => ({ path: p, how: !fs.existsSync(path.join(host.home, p)) ? "removed" : before.has(p) ? "changed" : "new" })), cards, reason);
+        return [label || `changes by ${agent}`, asked.slice(0, 200)].filter(Boolean).join("\n\n");
+      });
       // files in agent/ that aren't part of an agent, there now (a deleted one is the agent moving it: no new warning)
       const stray = changed.filter((p) => p.startsWith("agent/") && !host.isAgentPart(p.slice("agent/".length)) && fs.existsSync(path.join(host.home, p)));
       if (stray.length && host.agents.has(agent))
@@ -85,9 +131,14 @@ export default function (pi: ExtensionAPI) {
     });
   });
 
+  host.routes.set("/version/update", (_req: any, res: any) => {
+    const u = host.update && !host.update.told ? host.update : null;
+    if (u) u.told = true;
+    res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(u));
+  });
   host.routes.set("/version", async (_req: any, res: any) => {
     const now = await head();  // waits for queued work, so the log is complete
-    const out = (await git.log(repo)).map(({ oid, commit: c }) => ({ sha: oid, short: oid.slice(0, 7), author: c.author.name,
+    const out = (await versions()).map(({ oid, commit: c }) => ({ sha: oid, short: oid.slice(0, 7), author: c.author.name,
       date: new Date(c.author.timestamp * 1000).toISOString(), message: c.message.split("\n")[0], current: oid === now,
       shot: fs.existsSync(path.join(SHOTS, `${oid}.png`)) }));  // the page takes the current one's picture if it has none
     res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(out));
@@ -123,11 +174,10 @@ export default function (pi: ExtensionAPI) {
     if (what !== "rollback" || req.method !== "POST") return res.writeHead(404).end();
     const subject = `${sha.slice(0, 7)} ${(await git.readCommit({ ...repo, oid: sha })).commit.message.split("\n")[0]}`;
     await host.api.team?.stop();
-    const files = await queued(async () => {
+    let files: string[];
+    try { files = await queued(async () => {
       await commit("user", "uncommitted changes before rollback");  // nothing is ever lost
-      // that commit's agent/ and built/ into the folders and the index, removing files it doesn't have; the branch
-      // stays where it is. What the history doesn't keep (logins, endpoints) isn't touched.
-      await git.checkout({ ...repo, ref: sha, noUpdateHead: true, force: true, filepaths: kept.filepaths });
+      await restore(sha);  // that commit's agent/ and built/ (server.ts)
       const files = await stage();
       // git keeps files, not folders: a folder whose files the rollback removed stays, empty (an extension folder
       // without index.ts would show in the map). Remove those, up to the first one that isn't empty.
@@ -136,7 +186,9 @@ export default function (pi: ExtensionAPI) {
       }
       await git.commit({ ...repo, message: `rollback to ${subject}`, author: who("user") });
       return files;
-    });
+    }); } catch (e: any) {  // an answer, not a request left hanging
+      return res.writeHead(500, { "content-type": "application/json" }).end(JSON.stringify({ error: String(e?.message ?? e) }));
+    }
     for (const name of host.agents.keys()) await host.reloadAgent(name);
     if (files.includes("built/card.json")) { host.shared.get("card")?.load(); host.api.history?.add("user", `rolled back to ${subject}`); }
     for (const name of host.agents.keys())

package/agent/skills/design/SKILL.md

@@ -120,4 +120,4 @@ in it share a palette, a way of shading and a level of detail.
 
 ## 11. Check it
 Load browser-check and look at a screenshot: overlaps, clipped text, labels colliding, things outside their box.
-Fix what you see once, then stop polishing; the user will point at what they want changed.
+Fix everything you see before you show it: the user marks up details, not missing basics.

package/agent/skills/show-me/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: show-me
+description: Answer "how do I…", "what does this do", "what can I do here" questions about Chalky itself by showing, not telling - explain each thing in a note pinned on it, use the page's own tools in front of the user with your pointer (a spare board, a test file), then hand over. Use when the user asks how to use Chalky, a tool, a button or a panel, or asks to be shown or walked through something on the page.
+---
+# Showing the user how Chalky works
+
+The user learns a tool by seeing it used on their own screen. So answer a how-question by doing it on the page,
+slowly, while they watch: say what the thing is, right on it, use it as they would, show what came out, then let
+them try. A text card or a long reply describing the tools is the thing to avoid: it is what they asked you not to
+do. Don't build a tour app either: they asked about the page they have, not about what you could build.
+
+## How to show
+- **Show what they asked about.** "How do frames work?" is one demo, shown fully. "What can I do?" is a short tour:
+  two or three tools, then offer the rest. "Show me all the tools" is all of them: keep each one short, one step
+  per tool (below). Ask nothing first: start, they can stop you.
+- **One step per tool, in a tour.** Send a tool's calls together, in one step: delete the last tool's note, pin a
+  note on this tool's button, and one page_run that uses it once. For example, for Frames:
+  `note_done("n4", delete: true)`, `note_add(on: {element: "frames"}, text: "Frames: drag a box where something
+  should go and write what goes in it; Implement sends them to an agent. I'm drawing one now.")`, and `page_run`
+  that clicks the tool, drags a box at an empty spot and types in it. A tool that is better explained than used
+  (Dictate needs their microphone; Roll back is theirs to press) gets only the note.
+- **Explain on the thing, in a note.** Before using a tool, pin a note on it (note_add) with a sentence or two: what
+  it is for and what you are about to do. The user reads it right where your pointer goes; your text between tool
+  calls never reaches the page. When you move on to the next thing, delete it (note_done(id, delete: true)) so only
+  one explanation is on the page at a time. For a quick pointer without words to read ("this one"), circle it in ink
+  instead (doodle_mark), and clear the mark (doodle_clear) when you move on.
+- **Act with your pointer.** Use page_run's helpers (interact-with-page skill): click, type, drag, press. They move
+  your pointer, so the user can follow. One or two actions per page_run, ending with a small read, so you see what
+  happened before the next step. Check results with read() or a line of DOM code; look at the screen (screen_see)
+  only when the look itself matters.
+- **Use spots for empty space.** Tools that work on the page itself (frames, the pen, text, the eraser, Point) need a
+  place, not a button: give a spot {x, y} in window px. `await drag({x: 700, y: 300}, 300, 180)` draws a frame or a
+  pen stroke there, `await click({x, y})` points or places, `await type({x, y}, "words")` clicks there and types
+  (into the box the click opened, or as the Text tool's words). Choose spots on the empty part of the board: first
+  close a panel that covers it (messages, versions: click its rail button), then check the spot, e.g.
+  `document.elementFromPoint(x, y).closest('#top') && !document.elementFromPoint(x, y).closest('[data-card]')`.
+- **Never on their work.** Demo on a spare board (click "+" on the boards shelf) or with a test file you make.
+  Don't change, move or delete their cards, files or notes to show something.
+- **Hand over, then tidy.** End with their turn: say in a sentence what to do next ("drag a box on the empty space
+  and type in it"), with the tool left on for them. Delete your explaining notes and clear your marks. Leave no
+  other tool on. Then ask whether to keep what the demo made (the board, the test file, a frame) or remove it, and
+  do what they say.
+- **Point at what you must not press.** Rollback, Stop and deleting their things are theirs: put a note on the
+  button saying what it does. (The page refuses a rollback from your code anyway.)
+- **If they take over** (page_run says so), stop: they are trying it. When they hand back, read the page again
+  before going on; they may have done the next step themselves.
+- **Keep the reply short.** The page showed it. Your final reply says in two or three sentences what they saw and
+  what they can try.
+
+## The page, for showing
+Names are the data-name to use in note_add / doodle_mark (on: {element: "..."}) and page_run (`[data-name=...]`).
+The toolbar's order changes: find things by name, never by position.
+
+| What | Name | What it does, and how to show it |
+|---|---|---|
+| Point / notes | note | Click anything (or draw around an area) and write: a note pinned to that thing, a thread with an agent. Show: click the tool, click a spot on a thing, type, Enter. |
+| Doodle pen | pen | Draw and write on the page, click through it; Enter in the message line sends the drawing as steps (don't send it). Show: click the tool, drag at a spot. |
+| Text | text | Words placed on the page, sent with the doodle. Show: click the tool, type at a spot. |
+| Eraser | eraser | Takes away lines, words or unsent frames. Show: click the tool, drag over what you drew. |
+| Hide marks | show-marks | Hides or shows all marks. |
+| Frames | frames | Boxes the user lays out for agents to fill. Show: click the tool, drag a box at a spot, type in its box, then Implement (implement) sends them to an agent. |
+| Files | files | Opens the files panel: everything in the drops folder. A row dragged onto the page opens a note there; a click opens a preview (spreadsheets, PDF, Word, slides, pictures). An empty folder shows an empty panel: write a test file into it first. |
+| Microphone | dictate | Speech to text in the message line. |
+| Messages / Versions | messages, versions | The left rail: the conversation; and the history of the page, with a picture of each version and Roll back. |
+| Boards shelf | boards, new-board | Numbered boards; "+" makes a new one and goes to it. |
+| Message line | message-line | Where the user types to the agents. Don't send messages through it. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalky/chalky",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Chalky on pi: agents build what you see in the browser, and you point at it and mark it up",
   "license": "MIT",
   "type": "module",
@@ -29,6 +29,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "1.4.0",
+    "diff3": "0.0.3",
     "dom-to-image-more": "3.11.0",
     "dompurify": "3.4.17",
     "isomorphic-git": "1.44.2",