@surph_ai/cli 0.0.29 → 0.0.33

package/package.json

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

package/scaffold/board/README.md

@@ -21,7 +21,8 @@ index.html            The board's home page (edit it; it starts as an intro to t
 assets/
   css/site.css        Styles shared by every page in the board
   js/                 Scripts shared by the board's pages (optional)
-package.json          `npm run dev` serves this folder at http://localhost:4180
+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")
 README.md             This file
 ```
 
@@ -43,14 +44,46 @@ Every page links it in `<head>`, before its own `<style>`:
 
 ## Registering pages
 
-Surph only shows pages that are registered with the board. **Today the board's registry is set up by Surph**: when you add, remove or rename a page, or change which operations it calls, your hand-off must include the registry entry for it.
+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**, `npm run deploy` uploads this same file, and the live board is built from it (see [Deploying](#deploying)). There's no separate record to set up.
+
+```json
+{
+  "slug": "my-board",
+  "name": "My Board",
+  "description": "What the board is about.",
+  "logo": "logo.png",
+  "contexts": ["<context slug>"],
+  "defaultContext": "<context slug>",
+  "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`. |
+| `tools` | Slugs of Surph tools the board's chat can use. 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",
-  "url": "https://your-host.example.com/board/events.html",
+  "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"]
 }
@@ -59,8 +92,8 @@ 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. |
-| `url` | The page's full `https://` address, when you host the files yourself. |
-| `file` | Instead of `url`, when Surph hosts the board's files: the HTML file's name only, with no folder (`events.html`). |
+| `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. |
@@ -367,11 +400,30 @@ A field marked "omitted" is missing from the object, not `null`. Every URL is `h
 
 ## Developing locally
 
-1. Install once: `npm install`.
-2. Run `npm run dev`. It serves this folder at `http://localhost:4180` with caching off.
+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. To see a page with real data, it has to be registered with a board in Surph (see [Registering pages](#registering-pages)).
-5. 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.
+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.
+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` (`surph-board-deploy` from `@surph_ai/sdk`) 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:
+
+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.
+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.
+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.
+- **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
 
@@ -381,5 +433,7 @@ A field marked "omitted" is missing from the object, not `null`. Every URL is `h
 - [ ] 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.
-- [ ] Each page added, renamed or removed, or with changed `rpc` calls, comes with its registry entry: `name`, `url` or `file`, `shows` written as facts, and `ops` matching the file.
+- [ ] `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.
+- [ ] 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/board.json

@@ -0,0 +1,21 @@
+{
+  "slug": "my-board",
+  "name": "My Board",
+  "description": "",
+  "logo": "",
+  "contexts": [],
+  "defaultContext": "",
+  "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

@@ -91,8 +91,8 @@
   <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>…). Shared styles go in <code>assets/css/site.css</code>.</li>
-    <li><strong>Register them with your board.</strong> Each page needs a registry entry (its <code>name</code>, address, <code>shows</code> and the <code>ops</code> it calls) so Surph knows it exists. The README shows the format.</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>

package/scaffold/board/package.json

@@ -3,13 +3,14 @@
   "version": "1.0.0",
   "description": "",
   "scripts": {
-    "dev": "http-server -p 4180 -c-1"
+    "dev": "surph-board-dev",
+    "deploy": "surph-board-deploy"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "type": "commonjs",
-  "devDependencies": {
-    "http-server": "^14.1.1"
+  "dependencies": {
+    "@surph_ai/sdk": "latest"
   }
 }

package/scaffold/index.js

@@ -271,6 +271,7 @@ const scaffoldBoard = async (name) => {
 
     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')