openings 0.1.58 → 0.1.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "description": "A free, candidate-safe job-search substrate for AI agents",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/abhay-avagama/hiring-agent.git" },

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { ALL_PROVIDERS, type Ats } from "./types.ts";
 import { readFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { createRuntime } from "./runtime.ts";
 import { atomicJson } from "./atomic-file.ts";
 import { verifyBoards } from "./board-verification.ts";
@@ -11,6 +11,9 @@ import { runSourceDiscovery, runYcSourceDiscovery } from "./source-discovery.ts"
 import { discoverAndPromote } from "./source-discovery-pipeline.ts";
 import { traceCareerSources } from "./career-tracing.ts";
 import { discoverCommonCrawlSources } from "./common-crawl-discovery.ts";
+import { createLocalWatches } from "./local-watches.ts";
+import { notifyDesktop } from "./desktop-notify.ts";
+import type { CandidateProfile } from "./candidate-profile.ts";
 import { discoverCatalog } from "./catalog-discovery.ts";
 import { parseArgs } from "node:util";
 import { generateYcCompanySeeds } from "./company-seeds.ts";
@@ -31,6 +34,9 @@ import { mergeAttemptedRoundLeads, prepareRecruiteeRoundArtifacts } from "./recr
 const HELP = `Openings — search public company job boards
 
 Usage:
+  openings watch add RESUME.txt [--label NAME] [--country IN,US]   watch for roles that fit, on this machine
+  openings watch list | check ID [--peek] | stop ID
+  openings watch run [--country IN,US] [--no-refresh]              what a scheduler calls: refresh, match, notify
   openings crawl [--workday-countries IN,US] [--country CODE | --companies FILE] [--concurrency N] [--source-cache-hours N] [--source-limit N] [--delay-ms N] [--workday-page-delay-ms N] [--timeout-ms N] [--data-dir PATH]
   openings snapshot export [--input FILE] [--output-dir PATH]
   openings coverage report --country CODE [--snapshot FILE] [--catalog FILE] [--candidates FILE] [--registry FILE] [--output FILE] [--as-of ISO]
@@ -110,6 +116,58 @@ export async function run(args: string[]): Promise<number> {
     return 0;
   }
 
+  if (command === "watch") {
+    const sub = rest[0];
+    /** The value after a flag, or undefined. Local to this command; the other commands parse their own. */
+    const argValue = (args: string[], flag: string) => {
+      const at = args.indexOf(flag);
+      return at >= 0 && args[at + 1] && !args[at + 1]!.startsWith("--") ? args[at + 1] : undefined;
+    };
+    const dataDir = argValue(rest, "--data-dir") ?? process.env.OPENINGS_DATA_DIR ?? join(process.cwd(), ".openings");
+    const runtime = createRuntime({ dataDir });
+    const watches = createLocalWatches({
+      dataDir,
+      // Whatever the local index already holds; a monitor never fetches on its own behalf.
+      jobs: async () => (await runtime.search({ maxAgeDays: 0, limit: 200_000 }, { offline: true, staleDays: 3650 })).jobs.map((job) => ({
+        id: job.id, title: job.title, company: job.company, location: job.location, remote: job.remote,
+        countries: job.eligibleCountries ?? [], skills: (job as { skills?: string }).skills ?? "",
+        ...(job.experience === undefined || job.experience === null ? {} : { experience: job.experience }),
+      })),
+      profileFromResume: async (input) => (await runtime.recommend({ ...(input as object), limit: 1 }) as { profile: CandidateProfile }).profile,
+      notify: async (title, body) => { await notifyDesktop(title, body); },
+    });
+    if (sub === "add") {
+      const file = rest[1];
+      if (!file || file.startsWith("--")) return fail("watch add needs a resume file: openings watch add RESUME.txt [--label NAME] [--country IN]");
+      const content = await Bun.file(file).text();
+      const countries = (argValue(rest, "--country") ?? "").split(",").map((c) => c.trim().toUpperCase()).filter(Boolean);
+      const result = await watches.create({ resume: { content, format: file.toLowerCase().endsWith(".md") ? "markdown" : "text" },
+        intent: countries.length ? { countries } : {}, label: argValue(rest, "--label") });
+      console.log(JSON.stringify(result, null, 2));
+      return 0;
+    }
+    if (sub === "list") { console.log(JSON.stringify(await watches.list(), null, 2)); return 0; }
+    if (sub === "check") {
+      const id = rest[1];
+      if (!id || id.startsWith("--")) return fail("watch check needs a monitor id; `openings watch list` shows them");
+      console.log(JSON.stringify(await watches.check({ id, peek: rest.includes("--peek") }), null, 2));
+      return 0;
+    }
+    if (sub === "stop") {
+      const id = rest[1];
+      if (!id) return fail("watch stop needs a monitor id");
+      console.log(JSON.stringify(await watches.stop({ id }), null, 2));
+      return 0;
+    }
+    if (sub === "run") {
+      // What a scheduler calls. Refresh first so the monitor is reading today's index, then tell the desktop.
+      if (!rest.includes("--no-refresh")) await runtime.prepareJobSearch({ countries: (argValue(rest, "--country") ?? "IN,US").split(",") }).catch(() => undefined);
+      console.log(JSON.stringify(await watches.sweep(), null, 2));
+      return 0;
+    }
+    return fail("watch takes add, list, check, stop or run");
+  }
+
   if (command === "coverage") {
     if (rest[0] !== "report") return fail("coverage requires the `report` subcommand");
     const parsed = parseCoverageReport(rest.slice(1));

package/src/desktop-notify.ts

@@ -0,0 +1,27 @@
+/**
+ * A desktop notification, using whatever the machine already has.
+ *
+ * No dependency and no daemon: each platform ships something that puts a line on screen, and a monitor that runs
+ * on your own machine should not need a package to tell you it found something. Failure is silent by design —
+ * a missing notifier must never stop a monitor from recording what it found.
+ */
+const QUOTE = /["\\]/g;
+
+export async function notifyDesktop(title: string, body: string): Promise<boolean> {
+  const safeTitle = title.replace(QUOTE, "").slice(0, 120);
+  const safeBody = body.replace(QUOTE, "").slice(0, 240);
+  const attempts: string[][] = process.platform === "darwin"
+    ? [["osascript", "-e", `display notification "${safeBody}" with title "${safeTitle}"`]]
+    : process.platform === "win32"
+      ? [["powershell", "-NoProfile", "-Command",
+          `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] > $null; ` +
+          `Write-Output "${safeTitle}: ${safeBody}"`]]
+      : [["notify-send", safeTitle, safeBody], ["kdialog", "--passivepopup", `${safeTitle}\n${safeBody}`, "10"]];
+  for (const command of attempts) {
+    try {
+      const proc = Bun.spawn(command, { stdout: "ignore", stderr: "ignore" });
+      if (await proc.exited === 0) return true;
+    } catch { /* try the next one, or give up quietly */ }
+  }
+  return false;
+}

package/src/index.ts

@@ -41,6 +41,7 @@ export type { CountryJobCoverage, JobCoverageSummary } from "./job-coverage.ts";
 export { createHostedRuntime } from "./runtime.ts";
 export type { SnapshotStore } from "./crawler.ts";
 export { createToolHandler, SCOPES, scopeForTool, type Scope } from "./tools.ts";
+export { describeWatchProfile, matchWatch, toWatchProfile, type WatchableJob, type WatchMatch, type WatchProfile } from "./watch-profile.ts";
 export { createMcpHandler, FLOW_INSTRUCTIONS } from "./mcp.ts";
 export type { UpdateNotice } from "./update-check.ts";
 export { VERSION } from "./version.ts";

package/src/local-watches.ts

@@ -0,0 +1,146 @@
+/**
+ * Monitors that live on the candidate's own machine.
+ *
+ * The hosted monitor stores a derived profile on our server and emails what it finds. This one stores the same
+ * profile in the user's data directory and tells their desktop instead, which means the resume, the profile and
+ * the record of what has been seen never leave the machine at all. There is no account, no email address, and
+ * nothing for us to lose.
+ *
+ * It satisfies the same interface the hosted monitors do, so the four MCP tools behave identically whether an
+ * assistant is talking to a local install or to the hosted server.
+ */
+import { join } from "node:path";
+import { atomicJson } from "./atomic-file.ts";
+import { describeWatchProfile, matchWatch, toWatchProfile, type WatchableJob, type WatchProfile } from "./watch-profile.ts";
+import type { CandidateProfile } from "./candidate-profile.ts";
+
+export interface StoredWatch {
+  id: string;
+  label?: string;
+  profile: WatchProfile;
+  createdAt: string;
+  lastCheckedAt?: string;
+  /** Job ids already reported. Kept so a monitor says "new" and means it. */
+  seen: string[];
+}
+
+interface WatchFile { version: 1; watches: StoredWatch[] }
+
+const CAP_SEEN = 4_000;
+
+export interface LocalWatchOptions {
+  dataDir: string;
+  /** Live roles to match against; the caller supplies them from whichever index it already holds. */
+  jobs(): Promise<WatchableJob[]>;
+  /** Parses a resume into facts. The same parser the one-off tools use. */
+  profileFromResume(input: unknown): Promise<CandidateProfile>;
+  notify?(title: string, body: string): Promise<void>;
+  now?: () => Date;
+}
+
+export function createLocalWatches(options: LocalWatchOptions) {
+  const now = options.now ?? (() => new Date());
+  const path = join(options.dataDir, "watches.json");
+
+  async function read(): Promise<WatchFile> {
+    try {
+      const file = await Bun.file(path).json() as WatchFile;
+      return file?.version === 1 && Array.isArray(file.watches) ? file : { version: 1, watches: [] };
+    } catch { return { version: 1, watches: [] }; }
+  }
+  const write = (file: WatchFile) => atomicJson(path, file);
+
+  return {
+    async create(input: unknown) {
+      const body = (input ?? {}) as { resume?: unknown; intent?: Record<string, unknown>; label?: string };
+      if (!body.resume) throw new Error("watch_jobs needs a resume to derive a profile from");
+      const parsed = await options.profileFromResume({ resume: body.resume });
+      const intent = (body.intent ?? {}) as { countries?: string[]; locations?: string[]; remote?: boolean; excludedTerms?: string[] };
+      const profile = toWatchProfile(parsed, intent);
+      const file = await read();
+      const watch: StoredWatch = {
+        id: `w_${now().getTime().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+        ...(body.label ? { label: String(body.label).slice(0, 60) } : {}),
+        profile, createdAt: now().toISOString(), seen: [],
+      };
+      // Everything live counts as already seen, or the first check would report the whole index as new.
+      const jobs = await options.jobs();
+      const matches = matchWatch(profile, jobs, 20);
+      watch.seen = matchWatch(profile, jobs, 100_000).map((m) => m.job.id).slice(0, CAP_SEEN);
+      watch.lastCheckedAt = now().toISOString();
+      file.watches.push(watch);
+      await write(file);
+      return {
+        id: watch.id, holding: describeWatchProfile(profile), profile,
+        matchesNow: matches.map((m) => ({ ...m.job, why: m.reasons })),
+        emailing: false,
+        storedAt: path,
+        note: "This monitor is on your machine. The resume was read once and discarded; what is kept is the profile shown above, in a file you can open or delete.",
+      };
+    },
+
+    async list() {
+      const file = await read();
+      return { watches: file.watches.map((w) => ({
+        id: w.id, label: w.label, holding: describeWatchProfile(w.profile),
+        createdAt: w.createdAt, lastCheckedAt: w.lastCheckedAt, reported: w.seen.length,
+      })), storedAt: path };
+    },
+
+    async check(input: unknown) {
+      const body = (input ?? {}) as { id?: string; limit?: number; peek?: boolean };
+      const file = await read();
+      const watch = file.watches.find((w) => w.id === body.id);
+      if (!watch) throw new Error(`No monitor with id ${body.id}. Call list_watches to see them.`);
+      const jobs = await options.jobs();
+      const seen = new Set(watch.seen);
+      const fresh = matchWatch(watch.profile, jobs, 100_000).filter((m) => !seen.has(m.job.id));
+      const limited = fresh.slice(0, Math.min(body.limit ?? 20, 50));
+      const checkedAt = now().toISOString();
+      if (!body.peek) {
+        // Everything found is marked seen, not only what was returned, or the rest would arrive again tomorrow.
+        watch.seen = [...fresh.map((m) => m.job.id), ...watch.seen].slice(0, CAP_SEEN);
+        watch.lastCheckedAt = checkedAt;
+        await write(file);
+      }
+      return {
+        matches: limited.map((m) => ({ ...m.job, why: m.reasons })),
+        totalNew: fresh.length, checkedAt, newSince: watch.lastCheckedAt ?? watch.createdAt,
+        holding: describeWatchProfile(watch.profile),
+      };
+    },
+
+    async stop(input: unknown) {
+      const id = ((input ?? {}) as { id?: string }).id;
+      const file = await read();
+      const before = file.watches.length;
+      file.watches = file.watches.filter((w) => w.id !== id);
+      await write(file);
+      return { stopped: before !== file.watches.length,
+        deleted: before !== file.watches.length ? "the monitor, its profile, and the record of what it had reported" : "nothing; no monitor had that id" };
+    },
+
+    /** Check every monitor and tell the desktop about anything new. This is what a scheduled run calls. */
+    async sweep() {
+      const file = await read();
+      const jobs = await options.jobs();
+      const results: Array<{ id: string; label?: string; found: number }> = [];
+      for (const watch of file.watches) {
+        const seen = new Set(watch.seen);
+        const fresh = matchWatch(watch.profile, jobs, 100_000).filter((m) => !seen.has(m.job.id));
+        if (fresh.length) {
+          watch.seen = [...fresh.map((m) => m.job.id), ...watch.seen].slice(0, CAP_SEEN);
+          const first = fresh[0]!;
+          await options.notify?.(
+            `${fresh.length} new role${fresh.length === 1 ? "" : "s"} for ${watch.label ?? "your monitor"}`,
+            `${first.job.title} at ${first.job.company}${fresh.length > 1 ? ` and ${fresh.length - 1} more` : ""}`,
+          ).catch(() => undefined);
+        }
+        watch.lastCheckedAt = now().toISOString();
+        results.push({ id: watch.id, label: watch.label, found: fresh.length });
+      }
+      await write(file);
+      return { checked: file.watches.length, results };
+    },
+  };
+}

