create-pmos 0.65.0 → 0.65.1

package/workspace/public/pm/dest-docs.js

@@ -6,13 +6,17 @@
  * only the body is rebuilt when its own data changed.
  *
  * What it shows, for the repository the tab names (or the open one):
- *   - Docs, a search box, Needs you · All, and when the copies were last compared, with a control that compares again;
- *   - the copies grouped by initiative, ONE line per copy: a status dot, the title, a link that opens the copy, one
+ *   - Docs, a search box, Needs you · With a copy · All files, and when the copies were last compared, with a control
+ *     that compares again;
+ *   - the copies grouped by category, ONE line per copy: a status dot, the title, a link that opens the copy, one
  *     sentence (which side is newer, and who edited it last) and at most one button (Use PMOS version, Use Confluence
  *     version, or Choose… when both changed);
  *   - a click on a line: both sides with where they live and their last edit, a Use … version button for each, the first
- *     difference the check saw, Compare again and Stop tracking this copy;
- *   - search: every markdown file that matches; a file without a copy offers Add copy, in place.
+ *     difference the check saw, Compare again, Stop tracking this copy, and the file's links (doc-graph.js);
+ *   - All files (docs-library-graph): every repository file under folding categories, each line naming its initiative;
+ *     a category opens on its first 20 files. A press on a file shows the files it links to and the files that link to
+ *     it. Add copy shows on hover or focus, and always on a touch screen;
+ *   - search: every file whose title, path or initiative matches, grouped by category, with the match marked.
  * The signal is decided on the server (lib/doc-sync.js) from what a check session read. Nothing here reads or writes
  * Google Docs or Confluence. Use … version waits five seconds behind Undo, then asks the server to start ONE doc-sync
  * session for that copy, which writes one side with the PM's own connectors (the PM's ruling, amended 2026-10-06).
@@ -21,13 +25,20 @@
 
 import { el } from './dom.js';
 import { button, row, field, toast, empty, tabs, ensureComponentsCss } from './primitives.js';
-import { ensureSprite } from './icons.js';
+import { ensureSprite, icon } from './icons.js';
 import { pmGet, pmPost } from './http.js';
 import { wsOf } from './data.js';
 import { registerCommand, openDestination } from './registry.js';
+import { getLibrary, fileGraph } from './doc-graph.js';
+import { openDoc } from './panel-initiatives.js';
 
 const LABEL = { google: 'Google Docs', confluence: 'Confluence' };
 const UNDO_MS = 5000;
