create-pmos 0.131.0 → 0.133.0

package/workspace/public/pm/welcome.js

@@ -0,0 +1,283 @@
+/* pm/welcome.js — the first-run page (/welcome). One primary button per screen.
+ *
+ *   Welcome → First look → Your portfolio → Questions (only when the scan left any) → First Briefing → More sources
+ *
+ * Routes (lib/routes-onboarding.js): GET /api/onboarding/status|structure|briefing, POST /api/onboarding/scan|apply|undo.
+ * More sources uses POST /api/sources/refresh (lib/routes-sources.js): it starts the source's read-only skill as a session in
+ * the workspace with the PM's own connection. Nothing is read until the PM presses Bring in; the server calls nothing outside.
+ * Presses carry the launch nonce through pm/http.js. The page writes nothing itself; text taken from the scanned folder is
+ * untrusted, so every value goes through esc() and no quoted text from a file is shown.
+ * data-testid attributes are the browser suite's handles.
+ */
+import { pmGet, pmPost } from './http.js';
+
+const root = document.getElementById('wl-root');
+const params = new URLSearchParams(location.search);
+const S = {
+  ws: params.get('ws') || '', folder: null, added: [], step: 'welcome', busy: '', error: '', note: '',
+  look: null, structure: null, checked: {}, titles: {}, boardOf: {}, open: {}, answers: {}, skipped: {}, importId: '', briefing: [], sources: {},
+};
+const STEPS = [['welcome', 'Welcome'], ['look', 'First look'], ['portfolio', 'Your portfolio'], ['questions', 'Questions'], ['briefing', 'First Briefing'], ['sources', 'More sources']];
+/* The sources a first run can bring in. `source` is a lib/freshness.js SOURCES id with a read-only skill. Inbox and Slack
+ * have no import skill yet, so the page says so instead of offering a button that cannot work. */
+const MORE_SOURCES = [
+  { source: 'calendar', name: 'Calendar', adds: 'Your meetings today and for the next 14 days, so the Briefing can get you ready for them.' },
+  { source: 'my-work', name: 'Jira', adds: 'The Jira issues assigned to you, so My work starts with them.' },
+];
+
+const esc = (v) => String(v == null ? '' : v).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const ref = (e) => (e ? (e.line ? `${e.file}:${e.line}` : e.file) : '');
+
+/* ── model ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+const rowsOf = () => (S.structure ? S.structure.boards.flatMap((b) => b.initiatives.map((r) => ({ ...r, board: b.key }))) : []);
+const boardOfRow = (r) => S.boardOf[r.proposal_id] || r.board;
+function counts() {
+  const on = rowsOf().filter((r) => S.checked[r.proposal_id]);
+  return { n: on.length, m: new Set(on.map(boardOfRow)).size };
+}
+function adopt(structure) {
+  S.structure = structure; S.checked = {}; S.titles = {}; S.boardOf = {}; S.open = {}; S.answers = {}; S.skipped = {};
+  for (const r of rowsOf()) { S.checked[r.proposal_id] = !!r.checked; S.titles[r.proposal_id] = r.title; }
+}
+function revisions() {
+  const out = {};
+  for (const r of rowsOf()) {
+    const rev = {};
+    if (S.titles[r.proposal_id] !== r.title && String(S.titles[r.proposal_id]).trim()) rev.title = String(S.titles[r.proposal_id]).trim();
+    if (S.boardOf[r.proposal_id] && S.boardOf[r.proposal_id] !== r.board) rev.board = S.boardOf[r.proposal_id];
+    if (Object.keys(rev).length) out[r.proposal_id] = rev;
+  }
+  return out;
+}
+
+/* ── actions ─────────────────────────────────────────────────────────────────────────────────────────────────────── */
+const fail = (r, what) => { S.error = (r && r.error) || `${what} did not work.`; };
+async function run(label, fn) {
+  S.busy = label; S.error = ''; render();
+  try { await fn(); } catch (e) { S.error = String((e && e.message) || e); }
+  S.busy = ''; render();
+}
+async function loadStructure() {
+  const r = await pmGet(`/api/onboarding/structure?ws=${encodeURIComponent(S.ws)}`);
+  if (!r || !r.ok) { fail(r, 'Reading the portfolio'); return false; }
+  adopt(r); return true;
+}
+async function loadBriefing() {
+  const r = await pmGet(`/api/onboarding/briefing?ws=${encodeURIComponent(S.ws)}`);
+  if (!r || !r.ok) { fail(r, 'Reading the Briefing'); return false; }
+  S.briefing = r.items || []; return true;
+}
+const addFolder = () => run('add', async () => {
+  const p = await pmPost('/api/pick-folder', {});
+  if (!p || !p.ok) { if (p && p.cancelled) return; S.note = (p && p.unsupported) ? 'This system has no folder chooser. Start pmos in the folder instead.' : ''; if (!S.note) fail(p, 'Choosing a folder'); return; }
+  const w = await pmPost('/api/workspaces', { root: p.root, name: p.root.split(/[\\/]/).filter(Boolean).pop(), focus: false });
+  if (!w || !w.workspace) { fail(w, 'Adding the folder'); return; }
+  if (!S.added.some((a) => a.id === w.workspace.id) && w.workspace.id !== S.ws) S.added.push({ id: w.workspace.id, name: w.workspace.name, root: w.workspace.root });
+});
+const scan = () => run('scan', async () => {
+  const r = await pmPost('/api/onboarding/scan', { ws: S.ws, extra_roots: S.added.map((a) => a.root) });
+  if (!r || !r.ok) { fail(r, 'The scan'); return; }
+  S.look = r.first_look; S.step = 'look';
+});
+const toPortfolio = () => run('structure', async () => { if (await loadStructure()) S.step = 'portfolio'; });
+async function applyNow() {
+  const include = rowsOf().filter((r) => S.checked[r.proposal_id]).map((r) => r.proposal_id);
+  const answers = {};
+  // an untouched question sends its default (the PM saw it and pressed Import); a skipped one sends nothing
+  for (const q of (S.structure.questions || [])) {
+    if (S.skipped[q.id]) continue;
+    const v = S.answers[q.id] != null ? S.answers[q.id] : q.default;
+    if (q.id === 'template') answers.template = Object.assign(answers.template || {}, { [q.board]: v });
+    else answers[q.id] = v;
+  }
+  const r = await pmPost('/api/onboarding/apply', { ws: S.ws, include, revisions: revisions(), answers });
+  if (!r || !r.ok) { fail(r, 'The import'); return; }
+  S.importId = r.import_id;
+  if (await loadBriefing()) S.step = 'briefing';
+}
+const importNow = () => {
+  if (!counts().n) return;
+  if ((S.structure.questions || []).length && S.step !== 'questions') { S.step = 'questions'; render(); return; }
+  run('apply', applyNow);
+};
+// "Not now": Welcome stops opening on its own for this folder (`pmos welcome` still opens it), then the console opens
+const notNow = () => run('dismiss', async () => {
+  const r = await pmPost('/api/onboarding/dismiss', { ws: S.ws });
+  if (!r || !r.ok) { fail(r, 'Not now'); return; }
+  location.href = '/c3.html?ws=' + encodeURIComponent(S.ws);
+});
+const undo = () => run('undo', async () => {
+  const r = await pmPost('/api/onboarding/undo', { ws: S.ws, import_id: S.importId });
+  if (!r || !r.ok) { fail(r, 'Undo'); return; }
+  S.importId = '';
+  if (await loadStructure()) S.step = 'portfolio';
+});
+
+/* ── views ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+const spin = (txt) => `<span class="wl-spin" data-testid="loading" aria-hidden="true"></span>${esc(txt)}`;
+
+function viewWelcome() {
+  const f = S.folder || { name: '', root: '' };
+  const added = S.added.length ? `<ul class="wl-added" data-testid="added-folders">${S.added.map((a) => `<li data-testid="added-folder">${esc(a.name)} <span class="wl-path">${esc(a.root)}</span></li>`).join('')}</ul>` : '';
+  return `<h1 class="wl-h1">Welcome to PMOS</h1>
+<p class="wl-p wl-muted">PMOS reads your folder and shows you what it found: your initiatives, your documents and what needs you first.</p>
+<section class="wl-card"><h2 class="wl-h2" data-testid="folder-name">${esc(f.name || 'This folder')}</h2><div class="wl-path" data-testid="folder-path">${esc(f.root)}</div>${added}
+<div class="wl-actions"><button type="button" class="wl-btn" data-testid="add-folder" ${S.busy ? 'disabled' : ''}>${S.busy === 'add' ? spin('Waiting for the chooser') : 'Add another folder'}</button></div>
+${S.note ? `<p class="wl-p wl-muted" data-testid="note">${esc(S.note)}</p>` : ''}</section>
+<p class="wl-promise" data-testid="promise">Reads only. Writes nothing in your folder. Nothing leaves this computer.</p>
+<div class="wl-actions"><button type="button" class="wl-btn wl-primary" data-testid="scan-button" ${S.busy ? 'disabled' : ''}>${S.busy === 'scan' ? spin('Scanning your folder') : 'Scan'}</button>
+<button type="button" class="wl-btn wl-quiet" data-testid="not-now" ${S.busy ? 'disabled' : ''}>Not now</button></div>
+${S.busy === 'scan' ? '<p class="wl-p wl-muted" data-testid="scan-wait">A large folder can take a minute or two. PMOS keeps working while it reads.</p>' : ''}`;
+}
+
+function viewLook() {
+  const L = S.look || {};
+  const items = (L.findings || []).slice(0, 10).map((f) => `<li data-testid="finding"><strong>${esc(f.title)}</strong>${f.why ? `<div class="wl-muted">${esc(f.why)}</div>` : ''}<div class="wl-ref" data-testid="finding-ref">${esc(ref((f.evidence || [])[0]))}</div></li>`).join('');
+  return `<h1 class="wl-h1">First look</h1>
+<p class="wl-p" data-testid="first-look-sentence">${esc(L.sentence)}</p>
+<section class="wl-card"><h2 class="wl-h2">What matters most</h2>${items ? `<ol class="wl-findings">${items}</ol>` : '<p class="wl-p wl-muted" data-testid="no-findings">Nothing in this folder needs you urgently.</p>'}</section>
+<div class="wl-actions"><button type="button" class="wl-btn wl-primary" data-testid="continue-button" ${S.busy ? 'disabled' : ''}>${S.busy === 'structure' ? spin('Building your portfolio') : 'Continue'}</button></div>`;
+}
+
+function rowView(r) {
+  const id = r.proposal_id; const docs = r.docs || []; const open = !!S.open[id];
+  const opts = S.structure.boards.map((b) => `<option value="${esc(b.key)}" ${b.key === boardOfRow(r) ? 'selected' : ''}>${esc(b.name)}</option>`).join('');
+  return `<div class="wl-row" data-testid="row" data-id="${esc(id)}">
+<input type="checkbox" class="wl-check" data-testid="row-check" data-id="${esc(id)}" aria-label="Import ${esc(S.titles[id])}" ${S.checked[id] ? 'checked' : ''} />
+<div><input type="text" class="wl-input" data-testid="row-title" data-id="${esc(id)}" value="${esc(S.titles[id])}" aria-label="Title" />
+<div class="wl-meta"><span class="wl-chip" data-testid="row-lane">${esc(r.lane)}</span><span class="wl-chip" data-testid="row-anchor">${esc(r.anchor || 'no anchor')}</span><span class="wl-chip" data-testid="row-stage">${esc(r.stage)}</span>
+<button type="button" class="wl-btn wl-small" data-testid="row-docs-toggle" data-id="${esc(id)}" aria-expanded="${open}">${plural(docs.length, 'document', 'documents')}</button>
+<select class="wl-input" data-testid="row-board" data-id="${esc(id)}" aria-label="Board">${opts}</select></div>
+${open ? `<ul class="wl-docs" data-testid="row-docs">${docs.map((d) => `<li>${esc(d.title && d.title !== d.file ? d.title + ' · ' : '')}${esc(d.file)}</li>`).join('')}</ul>` : ''}</div></div>`;
+}
+
+function viewPortfolio() {
+  const all = rowsOf(); const c = counts();
+  const boards = S.structure.boards.map((b) => {
+    const mine = all.filter((r) => boardOfRow(r) === b.key);
+    return `<section class="wl-card wl-board" data-testid="board" data-board="${esc(b.key)}"><header><h2 class="wl-h2" data-testid="board-name">${esc(b.name)}</h2>
+<span class="wl-muted" data-testid="unsorted-count">${plural((b.unsorted || []).length, 'document', 'documents')} unsorted</span></header>
+${mine.length ? mine.map(rowView).join('') : '<p class="wl-p wl-muted">No initiatives here.</p>'}</section>`;
+  }).join('');
+  return `<h1 class="wl-h1">Your portfolio</h1>
+<p class="wl-p wl-muted">This is how PMOS would set up your work. Untick what you do not want, rename it, or move it to another board.</p>
+${boards}
+<div class="wl-actions"><button type="button" class="wl-btn wl-primary" data-testid="import-button" ${S.busy || !c.n ? 'disabled' : ''}>${S.busy === 'apply' ? spin('Importing') : `Import ${plural(c.n, 'initiative', 'initiatives')} into ${plural(c.m, 'board', 'boards')}`}</button></div>`;
+}
+
+function viewQuestions() {
+  const qs = (S.structure.questions || []).map((q) => {
+    const skipped = !!S.skipped[q.id];
+    const cur = S.answers[q.id] != null ? S.answers[q.id] : q.default;
+    const input = (q.options && q.options.length)
+      ? (q.options.length > 4 && !q.free
+        ? `<select class="wl-input" data-testid="question-select" data-id="${esc(q.id)}" ${skipped ? 'disabled' : ''}>${q.options.map((o) => { const v = typeof o === 'object' ? o.value : o; const t = typeof o === 'object' ? (o.label || o.value) : o; return `<option value="${esc(v)}" ${String(cur) === String(v) ? 'selected' : ''}>${esc(t)}</option>`; }).join('')}</select>`
+        : q.options.map((o) => { const v = typeof o === 'object' ? o.value : o; const t = typeof o === 'object' ? (o.label || o.value) : o; return `<label class="wl-label"><input type="radio" name="q-${esc(q.id)}" data-testid="question-option" data-id="${esc(q.id)}" value="${esc(v)}" ${String(cur) === String(v) ? 'checked' : ''} ${skipped ? 'disabled' : ''} /> ${esc(t)}</label>`; }).join('')
+          + (q.free ? `<label class="wl-label wl-free">${esc(q.free)} <input type="text" class="wl-input" data-testid="question-input" data-id="${esc(q.id)}" placeholder="KR-A1 or health:upkeep" value="${q.options.some((o) => String(typeof o === 'object' ? o.value : o) === String(cur)) ? '' : esc(cur)}" ${skipped ? 'disabled' : ''} /></label>` : ''))
+      : `<input type="text" class="wl-input" data-testid="question-input" data-id="${esc(q.id)}" value="${esc(cur)}" ${skipped ? 'disabled' : ''} />`;
+    return `<section class="wl-card wl-q" data-testid="question" data-id="${esc(q.id)}"><p class="wl-p"><strong>${esc(q.text)}</strong></p>${input}
+${q.options && q.options.length ? '' : `<p class="wl-p wl-muted">Default: ${esc(q.default)}</p>`}<button type="button" class="wl-btn wl-small" data-testid="question-skip" data-id="${esc(q.id)}" aria-pressed="${skipped}">${skipped ? 'Skipped. Use the default' : 'Skip'}</button></section>`;
+  }).join('');
+  const c = counts();
+  return `<h1 class="wl-h1">A few questions</h1><p class="wl-p wl-muted">The scan could not decide these. Each has a default, and you can skip any of them.</p>${qs}
+<div class="wl-actions"><button type="button" class="wl-btn wl-primary" data-testid="questions-continue" ${S.busy ? 'disabled' : ''}>${S.busy === 'apply' ? spin('Importing') : `Import ${plural(c.n, 'initiative', 'initiatives')} into ${plural(c.m, 'board', 'boards')}`}</button></div>`;
+}
+
+function viewBriefing() {
+  const items = S.briefing.map((b) => `<li data-testid="briefing-item"><strong>${esc(b.title)}</strong>${b.why ? `<div class="wl-muted">${esc(b.why)}</div>` : ''}${b.initiative ? `<div class="wl-muted" data-testid="briefing-initiative">${esc(b.initiative.title)} · board ${esc(b.initiative.board)}</div>` : ''}<div class="wl-ref">${esc(ref((b.evidence || [])[0]))}</div></li>`).join('');
+  return `<h1 class="wl-h1">Your first Briefing</h1>
+<p class="wl-p wl-muted">${S.briefing.length ? 'These need you first.' : 'Nothing needs you right now.'}</p>
+<section class="wl-card">${items ? `<ol class="wl-findings">${items}</ol>` : '<p class="wl-p wl-muted" data-testid="no-briefing">Your portfolio is in. Open PMOS to see it.</p>'}</section>
+<div class="wl-actions"><button type="button" class="wl-btn wl-primary" data-testid="sources-continue">Continue</button>
+<button type="button" class="wl-btn wl-quiet" data-testid="undo-link" ${S.busy ? 'disabled' : ''}>${S.busy === 'undo' ? spin('Undoing') : 'Undo this import'}</button></div>`;
+}
+
+function sourceRow(x) {
+  const st = S.sources[x.source] || {};
+  const busy = S.busy === 'source:' + x.source;
+  const state = st.started ? '<span class="wl-muted" data-testid="source-started">Started in an agent session. Follow it in PMOS.</span>'
+    : st.skipped ? '<span class="wl-muted" data-testid="source-skipped">Skipped. You can bring it in later from Settings.</span>'
+    : `<button type="button" class="wl-btn" data-testid="source-bring" data-id="${esc(x.source)}" ${S.busy ? 'disabled' : ''}>${busy ? spin('Starting') : 'Bring in'}</button>
+<button type="button" class="wl-btn wl-quiet" data-testid="source-skip" data-id="${esc(x.source)}" ${S.busy ? 'disabled' : ''}>Skip</button>`;
+  return `<li class="wl-source" data-testid="source-row" data-id="${esc(x.source)}"><div class="wl-source-text"><strong>${esc(x.name)}</strong><div class="wl-muted">${esc(x.adds)}</div>${st.error ? `<div class="wl-error" role="alert">${esc(st.error)}</div>` : ''}</div><div class="wl-source-actions">${state}</div></li>`;
+}
+function viewSources() {
+  return `<h1 class="wl-h1">Bring in more sources</h1>
+<p class="wl-p wl-muted">Your folder is in. These sources are optional. Each one runs in an agent session with your own connection, reads only, and writes nothing to the tool. Nothing is read until you press Bring in.</p>
+<section class="wl-card"><ul class="wl-sources">${MORE_SOURCES.map(sourceRow).join('')}</ul>
+<p class="wl-p wl-muted" data-testid="sources-not-yet">Inbox and Slack have no import yet.</p></section>
+<div class="wl-actions"><a class="wl-btn wl-primary" data-testid="open-pmos" href="/c3.html?ws=${encodeURIComponent(S.ws)}">Open PMOS</a></div>`;
+}
+
+const VIEWS = { welcome: viewWelcome, look: viewLook, portfolio: viewPortfolio, questions: viewQuestions, briefing: viewBriefing, sources: viewSources };
+
+function render() {
+  const keepScroll = window.scrollY;
+  const stepsBar = `<ol class="wl-steps" data-testid="steps">${STEPS.filter(([k]) => k !== 'questions' || S.step === 'questions' || (S.structure && (S.structure.questions || []).length))
+    .map(([k, t]) => `<li ${k === S.step ? 'aria-current="step"' : ''} data-step="${k}">${t}</li>`).join('')}</ol>`;
+  const a = document.activeElement;
+  const was = a && root.contains(a) ? [a.getAttribute('data-testid'), a.getAttribute('data-id')] : null;
+  root.setAttribute('data-step', S.step);
+  root.innerHTML = stepsBar + (S.error ? `<div class="wl-error" role="alert" data-testid="error">${esc(S.error)}</div>` : '') + VIEWS[S.step]();
+  window.scrollTo(0, keepScroll);
+  if (was && was[0]) {   // keep the keyboard where it was after a re-render
+    const again = [...root.querySelectorAll('[data-testid="' + was[0] + '"]')].find((el) => (el.getAttribute('data-id') || null) === (was[1] || null));
+    if (again && !again.disabled) again.focus();
+  }
+}
+
+/* ── events (one delegate; the markup is rebuilt on each render) ─────────────────────────────────────────────────── */
+const idOf = (el) => el.getAttribute('data-id');
+const bringIn = (source) => run('source:' + source, async () => {
+  const r = await pmPost('/api/sources/refresh', { ws: S.ws, source });
+  S.sources[source] = r && r.ok ? { started: true } : { error: (r && r.error) || 'Starting the import did not work.' };
+});
+document.addEventListener('click', (e) => {
+  if (!root.contains(e.target)) return;
+  const t = e.target.closest('[data-testid]'); if (!t) return;
+  const k = t.getAttribute('data-testid');
+  if (k === 'add-folder') addFolder();
+  else if (k === 'scan-button') scan();
+  else if (k === 'continue-button') toPortfolio();
+  else if (k === 'import-button' || k === 'questions-continue') { if (k === 'questions-continue') run('apply', applyNow); else importNow(); }
+  else if (k === 'undo-link') undo();
+  else if (k === 'sources-continue') { S.step = 'sources'; S.error = ''; render(); }
+  else if (k === 'source-bring') bringIn(idOf(t));
+  else if (k === 'source-skip') { S.sources[idOf(t)] = { skipped: true }; render(); }
+  else if (k === 'not-now') notNow();
+  else if (k === 'row-docs-toggle') { S.open[idOf(t)] = !S.open[idOf(t)]; render(); }
+  else if (k === 'question-skip') { const id = idOf(t); S.skipped[id] = !S.skipped[id]; render(); }
+});
+root.addEventListener('change', (e) => {
+  const t = e.target; const k = t.getAttribute && t.getAttribute('data-testid');
+  if (k === 'row-check') { S.checked[idOf(t)] = t.checked; render(); }
+  else if (k === 'row-board') { S.boardOf[idOf(t)] = t.value; render(); }
+  else if (k === 'question-option' || k === 'question-select') S.answers[idOf(t)] = t.value;
+});
+root.addEventListener('input', (e) => {
+  const t = e.target; const k = t.getAttribute && t.getAttribute('data-testid');
+  if (k === 'row-title') S.titles[idOf(t)] = t.value;
+  else if (k === 'question-input') {
+    const id = idOf(t); const q = ((S.structure && S.structure.questions) || []).find((x) => x.id === id);
+    S.answers[id] = t.value.trim() ? t.value : (q ? q.default : t.value); // an emptied free answer goes back to the default
+  }
+});
+
+/* ── start ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+async function start() {
+  render();
+  const list = await pmGet('/api/workspaces');
+  const all = (list && list.workspaces) || [];
+  const mine = all.find((w) => w.id === S.ws) || (!S.ws ? all[0] : null);
+  if (!mine) { S.error = 'This folder is not open in PMOS. Start pmos in the folder, then reload.'; render(); return; }
+  S.ws = mine.id; S.folder = { name: mine.name, root: mine.root };
+  const st = await pmGet(`/api/onboarding/status?ws=${encodeURIComponent(S.ws)}`);
+  if (st && st.ok && st.state === 'imported') {
+    const live = (st.imports || []).filter((i) => !i.retracted).pop();
+    S.importId = live ? live.import_id : '';
+    if (S.importId && await loadBriefing() && await loadStructure()) S.step = 'briefing';
+  }
+  render();
+}
+start();

package/workspace/public/welcome.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en" class="wl-page" data-pm-page-theme="light">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+<meta name="pmos-nonce" content="" />
+<title>Welcome to PMOS</title>
+<!-- The first-run page. The server fills the nonce meta the way it does for /c3.html, so a press (Scan, Import, Undo)
+     carries it. Tokens and fonts are the console's, so light and dark both resolve. The page does not load the console. -->
+<link rel="preload" href="/vendor/ibm-plex-mono-400.woff2" as="font" type="font/woff2" crossorigin />
+<link rel="stylesheet" href="/pm/tokens.css" />
+<link rel="stylesheet" href="/pm/components.css" />
+
+</head>
+<body class="wl-body">
+<main id="wl-root" class="wl-wrap" data-testid="welcome-root"></main>
+<noscript><p class="wl-wrap">This page needs JavaScript.</p></noscript>
+<script type="module" src="/pm/welcome.js"></script>
+</body>
+</html>

package/workspace/server.js

@@ -1942,6 +1942,21 @@ const autoSync = require('./lib/auto-sync').createAutoSync({
   onDone: (root) => boardCache.invalidate(root),
   label: `${os.hostname()} (auto-sync)`,
 });
+// workspace-data-freshness (R2 to R4): the facts cache is kept in the runtime state folder, and ONE change detector per
+// workspace starts the board and facts rebuilds when the repository changes, so nothing is re-read on a clock. The board
+// keeps its last value while it rebuilds (stale while revalidate): dropping it would show a blank Board on every change.
+const factsAsync = require('./lib/facts-async.js');
+factsAsync.configure({ stateDir: STATE });
+const freshness = require('./lib/freshness.js').create({
+  stateDir: STATE,
+  workspaces: () => [...workspaces.values()],
+  schedules: () => readSchedules(),
+  factsStatus: (root) => factsAsync.status(root),
+  onChange: (w) => { boardCache.board(w.root, { refreshNow: true }); factsAsync.refresh(w.root); },
+  pollMs: Math.max(250, Number(process.env.PMOS_FRESH_POLL_MS) || 10000),
+  stableMs: Math.max(0, Number(process.env.PMOS_FRESH_STABLE_MS) || 3000),
+});
+if (!REQUIRED_AS_LIBRARY) freshness.start();
 const STOPPED_STATES = ['closed', 'on-hold', 'cancelled'];
 function readLifecycle(w) {
   const latest = new Map();
@@ -2362,6 +2377,12 @@ const SEED_SETS = {
   // jira-wbs (J14): the agent step that reads the status of every pushed Jira ticket into each initiative's snapshot,
   // read-only. Daily at 06:30, so the morning brief (06:45) and every report read a status at most a day old.
   jira: [{ name: 'Jira status check', skill: 'jira-sync', cadence: 'daily', time: '06:30' }],
+  // workspace-data-freshness (R8): the read-only calendar pull, before the morning brief (06:45) and again at midday, so
+  // Briefing and Calendar never work from yesterday's events.
+  calendar: [
+    { name: 'Calendar pull (morning)', skill: 'calendar-sync', cadence: 'daily', time: '06:30' },
+    { name: 'Calendar pull (midday)', skill: 'calendar-sync', cadence: 'daily', time: '12:30' },
+  ],
 };
 function readSchedules() {
   try { const a = JSON.parse(fs.readFileSync(schedFile(), 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
@@ -4065,6 +4086,18 @@ function myWorkRead(wsId) {
   if (!s || s.state === 'exited') return { ok: false, status: 500, error: (s && s.note) || 'the read session could not start' };
   return { ok: true, session: s.id };
 }
+/** Refresh now (workspace-data-freshness R7): start skill `skillId` in a session of repository `wsId`, as myWorkRead does. */
+function startSkillSession(wsId, skillId, name) {
+  const w = getWs(wsId);
+  if (!w) return { ok: false, status: 400, error: 'no workspace' };
+  const task = taskById(skillId, w.root);
+  if (!task || task.kind !== 'agent' || !task.prompt) return { ok: false, status: 409, error: `the ${skillId} skill is not installed for this repository` };
+  const prompt = skillStore.retargetFiling(task.prompt, filingContract(w));
+  const s = spawnSession({ name, agent: task.agent || 'claude', ws: w.id, origin: 'source-refresh', initialInput: prompt + '\r',
+    modelAsk: { scheduleTier: null, skillTier: task.tier || null, skill: task.skill } });
+  if (!s || s.state === 'exited') return { ok: false, status: 500, error: (s && s.note) || 'the refresh session could not start' };
+  return { ok: true, session: s.id };
+}
 /* The calendar the Agenda remembers (G23): one file beside the briefs, written only by the brief route. */
 const CAL_MEMORY = () => path.join(STATE, 'calendar-memory.json');
 // the PM's key-meeting marks (lib/calendar-memory.js setMark): a small file beside the calendar memory, written only by