package/src/tools.ts

@@ -8,7 +8,8 @@ import type { JobCoverageSummary } from "./job-coverage.ts";
 import type { PrepareJobSearchResult } from "./job-search-preparation.ts";
 
 export interface ToolDefinition {
-  name: "prepare_job_search" | "get_job_coverage" | "recommend_jobs" | "analyze_job_fit" | "optimize_resume" | "search_jobs" | "get_job";
+  name: "prepare_job_search" | "get_job_coverage" | "recommend_jobs" | "analyze_job_fit" | "optimize_resume" | "search_jobs" | "get_job"
+    | "watch_jobs" | "list_watches" | "check_watch" | "stop_watch";
   /** Human-readable name for a consent screen or tool picker, where a snake_case identifier reads poorly. */
   title: string;
   description: string;
@@ -18,12 +19,16 @@ export interface ToolDefinition {
   outputSchema: Record<string, unknown>;
   /** Nothing here applies, submits, or writes on the candidate's behalf. Preparation is the one tool that writes
    * at all: it caches the job index on disk, so claiming readOnlyHint for it would be untrue. */
-  annotations: { readOnlyHint: boolean; destructiveHint: false; idempotentHint: true; openWorldHint: boolean };
+  annotations: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: true; openWorldHint: boolean };
 }
 
 /** Tools that reach employer boards over the network are open-world; the rest read the local index. */
