openings 0.1.21 → 0.1.22

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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

@@ -37,7 +37,7 @@ Then ask your agent something like:
 
 > Show me what Openings covers in India. If that looks useful, use my resume to find backend roles, including good jobs whose titles I would not have searched for. Rank by evidence and explain every gap.
 
-On first use the agent builds your private index in resumable batches of ten sources, reports real coverage, and only then asks for a resume. Results come back in three buckets: direct title matches, hidden roles found through grounded title families, and stretch roles, each with separate evidence and keyword scores. The index lives under `~/.openings`.
+On first use the agent downloads the shared index of every verified source in one call, reports real coverage, and only then asks for a resume; only missing or stale sources are crawled, in batches of 25. Results come back in three buckets: direct title matches, hidden roles found through grounded title families, and stretch roles, each with separate evidence and keyword scores. The index lives under `~/.openings`.
 
 The [job-seeker quickstart](docs/job-seeker-quickstart.md) has sample prompts, an example conversation, privacy details, and common errors.
 

package/docs/job-seeker-quickstart.md

@@ -86,7 +86,7 @@ In a client that accepts MCP configuration, add this stdio server:
 }
 ```
 
-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.
+The first `prepare_job_search` call starts a private index under `~/.openings` from verified structured job sources. The first call seeds the index from the shared aggregator and is normally ready at once; each later call handles at most 25 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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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/adzuna-signals.ts

@@ -0,0 +1,63 @@
+import { atomicJson } from "./atomic-file.ts";
+
+/**
+ * Adzuna as an employer signal for one country: which employers have posted recently and how much. Jobs are never
+ * ingested from it; names and dates feed the employer resolver. The trial plan allows 25 hits a minute and 250 a day,
+ * so every run takes a hit budget and paces itself.
+ */
+export interface AdzunaEmployer { companyName: string; jobs: number; newestCreated?: string; categories: string[]; locations: string[] }
+export interface AdzunaSignalReport { generatedAt: string; country: string; hits: number; jobsSeen: number; totalReported: number; employers: AdzunaEmployer[] }
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+export const ADZUNA_KEYWORDS = ["", "engineer", "developer", "software", "manager", "analyst", "sales", "marketing", "executive", "accountant", "finance", "designer", "data", "support", "operations", "recruiter", "consultant", "nurse", "teacher", "technician", "intern", "product", "quality", "customer", "associate", "java", "python", "react", "devops", "testing"];
+
+export async function collectAdzunaSignals(appId: string, appKey: string, outputPath: string, options: { country?: string; keywords?: string[]; maxHits?: number; maxPages?: number; fetcher?: Fetch; delayMs?: number; sleep?: (ms: number) => Promise<void>; maxDaysOld?: number } = {}): Promise<AdzunaSignalReport> {
+  const fetcher = options.fetcher ?? globalThis.fetch;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const country = (options.country ?? "in").toLowerCase();
+  const maxHits = options.maxHits ?? 200;
+  const employers = new Map<string, AdzunaEmployer>();
+  const seen = new Set<string>();
+  let hits = 0; let totalReported = 0;
+  outer: for (const keywords of options.keywords ?? ADZUNA_KEYWORDS) {
+    for (let page = 1; page <= (options.maxPages ?? 10); page += 1) {
+      if (hits >= maxHits) break outer;
+      if (hits > 0) await sleep(options.delayMs ?? 2_600); // 25 hits a minute
+      hits += 1;
+      const url = new URL(`https://api.adzuna.com/v1/api/jobs/${country}/search/${page}`);
+      url.searchParams.set("app_id", appId); url.searchParams.set("app_key", appKey);
+      url.searchParams.set("results_per_page", "50"); url.searchParams.set("content-type", "application/json");
+      url.searchParams.set("max_days_old", String(options.maxDaysOld ?? 30));
+      if (keywords) url.searchParams.set("what", keywords);
+      const response = await fetcher(url.href, { signal: AbortSignal.timeout(30_000) });
+      if (response.status === 429) break outer;
+      if (!response.ok) break;
+      const body = await response.json() as { count?: number; results?: Array<Record<string, unknown>> };
+      if (page === 1) totalReported = Math.max(totalReported, body.count ?? 0);
+      const results = body.results ?? [];
+      for (const job of results) {
+        const id = String(job.id ?? job.redirect_url ?? "");
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+        const company = isRecord(job.company) ? String(job.company.display_name ?? "").trim() : "";
+        if (company.length < 2) continue;
+        const key = company.toLowerCase();
+        const entry = employers.get(key) ?? { companyName: company, jobs: 0, categories: [], locations: [] };
+        entry.jobs += 1;
+        const created = typeof job.created === "string" ? job.created : undefined;
+        if (created && (!entry.newestCreated || created > entry.newestCreated)) entry.newestCreated = created;
+        const category = isRecord(job.category) ? String(job.category.label ?? "") : "";
+        if (category && !entry.categories.includes(category)) entry.categories.push(category);
+        const area = isRecord(job.location) && Array.isArray(job.location.area) ? String(job.location.area[job.location.area.length - 1] ?? "") : "";
+        if (area && !entry.locations.includes(area) && entry.locations.length < 5) entry.locations.push(area);
+        employers.set(key, entry);
+      }
+      if (results.length < 50) break;
+    }
+  }
+  const report: AdzunaSignalReport = { generatedAt: new Date().toISOString(), country, hits, jobsSeen: seen.size, totalReported, employers: [...employers.values()].sort((left, right) => right.jobs - left.jobs) };
+  await atomicJson(outputPath, report);
+  return report;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/src/catalog.ts

