@cs4alhaider/screenbook 0.1.0 → 0.2.0

package/README.md

@@ -1,208 +1,186 @@
 # ⧉ ScreenBook
 
-**A static, no-build prototype studio — built for AI agents to author, humans to review.**
+**Your local design studio for prototyping real products with AI agents — offline, versioned, and owned by you.**
 
-Drop folders of plain HTML screens plus small JSON files into a project and get a navigable,
-device-framed design gallery: iPhone / Android / browser frames, mock-data scenarios, design-token
-themes, dark/light and LTR/RTL toggles, guided demo flows, pinned review comments, and a
-machine-verified self-test — plus a CLI and an MCP server so agents can build screens
-**without ever holding the engine's implementation in context**.
+ScreenBook turns a folder on your machine into a professional prototyping studio: every screen
+of your product rendered inside real device frames — iPhone, Android, browser — with live mock
+data, dark mode, right-to-left languages, guided demo walkthroughs, and a built-in design-review
+workflow. AI agents build and revise the screens through a standard interface; you and your
+stakeholders review, comment, and approve. When a screen is final, you hand that same file to
+your agent and say: *now build the native version.*
 
-![The ScreenBook studio — Qahwa demo project](docs/shots/hero-studio.png)
+![The ScreenBook studio](docs/shots/hero-studio.png)
 
-## Why this exists
-
-Prototyping with AI agents has a failure mode: the prototype starts as "just an HTML file,"
-grows into a hand-rolled single-page app, and after a month you have a 20k-line runtime where
-**an agent can't touch one screen without reading the whole world** — and neither can you.
+```bash
+npm install -g @cs4alhaider/screenbook
+```
 
-ScreenBook inverts every cause of that rot:
+## Why I built this
 
-| Instead of… | ScreenBook does… |
-|---|---|
-| One growing SPA runtime | **One file = one screen.** Full standalone HTML documents; each opens alone in a browser. |
-| Metadata trapped in code | **Metadata as data.** A JSON block inside each screen; indexes are derived, never hand-kept. |
-| App code and viewer code tangled | **A hard engine/app boundary.** Screens know one include (`bridge.js`) and a tiny API. |
-| Hard-coded demo data | **Seed + scenario overlays** with `{{today±N}}` date tokens — "mid-trip today" is literally today. |
-| CSS forks per restyle | **Design tokens as JSON themes**, flattened to CSS variables, dark mode as a delta. |
-| "Trust me, it works" | **A self-test gate**: every screen × theme × light/dark × LTR/RTL must render with zero console errors. |
+I design and ship products with AI agents every day. The prototyping phase kept failing me in
+the same way: designs lived inside chat windows. A concept would look great in a conversation,
+and then reality arrived — I needed *forty* screens, not one. I needed to see the empty state
+and the busy state. I needed Arabic right-to-left and dark mode. I needed my co-founder to
+point at a button and say "this one, move it." I needed all of it next week, again, revised.
 
-| | | |
-|---|---|---|
-| ![Web dashboard frame](docs/shots/web-dashboard.png) | ![Android frame, dark](docs/shots/android-dark.png) | ![Two-theme re-skin](docs/shots/theming-noir.png) |
-| Browser-chrome frame, scenario-driven data | Android frame, dark mode | Same screens, different theme JSON |
+Chat canvases aren't built for that. Every iteration re-generates a wall of code inside a
+conversation that will eventually scroll away. Nothing is versioned. Nothing runs offline.
+Reviews happen in screenshots over WhatsApp. And when the design is finally "done," it's
+trapped — there's no clean way to hand it to the next stage of work.
 
-## Setup
+So I built the thing I needed: a studio where **screens are plain files on my disk**, agents
+do the labor, humans do the taste, and the finished prototype becomes the specification for
+the real app.
 
-Requirements: **Node ≥ 18**. For headless validation/screenshots: Google Chrome (or see below).
+## Why not just design in Claude?
 
