create-pmos 0.522.0 → 0.524.0

package/workspace/lib/idle-lab.js

@@ -0,0 +1,275 @@
+'use strict';
+/* idle-lab.js — what the PM sees of the idle lab (build U of the idle-lab B+C direction, 2026-11-04; canvas main, In development I1 IlBC,
+ * I2 IlB, I3 IlCompare; brief /mnt/project-files/idle-lab/brief.md). The engine (build E) runs the jobs; this file is what they file and
+ * what the screens read. Nothing here runs a model.
+ *
+ * TWO PLACES A RESULT WAITS (B + C):
+ *   on its initiative   a ✦ under the initiative's one blue ✦ (lib/proposals.js), one of three groups, always section 'check' (its own ✓):
+ *     prototyped   "Claude prototyped it": round 1, 2–3 divergent specimens. data { round: 1, specimens: [{ key, title, caption, file }], checked }
+ *     improved     "Claude improved it": a new round of one specimen. data { round, of: <the prototyped proposal id>, base: <specimen key>,
+ *                  changed: what changed (usually one thing), file, checked }
+ *     scanned      "Claude scanned for it": a finding to attach as evidence. why is the finding; sources are the pages read.
+ *                  data { pages: n, refreshed?: 'from the 18 Oct scan, 2 things new since' }
+ *     ✓ keeps it as the initiative's own document (a `doc` write, kind prototype or evidence: lib/routes-proposals.js). ✕ drops it (an
+ *     optional reason rides on the drop line, for the engine to learn from). Undo gives it back. Every specimen is a file under
+ *     <runtime>/idle-lab/specimens/; nothing is written to a product repo before ✓.
+ *   in Intelligence › Lab only the ✦ that fit no initiative, in <state>/idle-lab.jsonl (THE ONE WRITER and THE ONE FOLD of that file):
+ *     start   start an initiative from a scan finding. data { title, board, anchor, stage? }   ✓ starts it through the Board (Add an ask, Accept)
+ *     scan    a finding worth knowing that no initiative holds yet. ✓ keeps it (writes nothing else)
+ *
+ * THE LAB LEDGER, <state>/idle-lab.jsonl, one line per event { at, by, kind, ... }:
+ *   propose  { id, type: 'start' | 'scan', title, why, sources: [{ label, ref }], data }   the last line for an id wins
+ *   drop     { id, batch, why? }   ✕, with the PM's reason when given; an undo of its batch gives it back
+ *   keep     { id, batch, wrote }  ✓, with what it wrote (op create: the initiative started)
+ *   undo     { batch }
+ *   run      { job, ms?, n? }      one idle stretch the engine used: its job, the idle time it took and how many results it filed
+ *   next     { items: [{ kind, title, why }] }   what the engine will do the next time the PM steps away (the newest line wins; read only)
+ *
+ * PROVEN (proven-only rule, Wawan 2026-11-01): the compare view's Production and Design columns stay left out, with one line why, until the
+ * engine has shown on the PM's Mac that it can render production from the product repo and read the design (Figma or a canvas). The engine
+ * flips these when that is proven; until then no pin against them is drawn.
+ *
+ *   PROVEN · GROUPS · TITLES · specimenDir(runtimeDir) · specimenPath(runtimeDir, file) → absolute path | null (never outside the folder)
+ *   result(group, input)             → { prop } | { error }   what the engine files on an initiative (lib/proposals.js propose line)
+ *   loose(type, input)               → { prop } | { error }   what the engine files in the Lab
+ *   ledgerFile(dir) · readLines(file) · read(dir) → fold · append(dir, actor, line)
+ *   fold(lines)                      PURE → { props, drops, kept, undone, runs, next, t }
+ *   looseOpen(F)                     PURE → the open Lab ✦, newest first
+ *   labOf({ P, L, extra, now, titleOf }) PURE → the Lab section: { say, loose, record, kept, next } or null (zero is silence)
+ *   compareOf(P, id, { key, titleOf, proven }) PURE → the compare view: { title, round, say, columns, pins, history } | null */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const LEDGER = 'idle-lab.jsonl';
+const KINDS = new Set(['propose', 'drop', 'keep', 'undo', 'run', 'next']);
+const GROUPS = Object.freeze(['prototyped', 'improved', 'scanned']);
+const TITLES = Object.freeze({ prototyped: 'Claude prototyped it', improved: 'Claude improved it', scanned: 'Claude scanned for it' });
+const LOOSE = Object.freeze(['start', 'scan']);
+const PROVEN = Object.freeze({ production: false, design: false });
+const WEEK = 7 * 864e5;
+const LIM = { title: 140, why: 300, label: 80, ref: 500, caption: 120, file: 200, changed: 200, checked: 200 };
+const FILE_RE = /^[A-Za-z0-9][\w.-]*(\/[A-Za-z0-9][\w.-]*)*\.html$/;
+const KEY_RE = /^[A-Z]$/;
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/;
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' ? v : '');
+const one = (v, n) => String(v == null ? '' : v).replace(/\s+/g, ' ').trim().slice(0, n);
+const hash = (s) => crypto.createHash('sha1').update(String(s)).digest('hex').slice(0, 10);
+const plural = (n, a, b) => n + ' ' + (n === 1 ? a : b);
+
+/* ── the specimens ── */
+const specimenDir = (rt) => (rt ? path.join(rt, 'idle-lab', 'specimens') : null);
+/** The absolute path of a specimen file, or null when the name is not a plain relative .html name inside the folder. */
+function specimenPath(rt, file) {
+  const d = specimenDir(rt), f = str(file);
+  if (!d || !FILE_RE.test(f) || f.split('/').some((s) => s === '..' || s === '.')) return null;
+  const abs = path.resolve(d, f);
+  return abs.startsWith(path.resolve(d) + path.sep) ? abs : null;
+}
+const specimenUrl = (file) => '/api/lab/specimen?file=' + encodeURIComponent(file);
+
+/* ── what the engine files ── */
+function srcList(v, min) {
+  if (!Array.isArray(v) || v.length < min || v.length > 8) return { error: `sources is a list of ${min} to 8 { label, ref }: a claim without a pointer is not a result` };
+  const out = [];
+  for (const s of v) {
+    if (!isObj(s) || !str(s.label).trim()) return { error: 'each source has a label (and a ref: a link, a path or a meeting note)' };
+    out.push({ label: one(s.label, LIM.label), ...(str(s.ref) ? { ref: one(s.ref, LIM.ref) } : {}) });
+  }
+  return { v: out };
+}
+/** → { prop } | { error }. The engine has already proven it (a specimen opens and renders; a scan cites the pages it read). */
+function result(group, input) {
+  if (!GROUPS.includes(group)) return { error: 'group is one of ' + GROUPS.join(', ') };
+  if (!isObj(input)) return { error: 'the result is a JSON object' };
+  const why = one(input.why, LIM.why);
+  if (!why) return { error: 'why is one line: what Claude did and from what' };
+  const s = srcList(input.sources, 1); if (s.error) return s;
+  const data = {};
+  if (group === 'prototyped') {
+    const sp = Array.isArray(input.specimens) ? input.specimens : [];
+    if (sp.length < 2 || sp.length > 3) return { error: 'a first round has 2 or 3 different specimens' };
+    data.round = 1;
+    data.specimens = [];
+    for (const x of sp) {
+      if (!isObj(x) || !KEY_RE.test(str(x.key)) || !one(x.title, LIM.title) || !FILE_RE.test(str(x.file))) return { error: 'each specimen is { key: A–Z, title, caption, file: a .html name in the specimen folder }' };
+      data.specimens.push({ key: x.key, title: one(x.title, LIM.title), caption: one(x.caption, LIM.caption), file: x.file });
+    }
+    if (new Set(data.specimens.map((x) => x.key)).size !== data.specimens.length) return { error: 'each specimen has its own key' };
+  } else if (group === 'improved') {
+    if (!ID_RE.test(str(input.of))) return { error: 'of is the id of the prototyped proposal this round improves' };
+    if (!KEY_RE.test(str(input.base))) return { error: 'base is the key of the specimen this round improves' };
+    const round = Number(input.round);
+    if (!Number.isInteger(round) || round < 2 || round > 20) return { error: 'round is 2 or more' };
+    const changed = one(input.changed, LIM.changed);
+    if (!changed) return { error: 'changed says what changed since the last round, usually one thing' };
+    if (!FILE_RE.test(str(input.file))) return { error: 'file is a .html name in the specimen folder' };
+    Object.assign(data, { round, of: input.of, base: input.base, changed, file: input.file });
+  } else {
+    const pages = Number(input.pages);
+    data.pages = Number.isInteger(pages) && pages > 0 ? pages : s.v.length;
+    if (str(input.refreshed)) data.refreshed = one(input.refreshed, LIM.checked);
+  }
+  if (group !== 'scanned') {
+    const checked = one(input.checked, LIM.checked);
+    if (!checked) return { error: 'checked says how Claude proved it (for example: all three open and render in the Viewer)' };
+    data.checked = checked;
+  }
+  if (isObj(input.compare)) data.compare = compareData(input.compare);
+  return { prop: { group, type: group === 'improved' ? 'round' : group === 'prototyped' ? 'new' : 'finding', section: 'check', title: one(input.title, LIM.title) || null, why, sources: s.v, items: [], data } };
+}
+/** What the engine read for the compare view. Kept as filed; compareOf decides what shows. */
+function compareData(c) {
+  const col = (x) => (isObj(x) && FILE_RE.test(str(x.file)) ? { file: x.file, read: one(x.read, LIM.checked) } : null);
+  const pins = (Array.isArray(c.pins) ? c.pins : []).filter((p) => isObj(p) && ['production', 'design'].includes(p.vs) && one(p.text, LIM.why))
+    .slice(0, 6).map((p) => ({ vs: p.vs, text: one(p.text, LIM.why) }));
+  return { production: col(c.production), design: col(c.design), pins };
+}
+/** → { prop } | { error }. A Lab ✦ that fits no initiative. */
+function loose(type, input) {
+  if (!LOOSE.includes(type)) return { error: 'type is one of ' + LOOSE.join(', ') };
+  if (!isObj(input)) return { error: 'the result is a JSON object' };
+  const title = one(input.title, LIM.title), why = one(input.why, LIM.why);
+  if (!title || !why) return { error: 'title and why are each one short line' };
+  const s = srcList(input.sources, 1); if (s.error) return s;
+  const d = isObj(input.data) ? input.data : {}, data = {};
+  if (type === 'start') {
+    if (!one(d.title, LIM.title) || !ID_RE.test(str(d.board)) || !one(d.anchor, 80)) return { error: 'start needs data { title, board, anchor }: the new initiative, its board and what it counts toward' };
+    Object.assign(data, { title: one(d.title, LIM.title), board: d.board, anchor: one(d.anchor, 80), ...(str(d.stage) ? { stage: one(d.stage, 40) } : {}) });
+  }
+  if (str(d.refreshed)) data.refreshed = one(d.refreshed, LIM.checked);
+  const id = ID_RE.test(str(input.id)) ? input.id : 'lab-' + hash([type, title].join('|'));
+  return { prop: { id, type, title, why, sources: s.v, data } };
+}
+
+/* ── the Lab ledger ── */
+const ledgerFile = (dir) => (dir ? path.join(dir, LEDGER) : null);
+function readLines(file) {
+  if (!file) return [];
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const raw of text.split('\n')) { if (!raw.trim()) continue; try { const l = JSON.parse(raw); if (isObj(l) && KINDS.has(l.kind)) out.push(l); } catch { /* a torn line is skipped */ } }
+  return out;
+}
+const read = (dir) => fold(readLines(ledgerFile(dir)));
+function append(dir, actor, ev) {
+  const line = { at: new Date().toISOString(), by: (actor && actor.by) || null, ...ev };
+  fs.appendFileSync(ledgerFile(dir), JSON.stringify(line) + '\n');
+  return line;
+}
+function fold(lines) {
+  const props = new Map(), drops = new Map(), kept = [], undone = new Set(), runs = [], dropBatch = new Map();
+  let next = null, t = '';
+  for (const l of lines || []) {
+    if (!isObj(l) || !KINDS.has(l.kind)) continue;
+    if (l.at && String(l.at) > t) t = String(l.at);
+    if (l.kind === 'propose' && ID_RE.test(str(l.id)) && LOOSE.includes(l.type)) { props.set(l.id, { id: l.id, type: l.type, title: str(l.title), why: str(l.why), sources: Array.isArray(l.sources) ? l.sources : [], data: isObj(l.data) ? l.data : {}, at: str(l.at) }); drops.delete(l.id); }
+    else if (l.kind === 'drop' && str(l.id)) { drops.set(l.id, { why: one(l.why, LIM.why), at: str(l.at) }); if (str(l.batch)) dropBatch.set(l.batch, l.id); }
+    else if (l.kind === 'keep' && str(l.batch) && str(l.id)) kept.push({ id: l.id, batch: l.batch, wrote: Array.isArray(l.wrote) ? l.wrote.filter(isObj) : [], at: str(l.at) });
+    else if (l.kind === 'undo' && str(l.batch)) { undone.add(l.batch); if (dropBatch.has(l.batch)) drops.delete(dropBatch.get(l.batch)); }
+    else if (l.kind === 'run') runs.push({ job: one(l.job, 40), ms: Number(l.ms) > 0 ? Number(l.ms) : 0, n: Number(l.n) > 0 ? Number(l.n) : 0, at: str(l.at) });
+    else if (l.kind === 'next') next = { items: (Array.isArray(l.items) ? l.items : []).filter(isObj).slice(0, 3).map((x) => ({ kind: one(x.kind, 20), title: one(x.title, LIM.title), why: one(x.why, LIM.why) })).filter((x) => x.title), at: str(l.at) };
+  }
+  return { props, drops, kept, undone, runs, next, t };
+}
+const keptOf = (F) => { const m = new Map(); for (const k of F.kept) if (!F.undone.has(k.batch)) m.set(k.id, k); return m; };
+/** The open Lab ✦, newest first. */
+function looseOpen(F) {
+  const kept = keptOf(F);
+  return [...F.props.values()].filter((p) => !kept.has(p.id) && !F.drops.has(p.id)).sort((a, b) => String(b.at).localeCompare(String(a.at)));
+}
+
+/* ── the Lab section (I1) ── */
+const fmtMs = (ms) => { const m = Math.round(ms / 6e4); return m < 60 ? m + ' m' : Math.floor(m / 60) + ' h' + (m % 60 ? ' ' + (m % 60) + ' m' : ''); };
+/**
+ * PURE. The Lab section: the ✦ that fit no initiative, the week's record of every background job (links only), the keep rate and what comes
+ * next. null when nothing ran this week and nothing waits (zero is silence; it is also how the Lab first appears only once there is something).
+ *   P        lib/proposals.js fold of this product (the idle-lab groups on its initiatives)
+ *   L        this file's fold
+ *   extra    [{ job, title, meta?, at, ini?, board? }]: what other background jobs did this week (grill runs, AI jobs, the shared queue)
+ *   titleOf  (ini) → the initiative's name, or ''
+ */
+function labOf({ P, L, extra = [], now = Date.now(), titleOf = () => '' } = {}) {
+  L = L || fold([]);
+  const since = now - WEEK, inWeek = (at) => (Date.parse(at) || 0) >= since;
+  const keptP = new Set(); if (P) for (const k of P.kept) if (!P.undone.has(k.batch)) for (const id of k.ids) keptP.add(id);
+  const record = [], tally = { proto: [0, 0], scan: [0, 0] };
+  const PRsig = (() => { try { return require('./proposals.js').sigOf; } catch { return null; } })();
+  for (const p of P ? P.props.values() : []) {
+    if (!GROUPS.includes(p.group) || !inWeek(p.at)) continue;
+    const state = keptP.has(p.id) ? 'kept' : PRsig && P.drops.has(PRsig(p)) ? 'dropped' : 'open';
+    const t = p.group === 'scanned' ? tally.scan : tally.proto;
+    t[1]++; if (state === 'kept') t[0]++;
+    const name = titleOf(p.ini) || p.ini, d = p.data || {};
+    record.push({ kind: p.group, id: p.id, ini: p.ini, board: p.board || '', at: p.at, state, why: state === 'dropped' ? dropWhy(P, PRsig(p)) : '',
+      title: p.group === 'prototyped' ? plural((d.specimens || []).length, 'prototype', 'prototypes') + ' · ' + name : p.group === 'improved' ? 'Round ' + d.round + ' · ' + name : 'Scan · ' + name,
+      meta: p.group === 'prototyped' ? 'round 1 · ' + (d.checked || '') : p.group === 'improved' ? d.changed || '' : plural(d.pages || (p.sources || []).length, 'page', 'pages') + ' read',
+      compare: p.group !== 'scanned' });
+  }
+  const keptL = keptOf(L), open = looseOpen(L);
+  for (const p of L.props.values()) {
+    if (!inWeek(p.at)) continue;
+    const state = keptL.has(p.id) ? 'kept' : L.drops.has(p.id) ? 'dropped' : 'open';
+    tally.scan[1]++; if (state === 'kept') tally.scan[0]++;
+    record.push({ kind: 'loose', id: p.id, at: p.at, state, why: state === 'dropped' ? (L.drops.get(p.id).why || '') : '', title: 'Scan · ' + p.title, meta: plural((p.sources || []).length, 'page', 'pages') + ' read' });
+  }
+  for (const x of extra || []) if (x && inWeek(x.at) && one(x.title, LIM.title)) record.push({ kind: 'job', job: one(x.job, 40), at: x.at, state: 'done', title: one(x.title, LIM.title), meta: one(x.meta, LIM.why), ...(x.ini ? { ini: x.ini, board: x.board || '' } : {}) });
+  record.sort((a, b) => String(b.at).localeCompare(String(a.at)));
+  const next = L.next && L.next.items.length ? L.next.items : [];
+  if (!record.length && !open.length && !next.length) return null;
+  const filed = tally.proto[1] + tally.scan[1], kept = tally.proto[0] + tally.scan[0];
+  const idle = L.runs.filter((r) => inWeek(r.at)).reduce((s, r) => s + r.ms, 0);
+  const say = [idle ? 'This week I used ' + fmtMs(idle) + ' of your idle time.' : '', filed ? 'You kept ' + kept + ' of ' + filed + '.' : '',
+    open.length ? plural(open.length, 'finding fits', 'findings fit') + ' no initiative yet.' : ''].filter(Boolean).join(' ');
+  return { say, loose: open.map((p) => ({ id: p.id, type: p.type, title: p.title, why: p.why, sources: p.sources, data: p.data, at: p.at })),
+    record: record.slice(0, 12), more: Math.max(0, record.length - 12),
+    kept: filed ? { kept, filed, proto: tally.proto, scan: tally.scan } : null, next };
+}
+function dropWhy(P, sig) {
+  // the reason rides on the drop line (lib/routes-proposals.js keeps body.why); the fold keeps only the signature, so read it back here
+  return (P && P.dropWhy && P.dropWhy.get(sig)) || '';
+}
+
+/* ── the compare view (I3) ── */
+/**
+ * PURE. One prototype in the compare view: production (from the product repo's main), the design, the prototype round shown, and History.
+ * A column with no proven source is left out with one line why; a pin against a left-out column is not drawn.
+ *   P     lib/proposals.js fold;  id: a prototyped or improved proposal id;  key: the specimen to show (a first round), default the first
+ * → { ini, board, id, sig, state: open | kept | dropped, title, round, key, say, columns: [{ id, title, meta, file?, read?, left? }], pins: [{ n, vs, text }], history: [{ id, round, at, state, meta, current }] } | null
+ */
+function compareOf(P, id, { key = '', titleOf = () => '', proven = PROVEN } = {}) {
+  if (!P) return null;
+  const p = P.props.get(id);
+  if (!p || (p.group !== 'prototyped' && p.group !== 'improved')) return null;
+  const root = p.group === 'prototyped' ? p : P.props.get(p.data && p.data.of);
+  const keptP = new Set(); for (const k of P.kept) if (!P.undone.has(k.batch)) for (const x of k.ids) keptP.add(x);
+  const PRsig = require('./proposals.js').sigOf;
+  const stateOf = (x) => (keptP.has(x.id) ? 'kept' : P.drops.has(PRsig(x)) ? 'dropped' : 'open');
+  const rounds = [...P.props.values()].filter((x) => x.group === 'improved' && x.ini === p.ini && root && x.data && x.data.of === root.id).sort((a, b) => a.data.round - b.data.round);
+  const specs = root ? root.data.specimens || [] : [];
+  const k = p.group === 'improved' ? p.data.base : (specs.find((s) => s.key === key) || specs[0] || {}).key || '';
+  const spec = specs.find((s) => s.key === k) || null;
+  const file = p.group === 'improved' ? p.data.file : spec && spec.file;
+  if (!file) return null;
+  const round = p.group === 'improved' ? p.data.round : 1;
+  const c = (p.data && p.data.compare) || {};
+  const cols = [];
+  cols.push(proven.production && c.production ? { id: 'production', title: 'Production', meta: 'main, today', file: c.production.file, read: c.production.read }
+    : { id: 'production', title: 'Production', left: 'Left out: Claude cannot render production from the product repo yet. It shows here once that is proven.' });
+  cols.push(proven.design && c.design ? { id: 'design', title: 'Design', meta: 'the design for this screen', file: c.design.file, read: c.design.read }
+    : { id: 'design', title: 'Design', left: 'Left out: Claude cannot read the design from Figma or a canvas yet. It shows here once that is proven.' });
+  cols.push({ id: 'prototype', title: 'Prototype', meta: 'round ' + round + (spec ? ' · ' + spec.key : ''), file, read: (p.data && p.data.checked) || '' });
+  const shown = new Set(cols.filter((x) => !x.left).map((x) => x.id));
+  const pins = (c.pins || []).filter((x) => shown.has(x.vs)).map((x, i) => ({ n: i + 1, vs: x.vs, text: x.text }));
+  const history = [];
+  for (const r of rounds.slice().reverse()) history.push({ id: r.id, round: r.data.round, at: r.at, state: stateOf(r), meta: r.data.changed || '', current: r.id === p.id });
+  if (root) history.push({ id: root.id, round: 1, at: root.at, state: stateOf(root), meta: specs.map((s) => s.key).join(', ') + (specs.length ? ': ' : '') + specs.map((s) => s.title).join(' · '), current: root.id === p.id, keys: specs.map((s) => ({ key: s.key, title: s.title })) });
+  const name = titleOf(p.ini) || p.ini;
+  const say = p.group === 'improved' ? 'Round ' + round + ' of ' + k + ': ' + p.data.changed : (spec ? spec.title + (spec.caption ? ': ' + spec.caption : '') : '');
+  return { ini: p.ini, board: p.board || '', id: p.id, sig: PRsig(p), state: stateOf(p), title: name, round, key: k, say, columns: cols, pins, history };
+}
+
+module.exports = { LEDGER, GROUPS, TITLES, LOOSE, PROVEN, specimenDir, specimenPath, specimenUrl, result, loose, ledgerFile, readLines, read, append, fold, looseOpen, labOf, compareOf, fmtMs };