@@ -111,10 +111,14 @@ export function createCatalog(options: CatalogOptions): Catalog {
   };
 }
 
+export const DEFAULT_MAX_AGE_DAYS = 30;
 export function searchJobs(jobs: Job[], query: SearchQuery, now: number = Date.now()): JobSummary[] {
-  const since = query.maxAgeDays ? now - query.maxAgeDays * 86_400_000 : undefined;
+  const explicit = query.maxAgeDays !== undefined;
+  const days = explicit ? query.maxAgeDays! : DEFAULT_MAX_AGE_DAYS;
+  const since = days > 0 ? now - days * 86_400_000 : undefined;
+  const fresh = (job: Job) => since === undefined || postedTime(job) >= since || (!explicit && postedTime(job) === 0);
   return jobs
-    .filter((job) => matches(job, query) && (since === undefined || postedTime(job) >= since))
+    .filter((job) => matches(job, query) && fresh(job))
     .sort((left, right) => postedTime(right) - postedTime(left))
     .slice(0, query.limit ?? 50).map(toSummary);
 }

package/src/cli.ts

@@ -20,6 +20,9 @@ import { probeJobPostingJsonLd } from "./jobposting-probe.ts";
 import { probeSites } from "./site-probe.ts";
 import { admitSites } from "./site-admission.ts";
 import { kekaTenantCandidates } from "./keka-tenants.ts";
