parleyd 0.0.1

package/README.md

@@ -0,0 +1,60 @@
+# parleyd
+
+> A minimal, standalone, **live agent↔human canvas**. Agents and humans (and agents and other agents) co-think on one shared board in real time.
+
+`parleyd` is the third in the SandRise coordination family — **muster**d (gather a team), **baton**d (hand work off), **parley**d (think together). A *parley* is a structured talk between parties to reach understanding; parleyd is where that happens on a shared canvas.
+
+It exists because the alternatives are over-built and fragile: a 2026 attempt to drive a heavyweight whiteboard from an agent failed at the content layer (`addShape` "succeeded" but the canvas read back empty). parleyd's #1 rule is the fix.
+
+## Design rules
+
+1. **One canvas document.** An agent's writes go *into the same store* the human's canvas reads and renders — never a parallel "shapes" table. This is the rule that makes `add → read → render → export` round-trip.
+2. **Content layer proven first.** The headless `add → read → snapshot` loop has a passing test before any UI polish (see `packages/server/test`).
+3. **Canvas-neutral agent API.** Agents speak generic nodes (`addShape {type,text,x,y,color}`), not canvas-library types. tldraw is the rendering impl behind it — swappable later.
+4. **Engine / host seam.** The HTTP API is the engine boundary; a `@sandrise/agent-canvas` library is a later *extraction*, not a rewrite.
+5. **No login wall on localhost.** Open a URL and it works. Hosted/multi-tenant auth is a deferred, separate concern.
+
+## Architecture
+
+```
+agent (any harness)
+  │  HTTP (canvas-neutral)        ┌─ packages/server ──────────────┐
+  ├─ POST /api/boards            │  store.ts   SQLite, the ONE doc │
+  ├─ POST /api/boards/:id/shapes │  api.ts     HTTP agent API      │
+  ├─ GET  /api/boards/:id/canvas │  sync.ts    WS broadcast hub    │
+  └─ (or via thin MCP wrapper)   │  mcp.ts     MCP → HTTP          │
+                                 └────────────┬───────────────────┘
+human browser ── WS /ws/:id ──────────────────┘   live updates
+  └─ packages/web  (tldraw renders the nodes)
+```
+
+- **Server** owns the store (SQLite), the HTTP agent API, and a dead-simple WS broadcast for live updates (we own the sync — no dependency on a fragile external sync layer). `@tldraw/sync` full multiplayer/CRDT is a future upgrade.
+- **Web** is a tldraw canvas that loads a board's nodes and applies live `shape_added` events.
+- **MCP** is a thin stdio wrapper over the HTTP API, so MCP harnesses (Claude Code, Cursor) get ergonomic tools while any non-MCP agent uses HTTP directly.
+
+## Quick start
+
+```bash
+pnpm install
+pnpm test     # proves the content loop headlessly (add → read → snapshot)
+pnpm dev      # server on :8787, web on http://localhost:5190
+```
+
+Then, from an agent (HTTP):
+
+```bash
+# open a board
+curl -s -XPOST localhost:8787/api/boards -d '{"title":"demo"}'
+# add a shape (agent write → same doc the canvas renders)
+curl -s -XPOST localhost:8787/api/boards/<id>/shapes -d '{"text":"hello parleyd","x":40,"y":40}'
+# read it back
+curl -s localhost:8787/api/boards/<id>/canvas
+```
+
+Open `http://localhost:5190/#<id>` in a browser and watch agent writes appear live.
+
+## Status
+
+Early scaffold (`0.0.1`). The headless content loop is tested and green; the browser render + live sync are wired and verified by opening the web app. Roadmap: full tldraw multiplayer sync, snapshot export (PNG/SVG), auth for hosted use, the `@sandrise/agent-canvas` library extraction.
+
+MIT.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "parleyd",
+  "version": "0.0.1",
+  "private": false,
+  "description": "A minimal, standalone, live agent↔human canvas — agents and humans co-think on one shared board in real time.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@10.28.2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SandRiseStudio/parleyd.git"
+  },
+  "keywords": ["agent", "whiteboard", "canvas", "tldraw", "mcp", "collaboration", "brainstorm"],
+  "files": ["README.md"],
+  "scripts": {
+    "dev": "bash scripts/dev.sh",
+    "test": "pnpm --filter @parleyd/server test"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["better-sqlite3", "esbuild"]
+  }
+}