@cs4alhaider/screenbook 0.1.0

package/core/serve.js

@@ -0,0 +1,224 @@
+/* Static server for ScreenBook projects (EN-5, server-first).
+   - serves the project root, with /engine/* mounted from the engine package
+     (so examples and engine-less checkouts still work)
+   - no-cache headers everywhere — the ?v=N ritual dies here
+   - /__sb/health, /__sb/events (SSE live reload), /__sb/review/comments
+   - watches the project, auto-regenerates manifests, broadcasts changes */
+
+import http from 'node:http';
+import path from 'node:path';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import { readJSON, writeJSON } from './fsx.js';
+import { regenManifest } from './project.js';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.map': 'application/json'
+};
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { 'Cache-Control': 'no-store', ...headers });
+  res.end(body);
+}
+
+async function serveFile(res, absPath) {
+  try {
+    const data = await fsp.readFile(absPath);
+    send(res, 200, data, { 'Content-Type': MIME[path.extname(absPath).toLowerCase()] || 'application/octet-stream' });
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'EISDIR') send(res, 404, `Not found`);
+    else send(res, 500, `Read error: ${err.message}`);
+  }
+}
+
+/* Resolve a URL path inside a base dir; null on traversal attempts. */
+function safeJoin(base, urlPath) {
+  const decoded = decodeURIComponent(urlPath).replace(/\0/g, '');
+  const abs = path.normalize(path.join(base, decoded));
+  return abs.startsWith(path.normalize(base + path.sep)) || abs === path.normalize(base) ? abs : null;
+}
+
+function readBody(req, limit = 5 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > limit) { reject(new Error('body too large')); req.destroy(); }
+      else chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+/* Map a changed file to a live-reload event, or null to ignore. */
+function classify(rel) {
+  const p = rel.split(path.sep).join('/');
+  if (p.includes('node_modules/') || p.includes('.git/') || /\.tmp-/.test(p)) return null;
+  let m;
+  if ((m = /^features\/([^/]+)\/screens\/([^/]+)\.html$/.exec(p))) {
+    return { area: 'screens', feature: m[1], screen: m[2] };
+  }
+  if ((m = /^features\/([^/]+)\/screens\//.exec(p))) return { area: 'screens', feature: m[1] };
+  if ((m = /^features\/([^/]+)\/driver\.js$/.exec(p))) return { area: 'data', feature: m[1] };
+  if ((m = /^features\/([^/]+)\/data\//.exec(p))) return { area: 'data', feature: m[1] };
+  if ((m = /^features\/([^/]+)\/flows\.json$/.exec(p))) return { area: 'flows', feature: m[1] };
+  if ((m = /^features\/([^/]+)\/(feature|manifest)\.json$/.exec(p))) return { area: 'manifest', feature: m[1] };
+  if (/^themes\//.test(p)) return { area: 'theme' };
+  if (p === 'app.config.json') return { area: 'config' };
+  if (/^engine\//.test(p) && !/^engine\/(node_modules|examples)\//.test(p)) return { area: 'engine' };
+  return null;
+}
+
+export function startServer({ root, engineDir, port = 4600, quiet = false }) {
+  const clients = new Set();
+  const log = quiet ? () => {} : (...a) => console.log(...a);
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://x');
+    const p = url.pathname;
+
+    try {
+      if (p === '/' || p === '/index.html') {
+        send(res, 302, '', { Location: '/engine/index.html' });
+        return;
+      }
+
+      if (p === '/__sb/health') {
+        send(res, 200, JSON.stringify({ screenbook: true, version: '0.1.0', root: path.basename(root) }),
+          { 'Content-Type': 'application/json' });
+        return;
+      }
+
+      if (p === '/__sb/events') {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-store',
+          Connection: 'keep-alive'
+        });
+        res.write(':\n\n');
+        clients.add(res);
+        req.on('close', () => clients.delete(res));
+        return;
+      }
+
+      /* Theme Lab write-back: POST /__sb/theme/<id> → themes/<id>.json (atomic) */
+      if (p.startsWith('/__sb/theme/') && req.method === 'POST') {
+        const id = decodeURIComponent(p.slice('/__sb/theme/'.length));
+        if (!/^[a-z0-9][a-z0-9-]*$/i.test(id)) return send(res, 400, 'bad theme id');
+        const body = JSON.parse(await readBody(req) || '{}');
+        if (!body.theme?.modes?.light) return send(res, 400, 'theme must have modes.light');
+        await writeJSON(path.join(root, 'themes', `${id}.json`), body.theme);
+        log(`  🎨 theme saved: themes/${id}.json`);
+        send(res, 200, JSON.stringify({ saved: `themes/${id}.json` }), { 'Content-Type': 'application/json' });
+        return;
+      }
+
+      if (p === '/__sb/review/comments') {
+        const file = path.join(root, 'review', 'comments.json');
+        if (req.method === 'GET') {
+          const box = await readJSON(file, { comments: [] });
+          send(res, 200, JSON.stringify(box), { 'Content-Type': 'application/json' });
+        } else if (req.method === 'POST') {
+          const body = JSON.parse(await readBody(req) || '{}');
+          if (!Array.isArray(body.comments)) throw new Error('expected { comments: [...] }');
+          await writeJSON(file, { comments: body.comments });
+          send(res, 200, JSON.stringify({ saved: body.comments.length }), { 'Content-Type': 'application/json' });
+        } else {
+          send(res, 405, 'method not allowed');
+        }
+        return;
+      }
+
+      /* /engine/* always resolves inside the engine package — works even
+         when the project has no engine/ copy (examples, dev checkouts). */
+      if (p === '/engine' || p.startsWith('/engine/')) {
+        const sub = p === '/engine' ? '/index.html' : p.slice('/engine'.length);
+        const abs = safeJoin(engineDir, sub === '/' ? '/index.html' : sub);
+        if (!abs) return send(res, 403, 'forbidden');
+        await serveFile(res, abs);
+        return;
+      }
+
+      const abs = safeJoin(root, p);
+      if (!abs) return send(res, 403, 'forbidden');
+      await serveFile(res, abs);
+    } catch (err) {
+      send(res, 400, `Bad request: ${err.message}`);
+    }
+  });
+
+  /* ---------------- watch + broadcast ---------------- */
+
+  function broadcast(evt) {
+    const line = `data: ${JSON.stringify(evt)}\n\n`;
+    for (const c of clients) c.write(line);
+  }
+
+  const pendingRegen = new Map();   // feature → timer
+  const watchers = [];
+
+  function onFsEvent(base, rel) {
+    if (!rel) return;
+    const full = base === root ? rel : path.join('engine', rel);
+    const evt = classify(full);
+    if (!evt) return;
+    if (evt.area === 'screens' && evt.feature) {
+      clearTimeout(pendingRegen.get(evt.feature));
+      pendingRegen.set(evt.feature, setTimeout(async () => {
+        pendingRegen.delete(evt.feature);
+        try {
+          const r = await regenManifest(root, evt.feature);
+          if (r.written) log(`  ↻ manifest regenerated: features/${evt.feature}/manifest.json`);
+        } catch { /* mid-write scan; the next event retries */ }
+      }, 250));
+    }
+    broadcast(evt);
+  }
+
+  try {
+    watchers.push(fs.watch(root, { recursive: true }, (_e, rel) => onFsEvent(root, rel)));
+  } catch { /* recursive watch unsupported — live reload off */ }
+  const engineInsideRoot = path.resolve(engineDir).startsWith(path.resolve(root) + path.sep);
+  if (!engineInsideRoot) {
+    try {
+      watchers.push(fs.watch(engineDir, { recursive: true }, (_e, rel) => onFsEvent(engineDir, rel)));
+    } catch { /* optional */ }
+  }
+
+  const heartbeat = setInterval(() => { for (const c of clients) c.write(':hb\n\n'); }, 25000);
+
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      const actual = server.address().port;
+      resolve({
+        port: actual,
+        url: `http://127.0.0.1:${actual}`,
+        close: () => {
+          clearInterval(heartbeat);
+          for (const w of watchers) w.close();
+          for (const c of clients) c.end();
+          return new Promise((r) => server.close(r));
+        }
+      });
+    });
+  });
+}

