create-pmos 0.240.0 → 0.242.0

package/workspace/guide/reports-dashboards.md

@@ -15,7 +15,7 @@ Each tab has one job. A line under the tabs repeats it: **Live** goes to Dashboa
 
 - **Dashboards.** The charts of one scope, drawn from the repository's records. A dashboard is live: it changes when your work changes. The tab shows how many dashboards there are.
 - **Reports.** The documents you send, with their set-ups. See [Set up a report by asking](reports-set-up.md). The tab shows how many drafts wait for you.
-- **Charts.** Every chart the workspace can draw, with the question it answers, the dashboards that use it and the reports that use it. The tab shows how many charts there are.
+- **Charts.** Every chart the workspace can draw, with the question it answers, the dashboards that use it and the reports that use it. The tab shows how many charts there are. A chart that the Structure step of a report saved is listed too, tagged **Data chart**, with its source and the dashboards and reports that use it. See [Shape what a report says](report-structure.md).
 
 The old tab names still work. A link to Library opens Charts. A link to Drafts opens Reports.
 

package/workspace/guide/reports-set-up.md

@@ -43,6 +43,8 @@ The most likely finding also shows on the Briefing as **Report found**. Press **
 - **Draft it now** shows in place of Open when the report has no draft. PMOS writes the draft of the next cycle and opens it.
 - **All cycles** lists every cycle of the report.
 - **Pause** stops the drafts. **Resume** starts them again.
+- **Shape the report** opens the Structure step of the report studio. There you decide what the report answers, where each number comes from and how it is worked out. See [Shape what a report says](report-structure.md). **Shape it with PMOS** on an answer sets the report up and opens the same step.
+- **Shape the report** opens the Structure step of the report studio. There you decide what the report answers, where each number comes from and how it is worked out. See [Shape what a report says](report-structure.md). **Shape it with PMOS** on an answer sets the report up and opens the same step.
 - **Design how it looks** opens the design studio. There you design how the report looks, as a deck or a document. See [Design how a report looks](report-design.md).
 
 **Documents** has one row for each cycle: Draft or Issued, the output, the copy state and who made it. Filter by state or by source. Press **Open** to read a document in the [document sheet](document-sheet.md).

package/workspace/lib/charts-store.js