+import { collectJoobleSignals } from "./jooble-signals.ts";
+import { collectAdzunaSignals } from "./adzuna-signals.ts";
+import { resolveEmployers } from "./employer-resolver.ts";
 import { mergeAttemptedRoundLeads, prepareRecruiteeRoundArtifacts } from "./recruitee-round.ts";
 
 const HELP = `Openings — search public company job boards
@@ -41,6 +44,9 @@ Usage:
   openings sources probe-sites SEEDS.json [--sample N] [--limit N] [--concurrency N] [--max-pages N] [--delay-ms N] [--report FILE]
   openings sources admit-sites REPORT.json [--catalog FILE] [--min-postings N]
   openings sources keka-tenants HOSTS.txt [--output FILE] [--registry FILE] [--concurrency N]
+  openings sources jooble-signals [--location PLACE] [--max-pages N] [--output FILE]   (key from JOOBLE_API_KEY)
+  openings sources adzuna-signals [--country in] [--max-hits N] [--max-days-old N] [--output FILE]   (ADZUNA_APP_ID and ADZUNA_APP_KEY)
+  openings sources resolve-employers SIGNALS.json [--catalog FILE] [--registry FILE] [--min-jobs N] [--limit N] [--concurrency N] [--report FILE]
   openings sources prepare-recruitee-round IDENTITIES.json [--catalog FILE] [--artifacts DIR]
   openings sources merge-attempted-round-leads ISOLATED_REGISTRY [--registry FILE]
   openings search [words] [--country CODE|--india] [--location PLACE] [--remote|--onsite]
@@ -131,6 +137,33 @@ export async function run(args: string[]): Promise<number> {
       console.log(JSON.stringify({ ...summary, topSites: sites.slice(0, 15) }, null, 2));
       return 0;
     }
+    if (rest[0] === "resolve-employers") {
+      const args = rest.slice(1);
+      const signalsPath = args[0];
+      if (!signalsPath || signalsPath.startsWith("--")) return fail("sources resolve-employers requires a signals JSON file");
+      const value = (flag: string) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
+      const report = await resolveEmployers(signalsPath, { catalogPath: value("--catalog") ?? "data/companies.json", registryPath: value("--registry"), reportPath: value("--report") ?? ".openings/employer-resolver.json", minJobs: value("--min-jobs") ? Number(value("--min-jobs")) : undefined, limit: value("--limit") ? Number(value("--limit")) : undefined, concurrency: value("--concurrency") ? Number(value("--concurrency")) : undefined });
+      console.log(JSON.stringify({ ...report, leads: report.leads.slice(0, 20), unresolved: report.unresolved.length }, null, 2));
+      return 0;
+    }
+    if (rest[0] === "adzuna-signals") {
+      const args = rest.slice(1);
+      const appId = process.env.ADZUNA_APP_ID; const appKey = process.env.ADZUNA_APP_KEY;
+      if (!appId || !appKey) return fail("sources adzuna-signals requires ADZUNA_APP_ID and ADZUNA_APP_KEY in the environment");
+      const value = (flag: string) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
+      const report = await collectAdzunaSignals(appId, appKey, value("--output") ?? ".openings/adzuna-signals.json", { country: value("--country"), maxHits: value("--max-hits") ? Number(value("--max-hits")) : undefined, maxDaysOld: value("--max-days-old") ? Number(value("--max-days-old")) : undefined });
+      console.log(JSON.stringify({ country: report.country, hits: report.hits, jobsSeen: report.jobsSeen, totalReported: report.totalReported, employers: report.employers.length, top: report.employers.slice(0, 10) }, null, 2));
+      return 0;
+    }
+    if (rest[0] === "jooble-signals") {
+      const args = rest.slice(1);
+      const apiKey = process.env.JOOBLE_API_KEY;
+      if (!apiKey) return fail("sources jooble-signals requires JOOBLE_API_KEY in the environment");
+      const value = (flag: string) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
+      const report = await collectJoobleSignals(apiKey, value("--output") ?? ".openings/jooble-signals.json", { location: value("--location"), maxPages: value("--max-pages") ? Number(value("--max-pages")) : undefined, delayMs: 500 });
+      console.log(JSON.stringify({ location: report.location, queries: report.queries, jobsSeen: report.jobsSeen, employers: report.employers.length, seeds: report.seeds.length, top: report.employers.slice(0, 10) }, null, 2));
+      return 0;
+    }
     if (rest[0] === "keka-tenants") {
       const args = rest.slice(1);
       const hostsPath = args[0];

package/src/employer-resolver.ts

@@ -0,0 +1,78 @@
+import { readFile } from "node:fs/promises";
+import { atomicJson } from "./atomic-file.ts";
+import { mergeEnrichmentLeads, type EnrichmentLead } from "./enrichment-registry.ts";
+import { fetchSafeHead, type HeadTransport, type ResolveHost } from "./safe-head.ts";
+import { resolveSource } from "./source-verification.ts";
+
+/**
+ * Employer names from a hiring signal (Adzuna, Jooble) become board leads by guessing the provider token from the name
+ * and letting the provider confirm it exists. Nothing is admitted here: every hit is a lead for the board tier, which
+ * verifies identity against the provider's own record before anything is crawled.
+ */
+export interface ResolverSignal { companyName: string; jobs: number }
+export interface ResolverReport { generatedAt: string; employers: number; probed: number; requests: number; found: number; byProvider: Record<string, number>; leads: Array<{ companyName: string; sourceUrl: string; ats: string }>; unresolved: string[] }
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+const WORKDAY_HOSTS = ["wd1", "wd3", "wd5", "wd12", "wd103", "wd108", "wd10", "wd2"];
+const STOP = new Set(["the", "inc", "llc", "ltd", "limited", "pvt", "private", "corp", "corporation", "company", "co", "group", "india", "technologies", "technology", "solutions", "services", "global", "international", "bank", "plc", "lp", "llp", "and", "of"]);
+
+/** Token guesses in order of likelihood: full compact name, hyphenated name, distinctive first word. */
+export function tokenGuesses(name: string): string[] {
+  const words = name.toLowerCase().replace(/&/g, " and ").replace(/[^a-z0-9 ]+/g, " ").split(/\s+/).filter(Boolean);
+  const core = words.filter((word) => !STOP.has(word));
+  const base = core.length ? core : words;
+  const guesses = [base.join(""), base.join("-"), base[0] ?? ""].filter((guess) => guess.length >= 3);
+  if (base.length > 2) guesses.push(base.slice(0, 2).join(""));
+  return [...new Set(guesses)];
+}
+
+export async function resolveEmployers(signalsPath: string, options: { catalogPath?: string; registryPath?: string; reportPath?: string; minJobs?: number; limit?: number; concurrency?: number; fetcher?: Fetch; headTransport?: HeadTransport; resolveHost?: ResolveHost; timeoutMs?: number } = {}): Promise<ResolverReport> {
+  const fetcher = options.fetcher ?? globalThis.fetch;
+  const signals = JSON.parse(await readFile(signalsPath, "utf8")) as { employers: ResolverSignal[] };
+  const known = new Set<string>();
+  if (options.catalogPath) for (const entry of Object.values(JSON.parse(await readFile(options.catalogPath, "utf8")) as Record<string, { name: string; companyDomain?: string }>)) { known.add(compact(entry.name)); if (entry.companyDomain) known.add(compact(entry.companyDomain.split(".")[0]!)); }
+  let employers = signals.employers.filter((entry) => entry.jobs >= (options.minJobs ?? 1) && !known.has(compact(entry.companyName)));
+  if (options.limit) employers = employers.slice(0, options.limit);
+  const report: ResolverReport = { generatedAt: new Date().toISOString(), employers: signals.employers.length, probed: employers.length, requests: 0, found: 0, byProvider: {}, leads: [], unresolved: [] };
+  const timeout = options.timeoutMs ?? 12_000;
+  const seenSources = new Set<string>();
+  const ok = async (url: string, init?: RequestInit) => { report.requests += 1; try { const reply = await fetcher(url, { ...init, signal: AbortSignal.timeout(timeout) }); await reply.body?.cancel().catch(() => undefined); return reply; } catch { return null; } };
+  const probes: Array<(guess: string) => Promise<string | null>> = [
+    async (guess) => { for (const host of WORKDAY_HOSTS) { report.requests += 1; try { const head = await fetchSafeHead(`https://${guess}.${host}.myworkdayjobs.com/`, { timeoutMs: timeout, transport: options.headTransport, resolveHost: options.resolveHost }); if (head.response.ok && resolveSource(head.finalUrl)?.ats === "workday") return head.finalUrl; } catch { /* no such tenant */ } } return null; },
+    async (guess) => { const reply = await ok(`https://boards-api.greenhouse.io/v1/boards/${encodeURIComponent(guess)}/jobs`); return reply?.ok ? `https://job-boards.greenhouse.io/${guess}` : null; },
+    async (guess) => { const reply = await ok(`https://api.lever.co/v0/postings/${encodeURIComponent(guess)}?mode=json`); return reply?.ok ? `https://jobs.lever.co/${guess}` : null; },
+    async (guess) => { const reply = await ok(`https://api.ashbyhq.com/posting-api/job-board/${encodeURIComponent(guess)}`); return reply?.ok ? `https://jobs.ashbyhq.com/${guess}` : null; },
+    async (guess) => { // SmartRecruiters answers 200 with an empty list for any name, so only a posting proves the company exists
+      report.requests += 1;
+      try { const reply = await fetcher(`https://api.smartrecruiters.com/v1/companies/${encodeURIComponent(guess)}/postings?limit=1`, { signal: AbortSignal.timeout(timeout) }); if (!reply.ok) { await reply.body?.cancel().catch(() => undefined); return null; } const body = await reply.json() as { totalFound?: number }; return (body.totalFound ?? 0) > 0 ? `https://jobs.smartrecruiters.com/${guess}` : null; } catch { return null; }
+    },
+    async (guess) => { const reply = await ok(`https://apply.workable.com/api/v1/widget/accounts/${encodeURIComponent(guess)}`); return reply?.ok ? `https://apply.workable.com/${guess}/` : null; },
+    async (guess) => { if (!/^[a-z0-9-]+$/.test(guess)) return null; const reply = await ok(`https://${guess}.keka.com/careers`); if (!reply?.ok) return null; try { const shell = await (await fetcher(`https://${guess}.keka.com/careers`, { signal: AbortSignal.timeout(timeout) })).text(); const org = /\/ats\/documents\/([0-9a-f-]{36})\//i.exec(shell)?.[1]; return org ? `https://${guess}.keka.com/careers/api/embedjobs/default/active/${org.toLowerCase()}` : null; } catch { return null; } },
+  ];
+  const leads: EnrichmentLead[] = [];
+  let cursor = 0;
+  async function worker() {
+    while (cursor < employers.length) {
+      const employer = employers[cursor++]!;
+      let hit: string | null = null;
+      for (const guess of tokenGuesses(employer.companyName)) {
+        for (const probe of probes) { hit = await probe(guess); if (hit) break; }
+        if (hit) break;
+      }
+      const source = hit ? resolveSource(hit) : null;
+      if (!source) { report.unresolved.push(employer.companyName); continue; }
+      const sourceKey = `${source.ats}:${source.token.toLowerCase()}`;
+      if (seenSources.has(sourceKey)) continue;
+      seenSources.add(sourceKey);
+      report.found += 1; report.byProvider[source.ats] = (report.byProvider[source.ats] ?? 0) + 1;
+      report.leads.push({ companyName: employer.companyName, sourceUrl: source.canonicalSourceUrl, ats: source.ats });
+      leads.push({ sourceKey, sourceUrl: source.canonicalSourceUrl, ats: source.ats, token: source.token, discoveredFrom: [{ channel: "search", reference: `hiring-signal:${employer.companyName}` }], companyMatches: [], identityEvidence: [], attempts: [] });
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, options.concurrency ?? 6) }, worker));
+  if (options.registryPath && leads.length) await mergeEnrichmentLeads(options.registryPath, leads);
+  if (options.reportPath) await atomicJson(options.reportPath, report);
+  return report;
+}
+
+function compact(value: string): string { return value.toLowerCase().replace(/\b(inc|llc|ltd|limited|pvt|private|corp|corporation|company|group|india|the)\b/g, "").replace(/[^a-z0-9]/g, ""); }