+const WRITES = new Set<ToolDefinition["name"]>(["prepare_job_search", "watch_jobs", "stop_watch"]);
+/** Monitors need somewhere to persist, which a local install does not have. The host says whether it offers them. */
+const WATCH_TOOLS = new Set<ToolDefinition["name"]>(["watch_jobs", "list_watches", "check_watch", "stop_watch"]);
 const annotationsFor = (name: ToolDefinition["name"]): ToolDefinition["annotations"] =>
-  ({ readOnlyHint: name !== "prepare_job_search", destructiveHint: false, idempotentHint: true, openWorldHint: name === "prepare_job_search" || name === "recommend_jobs" || name === "get_job" });
+  ({ readOnlyHint: !WRITES.has(name), destructiveHint: name === "stop_watch", idempotentHint: true,
+     openWorldHint: name === "prepare_job_search" || name === "recommend_jobs" || name === "get_job" });
 
 interface JobWorkflows {
   prepareJobSearch(input: unknown): Promise<PrepareJobSearchResult>;
@@ -31,6 +36,13 @@ interface JobWorkflows {
   recommend(input: unknown): Promise<RecommendJobsResult>;
   analyzeJobFit(input: unknown): Promise<AnalyzeJobFitResult>;
   optimizeResume(input: unknown): Promise<OptimizeResumeResult>;
+  /** Monitors. Absent where the host does not offer them, in which case the four tools are not listed at all. */
+  watches?: {
+    create(input: unknown): Promise<unknown>;
+    list(): Promise<unknown>;
+    check(input: unknown): Promise<unknown>;
+    stop(input: unknown): Promise<unknown>;
+  };
 }
 
 /**
@@ -44,6 +56,10 @@ export type Scope = (typeof SCOPES)[keyof typeof SCOPES];
 const TOOL_SCOPE: Record<ToolDefinition["name"], Scope> = {
   prepare_job_search: SCOPES.jobs, get_job_coverage: SCOPES.jobs, search_jobs: SCOPES.jobs, get_job: SCOPES.jobs,
   recommend_jobs: SCOPES.resume, analyze_job_fit: SCOPES.resume, optimize_resume: SCOPES.resume,
+  // Creating or changing a monitor reads a resume. Reading one back does not, so an agent can poll a monitor
+  // with a job-search token and never hold resume access at all.
+  watch_jobs: SCOPES.resume, stop_watch: SCOPES.resume,
+  list_watches: SCOPES.jobs, check_watch: SCOPES.jobs,
 };
 
 /** The scope a tool needs, for a caller that wants to explain the boundary rather than discover it by refusal. */
@@ -222,6 +238,65 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         guidance: { type: "string", description: "How to present these results honestly; meant for the assistant, not the candidate" },
       }, ["jobs", "window", "pagination"]),
     },