@@ -0,0 +1,124 @@
+'use strict';
+/* charts-store.js — the chart store: the charts a report structure defines once (initiative report-structure, contract section 6).
+ *
+ *   paths(root)                          → { file, rel }                       <state>/charts.jsonl
+ *   append(root, line, { actor, now })   → the line written. THE SINGLE WRITER of charts.jsonl. `at` and `actor` are set here.
+ *   readEvents(root) · fold(events)      → Map id → chart                      a torn line is skipped
+ *   get(root, id)                        → chart | null
+ *   addChart(root, chart, { actor })     → { ok, chart } | refusal             slugs the id, makes it unique, writes one 'add' line
+ *   list(root, { runtimeDir })           → [chart + { users: [{ kind: 'report' | 'dashboard', id, name }] }]
+ *   slugOf(text)                         → a chart id slug
+ *
+ * THE LINES. Every line is { ev, id, chart?, at, actor }: 'add' (a whole chart), 'change' (the fields that changed), 'remove'.
+ * A CHART is { id, name, question, source: { kind, name, via?, ref? }, from, how, compare, flag, query, why, created_by }.
+ * USERS are folded from the ACCEPTED plans (a report whose saved structure names the chart in charts[].chart) and from the Reports dashboards'
+ * layouts (<runtime>/report-dashboards/layouts.json: a key whose list holds the chart id). A chart from the store is REFERENCED by a plan, never copied.
+ *
+ * NOTHING HERE STARTS A JOB OR SENDS ANYTHING.
+ */
+const fs = require('fs');
+const path = require('path');
+const RD = require('./report-draft.js');
+
+const ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const EVENTS = Object.freeze(['add', 'change', 'remove']);
+const FIELDS = Object.freeze(['name', 'question', 'from', 'how', 'compare', 'flag', 'query', 'why']);
+const PMOS_ACTOR = Object.freeze({ by: 'pmos', via: 'job' });
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' ? v : '');
+const refuse = (status, error) => ({ ok: false, status, error });
+
+function stateRel(root) { try { return RD.stateRel(root); } catch { return 'planning'; } }
+function paths(root) {
+  const abs = path.resolve(String(root));
+  const rel = `${stateRel(abs)}/charts.jsonl`;
+  return { abs, rel, file: path.join(abs, rel) };
+}
+function slugOf(text) {
+  const s = String(text == null ? '' : text).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').replace(/^[^a-z]+/, '').slice(0, 36).replace(/-+$/, '');
+  return s || 'chart';
+}
+
+function append(root, line, { actor, now } = {}) {
+  if (!isObj(line) || !EVENTS.includes(line.ev) || !ID_RE.test(str(line.id))) throw new Error(`charts-store: bad line ${JSON.stringify(line && line.ev)}`);
+  const p = paths(root);
+  const out = { ...line, at: new Date(now == null ? Date.now() : now).toISOString(), actor: isObj(actor) ? { by: str(actor.by), via: str(actor.via) } : { ...PMOS_ACTOR } };
+  fs.mkdirSync(path.dirname(p.file), { recursive: true });
+  fs.appendFileSync(p.file, JSON.stringify(out) + '\n');
+  return out;
+}
+function readEvents(root) {
+  let text = '';
+  try { text = fs.readFileSync(paths(root).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) && EVENTS.includes(l.ev) && ID_RE.test(str(l.id))) out.push(l); } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
+function fold(events) {
+  const m = new Map();
+  for (const l of events) {
+    if (l.ev === 'add' && isObj(l.chart)) m.set(l.id, { ...l.chart, id: l.id, added_at: l.at });
+    else if (l.ev === 'change' && m.has(l.id) && isObj(l.chart)) m.set(l.id, { ...m.get(l.id), ...l.chart, id: l.id, changed_at: l.at });
+    else if (l.ev === 'remove') m.delete(l.id);
+  }
+  return m;
+}
+const stateOf = (root) => fold(readEvents(root));
+function get(root, id) { return stateOf(root).get(String(id)) || null; }
+
+/** Write one new chart. The id is slugged from chart.id (else the name) and made unique with -2, -3, …. → { ok, chart } */
+function addChart(root, chart, { actor, now } = {}) {
+  if (!isObj(chart)) return refuse(400, 'chart must be an object');
+  const have = stateOf(root);
+  const base = slugOf(chart.id || chart.name);
+  let id = base; let k = 2;
+  while (have.has(id)) { id = `${base.slice(0, 36)}-${k++}`; }
+  const clean = { id, name: str(chart.name), question: str(chart.question), source: isObj(chart.source) ? chart.source : { kind: 'pmos-level', name: '' },
+    from: str(chart.from), how: str(chart.how), compare: str(chart.compare), flag: str(chart.flag), query: str(chart.query), why: str(chart.why), created_by: str(chart.created_by) };
+  append(root, { ev: 'add', id, chart: clean }, { actor, now });
+  return { ok: true, chart: clean };
+}
+
+/** The reports whose ACCEPTED structure uses each chart id: Map chart id → [{ kind: 'report', id, name }]. */
+function reportUsers(root, nameOf) {
+  const users = new Map();
+  const base = path.join(paths(root).abs, stateRel(root), 'reports');
+  let cadences = [];
+  try { cadences = fs.readdirSync(base); } catch { return users; }
+  const RS = require('./report-structure.js');
+  for (const cadence of cadences) {
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(cadence) || cadence === 'definitions') continue;
+    let st; try { st = RS.stateOf(root, cadence); } catch { continue; }
+    if (!st.saved) continue;
+    const plan = RS.readVersion(root, cadence, st.saved.n);
+    if (!plan) continue;
+    for (const c of plan.charts || []) {
+      if (!c.chart) continue;
+      if (!users.has(c.chart)) users.set(c.chart, []);
+      const list = users.get(c.chart);
+      if (!list.some((u) => u.id === cadence)) list.push({ kind: 'report', id: cadence, name: (nameOf && nameOf(cadence)) || cadence });
+    }
+  }
+  return users;
+}
+/** The dashboard layout keys whose list names the chart id. The layout reader keeps only the built-in ids, so the file is read as it is. */
+function dashboardUsers(runtimeDir, id) {
+  if (!runtimeDir) return [];
+  let raw; try { raw = JSON.parse(fs.readFileSync(path.join(runtimeDir, 'report-dashboards', 'layouts.json'), 'utf8')); } catch { return []; }
+  const src = isObj(raw) && isObj(raw.layouts) ? raw.layouts : raw;
+  if (!isObj(src)) return [];
+  return Object.entries(src).filter(([, v]) => Array.isArray(v) && v.includes(id)).map(([k]) => ({ kind: 'dashboard', id: k, name: k }));
+}
+
+function list(root, { runtimeDir, nameOf } = {}) {
+  const users = reportUsers(root, nameOf);
+  return [...stateOf(root).values()].sort((a, b) => (a.added_at < b.added_at ? -1 : a.added_at > b.added_at ? 1 : 0))
+    .map((c) => ({ ...c, users: [...(users.get(c.id) || []), ...dashboardUsers(runtimeDir, c.id)] }));
+}
+function one(root, id, opts) { return list(root, opts).find((c) => c.id === id) || null; }
+
+module.exports = { ID_RE, EVENTS, FIELDS, paths, append, readEvents, fold, stateOf, get, addChart, list, one, slugOf };

package/workspace/lib/headless.js

@@ -3,7 +3,7 @@
  * (initiative workspace-headless-jobs; PM decision 2026-10-11: keep Jev, no direct Claude API, background
  * jobs that need no human run headless).
  *
