create-pmos 0.166.0 → 0.168.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.166.0",
+  "version": "0.168.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@4ae0213
+kernel-source: pmos@21b6322
 assembled: 2026-10-12
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-12T13:44:56Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T14:26:40Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-12T13:44:56Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T14:26:40Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-12T13:44:56Z"}
+generated: {by: process:create-pmos, at: "2026-10-12T14:26:40Z"}
 status: stable
 ---
 

package/workspace/extension/README.md

@@ -0,0 +1,33 @@
+---
+type: Guide
+title: "PMOS for Google Meet: the Chrome extension"
+timestamp: 2026-10-12
+---
+
+# PMOS for Google Meet
+
+A small panel over a Google Meet call. It shows the PMOS meeting companion: the topic the room is on, the time left, what is being said, the notes from PMOS and a line to ask PMOS quietly. Only you see it. The extension has no build step and no remote code. It runs only on `https://meet.google.com/*`, reads the address and the title of the Meet tab, and talks only to the PMOS on your own computer.
+
+## Load it in Chrome
+
+1. Open `chrome://extensions`.
+2. Turn on **Developer mode** (top right).
+3. Press **Load unpacked** and pick this folder. `pmos extension` prints its path.
+
+If PMOS does not run on `http://localhost:7433`, open the extension's **Options** and set the address that `pmos` printed. A Meet tab that is already open picks up the new address when you reload it.
+
+## Use it
+
+Open a Meet call, for example `meet.google.com/abc-defg-hij`. The panel shows at the bottom right of the call. It finds the meeting on your PMOS calendar by the Meet link in the invite, then by the title of the tab, then by the meeting that is under way now. If none fits, the panel says so and lists today's meetings to pick from. **Fold** shrinks the panel to a pill, and the same button opens it again. **Open focus in PMOS** opens the full Meeting focus page in a new tab. When PMOS does not answer, the panel says "PMOS is not running at <address>" and links to the options.
+
+## Files
+
+| File | What it is |
+|---|---|
+| `manifest.json` | Manifest V3. Permission: `storage` only. Content script on `https://meet.google.com/*`. |
+| `content.js` | Adds the panel on a call page (`/abc-defg-hij`) and removes it when you leave. |
+| `panel.html`, `panel.js`, `panel.css` | The page inside the panel. It checks that PMOS answers, then frames PMOS's compact Meeting focus page. |
+| `options.html`, `options.js`, `options.css`, `address.js` | The one setting: where PMOS is. |
+| `icons/` | The PMOS icon at four sizes. |
+
+The extension ships in the workspace package. Publishing it in the Chrome Web Store is not part of it yet.

package/workspace/extension/address.js

@@ -0,0 +1,20 @@
+/* address.js — where PMOS is. Shared by panel.js and options.js (classic script; no build step).
+ * The address is kept in chrome.storage.sync under `pmosAddress`. The default is the workspace's default port.
+ * normalizeAddress('localhost:7500') → 'http://localhost:7500'; anything that is not an http or https address → ''. */
+(function () {
+  'use strict';
+  var DEFAULT_ADDRESS = 'http://localhost:7433';
+  var KEY = 'pmosAddress';
+  function normalizeAddress(text) {
+    var t = String(text == null ? '' : text).trim();
+    if (!t) return '';
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(t)) t = 'http://' + t;
+    var u;
+    try { u = new URL(t); } catch (e) { return ''; }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return '';
+    return u.origin;
+  }
+  var api = { DEFAULT_ADDRESS: DEFAULT_ADDRESS, KEY: KEY, normalizeAddress: normalizeAddress };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else window.PMOS_ADDRESS = api;
+})();

package/workspace/extension/content.js