+    {
+      name: "watch_jobs",
+      title: "Watch for roles that fit",
+      description: "Create a standing monitor from a resume, so new roles that fit are found without asking again. What is kept is the search the resume produced, never the resume: the skills, titles, seniority and years that matching uses, which the result shows back in plain words so the candidate can read, change or stop it. Use it when someone wants to be told about new roles over time; use recommend_jobs for a one-off ranking right now.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          resume: resumeSchema(),
+          intent: intentSchema(),
+          email: { type: "string", description: "Where to send new matches. Omit to create a monitor the assistant checks with check_watch instead of one that emails" },
+          label: { type: "string", description: "A short name for this monitor, so a person with several can tell them apart" },
+        },
+        required: ["resume"], additionalProperties: false,
+      },
+      outputSchema: output({
+        id: { type: "string", description: "Pass this to check_watch or stop_watch" },
+        holding: { type: "string", description: "What is stored, in plain words. Read it back to the candidate: it is the whole privacy claim" },
+        profile: { type: "object", additionalProperties: true, description: "The stored search itself, which contains no resume text" },
+        matchesNow: { type: "array", items: { type: "object", additionalProperties: true }, description: "Roles matching today, so the monitor is useful immediately" },
+        emailing: { type: "boolean", description: "Whether new matches will be emailed; false means the assistant must call check_watch" },
+      }, ["id", "holding"]),
+    },
+    {
+      name: "list_watches",
+      title: "List monitors",
+      description: "Every monitor on this account, with what each one holds and when it last found something. Reads no resume.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      outputSchema: output({ watches: { type: "array", items: { type: "object", additionalProperties: true } } }, ["watches"]),
+    },
+    {
+      name: "check_watch",
+      title: "What is new for a monitor",
+      description: "Roles matching a monitor that it has not reported before, newest first, each with the reason it matched. Reads no resume, so an assistant can poll a monitor without ever holding resume access. Calling it marks those roles as seen, so the next call returns only what is new after that.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", minLength: 1, description: "The monitor id from watch_jobs or list_watches" },
+          limit: { type: "integer", minimum: 1, maximum: 50, default: 20, description: "How many new roles to return" },
+          peek: { type: "boolean", default: false, description: "True to look without marking anything as seen" },
+        },
+        required: ["id"], additionalProperties: false,
+      },
+      outputSchema: output({
+        matches: { type: "array", items: { type: "object", additionalProperties: true }, description: "Each carries the job, why it matched, and the employer's own posting URL" },
+        checkedAt: { type: "string" },
+        newSince: { type: "string", description: "Roles are new relative to this moment, not to when they were posted" },
+      }, ["matches"]),
+    },
+    {
+      name: "stop_watch",
+      title: "Stop a monitor",
+      description: "Delete a monitor and everything stored with it, including the record of what it has already reported. Nothing is kept.",
+      inputSchema: {
+        type: "object",
+        properties: { id: { type: "string", minLength: 1, description: "The monitor id" } },
+        required: ["id"], additionalProperties: false,
+      },
+      outputSchema: output({ stopped: { type: "boolean" }, deleted: { type: "string", description: "What was removed" } }, ["stopped"]),
+    },
     {
       name: "get_job",
       title: "Get job details",
@@ -238,7 +313,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
 
   return {
     // A client sees only what it may call. Listing a tool it would be refused teaches it to try and fail.
-    list: () => definitions.filter((definition) => allowed(definition.name))
+    list: () => definitions.filter((definition) => allowed(definition.name) && (workflows.watches !== undefined || !WATCH_TOOLS.has(definition.name)))
       .map((definition) => ({ ...definition, annotations: annotationsFor(definition.name) })),
     async call(name: string, input: Record<string, unknown>) {
       const needed = TOOL_SCOPE[name as ToolDefinition["name"]];
@@ -251,9 +326,18 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
     },
   };
 
+  const requireWatches = () => {
+    if (!workflows.watches) throw new Error("Monitors are only available on the hosted server, where there is an account to attach one to.");
+    return workflows.watches;
+  };
+
   async function dispatch(name: string, input: Record<string, unknown>): Promise<unknown> {
       if (name === "prepare_job_search") return workflows.prepareJobSearch(input);
       if (name === "get_job_coverage") return workflows.getJobCoverage(input);
+      if (name === "watch_jobs") return requireWatches().create(input);
+      if (name === "list_watches") return requireWatches().list();
+      if (name === "check_watch") return requireWatches().check(input);
+      if (name === "stop_watch") return requireWatches().stop(input);
       if (name === "recommend_jobs") return workflows.recommend(input);
       if (name === "analyze_job_fit") return workflows.analyzeJobFit(input);
       if (name === "optimize_resume") return workflows.optimizeResume(input);

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.58";
+export const VERSION = "0.1.60";

package/src/watch-profile.ts

@@ -0,0 +1,121 @@
+/**
+ * The part of a candidate we are willing to remember.
+ *
+ * A monitor has to persist something or it cannot tell you what is new. Resumes are not that something: the
+ * privacy page says a resume is read for one request and never stored, and that promise is the product rather
+ * than a detail of it. What survives here is the search the resume produced — the skills, titles, seniority and
+ * years that matching actually uses — and never a word of the document itself.
+ *
+ * Evidence spans are dropped deliberately. They are verbatim quotes from the resume, and keeping them would put
+ * the document back in the database through a side door.
+ */
+import type { CandidateProfile } from "./candidate-profile.ts";
+
+export interface WatchProfile {
+  /** Skills named in the resume, lower-cased, with no surrounding text. */
+  skills: string[];
+  /** Role titles the candidate has held, as written, with no employer or dates attached. */
+  roles: string[];
+  seniority?: "intern" | "junior" | "mid" | "senior" | "lead" | "staff" | "principal" | "manager";
+  roleFamilies: string[];
+  /** Years as derived from dated work, not as claimed anywhere in prose. */
+  approximateYears?: number;
+  /** What the candidate asked for, which is theirs to state rather than ours to infer. */
+  countries: string[];
+  locations: string[];
+  remoteOnly?: boolean;
+  excludedTerms: string[];
+}
+
+const CAP = 40;
+const clean = (values: Iterable<string>, cap = CAP): string[] => {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of values) {
+    const value = raw.trim().toLowerCase().slice(0, 64);
+    // A fact long enough to be a sentence is a sentence, and a sentence from a resume is resume text.
+    if (!value || value.length > 64 || value.split(/\s+/).length > 5 || seen.has(value)) continue;
+    seen.add(value); out.push(value);
+    if (out.length >= cap) break;
+  }
+  return out;
+};
+
+/** Reduce a parsed resume to the little we keep. Everything not named here is discarded. */
+export function toWatchProfile(profile: CandidateProfile, intent: {
+  countries?: string[]; locations?: string[]; remote?: boolean; excludedTerms?: string[];
+} = {}): WatchProfile {
+  const facts = profile.facts ?? [];
+  const seniority = profile.inferences?.find((i) => i.kind === "seniority");
+  const years = profile.inferences?.find((i) => i.kind === "approximate_experience_years");
+  return {
+    skills: clean(facts.filter((f) => f.kind === "skill").map((f) => f.value)),
+    roles: clean(facts.filter((f) => f.kind === "role").map((f) => f.value), 12),
+    ...(seniority ? { seniority: seniority.value as WatchProfile["seniority"] } : {}),
+    roleFamilies: clean(profile.inferences?.filter((i) => i.kind === "role_family").map((i) => String(i.value)) ?? [], 6),
+    ...(years && typeof years.value === "number" ? { approximateYears: years.value } : {}),
+    countries: clean(intent.countries ?? [], 8).map((c) => c.toUpperCase()),
+    locations: clean(intent.locations ?? [], 12),
+    ...(intent.remote === true ? { remoteOnly: true } : {}),
+    excludedTerms: clean(intent.excludedTerms ?? [], 16),
+  };
+}
+
+/** What the candidate is told we hold, in their words rather than ours. A monitor they cannot read is a monitor
+ * they cannot trust, so this is shown whenever one is created, listed or edited. */
+export function describeWatchProfile(profile: WatchProfile): string {
+  const parts: string[] = [];
+  if (profile.roles.length) parts.push(`roles like ${profile.roles.slice(0, 3).join(", ")}`);
+  if (profile.seniority) parts.push(`at ${profile.seniority} level`);
+  if (profile.approximateYears !== undefined) parts.push(`around ${profile.approximateYears} years of experience`);
+  if (profile.skills.length) parts.push(`skills including ${profile.skills.slice(0, 6).join(", ")}`);
+  if (profile.countries.length) parts.push(`open to ${profile.countries.join(", ")}`);
+  if (profile.locations.length) parts.push(`in ${profile.locations.slice(0, 4).join(", ")}`);
+  if (profile.remoteOnly) parts.push("remote only");
+  if (profile.excludedTerms.length) parts.push(`not ${profile.excludedTerms.slice(0, 4).join(", ")}`);
+  return parts.join("; ") || "no details were derived from the resume";
+}
+
+/** The job fields a monitor needs. Deliberately the same shape the search already produces. */
+export interface WatchableJob {
+  id: string; title: string; company: string; location: string; remote: boolean;
+  countries: string[]; skills?: string; experience?: { min: number; max?: number } | null;
+}
+
+/** Why a role matched, so a candidate is told rather than asked to trust a score. */
+export interface WatchMatch { job: WatchableJob; score: number; reasons: string[] }
+
+/**
+ * Roles worth telling this candidate about. The rule is deliberately plain: a role has to look like work they
+ * have done, in a place they said they would work, and not be something they asked to avoid. A clever ranking
+ * that cannot be explained in one line is worse here than a simple one that can, because the candidate is reading
+ * an email rather than watching a demo.
+ */
+export function matchWatch(profile: WatchProfile, jobs: readonly WatchableJob[], limit = 20): WatchMatch[] {
+  const skills = new Set(profile.skills);
+  const roleWords = new Set(profile.roles.flatMap((role) => role.split(/\s+/)).filter((w) => w.length > 3));
+  const excluded = profile.excludedTerms;
+  const matches: WatchMatch[] = [];
+  for (const job of jobs) {
+    const title = (job.title || "").toLowerCase();
+    const haystack = `${title} ${(job.skills || "").toLowerCase()}`;
+    if (excluded.some((term) => title.includes(term))) continue;
+    if (profile.remoteOnly && !job.remote) continue;
+    if (profile.countries.length && !job.countries.some((code) => profile.countries.includes(code))) continue;
+    if (profile.locations.length && !job.remote) {
+      const where = (job.location || "").toLowerCase();
+      if (!profile.locations.some((place) => where.includes(place))) continue;
+    }
+    const titleHits = [...roleWords].filter((word) => title.includes(word));
+    const skillHits = [...skills].filter((skill) => haystack.includes(skill));
+    if (!titleHits.length && !skillHits.length) continue;
+    // Stated years are the employer's requirement, so a role far above the candidate is noise rather than a stretch.
+    if (profile.approximateYears !== undefined && job.experience && job.experience.min > profile.approximateYears + 3) continue;
+    const reasons: string[] = [];
+    if (titleHits.length) reasons.push(`the title matches your work: ${titleHits.slice(0, 3).join(", ")}`);
+    if (skillHits.length) reasons.push(`asks for ${skillHits.slice(0, 4).join(", ")}`);
+    if (job.experience) reasons.push(`wants ${job.experience.min}${job.experience.max ? `-${job.experience.max}` : "+"} years`);
+    matches.push({ job, score: titleHits.length * 2 + skillHits.length, reasons });
+  }
+  return matches.sort((left, right) => right.score - left.score).slice(0, limit);
+}