@frebreco/canvas 0.3.0-next.1 → 0.3.0-next.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frebreco/canvas",
-  "version": "0.3.0-next.1",
+  "version": "0.3.0-next.10",
   "description": "A multiplayer canvas for coding agents that run on your machine.",
   "license": "MIT",
   "type": "module",
@@ -18,6 +18,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "canvas",
+  "description": "Skills canvas gives the agents it runs.",
+  "skills": "./"
+}

package/skills/code-tour/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: code-tour
+description: Give a code tour on the canvas board — a guided walk through how part of the codebase works, as one files frame people click through. Use when asked for a tour or walkthrough of code, how a feature works across files, or to onboard someone to an area.
+---
+
+A code tour is one files frame on the board whose list holds, in reading order: a guide (a
+markdown scratch file), then the **stops** — project files at the lines that matter — and
+optionally a diagram at the end. People click through it at their own pace; the thread only
+points at it.
+
+## Steps
+
+1. **Find the stops.** Read the code until you can tell the story from entry point to effect.
+   Pick 4–10 stops in the order a newcomer needs them, usually where it starts → the core → the
+   edges. A stop is one file at a tight line range (roughly 5–40 lines): the function, the branch,
+   the type that carries the idea. Only files git tracks can be shown; a stop in an ignored file
+   gets described in the guide instead. Done when each stop's range is read from the file as it
+   is now, and the stops tell the story without gaps.
+
+2. **Write the guide**, `tour-<topic>.md`: a one-paragraph overview, then one short section per
+   stop, numbered and titled like its list entry — what to look at in those lines, why it
+   matters, and how it hands over to the next stop. Name functions and types; quote lines
+   sparingly, the frame shows them. End with open questions or pitfalls if you found any.
+
+3. **Draw it**, when the flow branches or spans several components: `tour-<topic>.html`, a
+   single self-contained page (inline CSS and SVG or script) with boxes named like the stops.
+   Skip it for a straight line of calls.
+
+4. **Open the tour.** `view_board` first; retarget an existing tour frame on the same topic with
+   `update_frame` rather than opening a second one. Otherwise one `open_frame` of type `file`
+   whose `files` list is the whole tour, the guide first:
+
+   ```json
+   {
+     "type": "file",
+     "title": "Tour: login",
+     "files": [
+       { "display": "0 Guide.md", "name": "tour-login.md", "content": "…" },
+       { "display": "1 Route/login.ts", "path": "src/routes/login.ts", "start_line": 12, "end_line": 30 },
+       { "display": "2 Session/session.ts", "path": "src/auth/session.ts", "start_line": 5, "end_line": 22 },
+       { "display": "3 Diagram.html", "name": "tour-login.html", "content": "…" }
+     ]
+   }
+   ```
+
+   Number the display names like the guide's sections, so people can match them; folders are
+   worth it only for chapters of a long tour. Done when every stop in the list has its section
+   in the guide and every section its stop.
+
+5. **Reply briefly**: the tour's frame, how many stops, and the story in one or two sentences.
+   The guide carries the explanation; the thread stays short.
+
+## Walking people through it
+
+When people ask to be walked through the tour ("next", "show stop 3"), `update_frame` the tour
+frame to that stop's `path`, `start_line` and `end_line`, and explain it in your reply. Changing
+the frame makes you its occupant for the turn, so everyone following scrolls with you.
+
+## Revising
+
+Follow-up questions often deserve a stop or a section. `write_board_file` with the guide's path
+rewrites it in place. `update_frame` with `files` replaces the whole list, so send every entry,
+the new one in its place. Name the guide and diagram there by their `canvas:scratch/` paths:
+`content` would create new copies.

package/src/cli.ts

@@ -54,6 +54,7 @@ const { server, room } = await serve({
   port: Number(values.port),
   hostname: tlsHost ? "0.0.0.0" : "127.0.0.1",
   ...(tlsHost && { tls: { cert: values.cert, key: values.key } }),
+  ...(manifest.version && { version: manifest.version }),
 });
 
 const serverUrl = tlsHost ? `wss://${tlsHost}:${server.port}` : `ws://127.0.0.1:${server.port}`;

package/src/server/agents.ts

@@ -46,6 +46,7 @@ import type {
   SessionSnapshot,
 } from "../shared/protocol";
 import { fromAcp, pendingChanges, settingsOf } from "./agent-config";
+import { SKILLS_DIR } from "./skills";
 import { trimEvent } from "./trim-event";
 
 interface AgentDefinition extends AgentInfo {
@@ -78,6 +79,8 @@ export function detectAgents(): ReadonlyArray<AgentDefinition> {
         claudeCode: {
           options: {
             allowedTools: BOARD_TOOL_NAMES.map((name) => `mcp__${BOARD_SERVER_NAME}__${name}`),
+            // canvas's own skills; the host's stay available beside them.
+            plugins: [{ type: "local", path: SKILLS_DIR, skipMcpDiscovery: true }],
           },
         },
       },
@@ -93,6 +96,8 @@ export function detectAgents(): ReadonlyArray<AgentDefinition> {
           model: opencodeModel,
           // Shell commands ask, so a person approves anything the agent runs.
           permission: { bash: "ask" },
+          // canvas's own skills; the host's stay available beside them.
+          skills: { paths: [SKILLS_DIR] },
         }),
       },
     },

package/src/server/board-mcp.ts

@@ -12,12 +12,24 @@
  * paths are checked against the shared set here first (ADR 0002), so the
  * agent hears why a file can't be shown. It listens on loopback only: agents
  * run on this machine.