package/workspace/lib/moments.js

@@ -0,0 +1,241 @@
+'use strict';
+/* moments.js — a feature appears when its moment comes (onboarding build B3, design ObA4Gradual; brief
+ * /mnt/project-files/onboarding-grill/brief-B3-gradual-exposure.md). lib/routes-moments.js does the HTTP; pm/home-moment.js draws the ✦ in
+ * Home's own chat, pm/cozy-nav.js the soft dot on a place's menu row, pm/quiet-place.js the one honest line of a place that is not open yet.
+ *
+ * STATE, NOT DAYS. Each moment opens on a fact PMOS can check in the workspace's own records, never on a timer:
+ *   first    the first initiative, kept or dropped on the after-setup reveal (B2, lib/first-reveal.js); without that module, setup done and
+ *            one initiative. Recorded only: B2 draws its card.
+ *   board    3 open initiatives, or a date on a program (its target or a milestone).        place 'board'
+ *   insights an OKR file with at least one key result: a goal is kept.                       place 'insights'
+ *   reports  a week of movement: the oldest initiative record is 7 days old or more, and a record changed in the last 7 days.
+ *                                                                                            place 'reports'
+ * ONE AT A TIME. At most one moment is proposed per day, across all workspaces. It is the day's moment until the PM answers it: ✓ keeps it
+ * (the page opens the place), ✕ drops it, and a dropped moment never comes back. After an answer, the next moment waits for the next day.
+ *
+ * ONLY NEW WORKSPACES. A workspace counts as new when setup ran for it (lib/onboarding-progress.js `started`, or the project-first
+ * conversation's `done.ws`, lib/routes-onboard.js). Any other workspace was already in use before this existed: every place is open for it, it
+ * gets no ✦ and no dot, and a page is quiet only when every registered workspace is new and none has opened that place.
+ *
+ * WHERE IT LIVES. The workspace's onboarding-progress record carries { moments: { [id]: { shown, kept?, dropped? } },
+ * places: { [place]: { open, visited? } } } beside its setup steps (saveMoments keeps `started` as it was).
+ *
+ * Everything here reads files; nothing calls a model, a connector or the network. */
+const fs = require('fs');
+const path = require('path');
+const progress = require('./onboarding-progress');
+
+const WEEK = 7 * 86400000;
+const PLACES = ['board', 'insights', 'reports'];
+/** The moments in the order they are proposed. `place` is where ✓ goes; `guide` the guide page linked inline. */
+const MOMENTS = [
+  { id: 'first', place: null, record: true },
+  { id: 'board', place: 'board', href: '/premium-board.html', guide: 'programs', guideLabel: 'How the Board works', go: 'Open the Board' },
+  { id: 'insights', place: 'insights', href: '/premium-intelligence.html', guide: 'intelligence-okr-goals', guideLabel: 'How Intelligence works', go: 'Open Intelligence' },
+  { id: 'reports', place: 'reports', href: '/premium-intelligence.html?tab=library', guide: 'reports', guideLabel: 'How reports work', go: 'Open reports' },
+];
+/** The one honest line a place shows before its moment comes. */
+const QUIET = {
+  board: 'The Board starts at three initiatives, or a date.',
+  insights: 'Intelligence starts when you keep a goal.',
+  reports: 'The first report comes after a week of movement.',
+};
+
+const INITIATIVE_DIRS = [['pmos', 'state', 'initiatives'], ['planning', 'initiatives'], ['pmos', 'planning', 'initiatives']];
+const ls = (d) => { try { return fs.readdirSync(d); } catch { return []; } };
+const fmOf = (text) => {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text || '');
+  const out = {};
+  if (m) for (const l of m[1].split(/\r?\n/)) { const x = /^([a-z_]+):\s*(.*)$/.exec(l); if (x) out[x[1]] = x[2].replace(/^["']|["']$/g, '').trim(); }
+  return out;
+};
+const readLines = (f) => { try { return fs.readFileSync(f, 'utf8').split('\n').filter((l) => l.trim()).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); } catch { return []; } };
+const DATE = /^\d{4}-\d{2}-\d{2}/;
+
+/** The initiative record folders of a workspace: the repository's, and its state folder's (a kit install). */
+function dirsOf(ctx, w) {
+  const dirs = INITIATIVE_DIRS.map((d) => path.join(w.root, ...d));
+  try { const s = ctx.stateDirFor && ctx.stateDirFor(w); if (s) dirs.push(path.join(s, 'initiatives')); } catch { /* no state folder */ }
+  return [...new Set(dirs.map((d) => path.resolve(d)))];
+}
+function stateDirsOf(ctx, w) {
+  const dirs = [path.join(w.root, 'pmos', 'state')];
+  try { const s = ctx.stateDirFor && ctx.stateDirFor(w); if (s) dirs.push(s); } catch { /* none */ }
+  return [...new Set(dirs.map((d) => path.resolve(d)))];
+}
+
+/** What a workspace's records say, read from files. → { initiatives, dated, goal, goalTitle, week } */
+function facts(ctx, w, now = Date.now()) {
+  // open initiatives: a record that is not a README or template, not stopped by its last lifecycle line (D70)
+  const stopped = new Map();
+  for (const f of [path.join(w.root, 'planning', 'runs', 'lifecycle.jsonl'), path.join(w.root, 'pmos', 'planning', 'runs', 'lifecycle.jsonl')]) {
+    for (const e of readLines(f)) if (e.initiative_id) stopped.set(e.initiative_id, e.state);
+  }
+  const ids = new Set(); let oldest = Infinity, newest = 0;
+  for (const d of dirsOf(ctx, w)) {
+    for (const n of ls(d)) {
+      if (!n.endsWith('.md') || /^(README|index|log)\.md$/i.test(n) || /template/i.test(n)) continue;
+      const f = path.join(d, n);
+      let text = '', st = null;
+      try { text = fs.readFileSync(f, 'utf8'); st = fs.statSync(f); } catch { continue; }
+      const id = fmOf(text).id || n.replace(/\.md$/, '');
+      const state = stopped.get(id);
+      if (state && state !== 'active') continue;
+      ids.add(id);
+      oldest = Math.min(oldest, st.mtimeMs); newest = Math.max(newest, st.mtimeMs);
+    }
+  }
+  // a date on a program: its target, or a milestone's date (lib/programs.js; <state>/programs.jsonl)
+  let dated = false;
+  for (const s of stateDirsOf(ctx, w)) {
+    for (const l of readLines(path.join(s, 'programs.jsonl'))) {
+      if (l.kind !== 'program') continue;
+      if (DATE.test(String(l.target || '')) || (Array.isArray(l.milestones) && l.milestones.some((m) => m && DATE.test(String(m.date || ''))))) dated = true;
+    }
+    for (const n of ls(s)) { if (!/\.jsonl$/.test(n)) continue; try { newest = Math.max(newest, fs.statSync(path.join(s, n)).mtimeMs); } catch { /* gone */ } }
+  }
+  // a goal kept: an OKR file with an objective that has a key result (lib/okr-goals.js)
+  let goal = false, goalTitle = '';
+  try { const r = require('./okr-goals.js').read(w.root); if (r.ok && r.objectives.length) { goal = true; goalTitle = String(r.objectives[0].title || '').slice(0, 120); } } catch { /* unreadable: no goal */ }
+  const week = ids.size > 0 && Number.isFinite(oldest) && oldest <= now - WEEK && newest >= now - WEEK;
+  return { initiatives: ids.size, dated, goal, goalTitle, week };
+}
+
+/** Which places the facts open. */
+function openOf(F) { return { board: F.initiatives >= 3 || F.dated, insights: !!F.goal, reports: !!F.week }; }
+
+/** Whether setup ran for this workspace. */
+function isNew(ctx, w) {
+  try { if (progress.read(ctx.runtimeDir, w.id).started) return true; } catch { /* no record */ }
+  try {
+    const st = JSON.parse(fs.readFileSync(path.join(ctx.runtimeDir, 'onboarding', 'project.json'), 'utf8'));
+    return !!(st && st.done && st.done.ws === w.id);
+  } catch { return false; }
+}
+
+const dayOf = (now) => { const d = new Date(now); return d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0'); };
+
+/** Whether moment m is due for a workspace with facts F and setup record P. */
+function due(m, F, P, open) {
+  if (m.id === 'first') return !!P.completed && F.initiatives >= 1;
+  return !!open[m.place];
+}
+
+/** The words of a moment's ✦, from the facts that opened it. */
+function wordsOf(m, F) {
+  if (m.id === 'board') {
+    return F.initiatives >= 3
+      ? { text: `${F.initiatives === 3 ? 'Three' : F.initiatives} initiatives now. See them by stage on the Board, and rank them.`, sub: 'One ranked list, in the order you set. Programs and the timeline follow once a program or a date exists.' }
+      : { text: 'A date is set now. See your initiatives on the Board, with the timeline, and rank them.', sub: 'One ranked list, in the order you set.' };
+  }
+  if (m.id === 'insights') return { text: 'You kept a goal. Intelligence reads it now: its key results and where each number comes from.', sub: F.goalTitle ? 'Goal: ' + F.goalTitle : '' };
+  if (m.id === 'reports') return { text: 'A week of movement now. The first report can be drafted from it.', sub: 'Reports and dashboards are in Intelligence, under ⋯.' };
+  return { text: '', sub: '' };
+}
+
+/**
+ * The whole view, and the writes it implies. Pure over its inputs: `rows` is one entry per workspace
+ * { w, isNew, facts, progress, reveal? }. → { moment, places, writes }
+ *   moment  the day's ✦ or null: { id, ws, product, text, sub, href, guide, guideLabel, go }
+ *   places  { [place]: { quiet, dot, line } }
+ *   writes  [{ ws, moments?, places? }] what to save (the first moment recorded, a place that opened)
+ */
+function view(rows, now = Date.now()) {
+  const today = dayOf(now);
+  const fresh = rows.filter((r) => r.isNew);
+  const writes = [];
+  const places = {};
+  for (const p of PLACES) {
+    const open = rows.some((r) => !r.isNew || openOf(r.facts)[p]);
+    places[p] = { quiet: rows.length > 0 && !open, dot: false, line: QUIET[p] };
+  }
+  let answeredToday = false, current = null;
+  for (const r of fresh) {
+    const P = r.progress || {}, M = { ...(P.moments || {}) }, PL = { ...(P.places || {}) }, open = openOf(r.facts);
+    let changed = false;
+    for (const p of PLACES) {
+      if (open[p] && !(PL[p] && PL[p].open)) { PL[p] = { open: new Date(now).toISOString() }; changed = true; }
+      if (PL[p] && PL[p].open && !PL[p].visited && !(M[p] && M[p].dropped)) places[p].dot = true;
+    }
+    // the first initiative: B2's reveal card records the PM's ✓ or ✕ (lib/first-reveal.js); before it ships, setup done + one initiative
+    const R = r.reveal;
+    if (!M.first && R && (R.kept || R.dropped)) { M.first = R.kept ? { shown: today, kept: R.kept.at || new Date(now).toISOString() } : { shown: today, dropped: (R.dropped && R.dropped.at) || new Date(now).toISOString() }; changed = true; }
+    else if (!M.first && !R && due(MOMENTS[0], r.facts, P, open)) { M.first = { shown: today, kept: new Date(now).toISOString() }; changed = true; }
+    if (changed) writes.push({ ws: r.w.id, moments: M, places: PL });
+    for (const m of MOMENTS) {
+      const s = M[m.id];
+      if (!s || m.record) continue;
+      if (s.shown === today && (s.kept || s.dropped)) answeredToday = true;
+      if (!s.kept && !s.dropped && !current) current = { m, r };
+    }
+  }
+  if (!current && !answeredToday) {
+    for (const r of fresh) {
+      const P = r.progress || {}, M = P.moments || {}, open = openOf(r.facts);
+      const m = MOMENTS.find((x) => !x.record && !M[x.id] && due(x, r.facts, P, open));
+      if (m) { current = { m, r }; break; }
+    }
+  }
+  let moment = null;
+  if (current) {
+    const { m, r } = current;
+    const W = wordsOf(m, r.facts);
+    moment = { id: m.id, ws: r.w.id, product: fresh.length > 1 ? (r.w.name || r.w.id) : '', text: W.text, sub: W.sub, href: m.href, guide: m.guide, guideLabel: m.guideLabel, go: m.go, shown: !!(r.progress && r.progress.moments && r.progress.moments[m.id]) };
+  }
+  return { moment, places, writes };
+}
+
+/** The after-setup reveal's answer on the first initiative (B2, lib/first-reveal.js read(runtimeDir, ws) → { kept } | { dropped } | null).
+ *  null while that module is not installed, or nothing was answered. */
+function revealOf(ctx, w) {
+  try { const r = require('./first-reveal.js').read(ctx.runtimeDir, w.id); return r && (r.kept || r.dropped) ? r : null; } catch { return null; }
+}
+/** The rows view() reads, from the registered workspaces. */
+function rowsOf(ctx, now = Date.now()) {
+  const list = (ctx.workspaceList ? ctx.workspaceList() : []).filter((w) => w && w.id && w.root);
+  return list.map((w) => {
+    const fresh = isNew(ctx, w);
+    return { w, isNew: fresh, facts: fresh ? facts(ctx, w, now) : null, progress: fresh ? progress.read(ctx.runtimeDir, w.id) : null, reveal: fresh ? revealOf(ctx, w) : null };
+  });
+}
+
+/** Read, save what opened, answer. → { moment, places } */
+function current(ctx, now = Date.now()) {
+  const rows = rowsOf(ctx, now);
+  const v = view(rows, now);
+  for (const x of v.writes) progress.saveMoments(ctx.runtimeDir, x.ws, { moments: x.moments, places: x.places });
+  return { moment: v.moment, places: v.places };
+}
+
+/** The PM's answer, or the card shown: shown | keep | drop. → { ok } | { ok: false, status, error } */
+function answer(ctx, verb, ws, id, now = Date.now()) {
+  const m = MOMENTS.find((x) => x.id === id && !x.record);
+  if (!m) return { ok: false, status: 400, error: 'There is no such moment.' };
+  const w = ctx.getWs && ctx.getWs(ws);
+  if (!w || w.id !== ws || !isNew(ctx, w)) return { ok: false, status: 404, error: 'That workspace has no moments.' };
+  const P = progress.read(ctx.runtimeDir, w.id), M = { ...(P.moments || {}) }, PL = { ...(P.places || {}) };
+  const s = { ...(M[id] || {}) };
+  if (s.dropped) return { ok: true };
+  if (!s.shown || verb === 'shown') s.shown = s.shown || dayOf(now);
+  const at = new Date(now).toISOString();
+  if (verb === 'keep') { s.kept = at; s.shown = dayOf(now); if (m.place && PL[m.place]) PL[m.place] = { ...PL[m.place], visited: PL[m.place].visited || at }; }
+  if (verb === 'drop') { s.dropped = at; s.shown = dayOf(now); }
+  M[id] = s;
+  progress.saveMoments(ctx.runtimeDir, w.id, { moments: M, places: PL });
+  return { ok: true };
+}
+
+/** The PM opened a place: its dot clears in every new workspace where it opened. */
+function visit(ctx, place, now = Date.now()) {
+  if (!PLACES.includes(place)) return { ok: false, status: 400, error: 'place is board, insights or reports' };
+  for (const r of rowsOf(ctx, now)) {
+    if (!r.isNew) continue;
+    const PL = { ...((r.progress && r.progress.places) || {}) };
+    if (!PL[place] || !PL[place].open || PL[place].visited) continue;
+    PL[place] = { ...PL[place], visited: new Date(now).toISOString() };
+    progress.saveMoments(ctx.runtimeDir, r.w.id, { places: PL });
+  }
+  return { ok: true };
+}
+
+module.exports = { MOMENTS, PLACES, QUIET, facts, openOf, isNew, view, rowsOf, current, answer, visit, dayOf };