-Full guides live in **[docs/](docs/README.md)** — getting started & prerequisites, the
-studio tour, the authoring guide, CLI/MCP references, app mode, troubleshooting.
+Keep using Claude — that's the point. ScreenBook isn't a competitor to your AI; it's the
+**workspace your AI works in**. The difference is where the output lives and what you can do
+with it:
 
-```bash
-# 1. Put the engine into your project (this repo IS the engine — folder name matters):
-git clone https://github.com/cs4alhaider/screenbook my-prototypes/engine
-#    (npm: @cs4alhaider/screenbook — after first publish)
+| Designing in a chat window | Designing in ScreenBook |
+|---|---|
+| One artifact per conversation; multi-screen products fall apart | A whole product: features → screens, organized like your app actually is |
+| Output trapped in the thread; gone when context resets | Plain HTML + JSON files in **your git repo** — diff, branch, revert, forever |
+| Needs the vendor's website, account, and connection | Runs from a folder on your machine — **works fully offline** |
+| Tied to one AI vendor's canvas | **Any agent** that speaks MCP (Claude Code today; the protocol is open) — or no agent at all, it's just files |
+| One rendering, usually desktop-ish | Real device frames: iPhone, Android, browser — plus dark/light, LTR/RTL, and named data states you switch live |
+| "Looks right" is the only test | A machine gate: every screen must render in every theme × mode × direction with **zero console errors** |
+| Feedback = screenshots and paragraphs | **Pin comments on the screen itself**; your agent reads them, fixes, and marks them resolved |
+| Regenerates everything each round | Agent edits one small file per screen — faster, cheaper, and nothing else breaks |
 
-# 2. Scaffold the project around it:
-cd my-prototypes
-node engine/cli/screenbook.js init .
+## What working in it feels like
 
-# 3. Run the studio:
-node engine/cli/screenbook.js serve .
-# → http://127.0.0.1:4600  · live reload · manifests auto-regenerate · no cache, ever
-```
+A concrete example — a specialty-coffee ordering app (it ships in `examples/qahwa`, so you can
+open exactly this):
 
-`init` creates `app.config.json`, a starter theme, a `welcome` feature with one screen — and
-drops **`CLAUDE.md`** (the authoring contract) plus a **packaged agent skill** into the project,
-so any AI agent that opens it immediately knows the rules.
+**1. You brief your agent, it builds screens.**
 
-For headless `validate` / `screenshot`, install the one dev dependency once:
+> *"Create an ordering feature: menu with our drinks from the seed data, a drink detail screen
+> with a size/milk customization sheet, a cart, and a live order-status screen. iPhone frames,
+> match our warm theme."*
 
-```bash
-cd engine && npm i        # playwright-core — drives your installed Chrome
-# no Chrome? use:  npm i -D playwright && npx playwright install chromium
-```
+The agent creates each screen as its own small HTML file. They appear in your studio's sidebar
+as they land — framed in an iPhone, styled by your design tokens, wired to your mock data.
 
-Try the shipped examples first:
+**2. You review like it's a real app.** Click through the flow. Flip the 🎭 scenario dropdown
+from *Regular morning* to *First visit* — the same screens now show the empty state honestly.
+Toggle dark mode. Switch to Arabic and watch the layout mirror right-to-left. Nothing is
+staged; the "order ready by 08:44" timestamp is computed from *today* every time you demo.
 
-```bash
-node engine/cli/screenbook.js serve engine/examples/qahwa       # ☕ coffee app: iOS + Android + web
-node engine/cli/screenbook.js serve engine/examples/tokens-lab  # 🎨 two themes, live token lab
-```
+![Scenario-driven data on a real dashboard frame](docs/shots/web-dashboard.png)
 
