create-pmos 0.516.0 → 0.518.0

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`.

package/workspace/skills/report-write.skill

@@ -0,0 +1,44 @@
+---
+name: report-write
+label: "Write a report (the report engine)"
+description: "Write any report as a draft, ad hoc or recurring, in any domain: derive the brief, read the sources, find what matters, choose the outline for these readers, and write report.json; PMOS renders the document and the deck. Never sends or posts."
+run: agent
+agent: claude
+output:
+  - "<state>/reports/<id>/<slot>.report.json (the answer, the sections you chose, the ask, the parts beyond the ask)"
+  - "<state>/reports/<id>/<slot>.md and the deck, rendered by PMOS from it"
+---
+
+/report-write — write one report for THIS repository as a draft, with the report engine (design E). The args are the report id, and for an ad hoc report the question, for example `scarlet-assessment "Do we keep Scarlet, or move small RSVP events to a SaaS?"`.
+
+There is no template and no fixed frame. You choose the outline of this report from its readers and their question. What never changes is the discipline below.
+
+Rules that always hold (D71):
+1. DRAFT ONLY. You write files in this repository. Never send, post, share, email, publish or upload the report anywhere; the PM issues it.
+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, BigQuery, calendar or any other source.
+3. EVERY FIGURE IS A READING. A number, a percentage, a count or a duration in your words is a reading token `{{r:<reading id>}}`, never typed by hand. `{{r:id}}` writes the value with its unit, `{{r:id|of}}` writes "597 of 733", `{{r:id|n}}` writes the count. PMOS refuses a report with a bare figure. Dates are written in full (21 October 2026); a date is not a figure.
+4. NOTHING INVENTED. A reading has a source of the brief, the date it was read or measured, and how it was read (the query, the filter, the field). A source you cannot reach is a gap with its reason. Never guess a value.
+5. THE ANSWER FIRST. The title is the answer to the readers' question, with its number. If you cannot write that sentence from the readings, there is nothing to report: stop and say so in one line.
+6. THE VOICE. Follow the brief's `voice` lines and its `rules`: neutral and straightforward sentences, one claim per paragraph, the mood never happier than the data (0% is written as 0%, with its why). A leadership report does not carry the engineering appendix; it links to it.
+7. SHOW THE STEPS. Keep a TodoWrite list of the steps below and mark each one completed. If a source needs a sign-in that expired, end with a pmos-ask block: {"kind":"reach","what":"<the source>","why":"sign-in expired","need":"signin"}.
+
+Procedure:
+1. Run `pmos report make <id>`. For an ad hoc report add `--ask "<the question>"`, and `--readers "<who>"` when you know them. Name sources the brief must read with `--source`, comma-separated: `connector:<name>=<what it is>` (Jira, BigQuery for GA4, Confluence, …), `document:<path>`, `pack:<state file of readings>`, `pmos` (the PMOS ledgers). It writes `<slot>.brief.json`, `<slot>.readings.json` and `<slot>.findings.json` next to the draft, and prints the gaps.
+   - If it refuses because the slot is issued, stop: an issued report is frozen.
+   - If it says there is no report with that id, it needs a question: ask the PM once for the question, or take it from the chat line.
+2. Read `<slot>.brief.json`: the readers, the questions, the window, the sources, the last issue, the agreed outline, the carried asks, the voice and the rules.
+3. Read each source that the gaps name, through its connector or the file, read-only. Write what you read as readings in one JSON file: `{"readings":[{"id":"web-login-rate","value":81,"unit":"%","n":597,"of":733,"at":"2026-10-19","source":"ga4","how":"events_20261019, sessions with a password start","label":"Web password login, recorded success"}],"gaps":[{"source":"native-app","reason":"read only on the device"}]}`. Give `target` and `better` ("higher" or "lower") when the reading has a target. Give `flag` when the reading is off what the readers expect. Run `pmos report read <id> --from <file>`. A parameter of a method (a 5-second match window) is a reading too.
+4. Find what answers the readers. Write the findings that answer each question, each citing the readings it rests on, and run `pmos report find <id> --from <file>` with `{"findings":[{"text":"…","readings":["…"],"kind":"answers-question","question":"…"}]}`. The engine adds its own findings: changes since the last issue, misses against a target, initiatives off plan, items due within 14 days, the asks carried over. If `<slot>.findings.json` says `"none": true`, there is nothing to report: stop and say so in one line. Do not write a report about nothing.
+5. Choose the outline for these readers and this question. Any sections, any titles, any order.
+   - A recurring report keeps `agreed_outline`, the sections of its last issued issue. Add a section only when a finding needs one, drop one only when it would be empty, and say so in `outline_note` (one line).
+   - `earlier_outline` is the shape of an issue written before the engine (the old fixed frame). It is an example, not an agreement: keep what served the readers.
+   - Each section title is a finding, not a label: "Sign-up stalls before submit", not "Sign-up". Reading only the titles tells the story.
+   - Shapes other reports took, as examples and never a menu: a decision (the lean · the options and what each costs · what could reverse it · your call); a watch (today against yesterday and the week · the drop that moved most · why); a stakeholder update (are the dates on track · what each team needs and by when · open decisions · what could stop it); a review (the summary for decision · the outcomes by segment · the challenges and answers · method); did-it-work (what was promised · what we got · the verdict).
+6. Write `<slot>.report.json` (in a scratch file, then `pmos report write <id> --from <file>`):
+   `{"title":"…{{r:…}}…","answer":{"text":"…","supports":["Label: …{{r:…}}…"]},"sections":[{"id":"…","title":"…","blocks":[{"kind":"p","text":"…"},{"kind":"list","items":["…"]},{"kind":"table","columns":["…"],"rows":[["…"]]},{"kind":"bars","title":"…","rows":[["label","{{r:id}}"]]},{"kind":"options","options":[{"name":"…","text":"…"}]},{"kind":"quote","text":"…"}]}],"ask":{"text":"…","who":"…","by":"YYYY-MM-DD","options":["…"]},"beyond":{"why":"…","so_what":"…","now_what":"…","since":"…","would_change":"…","unknown":["…"],"else":["…"],"next_question":"…"},"questions":[{"question":"<a question of the brief>","answered_in":"<section id or answer>","gap":"<why it cannot be answered>"}],"outline_note":"…"}`.
+   - `ask` is null when the readers have nothing to decide. When it is a call with no better option on the evidence, give the options and say "your call".
+   - BEYOND THE ASK. Answer the readers' next three questions before they ask: why (the cause, from the evidence), so what (the effect on the target and its date), now what (the recommendation, who, by), since the last issue (what moved, and each carried ask), what would change it (the one or two readings that would flip the recommendation), what we don't know (the gaps, counted, never padded), what else is here (at most two findings from a named source the readers did not ask about, when their question depends on them) and the next question (the split they will ask for next). Each part cites a reading. Leave a part out when no reading backs it, and leave out a part the brief's rules turn off.
+   - `questions`: map each question of the brief after the first to the section that answers it, or give the gap.
+7. Read what `pmos report write` prints. A refusal names the check: fix the report and run it again. When it passes, it writes `<slot>.md` and `<slot>.checks.json`; the deck, the PDF and the PowerPoint are drawn from the same model, in the report's saved look.
+8. Learn. When the PM's change in the chat is about the words (shorter, plainer, another tone) and it would apply to every issue, keep it: `pmos report rule <id> add wording "<the rule, one line>"`. When the PM removes a part beyond the ask, `pmos report rule <id> add off <part>`. Then change report.json and run `pmos report write` again. A change to a number is a change to a reading: read the source again and file it.
+9. Finish by saying in one line where the draft is and how many readings, findings and gaps it has. Do not commit; the PM's Sync carries the files.

package/workspace/test-lists/report-engine.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "report-engine: the report engine E (brief, read, find, write, render, substance checks; one deck for the reader, the PDF and the PPTX; no draft without a finding).",
+  "modules": ["report-engine.test.js"],
+  "seconds": { "report-engine.test.js": 2 }
+}

package/workspace/guide/ask-the-agent.md

@@ -1,46 +0,0 @@
----
-type: Guide
-title: "Ask the agent from the page"
-description: "How the console's Ask the agent, Fix with the agent, Have the agent draft it, a spike and an early gate start an agent from the page, what the agent may do, and what stays yours."
-timestamp: 2026-10-12
----
-
-# Ask the agent from the page
-
-Five presses in the console (`/`) start an agent from the page. You do not need a terminal, and you do not copy a request anywhere. Each run is listed in Sessions, so you can follow it there.
-
-## Ask the agent on a document
-
-1. Open a document in Initiatives › Documents, or open a report as a document from Reports.
-2. Select **Proposals**, write what to change, and select **Ask the agent**.
-3. The sheet says that the agent is drafting. You can close the sheet and come back.
-4. When the draft is ready, it shows in **Proposals** with the difference, section by section.
-5. Clear the tick of any section that you do not want, and slide to accept. Or select **Change the request** or **Reject**.
-
-The agent runs in the background and can only read: it has the Read, Glob and Grep tools and nothing else. It answers with the revised document. The workspace records that answer as a proposal. The file does not change until you slide to accept it, and the slide is bound to the proposal's hash. If the document changed while the agent worked, the sheet tells you to ask again.
-
-**Copy the request** stays beside the button. Use it to give the request to a session that you already have open.
-
-On a document's **Health** segment, **Fix with the agent** writes the fix as the request and opens Proposals.
-
-## Fix with the agent on a report
-
-In Reports, open a section that is not traced and select **Fix with the agent**. The report opens as a document on Proposals, with the fix written in. A report that is not issued yet has no stored document, so the sheet tells you to issue it first.
-
-## Lifecycle: a draft, a spike and an early gate
-
-These three start an ordinary agent session, the same as Next step › Go. The session opens on the initiative's branch and is listed in Sessions.
-
-| Press | What the agent does |
-|---|---|
-| **Have the agent: draft it** on a stage requirement | Drafts that requirement for the initiative, following AGENTS.md. |
-| **Run a 1-day spike first** on an idea | Writes a spike brief: the assumption, the cheapest test, and the result that would change the decision. |
-| **Request an early** gate in Quality gates | Checks the work so far against the PRD and its done-criteria, and writes down what passes and what fails. |
-
-The page sends only the task, the initiative and a short label. The prompt is fixed by the workspace. Each prompt tells the agent to leave a draft for you to read, and not to merge, push or send anything outside PMOS. Decisions that are yours, such as a stage decision, still have no start button.
-
-## When the agent does not start
-
-- **Background runs are switched off here.** `PMOS_HEADLESS=off` is set, so Ask the agent cannot run in the background. Copy the request to a session instead.
-- **This workspace cannot start sessions.** The workspace has no agent to start. Open the workspace from the PMOS app.
-- **The agent took too long and was stopped.** Ask again with a smaller request.

package/workspace/guide/briefing-cards.md

@@ -1,52 +0,0 @@
----
-type: Guide
-title: "Briefing: cards, time of day, Needs you and Portfolio pulse"
-description: "How the Briefing cards keep one height and flip in place, how to confirm an act on a large screen, how the day part follows the clock, how a Portfolio pulse row opens inline, and how overdue items reach Needs you."
-timestamp: 2026-10-12
----
-
-# Briefing: cards, time of day, Needs you and Portfolio pulse
-
-## Cards
-
-Every card in a deck has the same height at rest. Text that does not fit is cut short. The front shows the numbers the card carries as tiles, with a short kind label. Press a card to turn it over. The card turns in about a third of a second. The back grows to fit its content, so the options and the confirm control are never cut off. The other cards in the row keep their size, and the page below the deck moves down. Press the top line of the back to turn it again. When you decide, the card shows a check and a message offers **Undo**. With reduced motion on, the card changes at once.
-
-The page background is white. A soft, slow glow of colour drifts behind the page. With reduced motion on, it is one still picture.
-
-The tabs show counts: Briefing shows how many things need you, Work shows its inbox, and Initiatives shows new asks to triage. The Sessions button is a bolt icon with no label, and the dock button shows a bolt too. In the demo, the Record button and its arrow are visible when nothing is recording.
-
-### Kinds of card
-
-The label on a card says what kind of thing happened, for example **Deadline moved**, **Promise out of date**, **Blocked**, **Conflict**, **Risk**, **Waiting on someone** or **Report due**. A win keeps the label **Big win** or **Small win**. A card from your own data has the label **Overdue**, **Due today**, **Blocked**, **Worth asking** or **For you today** (see The Briefing: today's brief). The colour of the card shows how serious it is: red is critical, amber is a warning, green is good news, and the accent colour is neutral.
-
-Each kind has a short list of what its card must say. For example, a **Deadline moved** card says what moved, by how much, by when you must decide and the one move. When the card does not know a part, the back of the card says so under **Not known yet**. PMOS does not guess a missing part.
-
-A card shows only when it is relevant enough and links to a page that you can open. Critical cards always show. When nothing is relevant enough, there is no card.
-
-The icon of a card comes from fixed rules over the kind of the card. A kind the rules do not know gets a neutral icon. No card text leaves your machine to choose an icon.
-
-## Confirm an act
-
-On a screen with a mouse or trackpad, an act shows a compact button.
-
-- An act that sends something out, or that cannot be undone, asks you to press and hold. A ring fills for 0.6 seconds, and the act runs when it is full.
-- Any other act runs on one click.
-- With the keyboard, press Enter or Space on the button, then choose **Confirm** or **Cancel**. Escape closes the step.
-
-On a touch screen the slide stays. It is at most 320 pixels wide.
-
-## Time of day
-
-There is no selector for the part of the day. The Briefing reads the clock and checks it every five minutes. When the part of the day changes, the cards are ranked again only after you have not touched the page for a minute and no card is open, or the next time the page loads. A thin strip in the top bar shows the sun or the moon on the day's arc, with sunrise and sunset. It is worked out on this machine from the date and the time zone. It makes no network request.
-
-## Portfolio pulse
-
-Press a row of the Portfolio pulse to see it open under the row, on the Briefing. The tab does not change. The open row shows the promised date, the forecast and the slip. Press **Open initiative** inside it to go to the Initiatives tab.
-
-## Needs you
-
-Needs you also lists your own items that are overdue or due today. Overdue items come first, the most overdue first, then items due today. A row says how many days overdue it is. Done items, parked items, items waiting on someone and items without a date are not listed. At most five show.
-
-## Work
-
-The Work page shows **Focus** in its right column. There is no Flow today card and no Jobs card: you open a job from a Focus row.