@timurtekb/tekjobs 0.24.1

package/app/server/store.mjs

@@ -0,0 +1,1131 @@
+// The vault is the database. This module reads the TekJobs Obsidian vault (job notes, criteria, companies, logs)
+// and performs the few writes the app is allowed to make: change a job's status, append a note, save an
+// application draft, edit the criteria JSON block, append a company row. It never rewrites anything else.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { P, VAULT, HOME_DIR, CONFIG_FILE, loadCriteria, loadCompanies, criteriaPresetFile } from '../../scraper/config.mjs';
+import { loadHealth, healthState } from '../../scraper/health.mjs';
+import { readFrontmatter, LEGACY_NARRATIVE_DEFAULT } from '../../scraper/vault.mjs';
+import { weightsFingerprint, titlePoints, recencyPoints, payPoints, rescoreFull } from '../../scraper/rescore.mjs';
+import { RESUME_NOTE, LEGACY_RESUME_NOTES } from '../../scraper/resume-sync.mjs';
+import { onboardingStatus, onboardingMaterials, importResume, saveProfile, fetchLink, initProfile } from '../../scraper/profile.mjs';
+export { onboardingStatus, onboardingMaterials, importResume, saveProfile, fetchLink, initProfile };
+
+const ROOT = fileURLToPath(new URL('../..', import.meta.url)); // the scraper repo root
+const isoDay = () => new Date().toISOString().slice(0, 10);
+const DE = /design (engineer|technologist|system)|ux engineer|ui engineer|creative technologist|prototyp/i;
+// `ready` is the approval boundary: a packet drafted and waiting on a person. `reviewing` already serves as
+// shortlisted and `applying` as preparing, so this is the one state the pipeline was missing rather than a
+// new model imposed on notes that already exist.
+const STATUSES = ['new', 'reviewing', 'applying', 'ready', 'applied', 'interviewing', 'offer', 'rejected', 'passed'];
+export { STATUSES, VAULT };
+
+// ---------- jobs ----------
+const cache = { key: '', rows: [] };
+function dirKey() {
+  const files = fs.readdirSync(P.jobs).filter((f) => f.endsWith('.md'));
+  let key = String(files.length);
+  for (const f of files) key += ':' + fs.statSync(path.join(P.jobs, f)).mtimeMs;
+  return key;
+}
+/** Forget the row cache; for callers outside this module that write a note directly. */
+export function cacheClear() { cache.key = ''; }
+export function listJobs() {
+  if (!fs.existsSync(P.jobs)) return [];
+  const key = dirKey();
+  if (key === cache.key) return cache.rows;
+  const rows = fs.readdirSync(P.jobs).filter((f) => f.endsWith('.md')).map((f) => {
+    const file = path.join(P.jobs, f);
+    const fm = readFrontmatter(file);
+    // The packet count comes from the note body, not the frontmatter, so a note edited by hand in Obsidian
+    // counts the same as one written through the app. Both reads land in the same cache, which only misses
+    // when a file's mtime changes.
+    return fm ? rowOf(fm, fs.readFileSync(file, 'utf8')) : null;
+  }).filter(Boolean);
+  cache.key = key; cache.rows = rows;
+  return rows;
+}
+
+/**
+ * How many application fields a note has something in.
+ *
+ * Scoped twice, because both scopes are load-bearing: to the Application section, since job descriptions are
+ * full of their own `- **Stack:** …` lines, and to the known field names, since a reader may add bullets of
+ * their own there. Without either, every note in the vault reads as a started packet.
+ */
+function countPacketFields(text = '') {
+  const section = (text.match(/^## Application\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/m) || [, ''])[1];
+  if (!section) return 0;
+  let n = 0;
+  for (const { field } of APPLICATION_FIELDS) {
+    const m = section.match(new RegExp(`^- \\*\\*${escapeRe(field)}:\\*\\*(.*)$`, 'm'));
+    const value = m ? m[1].trim() : '';
+    if (!value) continue;
+    // A note written before the template stopped pre-filling this carries a narrative nobody chose.
+    if (field === 'Narrative' && value === LEGACY_NARRATIVE_DEFAULT) continue;
+    n++;
+  }
+  return n;
+}
+
+function rowOf(fm, text = '') {
+  return {
+    id: fm._name,
+    company: fm.company || '', title: fm.title || '', location: fm.location || '',
+    remote: fm.remote === 'true' || isRemoteRow({ remote: false, location: fm.location || '' }), source: fm.source || '', url: fm.url || '',
+    score: Number(fm.score) || 0, posted: fm.posted || '', found: fm.found || '',
+    salary: fm.salary || '', salaryMax: Number(fm.salary_max) || 0, payBand: fm.pay_band || 'unknown',
+    status: fm.status || 'new', listing: String(fm.listing || 'open').startsWith('open') ? 'open' : String(fm.listing),
+    kind: DE.test(fm.title || '') ? 'design-eng' : 'adjacent', department: fm.department || '', jobId: fm.job_id || '',
+    passedReason: fm.passed_reason || '',
+    // Which criteria weights scored this note; `rescore --full` brings the ones that differ over.
+    weights: fm.weights || '',
+    // "link" when the person pasted it (Add by link); scanned notes carry no added_by line.
+    addedBy: fm.added_by || 'scan',
+    packet: countPacketFields(text),
+  };
+}
+// The scan's remote flag comes from the board's own workplace field, which some boards leave unset on a posting
+// whose location text plainly says "Remote". Either counts.
+export const isRemoteRow = (r) => r.remote || /\b(remote|anywhere|distributed|work from home|wfh)\b/i.test(r.location || '');
+// A list filter value is one name, a comma-separated list, or an array; "all" or nothing means no filter.
+const listOf = (v) => new Set([].concat(v || []).flatMap((s) => String(s).split(',')).map((s) => s.trim()).filter((s) => s && s !== 'all'));
+const withinDays = (iso, days) => !!iso && (Date.now() - new Date(iso).getTime()) / 86400000 <= Number(days);
+const num = (v) => (v === '' || v == null ? null : Number(v));
+
+/**
+ * Every filter the Jobs view, the API and the MCP tool share. Pay filters read the top of the stated range
+ * (salaryMax), which is the number the pay band is judged on; a posting with no stated pay passes "pay at
+ * least" only when it is not asked to state one (payKnown).
+ */
+export function filterJobs(f = {}) {
+  const { q = '', location = '', status, band, kind, source, company, minScore, maxScore, payMin, payMax, payKnown = false, postedDays, foundDays, remoteOnly = false, openOnly = true } = f;
+  const ql = String(q).trim().toLowerCase();
+  // source values are the note's source (ashby, greenhouse, wellfound…); the special value "link" means every
+  // note added by pasting a link, whatever board it turned out to be on.
+  const sources = listOf(source), statuses = listOf(status), bands = listOf(band), kinds = listOf(kind);
+  const companies = new Set([...listOf(company)].map((s) => s.toLowerCase()));
+  // Whole words, so "wa" finds "Seattle, WA" and not "Hawaii".
+  const locTerms = String(location).split(',').map((s) => s.trim()).filter(Boolean).map((t) => new RegExp(`(^|[^a-z])${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^a-z])`, 'i'));
+  // No minScore means no floor at all. A note created from an email or a pasted link can carry a negative
+  // score (nothing for the title terms to match, no location), and it must still show on the board.
+  const lo = num(minScore), hi = num(maxScore), pMin = num(payMin), pMax = num(payMax), pd = num(postedDays), fd = num(foundDays);
+  return listJobs().filter((r) => (!statuses.size || statuses.has(r.status))
+    && (!bands.size || bands.has(r.payBand))
+    && (!kinds.size || kinds.has(r.kind))
+    && (!sources.size || sources.has(r.source) || (sources.has('link') && r.addedBy === 'link'))
+    && (!companies.size || companies.has(String(r.company).toLowerCase()))
+    && (lo == null || r.score >= lo) && (hi == null || r.score <= hi)
+    && (!payKnown || r.salaryMax > 0)
+    && (!pMin || r.salaryMax >= pMin)
+    && (!pMax || (r.salaryMax > 0 && r.salaryMax <= pMax))
+    && (!pd || withinDays(r.posted, pd))
+    && (!fd || withinDays(r.found, fd))
+    && (!remoteOnly || isRemoteRow(r))
+    && (!openOnly || r.listing === 'open')
+    && (!locTerms.length || locTerms.some((t) => t.test(r.location)))
+    && (!ql || `${r.company} ${r.title} ${r.location}`.toLowerCase().includes(ql)));
+}
+export function searchJobs({ sort = 'score', dir = 'desc', limit = 500, offset = 0, ...f } = {}) {
+  const rows = filterJobs(f);
+  const d = dir === 'asc' ? 1 : -1;
+  rows.sort((a, b) => { const va = a[sort], vb = b[sort]; return (typeof va === 'string' ? va.localeCompare(vb) : (va || 0) - (vb || 0)) * d; });
+  return { total: rows.length, rows: rows.slice(offset, offset + limit) };
+}
+/**
+ * Counts per filter value under the current filters, each dimension counted with its own filter lifted, so a
+ * picker shows what choosing each value would give rather than only what is already chosen. Pay comes back as
+ * a spread of the stated tops of range, for setting the pay fields with the eyes open.
+ */
+export function jobFacets(f = {}) {
+  const count = (rows, key) => rows.reduce((a, r) => { const k = key(r); if (k) a[k] = (a[k] || 0) + 1; return a; }, {});
+  const without = (...dims) => filterJobs(Object.fromEntries([...Object.entries(f), ...dims.map((d) => [d, undefined])]));
+  const sourceRows = without('source');
+  const source = count(sourceRows, (r) => r.source);
+  const link = sourceRows.filter((r) => r.addedBy === 'link').length;
+  if (link) source.link = link;
+  const remoteRows = without('remoteOnly');
+  const payRows = without('payMin', 'payMax', 'payKnown');
+  const tops = payRows.map((r) => r.salaryMax).filter((n) => n > 0).sort((a, b) => a - b);
+  return {
+    total: filterJobs(f).length,
+    status: count(without('status'), (r) => r.status),
+    band: count(without('band'), (r) => r.payBand),
+    kind: count(without('kind'), (r) => r.kind),
+    source,
+    company: count(without('company'), (r) => r.company),
+    remote: { remote: remoteRows.filter(isRemoteRow).length, onsite: remoteRows.filter((r) => !isRemoteRow(r)).length },
+    pay: { stated: tops.length, unstated: payRows.length - tops.length, min: tops[0] || 0, max: tops[tops.length - 1] || 0, median: tops[Math.floor(tops.length / 2)] || 0 },
+  };
+}
+/** The same filters, read off a query string (the API) so the two routes and the UI agree on names. */
+export function filtersFromParams(q) {
+  const g = (k) => q.get(k) ?? undefined;
+  return { q: g('q') || '', location: g('location') || '', status: g('status'), band: g('band'), kind: g('kind'), source: g('source'), company: g('company'), minScore: g('minScore'), maxScore: g('maxScore'), payMin: g('payMin'), payMax: g('payMax'), payKnown: g('payKnown') === '1', postedDays: g('postedDays'), foundDays: g('foundDays'), remoteOnly: g('remote') === '1', openOnly: g('closed') !== '1' };
+}
+function notePath(id) {
+  const safe = path.basename(String(id)).replace(/\.md$/, '');
+  const file = path.join(P.jobs, safe + '.md');
+  if (!fs.existsSync(file)) throw Object.assign(new Error(`No job note named "${safe}"`), { status: 404 });
+  return file;
+}
+/**
+ * The heading a note keeps the reader's own notes under.
+ *
+ * New notes are written with "Notes". Notes written before the heading was generalised say "Tek's notes",
+ * and are not rewritten: an existing note is the person's record, and a migration that touches every file to
+ * change one line is a worse trade than reading both. Whichever heading a note already has is the one it
+ * keeps; only a note that has neither gets the current default.
+ */
+const NOTES_HEADING = 'Notes';
+const LEGACY_NOTES_HEADING = "Tek's notes";
+function notesHeading(text) {
+  if (new RegExp(`^## ${NOTES_HEADING}[ \\t]*$`, 'm').test(text)) return NOTES_HEADING;
+  if (new RegExp(`^## ${LEGACY_NOTES_HEADING}[ \\t]*$`, 'm').test(text)) return LEGACY_NOTES_HEADING;
+  return NOTES_HEADING;
+}
+
+export function getJob(id) {
+  const file = notePath(id);
+  const text = fs.readFileSync(file, 'utf8');
+  const fm = readFrontmatter(file);
+  const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+  // A section runs to the next "## " heading or the true end of the note (not the end of a line: `$` is per-line under /m).
+  const section = (h) => { const m = body.match(new RegExp(`^## ${h}\\s*\\n([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm')); return m ? m[1].trim() : ''; };
+  // Where the note is, and a link Obsidian opens it from; `path=` works whatever the vault is called.
+  return { ...rowOf(fm), path: file, obsidianUrl: `obsidian://open?path=${encodeURIComponent(file)}`, body, sections: { why: section("Why it matched"), log: section('Status log'), notes: section(notesHeading(text)), application: section('Application'), coverLetter: section('Cover letter').replace(/^>.*\r?\n?/gm, '').trim(), description: section('Job description'), people: section('People') } };
+}
+export function replaceFrontmatterLine(text, key, value) {
+  const re = new RegExp(`^${key}: .*$`, 'm');
+  return re.test(text) ? text.replace(re, `${key}: ${value}`) : text.replace(/^---\r?\n/, `---\n${key}: ${value}\n`);
+}
+export function appendUnderHeading(text, heading, line) {
+  // `[ \t]*\n` rather than `\s*\n`: a greedy \s would swallow the blank lines after the heading into the heading group.
+  const re = new RegExp(`(^## ${heading}[ \\t]*\\n)([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm');
+  if (!re.test(text)) return text.trimEnd() + `\n\n## ${heading}\n${line}\n`;
+  return text.replace(re, (all, h, content) => { const body = content.trim(); return `${h}${body ? body + '\n' : ''}${line}\n\n`; });
+}
+/**
+ * Why a match was passed on. Recorded so the criteria can be argued with later from evidence rather than
+ * memory — a pass with no reason teaches nothing, and after three hundred of them the record is the only
+ * thing that can say which rule is wrong.
+ */
+export const PASS_REASONS = ['wrong role shape', 'weak evidence match', 'compensation', 'location or authorisation', 'too managerial', 'too visual', 'too engineering', 'stale or duplicate', 'company'];
+
+/**
+ * Statuses an agent may not set, and why.
+ *
+ * `applied` is not a preference, it is a claim that something was sent to another person. Nothing in this
+ * system can send an application, so nothing in it can truthfully record one — only the person who did it
+ * knows. An agent that drafts a packet moves it to `ready` and stops there; the human moves it on.
+ * `interviewing` and `offer` are the same kind of claim, about events outside this machine entirely.
+ */
+const HUMAN_ONLY_STATUSES = ['applied', 'interviewing', 'offer'];
+
+export function setStatus(id, status, via = 'app', reason = '') {
+  if (!STATUSES.includes(status)) throw Object.assign(new Error(`status must be one of ${STATUSES.join(', ')}`), { status: 400 });
+  if (reason && !PASS_REASONS.includes(reason)) throw Object.assign(new Error(`reason must be one of ${PASS_REASONS.join(', ')}`), { status: 400 });
+  if (via === 'mcp' && HUMAN_ONLY_STATUSES.includes(status)) {
+    throw Object.assign(new Error(`"${status}" records something that happened outside this machine, so only a person can set it. Move the packet to "ready" and ask them.`), { status: 403 });
+  }
+  const file = notePath(id);
+  let text = fs.readFileSync(file, 'utf8');
+  const before = (text.match(/^status: (.*)$/m) || [])[1] || 'new';
+  if (before === status) return getJob(id);
+  text = replaceFrontmatterLine(text, 'status', status);
+  if (reason) text = replaceFrontmatterLine(text, 'passed_reason', JSON.stringify(reason));
+  text = appendUnderHeading(text, 'Status log', `- ${isoDay()} — ${before} → **${status}**${reason ? ` (${reason})` : ''} (via ${via})`);
+  fs.writeFileSync(file, text);
+  cache.key = '';
+  return getJob(id);
+}
+export function addNote(id, note, via = 'app') {
+  const file = notePath(id);
+  let text = fs.readFileSync(file, 'utf8');
+  text = appendUnderHeading(text, notesHeading(text), `- ${isoDay()} (${via}): ${String(note).trim()}`);
+  fs.writeFileSync(file, text);
+  return getJob(id);
+}
+/**
+ * The application packet: what has to exist before a person can decide whether to send something.
+ *
+ * `required` is the subset that has to be filled before the packet counts as ready for a human to approve.
+ * The rest are useful and often empty — not every application needs a referral or an outreach message, and
+ * a checklist that demands them teaches people to fill boxes rather than to think.
+ *
+ * The first six are the fields the note template has always had; the rest were added with the packet, and
+ * are appended to a note's Application section the first time they are saved. Nothing is rewritten.
+ */
+export const APPLICATION_FIELDS = [
+  { field: 'Narrative', hint: 'Which story leads: design engineer, or AI systems.', required: true },
+  { field: 'Resume variant', hint: 'Which base resume this starts from.', required: true },
+  { field: 'Tailored summary', hint: 'The opening paragraph, rewritten for this posting.', required: true },
+  { field: 'Tailored bullets', hint: 'The three or four bullets that answer this posting’s requirements.', required: true },
+  { field: 'Portfolio', hint: 'Which projects to feature, and why these.', required: false },
+  { field: 'Cover letter', hint: 'Optional. Only where it is read.', required: false },
+  { field: 'Questions', hint: 'The posting’s own questions, with answers you have verified.', required: false },
+  { field: 'Risks', hint: 'Gaps a reader will notice, and what to say about them.', required: true },
+  { field: 'Outreach message', hint: 'To a recruiter or a referral, if there is one.', required: false },
+  { field: 'Contact / referral', hint: 'Who, and how you know them.', required: false },
+  { field: 'Deadline', hint: 'When this closes, if it says.', required: false },
+  { field: 'Applied on', hint: 'Filled when you actually send it.', required: false },
+  { field: 'Follow-up due', hint: 'When to chase, if nothing comes back.', required: false },
+];
+const FIELD_NAMES = APPLICATION_FIELDS.map((f) => f.field);
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export function saveApplicationDraft(id, { field, value }) {
+  if (!FIELD_NAMES.includes(field)) throw Object.assign(new Error(`field must be one of ${FIELD_NAMES.join(', ')}`), { status: 400 });
+  const file = notePath(id);
+  let text = fs.readFileSync(file, 'utf8');
+  const re = new RegExp(`^- \\*\\*${escapeRe(field)}:\\*\\*.*$`, 'm');
+  // Newlines are flattened: the Application section is a list, and a multi-line value would break the
+  // next field out of it. Long prose belongs in the note body, and the packet points at it.
+  const line = `- **${field}:** ${String(value).replace(/\r?\n/g, ' ').trim()}`;
+  text = re.test(text) ? text.replace(re, line) : appendUnderHeading(text, 'Application', line);
+  fs.writeFileSync(file, text);
+  cache.key = '';
+  return getJob(id);
+}
+
+/**
+ * Long drafts (the cover letter, the tailored resume) live in the note body under their own headings, not in
+ * the Application list: that list is one line per field, and these are paragraphs. The packet field points
+ * at the section. Sections are placed before "## Job description" so the person's material stays above the
+ * posting's. Function replacements throughout: a draft can contain "$" and String.replace reads "$&".
+ */
+const sectionRe = (heading) => new RegExp(`^## ${heading}[ \\t]*\\n([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm');
+export function getSection(id, heading) {
+  const m = fs.readFileSync(notePath(id), 'utf8').match(sectionRe(heading));
+  return m ? m[1].replace(/^>.*\r?\n?/gm, '').trim() : '';
+}
+export function saveSection(id, heading, body, banner) {
+  const file = notePath(id);
+  let text = fs.readFileSync(file, 'utf8');
+  const block = `## ${heading}\n> ${banner}\n\n${String(body).trim()}\n\n`;
+  if (sectionRe(heading).test(text)) text = text.replace(sectionRe(heading), () => block);
+  else if (/^## Job description[ \t]*$/m.test(text)) text = text.replace(/^## Job description[ \t]*$/m, () => `${block}## Job description`);
+  else text = `${text.trimEnd()}\n\n${block}`;
+  fs.writeFileSync(file, text);
+  cache.key = '';
+  return getSection(id, heading);
+}
+export { isoDay };
+
+const LETTER_HEADING = 'Cover letter';
+export function getCoverLetter(id) { return getSection(id, LETTER_HEADING); }
+export function saveCoverLetter(id, letter, via = 'app') {
+  const words = String(letter).trim().split(/\s+/).length;
+  saveSection(id, LETTER_HEADING, letter, `Drafted ${isoDay()} (via ${via}), ${words} words. A draft: read it, edit it, send it yourself.`);
+  saveApplicationDraft(id, { field: 'Cover letter', value: `Drafted ${isoDay()}, ${words} words. Full text under "Cover letter" in this note.` });
+  return getCoverLetter(id);
+}
+
+/**
+ * The packet as structured data, plus what it is still missing.
+ *
+ * `ready` says only that every required field has something in it. It is not a judgement that the
+ * application is good, and nothing in this codebase treats it as permission to send anything.
+ */
+export function applicationPacket(id) {
+  const text = fs.readFileSync(notePath(id), 'utf8');
+  const values = {};
+  for (const { field } of APPLICATION_FIELDS) {
+    const m = text.match(new RegExp(`^- \\*\\*${escapeRe(field)}:\\*\\*(.*)$`, 'm'));
+    values[field] = m ? m[1].trim() : '';
+  }
+  const missing = APPLICATION_FIELDS.filter((f) => f.required && !values[f.field]).map((f) => f.field);
+  const filled = FIELD_NAMES.filter((f) => values[f]).length;
+  return { id, fields: APPLICATION_FIELDS, values, missing, ready: missing.length === 0, filled, total: FIELD_NAMES.length };
+}
+
+// ---------- summary & runs ----------
+export function runs() {
+  if (!fs.existsSync(P.logs)) return [];
+  return fs.readdirSync(P.logs).filter((f) => f.endsWith('.md')).sort().reverse().slice(0, 30).map((f) => {
+    const text = fs.readFileSync(path.join(P.logs, f), 'utf8');
+    const blocks = [...text.matchAll(/^## Run (.+?)\n([\s\S]*?)(?=^## Run |(?![\s\S]))/gm)].map((m) => {
+      const b = m[2];
+      const g = (re) => (b.match(re) || [])[1];
+      const head = m[1].trim();
+      const boardsOk = Number(g(/Boards: (\d+)\//)), boardsTotal = Number(g(/Boards: \d+\/(\d+)/));
+      // Feeds that failed are their own lines: "- Himalayas: failed: HTTP 503".
+      const feedsFailed = [...b.matchAll(/^- (.+?): failed: (.+)$/gm)].map((x) => `${x[1]} (${x[2]})`);
+      const dry = /\(dry\)/.test(head);
+      // Success: every board answered and every feed too. Partial: some did not. Failed: no board answered,
+      // which is a network or a broken install, not a bad slug.
+      const outcome = boardsTotal > 0 && boardsOk === 0 ? 'failed' : boardsOk === boardsTotal && feedsFailed.length === 0 ? 'success' : 'partial';
+      return { when: head.replace(/\s*\(dry\)\s*$/, ''), dry, via: g(/^- Via: (.+)$/m) || '', outcome, boardsOk, boardsTotal, scanned: Number((g(/postings scanned: ([\d,]+)/) || '0').replace(/,/g, '')), matched: Number(g(/scored ≥ \d+: (\d+)/)), newMatches: Number(g(/\*\*new: (\d+)\*\*/)), closed: Number(g(/closed: (\d+)/)), seconds: Number(g(/([\d.]+)s/)), failed: g(/Failed slugs: (.+)/) || '', feedsFailed, criteria: g(/^- Criteria: (.+)$/m) || '' };
+    });
+    return { date: f.replace(/\.md$/, ''), runs: blocks };
+  });
+}
+export function summary() {
+  const rows = listJobs().filter((r) => r.listing === 'open');
+  const count = (k) => rows.reduce((m, r) => ((m[r[k]] = (m[r[k]] || 0) + 1), m), {});
+  const de = rows.filter((r) => r.kind === 'design-eng');
+  const lastLog = runs()[0]; const last = lastLog?.runs?.at(-1) || null;
+  const criteria = safe(() => loadCriteria(), {});
+  return {
+    open: rows.length, byStatus: count('status'), byBand: count('payBand'), byKind: count('kind'), bySource: count('source'),
+    designEng: { total: de.length, floor: de.filter((r) => r.payBand === 'floor').length, stretch: de.filter((r) => r.payBand === 'stretch').length, unknown: de.filter((r) => r.payBand === 'unknown').length },
+    active: rows.filter((r) => ['applying', 'applied', 'interviewing', 'offer'].includes(r.status)).length,
+    lastRun: last ? { ...last, date: lastLog.date } : null,
+    floor: criteria.salary?.minAnnual || null, stretch: criteria.salary?.stretchAnnual || null, minScore: criteria.minScore || null,
+    ceiling: fitCeiling(criteria),
+    companies: safe(() => loadCompanies().length, 0), vault: VAULT,
+  };
+}
+const safe = (fn, d) => { try { return fn(); } catch { return d; } };
+
+// ---------- today ----------
+
+/**
+ * The best score this criteria set can produce, used to turn the raw score into a 0-100 fit.
+ *
+ * The raw score is additive and unbounded, which is right for ranking and useless for judging: "125" means
+ * nothing without knowing what was available. This computes the ceiling from the criteria themselves.
+ *
+ * One assumption, stated because it is arguable: scoreJob pays 5 points for every title term beyond the
+ * first, with no cap, so the theoretical maximum is however many terms the profile has. A real posting hits
+ * two or three, so the ceiling allows for three. A job that somehow hits more simply reads as 100.
+ */
+export function fitCeiling(c = {}) {
+  const top = (o) => Math.max(0, ...Object.values(o || {}).map(Number).filter(Number.isFinite));
+  return Math.max(1, Math.round(
+    // Every point the scorer can award: the top title term plus the capped extras, the top seniority boost, the
+    // description cap, the location boosts, the pay bonus plus the capped above-floor points, the freshest recency.
+    top(c.titleTerms) + (c.titleExtraCap ?? 10) +
+    top(c.seniority?.boost) +
+    (c.descCap ?? 35) +
+    (c.location?.remoteBoost ?? 0) + (c.location?.bayAreaBoost ?? 0) +
+    (c.salary?.meetsBonus ?? 10) + (c.salary?.aboveCap ?? 0) +
+    Math.max(c.recency?.days2 ?? 0, c.recency?.days7 ?? 0, c.recency?.days30 ?? 0),
+  ));
+}
+const toFit = (raw, ceiling) => Math.max(0, Math.min(100, Math.round((Number(raw) || 0) / ceiling * 100)));
+
+/** The `- **Follow-up due:**` line from a note's Application section, or ''. Only worth reading for the few
+ *  jobs actually in flight, so it is never called across the whole vault. */
+function applicationField(id, label) {
+  try {
+    const text = fs.readFileSync(notePath(id), 'utf8');
+    const esc = label.replace(/[.*+?^${}()|[\]\\\/]/g, '\\$&');
+    const m = text.match(new RegExp(`^- \\*\\*${esc}:\\*\\*(.*)$`, 'm'));
+    return m ? m[1].trim() : '';
+  } catch { return ''; }
+}
+
+const IN_FLIGHT = ['applying', 'applied', 'interviewing', 'offer'];
+
+/** The lines under a job note's "## People": "- [[People/Jane Doe (Vanta)|Jane Doe]] · recruiter · jane@x.com · context". */
+export const PERSON_ROLES = ['recruiter', 'hiring-manager', 'interviewer', 'referral', 'other'];
+export function parsePeopleLines(section = '') {
+  return String(section).split('\n').map((l) => l.trim()).filter((l) => l.startsWith('- ')).map((l) => {
+    const link = l.match(/\[\[People\/([^\]|]+)(?:\|([^\]]*))?\]\]/);
+    const rest = l.replace(/^- /, '').replace(/\[\[[^\]]*\]\]/, '').split('·').map((s) => s.trim()).filter(Boolean);
+    // A hand-written line has no link, so its first part is the name.
+    const name = link ? (link[2] || link[1]).trim() : rest[0] || '';
+    const parts = link ? rest : rest.slice(1);
+    const email = parts.find((s) => s.includes('@')) || '';
+    const role = parts.find((s) => PERSON_ROLES.includes(s)) || '';
+    const context = parts.filter((s) => s !== email && s !== role).join(' · ');
+    return { id: link ? link[1].trim() : '', name, role, email, context };
+  }).filter((p) => p.name);
+}
+/** Who to write to about a note: the recruiter if one is named, else the hiring manager, else whoever is first. */
+function contactOf(text) {
+  const all = parsePeopleLines((text.match(/^## People\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/m) || [, ''])[1]);
+  const pick = all.find((p) => p.role === 'recruiter') || all.find((p) => p.role === 'hiring-manager') || all[0] || null;
+  return pick ? { id: pick.id, name: pick.name, email: pick.email, role: pick.role, others: all.length - 1 } : null;
+}
+/** When an application went out: the packet's Applied on, else the status log's move to applied. */
+function appliedOnOf(text) {
+  return (text.match(/^- \*\*Applied on:\*\*\s*(\d{4}-\d{2}-\d{2})/m) || [])[1] || (text.match(/^- (\d{4}-\d{2}-\d{2}) — .*?→ \*\*applied\*\*/m) || [])[1] || '';
+}
+
+/**
+ * The short list of things that actually want a decision today, as opposed to the whole inventory.
+ *
+ * Measured on this vault before it was written: every listing that closed did so within seven days of being
+ * found, median two. So an unreviewed match is a perishable thing, and the section that matters most is not
+ * the ranked pile but the one about to disappear.
+ *
+ * Sections three to five read the pipeline, which is empty until the pipeline is used. They return empty
+ * arrays rather than being hidden, so the page shows the shape of the work even before there is any.
+ */
+export function today({ cap = 7, agingDays = 2, waitingDays = 14 } = {}) {
+  const rows = listJobs();
+  const criteria = safe(() => loadCriteria(), {});
+  const ceiling = fitCeiling(criteria);
+  const withFit = (r) => ({ ...r, fit: toFit(r.score, ceiling) });
+  const daysSince = (d) => (d ? Math.floor((Date.now() - Date.parse(d)) / 864e5) : null);
+
+  const open = rows.filter((r) => r.listing === 'open');
+  const unreviewed = open.filter((r) => r.status === 'new');
+
+  const triage = [...unreviewed].sort((a, b) => b.score - a.score).slice(0, cap).map(withFit);
+  const triageIds = new Set(triage.map((r) => r.id));
+
+  // Still open, still untouched, and already past the age at which listings here start disappearing.
+  const aging = unreviewed
+    .filter((r) => !triageIds.has(r.id) && (daysSince(r.found) ?? 0) >= agingDays)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, cap)
+    .map((r) => ({ ...withFit(r), days: daysSince(r.found) }));
+
+  // Closed while it was still sitting in the inbox: the cost of not having looked, made visible.
+  const missedAll = rows
+    .filter((r) => r.status === 'new' && r.listing.startsWith('closed') && (daysSince(r.listing.replace('closed ', '')) ?? 99) <= 7)
+    .sort((a, b) => b.score - a.score);
+  const missed = missedAll.slice(0, cap).map((r) => ({ ...withFit(r), closed: r.listing.replace('closed ', '') }));
+
+  // Work already invested, wherever it ranks. A packet is the most expensive thing on this page — a drafted
+  // summary, a named contact — and the fit score knows nothing about it, so a role can be half-prepared and
+  // still fall off the bottom of the queue. Terminal statuses drop out; a closed listing does not, because a
+  // packet on a job that just closed is the one thing here you want to hear about immediately.
+  const DONE = ['applied', 'offer', 'rejected', 'passed'];
+  const started = rows
+    .filter((r) => r.packet > 0 && !DONE.includes(r.status) && !triageIds.has(r.id))
+    .sort((a, b) => b.packet - a.packet || b.score - a.score)
+    .slice(0, cap)
+    .map((r) => ({ ...withFit(r), packet: r.packet, closed: r.listing.startsWith('closed') ? r.listing.replace('closed ', '') : '' }));
+
+  const inFlight = rows.filter((r) => IN_FLIGHT.includes(r.status));
+  // Whoever is on the thread rides along with every in-flight row, so a nudge names the person to write to.
+  const noteText = (id) => { try { return fs.readFileSync(notePath(id), 'utf8'); } catch { return ''; } };
+  const withContact = (r) => { const text = noteText(r.id); return { ...withFit(r), contact: contactOf(text), appliedOn: appliedOnOf(text) }; };
+  const preparing = inFlight.filter((r) => r.status === 'applying').map((r) => ({ ...withContact(r), since: daysSince(r.found) }));
+  const followUps = inFlight
+    .map((r) => ({ ...withContact(r), due: applicationField(r.id, 'Follow-up due') }))
+    .filter((r) => r.due)
+    .sort((a, b) => a.due.localeCompare(b.due));
+  const interviewing = inFlight.filter((r) => r.status === 'interviewing' || r.status === 'offer').map(withContact);
+  // Applied, nothing back, past the point where silence is the answer unless someone is asked. The row names
+  // the person to ask; a row with no one on it is the nudge to find one.
+  const waitingAll = inFlight.filter((r) => r.status === 'applied').map(withContact).map((r) => ({ ...r, days: daysSince(r.appliedOn) })).filter((r) => r.days !== null && r.days >= waitingDays).sort((a, b) => b.days - a.days);
+  const waiting = waitingAll.slice(0, cap);
+
+  return {
+    generated: new Date().toISOString(),
+    ceiling,
+    // Real totals, not the capped section lengths: the point of the page is that the pile is bigger than the list.
+    counts: { open: open.length, unreviewed: unreviewed.length, inFlight: inFlight.length, closedUnreviewed: missedAll.length, aging: unreviewed.filter((r) => (daysSince(r.found) ?? 0) >= agingDays).length, started: rows.filter((r) => r.packet > 0 && !DONE.includes(r.status)).length, waiting: waitingAll.length, waitingDays },
+    sections: { triage, started, aging, missed, preparing, followUps, interviewing, waiting },
+  };
+}
+
+// ---------- criteria & companies ----------
+const JSON_BLOCK = /```json\s*\n([\s\S]*?)\n```/;
+const replaceJsonBlock = (md, parsed) => md.replace(JSON_BLOCK, () => '```json\n' + JSON.stringify(parsed, null, 2) + '\n```');
+export function getCriteria() {
+  const md = fs.readFileSync(P.criteria, 'utf8');
+  const m = md.match(JSON_BLOCK);
+  const parsed = m ? safe(() => JSON.parse(m[1]), null) : null;
+  return { raw: m ? m[1] : '', parsed, fingerprint: parsed ? weightsFingerprint(parsed) : '', path: P.criteria };
+}
+export function setCriteria(raw) {
+  let parsed; try { parsed = JSON.parse(raw); } catch (e) { throw Object.assign(new Error(`Not valid JSON: ${e.message}`), { status: 400 }); }
+  const md = fs.readFileSync(P.criteria, 'utf8');
+  if (!JSON_BLOCK.test(md)) throw new Error('No ```json block in Search Criteria.md');
+  // The previous version is kept beside the note, once per day: the change history the person can read.
+  const before = P.criteria.replace(/\.md$/, `.before-${isoDay()}.md`);
+  if (!fs.existsSync(before)) fs.copyFileSync(P.criteria, before);
+  fs.writeFileSync(P.criteria, replaceJsonBlock(md, parsed).replace(/^updated: .*$/m, `updated: ${isoDay()}`));
+  return getCriteria();
+}
+
+/**
+ * What a proposed criteria set would do to the notes that exist, before it is saved or scanned with.
+ *
+ * Uses the same three exact components `rescore` uses (title terms, recency at the age the posting had when
+ * it was found, pay), computed with today's rules on both sides so an unchanged set previews as no change.
+ * Description terms, seniority words and location rules take a scan to show, and the result says so. The
+ * bar (minScore) is applied on both sides, so raising it alone still shows who falls out.
+ */
+export function previewCriteria(raw) {
+  let proposed; try { proposed = typeof raw === 'string' ? JSON.parse(raw) : raw; } catch (e) { throw Object.assign(new Error(`Not valid JSON: ${e.message}`), { status: 400 }); }
+  const current = loadCriteria();
+  const exact = (r, c) => {
+    const ageAtScan = r.posted && r.found ? (Date.parse(r.found) - Date.parse(r.posted)) / 864e5 : NaN;
+    return titlePoints(r.title, c, c.titleExtraCap ?? 10) + recencyPoints(ageAtScan, c.recency, true) + payPoints(r.salaryMax, c.salary, true);
+  };
+  const rows = listJobs().filter((r) => r.listing === 'open');
+  const barBefore = Number(current.minScore ?? 0), barAfter = Number(proposed.minScore ?? 0);
+  const scored = rows.map((r) => { const after = Math.round(r.score + exact(r, proposed) - exact(r, current)); return { id: r.id, company: r.company, title: r.title, status: r.status, before: r.score, after, delta: after - r.score }; });
+  const top = (key) => [...scored].sort((a, b) => b[key] - a[key]).slice(0, 20).map((r) => r.id);
+  const topBefore = top('before'), topAfter = top('after');
+  const brief = (r) => ({ id: r.id, company: r.company, title: r.title, status: r.status, before: r.before, after: r.after, delta: r.delta });
+  // Who moves, by role family and by the board that surfaced the job: a change that empties one family or one
+  // source is the kind a person wants to see before saving.
+  const byRow = new Map(rows.map((r) => [r.id, r]));
+  const group = (key) => {
+    const out = {};
+    for (const r of scored) { const k = byRow.get(r.id)?.[key] || 'unknown'; const g = out[k] ||= { key: k, notes: 0, aboveBefore: 0, aboveAfter: 0, changed: 0 }; g.notes++; if (r.before >= barBefore) g.aboveBefore++; if (r.after >= barAfter) g.aboveAfter++; if (r.delta !== 0) g.changed++; }
+    return Object.values(out).sort((x, y) => y.notes - x.notes);
+  };
+  const fingerprintBefore = weightsFingerprint(current), fingerprintAfter = weightsFingerprint(proposed);
+  return {
+    fingerprintBefore, fingerprintAfter,
+    weightsChange: fingerprintBefore !== fingerprintAfter,
+    notesAtCurrent: rows.filter((r) => r.weights === fingerprintBefore).length,
+    byKind: group('kind'),
+    bySource: group('source').slice(0, 8),
+    openNotes: rows.length,
+    changed: scored.filter((r) => r.delta !== 0).length,
+    barBefore, barAfter,
+    aboveBefore: scored.filter((r) => r.before >= barBefore).length,
+    aboveAfter: scored.filter((r) => r.after >= barAfter).length,
+    rise: scored.filter((r) => r.before < barBefore && r.after >= barAfter).sort((a, b) => b.after - a.after).slice(0, 25).map(brief),
+    fall: scored.filter((r) => r.before >= barBefore && r.after < barAfter).sort((a, b) => b.before - a.before).slice(0, 25).map(brief),
+    enterTop20: topAfter.filter((id) => !topBefore.includes(id)).map((id) => brief(scored.find((r) => r.id === id))),
+    leaveTop20: topBefore.filter((id) => !topAfter.includes(id)).map((id) => brief(scored.find((r) => r.id === id))),
+    up: [...scored].filter((r) => r.delta > 0).sort((a, b) => b.delta - a.delta).slice(0, 10).map(brief),
+    down: [...scored].filter((r) => r.delta < 0).sort((a, b) => a.delta - b.delta).slice(0, 10).map(brief),
+    covers: 'title terms, recency and pay; description terms, seniority words and location rules show only after a scan',
+  };
+}
+
+/** Score every note again under the saved criteria (the CLI's `rescore --full`), from the app. */
+export function rescoreNotes({ dry = false } = {}) {
+  const r = rescoreFull({ dry: !!dry });
+  cache.key = '';
+  return { total: r.total, considered: r.considered, alreadyCurrent: r.alreadyCurrent, changed: r.changed, fingerprint: r.fingerprint, dry: !!dry, sample: (r.changes || []).slice(0, 10) };
+}
+
+// ---------- outcomes ----------
+// What the search is producing, from the notes: how far each job got, when it was applied to, and whether
+// anything came back. Dates come from the status log lines the app and the MCP write ("2026-09-21 — new →
+// **applied**"), from the packet's "Applied on" field when a person filled it, and from `found:`.
+const RANK = { new: 0, reviewing: 1, applying: 2, ready: 3, applied: 4, interviewing: 5, offer: 6 };
+const median = (xs) => { const s = [...xs].sort((a, b) => a - b); return s.length ? s[Math.floor(s.length / 2)] : null; };
+const dayDiff = (a, b) => Math.round((Date.parse(b) - Date.parse(a)) / 864e5);
+export function outcomes({ agingDays = [7, 14, 21] } = {}) {
+  const today = isoDay();
+  const files = fs.existsSync(P.jobs) ? fs.readdirSync(P.jobs).filter((f) => f.endsWith('.md')) : [];
+  const jobs = files.map((f) => {
+    const text = fs.readFileSync(path.join(P.jobs, f), 'utf8');
+    const fm = readFrontmatter(path.join(P.jobs, f)) || {};
+    const moves = [...text.matchAll(/^- (\d{4}-\d{2}-\d{2}) — .*?→ \*\*([a-z]+)\*\*/gm)].map((m) => ({ date: m[1], to: m[2] }));
+    const reached = (s) => (RANK[fm.status] ?? -1) >= RANK[s] || moves.some((m) => (RANK[m.to] ?? -1) >= RANK[s]);
+    const appliedOn = (text.match(/^- \*\*Applied on:\*\*\s*(\d{4}-\d{2}-\d{2})/m) || [])[1] || moves.find((m) => m.to === 'applied')?.date || (fm.status === 'applied' ? fm.found : '') || '';
+    const applied = reached('applied') || !!appliedOn || (fm.status === 'rejected' && moves.some((m) => m.to === 'applied'));
+    const responded = applied && (reached('interviewing') || fm.status === 'rejected');
+    const inFlight = fm.status === 'applied' || fm.status === 'interviewing';
+    const followUpDue = inFlight ? ((text.match(/^- \*\*Follow-up due:\*\*\s*(\d{4}-\d{2}-\d{2})/m) || [])[1] || '') : '';
+    return { id: fm._name, company: fm.company || '', title: fm.title || '', source: fm.source || '', kind: DE.test(fm.title || '') ? 'design-eng' : 'adjacent', status: fm.status || 'new', found: fm.found || '', appliedOn, followUpDue, reviewed: fm.status !== 'new', shortlisted: reached('reviewing') || fm.status === 'applying' || fm.status === 'ready', applied, interviewing: reached('interviewing'), offer: reached('offer'), responded };
+  });
+  const appliedJobs = jobs.filter((j) => j.applied);
+  const waiting = appliedJobs.filter((j) => j.status === 'applied' && j.appliedOn).map((j) => ({ ...j, days: dayDiff(j.appliedOn, today) })).sort((a, b) => b.days - a.days);
+  const bySource = {};
+  for (const j of appliedJobs) { const s = bySource[j.source] ||= { source: j.source, applied: 0, responded: 0 }; s.applied++; if (j.responded) s.responded++; }
+  const weekOf = (d) => { const x = new Date(d); const day = (x.getUTCDay() + 6) % 7; x.setUTCDate(x.getUTCDate() - day); return x.toISOString().slice(0, 10); };
+  const perWeek = {};
+  for (const j of appliedJobs) if (j.appliedOn) perWeek[weekOf(j.appliedOn)] = (perWeek[weekOf(j.appliedOn)] || 0) + 1;
+  // The funnel as stages, each with its share of the stage before, so "62% of what you shortlist gets applied to"
+  // is a number on the page rather than arithmetic the person does in their head.
+  const counts = [['found', jobs.length], ['reviewed', jobs.filter((j) => j.reviewed).length], ['shortlisted', jobs.filter((j) => j.shortlisted).length], ['applied', appliedJobs.length], ['interviewing', jobs.filter((j) => j.interviewing).length], ['offer', jobs.filter((j) => j.offer).length]];
+  const stages = counts.map(([stage, count], i) => ({ stage, count, rate: i === 0 ? null : counts[i - 1][1] ? count / counts[i - 1][1] : null }));
+  const byKind = ['design-eng', 'adjacent'].map((kind) => { const k = jobs.filter((j) => j.kind === kind); const ka = k.filter((j) => j.applied); return { kind, found: k.length, applied: ka.length, responded: ka.filter((j) => j.responded).length, interviewing: k.filter((j) => j.interviewing).length }; });
+  // What needs a hand this week: follow-ups due within seven days or already past, and the interviews in progress.
+  const followUps = jobs.filter((j) => j.followUpDue && dayDiff(today, j.followUpDue) <= 7).map((j) => ({ id: j.id, company: j.company, title: j.title, due: j.followUpDue, inDays: dayDiff(today, j.followUpDue) })).sort((x, y) => x.inDays - y.inDays);
+  const interviewing = jobs.filter((j) => j.status === 'interviewing').map((j) => ({ id: j.id, company: j.company, title: j.title }));
+  return {
+    stages, byKind, thisWeek: { followUps: followUps.slice(0, 8), interviewing: interviewing.slice(0, 8) },
+    funnel: { found: jobs.length, reviewed: jobs.filter((j) => j.reviewed).length, shortlisted: jobs.filter((j) => j.shortlisted).length, applied: appliedJobs.length, interviewing: jobs.filter((j) => j.interviewing).length, offer: jobs.filter((j) => j.offer).length },
+    responded: appliedJobs.filter((j) => j.responded).length,
+    responseRate: appliedJobs.length ? appliedJobs.filter((j) => j.responded).length / appliedJobs.length : null,
+    // A note created after the fact (from an email) was "found" after it was applied to; that is not a discovery time.
+    medianDaysToApply: median(appliedJobs.filter((j) => j.appliedOn && j.found && j.appliedOn >= j.found).map((j) => dayDiff(j.found, j.appliedOn))),
+    waiting: { total: waiting.length, buckets: Object.fromEntries(agingDays.map((d) => [d, waiting.filter((w) => w.days >= d).length])), oldest: waiting.slice(0, 8).map(({ id, company, title, appliedOn, days, source }) => ({ id, company, title, appliedOn, days, source })) },
+    bySource: Object.values(bySource).map((s) => ({ ...s, rate: s.applied ? s.responded / s.applied : 0 })).sort((a, b) => b.applied - a.applied).slice(0, 8),
+    appliedPerWeek: Object.entries(perWeek).sort().slice(-8).map(([week, n]) => ({ week, n })),
+    passed: jobs.filter((j) => j.status === 'passed').length,
+    rejected: jobs.filter((j) => j.status === 'rejected').length,
+  };
+}
+
+// ---------- settings ----------
+// The few things that live outside the profile folder because they say where it is: ~/.tekjobs/config.json.
+// The profile folder itself is read once at start (every module holds its paths), so changing it here takes a
+// server restart; the other settings are read when used.
+function readConfigFile() { try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; } }
+function writeConfigFile(patch) {
+  fs.mkdirSync(HOME_DIR, { recursive: true });
+  const next = { ...readConfigFile(), ...patch };
+  for (const k of Object.keys(next)) if (next[k] === '' || next[k] === null || next[k] === undefined) delete next[k];
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2));
+  return next;
+}
+export function resumeDir() {
+  const cfg = readConfigFile();
+  return cfg.resumeDir ? path.resolve(cfg.resumeDir) : path.join(VAULT, 'Templates', 'Resume');
+}
+export function settings() {
+  const cfg = readConfigFile();
+  return {
+    configFile: CONFIG_FILE,
+    profile: { active: VAULT, configured: cfg.profile || '', fromEnv: !!(process.env.TEKJOBS_PROFILE || process.env.TEKJOBS_VAULT), exists: fs.existsSync(VAULT) },
+    resumeDir: { path: resumeDir(), configured: cfg.resumeDir || '', exists: fs.existsSync(resumeDir()) },
+    resumeSource: cfg.resumeSource || '',
+    llm: { command: cfg.llm?.command || 'claude', args: (cfg.llm?.args || ['-p', '--output-format', 'text']).join(' '), configured: !!cfg.llm },
+    contact: cfg.contact || '',
+  };
+}
+export function saveSettings({ profile, resumeDir: rd, llmCommand, llmArgs, contact } = {}) {
+  const patch = {};
+  let restart = false;
+  if (profile !== undefined) {
+    const dir = String(profile).trim();
+    if (dir) {
+      const abs = path.resolve(dir);
+      if (!fs.existsSync(abs)) throw Object.assign(new Error(`${abs} does not exist. Create the folder first, or run tekjobs init <dir> to start a new profile there.`), { status: 400 });
+      if (!fs.statSync(abs).isDirectory()) throw Object.assign(new Error(`${abs} is not a folder.`), { status: 400 });
+      patch.profile = abs;
+      restart = abs !== VAULT;
+    } else patch.profile = '';
+  }
+  if (rd !== undefined) {
+    const dir = String(rd).trim();
+    if (dir && !fs.existsSync(path.resolve(dir))) throw Object.assign(new Error(`${path.resolve(dir)} does not exist.`), { status: 400 });
+    patch.resumeDir = dir ? path.resolve(dir) : '';
+  }
+  if (llmCommand !== undefined || llmArgs !== undefined) {
+    const command = String(llmCommand ?? 'claude').trim() || 'claude';
+    const args = String(llmArgs ?? '').split(/\s+/).filter(Boolean);
+    patch.llm = command === 'claude' && args.join(' ') === '-p --output-format text' ? '' : { command, args };
+  }
+  if (contact !== undefined) patch.contact = String(contact).trim();
+  writeConfigFile(patch);
+  return { ...settings(), restart };
+}
+
+// ---------- resume variants ----------
+// A folder of resume files (the master, the design-systems one, the AI one), each usable as the resume of
+// record with one click: `syncResume` reads it into Profile/Resume.md and remembers it as the source.
+const RESUME_EXT = new Set(['.pdf', '.docx', '.md', '.txt']);
+export function listResumes() {
+  const dir = resumeDir();
+  const current = readConfigFile().resumeSource || '';
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => RESUME_EXT.has(path.extname(f).toLowerCase())) : [];
+  const rows = files.map((f) => {
+    const p = path.join(dir, f);
+    const st = fs.statSync(p);
+    return { name: f, path: p, size: st.size, modified: st.mtime.toISOString().slice(0, 10), current: path.resolve(current) === path.resolve(p) };
+  }).sort((a, b) => b.modified.localeCompare(a.modified) || a.name.localeCompare(b.name));
+  return { dir, exists: fs.existsSync(dir), files: rows };
+}
+function resumePath(name) {
+  const p = path.join(resumeDir(), path.basename(String(name)));
+  if (!fs.existsSync(p)) throw Object.assign(new Error(`No resume file named "${name}" in ${resumeDir()}`), { status: 404 });
+  return p;
+}
+export async function useResume(name) {
+  const { syncResume } = await import('../../scraper/resume-sync.mjs');
+  const r = await syncResume({ source: resumePath(name) });
+  return { ...r, files: listResumes().files };
+}
+export function openResume(name) {
+  const file = resumePath(name);
+  const [bin, args] = process.platform === 'win32' ? ['explorer', [file]] : process.platform === 'darwin' ? ['open', [file]] : ['xdg-open', [file]];
+  spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
+  return { ok: true, path: file };
+}
+
+// ---------- snippets ----------
+// The copy panel: the lines applications keep asking for (email, phone, links, availability, the salary
+// answer), kept in Profile/Snippets.md as a json block so they are the person's to edit, here or in Obsidian.
+// Until that note exists the panel offers a set read from the profile's Basics, and writes nothing.
+const SNIPPETS_FILE = path.join(VAULT, 'Profile', 'Snippets.md');
+function defaultSnippets() {
+  const text = safe(() => fs.readFileSync(P.profile, 'utf8'), '');
+  const basic = (label) => { const m = text.match(new RegExp(`\\*\\*${label}:\\*\\*\\s*([^\\n·]*)`)); return m ? m[1].replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/\(".*?"\)/g, '').trim() : ''; };
+  const link = (host) => { const m = text.match(new RegExp(`\\((https?://[^)\\s]*${host}[^)\\s]*)\\)`)); return m ? m[1] : ''; };
+  const criteria = safe(() => loadCriteria(), {});
+  const floor = criteria.salary?.minAnnual ? `$${Number(criteria.salary.minAnnual).toLocaleString('en-US')} base` : '';
+  return [
+    { group: 'Identity', label: 'Full name', value: basic('Name').replace(/\s*\(.*\)$/, '') },
+    { group: 'Identity', label: 'Email', value: basic('Email') },
+    { group: 'Identity', label: 'Phone', value: basic('Phone') },
+    { group: 'Identity', label: 'Location', value: basic('Location') },
+    { group: 'Links', label: 'Portfolio', value: link('') && !/linkedin|github/.test(link('')) ? link('') : '' },
+    { group: 'Links', label: 'LinkedIn', value: link('linkedin.com') },
+    { group: 'Links', label: 'GitHub', value: link('github.com') },
+    { group: 'Answers', label: 'Available from', value: basic('Available from') },
+    { group: 'Answers', label: 'Salary expectation', value: floor },
+    { group: 'Answers', label: 'Work authorization', value: '' },
+    { group: 'Answers', label: 'Remote', value: 'Remote only.' },
+  ].filter((s) => s.label);
+}
+export function getSnippets() {
+  const exists = fs.existsSync(SNIPPETS_FILE);
+  if (!exists) return { items: defaultSnippets(), exists, path: SNIPPETS_FILE };
+  const m = fs.readFileSync(SNIPPETS_FILE, 'utf8').match(JSON_BLOCK);
+  const items = m ? safe(() => JSON.parse(m[1]), []) : [];
+  return { items: Array.isArray(items) ? items.filter((s) => s && typeof s === 'object').map((s) => ({ group: String(s.group || ''), label: String(s.label || ''), value: String(s.value ?? '') })) : [], exists, path: SNIPPETS_FILE };
+}
+export function saveSnippets(list) {
+  if (!Array.isArray(list)) throw Object.assign(new Error('snippets must be a list'), { status: 400 });
+  const items = list.map((s) => ({ group: String(s?.group || '').trim(), label: String(s?.label || '').trim(), value: String(s?.value ?? '') })).filter((s) => s.label);
+  fs.mkdirSync(path.dirname(SNIPPETS_FILE), { recursive: true });
+  const body = `---\ntype: snippets\nupdated: ${isoDay()}\n---\n# Copy panel\n\nWhat the copy panel in the app offers, one click each. Edit here or in the app; \`group\` is the heading, \`label\` the button, \`value\` what lands on the clipboard. Multi-line values are fine.\n\n\`\`\`json\n${JSON.stringify(items, null, 2)}\n\`\`\`\n`;
+  fs.writeFileSync(SNIPPETS_FILE, body);
+  return getSnippets();
+}
+
+// ---------- criteria presets ----------
+// Named criteria sets under Targets/Criteria/, one note each, same ```json shape as Search Criteria.md.
+// The daily scan uses the active note; a preset is for a different kind of search (a wider net, a different
+// title, a lower floor) that runs on request: from the Runs page, or `tekjobs scan --criteria "<name>"`.
+export function criteriaPresets() {
+  if (!fs.existsSync(P.criteriaDir)) return [];
+  const active = getCriteria().fingerprint;
+  return fs.readdirSync(P.criteriaDir).filter((f) => f.endsWith('.md')).sort().map((f) => {
+    const file = path.join(P.criteriaDir, f);
+    const parsed = safe(() => loadCriteria(file), null);
+    const fingerprint = parsed ? weightsFingerprint(parsed) : '';
+    return { name: f.replace(/\.md$/, ''), file, valid: !!parsed, minScore: parsed?.minScore ?? null, floor: parsed?.salary?.minAnnual ?? null, titles: Object.keys(parsed?.titleTerms || {}).length, fingerprint, active: !!fingerprint && fingerprint === active, updated: fs.statSync(file).mtime.toISOString().slice(0, 10) };
+  });
+}
+export function getCriteriaPreset(name) {
+  const file = criteriaPresetFile(name);
+  if (!fs.existsSync(file)) throw Object.assign(new Error(`No criteria preset named "${name}"`), { status: 404 });
+  const m = fs.readFileSync(file, 'utf8').match(JSON_BLOCK);
+  const parsed = m ? safe(() => JSON.parse(m[1]), null) : null;
+  return { name: path.basename(file, '.md'), file, raw: m ? m[1] : '', parsed, fingerprint: parsed ? weightsFingerprint(parsed) : '' };
+}
+export function saveCriteriaPreset(name, raw) {
+  let parsed; try { parsed = JSON.parse(raw); } catch (e) { throw Object.assign(new Error(`Not valid JSON: ${e.message}`), { status: 400 }); }
+  const file = criteriaPresetFile(name);
+  const clean = path.basename(file, '.md');
+  fs.mkdirSync(P.criteriaDir, { recursive: true });
+  if (fs.existsSync(file)) {
+    const md = fs.readFileSync(file, 'utf8');
+    fs.writeFileSync(file, JSON_BLOCK.test(md) ? replaceJsonBlock(md, parsed).replace(/^updated: .*$/m, `updated: ${isoDay()}`) : `${md.replace(/\n+$/, '')}\n\n\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\`\n`);
+  } else {
+    fs.writeFileSync(file, [
+      '---', 'type: criteria-preset', `updated: ${isoDay()}`, '---',
+      `# ${clean}`, '',
+      `> A criteria set the scan can run with instead of [[Targets/Search Criteria]]. Same JSON shape, same scoring. Load it on the app's Criteria page, make it the active set, or run one scan with it: \`tekjobs scan --criteria "${clean}"\`. Notes written by such a run carry this set's weights fingerprint.`, '',
+      '```json', JSON.stringify(parsed, null, 2), '```', '',
+    ].join('\n'));
+  }
+  return getCriteriaPreset(clean);
+}
+export function deleteCriteriaPreset(name) {
+  const file = criteriaPresetFile(name);
+  if (fs.existsSync(file)) fs.unlinkSync(file);
+  return criteriaPresets();
+}
+/** Copy a preset's JSON into Search Criteria.md, so the daily scan and every other reader use it. */
+export function activateCriteriaPreset(name) {
+  return setCriteria(getCriteriaPreset(name).raw);
+}
+/** The watchlist rows, each with where the board stands: state, last success, last attempt, last error. */
+export function companies() {
+  const h = loadHealth();
+  return loadCompanies().map((c) => {
+    const b = h.boards[`${c.ats}:${c.slug}`] || {};
+    return { ...c, health: { state: healthState(b, c.status), lastAttempt: b.lastAttempt || '', lastOk: b.lastOk || '', lastOkJobs: b.lastOkJobs ?? null, lastError: b.lastError || '', failStreak: b.failStreak || 0 } };
+  });
+}
+
+/** The aggregator feeds: which are on under the criteria's openSources, and how each did last time. */
+export async function feeds() {
+  const { OPEN_SOURCES } = await import('../../scraper/sources-extra.mjs');
+  const open = safe(() => loadCriteria().openSources, {}) || {};
+  const h = loadHealth();
+  const row = (key, label, enabled, needsKey = false) => {
+    const f = h.feeds[label] || {};
+    return { key, label, enabled, needsKey, health: { state: healthState(f, enabled ? '' : 'off'), lastAttempt: f.lastAttempt || '', lastOk: f.lastOk || '', lastOkJobs: f.lastOkJobs ?? null, lastError: f.lastError || '' } };
+  };
+  return [
+    row('remoteok', 'RemoteOK', open.remoteok !== false),
+    row('hn', 'HN Who is hiring', open.hn !== false),
+    ...Object.entries(OPEN_SOURCES).map(([key, def]) => row(key, def.label, def.defaultOn ? open[key] !== false : !!open[key], key === 'adzuna' || key === 'usajobs')),
+  ];
+}
+
+/**
+ * Views the criteria imply, offered before the saved ones: the person's own bar, floor and remote rule turned
+ * into links. They are computed, not stored, so they follow the criteria when it changes.
+ */
+export function defaultViews() {
+  const c = safe(() => loadCriteria(), {}) || {};
+  const floor = Number(c.salary?.minAnnual) || 0;
+  const stretch = Number(c.salary?.stretchAnnual) || 0;
+  const remote = !!c.location?.requireRemote;
+  const k = (n) => `$${Math.round(n / 1000)}k`;
+  const views = [
+    { name: 'Design eng at floor', query: 'kind=design-eng&band=floor', hint: 'design-engineering titles with a stated range at or above your floor' },
+    { name: 'New this week', query: 'status=new&foundDays=7', hint: 'unreviewed, found in the last seven days' },
+  ];
+  if (floor) views.push({ name: `${remote ? 'Remote, ' : ''}${k(floor)}+`, query: `${remote ? 'remote=1&' : ''}payMin=${floor}`, hint: `top of the stated range at least ${k(floor)}${remote ? ', remote' : ''}` });
+  if (stretch && floor) views.push({ name: `Stretch ${k(stretch)} to ${k(floor)}`, query: 'band=stretch', hint: 'stated pay under the floor but above the stretch line' });
+  views.push({ name: 'Waiting on a reply', query: 'status=applied', hint: 'applied, nothing back yet' });
+  views.push({ name: 'Added by me', query: 'source=link,mail', hint: 'notes you added by link or from mail, whatever they scored' });
+  return views;
+}
+
+// ---------- saved views ----------
+// Named filter sets for the Jobs page, kept in the vault like every other setting: Targets/Job Views.md holds
+// a ```json list of { name, query }, where query is the Jobs page's own query string.
+const VIEWS_FILE = path.join(VAULT, 'Targets', 'Job Views.md');
+export function getViews() {
+  if (!fs.existsSync(VIEWS_FILE)) return [];
+  const m = fs.readFileSync(VIEWS_FILE, 'utf8').match(JSON_BLOCK);
+  const list = m ? safe(() => JSON.parse(m[1]), []) : [];
+  return Array.isArray(list) ? list.filter((v) => v && v.name && typeof v.query === 'string') : [];
+}
+export function saveViews(list) {
+  const clean = [].concat(list || []).filter((v) => v && v.name && typeof v.query === 'string').map((v) => ({ name: String(v.name).trim().slice(0, 60), query: String(v.query).replace(/^\?/, '').slice(0, 2000) })).filter((v) => v.name);
+  const body = fs.existsSync(VIEWS_FILE) && JSON_BLOCK.test(fs.readFileSync(VIEWS_FILE, 'utf8'))
+    ? replaceJsonBlock(fs.readFileSync(VIEWS_FILE, 'utf8'), clean).replace(/^updated: .*$/m, `updated: ${isoDay()}`)
+    : ['---', 'type: config', `updated: ${isoDay()}`, '---', '# Job views', '', '> Saved filter sets for the app\'s Jobs page. Each `query` is the page\'s own query string; open one as `/#/jobs?<query>`. The app reads and writes this list; edit it here if you like.', '', '```json', JSON.stringify(clean, null, 2), '```', ''].join('\n');
+  fs.writeFileSync(VIEWS_FILE, body);
+  return getViews();
+}
+/** Show the note in the file manager (Explorer, Finder, or the desktop's default), selected where it can be. */
+export function revealJob(id) {
+  const file = notePath(id);
+  const [bin, args] = process.platform === 'win32' ? ['explorer', [`/select,${file}`]]
+    : process.platform === 'darwin' ? ['open', ['-R', file]]
+    : ['xdg-open', [path.dirname(file)]];
+  spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
+  return { ok: true, path: file };
+}
+
+/**
+ * Attach the real posting to a note that was created without one (from an email, or a thin page). The note
+ * keeps its name, status, status log, notes, packet, letter and tailored resume; the posting's own facts
+ * replace the frontmatter's, the score is recomputed from the posting, and the description section is
+ * replaced. A person asks for this on a specific note, so it is the one place the app rewrites what it wrote.
+ */
+export async function attachPosting(id, href, { linkOnly = false } = {}) {
+  const file = notePath(id);
+  if (!/^https?:\/\//i.test(String(href || ''))) throw Object.assign(new Error('Give an http(s) link.'), { status: 400 });
+  const { readLink } = await import('../../scraper/import-link.mjs');
+  const { weightsFingerprint: fp } = await import('../../scraper/rescore.mjs');
+  const { loadSeen, saveSeen } = await import('../../scraper/vault.mjs');
+  const criteria = loadCriteria();
+  const r = linkOnly ? { ok: false, error: '' } : await readLink(href, { criteria });
+  // A link the reader cannot turn into a posting (a page behind a login, a board with no API, an odd site)
+  // still belongs on the note: Open posting then goes somewhere real. Only the link and a log line are written.
+  if (!r.ok) return attachLinkOnly(file, id, String(href).trim(), r.error);
+  const { url, job: j, scored } = r;
+  let text = fs.readFileSync(file, 'utf8');
+  const y = (v) => JSON.stringify(v ?? '');
+  const setFm = (k, v) => { text = new RegExp(`^${k}: .*$`, 'm').test(text) ? text.replace(new RegExp(`^${k}: .*$`, 'm'), () => `${k}: ${v}`) : text.replace(/^---\n([\s\S]*?)\n---/, (m, body) => `---\n${body}\n${k}: ${v}\n---`); };
+  setFm('company', y(j.company)); setFm('title', y(j.title)); setFm('location', y(j.location)); setFm('remote', j.remote ? 'true' : 'false');
+  setFm('source', j.source); setFm('url', y(j.url || url)); setFm('score', scored.score); setFm('weights', fp(criteria));
+  setFm('posted', y(j.posted ? String(j.posted).slice(0, 10) : '')); setFm('salary', y(j.salary)); setFm('salary_max', j.salaryMax || ''); setFm('pay_band', scored.payBand || 'unknown');
+  setFm('department', y(j.department)); setFm('job_id', y(j.id));
+  text = text.replace(/^# .*$/m, () => `# ${j.title} @ ${j.company}`);
+  text = text.replace(/^\*\*\[Open posting\]\(.*?\)\*\*.*$/m, () => `**[Open posting](${j.url || url})** · ${j.location || 'location n/a'} · ${j.remote ? 'Remote' : 'On-site/Hybrid'} · score **${scored.score}**${j.salary ? ` · ${j.salary}` : ''}`);
+  text = text.replace(/^## Why it matched\s*\n[\s\S]*?(?=^## )/m, () => `## Why it matched\n${scored.reasons.map((x) => `- ${x}`).join('\n')}\n\n`);
+  text = text.replace(/^(## Status log\s*\n(?:- .*\n)*)/m, (m) => `${m}- ${isoDay()} — posting attached from ${url} (score ${scored.score}; was ${(m.match(/score (-?\d+)/) || [, '?'])[1]})\n`);
+  const desc = (j.descriptionText || '').slice(0, criteria.maxDescriptionChars ?? 6000);
+  const block = `## Job description\n> Source: ${j.source} · attached ${isoDay()}${(j.descriptionText || '').length > desc.length ? ' · truncated, open the posting for the full text' : ''}\n\n${desc}\n`;
+  text = /^## Job description/m.test(text) ? text.replace(/^## Job description[\s\S]*$/m, () => block) : `${text.replace(/\n+$/, '')}\n\n${block}`;
+  fs.writeFileSync(file, text);
+  const seen = loadSeen();
+  seen[j.id] = { path: file, firstSeen: new Date().toISOString(), company: j.company, title: j.title, companyKey: `link:${j.source}`, score: scored.score };
+  saveSeen(seen);
+  cache.key = '';
+  return getJob(id);
+}
+
+function attachLinkOnly(file, id, href, why) {
+  let text = fs.readFileSync(file, 'utf8');
+  const before = (text.match(/^url: (.*)$/m) || [, ''])[1];
+  text = replaceFrontmatterLine(text, 'url', JSON.stringify(href));
+  text = /^\*\*\[Open posting\]\(.*?\)\*\*/m.test(text)
+    ? text.replace(/^\*\*\[Open posting\]\(.*?\)\*\*/m, () => `**[Open posting](${href})**`)
+    : text.replace(/^(# .*\n)/m, (m) => `${m}\n**[Open posting](${href})**\n`);
+  text = appendUnderHeading(text, 'Status log', `- ${isoDay()} — posting link set to ${href}${why ? ` (the posting itself could not be read: ${why})` : ' (link only, by request)'}${before && !/mail\.google\.com/.test(before) ? `; was ${before.replace(/^"|"$/g, '')}` : ''}`);
+  fs.writeFileSync(file, text);
+  cache.key = '';
+  return { ...getJob(id), linkOnly: true, warning: why || '' };
+}
+
+/** Add postings from links the person pasted. One result per link, in order; a failure on one does not stop the rest. */
+export async function importLinks(urls) {
+  const list = [].concat(urls || []).flatMap((s) => String(s).split(/\s+/)).map((s) => s.trim()).filter(Boolean);
+  if (!list.length) throw Object.assign(new Error('Give at least one link.'), { status: 400 });
+  if (list.length > 25) throw Object.assign(new Error('At most 25 links at a time.'), { status: 400 });
+  const { importLink } = await import('../../scraper/import-link.mjs');
+  const criteria = loadCriteria();
+  const out = [];
+  for (const u of list) {
+    const r = await importLink(u, { criteria });
+    out.push(r.ok
+      ? { url: r.url, link: r.job.url || r.url, ok: true, added: r.added, id: r.note ? path.basename(r.note, '.md') : r.existing ? path.basename(r.existing, '.md') : '', company: r.job.company, title: r.job.title, location: r.job.location, score: r.score, reason: r.reason || '', belowMin: !!r.belowMin }
+      : { url: r.url || u, ok: false, error: r.error });
+  }
+  return out;
+}
+
+export function addCompany({ name, ats, slug, tier = 'B', notes = '' }) {
+  if (!name || !ats || !slug) throw Object.assign(new Error('name, ats and slug are required'), { status: 400 });
+  if (loadCompanies().some((c) => c.ats === ats.toLowerCase() && c.slug === slug)) throw Object.assign(new Error('that board is already in the table'), { status: 409 });
+  const md = fs.readFileSync(P.companies, 'utf8').replace(/\n+$/, '');
+  fs.writeFileSync(P.companies, `${md}\n| ${name} | ${ats.toLowerCase()} | ${slug} | ${tier} | | ${notes} |\n`);
+  return loadCompanies();
+}
+
+// ---------- profile ----------
+// The notes applications are written from. Profile, Positioning and Voice are the person's to edit; the resume
+// note is synced from the resume file and is read here, not written.
+const PROFILE_NOTES = [
+  { key: 'profile', title: 'Profile', rel: 'Profile/Profile.md', editable: true, hint: 'Who you are: location, availability, links, the facts every application reads. The onboarding interview wrote it; you keep it current.' },
+  { key: 'positioning', title: 'Positioning', rel: 'Profile/Positioning.md', editable: true, hint: 'How the story is told: which half leads for which posting, the evidence rule, what must never be claimed.' },
+  { key: 'voice', title: 'Voice', rel: 'Profile/Voice.md', editable: true, hint: 'How you write. The cover-letter writer treats this note as binding; edit it here to change every letter after.' },
+  { key: 'resume', title: 'Resume', rel: RESUME_NOTE, editable: false, hint: 'The resume of record, synced from your resume file. Edit the file and run `tekjobs resume sync`; this note is replaced on every sync.' },
+];
+export function profile() {
+  const read = (rel) => safe(() => fs.readFileSync(path.join(VAULT, rel), 'utf8'), '');
+  const notes = PROFILE_NOTES.map((n) => ({ ...n, path: path.join(VAULT, n.rel), markdown: read(n.rel), exists: fs.existsSync(path.join(VAULT, n.rel)) }));
+  const resume = notes.find((n) => n.key === 'resume').markdown || [...LEGACY_RESUME_NOTES, 'Profile/Resume - Source.md'].map(read).find(Boolean) || '';
+  return { profile: read('Profile/Profile.md'), positioning: read('Profile/Positioning.md'), voice: read('Profile/Voice.md'), resume, notes };
+}
+/**
+ * The profile as structure: who, what they aim at and whether the criteria agree, the constraints, the documents
+ * and their age, what is stale, and which note feeds which draft. Read from the Markdown each time; nothing is
+ * stored twice. Parsing follows the note's own headings and "- **Field:** value" lines.
+ */
+export function profileSummary() {
+  const md = safe(() => fs.readFileSync(P.profile, 'utf8'), '');
+  const fmOf = (text) => { const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/); const out = {}; if (m) for (const line of m[1].split(/\r?\n/)) { const i = line.indexOf(':'); if (i > 0) out[line.slice(0, i).trim()] = line.slice(i + 1).trim(); } return out; };
+  const fm = fmOf(md);
+  const section = (name) => { const m = md.match(new RegExp(`^## ${name.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}[^\\n]*\\n([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm')); return m ? m[1].trim() : ''; };
+  const field = (text, label) => { const m = text.match(new RegExp(`^- \\*\\*${label}[^*]*\\*\\*\\s*(.*)$`, 'm')); return m ? m[1].trim().replace(/\*\*/g, '').replace(/\s+/g, ' ') : ''; };
+  const basicsText = section('Basics'), constraintsText = section('Constraints & preferences') || section('Constraints');
+  const links = (field(basicsText, 'Links').match(/https?:\/\/[^\s·,)]+|[a-z0-9.-]+\.[a-z]{2,}(?:\/[^\s·,)]*)?/gi) || []).filter((x, i, arr) => arr.indexOf(x) === i);
+  const portfolio = field(basicsText, 'Portfolio'); if (portfolio && !links.includes(portfolio)) links.unshift(portfolio);
+  const basics = { name: field(basicsText, 'Name'), location: field(basicsText, 'Location'), email: field(basicsText, 'Email'), links, currentRole: field(basicsText, 'Current role') || field(basicsText, 'Current') || field(basicsText, 'Role') };
+  const whatHeading = (md.match(/^## (What [^\n]*)$/m) || [])[1] || 'What you are, in three sentences';
+  const summaryText = section(whatHeading).replace(/^\(The interview fills this in[\s\S]*$/m, '').replace(/^>.*$/gm, '').trim();
+  const proofPoints = section('Proof points').split(/\r?\n/).map((l) => l.replace(/^-\s*/, '').trim()).filter((l) => l && !/^\(/.test(l)).map((text) => ({ text, hasNumber: /\d/.test(text) }));
+  // Target roles: the table's rows, one entry per title, with the criteria title term that would find it.
+  const criteria = safe(() => loadCriteria(), {}) || {};
+  const terms = Object.keys(criteria.titleTerms || {}).map((t) => t.toLowerCase());
+  const targets = [];
+  for (const line of section('Target roles').split(/\r?\n/)) {
+    const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length < 2 || !/^[A-Z]$/.test(cells[0])) continue;
+    for (const title of cells[1].split(/\s*[·,;]\s*/).map((t) => t.trim()).filter(Boolean)) {
+      const lower = title.toLowerCase();
+      const term = terms.find((t) => lower.includes(t) || t.includes(lower)) || '';
+      targets.push({ tier: cells[0], title, term });
+    }
+  }
+  // Constraints beside what the scan enforces.
+  const moneyIn = (text) => { const m = text.replace(/,/g, '').match(/\$?\s*(\d{2,3})\s*k\b|\$\s*(\d{5,7})/i); return m ? (m[1] ? Number(m[1]) * 1000 : Number(m[2])) : null; };
+  const bullets = constraintsText.split(/\r?\n/).map((l) => l.replace(/^-\s*/, '').replace(/\*\*/g, '').trim()).filter(Boolean);
+  const bullet = (re) => bullets.find((b) => re.test(b)) || '';
+  const constraint = (label, re) => field(constraintsText, label) || bullet(re);
+  const payText = constraint('Pay floor', /floor|\bcomp\b|salary|\bpay\b|\$\s?\d/i);
+  const nums = payText ? [...payText.replace(/,/g, '').matchAll(/\$?\s*(\d{2,3})\s*k\b|\$\s*(\d{5,7})/gi)].map((m) => (m[1] ? Number(m[1]) * 1000 : Number(m[2]))) : [];
+  const profileFloor = nums[0] ?? null, profileStretch = nums[1] ?? null;
+  const critFloor = criteria.salary?.minAnnual ?? null, critStretch = criteria.salary?.stretchAnnual ?? null;
+  const workMode = constraint('Work mode', /\bremote\b|hybrid|on-?site/i);
+  const employmentText = constraint('Employment', /full-time|part-time|contract|freelance/i);
+  const startText = constraint('Earliest start', /\bstart\b|available|earliest|notice/i) || field(basicsText, 'Available from');
+  const stageText = constraint('Company stage', /stage|\bsize\b|headcount|startup|enterprise/i);
+  const avoidText = constraint('Industries to avoid', /avoid|industr|exclude|never/i);
+  // "Remote only. No hybrid, no relocation." is remote only: negated words are removed before the test.
+  const workModePlain = workMode.replace(/\b(no|not|never|without)\s+(hybrid|on-?site|office|relocation|relocating)\b/gi, '');
+  const profileRemoteOnly = /remote[\s-]*only|only remote/i.test(workMode) || (/^remote\b/i.test(workModePlain) && !/hybrid|on-?site|office|open to/i.test(workModePlain));
+  const fmt = (n) => (n == null ? '' : `$${Math.round(n / 1000)}k`);
+  const level = (ok, has) => (!has ? 'missing' : ok ? 'ok' : 'warn');
+  const constraints = [
+    { label: 'Pay floor', profile: profileFloor ? fmt(profileFloor) : payText, criteria: fmt(critFloor), level: level(profileFloor && critFloor && profileFloor === critFloor, !!(payText || critFloor)) },
+    { label: 'Stretch', profile: profileStretch ? fmt(profileStretch) : '', criteria: fmt(critStretch), level: profileStretch || critStretch ? level(profileStretch && critStretch && profileStretch === critStretch, true) : 'info' },
+    { label: 'Work mode', profile: workMode, criteria: criteria.location?.requireRemote ? 'remote only' : 'remote scores higher, on-site allowed', level: level(workMode ? profileRemoteOnly === !!criteria.location?.requireRemote : false, !!workMode) },
+    { label: 'Employment', profile: employmentText, criteria: '', level: employmentText ? 'info' : 'missing' },
+    { label: 'Company stage / size', profile: stageText, criteria: '', level: 'info' },
+    { label: 'Industries to avoid', profile: avoidText, criteria: (criteria.titleExclude || []).length ? `${criteria.titleExclude.length} excluded title words` : '', level: 'info' },
+    { label: 'Earliest start', profile: startText, criteria: '', level: startText ? 'info' : 'missing' },
+  ];
+  // Documents and their age.
+  const ageDays = (file) => safe(() => Math.round((Date.now() - fs.statSync(file).mtimeMs) / 864e5), null);
+  const resumeFile = path.join(VAULT, RESUME_NOTE);
+  const resumeAge = ageDays(resumeFile);
+  const resumes = safe(() => listResumes(), { files: [] });
+  const docState = (rel, label, freshDays) => { const file = path.join(VAULT, rel); const exists = fs.existsSync(file); const age = exists ? ageDays(file) : null; return { label, state: !exists ? 'missing' : freshDays && age > freshDays ? `${age} days old` : `updated ${age === 0 ? 'today' : age + 'd ago'}`, level: !exists ? 'missing' : freshDays && age > freshDays ? 'warn' : 'ok', where: rel }; };
+  const documents = [
+    docState(RESUME_NOTE, 'Resume of record', 60),
+    { label: 'Resume files', state: resumes.files.length ? `${resumes.files.length} file${resumes.files.length === 1 ? '' : 's'}${resumes.files.some((f) => f.current) ? ', one is the source' : ''}` : 'no folder yet', level: resumes.files.length ? 'ok' : 'info', where: resumes.dir || '' },
+    docState('Profile/Positioning.md', 'Positioning'),
+    docState('Profile/Voice.md', 'Voice'),
+    docState('Profile/Snippets.md', 'Snippets (copy panel)'),
+  ];
+  // What would trip a reader.
+  const attention = [];
+  if (!md) attention.push({ level: 'missing', note: 'Profile', text: 'Profile/Profile.md does not exist. Run the onboarding interview.' });
+  if (fm.status === 'draft') attention.push({ level: 'warn', note: 'Profile', text: 'The profile is still marked draft.' });
+  for (const [k, label] of [['name', 'Name'], ['location', 'Location'], ['email', 'Email'], ['currentRole', 'Current role']]) if (!basics[k]) attention.push({ level: 'missing', note: 'Profile', text: `Basics: ${label} is empty.` });
+  if (!summaryText) attention.push({ level: 'missing', note: 'Profile', text: 'The three-sentence summary is the template; every letter opens from it.' });
+  if (targets.length === 0) attention.push({ level: 'missing', note: 'Profile', text: 'No target roles in the table.' });
+  for (const t of targets.filter((t) => !t.term)) attention.push({ level: 'warn', note: 'Criteria', text: `"${t.title}" has no title term in the criteria, so the scan never finds it.` });
+  for (const c of constraints.filter((c) => c.level === 'missing')) attention.push({ level: 'missing', note: 'Profile', text: `Constraints: ${c.label} is empty.` });
+  for (const c of constraints.filter((c) => c.level === 'warn')) attention.push({ level: 'warn', note: 'Criteria', text: `${c.label}: the profile says ${c.profile}, the criteria say ${c.criteria || 'nothing'}.` });
+  // A profile without a Proof points section is not wrong (letters take their numbers from the resume of record); one with the section left empty is.
+  if (proofPoints.length === 0 && /^## Proof points/m.test(md)) attention.push({ level: 'warn', note: 'Profile', text: 'The Proof points section is empty; letters fall back to the resume of record for numbers.' });
+  for (const p of proofPoints.filter((p) => !p.hasNumber)) attention.push({ level: 'warn', note: 'Profile', text: `Proof point without a number: "${p.text.slice(0, 70)}${p.text.length > 70 ? '…' : ''}"` });
+  for (const d of documents.filter((d) => d.level !== 'ok' && d.level !== 'info')) attention.push({ level: d.level, note: d.label, text: d.level === 'missing' ? `${d.label} is missing (${d.where}).` : `${d.label} is ${d.state}; sync it if the file changed.` });
+  const feeds = [
+    { produces: 'Match scores and the daily scan', reads: 'Targets/Search Criteria.md only' },
+    { produces: 'Application packet: narrative, tailored summary and bullets, risks', reads: 'Profile, Positioning, the resume of record, the posting' },
+    { produces: 'Cover letters', reads: 'Voice for how it sounds; the resume of record as the only source of facts; Profile and Positioning for what leads' },
+    { produces: 'Tailored resumes', reads: 'The resume of record, reordered and pruned; never added to' },
+    { produces: 'The copy panel', reads: 'Snippets, seeded from Profile Basics' },
+    { produces: 'The onboarding interview', reads: 'Resume - Source, then writes Profile and the criteria' },
+  ];
+  return { exists: !!md, status: fm.status || '', updated: fm.updated || '', basics, summary: summaryText, targets, constraints, proofPoints, documents, attention, feeds, resumeAgeDays: resumeAge };
+}
+
+export function saveProfileNote(key, markdown) {
+  const note = PROFILE_NOTES.find((n) => n.key === key);
+  if (!note) throw Object.assign(new Error(`No profile note "${key}"`), { status: 404 });
+  if (!note.editable) throw Object.assign(new Error(`${note.title} is synced from your resume file; edit the file and run tekjobs resume sync.`), { status: 400 });
+  if (key === 'profile') return saveProfile(markdown);
+  if (!markdown || markdown.trim().length < 40) throw Object.assign(new Error(`${note.title} is too short to save.`), { status: 400 });
+  const file = path.join(VAULT, note.rel);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Same habit as saveProfile: the previous version is kept beside the note, once per day.
+  if (fs.existsSync(file)) fs.copyFileSync(file, file.replace(/\.md$/, `.before-${isoDay()}.md`));
+  fs.writeFileSync(file, markdown.replace(/^updated: .*$/m, `updated: ${isoDay()}`));
+  return { saved: file };
+}
+
+// ---------- scan ----------
+const scan = { running: false, startedAt: null, finishedAt: null, exitCode: null, output: [], criteria: '' };
+export function scanStatus() { return { ...scan, output: scan.output.slice(-200) }; }
+/**
+ * The top of the last scan's ranking, dry or real, from the snapshot every run writes. This is how the
+ * onboarding shows "here is what your criteria find" before a single note exists: a dry run writes no notes,
+ * so search_jobs has nothing to say until the first real scan.
+ */
+export function scanPreview({ limit = 15 } = {}) {
+  let snap;
+  try { snap = JSON.parse(fs.readFileSync(P.lastRun, 'utf8')); } catch { return { when: null, minScore: null, total: 0, rows: [], note: 'No scan has run yet for this profile folder. run_scan first.' }; }
+  const rows = (snap.jobs || []).slice(0, Math.max(1, Math.min(50, Number(limit) || 15))).map((j) => ({
+    score: j.score, company: j.company, title: j.title, location: j.location, remote: !!j.remote, salary: j.salary || '', payBand: j.payBand, posted: j.posted, url: j.url, source: j.source, isNew: !!j.isNew,
+    reasons: (j.reasons || []).slice(0, 3),
+  }));
+  return { when: snap.when, minScore: snap.minScore, total: (snap.jobs || []).length, aboveBar: (snap.jobs || []).filter((j) => j.score >= (snap.minScore || 0)).length, failed: (snap.failed || []).length, rows };
+}
+export function runScan(args = [], { criteria = '', retryFailed = false, via = 'app' } = {}) {
+  if (scan.running) return scanStatus();
+  if (retryFailed) args = [...args, '--retry-failed'];
+  if (criteria) getCriteriaPreset(criteria); // 404 now rather than a dead child process later
+  scan.running = true; scan.startedAt = new Date().toISOString(); scan.finishedAt = null; scan.exitCode = null; scan.output = []; scan.criteria = criteria;
+  const child = spawn(process.execPath, [path.join(ROOT, 'run.mjs'), ...args, ...(criteria ? ['--criteria', criteria] : [])], { cwd: ROOT, env: { ...process.env, TEKJOBS_RUN_VIA: via } });
+  const push = (d) => { for (const l of String(d).split(/\r?\n/)) if (l.trim()) scan.output.push(l); };
+  child.stdout.on('data', push); child.stderr.on('data', push);
+  child.on('close', (code) => { scan.running = false; scan.exitCode = code; scan.finishedAt = new Date().toISOString(); cache.key = ''; });
+  return scanStatus();
+}