@cs4alhaider/screenbook 0.1.0 → 0.2.0

package/core/browser.js

@@ -6,12 +6,13 @@ import path from 'node:path';
 import { startServer } from './serve.js';
 import { mkdirp } from './fsx.js';
 
-async function launch() {
+async function launch({ allowDownload = true } = {}) {
   let lastErr;
   for (const [pkg, opts] of [
     ['playwright', { headless: true }],
     ['playwright-core', { headless: true, channel: 'chrome' }],
-    ['playwright-core', { headless: true, channel: 'chromium' }]
+    ['playwright-core', { headless: true, channel: 'chromium' }],
+    ['playwright-core', { headless: true }]
   ]) {
     try {
       const mod = await import(pkg);
@@ -20,10 +21,24 @@ async function launch() {
       lastErr = err;
     }
   }
+
+  /* No usable browser on this machine — download one automatically, once.
+     (Nobody should ever be told to install something by hand.) */
+  if (allowDownload) {
+    console.error('No browser found — downloading a headless Chromium once (~120MB)…');
+    try {
+      const { spawnSync } = await import('node:child_process');
+      const { createRequire } = await import('node:module');
+      const req = createRequire(import.meta.url);
+      const cli = req.resolve('playwright-core/cli.js');
+      const r = spawnSync(process.execPath, [cli, 'install', 'chromium'], { stdio: ['ignore', 'inherit', 'inherit'] });
+      if (r.status === 0) return launch({ allowDownload: false });
+    } catch { /* fall through to the error below */ }
+  }
+
   throw new Error(
-    `No headless browser available. Install one inside engine/:\n` +
-    `  npm i -D playwright-core   (uses your installed Chrome)\n` +
-    `  npm i -D playwright && npx playwright install chromium   (self-contained)\n` +
+    `No headless browser available and the automatic download failed.\n` +
+    `Install Google Chrome, or run: npx playwright-core install chromium\n` +
     `Underlying error: ${lastErr?.message}`
   );
 }
@@ -62,7 +77,7 @@ export async function runBrowserSelftest({ root, engineDir, timeout = 180000 })
       shellErrors.push(text);
     });
 
-    await page.goto(`${base}/engine/index.html?selftest=1`, { waitUntil: 'domcontentloaded' });
+    await page.goto(`${base}/screenbook/?selftest=1`, { waitUntil: 'domcontentloaded' });
     await page.waitForFunction('window.__selftestDone === true', null, { timeout });
     const result = await page.evaluate('window.__selftestResult');
     result.shellErrors = shellErrors;