- *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | 'drive' | 'scan-web' | 'scan-repo' | 'scan-research-web' | 'scan-research-repo' | 'report-setup' | 'report-find' | 'core-doc' | 'report-design' | 'report-sample-fetch' | null   (null: open a pane, as before)
+ *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | 'ask' | 'drive' | 'scan-web' | 'scan-repo' | 'scan-research-web' | 'scan-research-repo' | 'report-setup' | 'report-find' | 'core-doc' | 'report-design' | 'report-sample-fetch' | 'report-structure' | 'report-structure-dry' | null   (null: open a pane, as before)
  *   argsFor(kind, { modelArgs, addDirs, writePaths }) → the argv after `claude` (writePaths: the one render file a report-design job may write)
  *   parseResult(stdout)                            → { ok, text, isError, turns, durationMs, costUsd, denied[] }
  *   streamLines(line)                              → { log: [lines], result: object|null }   one stream-json event, for the live log
@@ -48,6 +48,11 @@
  * (the cycle document, the samples, the earlier versions and the brief) and writes ONE file: the render at the pending path the server gives it, named in
  * its tool list as `Write(//<path>)` and `Edit(//<path>)`. It has no web tool, no Bash and no connector tool, and nothing that sends. The server sanitizes
  * the render before anything shows it. It never runs in a pane.
+ * The `report-structure` and `report-structure-dry` kinds are the report structure step (initiative report-structure): origins `report-structure:<id>` and
+ * `report-structure-dry:<id>`. A turn proposes or refines the plan of a report (sources, charts, outline); a dry run tries a saved version on the last complete
+ * period. Each reads the repository and, where the PM's own Claude Code settings allow it, reads through connectors (none is named in the list, as for
+ * `report-sample-fetch`), and each writes ONE file: structure/pending/<job>.json, named in its tool list like the design render. No Bash, no web fetch, no
+ * connector write tool, nothing that sends. The server validates the file before it lands. Neither kind ever runs in a pane.
  */
 
 // The skills whose every start runs headless: they read, file a result for PMOS, and send nothing out.
@@ -82,7 +87,10 @@ const CORE_DOC_ORIGINS = Object.freeze(['core-doc:']);
 const REPORT_DESIGN_ORIGINS = Object.freeze(['report-design:']);
 // report-design-studio: reading ONE linked Google or Confluence file through the PM's own connectors (origin `report-sample-fetch:<cadence>:<sampleId>`).
 const REPORT_SAMPLE_FETCH_ORIGINS = Object.freeze(['report-sample-fetch:']);
-const WRITE_PATH_KINDS = Object.freeze(['report-design', 'report-sample-fetch']);   // kinds whose one writable file the caller names (argsFor writePaths)
+// report-structure: a structure turn and a dry run on real data (origins `report-structure:<id>`, `report-structure-dry:<id>`).
+const REPORT_STRUCTURE_ORIGINS = Object.freeze(['report-structure:']);
+const REPORT_STRUCTURE_DRY_ORIGINS = Object.freeze(['report-structure-dry:']);
+const WRITE_PATH_KINDS = Object.freeze(['report-design', 'report-sample-fetch', 'report-structure', 'report-structure-dry']);   // kinds whose one writable file the caller names (argsFor writePaths)
 
 // What each kind may use. Read-only search is always allowed. The notes passes write their JSON (and rename the .tmp
 // file) in their notes folder, which --add-dir opens to them; the skills also run `pmos` verbs and repository scripts.
@@ -114,6 +122,9 @@ const TOOLS = Object.freeze({
   'report-design': Object.freeze(['Read', 'Glob', 'Grep']),
   // The link fetch run: Read, and its one write (the text copy of the linked file) is added per run by argsFor. No Bash, no web, no connector tool named.
   'report-sample-fetch': Object.freeze(['Read']),
+  // The structure runs: read and search; a connector read runs only where the PM's own settings allow it. Their one write, the JSON file, is added per run by argsFor.
+  'report-structure': Object.freeze(['Read', 'Glob', 'Grep']),
+  'report-structure-dry': Object.freeze(['Read', 'Glob', 'Grep']),
   skill: Object.freeze(['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash(pmos *)', 'Bash(node *)',
     'Bash(git log *)', 'Bash(git status *)', 'Bash(git diff *)', 'Bash(ls *)', 'Bash(date *)']),
 });
@@ -139,6 +150,9 @@ function kindFor({ agent, origin, skill, env } = {}) {
   if (CORE_DOC_ORIGINS.some((p) => o.startsWith(p))) return 'core-doc';
   if (REPORT_DESIGN_ORIGINS.some((p) => o.startsWith(p))) return 'report-design';
   if (REPORT_SAMPLE_FETCH_ORIGINS.some((p) => o.startsWith(p))) return 'report-sample-fetch';
+  // 'report-structure-dry:' is not a prefix of 'report-structure:' (the colon differs), so the two are told apart by their prefix alone
+  if (REPORT_STRUCTURE_DRY_ORIGINS.some((p) => o.startsWith(p))) return 'report-structure-dry';
+  if (REPORT_STRUCTURE_ORIGINS.some((p) => o.startsWith(p))) return 'report-structure';
   if (skill && HEADLESS_SKILLS.includes(String(skill))) return 'skill';
   return null;
 }
