openings 0.1.35 → 0.1.37

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Find evidence-grounded jobs, including relevant roles you may not have searched for, without accounts or API keys.",
   "author": { "name": "Openings contributors" },
   "license": "MIT",

package/README.md

@@ -61,7 +61,7 @@ The [job-seeker quickstart](docs/job-seeker-quickstart.md) has sample prompts, a
 | `recommend_jobs` | Ranks jobs against a resume and explicit intent. Returns direct, hidden, and stretch results with evidence. Performs at most one scoped refresh; `refresh.policy: "never"` guarantees no crawl. |
 | `analyze_job_fit` | Explains one job against verbatim resume evidence: supported, transferable, unsupported, and screening risks. |
 | `optimize_resume` | Proposes grounded suggestions, an additive diff, or revised Markdown. Never invents experience. |
-| `search_jobs` | Plain keyword, location, country, and remote search over the index, newest first. `country` takes a two-letter code such as `IN`; `maxAgeDays` keeps only roles posted within that window. |
+| `search_jobs` | Resume-free keyword, location, country, remote, and stated-experience search, newest first. `country` takes a two-letter code such as `IN`. Optional `experienceYears` compares stated min/max ranges, excluding unknowns unless `includeUnknownExperience: true`. Results include `pagination.total` and `pagination.nextOffset`; request the next page with that `offset`, unchanged filters, and `maxAgeDays` set to the returned `window.daysUsed`. Restart pagination after index refresh; this is not a frozen snapshot cursor. Without `maxAgeDays`, search widens through 7/14/30/all days until at least five results exist. |
 | `get_job` | Returns one job with its full description. |
 
 There is deliberately no form-fill, apply, or submit tool. The only thing Openings writes is your own job index.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "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/skills/openings/SKILL.md

@@ -12,8 +12,8 @@ Use `prepare_job_search` to bootstrap the private local index and set honest cou
 ## 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.
+2. Ask only for missing constraints that materially change the search. Search immediately with `search_jobs` when role and country are known; do not require or repeatedly request a resume. Use `experienceYears` only when supplied, explain that it compares stated posting ranges, and offer `includeUnknownExperience` when strict results are thin. Unknown experience is not proof of fit or a gap. To show another page, keep the filters, set `maxAgeDays` to the returned `window.daysUsed`, and use `pagination.nextOffset`; restart after an index refresh.
+3. Offer resume matching as optional. When the user chooses it, supply their 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.

package/src/catalog.ts

@@ -2,6 +2,7 @@ import { CASCADE_MINIMUM, CASCADE_WINDOWS, type Company, type Job, type JobAge,
 import { decodeEntities, providerSpec, type JsonGet } from "./providers.ts";
 import { crawlSite, sitePostingsToJobs } from "./jobposting-site.ts";
 import { classifyJob, isEligibleForCountry, normalizeLocation } from "./locations.ts";
+import { experienceMatches, normalizeJobExperience } from "./experience.ts";
 
 type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
 
@@ -101,13 +102,13 @@ export function createCatalog(options: CatalogOptions): Catalog {
       let job = (await fetchJobs(company)).find((candidate) => candidate.id === id) ?? null;
       if (job && !job.description.trim()) job = { ...job, description: await fetchJobDescription(company, job, fetcher) };
       if (job && !job.description.trim()) throw new Error(`Full description unavailable for job: ${id}`);
-      return job;
+      return job ? normalizeJobExperience(job) : null;
     },
   };
 }
 
 export const DEFAULT_MAX_AGE_DAYS = 30;
