@surph_ai/cli 0.0.34 → 0.0.36

package/board/deploy.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-// Deploy a board to Surph (`npm run deploy` → `surph-board-deploy`), run from
-// the board's folder. Built up step by step; so far:
+// Deploy a board to Surph (`npm run deploy` → `surph board-deploy`), run from
+// the board's folder. The folder mirrors the live board on S3
+// (boards/<slug>/): board.json at the top, the pages and assets in site/.
 //
-//   1. Zip the board's site: every file in the folder except the project
-//      files (package.json, package-lock.json, README.md, board.json,
-//      node_modules), dot-files (.env, .git, .DS_Store) and the zip itself.
-//      Written to site.zip in the board's folder.
+//   1. Zip the board's site: every file in site/ except dot-files (.env,
+//      .DS_Store) and node_modules. Written to site.zip in the board's folder
+//      (not inside site/).
 //   2. Ask Surph for an upload address for it: boards/<slug>/site/site.zip on
 //      S3, the slug from board.json.
 //   3. Upload site.zip there, then delete the local site.zip (it's kept when
@@ -14,7 +14,8 @@
 //   5. Upload board.json to boards/<slug>/board.json — last, so the live
 //      board's definition only changes once its site is up.
 //
-// Node's built-ins only (zlib for compression, fetch for the upload; Node 18+).
+// Node's built-ins only (zlib for compression, fetch for the upload). Needs
+// Node.js 20 or later.
 
 const fs = require('fs');
 const path = require('path');
@@ -27,16 +28,16 @@ const RPC_URL = 'https://rpc.surph.ai';
 const SYNC_URL = 'https://e3lunom2hka3u6iiotrlzrcez40uwdnk.lambda-url.us-east-1.on.aws/';
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
-// Left out at the board's top level: the project's own files.
-const SKIP_AT_ROOT = new Set(['package.json', 'package-lock.json', 'README.md', 'board.json', ZIP_NAME]);
+// The board's site: site/ in its folder (boards/<slug>/site/ when live).
+const SITE = path.join(ROOT, 'site');
 
