create-pmos 0.46.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

@@ -1,7 +1,8 @@
 ---
 type: Guide
 title: "Guide: initiatives and next steps"
-timestamp: 2026-10-03
+description: "What the initiative detail shows, top to bottom: status, lifecycle control, and the next step the workspace proposes."
+timestamp: 2026-10-04
 ---
 
 # Guide: initiatives and next steps
@@ -14,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

@@ -1,7 +1,8 @@
 ---
 type: Guide
 title: "Guide: find knowledge without reading whole files"
-timestamp: 2026-10-03
+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-04
 ---
 
 # Guide: find knowledge without reading whole files
@@ -18,7 +19,7 @@ The map has an **edge** only where a file states a relation:
 |---|---|
 | link | A Markdown link to a tracked file. |
 | frontmatter | A path in `prd_path`, `rubric_path`, `explainer_path` or `sources`. |
-| supersedes, amended_by, cites | A document that chooses to carry one of these keys. |
+| supersedes, amended_by, cites, initiative | A document that chooses to carry one of these keys. |
 | initiative | An `initiative_id` that names an initiative record. |
 | anchor | A `parent_kr` of `health:<id>` or a KR id. |
 | cites (mention) | A `D<nn>` in the text, such as `D65`, with two or more digits. |
@@ -27,6 +28,10 @@ A link that points at a missing file is **dangling**. It is listed and never bec
 
 It does not guess. A file that talks about a topic without a link, a path or a `D<nn>` is not connected to it. It does not use embeddings or a model, and it does not use the network.
 
+## Typed keys
+
+A document may carry `supersedes`, `amended_by`, `cites` and `initiative` in its frontmatter. Each key is one line and holds one or more paths to `.md` files, separated by commas. The map reads each path as a stated edge of that type. A path to a file that does not exist is listed as dangling and never becomes an edge. Nobody fills these keys in for existing documents; add them to new or edited ones. `pmos kg stats` shows how many edges are typed and how many are inferred from a `D<nn>` in the text.
+
 ## Commands
 
 | Command | What it does |
@@ -49,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

@@ -1,12 +1,39 @@
 ---
 type: Guide
 title: "Guide: layout"
-timestamp: 2026-10-03
+description: "The three workspace columns: navigation, detail and tabs, and what each one holds."
+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
 
@@ -31,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

@@ -1,7 +1,8 @@
 ---
 type: Guide
 title: "Guide: Today and the proactive engine"
-timestamp: 2026-10-03
+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-04
 ---
 
 # Guide: Today and the proactive engine
@@ -39,6 +40,22 @@ From a Today item that names an initiative, you can ask for the plan and approve
 
 The states of an entry are queued, started, skipped, expired and cancelled.
 
+## What it learns
+
+Today learns from you, and only from you. The evidence is your own records on this computer: the verdict you give an item, what you do with it (opened, acted, dismissed, ignored), and your accept or send-back on a prepared session. The workspace makes no model call to do this. The weights are arithmetic, and the lessons are written from fixed templates filled with counts.
+
+- **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 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.
+- **Where an approved lesson goes.** Into the state folder, and from there to the morning-brief session, which reads it with `pmos proactive learn lessons`. It goes into no other prompt, so the prompt and the plan hash of a prepared step do not change, and no file of any repository is written. To keep a lesson in repository memory, copy it there yourself.
+- **Narrowing.** A trigger other than needs and returned that you rated useful under 30% of the time over 10 or more ratings in 28 days is left off Today. Today says so, with the numbers and a **restore** button. The trigger is still scanned. A restore holds until 10 new ratings of that trigger have arrived.
+- **forget what it learned** makes the workspace ignore all earlier feedback from then on. Nothing is deleted.
+
+The records are `learn-events.jsonl` (restore and reset), `lessons.jsonl` and `proactive-rollups.jsonl`, in the workspace state folder. They are not committed.
+
 ## What it shows
 
 Today scans for five conditions. Each one becomes one item with the reason and the evidence.
@@ -60,7 +77,7 @@ The order is fixed and you can read it: what blocks on you first, then an unrevi
 - dismiss 7 days hides the item for 7 days.
 - something was missed records a note about what Today should have shown. It needs a note.
 
-A verdict never changes a status, a lifecycle record or an acceptance. In this release a verdict is only recorded. Nothing uses it to change the order yet.
+A verdict never changes a status, a lifecycle record or an acceptance. It is recorded, and it is evidence for what Today learns, as described above.
 
 ## Settings
 
@@ -74,7 +91,11 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 | name | Used in the greeting. |
 | stalled after N days | The stalled threshold, from 1 to 90 days. |
 | quiet hours | A start and an end time. No automatic scan runs between them. |
-| pause learning | Saved for later. Nothing learns from your verdicts in this release, so it changes nothing today. |
+| 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
 
@@ -83,12 +104,13 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 - `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--background-prepare on|off`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
 - `pmos proactive brief` shows today's brief. `pmos proactive brief submit --file PATH` submits one. `pmos proactive brief schedule` makes the 06:45 schedule for the current repository.
 - `pmos proactive prepare` shows the queue. `pmos proactive prepare plan --initiative ID` shows a plan and its hash. `pmos proactive prepare queue --initiative ID --item ITEM --sha HASH` approves it. `pmos proactive prepare cancel ID` cancels an entry. `pmos proactive prepare run` looks at the queue now.
+- `pmos proactive learn` shows the rollup, the weights, the narrowed triggers and the lessons. `pmos proactive learn run` takes the weekly review now. `pmos proactive learn lessons` lists the approved lessons. `pmos proactive learn approve ID`, `reject ID` and `retire ID` decide a lesson. `pmos proactive learn restore TRIGGER` brings back a narrowed trigger. `pmos proactive learn reset` makes it ignore earlier feedback.
 - `pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed` records feedback. Use `--missed "text"` for a missed item.
 
 ## Limits
 
 - It runs only while the workspace server runs. It does not catch up for time the server was off. A sleeping computer gets no scan.
 - The items from the records come from this computer. The workspace itself does not read your mail or your calendar. Only the morning-brief session does, and only the sources you switched on.
-- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
+- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback, and learns from it as described above. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
 - An unreadable repository is listed as not read. An empty list is not proof that nothing waits there.
 - The records stay in the workspace state folder on this computer. They are not committed.

package/workspace/guide/scheduled-tasks-and-cli.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: scheduled tasks and the command line"
+description: "How scheduled tasks run a skill in a terminal session, their limits, and the command line that manages them."
 timestamp: 2026-10-03
 ---
 

package/workspace/guide/statuses.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: statuses"
+description: "The nine initiative statuses, who acts on each, and why a status is worked out again each time and never typed."
 timestamp: 2026-10-03
 ---