@@ -0,0 +1,76 @@
+/* content.js — the PMOS panel over a Google Meet call. Runs only on https://meet.google.com/* (manifest.json).
+ *
+ * On a call path (/abc-defg-hij) it puts a fixed host element at the bottom right of the page. Its shadow root holds one iframe: panel.html of this
+ * extension, with the Meet code and the tab's title in the address. When the panel folds, the page inside it sends { pmosFocus: 'fold' } (and 'open'
+ * when it unfolds) and the host shrinks to a pill. On any other Meet page (the home page, a lobby list) there is no panel.
+ *
+ * Meet is a single-page app, so the address is watched: it is read again every second and on popstate. The only things read from the page are
+ * the address and the title. Nothing is sent from here. No call audio or captions are read. */
+(function () {
+  'use strict';
+  var CALL_PATH = /^\/[a-z]{3}-[a-z]{4}-[a-z]{3}$/;
+  var HOST_ID = 'pmos-meet-panel';
+  var OPEN = { width: 360, height: 520 };
+  var PILL_HEIGHT = 44;
+  var TITLE_WAIT_MS = 3000;   // Meet sets a title like "Meet - <name>" a moment after the call opens
+
+  /** The Meet code of a path, or '' when the path is not a call. */
+  function callCode(pathname) { return CALL_PATH.test(String(pathname || '')) ? String(pathname).slice(1) : ''; }
+  /** The panel's address: panel.html with the Meet code and the tab title. */
+  function panelSrc(base, code, title) { return base + '?meet=' + encodeURIComponent(code) + '&title=' + encodeURIComponent(title || ''); }
+
+  var api = { CALL_PATH: CALL_PATH, callCode: callCode, panelSrc: panelSrc };
+  if (typeof module !== 'undefined' && module.exports) { module.exports = api; return; }
+  if (typeof document === 'undefined' || typeof chrome === 'undefined' || !chrome.runtime || !chrome.runtime.getURL) return;
+  if (window.top !== window) return;
+
+  var CSS = [
+    ':host { position: fixed; right: 16px; bottom: 16px; z-index: 2147483647; width: ' + OPEN.width + 'px; height: ' + OPEN.height + 'px; max-width: calc(100vw - 32px); max-height: calc(100vh - 32px); }',
+    ':host([data-folded]) { height: ' + PILL_HEIGHT + 'px; }',
+    'iframe { display: block; width: 100%; height: 100%; border: 1px solid rgba(128, 128, 128, 0.35); border-radius: 12px; background: Canvas; color-scheme: light dark; box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3); }',
+    ':host([data-folded]) iframe { border-radius: 22px; }',
+  ].join('\n');
+
+  var mounted = null;   // { code, host, frame }
+  var seenAt = 0;       // when this call path was first seen
+
+  function unmount() {
+    if (mounted && mounted.host.parentNode) mounted.host.parentNode.removeChild(mounted.host);
+    mounted = null;
+  }
+  function mount(code) {
+    var host = document.createElement('div');
+    host.id = HOST_ID;
+    var root = host.attachShadow({ mode: 'closed' });
+    try { var sheet = new CSSStyleSheet(); sheet.replaceSync(CSS); root.adoptedStyleSheets = [sheet]; }
+    catch (e) { var st = document.createElement('style'); st.textContent = CSS; root.appendChild(st); }
+    var frame = document.createElement('iframe');
+    frame.title = 'PMOS meeting helper';
+    frame.src = panelSrc(chrome.runtime.getURL('panel.html'), code, document.title);
+    root.appendChild(frame);
+    document.documentElement.appendChild(host);
+    mounted = { code: code, host: host, frame: frame };
+  }
+
+  window.addEventListener('message', function (e) {
+    if (!mounted || e.source !== mounted.frame.contentWindow) return;
+    if (e.origin !== chrome.runtime.getURL('').replace(/\/$/, '')) return;   // the panel's own origin, chrome-extension://<id>
+    var m = e.data && e.data.pmosFocus;
+    if (m === 'fold') mounted.host.setAttribute('data-folded', '');
+    else if (m === 'open') mounted.host.removeAttribute('data-folded');
+  });
+
+  function check() {
+    var code = callCode(location.pathname);
+    if (!code) { seenAt = 0; unmount(); return; }
+    if (mounted && mounted.code === code) return;
+    if (mounted) unmount();
+    if (!seenAt) seenAt = Date.now();
+    var titled = document.title && !/^\s*(Google )?Meet\s*$/i.test(document.title);
+    if (titled || Date.now() - seenAt >= TITLE_WAIT_MS) mount(code);
+  }
+  window.addEventListener('popstate', check);
+  window.addEventListener('hashchange', check);
+  setInterval(check, 1000);
+  check();
+})();