-// The files to deploy, as paths relative to the board's folder ('/'-separated).
-const siteFiles = (dir = ROOT, rel = '') => {
+// The files to deploy, as paths relative to site/ ('/'-separated) — where
+// they land under boards/<slug>/site/.
+const siteFiles = (dir = SITE, rel = '') => {
   const out = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const name = entry.name;
     if (name.startsWith('.') || name === 'node_modules') continue;
-    if (!rel && SKIP_AT_ROOT.has(name)) continue;
     const relPath = rel ? `${rel}/${name}` : name;
     const full = path.join(dir, name);
     if (entry.isDirectory()) out.push(...siteFiles(full, relPath));
@@ -73,7 +74,7 @@ const zipFiles = (files) => {
   const central = [];
   let offset = 0;
   for (const rel of files) {
-    const full = path.join(ROOT, ...rel.split('/'));
+    const full = path.join(SITE, ...rel.split('/'));
     const data = fs.readFileSync(full);
     const deflated = zlib.deflateRawSync(data, { level: 9 });
     const stored = deflated.length >= data.length;
@@ -202,12 +203,15 @@ const main = async () => {
     fail(`No board.json in ${ROOT}. Run this from the board's folder.`);
   }
   const slug = boardSlug();
+  if (!fs.existsSync(SITE) || !fs.statSync(SITE).isDirectory()) {
+    fail(`No site/ folder in ${ROOT}. The board's pages and assets go in site/ (site/index.html, site/assets/…).`);
+  }
   const files = siteFiles();
-  if (!files.length) fail('Nothing to deploy: the board has no site files.');
+  if (!files.length) fail('Nothing to deploy: site/ has no files.');
 
   const zip = zipFiles(files);
   fs.writeFileSync(path.join(ROOT, ZIP_NAME), zip);
-  console.log(`Zipped ${files.length} file${files.length === 1 ? '' : 's'} into ${ZIP_NAME} (${(zip.length / 1024).toFixed(1)} KB):`);
+  console.log(`Zipped ${files.length} file${files.length === 1 ? '' : 's'} from site/ into ${ZIP_NAME} (${(zip.length / 1024).toFixed(1)} KB):`);
   for (const file of files) console.log(`  ${file}`);
 
   console.log(`\nDeploying the board "${slug}"…`);
@@ -224,7 +228,13 @@ const main = async () => {
   console.log(`Uploaded: ${boardUrl.split('?')[0]}`);
 };
 
-const run = () => main().catch((error) => fail(`Deploy failed: ${error.message}`));
+const MIN_NODE = 20;
+
+const run = () => {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < MIN_NODE) fail(`Deploying a board needs Node.js ${MIN_NODE} or later; this is ${process.version}. Install a newer Node.js (https://nodejs.org) and try again.`);
+  return main().catch((error) => fail(`Deploy failed: ${error.message}`));
+};
 
 // `surph board-deploy` calls run(); running this file directly runs it too.
 if (require.main === module) run();

package/board/server.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
-// The board's local dev server (`npm run dev` → `surph-board-dev`): serves
-// the board folder it's run from (the current directory) at
+// The board's local dev server (`npm run dev` → `surph board-server`):
+// serves the board folder it's run from (the current directory) at
 // http://localhost:4180 for Surph's dev mode (Settings → Developer → Run
-// Surph as a local board). Node's built-ins only.
+// Surph as a local board). Node's built-ins only; needs Node.js 20 or later.
 //
-//   GET  /<file>             This folder's files, never cached, with CORS so
-//                            Surph (another address) can read board.json.
-//   GET  /__surph/assets     The image files in assets/ (the logo picker).
+// The folder mirrors a live board on S3 (boards/<slug>/): board.json at the
+// top, the pages and assets in site/. Only those two are served — the
+// project's own files (README.md, AGENTS.md, package.json…) aren't.
+//
+//   GET  /board.json         The board, with CORS so Surph (another address)
+//                            can read it. Never cached, like everything here.
+//   GET  /site/<file>        The board's pages and assets (site/ in this folder).
+//   GET  /                   Redirects to /site/ (its index.html).
+//   GET  /__surph/assets     The image files in site/assets/ (the logo picker).
 //   PUT  /board.json         Surph's Local board panel saving the board. Only
 //                            from Surph's own addresses, only this one file,
 //                            only a JSON object with a config.pages list.
@@ -70,14 +76,20 @@ const cors = (req) => {
   return headers;
 };
 
-// A path inside this folder, or null (no way out of it, no dot-files).
+// The board's site: site/ in this folder (boards/<slug>/site/ when live).
+const SITE = path.join(ROOT, 'site');
+
+// A /site/… path → its file inside site/, or null (no way out of it, no
+// dot-files, no node_modules).
 const inside = (urlPath) => {
   let rel;
   try { rel = decodeURIComponent(urlPath.split('?')[0]); } catch { return null; }
+  if (rel !== '/site' && !rel.startsWith('/site/')) return null;
+  rel = rel.slice('/site'.length) || '/';
   if (rel.endsWith('/')) rel += 'index.html';
-  const full = path.normalize(path.join(ROOT, rel));
-  if (full !== ROOT && !full.startsWith(ROOT + path.sep)) return null;
-  if (path.relative(ROOT, full).split(path.sep).some((part) => part.startsWith('.') || part === 'node_modules')) return null;
+  const full = path.normalize(path.join(SITE, rel));
+  if (!full.startsWith(SITE + path.sep)) return null;
+  if (path.relative(SITE, full).split(path.sep).some((part) => part.startsWith('.') || part === 'node_modules')) return null;
   return full;
 };
 
@@ -138,8 +150,22 @@ const handle = async (req, res) => {
       send(res, 405, 'Method not allowed', headers);
       return;
     }
-    if (urlPath.split('?')[0] === '/__surph/assets') {
-      const dir = path.join(ROOT, 'assets');
+    const pathname = urlPath.split('?')[0];
+    if (pathname === '/') {
+      send(res, 302, '', { ...headers, Location: '/site/' });
+      return;
+    }
+    if (pathname === '/board.json') {
+      const file = path.join(ROOT, 'board.json');
+      if (!fs.existsSync(file)) {
+        send(res, 404, 'No board.json in this folder.', headers);
+        return;
+      }
+      send(res, 200, req.method === 'HEAD' ? '' : fs.readFileSync(file), { ...headers, 'Content-Type': TYPES['.json'] });
+      return;
+    }
+    if (pathname === '/__surph/assets') {
+      const dir = path.join(SITE, 'assets');
       const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((name) => IMAGE.test(name)).sort() : [];
       send(res, 200, JSON.stringify({ images: files }), { ...headers, 'Content-Type': 'application/json' });
       return;
@@ -158,7 +184,14 @@ const handle = async (req, res) => {
 
 // Start serving the current folder. localhost may be reached over IPv4 or
 // IPv6: listen on both loopbacks.
+const MIN_NODE = 20;
+
 const start = () => {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < MIN_NODE) {
+    console.error(`The board dev server needs Node.js ${MIN_NODE} or later; this is ${process.version}. Install a newer Node.js (https://nodejs.org) and try again.`);
+    process.exit(1);
+  }
   http.createServer(handle)
     .on('error', (error) => {
       console.error(error.code === 'EADDRINUSE'
@@ -167,7 +200,7 @@ const start = () => {
       process.exit(1);
     })
     .listen(PORT, '127.0.0.1', () => {
-      console.log(`Board dev server: http://localhost:${PORT} (serving ${ROOT})`);
+      console.log(`Board dev server: http://localhost:${PORT} (serving ${ROOT}: board.json and site/)`);
       console.log('In Surph: Settings → Developer → Run Surph as a local board.');
     });
   http.createServer(handle).listen(PORT, '::1').on('error', () => { /* no IPv6 loopback */ });

package/package.json

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

package/scaffold/board/AGENTS.md

@@ -0,0 +1,32 @@
+# Surph board: notes for coding agents
+
+This folder is a **Surph board**: static web pages that Surph shows in its canvas, beside the Surph chat. The person you're working with may not be technical. Explain steps in plain words, and say what a command does before you run it.
+
+**`README.md` is the full reference.** Read it before writing or changing a page: it lists every operation Surph answers, the item shape, the rules for pages, and how `board.json` works. This file covers setup and the working loop.
+
+## Setup: Node.js
+
+Previewing and publishing the board need **Node.js 20 or later**. The pages themselves don't.
+
+1. Check with `node -v`.
+2. If it's missing or older than 20, tell the person that Node.js is needed to preview the board inside Surph and to publish it, and offer to install it. Install only with their OK.
+   - **Mac:** prefer a user-level install that needs no admin password, such as [fnm](https://github.com/Schniz/fnm) (`curl -fsSL https://fnm.vercel.app/install | bash`, then `fnm install --lts`). Homebrew (`brew install node`) is fine if Homebrew is already installed.
+   - **Windows:** `winget install OpenJS.NodeJS.LTS` (Windows may ask the person to approve once).
+   - **Linux:** the distribution's package manager, or fnm as on Mac.
+3. A fresh install may not be visible in the current terminal. If `node -v` still fails afterwards, open a new terminal session (or load the shell profile) and check again.
+4. If an install isn't possible (declined, or blocked on a work computer), point them to the installer at https://nodejs.org and wait for them.
+
+## The working loop
+
+1. **Preview:** run `npm run dev` from this folder and leave it running. It serves the board at `http://localhost:4180`: `board.json`, and the pages in `site/` under `/site/` (nothing to install; it uses the Surph CLI through `npx`).
+2. **See it in Surph:** ask the person to open Surph, go to **Settings → Developer**, turn on **Run Surph as a local board**, and keep the address `http://localhost:4180`. Surph reloads as this board.
+3. **Configure the board** (name, contexts, tools, instructions): the person can click the **DEV** label in Surph's canvas header to open the Local board panel, which saves `board.json` for you. You can also edit `board.json` directly; the README describes every field.
+4. **Change pages:** the pages and their assets live in `site/` (`site/index.html`, `site/assets/…`). Edit them there and keep `board.json`'s `config.pages` in step (every page listed, `shows` written as plain facts, `ops` matching the page's `host.rpc` calls). The person reloads Surph to see the change.
+5. **Publish:** `npm run deploy`. **Only when the person asks you to in this conversation.** It replaces the live board for everyone who uses it. Check the board in dev mode first.
+
+## What to keep in mind
+
+- Pages talk to Surph only through the Surph SDK (`host.rpc(…)`) and only with the operations the README lists. Don't invent operations or fields; if a page needs data Surph doesn't offer, say so.
+- Write data from Surph with `textContent`, never `innerHTML`.
+- Everything in `site/` (except dot-files) gets published by `npm run deploy`, and nothing outside it except `board.json`. Keep drafts, notes and secrets out of `site/`.
+- Before handing off, go through the README's "Checklist before handing off a change".

package/scaffold/board/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/scaffold/board/README.md

@@ -16,18 +16,23 @@ This project is a **Surph board**: a set of web pages that Surph shows in its **
 ## 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)
+site/                 The board's site: everything here is published, nothing else is
+  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 locally; `npm run deploy` publishes the board (see "Deploying")
+package.json          `npm run dev` serves the board locally; `npm run deploy` publishes it (see "Deploying")
 README.md             This file
+AGENTS.md, CLAUDE.md  Notes for coding agents
 ```
 
-- **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`).
+The folder mirrors the live board in Surph's storage: `board.json` at the top, the pages and assets in `site/`.
+
+- **Pages sit at the top of `site/`.** A page's registry entry names its file without a folder, so a page can't live in a subfolder of `site/`.
+- **Everything else a page loads, apart from the SDK, goes under `site/assets/`**, linked with relative paths from the page (`assets/css/site.css`, `./items.html`).
+- **Only `site/` is published.** Keep notes, drafts and anything else outside it.
 
 ### Shared styles: `assets/css/site.css`
 
@@ -71,7 +76,7 @@ Surph only shows pages that are registered with the board. The board itself is d
 | `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. |
+| `logo` | An image file in `site/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`. |
 | `tools` | Slugs of Surph tools the board's chat can use. Optional. |
@@ -92,7 +97,7 @@ A registry entry:
 | 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. |
+| `file` | The HTML file's name only, with no folder (`events.html`). It's found in `site/`: on your local server while you develop, and in the board's `site/` folder in Surph's storage 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`. |
@@ -396,33 +401,33 @@ A field marked "omitted" is missing from the object, not `null`. Every URL is `h
 - **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.
+- **Plain, static files.** No build step is needed or expected. Scripts can live inline or under `site/assets/js/`; keep the SDK `<script>` tag as given.
 
 ## Developing locally
 
-1. Run `npm run dev` (nothing to install). It starts the board dev server from the Surph CLI (`npx @surph_ai/cli board-server`), 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.
+1. Run `npm run dev` (nothing to install). It starts the board dev server from the Surph CLI (`npx @surph_ai/cli board-server`), which serves the board at `http://localhost:4180` (`board.json`, and `site/` under `/site/`) 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.
+3. Open `http://localhost:4180/site/` 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 are kept as they are in the file; edit pages in `board.json` itself.
+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 `site/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 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.
 
 ## Deploying
 
-`npm run deploy` (`npx @surph_ai/cli board-deploy`, from the Surph CLI) publishes the board to Surph. Run it from the board's folder. It needs Node 18 or later and nothing else installed. In order, it:
+`npm run deploy` (`npx @surph_ai/cli board-deploy`, from the Surph CLI) publishes the board to Surph. Run it from the board's folder. It needs Node.js 20 or later and nothing else installed. In order, it:
 
 1. **Reads the board's `slug`** from `board.json` (lowercase letters, digits and dashes). The slug names the board's place in Surph; without a valid one it stops before doing anything.
-2. **Zips the site** into `site.zip`: every file in the folder except `package.json`, `package-lock.json`, `README.md`, `board.json`, `node_modules`, dot-files (`.env`, `.git`, `.DS_Store`) and `site.zip` itself. It lists the files it zipped.
+2. **Zips the site** into `site.zip`: every file in `site/`, except dot-files (`.env`, `.DS_Store`) and `node_modules`. Nothing outside `site/` is included (`board.json` goes up on its own in step 5). It lists the files it zipped.
 3. **Uploads `site.zip`** to the board's `site/` folder in Surph's storage, then deletes the local `site.zip`. If the upload fails, the zip is kept to look at.
-4. **Unzips it there**, so the pages and `assets/` sit in the board's `site/` folder, where each page's `file` is found.
+4. **Unzips it there**, so the board's `site/` folder in Surph's storage holds the same files as your `site/`, where each page's `file` is found.
 5. **Uploads `board.json`**, last, so the live board's definition only changes once its pages are up. If an earlier step fails, `board.json` isn't uploaded and the live board keeps its previous version.
 
 Each step prints what it did; a failure prints why and stops. After a deploy, Surph picks up the new `board.json` within about a minute.
 
 **For coding agents:**
 - **Deploying publishes the board to everyone who uses it.** Don't run `npm run deploy` unless the person asks you to in this conversation. Check the board with dev mode first (see [Developing locally](#developing-locally)).
-- **Everything in the folder outside the list above is uploaded.** Keep drafts, exports, archives and secrets out of the board's folder, or in dot-files, which are never deployed.
+- **Everything in `site/` is uploaded.** Keep drafts, exports, archives and secrets out of `site/` (anywhere else in the board's folder is fine; dot-files are never deployed).
 - **A deploy replaces the live `board.json` with the local one.** Make sure `slug` is the board you mean to update: a deploy under another board's slug overwrites that board.
 
 ## Checklist before handing off a change
@@ -432,8 +437,8 @@ Each step prints what it did; a failure prints why and stops. After a deploy, Su
 - [ ] 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.
+- [ ] Every page (in `site/`) 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.
+- [ ] Opened at `http://localhost:4180/site/<page>`, 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.
 - [ ] Not deployed unless the person asked for it; if deployed, `npm run deploy` finished without errors and its file list holds only the board's site.

package/scaffold/board/package.json

@@ -9,5 +9,8 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "type": "commonjs"
+  "type": "commonjs",
+  "engines": {
+    "node": ">=20"
+  }
 }

package/scaffold/board/{index.html → site/index.html}

@@ -68,7 +68,7 @@
 </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>
+  <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>site/index.html</code> to make it your board's home page.</p>
 
   <div class="status" id="status">
     <span class="dot" aria-hidden="true"></span>
@@ -90,9 +90,9 @@
   <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>
+    <li><strong>Run it locally:</strong> <code>npm run dev</code> serves the board at <code>http://localhost:4180</code> (this page is <code>/site/</code>) with caching off.</li>
+    <li><strong>Add pages</strong> in <code>site/</code>, 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>site/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 the board'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>

package/scaffold/index.js

@@ -270,15 +270,15 @@ const scaffoldBoard = async (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/AGENTS.md`), 'AGENTS.md')
+    shell.cp('-R', path.join(__dirname, `board/CLAUDE.md`), 'CLAUDE.md')
     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')
+    // The board's pages and assets go in site/ (boards/<slug>/site/ when live).
+    shell.mkdir('-p', 'site/assets/css')
+    shell.mkdir('-p', 'site/assets/js')
+    shell.cp('-R', path.join(__dirname, `board/site/index.html`), 'site/index.html')
+    shell.cp('-R', path.join(__dirname, `board/site/assets/css/site.css`), 'site/assets/css/site.css')
 
     await progress.done()