create-pmos 0.47.0 → 0.48.0

package/workspace/doc-category-bench.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/* doc-category-bench.js — scores lib/doc-category.js against the labelled set and counts what the repository leaves undecided
+ * (jev-doc-categorizer Run 1). Local only: no network, no model, nothing written.
+ *
+ *   node doc-category-bench.js          print the report
+ *   node doc-category-bench.js --json   print it as JSON
+ *
+ *   node doc-category-bench.js --jev                  Run 3's measured pass: show how many snippets of the labelled set
+ *                                                     would go to Jev, and send nothing
+ *   node doc-category-bench.js --jev --confirm N      send them, with the PM's own key, and report the agreement
+ *
+ * The measured pass is the PM's own press, never the build's or CI's. It uses the key, the consent and the "categorize with
+ * Jev" switch the PM set in the workspace for this repository (D82), and it refuses unless N is the count it shows now.
+ *
+ * The labelled set is workspace/fixtures/doc-category-labelled.json. Its labels were PROPOSED by the agent and are not yet the
+ * PM's, so every agreement figure here is provisional, and the report says so.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { categorize, namedFromRecords, CATEGORIES, UNDETERMINED } = require('./lib/doc-category');
+const { frontmatter } = require('./lib/related-docs');
+
+const REPO = path.join(__dirname, '..');
+const LABELS = path.join(__dirname, 'fixtures', 'doc-category-labelled.json');
+
+function trackedMd(root) {
+  return execFileSync('git', ['ls-files', '*.md'], { cwd: root, encoding: 'utf8', maxBuffer: 1 << 26 }).split('\n').filter(Boolean);
+}
+function namedMap(root, files) {
+  const records = [];
+  for (const f of files) {
+    if (!/(^|\/)initiatives\//.test(f)) continue;
+    try { records.push({ rel: f, fm: frontmatter(fs.readFileSync(path.join(root, f), 'utf8')) || {} }); } catch { /* unreadable */ }
+  }
+  return namedFromRecords(records);
+}
+function one(root, rel, named) {
+  let text = ''; try { text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch { return null; }
+  let fm = {}; try { fm = frontmatter(text) || {}; } catch { /* no frontmatter */ }
+  return { fm, c: categorize({ rel, fm, text, named }) };
+}
+
+function run(root = REPO) {
+  const files = trackedMd(root);
+  const named = namedMap(root, files);
+  const labelled = JSON.parse(fs.readFileSync(LABELS, 'utf8'));
+  const rows = []; const confusion = {};
+  let present = 0; let decided = 0; let right = 0;
+  for (const r of labelled.rows) {
+    const x = one(root, r.path, named);
+    if (!x) { rows.push({ path: r.path, expected: r.expected, got: null, missing: true }); continue; }
+    present++;
+    const got = x.c.category;
+    if (x.c.decided) { decided++; if (got === r.expected) right++; }
+    const key = r.expected + ' → ' + got;
+    confusion[key] = (confusion[key] || 0) + 1;
+    rows.push({ path: r.path, expected: r.expected, got, basis: x.c.basis, decided: x.c.decided, ok: got === r.expected });
+  }
+  const byCategory = {}; const refs = { total: 0, decided: 0, undetermined: 0 }; let undetermined = 0;
+  for (const f of files) {
+    const x = one(root, f, named); if (!x) continue;
+    byCategory[x.c.category] = (byCategory[x.c.category] || 0) + 1;
+    if (x.c.category === UNDETERMINED) undetermined++;
+    if (x.fm.type === 'Reference') { refs.total++; if (x.c.decided) refs.decided++; else refs.undetermined++; }
+  }
+  const untested = CATEGORIES.filter((c) => !labelled.rows.some((r) => r.expected === c));
+  return {
+    provisional: true, labelled_by: labelled.labelled_by, tenant_files: labelled.tenant_files,
+    files: files.length, labelled: labelled.rows.length, present, decided,
+    agreement_on_decided: decided ? right / decided : null, agreement_overall: present ? right / present : null,
+    by_category: byCategory, undetermined, reference: refs, untested_categories: untested, confusion, rows,
+  };
+}
+
+if (require.main === module && !process.argv.includes('--jev')) {
+  const r = run();
+  if (process.argv.includes('--json')) { console.log(JSON.stringify(r, null, 1)); process.exit(0); }
+  const pct = (n) => (n == null ? 'n/a' : (100 * n).toFixed(1) + '%');
+  console.log('doc-category-bench — PROVISIONAL: the labels were proposed by the agent, not confirmed by the PM.');
+  console.log(`files ${r.files} · labelled ${r.labelled} (present ${r.present}) · decided ${r.decided}`);
+  console.log(`agreement on decided ${pct(r.agreement_on_decided)} · overall (undetermined counts as wrong) ${pct(r.agreement_overall)}`);
+  console.log('by category:', JSON.stringify(r.by_category));
+  console.log(`Reference-typed: ${r.reference.total} · sharpened ${r.reference.decided} · left undetermined ${r.reference.undetermined}`);
+  console.log('untested categories (no label in the set):', r.untested_categories.join(', ') || 'none');
+  console.log('tenant files:', r.tenant_files);
+  console.log('disagreements and undetermined rows:');
+  for (const row of r.rows.filter((x) => !x.ok)) console.log(`  ${row.path}: expected ${row.expected}, got ${row.got}${row.basis ? ' (' + row.basis + ')' : ''}`);
+}
+/* ── Run 3: the measured pass through Jev ─────────────────────────────────────────────────────────────────────────────── */
+/* The labelled rows to measure. A row the PM corrected is marked, and the bridge never sends it. */
+function labelledRows(root, corrected = {}) {
+  const labelled = JSON.parse(fs.readFileSync(LABELS, 'utf8'));
+  const rows = [];
+  for (const r of labelled.rows) {
+    let text = ''; try { text = fs.readFileSync(path.join(root, r.path), 'utf8'); } catch { continue; }
+    let fm = {}; try { fm = frontmatter(text) || {}; } catch { /* no frontmatter */ }
+    rows.push({ rel: r.path, fm, text, expected: r.expected, corrected: !!corrected[r.path] });
+  }
+  return rows;
+}
+/* What the labelled set can and cannot measure: a category with no label in the set is untested, whatever Jev answers. */
+function labelledSet() {
+  const labelled = JSON.parse(fs.readFileSync(LABELS, 'utf8'));
+  return { labelled_by: labelled.labelled_by, tenant_files: labelled.tenant_files,
+    untested_categories: CATEGORIES.filter((c) => !labelled.rows.some((r) => r.expected === c)) };
+}
+/**
+ * The measured pass. `confirm` is `{ requests, fingerprint }` from the plan the PM saw: both must match the plan now, so the
+ * PM confirms these files and not merely this count. The key is the saved key, or TYPESAFE_API_KEY in `env`.
+ */
+async function jevPass({ root = REPO, stateDir, confirm = null, ask, askOpts = {}, env = process.env } = {}) {
+  const settings = require('./lib/typesafe-settings');
+  const jc = require('./lib/jev-categorize');
+  const corrections = require('./lib/doc-category-corrections');
+  const sd = stateDir || require('./lib/state-root').defaultRoot();
+  // the workspace keys a repository by the root it registered; a symlinked checkout may be registered by either path
+  let real = root; try { real = fs.realpathSync(root); } catch { /* keep as given */ }
+  const repoRoot = [root, real].find((r) => { const f = settings.getRepo(sd, r); return f.consent || f.categorize; }) || root;
+  const flags = settings.getRepo(sd, repoRoot);
+  const cacheDir = corrections.repoDir(sd, repoRoot);
+  const rows = labelledRows(root, corrections.get(cacheDir));
+  const plan = jc.measurePlan({ rows, exclude: flags.exclude });
+  const set = labelledSet();
+  if (confirm === null) return { plan, set };
+  if (!confirm || !Number.isInteger(confirm.requests) || typeof confirm.fingerprint !== 'string' || !confirm.fingerprint) {
+    return { plan, set, out: { ok: false, error: 'Confirm with the count and the files you saw, as the plan prints them: --confirm ' + plan.requests + ':' + plan.fingerprint } };
+  }
+  const out = await jc.measure({ rows, cacheDir, key: settings.getKey(sd, env), flags, exclude: flags.exclude,
+    expectRequests: confirm.requests, expectFingerprint: confirm.fingerprint, ...(ask ? { ask } : {}), askOpts });
+  return { plan, set, out };
+}
+
+if (require.main === module && process.argv.includes('--jev')) {
+  const i = process.argv.indexOf('--confirm');
+  let confirm = null;
+  if (i > 0) { const m = /^(\d+):([0-9a-f]{40})$/.exec(String(process.argv[i + 1] || '')); confirm = m ? { requests: Number(m[1]), fingerprint: m[2] } : {}; }
+  const setLines = (set) => {
+    console.log('untested categories (no label in the set): ' + (set.untested_categories.join(', ') || 'none'));
+    console.log('tenant files: ' + (set.tenant_files || 'none'));
+    if (set.untested_categories.length || typeof set.tenant_files !== 'number' || !set.tenant_files) console.log('This set cannot show whether Jev separates the untested categories. Add labelled tenant files for them before reading the result as an answer.');
+  };
+  jevPass({ confirm }).then(({ plan, set, out }) => {
+    if (!out) {
+      console.log(`The measured pass would send ${plan.requests} snippet(s) of the ${plan.labelled} labelled files, about ${plan.characters} characters, to ${plan.host}. Nothing was sent.`);
+      console.log('It sends labelled files the local rules already decide too, because it measures Jev on them (D82 point 11).');
+      console.log(`${plan.withheld_count} withheld by the credential scan · ${plan.excluded} excluded · ${plan.corrected} corrected by you, not sent.`);
+      setLines(set);
+      console.log(`To send, run: node doc-category-bench.js --jev --confirm ${plan.requests}:${plan.fingerprint}`);
+      return;
+    }
+    if (!out.ok) { console.log('✗ ' + out.error); process.exitCode = 1; return; }
+    const pct = (n) => (n == null ? 'n/a' : (100 * n).toFixed(1) + '%');
+    console.log('Measured pass — PROVISIONAL: the labels were proposed by the agent, not confirmed by the PM. Advisory (D40).');
+    console.log(`sent ${out.sent} · failed ${out.failed} · answered ${out.answered} of ${out.labelled} · agreement ${pct(out.agreement)} · unsure ${out.unsure} · unreadable ${out.unreadable} · not answered ${out.not_answered}`);
+    console.log(`withheld by the credential scan ${out.withheld_count} · excluded ${out.excluded} · corrected by you, not sent ${out.corrected}`);
+    setLines(set);
+    for (const [c, r] of Object.entries(out.by_category)) console.log(`  ${c}: ${r.right}/${r.labelled} right, ${r.unsure} unsure`);
+    if (out.paused) console.log('paused: ' + out.paused.reason);
+    console.log('disagreements:');
+    for (const d of out.disagreements) console.log(`  ${d.doc}: expected ${d.expected}, Jev ${d.got}${d.leading ? ' (between ' + d.leading.join(' and ') + ')' : ''}`);
+  });
+}
+module.exports = { run, trackedMd, namedMap, labelledRows, labelledSet, jevPass };

package/workspace/fixtures/doc-category-labelled.json

@@ -0,0 +1,167 @@
+{
+ "labelled_by": "PROPOSED by Claude from reading each file, 2026-10-04. NOT yet confirmed by the PM. Agreement against these labels is provisional until the PM confirms or corrects each row.",
+ "from": "this repository at the Run 1 branch point",
+ "tenant_files": "none yet: the PM has not supplied about 20 real meeting notes, reports and tickets, so meeting-notes and ticket are untested against real files",
+ "rows": [
+  {
+   "path": "planning/prd/jev-claim-checks-prd.md",
+   "expected": "prd"
+  },
+  {
+   "path": "planning/prd/workspace-cockpit-nav-prd.md",
+   "expected": "prd"
+  },
+  {
+   "path": "planning/prd/workspace-skill-authoring-prd.md",
+   "expected": "prd"
+  },
+  {
+   "path": "planning/evals/jev-claim-checks-eval-rubric.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/evals/knowledge-graph-eval-rubric.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/initiatives/jev-claim-checks.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/initiatives/workspace-cockpit-nav.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "okf/products/pmos/adr/d80-jev-claim-pairs.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "okf/products/pmos/adr/d65-two-graph-adlc.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "okf/products/pmos/adr/d01-control-plane.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "DECISIONS.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "pm-decisions.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/okrs/health-budgets.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/decisions-proposed-pmos-cockpit-mod.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/briefs/roadmap-time-model-spike-brief.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/design-system-plan.md",
+   "expected": "spec-artifact"
+  },
+  {
+   "path": "planning/explainers/jev-claim-checks-surface-explainer.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "planning/explainers/knowledge-graph-surface-explainer.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "okf/core/concepts/frontmatter-format.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "okf/core/playbooks/working-in-pmos.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "workspace/guide/validate-with-typesafe.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "README.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "workspace/README.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "kit/mods/pmos-cockpit/README.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "CLAUDE.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "kit/AGENTS.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "kit/SECURITY.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "okf/products/pmos/references/metrics/north-star-metric.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "planning/research/agent-memory.md",
+   "expected": "knowledge"
+  },
+  {
+   "path": "discoveries.md",
+   "expected": "report"
+  },
+  {
+   "path": "planning/autonomy-log.md",
+   "expected": "report"
+  },
+  {
+   "path": "planning/evals/acceptance-gate-anti-atrophy-dogfood.md",
+   "expected": "report"
+  },
+  {
+   "path": "planning/evals/builder-profiles-dogfood.md",
+   "expected": "report"
+  },
+  {
+   "path": "planning/evals/calibration-golden-set.md",
+   "expected": "report"
+  },
+  {
+   "path": "planning/radar/jtbd-map.md",
+   "expected": "report"
+  },
+  {
+   "path": "okf/core/templates/prd-template.md",
+   "expected": "other"
+  },
+  {
+   "path": "planning/archive/phase-build-sequences.md",
+   "expected": "other"
+  },
+  {
+   "path": "planning/evals/fixtures/injection-payloads/01-html-comment.md",
+   "expected": "other"
+  },
+  {
+   "path": "okf/index.md",
+   "expected": "other"
+  },
+  {
+   "path": "okf/log.md",
+   "expected": "other"
+  }
+ ]
+}

package/workspace/guide/initiatives-and-next-steps.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: initiatives and next steps"
 description: "What the initiative detail shows, top to bottom: status, lifecycle control, and the next step the workspace proposes."
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: initiatives and next steps
@@ -15,7 +15,20 @@ Select an initiative in the list. The detail opens in the detail column.
 2. **Lifecycle control.** Hold, close, cancel or reopen. Beneath it, the history of every change.
 3. **Next steps to done.** Everything between now and acceptance, in order. See below.
 4. **Phases and links.** The workflow phases and the external links.
-5. **Artifacts.** Documents, conversations and files.
+5. **What the documents say.** Up to three lines, and Jev's suggestions if you turned them on. See below.
+6. **Artifacts.** Documents, conversations and files.
+
+## What the documents say
+
+These lines show facts about the documents that the phases do not show. Each line gives its source: a commit, a file, a requirement id or the text of the record. A line never changes a phase, a status or a count, and nothing is written.
+
+- **Since approval.** The PRD, rubric or brief changed in a commit after you approved the contract or accepted the work. The line gives the number of commits and the latest commit. A small edit, such as a whitespace fix, also shows here. Open the commit to see what changed.
+- **Coverage.** A requirement id in the PRD that the rubric does not mention, or an id in the rubric that the PRD does not have. A mention is not a grade. If the rubric mentions no requirement id, the line says that coverage cannot be found.
+- **Record says.** The `status:` line in the initiative record names a stage that the phases contradict. Edit the record if the line is wrong. The phases do not change.
+
+If a check cannot run, for example in a shallow clone, the line says "Cannot tell" and gives the reason. A missing line means that the check has nothing to compare.
+
+If **read documents for status** is on for the repository, lines that start with **Documents suggest** can follow. They are Jev's answers about the documents of this initiative: a PRD, rubric or brief that may be a stub, or a note that may contradict a requirement. Each line says *very likely*, *likely* or *possible*, says that it is a suggestion and names the model. Open the document to decide. See [Guide: validate a repository](validate-with-typesafe.md).
 
 ## Next steps
 

package/workspace/guide/knowledge-graph.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: find knowledge without reading whole files"
 description: "How to use pmos kg to find one card, section or decision without reading whole files, and the limits of the map."
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: find knowledge without reading whole files
@@ -54,6 +54,88 @@ An unknown file, heading or decision stops with a message that says what was not
 - A file with no incoming link is not an error. It means no other file links to it.
 - A **derived** card comes from the first paragraph of a file that has no `description`.
 
+## Categories
+
+Each Markdown file also has a **category**. The category is the kind of document as you would name it: `prd`, `meeting-notes`, `report`, `ticket`, `knowledge`, `spec-artifact` or `other`. A ticket also has a kind: `design`, `engineering` or `other`. The category is kept beside the `type` in the frontmatter. It does not replace the `type`, and it does not change a file.
+
+The workspace decides the category with local rules only. It uses no model and sends nothing. It uses the first rule that applies, in this order:
+
+1. A `category:` line the author wrote.
+2. A `type` that maps to a category.
+3. An initiative record that names the file.
+4. The file name or the folder.
+5. The headings.
+
+When a later rule disagrees with the rule that decided, the file keeps the earlier answer. A `Reference` or `Research` file with no better evidence has no category. It shows as `undetermined`. That is not the same as `other`: `other` means the file is none of the kinds, and `undetermined` means no rule could tell.
+
+The Knowledge view shows the category after each document name. Point at it to see which rule decided. Press a category above the list to show only those documents, and press it again to show all. The category is advisory. `pmos kg stats` counts the files in each category.
+
+### Ask Jev about undetermined files
+
+Jev can give a category to a file that the local rules leave `undetermined`. This is off until you turn it on. Jev never sees a file that already has a category from a local rule or from your correction. The measured pass below is the one exception for the local rules.
+
+Three things must all be on before anything is sent:
+
+1. A TypeSafe key, saved on the Validate page.
+2. Validation, switched on for this repository.
+3. **Categorize with Jev**, the switch in the Knowledge view.
+
+If one of them is off, the Knowledge view tells you which one.
+
+To start:
+
+1. Turn on **categorize with Jev**.
+2. Press **ask Jev about undetermined files**. The view shows how many requests it will send, about how many characters, and the host. Nothing is sent yet.
+3. Press **confirm and send** to send that number. If the files changed after you looked, even when the number is the same, the send stops and you look again.
+
+After the first confirmed send, the workspace sends only new or changed undetermined files. It does this when it reads the documents of this repository, at most once a minute. It reads them when it starts and when you open the Knowledge view. If more than 25 files wait, it does not send them. It tells you, and you confirm the count again.
+
+What is sent for each file: the title, the headings and the start of the text, at most 3,000 characters. The file path and the whole file are not sent. A file under an excluded path is not sent. A file whose start looks like a password or a key is not sent.
+
+Jev's answer shows as the category with `(jev)` after it. Point at it to see how sure Jev was, in words. If Jev was not sure, the file stays `undetermined`, and the tooltip names the two categories Jev was between. A Jev category is advisory. Each answer is kept on your computer, outside the repository, and the same text is not sent twice. Nothing is written into the repository.
+
+If the service rejects the key two times, cannot be reached three times in a row, or sends three answers in a row that the workspace cannot read, sending stops for this repository. An answer that cannot be read is not sent again. Press **resume** to start again.
+
+### Measure how well Jev categorizes
+
+The measured pass sends the files of the labelled set to Jev and compares the answers with the labels. It runs only when you start it in a terminal. The workspace never starts it.
+
+The measured pass also sends labelled files that a local rule already decides, because it measures Jev on them. It does not send a file that you corrected. The three switches, the excluded paths and the password and key check apply as for the Knowledge view.
+
+1. Run `node workspace/doc-category-bench.js --jev`. It shows how many files it would send, about how many characters, the host, and a `--confirm` value. It sends nothing.
+2. Read which categories the labelled set cannot test. When a category has no label in the set, the result says nothing about that category.
+3. To send, run the command again with `--confirm` and the value it showed, for example `--confirm 40:372a…`. The value holds the count and the files. If the files changed, nothing is sent and you look again.
+
+It uses the key that you saved on the Validate page, or `TYPESAFE_API_KEY` in the terminal. It prints the agreement, each category, how many answers were unsure, how many files were not sent and why, and every disagreement. The labels in the set are not yet confirmed, so the result is provisional. Only one pass at a time runs for a repository. If the workspace is sending, the command stops and sends nothing.
+
+### Correct a category
+
+When a category is wrong, set the correct one. Your correction comes before all five rules.
+
+1. In the Knowledge view, press **fix** at the end of the document row.
+2. Select the category. For a `ticket`, also select the ticket kind.
+3. Press **save correction**.
+
+The category after the document name changes. Point at it: it says `decided by pm correction`. When a rule gives a different category, the text names that rule too.
+
+The workspace keeps your corrections in its runtime state directory, never in the repository. Each repository has its own corrections. A correction does not change a file. To remove a correction, press **fix** and then **clear correction**. The rules then decide again.
+
+### Write the category into the file
+
+You can also write the category into the document, as a `category:` line in its frontmatter. This is a separate step, and it is the only step here that changes a file.
+
+1. Press **fix** and select the category.
+2. Press **write it into the file**. The workspace shows the change. It does not write yet.
+3. Examine the change. Press **apply** to write it, or **cancel**.
+
+The workspace changes one `category:` line in the frontmatter block at the top of the file. For a ticket, it also changes one `ticket_kind:` line. It adds the line when there is none. No other line of the file changes.
+
+The workspace does not write when:
+
+- The file has no frontmatter block at the top. It does not add a block.
+- The frontmatter has two `category:` lines.
+- The file changed after the workspace showed you the change. Press **write it into the file** again to see the new change.
+
 ## Where the map is kept
 
 The command reads the tracked `.md` files of the Git repository you run it in. It keeps the map in the runtime state directory of the workspace, never in the repository. It builds the map again when the Git HEAD changes or when you edit a tracked `.md` file that is not yet committed. It does not use the cache for any other change.

package/workspace/guide/layout.md

@@ -2,12 +2,38 @@
 type: Guide
 title: "Guide: layout"
 description: "The three workspace columns: navigation, detail and tabs, and what each one holds."
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: layout
 
-The workspace has three columns. They are, from left to right, navigation, detail and tabs.
+On a desktop screen the workspace has four columns. They are, from left to right, the repository rail, the list, the detail and the tabs. A phone, and the address option `?layout=legacy`, keep the older layout with three columns: navigation, detail and tabs. The rest of this page describes those three columns.
+
+## The repository rail, the list and the tools
+
+The rail is 64 pixels wide and shows one tile for each repository. A dot on a tile means that repository has something that needs you. The selected repository has no dot, because the list beside it shows what needs you. The `+` tile adds a repository and the menu button opens the tools: knowledge, memory, skills, scheduled tasks, validate, the guide and the others.
+
+A tool opens as a tab, not in place of the list. Choose the same tool again and the existing tab comes to the front.
+
+Press ⌘K (Ctrl-K) to jump to anything: an initiative, a repository, an open tab, a session or a tool. Type to filter, use the arrow keys to choose, and press Enter. Esc closes it.
+
+Press ⌘↵ (Ctrl-Enter) to enter Focus. The rail and the list go out of view, the active tab takes the width, and the detail stays as a narrow slice on the right. Press Esc or Navigate to return. Focus does not restart a terminal.
+
+Today is a tool tab. It shows what needs you, with an action and a reason to dismiss each item, what is being prepared, and a Repository / All switch.
+
+Each tool tab shows a board: Today, All repos, Knowledge, Memory, Skills, Scheduled tasks, Validate, the guide and Reports. Reports is in the menu, under Library, and lists only the run reports that exist. If a part of a board has no data behind it, the board does not show that part, or it says that the data is not read.
+
+The `+` tile on the rail opens Add repository as a tab. The tab shows the scan of the folder before you add it.
+
+The list has a switch for Initiatives and Files. Choose Files to see the files of the current repository. Type in the filter to find a file. Press a file to open it in a tab.
+
+Under a terminal tab, the scratchpad holds a note that you can send to the terminal, copy or clear. The `+` session button opens a chooser for the new session. In a document tab, the Alignment button opens a drawer on the right. It shows the consistency findings for the document and lists only the documents that have a concrete tie to it.
+
+The list has a switch for Work, Today and All repos, a filter, and the groups Needs you, In progress and Done. The badge on a row names the step where the initiative is, for example `review`, `accept` or `build`.
+
+The detail shows the title, the summary, the chips, the blocker (when the initiative is blocked), the phases and the artifacts. Only the phase where the initiative is opens by itself, and the task where it is has a highlight. Press a phase to open or close it. Under each artifact are its link and sync controls.
+
+Each tab shows a dot, its title and, under the title, its initiative and its session. Press × on a tab to close it. The `+ session` button is at the right end of the tabs.
 
 ## Navigation
 
@@ -32,6 +58,7 @@ Press a file anywhere in the workspace to open it in a tab. Any text file opens,
 - **Markdown** opens as a document. You can edit it and save it.
 - **JSON** opens pretty-printed. If the file is not valid JSON, the tab shows the text as written and says why.
 - **JSONL** opens as numbered records, one for each line. The tab marks a line that is not valid JSON.
+- **HTML** opens in `view` as the page it is. Use `raw` to see its source. The page cannot run scripts and cannot load anything from the network. To run the page's own scripts, press `run scripts`. This grant is for this tab only. The page can then run the scripts written inside it, but it still cannot load anything from the network, cannot load a script from another location, and cannot read the workspace. Press `scripts running — stop` to stop the scripts. Closing the tab also removes the grant.
 - **Other text** opens as numbered source lines. Spreadsheets, PDFs and images open in their own views.
 
 A tab for a file that is not markdown is read-only. It has no edit, diff or save control, because the workspace saves only markdown.

package/workspace/guide/proactive-engine.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: Today and the proactive engine"
 description: "What the Today item shows, how the morning brief is made, and how the workspace works out what is waiting for you."
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: Today and the proactive engine
@@ -46,7 +46,7 @@ Today learns from you, and only from you. The evidence is your own records on th
 
 - **Weights.** Three adjustments are added to an item's place in the order: one for its trigger (at most 8 points), one for its lane (at most 4) and one for its trigger at this time of day (at most 3). Time of day is morning 05-12, afternoon 12-17, evening 17-22 and night, in your local time. A cell moves only after 5 events, and moves less than the raw average. The total is at most 15, so learning reorders items that are close and cannot turn the stated order upside down. An item shows its adjustment and the counts behind it.
 - **What it never does.** It never lowers or hides what blocks on you: the needs and returned triggers get no negative adjustment and are never narrowed. Items of the morning brief teach no weight, because their order is fixed. Pause learning makes every weight zero and stops the weekly review, the proposals and the narrowing; feedback is still recorded.
-- **The weekly review.** About every 7 days, only while the workspace server runs, the workspace takes one snapshot. It does not catch up after a gap: it takes one snapshot of the last 7 days. **run the weekly review now** does the same on demand and is refused while learning is paused. Quiet hours hold scans, not this review.
+- **The weekly review.** About every 7 days, only while the workspace server runs, the workspace takes one snapshot. It does not catch up after a gap: it takes one snapshot of the last 7 days. **run the weekly review now** does the same on demand and is refused while learning is paused. Quiet hours hold scans, not this review. The review runs from the proactive tick, so while the engine is switched off there is no weekly review either; **run the weekly review now** still works.
 - **The rollup.** For the last 7 days: the hit rate (useful and acted, over useful, acted, not useful, wrong priority and dismissed), the used-as-is rate (accepted over accepted and sent back), corrections per prepared run (sends-back over every session started from a step, reviewed or not), and the items you reported as missed. Every rate shows its count. With fewer than 5 rated items, or 3 runs, it says there is not enough evidence and shows no rate.
 - **The watermelon check.** It looks only when the hit rate is 0.6 or more. It then names any of these: 2 or more items reported as missed, a used-as-is rate under 0.5 over 3 or more reviewed runs, or 0.5 or more corrections per prepared run over 3 or more runs. A good hit rate with one of these under it is not a good week.
 - **Lessons.** The review proposes lessons from four templates: a trigger that was useful under 40% or at least 80% of the time (5 or more ratings), items you reported as missed (2 or more), and a trigger that did badly in one part of the day only. A lesson is a proposal. It is approved, rejected or retired only when you press the button. A rejected lesson is not proposed again for 28 days. At most 10 lessons are approved at once.
@@ -93,6 +93,10 @@ A verdict never changes a status, a lifecycle record or an acceptance. It is rec
 | quiet hours | A start and an end time. No automatic scan runs between them. |
 | pause learning | Stops all learning: weights are zero, and there is no weekly review, no proposal and no narrowing. Feedback is still recorded. |
 
+When you save a setting, Today shows the saved value immediately. A read that started before the save does not replace it.
+
+Text that you type in a setting (the name, the stalled days, the quiet hours) or in the "something was missed" box stays in the box until you save it. A refresh of Today does not clear it, and the box keeps the focus.
+
 ## The commands
 
 - `pmos proactive today` lists the items.

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

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: validate a repository"
 description: "How the validate item checks that a repository agrees with itself, and the optional second check with TypeSafe."
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: validate a repository
@@ -61,6 +61,21 @@ Jev's answers are **suspected**, not proven. They appear in their own group, **s
 
 Two rejected keys, or three failed requests in a row, pause automatic checking for that repository. The page says why and shows **resume**. The workspace appends suspected pairs to `claims.jsonl`. Those lines hold a short snippet of the claim. A pair that Jev found fine is not written.
 
+## Read documents for status
+
+A second switch, **read documents for status**, is next to the first one. It is off until you turn it on. It sends texts only when the four conditions above also hold.
+
+When it is on, the workspace asks Jev two more questions about the documents that belong to an initiative:
+
+- **Is it a stub?** Each PRD, rubric and brief that the initiative record names, against the initiative's title and intent.
+- **Does a note contradict a requirement?** Each other document whose frontmatter names the initiative, for example a meeting note, against the requirements of the initiative's PRD.
+
+A document belongs to an initiative only if the record names its path or its own frontmatter names the initiative. Similar words do not make a link.
+
+The first check after you turn this switch on records the documents that exist and sends nothing for them. After that, the workspace sends a document only when it changes. If you turn the switch off, the workspace forgets that starting point. When you turn it on again, it starts again from the documents that exist then. Documents that changed while the switch was off are not sent.
+
+The answers appear in the initiative detail under **What the documents say**, as lines that start with **Documents suggest**. Each line says that it is a suggestion and names the model. A suggestion never changes a phase, a status or a count, and the workspace writes nothing to the document.
+
 ## Check with TypeSafe
 
 ## What leaves your machine