Merge pull request #167 from ReScienceLab/prd-tab

PRD tab and the define-product skill

Author: Jing-yilin

AGENTS.md

@@ -7,25 +7,30 @@ holds only *data*.
 
 Code, shipped to every install:
 
-`skills/` holds `clone-prototype`, `new-ui-mock`, `prototype-canvas` and
-`brand-kit`.
+`skills/` holds `clone-prototype`, `new-ui-mock`, `prototype-canvas`,
+`define-product` and `brand-kit`.
 `.claude/skills/` and `.agents/skills/` are symlinks to it, so this checkout
 loads the same tree an install does.
 
 `canvas/` is the tldraw viewer, built with Bun and Vite. Its server serves
 every project under `~/Documents/Super Prototyping` (`PROTOTYPING_PROJECTS_DIR`
-moves it) at `/p/<name>/`, plus the one `sp start` or the app opened, with this
-repo's `canvases` as the examples shown beside each project's own. A
+moves it) at `/p/<name>/`, and no folder anywhere else, with this repo's
+`canvases` as the examples shown beside each project's own.
+`docs/2026-09-23-projects-folder-only.md` says why. A
 project's boards are its `canvases`, discovered as `*/*.html` one level
 deep. Discovery is `boardIndex()` in `canvas/server/boards.ts`, served as JSON at
 `/__sp/index.json` by `canvas/server/sp.ts` and written into `dist` by the
 build — not an `import.meta.glob`, because a glob pattern is a build-time
-literal and could only ever read one hard-coded directory. `sp start`
+literal and could only ever read one hard-coded directory. The same index
+carries a project's documents, for now only the `PRD.md` at its root. Each
+is a tab before the canvases, shown rendered or as editable text (`DOCS` in
+`boards.ts`, `DocTab.tsx`). `sp start`
 runs the built app, `dist/server.mjs`: the release's `canvas-dist.tgz`
 fetched into `~/.cache/super-prototyping/<version>/` for an install, or this
 checkout's own `canvas/dist` when `canvas/node_modules` exists. The canvas's
-`dev` script mounts the same server under Vite, with this checkout open as the
-project, for working on the app.
+`dev` script mounts the same server under Vite, for working on the app. It opens
+on the home page with no project, as the app does: this checkout's canvases are
+the examples there, not a project of their own.
 
 The hosted canvas is that build on Cloudflare Pages, and it lives at
 `prototyping.rescience.com/demo/` now: the root is the download page, whose
@@ -88,6 +93,8 @@ Rules inside a canvas folder:
   output. Edit the generator and re-run, never the HTML.
 - Commit `layout.json`, `icon.png` and `assets/`. `gen.py` inlines the
   images in `assets/` as `data:` URIs.
+- Commit `PRD.md`, the product the folder prototypes, to the `define-product`
+  skill's template. Its Screens table lists the folder's boards.
 - Commit `probes.json` and `crops.json`. They are the measurement evidence
   behind the tokens.
 - Commit `assets.json` where a folder has one (three do). It is a

README.md

@@ -143,18 +143,19 @@ is in there to copy from too.
 ## Run the canvas
 
 ```bash
-sp open               # this project, in the app
-sp open ~/my-app      # any project, from anywhere
-sp start ~/my-app     # the same canvas in a browser, without the app
+sp open               # the app, on its home page
+sp start              # the same canvas in a browser, without the app
 ```
 