package/src/intent-validation.ts

@@ -17,7 +17,7 @@ export function validateCandidateIntent(value: unknown, invalid: InvalidInput, o
     if (Array.isArray(countries) && !countries.every((country) => typeof country === "string" && /^[A-Za-z]{2}$/.test(country))) throw invalid(`intent.${field}`, `${field} must contain two-letter country codes`);
   }
   if (value.remote !== undefined && typeof value.remote !== "boolean") throw invalid("intent.remote", "remote must be a boolean");
-  if (value.maxAgeDays !== undefined && (!Number.isInteger(value.maxAgeDays) || (value.maxAgeDays as number) < 1 || (value.maxAgeDays as number) > 365)) throw invalid("intent.maxAgeDays", "maxAgeDays must be an integer between 1 and 365");
+  if (value.maxAgeDays !== undefined && (!Number.isInteger(value.maxAgeDays) || (value.maxAgeDays as number) < 0 || (value.maxAgeDays as number) > 365)) throw invalid("intent.maxAgeDays", "maxAgeDays must be an integer between 0 and 365");
   return value as unknown as CandidateIntent;
 }
 

package/src/job-matching.ts

@@ -2,7 +2,7 @@ import { validateCandidateProfileEvidence, type CandidateProfile } from "./candi
 import { isEligibleForCountry, normalizeLocation } from "./locations.ts";
 import { detectRequirementTerms, findTransferability, matchesExactSkillEvidence, requiresExactSkillEvidence, type TransferabilityKind } from "./requirement-vocabulary.ts";
 import type { Job } from "./types.ts";