-## How it helps — a five-minute story
-
-**1. A screen is one honest file.** No framework, no build, one conventional include:
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <script type="application/json" id="screen-meta">
-  { "title": "Cart", "description": "Lines, totals, checkout.",
-    "order": 30, "device": "ios", "status": "wip" }
-  </script>
-  <script src="../../../engine/bridge.js"></script>
-</head>
-<body>
-  <button data-go="040-checkout">Checkout</button>
-  <script>
-    Engine.ready(function (data) { /* seed ⊕ active scenario, dates resolved */ });
-  </script>
-</body>
-</html>
-```
+**3. Your team comments on the pixels, not around them.** Turn on 📌 Review Mode and click
+anywhere: each pin captures the screen, the data state, the theme, the mode, the direction,
+and the exact element under the cursor. Then:
 
-Save it under `features/shop/screens/030-cart.html` — it's already in the sidebar, framed as an
-iPhone, styled by your tokens (`var(--color-accent)`), live-reloading on every save.
+> *"Read the open review comments, apply the fixes, and resolve them."*
 
-**2. Colors are a panel, not a hunt.** The 🎨 **Theme Lab** shows every token the active theme
-defines and edits them **live against the hosted screens** — color pickers for hex values,
-plain fields for fonts/radii/spacing, a theme switcher, Export, and one-click **Save** straight
-back to `themes/<id>.json` while `serve` runs:
+Your agent does exactly that — it has tools for reading pins and marking them resolved.
 
-![Theme Lab — live token editing](docs/shots/theme-lab.png)
+**4. The finished screen becomes the spec for the real app.** This is the step that pays for
+everything. When a screen survives review, it's a complete, self-contained HTML file: exact
+layout and spacing, your design tokens, final copy in both languages, all interaction states.
+Now point your agent at it:
 
-**3. States are data, not branches.** Add a scenario and the 🎭 dropdown demos your empty state:
+> *"Take `features/order/screens/030-cart.html` and build it as a SwiftUI view. Use our design
+> tokens for colors and spacing. Preserve the empty state exactly as the `first-visit` scenario
+> shows it."*
 
-```json
-{ "id": "first-visit", "icon": "🆕", "title": "First visit",
-  "remove": ["order"], "patch": { "user": { "isNew": true } } }
-```
+The prototype you approved *is* the design document — no Figma-to-code guesswork, no "it looked
+different in the mockup." The same works for Jetpack Compose, React Native, Flutter, or web
+components.
 
-**4. Demos tell themselves.** A `flows.json` walkthrough gives stakeholders a guided,
-captioned story — each step can pin its own scenario, and every state is a shareable URL:
-`…#shop/030-cart?scenario=first-visit&mode=dark&dir=rtl`.
+![One click from English light to Arabic dark](docs/shots/rtl-arabic.png)
 
-**5. Review closes the loop.** Reviewers pin comments directly on screens; each pin captures
-screen, scenario, theme, mode, direction and the exact element clicked, and syncs to
-`review/comments.json` — where agents read and resolve them.
+## Two commands to your own studio
 
-**6. The machine decides "done".**
+Requirements: Node ≥ 18. Nothing else — no cloning, no per-project installs. (The automated
+screen checks use your installed Chrome, or download a headless browser once by themselves.)
 
 ```bash
-node engine/cli/screenbook.js validate .
-# ✓ static contract checks
-# ✓ 28/28 render checks green across 7 screens   (× themes × dark/light × ltr/rtl, zero console errors)
+npm install -g @cs4alhaider/screenbook    # once, ever
+
+cd any-project-you-are-working-on
+screenbook init                           # creates .screenbook/ — that's the whole setup
+screenbook serve                          # → http://127.0.0.1:4600 — live reload, no cache headaches
 ```
 
-## The agent workflow (the actual point)
+`init` creates a single **`.screenbook/`** folder in your project — the self-contained source
+of truth for the prototype: your **`brief.md`** (requirements — agents read it first), screens,
+mock data, scenarios, themes, review comments, and the agent authoring contract. Commit it or
+gitignore it; that's your call. The studio itself always runs from the installed package —
+your project never carries runtime code.
 