package/workspace/extension/manifest.json

@@ -0,0 +1,15 @@
+{
+  "manifest_version": 3,
+  "name": "PMOS for Google Meet",
+  "version": "0.1.0",
+  "description": "Shows your PMOS meeting companion in a small panel over a Google Meet call. Only you see it. It talks only to the PMOS on your own computer.",
+  "icons": { "16": "icons/icon-16.png", "32": "icons/icon-32.png", "48": "icons/icon-48.png", "128": "icons/icon-128.png" },
+  "permissions": ["storage"],
+  "content_scripts": [
+    { "matches": ["https://meet.google.com/*"], "js": ["content.js"], "run_at": "document_idle" }
+  ],
+  "web_accessible_resources": [
+    { "resources": ["panel.html"], "matches": ["https://meet.google.com/*"] }
+  ],
+  "options_ui": { "page": "options.html", "open_in_tab": true }
+}

package/workspace/extension/options.css

@@ -0,0 +1,33 @@
+/* options.css — the options page. PMOS does not serve this file, so the colours are PMOS's tokens by value. */
+:root {
+  color-scheme: light dark;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.148 0.004 228.8);
+  --muted-foreground: oklch(0.48 0.021 213.5);
+  --border: oklch(0.925 0.005 214.3);
+  --accent: oklch(0.488 0.243 264.376);
+  --destructive: oklch(0.577 0.245 27.325);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: oklch(0.148 0.004 228.8);
+    --foreground: oklch(0.987 0.002 197.1);
+    --muted-foreground: oklch(0.723 0.014 214.4);
+    --border: oklch(1 0 0 / 10%);
+    --accent: oklch(0.623 0.214 259.815);
+    --destructive: oklch(0.704 0.191 22.216);
+  }
+}
+body { margin: 0; background: var(--background); color: var(--foreground); font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width: 560px; margin: 0 auto; padding: 32px 16px; }
+h1 { margin: 0 0 8px; font-size: 20px; font-weight: 600; }
+.lede { margin: 0 0 24px; color: var(--muted-foreground); }
+code { font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; }
+label { display: block; margin-bottom: 6px; font-weight: 600; }
+.row { display: flex; gap: 8px; }
+input { flex: 1; min-width: 0; height: 32px; padding: 0 12px; border: 1px solid var(--border); border-radius: 6px; background: var(--background); color: var(--foreground); font: inherit; }
+input:focus-visible, button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+button { height: 32px; padding: 0 16px; border: 0; border-radius: 6px; background: var(--foreground); color: var(--background); font: inherit; font-weight: 600; cursor: pointer; }
+.status { min-height: 21px; margin: 8px 0 0; color: var(--muted-foreground); }
+.status.bad { color: var(--destructive); }
+.fine { margin: 24px 0 0; color: var(--muted-foreground); font-size: 12px; }

package/workspace/extension/options.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>PMOS for Google Meet: options</title>
+<link rel="stylesheet" href="options.css">
+</head>
+<body>
+<main>
+  <h1>PMOS for Google Meet</h1>
+  <p class="lede">The panel over a Meet call is a page of PMOS on your own computer. Type the address where your PMOS runs. The default is <code>http://localhost:7433</code>, the port the workspace starts on. If <code>pmos</code> printed another port, use that one.</p>
+  <form id="form">
+    <label for="addr">PMOS address</label>
+    <div class="row">
+      <input id="addr" name="addr" type="text" inputmode="url" autocomplete="off" spellcheck="false" placeholder="http://localhost:7433">
+      <button type="submit">Save</button>
+    </div>
+    <p id="status" class="status" role="status" aria-live="polite"></p>
+  </form>
+  <p class="fine">The extension runs only on meet.google.com. It reads the address and the title of the Meet tab, and it talks only to this PMOS address. It does not read the call's audio or captions.</p>
+</main>
+<script src="address.js"></script>
+<script src="options.js"></script>
+</body>
+</html>