-export type SearchResult = JobSummary[] & { window?: SearchWindow };
+export type SearchResult = JobSummary[] & { window?: SearchWindow; pagination?: { offset: number; limit: number; total: number; nextOffset: number | null } };
 
 /** One window: dated jobs inside it; 0 means everything including undated. */
 export function withinWindow(job: Pick<Job, "updatedAt">, days: number, now: number): boolean {
@@ -118,8 +119,12 @@ export function withinWindow(job: Pick<Job, "updatedAt">, days: number, now: num
 
 /** Keyword search newest first. Without maxAgeDays it walks 7, 14, 30, then everything until CASCADE_MINIMUM results appear; the window used rides on the result. */
 export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.now()): SearchResult {
-  const matched = jobs.filter((job) => matches(job, query));
-  const run = (days: number) => matched.filter((job) => withinWindow(job, days, now)).sort((left, right) => postedTime(right) - postedTime(left));
+  const matched = jobs.filter((job) => matches(job, query)).map(normalizeJobExperience).filter((job) => {
+    if (query.experienceYears === undefined) return true;
+    const experience = job.experience;
+    return experience ? experienceMatches(experience, query.experienceYears) : query.includeUnknownExperience === true;
+  });
+  const run = (days: number) => matched.filter((job) => withinWindow(job, days, now)).sort((left, right) => postedTime(right) - postedTime(left) || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
   const steps: SearchWindow["steps"] = [];
   let found: Job[] = [];
   for (const days of query.maxAgeDays !== undefined ? [query.maxAgeDays] : CASCADE_WINDOWS) {
@@ -127,7 +132,9 @@ export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.n
     steps.push({ days, results: found.length });
     if (found.length >= CASCADE_MINIMUM) break;
   }
-  const result = found.slice(0, query.limit ?? 50).map((job) => toSummary(job, now)) as SearchResult;
+  const offset = query.offset ?? 0, limit = query.limit ?? 50;
+  const result = found.slice(offset, offset + limit).map((job) => toSummary(job, now)) as SearchResult;
+  Object.defineProperty(result, "pagination", { value: { offset, limit, total: found.length, nextOffset: offset + limit < found.length ? offset + limit : null }, enumerable: false });
   Object.defineProperty(result, "window", { value: { daysUsed: steps[steps.length - 1]!.days, widened: steps.length > 1, steps } satisfies SearchWindow, enumerable: false });
   return result;
 }

package/src/crawler.ts

@@ -1,5 +1,5 @@
 import type { FetchJobsObserver } from "./catalog.ts";
-import { statedExperience } from "./experience.ts";
+import { EXPERIENCE_VERSION, normalizeJobExperience } from "./experience.ts";
 import { partitionFor, type Company, type CrawlFailure, type CrawlReport, type CrawlSourceResult, type Job, type JobPartition, type JobSnapshot } from "./types.ts";
 
 export interface SnapshotStore {
@@ -49,23 +49,22 @@ export function createCrawler(options: CrawlerOptions): Crawler {
 
   /** Required experience for every job: from its description, the last crawl's reading, or a paced detail fetch for recent roles in describeCountries. */
   async function withExperience(source: Company, jobs: Job[], previous: Job[] | undefined): Promise<Job[]> {
-    const known = new Map((previous ?? []).filter((job) => job.experience !== undefined).map((job) => [job.id, job.experience]));
+    const known = new Map((previous ?? []).map(normalizeJobExperience).filter((job) => job.experienceVersion === EXPERIENCE_VERSION && job.experience !== undefined).map((job) => [job.id, job]));
     const since = now().getTime() - 30 * 86_400_000;
     const deadline = Date.now() + DESCRIBE_BUDGET_MS;
     let budget = DESCRIBE_LIMIT;
     const out: Job[] = [];
     for (const job of jobs) {
-      if (job.experience !== undefined) out.push(job);
-      else if (job.description.trim()) out.push({ ...job, experience: statedExperience(job.description) });
-      else if (known.has(job.id)) out.push({ ...job, experience: known.get(job.id) });
+      if (job.description.trim() || job.experienceVersion === EXPERIENCE_VERSION) out.push(normalizeJobExperience(job));
+      else if (known.has(job.id)) out.push({ ...job, description: known.get(job.id)!.description, experience: known.get(job.id)!.experience, experienceVersion: EXPERIENCE_VERSION });
       else if (options.describe && budget > 0 && Date.now() < deadline && job.eligibleCountries.some((code) => describeCountries.has(code)) && Date.parse(job.updatedAt ?? "") >= since) {
         budget -= 1;
         try {
           if (options.workdayPageDelayMs) await pacingSleep(options.workdayPageDelayMs);
           const description = await options.describe(source, job);
-          out.push(description.trim() ? { ...job, experience: statedExperience(description) } : job);
-        } catch { out.push(job); } // unread; the next crawl tries again
-      } else out.push(job);
+          out.push(normalizeJobExperience({ ...job, description }));
+        } catch { out.push(normalizeJobExperience(job)); } // unread; the next crawl tries again
+      } else out.push(normalizeJobExperience(job));
     }
     return out;
   }

package/src/experience.ts

@@ -1,7 +1,8 @@
-import { decodeEntities } from "./providers.ts";
+import { plainText } from "./providers.ts";
 
 /** Years of experience a posting asks for, read from its own text. */
-export interface Experience { min: number; max?: number }
+export interface Experience { min: number; max?: number; maxOpen?: boolean }
+export const EXPERIENCE_VERSION = 2;
 
 const WORDS: Record<string, number> = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10, twelve: 12, fifteen: 15 };
 const NUM = String.raw`(\d{1,2}(?:\.\d)?|${Object.keys(WORDS).join("|")})`;
@@ -11,6 +12,7 @@ const YEARS_THEN_EXPERIENCE = new RegExp(String.raw`${RANGE}(?:\s+of)?(?:\s+[\w/
 const EXPERIENCE_THEN_YEARS = new RegExp(String.raw`\b(?:experiences?|exp)\b[^.\n\d]{0,30}?${RANGE}`, "gi");
 // "minimum 15+ years" with no word "experience" after it.
 const MINIMUM_YEARS = new RegExp(String.raw`\b(?:minimum|min\.?|at least|atleast)\s*(?:of\s*)?${RANGE}`, "gi");
+const STANDALONE_YEARS = new RegExp(String.raw`^[ \t]*(?:[•·-][ \t]*)?${RANGE}[ \t]*[.!]?[ \t]*$`, "gmi");
 // Company history reads the same way ("our 135 years of experience"); skip matches that talk about the employer.
 const ABOUT_EMPLOYER = /\b(?:our (?:company|firm|group|organi[sz]ation|brands?|history|legacy)|(?:company|firm|group) (?:has|with)|founded|established|history|legacy|heritage)\b[^.\n?!:;•·-]*$/i;
 const MIN_PREFIX = /\b(?:minimum|min\.?|at least|atleast)\s*(?:of\s*)?$/i;
@@ -20,11 +22,15 @@ function value(text: string | undefined): number | undefined {
   return WORDS[text.toLowerCase()] ?? Number(text);
 }
 
-/** The first experience requirement the text states, or null when it states none. */
+/** Prefer overall/total experience and standalone role ranges to skill-specific requirements. */
 export function statedExperience(description: string): Experience | null {
-  const text = decodeEntities(description);
-  const found: Array<{ index: number; experience: Experience }> = [];
-  for (const pattern of [YEARS_THEN_EXPERIENCE, EXPERIENCE_THEN_YEARS, MINIMUM_YEARS]) {
+  return readExperience(description)?.experience ?? null;
+}
+
+export function readExperience(description: string): { index: number; quote: string; priority: number; experience: Experience } | null {
+  const text = plainText(description);
+  const found: Array<{ index: number; quote: string; priority: number; experience: Experience }> = [];
+  for (const pattern of [YEARS_THEN_EXPERIENCE, EXPERIENCE_THEN_YEARS, MINIMUM_YEARS, STANDALONE_YEARS]) {
     for (const match of text.matchAll(pattern)) {
       const [low, high] = [value(match[1]), value(match[2])];
       if (low === undefined || !Number.isFinite(low)) continue;
@@ -32,11 +38,15 @@ export function statedExperience(description: string): Experience | null {
       if (low > 20 || (high !== undefined && (high < low || high > 40))) continue;
       const before = text.slice(Math.max(0, match.index - 60), match.index);
       if (pattern !== MINIMUM_YEARS && ABOUT_EMPLOYER.test(before) && !MIN_PREFIX.test(before)) continue;
-      found.push({ index: match.index, experience: high !== undefined && high !== low ? { min: low, max: high } : { min: low } });
+      const lineStart = Math.max(text.lastIndexOf("\n", match.index - 1), text.lastIndexOf(".", match.index - 1)) + 1;
+      const context = text.slice(lineStart, match.index) + match[0];
+      const priority = /\b(?:overall|total)\b/i.test(context) ? 3 : pattern === STANDALONE_YEARS ? 2 : 1;
+      const maxOpen = high !== undefined && /(?:\+\s*(?:years?|yrs?)|(?:years?|yrs?)\s*\+)/i.test(match[0]);
+      found.push({ index: match.index, quote: match[0], priority, experience: high !== undefined && high !== low ? { min: low, max: high, ...(maxOpen ? { maxOpen: true } : {}) } : { min: low } });
     }
   }
-  found.sort((left, right) => left.index - right.index);
-  return found[0]?.experience ?? null;
+  found.sort((left, right) => right.priority - left.priority || right.experience.min - left.experience.min || left.index - right.index);
+  return found[0] ?? null;
 }
 
 /** Entry-level titles (intern, trainee, fresher, graduate) as a rough 0–1 year estimate when the posting states nothing. */
@@ -46,5 +56,17 @@ export function titleExperience(title: string): Experience | undefined {
 
 /** "2–5 yrs", "5+ yrs". */
 export function experienceLabel(experience: Experience): string {
-  return experience.max === undefined ? `${experience.min}+ yrs` : `${experience.min}–${experience.max} yrs`;
+  return experience.max === undefined ? `${experience.min}+ yrs` : `${experience.min}–${experience.max}${experience.maxOpen ? "+" : ""} yrs`;
+}
+
+export function experienceMatches(experience: Experience, years: number): boolean {
+  return years >= experience.min && (experience.max === undefined || experience.maxOpen === true || years <= experience.max);
+}
+
+/** Old cached readings without their source text cannot be safely corrected: make them unknown. */
+export function normalizeJobExperience<T extends { description: string; experience?: Experience | null; experienceVersion?: number }>(job: T): Omit<T, "experience" | "experienceVersion"> & { experience?: Experience | null; experienceVersion?: number } {
+  if (job.description.trim()) return { ...job, experience: statedExperience(job.description), experienceVersion: EXPERIENCE_VERSION };
+  if (job.experienceVersion === EXPERIENCE_VERSION) return job;
+  const { experience: _experience, experienceVersion: _version, ...rest } = job;
+  return rest;
 }

package/src/index.ts

@@ -17,7 +17,7 @@ export const companies: Company[] = Object.entries(companyData).map(([slug, valu
 
 export const catalog = createCatalog({ companies });
 export { createCatalog } from "./catalog.ts";
-export { experienceLabel, statedExperience, titleExperience, type Experience } from "./experience.ts";
+export { EXPERIENCE_VERSION, experienceLabel, experienceMatches, normalizeJobExperience, statedExperience, titleExperience, type Experience } from "./experience.ts";
 export type { Catalog } from "./catalog.ts";
 export type { Ats, Company, CrawlReport, Job, JobPartition, JobSnapshot, JobSummary, SearchQuery } from "./types.ts";
 export { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";

package/src/job-matching.ts

@@ -1,4 +1,4 @@
-import { experienceLabel } from "./experience.ts";
+import { experienceLabel, normalizeJobExperience } from "./experience.ts";
 import { validateCandidateProfileEvidence, type CandidateProfile } from "./candidate-profile.ts";
 import { isEligibleForCountry, normalizeLocation } from "./locations.ts";
 import { detectRequirementTerms, findTransferability, matchesExactSkillEvidence, requiresExactSkillEvidence, type TransferabilityKind } from "./requirement-vocabulary.ts";
@@ -71,7 +71,8 @@ export function matchJobs(profile: CandidateProfile, intent: CandidateIntent, jo
   const roleFamilies = deriveRoleFamilies(profile, intent);
   const filteredOut: FilteredJob[] = [];
   const ranked: Array<JobMatch & { score: number; index: number }> = [];
-  for (const [index, job] of jobs.entries()) {
+  for (const [index, rawJob] of jobs.entries()) {
+    const job = normalizeJobExperience(rawJob);
     const rejectionReasons = hardFilterReasons(job, intent);
     if (rejectionReasons.length) {
       filteredOut.push({ jobId: job.id, reasons: rejectionReasons });
@@ -263,7 +264,7 @@ function seniorityAlignment(profile: CandidateProfile, intent: CandidateIntent,
   if (job.experience && typeof resumeYears === "number" && !intent.seniority?.length) {
     // The posting's own range is better evidence than a seniority word in the title. A year short or a few over still fits.
     const asked = experienceLabel(job.experience);
-    const fits = resumeYears >= job.experience.min - 1 && (job.experience.max === undefined || resumeYears <= job.experience.max + 3);
+    const fits = resumeYears >= job.experience.min - 1 && (job.experience.max === undefined || job.experience.maxOpen === true || resumeYears <= job.experience.max + 3);
     return { score: fits ? 3 : -3, reason: `posting asks for ${asked}; resume shows about ${resumeYears} years` };
   }
   const jobSeniority = seniorityTerms.find((term) => includesPhrase(job.title, term));

package/src/mcp.ts

@@ -19,7 +19,7 @@ interface ToolHandler {
 
 /** Read by the AI app before its first call: the order of operations that keeps results honest. */
 export const FLOW_INSTRUCTIONS = [
-  "Openings flow: 1) call prepare_job_search for the person's countries; it is normally ready in one call. 2) Ask for the resume before exploring roles, because recommend_jobs ranks by evidence from it. 3) If the person declines a resume, use search_jobs with their keywords. 4) If they decline that too, use your judgement.",
+  "Openings flow: ask only for missing search constraints, such as role and country. Call prepare_job_search when setup is needed, then search_jobs immediately; a resume is optional, never a prerequisite to explore jobs. Offer recommend_jobs when the person wants evidence-based matching and chooses to share a resume. Follow preparation.nextAction rather than assuming setup succeeded.",
   "Freshness: results start with roles posted in the last 7 days and widen to 14, 30, then everything only when fewer than 5 appear; each result carries age (new, older, stale, undated) and postedDaysAgo. Say which window results came from and present older or stale roles as possibly still open, never as current.",
   "Experience: a job's experience field is the years its posting states ({ min, max }); null means the posting states none, and absent means it was not read. Quote it as the employer's requirement.",
   "Every match carries applyUrl, the employer's own posting; include it. When recommend_jobs reports no_matches, relay its explanation and nextMoves instead of searching silently.",

package/src/runtime.ts

@@ -5,6 +5,7 @@ import { fetchJobDescription, fetchSourceJobs } from "./catalog.ts";
 import { createCrawlReporter, fetchSeedSnapshot, resolveAggregatorUrl } from "./crawl-reporting.ts";
 import { createUsageReporter, type UsageReporter } from "./usage.ts";
 import { VERSION } from "./version.ts";
+import { normalizeJobExperience } from "./experience.ts";
 import { catalog as liveCatalog, companies } from "./index.ts";
 import { createLocalJobs } from "./local-jobs.ts";
 import { createJobRecommender } from "./job-recommendations.ts";
@@ -82,7 +83,7 @@ export function createHostedRuntime(options: { sources: Company[]; store: Snapsh
     if (!company) return job;
     try {
       const description = await fetchJobDescription(company, job, globalThis.fetch);
-      return description.trim() ? { ...job, description } : job;
+      return description.trim() ? normalizeJobExperience({ ...job, description }) : job;
     } catch { return job; } // the employer's board is unreachable; the summary is still useful
   }
   const snapshotJob = async (id: string) => (await local.get(id, { offline: true, staleDays: 3650 })).job;

package/src/screening-requirements.ts

@@ -1,5 +1,7 @@
 import type { CandidateProfile } from "./candidate-profile.ts";
 import type { Job } from "./types.ts";
+import { readExperience } from "./experience.ts";
+import { plainText } from "./providers.ts";
 
 export interface ScreeningRequirement {
   kind: "experience" | "education";
@@ -14,6 +16,12 @@ export function evaluateScreeningRequirements(profile: CandidateProfile, job: Jo
     ...experienceRequirements(profile, description),
     ...educationRequirements(profile, description),
   ];
+  const text = plainText(job.description);
+  const reading = readExperience(text);
+  if (reading && (isMandatory(text, reading.index, reading.quote) || (reading.priority === 2 && lastSectionKind(text.slice(0, reading.index)) !== "optional")) && !requirements.some((item) => item.kind === "experience" && Number(item.requirement.match(/\d+/)?.[0]) === reading.experience.min)) {
+    const inference = profile.inferences.find((value) => value.kind === "approximate_experience_years");
+    requirements.push({ kind: "experience", requirement: clean(reading.quote), status: !inference ? "unsupported" : inference.value >= reading.experience.min ? "supported" : "partial", factIds: inference?.derivedFromFactIds ?? [] });
+  }
   return [...new Map(requirements.map((item) => [`${item.kind}:${item.requirement.toLocaleLowerCase()}`, item])).values()];
 }
 

package/src/selected-job-lookup.ts

@@ -1,4 +1,5 @@
 import type { Job } from "./types.ts";
+import { normalizeJobExperience } from "./experience.ts";
 
 export interface SelectedJobLookupOptions {
   getSnapshotJob(id: string): Promise<Job | null>;
@@ -8,7 +9,8 @@ export interface SelectedJobLookupOptions {
 export function createSelectedJobLookup(options: SelectedJobLookupOptions) {
   return async (id: string): Promise<Job | null> => {
     const snapshot = await options.getSnapshotJob(id);
-    if (snapshot?.description.trim()) return snapshot;
-    return options.getDetailedJob(id);
+    if (snapshot?.description.trim()) return normalizeJobExperience(snapshot);
+    const detailed = await options.getDetailedJob(id);
+    return detailed ? normalizeJobExperience(detailed) : null;
   };
 }

package/src/snapshot-catalog.ts

@@ -1,5 +1,6 @@
 import { searchJobs, type Catalog } from "./catalog.ts";
 import type { SnapshotStore } from "./crawler.ts";
+import { normalizeJobExperience } from "./experience.ts";
 
 export function createSnapshotCatalog(store: SnapshotStore): Catalog {
   return {
@@ -13,7 +14,7 @@ export function createSnapshotCatalog(store: SnapshotStore): Catalog {
       if (!snapshot) return null;
       for (const partition of Object.values(snapshot.partitions)) {
         const job = partition.jobs.find((candidate) => candidate.id === id);
-        if (job) return job;
+        if (job) return normalizeJobExperience(job);
       }
       return null;
     },

package/src/tools.ts

@@ -106,7 +106,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
     },
     {
       name: "search_jobs",
-      description: "Plain keyword search over the local job index, newest first, walking 7, 14, 30 days then everything until 5 results appear; the window used is returned. Use only when the person declines to share a resume or asks for a plain search; recommend_jobs ranks against a resume.",
+      description: "Search jobs immediately from role, country, location and optional stated experience. No resume required. Newest first; automatically widens 7, 14, 30 days then all dates until 5 matches. For another page reuse the same filters and returned window.daysUsed as maxAgeDays, with pagination.nextOffset. Resume-based ranking is optional via recommend_jobs.",
       inputSchema: {
         type: "object",
         properties: {
@@ -114,8 +114,11 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
           location: { type: "string", description: "Case-insensitive location substring" },
           country: { type: "string", pattern: "^[A-Za-z]{2}$", description: "Two-letter country code for job eligibility, such as IN or DE" },
           remote: { type: "boolean", description: "True for remote-only; false for non-remote-only" },
-          maxAgeDays: { type: "integer", minimum: 0, maximum: 365, description: "Only roles posted within this many days, newest first. Default 30 (undated roles kept, listed last); an explicit value also drops undated roles; 0 includes older roles" },
+          maxAgeDays: { type: "integer", minimum: 0, maximum: 365, description: "Omit to widen 7/14/30/all until 5 matches. Explicit positive values exclude undated roles; 0 includes all dates." },
           limit: { type: "integer", minimum: 1, maximum: 100, default: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 1000000, default: 0 },
+          experienceYears: { type: "number", minimum: 0, maximum: 60, description: "Years of experience to compare with the posting's stated min/max range; not a qualification or fit verdict." },
+          includeUnknownExperience: { type: "boolean", default: false, description: "With experienceYears, also keep roles without a stated range, clearly unknown rather than matched." },
         },
         additionalProperties: false,
       },
@@ -148,7 +151,10 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
       if (name === "analyze_job_fit") return workflows.analyzeJobFit(input);
       if (name === "optimize_resume") return workflows.optimizeResume(input);
       if (name === "search_jobs") {
-        assertToolKeys(input, ["query", "location", "country", "remote", "maxAgeDays", "limit"], "search_jobs");
+        assertToolKeys(input, ["query", "location", "country", "remote", "maxAgeDays", "limit", "offset", "experienceYears", "includeUnknownExperience"], "search_jobs");
+        if (input.offset !== undefined && (!Number.isInteger(input.offset) || (input.offset as number) < 0 || (input.offset as number) > 1000000)) throw new Error("offset must be an integer between 0 and 1000000");
+        if (input.experienceYears !== undefined && (typeof input.experienceYears !== "number" || !Number.isFinite(input.experienceYears) || input.experienceYears < 0 || input.experienceYears > 60)) throw new Error("experienceYears must be a number between 0 and 60");
+        if (input.includeUnknownExperience !== undefined && typeof input.includeUnknownExperience !== "boolean") throw new Error("includeUnknownExperience must be a boolean");
         if (input.query !== undefined && typeof input.query !== "string") throw new Error("query must be a string");
         if (input.location !== undefined && typeof input.location !== "string") throw new Error("location must be a string");
         if (input.remote !== undefined && typeof input.remote !== "boolean") throw new Error("remote must be a boolean");
@@ -162,10 +168,13 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         if (typeof input.remote === "boolean") query.remote = input.remote;
         if (typeof input.maxAgeDays === "number") query.maxAgeDays = input.maxAgeDays;
         if (typeof input.limit === "number") query.limit = input.limit;
+        if (typeof input.offset === "number") query.offset = input.offset;
+        if (typeof input.experienceYears === "number") query.experienceYears = input.experienceYears;
+        if (typeof input.includeUnknownExperience === "boolean") query.includeUnknownExperience = input.includeUnknownExperience;
         const jobs = await catalog.search(query) as SearchResult;
         return {
-          jobs, window: jobs.window,
-          guidance: "Unranked keyword matches. Present roles labelled older or stale as possibly still open, not as current. With a resume, recommend_jobs ranks roles by evidence and explains fit.",
+          jobs, window: jobs.window, pagination: jobs.pagination,
+          guidance: "Unranked keyword matches. Experience filters compare stated ranges only; unknown experience is not a match or a gap. Present older/stale roles as possibly still open, not current. Reuse window.daysUsed as maxAgeDays and pagination.nextOffset with unchanged filters for the next page. Pagination is over the current index, not a frozen snapshot; restart if the index refreshes. Resume-based matching is optional.",
         };
       }
       if (name === "get_job") {

package/src/types.ts

@@ -87,6 +87,7 @@ export interface JobSummary {
   updatedAt?: string;
   /** Years of experience the posting states, read from its description. null: the description states none. Absent: not read yet. */
   experience?: Experience | null;
+  experienceVersion?: number;
   /** Days since the posting date at the time of the search; absent when the board gave no date. */
   postedDaysAgo?: number;
   /** new = 7 days or less, older = 8 to 30, stale = beyond 30, undated = no posting date. Present it as such; a stale listing may still be open. */
@@ -116,6 +117,11 @@ export interface SearchQuery {
   /** Only jobs posted within this many days. Unset walks 7, 14, 30, then everything until 5 results appear; an explicit value is a single window that drops undated jobs; 0 includes everything. */
   maxAgeDays?: number;
   limit?: number;
+  /** Zero-based offset within the chosen date window; restart when the index changes. */
+  offset?: number;
+  /** Match stated experience ranges, not inferred seniority or a hiring guarantee. */
+  experienceYears?: number;
+  includeUnknownExperience?: boolean;
 }
 
 export interface CrawlFailure {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.35";
+export const VERSION = "0.1.37";