-Register the MCP server with your agent — for Claude Code:
+Connect your agent (Claude Code shown; any MCP client works):
 
 ```bash
 claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
-# or from a checkout:  claude mcp add screenbook -- node engine/cli/screenbook.js mcp --root .
 ```
 
-Then ask for work in plain language:
-
-> *"Add a checkout screen to the shop feature: summary card, payment method list from the seed,
-> a pay button that toasts. Match the existing screens. Validate and show me a screenshot."*
-
-The agent never opens `engine/` — it calls `list_screens` → `get_screen` (steals an existing
-screen's idioms) → `add_screen` (which **lints the contract, stamps the date, regenerates the
-manifest, writes atomically**) → `validate` (full headless render matrix) → `screenshot`
-(a PNG inside the real device frame). Human taste, machine discipline.
-
-18 tools: `list_features · list_screens · get_screen · add_screen · update_screen ·
-remove_screen · add_feature · get_data · set_data · get_theme · set_theme · get_flows ·
-set_flows · get_review_comments · resolve_comment · validate · screenshot · add_app`.
-
-## CLI
-
-| Command | Does |
-|---|---|
-| `init [dir] [--name X]` | Scaffold a project + authoring contract + agent skill |
-| `serve [dir] [--port]` | Studio server: live reload, auto-manifests, review sync, `/engine/*` mounted from this package, no-cache always |
-| `manifest [dir]` | Rescan screens → regenerate derived `manifest.json` per feature |
-| `validate [dir] [--static] [--json]` | Contract checks + headless render of every screen × theme × mode × direction |
-| `screenshot [dir] --screen f/s [--mode light,dark] [--dir ltr,rtl] [--scenario id] [--theme id]` | Device-framed PNGs (comma lists = matrix) |
-
-## What's in this repo
-
-```
-bridge.js        the ONLY file screens include (dual-mode: shell-driven / standalone)
-index.html + shell/   the studio: frames, dropdowns, flows, review mode, selftest
-core/            shared project API (scan, manifests, atomic writes, validate, serve, browser)
-cli/ · mcp/      two thin faces over the same core
-CLAUDE.md        the authoring contract agents follow (scaffolded into projects)
-skill/           packaged agent skill + reference docs (scaffolded into projects)
-examples/        qahwa (☕ 3-device demo app) · tokens-lab (🎨 multi-theme lab)
-test/            42-test suite: unit + serve E2E + CLI E2E   →  npm test
-TESTING.md       the full test map and gaps
-```
-
-RTL and Arabic are first-class (`dir` flipping, per-screen language dictionaries):
-
-<img src="docs/shots/rtl-arabic.png" width="320" alt="RTL Arabic screen in dark mode">
-
-## App mode — embed entire existing apps
-
-Already have a single-page prototype? Don't rewrite it — **embed it**:
+Want to explore first? Complete demo projects ship inside the package:
 
 ```bash
-node engine/cli/screenbook.js app add legacy/index.html --device ios --chrome self
+screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/qahwa"       # ☕ iPhone + Android + web
+screenbook serve "$(npm root -g)/@cs4alhaider/screenbook/examples/tokens-lab"  # 🎨 two themes, edited live
 ```
 
