@chalky/chalky 0.1.4 → 0.1.6

package/{app → agent}/extensions/viewer/browser.js

@@ -1,10 +1,10 @@
-// Browser half of the viewer plugin: a preview window per file, opened by the files plugin's "file-open" DOM
+// The page side of the viewer extension: a preview window per file, opened by the file extension's "file-open" DOM
 // event {file: {name, path, size}} (a click on a row of the file panel, or files dropped on the page).
 // A window starts attached to its row: left of the panel, at the row's height, a notch pointing at it, the row
 // lit. Only one window is attached at a time (opening another file replaces it); dragging its label (shown
-// on hover, like a surface's: name, ✕) or resizing it from the corner detaches it, and then it stays where
+// on hover, like a card's: name, ✕) or resizing it from the corner detaches it, and then it stays where
 // it was put. ✕ closes it. Windows live only in this page (not saved, not seen by the agent).
-// Pointing at a window with the pen: point.js asks its partAt(x, y), which answers which file and where:
+// Pointing at a window with the pen: note/browser.js asks its partAt(x, y), which answers which file and where:
 // {viewing, sheet, cell} | {viewing, slide} | {viewing, paragraph} | {viewing, line} | {viewing}.
 // Drawing around something: partIn(points) answers what is inside the drawn shape (a thing whose middle is
 // inside it; if none, the thing under the drawing's middle), with its content, at most MAX_PICK characters:
@@ -83,19 +83,19 @@ export default async function (page) {
   const layer = el("div", { class: "viewers" });
   document.body.append(layer);
 
-  const rowOf = (path) => document.querySelector(`#side .files-row[data-path="${CSS.escape(path)}"]`);
+  const rowOf = (path) => document.querySelector(`#side .file-row[data-path="${CSS.escape(path)}"]`);
 
   function place(w) {  // attached: left of the panel, at the row's height (the folder button if the panel is closed)
     if (!w.attached) return;
     const row = rowOf(w.file.path);
     const visible = row && row.offsetParent;
-    const anchor = visible ? row : document.querySelector("#side .files-toggle");
+    const anchor = visible ? row : document.querySelector("#side .file-toggle");
     if (!anchor) return;
     const a = anchor.getBoundingClientRect(), panel = (visible ? row.parentElement : anchor).getBoundingClientRect();
     const h = w.box.offsetHeight, y = Math.max(72, Math.min(a.top - 14, innerHeight - h - 16));  // 72: below the palette
     Object.assign(w.box.style, { right: `${innerWidth - panel.left + 14}px`, left: "", top: `${y}px` });
     w.box.style.setProperty("--notch", `${Math.max(10, Math.min(a.top + a.height / 2 - y - 6, h - 22))}px`);
-    for (const r of document.querySelectorAll("#side .files-row.viewing")) r.classList.remove("viewing");
+    for (const r of document.querySelectorAll("#side .file-row.viewing")) r.classList.remove("viewing");
     if (visible) row.classList.add("viewing");
   }
   const placeAll = () => Object.values(windows).forEach(place);
@@ -103,7 +103,7 @@ export default async function (page) {
   document.addEventListener("scroll", placeAll, true);  // the panel's list scrolls
   const side = document.getElementById("side");
   if (side) new MutationObserver(() => {  // the list redrawn or the panel opened or closed
-    for (const w of Object.values(windows)) if (!rowOf(w.file.path) && w.attached && side.querySelector(".files-row")) close(w);  // file gone
+    for (const w of Object.values(windows)) if (!rowOf(w.file.path) && w.attached) close(w);  // file gone (deleted too)
     placeAll();
   }).observe(side, { childList: true, subtree: true, attributes: true, attributeFilter: ["data-open", "hidden"] });
 
@@ -148,7 +148,7 @@ export default async function (page) {
       left: `${Math.max(0, Math.min(r.left + dx, innerWidth - 60))}px`, top: `${Math.max(24, Math.min(r.top + dy, innerHeight - 40))}px` }));
     corner.onpointerdown = (e) => dragging(w, e, (r, dx, dy) => Object.assign(box.style, {
       width: `${Math.max(240, r.width + dx)}px`, height: `${Math.max(160, r.height + dy)}px` }));
