@chalky/chalky 0.1.3 → 0.1.5

package/{app → agent}/extensions/page/page.html

@@ -2,7 +2,7 @@
 <!-- The page the user sees, served fresh on every load by the page extension (extensions/page/; edits show on reload).
   Design (pivot 2026-10-14, see the Chalky repo's NOTES.md "Direction"): what the agents build fills the screen; talk is secondary.
   Layout, every part fixed over the full window:
-    #top      main space: what the agents built (the ui plugin draws its surfaces here). Scrolls.
+    #top      main space: what the agents built (the card extension draws its cards here). Scrolls.
     #rail     left edge: icons that open a panel; clicking the open one closes it.
     #panel    a glass panel over the main space: #messages (the conversation) or #versions (history,
               a screenshot of each version, rollback; the user's way to undo the agent's own changes: keep it working).
@@ -14,9 +14,12 @@
               A tool with sub-tools (frames' Implement) is a <span class="tool">: its button, then a
               smaller row (.sub) that hangs directly under it, hidden while none of its buttons shows (pageApi.tool).
     #side     right edge: empty; a browser plugin fills it (the files plugin's file panel).
+  Names (data-name) an agent's pen can point at: tools (the palette), rail, messages, versions, message-line; the
+  palette's buttons get theirs from their plugins (pen, text, eraser, show-marks, note, frames, files, dictate).
   Look: glass layers on one soft background, tokens in :root (colours, glass, blur, sizes); icons are inline
   SVG from ICONS (data-icon="name").
-  Messages: only words are full text (the user's, and an agent's reply); everything else an agent does
+  Messages: only words are full text (the user's, and an agent's reply); a message the page wrote for the user
+  ("[note on the page] ...") shows their words, the whole text in its data-raw (plugins find their ids there); everything else an agent does
   (reasoning, tool calls, results, messages between agents) is a small icon: hover to peek, click to read.
   App agents (status "app": part of something built, e.g. a simulation's members) stay out of the messages,
   the picker and the working rows (one row per app): their app shows their talk.
@@ -24,7 +27,7 @@
   "status", "message", "version", errors. Sending: {to, text} is a message, {type: "stop"} stops all.
   Extending without editing this file: an extension's browser.js (extensions/<name>/browser.js; GET /page/scripts lists them);
   each script's default export gets pageApi: on(type, fn), send(obj) (-> the extensions' page handlers),
-  slot("top" | "status" | "side"), tool(button) -> the row under that palette tool (for its sub-tools), note(text), load(name), component(name, props) (components from extensions/ui/components),
+  slot("top" | "status" | "side"), tool(button) -> the row under that palette tool (for its sub-tools), note(text) -> the line, load(name), block(name, props) (blocks from extensions/card/blocks),
   command(name, fn, description): "/name rest" typed in the input calls fn(rest) instead of sending (other "/..." text
   is sent); typing "/" lists the commands above the input, narrowing as you type.
   provide(name, obj) / use(name) -> promise of obj: what one browser plugin offers others (scripts load in any
@@ -32,11 +35,11 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Chalky</title>
-<!-- Libraries that components import by name (installed from extensions/ui/package.json). Must come before any module. -->
+<!-- Libraries that blocks import by name (the host's dependencies, served by the card extension). Must come before any module. -->
 <script type="importmap">
 { "imports": {
-    "marked": "/ui/node_modules/marked/lib/marked.esm.js",
-    "dompurify": "/ui/node_modules/dompurify/dist/purify.es.mjs"
+    "marked": "/card/node_modules/marked/lib/marked.esm.js",
+    "dompurify": "/card/node_modules/dompurify/dist/purify.es.mjs"
 } }
 </script>
 <style>
@@ -113,17 +116,17 @@
          mask-image: var(--fade); -webkit-mask-image: var(--fade); }
   #log:hover { --fade: linear-gradient(transparent, #000 56px); }
   #log > :first-child { margin-top: auto; }  /* few messages: they sit at the bottom (flex-end would break scrolling) */
-  .block { margin: 0 0 22px; animation: rise 0.4s ease-out; }
+  .group { margin: 0 0 22px; animation: rise 0.4s ease-out; }
   @keyframes rise { from { opacity: 0; transform: translateY(14px); } }
   .who { display: flex; align-items: center; gap: 6px; font-size: 11.5px; font-weight: 500; letter-spacing: 0.01em;
          color: var(--c, var(--muted)); }
   .who svg { width: 16px; height: 16px; }
   .who time { margin-left: auto; font-weight: 400; color: var(--muted); opacity: 0; transition: opacity 0.2s; }
-  .block:hover .who time { opacity: 1; }
+  .group:hover .who time { opacity: 1; }
   .text { margin: 3px 0 0 22px; color: var(--soft); white-space: pre-wrap; overflow-wrap: anywhere; letter-spacing: -0.005em; }
-  .block:not([data-who="you"]) .text { color: var(--text); }
+  .group:not([data-who="you"]) .text { color: var(--text); }
   .text .to { color: var(--muted); font-size: 12px; margin-right: 4px; }
-  .text > ui-markdown, .text > ui-markdown > p:first-child { display: inline; }  /* first line next to .to */
+  .text > block-markdown, .text > block-markdown > p:first-child { display: inline; }  /* first line next to .to */
   .steps { display: flex; flex-wrap: wrap; gap: 1px; margin: 4px 0 0 19px; }
   .step { color: var(--muted); padding: 3px; border-radius: 6px; opacity: 0.8; }
   .step svg { width: 14px; height: 14px; }
@@ -187,9 +190,9 @@
 </style>
 <body data-panel="messages">
 <div id="top"></div>
-<nav id="rail">
-  <button id="show-messages" data-icon="messages" title="Messages"><span class="badge" id="unread"></span></button>
-  <button id="show-versions" data-icon="versions" title="Versions"></button>
+<nav id="rail" data-name="rail">
+  <button id="show-messages" data-name="messages" data-icon="messages" title="Messages"><span class="badge" id="unread"></span></button>
+  <button id="show-versions" data-name="versions" data-icon="versions" title="Versions"></button>
 </nav>
 <aside id="panel">
   <section id="messages"><div id="log"></div></section>
@@ -201,13 +204,13 @@
   </section>
 </aside>
 <div id="working" hidden><div id="busy"></div><button id="stop" data-icon="stop" title="Stop all agents"></button></div>
-<form id="f">
+<form id="f" data-name="message-line">
   <div id="cmds" hidden></div>
   <select id="to" title="Send to" hidden></select>
   <input id="text" placeholder="Tell the agents what to build or change" autocomplete="off">
   <button data-icon="send" title="Send"></button>
 </form>
-<nav id="status"></nav>
+<nav id="status" data-name="tools"></nav>
 <aside id="side"></aside>
 <script>
   const log = document.getElementById("log"), to = document.getElementById("to");
@@ -247,15 +250,15 @@
     to.hidden = to.options.length < 2;
   }
 
-  // ---- Component runtime: the catalog of reusable UI pieces (/ui/components/<Name>.js), each a custom
-  // element <ui-name> with update(props, ui). The page draws replies with it; browser plugins use
-  // page.load / page.component (the ui plugin draws agents' surfaces from the same catalog).
+  // ---- Block runtime: the catalog of blocks (/card/blocks/<Name>.js), each a custom element <block-name> with
+  // update(props, card). The page draws replies with it; browser parts use page.load / page.block (the card
+  // extension draws the agents' cards from the same catalog).
   let catalog = null;
-  const loading = {};  // name -> promise: true once <ui-name> is defined, false if there is no such component
+  const loading = {};  // name -> promise: true once <block-name> is defined, false if there is no such block
   const loaded = {};   // name -> version loaded (custom elements can't be redefined: changes need a reload)
   async function fetchCatalog() {  // false: the agent didn't answer (e.g. restarting); the catalog stays as it was
     try {
-      const r = await fetch("/ui-api/catalog");
+      const r = await fetch("/card/blocks");
       if (r.ok) { catalog = await r.json(); return true; }
     } catch {}
     catalog ??= {};
@@ -265,32 +268,32 @@
     return loading[name] ??= (async () => {
       if (!catalog || !(name in catalog)) await fetchCatalog();  // maybe just written
       if (!(name in catalog)) return false;
-      const tag = `ui-${name.toLowerCase()}`;
-      if (!customElements.get(tag)) customElements.define(tag, (await import(`/ui/components/${name}.js?v=${catalog[name]}`)).default);
+      const tag = `block-${name.toLowerCase()}`;
+      if (!customElements.get(tag)) customElements.define(tag, (await import(`/card/blocks/${name}.js?v=${catalog[name]}`)).default);
       loaded[name] = catalog[name];
       return true;
     })().catch((e) => { delete loading[name]; throw e; });  // a broken file: try again next time
   }
-  async function component(name, props = {}) {  // a ready element, or null if the component is missing/broken
-    try { if (!(await load(name))) return null; } catch (e) { console.warn(`component ${name}:`, e); return null; }
-    const el = document.createElement(`ui-${name.toLowerCase()}`);
+  async function block(name, props = {}) {  // a ready element, or null if the block is missing/broken
+    try { if (!(await load(name))) return null; } catch (e) { console.warn(`block ${name}:`, e); return null; }
+    const el = document.createElement(`block-${name.toLowerCase()}`);
     el.update(props, { children: [], mount() {}, set() {}, action() {} });
     return el;
   }
   // After an agent saves a version (end of its turn), show what it changed without a manual refresh:
-  // an App's files -> reload that App's frame; this page, a browser.js or a component in use -> reload the page
-  // (the browser can't redefine a custom element). New components need nothing: they load on first use.
+  // an app's files -> reload that app's frame; this page, a browser.js or a block in use -> reload the page
+  // (the browser can't redefine a custom element). New blocks need nothing: they load on first use.
   async function refreshAfter(files) {
     if (!(await fetchCatalog())) return reloadWhenUp();  // can't tell what changed: reload once the agent answers
     for (const [n, p] of Object.entries(loading)) p.then((ok) => { if (!ok) delete loading[n]; });  // maybe created now
     const changed = Object.keys(loaded).filter((n) => catalog[n] !== loaded[n]);
-    if (changed.length || files.some((f) => f === "extensions/page/page.html" || f.endsWith("/browser.js"))) return location.reload();
-    const apps = files.filter((f) => f.startsWith("ui/apps/")).map((f) => `/ui/apps/${f.split("/")[2]}/`);
+    if (changed.length || files.some((f) => f === "agent/extensions/page/page.html" || f.endsWith("/browser.js"))) return location.reload();
+    const apps = files.filter((f) => f.startsWith("built/apps/")).map((f) => `/built/apps/${f.split("/")[2]}/`);
     for (const frame of document.querySelectorAll("iframe"))
       if (apps.some((a) => new URL(frame.src, location.href).pathname.startsWith(a))) frame.contentWindow.location.reload();
   }
 
-  // ---- Messages: blocks of consecutive messages from one speaker (an agent, or "you"). A block has a
+  // ---- Messages: groups of consecutive messages from one speaker (an agent, or "you"). A group has a
   // header (robot in the agent's colour, name, time), then words as text and other work as rows of icons.
   let ts = null;  // time of the event being shown (set per event)
   let unread = 0;  // replies that arrived while the messages panel was closed
@@ -300,11 +303,11 @@
     if (atBottom) log.scrollTop = log.scrollHeight;
   }
 
-  function block(who) {
+  function group(who) {
     const last = log.lastElementChild;
     if (last?.dataset.who === who) return last;
     const b = document.createElement("div");
-    b.className = "block";
+    b.className = "group";
     b.dataset.who = who;
     if (who !== "you") b.style.setProperty("--c", colour(who));
     b.innerHTML = `<div class="who">${icon(who === "you" ? "person" : "robot")}<span></span><time></time></div>`;
@@ -318,18 +321,19 @@
     const div = document.createElement("div");
     div.className = "text";
     if (toWhom) div.append(Object.assign(document.createElement("span"), { className: "to", textContent: `→ ${toWhom}` }));
-    const span = document.createElement("span");  // plain at once; swapped for the Markdown component when ready
+    const span = document.createElement("span");  // plain at once; swapped for the Markdown block when ready
     span.textContent = words;
     div.append(span);
-    follow(() => block(who).append(div));
-    component("Markdown", { text: words }).then((el) => el && follow(() => span.replaceWith(el)));
+    follow(() => group(who).append(div));
+    block("Markdown", { text: words }).then((el) => el && follow(() => span.replaceWith(el)));
     if (who !== "you" && document.body.dataset.panel !== "messages")
       document.getElementById("unread").textContent = ++unread;
+    return div;
   }
 
   function step(agent, kind, title, content, error = false) {  // one icon in the agent's row; click to read it
     follow(() => {
-      const b = block(agent);
+      const b = group(agent);
       let row = b.lastElementChild;
       if (row.classList.contains("detail")) row = row.previousElementSibling;  // the row whose step is open
       if (!row.classList.contains("steps")) b.append((row = Object.assign(document.createElement("div"), { className: "steps" })));
@@ -351,8 +355,10 @@
     });
   }
 
-  function note(words) {  // a quiet line: joined, saved a version, errors, ...
-    follow(() => log.append(Object.assign(document.createElement("div"), { className: "note", textContent: words })));
+  function note(words) {  // a quiet line: joined, saved a version, errors, ... (returns it, for a plugin to act on)
+    const line = Object.assign(document.createElement("div"), { className: "note", textContent: words });
+    follow(() => log.append(line));
+    return line;
   }
 
   // ---- Working: animated dots for each agent that isn't idle (from "status" events), Stop beside them
@@ -391,8 +397,8 @@
     send: (obj) => ws.send(JSON.stringify(obj)),          // arrives at the extensions' page handlers
     slot: (id) => document.getElementById(id),  // "top": the main space; "status": the tool palette (top); "side": right edge
     note,       // note(text): a quiet line in the messages
-    load,       // load(name): define component <ui-name>; resolves false if there is no such component
-    component,  // component(name, props): a ready element, or null
+    load,       // load(name): define block <block-name>; resolves false if there is no such block
+    block,      // block(name, props): a ready element, or null
     command: (name, fn, description = "") => { commands[name] = { fn, description }; },
     provide: (name, obj) => { offered[name] = obj; for (const ok of wanted[name] || []) ok(obj); delete wanted[name]; },
     use: (name) => name in offered ? Promise.resolve(offered[name]) : new Promise((ok) => (wanted[name] ??= []).push(ok)),
@@ -409,7 +415,7 @@
   });
 
   const lastFrom = {};  // agent -> who its current turn's answer goes to
-  const asked = {};     // ask_agent / tell tool-call ids
+  const asked = {};     // team_ask / team_tell tool-call ids
 
   ws.onmessage = (e) => {
     const ev = JSON.parse(e.data);
@@ -433,11 +439,11 @@
         const m = /^\[(\w+) from ([^\s\]]+)[^\]]*\][^\n]*\n?/.exec(content);
         const from = m ? m[2] : "user", words = m ? content.slice(m[0].length) : content;
         if (ev.reply_to) lastFrom[a] = ev.reply_to;  // set on the message that starts a turn
