@chalky/chalky 0.1.3 → 0.1.5

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/agent/extensions/voice/browser.js

@@ -0,0 +1,72 @@
+// 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 "/voice/voice.js";
+
+const SVG = '<svg viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" stroke-linecap="round" ' +
+  'stroke-linejoin="round">';
+const MIC = SVG + '<rect x="9" y="3" width="6" height="11" rx="3"/><path d="M5 11a7 7 0 0 0 14 0M12 18v3"/></svg>';
+const WAVE = SVG + [4, 8, 12, 16, 20].map((x) => `<line x1="${x}" x2="${x}" y1="10" y2="14"/>`).join("") + "</svg>";
+const SHAPE = [0.45, 0.8, 1, 0.75, 0.5];  // the middle bars reach higher
+
+export default function (page) {
+  const input = document.getElementById("text");
+  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);
+  const style = document.createElement("style");
+  style.textContent = "#f button.mic.on { color: #fff; background: #e5484d; border-color: #e5484d; }";
+  document.head.append(style);
+
+  let on = false, stopWave = null;
+
+  // the wave: loudness (RMS of the mic's samples) sets the bars' height, each wobbling a little on its own
+  async function startWave() {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    const ctx = new AudioContext();
+    const analyser = ctx.createAnalyser();
+    ctx.createMediaStreamSource(stream).connect(analyser);
+    const samples = new Float32Array(analyser.fftSize);
+    button.innerHTML = WAVE;
+    const bars = button.querySelectorAll("line");
+    let level = 0, frame;
+    const draw = (t) => {
+      analyser.getFloatTimeDomainData(samples);
+      const rms = Math.sqrt(samples.reduce((s, x) => s + x * x, 0) / samples.length);
+      level += (Math.min(1, rms * 8) - level) * 0.3;  // smoothed: rises and falls over a few frames
+      bars.forEach((bar, i) => {
+        const half = 1 + 8 * level * SHAPE[i] * (0.7 + 0.3 * Math.sin(t / 90 + i * 1.7));
+        bar.setAttribute("y1", 12 - half);
+        bar.setAttribute("y2", 12 + half);
+      });
+      frame = requestAnimationFrame(draw);
+    };
+    frame = requestAnimationFrame(draw);
+    return () => { cancelAnimationFrame(frame); stream.getTracks().forEach((tr) => tr.stop()); ctx.close(); button.innerHTML = MIC; };
+  }
+
+  const set = (state) => {
+    on = state;
+    button.classList.toggle("on", on);
+    button.title = on ? "Stop dictating" : "Dictate";
+    if (!on && stopWave) { stopWave(); stopWave = null; }
+  };
+  button.addEventListener("click", async () => {
+    if (on) return voice.stop();
+    set(true);
+    startWave().then((stop) => { if (on) stopWave = stop; else stop(); }).catch(() => {});  // no wave: still dictates
+    await voice.start((text) => {
+      input.value = input.value.trim() ? `${input.value.trimEnd()} ${text}` : text;
+      input.focus();
+    }, { onState: (state, detail) => {
+      if (state === "error") { page.note(`voice: ${detail}`); voice.stop(); set(false); }
+      if (state === "off") set(false);
+    } });
+  });
+}

package/agent/extensions/voice/index.ts

@@ -0,0 +1,39 @@
+// 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/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";
+
+const host = (globalThis as any).chalky;
+
+export default function (_pi: ExtensionAPI) {
+  const base = (process.env.STT_BASE_URL || "").replace(/\/$/, "");
+  const json = (res: any, status: number, data: object) =>
+    res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(data));
+
+  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/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)
+      const form = await new Request("http://local", { method: "POST", headers: req.headers,
+        body: Readable.toWeb(req) as any, duplex: "half" } as any).formData();
+      if (!(form.get("file") instanceof Blob)) return json(res, 400, { error: "no audio file" });
+      form.set("model", process.env.STT_MODEL || "whisper-1");
+      const r = await fetch(`${base}/audio/transcriptions`, { method: "POST", body: form,
+        headers: process.env.STT_API_KEY ? { authorization: `Bearer ${process.env.STT_API_KEY}` } : {} });
+      const data: any = await r.json().catch(() => ({}));
+      if (!r.ok) return json(res, 502, { error: `speech to text: ${r.status} ${data.error?.message ?? ""}`.trim() });
+      json(res, 200, { text: data.text ?? "" });
+    } catch (e: any) { json(res, 502, { error: `speech to text: ${e.message}` }); }
+  });
+}

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.
+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.

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/{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,8 +1,8 @@
 #!/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=...] [MODEL_THINKING=...] chalky
+//   MODEL_BASE_URL=... MODEL_API_KEY=... [MODEL_NAME=...] chalky
 import os from "node:os";
 import path from "node:path";
 import { createJiti } from "jiti";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalky/chalky",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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"