sign-off-axi 0.4.2 → 0.4.4

package/README.md

@@ -352,7 +352,9 @@ event, by itself: the agent raises with `--filer my-agent` and blocks on
 answers, each once, and the card shows **Seen by agent**. An agent that
 cannot block can be woken instead: an `on_answer:` line in the
 `config.yaml` beside the board names a command the board runs for every
-answer. The full reference, with the worked example, is in
+answer. A `notify:` block in that config can send an HTTP POST when a card
+enters Waiting on you, with its bearer token read from a named environment
+variable. The full reference, with the worked example, is in
 [docs/commands.md](docs/commands.md).
 
 Every command takes `--help` and prints compact output with next-step hints.

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');
 }
@@ -751,27 +779,27 @@ function post(args, cmd = 'post') {
     const typed = cmd === 'post' ? { replace: { type: 'boolean' }, kind: { type: 'string' }, type: { type: 'string' }, tradeoff: { type: 'string' }, mock: { type: 'string', multiple: true },
         media: { type: 'string', multiple: true }, link: { type: 'string' }, view: { type: 'string' }, preview: { type: 'string' }, chapter: { type: 'string', multiple: true },
         ...Object.fromEntries(SIGNIN_FIELDS.map((f) => [f, { type: 'string' }])) } : {};
-    const { file, values, on } = parse(cmd, args, { from: { type: 'string' }, filer: { type: 'string' }, ...typed,
+    const { file, named, values, on } = parse(cmd, args, { from: { type: 'string' }, filer: { type: 'string' }, ...typed,
         ...Object.fromEntries(RAISE_FIELDS.map((f) => [f, { type: 'string', multiple: MANY.includes(f) }])) });
     const given = [...RAISE_FIELDS, 'type', 'tradeoff', 'mock', 'media', 'link', 'view', 'preview', 'chapter', ...SIGNIN_FIELDS].filter((f) => values[f] !== undefined);
     if (values.kind !== undefined) {
         const odd = [...given, ...(values.replace ? ['replace'] : [])][0];
         if (odd)
             throw fail(`--kind cannot be combined with --${odd}`, 'VALIDATION_ERROR', 'Put every field in the message file: sign-off-axi post --kind ask --from ask.json');
-        return postKind(file, on, values);
+        return postKind(file, named, on, values);
     }
     if (values.from !== undefined && given.length)
         throw fail(`--from cannot be combined with --${given[0]}`, 'VALIDATION_ERROR', `Put every field in the --from file, or ${cmd} with flags only`);
     if (values.replace)
-        return replace(file, on, values.from, filerOf(values));
+        return replace(file, named, on, values.from, filerOf(values));
     const filer = filerOf(values, true);
     const type = values.type ?? 'decision', told = ASK_FLAGS.find((f) => values[f] !== undefined);
     if (told && type !== 'decision')
         throw fail(`--${told} needs --type decision`, 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
     if (type === 'report')
-        return postReport(file, on, values);
+        return postReport(file, named, on, values);
     if (type === 'signin')
-        return postSignin(file, on, values, filer);
+        return postSignin(file, named, on, values, filer);
     const odd = SIGNIN_FIELDS.find((f) => values[f] !== undefined);
     if (odd)
         throw fail(`--${odd} needs --type signin`, 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
@@ -784,7 +812,7 @@ function post(args, cmd = 'post') {
     if (!['decision', 'design', 'evidence', 'diagram', 'interactive', 'explainer'].includes(type))
         throw fail(`--type must be decision, design, evidence, diagram, interactive, explainer, report or signin`, 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
     if (type === 'evidence' || type === 'explainer')
-        return postMedia(file, on, values, type, filer);
+        return postMedia(file, named, on, values, type, filer);
     if (values.media !== undefined || values.link !== undefined || values.chapter !== undefined)
         throw fail('--media, --link and --chapter need --type evidence or explainer', 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
     if (type !== 'design' && (values.tradeoff !== undefined || values.mock !== undefined))
@@ -793,7 +821,7 @@ function post(args, cmd = 'post') {
     if (view !== (values.view !== undefined))
         throw fail(view ? `--type ${type} needs --view <path>` : '--view needs --type diagram or interactive', 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
     if (type === 'decision')
-        return storeIncoming(file, on, buildIncoming(values, {}, filer, file), filer);
+        return storeIncoming(file, named, on, buildIncoming(values, {}, filer, file), filer);
     const root = resolve(dirname(file));
     if (view) {
         // The same real-path check the board serves with, so a post that passes always renders.
@@ -816,7 +844,7 @@ function post(args, cmd = 'post') {
         }
         if (!size.isFile() || size.size > MOCK_BYTES)
             throw fail(`--view ${values.view} must be a file of 5 MB or less`, 'VALIDATION_ERROR', 'Shrink the picture, or post an interactive page instead of a diagram');
-        return storeIncoming(file, on, buildIncoming(values, { type, view: values.view }, filer, file), filer);
+        return storeIncoming(file, named, on, buildIncoming(values, { type, view: values.view }, filer, file), filer);
     }
     const mocks = values.mock?.map((m) => {
         const at = m.indexOf('=');
@@ -840,7 +868,7 @@ function post(args, cmd = 'post') {
         }
         return { value: m.slice(0, at), path };
     });
-    return storeIncoming(file, on, buildIncoming(values, { type, tradeoff: values.tradeoff, mocks }, filer, file), filer);
+    return storeIncoming(file, named, on, buildIncoming(values, { type, tradeoff: values.tradeoff, mocks }, filer, file), filer);
 }
 const SIGNIN_FIELDS = ['service', 'unlocks', 'waits', 'expires', 'start'];
 const SIGNIN_EXAMPLE = 'sign-off-axi post --type signin --key npm-login --service npm --link https://example.com/login --unlocks "Publish the release" --waits "Main" --expires 15m';
@@ -855,7 +883,7 @@ function expiresAt(value) {
 }
 /** post --type signin: one card with a link to open. The same key again with another link or time swaps them on that card, which waits again.
  * The link can hold a one-time code, so no output prints it. */
-function postSignin(file, on, values, filer) {
+function postSignin(file, named, on, values, filer) {
     const odd = ['title', 'about', 'detail', 'option', 'recommend', 'default', 'close', 'tradeoff', 'mock', 'media', 'view', 'preview', 'chapter'].find((f) => values[f] !== undefined);
     if (odd)
         throw fail(`--${odd} does not apply to --type signin`, 'VALIDATION_ERROR', SIGNIN_EXAMPLE);
@@ -893,11 +921,13 @@ function postSignin(file, on, values, filer) {
                 items[at] = next;
             else
                 items.push(next);
+            const before = waitingKeys(file);
             writeItems(file, items);
             // A new link is a new sign-in: the card waits again, also when it was done or dismissed.
             appendAnswer(file, d, CLEARED);
             if (had)
                 appendDismissed(file, [d.key], false);
+            notifyEntered(file, named, before);
         }
         return toon({ board: tilde(file), posted: [{ key: d.key, status, service: d.title, ...(expires && { expires }) }] }, [
             ...(status === 'already done' ? [] : [`Run \`sign-off-axi open${on}\` so the user can sign in`]),
@@ -924,7 +954,7 @@ function signin(args) {
 }
 /** For a program that feeds the board: the --from file, checked like any post, becomes the whole board, items and top-level fields. Answers stay.
  * With a filer it replaces only that filer's items (and items with no filer it names by key); every other item and top-level field stays. */
-function replace(file, on, from, filer) {
+function replace(file, named, on, from, filer) {
     if (from === undefined)
         throw fail('--replace needs --from <board file>', 'VALIDATION_ERROR', 'sign-off-axi post board.json --from feed.json --replace');
     const source = resolve(from), fed = readItems(source);
@@ -960,8 +990,8 @@ function replace(file, on, from, filer) {
         let items = feed, extra = fed.extra, resulting = incoming;
         if (filer) {
             // The feed's items first: the board shows the file's last item first, so the other filers' items keep showing on top.
-            const named = new Set(feed.map((i) => i.key));
-            items = [...feed, ...(old?.items ?? []).filter((i) => i?.filer !== filer && !named.has(i?.key))];
+            const fedKeys = new Set(feed.map((i) => i.key));
+            items = [...feed, ...(old?.items ?? []).filter((i) => i?.filer !== filer && !fedKeys.has(i?.key))];
             extra = { ...old?.extra, ...fed.extra };
             // The merged board is checked before it is written, so a feed that breaks another filer's items leaves the board as it was.
             const check = `${file}.${process.pid}.check`;
@@ -979,14 +1009,17 @@ function replace(file, on, from, filer) {
         checkMerges(incoming, resulting, current);
         // Written only when it changed, so a feeder that runs every few seconds leaves the file alone.
         const changed = JSON.stringify(old && { ...old.extra, schema: old.schema, items: old.items }) !== JSON.stringify({ ...extra, schema: 2, items });
-        if (changed)
+        if (changed) {
+            const before = waitingKeys(file);
             writeItems(file, items, extra);
+            notifyEntered(file, named, before);
+        }
         return toon({ board: tilde(file), items: items.length, changed }, [`Run \`sign-off-axi answers${on}\` to read the answers`]);
     });
 }
 /** Copies the media into evidence/<n>/ next to the board and adds the item, numbered under the board lock: update-<n>, or an explainer under its own key.
  * `message` is a checked contract evidence message (post --kind evidence): its key, if any, takes only the same message again, and its run is stored as `evidence`. */
-function postMedia(file, on, values, type, filer, message) {
+function postMedia(file, named, on, values, type, filer, message) {
     fits(values.title);
     const explainer = type === 'explainer';
     const extra = (explainer ? ['mock', 'tradeoff', 'view', 'link'] : ['key', 'option', 'recommend', 'default', 'mock', 'tradeoff', 'view', 'chapter']).find((f) => values[f] !== undefined);
@@ -1087,14 +1120,16 @@ function postMedia(file, on, values, type, filer, message) {
         finally {
             rmSync(check, { force: true });
         }
+        const before = waitingKeys(file);
         writeItems(file, items);
+        notifyEntered(file, named, before);
         if (explainer)
             return toon({ board: tilde(file), raised: [{ key, status: 'raised', title }] }, [`Run \`sign-off-axi open${on}\` so the user can watch and answer`, waitFor(on, filer, key)]);
         return toon({ board: tilde(file), posted: [{ key, number, media: media.length, title, ...(message && { status: 'posted' }) }] }, [`Run \`sign-off-axi open${on}\` so the user can give a verdict`, waitFor(on, filer, key)]);
     });
 }
 /** post --type report: the flags as one report message, posted as post --kind report posts it. A report with no page is refused before anything is read. */
-function postReport(file, on, values) {
+function postReport(file, named, on, values) {
     const odd = ['option', 'recommend', 'default', 'close', 'detail', 'mock', 'tradeoff', 'media', 'chapter'].find((f) => values[f] !== undefined);
     if (odd)
         throw fail(`--${odd} does not apply to --type report: a report takes no answer`, 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
@@ -1106,11 +1141,11 @@ function postReport(file, on, values) {
     // Posting the same report again is a no-op, so it keeps the time it was first filed.
     const filed = (had?.kind === 'report' && had.filed) || new Date().toISOString().replace(/\.\d+Z$/, 'Z');
     const { title, about, view, preview, link } = values;
-    return postKind(file, on, values, { contract: 1, kind: 'report', schema: 2, key, title, about, view, preview, ...(link !== undefined && { link }), filed });
+    return postKind(file, named, on, values, { contract: 1, kind: 'report', schema: 2, key, title, about, view, preview, ...(link !== undefined && { link }), filed });
 }
 /** Posts one contract message (docs/contract.md), from a file or from stdin with --from -: checked against --kind, then stored like a raised item.
  * `built` is a message post --type report made from its flags. */
-async function postKind(file, on, values, built) {
+async function postKind(file, named, on, values, built) {
     const { kind, from } = values, example = 'sign-off-axi post --kind ask --from ask.json';
     const name = built ? '--type report' : from === '-' ? 'stdin' : from;
     let bytes, m = built;
@@ -1137,6 +1172,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;
@@ -1147,9 +1184,9 @@ async function postKind(file, on, values, built) {
     const filer = m.filer ?? filerOf(values, true), scratch = mkdtempSync(join(tmpdir(), 'sign-off-')), source = join(scratch, basename(name));
     try {
         if (m.kind === 'evidence')
-            return await postMedia(file, on, { title: m.title, about: m.about, media: sources }, 'evidence', filer, { ...m, ...(filer && { filer }) });
+            return await postMedia(file, named, on, { title: m.title, about: m.about, media: sources }, 'evidence', filer, { ...m, ...(filer && { filer }) });
         writeFileSync(source, JSON.stringify({ schema: 2, items: [{ ...m, ...(filer && { filer }) }] }));
-        return await storeIncoming(file, on, buildIncoming({ from: source }, {}, filer, file), filer, true);
+        return await storeIncoming(file, named, on, buildIncoming({ from: source }, {}, filer, file), filer, true);
     }
     catch (e) {
         if (!(e instanceof AxiError && e.code === 'CONFLICT'))
@@ -1225,11 +1262,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) {
@@ -1300,7 +1339,7 @@ function checkMerges(incoming, resulting, current) {
     }
 }
 /** exact: a contract post, where a key takes only the same message again, filer and filed included (contract section 4). */
-function storeIncoming(file, on, { incoming, raw }, filer, exact = false) {
+function storeIncoming(file, named, on, { incoming, raw }, filer, exact = false) {
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
     return locked(`${file}.lock`, () => {
         const current = board(file), items = existsSync(file) ? readItems(file).items : [], saved = readAnswers(file), now = new Date().toISOString();
@@ -1330,8 +1369,11 @@ function storeIncoming(file, on, { incoming, raw }, filer, exact = false) {
             }
             return { key: d.key, status: !had ? 'raised' : had.answer ? `already answered ${had.answer.answer}` : waits({ ...had, dismissed: false }) ? 'already waiting' : 'already posted', title: d.title };
         });
-        if (raised.some((r) => r.status === 'raised'))
+        if (raised.some((r) => r.status === 'raised')) {
+            const before = waitingKeys(file);
             writeItems(file, items);
+            notifyEntered(file, named, before);
+        }
         const key = raised.length === 1 ? ` --key ${raised[0].key}` : '';
         // Reports take no answer, so a post with nothing waiting asks the user to read it, never to answer.
         const anyWaiting = incoming.some((d, i) => waits(d) && !raised[i].status.startsWith('already answered'));
@@ -1432,7 +1474,7 @@ async function running(file) {
 /** Loopback, or one private address: 10/8, 172.16/12, 192.168/16, the 100.64/10 range mesh VPNs use, IPv6 fc00::/7. Never all interfaces or a public one. */
 const PRIVATE = /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.|::1$|f[cd][0-9a-f]{2}:)/i;
 const privateBind = (host) => isIP(host) > 0 && PRIVATE.test(host);
-const loopback = (host) => /^127\./.test(host) || host === '::1';
+const loopback = (host) => isIP(host) > 0 && (/^127\./.test(host) || host === '::1');
 const urlHost = (host) => (isIP(host) === 6 ? `[${host}]` : host);
 /** The config.yaml beside the board as it is named, never beside the file a symlinked board points to: the one place open, serve and doctor read it. */
 function setupOf(named) {
@@ -1548,14 +1590,26 @@ const skillInstalled = (dir, agent) => [join(dir, AGENTS[agent].dir), AGENTS[age
     .some((skills) => existsSync(join(skills, 'sign-off-axi', 'SKILL.md')));
 const SKILL_ADD = ['-y', 'skills', 'add', 'umeranjum17/sign-off', '--skill', 'sign-off-axi', '-y', '-a'];
 const skillAdd = (agents) => `npx ${[...SKILL_ADD, ...agents].join(' ')}`;
-const GITIGNORE = 'mocks/\nevidence/\n*.answers.jsonl\n*.rounds.jsonl\n*.messages.jsonl\n*.annotations.jsonl\n*.seen.jsonl\n*.dismissed.jsonl\n*.board.pid\n*.board.log\n*.token\n*.export.html\n';
+const GITIGNORE = 'mocks/\nevidence/\n*.answers.jsonl\n*.rounds.jsonl\n*.messages.jsonl\n*.annotations.jsonl\n*.seen.jsonl\n*.dismissed.jsonl\n*.board.pid\n*.board.log\nnotify.log\n*.token\n*.export.html\n';
 /** The board, port, bind and hosts in <so>/config.yaml (the `key: value` lines init writes). A bad line falls back on its own default
  * (decisions.json, 4410) and `problems` says what is wrong; a file that cannot be read throws. */
 function readSetup(so) {
-    const config = {}, problems = [], hosts = [];
-    let onAnswer = [];
+    const config = {}, problems = [], hosts = [], notify = {};
+    let onAnswer = [], notifyBlock = false, inNotify = false;
     readFileSync(join(so, 'config.yaml'), 'utf8').split(/\r?\n/).forEach((l, n) => {
-        const line = l.split('#')[0].trim(), kv = line.match(/^([A-Za-z]+)\s*:\s*(\S+)$/), key = line.match(/^(board|port|bind)(\s|:|$)/i);
+        // The notify block's indented lines keep their # , and } characters: only a # after a space starts a comment.
+        if (inNotify && (!l.trim() || /^\s/.test(l))) {
+            const text = l.replace(/(^|\s+)#.*$/, '').trim(), field = text.match(/^(url|token_env|link_base)\s*:\s*(.+)$/);
+            if (field)
+                notify[field[1]] = field[2].replace(/^(['"])(.*)\1$/, '$2');
+            else if (text)
+                problems.push(`line ${n + 1} is not one "url", "token_env" or "link_base" line under notify`);
+            return;
+        }
+        inNotify = false;
+        const line = l.split('#')[0].trim(), kv = line.match(/^([A-Za-z]+)\s*:\s*(\S+)$/), key = line.match(/^(board|port|bind|notify)(\s|:|$)/i);
+        if (/^notify\s*:$/i.test(line))
+            return void (inNotify = notifyBlock = true);
         // hosts: private DNS names that reach the bind address (a mesh VPN name), let in besides it; commas or spaces between them.
         const names = /^hosts\s*:(.*)$/i.exec(line)?.[1].split(/[\s,]+/).filter(Boolean).map((h) => h.toLowerCase().replace(/\.$/, ''));
         for (const h of names ?? []) {
@@ -1583,7 +1637,50 @@ function readSetup(so) {
     const bind = config.bind ?? '127.0.0.1';
     if (!privateBind(bind))
         problems.push(`bind ${bind} is not 127.0.0.1 or a private address`);
-    return { board: join(so, goodBoard ? config.board : 'decisions.json'), port: goodPort ? Number(port) : 4410, bind, hosts, onAnswer, goodBoard, problems };
+    const parsed = (u) => { try {
+        return new URL(u ?? '');
+    }
+    catch {
+        return undefined;
+    } };
+    const sendTo = parsed(notify.url), base = parsed(notify.link_base);
+    const usable = !!sendTo && !!base && (sendTo.protocol === 'https:' || (sendTo.protocol === 'http:' && (loopback(sendTo.hostname.replace(/^\[|\]$/g, '')) || sendTo.hostname === 'localhost')))
+        && ['http:', 'https:'].includes(base.protocol) && (notify.token_env === undefined || /^[A-Za-z_]\w*$/.test(notify.token_env));
+    if (notifyBlock && !usable)
+        problems.push('notify needs url (https://, or http:// on this machine) and link_base (http:// or https://) lines, and token_env must name an environment variable');
+    return { board: join(so, goodBoard ? config.board : 'decisions.json'), port: goodPort ? Number(port) : 4410, bind, hosts, onAnswer, goodBoard, problems,
+        notify: notifyBlock && usable ? { url: notify.url, token_env: notify.token_env, link_base: notify.link_base } : undefined };
+}
+const NOTIFY_SENDER = `void (async()=>{const delays=[2000,10000,60000];for(let i=0;i<4;i++){try{if((await fetch(process.env.SIGN_OFF_NOTIFY_URL,{method:'POST',headers:{'content-type':'application/json',...(process.env.SIGN_OFF_NOTIFY_TOKEN&&{authorization:'Bearer '+process.env.SIGN_OFF_NOTIFY_TOKEN})},body:process.env.SIGN_OFF_NOTIFY_BODY,signal:AbortSignal.timeout(10000)})).ok)return}catch{}if(i<3)await new Promise(r=>setTimeout(r,delays[i]))}require('node:fs').appendFileSync(process.env.SIGN_OFF_NOTIFY_LOG,new Date().toISOString()+' notification send failed for card '+process.env.SIGN_OFF_NOTIFY_ID+'\\n')})();`;
+/** The cards waiting on the user before a write: a card waiting after the write but not before it has entered Waiting on you. */
+function waitingKeys(file) {
+    try {
+        return new Set(board(file, () => { }).filter(waits).map((d) => d.key));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Announces each card that entered Waiting on you with a write. The card is already stored, so nothing here fails the command. */
+function notifyEntered(file, named, before) {
+    try {
+        const so = dirname(named), notify = before ? readSetup(so).notify : undefined;
+        if (!before || !notify || (notify.token_env && !process.env[notify.token_env]))
+            return;
+        for (const d of board(file, () => { }).filter((d) => waits(d) && !before.has(d.key)))
+            sendNotice(so, notify, d);
+    }
+    catch { }
+}
+function sendNotice(so, notify, d) {
+    const token = notify.token_env ? process.env[notify.token_env] : undefined;
+    const kind = d.kind ?? { decision: 'ask', explainer: d.options.length ? 'ask' : 'report' }[d.type] ?? d.type;
+    const body = JSON.stringify({ v: 1, source: 'sign-off', id: d.key, kind: ['ask', 'plan', 'design', 'evidence', 'report'].includes(kind) ? kind : 'ask',
+        title: [...d.title].slice(0, 120).join(''), text: [...(d.about ?? d.detail ?? d.why ?? d.title).replace(/[\r\n]+/g, ' ')].slice(0, 200).join(''),
+        url: `${notify.link_base.replace(/\/$/, '')}#waiting/${encodeURIComponent(d.key)}`, at: d.filed ?? new Date().toISOString() });
+    const child = spawn(process.execPath, ['-e', NOTIFY_SENDER], { detached: true, stdio: 'ignore', env: { ...process.env, SIGN_OFF_NOTIFY_URL: notify.url, SIGN_OFF_NOTIFY_BODY: body, SIGN_OFF_NOTIFY_TOKEN: token ?? '', SIGN_OFF_NOTIFY_ID: d.key, SIGN_OFF_NOTIFY_LOG: join(so, 'notify.log') } });
+    child.on('error', () => warn(`notification sender could not start for card ${d.key}`));
+    child.unref();
 }
 /** --port, else the port in a config.yaml beside the board (init writes one), else 4410. */
 const boardPort = (named, given) => portOf(given ?? String(setupOf(named)?.port ?? 4410));
@@ -1736,6 +1833,8 @@ async function doctor(args) {
                     check('config', `board ${basename(board)}, port ${port}`);
                 else
                     check('config', `${basename(config)}: ${setup.problems.join('; ')}`, `Edit ${shellPath(config)} to hold "board: <name>.json", "port: <0-65535>" and "bind: <127.0.0.1 or a private address>" lines, such as board: decisions.json, port: 4410 and bind: 127.0.0.1, and hosts: only DNS names${setup.goodBoard ? '' : `, or delete it and run \`${rerun}\``}`);
+                if (setup.notify?.token_env && !process.env[setup.notify.token_env])
+                    check('notify', `${setup.notify.token_env} is not set, so no notice is sent`, `Export ${setup.notify.token_env} with the receiver's token`);
                 // A hosts: name is only of use when it leads to the bind address.
                 const astray = [];
                 for (const h of setup.hosts) {
@@ -1989,7 +2088,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 +2193,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?.preview === path || 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 +2359,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 +2379,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 +2519,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.');

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', 0, 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,36 @@ 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) {
+        const hasJourney = n?.journey !== undefined, hasScreen = n?.screen !== undefined;
+        if (!n || hasJourney !== hasScreen || (hasJourney && !screens.has(`${n.journey}/${n.screen}`)) || !isText(n.note) || !n.note.trim() || [...n.note].length > NOTE_MAX) {
+            throw bad('each note needs both a known journey and screen, or neither for a design-level note, with text of 500 characters or fewer');
+        }
+    }
+    if (new Set(notes.map(n => n.journey === undefined ? '' : `${n.journey}/${n.screen}`)).size !== notes.length)
+        throw bad('notes must name each screen once, or contain one design-level note');
+    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 +322,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.2",
+  "version": "0.4.4",
   "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

@@ -20,11 +20,11 @@
   /* A phone keeps room at the bottom for the tab bar. */
   body { margin: 0; padding-bottom: calc(5.125rem + env(safe-area-inset-bottom)); background: var(--bg); color: var(--text); overflow-wrap: anywhere;
     -webkit-font-smoothing: antialiased; font: 1.0625rem/1.4706 -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, "Segoe UI", Roboto, sans-serif; letter-spacing: -0.022em; }
-  /* The four areas each have a colour, used on icons, dots and marks. */
+  /* The board areas each have a colour, used on icons, dots and marks. */
   .i-waiting { --area: var(--c-waiting); } .i-evidence { --area: var(--c-evidence); } .i-reports { --area: var(--c-reports); } .i-answered { --area: var(--c-answered); }
   main { max-width: 72rem; margin: 0 auto; padding: 0 max(1.25rem, env(safe-area-inset-right)) 0 max(1.25rem, env(safe-area-inset-left)); }
   .side { display: none; }
-  /* A phone moves between the areas with a tab bar, solid so no page text shows through it. */
+  /* A phone moves between areas with a tab bar, solid so no page text shows through it. */
   .tabs { position: fixed; z-index: 2; left: 0; right: 0; bottom: 0; display: flex; padding: 0 env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);
     background: var(--bar); border-top: 0.5px solid var(--line); }
   .tabs a { flex: 1; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 0.125rem; min-height: 4.125rem; color: var(--muted);
@@ -172,6 +172,8 @@
   .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); }
@@ -202,6 +204,10 @@
     .plan-section, .plan-decision { padding: 1.5rem; }
   }
   body.reading { overflow: hidden; }
+  @media (min-width: 60rem) {
+    body.design-reading main { display: none; }
+    body.design-reading #reader { position: static; inset: auto; z-index: auto; grid-column: 2; grid-row: 1; width: 100%; height: 100vh; min-width: 0; }
+  }
   .foot { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem 1rem; }
   .foot .meta { margin: 0 auto 0 0; }
   .foot a { color: var(--accent); font-weight: 600; text-decoration: none; }
@@ -338,6 +344,22 @@
   .done[open] + .x { align-self: start; margin-top: 1rem; }
   .needs .foot { justify-content: space-between; margin-top: 1rem; padding-top: 0.5rem; border-top: 1px solid var(--line); }
   .foot .dis { padding: 0 0.5rem; background: none; color: var(--muted); }
+  .design-list { display: grid; gap: 0.75rem; }
+  .design-card { display: grid; grid-template-columns: minmax(4rem, 7rem) minmax(0, 1fr); align-items: center; gap: 1rem; }
+  .design-card h3 a { color: inherit; text-decoration: none; }
+  .design-card .thumb { width: 100%; height: 8rem; object-fit: cover; }
+  .design-review { flex: 1; min-height: 0; overflow: auto; padding: 1.25rem; }
+  .design-preview-window { width: 100%; height: min(65vh, 844px); margin: 1rem auto; overflow: auto; border: 1px solid var(--line); border-radius: 1rem; background: var(--surface); }
+  .design-review-preview { display: block; width: 100%; height: auto; }
+  .design-preview-full { display: block; max-width: 56rem; margin: 0 auto; color: var(--accent); }
+  @media (min-width: 60rem) { .design-preview-window { max-width: 24.375rem; } }
+  .design-review label { display: grid; gap: 0.5rem; max-width: 56rem; margin: 1rem auto; color: var(--muted); }
+  .design-review textarea { min-height: 6rem; padding: 0.75rem; background: var(--surface); }
+  .design-review .foot { max-width: 56rem; margin: 1rem auto; }
+  .design-review .foot > * { flex: 1; }
+  .design-review .foot button.open-link { background: var(--action); color: var(--on-accent); }
+  .design-review > a { display: block; max-width: 56rem; margin: 1rem auto; color: var(--accent); }
+  .needs .foot .open-link { min-height: 2.75rem; padding: 0 1rem; background: var(--action); color: var(--on-accent); text-align: center; }
   /* The asks dismissed from Waiting on you: one muted row that opens to a list, each with Restore. */
   .gone-asks { margin-top: 0.5rem; } .gone-asks summary { color: var(--muted); }
   .gone-asks .rows { padding: 0; } .gone-asks li { justify-content: space-between; gap: 0.75rem; min-height: 2.75rem; }
@@ -604,6 +626,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.
@@ -811,6 +839,7 @@
 
   /** A mock or view is served from inside its own folder, so the files beside it load by their relative names. */
   const mockUrl = (key, value, path) => `${state.mockBase}${key}~${value}/${encodeURIComponent(path.split('?')[0].split('/').pop())}`;
+  const designUrl = (d, path) => `${state.mockBase.replace('/mock/', '/design/')}${d.key}/${encodeURIComponent(path)}`;
   /** A diagram shows inline at card width; an interactive page runs in a sandboxed frame. A tap or the link opens either full size. */
   function rung(d) {
     if (!d.view) return '';
@@ -912,11 +941,12 @@
       ...[...old].map(([m, n]) => el('p', { class: 'meta' }, `${n} comment${n > 1 ? 's' : ''} on an earlier version of “${name(m)}” ${n > 1 ? 'are' : 'is'} hidden`)), err);
   }
 
-  const AREAS = { waiting: 'Waiting on you', evidence: 'Evidence', reports: 'Reports and explainers', answered: 'Answered' };
+  const AREAS = { waiting: 'Waiting on you', designs: 'Designs', evidence: 'Evidence', reports: 'Reports and explainers', answered: 'Answered' };
   // The sidebar and the tab bar name the areas short enough for one line.
   const NAV = { ...AREAS, reports: 'Reports' }, TAB = { ...NAV, waiting: 'Waiting' };
-  const EMPTY = { waiting: 'Nothing is waiting on you.', evidence: 'No evidence updates.', reports: 'No reports or explainers.', answered: 'Nothing answered yet.' };
+  const EMPTY = { waiting: 'Nothing is waiting on you.', designs: 'No designs yet.', evidence: 'No evidence updates.', reports: 'No reports or explainers.', answered: 'Nothing answered yet.' };
   const ICONS = { summary: 'M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 5.999A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z',
+    designs: 'M3 3h18v18H3zM3 9h18M9 21V9',
     waiting: 'M22 12h-6l-2 3h-4l-2-3H2M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z',
     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',
@@ -930,7 +960,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;
   };
@@ -942,7 +972,7 @@
   const when = (at) => (isToday(at) ? hhmm(at) : `${day(at)} ${hhmm(at)}`);
   const pic = (d) => {
     const i = d.media?.findIndex((m) => !/\.(mp4|webm)$/i.test(m.path)), m = d.mocks?.find((x) => !/\.html?$/i.test(x.path));
-    return i >= 0 ? `/api/media?key=${encodeURIComponent(d.key)}&i=${i}` : d.preview ? mockUrl(d.key, '', d.preview) : d.type === 'diagram' ? mockUrl(d.key, '', d.view)
+    return d.kind === 'design' && d.preview ? designUrl(d, d.preview) : i >= 0 ? `/api/media?key=${encodeURIComponent(d.key)}&i=${i}` : d.preview ? mockUrl(d.key, '', d.preview) : d.type === 'diagram' ? mockUrl(d.key, '', d.view)
       : m ? mockUrl(d.key, m.value, m.path) : d.evidenceCard?.media.find((x) => x.type.startsWith('image/'))?.url;
   };
   const thumb = (a, url) => { if (!url) return icon(a); const img = el('img', { class: 'thumb', src: src(url), alt: '' }); img.onerror = () => img.replaceWith(icon(a)); return img; };
@@ -951,7 +981,7 @@
     const answeredToday = a === 'answered' && items.filter((d) => new Date(state.answers[d.key].at).toDateString() === new Date().toDateString()).length;
     // A short count line that never cuts off on a phone. Waiting gives the oldest ask's time when its items carry one.
     const oldest = items.map((d) => d.filed).filter(Boolean).sort((x, y) => Date.parse(x) - Date.parse(y))[0];
-    const detail = { waiting: oldest ? `Oldest ${when(oldest)}` : `${items.length} waiting`, evidence: items[0]?.number ? `Newest: Update ${items[0].number}` : `${items.length} to see`,
+    const detail = { waiting: oldest ? `Oldest ${when(oldest)}` : `${items.length} waiting`, designs: `${items.length} to review`, evidence: items[0]?.number ? `Newest: Update ${items[0].number}` : `${items.length} to see`,
       reports: `${items.length} to read`, answered: `${answeredToday} today` }[a];
     const thumbs = a === 'evidence' ? items.map(pic).filter(Boolean).slice(0, 3).map((u) => el('img', { src: src(u), alt: '' })) : [];
     const marks = thumbs.length ? thumbs : a === 'waiting' ? [items.length ? icon(a) : '']
@@ -1072,18 +1102,20 @@
     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 && q.options.some((o) => o.value === value))));
-    const remember = () => { drafts.set(draftKey, JSON.stringify({ notes: [...notes.values()], decisions: Object.fromEntries(picks) })); keep(); };
+    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) => !q.options.some((o) => o.value === picks.get(q.key)));
+      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) => !q.options.some((o) => o.value === picks.get(q.key))).length;
+      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;
@@ -1094,12 +1126,13 @@
     };
     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')));
+        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.'));
+    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');
@@ -1107,7 +1140,8 @@
       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 note = el('label', { for: field.id }, `What should change in ${s.heading.toLowerCase()}?`, field);
+      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 ?? '';
@@ -1115,27 +1149,38 @@
         approve.textContent = verdict === 'approve' ? '✓ Approved' : 'Approve';
         change.setAttribute('aria-pressed', verdict === 'change');
         approve.disabled = change.disabled = ro;
-        note.hidden = verdict !== 'change';
+        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', ...(n && { note: field.value }) });
+        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: 'change', note: field.value }); remember(); update(); };
+      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); remember(); [...choices.children].forEach((b, i) => b.setAttribute('aria-pressed', q.options[i].value === o.value)); update(); };
+        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));
+      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;
@@ -1144,10 +1189,16 @@
       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,
-        notes: d.sections.map((s) => notes.get(s.id)), decisions: Object.fromEntries(picks) }) }, () => {
+      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(); });
     };
@@ -1155,23 +1206,69 @@
     return el('div', { class: `plan-scroll${saved ? ' sent' : ''}` }, el('div', { class: `plan-layout${saved ? ' sent' : ''}` }, main, panel));
   }
 
+  function designReview(d) {
+    const saved = state.answers[d.key], screens = (d.journeys ?? []).flatMap((journey) => journey.screens.map((screen) => ({ journey, screen }))), savedNote = saved?.notes?.[0];
+    const screenKey = (target) => target && `${target.journey.id}/${target.screen.id}`, screenFor = (key) => screens.find((target) => screenKey(target) === key);
+    const note = el('textarea', { maxlength: '500', placeholder: 'What should change? (optional for approval)' });
+    const pick = el('select', { 'aria-label': 'Pick a direction' }, el('option', { value: '' }, 'Choose a direction'));
+    for (const option of d.options ?? []) pick.append(el('option', { value: option.value }, option.label));
+    pick.value = saved?.pick ?? '';
+    const screenSelect = screens.length > 1 ? el('select', { 'aria-label': 'Screen for note' }, ...screens.map((target) => el('option', { value: screenKey(target) }, `${target.journey.title} — ${target.screen.title}`))) : '';
+    const selectedKey = savedNote?.journey && savedNote?.screen ? `${savedNote.journey}/${savedNote.screen}` : screenKey(screens[0]);
+    if (screenSelect) screenSelect.value = screenFor(selectedKey) ? selectedKey : screenKey(screens[0]);
+    const target = () => screenSelect ? screenFor(screenSelect.value) : screens[0];
+    note.value = savedNote?.note ?? '';
+    const previewPath = () => (target() && Object.values(target().screen.views)[0]) || d.preview;
+    const previewElement = (path) => /\.html?$/i.test(path) ? el('iframe', { class: 'design-review-preview', src: src(designUrl(d, path)), title: `Design preview: ${d.title}`, sandbox: 'allow-scripts' }) : el('img', { class: 'design-review-preview', src: src(designUrl(d, path)), alt: `Design preview: ${d.title}` });
+    const preview = previewPath() ? el('div', { class: 'design-preview-window' }, previewElement(previewPath())) : '';
+    const fullPreview = previewPath() ? el('a', { class: 'design-preview-full', href: src(designUrl(d, previewPath())), target: '_blank', rel: 'noopener noreferrer' }, 'Open full preview') : '';
+    if (screenSelect) screenSelect.onchange = () => {
+      const path = previewPath();
+      if (preview) preview.replaceChildren(previewElement(path));
+      if (fullPreview) fullPreview.href = src(designUrl(d, path));
+    };
+    const status = el('p', { class: 'meta', role: 'status' }, saved ? saved.label : d.status === 'draft' ? 'Draft' : 'In review');
+    const err = el('p', { class: 'err', role: 'alert' });
+    const save = (verdict) => {
+      if (d.options?.length && !pick.value) { err.textContent = 'Choose a direction before sending your review.'; pick.focus(); return Promise.resolve(); }
+      const selected = target(), text = note.value.trim();
+      return call('/api/answers', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: d.key, verdict,
+        notes: text ? [{ ...(selected && { journey: selected.journey.id, screen: selected.screen.id }), note: text }] : [], ...(pick.value && { pick: pick.value }) }) }, render);
+    };
+    const approve = el('button', { class: 'open-link' }, 'Approve'), change = el('button', {}, 'Change');
+    approve.disabled = change.disabled = state.readonly || !!state.answers_only;
+    approve.onclick = () => save('approve').catch((e) => { err.textContent = `Couldn't save: ${e.message}`; });
+    change.onclick = () => { if (!note.value.trim()) { err.textContent = 'Add a note describing what should change.'; note.focus(); return; } save('change').catch((e) => { err.textContent = `Couldn't save: ${e.message}`; }); };
+    return el('div', { class: 'design-review' }, status, d.about ? el('p', { class: 'about' }, d.about) : '', preview, fullPreview,
+      screenSelect ? el('label', {}, 'Screen for note', screenSelect) : '', d.options?.length ? el('label', {}, 'Pick a direction', pick) : '',
+      el('label', {}, screens.length ? 'Screen note' : 'Design note', note), el('div', { class: 'foot' }, approve, change), err,
+      d.link ? el('a', { href: d.link, target: '_blank', rel: 'noopener noreferrer' }, 'Open original design') : '');
+  }
+
   /** 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');
   function readPage(d, from = 'reports') {
     document.body.classList.toggle('reading', !!d);
-    for (const n of [document.querySelector('main'), document.getElementById('nav'), document.getElementById('tabs')]) n.inert = !!d;
+    document.body.classList.toggle('design-reading', !!d && d.kind === 'design');
+    const inlineDesign = !!d && d.kind === 'design' && matchMedia('(min-width: 60rem)').matches;
+    reader.setAttribute('role', inlineDesign ? 'region' : 'dialog');
+    if (inlineDesign) reader.removeAttribute('aria-modal'); else reader.setAttribute('aria-modal', 'true');
+    document.querySelector('main').inert = !!d;
+    document.getElementById('nav').inert = !!d && !inlineDesign;
+    document.getElementById('tabs').inert = !!d;
     reader.hidden = !d;
-    const url = d ? src(mockUrl(d.key, '', d.view)) : '';
-    const answer = d?.type === 'plan' ? JSON.stringify(state.answers[d.key] ?? null) : '';
+    const url = d?.kind === 'design' ? `design:${d.key}` : d ? src(mockUrl(d.key, '', d.view)) : '';
+    const answer = d?.type === 'plan' || d?.kind === 'design' ? 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)),
-      d.type === 'plan' ? planReview(d, url) : el('iframe', { src: url, title: `Report: ${d.title}`, sandbox: 'allow-scripts' })] : []));
+      d.type === 'plan' ? planReview(d, url) : d.kind === 'design' ? designReview(d) : 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}`; });
+  addEventListener('resize', () => { if (!reader.hidden) readPage(state.decisions.find((d) => d.key === reader.dataset.key), reader.dataset.from); });
 
   /** Reports in sections, one per `group` in the order each first shows, each head with the newest filed time; items with no group come last, under Other reports when there are groups. */
   function reportGroups(items) {
@@ -1184,6 +1281,18 @@
     });
   }
 
+  function designGroups(items) {
+    if (!items.length) return el('p', { class: 'empty' }, EMPTY.designs);
+    const groups = [...new Set(items.map((d) => d.group || ''))];
+    return groups.flatMap((group) => [group ? el('div', { class: 'sec-h' }, el('h2', {}, group)) : '',
+      el('div', { class: 'design-list' }, ...items.filter((d) => (d.group || '') === group).map((d) => {
+        const saved = state.answers[d.key], status = saved?.answer === 'approve' ? 'Approved' : saved?.answer === 'change' ? 'Changes requested' : d.status === 'draft' ? 'Draft' : 'In review';
+        const href = `#designs/${d.key}`, image = pic(d);
+        return el('article', { class: 'card design-card', id: `item-${d.key}` }, image ? el('a', { href, class: 'design-preview', 'aria-label': `Open design, ${d.title}` }, thumb('designs', image)) : '',
+          el('div', {}, el('p', { class: 'eyebrow' }, status), el('h3', {}, el('a', { href }, d.title)), el('p', { class: 'meta' }, [d.filed ? day(d.filed) : '', saved?.pick ? `Pick: ${saved.pick}` : '', saved?.notes?.[0]?.note ?? ''].filter(Boolean).join(' · '))));
+      }))]);
+  }
+
   /** The asks dismissed from Waiting on you, folded under one row; Restore puts one back on the board. */
   function dismissed(items) {
     if (!canDismiss() || !items.length) return '';
@@ -1244,7 +1353,7 @@
     return el('div', { class: 'tri' }, queue, el('div', { class: 'focus' }, el('p', { class: 'fhead' }, `${i + 1} of ${n}`),
       el('div', { class: 'pbar', 'aria-hidden': 'true' }, el('i', { style: `width: ${((i + 1) / n) * 100}%` })),
       d.filed ? el('p', { class: 'meta since' }, `Waiting since ${when(d.filed)}`) : '', card,
-      skip || dis ? el('div', { class: 'quiet' }, skip || '', dis) : '', next ? el('div', { class: 'card upnext' }, el('p', { class: 'meta' }, 'Up next'), el('strong', { dir: 'auto' }, title(next))) : '',
+      d.kind === 'design' || skip || dis ? el('div', { class: 'quiet' }, d.kind === 'design' ? el('a', { class: 'open-link', href: `#designs/${d.key}` }, 'Open designs') : skip || '', dis) : '', next ? el('div', { class: 'card upnext' }, el('p', { class: 'meta' }, 'Up next'), el('strong', { dir: 'auto' }, title(next))) : '',
       hint ? el('p', { class: 'meta hint' }, hint) : '', el('p', { class: 'meta keys' }, `Keys: ${keys}`), dismissed(hidden)));
   }
   // Triage keys at a desk: a number picks that answer (in the order shown), E skips, Z takes back the last tap.
@@ -1256,13 +1365,14 @@
   });
 
   function render() {
-    const by = { waiting: [], evidence: [], reports: [], answered: [], notes: [] };
+    const by = { waiting: [], designs: [], evidence: [], reports: [], answered: [], notes: [] };
     // The board file appends new items at the end, so each list reads newest first; answers sort by their time.
     // One decision is one card: a card an open ask merges is not shown; that ask's answer closes it.
     const gone = new Set(state.dismissed ?? []), open = state.decisions.filter((d) => !gone.has(d.key) && !isAnswered(d));
     const openKeys = new Set(open.map((d) => d.key));
     const merged = new Set(open.flatMap((d) => d.merges ?? []).filter((k) => openKeys.has(k)));
     for (const d of [...state.decisions].reverse()) if (!gone.has(d.key) && !merged.has(d.key)) by[area(d)].push(d);
+    by.designs = [...state.decisions].reverse().filter((d) => d.kind === 'design' && !gone.has(d.key));
     // Waiting on you reads newest first unless the viewer chose oldest first. A sign-in blocks someone now, so sign-ins come first either way.
     let latest = -Infinity;
     const inFileOrder = by.waiting.slice().reverse().map((d, i) => { const t = Date.parse(d.filed); if (!Number.isNaN(t)) latest = t; return { d, t: latest, i }; });
@@ -1274,7 +1384,7 @@
     const shown = waitType === 'all' ? by.waiting : by.waiting.filter((d) => typeOf(d) === waitType);
     const hidden = state.decisions.filter((d) => gone.has(d.key) && !merged.has(d.key) && area(d) === 'waiting');
     by.answered.sort((x, y) => state.answers[y.key].at.localeCompare(state.answers[x.key].at));
-    const [, at, key] = /^#(waiting|evidence|reports|answered)(?:\/([\w.-]+))?$/.exec(location.hash) ?? [];
+    const [, at, key] = /^#(waiting|designs|evidence|reports|answered)(?:\/([\w.-]+))?$/.exec(location.hash) ?? [];
     const link = (a, name, n) => el('a', { href: `#${a}`, ...(a === (at ?? '') && { 'aria-current': 'page' }) }, icon(a || 'summary'), name, n === undefined ? '' : el('span', { class: 'n' }, String(n)));
     document.getElementById('nav').replaceChildren(el('p', { class: 'brand' }, 'sign-off'), link('', 'Summary'), ...Object.keys(AREAS).map((a) => link(a, NAV[a], by[a].length)));
     document.getElementById('tabs').replaceChildren(...Object.keys(AREAS).map((a) => el('a', { href: `#${a}`, 'aria-label': `${AREAS[a]}, ${by[a].length}`,
@@ -1289,14 +1399,14 @@
       : at === 'evidence' && by.evidence.length ? el('p', { class: 'lede' }, updates(by.evidence)) : '');
     const first = by.waiting[0], more = by.waiting.length > 1 ? `Answer all ${by.waiting.length} in Triage →` : 'Open in Triage →';
     const needs = el('section', { class: 'card needs' }, el('h2', {}, 'Needs you first'), ...(first ? [first.filed ? el('p', { class: 'meta since' }, `Waiting since ${when(first.filed)}`) : '', row(first, { x: false }),
-      el('div', { class: 'foot' }, xBtn(first, 'Dismiss'), el('a', { class: 'more', href: '#waiting' }, more))] : [el('p', { class: 'meta' }, 'Nothing is waiting on you.')]), dismissed(hidden));
+      el('div', { class: 'foot' }, xBtn(first, 'Dismiss'), first.kind === 'design' ? el('a', { class: 'open-link', href: `#designs/${first.key}` }, 'Open designs') : el('a', { class: 'more', href: '#waiting' }, more))] : [el('p', { class: 'meta' }, 'Nothing is waiting on you.')]), dismissed(hidden));
     document.getElementById('board').replaceChildren(top, ...(at === 'waiting' && !state.readonly ? [filters(by.waiting), triage(shown, hidden)]
-      : at === 'reports' && !state.readonly ? [by.reports.some((d) => d.steps) ? el('p', { class: 'card legend' }, ...Object.keys(MARKS).map((m) => el('span', {}, el('span', { class: `mk mk-${m}` }), MARKS[m]))) : '',
+      : at === 'designs' ? [...designGroups(by.designs)] : at === 'reports' && !state.readonly ? [by.reports.some((d) => d.steps) ? el('p', { class: 'card legend' }, ...Object.keys(MARKS).map((m) => el('span', {}, el('span', { class: `mk mk-${m}` }), MARKS[m]))) : '',
         ...(by.reports.length ? reportGroups(by.reports) : [el('p', { class: 'empty' }, EMPTY.reports)]), notes(by.notes)] : at === 'answered' && by.answered.length ? done(by.answered) : at ? [at === 'evidence' && by[at].length ? el('div', { class: 'sec-head' }, el('h2', {}, 'Updates')) : '', at === 'waiting' ? filters(by.waiting) : '', by[at].length ? el('div', { class: `list in-${at}${state.readonly ? ' readonly' : ''}` }, ...(at === 'waiting' ? shown : by[at]).map(row))
       : el('p', { class: 'empty' }, at === 'answered' && state.decisions.some((d) => gone.has(d.key) && isAnswered(d)) ? 'All done items cleared.' : EMPTY[at])] : [el('div', { class: 'tiles' }, ...Object.keys(AREAS).map((a) => tile(a, by[a]))),
       el('div', { class: 'pair' }, needs, today(by.answered)), ...(FROZEN || state.readonly || state.answers_only ? [] : [ask()]),
       el('div', { class: 'areas' }, ...Object.keys(AREAS).map((a) => section(a, by[a])))]));
-    readPage(key ? state.decisions.find((d) => d.key === key && reads(d) && !gone.has(d.key) && (at === 'reports' || (d.type === 'plan' && area(d) === at))) : undefined, at);
+    readPage(key ? state.decisions.find((d) => d.key === key && !gone.has(d.key) && (at === 'reports' && reads(d) || at === 'designs' && d.kind === 'design' || d.type === 'plan' && area(d) === at)) : undefined, at);
     if (FROZEN) freeze();
   }
   function freeze() {
@@ -1312,7 +1422,7 @@
     if (jump && location.hash === '#waiting') [cur, jump] = [jump, null];
     if (location.hash === '#waiting') waitType = 'all';
     render();
-    if (!reader.hidden) return reader.querySelector('h1').focus();
+    if (!reader.hidden) { scrollTo(0, 0); return reader.querySelector('h1').focus({ preventScroll: true }); }
     const item = (jump || back) && document.getElementById(`item-${jump || back}`);
     jump = null;
     item ? item.scrollIntoView() : scrollTo(0, 0);