sign-off-axi 0.3.5 → 0.3.7

package/README.md

@@ -131,6 +131,11 @@ sign-off-axi post --type explainer --title "<question>" --media <video> [--about
 sign-off-axi report init <folder>               write a report page to fill: the answer and a picture, a diagram, steps to tap, the detail folded
 sign-off-axi post --type report --title "<the answer>" --about "<why it matters>" --view <page.html> --preview <picture>
                                                 post that page as a report: a card with its picture that opens full screen; text alone is refused
+sign-off-axi post --type signin --service "<name>" --link <sign-in URL> --unlocks "<what>" --waits "<who>" [--expires 15m] [--key <key>]
+                                                ask the user to sign in: one card on top with an Open button and the time left
+sign-off-axi post --type signin --service "<name>" --start '<command as a JSON list>' --unlocks "<what>" --waits "<who>"
+                                                the same card, with a new link made at each tap: Open runs the command on this computer
+sign-off-axi signin done --key <key>            the sign-in is done: close its card
 sign-off-axi init [dir] [--agent auto|<name>]   write the repo setup under <dir>/.sign-off/ (config, board, mocks/ and evidence/ folders)
                                                 and install the skill for each chosen coding agent (auto: each one on PATH)
 sign-off-axi doctor [dir]                       check that setup and each agent's skill; every failure names its fix
@@ -151,11 +156,12 @@ sign-off-axi export [--out <file.html>]          write a frozen read-only copy o
 - `post --type design` asks for a pick between up to 6 mock options, each with an optional `--mock <value>=<path>` file (`.html`, `.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`, 5 MB or less) shown as a tall phone frame above its button (the recommended one first; on a phone the frames swipe sideways, the next one peeking in, and a tap opens one full size), plus a `--tradeoff` line and a `--recommend` badge. Mock paths are relative to the board file's folder and never escape it. One `.html` page can hold every variant: `--mock a=mocks/<key>/index.html?variant=a` loads the page with `?variant=a`. An `.html` mock or view loads the css, scripts, images and fonts beside it by relative name (`style.css`, `img/dot.png`), from its own folder only, never anything above it. The board adds a small pointing script to each `.html` mock: once the board turns it on for that frame, a tap on a part of the mock is kept from the mock and named back to the board as a path to that element, its tag and its words; it passes only text and gives the mock no reach into the board. With **Comment on the mocks** on, a tap opens a comment on that element: one per element, listed under the mocks with Edit and Delete (words typed but not yet saved stay with their element while the page is open, so tapping another element and back keeps them; a reload drops them), kept on the board and shown, until it is sent, only on the exact mock file it was made on. The comments go to the agent with the next answer on that card (a pick, Other answer or **Another round**, which may then have no note), each with its element, in `wait` and `answers` (`comments`); once sent they are listed as sent and can no longer change. An option with no mock, or whose file is gone, says "No mock for this option". `post --type decision` (the default) is exactly `raise`, and `raise` stays as its alias.
 - `post --type evidence` posts the next numbered update (`update-1`, `update-2`, ...) with 1 to 12 screenshots or recordings (`.png`, `.jpg`, `.jpeg`, `.webp`, `.mp4`, `.webm`, up to 50 MB each), a short note and an optional commit or PR link. The files are copied into `evidence/<number>/` next to the board, so the board is the store: no hosted service. The page shows the updates newest first; each file is served only while its size and SHA-256 still match what was posted, and recordings play inline on a phone. The person gives a verdict, **Pass**, **Fail** or **Needs work**, with an optional note, read back with `answers` or `wait --key update-<number>`.
 - `post --type diagram` and `post --type interactive` show a question with a picture: `--view <path>` names one board-relative file, an image (`.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`) drawn at card width for a diagram, or one self-contained `.html` page that runs in a sandboxed frame for interactive. Every mock and view is served under a Content-Security-Policy with no `fetch`, no remote files and no access to the dashboard or its tab. They answer like a decision.
-- `post --type report` posts an explainer page the user reads, with no answer: something they asked to have explained, or a concept, design or trade-off they must understand. `sign-off-axi report init <folder>` writes the page to fill, one self-contained `.html` file, phone first, light and dark: the answer in one plain sentence with a picture, then a diagram, then steps the reader taps through, then the detail folded. Reports and explainers lists each one as a card with its picture; a tap opens the page over the whole board, on a phone and a desk alike, with **‹ Reports** (or Escape) to go back. A report of text only is refused with the command that makes the page; one stored before reports had pages still loads, folded under **Notes**. Proof that something works is evidence, and a merge or a status note is neither.
+- `post --type report` posts an explainer page the user reads, with no answer: something they asked to have explained, or a concept, design or trade-off they must understand. `sign-off-axi report init <folder>` writes the page to fill, one self-contained `.html` file, phone first, light and dark: the answer in one plain sentence with a picture and an as-of line naming the date the facts were true, then a diagram, then steps the reader taps through, then the detail folded. Reports and explainers lists each one as a card with its picture; a tap opens the page over the whole board, on a phone and a desk alike, with **‹ Reports** (or Escape) to go back. A report of text only is refused with the command that makes the page; one stored before reports had pages still loads, folded under **Notes**. Proof that something works is evidence, and a merge or a status note is neither.
 - `post --type explainer` shows a question with a narrated video the agent made itself (stills plus speech from a free local engine such as piper or espeak-ng, joined with ffmpeg; the skill has the recipe). `--media` names one `.mp4` or `.webm`, copied into `evidence/<number>/` and served hash-checked like evidence media; it plays on the card with its own controls, at phone width too. `--about` is a short summary and each `--chapter m:ss=<title>` is a button that plays the video from there. sign-off itself never makes the video: it calls no speech engine, no ffmpeg and no network service.
+- `post --type signin` asks the person to sign in, for example with the link `npm login` prints. The card sits on top of Waiting on you, because someone waits on it now: the service, one big **Open** for the link (a new tab), what it unlocks, who waits, and the time left until `--expires` (an ISO date-time, or `90s`, `15m`, `2h`, `1d` from now), counting down on the open page. When the time is past, the card says "Link expired. Ask for a new link." and **Open** is off. Post again with the same `--key` and a new `--link` or `--expires` to put a new link on the same card; it waits again, also after it was done. The poster runs `signin done --key <key>` once it sees the sign-in worked: the card leaves Waiting on you and shows as **Signed in** under Answered; the open page picks that up within 20 seconds, with no reload. For a card posted with a link, the board runs no check of its own. The link must be `http(s)` with no user name or password in it, and no output prints it, because it can hold a one-time code. When links expire fast (an `npm login --auth-type=web` link lasts about 5 minutes), post `--start '["npm", "login", "--auth-type=web"]'` in place of `--link` and `--expires`: each tap on **Open** runs that command on the computer that serves the board (as a list, with no shell, in the board file's folder), opens a new tab at the first `https` link it prints on stdout (on stderr only when stdout has none within 2 seconds, since tools such as npm print other links there first), and keeps it running so the sign-in can finish; a second tap while it runs opens the same link. Its exit 0 closes the card as done by itself; a failure, or no link within 20 seconds, shows on the card in plain words and **Open** tries again. It is stopped after 10 minutes, when the card closes, or when the board stops. The page only learns that a tap makes a new link, never the command, and the link is kept in memory only while the command runs: never stored, printed or logged.
 - The person can also tap **Another round** inside **Other answer** (with the typed note), which wakes a waiting agent the same way an answer does; the agent reads it back in `answers --json` under `rounds`, with any comments on mock elements it carried.
 - **Dismiss** (the × on an item in a list, **Dismiss** under Needs you first and beside **Skip for now** in Triage, or **Clear all done** on Answered) hides items from the board, Today included; **Undo** in the toast brings them back, and so does **Restore** under **Dismissed (N)** at the end of Needs you first and Triage. `list` counts a dismissed item as neither waiting nor answered, as the board does (`list --full` says `dismissed` for an unanswered one and still its answer for an answered one), and `answers` does not count it as waiting; the agent is not told, so an ask it waits on keeps waiting, and `answers` still returns a dismissed answer. The storage is in [docs/file-formats.md](docs/file-formats.md).
-- The person can comment on any item (**Send as a comment**, also inside **Other answer**: each card has that one place to type) and queue a free-text prompt for the agent (**Ask the agent**). `poll` blocks until one arrives and prints every new one once (`--json` prints `{"messages":[{"id","kind","key"?,"text","at"}]}`); the page then shows it as read by the agent. Typed notes that are not sent yet stay in the browser across reloads; everything sent is saved next to the board and survives a restart.
+- The person can comment on any item (**Send as a comment**, also inside **Other answer**: every card but a sign-in has that one place to type) and queue a free-text prompt for the agent (**Ask the agent**). `poll` blocks until one arrives and prints every new one once (`--json` prints `{"messages":[{"id","kind","key"?,"text","at"}]}`); the page then shows it as read by the agent. Typed notes that are not sent yet stay in the browser across reloads; everything sent is saved next to the board and survives a restart.
 - The board runs on your own machine only: no hosted service, no recurring cost. It listens on `127.0.0.1` unless `--bind <address>` (or `bind:` in the `config.yaml` that `init` writes) names one private address of this machine, such as its VPN address, so a phone or tablet on your own network can open it. A `hosts:` line in that config names private DNS names that lead to the bind address, such as its mesh VPN name (commas between them), so the board also opens by name; `doctor` checks each one resolves to the bind address. All interfaces and public addresses are refused. Beyond `127.0.0.1` the board makes an access token once (`decisions.token`, mode 600, next to the board), `open` prints it in the link, and every request without it is refused; the link sets a cookie, so the page and its media work after the first load. Delete the token file to shut old links out at once, then `stop` and `open` for a new one.
 - `export` writes one self-contained HTML file (`decisions.export.html` by default): every item, answer, note and another-round request with its local mocks and media inlined; comments and queued prompts are left out. `--out` must end in `.html`, so a wrong path never overwrites the board. It opens from disk with no server, is read-only, and makes no network request. A mock page is inlined on its own, so the css and images beside it show only on the running board.
 - With no `--option` a question is Yes/No; give 2 to 6 `--option` flags for a pick-one question (`--option friday=Friday --option next-week="Next week"`). `--recommend` and `--default` name one of its values. Listing options needs `--recommend` (on `raise`, `post` and `--from` files): the board shows that option first and marks it; a plain Yes/No may leave it out. Each answer is one tap, with an Undo for a few seconds after it (an Undo is saved as an answer change). Typing is last: every question with options, a design's Picks included, has a text box folded behind **Other answer** (none when an option is valued `text`); the words are saved as the answer `text`, with the same Undo.

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, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, 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, 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';
@@ -26,8 +26,8 @@ const AGENTS = {
     'gemini-cli': { bin: 'gemini', dir: '.agents/skills', home: join(homedir(), '.gemini', 'skills') },
 };
 const TOP_HELP = `usage: sign-off-axi [command] [board.json] [flags]
-commands[16]:
-  (none)=list, raise, post, answers, wait, poll, open, status, stop, serve, export, init, report, doctor, validate, help
+commands[17]:
+  (none)=list, raise, post, answers, wait, poll, open, status, stop, serve, export, init, report, signin, doctor, validate, help
 board: the nearest .sign-off/ board (the walk's bounds and SIGN_OFF_HOME: README, "Test runs never touch your board"), else ~/.sign-off/decisions.json; a board file given always wins
 flags: --full and --json on list, answers and wait, --events on wait, --json on status, --filer on post, raise and wait, --help on every command, -v/--version
 examples:
@@ -39,6 +39,8 @@ examples:
   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
   sign-off-axi report init .sign-off/mocks/sign-in-flow
   sign-off-axi post .sign-off/decisions.json --type report --title "Sign-in now takes 2 steps" --about "Why the code step moved first." --view mocks/sign-in-flow/index.html --preview mocks/sign-in-flow/preview.svg
+  sign-off-axi post --type signin --key npm-login --service npm --link https://example.com/login --unlocks "Publish the release" --waits "Main" --expires 15m
+  sign-off-axi signin done --key npm-login
   sign-off-axi init
   sign-off-axi doctor
   sign-off-axi validate ask.json
@@ -167,6 +169,8 @@ examples:
        sign-off-axi post [board.json] --kind <kind> --from <message.json|-> [--filer <id>]
        sign-off-axi post [board.json] --type explainer --title "<question>" --media <video> [--about <summary>] [--chapter <m:ss>=<title>]... [--key <key>] [--option <value>=<label>]... [--recommend <value>]
        sign-off-axi post [board.json] --type report --title "<the answer>" --about "<why it matters>" --view <page.html> --preview <picture> [--key <key>] [--link <commit or URL>] [--filer <id>]
+       sign-off-axi post [board.json] --type signin --service "<name>" --link <sign-in URL> --unlocks "<what it unlocks>" --waits "<who waits>" [--expires <ISO time or 15m>] [--key <key>] [--filer <id>]
+       sign-off-axi post [board.json] --type signin --service "<name>" --start '<command as a JSON list>' --unlocks "<what it unlocks>" --waits "<who waits>" [--key <key>] [--filer <id>]
 Posts an item for the user. --type decision (the default) is a yes/no or pick-one question, exactly like raise.
 --kind posts one contract message (${CONTRACT}), read from a file or from stdin with --from -: it must be that kind and pass every rule,
 else it is refused with one fix line and nothing is written. A key already on the board takes only the same message again; anything else exits 2.
@@ -200,6 +204,14 @@ and played on the card. --about is its short summary; up to ${CHAPTERS_MAX} --ch
 --view is the page and --preview its picture on the card, beside it, both from the board file's folder; \`sign-off-axi report init <folder>\` makes them.
 The page must be filled (no FILL: line left), with a viewport tag, dark mode, a picture, something to tap, its detail folded, nothing from the web, and no block over about five lines on a phone.
 Merges, PR outcomes, receipts and status notes are not reports: post proof of a change as evidence.
+--type signin asks the user to sign in, at the top of what waits: the service, one Open button for the http(s) --link, what it unlocks,
+who waits, and the time left until --expires (an ISO date-time, or 90s, 15m, 2h, 1d from now). After that time the card says the link expired.
+No output prints the link. Post again with the same --key and a new --link or --expires to put a new link on the same card; it waits again.
+When the sign-in is done, run \`sign-off-axi signin done [board.json] --key <key>\`: the card leaves the open list and shows as done.
+For a link that expires fast, give --start, the command that prints a new sign-in link, as a JSON list such as '["npm", "login", "--auth-type=web"]'.
+Each tap on Open then runs it on the computer that serves the board (no shell, in the board file's folder) and opens the first https link it prints on stdout
+(on stderr when stdout has none within 2 seconds), so the card never shows an expired link. A tap while it runs opens the same link again. Its exit 0 closes the card as done; a failure, or no link
+within 20 seconds, shows on the card and Open can try again. It is stopped after 10 minutes, or when the card closes. The link is never stored or printed.
 examples:
   sign-off-axi post --type design --title "Pick the sign-in layout" --option a="A: single column" --option b="B: split screen" --mock a=mocks/a.html --mock b=mocks/b.html --tradeoff "B scans fastest; A is simplest." --recommend b
   sign-off-axi post .sign-off/decisions.json --type design --key sign-in --title "Pick the sign-in layout" --option a=A --option b=B --option c=C --mock a=mocks/sign-in/index.html?variant=a --mock b=mocks/sign-in/index.html?variant=b --mock c=mocks/sign-in/index.html?variant=c --tradeoff "..." --recommend b
@@ -212,6 +224,14 @@ examples:
   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"
   sign-off-axi post .sign-off/decisions.json --type report --title "Sign-in now takes 2 steps" --about "Why the code step moved first." --view mocks/sign-in-flow/index.html --preview mocks/sign-in-flow/preview.svg
+  sign-off-axi post --type signin --key npm-login --service npm --link https://example.com/login --unlocks "Publish the release" --waits "Main" --expires 15m
+  sign-off-axi post --type signin --key npm-login --service npm --start '["npm", "login", "--auth-type=web"]' --unlocks "Publish the release" --waits "Main"
+`,
+    signin: `usage: sign-off-axi signin done [board.json] --key <key>
+Closes a sign-in card that post --type signin made: the sign-in is done, so the card leaves the open list and shows as done.
+Run it when you see the sign-in worked. A card posted with --start also closes by itself when its command ends with exit 0. wait --key <key> also returns once it is done.
+examples:
+  sign-off-axi signin done --key npm-login
 `,
     report: `usage: sign-off-axi report init <folder>
 Writes a report page to fill: <folder>/index.html and its card picture <folder>/preview.svg. A file already there is kept.
@@ -422,7 +442,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);
+const waits = (d) => !d.dismissed && !d.answer && (d.options.length > 0 || !!d.reply || d.type === 'signin');
 /** 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) {
@@ -455,7 +475,7 @@ function list(args) {
     const { file, values, on } = parse('list', args, TIERS);
     const rows = board(file), waiting = rows.filter(waits), answered = rows.filter((d) => d.answer && !d.dismissed).length;
     if (values.json)
-        return JSON.stringify({ board: file, decisions: rows.map(({ dismissed, ...d }) => (dismissed ? { ...d, dismissed } : d)) });
+        return JSON.stringify({ board: file, decisions: rows.map(({ dismissed, ...d }) => ({ ...d, ...(d.type === 'signin' && { link: undefined }), ...(dismissed && { dismissed }) })) });
     const help = [
         ...(waiting.length ? [`Run \`sign-off-axi open${on}\` to show the board to the user`] : []),
         ...(answered ? [`Run \`sign-off-axi answers${on}\` to read the ${answered} saved answers`] : []),