-        // a message the page wrote for the user ("[note on the UI] <their words>" + lines for the agent):
+        // a message the page wrote for the user ("[note on the page] <their words>" + lines for the agent):
         // show their words; the lines meant for the agent go behind an icon
         const tagged = from === "user" && /^\[([^\]]+)\] ?(.*)/.exec(words);
         if (tagged) {
-          text("you", tagged[2] || tagged[1], agents.size > 1 ? a : null);
+          text("you", tagged[2] || tagged[1], agents.size > 1 ? a : null).dataset.raw = words;  // all of it, for plugins (doodle: its group)
           if (words.includes("\n")) step("you", "inbox", `${tagged[1]}: what ${a} got`, words);
         } else if (from === "user") text("you", words, agents.size > 1 ? a : null);
         // from another agent: already shown as its "asks"/"tells" step, or as its answer
@@ -454,12 +460,12 @@
         for (const c of ev.tool_calls || []) {
           let args = {};
           try { args = JSON.parse(c.function.arguments); } catch {}
-          if (c.function.name === "ask_agent") { asked[c.id] = true; step(a, "ask", `${a} asks ${args.to}`, args.text || ""); }
-          else if (c.function.name === "tell") { asked[c.id] = true; step(a, "ask", `${a} tells ${args.to}`, args.text || ""); }
+          if (c.function.name === "team_ask") { asked[c.id] = true; step(a, "ask", `${a} asks ${args.to}`, args.text || ""); }
+          else if (c.function.name === "team_tell") { asked[c.id] = true; step(a, "ask", `${a} tells ${args.to}`, args.text || ""); }
           else step(a, "tool", `${a} → ${c.function.name}`, c.function.arguments);
         }
       }
