openings 0.1.0

package/docs/job-seeker-quickstart.md

@@ -0,0 +1,109 @@
+# Openings for job seekers
+
+Openings helps an AI agent find real jobs from public company career systems and explain why each job does or does not fit your resume. Its useful difference is **hidden-job discovery**: it can surface relevant roles whose titles you might not have searched for yourself.
+
+It is application-safe. It cannot apply for a job, fill a form, or submit your resume. It has no account system and does not store your resume or extracted profile. It writes only its private local job index.
+
+## Before sharing your resume
+
+Ask the agent to prepare and check coverage for your target country:
+
+> Prepare Openings for India. Before I share my resume, tell me how many current jobs, employers, and indexed sources it covers.
+
+Coverage is job-level, not a marketing estimate. A company counts only when the local snapshot contains a job classified as eligible for the requested country. If coverage is thin, the agent should say so before asking for personal information.
+
+## Find jobs
+
+Openings currently accepts resume content as text or Markdown. If your resume is a PDF or DOCX, ask your MCP host to extract it to text first.
+
+> Use this resume to find backend or platform roles in India. I prefer remote or Bengaluru, and I do not want people-management roles. Rank by evidence. Include hidden opportunities and explain supported requirements, gaps, assumptions, and whether the job data was refreshed.
+
+You can choose either ranking mode:
+
+- **Evidence score** asks how much of the job's detected requirements the resume supports with exact, traceable facts. Use this by default when trust and fit matter most.
+- **Keyword score** asks how much relevant language overlaps. It can help discover adjacent roles, but overlap is not proof of competence.
+
+Both scores are returned. Changing the ranking mode changes ordering, not the underlying resume evidence.
+
+## Understand one result
+
+> Analyze this job against my resume. Separate direct support, transferable evidence, unsupported requirements, screening risks, and interview preparation gaps. Do not infer work authorization or experience from silence.
+
+For a hidden result, the response should name the title expansion that found it and whether that expansion came from your explicit intent or validated resume facts.
+
+## Improve the resume truthfully
+
+> Suggest a job-specific resume revision. Use only claims already supported by my resume, cite the supporting facts, and leave unsupported job requirements as gaps.
+
+Openings can return reviewable suggestions, an additive unified diff, or revised Markdown. It never overwrites the original and never inserts a skill merely because the job asks for it.
+
+## Example conversation
+
+**Candidate:** What does Openings cover in India?
+
+**Agent:** Calls `prepare_job_search` and follows `nextAction`: it passes the returned opaque `continuation` into the next call while the result says `call_again`, stops and explains failures on `retry_later`, and presents the returned source, employer, and job counts without recalculating them when ready.
+
+**Candidate:** That is useful. Here is my Markdown resume. Find backend roles, but exclude engineering-manager jobs.
+
+**Agent:** Calls `recommend_jobs` with the explicit constraints and evidence ranking. It presents direct, hidden, and stretch results separately, including both percentages and material gaps.
+
+**Candidate:** Why is the hidden platform role a fit?
+
+**Agent:** Calls `analyze_job_fit` for that stable job ID and presents only the returned evidence and risks.
+
+**Candidate:** Help me tailor my resume for it.
+
+**Agent:** Calls `optimize_resume`, shows the evidence-linked changes, and asks the candidate to verify them.
+
+## Common limitations and recovery
+
+- **`unsupported_resume_format`**: native PDF/DOCX parsing is not implemented. Extract the document to text or Markdown in the host and retry.
+- **Thin coverage**: coverage differs substantially by country. Treat a small result as a corpus limitation, not proof that no matching job exists.
+- **Thin resume**: add explicit, truthful projects, internships, technologies, outcomes, and target roles. Openings deliberately avoids inventing signals that are absent.
+- **Work authorization**: state hard country and sponsorship needs explicitly. Openings does not infer authorization from a location or resume silence.
+- **Evidence disagreement**: inspect the cited resume span and job text. Keyword overlap is never presented as demonstrated experience.
+
+## Connect the MCP server
+
+Install Bun 1.3 or newer, then install Openings with Bun, npm, or Yarn. Bun must stay on your `PATH`; it is the runtime the server runs on.
+
+```sh
+bun add --global openings
+# or: npm install --global openings
+# or: yarn global add openings
+```
+
+In a client that accepts MCP configuration, add this stdio server:
+
+```json
+{
+  "mcpServers": {
+    "openings": {
+      "command": "openings-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+The first `prepare_job_search` call starts a private index under `~/.openings` from verified structured job sources. Each call handles at most ten missing or stale sources, gives each source one bounded 90-second attempt, and returns `nextAction`, allowing the agent to continue across MCP requests. It crawls every currently missing verified source because a source's country eligibility is known only after its jobs are indexed; the requested countries control the coverage returned to the candidate, not which employers are assumed to belong to a country. Successful batches are cached, failures are reported, and later calls rotate past failed sources so the rest of the catalog can progress. Partitions older than 14 days are refreshed. Once all sources are fresh, the setup call makes no network request.
+
+For development from a source checkout, point the server at the absolute `src/mcp.ts` path and set `OPENINGS_DATA_DIR` to the repository's absolute `.openings` directory:
+
+```json
+{
+  "mcpServers": {
+    "openings": {
+      "command": "bun",
+      "args": ["run", "/absolute/path/to/hiring-agent/src/mcp.ts"],
+      "env": {
+        "OPENINGS_DATA_DIR": "/absolute/path/to/hiring-agent/.openings"
+      }
+    }
+  }
+}
+```
+
+When `OPENINGS_AGGREGATOR_URL` is set, first-time setup downloads the aggregator's published index before crawling, and every source you crawl is reported back so other installs benefit; only public job data is shared, never your resume. Leave it unset to keep crawls private. The packaged commands use `~/.openings` by default. The source entrypoint uses `.openings` under the MCP process's working directory unless `OPENINGS_DATA_DIR` is set. The included `.mcp.json` provides the repository-local configuration when this repository is installed as a Codex plugin.
+
+The MCP interface exposes setup, coverage, recommendation, fit analysis, resume optimization, search, and job-detail tools. There is no application-submission tool.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "openings",
+  "version": "0.1.0",
+  "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" },
+  "homepage": "https://github.com/abhay-avagama/hiring-agent#readme",
+  "bugs": { "url": "https://github.com/abhay-avagama/hiring-agent/issues" },
+  "keywords": ["jobs", "resume", "matching", "mcp", "greenhouse", "lever", "ashby", "workday", "recruitee"],
+  "type": "module",
+  "bin": { "openings-mcp": "./src/package-mcp.ts" },
+  "exports": "./src/index.ts",
+  "files": [
+    "src/",
+    "data/companies.json",
+    "skills/openings/",
+    ".codex-plugin/plugin.json",
+    ".mcp.json",
+    "README.md",
+    "docs/job-seeker-quickstart.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "test:live": "OPENINGS_LIVE_TESTS=1 bun test test/live-contract.test.ts",
+    "typecheck": "bunx tsc --noEmit",
+    "start": "bun run src/cli.ts",
+    "mcp": "bun run src/mcp.ts",
+    "expand:corpus": "bun run scripts/expand-corpus.ts",
+    "release:pack": "bun pm pack"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.2"
+  }
+}

package/skills/openings/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: openings
+description: Use MCP-native tools to find, analyze, and truthfully optimize a resume for evidence-grounded jobs.
+---
+
+# Openings
+
+Do not reproduce parsing, matching, fit classification, evidence validation, or resume rewriting in this skill. The MCP modules are the sole enforceable implementation.
+
+Use `prepare_job_search` to bootstrap the private local index and set honest country-level expectations before requesting a resume, `get_job_coverage` for later no-network coverage checks, `recommend_jobs` for resume-based discovery, `analyze_job_fit` for evidence-grounded analysis of a selected job, `optimize_resume` for a proposed revision, and `get_job` for its complete description. Keep `search_jobs` for direct lower-level searches that do not need resume matching. These tools must never be used to submit an application; the only local mutation is the job index maintained by setup and refresh.
+
+## Search
+
+1. Ask for the target countries and call `prepare_job_search` before requesting a resume. Explain that first-time setup runs in resumable batches and uses the network only to build a private local job index. While `nextAction` is `call_again`, call the tool again with the same countries and the returned opaque `continuation`; do not ask for a resume between batches. On `retry_later`, disclose failures and offer to continue with the indexed coverage or retry later without the old continuation. On `ready`, present its job-level source, job, and employer counts exactly as returned; never substitute discovery-cohort counts or recalculate coverage.
+2. Ask only for missing constraints that materially change the recommendation.
+3. Supply the user's resume content, explicit intent, and their chosen `ranking.mode` (`evidence` by default or `keyword`) to `recommend_jobs`; never pass an arbitrary filesystem path. Use `ranking.minimumPercent` only when the user requests a cutoff.
+4. Present the returned coverage summary alongside the recommendations without recalculating it.
+5. Present direct, hidden title-family, and stretch results separately. For a hidden result, quote the returned title expansions and whether each came from explicit intent or validated resume fact IDs; never invent or broaden an alias in the skill.
+6. Present both returned percentages, the selected score, assumptions, evidence, gaps, refresh status, and failures without recalculating fit. Never describe keyword overlap as demonstrated competence.
+7. Call `analyze_job_fit` before explaining a selected role's fit; present its evidence and gaps without independently recalculating them.
+8. Call `get_job` before discussing the complete description of a selected role.
+
+## Tailor an application
+
+1. Supply the selected job ID and resume content to `optimize_resume`; never pass an arbitrary filesystem path.
+2. Use `suggestions` for review, `unified_diff` for a patch, or `revised_markdown` for complete proposed content.
+3. Present the tool's evidence references and unsupported gaps without adding claims or independently rewriting its output.
+4. Ask the user to verify every proposed change. Never navigate to a submission flow, fill an application form, or submit an application.

package/src/artifact-path.ts

@@ -0,0 +1,48 @@
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, parse, relative, resolve, sep } from "node:path";
+
+export function openingsRootFor(path: string): string {
+  const absolute = resolve(path);
+  const parts = absolute.slice(parse(absolute).root.length).split(sep);
+  const index = parts.indexOf(".openings");
+  if (index < 0) throw new Error("Round 5 artifacts must be files under .openings");
+  return resolve(parse(absolute).root, ...parts.slice(0, index + 1));
+}
+
+export async function assertArtifactFile(path: string, root = openingsRootFor(path)): Promise<void> {
+  const expectedRoot = resolve(root);
+  const target = resolve(path);
+  const lexical = relative(expectedRoot, target);
+  if (!lexical || lexical.startsWith("..") || lexical.split(sep).includes("..")) throw new Error("Round 5 artifacts must be files under .openings");
+
+  await ensureDirectory(expectedRoot);
+  const actualRoot = await realpath(expectedRoot);
+  let current = expectedRoot;
+  const parentParts = relative(expectedRoot, dirname(target)).split(sep).filter(Boolean);
+  for (const component of parentParts) {
+    current = resolve(current, component);
+    await ensureDirectory(current);
+    const actual = await realpath(current);
+    if (relative(actualRoot, actual).startsWith("..")) throw new Error("Round 5 artifacts must be files under .openings");
+  }
+  try {
+    const status = await lstat(target);
+    if (status.isSymbolicLink()) throw new Error("Round 5 artifact files must not be symbolic links");
+    if (!status.isFile()) throw new Error("Round 5 artifact target must be a regular file");
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+  }
+}
+
+async function ensureDirectory(path: string): Promise<void> {
+  try {
+    const status = await lstat(path);
+    if (status.isSymbolicLink()) throw new Error("Round 5 artifact directories must not be symbolic links");
+    if (!status.isDirectory()) throw new Error("Round 5 artifact path component must be a directory");
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+    await mkdir(path);
+    const status = await lstat(path);
+    if (status.isSymbolicLink() || !status.isDirectory()) throw new Error("Round 5 artifact directory was replaced during creation");
+  }
+}

package/src/atomic-file.ts

@@ -0,0 +1,13 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export async function atomicWrite(path: string, content: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, content, "utf8");
+  await rename(temporary, path);
+}
+
+export function atomicJson(path: string, value: unknown): Promise<void> {
+  return atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`);
+}

