sign-off-axi 0.4.2 → 0.4.3

package/dist/cli.js

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

package/dist/contract.js

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

package/dist/store.js

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

package/fixtures/contract/README.md

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

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

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

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

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

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

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

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

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

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

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

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

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

package/package.json

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

package/web/index.html

@@ -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); }
@@ -604,6 +606,12 @@
   }
 
   function row(d, { x = true } = {}) {
+    if (d.kind === 'design') {
+      const original = /^https?:/.test(d.link ?? '') ? el('p', { class: 'meta' }, el('a', { href: d.link, target: '_blank', rel: 'noopener noreferrer',
+        'aria-label': `Open original, ${d.title}` }, 'Open original')) : '';
+      return el('article', { class: 'row design', id: `item-${d.key}` },
+        el('div', {}, el('h3', { dir: 'auto' }, d.title), el('p', { class: 'about', dir: 'auto' }, d.about)), original);
+    }
     const err = el('div', { class: 'err', role: 'alert', id: `err-${d.key}` });
     const saved = Object.hasOwn(state.answers, d.key) ? state.answers[d.key] : undefined;
     // A read-only board, or an item with nothing to answer, shows no answer, note or comment controls.
@@ -930,7 +938,7 @@
    *  A plan has no options but waits for its send-back. */
   const area = (d) => {
     const a = isAnswered(d) ? 'answered' : d.area ?? (d.type === 'evidence' ? 'evidence'
-      : state.readonly || d.type === 'explainer' || !(d.options.length || d.reply || d.type === 'signin' || d.type === 'plan') ? 'reports' : 'waiting');
+      : state.readonly || d.type === 'explainer' || !(d.options.length || d.reply || d.type === 'signin' || d.type === 'plan' || d.kind === 'design') ? 'reports' : 'waiting');
     // Reports lists only what explains: a page to tap through, or a narrated video. Text alone (a receipt, a status line) is a note, folded under it.
     return a === 'reports' && !state.readonly && d.type !== 'explainer' && !reads(d) ? 'notes' : a;
   };
@@ -1072,18 +1080,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 +1104,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 +1118,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 +1127,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 +1167,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(); });
     };