sign-off-axi 0.4.3 → 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

@@ -779,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`');
@@ -812,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))
@@ -821,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.
@@ -844,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('=');
@@ -868,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';
@@ -883,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);
@@ -921,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`]),
@@ -952,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);
@@ -988,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`;
@@ -1007,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);
@@ -1115,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`');
@@ -1134,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;
@@ -1177,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'))
@@ -1332,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();
@@ -1362,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'));
@@ -1464,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) {
@@ -1580,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 ?? []) {
@@ -1615,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));
@@ -1768,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) {
@@ -2129,7 +2196,7 @@ async function route(req) {
     if (req.method === 'GET' && req.url?.startsWith('/design/')) {
         const [, , , key, ...parts] = new URL(req.url, 'http://localhost').pathname.split('/');
         const path = parts.map(decodeURIComponent).join('/'), d = loadDecisions(file).find(x => x.key === key && x.type === 'design');
-        const allowed = d?.journeys?.some(j => j.screens.some(s => Object.values(s.views).includes(path)));
+        const 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)

package/dist/contract.js

@@ -265,7 +265,7 @@ export function checkMessage(m, want, flags = false) {
         if (!['draft', 'in_review'].includes(m.status))
             throw bad('status', 'must be draft or in_review', 'Set "status" to "draft" or "in_review"');
         page('preview', /\.(png|jpe?g|webp)$/i, '.png, .jpg, .jpeg or .webp', '"design/preview.png"', 'a design preview');
-        const journeys = list('journeys', 1, 40, ['id', 'title', 'screens'], '{"id":"signup","title":"Sign up","screens":[...]}');
+        const 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))

package/dist/store.js

@@ -288,11 +288,14 @@ export function appendDesignAnswer(decisionsPath, d, verdict, notes, pick) {
     if (!Array.isArray(notes) || (verdict === 'change' && !notes.length))
         throw bad('notes must be a list, with at least one note on change');
     const screens = new Set((d.journeys ?? []).flatMap(j => j.screens.map(s => `${j.id}/${s.id}`)));
-    for (const n of notes)
-        if (!n || !screens.has(`${n.journey}/${n.screen}`) || !isText(n.note) || !n.note.trim() || [...n.note].length > NOTE_MAX)
-            throw bad('each note needs a known journey and screen, and text of 500 characters or fewer');
-    if (new Set(notes.map(n => `${n.journey}/${n.screen}`)).size !== notes.length)
-        throw bad('notes must name each screen once');
+    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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sign-off-axi",
-  "version": "0.4.3",
+  "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);
@@ -204,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; }
@@ -340,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; }
@@ -819,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 '';
@@ -920,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',
@@ -950,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; };
@@ -959,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) : '']
@@ -1184,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) {
@@ -1213,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 '';
@@ -1273,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.
@@ -1285,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 }; });
@@ -1303,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}`,
@@ -1318,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() {
@@ -1341,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);