@@ -709,10 +729,11 @@ const mockFile = (path) => path.split('?')[0];
 /** Posts an item. `raise` is the alias for `post --type decision`: same flags as before, same output. */
 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 } } : {};
+        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,
         ...Object.fromEntries(RAISE_FIELDS.map((f) => [f, { type: 'string', multiple: f === 'option' }])) });
-    const given = [...RAISE_FIELDS, 'type', 'tradeoff', 'mock', 'media', 'link', 'view', 'preview', 'chapter'].filter((f) => values[f] !== undefined);
+    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)
@@ -727,6 +748,11 @@ function post(args, cmd = 'post') {
     const type = values.type ?? 'decision';
     if (type === 'report')
         return postReport(file, on, values);
+    if (type === 'signin')
+        return postSignin(file, 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`');
     if (values.preview !== undefined)
         throw fail('--preview needs --type report', 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
     if (values.from === undefined && values.title === undefined) {
@@ -734,7 +760,7 @@ function post(args, cmd = 'post') {
             : type === 'evidence' ? 'sign-off-axi post --type evidence --title "<what this shows>" --about "<short note>" --media <file>' : `sign-off-axi ${cmd} --title "<question>" [--recommend <value>]`);
     }
     if (!['decision', 'design', 'evidence', 'diagram', 'interactive', 'explainer'].includes(type))
-        throw fail(`--type must be decision, design, evidence, diagram, interactive, explainer or report`, 'VALIDATION_ERROR', 'Run `sign-off-axi post --help`');
+        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);
     if (values.media !== undefined || values.link !== undefined || values.chapter !== undefined)
@@ -794,6 +820,86 @@ function post(args, cmd = 'post') {
     });
     return storeIncoming(file, 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';
+const SIGNIN_START_EXAMPLE = 'sign-off-axi post --type signin --key npm-login --service npm --start \'["npm", "login", "--auth-type=web"]\' --unlocks "Publish the release" --waits "Main"';
+/** --expires: an ISO date-time, or a time from now such as 90s, 15m, 2h or 1d; refused when it is already past. */
+function expiresAt(value) {
+    const span = /^(\d{1,6})([smhd])$/.exec(value), at = span ? Date.now() + Number(span[1]) * { s: 1e3, m: 6e4, h: 36e5, d: 864e5 }[span[2]]
+        : /^\d{4}-\d{2}-\d{2}T/.test(value) ? Date.parse(value) : NaN;
+    if (!(at > Date.now()))
+        throw fail(`--expires ${value} must be a time still to come: an ISO date-time such as 2026-10-13T07:19:00Z, or a time from now such as 15m`, 'VALIDATION_ERROR', SIGNIN_EXAMPLE);
+    return new Date(at).toISOString().replace(/\.\d+Z$/, 'Z');
+}
+/** 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) {
+    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);
+    const missing = ['service', ...(values.start === undefined ? ['link'] : []), 'unlocks', 'waits'].filter((f) => values[f] === undefined);
+    if (missing.length)
+        throw fail(`--type signin needs ${missing.map((f) => `--${f}`).join(', ')}${values.link === undefined ? ' (or --start in place of --link)' : ''}`, 'VALIDATION_ERROR', SIGNIN_EXAMPLE);
+    const { service, link, unlocks, waits: who, key = `signin-${slug(service)}` } = values;
+    let start;
+    if (values.start !== undefined) {
+        try {
+            start = JSON.parse(values.start);
+        }
+        catch {
+            start = undefined;
+        }
+        if (!Array.isArray(start))
+            throw fail('--start must be the command as a JSON list, such as \'["npm", "login", "--auth-type=web"]\'', 'VALIDATION_ERROR', SIGNIN_START_EXAMPLE);
+        if (values.link !== undefined || values.expires !== undefined)
+            throw fail(`--${values.link !== undefined ? 'link' : 'expires'} does not apply with --start: each tap makes a new link`, 'VALIDATION_ERROR', SIGNIN_START_EXAMPLE);
+    }
+    const expires = values.expires === undefined ? undefined : expiresAt(values.expires);
+    const { incoming: [d], raw: [item] } = buildIncoming({ title: service, key }, { type: 'signin', link, unlocks, waits: who, ...(expires && { expires }), ...(start && { start }) }, filer, file);
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    return locked(`${file}.lock`, () => {
+        const items = existsSync(file) ? readItems(file).items : [], at = items.findIndex((x) => x?.key === d.key), had = items[at];
+        if (had && had.type !== 'signin')
+            throw fail(`key ${d.key} already holds a different question on ${tilde(file)}`, 'CONFLICT', 'Post the sign-in under a new --key');
+        const same = had && canon({ ...had, filed: undefined, filer: undefined }) === canon({ ...item, filed: undefined, filer: undefined });
+        const done = readAnswers(file)[d.key];
+        let status = same ? (done ? 'already done' : 'already waiting') : had ? 'new link' : 'posted';
+        if (!same) {
+            fits(d.title, d.key);
+            const next = { ...item, filed: new Date().toISOString().replace(/\.\d+Z$/, 'Z') };
+            if (had)
+                items[at] = next;
+            else
+                items.push(next);
+            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);
+        }
+        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`]),
+            `Run \`sign-off-axi signin done${on} --key ${d.key}\` when the sign-in is done; the card then closes`,
+            ...(start ? [] : [`Run \`sign-off-axi post${on} --type signin --key ${d.key} ...\` again with a new --link and --expires when this link expires`])
+        ]);
+    });
+}
+/** signin done [board.json] --key <key>: the sign-in is done, so its card leaves the open list and shows as done. */
+function signin(args) {
+    const [sub, ...rest] = args;
+    if (sub !== 'done')
+        throw fail(`unknown signin command ${sub ?? '(none)'}`, 'VALIDATION_ERROR', 'sign-off-axi signin done [board.json] --key <key>');
+    const { file, values, on } = parse('signin done', rest, { key: { type: 'string' } });
+    if (values.key === undefined)
+        throw fail('signin done needs --key <key>', 'VALIDATION_ERROR', 'sign-off-axi signin done [board.json] --key <key>');
+    return locked(`${file}.lock`, () => {
+        const d = board(file).find((x) => x.key === values.key);
+        if (d?.type !== 'signin')
+            throw fail(`no sign-in with key ${values.key} on ${tilde(file)}`, 'NOT_FOUND', `Run \`sign-off-axi list${on}\` to see the waiting keys`);
+        const saved = appendAnswer(file, d, SIGNED_IN);
+        return toon({ board: tilde(file), closed: [{ key: d.key, status: saved ? 'done' : 'already done', service: d.title }] }, [`Run \`sign-off-axi list${on}\` to see what still waits on the user`]);
+    });
+}
 /** 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) {
@@ -812,7 +918,7 @@ function replace(file, on, from, filer) {
         const feed = fed.items.map((i) => ({ filed: first.get(i?.key)?.filed ?? now, ...i, ...(filer && { filer }) }));
         // An answer belongs to its question: an answered key may not come back asking something else.
         // Evidence is answered for the media and run it shows, so those are part of its question too, as a gate's run and a finding's proposal are.
-        const question = (d) => JSON.stringify([d.title, [...d.options].sort((a, b) => a.value.localeCompare(b.value)), !!d.reply, d.run, d.finding, d.evidence, d.media]);
+        const question = (d) => JSON.stringify([d.title, [...d.options].sort((a, b) => a.value.localeCompare(b.value)), !!d.reply, d.run, d.finding, d.evidence, d.media, d.type === 'signin' ? [d.link, d.start] : '']);
         // A key whose answer outlived it may not come back: the board and the answers are read here, under the lock the feed writes with.
         const saved = readAnswers(file);
         for (const i of fed.items)
@@ -1710,6 +1816,7 @@ async function serve(args) {
         if (!server.listening)
             return;
         await sweep('periodic');
+        reap();
         if (server.listening)
             setTimeout(repeat, 5_000).unref();
     };
@@ -1796,6 +1903,7 @@ const page = readFileSync(new URL('../web/index.html', import.meta.url));
 const pointer = Buffer.from(`<script>${readFileSync(new URL('../web/point.js', import.meta.url), 'utf8')}</script>`);
 const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const state = () => {
+    reap();
     // The page marks sent comments in annotations, so answers and rounds go without theirs: a read-only board or an export carries none.
     const answers = Object.fromEntries(Object.entries(readAnswers(file, warn)).map(([k, { comments: _, ...a }]) => [k, a])), taken = seenBy(file);
     const rounds = readRounds(file, warn).map(({ comments: _, ...r }) => r);
@@ -1803,7 +1911,8 @@ const state = () => {
         file,
         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.
-        decisions: loadDecisions(file).map(({ filer: _, ...d }) => ({ ...d, evidenceCard: d.evidence ? evidenceCard(d.evidence) : null,
+        // 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,
             ...(d.mocks && { mocks: d.mocks.map((m) => ({ ...m, hash: mockHash(m.path) })) }) })),
         readonly: readOnly(),
         answers_only: answersOnly(),
@@ -1963,12 +2072,12 @@ async function route(req) {
     if (req.method === 'GET' && req.url === '/api/decisions') {
         return [200, state()];
     }
-    if (req.method !== 'POST' || !['/api/answers', '/api/rounds', '/api/messages', '/api/annotations', '/api/dismiss'].includes(req.url ?? ''))
+    if (req.method !== 'POST' || !['/api/answers', '/api/rounds', '/api/messages', '/api/annotations', '/api/dismiss', '/api/signin'].includes(req.url ?? ''))
         return [404, { error: 'Not found' }];
     if (readOnly())
         return [403, { error: 'This board is read-only' }];
     // Dismiss only hides an item on this page and sends nothing to the feeding program, so an answers-only board takes it too.
-    if (!['/api/answers', '/api/dismiss'].includes(req.url) && answersOnly())
+    if (!['/api/answers', '/api/dismiss', '/api/signin'].includes(req.url) && answersOnly())
         return [403, { error: 'This board takes answers only' }];
     if (!req.headers['content-type']?.startsWith('application/json'))
         return [415, { error: 'Send JSON' }];
@@ -2016,6 +2125,21 @@ async function route(req) {
         appendAnnotation(file, { id: same?.id, key, mock, hash, ref, tag, words, text: text.trim() });
         return [200, state()];
     }
+    if (req.url === '/api/signin') {
+        // Only the key comes from the page: the command is the one the poster stored on this host.
+        const { key } = JSON.parse(body) ?? {}, d = board(file).find((x) => x.key === key);
+        if (!d?.start)
+            return [404, { error: 'This card has no sign-in to start' }];
+        if (d.answer)
+            return [409, { error: 'This sign-in is already done' }];
+        try {
+            return [200, { open: await signinLink(d), state: state() }];
+        }
+        catch (e) {
+            // A run that ended with exit 0 before it printed a link was already signed in: the card is done, with no link to open.
+            return board(file).find((x) => x.key === key)?.answer ? [200, { state: state() }] : [502, { error: e.message, state: state() }];
+        }
+    }
     if (req.url === '/api/dismiss') {
         const { keys, dismissed } = JSON.parse(body) ?? {};
         if (!Array.isArray(keys) || !keys.length || keys.length > 200 || typeof dismissed !== 'boolean')
@@ -2078,6 +2202,96 @@ function answered(a, d) {
     child.stdin.on('error', () => { });
     child.stdin.end(`${JSON.stringify({ event: 'answer', ...kindOf(file)(a.key), ...a, ...(d && { title: d.title }), ...(d?.filer && { filer: d.filer }) })}\n`);
 }
+const runs = new Map(), failures = new Map();
+const SIGNIN_WAIT = 20_000, SIGNIN_LIFE = 600_000;
+const signinState = (key) => (runs.get(key)?.url ? 'live' : runs.has(key) ? 'starting' : failures.has(key) ? `failed: ${failures.get(key)}` : 'none');
+/** Stops a run and its child processes (it leads its own process group): SIGTERM first, SIGKILL if it stays. */
+function stopRun(key, why) {
+    const run = runs.get(key);
+    if (!run)
+        return;
+    run.why ??= why;
+    const signal = (sig) => { try {
+        process.kill(-run.child.pid, sig);
+    }
+    catch {
+        run.child.kill(sig);
+    } };
+    signal('SIGTERM');
+    setTimeout(() => { if (runs.get(key) === run)
+        signal('SIGKILL'); }, 2_000).unref();
+}
+/** Stops each run whose card closed: done, gone from the board, no longer a start-command sign-in, or swapped for another command. */
+function reap() {
+    if (!runs.size)
+        return;
+    const items = new Map(board(file, () => { }).map((d) => [d.key, d]));
+    for (const key of runs.keys()) {
+        const d = items.get(key), run = runs.get(key);
+        if (!d?.start || d.answer)
+            stopRun(key, 'The card closed.');
+        else if (JSON.stringify(d.start) !== JSON.stringify(run.argv))
+            stopRun(key, 'A new sign-in was posted for this card.');
+    }
+}
+/** The live link for a tap on Open: a run still going gives its link again; else the start command runs with no shell in the board's folder,
+ * and the first https link it prints on stdout (else on stderr) is the link. Its exit 0 closes the card as done. The link is never logged or stored. */
+function signinLink(d) {
+    const had = runs.get(d.key);
+    if (had)
+        return had.link;
+    failures.delete(d.key);
+    const [cmd, ...rest] = d.start, child = spawn(cmd, rest, { cwd: dirname(file), stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+    let found, lost, aside;
+    const run = { child, argv: [cmd, ...rest], link: new Promise((ok, no) => { found = ok; lost = (why) => no(new Error(why)); }) };
+    run.link.catch(() => { });
+    runs.set(d.key, run);
+    const take = (url) => { if (!run.url)
+        found((run.url = url)); };
+    // The link is the first https link on stdout: tools such as npm print notices with other links on stderr first.
+    // ponytail: a tool that prints its link only on stderr (gh) is read from there after 2 s of nothing on stdout; add a link pattern per card if a tool needs one.
+    const reader = (onOut) => {
+        let seen = '';
+        return (b) => {
+            if (run.url)
+                return;
+            seen = (seen + b).slice(-8000);
+            const url = /https:\/\/[^\s"'<>`]+/.exec(seen)?.[0];
+            if (url && onOut)
+                take(url);
+            else if (url)
+                aside ??= setTimeout(() => take(url), 2000);
+        };
+    };
+    child.stdout.on('data', reader(true));
+    child.stderr.on('data', reader(false));
+    const wait = setTimeout(() => run.url || stopRun(d.key, 'It gave no sign-in link within 20 seconds.'), SIGNIN_WAIT);
+    const life = setTimeout(() => stopRun(d.key, 'It was not done within 10 minutes, so it was stopped.'), SIGNIN_LIFE);
+    const end = (why) => {
+        clearTimeout(aside);
+        clearTimeout(wait);
+        clearTimeout(life);
+        if (runs.get(d.key) !== run)
+            return;
+        runs.delete(d.key);
+        if (why)
+            failures.set(d.key, why);
+        lost(why ?? 'The sign-in is done.');
+    };
+    child.on('error', (e) => end(e.code === 'ENOENT' ? `${basename(cmd)} is not on this computer.` : `It did not start (${e.code ?? e.message}).`));
+    child.on('exit', (code) => {
+        if (code === 0) {
+            const now = board(file).find((x) => x.key === d.key);
+            if (now?.start && !now.answer && JSON.stringify(now.start) === JSON.stringify(run.argv))
+                answered(appendAnswer(file, now, SIGNED_IN), now);
+            return end();
+        }
+        end(run.why ?? (code === null ? "It was stopped." : `It stopped with exit code ${code}.`));
+    });
+    return run.link;
+}
+process.on('exit', () => { for (const key of runs.keys())
+    stopRun(key, 'The board stopped.'); });
 const server = createServer(async (req, res) => {
     const { port: bound } = server.address();
     // Only loopback names, the bound address and the config's hosts: names: blocks DNS rebinding from a web page.
@@ -2132,7 +2346,7 @@ await runAxiCli({
     topLevelHelp: TOP_HELP,
     getCommandHelp: (cmd) => HELP[cmd],
     home: axi('list', list),
-    commands: { list: axi('list', list), raise: axi('raise', (args) => post(args, 'raise')), post: axi('post', post), answers: axi('answers', answers), wait: axi('wait', wait), poll: axi('poll', poll), open: axi('open', open), status: axi('status', status), stop: axi('stop', stop), serve: axi('serve', serve), export: axi('export', exportBoard), init: axi('init', init), report: axi('report', report), doctor: axi('doctor', doctor), validate, help: ([name, ...rest]) => {
+    commands: { list: axi('list', list), raise: axi('raise', (args) => post(args, 'raise')), post: axi('post', post), answers: axi('answers', answers), wait: axi('wait', wait), poll: axi('poll', poll), open: axi('open', open), status: axi('status', status), stop: axi('stop', stop), serve: axi('serve', serve), export: axi('export', exportBoard), init: axi('init', init), report: axi('report', report), signin: axi('signin', signin), doctor: axi('doctor', doctor), validate, help: ([name, ...rest]) => {
             if (rest.length || (name && !HELP[name]))
                 throw fail(`unknown command or argument: ${[name, ...rest].join(' ')}`, 'VALIDATION_ERROR', 'Run `sign-off-axi --help` to see the commands');
             return name ? HELP[name] : TOP_HELP;

package/dist/store.js

@@ -13,6 +13,8 @@ export function unreadable(code) {
                 : `cannot be read (${code ?? 'unknown error'})`;
 }
 const YES_NO = [{ value: 'yes', label: 'Yes' }, { value: 'no', label: 'No' }];
+/** The answer `signin done` saves: the sign-in is done and its card leaves the open list. */
+export const SIGNED_IN = { value: 'done', label: 'Signed in' };
 /** The answer a `reply: true` item saves for a short text reply; the text is its note. */
 export const REPLY = { value: 'text', label: 'Reply' };
 const VERDICTS = [{ value: 'pass', label: 'Pass' }, { value: 'fail', label: 'Fail' }, { value: 'needs-work', label: 'Needs work' }];
@@ -120,8 +122,35 @@ export function loadDecisions(path, board) {
             throw bad('decided', 'must be text of 200 characters or fewer');
         if (d.type === 'evidence' && !(Number.isInteger(d.number) && d.number >= 1))
             throw bad('number', 'must be a whole number from 1');
-        if (d.link !== undefined && !(isText(d.link) && /^(https?:\/\/\S{1,500}|[a-f0-9]{7,40})$/u.test(d.link)))
+        const signin = d.type === 'signin';
+        if (d.link !== undefined && !(isText(d.link) && /^(https?:\/\/\S{1,500}|[a-f0-9]{7,40})$/u.test(d.link)) && !signin)
             throw bad('link', 'must be an http(s) link or a commit hash');
+        // A sign-in is a link to open, what it unlocks and who waits; its answer is the `signin done` its poster saves, so the user gets no buttons.
+        if (signin) {
+            // A start command makes a new link at each tap, so it needs no fixed link and never expires.
+            const start = d.start !== undefined;
+            if (start && !(Array.isArray(d.start) && d.start.length >= 1 && d.start.length <= 64 && d.start.every((a) => isText(a) && a.length <= 4096 && !a.includes('\0')) && d.start[0].trim())) {
+                throw bad('start', 'must be a command and its arguments as a list of 1 to 64 texts, such as ["npm", "login", "--auth-type=web"]');
+            }
+            if (start && d.expires !== undefined)
+                throw bad('expires', 'must be left out with start: each tap makes a new link');
+            let url;
+            try {
+                url = new URL(d.link);
+            }
+            catch { }
+            if ((!start || d.link !== undefined) && (!(isText(d.link) && /^https?:\/\/\S{1,2000}$/u.test(d.link)) || !url || url.username || url.password)) {
+                throw bad('link', `must be an http(s) sign-in link of 2000 characters or fewer, with no user name or password in it${start ? '' : ' (or give a start command)'}`);
+            }
+            for (const f of ['unlocks', 'waits'])
+                if (!(isText(d[f]) && d[f].trim() && [...d[f]].length <= 120))
+                    throw bad(f, 'must be text of 120 characters or fewer');
+            if (d.expires !== undefined && !(isText(d.expires) && /^\d{4}-\d{2}-\d{2}T/.test(d.expires) && !Number.isNaN(Date.parse(d.expires))))
+                throw bad('expires', 'must be an ISO 8601 date-time such as 2026-10-13T07:19:00Z');
+            for (const f of ['options', 'reply', 'recommend_value', 'default_if_silent'])
+                if (d[f] !== undefined)
+                    throw bad(f, 'must be left out: a sign-in closes with signin done, not with an answer');
+        }
         // 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';
@@ -136,9 +165,9 @@ export function loadDecisions(path, board) {
             for (const f of ['options', 'reply', 'area', 'type'])
                 if (d[f] !== undefined)
                     throw bad(f, `must be left out: a report takes no answer${f === 'options' ? '' : ' and shows only under Reports'}`);
-        const options = d.options ?? (report ? [] : 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, or a report, shows those.
-        if (!Array.isArray(options) || options.length === 1 || (!options.length && !fed && !report) || options.length > 6
+        const options = d.options ?? (report || signin ? [] : 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) || options.length > 6
             || !options.every((o) => isKey(o?.value) && isText(o.label) && o.label.trim())) {
             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');
         }
@@ -173,6 +202,7 @@ export function loadDecisions(path, board) {
             recommend_value: d.recommend_value, default_if_silent: d.default_if_silent, close: d.close ?? 'done', evidence: d.evidence,
             type: d.type ?? 'decision', tradeoff: d.tradeoff, link: d.link, mocks: d.mocks?.map((m) => ({ value: m.value, path: m.path })),
             ...(views && { view: d.view }), ...(report && views && { preview: d.preview }), ...(d.reply && { reply: true }), ...(d.filer && { filer: d.filer }), ...(d.area && { area: d.area }),
+            ...(signin && { unlocks: d.unlocks, waits: d.waits, ...(d.expires && { expires: d.expires }), ...(d.start && { start: [...d.start] }) }),
             ...(d.group && { group: d.group }), ...(d.filed && { filed: d.filed }), ...(d.decided && { decided: d.decided }),
             ...(d.steps && { steps: d.steps.map(({ title, marks }) => ({ title, ...(marks?.length && { marks }) })) }),
             ...(stored && d.media && { media: d.media.map(({ path, sha256, bytes }) => ({ path, sha256, bytes })) }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sign-off-axi",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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

@@ -174,6 +174,11 @@
   .in-waiting .row { box-shadow: inset 3px 0 0 var(--accent), var(--shadow); }
   .in-answered .row { background: transparent; box-shadow: none; }
   .in-answered .row h3 { color: var(--muted); font-weight: 500; }
+  /* A sign-in: one big Open for its link, off once the link expired. */
+  .open-link { display: grid; place-items: center; min-height: 3.5rem; border-radius: 1rem; background: var(--accent); color: var(--on-accent);
+    font-size: 1.125rem; font-weight: 700; text-decoration: none; }
+  button.open-link:disabled { border: 1px solid var(--line); background: var(--sunk); color: var(--muted); cursor: not-allowed; }
+  .signin .line { margin: 0.375rem 0 0; } .signin .expiry { margin: 0.5rem 0 0; font-weight: 700; } .signin .expiry.gone { color: var(--danger); }
   .row h3, .report h3 { font-size: 1.1875rem; font-weight: 650; line-height: 1.3; letter-spacing: -0.005em; margin: 0; }
   .about, details p { margin: 0.375rem 0 0; max-width: 70ch; }
   details p { color: var(--muted); }
@@ -462,7 +467,7 @@
         el('p', { dir: 'auto' }, el('strong', {}, `${name}: `), run[name].replace(new RegExp(`^${name}:\\s*(?=\\S)`, 'i'), '')))] : []));
   }
 
-  const NAMES = { decision: 'Decision', design: 'Design', evidence: 'Evidence', diagram: 'Diagram', interactive: 'Interactive', explainer: 'Explainer' };
+  const NAMES = { decision: 'Decision', design: 'Design', evidence: 'Evidence', diagram: 'Diagram', interactive: 'Interactive', explainer: 'Explainer', signin: 'Sign-in' };
   // Any other type gets the plain card until it has its own renderer; a plain question needs no name.
   const kind = (d) => (d.type === 'decision' ? '' : NAMES[d.type] ?? d.type.replace(/-/g, ' '));
   // A done-done run's outcome line is the plain result a person can now see; the title it sends only names the run.
@@ -517,6 +522,7 @@
     const brow = [update ? `Update ${d.number}` : kind(d), result ? el('span', { class: `st ${result[0]}` }, result[1]) : '',
       update && d.filed ? (isToday(d.filed) ? el('span', { class: 'st new' }, 'New') : day(d.filed)) : '', seen].filter(Boolean);
     const lead = el('div', { class: 'lead' }, x ? xBtn(d) : '', brow.length ? el('p', { class: 'eyebrow' }, ...brow) : '', el('h3', { dir: 'auto' }, name));
+    if (d.type === 'signin') return signin(d, lead, saved, err);
     const silent = d.default_if_silent && !ro ? `If no answer: ${d.options.find((o) => o.value === d.default_if_silent).label}` : '';
     if (design) {
       return el('article', { class: 'row design', id: `item-${d.key}` }, lead,
@@ -539,6 +545,65 @@
       ro ? '' : other(d, saved, err), err, tech(d));
   }
 
+  /** The time left on a sign-in link, in whole minutes. */
+  const expiry = (at) => {
+    const m = Math.ceil((Date.parse(at) - Date.now()) / 60_000);
+    return m <= 0 ? 'Link expired. Ask for a new link.' : `Expires in ${m < 60 ? `${m} min` : `${Math.floor(m / 60)} h${m % 60 ? ` ${m % 60} min` : ''}`}`;
+  };
+  /** A sign-in: the service, what it unlocks, who waits, the time left and one Open for its link. Its poster closes it with signin done. */
+  function signin(d, lead, saved, err) {
+    if (d.start) return started(d, lead, saved, err);
+    const gone = !!d.expires && Date.parse(d.expires) <= Date.now();
+    const open = saved ? '' : gone ? el('button', { class: 'open-link', disabled: '' }, 'Open')
+      : el('a', { class: 'open-link', href: d.link, target: '_blank', rel: 'noopener noreferrer', 'aria-label': `Open the ${d.title} sign-in` }, 'Open');
+    // The time left counts down on the page (data-expires); an expired link is drawn once more, with Open off.
+    const left = saved ? el('p', { class: 'meta' }, `Signed in at ${when(saved.at)}.`) : d.expires
+      ? el('p', { class: gone ? 'expiry gone' : 'expiry', ...(!gone && { 'data-expires': d.expires }) }, expiry(d.expires)) : '';
+    return el('article', { class: 'row signin', id: `item-${d.key}` }, el('div', {}, lead,
+      el('p', { class: 'line', dir: 'auto' }, `Unlocks: ${d.unlocks}`), el('p', { class: 'line', dir: 'auto' }, `Waits: ${d.waits}`), left), open, err);
+  }
+  /** What a tap-time sign-in did last, in plain words. */
+  const RUNS = { none: 'Each tap gets a new link.', starting: 'Getting a new link…', live: 'The sign-in page is open. Finish it there.' };
+  /** A sign-in whose link this host makes at each tap: Open starts it and sends a new tab to the new link, so its link never expires on the card. */
+  function started(d, lead, saved, err) {
+    const failed = d.run?.startsWith('failed: ') && d.run.slice(8);
+    const open = saved ? '' : FROZEN || state.readonly ? el('button', { class: 'open-link', disabled: '' }, 'Open')
+      : el('button', { class: 'open-link', 'aria-label': `Open the ${d.title} sign-in` }, 'Open');
+    if (open && !open.disabled) open.onclick = async () => {
+      // The tab opens on the tap itself, so a browser does not block it; it goes to the link once this host has made one.
+      const tab = window.open('', '_blank');
+      if (tab) tab.opener = null;
+      open.disabled = true;
+      open.textContent = 'Getting a new link…';
+      try {
+        const res = await fetch('/api/signin', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: d.key }) });
+        const body = await res.json().catch(() => ({ error: `The server replied ${res.status}` }));
+        if (body.state) state = body.state;
+        if (!res.ok) throw new Error(body.error);
+        if (!body.open) tab?.close();
+        else if (tab) tab.location.href = body.open;
+        else location.href = body.open;
+        render();
+      } catch (e) {
+        tab?.close();
+        render();
+        shown(err).textContent = `The sign-in did not start: ${e.message}`;
+      }
+    };
+    const line = saved ? `Signed in at ${when(saved.at)}.` : failed ? `The last try failed: ${failed} Tap Open to try again.` : RUNS[d.run] ?? RUNS.none;
+    return el('article', { class: 'row signin', id: `item-${d.key}` }, el('div', {}, lead,
+      el('p', { class: 'line', dir: 'auto' }, `Unlocks: ${d.unlocks}`), el('p', { class: 'line', dir: 'auto' }, `Waits: ${d.waits}`),
+      el('p', { class: failed ? 'expiry gone' : saved ? 'meta' : 'expiry' }, line)), open, err);
+  }
+  setInterval(() => {
+    // While a sign-in runs on this host, the page checks often, so the card closes soon after the sign-in is done.
+    if (!FROZEN && state.decisions.some((d) => d.run === 'live' || d.run === 'starting')) refresh();
+    for (const p of document.querySelectorAll('[data-expires]')) {
+      if (Date.parse(p.dataset.expires) <= Date.now()) return render();
+      p.textContent = expiry(p.dataset.expires);
+    }
+  }, 5000);
+
   /** Boxes the person unfolded, kept open across redraws. */
   const unfolded = new Set();
   /** The one place to type on a card, folded behind Other answer so the buttons come first and typing is the last resort.
@@ -744,7 +809,7 @@
   /** Each item lives in one area: answered items, then the area the item names, then evidence updates, then what is only to read (explainers, pages with nothing to answer), then the open asks. */
   const area = (d) => {
     const a = isAnswered(d) ? 'answered' : d.area ?? (d.type === 'evidence' ? 'evidence'
-      : state.readonly || d.type === 'explainer' || !(d.options.length || d.reply) ? 'reports' : 'waiting');
+      : state.readonly || d.type === 'explainer' || !(d.options.length || d.reply || d.type === 'signin') ? '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;
   };
@@ -795,7 +860,7 @@
   }
 
   /** A short row's second line: what changed, unless the headline already says it. */
-  const sub = (d) => (d.about && d.about !== headline(d) ? d.about : NAMES[d.type] ?? d.type);
+  const sub = (d) => (d.type === 'signin' ? `Unlocks: ${d.unlocks}` : d.about && d.about !== headline(d) ? d.about : NAMES[d.type] ?? d.type);
   /** A short row: a picture (or the area's mark) and the title; an answered item has its answer and time under the title. */
   const compact = (d, a) => {
     const s = state.answers[d.key];
@@ -963,6 +1028,8 @@
     const gone = new Set(state.dismissed ?? []);
     for (const d of [...state.decisions].reverse()) if (!gone.has(d.key)) by[area(d)].push(d);
     by.waiting.reverse();
+    // A sign-in blocks someone now, so sign-ins come first.
+    by.waiting.sort((x, y) => (y.type === 'signin') - (x.type === 'signin'));
     const hidden = state.decisions.filter((d) => gone.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) ?? [];
@@ -1051,7 +1118,7 @@
     banner.textContent = `Can't read the board file: ${e.message}`;
     banner.hidden = false;
   };
-  // Another program rewrites a read-only or answers-only board's file, so the page checks it every 20 seconds and redraws only on a change.
+  // Another program can change the board file (a feed, a new sign-in, signin done), so the page checks it every 20 seconds and redraws only on a change.
   async function refresh() {
     try {
       const res = await fetch('/api/decisions'), body = await res.json().catch(() => ({ error: `The server replied ${res.status}` }));
@@ -1069,7 +1136,7 @@
   if (FROZEN) (state = FROZEN), render();
   else call('/api/decisions').then(() => {
     banner.hidden = true;
-    if (state.readonly || state.answers_only) setInterval(refresh, 20_000);
+    setInterval(refresh, 20_000);
   }, failed);
 </script>
 </body>

package/web/report-preview.svg

@@ -15,4 +15,5 @@
   <path class="tip" d="M346 166L370 180L346 194z"/>
   <rect class="after" x="380" y="110" width="220" height="140" rx="20"/>
   <text class="on-after" x="490" y="188" text-anchor="middle" font-size="26" font-weight="600">FILL: after</text>
+  <text class="label" x="320" y="300" text-anchor="middle" font-size="22" font-weight="500">FILL: as of the date, e.g. As of 15 Oct</text>
 </svg>

package/web/report.html

@@ -24,6 +24,7 @@
   h2 { font-size: 0.8125rem; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin: 0; }
   p { margin: 0; }
   .lead { font-size: 1.125rem; }
+  .asof { font-size: 0.9375rem; color: var(--muted); }
   svg { width: 100%; height: auto; display: block; }
   svg text { fill: var(--text); font: 600 15px system-ui, sans-serif; }
   .box { fill: var(--accent-soft); stroke: var(--accent); stroke-width: 2; }
@@ -58,6 +59,7 @@
     <h2>The answer</h2>
     <h1 id="answer">FILL: the answer in one plain sentence</h1>
     <p class="lead">FILL: one or two short lines on why it matters to the reader.</p>
+    <p class="asof">As of FILL: the date the facts were true, e.g. 15 Oct. Name a real date, never today or now.</p>
     <svg viewBox="0 0 340 120" role="img" aria-label="FILL: what the picture shows">
       <defs><marker id="tip" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z"/></marker></defs>
       <rect class="box" x="4" y="24" width="130" height="72" rx="12"/>