package/docs/README.md

@@ -0,0 +1,21 @@
+# ScreenBook documentation
+
+Start here. Each guide is short, self-contained, and ordered by how you'll actually meet
+the tool.
+
+| Guide | Read it when |
+|-------|--------------|
+| [Getting started](getting-started.md) | First contact — prerequisites, install, your first project in five minutes |
+| [The studio](studio-guide.md) | A tour of every control in the shell: sidebar, dropdowns, flows, review, Theme Lab, self-test |
+| [Authoring](authoring-guide.md) | You're building screens by hand — the full contract for screens, data, scenarios, themes, flows, strings |
+| [CLI reference](cli.md) | Every command and flag |
+| [AI agents & MCP](mcp-agents.md) | Hooking ScreenBook to Claude Code (or any MCP client) so agents author screens for you |
+| [App mode](app-mode-guide.md) | Embedding an EXISTING single-page app instead of (or alongside) file-per-screen features |
+| [Troubleshooting](troubleshooting.md) | Something's red, blank, or missing |
+
+Two more references live at the repo root:
+
+- **[CLAUDE.md](../CLAUDE.md)** — the authoring contract written for AI agents (scaffolded
+  into every project by `init`; humans are welcome to read it too).
+- **[TESTING.md](../TESTING.md)** — the engine's own test map, if you're contributing to
+  ScreenBook itself.