-      // an ask_agent result is the other agent's answer, already shown as its reply; a tell result is
+      // a team_ask result is the other agent's answer, already shown as its reply; a team_tell result is
       // just "sent" (errors still shown)
       // a result may be a list of parts (view_image): text, and [image <path>] for an image
       const res = typeof ev.content === "string" ? ev.content
@@ -562,7 +568,7 @@
   };
 
   async function loadVersions() {
-    try { versions = await (await fetch("/versions")).json(); } catch { return; }  // no versions plugin
+    try { versions = await (await fetch("/version")).json(); } catch { return; }  // no versions plugin
     sel = Math.max(0, versions.findIndex((v) => v.current));
     renderWheel();
   }
@@ -587,7 +593,7 @@
     detail.textContent = `${v.short} · ${v.author} · ${new Date(v.date).toLocaleString()}` + (v.current ? " · current" : "");
     rollbackBtn.disabled = v.current;
     preview.hidden = !v.shot;  // a version made while no page was open has no picture
-    if (v.shot) preview.src = `/versions/${v.sha}/shot`;
+    if (v.shot) preview.src = `/version/${v.sha}/shot`;
   }
 
   function select(i) {
@@ -602,7 +608,7 @@
     if (!confirm(`Roll back to "${v.message}" (${v.short})?\n\nThe agent restarts and busy agents are interrupted. ` +
                  `Later changes stay in the history, so you can roll forward again.`)) return;
     note(`rolling back to ${v.short}…`);
-    await fetch(`/versions/${v.sha}/rollback`, { method: "POST" });
+    await fetch(`/version/${v.sha}/rollback`, { method: "POST" });
   };
 
   openPanel(SHOT ? "" : document.body.dataset.panel);

