sign-off-axi 0.4.1 → 0.4.3

package/dist/cli.js

@@ -10,7 +10,7 @@ import { basename, delimiter, dirname, extname, isAbsolute, join, relative, reso
 import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
-import { CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, appendSendBack, appendMessage, appendRound, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
+import { CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
 import { ContractError, KINDS, MEDIA_BYTES, REPORT_INIT, checkMessage, mediaFiles, parseMessage, reportPage } from './contract.js';
 import { deliverVault, errors, readVaultExpiry, sweepVault, takeVaultExpiries, VaultError } from './vault.js';
 const FORMAT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/file-formats.md';
@@ -86,7 +86,7 @@ examples:
 `,
     validate: `usage: sign-off-axi validate <message.json>... [--kind <kind>] [--expect-invalid]
 Checks message files against the communication contract without posting them: ${CONTRACT}
-A message is one JSON object with "contract": 1, its "kind" and its "schema". This build checks kinds ask, evidence, gate, finding and plan at schema 1, and report at schema 2.
+A message is one JSON object with "contract": 1, its "kind" and its "schema". This build checks kinds ask, evidence, gate, finding, plan and design at schema 1, and report at schema 2.
 An evidence message's media paths read from the message file's folder: each file must be there, inside it, and 50 MB or less.
 A report is a page to tap through: its "view" (.html) and "preview" (its picture, beside it) are checked for their shape here; the files themselves are checked at post, from the board file's folder, filled with no FILL: lines left (see report init).
 A plan's "view" (.html) is checked for its shape here; the file itself is checked at post, from the board file's folder.
@@ -231,6 +231,8 @@ examples:
   sign-off-axi post --kind gate --from gate.json --filer done-done
   sign-off-axi post --kind finding --from finding.json --filer learn-from-mistakes
   sign-off-axi post --kind plan --from plan.json --filer agent-41
+  sign-off-axi post --kind design --from design.json --filer agent-41
+A design message lists project journeys, per-screen image or HTML view variants, and a card preview; post checks every asset stays under the board folder.
   sign-off-axi post .sign-off/decisions.json --type interactive --title "Does the sign-in flow feel right?" --view mocks/sign-in/demo.html --option yes=Yes --option no="Needs work" --recommend yes
   sign-off-axi post --type evidence --title "Sign-in screen on a phone" --about "The new screen loads in 1 second." --media phone.png --media flow.mp4 --link https://github.com/acme/app/pull/12
   sign-off-axi post --type explainer --title "Is the new sign-in clear?" --about "The new sign-in has 2 steps." --media explainer.mp4 --chapter 0:00=Start --chapter 0:12="Step 2"
@@ -322,7 +324,7 @@ function fits(title, key) {
 const ASK_FLAGS = ['why', 'outcome', 'recommend-reason', 'silent-by', 'merge'];
 const MANY = ['option', 'outcome', 'merge'];
 /** Board types that are contract kinds: a decision (the default type) is an ask. */
-const CONTRACT_TYPES = ['decision', 'ask', 'evidence', 'report', 'plan'];
+const CONTRACT_TYPES = ['decision', 'ask', 'evidence', 'report', 'plan', 'design'];
 /** The stored item as the message it came from: the board's own `filed` stamp is not part of a message that names none. */
 const asSent = ({ filed: _filed, ...rest }) => rest;
 /** Items of a --from file that carry contract or kind are contract messages: each is checked against its kind's rules before anything is stored.
@@ -367,12 +369,38 @@ function contractItems(items, from, file, replace = false) {
             checkMessage(check);
             if (check.kind === 'report' || check.kind === 'plan')
                 reportPage(check, dirname(file));
+            if (check.kind === 'design')
+                designFiles(check, dirname(file));
         }
         catch (e) {
             throw e instanceof ContractError ? fail(`${from}: items[${i}]: ${e.message}`, 'VALIDATION_ERROR', e.help) : e;
         }
     });
 }
+function designFiles(m, base) {
+    const paths = [m.preview, ...m.journeys.flatMap((j) => j.screens.flatMap((s) => Object.values(s.views)))];
+    for (const path of paths) {
+        let actual;
+        try {
+            actual = realpathSync(resolve(base, path));
+        }
+        catch {
+            throw new ContractError(`design path ${JSON.stringify(path)} is not there`, `Put ${path} in the board folder or fix its path`);
+        }
+        const rel = relative(realpathSync(base), actual);
+        if (!rel || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel))
+            throw new ContractError(`design path ${JSON.stringify(path)} leads outside the board folder`, 'Copy every design view into the board folder');
+        const info = statSync(actual);
+        if (!info.isFile() || info.size > 5_000_000)
+            throw new ContractError(`design path ${JSON.stringify(path)} must be a file of 5 MB or less`, 'Shrink the design view');
+        try {
+            accessSync(actual, constants.R_OK);
+        }
+        catch {
+            throw new ContractError(`design path ${JSON.stringify(path)} cannot be read`, 'Make the design view readable');
+        }
+    }
+}
 const RAISE_FIELDS = ['title', 'key', 'about', 'detail', 'option', 'recommend', 'default', 'close', ...ASK_FLAGS];
 /** Parses one command's flags strictly; `on` carries a given board file into the next-step hints. */
 function parse(cmd, args, flags) {
@@ -456,7 +484,7 @@ function filerOf(values, session = false) {
 const waitFor = (on, filer, key) => (filer ? `Run \`sign-off-axi wait${on} --filer ${filer}\` to block until the user answers`
     : `Run \`sign-off-axi wait${on}${key ? ` --key ${key}` : ''}\` to block until the user answers`);
 /** Still waiting on the user: not answered, not dismissed, and something to answer (an item with no options and no reply is only shown). */
-const waits = (d) => !d.dismissed && !d.answer && (d.options.length > 0 || !!d.reply || d.type === 'signin' || d.type === 'plan');
+const waits = (d) => !d.dismissed && !d.answer && (d.options.length > 0 || !!d.reply || d.type === 'signin' || d.type === 'plan' || d.type === 'design');
 /** The board's decisions with their latest answer; a missing board file is an empty board.
  *  A dismissal hides an item from the board and is not waiting here either, checked against the same dismissed log the board reads. */
 function board(file, say = warn) {
@@ -512,7 +540,7 @@ function printAnswers(file, rows, waiting, values, help) {
     const rounds = readRounds(file).filter((r) => rows.some((d) => d.key === r.key));
     if (values.json) {
         const asked = (key) => rounds.filter((r) => r.key === key).map(({ note, at, comments }) => ({ note, at, comments }));
-        const out = Object.fromEntries(done.map(({ key, answer, label, close, at, note, comments, notes, decisions }) => [key, { answer, label, close, at, note, comments, notes, decisions, ...(asked(key).length && { rounds: asked(key) }) }]));
+        const out = Object.fromEntries(done.map(({ key, answer, label, close, at, note, comments, notes, decisions, pick }) => [key, { answer, label, close, at, note, comments, notes, decisions, pick, ...(asked(key).length && { rounds: asked(key) }) }]));
         for (const r of rounds)
             if (!out[r.key])
                 out[r.key] = { rounds: asked(r.key) };
@@ -520,7 +548,7 @@ function printAnswers(file, rows, waiting, values, help) {
     }
     const notes = done.some((a) => a.note), sent = [...done, ...rounds].flatMap(({ key, comments = [] }) => comments.map(({ mock, ref, tag, words, text }) => ({ key, mock, ref, tag, words, text })));
     const plan = done.flatMap(({ key, notes: sections = [], decisions: picks = {} }) => [
-        ...sections.map(({ section, verdict, note = '' }) => ({ key, section, verdict, note })),
+        ...sections.map((n) => ({ key, section: n.section ?? `${n.journey}/${n.screen}`, verdict: n.verdict ?? 'change', note: n.note ?? '' })),
         ...Object.entries(picks).map(([decision, pick]) => ({ key, decision, pick })),
     ]);
     return toon({
@@ -555,7 +583,7 @@ function eventLines(file, rows, answers, rounds) {
     const kind = kindOf(file), item = new Map(rows.map((d) => [d.key, d]));
     const head = (event, key) => ({ event, ...kind(key), key, title: item.get(key)?.title });
     const tail = (key, comments) => ({ ...(item.get(key)?.filer && { filer: item.get(key).filer }), ...(comments?.length && { comments }) });
-    return [...answers.map(({ key, answer, label, close, at, note, comments, notes, decisions }) => ({ at, line: { ...head('answer', key), answer, label, close, at, ...(note && { note }), ...(notes && { notes, decisions }), ...tail(key, comments) } })),
+    return [...answers.map(({ key, answer, label, close, at, note, comments, notes, decisions, pick }) => ({ at, line: { ...head('answer', key), answer, label, close, at, ...(note && { note }), ...(notes && { notes, decisions }), ...(pick !== undefined && { pick }), ...tail(key, comments) } })),
         ...rounds.map(({ key, note, at, comments }) => ({ at, line: { ...head('round', key), note, at, ...tail(key, comments) } }))]
         .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0)).map(({ line }) => JSON.stringify(line)).join('\n');
 }
@@ -1137,6 +1165,8 @@ async function postKind(file, on, values, built) {
         // A report's or plan's page is served from the board file's folder, as --view is.
         if (m.kind === 'report' || m.kind === 'plan')
             reportPage(m, dirname(file));
+        if (m.kind === 'design')
+            designFiles(m, dirname(file));
     }
     catch (e) {
         throw e instanceof ContractError ? fail(`${name}: ${e.message}`, 'VALIDATION_ERROR', e.help) : e;
@@ -1225,11 +1255,13 @@ const outcomesOf = (values) => {
 /** Whoever lists the choices names the one they would pick: the board puts it first and marks it. A plain yes/no may leave it out,
  * and a program feeding a whole board with --replace is not held to it. */
 function recommended(items, flags) {
-    const d = items.find((i) => i?.options?.length && i.recommend_value === undefined), values = d?.options.map((o) => o.value).join(', ');
+    const d = items.find((i) => i?.options?.length && (flags || i.type !== 'design' && i.kind !== 'design' ? i.recommend_value === undefined : i.recommend === undefined)), values = d?.options.map((o) => o.value).join(', ');
     if (d && flags)
         throw fail('--recommend is required when you list options', 'VALIDATION_ERROR', `Add --recommend <value>, the option you would pick: one of ${values}`);
-    if (d)
-        throw fail(`items[${items.indexOf(d)}] (key ${d.key}) lists options but no recommend_value`, 'VALIDATION_ERROR', `Add "recommend_value": "<value>", the option you would pick: one of ${values}`);
+    if (d) {
+        const field = !flags && (d.type === 'design' || d.kind === 'design') ? 'recommend' : 'recommend_value';
+        throw fail(`items[${items.indexOf(d)}] (key ${d.key}) lists options but no ${field}`, 'VALIDATION_ERROR', `Add "${field}": "<value>", the option you would pick: one of ${values}`);
+    }
 }
 /** Flags are validated by the same loader as a file: write them as a one-decision file first. Items are checked against the board they go to, so its answers_only or readonly holds. */
 function buildIncoming(values, extra, filer, file) {
@@ -1989,7 +2021,7 @@ const state = () => {
         mockBase: `/mock/${loopback(bind) ? 'local' : mockPass(tokenOf(file))}/`,
         // Who filed an item stays in the file: the page only learns that its filer took the answer.
         // A sign-in's start command stays on this host too: the page only learns that a tap makes a new link, and how the last run went.
-        decisions: loadDecisions(file).map(({ filer: _, start, ...d }) => ({ ...d, ...(start && { start: true, run: signinState(d.key) }), evidenceCard: d.evidence ? evidenceCard(d.evidence) : null,
+        decisions: loadDecisions(file).map(({ filer: _, start, ...d }) => ({ ...d, ...(d.type === 'design' && answers[d.key]?.answer === 'approve' && { status: 'approved' }), ...(start && { start: true, run: signinState(d.key) }), evidenceCard: d.evidence ? evidenceCard(d.evidence) : null,
             ...(d.mocks && { mocks: d.mocks.map((m) => ({ ...m, hash: mockHash(m.path) })) }) })),
         readonly: readOnly(),
         answers_only: answersOnly(),
@@ -2094,6 +2126,23 @@ function evidenceCard(link) {
 }
 const MESSAGE_MAX = 2000;
 async function route(req) {
+    if (req.method === 'GET' && req.url?.startsWith('/design/')) {
+        const [, , , key, ...parts] = new URL(req.url, 'http://localhost').pathname.split('/');
+        const path = parts.map(decodeURIComponent).join('/'), d = loadDecisions(file).find(x => x.key === key && x.type === 'design');
+        const allowed = d?.journeys?.some(j => j.screens.some(s => Object.values(s.views).includes(path)));
+        const type = assetTypes[extname(path).toLowerCase()];
+        try {
+            if (!allowed || !type)
+                return [404, { error: 'Design view is unavailable' }];
+            const actual = under(dirname(file), path);
+            if (statSync(actual).size > MOCK_BYTES)
+                return [404, { error: 'Design view is unavailable' }];
+            return [200, { media: readFileSync(actual), type, point: type === 'text/html' }];
+        }
+        catch {
+            return [404, { error: 'Design view is unavailable' }];
+        }
+    }
     if (req.method === 'GET' && req.url?.startsWith('/mock/')) {
         // /mock/<pass>/<key>~<value>/<file>: that option's design mock, or with no value the item's own view (a diagram or interactive page),
         // and the files beside it in its own folder, so a mock page's relative css, scripts and images load.
@@ -2243,7 +2292,7 @@ async function route(req) {
         appendRound(file, key, note.trim(), comments);
         return [200, state()];
     }
-    const { key, answer, note = '', notes, decisions } = JSON.parse(body) ?? {};
+    const { key, answer, note = '', notes, decisions, verdict, pick } = JSON.parse(body) ?? {};
     if (typeof note !== 'string' || [...note.trim()].length > NOTE_MAX)
         return [400, { error: `The note must be text of ${NOTE_MAX} characters or fewer` }];
     const d = loadDecisions(file).find((x) => x.key === key);
@@ -2263,10 +2312,21 @@ async function route(req) {
         answered(appendAnswer(file, { key, close: 'done' }, answer === REPLY.value ? REPLY : { value: answer, label: answer }, note.trim()));
         return [200, state()];
     }
+    if (d.kind === 'design') {
+        try {
+            answered(appendDesignAnswer(file, d, verdict, notes, pick), d);
+        }
+        catch (e) {
+            if (e instanceof InputError)
+                return [400, { error: e.message }];
+            throw e;
+        }
+        return [200, state()];
+    }
     // A plan's answer is its one send-back: every section's verdict and note, and a pick for each decision.
     if (d.type === 'plan') {
         try {
-            answered(appendSendBack(file, d, notes, decisions), d);
+            answered(appendSendBack(file, d, notes, decisions, note), d);
         }
         catch (e) {
             if (e instanceof InputError)
@@ -2392,7 +2452,7 @@ const server = createServer(async (req, res) => {
         // Beyond loopback every request carries the token: once in the link, then in a cookie the link sets.
         // The file is read on every request, so deleting or replacing it shuts old links out at once.
         const token = tokenOf(file), cookie = `sign-off-${bound}`, given = req.url?.startsWith('/?') ? new URL(req.url, 'http://x').searchParams.get('token') : null;
-        const pass = /^\/mock\/([^/?]*)\//.exec(req.url ?? '')?.[1], want = Buffer.from(pass === undefined ? token : mockPass(token));
+        const pass = /^\/(?:mock|design)\/([^/?]*)\//.exec(req.url ?? '')?.[1], want = Buffer.from(pass === undefined ? token : mockPass(token));
         const sent = Buffer.from(pass ?? given ?? req.headers.cookie?.split(/;\s*/).find((c) => c.startsWith(`${cookie}=`))?.slice(cookie.length + 1) ?? '');
         if (!/^[\w-]{32,}$/.test(token) || sent.length !== want.length || !timingSafeEqual(sent, want)) {
             return res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' }).end('This board needs its access link: run sign-off-axi open on the computer that serves it and open the link it prints.');
@@ -2400,6 +2460,8 @@ const server = createServer(async (req, res) => {
         if (given !== null)
             return res.writeHead(303, { location: '/', 'set-cookie': `${cookie}=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=31536000` }).end();
     }
+    if (req.method === 'GET' && req.url === '/favicon.ico')
+        return res.writeHead(204).end();
     if (req.method === 'GET' && req.url === '/') {
         return res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "default-src 'self' 'unsafe-inline'" }).end(page);
     }

package/dist/contract.js

@@ -11,7 +11,7 @@ export class ContractError extends Error {
     }
 }
 /** The kinds, with the schema number of each. */
-export const SCHEMAS = { ask: 1, report: 2, evidence: 1, gate: 1, finding: 1, plan: 1 };
+export const SCHEMAS = { ask: 1, report: 2, evidence: 1, gate: 1, finding: 1, plan: 1, design: 1 };
 export const KINDS = Object.keys(SCHEMAS);
 const COMMON = ['contract', 'kind', 'schema', 'key', 'title', 'filer', 'link', 'about'];
 const FIELDS = {
@@ -21,6 +21,7 @@ const FIELDS = {
     gate: [...COMMON, 'run', 'options', 'recommend_value', 'close'],
     finding: [...COMMON, 'cause', 'incidents', 'days', 'evidence_ids', 'change_kind', 'proposal', 'options', 'recommend_value'],
     plan: [...COMMON, 'sections', 'decisions', 'steps', 'view'],
+    design: [...COMMON, 'group', 'filed', 'status', 'preview', 'journeys', 'options', 'recommend'],
 };
 /** A done-done run: its id, full commit and the four Checks lines. */
 const RUN = ['run_id', 'commit', 'outcome', 'repro', 'proof', 'evidence'];
@@ -256,6 +257,56 @@ export function checkMessage(m, want, flags = false) {
             throw bad('preview', `${show(m.preview)} must sit in the folder of ${show(m.view)}`, `Put the picture beside the page, such as "${dirname(m.view)}/preview.svg"`);
         return { kind: m.kind, schema: m.schema };
     }
+    if (m.kind === 'design') {
+        text('group', m.group, 40, 'the project name, in 40 characters or fewer');
+        const at = typeof m.filed === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(m.filed) ? new Date(m.filed) : undefined;
+        if (!at || Number.isNaN(at.getTime()) || at.toISOString().replace('.000', '') !== m.filed)
+            throw bad('filed', 'must be a real UTC time with seconds', 'Set "filed" to YYYY-MM-DDTHH:MM:SSZ');
+        if (!['draft', 'in_review'].includes(m.status))
+            throw bad('status', 'must be draft or in_review', 'Set "status" to "draft" or "in_review"');
+        page('preview', /\.(png|jpe?g|webp)$/i, '.png, .jpg, .jpeg or .webp', '"design/preview.png"', 'a design preview');
+        const journeys = list('journeys', 1, 40, ['id', 'title', 'screens'], '{"id":"signup","title":"Sign up","screens":[...]}');
+        const ids = [];
+        journeys.forEach((j, n) => {
+            if (typeof j.id !== 'string' || !/^[a-z0-9-]{1,40}$/.test(j.id))
+                throw bad(`journeys[${n}].id`, 'must be a short lowercase id', 'Set it to a slug such as "signup"');
+            if (ids.includes(j.id))
+                throw bad(`journeys[${n}].id`, `repeats ${j.id}`, 'Give each journey its own id');
+            ids.push(j.id);
+            text(`journeys[${n}].title`, j.title, 120, 'the journey title');
+            if (!Array.isArray(j.screens) || !j.screens.length || j.screens.length > 80)
+                throw bad(`journeys[${n}].screens`, 'must list 1 to 80 screens', 'Add at least one screen with a view');
+            const screenIds = [];
+            j.screens.forEach((s, k) => {
+                const p = `journeys[${n}].screens[${k}]`;
+                if (!s || typeof s !== 'object' || Array.isArray(s) || Object.keys(s).some(x => !['id', 'title', 'views'].includes(x)))
+                    throw bad(p, 'must have only id, title and views', 'Use {"id":"welcome","title":"Welcome","views":{...}}');
+                if (typeof s.id !== 'string' || !/^[a-z0-9-]{1,40}$/.test(s.id))
+                    throw bad(`${p}.id`, 'must be a short lowercase id', 'Set it to a slug such as "welcome"');
+                if (screenIds.includes(s.id))
+                    throw bad(`${p}.id`, `repeats ${s.id}`, 'Give each screen its own id');
+                screenIds.push(s.id);
+                text(`${p}.title`, s.title, 120, 'the screen title');
+                const views = s.views, variants = ['phone_light', 'phone_dark', 'computer_light', 'computer_dark'];
+                if (!views || typeof views !== 'object' || Array.isArray(views) || Object.keys(views).some(v => !variants.includes(v)) || !Object.keys(views).length)
+                    throw bad(`${p}.views`, 'must map at least one supported view to a path', 'Add a phone_light, phone_dark, computer_light or computer_dark path');
+                for (const [variant, path] of Object.entries(views)) {
+                    text(`${p}.views.${variant}`, path, 256, 'a board-relative image or HTML path');
+                    if (/^([\\/]|[A-Za-z]:)/.test(path) || path.split(/[\\/]/).includes('..') || /[?#\\]/.test(path) || !/\.(png|jpe?g|webp|html)$/i.test(path))
+                        throw bad(`${p}.views.${variant}`, 'must be a relative .png, .jpg, .jpeg, .webp or .html path without ..', 'Put the view under the board folder');
+                }
+            });
+        });
+        if (m.options !== undefined) {
+            if (!Array.isArray(m.options) || m.options.length < 2 || m.options.length > 6)
+                throw bad('options', 'must list 2 to 6 options', 'Set options to 2-6 {"value":"...","label":"..."} choices');
+            checkOptions('options', m.options);
+            recommend('recommend', m, m.options);
+        }
+        else if (m.recommend !== undefined)
+            throw bad('recommend', 'requires options', 'Add options or remove recommend');
+        return { kind: m.kind, schema: m.schema };
+    }
     // A plan is sections to approve or change, decisions with a recommended pick, steps to tap through, and where it goes as a diagram.
     if (m.kind === 'plan') {
         const ids = list('sections', 1, 8, ['id', 'heading', 'body'], '{"id":"goals","heading":"Goals and non-goals","body":"<what it does and does not do>"}').map((o, n) => {

package/dist/store.js

@@ -155,7 +155,7 @@ export function loadDecisions(path, board) {
         }
         // A ladder rung: a diagram image, or an interactive page the board frames in a sandbox.
         // A report is a page and its picture; one stored before reports had pages still loads, as a note with neither.
-        const report = d.kind === 'report', plan = d.kind === 'plan';
+        const report = d.kind === 'report', plan = d.kind === 'plan', design = d.kind === 'design';
         if (d.type === 'plan' && !plan)
             throw bad('type', 'plan needs "kind": "plan": post it with sign-off-axi post --kind plan');
         const views = report ? (d.view !== undefined || d.preview !== undefined ? VIEWS.interactive : undefined) : plan ? VIEWS.interactive : Object.hasOwn(VIEWS, d.type ?? '') ? VIEWS[d.type] : undefined;
@@ -170,9 +170,9 @@ export function loadDecisions(path, board) {
                 if (d[f] !== undefined)
                     throw bad(f, `must be left out: a report takes no answer${f === 'options' ? '' : ' and shows only under Reports'}`);
         // A plan takes its answer from its sections and decisions, sent back at once, so it has no options of its own.
-        const options = d.options ?? (report || signin || plan ? [] : d.type === 'evidence' ? VERDICTS : YES_NO);
+        const options = d.options ?? (report || signin || plan || design ? [] : d.type === 'evidence' ? VERDICTS : YES_NO);
         // An empty list is an item to look at only, unless it takes a reply: only a board another program feeds, a report or a sign-in shows those.
-        if (!Array.isArray(options) || options.length === 1 || (!options.length && !fed && !report && !signin && !plan) || options.length > 6
+        if (!Array.isArray(options) || options.length === 1 || (!options.length && !fed && !report && !signin && !plan && !design) || options.length > 6
             || !options.every((o) => isKey(o?.value) && isText(o.label) && o.label.trim() && (o.outcome === undefined || isText(o.outcome)))) {
             throw bad('options', 'must be 2 to 6 items (or empty on a readonly or answers_only board), each a value of 1-128 of A-Z a-z 0-9 . _ - and a label');
         }
@@ -218,6 +218,7 @@ export function loadDecisions(path, board) {
             // So is a finding's proposal, with the counts and records behind it.
             ...(d.kind === 'finding' && { finding: { cause: d.cause, incidents: d.incidents, days: d.days, evidence_ids: d.evidence_ids, change_kind: d.change_kind, proposal: d.proposal } }),
             ...(plan && { sections: d.sections, decisions: d.decisions }),
+            ...(design && { kind: 'design', type: 'design', group: d.group, filed: d.filed, status: d.status, preview: d.preview, journeys: d.journeys, ...(d.options && { options: d.options, recommend_value: d.recommend }) }),
             ...(d.type === 'explainer' && d.chapters && { chapters: d.chapters.map(({ at, title }) => ({ at, title })) }),
         };
     });
@@ -279,8 +280,33 @@ function saveAnswer(decisionsPath, d, option, note, comments = [], by) {
     appendLine(answersPath(decisionsPath), answer);
     return answer;
 }
-/** Saves a plan's one send-back as its answer: each section approved or changed (a change says what to change), and one option per decision. An identical send-back again saves nothing. */
-export function appendSendBack(decisionsPath, d, notes, picks = {}) {
+/** Saves a design answer with screen-specific notes and an optional listed direction pick. */
+export function appendDesignAnswer(decisionsPath, d, verdict, notes, pick) {
+    const bad = (rule) => new InputError(`key ${d.key}: ${rule}`);
+    if (verdict !== 'approve' && verdict !== 'change')
+        throw bad('verdict must be approve or change');
+    if (!Array.isArray(notes) || (verdict === 'change' && !notes.length))
+        throw bad('notes must be a list, with at least one note on change');
+    const screens = new Set((d.journeys ?? []).flatMap(j => j.screens.map(s => `${j.id}/${s.id}`)));
+    for (const n of notes)
+        if (!n || !screens.has(`${n.journey}/${n.screen}`) || !isText(n.note) || !n.note.trim() || [...n.note].length > NOTE_MAX)
+            throw bad('each note needs a known journey and screen, and text of 500 characters or fewer');
+    if (new Set(notes.map(n => `${n.journey}/${n.screen}`)).size !== notes.length)
+        throw bad('notes must name each screen once');
+    const options = d.options ?? [];
+    if (options.length ? !options.some(o => o.value === pick) : pick !== undefined)
+        throw bad('pick must be one listed option, or omitted when no options were offered');
+    const answer = { key: d.key, answer: verdict, label: verdict === 'approve' ? 'Approved' : 'Changes requested', close: d.close ?? 'done', at: now(), notes, ...(pick !== undefined && { pick: pick }) };
+    const current = readAnswers(decisionsPath)[d.key];
+    if (current?.answer === answer.answer && JSON.stringify([current.notes, current.pick]) === JSON.stringify([answer.notes, answer.pick]))
+        return;
+    appendLine(answersPath(decisionsPath), answer);
+    return answer;
+}
+/** Saves a plan's one send-back as its answer: each section approved or changed (a change says what to change, an approval may carry a comment),
+ * one answer per decision (a listed option value, or the person's own words when none fits), and an optional whole-plan comment.
+ * An identical send-back again saves nothing. */
+export function appendSendBack(decisionsPath, d, notes, picks = {}, comment = '') {
     const bad = (rule) => new InputError(`key ${d.key}: ${rule}`), ids = d.sections.map((s) => s.id), keys = d.decisions.map((q) => q.key);
     if (!Array.isArray(notes) || notes.length !== ids.length || !ids.every((id) => notes.filter((n) => n?.section === id).length === 1))
         throw bad(`notes must list each section once: ${ids.join(', ')}`);
@@ -293,13 +319,16 @@ export function appendSendBack(decisionsPath, d, notes, picks = {}) {
             throw bad(`section ${section} needs a note on what to change`);
     }
     const p = picks;
-    if (!p || typeof p !== 'object' || Array.isArray(p) || Object.keys(p).length !== keys.length || !d.decisions.every((q) => q.options.some((o) => o.value === p[q.key]))) {
-        throw bad(`decisions must pick one listed option for each of: ${keys.join(', ') || 'none'}`);
+    if (!p || typeof p !== 'object' || Array.isArray(p) || Object.keys(p).length !== keys.length || !d.decisions.every((q) => isText(p[q.key]) && p[q.key].trim() && [...p[q.key].trim()].length <= NOTE_MAX)) {
+        throw bad(`decisions must answer each of: ${keys.join(', ') || 'none'}, with an option or your own words of ${NOTE_MAX} characters or fewer`);
     }
-    const answer = { key: d.key, answer: 'sent', label: 'Sent back', close: d.close, at: now(),
-        notes: ids.map((id) => notes.find((n) => n.section === id)).map(({ section, verdict, note }) => ({ section, verdict, ...(note?.trim() && { note: note.trim() }) })), decisions: Object.fromEntries(keys.map((k) => [k, p[k]])) };
+    if (comment !== '' && comment !== undefined && (!isText(comment) || [...comment.trim()].length > NOTE_MAX))
+        throw bad(`comment must be text of ${NOTE_MAX} characters or fewer`);
+    const note = typeof comment === 'string' ? comment.trim() : '';
+    const answer = { key: d.key, answer: 'sent', label: 'Sent back', close: d.close, at: now(), ...(note && { note }),
+        notes: ids.map((id) => notes.find((n) => n.section === id)).map(({ section, verdict, note }) => ({ section, verdict, ...(note?.trim() && { note: note.trim() }) })), decisions: Object.fromEntries(keys.map((k) => [k, p[k].trim()])) };
     const current = readAnswers(decisionsPath)[d.key];
-    if (current?.answer === answer.answer && JSON.stringify([current.notes, current.decisions]) === JSON.stringify([answer.notes, answer.decisions]))
+    if (current?.answer === answer.answer && JSON.stringify([current.note ?? '', current.notes, current.decisions]) === JSON.stringify([answer.note ?? '', answer.notes, answer.decisions]))
         return;
     appendLine(answersPath(decisionsPath), answer);
     return answer;

package/fixtures/contract/README.md

@@ -9,8 +9,8 @@ fixtures/contract/<kind>.v<schema>/valid-<name>.json
 fixtures/contract/<kind>.v<schema>/invalid-<field>-<rule>.json
 ```
 
-- `<kind>` is `ask`, `report`, `evidence`, `gate`, `finding` or `plan`, and `<schema>` its schema number, such as `ask.v1/`. A version ships a folder for every kind it validates. This version ships `ask.v1/`, `report.v2/`, `evidence.v1/`, `gate.v1/`, `finding.v1/` and `plan.v1/`. This is the one list of shipped folders; other docs point here.
-- Each file holds one message. An evidence fixture that names `media` ships those files next to it, and a report fixture its page and picture, and a plan fixture its page, under `page/`.
+- `<kind>` is `ask`, `report`, `evidence`, `gate`, `finding`, `plan` or `design`, and `<schema>` its schema number, such as `ask.v1/`. A version ships a folder for every kind it validates. This version ships `ask.v1/`, `report.v2/`, `evidence.v1/`, `gate.v1/`, `finding.v1/`, `plan.v1/` and `design.v1/`. This is the one list of shipped folders; other docs point here.
+- Each file holds one message. An evidence fixture that names `media` ships those files next to it, and a report fixture its page and picture, a plan fixture its page, under `page/`, and a design fixture its views, under `design/`.
 - Each kind has at least 2 valid files and 3 invalid ones: one with a required field missing, one over a limit, and one with an unknown field.
 - An invalid file breaks exactly one rule. Its name gives the field and the rule, such as `invalid-title-too-long.json`, and sign-off's own tests check that the refusal names that field.
 - Demo data uses the name Umer. No real names, paths or tokens.

package/fixtures/contract/design.v1/design/welcome.html

@@ -0,0 +1 @@
+<!doctype html><html><head><meta name="viewport" content="width=device-width"><style>@media(prefers-color-scheme:dark){body{background:#111;color:#fff}}</style></head><body><button>Continue</button></body></html>

package/fixtures/contract/design.v1/invalid-journeys-missing.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"design","schema":1,"key":"chat-journeys","title":"Chat app journeys","about":"Review onboarding.","group":"Chat app","filed":"2026-10-18T12:00:00Z","status":"in_review","preview":"design/preview.png"}

package/fixtures/contract/design.v1/invalid-preview-escape.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"design","schema":1,"key":"chat-journeys","title":"Chat app journeys","about":"Review onboarding.","group":"Chat app","filed":"2026-10-18T12:00:00Z","status":"in_review","preview":"../preview.png","journeys":[{"id":"onboarding","title":"Onboarding","screens":[{"id":"welcome","title":"Welcome","views":{"phone_light":"design/welcome.png"}}]}]}

package/fixtures/contract/design.v1/invalid-unknown-field.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"design","schema":1,"key":"chat-journeys","title":"Chat app journeys","about":"Review onboarding.","group":"Chat app","filed":"2026-10-18T12:00:00Z","status":"in_review","preview":"design/preview.png","unknown":"x","journeys":[{"id":"onboarding","title":"Onboarding","screens":[{"id":"welcome","title":"Welcome","views":{"phone_light":"design/welcome.png"}}]}]}

package/fixtures/contract/design.v1/valid-basic.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"design","schema":1,"key":"chat-journeys","title":"Chat app journeys","filer":"agent-41","about":"Review onboarding and messaging.","group":"Chat app","filed":"2026-10-18T12:00:00Z","status":"in_review","preview":"design/preview.png","journeys":[{"id":"onboarding","title":"Onboarding","screens":[{"id":"welcome","title":"Welcome","views":{"phone_light":"design/welcome.png","computer_dark":"design/welcome.html"}}]}]}

package/fixtures/contract/design.v1/valid-choice.json

@@ -0,0 +1 @@
+{"contract":1,"kind":"design","schema":1,"key":"chat-choice","title":"Choose a chat direction","about":"Compare two chat layouts.","group":"Chat app","filed":"2026-10-18T12:00:00Z","status":"draft","preview":"design/preview.png","options":[{"value":"simple","label":"Simple"},{"value":"rich","label":"Rich"}],"recommend":"simple","journeys":[{"id":"messages","title":"Messages","screens":[{"id":"inbox","title":"Inbox","views":{"phone_light":"design/inbox.png"}}]}]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sign-off-axi",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "One review board for evidence, quick yes/no decisions and retro changes.",
   "type": "module",
   "bin": { "sign-off-axi": "dist/cli.js" },

package/web/index.html

@@ -149,6 +149,60 @@
   #reader .close { display: inline-flex; flex: none; align-items: center; min-height: 3rem; margin-left: -0.5rem; padding: 0 0.5rem; border-radius: 0.625rem; color: var(--accent); font-weight: 650; text-decoration: none; }
   #reader h1 { margin: 0; min-width: 0; overflow: hidden; font-size: 1rem; font-weight: 650; text-overflow: ellipsis; white-space: nowrap; }
   #reader iframe { flex: 1; width: 100%; border: 0; background: var(--bg); }
+  #reader h1:not(:focus-visible) { outline: none; }
+  #reader h1:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  .i-plan { --area: var(--c-waiting); }
+  #reader .plan-scroll { flex: 1; min-height: 0; overflow: auto; padding: 1.25rem 1.25rem 9rem; }
+  .plan-layout { max-width: 72rem; margin: auto; display: grid; gap: 2rem; }
+  .plan-main { min-width: 0; }
+  .plan-main > h2 { margin: 2rem 0 0.75rem; }
+  .plan-main > h2:first-of-type { font-size: 3.5rem; line-height: 1.15; margin: 0.5rem 0; }
+  .plan-main > p { margin: 0.5rem 0 1.5rem; }
+  .plan-summary { display: flex; gap: 0.75rem; color: var(--muted); font-size: 1.125rem; line-height: 1.5; margin: 1.5rem 0 2rem; }
+  #reader .plan-view { width: 100%; height: 22rem; flex: none; border-radius: 1rem; }
+  .plan-section, .plan-decision, .plan-explain { background: var(--surface); border-radius: 1.125rem; padding: 1rem; margin: 1rem 0; scroll-margin-top: 1rem; }
+  .plan-section h3, .plan-decision h3 { font-size: 1.375rem; line-height: 1.3; margin: 0 0 0.75rem; }
+  .plan-section p { white-space: pre-line; }
+  .plan-verdicts { display: flex; gap: 0.625rem; }
+  .plan-verdicts button { flex: 1; border: 0; border-radius: 980px; background: var(--sunk); font-weight: 600; }
+  .plan-verdicts button[aria-pressed="true"] { box-shadow: inset 0 0 0 1.5px currentColor; background: var(--surface); }
+  .plan-verdicts button[aria-pressed="true"]::before, .plan-decision button[aria-pressed="true"]::before { content: none; }
+  .plan-verdicts .approve[aria-pressed="true"] { color: var(--ok); }
+  .plan-verdicts .change[aria-pressed="true"] { color: var(--warn); }
+  .plan-section label { display: grid; gap: 0.5rem; margin-top: 1rem; color: var(--muted); }
+  .plan-section label[hidden] { display: none; }
+  .plan-section textarea { width: 100%; min-height: 7rem; padding: 0.75rem; background: var(--sunk); }
+.plan-decision label { display: grid; gap: 0.5rem; margin-top: 0.75rem; color: var(--muted); }
+.plan-decision textarea { width: 100%; min-height: 4rem; padding: 0.75rem; background: var(--sunk); }
+  .plan-decision .choices { display: grid; grid-template-columns: minmax(0, 1fr); gap: 0.625rem; }
+  .plan-decision .choices button { text-align: left; border-radius: 0.875rem; padding: 0.875rem; gap: 0.25rem; }
+  .plan-decision .choices button .tag { margin: 0; text-transform: none; letter-spacing: normal; color: var(--accent); }
+  .plan-decision .choices button .tag::before { content: none; }
+  .plan-decision .choices button[aria-pressed="true"] { background: color-mix(in srgb, var(--accent) 12%, var(--surface)); color: var(--text); border: 2px solid var(--accent); }
+  .plan-decision .tag { display: block; color: var(--accent); font-size: 0.875rem; }
+  .plan-explain .foot { justify-content: space-between; }
+  .plan-send { position: absolute; bottom: 0; left: 0; right: 0; padding: 0.625rem 1rem calc(0.75rem + env(safe-area-inset-bottom)); background: var(--bar); border-top: 1px solid var(--line); }
+  .plan-send p { margin: 0 0 0.5rem; }
+  .plan-send button { width: 100%; }
+  .plan-next-row { display: flex; align-items: center; justify-content: space-between; gap: 1rem; margin-bottom: 0.5rem; }
+  .plan-next { width: auto !important; padding: 0; border: 0; background: none; color: var(--accent); font-weight: 600; }
+  .plan-send .err:empty { display: none; }
+  .plan-progress button { width: 100%; padding: 0.5rem 0; display: flex; justify-content: space-between; gap: 1rem; background: none; text-align: left; border-radius: 0.5rem; font-size: 1rem; }
+  .plan-progress span { color: var(--muted); }
+  @media (max-width: 59.999rem) { #reader .plan-scroll { margin-bottom: calc(9rem + env(safe-area-inset-bottom)); } #reader .plan-scroll.sent { margin-bottom: 0; } .plan-send h2, .plan-progress { display: none; } .plan-send p { font-size: 1rem; } }
+  #reader .plan-sent .back { display: inline-flex; }
+  .plan-sent { text-align: center; padding-top: 2rem; }
+  .plan-sent h2 { color: var(--ok); font-size: 2.125rem; }
+  .plan-sent .icon { margin: auto; background: var(--ok); }
+  .plan-layout.sent { grid-template-columns: minmax(0, 42.5rem); justify-content: center; }
+  .plan-send[hidden] { display: none; }
+  @media (min-width: 60rem) {
+    #reader .plan-scroll { padding: 2rem 3rem; }
+    .plan-layout { grid-template-columns: minmax(0, 42.5rem) minmax(15rem, 1fr); }
+    .plan-send { position: sticky; align-self: start; top: 0; border: 0; border-radius: 1.125rem; padding: 1.25rem; }
+    .plan-next { display: none; }
+    .plan-section, .plan-decision { padding: 1.5rem; }
+  }
   body.reading { overflow: hidden; }
   .foot { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem 1rem; }
   .foot .meta { margin: 0 auto 0 0; }
@@ -552,6 +606,12 @@
   }
 
   function row(d, { x = true } = {}) {
+    if (d.kind === 'design') {
+      const original = /^https?:/.test(d.link ?? '') ? el('p', { class: 'meta' }, el('a', { href: d.link, target: '_blank', rel: 'noopener noreferrer',
+        'aria-label': `Open original, ${d.title}` }, 'Open original')) : '';
+      return el('article', { class: 'row design', id: `item-${d.key}` },
+        el('div', {}, el('h3', { dir: 'auto' }, d.title), el('p', { class: 'about', dir: 'auto' }, d.about)), original);
+    }
     const err = el('div', { class: 'err', role: 'alert', id: `err-${d.key}` });
     const saved = Object.hasOwn(state.answers, d.key) ? state.answers[d.key] : undefined;
     // A read-only board, or an item with nothing to answer, shows no answer, note or comment controls.
@@ -572,7 +632,7 @@
     const update = d.type === 'evidence', card = d.evidenceCard, result = RESULT[card?.result];
     const brow = [update && area(d) !== 'waiting' ? `Update ${d.number}` : kind(d), result ? el('span', { class: `st ${result[0]}` }, result[1]) : '',
       update && d.filed ? (isToday(d.filed) ? el('span', { class: 'st new' }, 'New') : day(d.filed)) : '', seen].filter(Boolean);
-    const lead = el('div', { class: 'lead' }, x ? xBtn(d) : '', brow.length ? el('p', { class: 'eyebrow' }, ...brow) : '', el('h3', { dir: 'auto' }, name));
+    const lead = el('div', { class: 'lead' }, x ? xBtn(d) : '', brow.length ? el('p', { class: 'eyebrow' }, ...(d.type === 'plan' ? [icon('plan')] : []), ...brow) : '', el('h3', { dir: 'auto' }, name));
     if (d.type === 'signin') return signin(d, lead, saved, err);
     if (d.type === 'plan') return plan(d, lead);
     const quiet = !ro && d.options.find((o) => o.value === d.default_if_silent);
@@ -869,6 +929,7 @@
     evidence: 'M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1zM9 12l2 2 4-4',
     reports: 'M12 7v14M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z',
     answered: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20zM9 12l2 2 4-4',
+    plan: 'M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7zM14 2v6h6M8 13h8M8 17h8M8 9h2',
     you: 'M12 4a4 4 0 1 0 0 8 4 4 0 0 0 0-8zM4.5 20.5c1.2-3.6 4-5.5 7.5-5.5s6.3 1.9 7.5 5.5' };
   // The drawings are fixed strings from this page, never text from the board file.
   const icon = (a) => { const s = el('span', { class: `icon i-${a}`, 'aria-hidden': 'true' }); s.innerHTML = `<svg viewBox="0 0 24 24"><path d="${ICONS[a]}"/></svg>`; return s; };
@@ -877,7 +938,7 @@
    *  A plan has no options but waits for its send-back. */
   const area = (d) => {
     const a = isAnswered(d) ? 'answered' : d.area ?? (d.type === 'evidence' ? 'evidence'
-      : state.readonly || d.type === 'explainer' || !(d.options.length || d.reply || d.type === 'signin' || d.type === 'plan') ? 'reports' : 'waiting');
+      : state.readonly || d.type === 'explainer' || !(d.options.length || d.reply || d.type === 'signin' || d.type === 'plan' || d.kind === 'design') ? 'reports' : 'waiting');
     // Reports lists only what explains: a page to tap through, or a narrated video. Text alone (a receipt, a status line) is a note, folded under it.
     return a === 'reports' && !state.readonly && d.type !== 'explainer' && !reads(d) ? 'notes' : a;
   };
@@ -932,7 +993,7 @@
   /** A short row: a picture (or the area's mark) and the title; an answered item has its answer and time under the title. */
   const compact = (d, a) => {
     const s = state.answers[d.key];
-    return [thumb(a, pic(d)), el('span', { class: 't' }, el('strong', { dir: 'auto' }, title(d)), s
+    return [thumb(d.type === 'plan' ? 'plan' : a, pic(d)), el('span', { class: 't' }, el('strong', { dir: 'auto' }, title(d)), s
       ? el('span', { class: 'ans' }, el('b', { dir: 'auto' }, s.answer === 'text' ? 'Your reply' : s.label), el('time', {}, isToday(s.at) ? hhmm(s.at) : day(s.at)))
       : el('span', { class: 'meta', dir: 'auto' }, sub(d)))];
   };
@@ -1013,6 +1074,116 @@
     return box;
   }
 
+  /** Plan answers stay on the trusted board, never in the agent's sandboxed page. Drafts survive refresh until the server saves them. */
+  function planReview(d, url) {
+    const saved = answerOf(d.key), ro = !!saved || state.readonly || !!FROZEN, draftKey = `plan:${d.key}`;
+    let draft;
+    try { draft = JSON.parse(drafts.get(draftKey) ?? '{}'); } catch { draft = {}; }
+    const notes = new Map((saved?.notes ?? draft.notes ?? []).filter((n) => d.sections.some((s) => s.id === n.section)).map((n) => [n.section, n]));
+    const picks = new Map(Object.entries(saved?.decisions ?? draft.decisions ?? {}).filter(([key, value]) => d.decisions.some((q) => q.key === key) && typeof value === 'string' && value.trim()));
+    let comment = saved?.note ?? (typeof draft.comment === 'string' ? draft.comment : '');
+    const answered = (q) => typeof picks.get(q.key) === 'string' && !!picks.get(q.key).trim();
+    const remember = () => { drafts.set(draftKey, JSON.stringify({ notes: [...notes.values()], decisions: Object.fromEntries(picks), ...(comment.trim() && { comment }) })); keep(); };
+    const main = el('div', { class: 'plan-main' }), panel = el('aside', { class: 'plan-send' });
+    const status = el('p', { role: 'status' }), err = el('p', { class: 'err', role: 'alert' }), progress = el('div', { class: 'plan-progress' });
+    const send = el('button', { class: 'open-link' }, 'Send back'), next = el('button', { class: 'plan-next' }, 'Go to next');
+    const complete = (s) => { const n = notes.get(s.id); return n?.verdict === 'approve' || (n?.verdict === 'change' && n.note?.trim()); };
+    next.onclick = () => {
+      const section = d.sections.find((s) => !complete(s)), decision = d.decisions.find((q) => !answered(q));
+      document.getElementById(section ? `plan-section-${section.id}` : `plan-decision-${decision?.key}`)?.scrollIntoView({ block: 'start' });
+    };
+    const update = () => {
+      const left = d.sections.filter((s) => !complete(s)).length, decisions = d.decisions.filter((q) => !answered(q)).length;
+      status.textContent = saved ? 'Sent back. Your answers are saved.' : left || decisions ? `${left} section${left === 1 ? '' : 's'} and ${decisions} decision${decisions === 1 ? '' : 's'} left` : 'Ready. Every part has an answer.';
+      send.disabled = ro || !!left || !!decisions;
+      next.hidden = !left && !decisions;
+      progress.replaceChildren(...d.sections.map((s) => {
+        const verdict = notes.get(s.id)?.verdict, b = el('button', {}, s.heading, el('span', {}, verdict === 'approve' ? 'Approved' : verdict === 'change' ? 'Change' : 'To review'));
+        b.onclick = () => document.getElementById(`plan-section-${s.id}`).scrollIntoView(); return b;
+      }), d.decisions.length ? el('p', { class: 'meta' }, `${d.decisions.length - decisions} of ${d.decisions.length} decisions answered`) : '');
+    };
+    if (saved) {
+      main.append(el('div', { class: 'plan-sent', role: 'status' }, icon('answered'), el('h2', {}, 'Sent back'), el('p', {}, 'Your section notes and decisions are saved for the agent.'),
+        el('a', { class: 'back', href: '#answered' }, 'See it in Answered'),
+        saved.note ? el('p', { dir: 'auto' }, `Your whole-plan comment: ${saved.note}`) : ''));
+    }
+    main.append(el('p', { class: 'eyebrow' }, icon('plan'), 'Plan'), el('h2', { dir: 'auto' }, d.title), el('p', { dir: 'auto' }, d.about ?? ''));
+    if (!saved) main.append(el('iframe', { class: 'plan-view', src: url, title: `Plan: ${d.title}`, sandbox: 'allow-scripts' }),
+      el('p', { class: 'plan-summary' }, icon('plan'), `${d.sections.length} sections to approve or change, and ${d.decisions.length} decisions to make. Nothing is built until you send back.`));
+    main.append(el('h2', {}, saved ? 'What you sent' : 'The plan'), saved ? '' : el('p', { class: 'meta' }, 'Approve or change each part. A change needs a note, an approval can carry a comment, and a decision takes an option or your own words.'));
+    d.sections.forEach((s, i) => {
+      const card = el('section', { class: 'plan-section', id: `plan-section-${s.id}`, 'aria-label': s.heading });
+      const approve = el('button', { class: 'approve', 'aria-label': `Approve, ${s.heading}` }, 'Approve');
+      const change = el('button', { class: 'change', 'aria-label': `Change, ${s.heading}` }, 'Change');
+      const field = el('textarea', { id: `plan-note-${s.id}`, maxlength: '500', placeholder: 'Write your note for the agent' });
+      field.value = notes.get(s.id)?.note ?? '';
+      field.disabled = ro;
+      const caption = el('span', {}, '');
+      const note = el('label', { for: field.id }, caption, field);
+      const draw = () => {
+        const verdict = notes.get(s.id)?.verdict;
+        card.dataset.verdict = verdict ?? '';
+        approve.setAttribute('aria-pressed', verdict === 'approve');
+        approve.textContent = verdict === 'approve' ? '✓ Approved' : 'Approve';
+        change.setAttribute('aria-pressed', verdict === 'change');
+        approve.disabled = change.disabled = ro;
+        caption.textContent = verdict === 'approve' ? `Comment for the agent on ${s.heading.toLowerCase()} (optional)` : `What should change in ${s.heading.toLowerCase()}?`;
+        note.hidden = !verdict && !field.value;
+        update();
+      };
+      [approve, change].forEach((b, n) => b.onclick = () => {
+        notes.set(s.id, { section: s.id, verdict: n ? 'change' : 'approve', ...(field.value.trim() && { note: field.value }) });
+        remember(); draw(); if (n) field.focus();
+      });
+      field.oninput = () => { notes.set(s.id, { section: s.id, verdict: notes.get(s.id)?.verdict ?? 'change', note: field.value }); remember(); draw(); };
+      card.append(el('h3', { dir: 'auto' }, `${i + 1}. ${s.heading}`), el('p', { dir: 'auto' }, s.body), el('div', { class: 'plan-verdicts', role: 'group', 'aria-label': s.heading }, approve, change), note);
+      main.append(card); draw();
+    });
+    if (d.decisions.length) main.append(el('h2', {}, 'Decisions for you'));
+    d.decisions.forEach((q) => {
+      const choices = el('div', { class: 'choices', role: 'group', 'aria-label': q.question });
+      const other = el('textarea', { id: `plan-other-${q.key}`, maxlength: '500', placeholder: 'Other: write your own answer' });
+      other.value = q.options.some((o) => o.value === picks.get(q.key)) ? '' : (picks.get(q.key) ?? '');
+      other.disabled = ro;
+      const press = () => [...choices.children].forEach((b, i) => b.setAttribute('aria-pressed', q.options[i].value === picks.get(q.key)));
+      other.oninput = () => {
+        if (other.value.trim()) picks.set(q.key, other.value);
+        else if (!q.options.some((o) => o.value === picks.get(q.key))) picks.delete(q.key);
+        remember(); press(); update();
+      };
+      q.options.forEach((o) => {
+        const b = el('button', { 'aria-pressed': picks.get(q.key) === o.value, ...(ro && { disabled: '' }) }, el('strong', {}, o.label),
+          o.value === q.recommend ? el('span', { class: 'tag' }, 'Recommended') : '', el('span', { class: 'out', dir: 'auto' }, o.outcome));
+        b.onclick = () => { picks.set(q.key, o.value); other.value = ''; remember(); press(); update(); };
+        choices.append(b);
+      });
+      main.append(el('section', { class: 'plan-decision', id: `plan-decision-${q.key}` }, el('h3', { dir: 'auto' }, q.question), el('p', { class: 'meta', dir: 'auto' }, q.why), choices,
+        el('label', { for: other.id }, 'Other (optional)', other)));
+    });
+    if (d.steps?.length && !saved) {
+      let step = 0;
+      const text = el('p', { 'aria-live': 'polite' }), prev = el('button', { 'aria-label': 'Previous step' }, '‹ Previous'), next = el('button', { 'aria-label': 'Next step' }, 'Next ›');
+      const draw = () => { text.textContent = `Step ${step + 1} of ${d.steps.length}: ${d.steps[step].title}`; prev.disabled = !step; next.disabled = step === d.steps.length - 1; };
+      prev.onclick = () => { step--; draw(); }; next.onclick = () => { step++; draw(); }; draw();
+      main.append(el('section', { class: 'plan-explain' }, el('h3', {}, 'How it works'), text, el('div', { class: 'foot' }, prev, next), el('p', { class: 'meta' }, 'The direction page above explains these steps.')));
+    }
+    const commentBox = el('textarea', { id: 'plan-comment', maxlength: '500', placeholder: 'Comment for the agent on the whole plan' });
+    commentBox.value = comment;
+    commentBox.disabled = ro;
+    commentBox.oninput = () => { comment = commentBox.value; remember(); };
+    if (!saved || saved.note) main.append(el('section', { class: 'plan-section', id: 'plan-comment-section', 'aria-label': 'Whole-plan comment' },
+      el('h3', {}, 'Whole-plan comment'), el('label', { for: commentBox.id }, 'Comment for the agent on the whole plan (optional)', commentBox)));
+    send.onclick = () => {
+      send.disabled = true; err.textContent = '';
+      call('/api/answers', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: d.key, note: comment,
+        notes: d.sections.map((s) => notes.get(s.id)), decisions: Object.fromEntries([...picks].map(([k, v]) => [k, v.trim()])) }) }, () => {
+        drafts.delete(draftKey); keep(); location.hash = `#answered/${d.key}`;
+      }).catch((e) => { err.textContent = `Couldn't send back: ${e.message}`; update(); });
+    };
+    panel.append(el('h2', {}, 'Your answers'), progress, el('div', { class: 'plan-next-row' }, status, next), send, err); panel.hidden = !!saved; update();
+    return el('div', { class: `plan-scroll${saved ? ' sent' : ''}` }, el('div', { class: `plan-layout${saved ? ' sent' : ''}` }, main, panel));
+  }
+
   /** The report a #reports/<key> link opens (or the plan a #waiting/<key> link opens), over the whole board: a bar with the way back and its title, then its page in a sandboxed frame.
    *  The frame is made again only for another page, so a redraw never resets a demo halfway through. */
   const reader = document.getElementById('reader');
@@ -1021,10 +1192,13 @@
     for (const n of [document.querySelector('main'), document.getElementById('nav'), document.getElementById('tabs')]) n.inert = !!d;
     reader.hidden = !d;
     const url = d ? src(mockUrl(d.key, '', d.view)) : '';
-    if (reader.dataset.url === url) return d && (reader.querySelector('h1').textContent = d.title);
+    const answer = d?.type === 'plan' ? JSON.stringify(state.answers[d.key] ?? null) : '';
+    const plan = d?.type === 'plan' ? JSON.stringify(d) : '';
+    if (reader.dataset.url === url && reader.dataset.answer === answer && reader.dataset.plan === plan) return d && (reader.querySelector('h1').textContent = d.title);
+    Object.assign(reader.dataset, { answer, plan });
     Object.assign(reader.dataset, { url, key: d?.key ?? '', from });
     reader.replaceChildren(...(d ? [el('header', {}, el('a', { class: 'close', href: `#${from}` }, `‹ ${from === 'reports' ? 'Reports' : AREAS[from]}`), el('h1', { id: 'reader-title', tabindex: '-1', dir: 'auto' }, d.title)),
-      el('iframe', { src: url, title: `${d.type === 'plan' ? 'Plan' : 'Report'}: ${d.title}`, sandbox: 'allow-scripts' })] : []));
+      d.type === 'plan' ? planReview(d, url) : el('iframe', { src: url, title: `Report: ${d.title}`, sandbox: 'allow-scripts' })] : []));
   }
   addEventListener('keydown', (e) => { if (e.key === 'Escape' && !reader.hidden) location.hash = `#${reader.dataset.from}`; });
 
@@ -1176,7 +1350,8 @@
   // An interactive page may post its own height, `{ height: <px> }`, and its frame then fits it with no blank below.
   // Only a frame's own message sizes that frame, and never past 10000px.
   addEventListener('message', (e) => {
-    const frame = [...document.querySelectorAll('.rung iframe')].find((f) => f.contentWindow === e.source), h = e.data?.height;
+    const frame = [...document.querySelectorAll('.rung iframe, iframe.plan-view')].find((f) => f.contentWindow === e.source), h = e.data?.height;
+    if (frame?.classList.contains('plan-view') && e.data?.['sign-off'] === 'ready') frame.contentWindow.postMessage({ 'sign-off': 'size' }, '*');
     if (frame && Number.isFinite(h) && h > 0) frame.style.height = `${Math.ceil(Math.min(h, 10_000))}px`;
   });
   // A design mock page may point (web/point.js): the board keeps the last element named per mock, and turns pointing on for one mock frame.

package/web/point.js

@@ -31,6 +31,10 @@
   };
   addEventListener('message', (m) => {
     if (m.source === parent && m.data?.['sign-off'] === 'point') on = m.data.on === true;
+    if (m.source === parent && m.data?.['sign-off'] === 'size') {
+      const size = () => parent.postMessage({ height: document.documentElement.scrollHeight }, '*');
+      new ResizeObserver(size).observe(document.body); size();
+    }
   });
   for (const type of ['pointerdown', 'mousedown', 'pointerup', 'mouseup', 'click']) addEventListener(type, (m) => {
     if (!on) return;