@@ -265,4 +279,4 @@ function logLines(r, exitCode) {
   return out;
 }
 
-module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, SCAN_WEB_ORIGINS, SCAN_REPO_ORIGINS, SCAN_RESEARCH_WEB_ORIGINS, SCAN_RESEARCH_REPO_ORIGINS, WEB_KINDS, REPORT_SETUP_ORIGINS, REPORT_FIND_ORIGINS, CORE_DOC_ORIGINS, REPORT_DESIGN_ORIGINS, REPORT_SAMPLE_FETCH_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, streamLines, outcomeOf, logLines, switchedOff };
+module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, ASK_ORIGINS, DRIVE_ORIGINS, SCAN_WEB_ORIGINS, SCAN_REPO_ORIGINS, SCAN_RESEARCH_WEB_ORIGINS, SCAN_RESEARCH_REPO_ORIGINS, WEB_KINDS, REPORT_SETUP_ORIGINS, REPORT_FIND_ORIGINS, CORE_DOC_ORIGINS, REPORT_DESIGN_ORIGINS, REPORT_SAMPLE_FETCH_ORIGINS, REPORT_STRUCTURE_ORIGINS, REPORT_STRUCTURE_DRY_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, streamLines, outcomeOf, logLines, switchedOff };

package/workspace/lib/meeting-material.js