+const PAGE = 20;
+/* the library's categories, in display order (lib/doc-library.js CATEGORIES) */
+const CATS = [['spec', 'Specs'], ['ini', 'Initiatives'], ['dec', 'Decisions'], ['res', 'Research & plans'], ['exp', 'Explainers'],
+  ['eval', 'Evals'], ['know', 'Knowledge'], ['guide', 'Guides & rules'], ['proto', 'Prototypes']];
+const CAT_NAME = Object.fromEntries(CATS);
 
 export const COPY = Object.freeze({
   title: 'Docs',
@@ -36,20 +47,25 @@ export const COPY = Object.freeze({
   loading: 'Reading…',
   readError: 'The documents could not be read.',
   find: 'Find a document',
+  findIn: (n) => `Find in ${n.toLocaleString('en-US')} files`,
   needs: 'Needs you',
-  all: 'All',
+  copies: 'With a copy',
+  files: 'All files',
+  readingFiles: 'Reading the files…',
+  filesError: 'The file list could not be read.',
+  matches: (n, all) => `${n} of ${all.toLocaleString('en-US')} files match by title, path or initiative. Press Esc to clear.`,
+  showAll: (n, cat) => `Show all ${n} in ${cat}`,
+  needYou: (n) => `${n} need${n === 1 ? 's' : ''} you`,
   compared: (iso) => 'Compared ' + ago(iso),
   never: 'Not compared yet',
   comparing: 'Comparing…',
   compareAll: 'Compare every copy again',
-  none: 'No document has a copy yet. Find a document above and press Add copy.',
+  none: 'No document has a copy yet. Open All files and press Add copy on a file.',
   nothingNeeds: 'Nothing needs you. Every copy matches PMOS.',
   noMatch: (q) => `No document matches “${q}”.`,
-  other: 'Other',
   usePmos: 'Use PMOS version',
   useCopy: (label) => `Use ${label} version`,
   choose: 'Choose…',
-  noCopy: 'No copy',
   addCopy: 'Add copy',
   add: 'Add',
   cancel: 'Cancel',
@@ -91,6 +107,23 @@ function when(iso) {
   if (days > 1 && days < 7) return t.toLocaleDateString('en-US', { weekday: 'short' }) + ' ' + hm;
   return t.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
 }
+/** A file's last edit from its YYYY-MM-DD date: "Oct 6", or "Oct 6, 2025" in another year. */
+function day(d) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(d || ''));
+  if (!m) return '';
+  const t = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  return t.toLocaleDateString('en-US', { month: 'short', day: 'numeric', ...(t.getFullYear() !== new Date().getFullYear() ? { year: 'numeric' } : {}) });
+}
+/** The text with every match of q marked. */
+function marked(text, q) {
+  const t = String(text || '');
+  if (!q) return t;
+  const out = []; const low = t.toLowerCase(); let at = 0;
+  for (let k = low.indexOf(q); k >= 0 && q; k = low.indexOf(q, at)) { out.push(t.slice(at, k), el('mark', { class: 'rp-docs-mark' }, t.slice(k, k + q.length))); at = k + q.length; }
+  out.push(t.slice(at));
+  return out;
+}
+const openFile = (p) => openDoc(null, p, 'FILE');
 const edit = (by, at) => [by, at ? when(at) : null].filter(Boolean).join(', ');
 const keyOf = (doc, link) => `${doc.path}|${link.kind}`;
 /** Which kind a pasted address names. The server checks it again; this only picks the kind. */
@@ -134,7 +167,8 @@ export function mountDestination(host, ctx) {
   if (!inst) {
     inst = { host, root: el('div', { class: 'rp-page rp-docs', 'data-docs': '' }), head: null, body: el('div', { class: 'rp-docs-body' }),
       ws: null, loaded: false, error: null, view: null, filter: 'needs', q: '', files: [], open: null, adding: null,
-      pending: new Map(), busy: false, seq: 0, fseq: 0, last: '', timer: null, ftimer: null };
+      pending: new Map(), busy: false, seq: 0, fseq: 0, last: '', timer: null, ftimer: null,
+      lib: null, libError: null, openCats: new Set(), full: new Set(), graph: null };
     insts.set(host, inst);
   }
   ensureComponentsCss();
@@ -144,7 +178,8 @@ export function mountDestination(host, ctx) {
   const ws = repo ? wsOf(repo) : null;
   if (ws !== inst.ws) {
     stopPoll(inst);
-    Object.assign(inst, { ws, loaded: false, error: null, view: null, last: '', open: null, adding: null, files: [] });
+    Object.assign(inst, { ws, loaded: false, error: null, view: null, last: '', open: null, adding: null, files: [], lib: null, libError: null, graph: null });
+    inst.openCats.clear(); inst.full.clear();
     if (ws) { ensureSprite(); refresh(inst); }
     draw(inst);
     return;
@@ -177,8 +212,9 @@ async function refresh(inst) {
   if (!ws) return;
   const seq = ++inst.seq;
   inst.readAt = Date.now();
-  const v = await pmGet('/api/docs?ws=' + encodeURIComponent(ws));
+  const [v, lib] = await Promise.all([pmGet('/api/docs?ws=' + encodeURIComponent(ws)), getLibrary(ws)]);
   if (seq !== inst.seq || ws !== inst.ws) return;
+  if (lib) { inst.lib = lib; inst.libError = null; } else if (!inst.lib) inst.libError = COPY.filesError;
   inst.loaded = true;
   if (!v || v.ok === false) { inst.error = (v && v.error) || COPY.readError; inst.view = null; }
   else { inst.error = null; inst.view = v; }
@@ -190,7 +226,7 @@ async function refresh(inst) {
 function searchFiles(inst) {
   if (inst.ftimer) clearTimeout(inst.ftimer);
   const q = inst.q.trim();
-  if (!q) { inst.files = []; return; }
+  if (!q || inst.lib) { inst.files = []; return; }
   inst.ftimer = setTimeout(async () => {
     const seq = ++inst.fseq;
     const r = await pmGet('/api/docs/files?ws=' + encodeURIComponent(inst.ws) + '&q=' + encodeURIComponent(q));
@@ -252,7 +288,7 @@ async function addCopy(inst, path, target, err) {
 
 /* ── lines ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
 
-function copyLine(inst, doc, link) {
+function copyLine(inst, doc, link, q = '') {
   const key = keyOf(doc, link);
   const L = link.label || LABEL[link.kind];
   const st = stateOf(inst, doc, link);
@@ -270,7 +306,7 @@ function copyLine(inst, doc, link) {
     ? el('a', { class: 'rp-docs-open', href: link.url, target: '_blank', rel: 'noopener noreferrer', 'data-docs-open': link.kind }, L + ' ↗')
     : el('span', { class: 'rp-docs-open' }, L);
   const line = row({
-    title: doc.title,
+    title: marked(doc.title, q),
     meta: [st.strong, st.rest].filter(Boolean),
     lead: [el('span', { class: 'rp-docs-dot rp-docs-dot--' + st.dot, 'aria-hidden': 'true' })],
     trail: [opener, act].filter(Boolean),
@@ -304,6 +340,7 @@ function details(inst, doc, link, st) {
     side('PMOS', doc.path, edit(doc.repo && doc.repo.modified_by, doc.repo && doc.repo.modified_at), pNew, 'pmos'),
     side(L, link.target, edit(link.remote_modified_by, link.remote_modified_at), cNew, 'copy'),
     diff,
+    inst.lib && inst.lib.byPath.has(doc.path) ? el('div', { class: 'rp-docs-links' }, fileGraph(inst.lib, doc.path, { onOpen: openFile })) : null,
     el('div', { class: 'rp-docs-more' },
       button({ label: COPY.compareAgain, variant: 'ghost', size: 'sm', disabled: !!(inst.view && (inst.view.open || inst.view.session)) || inst.busy,
         attrs: { 'data-docs-act': 'compare-one' }, onClick: () => compareAll(inst) }),
@@ -311,18 +348,28 @@ function details(inst, doc, link, st) {
         onClick: () => stopTracking(inst, doc, link) })));
 }
 
-/** A file with no copy: "No copy" and Add copy, which opens a paste field in place. */
-function fileLine(inst, f) {
-  const start = () => { inst.adding = f.path; draw(inst); };
+/**
+ * A file with no copy: its title, its initiative's short name (or its path) and the date of its last edit. A press shows
+ * its links; Add copy opens a paste field in place.
+ */
+function fileLine(inst, f, q = '') {
+  const start = () => { inst.adding = f.path; inst.graph = null; draw(inst); };
   const adding = inst.adding === f.path;
+  const open = inst.graph === f.path;
+  const toggle = () => { inst.graph = open ? null : f.path; draw(inst); };
+  const ini = inst.lib && f.initiative ? inst.lib.ini(f) : null;
   const line = row({
-    title: f.title,
-    meta: [COPY.noCopy],
+    title: marked(f.title, q),
+    meta: [ini ? el('span', { class: 'rp-docs-ini', title: ini.title }, marked(ini.short, q)) : el('span', { class: 'rp-docs-path' }, marked(f.path, q)), day(f.date)],
     lead: [el('span', { class: 'rp-docs-dot rp-docs-dot--none', 'aria-hidden': 'true' })],
-    trail: adding ? [] : [button({ label: COPY.addCopy, variant: 'outline', size: 'sm', attrs: { 'data-docs-act': 'add-copy', 'data-docs-key': f.path }, onClick: start })],
+    trail: adding ? [] : [button({ label: COPY.addCopy, variant: 'outline', size: 'sm', attrs: { class: 'rp-docs-addcopy', 'data-docs-act': 'add-copy', 'data-docs-key': f.path }, onClick: start })],
+    onOpen: inst.lib ? toggle : null,
+    openLabel: `${f.title}: show the files it links to`,
+    openAttrs: { 'aria-expanded': open ? 'true' : 'false', title: f.path, 'data-docs-file-toggle': f.path },
     attrs: { 'data-docs-file-line': f.path, title: f.path },
   });
   const wrap = el('div', { class: 'rp-docs-row', role: 'listitem', 'data-docs-file': f.path }, line);
+  if (open && inst.lib) wrap.appendChild(el('div', { class: 'rp-docs-links' }, fileGraph(inst.lib, f.path, { onOpen: openFile })));
   if (!adding) return wrap;
   const err = el('span', { class: 'rp-docs-add__err', role: 'alert' });
   const inp = field({ label: `Copy of ${f.title}`, hideLabel: true, placeholder: COPY.paste, attrs: { 'data-docs-field': 'target' } });
@@ -344,57 +391,110 @@ function header(inst) {
   if (inst.head) return inst.head;
   const find = field({ label: COPY.find, hideLabel: true, placeholder: COPY.find, attrs: { 'data-docs-find': '' } });
   const q = find.control;
-  q.addEventListener('input', () => { inst.q = q.value; inst.open = null; inst.adding = null; searchFiles(inst); draw(inst); });
+  inst.findControl = q;
+  q.addEventListener('input', () => { inst.q = q.value; inst.open = null; inst.adding = null; inst.graph = null; inst.full.clear(); searchFiles(inst); draw(inst); });
   // The field restores its last committed text on Escape; here Escape clears the search instead.
-  q.addEventListener('keydown', (e) => { if (e.key === 'Escape') { q.resetCommitted(''); inst.q = ''; searchFiles(inst); draw(inst); } });
+  q.addEventListener('keydown', (e) => { if (e.key === 'Escape') { q.resetCommitted(''); inst.q = ''; inst.graph = null; searchFiles(inst); draw(inst); } });
   inst.head = el('div', { class: 'rp-docs-top' }, el('h2', { class: 'rp-head__title' }, COPY.title), el('div', { class: 'rp-docs-find' }, find));
   return inst.head;
 }
 
-function grouped(inst, docs) {
-  const by = new Map();
-  for (const d of docs) {
-    const k = d.initiative ? d.initiative.id : '';
-    if (!by.has(k)) by.set(k, { title: d.initiative ? d.initiative.title : COPY.other, docs: [] });
-    by.get(k).docs.push(d);
+const needsYou = (inst, d, l) => l.signal !== 'same' || !!l.syncing || inst.pending.has(keyOf(d, l));
+
+/**
+ * One category: its title (a fold when `foldable`), then its lines — files with a copy first, then newest first; the
+ * first 20, then Show all. `entries` are { f, doc }: f the file, doc its copies (null for a file with none).
+ */
+function section(inst, key, entries, { q = '', foldable = false, page = true } = {}) {
+  const name = CAT_NAME[key] || key;
+  const open = !foldable || inst.openCats.has(key);
+  const copies = entries.reduce((n, e) => n + (e.doc ? e.doc.links.length : 0), 0);
+  const needs = entries.reduce((n, e) => n + (e.doc ? e.doc.links.filter((l) => needsYou(inst, e.doc, l)).length : 0), 0);
+  const toggle = () => { if (inst.openCats.has(key)) inst.openCats.delete(key); else inst.openCats.add(key); draw(inst); };
+  const head = foldable
+    ? row({ title: name, meta: [String(entries.length), needs ? COPY.needYou(needs) : null], lead: [icon(open ? 'chevron-down' : 'chevron-right')],
+      onOpen: toggle, openLabel: `${name}, ${entries.length} files${needs ? ', ' + COPY.needYou(needs) : ''}`,
+      openAttrs: { 'aria-expanded': open ? 'true' : 'false', 'data-docs-cat-toggle': key }, attrs: { class: 'rp-docs-cat', 'data-docs-cat': key, 'data-docs-count': String(entries.length) } })
+    : el('h3', { class: 'rp-docs-group__title' }, `${name} · ${entries.length}`);
+  const box = el('section', { class: 'rp-docs-group', 'data-docs-group': key }, head);
+  if (!open) return box;
+  const sorted = entries.slice().sort((a, b) => (!!b.doc - !!a.doc) || String(b.f.date || '').localeCompare(String(a.f.date || '')) || a.f.path.localeCompare(b.f.path));
+  const all = !page || inst.full.has(key);
+  const shown = all ? sorted : sorted.slice(0, PAGE);
+  const list = el('div', { role: 'list' }, shown.flatMap((e) => (e.doc ? e.doc.links.map((l) => copyLine(inst, e.doc, l, q)) : [fileLine(inst, e.f, q)])));
+  box.appendChild(list);
+  if (shown.length < sorted.length) {
+    box.appendChild(button({ label: COPY.showAll(sorted.length, name), variant: 'ghost', size: 'sm', attrs: { class: 'rp-docs-showall', 'data-docs-act': 'show-all', 'data-docs-key': key },
+      onClick: () => { inst.full.add(key); draw(inst); } }));
   }
-  return [...by.entries()].sort((a, b) => (a[0] === '') - (b[0] === '')).map(([k, g]) =>
-    el('section', { class: 'rp-docs-group', 'data-docs-group': k || 'other' },
-      el('h3', { class: 'rp-docs-group__title' }, g.title),
-      el('div', { role: 'list' }, g.docs.flatMap((d) => d.links.map((l) => copyLine(inst, d, l))))));
+  return box;
+}
+
+/** Entries grouped by category, in the categories' order. */
+function byCategory(entries) {
+  const by = new Map();
+  for (const e of entries) { const k = CAT_NAME[e.f.category] ? e.f.category : 'guide'; if (!by.has(k)) by.set(k, []); by.get(k).push(e); }
+  return CATS.map(([k]) => [k, by.get(k)]).filter(([, es]) => es && es.length);
+}
+
+/** Every file: the library's, with each one's copies, plus a file with a copy the library does not list yet. */
+function allEntries(inst) {
+  const v = inst.view;
+  const docOf = new Map(v.docs.map((d) => [d.path, d]));
+  const out = inst.lib ? inst.lib.files.map((f) => ({ f, doc: docOf.get(f.path) || null })) : [];
+  const listed = new Set(out.map((e) => e.f.path));
+  for (const d of v.docs) if (!listed.has(d.path)) out.push({ f: { path: d.path, title: d.title, category: d.category, date: null, initiative: null }, doc: d });
+  return out;
 }
 
 function body(inst) {
   const v = inst.view;
   const q = inst.q.trim().toLowerCase();
+  const lib = inst.lib;
+  if (inst.findControl) inst.findControl.placeholder = lib ? COPY.findIn(lib.files.length) : COPY.find;
   if (q) {
-    const hits = v.docs.filter((d) => [d.title, d.path, d.initiative ? d.initiative.title : ''].join(' ').toLowerCase().includes(q));
-    const rows = [...hits.flatMap((d) => d.links.map((l) => copyLine(inst, d, l))), ...inst.files.map((f) => fileLine(inst, f))];
-    return rows.length ? [el('div', { role: 'list', class: 'rp-docs-group', 'data-docs-results': '' }, rows)] : [el('p', { class: 'rp-section__empty' }, COPY.noMatch(inst.q.trim()))];
+    if (!lib) {
+      const hits = v.docs.filter((d) => [d.title, d.path, d.initiative ? d.initiative.title : ''].join(' ').toLowerCase().includes(q));
+      const rows = [...hits.flatMap((d) => d.links.map((l) => copyLine(inst, d, l, q))), ...inst.files.map((f) => fileLine(inst, f, q))];
+      return rows.length ? [el('div', { role: 'list', class: 'rp-docs-group', 'data-docs-results': '' }, rows)] : [el('p', { class: 'rp-section__empty' }, COPY.noMatch(inst.q.trim()))];
+    }
+    const hay = (e) => { const ini = e.f.initiative ? lib.ini(e.f) : null; return [e.f.title, e.f.path, ini ? ini.short + ' ' + ini.title : ''].join(' ').toLowerCase(); };
+    const hits = allEntries(inst).filter((e) => hay(e).includes(q));
+    if (!hits.length) return [el('p', { class: 'rp-section__empty' }, COPY.noMatch(inst.q.trim()))];
+    return [el('p', { class: 'rp-docs-hint', 'data-docs-results': String(hits.length) }, COPY.matches(hits.length, lib.files.length)),
+      ...byCategory(hits).map(([k, es]) => section(inst, k, es, { q }))];
   }
   const all = v.docs.reduce((n, d) => n + d.links.length, 0);
-  const needs = v.docs.reduce((n, d) => n + d.links.filter((l) => l.signal !== 'same' || l.syncing).length, 0);
+  const needs = v.docs.reduce((n, d) => n + d.links.filter((l) => needsYou(inst, d, l)).length, 0);
   const running = !!(v.open || v.session) || inst.busy;
   const out = [el('div', { class: 'rp-docs-views' },
-    tabs({ variant: 'line', items: [{ id: 'needs', label: COPY.needs, count: needs }, { id: 'all', label: COPY.all, count: all }],
-      value: inst.filter, ariaLabel: 'Filter', attrs: { 'data-docs-filter': '' }, onChange: (val) => { inst.filter = val; draw(inst); } }),
+    tabs({ variant: 'line', items: [{ id: 'needs', label: COPY.needs, count: needs }, { id: 'copies', label: COPY.copies, count: all },
+      { id: 'files', label: COPY.files, count: lib ? lib.files.length.toLocaleString('en-US') : null }],
+    value: inst.filter, ariaLabel: 'Filter', attrs: { 'data-docs-filter': '' }, onChange: (val) => { inst.filter = val; inst.graph = null; draw(inst); } }),
     el('span', { class: 'rp-docs-when', 'data-docs-summary': '' },
       running ? COPY.comparing : (v.last ? COPY.compared(v.last.finished_at) : COPY.never),
       button({ label: '↻', variant: 'ghost', size: 'sm', disabled: running || !all,
         attrs: { 'data-docs-act': 'check', 'aria-label': COPY.compareAll, title: COPY.compareAll }, onClick: () => compareAll(inst) })))];
+  if (inst.filter === 'files') {
+    if (!lib) { out.push(el('p', { class: 'rp-section__empty' + (inst.libError ? ' rp-section__empty--bad' : '') }, inst.libError || COPY.readingFiles)); return out; }
+    out.push(el('div', { class: 'rp-docs-folds' }, byCategory(allEntries(inst)).map(([k, es]) => section(inst, k, es, { foldable: true }))));
+    return out;
+  }
   if (!v.docs.length) { out.push(el('p', { class: 'rp-section__empty' }, COPY.none)); return out; }
-  const shown = inst.filter === 'needs'
-    ? v.docs.map((d) => ({ ...d, links: d.links.filter((l) => l.signal !== 'same' || l.syncing || inst.pending.has(keyOf(d, l))) })).filter((d) => d.links.length)
+  const docs = inst.filter === 'needs'
+    ? v.docs.map((d) => ({ ...d, links: d.links.filter((l) => needsYou(inst, d, l)) })).filter((d) => d.links.length)
     : v.docs;
-  if (!shown.length) { out.push(el('p', { class: 'rp-section__empty' }, COPY.nothingNeeds)); return out; }
-  out.push(...grouped(inst, shown));
+  if (!docs.length) { out.push(el('p', { class: 'rp-section__empty' }, COPY.nothingNeeds)); return out; }
+  const libFile = (d) => (lib && lib.byPath.has(d.path) ? lib.files[lib.byPath.get(d.path)] : { path: d.path, title: d.title, category: d.category, date: null });
+  out.push(...byCategory(docs.map((d) => ({ f: libFile(d), doc: d }))).map(([k, es]) => section(inst, k, es, { page: false })));
   return out;
 }
 
 function draw(inst) {
   const root = inst.root;
   if (!inst.ws) { root.replaceChildren(empty({ text: COPY.noRepo })); inst.last = 'none'; return; }
-  const fp = JSON.stringify([inst.loaded, inst.error, inst.view, inst.filter, inst.busy, inst.q, inst.files, inst.open, inst.adding, [...inst.pending.keys()]]);
+  const fp = JSON.stringify([inst.loaded, inst.error, inst.view, inst.filter, inst.busy, inst.q, inst.files, inst.open, inst.adding, [...inst.pending.keys()],
+    inst.lib ? inst.lib.key : null, inst.libError, [...inst.openCats], [...inst.full], inst.graph]);
   if (fp === inst.last && root.childNodes.length && root.contains(inst.body)) return;
   inst.last = fp;
   const head = header(inst);

package/workspace/public/pm/doc-graph.js

@@ -0,0 +1,272 @@
+/* pm/doc-graph.js — the library of every repository file and the links the files write, drawn two ways (initiative
+ * docs-library-graph, PRD R-G1 to R-G5 and R-N1 to R-N5).
+ *
+ *   getLibrary(ws)                      GET /api/docs/library once per workspace (kept for a short while), indexed
+ *   fileGraph(lib, path, { onOpen })    one file in the middle: the files that link to it on the left, the files it
+ *                                       links to on the right, at most 7 a side; a press on a file centres the graph on
+ *                                       it, Back returns; List all N links lists every link by kind
+ *   initiativeGraph(lib, paths, …)      an initiative's files as filled dots and the outside files they link to as hollow
+ *                                       dots (at most 14, the most-connected first); a press marks a dot's lines
+ *
+ * Every line is a link a file writes (lib/kg.js on the server): a markdown link, a path in the header, the initiative, the
+ * anchor, a decision number. Nothing is inferred. The layouts are computed from the files and links alone, so the same
+ * input draws the same picture. The pictures are an SVG of lines behind real buttons, placed with --rp-x and --rp-y. On a
+ * phone neither picture is drawn: the file graph shows its list, and the initiative sheet shows its own list.
+ */
+
+import { el } from './dom.js';
+import { button, narrowViewport } from './primitives.js';
+import { pmGet } from './http.js';
+
+const NS = 'http://www.w3.org/2000/svg';
+const MAX_SIDE = 7;
+const MAX_OUTSIDE = 14;
+const LIST_CAP = 12;
+const KEEP_MS = 30000;
+
+export const GROUP_OUT = [['initiative', 'Its initiative'], ['header', 'Named in its header'], ['link', 'Links to'], ['anchor', 'Anchored to'], ['cites', 'Decisions it cites']];
+export const GROUP_IN = [['initiative', 'Its initiative'], ['header', 'Named by'], ['link', 'Linked from'], ['anchor', 'Anchors'], ['cites', 'Cited by']];
+const ROLE = { spec: 'PRD', ini: 'Initiative record', exp: 'Explainer', proto: 'Prototype' };
+
+/* ── the library ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const libs = new Map();   // ws -> { at, promise }
+
+/** The workspace's library, indexed, or null when it could not be read. One request per workspace while it is fresh. */
+export function getLibrary(ws, { fresh = false } = {}) {
+  const hit = libs.get(ws);
+  if (hit && !fresh && Date.now() - hit.at < KEEP_MS) return hit.promise;
+  const promise = pmGet('/api/docs/library?ws=' + encodeURIComponent(ws)).then((r) => (r && r.ok ? indexed(r) : null));
+  libs.set(ws, { at: Date.now(), promise });
+  promise.then((v) => { if (!v) libs.delete(ws); });
+  return promise;
+}
+
+/** The response with lookups: byPath, out and inn (per file: [[neighbour, kind]]), and each file's initiative. */
+export function indexed(r) {
+  const byPath = new Map(r.files.map((f, i) => [f.path, i]));
+  const out = r.files.map(() => []);
+  const inn = r.files.map(() => []);
+  for (const [a, b, k] of r.edges) { out[a].push([b, r.kinds[k]]); inn[b].push([a, r.kinds[k]]); }
+  const ini = (f) => (f.initiative && r.initiatives[f.initiative]) ? { id: f.initiative, ...r.initiatives[f.initiative] } : null;
+  return { ...r, byPath, out, inn, ini };
+}
+
+const KIND_RANK = { initiative: 0, header: 1, link: 2, anchor: 3, cites: 4 };
+/** One entry per neighbour (its strongest kind), cites last, then the same initiative first, then newest first. */
+function neighbours(lib, i) {
+  const me = lib.files[i].initiative;
+  const uniq = (xs) => {
+    const m = new Map();
+    for (const x of xs) if (x[0] !== i && (!m.has(x[0]) || KIND_RANK[x[1]] < KIND_RANK[m.get(x[0])[1]])) m.set(x[0], x);
+    return [...m.values()].sort((a, b) => {
+      const A = lib.files[a[0]]; const B = lib.files[b[0]];
+      return (a[1] === 'cites') - (b[1] === 'cites')
+        || (B.initiative && B.initiative === me) - (A.initiative && A.initiative === me)
+        || String(B.date || '').localeCompare(String(A.date || ''))
+        || A.path.localeCompare(B.path);
+    });
+  };
+  return { out: uniq(lib.out[i]), inn: uniq(lib.inn[i]) };
+}
+
+const clip = (t, n) => (t.length > n ? t.slice(0, n - 1) + '…' : t);
+const svg = (tag, attrs = {}) => { const n = document.createElementNS(NS, tag); for (const [k, v] of Object.entries(attrs)) if (v != null) n.setAttribute(k, String(v)); return n; };
+const place = (node, vars) => { for (const [k, v] of Object.entries(vars)) node.style.setProperty('--rp-' + k, String(Math.round(v * 100) / 100)); return node; };
+
+/* ── one file's links ────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * The links of one file. `onOpen(path, title)` opens a file in the reader. Returns an element that redraws itself: a press
+ * on a neighbour centres the graph on it, Back returns. On a phone the list is shown in place of the picture.
+ */
+export function fileGraph(lib, path, { onOpen } = {}) {
+  const start = lib.byPath.get(path);
+  const wrap = el('div', { class: 'rp-graph', 'data-graph': path });
+  if (start === undefined) { wrap.appendChild(el('p', { class: 'rp-graph__hint' }, 'This file is not in the library yet. It shows after its first commit.')); return wrap; }
+  const stack = [start];
+  const state = { list: false, more: new Set() };
+  const go = (j) => { stack.push(j); state.list = false; state.more.clear(); draw(); };
+  const draw = () => {
+    const i = stack[stack.length - 1];
+    const f = lib.files[i];
+    const { out, inn } = neighbours(lib, i);
+    const narrow = narrowViewport();
+    wrap.setAttribute('data-graph-focus', f.path);
+    const head = el('div', { class: 'rp-graph__head' },
+      stack.length > 1 ? button({ label: 'Back', icon: 'arrow-left', variant: 'ghost', size: 'sm', attrs: { 'data-graph-act': 'back' }, onClick: () => { stack.pop(); state.list = false; draw(); } }) : null,
+      el('span', { class: 'rp-graph__title' }, el('strong', null, clip(f.title, 80)), ` · ${inn.length === 1 ? '1 file links' : inn.length + ' files link'} here, it links to ${out.length}`),
+      onOpen ? button({ label: 'Open file', variant: 'outline', size: 'sm', attrs: { 'data-graph-act': 'open' }, onClick: () => onOpen(f.path, f.title) }) : null);
+    const kids = [head];
+    if (!inn.length && !out.length) {
+      kids.push(el('p', { class: 'rp-graph__hint' }, 'No file links to this one, and it links to none. Only links written in the files are shown.'));
+      wrap.replaceChildren(...kids);
+      return;
+    }
+    if (!narrow) kids.push(picture(lib, i, inn, out, go));
+    const total = inn.length + out.length;
+    if (!narrow) {
+      kids.push(button({ label: state.list ? 'Hide the list' : `List all ${total} links`, variant: 'ghost', size: 'sm',
+        attrs: { 'data-graph-act': 'list', 'aria-expanded': state.list ? 'true' : 'false' }, onClick: () => { state.list = !state.list; draw(); } }));
+    }
+    if (narrow || state.list) kids.push(lists(lib, inn, out, go, state, draw));
+    kids.push(el('p', { class: 'rp-graph__hint' }, 'Only links written in the files count: a link, a path in the header, the initiative, or a decision number like D65. A dashed line is a decision it cites. Press a file to see its own links.'));
+    wrap.replaceChildren(...kids);
+  };
+  draw();
+  return wrap;
+}
+
+/** The picture: who links here (left), this file (middle), what it links to (right). */
+function picture(lib, i, inn, out, go) {
+  const L = inn.slice(0, MAX_SIDE); const R = out.slice(0, MAX_SIDE);
+  const nL = L.length + (inn.length > MAX_SIDE ? 1 : 0); const nR = R.length + (out.length > MAX_SIDE ? 1 : 0);
+  const W = 820; const RH = 34; const NW = 250; const CW = 220;
+  const H = Math.max(nL, nR, 1) * RH + 16; const cx = W / 2; const cy = H / 2;
+  const yOf = (k, n) => cy + (k - (n - 1) / 2) * RH;
+  const pic = place(el('div', { class: 'rp-graph__pic', role: 'group', 'aria-label': `${lib.files[i].title}: ${inn.length} files link here, it links to ${out.length}` }), { ar: W / H });
+  const lines = svg('svg', { class: 'rp-graph__lines', viewBox: `0 0 ${W} ${H}`, preserveAspectRatio: 'none', 'aria-hidden': 'true' });
+  const curve = (x1, y1, x2, y2, kind) => svg('path', { class: 'rp-graph__edge' + (kind === 'cites' ? ' rp-graph__edge--cites' : ''), d: `M${x1},${y1} C${(x1 + x2) / 2},${y1} ${(x1 + x2) / 2},${y2} ${x2},${y2}` });
+  L.forEach(([, k], n) => lines.appendChild(curve(NW, yOf(n, nL), cx - CW / 2, cy, k)));
+  R.forEach(([, k], n) => lines.appendChild(curve(cx + CW / 2, cy, W - NW, yOf(n, nR), k)));
+  pic.appendChild(lines);
+  const node = (j, kind, x, y, side) => place(button({ label: clip(lib.files[j].title, 40), variant: 'outline', size: 'sm',
+    attrs: { class: 'rp-graph__node rp-graph__node--' + side + (kind === 'cites' ? ' rp-graph__node--cites' : ''), title: `${lib.files[j].title}\n${lib.files[j].path}`,
+      'data-graph-node': lib.files[j].path, 'data-graph-side': side, 'data-graph-kind': kind }, onClick: () => go(j) }), { x: (x / W) * 100, y: (y / H) * 100, w: (NW / W) * 100 });
+  L.forEach(([j, k], n) => pic.appendChild(node(j, k, 0, yOf(n, nL), 'in')));
+  R.forEach(([j, k], n) => pic.appendChild(node(j, k, W - NW, yOf(n, nR), 'out')));
+  const more = (n, x, y, side) => place(el('span', { class: 'rp-graph__more rp-graph__more--' + side }, `+ ${n} more in the list`), { x: (x / W) * 100, y: (y / H) * 100, w: (NW / W) * 100 });
+  if (inn.length > MAX_SIDE) pic.appendChild(more(inn.length - MAX_SIDE, 0, yOf(L.length, nL), 'in'));
+  if (out.length > MAX_SIDE) pic.appendChild(more(out.length - MAX_SIDE, W - NW, yOf(R.length, nR), 'out'));
+  pic.appendChild(place(el('span', { class: 'rp-graph__centre', title: lib.files[i].path }, clip(lib.files[i].title, 34)), { x: ((cx - CW / 2) / W) * 100, y: (cy / H) * 100, w: (CW / W) * 100 }));
+  pic.appendChild(el('span', { class: 'rp-graph__cap rp-graph__cap--in' }, 'Links here'));
+  pic.appendChild(el('span', { class: 'rp-graph__cap rp-graph__cap--out' }, 'It links to'));
+  return pic;
+}
+
+/** Every link, both directions, grouped by kind. A group longer than 12 shows its first 12 and a Show all. */
+function lists(lib, inn, out, go, state, draw) {
+  const col = (xs, groups, label, side) => el('div', { class: 'rp-graph__col', 'data-graph-list': side },
+    el('span', { class: 'rp-graph__label' }, label),
+    groups.map(([kind, name]) => {
+      const g = xs.filter((x) => x[1] === kind);
+      if (!g.length) return null;
+      const key = side + kind;
+      const shown = state.more.has(key) ? g : g.slice(0, LIST_CAP);
+      return el('div', { class: 'rp-graph__group' },
+        el('span', { class: 'rp-graph__label' }, `${name} · ${g.length}`),
+        shown.map(([j]) => button({ label: lib.files[j].title, variant: 'ghost', size: 'sm', attrs: { class: 'rp-graph__item', title: lib.files[j].path, 'data-graph-item': lib.files[j].path }, onClick: () => go(j) })),
+        g.length > shown.length ? button({ label: `Show all ${g.length}`, variant: 'ghost', size: 'sm', onClick: () => { state.more.add(key); draw(); } }) : null);
+    }));
+  return el('div', { class: 'rp-graph__lists' }, col(inn, GROUP_IN, 'Links here', 'in'), col(out, GROUP_OUT, 'It links to', 'out'));
+}
+
+/* ── an initiative's files ───────────────────────────────────────────────────────────────────────────────────────── */
+
+/** The short label of a dot: a decision's number, the role of an initiative's file, or else its title, shortened. */
+export function roleOf(f) {
+  const d = /^(D\d+)\b/.exec(f.title);
+  if (d) return d[1];
+  if (f.category === 'eval') return /rubric/i.test(f.title + ' ' + f.path) ? 'Rubric' : /verdict/i.test(f.path) ? 'Verdict' : 'Eval';
+  return ROLE[f.category] || clip(f.title.replace(/^[^:]{1,24}:\s+/, ''), 22);
+}
+
+/**
+ * The positions of an initiative's network: its files (inner) and the outside files they link to (outer, at most 14).
+ * Pure and deterministic: the same files and links give the same positions. Exported for the tests.
+ */
+export function networkLayout(lib, paths, { W = 820, H = 460 } = {}) {
+  const inner = [...new Set(paths.map((p) => lib.byPath.get(p)).filter((x) => x !== undefined))].sort((a, b) => lib.files[a].path.localeCompare(lib.files[b].path));
+  const isIn = new Set(inner);
+  const score = new Map();
+  for (const i of inner) for (const [j] of [...lib.out[i], ...lib.inn[i]]) if (!isIn.has(j)) score.set(j, (score.get(j) || 0) + 1);
+  const outside = [...score.entries()].sort((a, b) => b[1] - a[1] || String(lib.files[b[0]].date || '').localeCompare(String(lib.files[a[0]].date || '')) || lib.files[a[0]].path.localeCompare(lib.files[b[0]].path));
+  const outer = outside.slice(0, MAX_OUTSIDE).map((x) => x[0]);
+  const ids = [...inner, ...outer];
+  const on = new Set(ids);
+  const cx = W / 2; const cy = H / 2;
+  const pos = new Map();
+  ids.forEach((i, k) => {
+    const mine = isIn.has(i); const n = mine ? inner.length : outer.length; const kk = mine ? k : k - inner.length;
+    const a = (kk / Math.max(n, 1)) * Math.PI * 2 + (mine ? 0 : 0.3); const r = mine ? 70 : 190;
+    pos.set(i, { x: cx + r * Math.cos(a) * 1.6, y: cy + r * Math.sin(a), vx: 0, vy: 0 });
+  });
+  const edges = [];
+  const seen = new Set();
+  for (const i of ids) for (const [j, kind] of lib.out[i]) {
+    if (!on.has(j) || i === j || !(isIn.has(i) || isIn.has(j))) continue;
+    const key = i + '>' + j;
+    if (seen.has(key)) continue;
+    seen.add(key); edges.push([i, j, kind]);
+  }
+  for (let it = 0; it < 500; it++) {
+    for (let a = 0; a < ids.length; a++) for (let b = a + 1; b < ids.length; b++) {
+      const A = pos.get(ids[a]); const B = pos.get(ids[b]);
+      let dx = A.x - B.x; let dy = (A.y - B.y) * 1.6;
+      const d2 = Math.max(dx * dx + dy * dy, 25); const f = 26000 / d2; const d = Math.sqrt(d2);
+      dx /= d; dy /= d; A.vx += dx * f; A.vy += dy * f; B.vx -= dx * f; B.vy -= dy * f;
+    }
+    for (const [i, j] of edges) {
+      const A = pos.get(i); const B = pos.get(j);
+      const dx = B.x - A.x; const dy = B.y - A.y; const d = Math.sqrt(dx * dx + dy * dy) || 1; const f = (d - 150) * 0.02;
+      A.vx += (dx / d) * f; A.vy += (dy / d) * f; B.vx -= (dx / d) * f; B.vy -= (dy / d) * f;
+    }
+    for (const i of ids) {
+      const P = pos.get(i); const g = isIn.has(i) ? 0.02 : 0.005;
+      P.vx += (cx - P.x) * g; P.vy += (cy - P.y) * g * 1.4;
+      P.x += Math.max(-20, Math.min(20, P.vx * 0.5)); P.y += Math.max(-20, Math.min(20, P.vy * 0.5));
+      P.vx *= 0.5; P.vy *= 0.5;
+      P.x = Math.max(30, Math.min(W - 160, P.x)); P.y = Math.max(22, Math.min(H - 22, P.y));
+    }
+  }
+  const at = new Map(ids.map((i) => [i, { x: Math.round(pos.get(i).x * 10) / 10, y: Math.round(pos.get(i).y * 10) / 10 }]));
+  return { W, H, inner, outer, left: outside.length - outer.length, edges, at };
+}
+
+/**
+ * An initiative's files as a network. `onOpen(path, title)` opens a file. Returns null on a phone: the caller shows its
+ * list instead (R-N5).
+ */
+export function initiativeGraph(lib, paths, { onOpen } = {}) {
+  if (narrowViewport()) return null;
+  const L = networkLayout(lib, paths);
+  const isIn = new Set(L.inner);
+  const wrap = el('div', { class: 'rp-net', 'data-net': '' });
+  if (!L.inner.length) { wrap.appendChild(el('p', { class: 'rp-graph__hint' }, 'None of this initiative’s files is in the library yet. They show after their first commit.')); return wrap; }
+  let sel = null;
+  const draw = () => {
+    const pic = place(el('div', { class: 'rp-net__pic', role: 'group', 'aria-label': `${L.inner.length} files of this initiative and ${L.outer.length} files outside it that they link to` }), { ar: L.W / L.H });
+    const lines = svg('svg', { class: 'rp-net__lines', viewBox: `0 0 ${L.W} ${L.H}`, preserveAspectRatio: 'none', 'aria-hidden': 'true' });
+    for (const [i, j, kind] of L.edges) {
+      const A = L.at.get(i); const B = L.at.get(j);
+      const cls = ['rp-net__edge', kind === 'cites' && 'rp-net__edge--cites', isIn.has(i) && isIn.has(j) && 'rp-net__edge--in', sel !== null && (sel === i || sel === j) && 'rp-net__edge--hot'].filter(Boolean).join(' ');
+      lines.appendChild(svg('line', { class: cls, x1: A.x, y1: A.y, x2: B.x, y2: B.y, 'data-net-edge': `${lib.files[i].path}>${lib.files[j].path}` }));
+    }
+    pic.appendChild(lines);
+    for (const i of [...L.inner, ...L.outer]) {
+      const f = lib.files[i]; const mine = isIn.has(i); const P = L.at.get(i);
+      const label = mine ? roleOf(f) : ((/^(D\d+)\b/.exec(f.title) || [])[1] || clip(f.title, 22));
+      pic.appendChild(place(button({ label: [el('span', { class: 'rp-net__dot' + (mine ? ' rp-net__dot--in' : ''), 'aria-hidden': 'true' }), el('span', { class: 'rp-net__label' }, label)],
+        variant: 'ghost', size: 'sm',
+        attrs: { class: 'rp-net__node' + (mine ? ' rp-net__node--in' : '') + (sel === i ? ' rp-net__node--sel' : ''), title: `${f.title}\n${f.path}`, 'aria-label': f.title, 'aria-pressed': sel === i ? 'true' : 'false',
+          'data-net-node': f.path, 'data-net-side': mine ? 'in' : 'out' },
+        onClick: () => { sel = sel === i ? null : i; draw(); } }), { x: (P.x / L.W) * 100, y: (P.y / L.H) * 100 }));
+    }
+    const legend = el('div', { class: 'rp-net__legend' },
+      el('span', null, el('span', { class: 'rp-net__dot rp-net__dot--in', 'aria-hidden': 'true' }), 'This initiative'),
+      el('span', null, el('span', { class: 'rp-net__dot', 'aria-hidden': 'true' }), 'Outside it'),
+      el('span', null, el('span', { class: 'rp-net__dash', 'aria-hidden': 'true' }), 'Cites a decision'),
+      L.left ? el('span', { 'data-net-left': String(L.left) }, `${L.left} more outside files are left out. Open a file in Docs to see all its links.`) : null);
+    const kids = [pic, legend];
+    if (sel !== null) {
+      const f = lib.files[sel];
+      const ini = lib.ini(f);
+      kids.push(el('div', { class: 'rp-net__sel', 'data-net-sel': f.path },
+        el('span', { class: 'rp-net__sel-text' }, el('strong', null, f.title), el('span', { class: 'rp-net__path' }, f.path + (ini && !isIn.has(sel) ? ' · ' + ini.short : ''))),
+        onOpen ? button({ label: 'Open file', variant: 'outline', size: 'sm', attrs: { 'data-net-act': 'open' }, onClick: () => onOpen(f.path, f.title) }) : null));
+    }
+    wrap.replaceChildren(...kids);
+  };
+  draw();
+  return wrap;
+}