package/agent/extensions/prompt/index.ts

@@ -0,0 +1,38 @@
+// The prompt after SYSTEM.md (pi's documented way to replace its default prompt, plain text): one section per
+// extension, its guide.md, then <paths>. A guide.md is found by looking in each extension folder, as the page finds
+// browser.js, so an extension has nothing to register. Read again on every input (an edited guide shows at once).
+// In a guide: {agent} {built} {data} {workspace} {page} become the full paths and address, {name} and {role} this
+// agent's, and README.md the full path of that extension's README.md. pi adds the skills list and <cwd> itself.
+// READMEs and skills keep the placeholders as written (agents edit them; <paths> says what each one is).
+import fs from "node:fs";
+import path from "node:path";
+import { getDocsPath, getExamplesPath, getReadmePath, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const host = (globalThis as any).chalky;
+const EXTENSIONS = path.dirname(import.meta.dirname);
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", (event) => {
+    const name = pi.getSessionName() ?? "", page = `http://127.0.0.1:${host.port}`;
+    const values: Record<string, string> = { agent: host.agent, built: host.built, data: host.data, workspace: host.workspace,
+      page, name, role: host.agents.get(name)?.role ?? "" };
+    const sections = event.systemPromptOptions.sections;
+    for (const ext of fs.readdirSync(EXTENSIONS).sort()) {
+      const guide = path.join(EXTENSIONS, ext, "guide.md");
+      if (!fs.existsSync(guide)) continue;
+      sections[ext] = fs.readFileSync(guide, "utf8").replace(/\{(\w+)\}/g, (m, k) => values[k] ?? m)
+        .replaceAll("README.md", path.join(EXTENSIONS, ext, "README.md"));
+    }
+    sections.paths = [
+      `{agent} = ${host.agent}: you: your prompt, settings, extensions/ and skills/`,
+      `{built} = ${host.built}: what you make for the user: card.json (the cards), board.json (the boards), apps/<name>/ (the apps)`,
+      `  {agent} and {built} are versioned together: each turn that changes them is saved, and the user can roll both back.`,
+      `{data} = ${host.data}: what is kept while running (conversations, what users typed into cards and apps, notes; not versioned)`,
+      `{workspace} = ${host.workspace}: your working folder (<cwd>), for project work; drops/ in it holds the user's files`,
+      `{page} = ${page}: the user's page; a file in {built} is at {page}/built/<its path in {built}>`,
+      `The host: ${host.root}/server.ts`,
+      `pi's docs: ${getDocsPath()}/extensions.md for extensions, examples in ${getExamplesPath()}/extensions/; the rest in `
+        + `${getReadmePath()} and ${getDocsPath()}/. Read pi's .md files completely and follow their links.`,
+    ].join("\n");
+  });
+}

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

