@cs4alhaider/screenbook 0.1.0 → 0.2.1

package/docs/contributing/architecture.md

@@ -0,0 +1,153 @@
+# Architecture — how the engine works
+
+One mental model: **two worlds meeting at plain files.**
+
+- **The studio** runs in the browser — plain ES modules, zero dependencies, no build step.
+  It reads the project's JSON + HTML over HTTP and renders screens in iframes.
+- **The tooling** runs in Node — the CLI and the MCP server, sharing one core. Exactly one
+  dependency (`playwright-core`), used only for headless validation and screenshots.
+
+Nothing is generated, bundled, or transpiled. What's in the repo is what executes.
+
+## Repo map
+
+```
+bridge.js          the ONLY file a screen includes — Engine API + sb:* protocol + EngineKit
+app-bridge.js      runs inside an embedded SPA — AppBridge API + sba:* protocol
+index.html         the studio page (loads shell/main.js)
+shell/             the studio, one module per concern (see below)
+core/              Node core shared by CLI + MCP: fs, meta, project API, server, browser
+cli/screenbook.js  command dispatcher: init · serve · manifest · validate · screenshot · app · mcp
+cli/templates.js   everything `init` scaffolds into a fresh project
+mcp/server.js      stdio JSON-RPC MCP server — 18 tools over the same core
+skill/             the agent skill `init` copies into consumer projects
+examples/          runnable demo projects that double as test fixtures
+test/              the engine's own suite (node:test) — see the testing map
+```
+
+## The bridge (`bridge.js`)
+
+A screen is a standalone HTML document whose only obligation is a meta block and one
+script include: the bridge. It boots in one of two modes:
+
+- **Embedded** — the screen is inside the studio's iframe. The bridge sends `sb:hello`,
+  the shell answers `sb:init` with everything the screen needs (theme, mode, dir, lang,
+  merged data, i18n, review pins). Live changes arrive as `sb:update` / `sb:review`.
+- **Standalone** — the screen was opened directly. The bridge self-loads
+  `app.config.json`, the theme, seed + scenarios, and i18n from their conventional
+  relative paths, honoring `?scenario=…&mode=dark&dir=rtl&lang=…` — so a screen file is
+  demoable with zero infrastructure. If an `sb:hello` goes unanswered for 600ms (iframed
+  by something that isn't the shell), it falls back to standalone.
+
+The top half of the file is **EngineKit** — the pure logic both worlds must agree on:
+deep merge, scenario overlay (`remove` dot-paths, then `patch`), `{{today±N}}` date
+tokens, token flattening (`color.ink-2` → `--color-ink-2`), dark-over-light theme
+resolution, i18n lookup, and the CSS-path builder for review pins. The shell loads
+`bridge.js` too (with `window.__SCREENBOOK_SHELL__` set) purely to reuse this kit — the
+merge/flatten/date logic exists exactly once. The Node unit tests load the same file in a
+VM, so the browser and the tests exercise identical code.
+
+What screens see: `Engine.ready(cb)` · `Engine.data` (frozen) · `Engine.env` ·
+`Engine.state` (localStorage-backed KV that syncs across screens via `storage` events) ·
+`Engine.go` / `data-go` · `Engine.t` · `Engine.toast`.
+
+## The shell (`shell/`)
+
+A tiny unidirectional loop, no framework:
+
+```
+store.js  →  set(patch)  →  subscribers get the set of changed keys  →  each module
+             re-renders only what its keys touch  →  syncHash() mirrors state to the URL
+```
+
+| Module | Owns |
+|--------|------|
+| `store.js` | UI state, selectors, hash deep links (`#feature/screen?scenario=…&mode=…`) |
+| `net.js` | project loading (config, features, themes), serve detection, SSE, review persistence |
+| `main.js` | boot, toolbar wiring, keyboard, live reload, the change→render map |
+| `screenhost.js` | the mounted iframe: builds frames, speaks sb:*/sba:*, pushes env updates |
+| `frames.js` | device chrome (iPhone island/status bar, Android punch-hole, browser bar) + scale-to-fit |
+| `sidebar.js` | searchable, grouped screen list |
+| `toolbar.js` | dropdown/toggle/action chip widgets |
+| `flowplayer.js` | walkthrough playback; steps can pin scenarios; restores state on exit |
+| `review.js` | pins, the comments panel, disk/localStorage persistence |
+| `themelab.js` | live token editing; dark stays a delta; save writes `themes/<id>.json` |
+| `selftest.js` | the in-browser render matrix (below) |
+
+Two decisions carry most of the weight here. **Screens live in iframes** — full style and
+error isolation, which is what lets the gate say "zero console errors" and mean it. And
+**state changes are described, not performed** — `set({mode:'dark'})` doesn't touch the
+DOM; every interested module reacts, which is why deep links, flows, and the self-test can
+drive the studio through the same door the toolbar uses.
+
+## App mode (`app-bridge.js`)
+
+An embedded SPA mounts once and is *driven* over `sba:*` instead of being remounted per
+screen. The adapter (`screens()`, `go()`, optional `current()`/`set()`/`scenarios()`)
+gets registered in one of two ways: **cooperative** — the app includes `app-bridge.js`
+itself; **driven** — the shell injects the runtime plus a project-owned `driver.js` into
+the (same-origin) iframe after load, so the app's own files stay byte-untouched.
+
+## The Node core (`core/`)
+
+| Module | Owns |
+|--------|------|
+| `fsx.js` | atomic writes (temp + rename), change-detecting JSON writes — every CLI/MCP write goes through here |
+| `meta.js` | the screen-meta block: parse, rewrite, `updated` stamping, the screen lint, `data-go` extraction |
+| `project.js` | **the one Project API** both CLI and MCP import: root resolution, feature scan, derived manifests, screen CRUD with lint-on-write, data/theme/flow/comment accessors, static validation |
+| `serve.js` | the dev server: project root + `/screenbook/*` package mount + `/project/*` parent mount, no-cache everywhere, SSE live reload, watch → debounced manifest regen, review/theme write-back APIs |
+| `browser.js` | headless side: playwright→system-Chrome resolution ladder (auto-download as last resort), the headless self-test wrapper, framed screenshots via the shell's `?solo=1` |
+
+The CLI and the MCP server are both **thin faces over `project.js`** — same validation,
+same atomic writes, same manifest regeneration, whether a human or an agent is typing.
+`manifest.json` is always derived from the screens' meta blocks; it exists so the studio
+can boot on any dumb static server, but the CLI/MCP/serve regenerate it — never edit it.
+
+## The gate (`selftest.js` + `validate`)
+
+`?selftest=1` renders **every screen × device variant × theme × light/dark × LTR/RTL** in
+hidden iframes (a small worker pool), replaying the exact shell handshake per combo, and
+requires `Engine.ready` + a meta title + zero console errors. Embedded apps must register
+within 20s, report ≥1 screen, and survive a visit to every screen they report.
+`screenbook validate` = static checks from `project.js` first, then this same matrix run
+headlessly, with results read off `window.__selftestResult`. Green is the definition of
+done — for humans and agents alike.
+
+## The protocols
+
+| Message | Direction | Meaning |
+|---------|-----------|---------|
+| `sb:hello` | screen → shell | bridge booted; carries the parsed meta |
+| `sb:init` | shell → screen | full environment: theme, mode, dir, lang, device, scenario, data, i18n, review |
+| `sb:update` | shell → screen | live env change (theme/mode/dir/lang) — no reload |
+| `sb:review` | shell → screen | review state + pins to render |
+| `sb:ready` | screen → shell | `Engine.ready` callbacks ran; hide the veil |
+| `sb:go` | screen → shell | `data-go`/`Engine.go` navigation request |
+| `sb:console-error` | screen → shell | forwarded error (also feeds the self-test) |
+| `sb:pin-request` / `sb:pin-open` | screen → shell | review-mode clicks |
+| `sba:hello` / `sba:screens` / `sba:current` | app → shell | registration, screen list, navigation echo |
+| `sba:go` / `sba:env` | shell → app | drive navigation / apply environment live |
+
+## Rules that keep it simple
+
+1. **No build, ever.** The studio must run from a folder on disk. Adding a bundler is a
+   rejected feature, not a missing one.
+2. **The viewer has zero dependencies; the tooling has one.** Anything heavier belongs in
+   a consumer project, not here.
+3. **Screens are standalone documents.** Every screen must work opened directly — the
+   bridge's standalone mode is a contract, not a fallback.
+4. **Derived files are never hand-edited** (`manifest.json`), and **every write is
+   atomic** (`fsx.js`) — agents and humans share the same safety rails.
+5. **One core, two faces.** New authoring capability goes into `core/project.js` first;
+   the CLI command and the MCP tool are wrappers.
+
+## Adding things
+
+- **A CLI command** → implement against `core/project.js`, register it in the `commands`
+  map in `cli/screenbook.js`, document it in [the CLI reference](../reference/cli.md).
+- **An MCP tool** → same core call, plus an entry in `TOOLS` in `mcp/server.js` (schema +
+  description are the agent's documentation — write them like you'd brief a new hire).
+- **A studio control** → a widget in `main.js#buildControls()`, state in `store.js`, and a
+  reaction in `onChange`; if it must survive reload, add its key to the hash sync.
+- **Anything** → update [the testing map](testing.md) and keep `npm test` +
+  `validate` green on the examples.

package/{TESTING.md → docs/contributing/testing.md}

@@ -2,21 +2,26 @@
 
 > The "don't forget" file: every test layer, what it covers, how to run it, and where the
 > gaps are. Update this whenever a layer is added or a gap closes. Definition of done for
-> any engine change: **`npm test` green AND `validate` green on all four projects below.**
+> any engine change: **`npm test` green AND `validate` green on the bundled examples.**
 
 ## How to run everything
 
+From a checkout of this repo:
+
 ```bash
-cd engine
 npm i                # once — playwright-core (drives your installed Chrome)
-npm test             # unit + E2E suites (node:test, ~58 tests, ~60s incl. browser)
+npm test             # unit + E2E suites (node:test, 64 tests, ~60s incl. browser)
 
-# full browser matrix on every project that ships in this repo:
-node cli/screenbook.js validate ..                        # Rahhal (repo root)
+# full browser matrix on the projects that ship in this repo:
 node cli/screenbook.js validate examples/qahwa
 node cli/screenbook.js validate examples/tokens-lab
+node cli/screenbook.js validate examples/spa-demo
 ```
 
+Docs screenshots (`docs/shots/`, light + dark variants of every subject) are regenerated in
+one shot with `node tools/capture-shots.mjs` — it serves scratch copies of the examples, so
+nothing in the repo is mutated by the capture run.
+
 ## Layers
 
 | Layer | File(s) | Covers |
@@ -36,7 +41,7 @@ node cli/screenbook.js validate examples/tokens-lab
 
 | Project | Exercises |
 |---------|-----------|
-| repo root (Rahhal) | iOS frame, AR/RTL/i18n screens, scenarios with `remove`, flows, `statusBar` override, shared.css/js — **plus both certified prototypes embedded as driven apps** (`features/rahhal-ios` 31 screens · `features/rahhal-web` 11 screens, drivers injected, `docs/mockups/` byte-untouched) |
+| the maintainer's host project (not shipped) | iOS frame, AR/RTL/i18n screens, scenarios with `remove`, flows, `statusBar` override, shared.css/js — plus two certified, sealed prototypes embedded as **driven** apps (31 + 11 screens, drivers injected, app files byte-untouched) |
 | `examples/qahwa` | iOS + **Android** + **web** frames in one project, in-screen sheet (EN-24), `Engine.state` cart, feature groups, device filter |
 | `examples/tokens-lab` | **Multi-theme** (Theme ▾ + theme axis in the matrix), **bare `none` frame**, live token re-skin, MutationObserver pattern |
 | `examples/spa-demo` | **Cooperative app mode** — a one-page notes app including `app-bridge.js` itself; engine chrome on an app |
@@ -50,5 +55,5 @@ node cli/screenbook.js validate examples/tokens-lab
 - RTL screenshot diffing / visual regression (screenshots exist; no baseline comparison).
 - Windows: paths are POSIX-tested only; `fs.watch` recursive + rename semantics unverified.
 - `file://` standalone mode has no automated check (manual only; fallback tokens by design).
-- Driven-app injection path in the shell suite uses the cooperative mini-app only; the two
-  Rahhal drivers are covered by root `validate` (64/64), not by `npm test`.
+- Driven-app injection path in the shell suite uses the cooperative mini-app only; real
+  driven-app drivers are exercised in the maintainer's host project, not by `npm test`.

package/docs/{app-mode-guide.md → guides/app-mode.md}

@@ -5,20 +5,26 @@ App mode puts the WHOLE app inside the studio: its views appear in the sidebar,
 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)