package/src/candidate-profile.ts

@@ -0,0 +1,273 @@
+export type ResumeFormat = "text" | "markdown" | "pdf_base64" | "docx_base64";
+
+export interface ResumeInput {
+  content: string;
+  format: ResumeFormat;
+}
+
+export interface NormalizedResume {
+  text: string;
+  normalization: "openings-resume:v1";
+  offsetEncoding: "utf16_code_units";
+}
+
+export interface CandidateProfile {
+  normalizedResume: NormalizedResume;
+  facts: CandidateFact[];
+  inferences: CandidateInference[];
+}
+
+export interface EvidenceSpan { start: number; end: number; quote: string }
+export type CandidateFactKind = "skill" | "role" | "employer" | "date" | "outcome" | "experience_statement" | "project" | "project_statement" | "education" | "certification";
+export interface CandidateFact { id: string; kind: CandidateFactKind; value: string; evidence: EvidenceSpan[] }
+export type CandidateInference =
+  | { kind: "role_family"; value: "backend" | "frontend" | "data" | "infrastructure"; derivedFromFactIds: string[] }
+  | { kind: "seniority"; value: "intern" | "junior" | "mid" | "senior" | "lead" | "staff" | "principal" | "manager"; derivedFromFactIds: string[] }
+  | { kind: "transferable_skill"; value: "backend_programming" | "frontend_programming" | "data_engineering" | "cloud_infrastructure"; derivedFromFactIds: string[] }
+  | { kind: "approximate_experience_years"; value: number; derivedFromFactIds: string[] };
+export interface EvidenceValidationResult { valid: boolean; errors: string[] }
+
+export class ResumeInputError extends Error {
+  constructor(
+    readonly code: "unsupported_resume_format" | "invalid_resume_input",
+    message: string,
+    readonly format?: ResumeFormat,
+    readonly supportedFormats?: Array<"text" | "markdown">,
+  ) { super(message); }
+}
+
+export function parseCandidateProfile(input: unknown): CandidateProfile {
+  if (!isRecord(input) || typeof input.format !== "string" || typeof input.content !== "string") {
+    throw new ResumeInputError("invalid_resume_input", "Resume must contain text or Markdown content");
+  }
+  if (input.format === "pdf_base64" || input.format === "docx_base64") {
+    throw new ResumeInputError("unsupported_resume_format", `Resume format ${input.format} is not supported yet`, input.format, ["text", "markdown"]);
+  }
+  if (!(["text", "markdown"] as string[]).includes(input.format)) {
+    throw new ResumeInputError("invalid_resume_input", "Resume must contain text or Markdown content");
+  }
+  const text = normalizeResumeText(input.content);
+  if (!text.trim()) throw new ResumeInputError("invalid_resume_input", "Resume content must not be empty");
+  const facts = extractFacts(text);
+  return {
+    normalizedResume: { text, normalization: "openings-resume:v1", offsetEncoding: "utf16_code_units" },
+    facts,
+    inferences: deriveInferences(facts),
+  };
+}
+
+export function validateCandidateProfileEvidence(value: unknown): EvidenceValidationResult {
+  const errors: string[] = [];
+  if (!isRecord(value)) return { valid: false, errors: ["candidate profile must be an object"] };
+  const normalized = value.normalizedResume;
+  if (!isRecord(normalized) || typeof normalized.text !== "string" || normalized.normalization !== "openings-resume:v1" || normalized.offsetEncoding !== "utf16_code_units") {
+    errors.push("candidate profile has invalid normalized resume metadata");
+  }
+  if (!Array.isArray(value.facts)) errors.push("candidate profile facts must be an array");
+  if (!Array.isArray(value.inferences)) errors.push("candidate profile inferences must be an array");
+  if (errors.length) return { valid: false, errors };
+  const profile = value as unknown as CandidateProfile;
+  const validFactKinds = new Set<CandidateFactKind>(["skill", "role", "employer", "date", "outcome", "experience_statement", "project", "project_statement", "education", "certification"]);
+  for (const [index, fact] of profile.facts.entries()) {
+    if (!isRecord(fact) || typeof fact.id !== "string" || !validFactKinds.has(fact.kind as CandidateFactKind) || typeof fact.value !== "string" || !Array.isArray(fact.evidence)) {
+      errors.push(`fact ${index}: invalid fact shape`);
+      continue;
+    }
+    for (const evidence of fact.evidence) {
+      if (!isRecord(evidence) || !Number.isInteger(evidence.start) || !Number.isInteger(evidence.end) || typeof evidence.quote !== "string") errors.push(`${fact.id}: invalid evidence shape`);
+    }
+  }
+  for (const [index, inference] of profile.inferences.entries()) {
+    if (!isValidInference(inference)) errors.push(`inference ${index}: invalid inference shape`);
+  }
+  if (errors.length) return { valid: false, errors };
+  const ids = new Set<string>();
+  for (const fact of profile.facts) {
+    if (ids.has(fact.id)) errors.push(`${fact.id}: duplicate fact id`);
+    ids.add(fact.id);
+    if (!fact.evidence.length) errors.push(`${fact.id}: evidence is required`);
+    if (!fact.evidence.some((evidence) => evidence.quote === fact.value)) errors.push(`${fact.id}: fact value is not identical to its evidence`);
+    for (const evidence of fact.evidence) {
+      const validOffsets = Number.isInteger(evidence.start) && Number.isInteger(evidence.end) && evidence.start >= 0 && evidence.end > evidence.start && evidence.end <= profile.normalizedResume.text.length;
+      if (!validOffsets || profile.normalizedResume.text.slice(evidence.start, evidence.end) !== evidence.quote) errors.push(`${fact.id}: evidence span does not match normalized resume`);
+    }
+  }
+  for (const inference of profile.inferences) {
+    for (const factId of inference.derivedFromFactIds) if (!ids.has(factId)) errors.push(`${inference.kind}:${inference.value}: inference references missing fact ${factId}`);
+  }
+  if (JSON.stringify(profile.inferences) !== JSON.stringify(deriveInferences(profile.facts))) errors.push("candidate inferences do not match current facts");
+  return { valid: errors.length === 0, errors };
+}
+
+function isValidInference(value: unknown): value is CandidateInference {
+  if (!isRecord(value) || !Array.isArray(value.derivedFromFactIds) || !value.derivedFromFactIds.every((id) => typeof id === "string")) return false;
+  if (value.kind === "role_family") return ["backend", "frontend", "data", "infrastructure"].includes(value.value as string);
+  if (value.kind === "seniority") return ["intern", "junior", "mid", "senior", "lead", "staff", "principal", "manager"].includes(value.value as string);
+  if (value.kind === "transferable_skill") return ["backend_programming", "frontend_programming", "data_engineering", "cloud_infrastructure"].includes(value.value as string);
+  return value.kind === "approximate_experience_years" && typeof value.value === "number" && Number.isFinite(value.value) && value.value >= 0;
+}
+
+type RoleFamily = Extract<CandidateInference, { kind: "role_family" }>["value"];
+const roleSkills: Record<RoleFamily, Set<string>> = {
+  backend: new Set(["java", "go", "golang", "python", "node.js", "nodejs", "postgresql", "postgres", "sql", "spring", "django"]),
+  frontend: new Set(["javascript", "typescript", "react", "vue", "angular", "html", "css"]),
+  data: new Set(["pandas", "spark", "hadoop", "dbt", "airflow", "snowflake", "machine learning"]),
+  infrastructure: new Set(["aws", "azure", "gcp", "kubernetes", "docker", "terraform", "ansible"]),
+};
+
+function deriveInferences(facts: CandidateFact[]): CandidateInference[] {
+  const skills = facts.filter((fact) => fact.kind === "skill");
+  const inferences: CandidateInference[] = (Object.entries(roleSkills) as Array<[RoleFamily, Set<string>]>).flatMap(([value, vocabulary]) => {
+    const supporting = skills.filter((fact) => vocabulary.has(fact.value.toLowerCase()));
+    return supporting.length ? [{ kind: "role_family", value, derivedFromFactIds: supporting.map((fact) => fact.id) }] : [];
+  });
+  const roles = facts.filter((fact) => fact.kind === "role");
+  const seniorityOrder = ["manager", "principal", "staff", "lead", "senior", "junior", "intern"] as const;
+  for (const role of roles) {
+    const seniority = seniorityOrder.find((value) => new RegExp(`\\b${value}\\b`, "i").test(role.value));
+    if (seniority) inferences.push({ kind: "seniority", value: seniority, derivedFromFactIds: [role.id] });
+  }
+  const transferable: Array<[RoleFamily, Extract<CandidateInference, { kind: "transferable_skill" }>["value"]]> = [
+    ["backend", "backend_programming"], ["frontend", "frontend_programming"], ["data", "data_engineering"], ["infrastructure", "cloud_infrastructure"],
+  ];
+  for (const [family, value] of transferable) {
+    const supporting = skills.filter((fact) => roleSkills[family].has(fact.value.toLowerCase()));
+    if (supporting.length) inferences.push({ kind: "transferable_skill", value, derivedFromFactIds: supporting.map((fact) => fact.id) });
+  }
+  const dateFacts = facts.filter((fact) => fact.kind === "date");
+  const hasOpenInterval = dateFacts.some((fact) => /\b(?:present|current)\b/i.test(fact.value));
+  const intervals = dateFacts.flatMap((fact) => {
+    const years = [...fact.value.matchAll(/\b(?:19|20)\d{2}\b/g)].map((match) => Number(match[0]));
+    return years.length >= 2 && years[1]! >= years[0]! ? [{ start: years[0]!, end: years[1]!, fact }] : [];
+  }).sort((left, right) => left.start - right.start);
+  const merged: Array<{ start: number; end: number; facts: CandidateFact[] }> = [];
+  for (const interval of intervals) {
+    const previous = merged.at(-1);
+    if (previous && interval.start <= previous.end) {
+      previous.end = Math.max(previous.end, interval.end);
+      previous.facts.push(interval.fact);
+    } else merged.push({ start: interval.start, end: interval.end, facts: [interval.fact] });
+  }
+  if (merged.length && !hasOpenInterval) {
+    inferences.push({
+      kind: "approximate_experience_years",
+      value: merged.reduce((total, interval) => total + interval.end - interval.start, 0),
+      derivedFromFactIds: merged.flatMap((interval) => interval.facts.map((fact) => fact.id)),
+    });
+  }
+  return inferences;
+}
+
+type ResumeSection = "skills" | "experience" | "projects" | "education" | "certifications";
+const sectionNames = new Map<string, ResumeSection>([
+  ["skills", "skills"], ["technical skills", "skills"], ["core skills", "skills"], ["key skills", "skills"], ["professional skills", "skills"],
+  ["experience", "experience"], ["work experience", "experience"], ["professional experience", "experience"], ["relevant experience", "experience"],
+  ["employment", "experience"], ["employment history", "experience"], ["work history", "experience"], ["career history", "experience"], ["professional history", "experience"],
+  ["projects", "projects"], ["selected projects", "projects"], ["key projects", "projects"], ["key development projects", "projects"],
+  ["relevant projects", "projects"], ["personal projects", "projects"], ["technical projects", "projects"], ["academic projects", "projects"],
+  ["education", "education"],
+  ["certifications", "certifications"], ["certificates", "certifications"],
+]);
+const plainTextBoundaries = new Set([
+  "summary", "professional summary", "profile", "objective", "contact", "interests", "hobbies", "awards", "publications", "languages", "references",
+  "volunteer experience", "volunteering", "additional information", "personal information", "achievements", "activities",
+]);
+const skillCategoryLabels = new Set([
+  "languages", "programming languages", "frameworks", "libraries", "frameworks and libraries", "libraries and frameworks",
+  "databases", "tools", "cloud", "platforms", "technologies", "frontend", "front end", "front-end", "frontend technologies",
+  "backend", "back end", "back-end", "backend technologies", "devops", "devops tools", "testing", "testing tools",
+  "operating systems", "version control", "build tools", "messaging",
+]);
+// Standalone lines are ambiguous with real skills, so retain only the historically
+// supported, low-ambiguity headings here. The broader set is safe after a colon.
+const skillSubheadings = new Set(["languages", "programming languages", "frameworks", "databases", "tools", "cloud", "platforms", "technologies"]);
+
+function extractFacts(text: string): CandidateFact[] {
+  const facts: CandidateFact[] = [];
+  let section: ResumeSection | undefined;
+  let sectionLevel = 0;
+  let lineStart = 0;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    const markdownHeading = /^(#{1,6})\s+(.+)$/.exec(trimmed);
+    const heading = (markdownHeading?.[2] ?? trimmed).replace(/:$/, "").trim().toLowerCase();
+    const nextSection = sectionNames.get(heading);
+    if (nextSection) { section = nextSection; sectionLevel = markdownHeading?.[1]?.length ?? 0; }
+    else if (section === "skills" && skillSubheadings.has(heading)) { /* category label, not a fact */ }
+    else if (markdownHeading && section === "skills") section = undefined;
+    else if (markdownHeading && section && (sectionLevel === 0 || markdownHeading[1]!.length <= sectionLevel)) section = undefined;
+    else if (!markdownHeading && plainTextBoundaries.has(heading)) section = undefined;
+    else if (section && trimmed) facts.push(...factsFromLine(section, line, lineStart, Boolean(markdownHeading && markdownHeading[1]!.length > sectionLevel)));
+    lineStart += line.length + 1;
+  }
+  return facts;
+}
+
+function factsFromLine(section: ResumeSection, line: string, lineStart: number, isNestedHeading: boolean): CandidateFact[] {
+  const withoutPrefix = line.trimStart().replace(/^(?:#{1,6}\s+|[-*+]\s+|\d+[.)]\s+)/, "");
+  if (/^(?:ignore (?:all |any )?(?:previous |prior )?instructions?|do not|don't|never|pretend|claim|add|use)\b/i.test(withoutPrefix)) return [];
+  if (/\b(?:did not|was not|is not|expired|lapsed|revoked)\b/i.test(withoutPrefix)) return [];
+  if (section === "certifications" && /\b(?:inactive|pending|scheduled|planned|in progress|not yet)\b/i.test(withoutPrefix)) return [];
+  if (section === "skills" && /\b(?:no|not|without)\b/i.test(withoutPrefix)) return [];
+  const skillLabel = /^([^,:|]{1,30}):\s*/.exec(withoutPrefix);
+  const content = section === "skills" && skillLabel && skillCategoryLabels.has(skillLabel[1]!.trim().toLowerCase()) ? withoutPrefix.slice(skillLabel[0].length) : withoutPrefix;
+  const dateRange = /\b(?:(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\.?\s+)?(?:19|20)\d{2}\s*(?:—|–|-|to)\s*(?:(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\.?\s+)?(?:(?:19|20)\d{2}|present|current)\b/i.exec(content);
+  const dateFacts = section === "experience" && dateRange ? [factFromValue("date", dateRange[0], line, lineStart)] : [];
+  const roleContent = dateRange ? content.slice(0, dateRange.index).trimEnd() : content;
+  const roleSeparator = /\s+(?:—|–|-|\bat\b|\|)\s+/i.exec(roleContent);
+  const looksLikeRole = /\b(?:engineer|developer|architect|manager|analyst|scientist|designer|consultant|specialist|administrator|lead|director|intern)\b/i.test(roleContent);
+  const standaloneRoleWords = roleContent.trim().split(/\s+/);
+  const standaloneRole = standaloneRoleWords.length <= 7
+    && standaloneRoleWords.every((word) => /^(?:of|and|&)$/i.test(word) || /^[A-Z][A-Za-z0-9+.#/-]*$/.test(word))
+    && /\b(?:engineer|developer|architect|manager|analyst|scientist|designer|consultant|specialist|administrator|lead|director|intern)$/i.test(roleContent.trim());
+  if (section === "experience" && (isNestedHeading || standaloneRole || (roleSeparator && looksLikeRole))) {
+    if (roleSeparator) return [
+      ...optionalFact("role", roleContent.slice(0, roleSeparator.index).trim(), line, lineStart),
+      ...optionalFact("employer", roleContent.slice(roleSeparator.index + roleSeparator[0].length).trim(), line, lineStart),
+      ...dateFacts,
+    ];
+    return [factFromValue("role", roleContent, line, lineStart), ...dateFacts];
+  }
+  if (section === "projects" && isNestedHeading) return [factFromValue("project", content, line, lineStart)];
+  if (dateFacts.length) return dateFacts;
+  const measurable = /(?:\b\d+(?:\.\d+)?%|[$€£]\s?\d|\b\d+(?:\.\d+)?x\b|\b\d+\s?(?:ms|seconds?|minutes?|hours?|users?|requests?|transactions?)\b)/i.test(content);
+  if (section === "experience") return [factFromValue(measurable ? "outcome" : "experience_statement", content, line, lineStart)];
+  if (section === "projects") return [factFromValue(measurable ? "outcome" : "project_statement", content, line, lineStart)];
+  if (section === "education") return [factFromValue("education", content, line, lineStart)];
+  if (section === "certifications") return [factFromValue("certification", content, line, lineStart)];
+  const values = content.split(/[,;|]/).map((value) => value.trim()).filter(Boolean);
+  const kind: CandidateFactKind = "skill";
+  let searchFrom = 0;
+  return values.flatMap((value) => {
+    const relativeStart = line.indexOf(value, searchFrom);
+    if (relativeStart < 0) return [];
+    searchFrom = relativeStart + value.length;
+    const start = lineStart + relativeStart;
+    const end = start + value.length;
+    return [{ id: `fact_${kind}_${start}_${end}`, kind, value, evidence: [{ start, end, quote: value }] }];
+  });
+}
+
+function factFromValue(kind: CandidateFactKind, value: string, line: string, lineStart: number): CandidateFact {
+  const relativeStart = line.indexOf(value);
+  const start = lineStart + relativeStart;
+  const end = start + value.length;
+  return { id: `fact_${kind}_${start}_${end}`, kind, value, evidence: [{ start, end, quote: value }] };
+}
+
+function optionalFact(kind: CandidateFactKind, value: string, line: string, lineStart: number): CandidateFact[] {
+  return value ? [factFromValue(kind, value, line, lineStart)] : [];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+
+function normalizeResumeText(content: string): string {
+  return content
+    .replace(/^\uFEFF/, "")
+    .normalize("NFC")
+    .replace(/\r\n?/g, "\n")
+    .split("\n")
+    .map((line) => line.replace(/[\t ]+$/g, ""))
+    .join("\n")
+    .replace(/^\n+|\n+$/g, "");
+}