-The app's views appear in the sidebar as screens, deep links work, dark/RTL/scenario toggles
-drive it live. Cooperative apps include `engine/app-bridge.js` and register themselves
-(`examples/spa-demo`); sealed apps get a small project-owned **driver** injected at runtime —
-**zero changes to the app's own files**. `validate` boots each app and visits every screen it
-reports, still demanding zero console errors.
+## What's in the box
+
+- **Device frames** — iPhone (Dynamic Island, status bar), Android (punch-hole), browser
+  chrome, or bare; scaled to fit, screenshot-ready.
+- **Data scenarios** — named states over your mock data (*brand-new user*, *mid-trip*,
+  *after close*) with date tokens like `{{today+3}}`, so time-based demos are always true.
+- **Theme Lab** — every design token visible and editable live against your screens; save
+  writes the JSON back to disk. Dark mode is a delta, not a fork.
+
+  ![Theme Lab](docs/shots/theme-lab.png)
+- **Flows** — guided, captioned walkthroughs for stakeholder demos; every step is a shareable
+  URL that opens in the exact state (screen, data, theme, direction).
+- **Review Mode** — pinned comments with full context, synced to a JSON file your agent reads
+  and resolves.
+- **Multilingual by design** — per-feature strings files with side-by-side translations;
+  right-to-left is a first-class toggle, not an afterthought.
+- **Embed existing prototypes** — already have a working single-page prototype? One command
+  mounts the *whole app* inside the studio without touching its files
+  (`screenbook app add legacy/index.html`) — see [App mode](docs/app-mode-guide.md).
+- **A machine-verified quality gate** — `screenbook validate` renders every screen in every
+  theme × light/dark × LTR/RTL and fails on any console error. Green means done — for humans
+  and agents alike.
+- **CLI + 18 agent tools** — everything above is scriptable and agent-operable:
+  create screens, update data, restyle themes, take device-framed screenshots, run the gate.
+
+Full guides: **[docs/](docs/README.md)** — getting started, the studio tour, the authoring
+contract, CLI and agent references, troubleshooting.
+
+## The shape of a project
 
-![A sealed legacy app running inside the studio](docs/shots/app-mode.png)
-
-## Status
+```
+my-product/                          ← your real project, any stack, untouched
+└── .screenbook/                     ← everything ScreenBook, in one folder
+    ├── brief.md                     your requirements — agents read this FIRST
+    ├── app.config.json              product name · features · devices · themes · languages
+    ├── CLAUDE.md                    the authoring contract agents follow
+    ├── themes/default.json          design tokens (light + dark)
+    ├── features/
+    │   └── order/
+    │       ├── feature.json         title, icon, order
+    │       ├── flows.json           demo walkthroughs
+    │       ├── i18n.json            strings, side-by-side languages
+    │       ├── data/seed.json       mock data
+    │       ├── data/scenarios.json  named data states
+    │       └── screens/
+    │           ├── 010-menu.html    ← one file = one screen
+    │           └── 020-drink.html
+    └── review/comments.json         pinned feedback, read by your agent
+```
 
-**v1 — complete and machine-verified** (studio, 4 frames, scenarios, flows, Theme Lab,
-review mode, selftest, CLI, MCP, agent onboarding, example projects, 44-test suite).
-**v2 — in progress**: app mode ✓ shipped (above) · theme write-back ✓ (Theme Lab Save) ·
-i18n strings ✓ (`Engine.t` + key-first per-feature `i18n.json`, fallback chain, validate
-warnings on gaps) · npm packaging next.
+Everything is a plain file an intern could read. That's the whole trick: it's why agents stay
+fast and cheap (they touch one small file at a time), why git can review every change, why it
+works on a plane, and why the approved prototype can walk straight into production.
 