+![A sealed app running inside the studio](../shots/app-mode-light.png)
 
 ## Register it
 
 ```bash
-node engine/cli/screenbook.js app add legacy/index.html --device ios --chrome self
+screenbook 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" }
+```jsonc
+{
+  "id": "legacy",              // feature id — the folder name under features/
+  "title": "Legacy app",       // shown in the Feature ▾ dropdown
+  "type": "app",               // app-type feature: one embedded SPA instead of file screens
+  "src": "legacy/index.html",  // project-relative entry point the studio mounts
+  "device": "ios",             // bezel: ios · android · web · none
+  "chrome": "self",            // the app draws its own status/home bars — bezel only
+  "driver": "driver.js"        // injected adapter (omitted for --cooperative apps)
+}
 ```
 
 - `device` picks the bezel; `chrome: "self"` means the app draws its own status/home bars
@@ -72,8 +78,9 @@ reported screen, and **a clean visit to every reported screen — zero console e
 Driver bugs surface as `driver <fn>: <message>` rows. `ignoreErrors` patterns are for
 narrow, documented third-party noise only — everything else still fails.
 
-## Reference drivers
+## Reference material
 
-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.
+For the **driven** path, `app add` scaffolds a fully commented `driver.js` template — its
+TODOs walk you through `screens()`, `go()` and `set()` against your app's real globals.
+For the **cooperative** path, `examples/spa-demo` inside the package is a complete working
+app to copy from.

package/docs/{authoring-guide.md → guides/authoring.md}

@@ -30,10 +30,16 @@ features/trip-planning/
   <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"] }
+  {
+    "title": "Home",
+    "description": "Entry point.",
+    "order": 10,
+    "device": "ios",
+    "status": "wip",
+    "tags": ["core"]
+  }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <link rel="stylesheet" href="shared.css">
 </head>
 <body>
@@ -80,11 +86,19 @@ Rules that keep everything sane:
 
 `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 } } } ] }