package/workspace/extension/options.js

@@ -0,0 +1,24 @@
+/* options.js — the one setting: where PMOS is (chrome.storage.sync, key pmosAddress). */
+(function () {
+  'use strict';
+  var A = window.PMOS_ADDRESS;
+  var input = document.getElementById('addr');
+  var status = document.getElementById('status');
+  var say = function (t, bad) { status.textContent = t; status.className = 'status' + (bad ? ' bad' : ''); };
+
+  try {
+    var o = {}; o[A.KEY] = A.DEFAULT_ADDRESS;
+    chrome.storage.sync.get(o, function (v) { input.value = A.normalizeAddress(v && v[A.KEY]) || A.DEFAULT_ADDRESS; });
+  } catch (e) { input.value = A.DEFAULT_ADDRESS; }
+
+  document.getElementById('form').addEventListener('submit', function (e) {
+    e.preventDefault();
+    var addr = A.normalizeAddress(input.value) || (input.value.trim() === '' ? A.DEFAULT_ADDRESS : '');
+    if (!addr) { say('That is not an address. Use a form like http://localhost:7433.', true); return; }
+    var o = {}; o[A.KEY] = addr;
+    chrome.storage.sync.set(o, function () {
+      input.value = addr;
+      say('Saved. A Meet tab that is open picks it up when you reload the tab.');
+    });
+  });
+})();

package/workspace/extension/panel.css