-`sp open` hands the project to the app, starting it if it is not running, and
-prints the address. `sp start` is for where the app cannot run. From a checkout
-without a build, it downloads the canvas built for that version into `~/.cache/super-prototyping/`, then serves it on 127.0.0.1:5173
-against the project's `canvases` with node or bun, opens the browser,
-and prints the address. Every project under `~/Documents/Super Prototyping` is
-served beside it at `/p/<name>/`, the same way the app serves them;
-`PROTOTYPING_PROJECTS_DIR` moves that folder. `--port N` (or
+Every project is a folder under `~/Documents/Super Prototyping`, made from the
+home page's New project, and served at `/p/<name>/`;
+`PROTOTYPING_PROJECTS_DIR` moves that folder. No folder elsewhere is ever
+opened as a project, so a project's Delete cannot trash code you did not make
+there. `sp open` starts the app if it is not running and prints the address.
+`sp start` is for where the app cannot run. From a checkout without a build,
+it downloads the canvas built for that version into
+`~/.cache/super-prototyping/`, then serves it on 127.0.0.1:5173 with node or
+bun, opens the browser, and prints the address. `--port N` (or
 `SP_CANVAS_PORT`) moves the port, `sp status` and `sp stop` do what
 they say. `sp paths` lists the two directories it writes, and
 `sp clean` removes them.
@@ -167,14 +168,15 @@ folder added after boot appears on its own.
 
 ## The workflow
 
-Four skills, in `skills/` (which `.claude/skills/` and `.agents/skills/`
+Five skills, in `skills/` (which `.claude/skills/` and `.agents/skills/`
 symlink to, so this checkout loads what an install does):
 
 | Skill | Use it for |
 |---|---|
 | **clone-prototype** | Copying a real app's screens. Grid the reference, sample colours *visually*, name the type face, derive one measured token block, generate the artboards, verify by re-rendering, park the reference underneath. |
 | **new-ui-mock** | Designing new screens with no reference, built on existing tokens, including the empty/loading/error states and side-by-side proposals. |
 | **prototype-canvas** | Running and operating the canvas: boards, `layout.json`, the `window.snapCanvas` bridge, annotated-screenshot review, the force-refresh. |
+| **define-product** | Working out what the product is before anything is drawn: an interview, one or two questions at a time, problem before solution, gaps left TBD rather than invented. It writes the project's `PRD.md`, which the canvas shows as the first tab, with the screen inventory new-ui-mock designs from. |
 | **brand-kit** | Collecting a product's own brand and promotional material -- the company's own brand or press kit, store listings, verified social accounts, the newsroom -- and turning it into the image rows of a canvas folder, each asset carrying its source and whether the company published it. |
 
 The rule the whole thing is built around: **every colour and every metric in

canvas/server/agent.ts

@@ -435,6 +435,12 @@ export function createAgentServer(options: {
               "the prototype-canvas skill of the super-prototyping plugin: one folder is one canvas " +
               "page, one .html file in it is one board, layout.json places them, and the open canvas " +
               "reloads by itself when a board is rewritten.",
+            dir !== undefined &&
+              `${path.join(dir, "PRD.md")}, when there is one, is a tab of the canvas ` +
+                "and says what the product is for. When they start from an idea, or ask for screens " +
+                "with no PRD.md there, offer to define the product with them first, following " +
+                `${repoRoot}/skills/define-product/SKILL.md; never insist. When it exists, read it ` +
+                "before designing.",
             // On the turn that starts the session only. A resumed one has its title.
             record.resume === null &&
               "Open your first reply with a title for this conversation on a line of its own, " +

canvas/server/boards.ts

@@ -13,6 +13,19 @@ import { svgSignature } from "../src/svgSignature.ts";
  */
 export const CANVASES = "canvases";
 
+/**
+ * A project's documents: the Markdown files at its root, beside its canvases, that the canvas
+ * shows as tabs before them, in this order. For now only the PRD the define-product skill writes
+ * with the user. An example is a project of one canvas, so its folder is its root and its
+ * documents are read from there. */
+export const DOCS = ["PRD.md"];
+
+export function readDocs(dir: string) {
+  return DOCS.filter((name) =>
+    fs.statSync(path.join(dir, name), { throwIfNoEntry: false })?.isFile(),
+  ).map((name) => ({ name, text: fs.readFileSync(path.join(dir, name), "utf8") }));
+}
+
 /** The image types a board folder can hold, and what each is served as. */
 export const IMAGE_MIME: Record<string, string> = {
   ".png": "image/png",
@@ -287,6 +300,7 @@ export function boardIndex(
             thumbs: [] as string[],
             assets: assetIndex(folder),
             comments: readJson(path.join(folder, "comments.json")),
+            docs: readDocs(folder),
           };
         })
         .filter(

canvas/server/main.ts

@@ -2,12 +2,11 @@
  * The canvas as a localhost app: the built `dist` served as static files, with every project's
  * `/__sp` and `/board` server in front of it (projects.ts), the same one the Vite dev server
  * mounts. Bundled to `dist/server.mjs` by `bun run build`, so `sp start` runs one file with node
- * or bun and no dev toolchain. Usage: `node dist/server.mjs --port 5173 --open <project>`.
+ * or bun and no dev toolchain. Usage: `node dist/server.mjs --port 5173`.
  *
  * Every folder in the projects directory is served at `/p/<name>/`, with the examples beside
- * it. `--open` serves one more folder, from anywhere, which is what `sp start` opens, and `/`
- * redirects to it. The desktop app runs this same file and opens its folders over the parent
- * port instead.
+ * it, and no other folder: `/` is the home page, where a project is made. The desktop app runs
+ * this same file.
  */
 import fs from "node:fs";
 import http from "node:http";
@@ -85,30 +84,6 @@ function serveStatic(req: http.IncomingMessage, res: http.ServerResponse) {
 }
 
 const projects = createProjectsServer({ projectsDir, repoRoot });
-// Before the port is taken, so a folder that is not there fails the start rather than a server.
-const openArg = arg("--open");
-if (openArg !== undefined) projects.open(openArg);
-
-/**
- * A folder's path, from the desktop app before it opens a project, answered with the address it
- * is served at. The path comes over the parent port of Electron's utility process, which only the
- * app that started this server holds. `sp start` runs under node, which has no parent port.
- */
-const parentPort = (
-  process as NodeJS.Process & {
-    parentPort?: {
-      on(event: "message", listener: (message: { data: string }) => void): void;
-      postMessage(message: { address: string } | { error: string }): void;
-    };
-  }
-).parentPort;
-parentPort?.on("message", ({ data }) => {
-  try {
-    parentPort.postMessage({ address: projects.open(data) });
-  } catch (error) {
-    parentPort.postMessage({ error: String(error) });
-  }
-});
 
 const server = http.createServer((req, res) =>
   projects.handle(req, res, () => serveStatic(req, res)),

canvas/server/projects.test.ts

@@ -27,7 +27,7 @@ it("serves every project at its own address and makes new ones", async () => {
   // Both projects keep their boards where they used to be, which the server moves to `canvases`.
   write("projects/alpha/mockups/canvases/one/01-a.html", "alpha one");
   write("projects/alpha/mockups/.DS_Store", ""); // Finder's, which is no reason to keep the folder
-  write("elsewhere/mockups/canvases/mine/01-a.html", "mine");
+  write("elsewhere/canvases/mine/01-a.html", "mine");
 
   const projects = createProjectsServer({
     projectsDir: path.join(tmp, "projects"),
@@ -115,14 +115,8 @@ it("serves every project at its own address and makes new ones", async () => {
     fs.rmSync(path.join(tmp, "projects/.workspaces"), { recursive: true });
     expect((await ask("/__sp/agent/run/gone-run/events")).status).toBe(404);
 
-    expect(projects.open(path.join(tmp, "elsewhere"))).toBe("/p/elsewhere/");
-    expect(fs.existsSync(path.join(tmp, "elsewhere/canvases/mine"))).toBe(true);
-    expect(await ask("/?canvas=x")).toMatchObject({
-      status: 302,
-      location: "/p/elsewhere/?canvas=x",
-    });
-    expect((await ask("/p/elsewhere/")).text).toBe("static /");
-    expect((await ask("/p/elsewhere/board/mine/01-a.html")).text).toBe("mine");
+    // A folder outside the projects directory is never a project.
+    expect((await ask("/p/elsewhere/")).status).toBe(404);
     expect((await ask("/p/alpha/board/one/01-a.html")).text).toBe("alpha one");
     expect((await ask("/p/nowhere/")).status).toBe(404);
     // The examples come from the plugin root, beside every project's own.
@@ -131,7 +125,6 @@ it("serves every project at its own address and makes new ones", async () => {
     );
     const listed = JSON.parse((await ask("/__sp/projects.json")).text);
     expect(listed.map((p: any) => [p.name, p.url, p.path])).toEqual([
-      ["elsewhere", "/p/elsewhere/", path.join(tmp, "elsewhere")],
       ["alpha", "/p/alpha/", path.join(tmp, "projects/alpha")],
     ]);
     // A card's menu names a project the server has. Moving one to the Trash and showing one in