+```jsonc
+{
+  "list": [
+    { "id": "default", "icon": "🧪", "title": "Full demo" },  // baseline — the seed, untouched
+    {
+      "id": "new-user",
+      "icon": "🆕",
+      "title": "Brand-new user",
+      "remove": ["trips", "user.points"],       // 1. delete these dot-paths from the seed…
+      "patch": { "user": { "isNew": true } }    // 2. …then deep-merge this over what's left
+    }
+  ]
+}
 ```
 
 `remove` deletes dot-paths, then `patch` deep-merges (arrays replace whole). Date tokens —
@@ -101,9 +115,11 @@ delta over light. Edit visually in the 🎨 Theme Lab and Save. Register extra t
 
 `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}، أهلاً بعودتك" } }
+```jsonc
+{
+  "home.title": { "en": "Trips", "ar": "الرحلات" },
+  "home.greet": { "en": "{name}, welcome back", "ar": "يا {name}، أهلاً بعودتك" }  // {name} fills from Engine.t vars
+}
 ```
 
 `Engine.t('home.greet', {name})` — fallback: active language → `defaultLanguage` → the key.
@@ -111,10 +127,20 @@ Language switches reload the screen. Gaps show up as `validate` warnings, never
 
 ## 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." } ] } ] }
+```jsonc
+{
+  "list": [
+    {
+      "id": "pitch",
+      "title": "The pitch",
+      "icon": "✨",
+      "steps": [
+        { "screen": "010-home", "note": "Start empty.", "scenario": "new-user" },  // a step may pin a scenario
+        { "screen": "020-detail", "note": "One tap deeper." }                      // …the note is presenter narration
+      ]
+    }
+  ]
+}
 ```
 
 Write notes as presenter narration; 3–7 steps; end on the money shot.
@@ -122,8 +148,8 @@ 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
+screenbook manifest    # if you added/renamed screens
+screenbook validate    # the done gate
 ```
 
 (Under `serve`, manifests regenerate automatically on save. MCP writes do both for you.)