-Born inside [Rahhal](https://github.com/cs4alhaider)'s product lab, where the predecessor
-prototypes grew to ~22k lines and taught every lesson this engine inverts.
+## Status & license
 
-License: MIT.
+v0.2.0 — studio, frames, scenarios, themes, flows, review, i18n, app mode, self-test gate,
+CLI, MCP server, docs, and a 64-test suite; built and verified end-to-end with AI agents,
+reviewed by a human with taste. MIT © [Abdullah Alhaider](https://github.com/cs4alhaider).

package/bridge.js

@@ -12,7 +12,7 @@
 (function () {
   'use strict';
 
-  var VERSION = '0.1.0';
+  var VERSION = '0.2.0';
 
   /* ------------------------------------------------------------------ *
    *  EngineKit — pure helpers shared by bridge (screens) and shell

package/cli/screenbook.js

@@ -10,7 +10,7 @@ import { startServer } from '../core/serve.js';
 import * as T from './templates.js';
 
 const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const VERSION = '0.1.0';
+const VERSION = '0.2.0';
 
 /* ---------------- arg parsing ---------------- */
 
@@ -48,13 +48,17 @@ async function requireRoot() {
 /* ---------------- commands ---------------- */
 
 async function cmdInit() {
-  const dir = path.resolve(positional[0] || '.');
+  /* Everything lands in <project>/.screenbook/ — the self-contained source of
+     truth for the prototype. The user decides to commit or gitignore it.
+     No cloning, no runtime copy: `serve` mounts the studio from this package. */
+  const projectDir = path.resolve(positional[0] || '.');
+  const dir = path.join(projectDir, '.screenbook');
   const configPath = path.join(dir, 'app.config.json');
   if (await exists(configPath) && !flags.force) {
-    console.error(bad(`app.config.json already exists in ${dir} — refusing to overwrite (use --force).`));
+    console.error(bad(`.screenbook/ already exists in ${projectDir} — refusing to overwrite (use --force).`));
     process.exit(2);
   }
-  const name = flags.name || path.basename(dir);
+  const name = flags.name || path.basename(projectDir);
   const day = today();
 
   await mkdirp(path.join(dir, 'features/welcome/screens'));
@@ -63,6 +67,7 @@ async function cmdInit() {
   await mkdirp(path.join(dir, 'review'));
 
   await writeJSON(configPath, T.APP_CONFIG(name));
+  await writeAtomic(path.join(dir, 'brief.md'), T.BRIEF(name));
   await writeJSON(path.join(dir, 'themes/default.json'), T.DEFAULT_THEME);
   await writeJSON(path.join(dir, 'review/comments.json'), { comments: [] });
   await writeJSON(path.join(dir, 'features/welcome/feature.json'), T.WELCOME_FEATURE);
@@ -71,39 +76,45 @@ async function cmdInit() {
   await writeJSON(path.join(dir, 'features/welcome/flows.json'), T.WELCOME_FLOWS);
   await writeAtomic(path.join(dir, 'features/welcome/screens/010-hello.html'), T.WELCOME_SCREEN(day));
 
-  /* agent onboarding ships with the product (EN-32) */
-  const claudeMd = path.join(dir, 'CLAUDE.md');
-  if (!(await exists(claudeMd))) {
-    const contract = await readTextSafe(path.join(ENGINE_DIR, 'CLAUDE.md'));
-    if (contract) await writeAtomic(claudeMd, contract);
-  }
+  /* Agent onboarding, multi-agent (Abdullah's panel picks):
+     - the full contract at .screenbook/AGENTS.md (the 2026 open standard —
+       Codex, Cursor, Gemini, Copilot AND Claude Code read it natively)
+     - .screenbook/CLAUDE.md as a 3-line pointer for older Claude versions
+     - the skill in BOTH standard locations: .agents/skills/ + .claude/skills/
+     - a marked, idempotent breadcrumb appended to the PROJECT's root AGENTS.md */
+  const contract = await readTextSafe(path.join(ENGINE_DIR, 'AGENTS.md'));
+  if (contract) await writeAtomic(path.join(dir, 'AGENTS.md'), contract);
+  await writeAtomic(path.join(dir, 'CLAUDE.md'), T.CLAUDE_POINTER);
   const skillSrc = path.join(ENGINE_DIR, 'skill');
   if (await exists(skillSrc)) {
-    await copyDir(skillSrc, path.join(dir, '.claude/skills/screenbook'));
+    await copyDir(skillSrc, path.join(projectDir, '.claude/skills/screenbook'));
+    await copyDir(skillSrc, path.join(projectDir, '.agents/skills/screenbook'));
   }
+  await upsertRootPointer(projectDir);
 
   await regenAllManifests(dir);
 
-  /* `init --app <path>`: register an existing SPA in this folder as an
-     embedded app in the same breath (Abdullah's flow: point ScreenBook at
-     any folder that already contains an app). */
+  /* `init --app <path>`: register an existing SPA from the USER'S project as
+     an embedded app — recorded as project/<path>, served via the /project mount. */
   if (flags.app) {
-    const rel = path.relative(dir, path.resolve(flags.app)) || flags.app;
+    const rel = path.relative(projectDir, path.resolve(flags.app));
+    if (rel.startsWith('..')) {
+      console.error(bad(`--app must point inside ${projectDir}`));
+      process.exit(2);
+    }
     const r = await addApp(dir, {
-      src: rel.split(path.sep).join('/'),
+      src: `project/${rel.split(path.sep).join('/')}`,
       driver: !flags.cooperative
     });
     console.log(ok(`✓ app registered: ${r.feature.id}`) + dim(` → ${r.feature.src}`));
-    if (r.driver) console.log(`  fill in ${bold(r.driver)} to teach ScreenBook the app's internals`);
+    if (r.driver) console.log(`  fill in ${bold('.screenbook/' + r.driver.replace(/^features\//, 'features/'))} to teach ScreenBook the app's internals`);
   }
 
-  console.log(ok(`✓ ScreenBook project scaffolded in ${dir}`));
-  console.log(`  app.config.json · themes/default.json · features/welcome/ · review/`);
-  console.log(`  CLAUDE.md + .claude/skills/screenbook/ ${dim('(agent authoring contract)')}`);
-  if (!(await exists(path.join(dir, 'engine')))) {
-    console.log(dim(`  note: no engine/ folder here — ${bold('screenbook serve')} mounts it automatically;`));
-    console.log(dim(`  copy the engine folder in when you want plain static servers to work too.`));
-  }
+  console.log(ok(`✓ ScreenBook ready — everything lives in ${bold('.screenbook/')}`));
+  console.log(`  ${bold('brief.md')} ${dim('(write your requirements here — agents read it first)')}`);
+  console.log(`  app.config.json · themes/ · features/welcome/ · review/ · AGENTS.md ${dim('(+CLAUDE.md pointer)')}`);
+  console.log(`  agent setup: root AGENTS.md section · .agents/skills/ + .claude/skills/ ${dim('(Claude, Codex, Cursor, Gemini, …)')}`);
+  console.log(dim(`  commit .screenbook/ or add it to .gitignore — your call; it is the source of truth.`));
   console.log(`\nNext: ${bold(`screenbook serve ${positional[0] || '.'}`)}  → http://127.0.0.1:4600`);
 }
 
@@ -112,6 +123,25 @@ async function readTextSafe(p) {
   catch { return null; }
 }
 
+/* Root AGENTS.md breadcrumb: create the file if missing; if it exists, replace
+   only the marked ScreenBook section (or append it) — user content is never touched. */
+async function upsertRootPointer(projectDir) {
+  const file = path.join(projectDir, 'AGENTS.md');
+  const START = '<!-- screenbook:start -->';
+  const END = '<!-- screenbook:end -->';
+  const existing = await readTextSafe(file);
+  if (existing === null) {
+    await writeAtomic(file, T.ROOT_POINTER + '\n');
+    return;
+  }
+  const s = existing.indexOf(START);
+  const e = existing.indexOf(END);
+  const next = (s >= 0 && e > s)
+    ? existing.slice(0, s) + T.ROOT_POINTER + existing.slice(e + END.length)
+    : existing.replace(/\s*$/, '') + '\n\n' + T.ROOT_POINTER + '\n';
+  if (next !== existing) await writeAtomic(file, next);
+}
+
 async function copyDir(src, dest) {
   const fs = await import('node:fs/promises');
   await fs.mkdir(dest, { recursive: true });
@@ -123,8 +153,8 @@ async function cmdServe() {
   const port = parseInt(flags.port || '4600', 10);
   const srv = await startServer({ root, engineDir: ENGINE_DIR, port });
   console.log(bold(`⧉ ScreenBook`) + ` serving ${dim(root)}`);
-  console.log(`  studio   ${ok(srv.url + '/engine/index.html')}`);
-  console.log(`  selftest ${dim(srv.url + '/engine/index.html?selftest=1')}`);
+  console.log(`  studio   ${ok(srv.url + '/screenbook/')}`);
+  console.log(`  selftest ${dim(srv.url + '/screenbook/?selftest=1')}`);
   console.log(`  live reload + manifest refresh + review sync ${ok('on')} ${dim('(no-cache always)')}`);
 }
 
@@ -205,8 +235,17 @@ async function cmdApp() {
   }
   positional.splice(0, 2, positional[2]);   // remaining positional = project dir
   const root = await requireRoot();
-  const rel = path.isAbsolute(srcArg)
-    ? path.relative(root, srcArg).split(path.sep).join('/')
+
+  /* Normalize src: apps usually live in the USER'S project. With a .screenbook
+     root, record them as project/<path> (served via the /project mount).
+     Relative paths are taken relative to the project directory. */
+  const isDotRoot = path.basename(root) === '.screenbook';
+  const projectDir = isDotRoot ? path.dirname(root) : root;
+  const absSrc = path.isAbsolute(srcArg) ? srcArg : path.resolve(projectDir, srcArg);
+  const fromRoot = path.relative(root, absSrc);
+  const fromProject = path.relative(projectDir, absSrc);
+  const rel = !fromRoot.startsWith('..') ? fromRoot.split(path.sep).join('/')
+    : isDotRoot && !fromProject.startsWith('..') ? `project/${fromProject.split(path.sep).join('/')}`
     : srcArg;
   const r = await addApp(root, {
     src: rel,

package/cli/templates.js

@@ -87,7 +87,7 @@ export const WELCOME_SCREEN = (today) => `<!DOCTYPE html>
     "updated": "${today}"
   }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <style>
     * { box-sizing: border-box; }
     body {
@@ -137,3 +137,56 @@ export const WELCOME_SCREEN = (today) => `<!DOCTYPE html>
 export const GITIGNORE = `node_modules/
 .DS_Store
 `;
+
+/* Marked section appended to the PROJECT's root AGENTS.md so every agent
+   (Codex, Cursor, Gemini, Claude, …) discovers ScreenBook unprompted.
+   Idempotent: init replaces the content between the markers. */
+export const ROOT_POINTER =
+`<!-- screenbook:start -->
+## UI prototyping (ScreenBook)
+
+This project's UI prototypes live in **.screenbook/** — a [ScreenBook](https://github.com/cs4alhaider/screenbook) studio.
+Before designing or changing any screen: read **.screenbook/brief.md** (the requirements)
+and **.screenbook/AGENTS.md** (the authoring contract).
+Preview locally: \`screenbook serve\` → http://127.0.0.1:4600
+Agent tools (MCP, 18 tools): \`npx -y @cs4alhaider/screenbook mcp --root .\`
+<!-- screenbook:end -->`;
+
+export const CLAUDE_POINTER = `# ScreenBook
+
+The authoring contract for this prototype lives in **AGENTS.md** (same folder) — read
+that, plus **brief.md** for the product requirements, before creating or changing any
+screen.
+`;
+
+export const BRIEF = (name) => `# ${name} — product brief
+
+> **AI agents: read this file first, before creating or changing any screen.**
+> It is the source of truth for what we are building and why.
+
+## What we're building
+
+_One paragraph: the product, who it's for, the core promise._
+
+## The screens we need
+
+_List the features and screens you expect, roughly in user-journey order.
+Agents: turn each line into screens under features/, and ask (via review
+comments) when something here is ambiguous._
+
+- …
+
+## Design direction
+
+_Tone, references, the feeling. The design tokens in themes/ are the palette —
+change them there, not per-screen._
+
+## States that must exist
+
+_Empty / first-run · busy / real usage · edge cases. Agents: model these as
+data scenarios so every screen can be reviewed in each state._
+
+## Out of scope (for now)
+
+- …
+`;