@surph_ai/cli 0.0.28 → 0.0.32

package/cli.js

@@ -293,6 +293,10 @@ program.command('tool <name>')
 .description('create new Surph tool')
 .action(name => scaffold(name, 'tool'))
 
+program.command('board <name>')
+.description('create new Surph board')
+.action(name => scaffold(name, 'board'))
+
 program.command('manifest')
 .description('update manifest for Surph tool')
 .action(async (cmd, options) => {
@@ -537,7 +541,6 @@ program.command('publish')
   }
 })
 
-
 program.command('deploy')
 .description('Deploy to Surph')
 .action(async (cmd, options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surph_ai/cli",
-  "version": "0.0.28",
+  "version": "0.0.32",
   "description": "",
   "main": "index.js",
   "types": "./types.d.ts",

package/scaffold/board/README.md

@@ -0,0 +1,422 @@
+# Surph board
+
+This project is a **Surph board**: a set of web pages that Surph shows in its **canvas**, the panel beside the Surph chat. Each page is a static HTML file. Surph loads it in an iframe and answers the page's requests for data. The page talks to Surph only through the Surph SDK (`surph-wave.js`), which works over `postMessage`.
+
+**If you're a coding agent, read this whole file before writing a page.** Surph answers only the operations listed in [Operations the host answers](#operations-the-host-answers), with exactly the payloads shown. A page that calls anything else gets an error, and a field not listed here doesn't exist.
+
+## How a page runs in Surph
+
+- **Surph is the host; the page is the guest.** Surph frames the page and answers its `host.rpc(op, args)` calls with data it already has: the board's recent items, the chat's context, the items the chat looked up, the signed-in person's contexts. The page never calls Surph's servers itself, and it can't read Surph's cookies, session or DOM.
+- **The chat decides which page to show.** Every page is registered with a `shows` line: plain facts about what it displays. The chat's model reads the board's pages and their `shows` lines and opens the page that fits what the person asked. A person can also pick a page from the canvas's Pages menu.
+- **The chat can hand a page values.** A page can declare address parameters (for example `?ids=`). The chat's model sees them and opens the page at an address that carries them; the page reads them from `location.search`.
+- **Pages update as the chat goes.** When the data behind an operation changes (the chat looked up new items, the person subscribed to a context), Surph calls the page's `onRefresh`, and the page asks again and repaints.
+- **A board's pages replace Surph's own.** A chat on your board shows only your board's pages. One of them is the **start page** the canvas opens on.
+- **Opened directly, a page still loads.** Outside Surph, `host.hosted` is `false` and every call rejects. The page must still render its empty layout without errors. That's what you see when you run this project locally.
+
+## Project layout
+
+```
+index.html            The board's home page (edit it; it starts as an intro to this setup)
+<page>.html           Each further page sits next to it (items.html, events.html, …)
+assets/
+  css/site.css        Styles shared by every page in the board
+  js/                 Scripts shared by the board's pages (optional)
+board.json            The board itself: name, contexts, instructions, and its pages (see "Registering pages")
+package.json          `npm run dev` serves this folder at http://localhost:4180
+README.md             This file
+```
+
+- **Pages sit at the top of the folder.** A page's registry entry names its file without a folder, so a page can't live in a subfolder.
+- **Everything else a page loads, apart from the SDK, goes under `assets/`**, linked with relative paths (`assets/css/site.css`, `./items.html`).
+
+### Shared styles: `assets/css/site.css`
+
+Every page links it in `<head>`, before its own `<style>`:
+
+```html
+<link rel="stylesheet" href="assets/css/site.css?v=1">
+```
+
+- It holds the colour variables (`--ink`, `--muted`, `--faint`, `--subtle`, `--accent`, `--rule`, `--tint`, …), the page shell (body, `h1`, `h2`, `p.empty`) and a few shared pieces (a context list `ul.contexts` of `.context` rows with an `.icon`, and an owner pill `button.owner`). Use the variables in page styles rather than repeating colours.
+- A page's own `<style>` holds only what that page alone uses.
+- **A change to `site.css` changes every page.** Check each page that uses what you changed.
+- **Bump `?v=` in every page's link** whenever `site.css` changes, so browsers don't keep serving the old copy.
+
+## Registering pages
+
+Surph only shows pages that are registered with the board. The board itself is described by **`board.json`** in this folder, shaped like the board's record in Surph; its pages are `config.pages`, one entry per page. Keep it in step with the pages, because it's what Surph reads:
+- **While you develop**, Surph's dev mode runs as the board this file describes, read from your local server (see [Developing locally](#developing-locally)). No live board is needed.
+- **When the board goes live**, Surph sets up the board's record from this same file; today Surph does that step, so your hand-off includes `board.json`.
+
+```json
+{
+  "slug": "my-board",
+  "name": "My Board",
+  "description": "What the board is about.",
+  "logo": "logo.png",
+  "contexts": ["<context slug>"],
+  "defaultContext": "<context slug>",
+  "waves": [],
+  "tools": [],
+  "config": {
+    "instructions": "How the board's chat should behave: its tone, what it helps with.",
+    "pages": [
+      { "name": "home", "file": "index.html", "shows": "…", "start": "always", "ops": ["board.get"] }
+    ]
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `slug` | The board's short id. |
+| `name` | The board's name, shown in Surph's header and returned by `board.get`. |
+| `description` | One line about the board. |
+| `logo` | An image file in `assets/` (just its name, e.g. `logo.png`), shown in Surph's header. |
+| `contexts` | Slugs of the Surph contexts the board draws on. Their items are what `board.get` and the chat's lookups return. They're live Surph contexts; find a context's slug in its address (`/c/<slug>`). |
+| `defaultContext` | The context the chat starts with; else the first in `contexts`. |
+| `waves`, `tools` | Slugs of Surph waves and tools on the board. Optional. |
+| `config.instructions` | Instructions from the board's owner for the board's chat: tone, behavior, what it helps with. On a board they take the place of each context's own instructions. |
+| `config.pages` | The board's pages, one registry entry each (below). |
+
+A registry entry:
+
+```json
+{
+  "name": "events",
+  "file": "events.html",
+  "shows": "Upcoming events from the board's contexts: each event's name, date, place, and a link to its source.",
+  "ops": ["board.get"]
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Short, stable label. The chat's model and saved conversations refer to the page by this name, and the canvas header shows it, so don't rename it casually. Unique within the board. |
+| `file` | The HTML file's name only, with no folder (`events.html`). It's found next to `board.json`: on your local server while you develop, and wherever the board's files are hosted when it's live. |
+| `url` | Instead of `file`, a page's full `https://` address when it lives somewhere else. |
+| `shows` | What the page displays, as plain facts. The chat's model reads this to judge when the page fits. Describe the content, not instructions: write "Every item in the board's newest 25, …", not "Use this when the user asks about…". |
+| `start` | Optional. Marks a page the canvas opens on before the chat starts: `"always"`, `"context"` (a chat that has a context) or `"no-context"` (a chat without one). A board needs at least one. A start page may route on load to another page with [`page.open`](#pageopen) and `replace: true`. |
+| `ops` | The operations the page calls. It must match the `host.rpc(…)` calls in the file. Surph finds pages by op; for example, the page that calls `items.get` is used to show the items a chat looked up. |
+| `params` | Optional. Address parameters the page reads, as `{ "<name>": "<what it is>" }`. The chat's model sees them and can open the page with them. |
+
+## The SDK
+
+Every page loads the SDK from this exact URL. Don't copy, bundle, edit or replace it.
+
+```html
+<script src="https://surph.s3.us-east-1.amazonaws.com/admin/desktop/js/wave-sdk/v1/surph-wave.js"></script>
+```
+
+It defines one global, `SurphWave`:
+
+```js
+const host = SurphWave.connect({
+  pageSlug: 'events',                    // The page's own name (any short string)
+  onRefresh: function () { paint(); }    // Surph's data changed: ask again and repaint
+});
+
+host.ready();                       // Call once, after connect
+host.rpc(op, args, { timeout });    // Ask Surph for something; returns a Promise
+host.hosted;                        // true inside the Surph canvas, false when opened directly
+```
+
+- `rpc(op, args, extra)` sends `args` as an object (use `{}` when there are none). It resolves with the operation's result object.
+- It rejects with:
+  - `Error('host timeout')`: no reply in time. The default wait is 15 seconds; pass `{ timeout: 800 }` on reads.
+  - `Error('not in a Surph host')`: the page isn't inside the canvas (`hosted` is false).
+  - `Error('<message>')`: Surph answered with an error, for example `Unknown op: …` for an operation it doesn't support.
+- Only use `connect`, `ready`, `rpc`, `hosted` and the `onRefresh` option. The script has other options; they belong to other hosts and do nothing here.
+
+## Call pattern
+
+Every page that reads data uses this loop. Keep its rules:
+- a **timeout** means Surph is still loading, so ask again shortly;
+- any **other error** means stop;
+- paint only after a successful reply.
+
+```js
+const host = SurphWave.connect({
+  pageSlug: 'events',
+  onRefresh: function () { paint(); }
+});
+
+let painting = false;
+async function paint() {
+  if (painting) return;
+  painting = true;
+  let got;
+  try {
+    got = await host.rpc('board.get', {}, { timeout: 800 });
+  } catch (e) {
+    painting = false;
+    if (e && e.message === 'host timeout' && host.hosted) setTimeout(paint, 200);
+    return;
+  }
+  painting = false;
+  // got is the operation's result. Paint it here (see "Rules for pages").
+}
+
+host.ready();
+paint();
+```
+
+Surph holds a read until its data is ready rather than answering with an error, so a short timeout plus a retry is expected while it loads. Don't clear the page before a reply arrives: if a refresh fails, the page keeps what it last painted.
+
+## Operations the host answers
+
+These are the only operations Surph answers. Every field below is exactly what arrives; treat anything not listed as absent.
+
+### `board.get`
+
+No args. Resolves once the board's recent items have loaded.
+
+```js
+{
+  name: "University of Maryland",
+  items: [ /* Item, … */ ]
+}
+```
+
+- `name`: the board's name; `""` when the chat isn't on a board.
+- `items`: the 25 newest visible items across every context on the board, newest first (by `createdAt`, else `updatedAt`), each an [Item](#item). `[]` when there are none.
+
+### `items.get`
+
+The items the chat has looked up. Two forms:
+
+- **No args (`{}`).** Resolves once the chat has looked items up; until then the call is held. The items are the chat's current list, which changes as the conversation goes on; when it does, Surph sends `onRefresh`. A lookup sets the list to what it returned; when the chat's reply finishes, the list becomes the items the reply cited, in citation order, if it cited any.
+- **`{ ids: ['<id>', …] }`.** Resolves at once with exactly those items, in that order (at most 50); never held. Ids that aren't made of letters, digits, `_` or `-` are dropped, and an id with no visible item is left out.
+
+```js
+{
+  title: "",
+  description: "",
+  items: [ /* Item, … */ ]
+}
+```
+
+- `title` and `description` are strings, currently always `""`. Hide them when they're empty.
+- `items`: the chat's current items (or the requested `ids`), each an [Item](#item), in that list's order.
+
+A page that takes `?ids=a,b,c` passes them on, and its registry entry declares the parameter so the chat's model can open it with a chosen set:
+
+```js
+const raw = new URLSearchParams(location.search).get('ids') || '';
+const ids = raw.split(',').map(function (id) { return id.trim(); }).filter(Boolean);
+got = await host.rpc('items.get', ids.length ? { ids: ids } : {}, { timeout: 800 });
+```
+
+```json
+"params": { "ids": "Comma-separated item ids (the <id> of [[ref:<id>]]). The page shows exactly those items, in that order." }
+```
+
+### `context.get`
+
+The chat's context. No args. Resolves once the chat has one.
+
+```js
+{
+  slug: "university-of-maryland-ufiz9v9e",
+  name: "University of Maryland",
+  topics: [
+    { name: "Events", description: "What's happening on campus." }
+  ],
+  subscribed: false,
+  isCreator: false
+}
+```
+
+- `topics` only includes topics that have a name. `description` is `""` when a topic has none.
+- `subscribed`: `true` when the signed-in person subscribes to the context. When that changes, Surph sends `onRefresh`.
+- `isCreator`: `true` when the signed-in person created the context. It's `false` until Surph has loaded the context's record; Surph sends `onRefresh` when it changes.
+
+### `context.subscribe`
+
+Subscribes the signed-in person to the chat's context. `{ subscribed: false }` unsubscribes.
+
+```js
+await host.rpc('context.subscribe', { subscribed: true });
+// resolves { subscribed: true }
+```
+
+- Resolves with the new state once Surph has saved it.
+- Rejects with `The chat has no context`, `Sign in to subscribe` (no signed-in person), or `Could not subscribe` / `Could not unsubscribe` (the save failed and nothing changed). Keep the old state on a rejection.
+- Call it only from the person's own click, and disable the button while the call is out so a double click doesn't toggle twice.
+
+### `contexts.get`
+
+The contexts the signed-in person subscribes to. No args. Resolves at once; never held.
+
+```js
+{
+  contexts: [
+    {
+      slug: "recommendations-w1ey7i96",
+      name: "Recommendations",
+      description: "Tracks personal recommendations for products, food, …",
+      icon: "https://…/recommendations-icon.png",
+      creator: { username: "dev_kinney5521", avatar: "https://…" },
+      canEdit: true
+    }
+  ]
+}
+```
+
+- `contexts`: `[]` when the person has none or isn't signed in.
+- `name`: the context's name, else its slug. `description`: `""` when there is none.
+- `icon`: the full URL of the context's icon. Omitted when it has none.
+- `creator`: the context's owner, `{ username, avatar? }`. `avatar` is omitted when there is none; `creator` is omitted when the owner isn't known. Avatars may come from another site, so set `referrerPolicy = 'no-referrer'` on the `<img>`.
+- `canEdit`: `true` when the signed-in person created the context or collaborates on it. Show an edit control only when it's `true`.
+- When the list changes, Surph sends `onRefresh`.
+
+### `contexts.public`
+
+Every public context on Surph (at most 100). No args. Surph fetches the list the first time a page asks and the call waits for it, so pass a longer timeout than 800ms (for example `{ timeout: 5000 }`).
+
+```js
+{ contexts: [ /* same shape as contexts.get */ ] }
+```
+
+- `contexts`: `[]` when there are none or the list couldn't be fetched; the next call fetches again.
+
+### `profile.get`
+
+On a person's profile in Surph: that profile and the contexts it created. No args. Held until a profile is open and its contexts have loaded.
+
+```js
+{
+  username: "dev_kinney5521",
+  contexts: [ /* same shape as contexts.get */ ]
+}
+```
+
+### `context.open`
+
+Starts a chat with a context and moves the canvas to the page that calls `context.get`.
+
+```js
+await host.rpc('context.open', { slug: 'recommendations-w1ey7i96' });
+// resolves { ok: true }
+```
+
+- `slug` is required: a `slug` from `contexts.get`, `contexts.public` or `profile.get`. A missing one rejects with `slug is required`.
+- The calling page is replaced, so don't count on running code after the call.
+
+### `context.edit`
+
+Opens a context in Surph's context builder (the whole app moves there).
+
+```js
+await host.rpc('context.edit', { slug: 'recommendations-w1ey7i96' });
+// resolves { ok: true }
+```
+
+- `slug` is required, from a context whose `canEdit` is `true`. Surph rejects any other with `You can't edit this context`.
+
+### `profile.open`
+
+Takes the person to someone's profile in Surph (the whole app moves there).
+
+```js
+await host.rpc('profile.open', { username: 'dev_kinney5521' });
+// resolves { ok: true }
+```
+
+- `username` is required, for example a context's `creator.username`. A missing or malformed one rejects with `username is required`.
+
+### `page.open`
+
+Moves the canvas to another page of this board, by its registry `name`.
+
+```js
+await host.rpc('page.open', { name: 'events', replace: true });
+// resolves { ok: true }
+```
+
+- `name` is required. A name the board doesn't have rejects with `Unknown page: <name>`; catch it and paint the calling page instead.
+- The new page loads as if picked from the Pages menu: the header shows its name, the chat is told it's showing, and the conversation remembers it.
+- `replace: true` puts the new page in the calling page's place, so Back skips the caller. Use it when a start page routes on load (otherwise Back returns to the start page, which routes again). Replacing a page with itself does nothing.
+- The calling page is unloaded, so don't count on running code after the call.
+
+### `chat.say`
+
+Puts one short line into the chat, for a greeting or a short note. The page is what the canvas shows, so don't use this to repeat page content.
+
+```js
+await host.rpc('chat.say', { text: 'Welcome to the board.' });
+// resolves { ok: true }
+```
+
+- `text` is required. Surph trims it and keeps the first 500 characters. An empty `text` rejects with `text is required`.
+
+### Item
+
+`board.get` and `items.get` return items in this one shape: a chosen set of public fields, not the stored record.
+
+```js
+{
+  id: "item_mvbf9necbickh1",
+  title: "Black Beans (30 oz, 6-Pack)",
+  preview: "My go-to pantry staple — great for tacos, salads, soups…",
+  content: "My go-to pantry staple — great for tacos, salads, soups, and batch cooking. …",
+  source: { type: "url", url: "https://www.amazon.com/dp/B00GXHTZCI" },
+  context: { slug: "recommendations-w1ey7i96", name: "Recommendations" },
+  topic: { id: "topic_mva2c2v8b698k4", name: "Food" },
+  addedBy: { username: "dev_kinney5521", avatar: "https://…" },
+  media: [{ type: "image", url: "https://…" }],
+  tags: ["pantry"],
+  createdAt: "2026-10-16T20:30:35.087Z",
+  updatedAt: "2026-10-19T15:24:42.587Z"
+}
+```
+
+| Field | |
+| --- | --- |
+| `id` | The item's id (a string). |
+| `title` | The item's title, else its URL, else `"Untitled"`. |
+| `preview` | A short summary. `""` when the item has none. |
+| `content` | The item's full text (it may contain line breaks and Markdown). `""` when it has none. A list page shortens it itself. |
+| `source` | `{ type }` (`"url"` or `"text"`), plus `url` when the item came from an address. Omitted when unknown. |
+| `context` | `{ slug, name }` of the context the item belongs to. Omitted when unknown. |
+| `topic` | `{ id, name }` of the item's topic. Omitted when it has none. |
+| `addedBy` | `{ username, avatar? }` of the person who added it. Omitted when unknown. |
+| `media` | `[{ type, url }]`. `[]` when there is none. |
+| `tags` | Strings. `[]` when there are none. |
+| `createdAt` | When it was added, ISO 8601. Omitted when unknown. |
+| `updatedAt` | When it was last changed, ISO 8601. Omitted when unknown. |
+
+A field marked "omitted" is missing from the object, not `null`. Every URL is `http` or `https`.
+
+## Rules for pages
+
+- **Write data with `textContent`, never `innerHTML`.** Every string from Surph comes from what people submitted. Build elements with `document.createElement` and set `textContent`. Set `href` and `src` only to values that start with `http://` or `https://`.
+- **Data comes through the operations above.** Don't try to reach Surph's servers, cookies or session; a page can't, and it doesn't need to.
+- **Change the app only through operations, and only when the person asked.** `context.subscribe`, `context.open`, `context.edit`, `profile.open`, `page.open` and `chat.say` act for the signed-in person. Call them from that person's own click, except a start page routing on load with `page.open`.
+- **Work when not hosted.** Opened directly, `host.hosted` is false and every `rpc` rejects. The page renders its empty layout without errors and stops retrying, which the call pattern already does.
+- **One `ready()` per page load**, called after `connect`.
+- **Don't invent operations or fields.** If a page needs data the operations above don't provide, say so in your hand-off; a new operation needs a change in Surph first.
+- **Keep the registry in step.** A page added, renamed or removed, or with changed `rpc` calls, needs its registry entry in your hand-off.
+- **Plain, static files.** No build step is needed or expected. Scripts can live inline or under `assets/js/`; keep the SDK `<script>` tag as given.
+
+## Developing locally
+
+1. Install once with `npm install`, then run `npm run dev`. It starts the board dev server from `@surph_ai/sdk` (`surph-board-dev`), which serves this folder at `http://localhost:4180` with caching off, lets Surph read it from another address, and lets Surph's Local board panel save `board.json`. It only listens on your own machine.
+2. Keep it running while you work; the terminal shows a line each time Surph saves `board.json`.
+3. Open `http://localhost:4180/` to check a page loads without console errors. It shows its empty layout there (`hosted` is false); real data only appears inside the Surph canvas.
+4. **Run Surph as your board with dev mode.** Keep `npm run dev` running. In Surph, open **Settings → Developer**, turn on **Run Surph as a local board**, and keep the address `http://localhost:4180`. Surph reloads as the board `board.json` describes: its name and logo in the header, its contexts and instructions in the chat, and its pages in the canvas (it opens on your start page, the Pages menu lists your pages, and the chat's model sees their `shows` lines). The status under the address says what loaded, or why it couldn't read `board.json`; until it loads, Surph runs as usual. A **DEV** label in the canvas header shows your board is loaded. While it's on, anything the chat saves goes to your own space in Surph, not to a board's shared space.
+5. **Configure the board from Surph.** Click the **DEV** label to open the **Local board** panel: set the board's name, slug, description and logo (an image in `assets/`), pick its contexts (yours, or public ones by search) and which one the chat starts with, pick its tools, and write its instructions. The panel also lists the pages and flags a missing `shows` line or an operation the host doesn't answer. **Save and reload** writes `board.json` through the dev server and reloads Surph as the updated board. Pages and any other fields (such as `waves`) are kept as they are in the file; edit pages in `board.json` itself.
+6. Dev mode affects only your browser. Turn it off in the same place to get Surph's own pages back.
+7. In Surph, keep your browser's DevTools open with **Network → Disable cache** checked, or the canvas may keep showing an older copy of a page after you change it. After editing `board.json` by hand, reload Surph so it reads the file again.
+
+## Checklist before handing off a change
+
+- [ ] Every `host.rpc(…)` call uses an operation from [Operations the host answers](#operations-the-host-answers) and reads only the fields listed for it and for [Item](#item).
+- [ ] Reads use the call pattern: a timeout retries, other errors stop, nothing is cleared before a reply.
+- [ ] Data from Surph is written with `textContent`; links and images use only `http(s)` values.
+- [ ] Operations that act for the person run only from their click (a start page's `page.open` aside).
+- [ ] The SDK `<script>` tag is the v1 URL above, unchanged.
+- [ ] Every page links `assets/css/site.css?v=<n>`; if `site.css` changed, `<n>` is bumped in every page.
+- [ ] `board.json`'s `config.pages` lists every page: `name`, `file` (or `url`), `shows` written as facts, `ops` matching the file's `rpc` calls, and one `start` page.
+- [ ] Opened at `http://localhost:4180/`, every page loads without console errors.
+- [ ] Checked in Surph with dev mode on: the canvas opens on the start page and each page paints with real data.

package/scaffold/board/assets/css/site.css

@@ -0,0 +1,224 @@
+/* Shared styles for every page in this set. Linked from each page as
+   assets/css/site.css?v=<n> — bump <n> on every change (S3 caches it).
+   Each set (base, each board) has its own copy; they start the same and
+   may diverge.
+   A page's own <style> holds only what that page alone uses. */
+
+:root {
+  --ink: #1e0a3c;          /* text */
+  --muted: #4b5563;        /* secondary text */
+  --faint: #6b7280;        /* empty / status lines */
+  --subtle: #9ca3af;       /* dates, link icons */
+  --accent: #6b5b8a;       /* section headings, initials */
+  --rule: #ece7f3;         /* row dividers */
+  --tint: #f6f3fa;         /* row hover */
+  --tint-strong: #f3f0f8;  /* icon placeholder */
+  --pill: #f1eff6;         /* owner pill */
+  --pill-hover: #e4e0ec;
+  --owner: #1f7f78;        /* owner pill text */
+  --owner-hover: #145f5a;
+}
+
+/* Page shell */
+
+html, body {
+  margin: 0;
+  background: #fff;
+  color: var(--ink);
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  padding: 28px 24px;
+}
+
+h1 {
+  margin: 0;
+  font-size: 1.35rem;
+  font-weight: 650;
+  line-height: 1.3;
+}
+
+/* A section heading (filled in once the section's data arrives). */
+h2 {
+  margin: 1.75rem 0 0;
+  font-size: 0.8rem;
+  font-weight: 650;
+  letter-spacing: 0.02em;
+  color: var(--accent);
+}
+
+h2:empty {
+  display: none;
+}
+
+/* The line shown when a list has nothing in it. */
+p.empty {
+  margin: 0.5rem 0 0;
+  font-size: 0.9rem;
+  color: var(--faint);
+}
+
+/* Context lists (landing, explore, profile): <ul class="contexts">, each
+   <li> holding one .context row. --icon-size sets the icon square; a list
+   whose rows have no owner pill sets it smaller. */
+
+ul.contexts {
+  --icon-size: 64px;
+  list-style: none;
+  margin: 0.5rem 0 0;
+  padding: 0;
+}
+
+ul.contexts > li {
+  border-top: 1px solid var(--rule);
+}
+
+/* The row: icon, then name / description / owner. A <button>, or a
+   div[role=button] when it holds the owner's button. Scoped to
+   ul.contexts: other pages use a .context class of their own. */
+ul.contexts .context {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  padding: 0.7rem 0.5rem;
+  margin: 0 -0.5rem;
+  box-sizing: content-box;
+  background: transparent;
+  border: none;
+  border-radius: 8px;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+ul.contexts .context:hover,
+ul.contexts .context:focus-visible {
+  background: var(--tint);
+}
+
+/* The icon square; the image fills it, else it shows the name's initial. */
+ul.contexts .context > .icon {
+  position: relative;
+  flex-shrink: 0;
+  width: var(--icon-size);
+  height: var(--icon-size);
+  border-radius: 10px;
+  overflow: hidden;
+  background: var(--tint-strong);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 650;
+  color: var(--accent);
+}
+
+ul.contexts .context > .icon img {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+ul.contexts .context .text {
+  flex: 1;
+  min-width: 0;
+}
+
+/* The line under the description: owner pill, then the settings (edit) button. */
+ul.contexts .context .meta {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  margin-top: 0.35rem;
+}
+
+ul.contexts .context .meta button.owner {
+  margin-top: 0;
+}
+
+/* Settings (gear): only on contexts this user created or collaborates on
+   (canEdit); opens the context builder (context.edit). */
+ul.contexts .context button.edit {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--subtle);
+  cursor: pointer;
+}
+
+ul.contexts .context button.edit:hover,
+ul.contexts .context button.edit:focus-visible {
+  background: var(--pill-hover);
+  color: var(--accent);
+}
+
+ul.contexts .context button.edit svg {
+  width: 14px;
+  height: 14px;
+}
+
+ul.contexts .context strong {
+  display: block;
+  font-size: 0.95rem;
+  font-weight: 650;
+}
+
+ul.contexts .context span.description {
+  display: block;
+  margin-top: 0.15rem;
+  font-size: 0.85rem;
+  line-height: 1.4;
+  color: var(--muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* The context's owner: avatar + username, as in the chat's pills. A
+   <button> that opens their profile (profile.open). */
+button.owner {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  margin-top: 0.35rem;
+  padding: 0.2rem 0.6rem 0.2rem 0.25rem;
+  border: none;
+  border-radius: 999px;
+  background: var(--pill);
+  color: var(--owner);
+  font-family: inherit;
+  font-size: 0.78rem;
+  font-weight: 500;
+  line-height: 1.2;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+button.owner:hover,
+button.owner:focus-visible {
+  background: var(--pill-hover);
+  color: var(--owner-hover);
+}
+
+button.owner.no-avatar {
+  padding-left: 0.6rem;
+}
+
+button.owner img {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  object-fit: cover;
+  background: var(--pill-hover);
+}

package/scaffold/board/board.json

@@ -0,0 +1,22 @@
+{
+  "slug": "my-board",
+  "name": "My Board",
+  "description": "",
+  "logo": "",
+  "contexts": [],
+  "defaultContext": "",
+  "waves": [],
+  "tools": [],
+  "config": {
+    "instructions": "",
+    "pages": [
+      {
+        "name": "home",
+        "file": "index.html",
+        "shows": "The board's home page: an introduction to how this board's pages work in Surph, and whether the page is running inside Surph.",
+        "start": "always",
+        "ops": ["board.get"]
+      }
+    ]
+  }
+}

package/scaffold/board/index.html

@@ -0,0 +1,152 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>your surph board</title>
+  <link rel="stylesheet" href="assets/css/site.css?v=1">
+  <style>
+    p.lead {
+      margin: 0.5rem 0 0;
+      font-size: 0.95rem;
+      line-height: 1.5;
+      color: var(--muted);
+    }
+    ol.steps,
+    ul.facts {
+      margin: 0.6rem 0 0;
+      padding-left: 1.2rem;
+      font-size: 0.9rem;
+      line-height: 1.55;
+      color: var(--muted);
+    }
+    ol.steps li,
+    ul.facts li {
+      margin-top: 0.4rem;
+    }
+    ol.steps strong,
+    ul.facts strong {
+      color: var(--ink);
+    }
+    code {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 0.82rem;
+      padding: 0.05rem 0.3rem;
+      border-radius: 4px;
+      background: var(--tint);
+      color: var(--ink);
+    }
+    /* Where this page is running: inside Surph's canvas, or opened directly. */
+    .status {
+      display: flex;
+      align-items: flex-start;
+      gap: 10px;
+      margin-top: 0.75rem;
+      padding: 0.75rem 0.9rem;
+      border: 1px solid var(--rule);
+      border-radius: 10px;
+      font-size: 0.9rem;
+      line-height: 1.45;
+      color: var(--muted);
+    }
+    .status .dot {
+      flex-shrink: 0;
+      width: 10px;
+      height: 10px;
+      margin-top: 0.35rem;
+      border-radius: 50%;
+      background: var(--subtle);
+    }
+    .status.is-hosted .dot {
+      background: var(--owner);
+    }
+    .status strong {
+      display: block;
+      color: var(--ink);
+    }
+  </style>
+</head>
+<body>
+  <h1>your surph board</h1>
+  <p class="lead">This page is part of a Surph board. Surph shows it in the <strong>canvas</strong>, the panel beside its chat, and answers its requests for data. Edit <code>index.html</code> to make it your board's home page.</p>
+
+  <div class="status" id="status">
+    <span class="dot" aria-hidden="true"></span>
+    <div>
+      <strong id="status-title">Checking…</strong>
+      <span id="status-text"></span>
+    </div>
+  </div>
+
+  <h2>How a page works in Surph</h2>
+  <ul class="facts">
+    <li><strong>It's a static HTML file.</strong> No build step or framework. Surph loads it in an iframe; you can host it anywhere on <code>https</code>.</li>
+    <li><strong>It talks to Surph through the SDK.</strong> The page loads <code>surph-wave.js</code>, calls <code>SurphWave.connect()</code>, then asks the host for data with <code>host.rpc(op, args)</code>: the board's recent items, the chat's context, the items the chat looked up, and more. The page never calls Surph's servers itself.</li>
+    <li><strong>The chat decides when to show it.</strong> Each page is registered with a <code>shows</code> line, plain facts about what it displays. The chat's model reads those and opens the page that fits what the person asked. A page can also take values in its address (<code>?ids=…</code>) that the chat fills in.</li>
+    <li><strong>It updates as the chat goes.</strong> When the host's data changes, it calls the page's <code>onRefresh</code>, and the page asks again and repaints.</li>
+    <li><strong>Opened directly, it still loads.</strong> Outside Surph, <code>host.hosted</code> is false and every call rejects, so the page shows its empty layout. That's what you see here when you run it locally.</li>
+  </ul>
+
+  <h2>Next steps</h2>
+  <ol class="steps">
+    <li><strong>Read <code>README.md</code>.</strong> It lists every operation the host answers, the item shape, and the rules a page follows. Point your coding agent at it.</li>
+    <li><strong>Run it locally:</strong> <code>npm run dev</code> serves this folder at <code>http://localhost:4180</code> with caching off.</li>
+    <li><strong>Add pages</strong> next to this one (<code>items.html</code>, <code>events.html</code>…), and list each in <code>board.json</code> with its <code>name</code>, <code>file</code>, <code>shows</code> and the <code>ops</code> it calls. Shared styles go in <code>assets/css/site.css</code>.</li>
+    <li><strong>See them in Surph:</strong> open <strong>Settings → Developer</strong> and turn on dev mode for <code>http://localhost:4180</code>. The canvas then shows this folder's pages, with real data.</li>
+  </ol>
+
+  <script src="https://surph.s3.us-east-1.amazonaws.com/admin/desktop/js/wave-sdk/v1/surph-wave.js"></script>
+  <script>
+    const host = SurphWave.connect({
+      pageSlug: 'index',
+      onRefresh: function () { paint(); }
+    });
+
+    const statusBox = document.getElementById('status');
+    const statusTitle = document.getElementById('status-title');
+    const statusText = document.getElementById('status-text');
+
+    function setStatus(hosted, title, text) {
+      statusBox.classList.toggle('is-hosted', hosted);
+      statusTitle.textContent = title;
+      statusText.textContent = text;
+    }
+
+    // The call pattern every page uses: a timeout means the host is still
+    // loading (ask again shortly), any other error means stop, and the page
+    // paints only after a successful reply.
+    let painting = false;
+    async function paint() {
+      if (!host.hosted) {
+        setStatus(false, 'Opened directly, not inside Surph', 'Host calls reject here, so this page shows its layout only. Inside the Surph canvas, this box shows your board.');
+        return;
+      }
+      if (painting) return;
+      painting = true;
+      let got;
+      try {
+        got = await host.rpc('board.get', {}, { timeout: 800 });
+      } catch (e) {
+        painting = false;
+        if (e && e.message === 'host timeout') {
+          setStatus(true, 'Inside Surph', 'Loading the board…');
+          setTimeout(paint, 200);
+        } else {
+          setStatus(true, 'Inside Surph', 'The host answered: ' + ((e && e.message) || 'an error') + '.');
+        }
+        return;
+      }
+      painting = false;
+      const name = got && typeof got.name === 'string' ? got.name : '';
+      const count = Array.isArray(got && got.items) ? got.items.length : 0;
+      setStatus(true, 'Inside Surph' + (name ? ': ' + name : ''),
+        name
+          ? 'board.get answered with ' + count + ' recent item' + (count === 1 ? '' : 's') + ' from this board.'
+          : 'board.get answered: this chat isn’t on a board, so it has no board items.');
+    }
+
+    host.ready();
+    paint();
+  </script>
+</body>
+</html>

package/scaffold/board/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "surph-board",
+  "version": "1.0.0",
+  "description": "",
+  "scripts": {
+    "dev": "surph-board-dev"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@surph_ai/sdk": "latest"
+  }
+}

package/scaffold/index.js

@@ -1,8 +1,8 @@
 // const program = require('commander')
+// const fs = require('fs')
+// const dotenv = require('dotenv')
 const shell = require('shelljs')
 const path = require('path')
-const fs = require('fs')
-const dotenv = require('dotenv')
 const colors = require('colors/safe')
 const utils = require('../utils')
 const { StepProgress } = require('../utils/progress')
@@ -22,6 +22,17 @@ const TOOL_STEPS = [
   { id: 'devserver', doing: 'Starting dev server', done: 'Dev server starting', weight: 8 }
 ]
 
+const BOARD_STEPS = [
+  { id: 'directory', doing: 'Creating project directory', done: 'Project directory created', weight: 1 },
+  { id: 'package', doing: 'Writing package.json', done: 'package.json written', weight: 1 },
+  { id: 'examples', doing: 'Copying example tools', done: 'Example tools copied', weight: 2 },
+  { id: 'manifests', doing: 'Writing manifests', done: 'Manifests written', weight: 1 },
+  { id: 'config', doing: 'Writing .env and tsconfig.json', done: '.env and tsconfig.json written', weight: 1 },
+  { id: 'cheatsheet', doing: 'Fetching cheatsheet', done: 'Cheatsheet fetched', weight: 4 },
+  { id: 'install', doing: 'Installing dependencies', done: 'Dependencies installed', weight: 82 },
+  { id: 'devserver', doing: 'Starting dev server', done: 'Dev server starting', weight: 8 }
+]
+
 // Expected package count for install sub-progress; grows if the tree is larger.
 // Used as clamp for install sub-progress. Never shown to the user.
 const EXPECTED_PACKAGES = 324
@@ -241,6 +252,122 @@ const scaffoldTool = async (name) => {
   shell.exec('npm run dev')
 }
 
+const scaffoldBoard = async (name) => {
+  const progress = new StepProgress(BOARD_STEPS)
+  console.log(progress.paint(colors.cyan, `\nCreating Surph board: ${name}\n`))
+  progress.start()
+
+  try {
+    progress.begin('directory')
+    shell.mkdir('-p', name)
+    shell.cd(name)
+    await progress.done()
+
+    progress.begin('package')
+    const pkgJsonStr = utils.readFile(path.join(__dirname, 'board/package.json'))
+    const pkgJson = JSON.parse(pkgJsonStr)
+    pkgJson.name = name
+    utils.write('package.json', JSON.stringify(pkgJson, null, 2) + '\n')
+
+    shell.cp('-R', path.join(__dirname, `board/README.md`), 'README.md')
+    shell.cp('-R', path.join(__dirname, `board/index.html`), 'index.html')
+    shell.cp('-R', path.join(__dirname, `board/board.json`), 'board.json')
+
+    shell.mkdir('-p', 'assets')
+    shell.mkdir('-p', 'assets/css')
+    shell.mkdir('-p', 'assets/js')
+    shell.cp('-R', path.join(__dirname, `board/assets/css/site.css`), 'assets/css/site.css')
+
+    // shell.cp('-R', path.join(__dirname, `board/assets/js/wave-sdk/v1/surph-wave.js`), 'assets/js/surph-wave.js')
+
+    await progress.done()
+
+    progress.begin('install')
+    await installDependencies(progress, process.cwd())
+    await progress.done()
+
+
+    /*
+    progress.begin('examples')
+    shell.mkdir('-p', 'tools')
+    shell.cp('-R', path.join(__dirname, `tool/tools/index.ts`), 'tools/index.ts')
+
+    shell.mkdir('-p', 'examples')
+    shell.cp('-R', path.join(__dirname, `tool/examples/README.md`), 'examples/README.md')
+
+    shell.mkdir('-p', 'examples/population')
+    shell.cp('-R', path.join(__dirname, `tool/examples/population/index.ts`), 'examples/population/index.ts')
+    shell.cp('-R', path.join(__dirname, `tool/examples/population/manifest.json`), 'examples/population/manifest.json')
+
+    shell.mkdir('-p', 'examples/weather')
+    shell.cp('-R', path.join(__dirname, `tool/examples/weather/index.ts`), 'examples/weather/index.ts')
+    shell.cp('-R', path.join(__dirname, `tool/examples/weather/manifest.json`), 'examples/weather/manifest.json')
+    await progress.done()
+
+    progress.begin('manifests')
+    utils.write('manifest-example.json', JSON.stringify(manifestExample, null, 2) + '\n')
+
+    const slug = slugify(name, 8)
+    const manifest = {}
+    manifest[slug] = {
+      name,
+      slug,
+      type: 'custom',
+      description: '',
+      parameters: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    }
+
+    utils.write('manifest.json', JSON.stringify(manifest, null, 2) + '\n')
+    await progress.done()
+
+    progress.begin('config')
+    const envStr = utils.readFile(path.join(__dirname, 'tool/env.txt'))
+    utils.write('.env', envStr.replace('<SURPH_TOOL>', slug))
+    utils.write('tsconfig.json', JSON.stringify(tsConfig, null, 2) + '\n')
+    await progress.done()
+
+    progress.begin('cheatsheet')
+    try {
+      const cheatsheetResp = await fetch(CHEATSHEET_URL)
+      if (!cheatsheetResp.ok) {
+        throw new Error(`HTTP ${cheatsheetResp.status}`)
+      }
+      utils.write('CHEATSHEET.md', await cheatsheetResp.text())
+    } catch (error) {
+      // Cosmetic — a reference doc that didn't download is no reason to fail
+      // a scaffold that is otherwise complete.
+      progress.warn(`Could not fetch CHEATSHEET.md (${error.message}) - skipped.`)
+    }
+    await progress.done()
+
+    progress.begin('install')
+    await installDependencies(progress, process.cwd())
+    await progress.done()
+
+    progress.begin('devserver')
+    */
+
+
+    await progress.complete()
+  } catch (error) {
+    progress.fail(error)
+    process.exitCode = 1
+    return
+  }
+
+  console.log('\n- - - - - Next Steps - - - - - ')
+  // console.log('Open codebase in a code editor and navigate to /tools/index.ts - this is where your tool code goes.')
+  // console.log('\nFor full documentation, visit https://docs.surph.ai\n')
+  // console.log('Starting the dev server - your browser will open at http://localhost:6767')
+  // console.log('To stop it, press Ctrl+C. To start it again, run: npm run dev\n')
+
+  // shell.exec('npm run dev')
+}
+
 module.exports = async (name, type = 'app') => {
   /*
   https://stackoverflow.com/questions/8683895/how-do-i-determine-the-current-operating-system-with-node-js
@@ -255,4 +382,8 @@ module.exports = async (name, type = 'app') => {
   if (type === 'tool') {
     await scaffoldTool(name)
   }
+
+  if (type === 'board') {
+    await scaffoldBoard(name)
+  }
 }

package/scaffold/project/package.json

@@ -1,21 +1,15 @@
 {
-  "name": "base-template",
-  "version": "0.0.0",
-  "private": true,
+  "name": "surph-board",
+  "version": "1.0.0",
+  "description": "",
   "scripts": {
-    "start": "node ./app",
-    "dev": "nodemon",
-    "test": "",
-    "build": ""
-  },
-  "dependencies": {
-    "@turbo360/turbo-sdk": "^0.0.8",
-    "cookie": "^0.5.0",
-    "express": "^4.18.1",
-    "mustache": "^4.2.0",
-    "saxa": "^0.0.26"
+    "dev": "http-server -p 4180 -c-1"
   },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
   "devDependencies": {
-    "nodemon": "^2.0.2"
+    "http-server": "^14.1.1"
   }
 }