package/docs/guides/getting-started.md

@@ -0,0 +1,84 @@
+# 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 build step. The studio itself has **zero**
+dependencies; the CLI carries exactly one (`playwright-core`), used only for headless
+validation and screenshots — it comes along automatically with the install below. On a
+machine without Chrome, the first `validate` downloads a headless browser once, by itself.
+
+## Install
+
+One command, once, globally:
+
+```bash
+npm install -g @cs4alhaider/screenbook
+```
+
+That's the entire install — no cloning, nothing copied into your projects. (Prefer no global
+installs? `npx -y @cs4alhaider/screenbook <cmd>` works everywhere `screenbook` appears below.)
+
+## Your first project — five minutes
+
+Go to **any project you're working on** — an iOS app, a web app, an empty folder — and:
+
+```bash
+screenbook init --name "My product"
+screenbook serve
+# → open http://127.0.0.1:4600
+```
+
+`init` creates one folder, **`.screenbook/`** — the self-contained source of truth for your
+prototype. Commit it or add it to `.gitignore`; your call.
+
+```
+.screenbook/
+  brief.md                    ← WRITE YOUR REQUIREMENTS HERE — agents read this first
+  app.config.json             project name · feature order · devices · themes · languages
+  CLAUDE.md                   the authoring contract (for you AND your AI agents)
+  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/skills/screenbook/    packaged skill so Claude knows the rules instantly
+```
+
+The studio runtime always comes from the installed package — `screenbook serve` mounts it at
+`/screenbook/` automatically, and screens reference it as `../../../screenbook/bridge.js`.
+
+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
+screenbook init . --app path/to/index.html
+```
+
+(see [App mode](app-mode.md)).
+
+## The definition of done
+
+```bash
+screenbook 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.
+
+## Offline & prerequisites for the checks
+
+Everything runs on your machine — after the one npm install, ScreenBook needs no network at
+all. The automated checks (`screenbook validate`, `screenshot`) drive your installed Google
+Chrome; on a machine without Chrome they download a headless browser once (~120MB),
+automatically. Nobody is ever asked to install anything by hand.

