paper-motion 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 All notable changes to the `paper-motion` npm package. Dates are release dates on npm.
 
+## 0.5.0 · 2026-11-13
+
+**Studio v2: one page, four steps, an honest agent.** The user makes a piece in the studio alone (What you want to
+say, How it looks, Your video, Export); the agent listens in the background, and its visual choices come into the
+studio instead of links. Five phases, one end-to-end check (`scripts/check-studio.mjs`, 53 checks).
+
+Studio v2, phase 1 ([spec](../../docs/spec-studio-v2.md), [plan](../../docs/plan-studio-v2.md)): an honest connection with the agent.
+
+- **`piece listen <piece>`**: the agent keeps it running in the background between turns. It returns as soon as the
+  user does something that needs the agent (a message, an answer, an approval, a choice), printing it as lines and
+  marking them read, or exits 3 after 9 minutes with nothing. The user no longer has to go to the chat to say
+  "continue".
+- **The studio only says what it can check about the agent:** listening (a command of the agent is waiting on the
+  piece, and its process is alive), working on something (said with `piece working … --on "…"`, for up to 20
+  minutes), asking you, or not connected. "Your agent waits" and "tell your agent continue" are gone. A command
+  that was killed stops showing as listening at once.
+- **Questions are answered in the studio.** `piece ask` shows the question with an answer box; the answer reaches
+  `piece listen` as an `answered "…": "…"` line. **Answered in the chat** closes it.
+- **Ask your agent is a thread:** each message shows Sent, then Read with the time; `piece say <piece> "…"` puts the
+  agent's reply there. A message no longer moves the stage to "changes".
+- `scripts/check-studio.mjs` drives a fresh project end to end (headless Chrome for the user, real `pamo` commands
+  for the agent).
+
+Studio v2, phase 2: one page, four steps, and How it looks.
+
+- **A new stage, `look`**, between `inventory` and `video` (`STAGES`: brief, inventory, look, video, final). A
+  project whose brand already settles colours, type and a background starts with it done; older pieces get it as
+  approved.
+- **The stepper:** What you want to say · How it looks · Your video · Export. Steps ahead stay locked until reached;
+  earlier ones reopen. Style moved into How it looks.
+- **How it looks:** colours, type, background and movement (pace, and how words arrive), each a still card. Pointing
+  at one plays it in a single live preview of the user's own first sentence (`line-in`, with the look laid over the
+  brand only for that preview: `?embed&look=…`, read by `runtime/brand.js`). Choosing writes `brand/`: the palette
+  (the brand's library backgrounds take its colours again), the font pair, a colour by hand, the brand's main
+  background (added from the library in its colours when needed), pace and the default entrance
+  (`brand/motion.json` `entrance`, which `line-in` uses when a part sets none). **Make my video** builds the first
+  version, which used to happen on approving the content.
+- **A still of every background** (`apps/web/public/previews/<id>.jpg`, from `scripts/render-backgrounds.mjs`), so
+  cards never run a shader.
+
+Studio v2, phase 3: the agent's choices come into the studio ([ADR 0005](../../docs/adr/0005-the-studio-replaces-board-links-during-a-piece.md)).
+
+- With a piece open and its studio running, **`pamo board --url …` puts the options into the studio** instead of a
+  link, on the step they decide: palettes, font pairs, backgrounds and moves in How it looks (kits as a whole look
+  at its top), transitions, structures and blocks in Your video. The step shows a dot; the options come first in
+  their section, marked **Suggested by your agent**, with the agent's question and notes, and play in the preview
+  when pointed at. The command waits (the studio shows the agent listening) and prints the same reply line, built
+  with `replyLine`. **None of these** sends what the user would rather see. `--link` makes a link anyway.
+- A palette, font pair or background picked there is applied to `brand/` at once, like any card; moves,
+  transitions and structures go to the agent as the line.
+- `board --await c1` waits again for a studio choice, `board --forget c1` takes it out.
+
+Studio v2, phase 4: Your video as scenes.
+
+- **A list of scenes instead of the strip:** each with its number, a still of itself, what it says and how long it
+  plays; drag to reorder; **Add a scene** at the end asks what it is for.
+- **Stills of the real scenes** (the user's words, brand and settings), rendered by the studio one at a time after a
+  scene changes (`pieces/<piece>/.stills/`), never while a final renders; until then the library's still shows.
+- **Five tabs:** Text, Animation (with the block's own settings), Background, Speed (length is speed) and Next scene
+  (the transition, chosen by watching, or the same between every scene).
+- **Nothing rebuilds by itself.** Something new kept in What you want to say offers **Add it to the video**; approving
+  the content again never takes a built piece back to How it looks.
+- **The playing scene no longer restarts when the page redraws** (a still arriving, the agent's state changing): it is
+  moved without reloading (`moveBefore`, where the browser has it), and a still only updates its thumbnail.
+
+Studio v2, phase 5: light on the machine.
+
+- An embedded preview that ended stops its frame loop (a click starts it again): an idle studio draws nothing. The
+  check measures it: 0 shader draws and 0 animation frames for 5 s after a scene ends, and at most one live preview
+  on the page.
+- **Fixed for npm installs:** the site's `registry.json` lists params by name only, so an installed studio had no
+  block settings or entrances to offer (since 0.4) and, now, no palettes' colours, font pairs or backgrounds. It
+  fetches the full resource of those (`/r/<id>.json`) when it starts. `scripts/check-studio.mjs` runs against an
+  installed package with `PAMO_BIN=…`.
+- The site's making-of, hero and docs page tell the four steps, the five stages behind them, `piece listen` and the
+  choices in the studio.
+
+
 ## 0.4.1 · 2026-11-12
 
 - **The studio's live previews are much lighter.** A scene opened with `?embed` draws its shaders at the size it is

package/bin/pamo.mjs

@@ -364,7 +364,7 @@ async function main() {
         const { parseSet, setArgs } = await import('../lib/customize.mjs');
         const reg = resolveRegistry(args.registry), { items } = await getIndex(reg), index = Object.fromEntries(items.map((i) => [i.id, i]));
         const opts = process.argv.flatMap((a, i, all) => (a === '--option' ? [all[i + 1]] : a.startsWith('--option=') ? [a.slice(9)] : [])).filter(Boolean);
-        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette[:key=value,…],font | --look brand] --option id[:key=value,…] [--note "why"] … [--kit] [--choose 1-3] [--wait minutes | --no-wait] [--long] [--site url]\n       board --await <id|link> [--wait minutes]   (wait again for a board already shared)\n       board --forget <id>\n  On a recipe board an option may be a structure of your own: --option "@Title | 18 | Hook 0-2 [word-swap] one line; Proof 2-12 [browser-frame] three shots; Close 12-18 [svg-logo] the action" (a [block-id] makes the board play that clip for the beat).\n  Prints a live board link: short (/b/<id>, stored on the site for 90 days) when the site answers, long (the board in the URL fragment) otherwise or with --long. Values after the colon are your adjustments; the reply line carries every non-default value.\n  With a short link the command keeps running until the user chooses in the browser (10 min; --wait 3 changes it, in minutes; --no-wait returns at once) and prints the reply line, the same one they could paste. If your shell caps how long a command runs, share with --no-wait and then wait in short steps: board --await <id> --wait 2, again until it prints the line (exit code 3 means not yet). Values take lists and several keys: --option graphite:accent=#B8F03C,ramp=["#0A0A0B","#B8F03C"] (quote it for the shell); --look brand uses the palette, colors and font pair this project installed. --choose lets them pick several options (a count, or min-max). --forget deletes a stored board early.'); process.exit(args.help ? 0 : 1); }
+        if (!opts.length || !args.title || args.help) { console.error('Usage: board --url --title "…" [--ask "…"] [--reply name] [--look palette[:key=value,…],font | --look brand] --option id[:key=value,…] [--note "why"] … [--kit] [--choose 1-3] [--wait minutes | --no-wait] [--long] [--site url] [--link]  (with a piece open and its studio running the options go into the studio, not a link; --link makes a link anyway)\n       board --await <id|link> [--wait minutes]   (wait again for a board already shared)\n       board --forget <id>\n  On a recipe board an option may be a structure of your own: --option "@Title | 18 | Hook 0-2 [word-swap] one line; Proof 2-12 [browser-frame] three shots; Close 12-18 [svg-logo] the action" (a [block-id] makes the board play that clip for the beat).\n  Prints a live board link: short (/b/<id>, stored on the site for 90 days) when the site answers, long (the board in the URL fragment) otherwise or with --long. Values after the colon are your adjustments; the reply line carries every non-default value.\n  With a short link the command keeps running until the user chooses in the browser (10 min; --wait 3 changes it, in minutes; --no-wait returns at once) and prints the reply line, the same one they could paste. If your shell caps how long a command runs, share with --no-wait and then wait in short steps: board --await <id> --wait 2, again until it prints the line (exit code 3 means not yet). Values take lists and several keys: --option graphite:accent=#B8F03C,ramp=["#0A0A0B","#B8F03C"] (quote it for the shell); --look brand uses the palette, colors and font pair this project installed. --choose lets them pick several options (a count, or min-max). --forget deletes a stored board early.'); process.exit(args.help ? 0 : 1); }
         const LABELS = ['A', 'B', 'C', 'D'];
         // commas only separate at the top level (not inside [..], {..} or quotes), and only before a new "key=":
         // so ramp=["#000","#111"] and multi-value colors survive
@@ -420,6 +420,31 @@ async function main() {
         } else if (typeof args.look === 'string') for (const spec of splitLook(args.look)) { const o = await parseOne(spec); const t = index[o.id]?.type; if (t === 'palette') look.palette = o; else if (t === 'font-pair') look.font = o; else throw new Error(`--look takes a palette and a font pair (or "brand"), not "${o.id}"`); }
         const choose = args.choose === undefined ? undefined : /^\d+-\d+$/.test(String(args.choose)) ? String(args.choose).split('-').map(Number) : Number(args.choose);
         const board = { v: 1, kind: args.kit ? 'kit' : 'resource', title: String(args.title), ...(args.ask ? { ask: String(args.ask) } : {}), ...(args.reply ? { reply: String(args.reply) } : {}), ...(Object.keys(look).length ? { look } : {}), ...(choose !== undefined ? { choose } : {}), options };
+        // a piece open with its studio running: the options go into the studio, on the step they decide, not into a
+        // link; the command waits there and prints the same reply line (ADR 0005). --link makes a site link anyway.
+        if (!args.link) {
+          const PCs = await import('../lib/piece.mjs');
+          const pdirS = PCs.activePiece(process.cwd(), typeof args.piece === 'string' ? args.piece : undefined);
+          const st = pdirS ? await (await import('../lib/studio.mjs')).findStudio(process.cwd()) : null;
+          if (st) {
+            const { validateBoard } = await import('../lib/live-board.js');
+            const errs = validateBoard(board, index); if (errs.length) { console.error(`✗ ${errs.join('; ')}`); process.exit(1); }
+            const type = board.kind === 'kit' ? 'kit' : board.options[0].structure ? 'structure' : index[board.options[0].id]?.type;
+            const PLACE = { palette: ['look', 'colours', 'How it looks · Colours'], 'font-pair': ['look', 'type', 'How it looks · Type'], background: ['look', 'background', 'How it looks · Background'],
+              text: ['look', 'movement', 'How it looks · Movement'], component: ['look', 'movement', 'How it looks · Movement'], camera: ['look', 'movement', 'How it looks · Movement'], kit: ['look', 'kit', 'How it looks'],
+              transition: ['video', 'joins', 'Your video'], structure: ['video', 'structure', 'Your video'], recipe: ['video', 'structure', 'Your video'], block: ['video', 'scenes', 'Your video'], shot: ['video', 'scenes', 'Your video'] };
+            const [step, section, label] = PLACE[type] ?? ['video', 'other', 'Your video'];
+            const cid = PCs.addChoice(pdirS, { board, where: { step, section, type } });
+            console.log(`in the studio, on ${label}: ${st.url}?p=${encodeURIComponent(path.basename(pdirS))}  (choice ${cid}; no link to share)`);
+            if (args['no-wait']) { console.error(`the user chooses in the studio; wait for it with: board --await ${cid}`); break; }
+            const minutes = Number.isFinite(Number(args.wait)) && args.wait !== undefined && args.wait !== true ? Number(args.wait) : 10;
+            console.error(`waiting up to ${minutes} min for their choice in the studio…`);
+            const line = await PCs.awaitChoiceIn(pdirS, cid, { timeout: minutes * 60 * 1000 });
+            if (!line) { console.error(`no choice yet: wait again with board --await ${cid}`); process.exit(3); }
+            console.log(line);
+            break;
+          }
+        }
         const site = typeof args.site === 'string' ? args.site : SITE;
         let frag, short = null;
         try { frag = await encodeBoard(board, index); } catch (e) { console.error(e.message); process.exit(1); }
@@ -443,6 +468,22 @@ async function main() {
         } else if (!short && wait) console.error('(no short link, so no waiting: the user will paste the line from the board)');
         break;
       }
+      if (args.await && /^c\d+$/.test(String(args.await))) {   // a choice in the studio
+        const PCs = await import('../lib/piece.mjs'), pdirS = PCs.activePiece(process.cwd(), typeof args.piece === 'string' ? args.piece : undefined);
+        if (!pdirS) { console.error('no open piece here (pass --piece)'); process.exit(1); }
+        const minutes = Number.isFinite(Number(args.wait)) && args.wait !== undefined && args.wait !== true ? Number(args.wait) : 10;
+        console.error(`waiting up to ${minutes} min for their choice in the studio…`);
+        const line = await PCs.awaitChoiceIn(pdirS, String(args.await), { timeout: minutes * 60 * 1000 });
+        if (!line) { console.error('no choice yet: run it again'); process.exit(3); }
+        console.log(line);
+        break;
+      }
+      if (args.forget && /^c\d+$/.test(String(args.forget))) {
+        const PCs = await import('../lib/piece.mjs'), pdirS = PCs.activePiece(process.cwd(), typeof args.piece === 'string' ? args.piece : undefined);
+        if (!pdirS) { console.error('no open piece here (pass --piece)'); process.exit(1); }
+        PCs.forgetChoice(pdirS, String(args.forget)); console.log(`took choice ${args.forget} out of the studio`);
+        break;
+      }
       if (args.await) {
         // wait (again) for the choice on a board already shared: for shells that cap how long one command may run
         const { awaitChoice } = await import('../lib/live-board.js');
@@ -657,7 +698,7 @@ async function main() {
 
     case 'piece': {
       const sub = args._[1], piece = args._[2];
-      if (!['init', 'review', 'working', 'status', 'ask'].includes(sub) || !piece || args.help) { console.error('Usage: piece init <piece> [--title "…"] [--what …] [--who …] [--format …] [--tone …] [--action …] [--no-studio] [--force]\n       piece review <piece> <stage> [--wait 30 (minutes)] [--no-wait] [--no-open] [--no-studio] [--skip]\n       piece working <piece> <stage>\n       piece ask <piece> "the question you are asking in the chat" | --done\n       piece status <piece>\n  ask: run it right before you ask the user anything in the chat, so the studio sends them there (the next review or working clears it, or --done). --return <url> on any of these gives the studio a link back to you when you run in a browser.\n  Stages: brief, inventory (what the video can show), video (they edit it in the studio), final. review hands a stage to the user in the studio and prints what they did, one line each; it refuses while an earlier stage is not approved (--skip moves on without it, only when the user agreed). --no-wait returns at once with what is unread; --no-open does not open their browser; --no-studio runs without the studio.'); process.exit(args.help ? 0 : 1); }
+      if (!['init', 'review', 'working', 'status', 'ask', 'listen', 'say'].includes(sub) || !piece || args.help) { console.error('Usage: piece init <piece> [--title "…"] [--what …] [--who …] [--format …] [--tone …] [--action …] [--no-studio] [--force]\n       piece review <piece> <stage> [--wait 30 (minutes)] [--no-wait] [--no-open] [--no-studio] [--skip]\n       piece listen <piece> [--wait 9 (minutes)]\n       piece working <piece> <stage> [--on "what you are doing, in plain words"]\n       piece say <piece> "a short reply the user reads in the studio"\n       piece ask <piece> "the question" | --done\n       piece status <piece>\n  listen: run it in the background between your turns; it returns as soon as the user does something that needs you (a message, an answer, an approval, a choice), printing it as lines, or after --wait minutes with nothing (exit 3: start it again). While it runs the studio says you are listening.\n  ask: run it right before you ask the user anything in the chat, so the studio sends them there (the next review or working clears it, or --done). --return <url> on any of these gives the studio a link back to you when you run in a browser.\n  Stages: brief, inventory (what the video can show), video (they edit it in the studio), final. review hands a stage to the user in the studio and prints what they did, one line each; it refuses while an earlier stage is not approved (--skip moves on without it, only when the user agreed). --no-wait returns at once with what is unread; --no-open does not open their browser; --no-studio runs without the studio.'); process.exit(args.help ? 0 : 1); }
       const P = await import('../lib/piece.mjs');
       const { pieceDir } = await import('../lib/chain.mjs');
       const dir = pieceDir(piece), studioLib = await import('../lib/studio.mjs'), q = `?p=${encodeURIComponent(path.basename(dir))}`;
@@ -689,15 +730,31 @@ async function main() {
         await host();
         if (args.done) { P.clearAsk(dir); console.log('✓ cleared: the studio no longer sends the user to the chat'); break; }
         const question = typeof args._[3] === 'string' ? args._[3].trim() : '';
-        if (!question) { console.error('piece ask: give the question in one line (the one you are asking in the chat), or --done'); process.exit(1); }
+        if (!question) { console.error('piece ask: give the question in one line, or --done'); process.exit(1); }
         P.setAsk(dir, question);
-        console.log(`✓ the studio now tells the user you asked this in the chat${P.readPiece(dir).agent ? ', with a way back to you' : ''}. Ask it now; the next piece review or piece working clears it (or piece ask ${piece} --done).`);
+        console.log(`✓ the studio shows your question with a box to answer it; their answer reaches piece listen ${piece} as an "answered" line. Ask it in the chat too. It closes when they answer, or with the next piece review or piece working (or piece ask ${piece} --done).`);
+        break;
+      }
+      if (sub === 'listen') {
+        if (!P.readPiece(dir)) { console.error(`no piece.json in ${path.relative(process.cwd(), dir)}`); process.exit(1); }
+        await host();
+        const minutes = Number.isFinite(Number(args.wait)) && args.wait !== undefined && args.wait !== true ? Number(args.wait) : 9;
+        const r = await P.listenFor(dir, { timeout: minutes * 60 * 1000 });
+        for (const l of r.lines) console.log(l);
+        if (!r.done) { console.log(`(nothing from the user in ${minutes} min: run piece listen ${piece} again)`); process.exit(3); }
+        break;
+      }
+      if (sub === 'say') {
+        if (!P.readPiece(dir)) { console.error(`no piece.json in ${path.relative(process.cwd(), dir)}`); process.exit(1); }
+        const text = typeof args._[3] === 'string' ? args._[3].trim() : '';
+        if (!text) { console.error('piece say: give the reply in one or two plain sentences'); process.exit(1); }
+        P.addNote(dir, text); console.log('✓ the user sees it in the studio, under Ask your agent');
         break;
       }
       const stage = args._[3];
       await host();
       if (!P.STAGES.includes(stage)) { console.error(`piece ${sub}: give a stage (${P.STAGES.join(', ')})`); process.exit(1); }
-      if (sub === 'working') { P.updatePiece(dir, (p) => { delete p.ask; p.stage = stage; p.stages[stage] = { ...p.stages[stage], status: 'working', since: new Date().toISOString() }; }); console.log(`✓ ${stage}: working`); break; }
+      if (sub === 'working') { P.updatePiece(dir, (p) => { p.stage = stage; p.stages[stage] = { ...p.stages[stage], status: 'working', since: new Date().toISOString() }; }); P.setWorking(dir, typeof args.on === 'string' ? args.on : null); console.log(`✓ ${stage}: working${typeof args.on === 'string' ? ` on ${args.on}` : ''} (the studio shows it until you listen or review, or for 20 minutes)`); break; }
       // review: hand the stage over and wait for the user's decision in the studio
       if (stage === 'inventory') {
         // the user is asked whether each thing is true and worth showing: they cannot judge half an item

package/lib/edit.mjs

@@ -320,19 +320,47 @@ export async function ensureLook(cwd, name) {
   return installed;
 }
 
+// the brand's backgrounds that come from the library take its colours again (after the palette or a colour changed)
+async function recolorBackgrounds(cwd) {
+  const setFile = path.join(cwd, 'brand/shader-set/set.json'), set = readJson(setFile, {});
+  const { add, getIndex } = await import('./registry.mjs');
+  const index = new Set(((await getIndex().catch(() => ({ items: [] }))).items ?? []).filter((x) => x.type === 'background').map((x) => x.id));
+  const ids = (set.entries ?? []).filter((e) => e.shader && !e.image && index.has(e.id)).map((e) => e.id);
+  if (!ids.length) return;
+  const order = (set.entries ?? []).map((e) => e.id);
+  await add(ids, { cwd, palette: 'brand', force: true });
+  const after = readJson(setFile, {});   // keep the order the user had: the first is the brand's background
+  after.entries = [...(after.entries ?? [])].sort((x, y) => (order.indexOf(x.id) + 1 || 1e9) - (order.indexOf(y.id) + 1 || 1e9));
+  writeJson(setFile, after);
+}
+
 export async function editStyle(cwd, dir, a) {
-  const tokens = path.join(cwd, 'brand/tokens.json'), motion = path.join(cwd, 'brand/motion.json');
-  snapshot(cwd, dir, [tokens, motion, path.join(cwd, 'brand/fonts.css')], 'the style');
+  const tokens = path.join(cwd, 'brand/tokens.json'), motion = path.join(cwd, 'brand/motion.json'), setFile = path.join(cwd, 'brand/shader-set/set.json');
+  snapshot(cwd, dir, [tokens, motion, path.join(cwd, 'brand/fonts.css'), setFile], 'the style');
   if (a.type === 'palette' || a.type === 'font') {
     const { add } = await import('./registry.mjs');
     await add([a.value], { cwd, force: true });
+    if (a.type === 'palette') await recolorBackgrounds(cwd);
     return { say: `${a.type === 'palette' ? 'Colours' : 'Type'}: ${a.value}` };
   }
   if (a.type === 'color') {
     if (!/^#[0-9a-f]{6}$/i.test(a.value) || !['ground', 'figure', 'accent'].includes(a.key)) throw new Error('bad colour');
-    const t = readJson(tokens, {}); t.colors ??= {}; t.colors[a.key] = { ...(t.colors[a.key] ?? {}), hex: a.value.toUpperCase() }; writeJson(tokens, t);
+    const t = readJson(tokens, {}); t.colors ??= {}; t.colors[a.key] = { ...(t.colors[a.key] ?? {}), hex: a.value.toUpperCase() }; delete t.ramp; writeJson(tokens, t);
+    await recolorBackgrounds(cwd);
     return { say: `${{ ground: 'Background', figure: 'Text', accent: 'Accent' }[a.key]} colour ${a.value}` };
   }
+  if (a.type === 'background') {   // the brand's background: the first entry of its set, added from the library in its colours
+    let set = readJson(setFile, { entries: [] });
+    if (!(set.entries ?? []).some((e) => e.id === a.value)) { const { add } = await import('./registry.mjs'); await add([a.value], { cwd, palette: 'brand' }); set = readJson(setFile, { entries: [] }); }
+    const i = set.entries.findIndex((e) => e.id === a.value); if (i < 0) throw new Error('no such background');
+    set.entries.unshift(...set.entries.splice(i, 1)); writeJson(setFile, set);
+    return { say: `Background: ${a.value}` };
+  }
+  if (a.type === 'entrance') {   // how words arrive, unless a part says otherwise
+    if (!/^[a-z-]+$/.test(a.value)) throw new Error('bad entrance');
+    const m = readJson(motion, {}); m.entrance = a.value; writeJson(motion, m);
+    return { say: `Words arrive: ${a.value}` };
+  }
   if (a.type === 'pace') {
     if (!['calm', 'medium', 'fast'].includes(a.value)) throw new Error('bad pace');
     const m = readJson(motion, {}); m.pace = a.value; writeJson(motion, m);

package/lib/piece.mjs

@@ -1,12 +1,17 @@
 // A piece's progress: pieces/<piece>/piece.json, shared by the agent (CLI) and the user (pamo studio).
 //
-//   stage      the stage the piece is at: brief → inventory → video → final. The user sees three steps (What it says,
-//              Your video, Export); the brief is settled in the chat.
+//   stage      the stage the piece is at: brief → inventory → look → video → final. The user sees four steps (What
+//              you want to say: the brief and the inventory; How it looks; Your video; Export).
 //   stages     each stage's status: pending · working (the agent's turn) · review (the user's turn) · changes · approved
 //   brief      what, who, format, tone, action: written by the agent, editable by the user
 //   parts      per part (by its folder in chain.json): status (queued · rendering · review · changes · approved), note
-//   events     what the user did in the studio, in order; `seen` is the last one the agent has read
-//   ask        a question the agent asked in the chat and is waiting on (the studio sends the user there)
+//   events     what the user did in the studio, in order; `seen` is the last one the agent has read, and each
+//              event the agent read carries `readAt`
+//   ask        a question the agent asked and is waiting on; the user answers it in the studio (an `answer` event)
+//   working    what the agent said it is doing (`piece working --on`) and since when; it lapses after 20 minutes
+//   notes      the agent's short replies to the user, shown in the studio's thread (`piece say`)
+//   choices    options the agent put into the studio (`pamo board` while a piece is open), where they show, and
+//              the reply line once the user chose (ADR 0005)
 //   agent      the app or page the agent runs in, so the studio can take the user back to it
 //
 // chain.json stays the source of what plays (order, seconds, joins); piece.json only tracks decisions.
@@ -14,7 +19,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pieceDir } from './chain.mjs';
 
-export const STAGES = ['brief', 'inventory', 'video', 'final'];
+export const STAGES = ['brief', 'inventory', 'look', 'video', 'final'];
 // the stages a piece had before Your video took them over: a piece at one of them is at `video` now
 const OLD_VIDEO = ['look', 'structure', 'parts', 'assembly'];
 export const STAGE_STATUS = ['pending', 'working', 'review', 'changes', 'approved'];
@@ -39,6 +44,13 @@ function upgrade(p) {
   return p;
 }
 
+/** A project whose brand already settles colours, type and a background: How it looks starts done. */
+export function brandSettled(cwd) {
+  const read = (f) => { try { return JSON.parse(fs.readFileSync(path.join(cwd, f), 'utf8')); } catch { return {}; } };
+  const t = read('brand/tokens.json'), set = read('brand/shader-set/set.json');
+  return !!(t.colors?.ground && t.colors?.figure && t.fonts?.display && (Array.isArray(set) ? set : set.entries ?? []).some((e) => e.shader && !e.image));
+}
+
 /** Writes atomically (the studio and the CLI both write it). */
 export function writePiece(dir, p) {
   fs.mkdirSync(dir, { recursive: true });
@@ -67,7 +79,7 @@ export function initPiece({ cwd = process.cwd(), piece, title, brief = {}, force
   return writePiece(dir, {
     v: 1, piece: path.basename(dir), title: title ?? path.basename(dir), brand: tokens.brand ?? null,
     stage: 'brief',
-    stages: Object.fromEntries(STAGES.map((s, i) => [s, { status: i ? 'pending' : 'working' }])),
+    stages: Object.fromEntries(STAGES.map((s, i) => [s, s === 'look' && brandSettled(cwd) ? { status: 'approved', brand: true } : { status: i ? 'pending' : 'working' }])),
     brief: Object.fromEntries(BRIEF_KEYS.map((k) => [k, brief[k] ?? ''])),
     parts: {}, events: [], seen: 0, created: now(), updated: now(),
   });
@@ -75,12 +87,14 @@ export function initPiece({ cwd = process.cwd(), piece, title, brief = {}, force
 
 /** The line the agent reads for an event (same family as the board reply). */
 export function eventLine(p, e) {
-  const who = e.part ? `part ${e.part}` : e.stage;
+  const who = e.part ? `part ${e.part}` : e.stage ?? '';
   const what = e.kind === 'approve' ? 'approved'
     : e.kind === 'changes' ? `changes: "${e.text}"`
     : e.kind === 'order' ? `order ${e.text}`
     : e.kind === 'reopen' ? 'reopened'
     : e.kind === 'failed' ? `could not join the parts: "${e.text}"`
+    : e.kind === 'answer' ? `answered${e.q ? ` "${e.q}"` : ''}: "${e.text}"`
+    : e.kind === 'choice' ? `chose${e.title ? ` on "${e.title}"` : ''}: ${e.text}`
     : e.say ? e.say : `${e.key}="${e.text}"${e.rerendered ? ' (re-rendered)' : ''}`;
   // the studio joins the draft again by itself after an edit by hand; the full-quality render stays the agent's
   const tail = `${e.rejoined ? ' (the studio is joining the draft again)' : ''}${e.rejoin ? ' · join again: pamo chain --draft' : ''}${e.refinal ? ` · the final is out of date: render it again (pamo chain ${p.piece} --motion-blur 5), then review final` : ''}`;
@@ -105,6 +119,7 @@ export function toReview(dir, stage, { skip = false } = {}) {
     if (open.length && !skip) throw new Error(`${open.join(', ')} not approved yet: review ${open.length > 1 ? 'them' : 'it'} first (piece review ${p.piece} ${open[0]}), or pass --skip when the user agreed to move on without ${open.length > 1 ? 'them' : 'it'}`);
     for (const s of open) p.stages[s] = { ...p.stages[s], status: 'approved' };
     delete p.ask;   // handing a stage over means the question in the chat is settled
+    delete p.working;
     p.stage = stage;
     p.stages[stage] = { status: 'review', since: now() };
   });
@@ -116,10 +131,55 @@ export const earlierOpen = (p, stage) => STAGES.slice(0, STAGES.indexOf(stage)).
 /** Events the agent hasn't read; marks them read when `mark`. */
 export function unseen(dir, { mark = true } = {}) {
   let out = [];
-  const p = updatePiece(dir, (q) => { out = q.events.filter((e) => e.n > (q.seen ?? 0)); if (mark && out.length) q.seen = out.at(-1).n; });
+  const p = updatePiece(dir, (q) => {
+    out = q.events.filter((e) => e.n > (q.seen ?? 0));
+    if (mark && out.length) { const at = now(); for (const e of out) e.readAt = at; q.seen = out.at(-1).n; }
+  });
   return { piece: p, events: out };
 }
 
+// what the user does that needs the agent: something asked, answered, approved, reopened, chosen, or a join that failed
+const needsAgent = (e) => ['changes', 'answer', 'reopen', 'choice', 'failed'].includes(e.kind) || (e.kind === 'approve' && !e.part) || e.rejoin || e.refinal;
+
+/**
+ * Listens on the piece between the agent's turns (`pamo piece listen`): returns as soon as the user does something
+ * that needs the agent, with every unread event as lines (and marks them read), or after `timeout` with nothing.
+ * While it listens the studio says so; it is the agent's way to hear the studio without the user going to the chat.
+ */
+export async function listenFor(dir, { timeout = 9 * 60 * 1000, every = 1000, signal } = {}) {
+  const t0 = Date.now();
+  let last = 0;
+  updatePiece(dir, (p) => { delete p.working; });   // listening means it is not doing anything else
+  // interrupted (the agent cancels it, Ctrl+C): stop saying it listens right away
+  const stop = () => { unbeat(dir); process.exit(130); };
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  try {
+    for (;;) {
+      if (Date.now() - last > 3000) { beat(dir, { waiting: 'listen' }); last = Date.now(); }
+      const p = readPiece(dir);
+      const fresh = p.events.filter((e) => e.n > (p.seen ?? 0));
+      if (fresh.some(needsAgent)) { const r = unseen(dir); return { done: true, piece: r.piece, events: r.events, lines: r.events.map((e) => eventLine(r.piece, e)) }; }
+      if (Date.now() - t0 > timeout || signal?.aborted) return { done: false, piece: p, events: [], lines: [] };
+      await new Promise((res) => setTimeout(res, every));
+    }
+  } finally { unbeat(dir); process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+}
+
+const WORKING_FOR = 20 * 60 * 1000;
+/** The agent says what it is doing; the studio shows it, with how long, until it listens, reviews or 20 minutes pass. */
+export function setWorking(dir, on) { return updatePiece(dir, (p) => { delete p.ask; p.working = { on: String(on ?? '').trim() || null, at: now() }; }); }
+/** A short reply from the agent to the user, shown in the studio's thread. */
+export function addNote(dir, text) { return updatePiece(dir, (p) => { (p.notes ??= []).push({ at: now(), text: String(text).trim() }); }); }
+
+/**
+ * What the studio may say about the agent, only from facts: `ask` (a question is open), `listen` (a command of the
+ * agent is waiting on this piece right now), `work` (it said what it is doing, less than 20 minutes ago) or `off`.
+ */
+export function agentState(dir, p = readPiece(dir)) {
+  const l = listening(dir), w = p?.working && Date.now() - Date.parse(p.working.at) < WORKING_FOR ? p.working : null;
+  return { state: p?.ask ? 'ask' : l ? 'listen' : w ? 'work' : 'off', listening: !!l, working: w };
+}
+
 // an event that ends the agent's wait: a decision on the stage under review, or a change asked anywhere
 const decisive = (e, stage) => (e.kind === 'approve' && e.stage === stage && !e.part) || e.kind === 'changes' || e.kind === 'reopen' || e.rejoin || e.refinal;
 
@@ -152,7 +212,15 @@ const beatFile = (dir) => path.join(dir, '.agent.json');
 export function beat(dir, info = {}) { try { fs.writeFileSync(beatFile(dir), JSON.stringify({ at: Date.now(), pid: process.pid, ...info })); } catch { /* a read-only project: the studio just won't know */ } }
 export function unbeat(dir) { try { if (JSON.parse(fs.readFileSync(beatFile(dir), 'utf8')).pid === process.pid) fs.rmSync(beatFile(dir)); } catch { /* already gone */ } }
 /** The command waiting on this piece right now, if any. */
-export function listening(dir, within = 9000) { try { const a = JSON.parse(fs.readFileSync(beatFile(dir), 'utf8')); return Date.now() - a.at < within ? a : null; } catch { return null; } }
+export function listening(dir, within = 9000) {
+  try {
+    const a = JSON.parse(fs.readFileSync(beatFile(dir), 'utf8'));
+    if (Date.now() - a.at >= within) return null;
+    // a command that was killed leaves its last beat behind: it only counts while its process is alive
+    if (a.pid) { try { process.kill(a.pid, 0); } catch (e) { if (e.code === 'ESRCH') return null; } }
+    return a;
+  } catch { return null; }
+}
 
 /** The agent asked the user something in the chat: the studio says so until the agent moves on. */
 export function setAsk(dir, text) { return updatePiece(dir, (p) => { p.ask = { text: String(text ?? '').trim(), at: now() }; }); }
@@ -196,6 +264,49 @@ export function setSceneText(html, key, value) {
   return head + next + tail;
 }
 
+// ── choices: a board shown inside the studio instead of a link (ADR 0005) ─────────────────────────────────────
+/** Puts a board into the piece, on the step and section it decides. Returns its id (`c1`, `c2`…). */
+export function addChoice(dir, { board, where }) {
+  let id;
+  updatePiece(dir, (p) => {
+    p.choices ??= [];
+    id = `c${p.choices.length + 1}`;
+    p.choices.push({ id, board, where, status: 'waiting', at: now() });
+  });
+  return id;
+}
+/** The user's pick on a choice: records the reply line and an event the agent reads. */
+export function settleChoice(p, id, line) {
+  const c = (p.choices ?? []).find((x) => x.id === id);
+  if (!c) throw new Error('no such choice');
+  if (c.status !== 'waiting') throw new Error('already chosen');
+  c.status = 'chosen'; c.line = line; c.chosenAt = now();
+  addEvent(p, { kind: 'choice', stage: c.where?.step ?? p.stage, text: line, title: c.board.title, choice: id });
+  return c;
+}
+/** Waits for the user's pick on a studio choice, beating as listening; returns the reply line, or null on timeout. */
+export async function awaitChoiceIn(dir, id, { timeout = 10 * 60 * 1000, every = 1000 } = {}) {
+  const t0 = Date.now(); let last = 0;
+  const stop = () => { unbeat(dir); process.exit(130); };
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  try {
+    for (;;) {
+      if (Date.now() - last > 3000) { beat(dir, { waiting: 'board' }); last = Date.now(); }
+      const c = (readPiece(dir)?.choices ?? []).find((x) => x.id === id);
+      if (!c) return null;
+      if (c.status === 'chosen') {
+        // the agent has the pick from here: the event that carries it counts as read
+        updatePiece(dir, (p) => { const at = now(); for (const e of p.events) if (e.kind === 'choice' && e.choice === id && !e.readAt) { e.readAt = at; if (e.n === (p.seen ?? 0) + 1) p.seen = e.n; } });
+        return c.line;
+      }
+      if (Date.now() - t0 > timeout) return null;
+      await new Promise((res) => setTimeout(res, every));
+    }
+  } finally { unbeat(dir); process.off('SIGINT', stop); process.off('SIGTERM', stop); }
+}
+/** Takes a choice back out of the studio. */
+export function forgetChoice(dir, id) { return updatePiece(dir, (p) => { p.choices = (p.choices ?? []).filter((x) => x.id !== id); }); }
+
 // ── boards: the decisions taken on paper-motion.app, listed in the studio so the user finds them there too ──────
 const BOARD_STAGE = () => 'video';
 
@@ -204,7 +315,7 @@ export function activePiece(cwd, name) {
   if (name) { const dir = pieceDir(name, cwd); return readPiece(dir) ? dir : null; }
   const root = path.join(cwd, 'pieces');
   if (!fs.existsSync(root)) return null;
-  const live = fs.readdirSync(root).map((d) => path.join(root, d)).filter((d) => { const p = readPiece(d); return p && ['brief', 'inventory', 'video'].includes(p.stage); });
+  const live = fs.readdirSync(root).map((d) => path.join(root, d)).filter((d) => { const p = readPiece(d); return p && ['brief', 'inventory', 'look', 'video'].includes(p.stage); });
   return live.length === 1 ? live[0] : null;
 }
 

package/lib/registry.mjs

@@ -122,7 +122,11 @@ export function llmsTxt(items, site, { full = false } = {}) {
    (an approval, a change to make, or an edit they already made by hand: the brief, words on screen, lengths, joins,
    order; build on those, never undo them). Quick renders for review: \`chain <piece> --drafts\` (each part on its
    own) and \`chain <piece> --draft\` (joined). Only when the user can't open a browser, run the same stages in the
-   chat.
+   chat. Between your turns keep \`npx paper-motion piece listen <piece>\` running in the background: it returns as
+   soon as the user needs you (a message, an answer, an approval), with lines like review's, so they never have to
+   come back to the chat (start it again after; exit 3 means nothing in 9 minutes). Say what you are doing with
+   \`piece working <piece> <stage> --on "…"\`, ask with \`piece ask <piece> "…"\` (they answer in the studio), and
+   reply there with \`piece say <piece> "…"\`. The studio only shows what it can check about you.
 3. **Interview.** Follow the \`make-video\` skill. Without the skills, ask at least: what the brand is in one plain
    line; what this video is for and where it plays (format: 16:9, 9:16, 1:1); its ground, text and accent colors or
    "no brand yet"; three words for the feel and one thing it must never look like; the one action at the end.
@@ -164,9 +168,11 @@ export function llmsTxt(items, site, { full = false } = {}) {
    builds the video itself from what they kept, and then they edit it there, live (words, how each part arrives,
    backgrounds, settings, lengths, transitions, order, adding and swapping parts, colours, type, pace); every edit
    reaches you as a line. Review \`video\` to wait for their approval; they can render the final from the studio. \`chain --check\` warns when the total drifts from the brief's
-   length. Boards you share while a piece is open also appear in its studio (Look or Structure), so the user finds them
-   there; if your shell caps how long a command may run, share with \`--no-wait\` and then
-   \`npx paper-motion board --await <id> --wait 2\` until it prints the line (exit code 3 = not yet).
+   length. While a piece is open and its studio runs, \`board --url\` puts the options into the studio, on the step
+   they decide (How it looks for palettes, type, backgrounds and moves; Your video for transitions and structures),
+   instead of making a link; it waits there and prints the same reply line, and a palette, font pair or background
+   the user picks is applied already. \`--link\` makes a link anyway. If your shell caps how long a command may run,
+   use \`--no-wait\` and then \`npx paper-motion board --await <c1…> --wait 2\` (exit code 3 = not yet).
 
 ## Choosing well: the metadata