+ *
+ * An agent's comment (ADR 0006) gets the text of its lines here, from the
+ * shared set: the browser keeps it to find the lines again as the file
+ * changes.
+ *
+ * Scratch files (ADR 0005) never reach the browser as content: a call's
+ * `content` becomes a file in `.canvas/scratch/` here, and the call goes on
+ * with its path. Reading and writing them needs no board, so those tools are
+ * answered here.
  */
 
 import { randomBytes } from "node:crypto";
 import type { McpServer } from "@agentclientprotocol/sdk";
 import { BOARD_SERVER_NAME, BOARD_TOOLS, boardInstructions } from "../shared/board-tools";
+import { linesOf, quoteOf } from "../shared/comments";
 import type { FileContent } from "../shared/protocol";
+import type { Scratch } from "./scratch";
+import type { Skill } from "./skills";
 
 export interface BoardCall {
   readonly callId: string;
@@ -29,8 +41,11 @@ export interface BoardCall {
 export interface BoardMcpOptions {
   /** A file as the shared set lets it out. */
   readonly read: (path: string) => FileContent;
+  readonly scratch: Pick<Scratch, "create" | "write" | "read" | "list" | "remove">;
   /** Send a call to the host's browser; false if none is connected. */
   readonly relay: (call: BoardCall) => boolean;
+  /** canvas's skills, named in the priming. */
+  readonly skills?: ReadonlyArray<Skill>;
   readonly timeoutMs?: number;
 }
 
@@ -126,7 +141,7 @@ export class BoardMcp {
               : LATEST_PROTOCOL,
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: BOARD_SERVER_NAME, version: "0.0.0" },
-          instructions: boardInstructions(sessionId),
+          instructions: boardInstructions(sessionId, this.options.skills),
         });
       case "ping":
         return reply({});
