create-pmos 0.38.7 → 0.39.0

package/workspace/public/pm/panel-initiatives.js

@@ -265,15 +265,19 @@ export function openTerm(slug, sess) {
   });
 }
 
-export function openDoc(slug, path, role, tree) {
+export function openDoc(slug, path, role, tree, opts) {
   /* `tree` — the line of work a search hit came from (overhaul-r1 R1.3). A hit on a LINKED worktree
    * opens a tab that carries that tree's `ws` and `branch`, under its own id, so it is read from and
    * saved to that tree and can sit beside the main tree's copy of the same path. A main-tree hit
    * opens exactly the tab it always did. */
   const linked = !!(tree && tree.ws && tree.linked);
+  // `opts.ref` — read the file from that initiative branch through git (it is not in the checked-out tree);
+  // `opts.readonly` — a git file is evidence, so the tab offers no edit or save.
+  const ref = opts && opts.ref ? opts.ref : null;
   openTab({
-    id: 'doc:' + (linked ? tree.ws + ':' : '') + path, kind: 'doc', title: path.split('/').pop(), slug,
+    id: 'doc:' + (linked ? tree.ws + ':' : '') + (ref ? 'ref:' + ref + ':' : '') + path, kind: 'doc', title: path.split('/').pop(), slug,
     ...(linked ? { ws: tree.ws, branch: tree.branch || null } : {}),
+    ...(ref ? { ref } : {}), ...(opts && opts.readonly ? { readonly: true } : {}),
     /* A file opened from the FOLDER search belongs to no initiative, so `slugProduct()` has no
      * answer for it — and `panel-tabs.visibleTabs` shows a tab whose repo is `undefined` in EVERY
      * repository, which would hang this workspace's file in another one's tab strip and read its
@@ -828,7 +832,61 @@ export function renderInitiatives(host) {
 
   const hits = searchHits(q, DATA, live);
 
-  const kids = [header, searchBox];
+  /* GROUP BY STATUS (initiative-surface-batch R2). The status is the one the server DERIVES (deriveState + the
+   * lifecycle ledger), mapped to the PM's words by lib/status-groups.js; nothing typed in a record decides where a
+   * row lands. A failed read of the statuses is said under the control and everything files under Unknown. */
+  const SG = typeof window !== 'undefined' ? window.PMOSStatusGroups : null;
+  const byStatus = state.groupBy === 'status' && !!SG;
+  const statusRows = (state.statuses && state.statuses[product]) || {};
+  const statusErr = (state.statusErrors && state.statusErrors[product]) || null;
+  const STATUS_TONE = { 'needs-you': 'var(--destructive)', 'in-progress': 'var(--brand)', planning: 'var(--muted-foreground)',
+    'awaiting-acceptance': 'var(--foreground)', accepted: 'var(--muted-foreground)', 'on-hold': 'var(--muted-foreground)',
+    closed: 'var(--muted-foreground)', cancelled: 'var(--muted-foreground)', unknown: 'var(--destructive)' };
+  if (byStatus) {
+    const seen = new Set(); const all = [];
+    for (const g of groupsFor(product)) for (const sl of g.slugs) if (!seen.has(sl)) { seen.add(sl); all.push(sl); }
+    const shown = all.filter((sl) => !q || sl.includes(q));
+    // An active search shows every match whatever its status: the "active" filter must not hide a hit.
+    const sgs = SG.group(shown, statusRows, { activeOnly: !!state.activeOnly && !q });
+    total = 0;
+    groups.length = 0;
+    for (const sg of sgs) {
+      const inits = sg.slugs.map((sl) => rowOf(sl, null));
+      total += inits.length;
+      groups.push({ gid: 'status:' + sg.key, idc: STATUS_TONE[sg.key] || 'var(--muted-foreground)', gname: sg.label, gct: String(inits.length),
+        hasKr: true, krid: '●', krname: sg.meaning || sg.hint, krct: String(inits.length), slugs: sg.slugs, inits, isEmpty: false });
+    }
+  }
+  const CHIP = 'font-family:var(--mono);font-size:10.5px;padding:2px 8px;border:1px solid var(--border);min-height:24px';
+  const chip = (label, on, onClick, attr) => el('button', { onClick, 'data-r16': attr,
+    style: CHIP + ';' + (on ? 'color:var(--foreground);background:var(--secondary);border-color:var(--input)' : 'color:var(--muted-foreground)'),
+    hover: 'color:var(--foreground)', 'aria-pressed': on ? 'true' : 'false' }, label);
+  const groupBar = FIXTURE ? null : el('div', { 'data-r16': 'group-bar', style: 'display:flex;gap:5px;flex-wrap:wrap;align-items:center;padding:4px 12px 6px' },
+    el('span', { style: 'font-family:var(--mono);font-size:10px;letter-spacing:.08em;text-transform:uppercase;color:var(--muted-foreground)' }, 'group by'),
+    chip('objective', !byStatus, () => setState({ groupBy: 'objective' }), 'by-objective'),
+    chip('status', byStatus, () => setState({ groupBy: 'status' }), 'by-status'),
+    byStatus ? chip('active only', !!state.activeOnly, () => setState({ activeOnly: !state.activeOnly }), 'active-only') : null,
+    SG ? chip('what do these mean?', !!state.legendOpen, () => setState({ legendOpen: !state.legendOpen }), 'legend-toggle') : null,
+    byStatus && statusErr ? el('span', { 'data-r16': 'status-error', style: 'flex-basis:100%;font-size:10.5px;color:var(--destructive)' }, 'status could not be read — ' + statusErr + ' (every initiative is under Unknown)') : null);
+
+  /* THE LEGEND (status-clarity R1). One row per group, read from the same table that files the rows, so what this
+   * says and where a row lands cannot disagree: what it means, the fact it is read from, who acts, what moves it,
+   * and what the PM can do by hand. */
+  const OWNER_WORD = { pm: 'you', agent: 'the agent', system: 'nobody (derived)' };
+  const legend = !FIXTURE && SG && state.legendOpen ? el('div', { 'data-r18': 'legend',
+    style: 'display:flex;flex-direction:column;gap:8px;margin:0 12px 8px;padding:8px 10px;border:1px solid var(--border);background:var(--secondary)' },
+    el('div', { style: 'font-size:11px;color:var(--muted-foreground);line-height:1.5' },
+      'A status is never typed. It is worked out again each time from the ledgers and git. You can only hold, close, cancel or reopen an initiative by hand.'),
+    SG.GROUPS.map((g) => el('div', { 'data-r18': 'legend-row', 'data-key': g.key, style: 'display:flex;flex-direction:column;gap:2px;padding-top:6px;border-top:1px solid var(--border)' },
+      el('div', { style: 'display:flex;gap:7px;align-items:baseline' },
+        el('span', { style: 'font-size:12px;font-weight:600;color:' + (STATUS_TONE[g.key] || 'var(--foreground)') }, g.label),
+        el('span', { style: 'font-family:var(--mono);font-size:9.5px;letter-spacing:.1em;text-transform:uppercase;color:var(--muted-foreground)' }, 'acts: ' + (OWNER_WORD[g.owner] || g.owner))),
+      el('div', { style: 'font-size:11.5px;line-height:1.5;color:var(--foreground)' }, g.meaning),
+      el('div', { style: 'font-size:10.5px;line-height:1.5;color:var(--muted-foreground)' }, 'read from: ' + g.source),
+      el('div', { style: 'font-size:10.5px;line-height:1.5;color:var(--muted-foreground)' }, 'moves: ' + g.moves),
+      el('div', { style: 'font-size:10.5px;line-height:1.5;color:var(--muted-foreground)' }, 'you can: ' + g.pmCan)))) : null;
+
+  const kids = [header, searchBox, groupBar, legend];
   /* THE WORKING SET, pinned above the Objectives.
    *
    * It is `groupNode` — the same element, the same collapse key, the same forced-open-on-search

package/workspace/public/pm/panel-repos.js

@@ -177,8 +177,8 @@ export const UNBACKED_MODES = ['agent', 'connect'];   // mode ids (labels: agent
 /* overhaul-r4 — the PORTFOLIO mode joins "all repositories" in live mode only (the fixture drawer is the
  * prototype's, and the design comparison reads it). Its meta lives here, not in fixture.js, for the
  * same reason. */
-const META = Object.assign({}, MODE_META, { portfolio: ['▦', 'portfolio'] });
-const LIVE_EXTRA = { 'all repositories': ['portfolio'] };
+const META = Object.assign({}, MODE_META, { portfolio: ['▦', 'portfolio'], guide: ['?', 'guide'], validate: ['◉', 'validate'] });
+const LIVE_EXTRA = { 'all repositories': ['portfolio', 'guide', 'validate'] };
 const DRAWER_GROUPS = SETTINGS_GROUPS.map((g) => ({
   label: g.label,
   items: (FIXTURE ? [] : LIVE_EXTRA[g.label] || []).concat(

package/workspace/public/pm/panel-tabs.js

@@ -42,7 +42,7 @@ import { boardOf, currentProduct } from './board-read.js';
 let termMod = null;
 let liveMod = null;
 /* Loaded lazily; a repaint is asked for only when a skill tab is already open (restored on reload) and waiting for it. */
-import('./modes-live.js').then((m) => { liveMod = m; if ((state.tabs || []).some((t) => t.kind === 'skill')) setState({}); }).catch(() => { liveMod = null; });
+import('./modes-live.js').then((m) => { liveMod = m; if ((state.tabs || []).some((t) => t.kind === 'skill' || t.kind === 'transcript')) setState({}); }).catch(() => { liveMod = null; });
 import('./tab-term.js')
   .then((m) => { termMod = m; setState({}); })
   .catch(() => { termMod = null; });
@@ -144,6 +144,40 @@ export function closeTab(id) {
   });
 }
 
+/**
+ * The terminal tabs attached to ONE session, by tab id (initiative-surface-batch R1).
+ *
+ * A terminal tab carries the SERVER's session id (`sessionId`), which is the exact join. Read it BEFORE the
+ * server is asked to end the session, not after: the moment the server drops the session it pushes the new
+ * list, and a tab whose id is no longer listed re-joins by NAME (tab-term.js `resolveSessionId`) — so when two
+ * sessions share a name the doomed tab quietly adopts its sibling and starts reporting the sibling's id, and a
+ * lookup made after the answer finds nothing to close.
+ */
+export function tabIdsOfSession(sessionId) {
+  if (!sessionId) return [];
+  return (state.tabs || []).filter((t) => t && t.kind === 'term' && t.sessionId === sessionId).map((t) => t.id);
+}
+
+/**
+ * Close tabs by id. Called only after the server said the session is gone; closing a tab by hand still only
+ * detaches. Another session's tab, and a tab that is not in `ids`, are untouched. Returns how many closed.
+ */
+export function closeTabsById(ids) {
+  const doomed = (state.tabs || []).filter((t) => t && (ids || []).includes(t.id)).map((t) => t.id);
+  if (!doomed.length) return 0;
+  setState((s) => {
+    const rest = s.tabs.filter((t) => !doomed.includes(t.id));
+    return {
+      tabs: rest,
+      active: doomed.includes(s.active) ? (rest.length ? rest[rest.length - 1].id : null) : s.active,
+      splitId: doomed.includes(s.splitId) ? null : s.splitId,
+    };
+  });
+  return doomed.length;
+}
+
+export const closeTabsOfSession = (sessionId) => closeTabsById(tabIdsOfSession(sessionId));
+
 /* The data layer's optional session-start hook. In fixture mode nothing is ever started; in real
  * mode the PTY is data.js's to create, and panel 4's part is only to show the tab for it. */
 let dataMod = null;
@@ -797,6 +831,8 @@ function paneFor(tab) {
     mountTask(host, tab);
   } else if (tab.kind === 'skill') {
     if (liveMod && typeof liveMod.mountSkillTab === 'function') liveMod.mountSkillTab(host, tab);
+  } else if (tab.kind === 'transcript') {
+    if (liveMod && typeof liveMod.mountTranscriptTab === 'function') liveMod.mountTranscriptTab(host, tab);
   } else if (tab.kind === 'web') {
     mountWeb(host, tab);              // overhaul-r5 — never falls through to an empty doc tab
   } else {
@@ -913,7 +949,7 @@ function tabNode(t, act, splitTab) {
    * fixture render keeps the design's literal — the comparator reads this text node. */
   const meta = t.kind === 'term'
     ? ((!FIXTURE && t.sessionId) ? 'session ' + t.sessionId : 'session')
-    : (t.kind === 'task' ? 'task' : t.kind === 'web' ? 'web' : t.kind === 'skill' ? 'skill' : t.role);
+    : (t.kind === 'task' ? 'task' : t.kind === 'web' ? 'web' : t.kind === 'skill' ? 'skill' : t.kind === 'transcript' ? 'conversation' : t.role);
 
   return el('div', {
     style: 'flex:none;display:flex;align-items:center;gap:8px;padding:0 10px;background:' + bg

package/workspace/public/pm/panel-trees.js

@@ -23,10 +23,11 @@ const MONO = 'font-family:var(--mono);font-size:10.5px';
 const BTN = MONO + ';padding:2px 8px;border:1px solid var(--border);color:var(--muted-foreground);min-height:24px';
 const MUTED = 'color:var(--muted-foreground)';
 
-let dataMod = null; let termMod = null; let iniMod = null;
+let dataMod = null; let termMod = null; let iniMod = null; let tabsMod = null;
 import('./data.js').then((m) => { dataMod = m; }).catch(() => { dataMod = null; });
 import('./tab-term.js').then((m) => { termMod = m; }).catch(() => { termMod = null; });
 import('./panel-initiatives.js').then((m) => { iniMod = m; }).catch(() => { iniMod = null; });
+import('./panel-tabs.js').then((m) => { tabsMod = m; }).catch(() => { tabsMod = null; });
 
 const note = (name, text, tone) => setState({ treeNote: { name, text, tone: tone || null } });
 const refresh = () => (dataMod && dataMod.refreshTrees ? dataMod.refreshTrees() : Promise.resolve());
@@ -62,10 +63,16 @@ export async function startHere(name, t) {
 }
 
 async function endSession(name, s) {
+  // Which tabs are on this session, read BEFORE asking: once the server drops it, a tab re-joins by name and stops saying.
+  const tabIds = tabsMod && typeof tabsMod.tabIdsOfSession === 'function' ? tabsMod.tabIdsOfSession(s.id) : [];
   const out = dataMod ? await dataMod.removeSessionById(s.id) : null;
   setState({ treeConfirm: null });
   if (!out || out.ok === false) { note(name, (out && out.error) || 'the session could not be removed', 'bad'); return; }
-  note(name, out.removed === false ? (out.note || 'asked it to end') : 'session removed');
+  // The session is gone: the tab attached to it has nothing left to show, so it closes too (R1). A refusal returned
+  // above and leaves the tab open beside the reason; so does "asked it to end, not exited yet" — the process is still
+  // there, and pressing again removes it and closes the tab.
+  const closed = out.removed !== false && tabsMod && typeof tabsMod.closeTabsById === 'function' ? tabsMod.closeTabsById(tabIds) : 0;
+  note(name, (out.removed === false ? (out.note || 'asked it to end') : 'session removed') + (closed ? ' — its tab was closed' : ''));
 }
 
 async function removeTree(name, t) {

package/workspace/public/pm/state.js

@@ -24,7 +24,7 @@ const STORE_KEY = 'pmos.workspace.pm.v1';
 /** The initial state — the prototype's `state = {…}` block, key for key. */
 function initial() {
   return {
-    theme: 'dark', sel: null, q: '', mode: 'product', collapsedGroups: {}, settingsOpen: false,
+    theme: 'dark', sel: null, q: '', mode: 'product', collapsedGroups: {}, groupBy: 'objective', activeOnly: false, legendOpen: false, settingsOpen: false,
     product: null, intgSynced: {},
     addSrc: 'github', addRepo: 'github.com/acme/atlas-mobile', addPath: '~/code/notes-cli',
     addLog: [], addedProducts: [], extraKnow: {},
@@ -153,7 +153,9 @@ const TAB_FIELDS = ['id', 'kind', 'title', 'slug', 'repo', 'sess', 'sessionId',
   // a web tab's address (overhaul-r5, D69) — restored, re-validated, and loaded only on a PM press
   'url',
   // a skill tab's skill id — a reload reopens the same skill
-  'skillId'];
+  'skillId',
+  // a conversation tab's session id — a reload reopens the same transcript
+  'convId'];
 const MAX_TABS = 40;
 
 function packTab(t) {
@@ -174,13 +176,16 @@ const isTabList = (v) =>
 const PERSIST = {
   theme: (v) => v === 'dark' || v === 'light',
   col0: isBool, col1: isBool, col2: isBool,
-  // the dragged widths of panels 1 and 2 (clamped again by app.js on the way out)
+  // the dragged width of the navigation column (clamped again by app.js on the way out). `col1` now means "the list under the
+  // repositories is open"; the old second-column width (col1W) is no longer stored and an old value is ignored on load.
   col0W: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 100 && v <= 1200,
-  col1W: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 100 && v <= 1200,
   settingsOpen: isBool,
   product: isSlug,
   sel: isSlug,
   collapsedGroups: isFlagMap,
+  // how the initiative list is grouped: by objective (default) or by derived status (initiative-surface-batch R2)
+  groupBy: (v) => v === 'objective' || v === 'status',
+  activeOnly: isBool,
   collapsedPhases: isFlagMap,
   // per doc tab: true = 72ch measure, false = full width; absent = the viewport default (R5.1)
   docNarrow: isFlagMap,

package/workspace/public/pm/status-banner.js

@@ -0,0 +1,87 @@
+/**
+ * status-banner.js — status-clarity R2/R3/R4. The block at the top of an initiative that says where it stands.
+ *
+ * It states, from facts the server already derived: the group, why (the evidence behind it), who acts, the one
+ * thing to do next, how the status will change, and, for "needs you", each open item by its own words. It adds
+ * no fact of its own: the group text comes from lib/status-groups.js, the evidence from deriveState, the steps
+ * from lib/next-steps.js. A failed read says so and shows no group.
+ *
+ * The lifecycle control (hold, close, cancel, reopen) sits beside it with one sentence on what it does and the
+ * history of every change. Acceptance is the PM's and is recorded in a session, not by a button here (D12), so the
+ * banner says how and offers the list of what is waiting.
+ */
+import { el } from './dom.js';
+import { state, setState, FIXTURE } from './state.js';
+
+const SG = () => (typeof window !== 'undefined' ? window.PMOSStatusGroups : null);
+const LAB = 'font-family:var(--mono);font-size:9.5px;letter-spacing:.12em;text-transform:uppercase;color:var(--muted-foreground)';
+const TONE = { 'needs-you': 'var(--destructive)', 'in-progress': 'var(--brand)', 'awaiting-acceptance': 'var(--foreground)', unknown: 'var(--destructive)' };
+const WHO = { pm: 'you', agent: 'the agent', system: 'nobody — it is derived' };
+const iv = (t) => el('span', null, t == null ? '' : String(t));
+
+function line(label, value, attr) {
+  return el('div', { style: 'display:grid;grid-template-columns:78px 1fr;gap:8px;padding:2px 0' },
+    el('span', { style: LAB + ';padding-top:2px' }, label),
+    el('span', { 'data-r18': attr, style: 'font-size:12px;line-height:1.5;color:var(--foreground);overflow-wrap:anywhere' }, iv(value)));
+}
+
+/** @returns {HTMLElement|null} null in fixture mode (the prototype has no such block). */
+export function statusBanner(product, slug, rec) {
+  const sg = SG();
+  if (FIXTURE || !sg || !slug) return null;
+  const err = state.statusErrors && state.statusErrors[product];
+  const row = state.statuses && state.statuses[product] && state.statuses[product][slug];
+  if (err || !row) {
+    return el('div', { 'data-r18': 'status-banner', 'data-key': 'unreadable', style: 'padding:8px 14px;border-bottom:1px solid var(--border)' },
+      el('span', { style: LAB }, 'status'),
+      el('div', { 'data-r18': 'status-error', style: 'font-size:12px;color:var(--destructive);line-height:1.5' },
+        'The status could not be read — ' + (err || 'the server returned no status for this initiative') + '. No group is shown because none can be derived.'));
+  }
+  const key = sg.keyOf(row);
+  const g = sg.BY_KEY[key];
+  const items = (rec && rec.nextSteps && rec.nextSteps.items) || [];
+  const waiting = items.filter((i) => i.kind === 'needs' || i.kind === 'returned');
+  // The one thing to do next: the engine's first item, unless it is not yours and something is waiting on you.
+  const mine = items.filter((i) => i.owner === 'pm' && !i.held);
+  const first = items.find((i) => i.first) || items[0] || null;
+  const next = g.owner === 'pm' ? (mine[0] || first) : first;
+  const nextText = next ? next.text + ' — ' + next.action : (g.key === 'accepted' ? 'Nothing remains.' : 'No step is outstanding.');
+
+  const kids = [
+    el('div', { style: 'display:flex;gap:8px;align-items:baseline;flex-wrap:wrap' },
+      el('span', { style: LAB }, 'status'),
+      el('span', { 'data-r18': 'status-group', style: 'font-size:13px;font-weight:600;color:' + (TONE[key] || 'var(--foreground)') }, g.label),
+      el('span', { style: 'font-family:var(--mono);font-size:9.5px;letter-spacing:.1em;text-transform:uppercase;color:var(--muted-foreground)' }, 'derived, not typed')),
+    line('why', row.statusText ? row.statusText + '. ' + g.meaning : g.meaning, 'status-why'),
+    line('acts now', WHO[g.owner] || g.owner, 'status-owner'),
+    line('next', nextText, 'status-next'),
+    line('changes when', g.moves, 'status-moves'),
+  ];
+  if (waiting.length) {
+    kids.push(el('div', { 'data-r18': 'needs-items', style: 'display:flex;flex-direction:column;gap:2px;padding-top:4px' },
+      el('span', { style: LAB }, 'waiting on you · ' + waiting.length),
+      waiting.map((w) => el('div', { 'data-r18': 'needs-item', style: 'font-size:12px;line-height:1.5;color:var(--foreground);padding-left:10px;border-left:2px solid var(--destructive)' },
+        iv(w.text + (w.action ? ' — ' + w.action : ''))))));
+  }
+  if (key === 'awaiting-acceptance' || key === 'needs-you') {
+    kids.push(el('div', { 'data-r18': 'acceptance-note', style: 'font-size:11px;line-height:1.5;color:var(--muted-foreground);padding-top:4px' },
+      'Acceptance is yours and cannot be delegated (D12). Tell the session that holds this initiative to record it, or run scripts/record-acceptance.js. The workspace never records one for you.'),
+      el('button', { 'data-r18': 'see-waiting', onClick: () => setState({ mode: 'focus', settingsOpen: false, col1: true }),
+        style: 'align-self:flex-start;font-family:var(--mono);font-size:10px;padding:2px 7px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground);margin-top:4px' },
+        'see everything waiting on you'));
+  }
+  return el('div', { 'data-r18': 'status-banner', 'data-key': key, style: 'display:flex;flex-direction:column;gap:2px;padding:8px 14px;border-bottom:1px solid var(--border)' }, kids);
+}
+
+/** What the lifecycle control does, and every change made with it. Sits under the control row. */
+export function lifecycleNotes(rec) {
+  if (FIXTURE) return null;
+  const hist = (rec && rec.lcHistory) || [];
+  return el('div', { 'data-r18': 'lifecycle-notes', style: 'display:flex;flex-direction:column;gap:2px;padding:4px 14px 6px;border-bottom:1px solid var(--border)' },
+    el('span', { 'data-r18': 'lifecycle-explain', style: 'font-size:10.5px;line-height:1.5;color:var(--muted-foreground)' },
+      'Hold, close and cancel take this initiative off the board and stop it gating; reopen puts it back. They are the only statuses you set by hand. Every other status is read from git and the ledgers, so it cannot be edited here.'),
+    hist.length ? el('div', { 'data-r18': 'lifecycle-history', style: 'display:flex;flex-direction:column;gap:1px' },
+      el('span', { style: LAB + ';padding-top:2px' }, 'lifecycle history · ' + hist.length),
+      hist.map((h) => el('span', { style: 'font-family:var(--mono);font-size:10px;color:var(--muted-foreground)' },
+        iv(String(h.at || '').slice(0, 10) + ' · ' + h.state + (h.reason ? ' — ' + h.reason : ''))))) : null);
+}

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

@@ -60,7 +60,7 @@ const wsId = () => state.wsId || state.ws || state.product || '';
  * `ws`, and is read from and saved to THAT tree. Two trees can hold the same path with different
  * content, so every per-document cache keys on tree + path; a main-tree tab keys on path alone,
  * exactly as before. */
-const docKey = (tab) => (tab && tab.ws ? tab.ws + '\u241f' : '') + (tab ? tab.path : '');
+const docKey = (tab) => (tab && tab.guide ? 'guide\u241f' : '') + (tab && tab.ws ? tab.ws + '\u241f' : '') + (tab && tab.ref ? tab.ref + '\u241f' : '') + (tab ? tab.path : '');
 const wsOf = (tab) => (tab && tab.ws) || wsId();
 
 /* A REFERENCE is not a file. Panel 3's links section files `jira://ATL-501`, `confluence://PM/x`,
@@ -97,9 +97,12 @@ function requestDoc(tab) {
   if (pending.has(path)) return;
   pending.add(path);
   const done = (text) => { pending.delete(path); disk.set(path, text); setState({}); };
-  const load = (dataMod && typeof dataMod.readDoc === 'function')
-    ? dataMod.readDoc(tab.path, tab.ws)
-    : fetch('/api/doc?ws=' + encodeURIComponent(wsOf(tab)) + '&path=' + encodeURIComponent(tab.path))
+  // A guide page ships with the app and is read from it, not from the repository (status-clarity R6).
+  const load = tab.guide
+    ? fetch('/api/guide?page=' + encodeURIComponent(tab.path)).then((r) => (r.ok ? r.text() : Promise.reject(new Error('no such guide page'))))
+    : (dataMod && typeof dataMod.readDoc === 'function')
+    ? dataMod.readDoc(tab.path, tab.ws, tab.ref)
+    : fetch('/api/doc?ws=' + encodeURIComponent(wsOf(tab)) + '&path=' + encodeURIComponent(tab.path) + (tab.ref ? '&ref=' + encodeURIComponent(tab.ref) : ''))
       .then((r) => (r.ok ? r.text() : Promise.reject(new Error('HTTP ' + r.status))));
   Promise.resolve(load).then(
     (text) => { unread.delete(path); done(typeof text === 'string' ? text : String(text == null ? '' : text)); },
@@ -478,11 +481,13 @@ export function mountDoc(host, tab) {
   if (!FIXTURE && extOfPath(tab.path) === 'xlsx') { setChildren(host, [sheetBody(tab)]); return; }
   const raw = docText(tab);
   const text = state.docEdits[docKey(tab)] ?? raw;
-  const dm = state.docModes[tab.id] ?? 'view';
+  const dm = (tab.readonly && (state.docModes[tab.id] === 'edit' || state.docModes[tab.id] === 'diff')) ? 'view' : (state.docModes[tab.id] ?? 'view');
   const dirty = text !== raw;
   const err = saveErr.get(docKey(tab));
 
-  const modeBtns = ['view', 'raw', 'edit', 'diff'].map((mm) => el('button', {
+  // A file opened from the initiative's git files is evidence of what changed: it is read, never edited or saved here.
+  const readonly = !!tab.readonly;
+  const modeBtns = ['view', 'raw', 'edit', 'diff'].filter((mm) => !(readonly && (mm === 'edit' || mm === 'diff'))).map((mm) => el('button', {
     onClick: () => setState((s) => ({ docModes: { ...s.docModes, [tab.id]: mm } })),
     style: 'font-family:var(--mono);font-size:10.5px;padding:4px 10px;min-height:26px;background:'
       + (dm === mm ? 'var(--secondary)' : 'transparent')