-    box.partAt = (x, y) => {  // for point.js: which file, and where in it
+    box.partAt = (x, y) => {  // for note/browser.js: which file, and where in it
       const r = box.getBoundingClientRect();
       const hit = document.elementsFromPoint(r.left + x, r.top + y).find((e) => box.contains(e));
       const spot = hit?.closest("[data-part]");

package/agent/extensions/viewer/guide.md

@@ -0,0 +1,3 @@
+# Previews of the user's files
+A note whose part has "viewing": <a file> is about that spot in that file, not the page: read README.md before you
+handle one.

package/{app → agent}/extensions/viewer/index.ts

@@ -1,5 +1,5 @@
-// Viewer: previews of the user's files (the ones in the files plugin's folder), in a window on the page (port of the
-// Python viewer plugin; the browser half, browser.js, is its viewer.js). browser.js opens a window when files' browser.js fires
+// Viewer: previews of the user's files (the ones in the file extension's folder), in a window on the page (the
+// browser half: browser.js). browser.js opens a window when files' browser.js fires
 // "file-open"; the window lives only in that page (a note pointed at it says which file and which spot).
 // Parsing happens here, one library per format (plain previews, no LibreOffice):
 //   images, pdf                     shown by the browser itself, from /viewer/raw
@@ -12,11 +12,12 @@
 //   GET  /viewer/view?path=   {"kind": "image"|"pdf"|"text"|"sheets"|"doc"|"slides"|"none", ...} (see preview())
 //   GET  /viewer/raw?path=    the file's bytes, images and pdf only
 //   POST /viewer/shot         a png of an area the user drew around on a pdf; saved in SHOTS, returns {"path"}
-// Tool read_document(path): the same content as text, for the agent (pdf text with unpdf). The Python tool was
+// Tool viewer_read(path, offset?): the same content as text, for the agent (pdf text with unpdf). The Python tool was
 // read_file; renamed so it isn't mistaken for pi's read (text and pictures, which the guide now names for pictures).
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
-import * as XLSX from "xlsx";
+import type { WorkSheet } from "xlsx";  // types only: erased when this runs
 import mammoth from "mammoth";
 import PptxParser from "node-pptx-parser";
 import WordExtractor from "word-extractor";
@@ -25,13 +26,16 @@ import { Type } from "typebox";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const host = (globalThis as any).chalky;
-const DIR = path.join(host.work, "drops");  // the files plugin's folder
+// xlsx is a bundled dependency: npm keeps it inside our package's node_modules and never moves it up next to the
+// others, so a plain import from this home copy doesn't find it. Look for it from the package's own folder instead.
+const XLSX: typeof import("xlsx") = createRequire(path.join(host.root, "package.json"))("xlsx");
+const DIR = path.join(host.workspace, "drops");  // the file extension's folder
 const IMAGES: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
   ".webp": "image/webp", ".bmp": "image/bmp", ".svg": "image/svg+xml", ".avif": "image/avif", ".ico": "image/x-icon" };
 const MAX_ROWS = 1000, MAX_COLS = 60;  // per sheet shown
 const MAX_TEXT = 300_000;              // characters shown
-const MAX_TOOL_TEXT = 40_000;          // characters read_document returns
-const SHOTS = path.join(host.state, "pointed");  // pictures of drawn-around pdf areas (outside the user's folder)
+const MAX_TOOL_TEXT = 40_000;          // characters viewer_read returns
+const SHOTS = path.join(host.data, "viewer");  // pictures of drawn-around pdf areas (outside the user's folder)
 const MAX_SHOT = 10 * 1024 * 1024;
 
 function inside(p: string | null) {  // the real path, if it is a file in DIR; else null (no reading elsewhere)
@@ -41,7 +45,7 @@ function inside(p: string | null) {  // the real path, if it is a file in DIR; e
   } catch { return null; }
 }
 
-function sheet(name: string, ws: XLSX.WorkSheet) {  // {name, rows, cut}: from A1, at most MAX_ROWS x MAX_COLS
+function sheet(name: string, ws: WorkSheet) {  // {name, rows, cut}: from A1, at most MAX_ROWS x MAX_COLS
   if (!ws["!ref"]) return { name, rows: [], cut: false };
   const r = XLSX.utils.decode_range(ws["!ref"]);
   const cut = r.e.r >= MAX_ROWS || r.e.c >= MAX_COLS;
@@ -132,7 +136,7 @@ async function preview(p: string) {
   return { kind: "text", text: head.subarray(0, n).toString("utf8"), cut: fs.statSync(p).size > MAX_TEXT };
 }
 
-async function asText(p: string): Promise<string> {  // what read_document returns: the preview, written out as text
+async function asText(p: string): Promise<string> {  // what viewer_read returns: the preview, written out as text
   const v: any = await preview(p);
   if (v.kind === "image") return `${p} is an image: look at it with read.`;
   if (v.kind === "pdf") {
@@ -188,22 +192,23 @@ export default function (pi: ExtensionAPI) {
 
 
   pi.registerTool({
-    name: "read_document", label: "Read document",
+    name: "viewer_read", label: "Viewer read", exposure: "deferred",
     description: "Read a document as text: docx, pptx, xlsx, xls, csv, pdf, doc, or any text file "
       + "(sheets come back as CSV, slides and pages numbered).",
-    parameters: Type.Object({ path: Type.String() }),
-    async execute(_id, { path: p }) {
+    parameters: Type.Object({ path: Type.String(),
+      offset: Type.Optional(Type.Number({ description: "the character to start from, to read on in a long document" })) }),
+    async execute(_id, { path: p, offset = 0 }) {
       let text: string;
       if (!fs.existsSync(p) || !fs.statSync(p).isFile()) text = `error: no file ${p}`;
       else {
-        try { text = await asText(p); } catch (e: any) { text = `error: could not read ${p}: ${e.name}: ${e.message}`; }
-        if (text.length > MAX_TOOL_TEXT) text = text.slice(0, MAX_TOOL_TEXT) + `\n[... cut: ${text.length} characters in all; read parts of it with bash]`;
+        try {
+          const whole = await asText(p), end = offset + MAX_TOOL_TEXT;
+          text = whole.slice(offset, end);
+          if (end < whole.length) text += `\n[... cut: ${whole.length} characters in all; call again with offset=${end} for the rest]`;
+        } catch (e: any) { text = `error: could not read ${p}: ${e.name}: ${e.message}`; }
       }
       return { content: [{ type: "text", text }], details: undefined };
     },
   });
 
-  const guide = fs.readFileSync(path.join(import.meta.dirname, "guide.md"), "utf8")  // short; README.md: the whole of it, read when it says
-    .replace("README.md", path.join(import.meta.dirname, "README.md"));
-  pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.viewer = guide; });
 }

package/{app → agent}/extensions/voice/browser.js

@@ -1,9 +1,9 @@
-// Browser half of the voice extension: a microphone button left of the send button. Click to dictate, click again
-// to stop; each finished piece of speech is added to the input (to read, fix and send). /ui/voice.js does the
+// The page side of the voice extension: a microphone button left of the send button. Click to dictate, click again
+// to stop; each finished piece of speech is added to the input (to read, fix and send). /voice/voice.js does the
 // listening: the server's speech to text when it has STT_BASE_URL, else the browser's own recognition.
 // While dictating, the icon is a sound wave whose bars follow the microphone's loudness (its own AnalyserNode, so
 // it works in both modes).
-import voice from "/ui/voice.js";
+import voice from "/voice/voice.js";
 
 const SVG = '<svg viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" stroke-linecap="round" ' +
   'stroke-linejoin="round">';
@@ -16,6 +16,7 @@ export default function (page) {
   const button = document.createElement("button");
   button.type = "button";  // in the form: not a send
   button.className = "mic";
+  button.dataset.name = "dictate";
   button.title = "Dictate";
   button.innerHTML = MIC;
   input.after(button);

package/{app → agent}/extensions/voice/index.ts

@@ -1,11 +1,12 @@
-// Voice input: speech to text (port of the Python voice plugin). The browser half: a microphone button by the send
-// button (browser.js) and /ui/voice.js, which apps can import too.
+// Voice input: speech to text. The browser half: a microphone button by the send
+// button (browser.js) and /voice/voice.js, which apps can import too.
 // Settings (environment, like MODEL_*): STT_BASE_URL, STT_MODEL, STT_API_KEY. With STT_BASE_URL set, audio goes to
 // POST {STT_BASE_URL}/audio/transcriptions, OpenAI's endpoint, which most providers speak (OpenAI, Groq, Mistral,
 // vLLM; others through LiteLLM). Without it, voice.js uses the browser's own speech recognition.
 // The key stays here: apps are agent-written code, so they post audio to this server, never to the provider.
-//   GET  /voice-api/config      {"api": true | false}: whether audio can go to the API
-//   POST /voice-api/transcribe  multipart: file (a complete audio file, e.g. chunk.webm), language?, prompt?
+//   GET  /voice/config      {"api": true | false}: whether audio can go to the API
+//   POST /voice/transcribe  multipart: file (a complete audio file, e.g. chunk.webm), language?, prompt?
+//   GET  /voice/voice.js    the browser side, for the page (browser.js) and for apps
 //                               -> {"text"} or {"error"} (with the provider's status)
 import { Readable } from "node:stream";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -17,9 +18,10 @@ export default function (_pi: ExtensionAPI) {
   const json = (res: any, status: number, data: object) =>
     res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(data));
 
-  host.routes.set("/voice-api/config", (_req: any, res: any) => json(res, 200, { api: !!base }));
+  host.routes.set("/voice/voice.js", (_req: any, res: any) => host.file(res, `${import.meta.dirname}/voice.js`));
+  host.routes.set("/voice/config", (_req: any, res: any) => json(res, 200, { api: !!base }));
 
-  host.routes.set("/voice-api/transcribe", async (req: any, res: any) => {
+  host.routes.set("/voice/transcribe", async (req: any, res: any) => {
     if (!base) return json(res, 400, { error: "no STT_BASE_URL: use the browser's speech recognition" });
     try {
       // the page's form as is, plus the model (Node reads multipart itself: Request.formData)

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

@@ -1,19 +1,19 @@
 // Voice input for apps: speech from the microphone, as text. An app imports it:
-//   import voice from "/ui/voice.js";
+//   import voice from "/voice/voice.js";
 //   await voice.start(onText, opts)  start listening; onText(text) gets each finished piece of speech, in order
 //                                    opts: language ("en", optional), onState(state, detail) with state one of
 //                                    "listening", "speech", "sending", "off", "error" (detail: the message)
 //   voice.stop()                     stop listening; a piece still being spoken is sent first
 //   voice.mode()                     "api" or "browser", known after start
-// "api" (the sandbox has STT_BASE_URL, see /app/plugins/voice.py): the mic is cut into pieces at pauses
-// (2 to 10 s), each sent as a complete audio file to /voice-api/transcribe; silent pieces aren't sent.
+// "api" (the server has STT_BASE_URL: the voice extension's index.ts): the mic is cut into pieces at pauses
+// (2 to 10 s), each sent as a complete audio file to /voice/transcribe; silent pieces aren't sent.
 // "browser": the browser's own speech recognition (Chrome, Edge, Safari; audio goes to their vendor).
 const shot = new URLSearchParams(window.top.location.search).has("shot");  // a screenshot: don't listen
 let mode = null, stopNow = null;
 
 async function start(onText, { language = "", onState = () => {} } = {}) {
   if (shot || stopNow) return;
-  const config = await fetch("/voice-api/config").then((r) => r.json()).catch(() => ({ api: false }));
+  const config = await fetch("/voice/config").then((r) => r.json()).catch(() => ({ api: false }));
   mode = config.api ? "api" : "browser";
   stopNow = mode === "api" ? await startApi(onText, language, onState) : startBrowser(onText, language, onState);
 }
@@ -57,7 +57,7 @@ async function startApi(onText, language, onState) {
     if (lastText) form.append("prompt", lastText.slice(-200));
     onState("sending");
     try {
-      const r = await fetch("/voice-api/transcribe", { method: "POST", body: form });
+      const r = await fetch("/voice/transcribe", { method: "POST", body: form });
       const data = await r.json();
       if (data.error) return onState("error", data.error);
       if (data.text.trim()) { lastText = data.text; onText(data.text.trim()); }

package/agent/settings.json

@@ -0,0 +1,8 @@
+{
+  "compaction": {
+    "keepRecentTokens": 20000
+  },
+  "defaultTools": [
+    "+tool_search"
+  ]
+}

package/{app/extensions/ui/skills/ui-check → agent/skills/browser-check}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: ui-check
-description: Check a web UI in a real headless browser - JavaScript errors, failed requests, clipped or overflowing elements, how it looks, and whether clicks and keys work. Use after changing any UI (the page, UI components or surfaces, an app you built) and before calling UI work done.
+name: browser-check
+description: Check a web UI in a real headless browser - JavaScript errors, failed requests, clipped or overflowing elements, how it looks, and whether clicks and keys work. Use to check the page itself or a block you wrote, or for steps beyond the app README's example (drag, keys, dialogs, sizes).
 ---
 # Checking a UI in a headless browser
 
@@ -13,7 +13,7 @@ From this skill's folder (paths here are relative to it):
 node scripts/check.mjs URL [STEPS ...] [--size 1280x800] [--shot /tmp/ui.png] [--full]
 ```
 - URL: the user's page is `{page}/`. An app you built is served by it too
-  (`{page}/ui/apps/<name>/index.html`); any other file: `file:///<full path>`.
+  (`{page}/built/apps/<name>/index.html`); any other file: `file:///<full path>`.
 - Steps run in order after the page loads (it gets 1.5 s first):
   `wait:500`, `click:#pause`, `drag:#card=200,0`, `altdrag:#top=-150,0` (Alt held), `hold:.label=800` (press and hold),
   `dblclick:.label`, `type:#message=hello`, `key:Enter`, `eval:document.querySelectorAll('.agent').length`,
@@ -65,7 +65,7 @@ The command you ran, its counts ("0 errors, 0 layout problems at 1280x800 and 39
 eval steps returned, and what you saw in the screenshot.
 
 ## Pitfalls
-- `type:` splits at the first `=`: use a selector without one (`ui-textfield input`, not `[data-surface=x] input`).
+- `type:` splits at the first `=`: use a selector without one (`block-textfield input`, not `[data-card=x] input`).
 - `querySelector` doesn't reach inside a shadow root; use `eval:` with `el.shadowRoot.querySelector(...)`.
 - Content that arrives over the WebSocket may need `wait:1000` before you check it.
 - Chrome starts fresh for each run (no cookies, no storage); each run takes a few seconds.

package/{app/extensions/ui/skills/ui-check → agent/skills/browser-check}/scripts/check.mjs

@@ -247,7 +247,7 @@ async function main(url, steps, size, shotPath, full, fit) {
     return 2;
   }
   const [w, h] = size.split("x").map(Number);
-  const profile = fs.mkdtempSync(path.join(os.tmpdir(), "ui-check-"));
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), "browser-check-"));
   const headless = path.basename(chromePath).startsWith("chrome-headless-shell") ? [] : ["--headless"];  // a full browser: no window
   const chrome = spawn(chromePath, [...headless, "--no-sandbox", "--disable-dev-shm-usage", "--disable-gpu", "--no-first-run",
     `--user-data-dir=${profile}`, "--remote-debugging-port=0", "about:blank"], { stdio: "ignore" });

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

@@ -1,6 +1,6 @@
 ---
-name: ui-design
-description: How to make what you build for the user look good and read clearly - surfaces, components, apps, charts and diagrams. Use before building or restyling anything the user will see in the main space.
+name: design
+description: How to make what you build for the user look good and read clearly - charts, diagrams, game art, dashboards, one look across cards. Use for those, for a restyle, or for a look the user asks for; the app README has the basics a usual app needs.
 ---
 # Designing what the user sees
 
@@ -11,21 +11,21 @@ Precedence: the user's own words, then the page's existing look, then your choic
 ## 1. Fit the page
 The page is light, glassy and quiet (Apple-like): soft gradient background, translucent white glass,
 thin edges, system font. Match it unless the user asks for another look.
-- Use the page's tokens instead of literal colours (they are defined on the page and reach components;
+- Use the page's tokens instead of literal colours (they are defined on the page and reach blocks;
   apps in a frame copy the values they need):
   `--text #1d1d1f`, `--soft rgba(29,29,31,.72)`, `--muted rgba(60,60,67,.55)`, `--accent #0071e3`,
   `--danger #e5484d`, `--line rgba(0,0,0,.06)`, `--glass rgba(255,255,255,.45)`,
   `--glass-strong rgba(255,255,255,.7)`, `--edge rgba(255,255,255,.75)`, `--radius 16px`.
-- The built-in components (Card, Button, Table, Text, TextField, Markdown) already use these tokens;
-  prefer them, and style your own components the same way.
+- The built-in blocks (Panel, Button, Table, Text, TextField, Markdown) already use these tokens;
+  prefer them, and style your own blocks the same way.
 - Font: inherit the page's system font. Use a Google Font only when the subject calls for it
   (a pixel-art game, a poster), and always give a fallback stack.
 - Show just the thing: no frame, card or background around it unless it needs one. Transparent app backgrounds.
-- A user-requested look (pixel art, neon, paper) wins. Commit to it fully inside that surface,
+- A user-requested look (pixel art, neon, paper) wins. Commit to it fully inside that card,
   and keep the rest of the page as it is.
 
 ## 2. Ground it in the subject
-- Pick one concrete job for each surface. Use real content, never lorem ipsum.
+- Pick one concrete job for each card. Use real content, never lorem ipsum.
 - Take at least one detail from the subject's own world: its real units, terms, conventions
   (a chess clock shows mm:ss; a kanban card has an owner and a state).
 - Structure must mean something: number things only when order matters; a divider only between real groups.
@@ -87,19 +87,19 @@ talk, what changes between two options.
 
 ## 9. Make it easy to reshape
 The user changes what you build by hand (pins, levers on the back side, combining, undo), so build for that.
-- One clear thing per surface, with a name the user would say (`lunch-orders`, not `surface3`).
+- One clear thing per card, with a name the user would say (`lunch-orders`, not `card3`).
 - Write `about`: what it is for and any decision a later change should respect ("drinks are not counted").
-- Put what changes in data (rows, scores, settings) and the look in components: data changes are instant
+- Put what changes in data (rows, scores, settings) and the look in blocks: data changes are instant
   for the user and never need you.
-- Read other surfaces' data with `{"ref": "<surface>", "path": "/..."}` instead of copying it, so it stays live.
-- A component you write: its about block lists every prop with a type, and `levers` for the few a user
+- Read other cards' data with `{"ref": "<card>", "path": "/..."}` instead of copying it, so it stays live.
+- A block you write: its about block lists every prop with a type, and `levers` for the few a user
   would want to change (a size, a mode, a label), written as plain sentences.
 
 ## 10. One look
 What the user builds over time should look like one hand made it: a garden and the wrestler standing
 in it share a palette, a way of shading and a level of detail.
 - Before drawing something new, look at what is already there (a screenshot, and the code of the
-  surfaces it sits beside). Match its palette, shading, line weight and detail. Read their code and
+  cards it sits beside). Match its palette, shading, line weight and detail. Read their code and
   reuse their colours and helpers rather than redrawing them from memory.
 - Keep a small palette: a ground, a main colour for shapes, an ink for words, and one accent for the
   one thing to look at. Mix shades from those (`color-mix(in srgb, <main> 70%, <ground>)`, lighter and
@@ -114,10 +114,10 @@ in it share a palette, a way of shading and a level of detail.
   three. Neon, glows, gloss and full saturation everywhere look machine-made unless the subject calls for them.
 - Games and 3D: the same idea as art direction, not exact colours. One sky or fog colour and one light
   colour across the scene hold it together, however many materials it has; the accent marks what the
-  player should notice; the HUD and menus use the palette like any surface.
+  player should notice; the HUD and menus use the palette like any card.
 - A default, not a rule: when the user asks for another look, or a piece clearly needs its own world
   (a dark space game beside a light garden), give it one, commit to it, and say so in its `about`.
 
 ## 11. Check it
-Load ui-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.
+Load browser-check and look at a screenshot: overlaps, clipped text, labels colliding, things outside their box.
+Fix everything you see before you show it: the user marks up details, not missing basics.

package/agent/skills/extension-map/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: extension-map
+description: Find your way around your own code (the pi extensions in your agent folder, the page among them) without reading whole files. Use before changing yourself, or before planning work for others that will.
+---
+# Getting a map of your own code
+
+Your agent folder ({agent} in your prompt) holds `extensions/`. Every feature is one extension, and every extension
+is one folder, `extensions/<name>/`, named after the one thing it is (card, board, note, team...), holding all of it:
+
+| File          | What it is                                                         |
+|---------------|--------------------------------------------------------------------|
+| `index.ts`    | the extension itself (pi loads it); starts with a header comment    |
+| `guide.md`    | its short prompt section (found by itself: the prompt extension adds every one) |
+| `README.md`   | the whole of what the guide says, read when the guide says          |
+| `browser.js`  | its part of the page (found by itself: the page extension loads every one) |
+| `skills/`     | skills only this feature needs (its index.ts gives them to pi)      |
+
+An extension can have other files too (`card/` has its `blocks/`, `page/` has `page.html`, `model/` has
+`login.ts`). The headers are the documentation, kept with the code, so read them before the code itself.
+
+## The naming rule
+Everything an extension adds carries its name: tools `<name>_<verb>` (card_show, note_done, team_ask), page
+messages `<name>_<verb>` (card_move, history_undo), page events `<name>` (card, history), routes `/<name>/...`
+(/card/all, /note/all), its data in {data} (`<name>.json` or `<name>/`), and what it offers others as
+`host.api.<name>` (host.api.card.watch, host.api.team.send). So from any one name you can find the rest.
+
+## 1. The map: one line per extension
+From your agent folder:
+```
+for d in extensions/*/; do printf '%-24s %s\n' "$d" "$(grep -m1 '^//' "$d/index.ts" | sed 's|^// \?||' | cut -c1-140)"; done
+```
+Also there:
+- `extensions/page/`: the page itself (`page.html`), its list of browser parts, and what serves them.
+- `extensions/card/blocks/*.js`: the blocks cards are built from, each starting with a comment line on what it
+  is, then its `about` block (props, levers, example; read its first 20 lines).
+- `skills/<name>/SKILL.md`: skills about you as a whole (this one); a feature's own skills are in its folder.
+- {built}: what you made for the user, not code: `card.json` (the cards), `board.json`, `apps/<name>/`.
+- The host, `server.ts` (its path is in your prompt): the four folders, sessions, the web server, the version
+  history's rule, `globalThis.chalky`. Read its header; don't edit it.
+
+## 2. The headers of the extensions involved
+```
+awk '/^import /{exit} 1' extensions/team/index.ts     # everything above the imports
+```
+Read only the headers of the extensions your work touches. All of them at once is over 13,000 characters.
+
+## 3. Then only the code you will change
+Use `grep -n` to find the function, then `read` with `offset` (its first line) and `limit` for that part.
+A whole file can be long (team's index.ts is over 15,000 characters). If you are planning work for other agents,
+the headers are usually enough: let each agent read the code it owns.
+
+## Keep the headers true
+When you change what an extension provides (a tool, a route, a page message, an event, a host service), update
+its header in the same change, and follow the naming rule. Other agents, and you after a reload, rely on it. A new
+extension is a new folder with an `index.ts` whose header starts with a one-line summary: that line is its entry
+in the map. After editing, call the reload tool.

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/{app → agent}/skills/write-skill/SKILL.md

@@ -19,7 +19,7 @@ skills/<name>/    in your code folder (the one your prompt names, with extension
   assets/         optional: templates, data files
 ```
 A skill that only one feature needs goes in that extension's folder instead, `extensions/<name>/skills/<skill>/`
-(as `extensions/ui/skills/`), and its `index.ts` gives the folder to pi:
+(as `extensions/app/skills/`), and its `index.ts` gives the folder to pi:
 `pi.on("resources_discover", () => ({ skillPaths: [path.join(import.meta.dirname, "skills")] }))`.
 
 ## SKILL.md

package/bin/chalky.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// chalky: starts Chalky from the installed package. Its home (app/, state/, workspace/) is CHALKY_HOME, else
-// ~/.chalky; the first run copies the package's app/ there. Node won't run TypeScript under node_modules
+// chalky: starts Chalky from the installed package. Its home (agent/, built/, data/, workspace/) is CHALKY_HOME,
+// else ~/.chalky; the first run copies the package's agent/ there. Node won't run TypeScript under node_modules
 // (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so server.ts loads through jiti, as pi loads extensions.
 //   MODEL_BASE_URL=... MODEL_API_KEY=... [MODEL_NAME=...] chalky
 import os from "node:os";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalky/chalky",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
@@ -10,13 +10,13 @@
   "files": [
     "bin/",
     "server.ts",
-    "app/",
-    "!app/auth.json",
-    "!app/models-store.json",
-    "!app/mcp-auth.json",
-    "!app/ui/surfaces.json",
-    "!app/ui/apps/*",
-    "app/ui/apps/.keep"
+    "agent/",
+    "!agent/auth.json",
+    "!agent/models-store.json",
+    "!agent/models.json",
+    "!agent/mcp-auth.json",
+    "!agent/mcp.json",
+    "!agent/ui/"
   ],
   "publishConfig": {
     "access": "public"
@@ -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",