create-pmos 0.47.0 → 0.49.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/index.md

@@ -1,7 +1,7 @@
 ---
 type: Guide
 title: "Guide: start here"
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: start here
@@ -38,4 +38,5 @@ The workspace has three columns. [Layout](layout.md) explains where things open.
 - [Scheduled tasks and the command line](scheduled-tasks-and-cli.md): how to make, edit and run scheduled tasks.
 - [Validate a repository](validate-with-typesafe.md): what each kind of document is compared with, how to read the verdict, and what leaves your machine.
 - [Today and the proactive engine](proactive-engine.md): what Today finds, what you can do with an item, the settings, the commands and the limits.
+- [Live notes](live-notes.md): take notes in a meeting, confirm each talking point, and what goes to Jev when you turn it on.
 - [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.

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,22 @@ 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. If no check has anything to compare yet, the section says "Nothing to compare yet" and tells you what each check waits for, such as an approved contract, a feature lane or a stage word in the status line.
+
+In a documents repository (the pm-artifacts profile), only **Since approval** applies. It starts when you accept the work: after that, a commit to the brief or the deliverable shows here. Coverage and Record says are for product-code repositories.
+
+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,99 @@ 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` with `(jev unsure)` after it, 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.
+
+After a pass, the Knowledge view shows what happened to each undetermined file. Files with a problem are at the top of the list:
+
+- **failed**: the request did not succeed. The row gives the reason. The file keeps the local result, and the next pass sends it again.
+- **not asked**: sending stopped before this file. The row gives the reason.
+- **unreadable**: the workspace could not read Jev's answer. The file is not sent again until it changes.
+- **unsure**: Jev was not sure. The row names the two categories, and the file stays `undetermined`.
+- **withheld** or **excluded**: the file was not sent. The row says why.
+- **categorized**: Jev gave a category. The row names it.
+
+A line above the list counts the files in the view: decided by the local rules or your corrections, categorized by Jev, and still `undetermined`.
+
+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,40 @@
 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.
+
+If many tabs are open, the strip stays one row and scrolls sideways. Use the mouse wheel on the strip to scroll it. The tab in front always scrolls into view. Press `⇅ tabs at side` to show the tabs as a list down the left of the tabs column. In the list, each tab is one row, with its title, its initiative and session, and ×. The `+ session` button is at the top of the list, and the other controls are at the bottom. Press `⇆ tabs on top` to go back to the strip. The workspace remembers your choice in this browser. A phone and `?layout=legacy` always show the strip.
 
 ## Navigation
 
@@ -32,6 +60,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/live-notes.md

@@ -0,0 +1,78 @@
+---
+type: Guide
+title: "Guide: live notes"
+description: "How the Live notes view listens to a meeting, turns what is said into talking points, and lets you confirm each one, with an optional check by Jev."
+timestamp: 2026-10-04
+---
+
+# Guide: live notes
+
+The Live notes view takes notes during a meeting. Each thing that is said becomes a talking point. The workspace guesses which open initiative the point is about. You confirm the guess, change it or reject it, one card at a time. Nothing changes an initiative until you confirm.
+
+## Open the view
+
+1. Select the repository in the navigation column.
+2. Open the menu and select **live notes** under **Library**. The view opens as a tab for that repository.
+3. Press **New session**. A session is one meeting.
+
+If the repository has more than 255 open initiatives, the view asks you to select an anchor first. The session then uses only the initiatives of that anchor.
+
+## Add talking points
+
+You can type the points or let the view listen.
+
+- **Type.** Write one point for each line. Press Enter or **Add**. Shift+Enter starts a new line.
+- **Listen.** Press **Start listening**. The browser recognises speech on this device. No audio leaves the device. The first time, the browser can ask you to download the language. Press **Download for** and the language name.
+
+While the view listens, it shows **● Listening: notes are being taken**. Words that are not final show in grey and are not added. A phrase becomes a point at the end of a sentence or after a pause. Before the phrase becomes a point, the workspace cleans it: it removes filler words (um, uh, er, erm, hmm) and repeated words, adds a capital letter and adds a full stop.
+
+Press **Stop** to stop listening. Press **This meeting is private** to stop listening and mark the session private. Nothing from a private session goes to Jev.
+
+A browser that cannot recognise speech on the device says so. The view never sends audio to a cloud service. Chrome 139 and later can recognise speech on the device.
+
+## Confirm each point
+
+Each point shows as a card. Cards that wait for you are at the top. The card shows the guess and where the guess came from:
+
+| Source | What it means |
+|---|---|
+| local word match | The workspace compared the words of the point with the titles, intents and open questions of the open initiatives. A local guess is never shown above *possible*. |
+| Jev | Jev compared the point with the same titles, intents and open questions. Its band is in words: *very likely*, *likely* or *possible*. |
+| agent session | An agent session placed the point with the `live-notes` command. |
+
+On each card:
+
+1. Select the initiative, or **none of these initiatives**.
+2. Select how the point relates to it: **validates**, **clarifies**, **extends**, **contradicts** or **answers a question**.
+3. For **answers a question**, select which open question it answers. The view refuses **answers a question** without one.
+4. Press **Confirm** or **Reject**.
+
+If you change nothing, Confirm records *accept*. If you change the initiative, the relation or the question, it records *change*. The counter shows how many points are confirmed, changed, rejected, waiting and withheld.
+
+A point that looks like a secret, such as a key or a token, is withheld. The view shows the reason and never the text.
+
+## Check with Jev
+
+**Check with Jev** is off until you turn it on. When it is off, every guess is a local word match and nothing leaves this machine.
+
+Jev checks a point only when all three of these are true:
+
+1. A TypeSafe key is saved (open **validate** in the settings and tools drawer).
+2. Validation is turned on for this repository (also under **validate**).
+3. **Check with Jev** is on in the Live notes view. It applies to this repository only.
+
+If one is missing, the view says which one, in words.
+
+When all three are true, the workspace sends each cleaned point to TypeSafe. It sends only the cleaned sentence and the titles, intents and open questions of the initiatives in the session. It does not send the speaker's name. It does not send a withheld point. It does not send a point from a private session. The key goes only in the request header.
+
+If Jev cannot be reached, or its answer cannot be read, the card still gets the local guess. The card says that Jev was not reached. If the service rejects the key twice, or cannot be reached three times in a row, Jev pauses for that session and the view shows the reason. The local word match continues.
+
+## Close the session
+
+Press **End and file the note**. The workspace writes a section in the day's requirements note, with your decisions. A rejected point is left out and counted. The raw transcript is deleted. The view shows the path of the note. A closed session is read-only.
+
+## Limits
+
+- The local word match compares words only. It does not understand meaning.
+- How well speech recognition and Jev work on a real meeting has not been measured. The share of guesses you change is the measure.
+- The view does not read meetings from Wispr Flow. The `live-notes` command does that in an agent session.