@@ -87,7 +102,7 @@ export async function screenshot({ root, engineDir, combos, outDir }) {
       if (c.dir && c.dir !== 'ltr') params.set('dir', c.dir);
       if (c.lang) params.set('lang', c.lang);
       const q = params.toString();
-      const url = `${base}/engine/index.html?solo=1#${encodeURIComponent(c.feature)}/${encodeURIComponent(c.screen)}${q ? `?${q}` : ''}`;
+      const url = `${base}/screenbook/?solo=1#${encodeURIComponent(c.feature)}/${encodeURIComponent(c.screen)}${q ? `?${q}` : ''}`;
 
       await page.goto('about:blank');
       await page.goto(url, { waitUntil: 'domcontentloaded' });

package/core/project.js

@@ -10,15 +10,36 @@ const MANIFEST_FIELDS = ['title', 'description', 'order', 'device', 'devices', '
 
 /* ---------------- roots + config ---------------- */
 
+/*
+ * Find the ScreenBook root for a directory. The standard home is a
+ * `.screenbook/` folder inside the user's project (created by `init` — the
+ * self-contained source of truth they can commit or gitignore). A config at
+ * the directory itself also works (bundled examples, legacy layouts).
+ */
 export async function resolveRoot(dir) {
-  const root = path.resolve(dir || process.cwd());
-  if (await exists(path.join(root, 'app.config.json'))) return root;
-  /* convenience: running from inside engine/ of a project */
-  const parent = path.dirname(root);
-  if (await exists(path.join(parent, 'app.config.json'))) return parent;
+  const base = path.resolve(dir || process.cwd());
+  const candidates = [
+    base,
+    path.join(base, '.screenbook'),
+    path.dirname(base),                               // running from inside engine/ or .screenbook/
+    path.join(path.dirname(base), '.screenbook')
+  ];
+  for (const c of candidates) {
+    if (await exists(path.join(c, 'app.config.json'))) return c;
+  }
   return null;
 }
 
+/* Disk location of an app-feature src. Apps usually live in the USER'S
+   project, outside .screenbook/ — those are recorded as "project/<path>"
+   and served via the /project mount. */
+export function appSrcPath(root, src) {
+  if (src.startsWith('project/') && path.basename(root) === '.screenbook') {
+    return path.join(path.dirname(root), src.slice('project/'.length));
+  }
+  return path.join(root, src);
+}
+
 export async function readConfig(root) {
   return readJSON(path.join(root, 'app.config.json'), {});
 }
@@ -195,7 +216,7 @@ export async function addFeature(root, { id, title, icon, description, order })
  */
 export async function addApp(root, { src, id, title, icon, description, device, chrome, driver, order }) {
   if (!src) throw new Error('src required — project-relative path to the app\'s index.html');
-  const srcPath = path.join(root, src);
+  const srcPath = appSrcPath(root, src);
   if (!(await exists(srcPath))) throw new Error(`app entry not found: ${src}`);
 
   const appId = id || path.basename(path.dirname(srcPath)).toLowerCase().replace(/[^a-z0-9-]+/g, '-') || 'app';
@@ -386,7 +407,7 @@ export async function staticValidate(root) {
     const fMeta = await readJSON(path.join(featureDir(root, id), 'feature.json'), null);
     if (fMeta?.type === 'app') {
       if (!fMeta.src) errors.push(`${id}: app feature has no "src"`);
-      else if (!(await exists(path.join(root, fMeta.src)))) errors.push(`${id}: app src not found: ${fMeta.src}`);
+      else if (!(await exists(appSrcPath(root, fMeta.src)))) errors.push(`${id}: app src not found: ${fMeta.src}`);
       if (fMeta.driver && !(await exists(path.join(featureDir(root, id), fMeta.driver)))) {
         errors.push(`${id}: driver not found: features/${id}/${fMeta.driver}`);
       }

package/core/serve.js

@@ -97,12 +97,12 @@ export function startServer({ root, engineDir, port = 4600, quiet = false }) {
 
     try {
       if (p === '/' || p === '/index.html') {
-        send(res, 302, '', { Location: '/engine/index.html' });
+        send(res, 302, '', { Location: '/screenbook/' });
         return;
       }
 
       if (p === '/__sb/health') {
-        send(res, 200, JSON.stringify({ screenbook: true, version: '0.1.0', root: path.basename(root) }),
+        send(res, 200, JSON.stringify({ screenbook: true, version: '0.2.0', root: path.basename(root) }),
           { 'Content-Type': 'application/json' });
         return;
       }
@@ -147,16 +147,31 @@ export function startServer({ root, engineDir, port = 4600, quiet = false }) {
         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);
+      /* When the root is a .screenbook/ folder, the user's real project sits
+         one level up — mount it at /project/ so embedded apps (app mode) are
+         reachable same-origin without any copying. */
+      const parentMount = path.basename(root) === '.screenbook' ? path.dirname(root) : null;
+      if (parentMount && (p === '/project' || p.startsWith('/project/'))) {
+        const sub = p === '/project' ? '/index.html' : p.slice('/project'.length);
+        const abs = safeJoin(parentMount, sub === '/' ? '/index.html' : sub);
         if (!abs) return send(res, 403, 'forbidden');
         await serveFile(res, abs);
         return;
       }
 
+      /* The studio runtime is served from THIS installed package at
+         /screenbook/* — nothing is ever copied into user projects.
+         /engine/* remains as a compatibility alias for older screens. */
+      for (const prefix of ['/screenbook', '/engine']) {
+        if (p === prefix || p.startsWith(prefix + '/')) {
+          const sub = p === prefix ? '/index.html' : p.slice(prefix.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);

package/docs/authoring-guide.md

@@ -33,7 +33,7 @@ features/trip-planning/
   { "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>

package/docs/cli.md

@@ -1,14 +1,18 @@
 # 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
+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 engine/cli/screenbook.js <command>`. 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`.
+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`).
 

package/docs/getting-started.md

@@ -24,40 +24,44 @@ npm i -D playwright && npx playwright install chromium
 
 ## Install
 
-ScreenBook lives INSIDE your project as a folder named `engine/`:
+One command, once, globally:
 
 ```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/)
+npm install -g @cs4alhaider/screenbook
 ```
 
-The folder name matters: screens reference `../../../engine/bridge.js` by convention.
+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
-cd my-prototypes
-node engine/cli/screenbook.js init . --name "My product"
-node engine/cli/screenbook.js serve .
+screenbook init --name "My product"
+screenbook serve
 # → open http://127.0.0.1:4600
 ```
 
-You now have:
+`init` creates one folder, **`.screenbook/`** — the self-contained source of truth for your
+prototype. Commit it or add it to `.gitignore`; your call.
 
 ```
-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)
+.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.
@@ -80,9 +84,9 @@ Green means: every screen renders in every theme × light/dark × LTR/RTL with *
 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
+## Offline & prerequisites for the checks
 
-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.
+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/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; }

package/examples/qahwa/features/order/screens/050-status-android.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>
     /* Material-ish accents for the Android take */

package/examples/qahwa/features/roastery/screens/010-orders.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/roastery/screens/020-menu-editor.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/spa-demo/app/index.html

@@ -62,7 +62,7 @@
   </div>
 
   <!-- the ONE line that makes this a cooperative ScreenBook app -->
-  <script src="../engine/app-bridge.js"></script>
+  <script src="../screenbook/app-bridge.js"></script>
   <script>
     var VIEWS = [
       { id: 'inbox', title: 'Inbox', description: 'The notes list — tap one to open it.' },

package/examples/tokens-lab/features/lab/screens/010-swatches.html

@@ -15,7 +15,7 @@
     "updated": "2026-07-18"
   }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <style>
     * { box-sizing: border-box; }
     body {

package/examples/tokens-lab/features/lab/screens/020-typography.html

@@ -15,7 +15,7 @@
     "updated": "2026-07-18"
   }
   </script>
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
   <style>
     * { box-sizing: border-box; }
     body {

package/mcp/server.js

@@ -16,7 +16,7 @@ import {
 } from '../core/project.js';
 
 const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const VERSION = '0.1.0';
+const VERSION = '0.2.0';
 
 const rootFlagIx = process.argv.indexOf('--root');
 const rootArg = rootFlagIx > -1 ? process.argv[rootFlagIx + 1] : undefined;
@@ -32,7 +32,7 @@ const SCREEN_CONTRACT =
   'A screen is one full standalone HTML document: <!DOCTYPE html>, a required ' +
   '<script type="application/json" id="screen-meta"> block ({title, description, order, ' +
   'device: ios|android|web|none, status?, tags?, group?, statusBar?: light|dark, updated?}), and one ' +
-  '<script src="../../../engine/bridge.js"></script> include. Use CSS vars from the active theme ' +
+  '<script src="../../../screenbook/bridge.js"></script> include. Use CSS vars from the active theme ' +
   '(--color-*, --font-*, --radius-*, --space-*, --safe-top, --safe-bottom), bind mock data with ' +
   'Engine.ready(cb → cb(data)), navigate with data-go="<screen-id>" attributes, share state via ' +
   'Engine.state.get/set/subscribe, notify with Engine.toast(msg). Screens must render sensibly ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cs4alhaider/screenbook",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -35,10 +35,11 @@
     "skill/",
     "examples/",
     "docs/",
+    "AGENTS.md",
     "CLAUDE.md",
     "TESTING.md"
   ],
-  "devDependencies": {
+  "dependencies": {
     "playwright-core": "^1.45.0"
   },
   "scripts": {

package/shell/screenhost.js

@@ -30,7 +30,7 @@ export function injectAppRuntime(iframe, featureId, driverFile, onFail) {
   }
   const host = doc.head || doc.documentElement;
   const runtime = doc.createElement('script');
-  runtime.src = url('engine/app-bridge.js');
+  runtime.src = url('screenbook/app-bridge.js');
   runtime.onload = () => {
     const driver = doc.createElement('script');
     driver.src = url(`features/${featureId}/${driverFile}`);

package/shell/selftest.js

@@ -200,11 +200,12 @@ export async function runSelftest() {
   overlay.hidden = false;
   overlay.innerHTML =
     `<div class="st-card">
-      <div class="st-head"><h2>ScreenBook self-test</h2><span class="st-summary" id="st-summary">0 / ${all.length}</span></div>
+      <div class="st-head"><h2>Self-test</h2><span class="st-summary" id="st-summary">0 / ${all.length}</span></div>
       <div class="st-progress"><i id="st-bar"></i></div>
+      <div class="st-now" id="st-now">warming up…</div>
       <div class="st-rows" id="st-rows"></div>
       <div class="st-foot">
-        <span class="st-note">screens × themes × light/dark × ltr/rtl · zero console errors · meta present</span>
+        <span class="st-note">every screen × theme × mode × direction · zero console errors</span>
         <button class="btn-ghost" onclick="location.search=''">Close</button>
       </div>
     </div>`;
@@ -217,11 +218,13 @@ export async function runSelftest() {
   const results = [];
   let done = 0;
 
+  const nowLine = document.getElementById('st-now');
   function report(r) {
     results.push(r);
     done++;
     summary.textContent = `${done}${done <= all.length ? ` / ${all.length}` : ' checks'}`;
     bar.style.width = `${Math.min(100, (done / Math.max(1, all.length)) * 100)}%`;
+    nowLine.textContent = `${r.ok ? '✓' : '✕'} ${r.feature}/${r.screen} · ${r.theme}·${r.mode}·${r.dir}${r.device && r.device !== 'app' ? '·' + r.device : ''}`;
     if (!r.ok) {
       const row = document.createElement('div');
       row.className = 'st-row is-fail';
@@ -245,6 +248,7 @@ export async function runSelftest() {
   for (const f of project.features.values()) {
     if (f.type !== 'app') continue;
     summary.textContent = `app: ${f.id}…`;
+    nowLine.textContent = `booting embedded app "${f.id}" — visiting every screen it reports…`;
     await runAppFeature(f, report);
   }
 

package/shell/shell.css

@@ -868,19 +868,18 @@ body.solo .canvas { padding: 0; }
 
 /* ---------------------------------------------------------------- selftest */
 
+/* Self-test runs in a floating card — the studio stays fully visible. */
 .selftest-overlay {
   position: fixed;
-  inset: 0;
+  right: 18px;
+  bottom: 18px;
   z-index: 400;
-  background: color-mix(in srgb, var(--sb-bg) 88%, transparent);
-  backdrop-filter: blur(6px);
-  display: grid;
-  place-items: center;
-  padding: 30px;
+  max-width: min(520px, calc(100vw - 36px));
 }
 .st-card {
-  width: min(760px, 100%);
-  max-height: 100%;
+  width: 480px;
+  max-width: 100%;
+  max-height: min(70vh, 640px);
   display: flex;
   flex-direction: column;
   background: var(--sb-panel-2);
@@ -915,7 +914,16 @@ body.solo .canvas { padding: 0; }
   border-radius: 2px;
   transition: width .15s ease;
 }
-.st-rows { flex: 1; overflow-y: auto; padding: 10px 12px 14px; min-height: 120px; }
+.st-now {
+  padding: 8px 18px 2px;
+  font-size: 11px;
+  font-family: var(--sb-mono);
+  color: var(--sb-ink-2);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.st-rows { flex: 1; overflow-y: auto; padding: 8px 12px 12px; min-height: 60px; }
 .st-row {
   display: flex;
   align-items: baseline;

package/skill/SKILL.md

@@ -13,7 +13,7 @@ read or modify `engine/` internals.
 
 - One screen = one full HTML document in `features/<f>/screens/<id>.html`, with a required
   `<script type="application/json" id="screen-meta">` block and one bridge include
-  (`../../../engine/bridge.js`). It works opened alone AND inside the shell.
+  (`../../../screenbook/bridge.js`). It works opened alone AND inside the shell.
 - Mock data = `features/<f>/data/seed.json`; named **scenarios** overlay it
   (`patch` deep-merge, `remove` dot-paths, `{{today±N}}` date tokens).
 - Look = design tokens in `themes/<id>.json`, flattened to CSS vars (`--color-accent`,

package/skill/references/cli-mcp.md

@@ -37,7 +37,7 @@ scenario?, theme?, lang?, return_image?}`
 Register with Claude Code:
 ```
 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 .
+# or from a checkout: node <path-to-package>/cli/screenbook.js mcp --root .   # rarely needed
 ```
 
 ## Serve endpoints (for tooling)

package/skill/references/screen-contract.md

@@ -29,7 +29,7 @@ fallback and keeps directory listings readable. Prefer ids like `010-home`, `020
   </script>
 
   <!-- 2. REQUIRED bridge — the ONLY engine include, exact relative path -->
-  <script src="../../../engine/bridge.js"></script>
+  <script src="../../../screenbook/bridge.js"></script>
 
   <!-- 3. Optional shared feature look/helpers (explicit opt-in per screen) -->
   <link rel="stylesheet" href="shared.css">