@@ -5514,12 +5547,12 @@ async function handleRequest(req, res) {
   const built = BUILD_RE.exec(url.pathname);
   const p = built ? built[1] : url.pathname;
 
-  if (p === '/' || p === '/index.html' || p === '/c3.html') {
+  if (p === '/' || p === '/index.html' || p === '/c3.html' || p === '/welcome' || p === '/welcome.html') {
     // pm-os-absorb Run 2 (R25, X11): the per-launch nonce goes into the base meta line, nowhere else. no-store, so a
     // restarted server never answers a press from a page that holds the previous launch's value. The page code is
     // referenced under this launch's build prefix.
     const n = pmGuard.launchNonce();
-    return fs.readFile(path.join(PUB, p === '/c3.html' ? 'c3.html' : 'index.html'), 'utf8', (err, html) => {
+    return fs.readFile(path.join(PUB, p === '/c3.html' ? 'c3.html' : (p === '/welcome' || p === '/welcome.html') ? 'welcome.html' : 'index.html'), 'utf8', (err, html) => {
       if (err) { res.writeHead(404); res.end('not found'); return; }
       let out = withBuild(html);
       if (n) out = out.replace('<meta name="' + pmGuard.NONCE_META + '" content="" />', '<meta name="' + pmGuard.NONCE_META + '" content="' + n + '" />');
@@ -6457,7 +6490,9 @@ async function handleRequest(req, res) {
   // `ledgers` (pm-os-absorb Run 1) — the plan-items signature of every registered workspace, so an open Breakdown
   // knows to refetch: `items` is one stat per workspace; `evidence` is computed only for the ids in ?ledgers=
   // (at most 4). Computed on this request and never stored (D33).
-  if (p === '/api/sessions') return json(res, { sessions: sessionList(), version: APP_VERSION,
+  // `data_versions` (workspace-data-freshness R4): a number per workspace that moves when its files change, so a page
+  // refetches only then.
+  if (p === '/api/sessions') return json(res, { sessions: sessionList(), version: APP_VERSION, data_versions: freshness.versions(),
     ledgers: planItems.ledgerSigs([...workspaces.values()].map((w) => ({ id: w.id, root: w.root })), url.searchParams.get('ledgers')) });
   if (p === '/api/git/branches') {
     // Read-only branch awareness for a workspace. A non-repo returns {ok:false} (never a fake
@@ -8654,7 +8689,9 @@ async function handleRequest(req, res) {
   if (await routeModules.dispatch(req, res, url, { json, readBody, getWs, invalidateNeedsAgg, boardCache, consoleState, stateDirFor, sessionList, initiativeIndex,
     runtimeDir: STATE, spawnSession, jevModelOpts, sendToSession,
     // initiative my-work: every registered repository, the day runs, and the two presses that start sessions
-    workspaceList: () => [...workspaces.values()], readDayRun, myWorkBrief, myWorkRead })) return;
+    workspaceList: () => [...workspaces.values()], readDayRun, myWorkBrief, myWorkRead,
+    // workspace-data-freshness: the source table, the facts rebuild and Refresh now's skill sessions
+    freshness, factsRefresh: (root) => factsAsync.refresh(root, { force: true }), startSkill: startSkillSession })) return;
   res.writeHead(404); res.end('not found');
 }
 

package/workspace/skills/calendar-sync.skill

@@ -0,0 +1,30 @@
+---
+name: calendar-sync
+label: "Calendar pull"
+description: "Read, read-only, the PM's calendar events for today and the next 14 days, and hand them to PMOS so Briefing and Calendar work from today's events. It writes nothing to the calendar."
+run: agent
+agent: claude
+output:
+  - Imported
+  - Not reached
+  - Needs you
+---
+
+/calendar-sync — bring the PM's calendar up to date in PMOS. You read the calendar with the PM's own calendar connection. PMOS saves what you read and shows it on Briefing and Calendar. You change nothing in the calendar.
+
+Rules that always hold:
+1. READ-ONLY on the calendar. Use only the tools that list or read events. Never create, edit, move, accept, decline, delete or respond to an event, and never send an invitation or a message.
+2. THE ONLY WRITE is `pmos calendar import --from <file> --sensitivity <label>`, once, at the end. Never edit a repository file. Never commit.
+3. LIGHT ON CONTENT. For each event, give only its id, title, start, end, the attendees' display names and, when you can tell, the initiative id it is for. Never copy a description, a meeting link, a dial-in number, an attachment, an email address or a token.
+4. SENSITIVITY. Use `internal` unless the PM said otherwise. Leave out any event marked private, personal, confidential or HR, and count it.
+5. TEMPORARY FILES OUTSIDE THE REPOSITORY. Write the events file in this session's scratch folder, and delete it after the import.
+6. NOTHING INVENTED. If the calendar cannot be reached, list it under "Not reached" and import nothing: an empty import is not a calendar with no meetings.
+
+Procedure:
+1. List the PM's events from the start of today to the end of the 14th day after today, from the primary calendar. Fetch every page. Skip an event the PM declined.
+2. Write the events as JSON in the scratch folder, for example `<scratch>/calendar.json`, as a list with one object per event:
+   `{"id", "title", "start", "end", "attendees": ["Display Name", …], "initiative": "<initiative id or null>"}`
+   `start` and `end` are ISO times with the offset, for example `2026-10-12T09:00:00+07:00`. An all-day event has the date only.
+3. Run `pmos calendar import --from <scratch>/calendar.json --sensitivity internal`. If it refuses the file, fix what it names and run it once more.
+4. Delete the scratch file.
+5. Report in four short lists: Imported (the count, and the first and last day), Left out (the count of private events), Not reached, and Needs you (only when something blocked the pull).

package/workspace/test-lists/onboarding-firstrun.json

@@ -0,0 +1,15 @@
+{
+  "_comment": "Initiative onboarding-scan-and-map, slice 2: the first-run routes (in-process) and the /welcome page (browser).",
+  "modules": [
+    "routes-onboarding.test.js",
+    "onboarding-scripts.test.js"
+  ],
+  "panels": [
+    "pm-welcome-test.js"
+  ],
+  "seconds": {
+    "routes-onboarding.test.js": 6,
+    "pm-welcome-test.js": 25,
+    "onboarding-scripts.test.js": 8
+  }
+}

package/workspace/test-lists/workspace-data-freshness.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "workspace-data-freshness: the shared commit range, the change-keyed facts cache, the change detector and data version, the source table and Refresh now, the worker-thread folds, and pmos calendar.",
+  "modules": ["data-freshness.test.js"],
+  "panels": [],
+  "seconds": { "data-freshness.test.js": 25 }
+}