@@ -0,0 +1,21 @@
+/* panel.css — the panel's own page, shown only while PMOS is being looked for. PMOS does not serve this file, so the colours are PMOS's tokens by value. */
+:root {
+  color-scheme: light dark;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.148 0.004 228.8);
+  --muted-foreground: oklch(0.48 0.021 213.5);
+  --accent: oklch(0.488 0.243 264.376);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: oklch(0.148 0.004 228.8);
+    --foreground: oklch(0.987 0.002 197.1);
+    --muted-foreground: oklch(0.723 0.014 214.4);
+    --accent: oklch(0.623 0.214 259.815);
+  }
+}
+html, body { height: 100%; margin: 0; }
+body { background: var(--background); color: var(--foreground); font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+.msg { margin: 0; padding: 16px; color: var(--muted-foreground); }
+.msg a { color: var(--accent); text-underline-offset: 2px; }
+iframe { display: block; width: 100%; height: 100%; border: 0; background: var(--background); }

package/workspace/extension/panel.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>PMOS meeting helper</title>
+<link rel="stylesheet" href="panel.css">
+</head>
+<body>
+<main id="msg" class="msg" role="status" aria-live="polite">Looking for PMOS.</main>
+<script src="address.js"></script>
+<script src="panel.js"></script>
+</body>
+</html>

package/workspace/extension/panel.js

@@ -0,0 +1,67 @@
+/* panel.js — the page the content script frames over a Meet call (panel.html).
+ * It reads the PMOS address from chrome.storage.sync (pmosAddress, default http://localhost:7433) and asks whether anything answers there.
+ * When PMOS answers, the page becomes one frame: ${address}/c3.html?focus=now&pop=1&meet=…&mtitle=… (PMOS's compact meeting focus). When it does not,
+ * the page says where it looked and links to the options. Nothing else is fetched. The frame's { pmosFocus } message (fold or open, no data) is passed
+ * up to the content script. */
+(function () {
+  'use strict';
+  var A = window.PMOS_ADDRESS;
+  var CHECK_MS = 4000;     // how long to wait for PMOS to answer
+  var RETRY_MS = 5000;     // looked again while it does not answer, so a PMOS started later fills the panel
+  var MEET_ORIGIN = 'https://meet.google.com';
+  var params = new URLSearchParams(location.search);
+  var meet = params.get('meet') || '';
+  var title = params.get('title') || '';
+  var msg = document.getElementById('msg');
+  var frame = null;
+  var frameOrigin = '';
+  var timer = null;
+
+  function readAddress(done) {
+    var fallback = A.DEFAULT_ADDRESS;
+    try {
+      var o = {}; o[A.KEY] = fallback;
+      chrome.storage.sync.get(o, function (v) { done(A.normalizeAddress(v && v[A.KEY]) || fallback); });
+    } catch (e) { done(fallback); }
+  }
+  /** Resolves when something answers at the address (an opaque no-cors reply is enough), rejects when nothing listens. */
+  function answers(addr) {
+    var ctl = typeof AbortController === 'function' ? new AbortController() : null;
+    var t = ctl ? setTimeout(function () { ctl.abort(); }, CHECK_MS) : null;
+    return fetch(addr + '/c3.html', { mode: 'no-cors', cache: 'no-store', signal: ctl ? ctl.signal : undefined })
+      .then(function (r) { if (t) clearTimeout(t); return r; }, function (e) { if (t) clearTimeout(t); throw e; });
+  }
+  function showMissing(addr) {
+    msg.textContent = '';
+    msg.className = 'msg';
+    msg.appendChild(document.createTextNode('PMOS is not running at ' + addr + '. '));
+    var a = document.createElement('a');
+    a.href = '#';
+    a.textContent = 'Set the address';
+    a.addEventListener('click', function (e) { e.preventDefault(); try { chrome.runtime.openOptionsPage(); } catch (x) { /* no options page */ } });
+    msg.appendChild(a);
+    msg.appendChild(document.createTextNode('.'));
+  }
+  function showFrame(addr) {
+    var q = new URLSearchParams({ focus: 'now', pop: '1', meet: meet, mtitle: title });
+    frame = document.createElement('iframe');
+    frame.title = 'PMOS meeting helper';
+    frame.src = addr + '/c3.html?' + q.toString();
+    frameOrigin = new URL(addr).origin;
+    msg.remove();
+    document.body.appendChild(frame);
+  }
+  function start() {
+    readAddress(function (addr) {
+      answers(addr).then(function () { showFrame(addr); }, function () { showMissing(addr); timer = setTimeout(start, RETRY_MS); });
+    });
+  }
+
+  window.addEventListener('message', function (e) {
+    if (!frame || e.source !== frame.contentWindow || e.origin !== frameOrigin) return;
+    var m = e.data && e.data.pmosFocus;
+    if (m !== 'fold' && m !== 'open') return;
+    if (window.parent !== window) window.parent.postMessage({ pmosFocus: m }, MEET_ORIGIN);
+  });
+  start();
+})();

package/workspace/guide/console-calendar.md

@@ -137,6 +137,20 @@ To fix the topic, press **Topics**. Press **Not this topic** and pick the topic
 
 The companion starts only while the meeting is recorded. It reads the new lines of the transcript at most every 40 seconds. It writes the sentence, the chips, the topic and the notes. If the answer is not usable, PMOS drops it and shows nothing. To stop the companion, set `PMOS_FOCUS_AGENT` to `off`. The page then shows the transcript and a quiet line, and it adds no notes. In the last 5 minutes, and after the meeting, the page shows the captured items under the material. You confirm them in the note after the meeting. Nothing goes to other people.
 
+### Meeting focus over Google Meet
+
+The PMOS Chrome extension shows a small panel over a Google Meet call, so you do not need to switch to the PMOS tab. The panel is the Meeting focus page in a compact form. It has a head with the topic the room is on (or "Starts in" before the start) and the time left, the **What's being said** line, the conversation with PMOS, and **Ask PMOS quietly**. Only you see it. It is not part of the screen you share. The extension reads the address and the title of the Meet tab only. It does not read the call's audio or captions, and it talks only to the PMOS on your computer.
+
+To add the extension:
+
+1. Run `pmos extension`. It prints the folder of the extension and these steps.
+2. In Chrome, open `chrome://extensions` and turn on **Developer mode**.
+3. Press **Load unpacked** and pick the folder that `pmos extension` printed.
+
+PMOS must run while you use the panel. The extension looks for PMOS at `http://localhost:7433`. If `pmos` started on another port, open the extension's **Options**, type that address and press **Save**, then reload the Meet tab.
+
+To use it, open a Meet call. The panel shows at the bottom right of the call, and not on the Meet home page. PMOS finds the meeting on your calendar by the Meet link in the invite. If no invite has that link, it uses the title of the tab, and then the meeting that is under way now (from 10 minutes before the start to 10 minutes after the end). If none fits, the panel says "No meeting right now" and lists today's meetings. Press the one this call is. **Fold** shrinks the panel to a pill that shows the head only, and the same button opens it again. **Open focus in PMOS** opens the full Meeting focus page in a new tab, with the material, the topics and the captured items. If PMOS does not answer, the panel says "PMOS is not running at" and the address, with a link to the Options.
+
 ## Free time
 
 Press **Free time** to show the free blocks. A free block is a gap inside your working hours that is long enough to use. On Day and Week, each block is a dashed purple window on the timeline, with its length, for example "1.5 h focus". The side column lists the blocks, up to 8, with the suggestion for each. On Month, Quarter and Year the list says that free time shows in the Day and Week views, and the chip still shows the number of blocks.

package/workspace/guide/index.md

@@ -61,6 +61,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.
 - [Initiatives: the Roadmap, the List and the initiative sheet](initiatives-screen.md): how to read and order the initiatives of a repository, open the sheet, make a new initiative, and review the cycle.
 - [Initiatives and the Roadmap: Now, Next and Later](initiatives-roadmap.md): what day one shows, how an agent proposes a move, and `pmos initiative` and `pmos measure` from a terminal.
+- [The Initiative Driver: drafts the agent files for you](initiative-driver.md): when the driver runs, the unblock sweep, the limits, Keep, Send back and Drop, the board modes, and `pmos driver`.
 - [PM-only acts: what only you can do](pm-only-acts.md): which acts are yours, how the workspace checks that a press comes from your page or your terminal, and what to do when one is refused.
 - [PM-only lines: how the workspace checks your acts](pm-only-lines.md): how each act is recorded, what the Today card "A PM-only line is not attested" means, and the grants for a bulk lifecycle change and a Release.
 - [Breakdown › Timeline](timeline.md): an initiative's items on a time axis, split by stage, with milestones, today, and the at-risk flag when an item starts before its predecessor ends.

package/workspace/guide/initiative-driver.md

@@ -0,0 +1,79 @@
+---
+type: Guide
+title: "The Initiative Driver: drafts the agent files for you"
+description: "What the Initiative Driver does when an initiative is created or moved, what stops it, how it files proposals you keep, send back or drop, the board modes, and the pmos driver commands."
+timestamp: 2026-10-12
+---
+
+# The Initiative Driver: drafts the agent files for you
+
+The Initiative Driver is a short background agent run for one initiative or one Work task. It reads the record, decides the next useful step, files the result as a **proposal**, and ends. It never decides for you. You keep a proposal, send it back with a note, or drop it.
+
+## When a run starts
+
+A run starts for one of four reasons:
+
+- **Created.** An initiative is created from the page, from Triage (accept), or with `pmos initiative new`. The run starts within one tick of the server (about one minute).
+- **Moved.** You move the initiative to another stage on the board.
+- **Answered.** You send a proposal back with a note.
+- **Stuck.** The unblock sweep finds a blocker the agent can work on.
+
+An initiative that existed before you first ran this version does not start a run. Only events after the first scan count.
+
+## The unblock sweep
+
+The sweep reads every active initiative and every open Work task. It uses no model. It runs every 30 minutes, inside the working hours of the daytime check (09:00 to 18:00 by default) and outside your quiet hours.
+
+| Where | What it finds |
+| --- | --- |
+| You are the blocker | An open proposal is more than one day old. No run starts. The row comes back in Needs you once a day. |
+| Discover | No kept problem statement, or no kept evidence. |
+| Plan | No PRD, no done-criteria, or no anchor. |
+| Do | No Jira ticket moved for the stall threshold, or a ticket is flagged blocked. |
+| Learn | The check-by date passed with no outcome check, or a kill condition tripped. |
+| Any stage | Nothing changed for the stall threshold (5 days by default). |
+| Work task | Overdue, waiting on someone for 3 days or more, untouched for 7 days, or no next step. |
+
+The sweep starts a run for a blocker the agent can work on, at most once per blocker per day. A dormant initiative starts no run.
+
+## The limits
+
+- At most 3 runs per initiative per day, and 1 per Work task per day.
+- At most 3 runs at the same time. The others wait.
+- A run that fails or times out counts against the day. Its reason is in the ledger.
+- A paused initiative or Work task starts no run.
+- `PMOS_DRIVER=off` in the environment of the server starts none.
+
+## What the agent can and cannot do
+
+The agent reads, and it files proposals with `pmos driver propose`. It has no Write or Edit tool, no `git push`, and no tool that sends anything. Every claim in a proposal carries a pointer: a Jira key, a link or a path. A follow-up to a person is draft text only. You send it from your own session.
+
+In Discover, the agent writes the problem statement, the evidence, the opportunity sizing, the riskiest assumption and the stakeholders. When you have kept the first three, it proposes the move to Plan. In the other stages, it names the blocker and proposes what would clear it.
+
+## Keep, send back, drop
+
+Open proposals appear in Needs you as one row for each initiative or task: "Agent has 3 drafts on the initiative".
+
+- **Keep** writes the record as you. A problem statement goes into the problem record of the initiative. A move goes through the board move, with its warnings. A Work next step goes into the steps of the task. Other kinds are kept as your decision to rely on them.
+- **Send back** needs a note. The note starts a new run. It counts as a correction.
+- **Drop** closes the proposal. It counts as a correction.
+
+The agent cannot keep, send back, drop, pause or change the mode. Those acts need your page or your terminal.
+
+## Board modes
+
+- **Approve** is the default. The agent runs and drafts, and Needs you shows the rows.
+- **Shadow.** The agent runs and drafts, and raises no Needs you rows.
+- **Off.** No run starts.
+
+## The commands
+
+The agent uses `pmos driver propose` to file a proposal and `pmos driver status` to read what exists. The other commands are yours, at an interactive terminal:
+
+- `pmos driver keep <proposal>` asks you to type the proposal id. A kept move is pressed on the page.
+- `pmos driver return <proposal> --note "<what to change>"` sends it back.
+- `pmos driver drop <proposal>` drops it.
+- `pmos driver pause <initiative|work> <id>` and `pmos driver resume <initiative|work> <id>` stop and restart the runs for one target.
+- `pmos driver mode <off|shadow|approve> [--board <id>]` sets the board mode. Without `--board` it sets every board.
+
+The ledger is `driver.jsonl` in the state folder of the repository (`pmos/state`, `state` or `.pmos`). Each action adds one line. Nothing is changed or removed.

package/workspace/guide/validate-with-typesafe.md

@@ -112,7 +112,7 @@ The workspace reads the TypeSafe key only on this machine. After you save the ke
 If you have no TypeSafe key, a model on your computer can answer the same questions. Two models are supported. Both use the same interface as Jev.
 
 - **Winnow**: in a `winnow-inference` folder, run `python3 scripts/serve.py`. It uses port 8091. Winnow-12B needs about 16 GB of memory.
-- **Laya**: run `pip install "laya[serve]"`, then `laya-serve`. It uses port 8000. Laya is small and runs on a laptop.
+- **Laya**: in Settings, press **Set up Laya**. A terminal named Set up Laya opens with the commands typed in. Read them and press Enter. The first time, they install Laya into the PMOS data folder. Then Laya starts and uses port 8000. Laya is small and runs on a laptop. Laya stops when you close that terminal or restart the computer. Press **Set up Laya** again to start it.
 
 1. Start the model.
 2. Open Settings, then **Privacy and data**. Under **Local model if Jev is missing**, press **Winnow** or **Laya**.