-import { postedTime } from "./catalog.ts";
+import { DEFAULT_MAX_AGE_DAYS, postedTime } from "./catalog.ts";
 import { evaluateScreeningRequirements, type ScreeningRequirement } from "./screening-requirements.ts";
 
 export interface CandidateIntent {
@@ -16,7 +16,7 @@ export interface CandidateIntent {
   excludedCountries?: string[];
   excludedLocations?: string[];
   excludedRoles?: string[];
-  /** Only roles posted within this many days; undated roles are dropped when set. */
+  /** Only roles posted within this many days. Default 30 keeps undated roles; an explicit value drops them too; 0 includes everything. */
   maxAgeDays?: number;
 }
 
@@ -49,6 +49,8 @@ export interface JobMatch {
   transferable: TransferableRequirement[];
   gaps: string[];
   discovery: { category: "direct" | "hidden" | "stretch"; titleExpansions: TitleExpansion[] };
+  /** The employer's own posting, repeated at the top level so it is never dropped from a summary. */
+  applyUrl: string;
 }
 
 export interface FilteredJob { jobId: string; reasons: string[] }
@@ -115,6 +117,7 @@ export function matchJobs(profile: CandidateProfile, intent: CandidateIntent, jo
       transferable,
       gaps,
       discovery: { category, titleExpansions },
+      applyUrl: job.url,
       score,
       index,
     });