package/docs/{studio-guide.md → guides/studio.md}

@@ -1,8 +1,9 @@
 # The studio, control by control
 
-Open `http://127.0.0.1:4600` (or `/engine/index.html` under any server).
+Open `http://127.0.0.1:4600` — `screenbook serve` redirects straight to the studio at
+`/screenbook/`.
 
-![The studio](shots/hero-studio.png)
+![The studio](../shots/hero-studio-light.png)
 
 ## Top bar
 

package/docs/{troubleshooting.md → guides/troubleshooting.md}

@@ -1,13 +1,13 @@
 # Troubleshooting
 
 **The studio is blank / "could not load this project".**
-The shell expects to live at `<project>/engine/` with `app.config.json` one level up.
-Serve the PROJECT root (not `engine/`), then open `/engine/index.html`. Under
-`screenbook serve` the `/engine/*` mount handles this automatically.
+The studio expects `app.config.json` one level above where it's mounted. `screenbook serve`
+wires this automatically (the studio lives at `/screenbook/`, your project at `/`). Under a
+plain static server, serve the PROJECT root — never the studio folder itself.
 
 **My new screen isn't in the sidebar.**
 The sidebar reads the derived `features/<f>/manifest.json`. Under `serve` it regenerates on
-save; under any other server run `node engine/cli/screenbook.js manifest .`. Also check the
+save; under any other server run `screenbook manifest`. Also check the
 meta block parses (validate says exactly what's wrong).
 
 **The screen shows "Loading…" forever.**
@@ -23,8 +23,10 @@ the console). Cooperative app: the include path to `engine/app-bridge.js` is wro
 them cooperative.
 
 **`validate` fails with "No headless browser available".**
