create-pmos 0.516.0 → 0.518.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/lib/routes-sources.js

@@ -5,7 +5,8 @@
  *                                              lib/harness-health.js of(): { level, line, issues } or null; all is the last Refresh all
  *                                              (lib/refresh-run.js allState) or null; derived is the content built from stored reads
  *                                              (refresh-run derived: the brief, core documents, the scan, and the reads each was built from).
- *                                              Each source row has a group: 'machine' (read on this machine) or 'connector'
+ *                                              Each source row has a group: 'machine' (read on this machine) or 'connector',
+ *                                              and `heal` while Claude repairs it by itself or it needs the PM (lib/source-heal.js view())
  *   POST /api/sources/refresh { ws, source } → { ok, source, started: 'rebuild'|'session', session? }
  *   POST /api/sources/refresh-all { ws }     → { ok, joined, started, already, failed, all }   every source that is on, then the
  *                                              Briefing from those reads (briefing-source-flow, slice 3); a press while one runs joins it
@@ -18,6 +19,7 @@
  */
 const guard = require('./pm-guard.js');
 const freshness = require('./freshness.js');
+const heal_ = require('./source-heal.js');
 
 function wsOf(ctx, id) {
   const w = ctx.getWs(id || '');
@@ -33,7 +35,9 @@ async function handle(req, res, url, ctx) {
     if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
     const w = wsOf(ctx, url.searchParams.get('ws'));
     if (!w) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
-    const sources = F.sources({ id: w.id, root: w.root, repoStateDir: repoStateDir(ctx, w) });
+    let heal = {}; try { heal = ctx.runtimeDir ? heal_.viewAll(ctx.runtimeDir) : {}; } catch { heal = {}; }
+    // self-heal (lib/source-heal.js): a row Claude is repairing, or that needs the PM, carries its repair
+    const sources = F.sources({ id: w.id, root: w.root, repoStateDir: repoStateDir(ctx, w) }).map((r) => (heal[r.id] ? { ...r, heal: heal[r.id] } : r));
     let health = null; try { health = ctx.health ? ctx.health() : null; } catch { health = null; }
     let all = null; try { all = ctx.refreshAllState ? ctx.refreshAllState() : null; } catch { all = null; }
     let derived = []; try { derived = ctx.refreshDerived ? ctx.refreshDerived(w.id) : []; } catch { derived = []; }

package/workspace/lib/source-heal.js

@@ -0,0 +1,140 @@
+'use strict';
+/* source-heal.js — Claude repairs a source that is behind by itself, and asks the PM only when the PM must act
+ * (feedback batch 26 item 7, Wawan 2026-11-03: "any issue with connection should self diagnose and resolve unless necessary for
+ * the user to take action").
+ *
+ *   diagnose(error, { result }) → cause    why a read failed: one of CAUSES' keys
+ *   step(x) → { h, start?, note?, tell? }   one tick for one source: what to do now, and its new repair record
+ *   view(h, name) → { state, cause, why, tried, action, attempts, next_at } | null   what /api/sources shows on the row
+ *   MAX · BACKOFF_MIN · CAUSES
+ *
+ * THE REPAIR. A source that is on and behind (stale, failed or never read) is read again by Claude, without a press. Attempt 1 starts
+ * at once; the next ones wait BACKOFF_MIN minutes (longer after a rate limit). After each attempt the cause is diagnosed from the
+ * run's end (the log's error), and a read that ended "done" while the source is still behind counts as failed ("saved nothing new"):
+ * a source is fresh only when a read proved it. A cause the PM must fix (a connector that is not connected, a sign-in that still
+ * fails after one more try) stops the repair at once; any other cause stops after MAX attempts. Then the record is `needs-you`,
+ * with the one action and what Claude tried. The schedule keeps running all the time, so a source the PM fixed turns fresh on its
+ * next read and the record becomes `repaired`.
+ *
+ * A source that is off is left alone (the PM chose it). A source that is read only on a press has no schedule to be past, so its
+ * one action is the press.
+ *
+ * PURE but for viewAll(dir), which reads <state>/source-heal.json for /api/sources (any server, not only the one that runs the
+ * schedules). lib/refresh-run.js holds the records, starts the reads, and writes each attempt to the refresh log (trigger 'repair',
+ * with the attempt and the last cause in its note).
+ */
+
+const MAX = 5;
+const BACKOFF_MIN = Object.freeze([0, 2, 10, 30, 120]);        // minutes before attempt n+1, by the attempts made so far
+const RATE_MIN = Object.freeze([0, 15, 60, 120, 240]);         // the same after a rate limit
+const KEEP_REPAIRED_MS = 24 * 3600 * 1000;                     // a repaired record is kept this long, then dropped
+
+const CONNECTORS = 'https://claude.ai/settings/connectors';
+/* cause → why (the words after "because"), user: the PM must act, after: attempts before that is sure (1 = the first failure tells) */
+const CAUSES = Object.freeze({
+  'claude-signin': { why: 'Claude is signed out on this computer', user: true, after: 2 },
+  'connector-missing': { why: 'its connector is not connected', user: true, after: 1 },
+  'sign-in': { why: 'its sign-in has expired', user: true, after: 2 },
+  'rate-limit': { why: 'it asked Claude to slow down', user: false },
+  network: { why: 'the network or the proxy did not answer', user: false },
+  'connector-failed': { why: 'its connector did not start', user: false },
+  interrupted: { why: 'the read was stopped before it ended', user: false },
+  empty: { why: 'the read ended but saved nothing new', user: false },
+  skill: { why: 'the read stopped with an error', user: false },
+  manual: { why: 'it is read only when you press ↻', user: true, after: 0 },
+});
+
+/** Why a read failed, from the error its run ended with. The order matters: Claude's own sign-in first, then a missing connector. */
+function diagnose(error, { result } = {}) {
+  const e = String(error || '').toLowerCase();
+  if (result === 'done') return 'empty';
+  if (/claude is signed out|not logged in|please run \/login|type \/login|invalid api key/.test(e)) return 'claude-signin';
+  if (/not connected|connector (is )?(missing|not (found|installed|available|configured|enabled))|no (\w+ )?(connector|mcp server)|no such tool|tools? .{0,40}not (available|found)|mcp server .{0,40}not (found|configured)/.test(e)) return 'connector-missing';
+  if (/\b429\b|rate.?limit|too many requests|quota|throttl/.test(e)) return 'rate-limit';
+  if (/\b401\b|unauthori[sz]ed|token (has )?expired|expired (token|session|credentials)|re-?authori[sz]|re-?authenticat|sign.?in (has )?expired|reconnect|invalid[_ ]grant|oauth/.test(e)) return 'sign-in';
+  if (/econn|etimedout|enotfound|eai_again|network|proxy|socket hang up|tunnel|\b50[234]\b|unreachable|\bdns\b|fetch failed/.test(e)) return 'network';
+  if (/failed to connect|mcp.{0,40}(error|failed)|connector.{0,40}(failed|error)/.test(e)) return 'connector-failed';
+  if (result === 'interrupted' || /stopped by you|restarted|session was gone/.test(e)) return 'interrupted';
+  return 'skill';
+}
+
+const behindOf = (row) => !!row && ['stale', 'failed', 'never'].includes(row.state);
+const waitMin = (cause, n) => { const L = cause === 'rate-limit' ? RATE_MIN : BACKOFF_MIN; return L[Math.min(n, L.length - 1)]; };
+
+/**
+ * One tick for one source. Every field is plain data:
+ *   x { now, row (lib/freshness.js row), on, manual, busy (a run is going, or the schedule's own retry or a press waits),
+ *       last (the source's last run in the log: { start_at, end_at, result, error }), h (its repair record or null), canStart }
+ * → { h, start?: true, note?, tell?: { cause, why } }   h null drops the record
+ */
+function step(x) {
+  const { now, row } = x;
+  let h = x.h ? { ...x.h, attempts: (x.h.attempts || []).slice() } : null;
+  if (!row || !x.on) return { h: null };
+  if (!behindOf(row)) {
+    if (h && h.state !== 'repaired' && (h.attempts.length || h.state === 'needs-you')) return { h: { ...h, state: 'repaired', repaired_at: now, open: null, next_at: null } };
+    if (h && h.state === 'repaired' && now - (h.repaired_at || 0) < KEEP_REPAIRED_MS) return { h };
+    return { h: null };
+  }
+  if (x.manual) return { h: { state: 'needs-you', cause: 'manual', attempts: [], since: (h && h.since) || now } };
+  if (!h || h.state === 'repaired' || h.cause === 'manual') h = { state: 'repairing', since: now, attempts: [], open: null, cause: null, next_at: null };
+
+  // the attempt that is open ends when its run ends in the log
+  if (h.open) {
+    const l = x.last;
+    const ended = l && l.end_at && Date.parse(l.start_at || l.end_at) >= h.open.at - 1000;
+    if (!ended) {
+      if (now - h.open.at < 30 * 60000 || x.busy) return { h: { ...h, state: 'repairing' } };
+      h.attempts.push({ at: h.open.at, result: 'lost', cause: 'interrupted' });   // no run came of it in 30 minutes
+    } else {
+      const cause = diagnose(l.error, { result: l.result });
+      h.attempts.push({ at: h.open.at, result: l.result, cause, error: l.error ? String(l.error).slice(0, 300) : null });
+    }
+    h.open = null; h.cause = h.attempts[h.attempts.length - 1].cause;
+  }
+  if (x.busy) return { h: { ...h, state: h.state === 'needs-you' ? 'needs-you' : 'repairing' } };
+  if (h.state === 'needs-you') return { h };   // the schedule keeps reading; a good read makes it repaired
+
+  const n = h.attempts.length;
+  const c = h.cause && CAUSES[h.cause];
+  const same = n >= (c && c.after || 1) && h.attempts.slice(-(c && c.after || 1)).every((a) => a.cause === h.cause);
+  if ((c && c.user && same) || n >= MAX) {
+    return { h: { ...h, state: 'needs-you', next_at: null, told_at: h.told_at || now }, tell: h.told_at ? null : { cause: h.cause, why: c ? c.why : '' } };
+  }
+  const next = n ? h.attempts[n - 1].at + waitMin(h.cause, n) * 60000 : now;
+  if (now < next || !x.canStart) return { h: { ...h, state: 'repairing', next_at: Math.max(next, now) } };
+  h.open = { at: now };
+  return { h: { ...h, state: 'repairing', next_at: null }, start: true, note: `Repair ${n + 1} of ${MAX}` + (c ? `: the last read failed because ${c.why}` : `: ${row.state === 'never' ? 'never read' : row.state === 'failed' ? 'the last read failed' : 'past its schedule'}`) };
+}
+
+const hm = (ms) => { const d = new Date(ms); return String(d.getHours()).padStart(2, '0') + ':' + String(d.getMinutes()).padStart(2, '0'); };
+
+/** What the Sources row and the banner show. `name` is the source's name ('Jira'). */
+function view(h, name = 'It') {
+  if (!h) return null;
+  const c = h.cause ? CAUSES[h.cause] : null;
+  const n = (h.attempts || []).length;
+  const tried = n ? `Claude read it again ${n === 1 ? 'once' : n + ' times'} since ${hm(h.attempts[0].at)}${c ? `, and ${c.why}` : ''}.` : '';
+  let action = null;
+  if (h.state === 'needs-you') {
+    if (h.cause === 'claude-signin') action = { label: 'Sign in to Claude', how: 'Open Terminal, run claude, type /login and sign in.', sec: 'claude' };
+    else if (h.cause === 'connector-missing') action = { label: 'Connect ' + name, how: 'Turn on its connector in your Claude connectors.', href: CONNECTORS };
+    else if (h.cause === 'sign-in') action = { label: 'Reconnect ' + name, how: 'Sign in to its connector again in your Claude connectors.', href: CONNECTORS };
+    else action = { label: 'Read ' + name + ' again', how: h.cause === 'manual' ? 'You chose to read it only when you press ↻.' : 'Claude stopped after ' + n + ' tries.', read: true };
+  }
+  return { state: h.state, cause: h.cause || null, why: c ? c.why : '', tried, action, attempts: n, next_at: h.next_at ? new Date(h.next_at).toISOString() : null,
+    ...(h.repaired_at ? { repaired_at: new Date(h.repaired_at).toISOString() } : {}) };
+}
+
+const NAME = Object.freeze({ calendar: 'your calendar', jira: 'Jira', 'my-work': 'Jira', tracker: 'the tracker files', tools: 'your tools' });   // who the PM reconnects
+const FILE = 'source-heal.json';
+/** Every repair record as view() shows it, keyed by its lib/freshness.js id. A missing or torn file is no repair. */
+function viewAll(dir) {
+  let x = {};
+  try { x = JSON.parse(require('fs').readFileSync(require('path').join(dir, FILE), 'utf8')) || {}; } catch { return {}; }
+  const out = {};
+  for (const [id, h] of Object.entries(x)) if (h && typeof h === 'object') out[h.fresh || id] = view(h, NAME[h.fresh || id] || id);
+  return out;
+}
+
+module.exports = { viewAll, FILE, NAME, diagnose, step, view, MAX, BACKOFF_MIN, RATE_MIN, CAUSES, CONNECTORS };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.516.0",
+  "version": "0.518.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.516.0",
+      "version": "0.518.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.518.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-evmodel.js

@@ -4,6 +4,8 @@
  *   ago(iso, now)                 → '2 min ago' · '1 hour ago' · '5 days ago' · ''
  *   sourceName(row)               → the name a source shows: 'Jira', 'Calendar', 'Repository', …
  *   staleOf(sources, now)         → { id, name, text: 'Jira 5 days old', ago, state } | null   the source furthest behind (failed, then the oldest)
+ *   bannerOf(sources, now)        → { id, name, title: 'Reconnect Jira.', body, text, action } | null   the one source the PM must act on
+ *                                   (self-heal, feedback batch 26 item 7): null while Claude repairs a source by itself, or after it did
  *   sourceRows(sources, now)      → [{ id, name, sub, when, risk, act: 'read' | 'connect' | '' }]   the Sources table (EvSources)
  *   partsOf(id)                   → what may be out of date when that source is old ('Board and the Jira-linked initiatives')
  *   fabLabel(here, open, stale, news) → 'Open the menu. You are in Home. 3 new for you. Jira 5 days old' (the button says both dots, FmGrill 13)
@@ -44,11 +46,26 @@ export function staleOf(sources, now = Date.now()) {
   return { id: s.id, name, text, ago: ago(s.as_of, now), state: s.state };
 }
 
+/** The one source the PM must act on, or null. The server repairs a source that is behind by itself (lib/source-heal.js) and marks a
+ * row `heal.state: 'needs-you'` only when the PM must act; until then, and after a repair, there is no banner. The body says what is
+ * old and why, what it makes old, and what Claude already tried. It never says a source is fresh: only a read says that. */
+export function bannerOf(sources, now = Date.now()) {
+  const L = (sources || []).filter((s) => s && s.heal && s.heal.state === 'needs-you' && s.heal.action);
+  if (!L.length) return null;
+  const rank = (s) => (s.heal.action.read ? 1 : 0);   // a connection to fix leads a read to press
+  L.sort((a, b) => rank(a) - rank(b) || (Date.parse(a.as_of || '') || 0) - (Date.parse(b.as_of || '') || 0));
+  const s = L[0], h = s.heal, name = sourceName(s);
+  const when = s.as_of ? name + ' was last read ' + ago(s.as_of, now) : name + ' was never read';
+  const body = when + (h.why ? ' because ' + h.why : '') + '. ' + partsOf(s.id) + ' may be out of date.' + (h.tried ? ' ' + h.tried : '');
+  return { id: s.id, name, title: h.action.label + '.', body, text: h.action.label, action: h.action, cause: h.cause };
+}
+
 /** The Sources table: one row per source, in the order the server lists them. */
 export function sourceRows(sources, now = Date.now()) {
   return (sources || []).filter(Boolean).map((s) => {
     const behind = s.state === 'stale' || s.state === 'failed' || s.state === 'never';
-    const when = s.state === 'off' ? 'Not connected' : s.state === 'building' ? 'Reading now' : s.state === 'never' ? 'Never read'
+    const mend = behind && s.heal && s.heal.state === 'repairing';
+    const when = s.state === 'off' ? 'Not connected' : s.state === 'building' ? 'Reading now' : mend ? 'Reading again' : s.state === 'never' ? 'Never read'
       : s.state === 'failed' ? 'Could not be read' : s.id === 'repository' && s.state === 'fresh' ? 'Watching' : ago(s.as_of, now) || 'Never read';
     return { id: s.id, name: sourceName(s), sub: SRC_SUB[s.id] || s.label || '', when, risk: behind, act: s.state === 'off' ? 'connect' : behind && s.id !== 'repository' ? 'read' : '' };
   });

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,13 +3,14 @@
  * 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 button keeps its two dots on every page: blue when something is new for you, amber when a source needs you (Claude repairs the rest by itself). 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
- *   Settings     pm/cozy-settings.js; it opens at Connectors while a source is stale, so the stale one is the first thing there
+ *   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 needs you, so that 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
  * read of New for you is passed on as the event 'cz:news-for-you' (detail: the answer), so Home's Your day and Good morning follow it.
@@ -19,7 +20,7 @@
  * call, the menu open, a desk, Settings > Adler not Full, or after Quiet after: no ears (zero is silence).
  */
 import { esc, svg, ICON, wsQ } from './cozy-evui.js';
-import { fabLabel, staleOf } from './cozy-evmodel.js';
+import { fabLabel, bannerOf } from './cozy-evmodel.js';
 import { mountToastFaces, loadPrefs, adlerPeek, asleep } from './cozy-adler.js';   // Adler (batch 16 item 2): every toast carries his S face; Settings > Adler is read once
 
 export const PLACES = [
@@ -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
@@ -131,7 +134,7 @@ export function mountNav(here, doc = document, opts = {}) {
     if (doc.hidden) return;
     const [n, s] = await Promise.all([getj('/api/news-for-you' + wsQ()), getj('/api/sources' + wsQ())]);
     if (n && n.ok) { N.news = n.count || 0; doc.dispatchEvent(new CustomEvent('cz:news-for-you', { detail: n })); }
-    if (s && s.ok) { N.stale = staleOf(s.sources); doc.dispatchEvent(new CustomEvent('cz:sources', { detail: s })); }   // Your day's failed source (AdP5)
+    if (s && s.ok) { N.stale = bannerOf(s.sources); doc.dispatchEvent(new CustomEvent('cz:sources', { detail: s })); }   // Your day's failed source (AdP5)
     if (menu.hidden || !menu.contains(doc.activeElement)) draw();
   };
   read();
@@ -140,6 +143,6 @@ export function mountNav(here, doc = document, opts = {}) {
   doc.addEventListener('cz:news', (e) => { if (e.detail && Number.isFinite(e.detail.count)) { N.news = e.detail.count; draw(); } else read(); });
   doc.addEventListener('cz:calls', (e) => { const n = e.detail && Number(e.detail.count); N.calls = Number.isFinite(n) && n > 0 ? n : 0; draw(); });
   doc.addEventListener('adler:prefs', () => { ears.innerHTML = ''; draw(); });
-  window.addEventListener('pm:sources', (e) => { const d = e.detail; if (d && d.ok) { N.stale = staleOf(d.sources); draw(); } });
+  window.addEventListener('pm:sources', (e) => { const d = e.detail; if (d && d.ok) { N.stale = bannerOf(d.sources); draw(); } });
   return w;
 }

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

@@ -25,15 +25,15 @@
  * Adler's moments (batch 17 item 4-B, AdM4): one face per section, where Claude speaks. Updates: glasses while it checks or installs,
  * holding the card when a version is ready, calm when up to date. General: holding the update card, else the Jira promise (only after
  * Commit). A failure in the status line takes the honest face, and then the section's face steps back (one Adler per screen).
- * The card at the bottom of General says when an update is ready. While a source is stale, an amber box at the top of every section names
- * it with ↻ Read again, and the place menu opens Settings at Connectors. Every write is the PM's press (pmPost carries the launch nonce).
+ * The card at the bottom of General says when an update is ready. While a source needs you (lib/source-heal.js), an amber box at the top of every section names
+ * it with its one action and what Claude tried, and the place menu opens Settings at Connectors. Every write is the PM's press (pmPost carries the launch nonce).
  * PMOS reads the sources and never posts to them.
  *   openSettings(section?) */
 import { mountClaudeSetup } from './cozy-claude-setup.js';
 import * as JL from './cozy-jl.js';
 import { pmGet, pmPost, pressFetch } from './http.js';
 import { esc, svg, ICON, toast, wsParam, wsQ } from './cozy-evui.js';
-import { sourceRows, staleOf, partsOf } from './cozy-evmodel.js';
+import { sourceRows, bannerOf } from './cozy-evmodel.js';
 import * as AD from './cozy-adler.js';
 import * as SE from './cozy-seasons.js';
 import { weeksOf, lineOf, storiesOf } from './upd-weeks.js';
@@ -182,11 +182,16 @@ function readsHtml() {
   const L = T.lines ? [['Today', T.lines.readLine(s, ['calendar'])], ['Needs you', T.lines.readLine(s, ['initiatives', 'my-work', 'd:brief'])]].filter((x) => x[1]) : [];
   return `${health}<div class="ev-reads">${rows}</div>${L.map(([k, v]) => `<p class="ev-small ev-mut ev-rl" data-reads="${esc(k)}"><b>${esc(k)}:</b> ${esc(v)}</p>`).join('')}`;
 }
-/** The amber box at the top of Settings while a source is stale (FmA3Settings): what is old, what it makes old, and ↻ Read again. */
+/** The amber box at the top of Settings, only when the PM must act on a source (self-heal, feedback batch 26 item 7). While Claude
+ * reads a source again by itself, or after it did, there is no box. The box names the one action and links to the exact place:
+ * the Claude connectors, Settings › Claude, or ↻ when only a press reads it. It says what Claude already tried. */
 function staleHtml() {
-  const st = T.fresh && T.fresh.ok ? staleOf(T.fresh.sources) : null;
-  if (!st) return '';
-  return `<div class="ev-warn ev-line ev-st-warn" id="srcWarn"><i class="ev-dot risk" aria-hidden="true"></i><p class="ev-grow"><b>${esc(st.state === 'stale' ? st.name + ' was last read ' + st.ago + '.' : st.text + '.')}</b> ${esc(partsOf(st.id))} may be out of date.</p>${readBtn(st.id, 'Read ' + st.name + ' again', 'ev-ib ev-ib-card')}</div>`;
+  const b = T.fresh && T.fresh.ok ? bannerOf(T.fresh.sources) : null;
+  if (!b) return '';
+  const a = b.action;
+  const act = a.read ? readBtn(b.id, a.label, 'ev-ib ev-ib-card')
+    : `<a class="ev-ib ev-ib-card" href="${esc(a.href || '#' + a.sec)}"${a.href ? ' target="_blank" rel="noopener"' : ` data-ev-sec="${esc(a.sec)}"`} aria-label="${esc(a.label)}" title="${esc(a.label)}">${svg(ICON.open, 18)}</a>`;
+  return `<div class="ev-warn ev-line ev-st-warn" id="srcWarn" data-cause="${esc(b.cause || '')}"><i class="ev-dot risk" aria-hidden="true"></i><p class="ev-grow"><b>${esc(b.title)}</b> ${esc(b.body)}${a.read ? '' : ' ' + esc(a.how)}</p>${act}</div>`;
 }
 function connectors() {
   if (T.src === null) return readsHtml() + '<p class="ev-small ev-mut">Reading the connectors.</p>';
@@ -315,8 +320,8 @@ function draw() {
   // a redraw replaces the nodes: keep focus on the same control (by its data-ev-* key), else on the open section, never on the body
   const ae = document.activeElement, had = ae && el.contains(ae), key = had ? [...ae.attributes].find((a) => a.name.startsWith('data-ev-')) : null;
   const n = { connectors: T.src === null ? '' : Object.keys(SRC).filter((k) => T.src[k]).length + T.conn.filter((c) => !c.source && T.con[c.name]).length, workspaces: T.ws ? T.ws.filter((x) => !x.linked).length : '', updates: ready() ? '<span class="ev-pill y">1</span>' : '' };
-  const stale = T.fresh && T.fresh.ok ? staleOf(T.fresh.sources) : null;
-  el.querySelector('.ev-st-nav').innerHTML = '<h2 class="ev-h2">Settings</h2>' + SECTIONS.map(([k, l]) => PAGE_LINKS[k] ? `<a href="${PAGE_LINKS[k]}" class="ev-mi">${esc(l)}</a>` : `<a href="#${k}" class="ev-mi" data-ev-sec="${k}"${T.sec === k ? ' aria-current="page"' : ''}>${esc(l)}${k === 'connectors' && stale ? '<i class="ev-dot risk" aria-label="A source is stale" role="img"></i>' : ''}${n[k] !== undefined && n[k] !== '' ? `<span class="ev-k">${typeof n[k] === 'number' ? n[k] : n[k]}</span>` : ''}</a>`).join('');
+  const stale = T.fresh && T.fresh.ok ? bannerOf(T.fresh.sources) : null;
+  el.querySelector('.ev-st-nav').innerHTML = '<h2 class="ev-h2">Settings</h2>' + SECTIONS.map(([k, l]) => PAGE_LINKS[k] ? `<a href="${PAGE_LINKS[k]}" class="ev-mi">${esc(l)}</a>` : `<a href="#${k}" class="ev-mi" data-ev-sec="${k}"${T.sec === k ? ' aria-current="page"' : ''}>${esc(l)}${k === 'connectors' && stale ? '<i class="ev-dot risk" aria-label="A source needs you" role="img"></i>' : ''}${n[k] !== undefined && n[k] !== '' ? `<span class="ev-k">${typeof n[k] === 'number' ? n[k] : n[k]}</span>` : ''}</a>`).join('');
   const label = (SECTIONS.find((x) => x[0] === T.sec) || SECTIONS[0])[1];
   const all = T.sec === 'connectors' ? `<button type="button" class="ev-ib" data-ev-readall aria-label="Read every source again" title="Read all again"${T.reading ? ' disabled' : ''}>${svg(RD, 18)}</button>` : '';
   el.querySelector('.ev-st-main').innerHTML = staleHtml() + `<div class="ev-top"><h3 class="ev-h2" id="evStTitle">${esc(label)}</h3>${all}<button type="button" class="ev-ib" data-ev-close aria-label="Close settings" title="Close settings">${svg(ICON.close, 18)}</button></div>`
@@ -512,6 +517,7 @@ async function load() {
 export function openSettings(section) {
   const el = mount();
   if (section === 'dress') { T.sec = 'adler'; T.dress = true; } else if (section && BODY[section]) { T.sec = section; T.dress = false; }
+  else if (el.hidden) { T.sec = 'general'; T.dress = false; }   // a fresh open with no section opens on General (R2), not on the section of the last visit
   if (el.hidden) { const ae = document.activeElement; T.back = ae && ae !== document.body ? ae : null; T.ws = null; T.src = null; T.msg = ''; T.phase = ''; T.auto = false; T.wkOpen = new Set(); T.wkMore = new Set(); T.arc = false; T.fresh = null; T.note = {}; T.dset = {}; T.cl = null; T.gr = null; T.np = null; JL.reset(); }
   el.hidden = false; document.getElementById('evStScrim').hidden = false; el.setAttribute('data-esc-layer', '');
   draw();

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)}
+}