@@ -151,22 +166,105 @@ export class BoardMcp {
   private async call(
     sessionId: string,
     tool: string,
-    args: Record<string, unknown>,
+    input: Record<string, unknown>,
   ): Promise<ToolResult> {
     if (!BOARD_TOOLS.some((t) => t.name === tool)) return failed(`no tool ${tool}`);
-    let note = "";
-    if (typeof args.path === "string" && args.path.trim()) {
-      const path = args.path.trim().replace(/^(\.\/)+/, "");
-      const file = this.options.read(path);
-      if (file.kind === "denied") return failed(file.reason);
-      if (file.kind === "missing")
-        note = `\n(${path} doesn't exist yet; the frame shows it as soon as it is written.)`;
-      if (file.kind === "text" && typeof args.start_line === "number") {
-        const lines = file.text.split("\n").length - (file.text.endsWith("\n") ? 1 : 0);
-        if (args.start_line > lines) return failed(`${path} has ${lines} lines`);
+    const args = { ...input };
+    const notes: string[] = [];
+    // Content becomes a scratch file; the board only ever sees its path.
+    const created: string[] = [];
+    const undo = () => created.forEach((path) => this.options.scratch.remove(path));
+    try {
+      switch (tool) {
+        case "read_board_file":
+          return done(this.readScratch(args.path));
+        case "write_board_file":
+          return done(this.writeScratch(args));
       }
+      if (args.content !== undefined) {
+        if (args.path !== undefined) throw new Error("give either path or content, not both");
+        args.path = this.createScratch(args.name, args.content, created, notes);
+        delete args.content;
+        delete args.name;
+      } else this.checkPath(args, notes);
+      if (tool === "add_comment") this.quote(args);
+      if (Array.isArray(args.files))
+        args.files = args.files.map((value: unknown) => {
+          if (typeof value !== "object" || value === null)
+            throw new Error("each entry of files is an object with a display path");
+          const entry = { ...(value as Record<string, unknown>) };
+          if (entry.content !== undefined) {
+            if (entry.path !== undefined)
+              throw new Error("give a list entry either path or content, not both");
+            // No name: one from the display path's last segment, e.g. "1 Overview.md" → 1-Overview.md.
+            const name =
+              entry.name ??
+              (String(entry.display ?? "")
+                .split("/")
+                .at(-1)!
+                .replace(/[^\w.-]+/g, "-")
+                .replace(/^[^\w]+/, "") ||
+                "file");
+            entry.path = this.createScratch(name, entry.content, created, notes);
+            delete entry.content;
+            delete entry.name;
+          } else this.checkPath(entry, notes);
+          return entry;
+        });
+    } catch (error) {
+      undo();
+      return failed((error as Error).message);
+    }
+    if (tool === "view_board") {
+      const scratch = this.options.scratch.list();
+      notes.push(
+        scratch.length ? `Scratch files: ${scratch.join(", ")}.` : "No scratch files yet.",
+      );
     }
 
+    const answer = await this.relay(sessionId, tool, args);
+    if (answer.isError) {
+      undo();
+      return answer;
+    }
+    return notes.length ? done([answer.content[0]!.text, ...notes].join("\n")) : answer;
+  }
+
+  /** A named file must be in the shared set (or a scratch file), and have the lines asked for. */
+  private checkPath(args: Record<string, unknown>, notes: string[]) {
+    if (typeof args.path !== "string" || !args.path.trim()) return;
+    const path = args.path.trim().replace(/^(\.\/)+/, "");
+    const file = this.options.read(path);
+    if (file.kind === "denied") throw new Error(file.reason);
+    if (file.kind === "missing")
+      notes.push(`(${path} doesn't exist yet; the frame shows it as soon as it is written.)`);
+    if (file.kind === "text" && typeof args.start_line === "number") {
+      const lines = file.text.split("\n").length - (file.text.endsWith("\n") ? 1 : 0);
+      if (args.start_line > lines) throw new Error(`${path} has ${lines} lines`);
+    }
+  }
+
+  /** An agent's comment carries the text of its lines. */
+  private quote(args: Record<string, unknown>) {
+    if (typeof args.path !== "string" || !args.path.trim())
+      throw new Error("a comment needs the path of the file it is on");
+    const path = args.path.trim().replace(/^(\.\/)+/, "");
+    const file = this.options.read(path);
+    if (file.kind !== "text")
+      throw new Error(
+        `${path} can't be commented on: ${file.kind === "denied" ? file.reason : file.kind}`,
+      );
+    const start = Math.floor(Number(args.start_line));
+    const end = args.end_line === undefined ? start : Math.floor(Number(args.end_line));
+    const quote = quoteOf(file.text, start, end);
+    if (quote === null)
+      throw new Error(
+        `lines ${start}-${end} aren't in ${path}: it has ${linesOf(file.text).length} lines`,
+      );
+    Object.assign(args, { path, start_line: start, end_line: end, quote });
+  }
+
+  private relay(sessionId: string, tool: string, args: Record<string, unknown>) {
     const callId = crypto.randomUUID();
     const result = new Promise<ToolResult>((resolve) => {
       const timer = setTimeout(
@@ -182,8 +280,41 @@ export class BoardMcp {
         "the board isn't open right now: it lives in the host's browser, which is not connected",
       );
     }
-    const answer = await result;
-    return note && !answer.isError ? done(answer.content[0]!.text + note) : answer;
+    return result;
+  }
+
+  /** A new scratch file for `content`; its path. Says so in `notes`. */
+  private createScratch(name: unknown, content: unknown, created: string[], notes: string[]) {
+    if (typeof content !== "string") throw new Error("content must be text");
+    if (typeof name !== "string" || !name.trim())
+      throw new Error("content needs a name for its scratch file, e.g. overview.md");
+    const path = this.options.scratch.create(name.trim(), content);
+    created.push(path);
+    const taken = !path.endsWith(`/${name.trim()}`);
+    notes.push(`Wrote scratch file ${path}${taken ? ` (${name.trim()} was taken)` : ""}.`);
+    return path;
+  }
+
+  private readScratch(path: unknown): string {
+    if (typeof path !== "string") throw new Error("path must be a canvas:scratch/… path");
+    const file = this.options.scratch.read(path.trim());
+    if (file.kind === "text") return file.text;
+    if (file.kind === "denied") throw new Error(file.reason);
+    if (file.kind === "missing")
+      throw new Error(`${path} doesn't exist; view_board lists the scratch files`);
+    throw new Error(`${path} can't be read`);
+  }
+
+  private writeScratch(args: Record<string, unknown>): string {
+    if (typeof args.path === "string" && args.path.trim()) {
+      if (args.name !== undefined) throw new Error("give either path (overwrite) or name (create)");
+      if (typeof args.content !== "string") throw new Error("content must be text");
+      this.options.scratch.write(args.path.trim(), args.content);
+      return `Wrote ${args.path.trim()}; frames showing it update.`;
+    }
+    const notes: string[] = [];
+    this.createScratch(args.name, args.content, [], notes);
+    return notes[0]!;
   }
 }
 

package/src/server/files.ts

@@ -8,11 +8,15 @@
  * One recursive watcher covers the working dir: editors and agents often
  * replace files rather than write them in place, and a frame may wait for a
  * file (or its directory) that does not exist yet.
+ *
+ * Scratch files (`canvas:scratch/…`, ADR 0005) are read and listed alongside;
+ * the watcher skips `.canvas/`, so `Scratch` reports its writes itself.
  */
 
 import { readFileSync, statSync, watch, type FSWatcher } from "node:fs";
 import { sep } from "node:path";
 import type { FileContent } from "../shared/protocol";
+import { isScratchPath, Scratch } from "./scratch";
 import { SharedSet } from "./shared-set";
 
 export const MAX_FILE_BYTES = 1024 * 1024;
@@ -35,11 +39,13 @@ export class Files {
     dir: string,
     private readonly onFile: (path: string, file: FileContent) => void,
     private readonly onTree: (paths: ReadonlyArray<string>) => void,
+    private readonly scratch: Scratch = new Scratch(dir),
   ) {
     this.shared = new SharedSet(dir);
   }
 
   read(path: string): FileContent {
+    if (isScratchPath(path)) return this.scratch.read(path);
     let absolute: string;
     try {
       absolute = this.shared.resolve(path);
@@ -83,6 +89,12 @@ export class Files {
     this.ensureWatcher();
   }
 
+  /** A scratch file was written: re-send it, and the tree if it is new. */
+  scratchChanged(path: string): void {
+    if (this.subscribers.has(path)) this.send(path);
+    if (this.treeWatched) this.sendTree();
+  }
+
   stop(): void {
     this.watcher?.close();
     if (this.timer) clearTimeout(this.timer);
@@ -97,7 +109,7 @@ export class Files {
   }
 
   private sendTree() {
-    const paths = this.shared.list();
+    const paths = [...this.shared.list(), ...this.scratch.list()];
     const key = paths.join("\0");
     if (key === this.lastTree) return;
     this.lastTree = key;

package/src/server/scratch.ts

@@ -0,0 +1,115 @@
+/**
+ * Scratch files (ADR 0005): content an agent writes for the board only —
+ * a write-up, an HTML visualisation — kept in `<dir>/.canvas/scratch/`, out
+ * of the project. Board paths name them `canvas:scratch/<name>`; they are
+ * read like the shared set's files and mirrored the same way.
+ *
+ * Only agents write them, through their board tools: nothing a browser
+ * sends reaches `create` or `write`. One flat namespace; a name is never
+ * taken twice, so creating one never overwrites another agent's file.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { SCRATCH_PREFIX } from "../shared/board-tools";
+import type { FileContent } from "../shared/protocol";
+
+export const MAX_SCRATCH_BYTES = 1024 * 1024;
+
+export const isScratchPath = (path: string) => path.startsWith(SCRATCH_PREFIX);
+
+/** A name as agents may give it: one plain segment, e.g. `auth-overview.md`. */
+const NAME = /^[\w][\w.-]*$/;
+
+export class Scratch {
+  private readonly dir: string;
+
+  constructor(
+    root: string,
+    /** A scratch file was written: `canvas:scratch/<name>`. */
+    private readonly onChange: (path: string) => void = () => {},
+  ) {
+    this.dir = join(root, ".canvas", "scratch");
+  }
+
+  /** A new file, under `name` or, if that is taken, `name-2`, `name-3`…; its path. */
+  create(name: string, text: string): string {
+    checkName(name);
+    checkSize(text);
+    const dot = name.lastIndexOf(".");
+    const [stem, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
+    let free = name;
+    for (let n = 2; existsSync(join(this.dir, free)); n++) free = `${stem}-${n}${ext}`;
+    mkdirSync(this.dir, { recursive: true });
+    writeFileSync(join(this.dir, free), text);
+    const path = SCRATCH_PREFIX + free;
+    this.onChange(path);
+    return path;
+  }
+
+  /** Overwrite an existing scratch file. */
+  write(path: string, text: string): void {
+    const name = this.name(path);
+    if (!existsSync(join(this.dir, name)))
+      throw new Error(`${path} doesn't exist; give a name to create it`);
+    checkSize(text);
+    writeFileSync(join(this.dir, name), text);
+    this.onChange(path);
+  }
+
+  /** Undo a `create` whose board call failed. */
+  remove(path: string): void {
+    rmSync(join(this.dir, this.name(path)), { force: true });
+    this.onChange(path);
+  }
+
+  read(path: string): FileContent {
+    let name: string;
+    try {
+      name = this.name(path);
+    } catch (error) {
+      return { kind: "denied", reason: (error as Error).message };
+    }
+    const file = join(this.dir, name);
+    const stat = statSync(file, { throwIfNoEntry: false });
+    if (!stat?.isFile()) return { kind: "missing" };
+    if (stat.size > MAX_SCRATCH_BYTES) return { kind: "too-large", size: stat.size };
+    return { kind: "text", text: readFileSync(file, "utf8") };
+  }
+
+  /** Every scratch file's path, sorted. */
+  list(): string[] {
+    if (!existsSync(this.dir)) return [];
+    return readdirSync(this.dir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && NAME.test(entry.name))
+      .map((entry) => SCRATCH_PREFIX + entry.name)
+      .sort();
+  }
+
+  private name(path: string): string {
+    if (!isScratchPath(path)) throw new Error(`not a scratch file: ${path}`);
+    const name = path.slice(SCRATCH_PREFIX.length);
+    checkName(name);
+    return name;
+  }
+}
+
+function checkName(name: string) {
+  if (!NAME.test(name) || name.length > 120)
+    throw new Error(
+      `scratch file names are one plain segment of letters, digits, '.', '_' and '-' (got ${JSON.stringify(name)})`,
+    );
+}
+
+function checkSize(text: string) {
+  if (Buffer.byteLength(text) > MAX_SCRATCH_BYTES)
+    throw new Error("scratch files are at most 1 MiB");
+}

package/src/server/server.ts

@@ -1,16 +1,19 @@
 /**
  * `canvas serve`: the local half of canvas. One WebSocket endpoint that only
- * the host's browser may use (it presents the token from the printed link).
+ * the host's browser may use (it presents the token from the printed link),
+ * in one tab at a time: a newer tab takes over from an older one.
  * Nothing here knows about guests — the host's browser is the relay.
  */
 
 import type { ServerWebSocket } from "bun";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { ClientToServer, ServerToClient } from "../shared/protocol";
+import { HOST_REPLACED, type ClientToServer, type ServerToClient } from "../shared/protocol";
 import { AgentManager, detectAgents } from "./agents";
 import { BoardMcp } from "./board-mcp";
 import { Files } from "./files";
+import { Scratch } from "./scratch";
+import { canvasSkills } from "./skills";
 import { Store } from "./store";
 import { Terminals } from "./terminals";
 
@@ -19,33 +22,37 @@ export interface ServeOptions {
   readonly port: number;
   readonly hostname: string;
   readonly tls?: { readonly cert: string; readonly key: string };
+  /** The published version this runs as; none for a checkout. */
+  readonly version?: string;
 }
 
 export async function serve(options: ServeOptions) {
   const store = new Store(options.dir);
   excludeFromGit(options.dir);
   const room = await store.room();
-  const clients = new Set<ServerWebSocket<unknown>>();
-  const broadcast = (message: ServerToClient) => {
-    const text = JSON.stringify(message);
-    for (const ws of clients) ws.send(text);
-  };
+  // The host tab: the board, and so every board tool call, lives there.
+  let host: ServerWebSocket<unknown> | null = null;
+  const broadcast = (message: ServerToClient) => host?.send(JSON.stringify(message));
 
+  // Scratch files are written by agents' board tools; `files` mirrors them.
+  const scratch = new Scratch(options.dir, (path) => files.scratchChanged(path));
   const files = new Files(
     options.dir,
     (path, file) => broadcast({ t: "file", path, file }),
     (paths) => broadcast({ t: "tree", paths }),
+    scratch,
   );
   process.on("exit", () => files.stop());
   // Board tools: an agent's call goes to one host browser (the board is there).
   const boardMcp = new BoardMcp({
     read: (path) => files.read(path),
+    scratch,
     relay: (call) => {
-      const [ws] = clients;
-      if (!ws) return false;
-      ws.send(JSON.stringify({ t: "board-call", ...call } satisfies ServerToClient));
+      if (!host) return false;
+      host.send(JSON.stringify({ t: "board-call", ...call } satisfies ServerToClient));
       return true;
     },
+    skills: canvasSkills(),
   });
   process.on("exit", () => boardMcp.stop());
 
@@ -143,12 +150,17 @@ export async function serve(options: ServeOptions) {
     websocket: {
       maxPayloadLength: 64 * 1024 * 1024,
       open(ws) {
-        clients.add(ws);
+        if (host) {
+          files.drop(host);
+          host.close(HOST_REPLACED, "opened in another tab");
+        }
+        host = ws;
         const board = store.board();
         const { token: _, ...secrets } = room;
         ws.send(
           JSON.stringify({
             t: "welcome",
+            version: options.version ?? null,
             room: secrets,
             cwd: options.dir,
             agents: agentDefinitions.map(({ kind, label }) => ({ kind, label })),
@@ -158,6 +170,8 @@ export async function serve(options: ServeOptions) {
         );
       },
       message(ws, data) {
+        // Still in flight from a tab that was just replaced.
+        if (ws !== host) return;
         try {
           handle(ws, JSON.parse(String(data)) as ClientToServer);
         } catch (error) {
@@ -165,7 +179,7 @@ export async function serve(options: ServeOptions) {
         }
       },
       close(ws) {
-        clients.delete(ws);
+        if (ws === host) host = null;
         files.drop(ws);
       },
     },

package/src/server/skills.ts

@@ -0,0 +1,32 @@
+/**
+ * The skills canvas gives every agent session, shipped in `skills/` beside
+ * `src/` (finding 12). The folder is a Claude Code plugin (its manifest points
+ * `skills` at itself) and an opencode skills path at once; `agents.ts` hands
+ * it to each agent, which lists the skills beside the host's own.
+ *
+ * Claude drops skill descriptions from its listing once the host has many
+ * skills, so the board priming names them too (`boardInstructions`).
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export const SKILLS_DIR = resolve(import.meta.dir, "../../skills");
+
+export interface Skill {
+  readonly name: string;
+  readonly description: string;
+}
+
+/** Every skill in `dir`, from its `SKILL.md` frontmatter. */
+export function canvasSkills(dir: string = SKILLS_DIR): ReadonlyArray<Skill> {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => {
+      const text = readFileSync(join(dir, entry.name, "SKILL.md"), "utf8");
+      const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? "";
+      const field = (key: string) => new RegExp(`^${key}: (.+)$`, "m").exec(frontmatter)?.[1];
+      return { name: field("name") ?? entry.name, description: field("description") ?? "" };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/server/terminals.ts

@@ -6,6 +6,17 @@
 
 const SCROLLBACK = 200_000;
 
+/**
+ * The shell must lead a session of its own, with the PTY as its controlling
+ * terminal, as in any terminal emulator. `Bun.spawn` leaves it in the session
+ * of `canvas serve` (Bun 1.4): Ctrl-C reaches nothing, and whatever opens
+ * `/dev/tty` — fzf's Ctrl-R, sudo, ssh prompts — gets the terminal `canvas
+ * serve` runs in, where it is stopped as a background job. util-linux
+ * `setsid -c` does both; where it is missing (macOS) the shell runs as before.
+ */
+const SETSID = Bun.which("setsid");
+const SESSION = SETSID ? [SETSID, "-c"] : [];
+
 interface Term {
   terminal: Bun.Terminal;
   scrollback: string;
@@ -19,6 +30,7 @@ export class Terminals {
     private readonly dir: string,
     private readonly onData: (id: string, data: string) => void,
     private readonly onExit: (id: string, code: number | null) => void,
+    private readonly shell = process.env.SHELL ?? "bash",
   ) {}
 
   /** Open (or re-attach to) a terminal; returns the scrollback to replay. */
@@ -42,8 +54,7 @@ export class Terminals {
       }),
     };
     this.terms.set(id, term);
-    const shell = process.env.SHELL ?? "bash";
-    const proc = Bun.spawn([shell, "-l"], {
+    const proc = Bun.spawn([...SESSION, this.shell, "-l"], {
       cwd: this.dir,
       terminal: term.terminal,
       env: { ...process.env, TERM: "xterm-256color" },

package/src/shared/board-tools.ts

@@ -11,9 +11,15 @@
 
 export const BOARD_TOOL_NAMES = [
   "view_board",
+  "view_frame",
   "open_frame",
   "update_frame",
   "close_frame",
+  "read_board_file",
+  "write_board_file",
+  "add_comment",
+  "edit_comment",
+  "delete_comment",
 ] as const;
 export type BoardToolName = (typeof BOARD_TOOL_NAMES)[number];
 
@@ -39,7 +45,25 @@ interface FileTarget {
   readonly end_line?: number;
 }
 
-export interface OpenFrameArgs extends Placement, FileTarget {
+/** A new scratch file to show (ADR 0005); `canvas serve` turns it into a `path`. */
+interface ScratchContent {
+  readonly name?: string;
+  readonly content?: string;
+}
+
+/** One entry of a file frame's list (ADR 0005): a file at a display path. */
+export interface FileListEntry extends ScratchContent {
+  readonly display: string;
+  readonly path?: string;
+  readonly start_line?: number;
+  readonly end_line?: number;
+}
+
+interface FileList {
+  readonly files?: ReadonlyArray<FileListEntry>;
+}
+
+export interface OpenFrameArgs extends Placement, FileTarget, ScratchContent, FileList {
   readonly type: FrameKind;
   readonly title?: string;
   readonly url?: string;
@@ -47,17 +71,55 @@ export interface OpenFrameArgs extends Placement, FileTarget {
   readonly draft?: string;
 }
 
-export interface UpdateFrameArgs extends Placement, FileTarget {
+export interface UpdateFrameArgs extends Placement, FileTarget, ScratchContent, FileList {
   readonly frame: string;
   readonly title?: string;
   readonly url?: string;
   readonly view?: "preview" | "source";
+  /** A comment's id: show its file at its lines. */
+  readonly comment?: string;
+}
+
+export interface ViewFrameArgs {
+  readonly frame: string;
+}
+
+export interface AddCommentArgs {
+  readonly frame: string;
+  readonly path: string;
+  readonly start_line: number;
+  readonly end_line?: number;
+  readonly body: string;
+  /** The lines' text, which `canvas serve` adds (ADR 0006). */
+  readonly quote?: string;
+}
+
+export interface EditCommentArgs {
+  readonly frame: string;
+  readonly comment: string;
+  readonly body: string;
+}
+
+export interface DeleteCommentArgs {
+  readonly frame: string;
+  readonly comment: string;
 }
 
 export interface CloseFrameArgs {
   readonly frame: string;
 }
 
+export interface ReadBoardFileArgs {
+  readonly path: string;
+}
+
+export interface WriteBoardFileArgs extends ScratchContent {
+  readonly path?: string;
+}
+
+/** Where scratch files live, as board paths name them. */
+export const SCRATCH_PREFIX = "canvas:scratch/";
+
 const placement = {
   next_to: {
     type: "string",
@@ -74,12 +136,60 @@ const placement = {
 const fileTarget = {
   path: {
     type: "string",
-    description: "File path relative to the project root, e.g. src/auth/session.ts.",
+    description:
+      "File path relative to the project root, e.g. src/auth/session.ts, or a scratch file: " +
+      "canvas:scratch/<name>.",
   },
   start_line: { type: "integer", minimum: 1, description: "First line to show and highlight." },
   end_line: { type: "integer", minimum: 1, description: "Last highlighted line (inclusive)." },
 };
 
+const scratchContent = {
+  content: {
+    type: "string",
+    description:
+      "Instead of path: the text of a new scratch file to show — content for this board only, " +
+      "like a write-up or an HTML visualisation. canvas keeps it outside the project.",
+  },
+  name: {
+    type: "string",
+    description:
+      "With content: the scratch file's name, e.g. auth-overview.md; its extension decides how " +
+      "it shows. A taken name gets a suffix; the result says which path you got.",
+  },
+};
+
+const fileList = {
+  files: {
+    type: "array",
+    description:
+      "file: a list of files for the frame's tree, for people to click through at their pace — " +
+      "e.g. the files of one feature, with a write-up first. Each entry is a project file or a " +
+      "scratch file at a display path you choose: make folders, rename, order it (a folder sorts " +
+      "where its first entry is; no folders for a flat list). The frame shows path, else the " +
+      "first entry. update_frame replaces the list; [] removes it.",
+    items: {
+      type: "object",
+      properties: {
+        display: {
+          type: "string",
+          description:
+            'Where it shows in the tree, e.g. "1 Overview.md" or "Auth/session.ts". Unique.',
+        },
+        path: { type: "string", description: "A project file or canvas:scratch/<name>." },
+        ...scratchContent,
+        start_line: {
+          type: "integer",
+          minimum: 1,
+          description: "Lines to open it at, shown as a badge.",
+        },
+        end_line: { type: "integer", minimum: 1 },
+      },
+      required: ["display"],
+    },
+  },
+};
+
 export const BOARD_TOOLS: ReadonlyArray<{
   readonly name: BoardToolName;
   readonly description: string;
@@ -101,11 +211,25 @@ export const BOARD_TOOLS: ReadonlyArray<{
       },
     },
   },
+  {
+    name: "view_frame",
+    description:
+      "Look at one frame in full. For a file frame: what it shows, its list of files, and its " +
+      "comments — people's and agents' notes on lines of its files, with ids, authors and lines. " +
+      "view_board says which frames have comments.",
+    inputSchema: {
+      type: "object",
+      properties: { frame: { type: "string", description: "Id of the frame." } },
+      required: ["frame"],
+    },
+  },
   {
     name: "open_frame",
     description:
       "Open a new frame on the board, in your own cluster unless placed next to another frame. " +
-      "file: a project file (read-only, live), optionally at a line range which gets highlighted. " +
+      "file: a project file (read-only, live), optionally at a line range which gets highlighted, " +
+      "or a scratch file: content you pass, kept by canvas outside the project. A file frame can " +
+      "also carry a list of files (files): one frame to click through, instead of many. " +
       "browser: a URL, loaded by each viewer's own browser. terminal: an idle shell people can " +
       "type into. agent: another agent session; `draft` pre-fills its prompt, a person sends it.",
     inputSchema: {
@@ -113,6 +237,8 @@ export const BOARD_TOOLS: ReadonlyArray<{
       properties: {
         type: { type: "string", enum: ["file", "browser", "terminal", "agent"] },
         ...fileTarget,
+        ...scratchContent,
+        ...fileList,
         url: { type: "string", description: "browser: an http(s) URL." },
         agent: { type: "string", description: "agent: which agent runs it (see view_board)." },
         draft: { type: "string", description: "agent: a prompt draft for people to send." },
@@ -125,7 +251,8 @@ export const BOARD_TOOLS: ReadonlyArray<{
   {
     name: "update_frame",
     description:
-      "Change a frame: point a file frame at another file or line range, switch a markdown " +
+      "Change a frame: point a file frame at another file, line range or new scratch file " +
+      "(content), give it a list of files or replace it (files), switch a markdown " +
       "or HTML file between preview and source, change a browser frame's URL, rename a frame, or move " +
       "it next to another frame.",
     inputSchema: {
@@ -133,7 +260,13 @@ export const BOARD_TOOLS: ReadonlyArray<{
       properties: {
         frame: { type: "string", description: "Id of the frame to change." },
         ...fileTarget,
+        ...scratchContent,
+        ...fileList,
         view: { type: "string", enum: ["preview", "source"] },
+        comment: {
+          type: "string",
+          description: "file: a comment's id (view_frame) — show its file at its lines.",
+        },
         url: { type: "string" },
         title: { type: "string" },
         ...placement,
@@ -151,15 +284,90 @@ export const BOARD_TOOLS: ReadonlyArray<{
       required: ["frame"],
     },
   },
+  {
+    name: "read_board_file",
+    description:
+      "Read a scratch file (canvas:scratch/<name>), e.g. one another agent wrote. view_board " +
+      "lists them.",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string", description: "canvas:scratch/<name>" } },
+      required: ["path"],
+    },
+  },
+  {
+    name: "write_board_file",
+    description:
+      "Write a scratch file without opening a frame. With name: a new one. With path: overwrite " +
+      "an existing one (any agent's); every frame showing it updates. Show a new one with " +
+      "open_frame (path).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "canvas:scratch/<name> to overwrite." },
+        name: scratchContent.name,
+        content: { type: "string", description: "The file's full text." },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "add_comment",
+    description:
+      "Comment on lines of a file, in a file frame: it shows below the lines for everyone, " +
+      "whatever file the frame shows. Markdown. The frame keeps it; people read it there.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        path: {
+          type: "string",
+          description: "The file, relative to the project root, or canvas:scratch/<name>.",
+        },
+        start_line: { type: "integer", minimum: 1 },
+        end_line: { type: "integer", minimum: 1, description: "Default: start_line." },
+        body: { type: "string", description: "The comment, markdown." },
+      },
+      required: ["frame", "path", "start_line", "body"],
+    },
+  },
+  {
+    name: "edit_comment",
+    description: "Rewrite a comment's text. Only agents' comments: people's are theirs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        comment: { type: "string", description: "The comment's id (view_frame)." },
+        body: { type: "string", description: "The new text, markdown." },
+      },
+      required: ["frame", "comment", "body"],
+    },
+  },
+  {
+    name: "delete_comment",
+    description: "Remove a comment. Only agents' comments: people's are theirs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        comment: { type: "string", description: "The comment's id (view_frame)." },
+      },
+      required: ["frame", "comment"],
+    },
+  },
 ];
 
 /** The agent's standing context, sent as MCP server instructions. */
-export function boardInstructions(frameId: string): string {
+export function boardInstructions(
+  frameId: string,
+  skills: ReadonlyArray<{ readonly name: string; readonly description: string }> = [],
+): string {
   return `You are running inside canvas: a shared, multiplayer board that people are looking at together, live. Its frames are coding-agent sessions, files of this project, browser previews and terminals. You are the agent in frame ${frameId}; people write prompts into it and read your replies there. Several people may prompt you.
 
 Frames that sit close together form a cluster: people keep related work together that way, and your own cluster is your workspace. Within a cluster frames sit in rows; frames in a row share a height.
 
-The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NAMES.join(", ")}. Use them when showing something on the board helps the people you work with — e.g. asked to show the files relevant to a topic, open them as file frames at the relevant lines instead of pasting code. Don't use them when a plain answer is enough.
+The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NAMES.join(", ")}. Use them when showing something on the board helps the people you work with — e.g. asked to show the files relevant to a topic, show them on the board (one file, or a list of them) at the relevant lines instead of pasting code. Don't use them when a plain answer is enough.
 
 - Look first (view_board). Reuse or retarget a frame (update_frame) rather than open a duplicate.
 - New frames go into your cluster by default; that is almost always right. Keep it to a handful per request.
@@ -168,5 +376,24 @@ The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NA
 - A terminal frame is an idle shell for people; you cannot type into it. Run commands with your own tools.
 - An agent frame starts another agent. You can leave a draft prompt in it; only a person can send it.
 - A browser frame loads its URL in each viewer's own browser, so localhost means their machine, not this one: only the host sees a localhost URL, guests get a notice.
-- To show a page you wrote to everyone, open the HTML file as a file frame: it renders, scripts included, but relative links and assets (CSS, images, other scripts) don't load, so inline them.`;
+- Scratch files hold what exists only to be shown on this board: a write-up, a diagram, an HTML visualisation. Pass the text as \`content\` (with a \`name\`) to open_frame or update_frame, or use write_board_file; canvas keeps them outside the project, as canvas:scratch/<name>. Don't write such files into the project for the board. Anything else — a temp file for your own work, a script, test data — goes wherever it would without canvas.
+- Any agent may read (read_board_file) and overwrite (write_board_file) any scratch file; view_board lists them.
+- To show several files for one topic, prefer one file frame with a list (files) over a frame per file: people click through it at their own pace. You decide the tree: display paths, folders, order, line ranges. A write-up (a scratch file) at the top and a visualisation at the bottom fit in the same list.
+- People (and agents) comment on lines of files in a file frame. view_board says which frames have comments; view_frame lists them, with ids. You aren't told when someone comments: look when asked to, e.g. to address feedback. add_comment leaves one of yours; edit_comment and delete_comment change agents' comments, never people's. update_frame with a comment's id shows its file at its lines. A comment is "outdated" when its lines changed since; it shows what they were.
+- Markdown and HTML files render. HTML runs its scripts, but relative assets (CSS, images, other scripts) don't load, so inline them. Links do work (see below).
+
+Your replies, comments, markdown and HTML can link to places on the board with ordinary markdown links (or <a href> in HTML). A click takes that person there, opening a file frame if no frame shows the file:
+- A file, from the project root: [session.ts](src/auth/session.ts); lines of it: [session.ts:42-60](src/auth/session.ts#L42-L60); a markdown heading: [Setup](docs/guide.md#setup); a scratch file: [overview](canvas:scratch/overview.md). \`path:line\` in inline code becomes a link too, if the file exists.
+- A frame, by its id from view_board: [the review](#frame=<id>); a file or lines in it: #frame=<id>&path=src/a.ts&lines=10-20; a comment: #frame=<id>&comment=<comment id>.
+- In a markdown or HTML file, relative paths are from that file. HTML pages can link each other: a link to another HTML file opens in the same frame, so several scratch pages make a small site.
+Link to what you talk about when it's on the board or in the project; don't link to everything.${skillsSection(skills)}`;
+}
+
+/** canvas's own skills: the agent lists them, but may have dropped their descriptions. */
+function skillsSection(
+  skills: ReadonlyArray<{ readonly name: string; readonly description: string }>,
+): string {
+  if (skills.length === 0) return "";
+  const list = skills.map((skill) => `- ${skill.name}: ${skill.description}`).join("\n");
+  return `\n\ncanvas also gives you skills for work on the board. When one fits the request, load it with your skill tool before you start:\n${list}`;
 }

package/src/shared/comments.ts

@@ -0,0 +1,48 @@
+/**
+ * Comments on the lines of a file (ADR 0006). A comment keeps the lines it
+ * was written on as text, its quote: files change under it — agents edit them
+ * live — and the quote is how it finds its lines again, or knows it can't.
+ * Pure, so `canvas serve` (which quotes agents' comments) and the browser
+ * agree on what a line is.
+ */
+
+/** A file's lines as the frames number them: a final newline ends the last line. */
+export function linesOf(text: string): string[] {
+  const lines = text.split("\n");
+  if (lines.length > 1 && lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+/** Lines `start`–`end` (1-based, inclusive) of `text`; null if the file hasn't got them. */
+export function quoteOf(text: string, start: number, end: number): string | null {
+  const lines = linesOf(text);
+  if (start < 1 || end < start || end > lines.length) return null;
+  return lines.slice(start - 1, end).join("\n");
+}
+
+/**
+ * Where a quote is now: its old place if the lines there still read the same,
+ * else the nearest place they do. null if they're gone — the comment is
+ * outdated. A quote of blank lines only stays where it was: blank lines are
+ * everywhere, finding "them" elsewhere would be a guess.
+ */
+export function relocate(
+  text: string,
+  quote: string,
+  start: number,
+): { start: number; end: number } | null {
+  const lines = linesOf(text);
+  const wanted = quote.split("\n");
+  const at = (s: number) => wanted.every((line, i) => lines[s - 1 + i] === line);
+  const found = (s: number) => ({ start: s, end: s + wanted.length - 1 });
+  const last = lines.length - wanted.length + 1;
+  if (start >= 1 && start <= last && at(start)) return found(start);
+  if (!quote.trim()) return null;
+  for (let distance = 1; distance < Math.max(start, last); distance++) {
+    if (start - distance >= 1 && start - distance <= last && at(start - distance))
+      return found(start - distance);
+    if (start + distance >= 1 && start + distance <= last && at(start + distance))
+      return found(start + distance);
+  }
+  return null;
+}

package/src/shared/protocol.ts

@@ -157,6 +157,13 @@ export interface RoomSecrets {
   readonly hostPrivateKey: JsonWebKey;
 }
 
+/**
+ * Close code of a host browser's WebSocket when another one connected: one
+ * host tab at a time, and the replaced one must not reconnect by itself, or
+ * two tabs would take the connection from each other forever.
+ */
+export const HOST_REPLACED = 4001;
+
 export type ClientToServer =
   | { readonly t: "board-save"; readonly state: string }
   | { readonly t: "agent-create"; readonly id: string; readonly agent: AgentKind }
@@ -204,6 +211,8 @@ export type ClientToServer =
 export type ServerToClient =
   | {
       readonly t: "welcome";
+      /** The version `canvas serve` runs as; null for a checkout. */
+      readonly version: string | null;
       readonly room: RoomSecrets;
       readonly cwd: string;
       readonly agents: ReadonlyArray<AgentInfo>;
@@ -251,6 +260,8 @@ export interface RoomState {
   readonly access: GuestAccess;
   readonly cwd: string;
   readonly agents: ReadonlyArray<AgentInfo>;
+  /** `canvas serve`'s version, null for a checkout; absent from hosts older than it. */
+  readonly version?: string | null;
 }
 
 /** Requests a guest sends the host; the host answers `{ok}` or `{ok:false, error}`. */