-`cd engine && npm i` (uses your installed Chrome via playwright-core). No Chrome:
-`npm i -D playwright && npx playwright install chromium`.
+The checks drive your installed Google Chrome via `playwright-core` (bundled with the
+package), and on a Chrome-less machine they download a headless browser once, automatically.
+If both routes failed (offline machine, blocked download), run
+`npx playwright-core install chromium` when you're back online.
 
 **`validate` is red on a screen that looks fine.**
 The gate is zero console errors across every theme × mode × direction. The failure row
@@ -51,5 +53,6 @@ Python's server sends cache headers; hard-reload, or use `screenbook serve`
 (no-store on everything — this problem is why).
 
 **Something engine-side looks wrong.**
-`?selftest=1` in the browser for the live matrix; `TESTING.md` maps every layer
-(`npm test` inside `engine/` runs the engine's own 61-test suite).
+`?selftest=1` in the browser for the live matrix; the [testing map](../contributing/testing.md)
+covers every layer (`npm test` in a checkout of the ScreenBook repo runs the engine's own
+64-test suite).

package/docs/{cli.md → reference/cli.md}

@@ -1,14 +1,19 @@
 # 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).
+Get the direct `screenbook` command with one global install:
+
+```bash
+npm install -g @cs4alhaider/screenbook
+```
+
+Alternatives that need no install: `npx -y @cs4alhaider/screenbook <command>`, or from a
+checkout `node cli/screenbook.js <command>`. Every command takes an optional project
+directory (default: the current one; running from inside `.screenbook/` resolves to its
+parent project automatically).
 
 ## `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`.
+Create `.screenbook/` in the target project — brief.md (your requirements), app.config.json, starter theme, a `welcome` feature, review/, the agent authoring contract, plus the packaged skill at `.claude/skills/screenbook/`. The folder is the prototype's source of truth; commit or gitignore it. Refuses to overwrite an existing `.screenbook/` without `--force`.
 `--app path/to/index.html` additionally registers an existing SPA in that folder as an
 embedded app (driver scaffolded unless `--cooperative`).
 
@@ -16,8 +21,8 @@ embedded app (driver scaffolded unless `--cooperative`).
 
 The dev server. Static hosting with:
 
-- `/engine/*` mounted from the package folder — projects and the bundled examples work even
-  without a local `engine/` copy
+- the studio runtime mounted at `/screenbook/*` straight from the installed package
+  (`/engine/*` kept as a compatibility alias) — your project never carries runtime code
 - live reload over SSE — saving any project file refreshes the studio; screen edits reload
   the current frame
 - automatic `manifest.json` regeneration when screens change
@@ -53,8 +58,8 @@ Device-framed PNGs via headless Chrome. Options: `--mode light,dark` · `--dir l
 
 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).
+which case the app is expected to include the packaged `app-bridge.js` itself. See
+[App mode](../guides/app-mode.md).
 
 ## `mcp [--root dir]`
 

package/docs/{mcp-agents.md → reference/mcp-agents.md}

@@ -15,11 +15,11 @@ 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 .
+node <path-to-package>/cli/screenbook.js mcp --root .   # rarely needed
 ```
 
-`--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
+`--root` points at your project directory — the `.screenbook/` inside it is found automatically. `init` has already
+dropped `AGENTS.md` (the universal contract) 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

package/examples/qahwa/features/order/screens/010-menu.html

@@ -15,7 +15,7 @@
     "updated": "2026-07-18"
   }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <link rel="stylesheet" href="shared.css">
 </head>
 <body>

package/examples/qahwa/features/order/screens/020-drink.html

@@ -15,7 +15,7 @@
     "updated": "2026-07-18"
   }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <link rel="stylesheet" href="shared.css">
 </head>
 <body>

package/examples/qahwa/features/order/screens/030-cart.html

@@ -15,7 +15,7 @@
     "updated": "2026-07-18"
   }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <link rel="stylesheet" href="shared.css">
 </head>
 <body>

package/examples/qahwa/features/order/screens/040-status.html

@@ -16,7 +16,7 @@
     "updated": "2026-07-18"
   }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <link rel="stylesheet" href="shared.css">
   <style>
     .stepper { position: relative; padding-inline-start: 26px; }