create-pmos 0.516.0 → 0.517.0

package/workspace/lib/report-export.js

@@ -332,6 +332,40 @@ function pyramidSlideXml(s, L) {
     let yy = y + (n ? 146 : 0);
     if (a.more) { text(67, yy, 1146, 60, a.more, { size: 18, color: L.soft }); yy += 70; }
     text(67, yy, 1146, 26, [[['Who ', { bold: true }], [a.who, {}], ...(a.by ? [['      By ', { bold: true }], [a.by, {}]] : [])]], { size: 18, color: L.soft });
+  } else if (s.kind === 'beyond') {
+    // the report engine's parts beyond the question: numbered, as the answer's supports
+    s.items.forEach((x, i) => {
+      const yy = y + i * 104;
+      if (i) shape(67, yy - 10, 1146, 1, { fill: L.line });
+      shape(67, yy, 35, 35, { geom: 'ellipse', fill: L.accent });
+      text(67, yy + 6, 35, 24, String(i + 1), { size: 18, bold: true, color: '#FFFFFF', align: 'ctr' });
+      text(121, yy, 1092, 30, x.head, { size: 22, bold: true });
+      text(121, yy + 32, 1092, 60, x.text, { size: 17, color: L.soft });
+    });
+  } else if (s.kind === 'section') {
+    // a section of an engine report: paragraphs and lists as text, a table as a grid, bars as shapes. Anything below the footer is cut, never squeezed.
+    for (const b of s.blocks || []) {
+      if (y > 600) break;
+      if (b.kind === 'p') { const h = Math.min(120, 26 * Math.ceil(b.text.length / 110) + 6); text(67, y, 1146, h, b.text, { size: 18, color: L.soft }); y += h + 10; }
+      else if (b.kind === 'list') { for (const it of b.items) { if (y > 620) break; text(67, y, 1146, 30, '•  ' + it, { size: 18, color: L.soft }); y += 34; } y += 8; }
+      else if (b.kind === 'table') {
+        const n = b.columns.length; const w = 1146 / n; const rowH = 40;
+        b.columns.forEach((c, i) => text(67 + i * w + 6, y, w - 12, 22, c.toUpperCase(), { size: 13, bold: true, color: L.muted }));
+        shape(67, y + 26, 1146, 2, { fill: '#D3CCBF' }); y += 34;
+        for (const r of b.rows) { if (y > 630) break; r.forEach((c, i) => text(67 + i * w + 6, y + 8, w - 12, 26, c, { size: 15, bold: i === 0 })); shape(67, y + rowH, 1146, 1, { fill: L.line }); y += rowH; }
+        y += 12;
+      } else if (b.kind === 'bars') {
+        for (const r of b.rows) {
+          if (y > 630) break;
+          text(67, y, 290, 26, r.label, { size: 17 });
+          shape(367, y + 4, 700, 18, { geom: 'roundRect', fill: L.track });
+          shape(367, y + 4, Math.max(1, 700 * r.share), 18, { geom: 'roundRect', fill: L.accent });
+          text(1083, y, 130, 26, r.text, { size: 17, bold: true, align: 'r' });
+          y += 36;
+        }
+        y += 10;
+      }
+    }
   } else if (s.kind === 'sources') {
     text(67, y, 540, 20, 'REACHED', { size: 15, bold: true, color: L.muted });
     (s.reached.length ? s.reached : ['None']).slice(0, 8).forEach((x, i) => text(67, y + 34 + i * 44, 540, 40, x, { size: 18, color: L.soft }));
@@ -480,7 +514,8 @@ function exportOf(markdown, fmt, opts = {}) {
   if (!Object.prototype.hasOwnProperty.call(FORMATS, fmt)) return { ok: false, error: `fmt must be one of ${Object.keys(FORMATS).join(', ')}` };
   const report = parseReport(markdown);
   let buffer;
-  try { buffer = fmt === 'pptx' ? pptx(report, require('./report-pyramid.js').deckOf(markdown, opts.look, { data: opts.data || null })) : BUILD[fmt](report); } catch (e) { return { ok: false, error: 'the file could not be built: ' + String((e && e.message) || e).slice(0, 160) }; }
+  // opts.deck: the report engine's deck (lib/report-engine.js engineDeckOf), so the PPTX holds the slides the reader shows
+  try { buffer = fmt === 'pptx' ? pptx(report, opts.deck || require('./report-pyramid.js').deckOf(markdown, opts.look, { data: opts.data || null })) : BUILD[fmt](report); } catch (e) { return { ok: false, error: 'the file could not be built: ' + String((e && e.message) || e).slice(0, 160) }; }
   const stem = plain(report.title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'report';
   return { ok: true, fmt, name: `${stem}.${fmt}`, mime: FORMATS[fmt].mime, buffer };
 }

package/workspace/lib/report-pyramid.js

@@ -460,6 +460,12 @@ function slideHtml(s, L) {
     const opts = a.options.map((o, i) => `<div class="ask${i ? ' alt' : ''}" style="flex:1"><div class="tag">Option ${'ABC'[i]}</div><div class="q">${esc(o)}</div></div>`).join('');
     body = (opts ? `<div style="display:flex;gap:26px">${opts}</div>` : '') + (a.more ? `<p class="sm" style="margin:${opts ? '22px' : '0'} 0 0">${esc(a.more)}</p>` : '')
       + `<div class="sm" style="display:flex;gap:45px;margin-top:29px"><span><b>Who</b> ${esc(a.who)}</span>${a.by ? `<span><b>By</b> ${esc(a.by)}</span>` : ''}</div>`;
+  } else if (s.kind === 'beyond') {
+    // the report engine's parts beyond the question (lib/report-engine.js deckOf): each part a numbered support
+    body = s.items.map((x, i) => `<div class="sup"><span class="n">${i + 1}</span><div><b>${esc(x.head)}</b><span>${esc(x.text)}</span></div></div>`).join('');
+  } else if (s.kind === 'section') {
+    // a section of an engine report: any title the writer chose, its blocks as they are (paragraphs, lists, a table, bars of readings)
+    body = (s.blocks || []).map((b) => sectionBlockHtml(b, L)).join('');
   } else if (s.kind === 'sources') {
     const reached = s.reached.map((x) => `<div class="sup"><span class="sm">${esc(x)}</span></div>`).join('') || '<div class="sup"><span class="sm">None</span></div>';
     const miss = s.notReached.map((x) => `<div class="sup"><div><b>${esc(x.source)}</b><span>${esc(cap(x.why))}${x.why ? '.' : ''}</span></div></div>`).join('');
@@ -467,6 +473,20 @@ function slideHtml(s, L) {
   }
   return open('') + `<div class="in">${head(s.tag)}${body}</div>${footer(s)}</section>`;
 }
+/** One block of an engine section slide. */
+function sectionBlockHtml(b, L) {
+  if (b.kind === 'p') return `<p class="sm" style="margin:0 0 14px;max-width:1120px">${esc(b.text)}</p>`;
+  if (b.kind === 'list') return `<div style="margin:0 0 10px">${b.items.map((x) => `<div class="sup" style="padding:9px 0"><span class="sm">${esc(x)}</span></div>`).join('')}</div>`;
+  if (b.kind === 'table') {
+    return `<div class="tb" style="grid-template-columns:repeat(${b.columns.length},minmax(0,1fr));font-size:16px;margin:0 0 14px;align-items:stretch">${b.columns.map((c) => `<div class="h">${esc(c)}</div>`).join('')}`
+      + b.rows.map((r) => r.map((c, i) => `<div${i ? '' : ' style="font-weight:800"'}>${esc(c)}</div>`).join('')).join('') + '</div>';
+  }
+  if (b.kind === 'bars') {
+    return `<div style="display:flex;flex-direction:column;gap:12px;margin:0 0 14px">${b.rows.map((r) => `<div style="display:flex;align-items:center;gap:16px;font-size:18px"><span style="width:300px;flex:none">${esc(r.label)}</span>`
+      + `<span style="flex:1;height:20px;background:${L.track};border-radius:4px;overflow:hidden"><i style="display:block;height:100%;width:${Math.round(r.share * 1000) / 10}%;background:${L.accent}"></i></span><b style="width:120px;flex:none;text-align:right">${esc(r.text)}</b></div>`).join('')}</div>`;
+  }
+  return '';
+}
 /** The deck as one HTML string (the viewer's frames and the PDF print). */
 function deckHtml(deck) {
   if (!deck) return '';

package/workspace/lib/routes-ready-reports.js

@@ -437,7 +437,9 @@ async function tickScope(ctx, w, s, now, cache = null) {
     const e = ensureSetup(w, s.scope, m.kind, s.name, { now });
     if (!e.ok) { out.push({ scope: s.scope, kind: m.kind, ok: false, error: e.error }); continue; }
     const r = await SR.draftIntelligence(ctx, w, e.setup, m.slot, { model: X.model, now, ready: extras(X) });
-    if (r.ok || r.existing) RR.append(RR.ledgerFile(stateDir(w)), { ev: 'moment', key, slot: m.slot, why: m.why }, { now });
+    if (r.ok || r.existing || r.quiet) RR.append(RR.ledgerFile(stateDir(w)), { ev: 'moment', key, slot: m.slot, why: m.why }, { now });
+    // nothing to report at this moment: one quiet line (Your day says it), no draft to grade
+    if (r.quiet) RR.append(RR.ledgerFile(stateDir(w)), { ev: 'quiet', key, slot: m.slot }, { now });
     out.push({ scope: s.scope, kind: m.kind, slot: m.slot, why: m.why, ...r });
   }
   // a heads-up: a broken health budget or a critical slip, at once and outside the schedule (PbG3)

package/workspace/lib/routes-report-design.js

@@ -49,6 +49,7 @@ const RS = require('./report-setups.js');
 const RC = require('./report-checks.js');
 const RDraft = require('./report-draft.js');
 const RP = require('./report-pyramid.js');
+const RE = require('./report-engine.js');
 const headless = require('./headless.js');
 
 const text = (v) => (typeof v === 'string' ? v : '');
@@ -293,6 +294,8 @@ function startCycle(ctx, w, cadence, rel) {
     const st = D.stateOf(w.root, cadence);
     if (!st.saved) return { ok: false, error: 'no saved design' };
     if (D.isIssuedSlot(w.root, cadence, c.slot)) return { ok: false, error: 'issued' };
+    // the report engine draws its own deck from report.json; the saved design is its theme, so no per-cycle render rewrites its words
+    if (RE.engineReportOf(c.md)) return { ok: false, error: 'drawn by the report engine' };
     const key = keyOf(w.root, cadence);
     if (jobs.has(key)) {
       const j = jobs.get(key);
@@ -436,7 +439,8 @@ function cycleAnswer(w, c) {
   const differences = rec && Array.isArray(rec.differences) ? rec.differences : [];
   // designed: THIS cycle has a render drawn to a saved design (the contract's answer is per document). A cycle drafted before the design,
   // or one whose first render is still running, is not designed yet: the page reads it in its format view and fetches no cycle-html.
-  return { ok: true, designed: !!st.saved && !!rec, design_version: rec ? rec.design_version : null,
+  const engine = !!RE.engineReportOf(c.md);
+  return { ok: true, designed: !engine && !!st.saved && !!rec, engine, design_version: rec ? rec.design_version : null,
     format: (rec && rec.format) || (st.saved && (D.versionMeta(w.root, c.cadence, st.saved.version) || {}).format) || st.format || 'deck',
     outline: rec && Array.isArray(rec.outline) ? rec.outline : [], differences, decisions: rec && Array.isArray(rec.decisions) ? rec.decisions : [],
     matches: !!rec && differences.length === 0, rendering: !!(j && j.slotPath === c.rel), previous: prev ? { path: prev.path, slot: prev.slot } : null };
@@ -482,7 +486,8 @@ async function handle(req, res, url, ctx) {
       // The finished slides of a cadence draft (canvas RsA): the Pyramid deck in the report's saved look, else the standard PMOS look.
       const d = reportDoc(w, text(url.searchParams.get('path'))); if (d.error) return send(d.error);
       let md; try { md = fs.readFileSync(d.c.md, 'utf8'); } catch { return send(bad(404, 'no such report document')); }
-      const deck = RP.deckOf(md, RP.lookOf(w.root, d.c.cadence), { data: RP.dataOf(d.c.md) });
+      // a draft the report engine wrote is drawn from its own model (report.json), in the report's look: the reader, the PDF and the PPTX are one deck
+      const deck = RE.engineDeckOf(d.c.md, RP.lookOf(w.root, d.c.cadence)) || RP.deckOf(md, RP.lookOf(w.root, d.c.cadence), { data: RP.dataOf(d.c.md) });
       if (!deck) return send(bad(404, 'this document is not a cadence draft, so it has no Pyramid deck'));
       return sendHtml(res, D.sanitize(RP.deckHtml(deck)));
     }

package/workspace/lib/routes-report-setups.js

@@ -254,7 +254,10 @@ async function tick(ctx, now = new Date()) {
         if (s.drafted.some((d) => d.slot === slot)) continue;
         let out;
         if (IR.isIntelligence(s.source)) {
+          const qk = `${w.root}|${s.id}|${slot}`;
+          if (quietSlots.has(qk)) continue;   // nothing to report at this slot already: not read again every tick
           try { out = await draftIntelligence({ ...ctx, getWs: (id) => (id === w.id || id == null ? w : ctx.getWs(id)) }, w, s, slot, { now }); } catch (e) { out = { ok: false, error: String((e && e.message) || e) }; }
+          if (out && out.quiet) quietSlots.add(qk);
           done.push({ id: s.id, slot, ...out });
           continue;
         }
@@ -293,7 +296,9 @@ function exportAnswer(ctx, res, w, url) {
   } catch { return bad(404, 'no such document'); }
   const cyc = /(?:^|\/)reports\/([a-z][a-z0-9-]{0,39})\/\d{4}-\d{2}-\d{2}\.md$/.exec(rel);
   const RPy = require('./report-pyramid.js');
-  const out = RX.exportOf(md, fmt, fmt === 'pptx' && cyc ? { look: RPy.lookOf(abs, cyc[1]), data: RPy.dataOf(full) } : {});
+  const look = fmt === 'pptx' && cyc ? RPy.lookOf(abs, cyc[1]) : null;
+  const deck = look ? require('./report-engine.js').engineDeckOf(full, look) : null;
+  const out = RX.exportOf(md, fmt, fmt === 'pptx' && cyc ? { look, data: RPy.dataOf(full), ...(deck ? { deck } : {}) } : {});
   if (!out.ok) return bad(500, out.error);
   return { status: 200, file: out };
 }
@@ -563,6 +568,8 @@ async function draftIntelligence(ctx, w, s, slot, { model, now = new Date(), rea
   try { if (fs.statSync(path.join(path.resolve(w.root), rel)).isFile()) return { ok: false, existing: true, slot, path: rel, error: 'drafted already' }; } catch { /* not there yet */ }
   const m = model || await intelModel(null, ctx, w.id, null);
   if (!m) return { ok: false, error: 'Intelligence could not be read' };
+  // no draft without a finding (design R item 2, report engine E step 3): a scope with no reading, no verdict and no read budget has nothing to report
+  if (!hasFinding(m, s)) return { ok: false, quiet: true, status: 422, slot, error: 'nothing to report: no goal here has a reading yet' };
   const mine = (RN.reportsOf(w.root).reports || []).filter((x) => x.cadence === s.id && x.slot < slot).sort((a, b) => (a.slot < b.slot ? -1 : 1));
   const before = mine.filter((x) => x.issued).pop() || null;
   let prior = null;
@@ -572,6 +579,14 @@ async function draftIntelligence(ctx, w, s, slot, { model, now = new Date(), rea
   return r.ok ? { ok: true, slot, path: r.path } : { ok: false, status: r.status, error: r.error };
 }
 
+/** The slots of Intelligence reports that had nothing to report, in this process: the tick does not read them again. */
+const quietSlots = new Set();
+/** True when Intelligence holds something to report for the setup's scope: a reading on a goal or budget, or a recorded verdict. */
+function hasFinding(model, setup) {
+  const scope = IR.scopeOf(setup && setup.source) || 'view';
+  const sl = IR.storylineOf(model, { scope });
+  return sl.items.some((it) => it.kind === 'scorecard' || it.kind === 'exhibit' || it.kind === 'verdict');
+}
 /** Draft a report's cycle now through the one writer (report-draft.js writeDraft). → { slot, path } | { error } */
 function draftCycle(root, cadence, slot, actor) {
   const d = RD.draftOf(root, { cadence, slot: slot || undefined });
@@ -587,4 +602,4 @@ function firstDraft(root, r, actor) {
   return draftCycle(root, r.setup.id, r.first_draft && r.first_draft.slot, actor);
 }
 
-module.exports = { prefixes: ['/api/report-setups', '/api/report-documents', '/api/report-export'], handle, tick, ensureMigrated, documentsOf, listAnswer, copyOf, draftIntelligence, intelModel };
+module.exports = { prefixes: ['/api/report-setups', '/api/report-documents', '/api/report-export'], handle, tick, ensureMigrated, documentsOf, listAnswer, copyOf, draftIntelligence, intelModel, hasFinding };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.516.0",
+  "version": "0.517.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.516.0",
+      "version": "0.517.0",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/sdk": "^1.3.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.516.0",
+  "version": "0.517.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/cozy-evui.js

@@ -23,6 +23,7 @@ export const ICON = {
   refresh: 'M4 12a8 8 0 0 1 14-5.3M20 4v4h-4M20 12a8 8 0 0 1-14 5.3M4 20v-4h4', jira: 'M4 4h16v16H4zM8.5 12.5l2.5 2.5 4.5-5', cal: 'M4 5h16v15H4zM4 10h16M8 3v4M16 3v4',
   repo: 'M6 3h12v18l-6-4-6 4z', mic: 'M12 3a3 3 0 0 0-3 3v6a3 3 0 0 0 6 0V6a3 3 0 0 0-3-3zM5 11a7 7 0 0 0 14 0M12 18v3', tools: 'M3 6h18v12H3zM3 7l9 6 9-6',
   analytics: 'M4 20V10M10 20V4M16 20v-8M22 20H2', check: 'M5 12l4.5 4.5L19 7',
+  guide: 'M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18M9.5 9.5a2.5 2.5 0 1 1 3.5 2.3c-.6.3-1 .9-1 1.6v.6M12 17h.01',
 };
 export function toast(t) { const el = typeof document !== 'undefined' && document.getElementById('toast'); if (!el) return; el.textContent = t; el.classList.add('on'); clearTimeout(toast.t); toast.t = setTimeout(() => el.classList.remove('on'), 4200); }
 export const wsParam = () => (typeof location !== 'undefined' ? new URLSearchParams(location.search).get('ws') || '' : '');

package/workspace/public/pm/cozy-nav.js

@@ -3,12 +3,13 @@
  * item 5, canvas FmA1Menu and FmA4Desk: fewer menus).
  *
  * One button, bottom left on desktop and bottom right on a phone, opens the menu: the three places, Home, Board and Intelligence; then a
- * tray of two icons, Search (⌘K on a desk) and Settings. It is the one way between places, and it holds nothing else: New for you is a fold
+ * tray of three icons, Search (⌘K on a desk), Guide and Settings. It is the one way between places, and it holds nothing else: New for you is a fold
  * in Your day, Sources are Settings › Connectors, Theme is Settings › General, and More is gone (feedback batch 16 item 5).
  * The button keeps its two dots on every page: blue when something is new for you, amber when a source is stale. Open, the blue dot sits on
  * the Home row (where Your day is) and the amber dot on the Settings icon; the button's own name says both ("Open the menu. 3 new for you.
  * Jira is stale.").
  *   Search       pm/cozy-search.js: across the repository and every worktree; Ctrl K (Cmd K) or "/" opens it from any page
+ *   Guide        pm/premium-vw-guide.js: the user guide's Start here, in the Viewer of the page you are on (initiative guide-in-app)
  *   Settings     pm/cozy-settings.js; it opens at Connectors while a source is stale, so the stale one is the first thing there
  * A page that passes opts.here() runs it when its own place is pressed, in place of a reload (Home: Menu > Home closes the page that is open).
  * The counts come from GET /api/news-for-you and GET /api/sources, read when the page opens and every two minutes while it is shown; each
@@ -55,6 +56,7 @@ export function menuHtml(here, o = {}) {
   }).join('')
     + '<div class="ev-tray">'
     + `<button type="button" class="ev-tb" data-cz-search aria-label="Search (⌘K)" title="Search ⌘K">${svg(ICON.search, 20)}</button>`
+    + `<button type="button" class="ev-tb" data-cz-guide aria-label="Guide" title="Guide">${svg(ICON.guide, 20)}</button>`
     + `<button type="button" class="ev-tb" data-cz-settings aria-label="Settings${o.stale ? '. ' + esc(o.stale.text) : ''}" title="Settings">${svg(ICON.settings, 20)}${o.stale ? dot('risk') : ''}</button>`
     + '</div>';
 }
@@ -116,6 +118,7 @@ export function mountNav(here, doc = document, opts = {}) {
     set(false);
     if ('czSearch' in b.dataset) import('./cozy-search.js').then((M) => M.openSearch(opts.search ? { go: opts.search() } : {}));
     // a stale source opens Settings at Connectors, the stale one first (FmA3Settings: open where it matters)
+    else if ('czGuide' in b.dataset) import('./premium-vw-open.js').then((M) => M.openGuide('index'));
     else if ('czSettings' in b.dataset) import('./cozy-settings.js').then((M) => M.openSettings(N.stale ? 'connectors' : undefined));
   });
   // Ctrl K (Cmd K) and "/" open Search from any page; a second press focuses it

package/workspace/public/pm/premium-vw-guide.css

@@ -0,0 +1,36 @@
+/* premium-vw-guide.css — the guide in the Viewer (premium-vw-guide.js; canvas Exploring › User guide, option B): a page rail on the left,
+ * the page on the right with its section chips. Under 720 px the rail hides and the list icon shows it over the page. Quiet: hairlines, one
+ * well for the open page, no colour but the chips' hover. */
+.vwdoc.gd{padding:0}
+.gd-wrap{container-type:inline-size;display:flex;align-items:flex-start;gap:20px;position:relative}
+.gd-rail{width:248px;flex:none;position:sticky;top:0;max-height:calc(100vh - 140px);overflow:auto;padding:4px 4px 16px 0;display:flex;flex-direction:column;gap:2px}
+.gd-read{flex:1;min-width:0}
+.gd-tog{display:none}
+.gd-find{display:flex;align-items:center;gap:8px;height:40px;padding:0 10px;margin:0 0 6px;border-radius:10px;background:var(--well);color:var(--ink-3)}
+.gd-find .i{width:16px;height:16px;fill:none;stroke:currentColor;stroke-width:1.8;stroke-linecap:round;flex:none}
+.gd-find input{flex:1;min-width:0;border:0;background:transparent;color:var(--ink);font:var(--fw-regular) var(--fs-body)/var(--lh-body) var(--sans);outline:none;box-shadow:none}
+.gd-find input:focus,.gd-find input:focus-visible{outline:none}
+.gd-find:focus-within{outline:2px solid var(--ember);outline-offset:1px}
+.gd-grp summary{list-style:none;cursor:pointer;padding:8px 8px 4px;color:var(--ink-3);font:var(--fw-strong) var(--fs-meta)/var(--lh-meta) var(--sans);border-radius:6px}
+.gd-grp summary::-webkit-details-marker{display:none}
+.gd-grp summary::after{content:"";display:inline-block;width:6px;height:6px;margin-left:8px;border-right:1.5px solid currentColor;border-bottom:1.5px solid currentColor;transform:translateY(-2px) rotate(45deg)}
+.gd-grp:not([open]) summary::after{transform:translateY(0) rotate(-45deg)}
+.gd-grp summary:focus-visible{outline:2px solid var(--ember);outline-offset:1px}
+.gd-grp ul{list-style:none;margin:0;padding:0}
+.gd-grp a{display:block;padding:5px 8px;border-radius:6px;color:var(--ink-2);text-decoration:none;font:var(--fw-regular) var(--fs-meta)/var(--lh-meta) var(--sans)}
+.gd-grp a:hover{background:var(--well);color:var(--ink)}
+.gd-grp a[aria-current="page"]{background:var(--well);color:var(--ink);font-weight:var(--fw-strong)}
+.gd-grp a:focus-visible{outline:2px solid var(--ember);outline-offset:1px}
+.gd-rail [hidden]{display:none}
+.gd-none{margin:8px;color:var(--ink-3);font:var(--fw-regular) var(--fs-meta)/var(--lh-meta) var(--sans)}
+.gd-secs{display:flex;flex-wrap:wrap;gap:6px;margin:0 0 12px}
+.gd-chip{display:inline-flex;align-items:center;min-height:32px;padding:0 12px;border-radius:999px;background:var(--well);color:var(--ink-2);text-decoration:none;font:var(--fw-regular) var(--fs-meta)/var(--lh-meta) var(--sans)}
+.gd-chip:hover{color:var(--ink)}
+.gd-chip[hidden]{display:none}
+.gd-more{border:0;cursor:pointer;color:var(--ink-3)}
+.gd-chip:focus-visible{outline:2px solid var(--ember);outline-offset:1px}
+@container (max-width: 720px){
+  .gd-rail{display:none}
+  .gd-tog{display:flex}
+  .gd-railon .gd-rail{display:flex;position:absolute;z-index:3;top:64px;left:0;right:0;width:auto;max-height:70vh;padding:12px;border:1px solid var(--hair);border-radius:14px;background:var(--card-solid);box-shadow:var(--card-shadow)}
+}

package/workspace/public/pm/premium-vw-guide.js

@@ -0,0 +1,137 @@
+/* pm/premium-vw-guide.js — the user guide, read in the Viewer (initiative guide-in-app; canvas Exploring › User guide, option B, Wawan 2026-11-03).
+ *
+ * The guide ships with the app (workspace/guide/*.md, GET /api/guide). The menu's Guide icon (cozy-nav.js) opens its start page here, and
+ * /premium-viewer.html?open=guide&page=<name> opens any page on its own. The guide opens wide (the Viewer's wide mode) unless the PM set a width
+ * for it before.
+ *   Rail      every page, grouped by Start here's own headings, with Find a page on top; the open page is marked; a group folds and stays folded.
+ *   Page      the title, then one chip per section (a press scrolls there), then the text. A link to another guide page opens that page in the same
+ *             Viewer card as a drill-in, so ← comes back. A link to a repository file is drawn as text.
+ *   Narrow    under 720 px (a phone, or a narrow Viewer) the rail hides; the list icon beside the title shows it over the page.
+ * Nothing here writes, except the folded groups, kept in this browser.
+ *   openGuide(page = 'index') -> the pane
+ *   guideHtml(name, text, groups) -> the page as html (pure)
+ *   guideLinks(md)            -> the markdown with each link to a guide page rewritten to #guide:<name> (pure)
+ *   contentsOf(indexMd)       -> [{ group, pages: [{ page, title }] }] from Start here's headings and links (pure) */
+import { vwOpen, vwStyle } from './premium-viewer.js';
+import { drill, wide, widthOf } from './cozy-viewer.js';
+import { bodyHtml, pageHead, splitDoc, readMinutes } from './premium-vw-doc-model.js';
+
+const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const TOC_ICON = '<svg class="i" viewBox="0 0 24 24" aria-hidden="true"><path d="M9 6h11M9 12h11M9 18h11M4 6h.01M4 12h.01M4 18h.01"/></svg>';
+const FIND_ICON = '<svg class="i" viewBox="0 0 24 24" aria-hidden="true"><path d="M11 4a7 7 0 1 0 0 14a7 7 0 1 0 0-14M20 20l-4-4"/></svg>';
+const FOLD_KEY = 'pmos.guide.folded';
+const CHIPS = 6;
+let TOC = null;   // the groups, read once from Start here
+
+const store = { get() { try { return JSON.parse(localStorage.getItem(FOLD_KEY) || '[]'); } catch { return []; } }, set(v) { try { localStorage.setItem(FOLD_KEY, JSON.stringify(v)); } catch { /* a private window */ } } };
+
+/** Start here's groups: each ## or ### heading from "Read next" on, with the guide pages its list links, in order. A page linked twice keeps its first place. */
+export function contentsOf(md) {
+  const out = [], seen = new Set(['index']); let cur = null, on = false;
+  for (const l of String(md || '').replace(/\r/g, '').split('\n')) {
+    const h = /^#{2,3}\s+(.*)$/.exec(l);
+    if (h && /^Read next$/i.test(h[1].trim())) { on = true; cur = null; continue; }
+    if (h && on) { cur = { group: h[1].trim(), pages: [] }; out.push(cur); continue; }
+    if (!cur) continue;
+    for (const m of l.matchAll(/\[([^\]]+)\]\(([a-z0-9][a-z0-9-]*)\.md\)/g)) if (!seen.has(m[2])) { seen.add(m[2]); cur.pages.push({ page: m[2], title: m[1] }); }
+  }
+  return [{ group: 'Start here', pages: [{ page: 'index', title: 'Start here' }] }, ...out.filter((g) => g.pages.length)];
+}
+
+/** The rail: Find a page, then every page by group, the open one marked. folded: the group names kept folded. */
+export function railHtml(name, groups, folded = []) {
+  return '<nav class="gd-rail" aria-label="Guide pages">'
+    + `<div class="gd-find">${FIND_ICON}<input type="search" placeholder="Find a page" aria-label="Find a page" autocomplete="off" data-gd-find></div>`
+    + (groups || []).map((g) => {
+      const here = g.pages.some((x) => x.page === name), open = here || !folded.includes(g.group);
+      return `<details class="gd-grp" data-gd-grp="${esc(g.group)}"${open ? ' open' : ''}><summary>${esc(g.group)}</summary><ul>`
+        + g.pages.map((x) => `<li><a href="#guide:${esc(x.page)}"${x.page === name ? ' aria-current="page"' : ''} data-gd-t="${esc(x.title.toLowerCase())}">${esc(x.title)}</a></li>`).join('')
+        + '</ul></details>';
+    }).join('')
+    + '<p class="gd-none" data-gd-none hidden>No page has that name.</p></nav>';
+}
+
+/** Each markdown link to a guide page (`[x](layout.md)`, `[x](layout.md#keys)`) becomes `[x](#guide:layout)`, which the page model keeps as a link. */
+export const guideLinks = (md) => String(md || '').replace(/\]\(([a-z0-9][a-z0-9-]*)\.md(?:#[^)\s]*)?\)/g, '](#guide:$1)');
+
+/** One guide page: the rail, then the page with its title, its section chips, the text and a quiet footer. */
+export function guideHtml(name, text, groups = TOC, folded = []) {
+  const t = guideLinks(text), h = pageHead(t), sd = splitDoc(t);
+  const b = bodyHtml([sd.pre, ...sd.sections.map((s, n) => (n === 0 && h.h1 ? s.body : s.head + '\n' + s.body))].join('\n'));
+  const secs = b.heads.filter((x) => x[0] === 2);
+  // At most 6 chips show; the rest wait behind "N more", so a long page does not open on a wall of chips.
+  const chip = ([, s, id], n) => `<a href="#${esc(id)}" class="gd-chip" data-gd-jump="${esc(id)}"${n >= CHIPS ? ' hidden' : ''}>${esc(s)}</a>`;
+  const more = secs.length > CHIPS ? `<button type="button" class="gd-chip gd-more" data-gd-more>${secs.length - CHIPS} more</button>` : '';
+  const chips = secs.length > 1 ? `<div class="gd-secs" role="group" aria-label="On this page">${secs.map(chip).join('')}${more}</div>` : '';
+  const home = name === 'index' ? '' : '<span class="gap"></span><a href="#guide:index">Start here</a>';
+  return `<div class="vwdoc gd"><div class="gd-wrap">${railHtml(name, groups || [], folded)}`
+    + `<article class="cf vwfile gd-read"><header class="cfh vwfh"><h1 class="cft">${esc(h.title || name)}</h1>`
+    + `<div class="vwacts gd-tog"><button type="button" class="vwib" data-gd-toc aria-label="Guide pages" title="Guide pages" aria-expanded="false">${TOC_ICON}</button></div></header>`
+    + chips
+    + `<div class="cfb">${b.html || '<p class="vwmut">This page has no text yet.</p>'}</div>`
+    + `<footer class="cff"><span>Guide · ${readMinutes(text)} min read</span>${home}</footer></article></div></div>`;
+}
+
+const failHtml = (why) => `<div class="vwdoc"><div class="vwfnone" role="status"><b>The guide page could not be shown</b><p class="vwmut">${esc(why)}</p></div></div>`;
+
+async function read(name) {
+  try {
+    const r = await fetch('/api/guide?page=' + encodeURIComponent(name), { credentials: 'same-origin' });
+    return r.ok ? { ok: true, text: await r.text() } : { ok: false, why: 'There is no guide page called ' + name + '.' };
+  } catch { return { ok: false, why: 'The workspace server did not answer.' }; }
+}
+
+function wire(el) {
+  const wrap = () => el.querySelector('.gd-wrap'), btn = () => el.querySelector('[data-gd-toc]');
+  const show = (on) => { const w = wrap(), b = btn(); if (!w || !b) return; w.classList.toggle('gd-railon', on); b.setAttribute('aria-expanded', String(on)); if (on) { const f = w.querySelector('[data-gd-find]'); if (f) f.focus(); } };
+  el.addEventListener('input', (e) => {
+    if (!e.target.matches('[data-gd-find]')) return;
+    const q = e.target.value.trim().toLowerCase(), r = el.querySelector('.gd-rail'); let any = false;
+    r.querySelectorAll('details.gd-grp').forEach((d) => {
+      let n = 0; d.querySelectorAll('li').forEach((li) => { const hit = !q || li.firstChild.dataset.gdT.includes(q); li.hidden = !hit; if (hit) n++; });
+      d.hidden = !n; if (q && n) d.open = true; if (n) any = true;
+    });
+    r.querySelector('[data-gd-none]').hidden = any;
+  });
+  el.addEventListener('toggle', (e) => {
+    const d = e.target; if (!d.matches || !d.matches('details.gd-grp') || el.querySelector('[data-gd-find]').value) return;
+    const k = d.dataset.gdGrp, f = store.get().filter((x) => x !== k);
+    if (!d.open) f.push(k);
+    store.set(f);
+  }, true);
+  el.addEventListener('keydown', (e) => { if (e.key === 'Escape' && wrap() && wrap().classList.contains('gd-railon')) { e.stopPropagation(); show(false); btn().focus(); } });
+  el.addEventListener('click', (e) => {
+    if (e.target.closest('[data-gd-toc]')) { show(!wrap().classList.contains('gd-railon')); return; }
+    const m = e.target.closest('[data-gd-more]');
+    if (m) { m.parentElement.querySelectorAll('.gd-chip[hidden]').forEach((c) => { c.hidden = false; }); m.remove(); return; }
+    const j = e.target.closest('[data-gd-jump]');
+    if (j) { e.preventDefault(); const h = el.querySelector('#' + CSS.escape(j.dataset.gdJump)); if (h) h.scrollIntoView({ block: 'start', behavior: 'smooth' }); return; }
+    const a = e.target.closest('a'); if (!a) return;
+    const href = a.getAttribute('href') || '';
+    const g = /^#guide:([a-z0-9-]+)$/.exec(href);
+    if (g) { e.preventDefault(); drill(); openGuide(g[1]); return; }
+    if (href === '#') e.preventDefault();   // a link to a repository file: the page model drew it without a target
+  });
+}
+
+/** Open a guide page in the Viewer. */
+export function openGuide(page = 'index') {
+  const name = NAME.test(String(page || '')) ? String(page) : 'index';
+  vwStyle('doc'); vwStyle('guide');
+  const id = 'guide:' + name;
+  let pane = null, done = null;
+  pane = vwOpen({ id, kind: 'Guide', title: 'Guide', icon: 'doc', url: '/premium-viewer.html?open=guide&page=' + name,
+    render: (el) => { el.innerHTML = done || '<div class="vwdoc"><p class="vwmut" role="status">Opening the guide.</p></div>'; wire(el); } });
+  try { if (!widthOf('Guide')) wide(true); } catch { /* a page with no cozy Viewer */ }
+  const toc = TOC ? Promise.resolve() : read('index').then((r) => { if (r.ok) TOC = contentsOf(r.text); });
+  Promise.all([read(name), toc]).then(([r]) => {
+    done = r.ok ? guideHtml(name, r.text, TOC, store.get()) : failHtml(r.why);
+    const el = document.querySelector(`.obody.vw[data-vw="${CSS.escape(id)}"]`) || pane;
+    if (el && el.isConnected) {
+      el.innerHTML = done; el.scrollTop = 0;
+      const cur = el.querySelector('.gd-rail [aria-current="page"]'); if (cur) cur.scrollIntoView({ block: 'nearest' });
+    }
+  });
+  return pane;
+}

package/workspace/public/pm/premium-vw-open.js

@@ -8,6 +8,7 @@
  *   openReport(idOrRow, { ws, name, cycles, onIssue, onChange })   a report path reports/<cadence>/<date>.md or a Reports card row
  *   newNote(ws | { ws })           starts an untitled note now and opens it, recording
  *   makeWorkItem(noteId, step)     Becomes V.4: a ticket drafted in PMOS from a next step (never pushed to Jira here)
+ *   openGuide(page)                a page of the user guide (workspace/guide/<page>.md); no page: Start here
  * The modules load on first use (dynamic import), so this file has no import cycle with the view modules that import it.
  * It also adds the Viewer's style sheet (cozy-vw.css) to the page once. */
 
@@ -19,6 +20,7 @@ export function vzStyle() {
 const mtg = () => import('./premium-vw-mtg.js');
 const cal = () => import('./premium-vw-cal.js');
 const rep = () => import('./premium-report-read.js');
+const gd = () => import('./premium-vw-guide.js');
 const plain = (o) => (o && typeof o === 'object' && !o.openDlg && !o.$ ? o : {});   // an old caller passed the shell's deps
 
 export async function openMeeting(ref, o = {}) { vzStyle(); return (await mtg()).openMeeting(ref, plain(o)); }
@@ -27,8 +29,9 @@ export async function openNotes(o = {}) { vzStyle(); return (await cal()).openNo
 export async function openReport(ref, o = {}) { vzStyle(); return (await rep()).openReportView(ref, plain(o)); }
 export async function newNote(o) { vzStyle(); return (await mtg()).newNote(typeof o === 'string' ? o : (o && o.ws) || ''); }
 export async function makeWorkItem(noteId, step) { return (await mtg()).workItem(noteId, step); }
+export async function openGuide(page) { vzStyle(); return (await gd()).openGuide(page); }
 
-export const views = { openMeeting, openCalendar, openNotes, openReport, newNote, makeWorkItem };
+export const views = { openMeeting, openCalendar, openNotes, openReport, newNote, makeWorkItem, openGuide };
 if (typeof window !== 'undefined') {
   window.czViews = Object.assign(window.czViews || {}, views);
   window.pmViewer = window.czViews;

package/workspace/public/pm/premium-vw-page.js

@@ -1,6 +1,6 @@
 /* pm/premium-vw-page.js — /premium-viewer.html: opens the item its address names in the Viewer card (initiative premium-agreed-design).
  *   ?open=meeting&note=<id> | &event=<id>&date=YYYY-MM-DD   ?open=calendar[&tab=notes][&date=]   ?open=notes[&initiative=]
- *   ?open=report&path=reports/<cadence>/<date>.md            each with an optional &ws=
+ *   ?open=report&path=reports/<cadence>/<date>.md            ?open=guide[&page=<name>]   each with an optional &ws=
  * Closing the card leaves a line that links to Home. An address that names nothing says so. */
 import { views } from './premium-vw-open.js';
 import { onChange } from './cozy-viewer.js';
@@ -13,4 +13,5 @@ if (what === 'meeting') views.openMeeting(q.get('note') ? { note: q.get('note')
 else if (what === 'calendar') views.openCalendar({ ws, tab: q.get('tab') === 'notes' ? 'notes' : 'cal', date: q.get('date') || '' });
 else if (what === 'notes') views.openNotes({ ws, initiative: q.get('initiative') || '' });
 else if (what === 'report' && q.get('path')) views.openReport(q.get('path'), { ws });
+else if (what === 'guide') views.openGuide(q.get('page') || 'index');
 else gone.hidden = false;

package/workspace/run-tests.js

@@ -498,6 +498,12 @@ function traceChanges(changes, ctx) {
     }
     if (/^(guide|docs)\/|\.md$/.test(f)) continue; // prose: no suite asserts on it except guide.test.js, a unit suite
     if (f === 'test-timings.json') continue; // run order only: no suite reads it
+    if (/^skills\/[^/]+\.skill$/.test(f) && get(f) != null) {
+      // a built-in skill is prose an agent reads: a suite reads it by its name, or loads the whole folder
+      nameHits(f).forEach((s) => picked.add(s));
+      for (const s of list) if (/\b(loadDir|readdirSync)\(path\.join\(__dirname, 'skills'\)/.test(get(s) || '')) picked.add(s);
+      continue;
+    }
     let why = null;
     const before = picked.size;
     if (get(f) == null) { // removed: only the names in the suites can say who used it

package/workspace/skills/report-biweekly.skill

@@ -23,6 +23,13 @@ Rules that always hold (D71):
 7. THE SCRIPT WRITES EVERY NUMBER. In a note you type none: no count, no ratio such as "7 of 12", no percentage, no date, no day count. If a sentence needs a number, write it without the number; the block above the note already shows it. A name is not a number: an initiative id, a file path and a note id may be written as they are.
 8. PROSE ONLY BETWEEN NOTE MARKERS. In the draft file, write only between a `<!-- pmos:note <id> -->` line and its `<!-- /pmos:note -->` line. Never edit, move or delete a marker or any line outside one. Never add a section to the file.
 
+THE REPORT ENGINE FIRST (design E). A new biweekly report is written with the report engine:
+- Run `pmos report make biweekly`. It derives the brief from the definition's purpose, audience and sources, reads every source PMOS reaches, and finds what changed since the last issue.
+- If it prints "No finding, so no draft", read the sources its gaps name and file their readings (`pmos report read biweekly --from <file>`). If there is still no finding, there is nothing to report: stop and say so in one line.
+- Otherwise follow `skills/report-write.skill` from its step 2: you choose the outline for the readers; every figure is a reading.
+- If `pmos report make biweekly` refuses because the definition names no purpose, use the procedure below.
+The procedure below is the older path: use it only when the engine refuses the brief, or for a change to a draft that has no `<slot>.report.json`.
+
 Procedure:
 1. Find the state directory: `pmos/state/` if it exists, otherwise `planning/`. Call it <state>.
 2. Read the definition: `<state>/reports/definitions/biweekly.md`.

package/workspace/skills/report-daily.skill

@@ -22,6 +22,13 @@ Rules that always hold (D71):
 6. THE PM'S DEFINITION RULES. The shape of this report is whatever the definition says. Do not substitute your own format.
 7. SHOW THE STEPS. Keep a TodoWrite list of the steps of the procedure below, one item each, and mark each one completed as you finish it. The PM's chat shows "3 of 5 done". If a source you need cannot be reached because its sign-in expired, end with a pmos-ask block: {"kind":"reach","what":"<the source>","why":"sign-in expired","need":"signin"}.
 
+THE REPORT ENGINE FIRST (design E). A new daily report is written with the report engine:
+- Run `pmos report make daily`. It derives the brief from the definition's purpose, audience and sources, reads every source PMOS reaches, and finds what changed since the last issue.
+- If it prints "No finding, so no draft", read the sources its gaps name and file their readings (`pmos report read daily --from <file>`). If there is still no finding, there is nothing to report: stop and say so in one line.
+- Otherwise follow `skills/report-write.skill` from its step 2: you choose the outline for the readers; every figure is a reading.
+- If `pmos report make daily` refuses because the definition names no purpose, use the procedure below.
+The procedure below is the older path: use it only when the engine refuses the brief, or for a change to a draft that has no `<slot>.report.json`.
+
 Procedure:
 1. Find the state directory: `pmos/state/` if it exists, otherwise `planning/`. Call it <state>.
 2. Read the definition: `<state>/reports/definitions/daily.md`.

package/workspace/skills/report-monthly.skill

@@ -22,6 +22,13 @@ Rules that always hold (D71):
 6. THE PM'S DEFINITION RULES. The shape of this report is whatever the definition says. Do not substitute your own format.
 7. SHOW THE STEPS. Keep a TodoWrite list of the steps of the procedure below, one item each, and mark each one completed as you finish it. The PM's chat shows "3 of 5 done". If a source you need cannot be reached because its sign-in expired, end with a pmos-ask block: {"kind":"reach","what":"<the source>","why":"sign-in expired","need":"signin"}.
 
+THE REPORT ENGINE FIRST (design E). A new monthly report is written with the report engine:
+- Run `pmos report make monthly`. It derives the brief from the definition's purpose, audience and sources, reads every source PMOS reaches, and finds what changed since the last issue.
+- If it prints "No finding, so no draft", read the sources its gaps name and file their readings (`pmos report read monthly --from <file>`). If there is still no finding, there is nothing to report: stop and say so in one line.
+- Otherwise follow `skills/report-write.skill` from its step 2: you choose the outline for the readers; every figure is a reading.
+- If `pmos report make monthly` refuses because the definition names no purpose, use the procedure below.
+The procedure below is the older path: use it only when the engine refuses the brief, or for a change to a draft that has no `<slot>.report.json`.
+
 Procedure:
 1. Find the state directory: `pmos/state/` if it exists, otherwise `planning/`. Call it <state>.
 2. Read the definition: `<state>/reports/definitions/monthly.md`.

package/workspace/skills/report-special.skill

@@ -13,6 +13,8 @@ output:
 
 /report-special — prepare a one-off report for THIS repository as a draft.
 
+THE REPORT ENGINE FIRST (design E). A one-off report is an ad hoc report of the engine: once the PM has said what it is for, follow `skills/report-write.skill` with an id you make from the topic (lower case, dashes) and the PM's question as `--ask`. You choose the outline; every figure is a reading. The procedure below is the older path: use it only when the engine refuses the brief.
+
 Rules that always hold (D71):
 1. DRAFT ONLY. You write a file in this repository. Never send, post, share, email, publish or upload the report anywhere; the PM does that.
 2. READ-ONLY on every source. Never send, reply, forward, post, comment, create, edit, transition, label, archive or delete anything in mail, chat, Jira, Confluence, calendar or any other source.

package/workspace/skills/report-template.skill

@@ -1,7 +1,7 @@
 ---
 name: report-template
 label: "Saved report (from its template)"
-description: "Prepare a saved report as a draft. The schedule's args name the template; the script writes every number, then this skill writes the notes between the markers. Never sends or posts."
+description: "Prepare a saved report as a draft with the report engine (pmos report make, then the report-write skill). The schedule's args name the template. Never sends or posts."
 run: agent
 agent: claude
 output:
@@ -23,6 +23,13 @@ Rules that always hold (D71):
 6. THE SCRIPT WRITES EVERY NUMBER. In a note you type no count, ratio, percentage or date.
 7. PROSE ONLY BETWEEN NOTE MARKERS. Write only between a `<!-- pmos:note <id> -->` line and its `<!-- /pmos:note -->` line. Never edit, move or delete a marker or any line outside one. Never add a section to the file.
 
+THE REPORT ENGINE FIRST (design E). A new cycle is written with the report engine, not with the note markers:
+- Run `pmos report make <id>` (the id is the schedule's args). It derives the brief from the template's purpose, audience and sources, and from a saved structure's purpose and questions, reads every source PMOS reaches, and finds what changed.
+- If it prints "No finding, so no draft", read the sources its gaps name and file their readings (`pmos report read <id> --from <file>`). If there is still no finding, there is nothing to report this cycle: stop and say so in one line. Do not draft a report about nothing.
+- Otherwise follow `skills/report-write.skill` from its step 2. The template's sections are the agreed outline only when the last issue was written by the engine; you choose the outline. A saved structure's charts are sources to read: file each value as a reading.
+- A change to a draft that has a `<slot>.report.json` is a change to that report.json: edit it and run `pmos report write <id> --slot <slot> --from <file>` again. A figure stays a reading.
+The procedure below is for a change to a draft written before the engine (a draft with note markers and no `<slot>.report.json`), and for a template whose engine brief is refused.
+
 Procedure:
 1. The template id is the schedule's `args`. It must match `^[a-z][a-z0-9-]{0,39}$`. If it is missing or does not match, stop and say which schedule has no valid template id.
 2. Find the state directory: `pmos/state/` if it exists, otherwise `planning/`. Call it <state>.

package/workspace/skills/report-weekly.skill

@@ -22,6 +22,13 @@ Rules that always hold (D71):
 6. THE PM'S DEFINITION RULES. The shape of this report is whatever the definition says. Do not substitute your own format.
 7. SHOW THE STEPS. Keep a TodoWrite list of the steps of the procedure below, one item each, and mark each one completed as you finish it. The PM's chat shows "3 of 5 done". If a source you need cannot be reached because its sign-in expired, end with a pmos-ask block: {"kind":"reach","what":"<the source>","why":"sign-in expired","need":"signin"}.
 
+THE REPORT ENGINE FIRST (design E). A new weekly report is written with the report engine:
+- Run `pmos report make weekly`. It derives the brief from the definition's purpose, audience and sources, reads every source PMOS reaches, and finds what changed since the last issue.
+- If it prints "No finding, so no draft", read the sources its gaps name and file their readings (`pmos report read weekly --from <file>`). If there is still no finding, there is nothing to report: stop and say so in one line.
+- Otherwise follow `skills/report-write.skill` from its step 2: you choose the outline for the readers; every figure is a reading.
+- If `pmos report make weekly` refuses because the definition names no purpose, use the procedure below.
+The procedure below is the older path: use it only when the engine refuses the brief, or for a change to a draft that has no `<slot>.report.json`.
+
 Procedure:
 1. Find the state directory: `pmos/state/` if it exists, otherwise `planning/`. Call it <state>.
 2. Read the definition: `<state>/reports/definitions/weekly.md`.