package/docs/app-mode-guide.md

@@ -0,0 +1,79 @@
+# App mode — embedding an existing app
+
+You have a working single-page prototype and zero desire to rewrite it screen-by-screen.
+App mode puts the WHOLE app inside the studio: its views appear in the sidebar, deep links
+work, dark/RTL/scenario controls drive it — and for sealed apps, **not one byte of the
+app's files changes**.
+
+![A sealed app running inside the studio](shots/app-mode.png)
+
+## Register it
+
+```bash
+node engine/cli/screenbook.js app add legacy/index.html --device ios --chrome self
+```
+
+That writes an app-type feature:
+
+```json
+{ "id": "legacy", "title": "Legacy app", "type": "app",
+  "src": "legacy/index.html", "device": "ios", "chrome": "self",
+  "driver": "driver.js" }
+```
+
+- `device` picks the bezel; `chrome: "self"` means the app draws its own status/home bars
+  so the engine shows bezel only (no doubling). Use `"engine"` for apps with no chrome.
+- Same-origin is required for driven apps (the app is served from the project).
+
+## Two integration modes, one protocol
+
+**Driven (sealed apps).** `app add` scaffolds `features/<id>/driver.js` — a small script
+the shell injects into the app AFTER it loads. It teaches ScreenBook the app's internals:
+
+```js
+AppBridge.register({
+  title: 'Legacy',
+  screens: () => Object.keys(App.screens).map(id => ({ id, title: App.screens[id].title })),
+  go: (id) => App.go(id),
+  current: () => App.state.screen,
+  set: (env) => {                       // called live on every toggle
+    App.state.dark = env.mode === 'dark';
+    App.render();
+  },
+  scenarios: () => SCENARIOS.list,      // optional: surfaces the app's own 🎭
+  ignoreErrors: [/some-cdn-lib/]        // optional, narrow, commented — known 3rd-party noise
+});
+```
+
+The driver lives in YOUR project, not in the app — the app stays certified-untouched.
+Call `AppBridge.navigated(id)` when the app navigates itself (wrap its router once).
+
+**Cooperative (apps you can edit).** Skip the driver (`--cooperative`); the app includes
+one script and registers itself:
+
+```html
+<script src="../engine/app-bridge.js"></script>
+<script>AppBridge.register({ screens, go, current, set });</script>
+```
+
+`examples/spa-demo` is a complete working cooperative app.
+
+## What the shell does with it
+
+Sidebar lists the app-reported screens (with the app's own groups) · `#feature/screen`
+deep links → `go(id)` · in-app navigation reflects back into the URL · mode/dir/lang/theme
+tokens/scenario changes arrive live through `set(env)` · driver-reported scenarios populate
+the 🎭 dropdown · `flows.json` steps work over app screen ids.
+
+## The gate
+
+`validate` boots each app headlessly and requires: registration within 20s, at least one
+reported screen, and **a clean visit to every reported screen — zero console errors**.
+Driver bugs surface as `driver <fn>: <message>` rows. `ignoreErrors` patterns are for
+narrow, documented third-party noise only — everything else still fails.
+
+## Reference drivers
+
+This repo's root project embeds two real, sealed prototypes — `features/rahhal-ios/driver.js`
+(screen registry, dark/RTL state, scenario player, router wrap) and
+`features/rahhal-web/driver.js` (view/tab model) — read them when writing yours.

package/docs/authoring-guide.md

@@ -0,0 +1,129 @@
+# Authoring guide
+
+The whole product rests on one idea: **everything is a plain file an intern could read.**
+One screen = one HTML document. Data, scenarios, themes, flows, strings = small JSON files.
+
+## A feature
+
+```
+features/trip-planning/
+├── feature.json          { "id", "title", "icon", "description", "order" }
+├── manifest.json         DERIVED — never edit; the CLI/MCP regenerates it
+├── flows.json            guided walkthroughs (optional)
+├── i18n.json             strings for Engine.t (optional)
+├── data/
+│   ├── seed.json         the feature's mock data
+│   └── scenarios.json    named overlays over the seed
+└── screens/
+    ├── shared.css        optional feature-wide look — screens opt in per file
+    ├── shared.js         optional feature-wide helpers
+    └── 010-home.html     one file = one screen
+```
+
+## A screen
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Home</title>
+  <script type="application/json" id="screen-meta">
+  { "title": "Home", "description": "Entry point.", "order": 10,
+    "device": "ios", "status": "wip", "tags": ["core"] }
+  </script>
+  <script src="../../../engine/bridge.js"></script>
+  <link rel="stylesheet" href="shared.css">
+</head>
+<body>
+  <button data-go="020-detail">Open detail</button>
+  <script>
+    Engine.ready(function (data) { /* bind seed ⊕ scenario */ });
+  </script>
+</body>
+</html>
+```
+
+Rules that keep everything sane:
+
+- The **meta block is required** (`title` at minimum). `device`: `ios` 393×852 · `android`
+  412×915 · `web` 1280×760 · `none`. Optional: `devices: ["ios","android"]` (one screen,
+  several frames — switcher chips appear over the stage and the self-test covers every
+  listed device), `status`, `tags`, `group` (sidebar section), `statusBar: "light"|"dark"`,
+  `updated` (auto-stamped on CLI/MCP saves).
+- One bridge include, exactly that relative path. Style with theme tokens
+  (`var(--color-accent)`, `--font-*`, `--radius-*`, `--space-*`) and pad with
+  `var(--safe-top)` / `var(--safe-bottom)`.
+- Screens must render sensibly with **empty data** — guard your bindings.
+- Sheets/modals are hidden markup **inside** the screen that opens them.
+- Duplicated markup between screens is fine — there is no templating system, on purpose.
+  Shared look goes to `shared.css`/`shared.js`, included explicitly.
+- Numeric filename prefixes (`010-`, `020-`) order the sidebar and leave room to insert.
+- CDN libraries are allowed (iframes isolate them). Zero-JS screens are allowed.
+- Every screen opens standalone too (no shell): the bridge self-loads the theme + seed and
+  honors `?scenario=…&mode=dark&dir=rtl&lang=ar`.
+
+## The bridge API (inside screens)
+
+| | |
+|---|---|
+| `Engine.ready(cb)` | `cb(data)` when tokens + data are in. |
+| `Engine.data` | frozen seed ⊕ scenario, `{{today±N}}` dates resolved |
+| `Engine.state` | cross-screen KV: `get/set/subscribe/keys` — survives navigation, reset from the shell |
+| `Engine.go(id)` / `data-go` | navigate within the feature |
+| `Engine.t(key, {vars})` | strings from `i18n.json` (see below) |
+| `Engine.toast(msg)` | transient toast |
+| `Engine.env` | `{ mode, dir, lang, device, scenario, theme }` |
+
+## Mock data + scenarios
+
+`seed.json` is the demo-complete state. `scenarios.json` layers named states over it:
+
+```json
+{ "list": [
+  { "id": "default",  "icon": "🧪", "title": "Full demo" },
+  { "id": "new-user", "icon": "🆕", "title": "Brand-new user",
+    "remove": ["trips", "user.points"], "patch": { "user": { "isNew": true } } } ] }
+```
+
+`remove` deletes dot-paths, then `patch` deep-merges (arrays replace whole). Date tokens —
+`{{today}}`, `{{today+7}}`, `{{today-2}}` — resolve to real dates at injection, so
+"mid-trip today" demos truthfully forever. Model lifecycle states: new → mid → done → edge.
+
+## Themes
+
+`themes/<id>.json`, flattened to CSS variables (`color.ink-2` → `--color-ink-2`), dark as a
+delta over light. Edit visually in the 🎨 Theme Lab and Save. Register extra themes in
+`app.config.json`'s `themes` array; the first is the default.
+
+## Strings (optional)
+
+`i18n.json`, key-first — every key shows all its languages side by side:
+
+```json
+{ "home.title": { "en": "Trips", "ar": "الرحلات" },
+  "home.greet": { "en": "{name}, welcome back", "ar": "يا {name}، أهلاً بعودتك" } }
+```
+
+`Engine.t('home.greet', {name})` — fallback: active language → `defaultLanguage` → the key.
+Language switches reload the screen. Gaps show up as `validate` warnings, never blockers.
+
+## Flows
+
+```json
+{ "list": [ { "id": "pitch", "title": "The pitch", "icon": "✨",
+  "steps": [ { "screen": "010-home", "note": "Start empty.", "scenario": "new-user" },
+             { "screen": "020-detail", "note": "One tap deeper." } ] } ] }
+```
+
+Write notes as presenter narration; 3–7 steps; end on the money shot.
+
+## After editing by hand
+
+```bash
+node engine/cli/screenbook.js manifest .    # if you added/renamed screens
+node engine/cli/screenbook.js validate .    # the done gate
+```
+
+(Under `serve`, manifests regenerate automatically on save. MCP writes do both for you.)

package/docs/cli.md

@@ -0,0 +1,78 @@
+# CLI reference
+
+Run as `node engine/cli/screenbook.js <command>` (or `screenbook <command>` once the
+package is installed with npm and on your PATH). Every command takes an optional project
+directory (default: the current one; running from inside `engine/` resolves to its parent).
+
+## `init [dir] [--name X] [--force] [--app <src>] [--cooperative]`
+
+Scaffold a consumer project: `app.config.json`, starter theme, a `welcome` feature with one
+screen, `review/`, the agent authoring contract (`CLAUDE.md`) and the packaged skill
+(`.claude/skills/screenbook/`). Refuses to overwrite an existing project without `--force`.
+`--app path/to/index.html` additionally registers an existing SPA in that folder as an
+embedded app (driver scaffolded unless `--cooperative`).
+
+## `serve [dir] [--port 4600]`
+
+The dev server. Static hosting with:
+
+- `/engine/*` mounted from the package folder — projects and the bundled examples work even
+  without a local `engine/` copy
+- live reload over SSE — saving any project file refreshes the studio; screen edits reload
+  the current frame
+- automatic `manifest.json` regeneration when screens change
+- `review/comments.json` disk sync and 🎨 Theme-Lab **Save** (`POST /__sb/theme/<id>`)
+- `Cache-Control: no-store` on everything — stale-cache rituals don't exist here
+- `/` redirects to the studio
+
+## `manifest [dir]`
+
+Rescan `features/*/screens/*.html` → regenerate each feature's derived `manifest.json`
+(writes only on change; reports per-feature counts and any broken meta blocks).
+
+## `validate [dir] [--static] [--json]`
+
+The done gate, two halves:
+
+1. **Static** — config/feature wiring, screen contract lint (meta block, bridge include,
+   ids), dangling `data-go` targets, manifest freshness, scenario/flow references, theme
+   shape, i18n gaps (warnings), app-feature `src`/driver existence.
+2. **Browser** (skipped with `--static`) — headless Chrome renders **every screen × theme ×
+   light/dark × LTR/RTL**, asserting `Engine.ready`, meta present, zero console errors;
+   embedded apps must register and survive a visit to every screen they report.
+
+Exit code 0 = green. `--json` prints the full machine-readable report.
+
+## `screenshot [dir] --screen <feature>/<screen> [options]`
+
+Device-framed PNGs via headless Chrome. Options: `--mode light,dark` · `--dir ltr,rtl` ·
+`--scenario id` · `--theme id` · `--lang xx` · `--out dir` (default
+`review/screenshots/`). Comma lists produce a matrix.
+
+## `app add <src> [dir] [--id --title --icon --device --chrome self|engine --cooperative]`
+
+Embed an existing single-page app as an app-type feature. Scaffolds an injectable
+`driver.js` template (fill in `screens()` / `go()` / `set()`) unless `--cooperative`, in
+which case the app is expected to include `engine/app-bridge.js` itself. See
+[App mode](app-mode-guide.md).
+
+## `mcp [--root dir]`
+
+Start the stdio MCP server (18 authoring tools for AI agents). This is what makes the
+npx registration line work:
+
+```bash
+claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+```
+
+Nothing but JSON-RPC goes to stdout; server logs go to stderr. See
+[AI agents & MCP](mcp-agents.md).
+
+## `help` · `version`
+
+What you'd expect.
+
+## Exit codes
+
+`0` success/green · `1` operation failed (validate red, bad input to an operation) ·
+`2` usage errors (no project found, missing arguments, refused overwrite).

package/docs/getting-started.md

@@ -0,0 +1,88 @@
+# Getting started
+
+## Prerequisites
+
+| You need | For | Notes |
+|----------|-----|-------|
+| **Node.js ≥ 18** | the CLI, the dev server, the MCP server | the only hard requirement — check with `node --version` |
+| **A modern browser** | the studio itself | Chrome, Safari, Edge, Firefox — the viewer is plain ES modules, no build |
+| **Google Chrome installed** | `validate` and `screenshot` (headless checks) | used through `playwright-core`; see below if you don't have Chrome |
+| **Git** | recommended | ScreenBook writes plain files — git is your undo and your review tool |
+
+Nothing else. No bundler, no framework, no global installs. The viewer has **zero**
+dependencies; the CLI has exactly one *dev* dependency (`playwright-core`) used only for
+headless validation and screenshots.
+
+One-time setup for the headless checks:
+
+```bash
+cd engine
+npm i                       # installs playwright-core (~3s, no browser download)
+# no Chrome on this machine? use a bundled browser instead:
+npm i -D playwright && npx playwright install chromium
+```
+
+## Install
+
+ScreenBook lives INSIDE your project as a folder named `engine/`:
+
+```bash
+# today (from the repo):
+git clone https://github.com/cs4alhaider/screenbook my-prototypes/engine
+
+# after npm publish:
+#   npm i @cs4alhaider/screenbook   (then copy/link node_modules/@cs4alhaider/screenbook → engine/)
+```
+
+The folder name matters: screens reference `../../../engine/bridge.js` by convention.
+
+## Your first project — five minutes
+
+```bash
+cd my-prototypes
+node engine/cli/screenbook.js init . --name "My product"
+node engine/cli/screenbook.js serve .
+# → open http://127.0.0.1:4600
+```
+
+You now have:
+
+```
+app.config.json               project name · feature order · devices · themes · languages
+themes/default.json           design tokens (light + dark) — edit live in the 🎨 Theme Lab
+features/welcome/             one starter feature with one screen
+  feature.json · flows.json · data/seed.json · data/scenarios.json
+  screens/010-hello.html      ← copy this file to make your second screen
+review/comments.json          review pins land here
+CLAUDE.md                     the authoring contract (for you AND your AI agents)
+.claude/skills/screenbook/    packaged skill so Claude knows the rules instantly
+```
+
+Edit `features/welcome/screens/010-hello.html`, save — the browser reloads itself.
+Copy it to `020-something.html`, change the meta block's `title`/`order`, save — it's in
+the sidebar. That's the whole loop.
+
+Already have a single-page prototype? Embed it whole instead of rewriting:
+
+```bash
+node engine/cli/screenbook.js init . --app path/to/index.html
+```
+
+(see [App mode](app-mode-guide.md)).
+
+## The definition of done
+
+```bash
+node engine/cli/screenbook.js validate .
+```
+
+Green means: every screen renders in every theme × light/dark × LTR/RTL with **zero console
+errors**, all metadata is present, every navigation target exists. Make it your habit —
+it's the same gate AI agents are held to.
+
+## Serving without the CLI
+
+Any static server works once `engine/` is copied into the project
+(`python3 -m http.server`, nginx, GitHub Pages…). You lose the live extras — auto-reload,
+manifest regeneration, review-comment disk sync, Theme-Lab save — but the studio, screens,
+scenarios and flows all work. `/engine/index.html` is the entry point.

package/docs/mcp-agents.md

@@ -0,0 +1,60 @@
+# AI agents & MCP
+
+ScreenBook is built agents-first: the MCP server gives any MCP client (Claude Code, etc.)
+a complete authoring surface, and the tool descriptions teach the contract — **agents never
+need to read the engine's source**.
+
+## Hook it up (Claude Code)
+
+The standard local-MCP form, via npx (no install needed):
+
+```bash
+claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+```
+
+Working from a checkout instead (engine copied into the project)? Point at it directly:
+
+```bash
+claude mcp add screenbook -- node engine/cli/screenbook.js mcp --root .
+```
+
+`--root` points at the project (the folder with `app.config.json`). `init` has already
+dropped `CLAUDE.md` and the `screenbook` skill into the project, so a fresh Claude session
+knows the rules the moment it opens the folder.
+
+## What agents can do
+
+Read: `list_features` · `list_screens` · `get_screen` · `get_data` (seed + scenarios +
+i18n) · `get_theme` · `get_flows` · `get_review_comments`
+
+Write (validated, atomic, manifest-refreshing, date-stamping):
+`add_screen` · `update_screen` · `remove_screen` · `add_feature` · `add_app` ·
+`set_data` · `set_theme` · `set_flows` · `resolve_comment`
+
+Verify: `validate {mode: "static"|"full"}` · `screenshot {feature, screen, …}`
+
+Guardrails built in: `add_screen`/`update_screen` lint the screen contract and reject
+violations with actionable messages; `add` fails on existing screens and `update` on
+missing ones (read-then-write); every write is atomic; `manifest.json` is regenerated for
+you.
+
+## A working prompt
+
+> Add a checkout screen to the shop feature: order summary card, payment method list from
+> the seed, a pay button that toasts. Match the existing screens' style. Validate and give
+> me a screenshot.
+
+A well-behaved agent will `list_screens` → `get_screen` (borrow idioms) → `add_screen` →
+`validate` → `screenshot`. Human taste, machine discipline.
+
+## The review loop
+
+Humans pin comments in 📌 Review Mode; each pin carries screen, scenario, theme, mode,
+direction and the CSS path of the clicked element. Agents read them
+(`get_review_comments {unresolvedOnly: true}`), fix the screens, and `resolve_comment` —
+a full design-review cycle without a meeting.
+
+## Serving + MCP together
+
+Run `serve` while agents work: every MCP write triggers live reload, so you watch screens
+appear and change in the studio in real time.