create-pmos 0.62.0 → 0.63.1

package/package.json

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

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@ff2e983
+kernel-source: pmos@4cf3dc9
 assembled: 2026-10-06
 mode: vendor

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

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-06T17:04:03Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T22:58:51Z"}
 status: stable
 ---
 

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

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-06T17:04:03Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T22:58:51Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-06T17:04:03Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T22:58:51Z"}
 status: stable
 ---
 

package/workspace/guide/index.md

@@ -48,6 +48,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [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.
+- [Notes](notes.md): listen to a meeting on this machine, see decisions, actions and questions caught and checked against the repository, and get a summary.
 - [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.
 - [Initiatives: the Roadmap, the List and the initiative sheet](initiatives-screen.md): how to read and order the initiatives of a repository, open the sheet, make a new initiative, and review the cycle.
 - [Initiatives and the Roadmap: Now, Next and Later](initiatives-roadmap.md): what day one shows, how an agent proposes a move, and `pmos initiative` and `pmos measure` from a terminal.

package/workspace/guide/layout.md

@@ -127,7 +127,7 @@ The address options `?layout=legacy` and `?fixture=cockpit` keep the older layou
 
 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. The rail has no tools menu: the repository list and Validate are in Settings, and everything else is in ⌘K.
 
-Today, Validate, live notes and Add repository open as a tab, not in place of the list. Choose the same one again and the existing tab comes to the front.
+Today, Validate, live notes, notes and Add repository open as a tab, not in place of the list. Choose the same one 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.
 

package/workspace/guide/notes.md

@@ -0,0 +1,79 @@
+---
+type: Guide
+title: "Guide: notes"
+description: "How to take notes in a meeting: listen to your microphone and the meeting on this machine, see decisions, actions and questions caught as they are said, check them against the repository, and get a summary."
+timestamp: 2026-10-06
+---
+
+# Guide: notes
+
+The Notes view is one screen for one meeting. Your own notes are on the left, with the decisions, actions and questions that the workspace catches while people talk. The transcript is on the right. Notes are kept on this machine, outside every repository.
+
+## Start a meeting
+
+1. Press ⌘K, type **notes** and press Enter. The view opens as a tab. It is the same in every repository.
+2. Press **New meeting**. Type a title. Type your own notes in the box below it; they steer the summary. The note saves itself when you stop typing.
+3. Press **All notes** to open an earlier note. Press the settings button for local transcription, Jev, private and delete.
+
+## Listen
+
+1. Press **Listen**. Select what to listen to:
+   - **My microphone**: what you say.
+   - **The meeting**: the other people in an online meeting. Select the meeting's tab or window next, and tick **Share tab audio**.
+2. Press **Start**. The header shows a red dot, the time, and the sources. Tell people that you are taking notes.
+3. Each line shows in the transcript a few seconds after it is said, with who said it, the time and its label. Your lines are **You**. The meeting's lines are **Meeting**: click the name to change it. The transcript cannot tell the people in the meeting apart.
+4. Press **Stop** to end. The summary shows at the top of your notes.
+
+The meeting can only be heard when local transcription is set up. Until then, **Listen** hears your microphone only, through the browser's own recognition on this device.
+
+## What is caught
+
+Each line gets a label: decision, action, question, topic, statement or small talk. Decisions, actions and questions go into their sections as they are said. After **Stop**, statements with a number go under **Facts mentioned**.
+
+- To remove an item that does not belong, press the **x** beside it.
+- When a caught line is about something in the repository, the closest file shows beside it: **see** the file, a check mark when Jev finds that the file says the same, or **≠** the file when Jev finds that the line says something different. Point at the mark to see the file and the line.
+
+## Set up local transcription
+
+Local transcription uses whisper.cpp, a free program that runs on your machine. A Mac with Apple silicon (M1 or later) and 8 GB of memory is enough. The model is about 1.6 GB on disk and uses about 3 GB of memory while it runs.
+
+1. Open the settings and press **Set up in a terminal**. A terminal opens with the setup commands typed in. They install whisper.cpp with Homebrew and download the model into the workspace's own folder.
+2. Read the commands and press Enter in the terminal. The workspace does not run them for you.
+3. Homebrew then says that whisper.cpp needs a model file. That is expected: the next command downloads it. Keep the terminal open until it says **Whisper is set up**.
+4. Open the settings again. It says **Whisper is set up**.
+
+If lines come slowly, choose **Faster (about 550 MB)** under **Model** in the settings, press **Set up in a terminal** and press Enter to download it. It is the same model in a smaller form: it starts and runs faster on an M1 and makes a few more mistakes. **Most accurate (1.6 GB)** is the default.
+
+Whisper writes in the language you choose in the settings under **Language spoken in the meeting**: English unless you change it, or Indonesian. **Detect for each line** lets Whisper guess for each few seconds of speech; it can guess wrong and write a line in another language, so choose the language when you know it.
+
+If the download stops, press **Set up in a terminal** again and press Enter. The download continues where it stopped, and a part-downloaded model is never used.
+
+## Use Jev for labels and checks
+
+Without Jev, the workspace labels each line with its own rules and finds the closest file by shared words. Jev labels better and can say whether a line agrees with the file.
+
+1. Save a TypeSafe key and switch on validation for the repository (see [Validate with TypeSafe](validate-with-typesafe.md)).
+2. Open the settings and switch on **Label lines with Jev**. Switch on **Check notes against this repository with Jev** for the checks too. Both are off until you switch them on, for each repository.
+
+With the switches on, each line goes to TypeSafe for its label. For a caught line, that line and one passage of the closest file go too. Audio, speaker names and private notes never go. A line that looks like a secret is not sent.
+
+## Dictate into your notes
+
+1. Put the cursor where the text must go, then press **Dictate** and speak.
+2. Say **new line** or **new paragraph** to start one. Say **scratch that** to remove the phrase you just said.
+3. Press **Stop dictating** when you are done.
+
+## Copy, private and delete
+
+- **Copy as Markdown** puts the title, the summary, your notes, the caught items and the transcript on the clipboard.
+- In the settings, **Mark private** stops listening at once. A private note is not recorded again, and nothing from it goes to Jev or to an agent. **Mark not private** undoes it.
+- **Summary by agent** starts an agent session in the selected repository that writes a summary into the note. Lines that look like a secret are removed first.
+- **Delete** removes the note, its transcript and its summaries from this machine after you confirm. You cannot undo it.
+
+## What stays on your machine
+
+- Audio never leaves this machine. The page sends it to the workspace on this machine, which gives it to whisper.cpp in a temporary file and deletes the file at once. The browser's own recognition is used only on the device, never in the cloud.
+- Notes are files in the workspace's own folder on this machine (`notes/` in the state folder). They are never written into a repository.
+- Only Jev, with the switches on, and **Summary by agent**, when you press it, receive any text from a note.
+
+Live notes is a different tool: it maps each talking point to an initiative. See [Live notes](live-notes.md).

package/workspace/lib/jev-notes.js

@@ -0,0 +1,162 @@
+'use strict';
+/* jev-notes.js — the one bridge from the Notes view to Jev (meeting-notes Run 2, D91).
+ *
+ *   gatesFor(key, flags) · checkGatesFor(key, flags) · senderFor(key, flags, askOpts) · infoFor(present, flags)
+ *   label({ ask, key, askOpts, text, pause })            → { cat, p } | { cat: null, reason }
+ *   compare({ ask, key, askOpts, text, passage, pause }) → { verdict: 'agrees'|'differs'|'related', words } | { verdict: null, reason }
+ *   getSwitch(runtimeDir, root) · setSwitch(runtimeDir, root, { jev, check })
+ *
+ * WHAT MAY LEAVE THE MACHINE. For a label: one cleaned transcript line and one Choice question. For a check: the line and
+ * ONE repository passage (lib/notes-repo.js closest, at most 1,200 characters) and two Noul questions. Only through
+ * lib/typesafe.js. Labels need three gates: a saved key, D79 consent for the repository and the switch "notes may use Jev".
+ * A check needs those and the switch "check notes against this repository". Both switches default off and live in the
+ * per-user runtime directory. Never sent: audio, a speaker's name, a line or passage the secret scan matches, a private
+ * note (the caller refuses it before this module), anything while paused.
+ *
+ * WHAT A RESULT IS. Advisory (D40), shown in words. A label under UNSURE_BELOW keeps the local label. A check says
+ * "agrees" or "differs" only above SURE; otherwise "related", which is what the local match alone also says.
+ *
+ * PAUSE. Two rejected keys or three failed asks in a row pause Jev for the repository until the server restarts or the
+ * PM turns a switch off and on again; the local labels carry on.
+ */
+const fs = require('fs');
+const path = require('path');
+const typesafe = require('./typesafe');
+const scanner = require('./secret-scan');
+
+const UNSURE_BELOW = 0.55;
+const SURE = 0.65;
+const REJECTED_LIMIT = 2;
+const UNREACHABLE_LIMIT = 3;
+const NOTES_ASK = { timeoutMs: 10000, retries: 1, backoffMs: 400 };
+
+const CATS = {
+  decision: 'A decision: something the group agreed, chose, approved or ruled out.',
+  action: 'An action item: a task someone will do, or is asked to do, often with an owner or a due day.',
+  question: 'An open question the meeting raises and has not answered.',
+  topic: 'A topic explanation: it introduces or explains what is being discussed, or moves to a new subject.',
+  statement: 'A statement of fact, data, a claim or an opinion about the work.',
+  'small talk': 'Small talk, a greeting, thanks, or talk about the meeting itself.',
+};
+const LABEL_INSTRUCTIONS = 'This is one line from a meeting transcript. Which kind of line is it?';
+const SAME_Q = 'Does the PASSAGE from the repository already say what the MEETING LINE says?';
+const DIFF_Q = 'Does the MEETING LINE say something different from, or in conflict with, the PASSAGE from the repository (for example another number, date, owner or choice)?';
+
+/* ── gates and switches ─────────────────────────────────────────────────────────────────────────── */
+function gates({ key, consent, jev }) {
+  const missing = [];
+  if (!key) missing.push('key');
+  if (!consent) missing.push('consent');
+  if (!jev) missing.push('jev');
+  return { open: missing.length === 0, missing };
+}
+function checkGates({ key, consent, jev, check }) {
+  const g = gates({ key, consent, jev });
+  if (!check) g.missing.push('check');
+  return { open: g.missing.length === 0, missing: g.missing };
+}
+const GATE_WORDS = {
+  key: 'No TypeSafe key is saved.',
+  consent: 'Validation is not switched on for this repository.',
+  jev: 'Notes may not use Jev in this repository.',
+  check: 'Checking notes against this repository is off.',
+};
+const gateSentence = (missing) => missing.map((m) => GATE_WORDS[m]).join(' ');
+const gatesFor = (key, f) => gates({ key: typesafe.validKey(key), consent: !!(f && f.consent), jev: !!(f && f.jev) });
+const checkGatesFor = (key, f) => checkGates({ key: typesafe.validKey(key), consent: !!(f && f.consent), jev: !!(f && f.jev), check: !!(f && f.check) });
+
+/** { ask, check, askOpts }: `ask` sends labels and `check` is true when checks may also be sent. Both shut when a gate is. */
+function senderFor(key, flags, askOpts = {}) {
+  const g = gatesFor(key, flags);
+  if (!g.open) return { ask: null, check: false, gates: g, askOpts: {} };
+  return { ask: (a) => typesafe.ask(a), check: checkGatesFor(key, flags).open, gates: g, askOpts: { ...NOTES_ASK, ...askOpts } };
+}
+/** What the view needs to explain the two switches. Booleans and sentences only. */
+function infoFor(present, flags) {
+  const f = { key: !!present, consent: !!(flags && flags.consent), jev: !!(flags && flags.jev), check: !!(flags && flags.check) };
+  const l = gates(f); const c = checkGates(f);
+  return { jev: f.jev, check: f.check, label_open: l.open, check_open: c.open, missing: c.missing,
+    sentence: l.open ? (c.open ? null : gateSentence(c.missing.filter((m) => m === 'check'))) : gateSentence(l.missing) };
+}
+
+const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
+const switchFile = (runtimeDir) => path.join(runtimeDir, 'notes', 'settings.json');
+function getSwitch(runtimeDir, root) {
+  const s = readJson(switchFile(runtimeDir), {});
+  const r = s && s.repos && root ? s.repos[root] : null;
+  return { jev: !!(r && r.jev === true), check: !!(r && r.check === true) };
+}
+function setSwitch(runtimeDir, root, { jev, check } = {}) {
+  const s = readJson(switchFile(runtimeDir), {});
+  const prev = getSwitch(runtimeDir, root);
+  const next = { jev: typeof jev === 'boolean' ? jev : prev.jev, check: typeof check === 'boolean' ? check : prev.check };
+  const f = switchFile(runtimeDir);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const tmp = f + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify({ repos: { ...((s && s.repos) || {}), [root]: next } }), { mode: 0o600 });
+  fs.renameSync(tmp, f);
+  pauses.delete(root);
+  return next;
+}
+
+/* ── pause ─────────────────────────────────────────────────────────────────────────────────────── */
+const pauses = new Map();    // root → { rejected, unreachable, paused }
+const pauseOf = (root) => { if (!pauses.has(root)) pauses.set(root, { rejected: 0, unreachable: 0, paused: null }); return pauses.get(root); };
+function note(p, res) {
+  if (res.ok) { p.rejected = 0; p.unreachable = 0; return; }
+  if (res.status === 401) { p.rejected++; p.unreachable = 0; } else { p.unreachable++; p.rejected = 0; }
+  if (p.rejected >= REJECTED_LIMIT) p.paused = 'The service rejected the key twice, so Jev is paused for notes.';
+  else if (p.unreachable >= UNREACHABLE_LIMIT) p.paused = 'The service could not be reached three times in a row, so Jev is paused for notes.';
+}
+const secretIn = (...texts) => texts.some((t) => scanner.scan(String(t || '')).length > 0);
+
+/* ── asking ────────────────────────────────────────────────────────────────────────────────────── */
+function choiceProbs(ans) {
+  const probs = {};
+  const put = (k, v) => { const n = Number(v); if (typeof k === 'string' && Number.isFinite(n)) probs[k.toLowerCase()] = n; };
+  if (!ans || typeof ans !== 'object') return probs;
+  const raw = ans.probabilities || ans.distribution;
+  if (Array.isArray(raw)) { for (const x of raw) if (x && typeof x === 'object') put(x.option || x.label || x.choice, x.probability != null ? x.probability : x.p); }
+  else if (raw && typeof raw === 'object') for (const [k, v] of Object.entries(raw)) put(k, v);
+  if (!Object.keys(probs).length && typeof ans.choice === 'string') put(ans.choice, ans.confidence != null ? ans.confidence : 1);
+  return probs;
+}
+
+/** One line's label from Jev. The caller has checked the private flag; this checks the pause and the scan. */
+async function label({ ask, key, askOpts = {}, text, root = '' }) {
+  const p = pauseOf(root);
+  if (!ask) return { cat: null, reason: 'off' };
+  if (p.paused) return { cat: null, reason: 'paused', sentence: p.paused };
+  if (secretIn(text)) return { cat: null, reason: 'withheld' };
+  const res = await ask({ key, state: String(text).slice(0, 2000), questions: { kind: { type: 'choice', instructions: LABEL_INSTRUCTIONS, criteria: CATS } }, ...askOpts });
+  note(p, res);
+  if (!res.ok) return { cat: null, reason: 'failed', sentence: res.reason || null };
+  const probs = choiceProbs(res.answers && res.answers.kind);
+  const top = Object.entries(probs).filter(([k]) => CATS[k]).sort((a, b) => b[1] - a[1])[0];
+  if (!top || top[1] < UNSURE_BELOW) return { cat: null, reason: 'unsure' };
+  return { cat: top[0], p: top[1], model: res.model || null };
+}
+
+const wordsFor = (v) => (v >= 0.85 ? 'very likely' : 'likely');
+/** One captured line against one passage. */
+async function compare({ ask, key, askOpts = {}, text, passage, root = '' }) {
+  const p = pauseOf(root);
+  if (!ask) return { verdict: null, reason: 'off' };
+  if (p.paused) return { verdict: null, reason: 'paused', sentence: p.paused };
+  if (!passage || !passage.text) return { verdict: null, reason: 'nothing' };
+  if (secretIn(text, passage.text)) return { verdict: null, reason: 'withheld' };
+  const state = 'MEETING LINE:\n' + String(text).slice(0, 2000) + '\n\nPASSAGE (' + passage.path + '):\n' + String(passage.text).slice(0, 1200);
+  const res = await ask({ key, state, questions: { same: { type: 'noul', instructions: SAME_Q }, differs: { type: 'noul', instructions: DIFF_Q } }, ...askOpts });
+  note(p, res);
+  if (!res.ok) return { verdict: null, reason: 'failed', sentence: res.reason || null };
+  const num = (a) => { const v = a && (a.type == null || a.type === 'noul') ? Number(a.noul) : NaN; return Number.isFinite(v) && v >= 0 && v <= 1 ? v : null; };
+  const same = num(res.answers && res.answers.same); const diff = num(res.answers && res.answers.differs);
+  if (same == null && diff == null) return { verdict: null, reason: 'unreadable' };
+  if (diff != null && diff >= SURE && (same == null || diff > same)) return { verdict: 'differs', words: wordsFor(diff), model: res.model || null };
+  if (same != null && same >= SURE) return { verdict: 'agrees', words: wordsFor(same), model: res.model || null };
+  return { verdict: 'related', words: null, model: res.model || null };
+}
+function pauseStatus(root) { const p = pauses.get(root); return p && p.paused ? p.paused : null; }
+
+module.exports = { gates, checkGates, gatesFor, checkGatesFor, gateSentence, senderFor, infoFor, getSwitch, setSwitch, label, compare, choiceProbs, pauseStatus,
+  CATS, UNSURE_BELOW, SURE, REJECTED_LIMIT, UNREACHABLE_LIMIT };

package/workspace/lib/notes-repo.js

@@ -0,0 +1,133 @@
+'use strict';
+/* notes-repo.js — find the repository passage a meeting line is about (meeting-notes Run 2, D91). Local and read-only.
+ *
+ *   passages(root, { exclude }) → [{ path, line, text }]      the repository's Markdown paragraphs, cached for a minute
+ *   closest(root, text, { exclude }) → { path, line, text, shared } | null
+ *
+ * WHAT IT READS. Every tracked-looking Markdown file under the repository root, skipping dependency, build and hidden
+ * folders, at most MAX_FILES files and MAX_FILE_BYTES each. A paragraph is a run of non-blank lines outside frontmatter
+ * and code fences, cut to PASSAGE_MAX characters. An excluded path (D79 exclusions) is never read.
+ *
+ * HOW IT MATCHES. Content words and numbers shared with the line, each weighted by how rare it is across the paragraphs.
+ * A passage counts only when it shares at least MIN_SHARED words and scores at least MIN_SCORE, so a line about nothing
+ * in particular finds nothing. Numbers count as words: "a 14-day trial" and "21 days" are what a consistency check is for.
+ *
+ * WHAT IT NEVER DOES. It writes nothing and sends nothing. The Jev check (lib/jev-notes.js) decides what leaves.
+ */
+const fs = require('fs');
+const path = require('path');
+const settings = require('./typesafe-settings');
+
+const MAX_FILES = 3000;
+const MAX_FILE_BYTES = 512 * 1024;
+const PASSAGE_MAX = 1200;
+const MIN_SHARED = 3;
+const MIN_SCORE = 3;
+const CACHE_MS = 60000;
+const SKIP = new Set(['node_modules', '.git', 'vendor', 'dist', 'build', 'out', 'coverage', '.next', 'tmp', 'payload']);
+
+const STOP = new Set(('the and for are but not you all any can had her was one our out has have this that with from they will would there their what '
+  + 'about which when make like time just know take into year your some could them than then look only come its over think also back after use '
+  + 'two how work first well way even want because these give most should does did done been being were yeah okay right really thing things '
+  + 'going gonna said say says very much more less here where who why let lets get got need needs maybe sure good great thanks thank '
+  + 'today week next last new old same other each every into onto upon per via yes no').split(/\s+/));
+const NUM_WORDS = { one: '1', two: '2', three: '3', four: '4', five: '5', six: '6', seven: '7', eight: '8', nine: '9', ten: '10', eleven: '11', twelve: '12',
+  thirteen: '13', fourteen: '14', fifteen: '15', sixteen: '16', seventeen: '17', eighteen: '18', nineteen: '19', twenty: '20', thirty: '30', forty: '40', fifty: '50' };
+const stem = (w) => {
+  const x = w.replace(/'s$/, '');
+  if (/(?:ing|ed|es)$/.test(x)) return x.replace(/(?:ing|ed|es)$/, (s) => (x.length - s.length >= 4 ? '' : s));
+  return /[^s]s$/.test(x) && x.length >= 4 ? x.slice(0, -1) : x;
+};
+/** Content words and numbers. "twenty-one" is 21; "14-day" is 14 and day. */
+function termsOf(text) {
+  const t = String(text || '').toLowerCase().replace(/\b(twenty|thirty|forty|fifty)[- ](one|two|three|four|five|six|seven|eight|nine)\b/g,
+    (m, a, b) => String(Number(NUM_WORDS[a]) + Number(NUM_WORDS[b])));
+  const out = [];
+  for (const raw of t.match(/[\p{L}\p{N}']+/gu) || []) {
+    const w = NUM_WORDS[raw] || raw;
+    if (/^\d+$/.test(w)) { out.push(w); continue; }
+    if (w.length < 3 || STOP.has(w)) continue;
+    out.push(stem(w));
+  }
+  return out;
+}
+
+function walk(root, exclude) {
+  const out = [];
+  const go = (dir) => {
+    if (out.length >= MAX_FILES) return;
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (out.length >= MAX_FILES) return;
+      if (e.name.startsWith('.') || SKIP.has(e.name)) continue;
+      const p = path.join(dir, e.name);
+      const rel = path.relative(root, p).split(path.sep).join('/');
+      if (settings.isExcluded(exclude, rel)) continue;
+      if (e.isDirectory()) go(p);
+      else if (e.isFile() && /\.md$/i.test(e.name)) out.push(rel);
+    }
+  };
+  go(root);
+  return out;
+}
+function paragraphsOf(rel, text) {
+  const out = [];
+  const lines = String(text).split(/\r?\n/);
+  let i = 0;
+  if (lines[0] === '---') { i = 1; while (i < lines.length && lines[i] !== '---') i++; i++; }
+  let fence = false; let buf = []; let start = 0;
+  const end = () => { if (buf.length) { const t = buf.join(' ').replace(/\s+/g, ' ').trim(); if (t.length >= 30) out.push({ path: rel, line: start + 1, text: t.slice(0, PASSAGE_MAX) }); } buf = []; };
+  for (; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^\s*(```|~~~)/.test(l)) { end(); fence = !fence; continue; }
+    if (fence) continue;
+    if (!l.trim() || /^#{1,6}\s/.test(l) || /^\s*\|?\s*-{3,}/.test(l)) { end(); continue; }
+    if (!buf.length) start = i;
+    buf.push(l.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, ''));
+  }
+  end();
+  return out;
+}
+
+const cache = new Map();     // root → { at, key, items, df }
+function index(root, { exclude = [], now = Date.now() } = {}) {
+  const key = JSON.stringify(exclude);
+  const hit = cache.get(root);
+  if (hit && hit.key === key && now - hit.at < CACHE_MS) return hit;
+  const items = [];
+  for (const rel of walk(root, exclude)) {
+    let text = '';
+    try { const st = fs.statSync(path.join(root, rel)); if (st.size > MAX_FILE_BYTES) continue; text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch { continue; }
+    for (const p of paragraphsOf(rel, text)) items.push({ ...p, terms: new Set(termsOf(p.text)) });
+  }
+  const df = new Map();
+  for (const it of items) for (const w of it.terms) df.set(w, (df.get(w) || 0) + 1);
+  const ix = { at: now, key, items, df };
+  cache.set(root, ix);
+  return ix;
+}
+function passages(root, opts = {}) { return index(root, opts).items.map(({ path: p, line, text }) => ({ path: p, line, text })); }
+
+/** The passage that shares the most rare words with `text`, or null when none shares enough. */
+function closest(root, text, { exclude = [], now = Date.now() } = {}) {
+  if (!root) return null;
+  const ix = index(root, { exclude, now });
+  const q = new Set(termsOf(text));
+  if (q.size < MIN_SHARED) return null;
+  const n = ix.items.length || 1;
+  let best = null;
+  for (const it of ix.items) {
+    let s = 0; const shared = [];
+    // a shared word counts 1, more when it is rare in the repository; a long passage is not favoured for its length
+    for (const w of q) if (it.terms.has(w)) { s += 1 + Math.log(n / (ix.df.get(w) || 1)); shared.push(w); }
+    if (shared.length < MIN_SHARED || s < MIN_SCORE) continue;
+    const rank = s / Math.sqrt(it.terms.size / 20 + 1);
+    if (!best || rank > best.rank) best = { path: it.path, line: it.line, text: it.text, shared, score: s, rank };
+  }
+  if (!best) return null;
+  return { path: best.path, line: best.line, text: best.text, shared: best.shared };
+}
+function clearCache() { cache.clear(); }
+
+module.exports = { passages, closest, termsOf, paragraphsOf, clearCache, PASSAGE_MAX, MIN_SHARED, MIN_SCORE };