@@ -1,8 +1,8 @@
-// Self-edits take effect: the Python agent's restart plugin, the pi way. The tool only asks; when this agent's turn
+// Reload: an agent's edits to itself take effect. The tool only asks; when this agent's turn
 // has ended, the host calls pi's session.reload() (extensions, skills and prompt load again; the conversation stays).
 // Not pi's reload-runtime.ts example: its pi.sendUserMessage("/reload-runtime") reaches the model as text in 1.4.0
 // (expandPromptTemplates defaults to false), and the model kept calling the tool again.
-// No process restart, so no start.sh (a rollback: the versions plugin, which reloads every agent).
+// No process restart, so no start.sh (a rollback: the version extension, which reloads every agent).
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
@@ -13,7 +13,7 @@ export default function (pi: ExtensionAPI) {
     async execute(_id, a) {
       const host = (globalThis as any).chalky, name = pi.getSessionName();
       host.reloadAfterTurn.set(name, false);  // not quiet: the page notes the reload
-      host.shared.set(`reload-reason ${name}`, a.reason);  // the versions plugin's commit message for this turn
+      host.shared.set(`reload-reason ${name}`, a.reason);  // the version extension's commit message for this turn
       return { content: [{ type: "text", text: "Reload scheduled for when your turn ends. End your turn now; don't call reload again." }],
                details: undefined };
     },

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

@@ -1,11 +1,11 @@
-// Browser half of the screen extension (Python's screen.js, unchanged but for this header): this tab, shared once (getDisplayMedia), for every plugin that needs a picture
-// of what the user sees. Offered as page.provide("screen", {...}); a plugin gets it with await page.use("screen"):
+// The page side of the screen extension: this tab, shared once (getDisplayMedia), for every extension that needs a picture
+// of what the user sees. Offered as page.provide("screen", {...}); an extension gets it with await page.use("screen"):
 //   share()            ask the browser to share this tab (only works right after a click: transient activation);
 //                      resolves true if shared. The user can stop sharing any time (the browser's bar).
 //   shared()           whether the tab is shared now
 //   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 see_user_screen, event screen_ask): if the tab is shared, a picture
+// 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
 // (screen_reply {id, shot, window, main}).
 export default async function (page) {
@@ -57,7 +57,7 @@ export default async function (page) {
     await new Promise((ok) => setTimeout(ok, 300));         // 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 point.js)
+    const m = area.getBoundingClientRect();  // 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 } });
   }

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

@@ -1,9 +1,9 @@
-// Screen: what the user sees, as pictures (port of the Python screen plugin; browser.js is its screen.js). The
+// Screen: what the user sees, as pictures. The
 // browser half shares the tab once (for every extension: doodle's steps, an agent's look) and uploads pictures
-// cropped from it. This half keeps them and gives agents the tool see_user_screen: the user's window as it is now
-// (their size, scroll, panels, running apps; ui-check's headless Chrome is a fresh window of its own).
-//   POST /screen/shot       a png (at most MAX_BYTES): saved in state/screens, {path} back
-//   event "screen_ask"      {id, agent} to every open page, when an agent calls see_user_screen
+// cropped from it. This half keeps them and gives agents the tool screen_see: the user's window as it is now
+// (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)
 //   event "screen_ask_done" {id} to every page when answered or after ASK_WAIT s, so the asks go away
@@ -14,14 +14,14 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 const host = (globalThis as any).chalky;
-const SHOTS = path.join(host.state, "screens");  // outside app/: not code
+const SHOTS = path.join(host.data, "screen");
 const MAX_BYTES = 8 * 1024 * 1024;
 const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-const ASK_WAIT = 90;  // s for the user to answer see_user_screen
+const ASK_WAIT = 90;  // s for the user to answer screen_see
 
 const isShot = (p: unknown) => typeof p === "string" && path.dirname(p) === SHOTS && fs.existsSync(p);
 host.api.screen = { isShot };
-// id -> resolve, while see_user_screen waits for a page (on the host: the tool is per agent, the page handler one)
+// id -> resolve, while screen_see waits for a page (on the host: the tool is per agent, the page handler one)
 const asks: Map<string, (msg: any) => void> = host.shared.get("screen-asks") ?? new Map();
 host.shared.set("screen-asks", asks);
 
@@ -50,9 +50,9 @@ const result = (text: string, png?: string) => ({ details: undefined, content: [
 
 export default function (pi: ExtensionAPI) {
   pi.registerTool({
-    name: "see_user_screen", label: "See the user's screen",
+    name: "screen_see", label: "Screen see", exposure: "deferred",
     description: "See the user's screen as they see it right now: a picture of their whole window (their size, scroll, "
-      + "open panels, apps as they are running). ui-check's headless Chrome is a fresh window of its own, not theirs: when "
+      + "open panels, apps as they are running). browser-check's headless Chrome is a fresh window of its own, not theirs: when "
       + "the user talks about what they see, or before you say something looks right to them, look here. The first "
       + "time, the user is asked to share the tab (they may say no); then it's instant.",
     parameters: Type.Object({}),
@@ -74,7 +74,7 @@ export default function (pi: ExtensionAPI) {
       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 ui_render's place uses).`, reply.shot);
+        + `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/{app/extensions/steps → agent/extensions/step}/index.ts

@@ -1,4 +1,4 @@
-// A limit on steps (model calls) per input, as the Python loop's MAX_STEPS: pi's loop has none, and a model that
+// Step: a limit on steps (model calls) per input: pi's loop has none, and a model that
 // keeps calling tools would run on (it did once: 55 rounds). At the limit the run is stopped and the agent says so.
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 

package/{app/extensions/swarm → agent/extensions/team}/README.md

@@ -1,4 +1,4 @@
-# Your team (the swarm extension)
+# Your team (the team extension)
 Your name and role are in your team section.
 You work with other AI agents as peers; there is no manager.
 
@@ -6,30 +6,30 @@ You work with other AI agents as peers; there is no manager.
 - What you receive starts with a header: "[<kind> from <name> · <time>]". <name> is "user" (the human),
   another agent, or a harness part ("system"). Kinds:
   message (from the user or the harness), question (the sender is waiting for your answer),
-  note (the sender went on working), reply (the answer to a note you sent),
+  request (the sender went on working), reply (the answer to a request you sent),
   fyi (an update from an agent working for you; its final answer still comes).
-- Your final answer in a turn is delivered for you: to the sender of a message, question or note; after a
+- Your final answer in a turn is delivered for you: to the sender of a message, question or request; after a
   reply, to whoever you were working for (the header says where). Say it once, there; don't repeat it.
-- tell(to, text): send a note and keep working. If the agent is busy it sees the note between its tool
+- team_tell(to, text): send a request and keep working. If the agent is busy it sees the request between its tool
   calls; if idle it starts on it. Its answer comes back to you later as a reply.
-  Notes that arrive while you work show up between your tool calls: if one needs an answer other than
-  your final one, answer it with tell.
-  A tell to the agent you are working for is information only (it gets your final answer anyway and won't
-  reply to the tell). To ask it something, use ask_agent.
-- Waiting: when all that is left is waiting for others, end your turn. Replies and notes wake
+  Requests that arrive while you work show up between your tool calls: if one needs an answer other than
+  your final one, answer it with team_tell.
+  A team_tell to the agent you are working for is information only (it gets your final answer anyway and won't
+  reply to it). To ask it something, use team_ask.
+- Waiting: when all that is left is waiting for others, end your turn. Replies and requests wake
   you. Never sleep or poll (no sleep loops, no repeated status checks).
-- Don't use tell to deliver your result: your final answer already gets there. Don't send thanks or
+- Don't use team_tell to deliver your result: your final answer already gets there. Don't send thanks or
   acknowledgements.
-- ask_agent(to, text): ask and wait for the answer (it comes back as the result). Use it for quick
-  questions you can't continue without; use tell for work that takes a while. Several ask_agent calls
-  in one step run in parallel. You can't ask an agent that is waiting on you (tell it instead).
-- list_agents shows the team and what each agent is doing right now (idle, working on what, waiting on
+- team_ask(to, text): ask and wait for the answer (it comes back as the result). Use it for quick
+  questions you can't continue without; use team_tell for work that takes a while. Several team_ask calls
+  in one step run in parallel. You can't ask an agent that is waiting on you (team_tell it instead).
+- team_list shows the team and what each agent is doing right now (idle, working on what, waiting on
   whom). Check it instead of asking agents for status.
-- spawn_agent adds a member (numbered agent1, agent2, ... in creation order; spawn_agent says when the team is full).
+- team_spawn adds a member (numbered agent1, agent2, ... in creation order; it says when the team is full).
   An agent that is part of something you build (a simulation's member, a character) is an app agent,
-  not a worker: load the agent-apps skill. spawn_agent(..., app=<its surface>) keeps its talk out of the
+  not a worker: load the app-agents skill. team_spawn(..., app=<its card>) keeps its talk out of the
   user's messages panel (the app shows it).
-  reset_agent(name, or app=<surface> for all of an app's agents) empties their memory, keeping their
+  team_reset(name, or app=<card> for all of an app's agents; load it with tool_search) empties their memory, keeping their
   roles: for a new round that should start fresh.
 
 # Working as a team
@@ -42,6 +42,6 @@ You work with other AI agents as peers; there is no manager.
 - Found a defect in someone else's work? Tell its owner what is wrong and how you found it; don't fix it
   in their files yourself.
 - When others' code will import yours, create the file (a stub) first so imports work while you build.
-- Before saying something is missing or not done, check again (files, list_agents): it may have changed.
+- Before saying something is missing or not done, check again (files, team_list): it may have changed.
 - Say so before installing anything or making a decision that affects others.
-- Other agents may change the same files (in {code} too). Check list_agents and coordinate with tell.
+- Other agents may change the same files (in {agent} too). Check team_list and coordinate with team_tell.

package/{app/extensions/swarm → agent/extensions/team}/guide.md

@@ -1,11 +1,11 @@
 # Your team
 Your name: {name}. Your role: {role}. You work with other AI agents as peers; there is no manager.
 - What you receive starts with "[<kind> from <name> · <time>]": a message (from the user or the harness), a
-  question (the sender waits for your answer), a note (the sender went on working), a reply (the answer to
-  your note) or an fyi (an update, no answer needed). Your final answer is delivered for you, to whoever the
+  question (the sender waits for your answer), a request (the sender went on working), a reply (the answer to
+  your request) or an fyi (an update, no answer needed). Your final answer is delivered for you, to whoever the
   header says: say it once, there.
-- tell(to, text) sends a note and you keep working; its answer comes back as a reply. ask_agent(to, text) asks
-  and waits. list_agents shows who is doing what now. spawn_agent adds a member (at most {max_agents}).
+- team_tell(to, text) sends a request and you keep working; its answer comes back as a reply. team_ask(to, text)
+  asks and waits. team_list shows who is doing what now. team_spawn adds a member (it says when the team is full).
 - When all that is left is waiting, end your turn: replies wake you. Never sleep or poll.
 - Done means checked: run or test it, and say what you ran and what it showed.
 - Simple work: do it yourself. Before you spawn, split or hand out work, or take work from another agent, read README.md.