@@ -229,7 +232,9 @@ function hardFilterReasons(job: Job, intent: CandidateIntent): string[] {
   if (intent.locations?.length && !intent.locations.some((location) => normalizeLocation(job.location).includes(normalizeLocation(location)))) reasons.push("location_mismatch");
   for (const location of intent.excludedLocations ?? []) if (normalizeLocation(job.location).includes(normalizeLocation(location))) reasons.push(`location_excluded:${location}`);
   for (const role of intent.excludedRoles ?? []) if (includesPhrase(job.title, role) || tokenOverlap(role, job.title) === 1) reasons.push(`role_excluded:${role}`);
-  if (intent.maxAgeDays && postedTime(job) < Date.now() - intent.maxAgeDays * 86_400_000) reasons.push(`posted_too_old:${intent.maxAgeDays}d`);
+  const explicitAge = intent.maxAgeDays !== undefined;
+  const maxAgeDays = explicitAge ? intent.maxAgeDays! : DEFAULT_MAX_AGE_DAYS;
+  if (maxAgeDays > 0 && (postedTime(job) > 0 || explicitAge) && postedTime(job) < Date.now() - maxAgeDays * 86_400_000) reasons.push(`posted_too_old:${maxAgeDays}d`);
   if (intent.remote === true && job.workMode !== "remote") reasons.push("remote_required");
   if (intent.remote === false && (job.workMode === "remote" || job.workMode === "unknown")) reasons.push("non_remote_required");
   const searchable = `${job.title}\n${job.company}\n${job.location}\n${job.description}`;

package/src/job-search-preparation.ts

@@ -6,6 +6,7 @@ import { partitionFor, type Company, type CrawlReport, type JobSnapshot } from "
 export interface PrepareJobSearchResult {
   status: "ready" | "partial";
   nextAction: "ready" | "call_again" | "retry_later";
+  note?: string;
   continuation?: string;
   networkAttempted: boolean;
   sources: { catalog: number; indexed: number; fresh: number; stale: number; missing: number; pending: number };
@@ -25,7 +26,7 @@ export function createJobSearchPreparer(options: {
 }) {
   const now = options.now ?? (() => new Date());
   const freshnessMs = (options.freshnessDays ?? 14) * 86_400_000;
-  const batchSize = Math.max(1, Math.min(10, Math.trunc(options.batchSize ?? 10)));
+  const batchSize = Math.max(1, Math.min(25, Math.trunc(options.batchSize ?? 25)));
   return {
     async prepare(value: unknown): Promise<PrepareJobSearchResult> {
       const input = validateInput(value, options.sources);
@@ -44,10 +45,13 @@ export function createJobSearchPreparer(options: {
       const state = sourceState(options.sources, snapshot, now(), freshnessMs);
       const attempted = new Set([...input.attempted, ...selected]);
       const hasUnattemptedPending = pendingSources(options.sources, snapshot, now(), freshnessMs).some((source) => !attempted.has(source.slug));
-      const nextAction = state.pending === 0 ? "ready" : hasUnattemptedPending ? "call_again" : "retry_later";
+      // The shared seed normally covers the whole catalog on the first call; a few missing or stale sources never justify another round trip.
+      const covered = state.fresh / Math.max(1, options.sources.length);
+      const nextAction = state.pending === 0 || covered >= 0.95 ? "ready" : hasUnattemptedPending ? "call_again" : "retry_later";
       return {
         status: state.pending === 0 ? "ready" : "partial",
         nextAction,
+        ...(nextAction === "ready" && state.pending > 0 ? { note: `${state.indexed} of ${options.sources.length} sources are indexed; the remaining ${state.pending} are optional and refresh in the background of later calls.` } : {}),
         ...(nextAction === "call_again" ? { continuation: encodeContinuation(countries, attempted) } : {}),
         networkAttempted: Boolean(crawl),
         sources: { catalog: options.sources.length, ...state },

package/src/jooble-signals.ts

@@ -0,0 +1,65 @@
+import { atomicJson } from "./atomic-file.ts";
+
+/**
+ * Jooble as an employer signal, never as a job source: who is hiring right now, and on which site the posting originated.
+ * When the origin site is a company-owned host it doubles as the employer's domain, which the site and board tracers verify.
+ */
+export interface JoobleSignal { companyName: string; jobs: number; newestUpdated?: string; sources: string[]; companyDomain?: string }
+export interface JoobleSignalReport { generatedAt: string; location: string; queries: number; jobsSeen: number; employers: JoobleSignal[]; seeds: Array<{ companyName: string; companyDomain: string }> }
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+const AGGREGATOR_HOSTS = /jooble|indeed|linkedin|glassdoor|naukri|monster|shine|timesjobs|foundit|hireskys|decentrajobs|jobrapido|talent\.com|adzuna|careerjet|neuvoo|whatjobs|jobisjob|trovit|mitula|jora|recruit\.net|simplyhired|ziprecruiter|lensa|bebee|learn4good|expertini|workable|greenhouse|lever|ashby|smartrecruiters|myworkdayjobs|recruitee|breezy|freshteam|keka|zohorecruit|jobvite|icims|taleo|successfactors|bamboohr|applytojob|jazzhr/i;
+export const DEFAULT_KEYWORDS = ["", "engineer", "developer", "software", "manager", "analyst", "sales", "marketing", "executive", "accountant", "finance", "designer", "data", "support", "operations", "hr", "consultant", "nurse", "teacher", "technician", "intern", "product", "quality", "customer", "associate"];
+
+export async function collectJoobleSignals(apiKey: string, outputPath: string, options: { location?: string; keywords?: string[]; maxPages?: number; fetcher?: Fetch; delayMs?: number; sleep?: (ms: number) => Promise<void> } = {}): Promise<JoobleSignalReport> {
+  const fetcher = options.fetcher ?? globalThis.fetch;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const location = options.location ?? "India";
+  const employers = new Map<string, JoobleSignal>();
+  let queries = 0; let jobsSeen = 0;
+  const seen = new Set<string>();
+  for (const keywords of options.keywords ?? DEFAULT_KEYWORDS) {
+    for (let page = 1; page <= (options.maxPages ?? 10); page += 1) {
+      if (queries > 0 && options.delayMs) await sleep(options.delayMs);
+      queries += 1;
+      const response = await fetcher(`https://jooble.org/api/${encodeURIComponent(apiKey)}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ keywords, location, page, ResultOnPage: 100 }), signal: AbortSignal.timeout(30_000) });
+      if (!response.ok) break;
+      const body = await response.json() as { totalCount?: number; jobs?: Array<Record<string, unknown>> };
+      const jobs = body.jobs ?? [];
+      for (const job of jobs) {
+        const id = String(job.id ?? job.link ?? "");
+        if (!id || seen.has(id)) continue;
+        seen.add(id); jobsSeen += 1;
+        const name = String(job.company ?? "").trim();
+        if (!name || name.length < 2) continue;
+        const key = name.toLowerCase();
+        const entry = employers.get(key) ?? { companyName: name, jobs: 0, sources: [] };
+        entry.jobs += 1;
+        const updated = typeof job.updated === "string" ? job.updated : undefined;
+        if (updated && (!entry.newestUpdated || updated > entry.newestUpdated)) entry.newestUpdated = updated;
+        const source = String(job.source ?? "").toLowerCase().replace(/^www\./, "");
+        if (source && !entry.sources.includes(source)) entry.sources.push(source);
+        employers.set(key, entry);
+      }
+      if (jobs.length < 100 || seen.size >= (body.totalCount ?? 0)) break;
+    }
+  }
+  for (const entry of employers.values()) {
+    // Company-owned only when the site's name shares a token with the employer's name; unknown aggregators never qualify.
+    const tokens = entry.companyName.toLowerCase().replace(/[^a-z0-9 ]/g, " ").split(/\s+/).filter((token) => token.length >= 3 && !["the", "ltd", "limited", "inc", "pvt", "private", "group", "technologies", "solutions", "services", "india", "bank", "corporation", "company"].includes(token));
+    const owned = entry.sources.map(registrable).find((domain) => !AGGREGATOR_HOSTS.test(domain) && /^[a-z0-9.-]+\.[a-z]{2,}$/.test(domain) && tokens.some((token) => domain.split(".")[0]!.replace(/-/g, "").includes(token)));
+    if (owned) entry.companyDomain = owned;
+  }
+  const list = [...employers.values()].sort((left, right) => right.jobs - left.jobs);
+  const report: JoobleSignalReport = { generatedAt: new Date().toISOString(), location, queries, jobsSeen, employers: list, seeds: list.filter((entry) => entry.companyDomain).map((entry) => ({ companyName: entry.companyName, companyDomain: entry.companyDomain! })) };
+  await atomicJson(outputPath, report);
+  return report;
+}
+
+/** careers-inc.nttdata.com -> nttdata.com; keeps two labels under a two-letter country suffix such as co.in. */
+function registrable(host: string): string {
+  const parts = host.split(".");
+  if (parts.length <= 2) return host;
+  const last = parts[parts.length - 1]!; const second = parts[parts.length - 2]!;
+  return last.length === 2 && ["co", "com", "org", "net", "ac", "gov", "edu"].includes(second) ? parts.slice(-3).join(".") : parts.slice(-2).join(".");
+}

package/src/screening-requirements.ts

@@ -59,7 +59,27 @@ function educationRequirements(profile: CandidateProfile, description: string):
     const requirement = level.startsWith("bachelor") ? "Bachelor's degree" : level.startsWith("master") ? "Master's degree" : "Doctoral degree";
     return [{ kind: "education", requirement, status: fact ? "supported" : "unsupported", factIds: fact ? [fact.id] : [] }];
   });
-  return [...fieldSpecific, ...generic];
+  // "Qualification: Polymer Science, Chemistry, Materials Science or a related technical discipline" names the disciplines without the word degree.
+  const disciplinePattern = /\b(?:qualifications?|degree|graduate|graduation|b\.?\s?tech|b\.?\s?e\.?|m\.?\s?tech|m\.?\s?sc|b\.?\s?sc|bachelors?|masters?)\b[^.\n:]{0,30}?(?:\bin\b|:)\s+([A-Za-z][^.\n]{3,140})/gi;
+  const named = [...description.matchAll(disciplinePattern)].flatMap<ScreeningRequirement>((match) => {
+    if (!isMandatory(description, match.index!, match[0]) || !namedDisciplines(match[1]!).length) return [];
+    const requirement = clean(match[0]);
+    if (fieldSpecific.some((item) => item.requirement === requirement)) return [];
+    const fact = profile.facts.find((value) => value.kind === "education" && educationFieldMatches(match[1]!, value.value));
+    return [{ kind: "education", requirement, status: fact ? "supported" : "unsupported", factIds: fact ? [fact.id] : [] }];
+  });
+  return dedupe([...fieldSpecific, ...generic, ...named]);
+}
+
+function dedupe(items: ScreeningRequirement[]): ScreeningRequirement[] {
+  const seen = new Set<string>();
+  return items.filter((item) => { const key = item.requirement.toLocaleLowerCase(); if (seen.has(key)) return false; seen.add(key); return true; });
+}
+
+/** Specific disciplines in a requirement, with "or a related technical discipline" style tails removed. */
+function namedDisciplines(field: string): string[] {
+  return field.replace(/\b(?:or|and)?\s*(?:a|an)?\s*(?:related|relevant|similar|equivalent|other)\b[^,;/]*$/i, "").split(/,|;|\/|\bor\b|\band\b/i)
+    .map((part) => part.trim().toLocaleLowerCase()).filter((part) => part.length >= 3 && !/^(?:related|relevant|equivalent|similar|field|discipline|technical|any)\b/.test(part));
 }
 
 function isMandatory(description: string, start: number, value: string): boolean {
@@ -91,8 +111,12 @@ function educationLevelMatches(level: string, value: string): boolean {
   return /\b(?:ph\.?d|doctorate)\b/i.test(value);
 }
 
+const GENERIC_DISCIPLINE_WORDS = new Set(["science", "sciences", "technology", "engineering", "studies", "management", "arts", "field", "degree", "related", "discipline"]);
 function educationFieldMatches(requiredField: string, value: string): boolean {
   const candidate = value.toLocaleLowerCase();
+  // Named disciplines are the bar; a broad "related technical discipline" clause only widens it when nothing specific is named.
+  const named = namedDisciplines(requiredField).filter((part) => !/\b(?:technical|business)\b/.test(part) || part.split(/\s+/).length > 1);
+  if (named.length) return named.some((part) => candidate.includes(part) || part.split(/\s+/).filter((word) => word.length > 3 && !GENERIC_DISCIPLINE_WORDS.has(word)).some((word) => candidate.includes(word)));
   if (/\b(?:computer science|computing|software|information technology|engineering)\b/i.test(requiredField) && /\b(?:computer science|computing|software|information technology|engineering|b\.?tech|b\.?e\.?|m\.?tech|m\.?e\.?)\b/i.test(candidate)) return true;
   if (/\b(?:technical|business)\b/i.test(requiredField) && /\b(?:technology|technical|engineering|computer|software|information systems|business|commerce|bba|mba|b\.?tech|m\.?tech)\b/i.test(candidate)) return true;
   return false;

package/src/tools.ts

@@ -24,7 +24,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
   const definitions: ToolDefinition[] = [
     {
       name: "prepare_job_search",
-      description: "Initialize or refresh the local job index from verified public sources in resumable batches of at most ten, then report current coverage and whether to call again. This may use the network and write only job data under the local Openings data directory; it never processes a resume.",
+      description: "Initialize the local job index: the first call downloads the shared index of every verified source (thousands of employers) and returns ready; only missing or stale sources are crawled, in batches of at most 25. Report coverage from the result rather than calling again once nextAction is ready. This may use the network and write only job data under the local Openings data directory; it never processes a resume.",
       inputSchema: {
         type: "object",
         properties: {
@@ -107,7 +107,7 @@ 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: 1, maximum: 365, description: "Only roles posted within this many days; results are newest first" },
+          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" },
           limit: { type: "integer", minimum: 1, maximum: 100, default: 50 },
         },
         additionalProperties: false,
@@ -145,7 +145,7 @@ export function createToolHandler(catalog: Catalog, workflows: JobWorkflows, opt
         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");
-        if (input.maxAgeDays !== undefined && (!Number.isInteger(input.maxAgeDays) || (input.maxAgeDays as number) < 1 || (input.maxAgeDays as number) > 365)) throw new Error("maxAgeDays must be an integer between 1 and 365");
+        if (input.maxAgeDays !== undefined && (!Number.isInteger(input.maxAgeDays) || (input.maxAgeDays as number) < 0 || (input.maxAgeDays as number) > 365)) throw new Error("maxAgeDays must be an integer between 0 and 365");
         if (input.limit !== undefined && (!Number.isInteger(input.limit) || (input.limit as number) < 1 || (input.limit as number) > 100)) throw new Error("limit must be an integer between 1 and 100");
         const query: SearchQuery = {};
         if (typeof input.query === "string") query.query = input.query;
@@ -184,7 +184,7 @@ function intentSchema(): Record<string, unknown> {
       roles: stringArray(), countries: countryArray(), locations: stringArray(), remote: { type: "boolean" }, seniority: stringArray(),
       requiredSkills: stringArray(), excludedTerms: stringArray(),
       excludedCountries: countryArray(), excludedLocations: stringArray(), excludedRoles: stringArray(),
-      maxAgeDays: { type: "integer", minimum: 1, maximum: 365, description: "Only roles posted within this many days" },
+      maxAgeDays: { type: "integer", minimum: 0, maximum: 365, description: "Only roles posted within this many days. Default 30 (undated roles kept); an explicit value also drops undated roles; 0 includes older roles" },
     },
     additionalProperties: false,
   };

package/src/types.ts

@@ -99,7 +99,7 @@ export interface SearchQuery {
   location?: string;
   country?: string;
   remote?: boolean;
-  /** Only jobs posted within this many days; undated jobs are excluded when set. */
+  /** Only jobs posted within this many days. Default 30 keeps undated jobs (sorted last); an explicit value also drops undated jobs; 0 includes everything. */
   maxAgeDays?: number;
   limit?: number;
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.21";
+export const VERSION = "0.1.22";