@cs4alhaider/screenbook 0.1.0 → 0.2.1

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.1';
 
 /* ---------------- 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,21 @@ 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 to something the server can actually mount. Relative paths
+     are taken relative to the project directory. Three cases:
+       1. inside the ScreenBook root itself       → keep it root-relative
+       2. inside the user's project (.screenbook) → "project/<path>" — served
+          by the /project mount that maps one level above the root
+       3. anywhere else → keep the raw argument and let addApp's existence
+          check produce the error message */
+  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,
@@ -253,21 +296,28 @@ async function cmdScreenshot() {
 }
 
 function help() {
-  console.log(`${bold('screenbook')} ${VERSION} — static prototype studio
+  console.log(`${bold('⧉ screenbook')} ${VERSION} — a design workspace for AI agents, to present to humans
+
+  ${bold('Start here')}
+    ${ok('screenbook init')}                   scaffold .screenbook/ in your project — write brief.md first
+    ${ok('screenbook serve')}                  your studio → http://127.0.0.1:4600
+    claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+                                      ${dim('connect your AI agent (any MCP client works)')}
 
-  ${bold('init')} [dir] [--name X] [--force]     scaffold a consumer project (+ CLAUDE.md + skill)
+  ${bold('Commands')}
+  ${bold('init')} [dir] [--name X] [--force]     scaffold a consumer project (+ agent contract + skill)
              [--app <src>] also register an existing SPA in that folder as an embedded app
   ${bold('app add')} <src> [dir] [--id --title --icon --device --chrome self|engine --cooperative]
                                         embed an existing single-page app (driver scaffolded unless --cooperative)
   ${bold('serve')} [dir] [--port 4600]           static server · live reload · manifest refresh · review sync
   ${bold('manifest')} [dir]                      rescan screens → regenerate features/*/manifest.json
-  ${bold('validate')} [dir] [--static] [--json]  static checks + headless browser self-test
-  ${bold('mcp')} [--root dir]                    start the stdio MCP server (for agents):
-                                        claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+  ${bold('validate')} [dir] [--static] [--json]  static checks + headless browser self-test — the done gate
   ${bold('screenshot')} [dir] --screen f/s       PNG of a screen in its device frame
              [--mode light,dark] [--dir ltr,rtl] [--scenario id] [--theme id] [--lang xx] [--out dir]
+  ${bold('mcp')} [--root dir]                    stdio MCP server — 18 authoring tools for agents
 
-  Projects are folders with app.config.json + features/ + themes/ (see engine/CLAUDE.md).`);
+  ${dim('Docs & guides')}   https://cs4alhaider.github.io/screenbook/
+  ${dim('Bugs & ideas')}    https://github.com/cs4alhaider/screenbook/issues`);
 }
 
 const commands = {

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)
+
+- …
+`;

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.1', 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/README.md

@@ -3,19 +3,30 @@
 Start here. Each guide is short, self-contained, and ordered by how you'll actually meet
 the tool.
 
+## Guides — using ScreenBook
+
 | 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.
+| [Getting started](guides/getting-started.md) | First contact — prerequisites, install, your first project in five minutes |
+| [The studio](guides/studio.md) | A tour of every control in the shell: sidebar, dropdowns, flows, review, Theme Lab, self-test |
+| [Authoring](guides/authoring.md) | You're building screens by hand — the full contract for screens, data, scenarios, themes, flows, strings |
+| [App mode](guides/app-mode.md) | Embedding an EXISTING single-page app instead of (or alongside) file-per-screen features |
+| [Troubleshooting](guides/troubleshooting.md) | Something's red, blank, or missing |
+
+## Reference — looking things up
+
+| Reference | Covers |
+|-----------|--------|
+| [CLI](reference/cli.md) | Every command and flag: `init` · `serve` · `manifest` · `validate` · `screenshot` · `app add` · `mcp` |
+| [AI agents & MCP](reference/mcp-agents.md) | Hooking ScreenBook to Claude Code (or any MCP client) so agents author screens for you |
+
+## Contributing — hacking on ScreenBook itself
+
+| Document | Covers |
+|----------|--------|
+| [Architecture](contributing/architecture.md) | How the engine works: the shell, the bridge protocol, the core, CLI, MCP server, and the self-test |
+| [Testing map](contributing/testing.md) | Every test layer, what it covers, how to run it, and where the gaps are |
+
+One more reference lives at the repo root: **[AGENTS.md](../AGENTS.md)** — the authoring
+contract written for AI agents (scaffolded into every project by `init`; humans are welcome
+to read it too).