@@ -0,0 +1,151 @@
+'use strict';
+/* lib/meeting-material.js — the material the PM linked to a meeting (initiative meeting-material-replay, part 1).
+ *
+ *   keyOf(event)                          → 's:<series>' or 't:<normalized title>' (calendar-memory.js seriesKey), as lib/calendar-links.js
+ *   append(runtimeDir, body, by)          → { ok, items } | { ok: false, error }   op 'add' (the default) or 'remove'
+ *   forMeeting(runtimeDir, event)         → [item]   the series items of the meeting and the items for this one meeting, in the order they were added
+ *   read(runtimeDir)                      → Map<identity, row>   the rows that hold now (a removed item is gone)
+ *   check(body)                           → null | the reason the body is refused
+ *   classifyUrl(url)                      → { kind: slides|gdoc|conf|link, url } | null
+ *
+ * The calendar is read-only (PMOS never edits an invite), so the material lives beside it: <runtime>/meeting-material.jsonl, append-only.
+ * A row: { at, by, key, series, event?, scope: 'meeting'|'series', item: { kind, ref?, title, url?, ws? }, topic?, present, removed? }.
+ * An item is named by its key, its event ("this meeting"; empty for the series) and its kind and ref or url. The last row of a name wins,
+ * and a row with removed: true takes the item off. Nothing is ever rewritten.
+ *
+ * Kinds. PMOS items name a file of the repository by ref: pmos-doc (a document), pmos-deck (a report cycle that is a slide deck), report
+ * (any other report cycle). Links name an address: slides, gdoc, conf, link. The server decides a link's kind from its address. */
+const fs = require('fs');
+const path = require('path');
+const calMem = require('./calendar-memory.js');
+
+const FILE = 'meeting-material.jsonl';
+const PMOS_KINDS = ['pmos-deck', 'pmos-doc', 'report'];
+const LINK_KINDS = ['slides', 'gdoc', 'conf', 'link'];
+const KINDS = [...PMOS_KINDS, ...LINK_KINDS];
+const SCOPES = ['meeting', 'series'];
+const OPS = ['add', 'remove'];
+const MAX_ITEMS = 60;
+const str = (v) => (typeof v === 'string' ? v.trim() : '');
+
+const keyOf = (e) => calMem.seriesKey({ series: e && e.series ? String(e.series) : null, title: e && e.title });
+const fileOf = (runtimeDir) => path.join(runtimeDir, FILE);
+
+/** What an address is. Only https addresses are kept; the server and the page agree on the kind. */
+function classifyUrl(raw) {
+  const s = str(raw);
+  if (!s || s.length > 1000 || /\s/.test(s)) return null;
+  let u; try { u = new URL(/^[a-z][a-z0-9+.-]*:/i.test(s) ? s : 'https://' + s); } catch { return null; }
+  if (u.protocol !== 'https:' || !u.hostname.includes('.')) return null;
+  if (u.hostname === 'docs.google.com' && /^\/presentation\/d\//.test(u.pathname)) return { kind: 'slides', url: u.href };
+  if (u.hostname === 'docs.google.com' && /^\/document\/d\//.test(u.pathname)) return { kind: 'gdoc', url: u.href };
+  if (/\.atlassian\.net$/.test(u.hostname) && u.pathname.startsWith('/wiki')) return { kind: 'conf', url: u.href };
+  return { kind: 'link', url: u.href };
+}
+
+/** A repository-relative file path: no leading slash, no "..", no backslash, no control character. */
+const refOk = (r) => typeof r === 'string' && r.length > 0 && r.length <= 300 && !r.startsWith('/') && !r.includes('\\') && !/(^|\/)\.\.(\/|$)/.test(r) && !/[\u0000-\u001f]/.test(r);
+
+/** The name of an item inside one meeting or series. */
+const idOf = (item) => item.kind + '|' + (PMOS_KINDS.includes(item.kind) ? item.ref : item.url);
+const identity = (row) => [row.key, row.scope === 'series' ? '' : row.event || '', idOf(row.item)].join('\u0000');
+
+/** The reason a POST body is refused, or null.
+ *  body: { op?: 'add'|'remove', event: { id?, title, series? }, scope: 'meeting'|'series', item: { kind, ref | url, title?, ws? }, topic?, present? } */
+function check(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return 'the body must be a JSON object';
+  if (body.op != null && !OPS.includes(body.op)) return 'op is one of ' + OPS.join(', ');
+  const e = body.event;
+  if (!e || typeof e !== 'object' || !str(e.title) || str(e.title).length > 300) return 'event.title is required (one line, at most 300 characters)';
+  if (e.series != null && (typeof e.series !== 'string' || e.series.length > 300)) return 'event.series must be text';
+  if (e.id != null && (typeof e.id !== 'string' || e.id.length > 120)) return 'event.id must be text';
+  const scope = body.scope == null ? 'meeting' : body.scope;
+  if (!SCOPES.includes(scope)) return 'scope is one of ' + SCOPES.join(', ');
+  if (scope === 'meeting' && !str(e.id)) return 'a link for one meeting needs event.id';
+  const it = body.item;
+  if (!it || typeof it !== 'object') return 'item is required';
+  if (PMOS_KINDS.includes(it.kind)) { if (!refOk(it.ref)) return 'a PMOS item needs ref, the path of the file in the repository'; }
+  else if (it.kind == null || LINK_KINDS.includes(it.kind)) { if (!classifyUrl(it.url)) return 'a link must be an https address'; }
+  else return 'item.kind is one of ' + KINDS.join(', ');
+  if (it.title != null && (typeof it.title !== 'string' || it.title.length > 300 || /[\r\n]/.test(it.title))) return 'item.title is one line of at most 300 characters';
+  if (it.ws != null && (typeof it.ws !== 'string' || it.ws.length > 120)) return 'item.ws must be text';
+  if (body.topic != null && (typeof body.topic !== 'string' || body.topic.length > 160 || /[\r\n]/.test(body.topic))) return 'topic is one line of at most 160 characters';
+  if (body.present != null && typeof body.present !== 'boolean') return 'present must be true or false';
+  return null;
+}
+
+/** The item as it is kept: the kind a link has, its address in full, a title. */
+function cleanItem(it) {
+  if (PMOS_KINDS.includes(it.kind)) return { kind: it.kind, ref: it.ref, title: str(it.title) || it.ref, ...(str(it.ws) ? { ws: str(it.ws) } : {}) };
+  const c = classifyUrl(it.url);
+  return { kind: c.kind, url: c.url, title: str(it.title) || c.url };
+}
+
+function lines(runtimeDir) {
+  if (!runtimeDir) return [];
+  let text = '';
+  try { text = fs.readFileSync(fileOf(runtimeDir), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const l of text.split('\n')) {
+    if (!l.trim()) continue;
+    let x; try { x = JSON.parse(l); } catch { continue; }
+    if (!x || typeof x.key !== 'string' || !SCOPES.includes(x.scope) || !x.item || !KINDS.includes(x.item.kind)) continue;
+    if (PMOS_KINDS.includes(x.item.kind) ? !refOk(x.item.ref) : !x.item.url) continue;
+    out.push(x);
+  }
+  return out;
+}
+
+/** The rows that hold now, in the order their items were first added (a changed item keeps its place). */
+function read(runtimeDir) {
+  const out = new Map();
+  for (const row of lines(runtimeDir)) {
+    const id = identity(row);
+    if (row.removed) { out.delete(id); continue; }
+    out.set(id, out.has(id) ? { ...row, firstAt: out.get(id).firstAt } : { ...row, firstAt: row.at || null });
+  }
+  return out;
+}
+
+const view = (row) => ({
+  id: crypto16(identity(row)), kind: row.item.kind, ref: row.item.ref || null, url: row.item.url || null, title: row.item.title || row.item.ref || row.item.url,
+  ws: row.item.ws || null, topic: row.topic || null, present: row.present === true, scope: row.scope, from: 'you', by: row.by || null, at: row.at || null,
+});
+/** A short stable id for a row, so the page can name an item without sending its path back and forth. */
+function crypto16(s) { return require('crypto').createHash('sha1').update(s).digest('hex').slice(0, 12); }
+
+/** The material of one meeting: its series items and its own, in the order they were added. event: { id?, title, series? } */
+function forMeeting(runtimeDir, event) {
+  if (!event || !str(event.title)) return [];
+  const key = keyOf(event);
+  const id = str(event.id);
+  const mine = [];
+  for (const row of read(runtimeDir).values()) {
+    if (row.key !== key) continue;
+    if (row.scope === 'meeting' && !(id && row.event === id)) continue;
+    mine.push(row);
+  }
+  return mine.sort((a, b) => String(a.firstAt).localeCompare(String(b.firstAt))).map(view);
+}
+
+function append(runtimeDir, body, by) {
+  const bad = check(body);
+  if (bad) return { ok: false, error: bad };
+  if (!runtimeDir) return { ok: false, error: 'this server has no runtime folder, so the material cannot be saved' };
+  const op = body.op || 'add';
+  const scope = body.scope || 'meeting';
+  const item = cleanItem(body.item);
+  const line = { at: new Date().toISOString(), by: by || null, key: keyOf(body.event), series: body.event.series ? String(body.event.series) : null, event_title: str(body.event.title), scope, item };
+  if (scope === 'meeting') line.event = str(body.event.id);
+  if (op === 'remove') line.removed = true;
+  else {
+    if (str(body.topic)) line.topic = str(body.topic);
+    line.present = body.present === true && ['pmos-deck', 'slides', 'report'].includes(item.kind);
+    if (forMeeting(runtimeDir, body.event).length >= MAX_ITEMS && !read(runtimeDir).has(identity(line))) return { ok: false, error: 'a meeting holds at most ' + MAX_ITEMS + ' items' };
+  }
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  fs.appendFileSync(fileOf(runtimeDir), JSON.stringify(line) + '\n');
+  return { ok: true, items: forMeeting(runtimeDir, body.event) };
+}
+
+module.exports = { keyOf, read, forMeeting, append, check, classifyUrl, KINDS, PMOS_KINDS, LINK_KINDS, FILE };

package/workspace/lib/meeting-replay.js

@@ -0,0 +1,170 @@
+'use strict';
+/* meeting-replay.js — the pure join behind the meeting replay page (initiative meeting-material-replay, part 2).
+ *
+ *   build({ note, event?, stateLines?, frames?, audio?, topics?, now? }) → the replay
+ *
+ * The replay is Focus played back, so it joins three records PMOS already keeps and invents nothing:
+ *   the note       transcript lines (with who said them), decisions, next steps and questions, the audio's length
+ *   the Focus file <runtime>/focus/<note or event id>.jsonl, folded by lib/meeting-focus.js: topics, the stretches of talk, PMOS's notes
+ *   the shots      lib/notes-screen.js frames; a frame with `aside` truthy was set aside (it looked like another app) and is NEVER in the replay
+ *
+ * Every time is MEETING time in ms: 0 is where the recording starts, the same clock the audio, the transcript and the shots use
+ * (the audio's currentTime * 1000). `start_ms` is the wall clock (epoch ms) of meeting time 0, so the page can show 11:18.
+ *
+ * A KEY POINT'S TIME is the time of the transcript line it was caught from: the item's own `t` (the final notes and the minute
+ * bullets keep it), else the line its quote (or, failing that, its text) is found in. When none is known `t` is null and the page
+ * shows no play button. Nothing here reads a file or starts a process; lib/routes-meeting-replay.js reads and calls build().
+ *
+ * Output:
+ *   { ok, note: { id, title, state, initiative, ws }, meeting: { title, at, end, attendees },
+ *     audio: { url, ms } | null, start_ms, length_ms,
+ *     lines:  [{ i, t, who, text, source, key: { k, id } | null }]            by t
+ *     keys:   [{ id, k: 'decision'|'action'|'question', text, t, owner, due, by, state: 'draft'|'owner'|'open'|'answered', warn }]
+ *     topics: [{ id, text, src, state, minutes, n, first_t, stretches, parked, by }]   visited ones first, in the order they came up
+ *     runs:   [{ topic, n, from_ms, to_ms }]
+ *     notes:  [{ id, t, cat, body, heard, why, src }]                          PMOS's notes with the time they were made
+ *     shots:  [{ t, w, h, why?, text? }]                                       kept shots only
+ *     aside_count }
+ */
+const N = require('./notes.js');
+const F = require('./meeting-focus.js');
+
+const SHOT_TEXT_MAX = 400;
+const NEAR_LINE_MS = 3000;       // a key point whose time is not exactly a line's belongs to the line this close
+const ANSWER_OVERLAP = 0.6;
+
+const str = (v, n) => (typeof v === 'string' ? v.replace(/\s+/g, ' ').trim().slice(0, n) : '');
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+const words = (t) => String(t == null ? '' : t).toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').match(/[\p{L}\p{N}]+/gu) || [];
+const share = (a, b) => {
+  const wa = words(a); const hb = new Set(words(b));
+  return wa.length ? wa.filter((w) => hb.has(w)).length / wa.length : 0;
+};
+
+/** The wall clock (epoch ms) of meeting time 0: a transcript line's `at` minus its `t`, else when recording began, else the meeting's start. */
+function startOf(note, event) {
+  for (const x of (note && note.transcript) || []) {
+    const at = Date.parse(x && x.at);
+    if (x && finite(x.t) && Number.isFinite(at)) return at - x.t;
+  }
+  const rec = Date.parse(note && note.recorded_from);
+  if (Number.isFinite(rec)) return rec;
+  const ev = Date.parse(event && event.at);
+  return Number.isFinite(ev) ? ev : null;
+}
+
+/** The lines of the talk with a time: the final pass's segments when there are some, else the live lines; by t. */
+function linesOf(note) {
+  let raw = [];
+  try { raw = N.transcriptLines(note); } catch { raw = []; }
+  return raw.filter((x) => x && finite(x.t) && typeof x.text === 'string' && x.text.trim())
+    .map((x) => ({ t: Math.round(x.t), who: str(x.who, 60), text: str(x.text, 600), source: x.source || 'speech' }))
+    .sort((a, b) => a.t - b.t)
+    .map((x, i) => ({ i, ...x, key: null }));
+}
+
+/** The decisions, next steps and questions of the note, as the Notes page shows them: the final notes when written, else the minute
+ *  bullets, else the local summary. → { decision: [item], action: [item], question: [item] }, item = { text, quote?, t?, owner?, due?, by? } */
+function caughtOf(note) {
+  const out = { decision: [], action: [], question: [] };
+  const f = note && note.final_notes;
+  const fromList = (kind, list) => {
+    for (const x of Array.isArray(list) ? list : []) {
+      const text = str(x && x.text, 300);
+      if (text) out[kind].push({ text, quote: str(x.quote, 400), t: finite(x.t) ? x.t : null, owner: str(x.owner, 60) || null, due: str(x.due, 40) || null, by: str(x.by, 120) || null });
+    }
+  };
+  if (f && ((f.decisions || []).length || (f.actions || []).length || (f.questions || []).length)) {
+    fromList('decision', f.decisions); fromList('action', f.actions); fromList('question', f.questions);
+    return out;
+  }
+  const bl = ((note && note.bullets) || []).filter((b) => b && b.text && !b.dropped && !b.open);
+  if (bl.length) {
+    for (const b of bl) if (out[b.cat]) out[b.cat].push({ text: str(b.text, 300), quote: '', t: finite(b.t) ? b.t : null, owner: str(b.owner, 60) || null, due: str(b.due, 40) || null, by: null });
+    if (out.decision.length || out.action.length || out.question.length) return out;
+  }
+  const sec = (note && note.summary && note.summary.sections) || {};
+  const at = (x) => { const m = /^\s*\[?(\d+:\d{2}(?::\d{2})?)\]?\s*$/.exec(String((x && x.at) || '')); return m ? N.parseTime(m[1]) : null; };
+  const fromSec = (kind, list) => { for (const x of Array.isArray(list) ? list : []) { const text = str(x && x.text, 300); if (text) out[kind].push({ text, quote: '', t: at(x), owner: str(x.owner, 60) || null, due: str(x.due, 40) || null, by: null }); } };
+  fromSec('decision', sec.decisions); fromSec('action', sec.actions); fromSec('question', sec.questions);
+  return out;
+}
+
+/** The time of the line a key point was caught from: its own t, else the line its quote (or its text) is in; null when unknown. */
+function timeOfKey(item, lines) {
+  if (finite(item.t)) return Math.max(0, Math.round(item.t));
+  const timed = lines.map((l) => ({ t: l.t, text: l.text }));
+  for (const probe of [item.quote, item.text]) {
+    if (!probe) continue;
+    let at = null;
+    try { at = N.groundQuote(timed, probe, null); } catch { at = null; }
+    if (finite(at)) return Math.max(0, Math.round(at));
+  }
+  return null;
+}
+
+/** Join the three records. */
+function build({ note, event = null, stateLines = [], frames = [], audio = null, topics = [], now = Date.now() } = {}) {
+  const n = note || {};
+  const lines = linesOf(n);
+  const start = startOf(n, event);
+  const shots = (frames || []).filter((f) => f && finite(f.t) && !f.aside).sort((a, b) => a.t - b.t)
+    .map((f) => ({ t: f.t, w: f.w || 0, h: f.h || 0, ...(f.why ? { why: f.why } : {}), ...(f.text ? { text: str(f.text, SHOT_TEXT_MAX) } : {}) }));
+  const asideCount = (frames || []).filter((f) => f && f.aside).length;
+
+  // Focus's state: topics, stretches, PMOS's notes. Stretches are measured from meeting time 0.
+  const fold = F.foldState(stateLines || [], { topics, startMs: start, nowMs: start == null ? now : start + 0 });
+  const pmos = start == null ? [] : fold.notes.filter((x) => x && x.body && finite(x.at)).map((x) => ({ id: x.id, t: Math.max(0, Math.round(x.at - start)), cat: str(x.cat, 30), body: str(x.body, 700), heard: str(x.heard, 300), why: str(x.why, 300), src: str(x.src, 80) }))
+    .sort((a, b) => a.t - b.t);
+
+  // length: the audio, the clock of the note, else the last thing that has a time
+  let heard = 0;
+  if (n.ended_at || n.paused_at) { try { heard = N.heardMs(n, now) || 0; } catch { heard = 0; } }   // a note still recording has no end to trust
+  const caught = caughtOf(n);
+  const keys = [];
+  for (const [kind, list] of [['decision', caught.decision], ['action', caught.action], ['question', caught.question]]) {
+    list.forEach((it, i) => {
+      const t = timeOfKey(it, lines);
+      const answered = kind === 'question' && t != null && pmos.some((p) => p.cat === 'Answer' && p.t >= t && share(it.text, p.heard || p.body) >= ANSWER_OVERLAP);
+      const state = kind === 'action' ? (it.owner ? 'draft' : 'owner') : kind === 'question' ? (answered ? 'answered' : 'open') : 'draft';
+      keys.push({ id: kind[0] + (i + 1), k: kind, text: it.text, t, owner: it.owner, due: it.due, by: it.by, state, warn: state === 'owner' || state === 'open' });
+    });
+  }
+  keys.sort((a, b) => (a.t == null) - (b.t == null) || (a.t || 0) - (b.t || 0));
+  // the line a key point was caught from carries its mark
+  for (const k of keys) {
+    if (k.t == null || !lines.length) continue;
+    let best = null;
+    for (const l of lines) if (!l.key && (best === null || Math.abs(l.t - k.t) < Math.abs(best.t - k.t))) best = l;
+    if (best && Math.abs(best.t - k.t) <= NEAR_LINE_MS) best.key = { k: k.k, id: k.id };
+  }
+
+  const lastT = (xs) => xs.reduce((m, x) => (finite(x.t) && x.t > m ? x.t : m), 0);
+  const length = Math.max(finite(audio && audio.ms) ? audio.ms : 0, heard, lastT(lines), lastT(shots), lastT(keys), lastT(pmos));
+
+  // stretches, in ms; a stretch still open runs to the end
+  const runs = fold.runs.map((r) => ({ topic: r.topic, from_ms: Math.round(r.from_min * 60000), to_ms: r.to_min == null ? length : Math.round(r.to_min * 60000) }))
+    .filter((r) => r.to_ms > r.from_ms || r.to_ms === length);
+  const firstOf = new Map();
+  for (const r of runs) if (!firstOf.has(r.topic)) firstOf.set(r.topic, r.from_ms);
+  const visited = fold.topics.filter((t) => firstOf.has(t.id)).sort((a, b) => firstOf.get(a.id) - firstOf.get(b.id));
+  const numOf = new Map(visited.map((t, i) => [t.id, i + 1]));
+  const stretches = (id) => runs.filter((r) => r.topic === id).length;
+  const minutesOf = (id) => Math.round(runs.filter((r) => r.topic === id).reduce((s, r) => s + (r.to_ms - r.from_ms), 0) / 60000);
+  const topicRows = [...visited, ...fold.topics.filter((t) => !firstOf.has(t.id))].map((t) => ({
+    id: t.id, text: t.text, src: t.src, state: t.state, minutes: minutesOf(t.id), n: numOf.get(t.id) || null, first_t: firstOf.has(t.id) ? firstOf.get(t.id) : null,
+    stretches: stretches(t.id), parked: t.state === 'parked', by: t.by || null }));
+  const ev = event || {};
+  const m = n.meeting || {};
+  return {
+    ok: true,
+    note: { id: n.id, title: n.title || m.title || ev.title || 'Untitled note', state: n.state || null, initiative: n.initiative || null, ws: n.ws || (n.initiative && n.initiative.ws) || null },
+    meeting: { title: ev.title || m.title || n.title || 'Untitled note', at: ev.at || m.start || n.recorded_from || n.created_at || null, end: ev.end || m.end || null,
+      attendees: [].concat(ev.attendees || ev.people || []).map((p) => (p && typeof p === 'object' ? p.name || p.id : p)).filter(Boolean).map(String) },
+    audio: audio && audio.url ? { url: audio.url, ms: finite(audio.ms) ? audio.ms : null } : null,
+    start_ms: start, length_ms: length,
+    lines, keys, topics: topicRows, runs: runs.map((r) => ({ ...r, n: numOf.get(r.topic) || null })), notes: pmos, shots, aside_count: asideCount,
+  };
+}
+
+module.exports = { build, caughtOf, timeOfKey, linesOf, startOf };

package/workspace/lib/needs-providers.js

@@ -35,6 +35,7 @@ const PROVIDERS = Object.freeze([
   'report-needs',       // Run 5 (5C): a report to issue (kind 1), cycle rows (kind 7), a schedule left no output (kind 8)
   'driver-needs',       // initiative-driver: drafts the agent filed (kind 7), a target the PM is blocking (kind 7)
   'core-docs-needs',    // core-documents: one row per scope with core document drafts waiting for the PM (kind 1)
+  'report-structure-needs', // report-structure: a Chrome or computer source that failed its check while a draft waits for it (kind 8)
 ]);
 /** Kinds that already mean something in the needs queue. A provider may not reuse one. */
 const RESERVED_KINDS = Object.freeze(['question', 'accept', 'outcome', 'keep', 'evidence', 'plan-flag', 'provider-error']);