resuml 3.1.0 → 3.2.0

package/DOCS.md

@@ -8,6 +8,7 @@
 - [Installation](#installation)
 - [CLI commands and options](#cli-commands-and-options)
 - [ATS analysis](#ats-analysis)
+- [Job search](#job-search)
 - [Themes](#themes)
 - [Example YAML structure](#example-yaml-structure)
 - [CI/CD integration](#cicd-auto-build-on-push)
@@ -47,21 +48,32 @@ Requires Node.js ≥ 20 and npm ≥ 10.
 | `pdf`            | Render to PDF                                       |
 | `dev`            | Dev server with hot-reload                          |
 | `mcp`            | Start the MCP server for AI agents                  |
+| `jobs search`    | Discover and rank job postings from free sources    |
+| `jobs score`     | Score a single posting against your resume          |
+| `jobs tailor`    | Generate a tailoring prompt for a posting           |
 
 ### Options
 
 | Option            | Alias | Description                                  |
 | ----------------- | ----- | -------------------------------------------- |
-| `--resume`        | `-r`  | Input YAML file(s) or directory              |
-| `--output`        | `-o`  | Output file path                             |
-| `--theme`         | `-t`  | Theme name                                   |
-| `--port`          | `-p`  | Dev server port (default: 3000)              |
-| `--language`      |       | Locale (default: `en`)                       |
-| `--debug`         |       | Detailed errors                              |
-| `--ats`           |       | Run ATS analysis (with `validate`)           |
-| `--jd`            |       | Path to job description file (with `--ats`)  |
-| `--ats-threshold` |       | Minimum score (0-100); exits 1 if below      |
-| `--format`        |       | Output format for validate: `text` or `json` |
+| `--resume`        | `-r`  | Input YAML file(s) or directory                                          |
+| `--output`        | `-o`  | Output file path                                                         |
+| `--theme`         | `-t`  | Theme name                                                               |
+| `--port`          | `-p`  | Dev server port (default: 3000)                                          |
+| `--language`      |       | Locale (default: `en`)                                                   |
+| `--debug`         |       | Detailed errors                                                          |
+| `--ats`           |       | Run ATS analysis (with `validate`)                                       |
+| `--jd`            |       | Path to job description file (with `--ats`)                              |
+| `--ats-threshold` |       | Minimum score (0-100); exits 1 if below                                  |
+| `--format`        |       | Output format for validate: `text` or `json`                             |
+| `--location`      |       | Override candidate location as `"City, CC"` (with `jobs search`)        |
+| `--min-score`     |       | Minimum ATS score for results (default 85, with `jobs search`)           |
+| `--limit`         |       | Max postings returned after ranking (default 20, with `jobs search`)     |
+| `--providers`     |       | Comma-separated provider list (with `jobs search`)                       |
+| `--remote`        |       | Restrict to remote-friendly postings (with `jobs search`)                |
+| `--posting`       |       | Posting YAML/JSON file for `jobs score` / `jobs tailor`                  |
+| `--body`          |       | Posting body text; use `-` for stdin (with `jobs tailor`)                |
+| `--json`          |       | Machine-readable JSON output (with `jobs search`, `score`, `tailor`)     |
 
 ### Quick start
 
@@ -141,6 +153,49 @@ Supports English and German (language-specific action verbs and pronouns). Use `
 resuml validate --resume lebenslauf.yaml --ats --language de
 ```
 
+## Job search
+
+Discover, score, and tailor job postings against your resume — all offline, no API keys.
+
+```bash
+# Search free job sources and rank results against your resume (default minScore: 85)
+resuml jobs search -r resume.yaml
+
+# Filter to remote-friendly postings in your country
+resuml jobs search -r resume.yaml --remote --location "Zürich, CH"
+
+# Score a single posting (full per-tier ATS breakdown)
+resuml jobs score -r resume.yaml --posting posting.yaml
+
+# Generate a tailoring prompt for a posting (pipe output to Claude)
+resuml jobs tailor --posting posting.yaml
+resuml jobs tailor --body - < jd.txt   # read body from stdin
+
+# Machine-readable output
+resuml jobs search -r resume.yaml --json
+```
+
+### Posting file format (`--posting posting.yaml`)
+
+```yaml
+company: Acme Corp
+title: Senior Backend Engineer
+url: https://acme.com/jobs/123
+body: |
+  We are looking for a backend engineer with 5+ years of experience...
+location: Berlin, DE   # optional
+remote: false          # optional
+```
+
+### How search works
+
+1. Derives a query from your resume (seniority, top skills, location).
+2. Fetches postings from free sources in parallel (Greenhouse, Lever, Ashby, Workable, RemoteOK, WWR, Remotive, HN Who's Hiring).
+3. Drops on-site postings in the wrong country when `--location` is set.
+4. Scores every posting with the full ATS engine; dedupes by `(company, title, location)`.
+5. Removes postings below `--min-score` (default 85) and caps to `--limit` (default 20).
+6. Off-specialty roles (e.g. a backend JD for a frontend CV) are capped at 45 and filtered out automatically.
+
 ## Themes
 
 resuml supports any `jsonresume-theme-*` package from npm. Install a theme, then pass its name to `--theme`:
@@ -277,14 +332,18 @@ Claude Code will:
 
 ### Tools
 
-| Tool                 | Purpose                                             |
-| -------------------- | --------------------------------------------------- |
-| `resuml_init_resume` | Generate a starter YAML template                    |
-| `resuml_validate`    | Validate resume YAML against the JSON Resume schema |
-| `resuml_ats_check`   | ATS analysis + JD keyword matching                  |
-| `resuml_render`      | Render to HTML using a theme (supports `locale`)    |
-| `resuml_list_themes` | List available themes and install status            |
-| `resuml_export_pdf`  | Export as PDF (supports `margin`, `locale`)         |
+| Tool                   | Purpose                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `resuml_init_resume`   | Generate a starter YAML template                                                |
+| `resuml_validate`      | Validate resume YAML against the JSON Resume schema                             |
+| `resuml_ats_check`     | Tiered ATS analysis (Parsing / Match / Recruiter) with knockout signals         |
+| `resuml_ats_explain`   | Return the rubric entry for a specific check id                                 |
+| `resuml_render`        | Render to HTML using a theme (supports `locale`)                                |
+| `resuml_list_themes`   | List available themes and install status                                        |
+| `resuml_export_pdf`    | Export as PDF (supports `margin`, `locale`)                                     |
+| `resuml_jobs_search`   | Discover and rank job postings from free sources against the resume             |
+| `resuml_jobs_score`    | Score a single job posting against the resume; returns full ATS breakdown       |
+| `resuml_jobs_tailor`   | Build a tailoring prompt for a specific posting (returns prompt text)           |
 
 ### Resources
 

package/README.md

@@ -72,6 +72,11 @@ npm install -g jsonresume-theme-stackoverflow
 resuml validate --resume resume.yaml --ats --jd job.txt
 resuml render   --resume resume.yaml --theme stackoverflow --output resume.html
 resuml pdf      --resume resume.yaml --theme stackoverflow --output resume.pdf
+
+# discover and rank job postings from free sources
+resuml jobs search --resume resume.yaml --location "Zürich, CH"
+resuml jobs score  --resume resume.yaml --posting posting.yaml
+resuml jobs tailor --posting posting.yaml
 ```
 
 `resuml pdf` and snapshot rendering need Playwright. Install it once with `npm install -g playwright` (it's an optional peer dep so the base install stays slim).

package/data/jobs/companies.json

@@ -0,0 +1,76 @@
+{
+  "_comment": "Seed allowlists for ATS-direct providers. Slugs are the board-id segment of each company's public ATS URL. Curated from public job boards as of 2026-05. Add to this list via the --extra-companies CLI flag or extraCompanies SearchOption.",
+  "greenhouse": [
+    "airbnb",
+    "stripe",
+    "anthropic",
+    "openai",
+    "datadog",
+    "discord",
+    "duolingo",
+    "elastic",
+    "figma",
+    "gitlab",
+    "instacart",
+    "linear",
+    "lyft",
+    "mongodb",
+    "notion",
+    "nubank",
+    "pinterest",
+    "plaid",
+    "ramp",
+    "reddit",
+    "robinhood",
+    "samsara",
+    "scaleai",
+    "snowflake",
+    "squareup",
+    "twilio",
+    "vercel",
+    "wise",
+    "zapier"
+  ],
+  "lever": [
+    "netflix",
+    "spotify",
+    "shopify",
+    "github",
+    "palantir",
+    "asana",
+    "intercom",
+    "kraken",
+    "leetcode",
+    "miro",
+    "patreon",
+    "showpad",
+    "thumbtack"
+  ],
+  "ashby": [
+    "ashbyhq",
+    "openai",
+    "anthropic",
+    "ramp",
+    "linear",
+    "vercel",
+    "posthog",
+    "modal",
+    "replicate",
+    "perplexity",
+    "supabase",
+    "huggingface",
+    "ironclad",
+    "warp",
+    "writer"
+  ],
+  "workable": [
+    "deliveroo",
+    "getyourguide",
+    "n26",
+    "personio",
+    "celonis",
+    "tier",
+    "wefox",
+    "blinkist"
+  ]
+}

package/dist/ats/index.d.ts

@@ -1,83 +1,7 @@
 import { Resume as ResumeSchema } from '../types/index.js';
-
-type Tier = 'parsing' | 'match' | 'recruiter';
-type AtsCheckWeight = 'high' | 'medium' | 'low';
-type AtsRating = 'excellent' | 'good' | 'needs-work' | 'poor';
-type CheckStatus = 'pass' | 'warn' | 'fail' | 'skipped';
-type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
-interface CheckResult {
-    id: string;
-    tier: Tier;
-    status: CheckStatus;
-    score: number;
-    weight: AtsCheckWeight;
-    message: string;
-    hints: string[];
-}
-interface TierResult {
-    score: number;
-    grade: Grade;
-    checks: CheckResult[];
-}
-interface KnockoutSignal {
-    signal: string;
-    evidence: string;
-    recommendation: string;
-}
-interface TieredAtsResult {
-    score: number;
-    rating: AtsRating;
-    tiers: {
-        parsing: TierResult;
-        match?: TierResult;
-        recruiter: TierResult;
-    };
-    knockouts: KnockoutSignal[];
-    summary: string;
-}
-interface AtsOptions {
-    language?: string;
-    jobDescription?: string;
-    threshold?: number;
-    config?: AtsConfig;
-}
-interface AtsConfig {
-    weights: {
-        tiers: {
-            parsing: number;
-            match: number;
-            recruiter: number;
-        };
-        checks: Record<string, AtsCheckWeight>;
-    };
-    thresholds: {
-        rating: {
-            excellent: number;
-            good: number;
-            needsWork: number;
-        };
-        grade: {
-            A: number;
-            B: number;
-            C: number;
-            D: number;
-        };
-        seniorYoeCutoff: number;
-        wordCount: {
-            min: number;
-            max: number;
-            seniorMax: number;
-        };
-        bulletsPerRole: {
-            min: number;
-            max: number;
-            seniorMax: number;
-        };
-    };
-    disable: string[];
-    locale: string;
-}
+import { A as AtsOptions, T as TieredAtsResult } from '../types-B_jASYU4.js';
+export { C as CheckResult, K as KnockoutSignal, a as TierResult } from '../types-B_jASYU4.js';
 
 declare function analyzeAts(resume: ResumeSchema, options?: AtsOptions): TieredAtsResult;
 
-export { type AtsOptions, type CheckResult, type KnockoutSignal, type TierResult, type TieredAtsResult, analyzeAts };
+export { AtsOptions, TieredAtsResult, analyzeAts };

package/dist/ats/index.js

@@ -1,6 +1,6 @@
 import {
   analyzeAts
-} from "../chunk-N55EPZ2N.js";
+} from "../chunk-C2JG5KF4.js";
 import "../chunk-QR77BRMN.js";
 export {
   analyzeAts

package/dist/{chunk-N55EPZ2N.js → chunk-C2JG5KF4.js}

@@ -1430,6 +1430,176 @@ function matchJobDescription(resume, jobDescription, _language = "en") {
   return { matched, missing, extra, matchPercentage };
 }
 
+// src/ats/roleFamily.ts
+var SIGNATURES = {
+  engineering: [
+    "software engineer",
+    "engineer",
+    "developer",
+    "programmer",
+    "swe",
+    "backend",
+    "back-end",
+    "frontend",
+    "front-end",
+    "full stack",
+    "full-stack",
+    "devops",
+    "sre",
+    "site reliability",
+    "software development",
+    "microservices",
+    "codebase"
+  ],
+  data: [
+    "data scientist",
+    "data engineer",
+    "machine learning",
+    "ml engineer",
+    "data analyst",
+    "analytics engineer",
+    "mlops"
+  ],
+  design: [
+    "designer",
+    "ux ",
+    "ui designer",
+    "product design",
+    "graphic design",
+    "visual design",
+    "user research"
+  ],
+  product: ["product manager", "product owner", "program manager", "product management"],
+  recruiting: [
+    "recruiter",
+    "recruiting",
+    "recruitment",
+    "talent acquisition",
+    "sourcer",
+    "sourcing",
+    "full-cycle recruiting",
+    "candidate experience",
+    "hiring manager",
+    "people ops",
+    "human resources"
+  ],
+  sales: [
+    "account executive",
+    "business development",
+    "sales development",
+    "sales representative",
+    "quota",
+    "sdr",
+    "bdr"
+  ],
+  marketing: [
+    "marketing",
+    "growth marketing",
+    "demand generation",
+    "content marketing",
+    "brand manager",
+    "seo"
+  ],
+  legal: ["legal counsel", "attorney", "paralegal", "lawyer", "litigation", "general counsel"],
+  finance: ["accountant", "accounting", "controller", "fp&a", "financial analyst", "bookkeeping"],
+  support: [
+    "customer support",
+    "customer success",
+    "support specialist",
+    "technical support",
+    "help desk"
+  ],
+  operations: ["operations manager", "business operations", "supply chain", "logistics"]
+};
+var FAMILIES = Object.keys(SIGNATURES);
+function countOccurrences(haystack, needle) {
+  let count = 0;
+  let idx = haystack.indexOf(needle);
+  while (idx !== -1) {
+    count++;
+    idx = haystack.indexOf(needle, idx + needle.length);
+  }
+  return count;
+}
+function classifyRoleFamily(body, title = "") {
+  const b = body.toLowerCase();
+  const t = title.toLowerCase();
+  const scores = FAMILIES.map((family) => {
+    let score = 0;
+    for (const sig of SIGNATURES[family]) {
+      score += countOccurrences(b, sig);
+      score += countOccurrences(t, sig) * 3;
+    }
+    return { family, score };
+  }).sort((a, b2) => b2.score - a.score);
+  const top = scores[0];
+  const second = scores[1];
+  if (!top || top.score < 2) return null;
+  const margin = top.score - (second?.score ?? 0);
+  if (margin < 1) return null;
+  return { family: top.family, score: top.score, margin };
+}
+var SPECIALTY_SIGNATURES = {
+  frontend: ["frontend", "front-end", "front end", "react", "vue", "angular", "css", "ui engineer", "web developer", "design system"],
+  backend: ["backend", "back-end", "back end", "server-side", "microservices", "api development", "distributed systems"],
+  security: ["security", "appsec", "application security", "infosec", "penetration", "vulnerability", "secure coding", "cryptography", "threat"],
+  ml: ["machine learning", "ml engineer", "deep learning", "nlp", "computer vision", "ai engineer", "pytorch", "tensorflow"],
+  mobile: ["ios engineer", "android engineer", "mobile engineer", "swift", "kotlin", "react native", "flutter"],
+  devops: ["devops", "sre", "site reliability", "platform engineer", "kubernetes", "terraform", "infrastructure engineer"],
+  data: ["data engineer", "etl", "data pipeline", "spark", "hadoop", "data warehouse"],
+  embedded: ["embedded", "firmware", "rtos", "microcontroller", "bare metal"],
+  qa: ["qa engineer", "test engineer", "sdet", "automation testing", "quality assurance"]
+};
+var SPECIALTIES = Object.keys(SPECIALTY_SIGNATURES);
+function classifySpecialty(body, title = "") {
+  const b = body.toLowerCase();
+  const t = title.toLowerCase();
+  const scores = SPECIALTIES.map((sp) => {
+    let score = 0;
+    for (const sig of SPECIALTY_SIGNATURES[sp]) {
+      score += countOccurrences(b, sig);
+      score += countOccurrences(t, sig) * 3;
+    }
+    return { sp, score };
+  }).sort((a, b2) => b2.score - a.score);
+  const top = scores[0];
+  const second = scores[1];
+  if (!top || top.score < 2) return null;
+  if (top.score - (second?.score ?? 0) < 1) return null;
+  return top.sp;
+}
+var SPECIALTY_MIN_SCORE = 4;
+var TOP_MARGIN_FACTOR = 0.5;
+var SPECIALTY_ABS_MARGIN = 3;
+function resumeSpecialties(resume) {
+  const text = resumeRoleText(resume).toLowerCase();
+  const scored = SPECIALTIES.map((sp) => {
+    let score = 0;
+    for (const sig of SPECIALTY_SIGNATURES[sp]) score += countOccurrences(text, sig);
+    return { sp, score };
+  }).sort((a, b) => b.score - a.score);
+  const top = scored[0];
+  if (!top || top.score < SPECIALTY_MIN_SCORE) return [];
+  const margin = Math.min(SPECIALTY_ABS_MARGIN, Math.max(TOP_MARGIN_FACTOR * top.score, 1));
+  const threshold = top.score - margin;
+  return scored.filter((s) => s.score >= threshold).map((s) => s.sp);
+}
+function resumeRoleText(resume) {
+  const parts = [];
+  if (resume.basics?.label) parts.push(resume.basics.label);
+  if (resume.basics?.summary) parts.push(resume.basics.summary);
+  for (const w of resume.work ?? []) {
+    if (w.position) parts.push(w.position);
+    if (w.summary) parts.push(w.summary);
+    parts.push(...w.highlights ?? []);
+  }
+  for (const s of resume.skills ?? []) {
+    if (s.name) parts.push(s.name);
+    parts.push(...s.keywords ?? []);
+  }
+  return parts.join(" ");
+}
+
 // src/ats/checks/match.ts
 var SENIORITY = /\b(junior|senior|lead|staff|principal|head of|vp|chief)\b/gi;
 var STOPWORDS = /* @__PURE__ */ new Set([
@@ -1470,7 +1640,7 @@ function extractJdTitle(jd) {
   );
   return fallback ? trimTitle(fallback) : void 0;
 }
-var titleAlignment = (resume, _l, { jobDescription }) => {
+var titleAlignment = (resume, _l, { jobDescription, jobTitle }) => {
   if (!jobDescription) {
     return {
       id: "title-alignment",
@@ -1483,16 +1653,16 @@ var titleAlignment = (resume, _l, { jobDescription }) => {
     };
   }
   const resumeTitle = resume.work?.[0]?.position || resume.basics?.label;
-  const jdTitle = extractJdTitle(jobDescription);
+  const jdTitle = jobTitle?.trim() ? trimTitle(jobTitle) : extractJdTitle(jobDescription);
   if (!resumeTitle || !jdTitle) {
     return {
       id: "title-alignment",
       tier: "match",
       weight: "high",
-      status: "warn",
-      score: 50,
-      message: "Could not extract title from JD or resume.",
-      hints: ["Set basics.label to your target title."]
+      status: "skipped",
+      score: 0,
+      message: "Could not extract a title from the JD or resume.",
+      hints: ["Set basics.label to your target title, or supply the posting title."]
     };
   }
   const j = jaccard(tokenize(resumeTitle), tokenize(jdTitle));
@@ -1618,7 +1788,81 @@ var hardSkillOverlap = (resume, language, { jobDescription }) => {
     hints: status === "pass" ? [] : km.missing.slice(0, 5).map((s) => `Add evidence of "${s}" to skills/highlights.`)
   };
 };
-var allMatchChecks = [hardSkillOverlap, titleAlignment, educationLevel, yoeMatch];
+var roleFamilyMatch = (resume, _l, { jobDescription, jobTitle }) => {
+  if (!jobDescription) {
+    return {
+      id: "role-family-match",
+      tier: "match",
+      weight: "high",
+      status: "skipped",
+      score: 0,
+      message: "No JD.",
+      hints: []
+    };
+  }
+  const jd = classifyRoleFamily(jobDescription, jobTitle ?? "");
+  const cv = classifyRoleFamily(resumeRoleText(resume));
+  if (!jd || !cv) {
+    return {
+      id: "role-family-match",
+      tier: "match",
+      weight: "high",
+      status: "skipped",
+      score: 0,
+      message: "Could not confidently classify the role family of the JD or resume.",
+      hints: []
+    };
+  }
+  if (jd.family !== cv.family) {
+    return {
+      id: "role-family-match",
+      tier: "match",
+      weight: "high",
+      status: "fail",
+      score: 0,
+      message: `Role mismatch: ${cv.family} resume vs ${jd.family} role.`,
+      hints: [
+        `This posting reads as a ${jd.family} role; your resume reads as ${cv.family}. Likely not a fit.`
+      ]
+    };
+  }
+  if (cv.family === "engineering") {
+    const jdSpec = classifySpecialty(jobDescription, jobTitle ?? "");
+    if (jdSpec) {
+      const cvTopSpecs = resumeSpecialties(resume);
+      const satisfied = cvTopSpecs.length === 0 || cvTopSpecs.includes(jdSpec);
+      if (!satisfied) {
+        return {
+          id: "role-family-match",
+          tier: "match",
+          weight: "high",
+          status: "fail",
+          score: 0,
+          message: `Specialty mismatch: ${jdSpec} role, resume specializes in ${cvTopSpecs[0] ?? "general engineering"}.`,
+          hints: [
+            `This is a ${jdSpec} engineering role; your resume doesn't show ${jdSpec} depth. Likely not a fit.`
+          ]
+        };
+      }
+    }
+  }
+  return {
+    id: "role-family-match",
+    tier: "match",
+    weight: "high",
+    status: "pass",
+    score: 100,
+    message: `Role family aligned (${cv.family}).`,
+    hints: []
+  };
+};
+var allMatchChecks = [
+  hardSkillOverlap,
+  titleAlignment,
+  roleFamilyMatch,
+  educationLevel,
+  yoeMatch
+];
 var KNOCKOUTS = [
   {
     signal: "work-auth",
@@ -1807,19 +2051,26 @@ function analyzeAts(resume, options = {}) {
   const recruiter = buildTier("recruiter", recruiterChecks, cfg);
   let match;
   let knockouts = [];
+  let roleMismatch = false;
   if (options.jobDescription) {
     const matchChecks = allMatchChecks.map(
-      (fn) => fn(resume, language, { jobDescription: options.jobDescription })
+      (fn) => fn(resume, language, { jobDescription: options.jobDescription, jobTitle: options.jobTitle })
     );
     match = buildTier("match", matchChecks, cfg);
+    roleMismatch = matchChecks.some(
+      (c) => c.id === "role-family-match" && c.status === "fail"
+    );
     knockouts = extractKnockouts(resume, options.jobDescription);
   }
-  const totalScore = computeTotalScore(
+  let totalScore = computeTotalScore(
     { parsing: parsing.score, match: match?.score, recruiter: recruiter.score },
     cfg.weights.tiers
   );
+  const capped = roleMismatch && totalScore > ROLE_MISMATCH_CAP;
+  if (capped) totalScore = ROLE_MISMATCH_CAP;
   const rating = scoreToRating(totalScore, cfg.thresholds.rating);
-  const summary = generateSummary(totalScore, rating, !!options.jobDescription, knockouts.length);
+  let summary = generateSummary(totalScore, rating, !!options.jobDescription, knockouts.length);
+  if (capped) summary += " Score capped: resume role family does not match this posting.";
   return {
     score: totalScore,
     rating,
@@ -1828,9 +2079,10 @@ function analyzeAts(resume, options = {}) {
     summary
   };
 }
+var ROLE_MISMATCH_CAP = 45;
 
 export {
   loadConfig,
   analyzeAts
 };
-//# sourceMappingURL=chunk-N55EPZ2N.js.map
+//# sourceMappingURL=chunk-C2JG5KF4.js.map