job-hunter-kit 0.1__tar.gz

job_hunter_kit-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdul Basit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

job_hunter_kit-0.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: job-hunter-kit
+Version: 0.1
+Summary: Job search automation with LLM API pipeline mode and Claude Code agent mode.
+Author: Abdul Basit
+License: MIT
+Project-URL: Homepage, https://github.com/abdulrbasit/job-hunter
+Project-URL: Repository, https://github.com/abdulrbasit/job-hunter
+Project-URL: Issues, https://github.com/abdulrbasit/job-hunter/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: anthropic>=0.50.0
+Requires-Dist: openai>=1.68.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-jobspy>=0.20.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: headroom-ai>=0.1.0; sys_platform != "win32"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40.0; extra == "browser"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ty>=0.0.1a20; extra == "dev"
+Provides-Extra: secrets
+Requires-Dist: keyring>=24.0.0; extra == "secrets"
+Provides-Extra: all
+Requires-Dist: job-hunter-kit[browser,secrets]; extra == "all"
+Dynamic: license-file
+
+# Job Hunter
+
+Job Hunter is an installable Python package for running a personal job-search workspace. It has one CLI and two modes:
+
+- `agent`: Python handles deterministic work; Claude/Codex skills handle screening, scoring, tailoring, and writing.
+- `llm-api`: Python runs the autonomous LLM-backed pipeline for unattended jobs.
+
+The default mode is `agent`.
+
+## Install
+
+```bash
+pip install job-hunter-kit
+# or
+uv tool install job-hunter-kit
+```
+
+## Create a Workspace
+
+```bash
+job-hunter init my-job-hunter-workspace
+cd my-job-hunter-workspace
+cp .env.example .env
+job-hunter config check
+job-hunter doctor
+```
+
+Edit `config/job_hunter.yml` with deterministic machine choices: titles, regions, exclusions, profile paths, mode, scoring thresholds, LLM search gate, and provider/model choices. Put personal positioning and writing preferences in `profile/career_context.md`. Secrets use fixed environment variable names in `.env` or GitHub Actions.
+
+## Daily Use
+
+```bash
+job-hunter hunt --region primary
+job-hunter brief
+job-hunter dashboard --no-interactive
+```
+
+In `agent` mode, open the workspace in Claude Code or Codex and use:
+
+```text
+/job-hunter brief
+/job-hunter batch
+/job-hunter one <url>
+/job-hunter finalize
+```
+
+In `llm-api` mode, `job-hunter hunt` runs scrape, score, tailor, cover letter, PDF, tracker, and README updates in one pipeline.
+
+## Public CLI
+
+- `job-hunter init <workspace>` creates a workspace.
+- `job-hunter config check` validates `config/job_hunter.yml`.
+- `job-hunter doctor` checks setup health.
+- `job-hunter hunt` discovers and enriches jobs.
+- `job-hunter brief` writes the daily briefing.
+- `job-hunter tailor` processes provided job URLs or JD text.
+- `job-hunter dashboard`, `job-hunter applications`, and `job-hunter analytics` inspect application state.
+- `job-hunter update-skills` refreshes bundled `.claude/skills/` only.
+- `job-hunter version` and `job-hunter update-info` show version and upgrade guidance.
+
+Support commands such as `agent-context`, `import-job`, `compile-pdf`, `update-readme`, `mark-processed`, `discard-job`, `cleanup-transient`, and `finalize-run` exist for skills and automation.
+
+## Data Contract
+
+Deterministic user choices live in `config/job_hunter.yml`; human career and writing guidance lives in `profile/career_context.md`. Persistent URL dedup lives in `outputs/state/discovered_urls.yml`. Product updates must not overwrite `config/`, `profile/`, `outputs/`, or `.env`.
+
+See `DATA_CONTRACT.md` for the full contract.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest tests/ -q --tb=short
+uv run ruff format --check job_hunter tests .github/scripts
+uv run ruff check job_hunter tests .github/scripts
+uv run ty check job_hunter tests
+uv build
+```
+
+MIT licensed. See `CONTRIBUTING.md`.

job_hunter_kit-0.1/README.md

@@ -0,0 +1,80 @@
+# Job Hunter
+
+Job Hunter is an installable Python package for running a personal job-search workspace. It has one CLI and two modes:
+
+- `agent`: Python handles deterministic work; Claude/Codex skills handle screening, scoring, tailoring, and writing.
+- `llm-api`: Python runs the autonomous LLM-backed pipeline for unattended jobs.
+
+The default mode is `agent`.
+
+## Install
+
+```bash
+pip install job-hunter-kit
+# or
+uv tool install job-hunter-kit
+```
+
+## Create a Workspace
+
+```bash
+job-hunter init my-job-hunter-workspace
+cd my-job-hunter-workspace
+cp .env.example .env
+job-hunter config check
+job-hunter doctor
+```
+
+Edit `config/job_hunter.yml` with deterministic machine choices: titles, regions, exclusions, profile paths, mode, scoring thresholds, LLM search gate, and provider/model choices. Put personal positioning and writing preferences in `profile/career_context.md`. Secrets use fixed environment variable names in `.env` or GitHub Actions.
+
+## Daily Use
+
+```bash
+job-hunter hunt --region primary
+job-hunter brief
+job-hunter dashboard --no-interactive
+```
+
+In `agent` mode, open the workspace in Claude Code or Codex and use:
+
+```text
+/job-hunter brief
+/job-hunter batch
+/job-hunter one <url>
+/job-hunter finalize
+```
+
+In `llm-api` mode, `job-hunter hunt` runs scrape, score, tailor, cover letter, PDF, tracker, and README updates in one pipeline.
+
+## Public CLI
+
+- `job-hunter init <workspace>` creates a workspace.
+- `job-hunter config check` validates `config/job_hunter.yml`.
+- `job-hunter doctor` checks setup health.
+- `job-hunter hunt` discovers and enriches jobs.
+- `job-hunter brief` writes the daily briefing.
+- `job-hunter tailor` processes provided job URLs or JD text.
+- `job-hunter dashboard`, `job-hunter applications`, and `job-hunter analytics` inspect application state.
+- `job-hunter update-skills` refreshes bundled `.claude/skills/` only.
+- `job-hunter version` and `job-hunter update-info` show version and upgrade guidance.
+
+Support commands such as `agent-context`, `import-job`, `compile-pdf`, `update-readme`, `mark-processed`, `discard-job`, `cleanup-transient`, and `finalize-run` exist for skills and automation.
+
+## Data Contract
+
+Deterministic user choices live in `config/job_hunter.yml`; human career and writing guidance lives in `profile/career_context.md`. Persistent URL dedup lives in `outputs/state/discovered_urls.yml`. Product updates must not overwrite `config/`, `profile/`, `outputs/`, or `.env`.
+
+See `DATA_CONTRACT.md` for the full contract.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest tests/ -q --tb=short
+uv run ruff format --check job_hunter tests .github/scripts
+uv run ruff check job_hunter tests .github/scripts
+uv run ty check job_hunter tests
+uv build
+```
+
+MIT licensed. See `CONTRIBUTING.md`.

job_hunter_kit-0.1/job_hunter/__init__.py

@@ -0,0 +1,6 @@
+"""Job Hunter — dual-mode job search automation.
+
+Modes (set via config/job_hunter.yml → mode):
+  agent:   Python prepares bounded context; Claude Code skills drive judgment.
+  llm-api: Full autonomous pipeline; LLM APIs called directly inside Python.
+"""

job_hunter_kit-0.1/job_hunter/agent_context/__init__.py

@@ -0,0 +1,24 @@
+"""Agent context package — bounded context builders for Claude Code skills."""
+
+from job_hunter.agent_context.batch import build_candidate_batch, screen_candidate_batch
+from job_hunter.agent_context.briefing import brief_context, linkedin_weekly_context, llm_search_config
+from job_hunter.agent_context.candidates import build_candidate_queue, candidate_from_queue
+from job_hunter.agent_context.lifecycle import candidate_lifecycle, validate_score_file
+from job_hunter.agent_context.score_context import score_context
+from job_hunter.agent_context.stories import final_stories_text, story_by_id, story_index
+
+__all__ = [
+    "brief_context",
+    "build_candidate_batch",
+    "build_candidate_queue",
+    "candidate_from_queue",
+    "candidate_lifecycle",
+    "final_stories_text",
+    "linkedin_weekly_context",
+    "llm_search_config",
+    "score_context",
+    "screen_candidate_batch",
+    "story_by_id",
+    "story_index",
+    "validate_score_file",
+]

job_hunter_kit-0.1/job_hunter/agent_context/_types.py

@@ -0,0 +1,25 @@
+"""Shared types and constants for agent_context sub-modules."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+MAX_SNIPPET_CHARS = 700
+MAX_JD_CHARS = 6000
+DEFAULT_QUEUE_PATH = "outputs/state/agent_candidate_queue.json"
+DEFAULT_CANDIDATE_SCOPE = "briefing-backlog"
+JD_LIFECYCLE_IMPORT_STATUSES = {"thin", "fetch_failed", "page_noise"}
+STORY_HEADING_RE = re.compile(r"^###\s+([A-Za-z0-9]+-\d+)\s+[—-]\s+(.+?)\s*$")
+RATING_RE = re.compile(r"Rating:\s*([0-9]+(?:\.[0-9]+)?/10)")
+
+
+@dataclass(frozen=True)
+class StoryBlock:
+    story_id: str
+    title: str
+    role: str
+    rating: str
+    tags: list[str]
+    summary: str
+    text: str

job_hunter_kit-0.1/job_hunter/agent_context/_utils.py

@@ -0,0 +1,44 @@
+"""Shared utility helpers for agent_context sub-modules."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from job_hunter.tracker import repo_path
+
+
+def _root(root: Path | None = None) -> Path:
+    return root if root is not None else repo_path()
+
+
+def _read_yaml(path: Path) -> Any:
+    if not path.exists():
+        return {}
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def _read_json_or_yaml(path: Path) -> Any:
+    text = path.read_text(encoding="utf-8")
+    if path.suffix.lower() == ".json":
+        return json.loads(text)
+    return yaml.safe_load(text) or {}
+
+
+def _clip(value: Any, limit: int) -> str:
+    text = re.sub(r"\s+", " ", str(value or "")).strip()
+    if len(text) <= limit:
+        return text
+    suffix = " ... [truncated]"
+    if limit <= len(suffix):
+        return suffix[:limit]
+    return text[: limit - len(suffix)].rstrip() + suffix
+
+
+def _resolve_path(root: Path, path: Path | str) -> Path:
+    resolved = Path(path)
+    return resolved if resolved.is_absolute() else root / resolved

job_hunter_kit-0.1/job_hunter/agent_context/batch.py

@@ -0,0 +1,125 @@
+"""Candidate batch building and screening helpers."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from job_hunter.agent_context._utils import _read_yaml, _root
+from job_hunter.agent_context.candidates import _title_key
+from job_hunter.config import get_config
+from job_hunter.constants import DEFAULT_BATCH_SIZE
+from job_hunter.sources._policy import JobPolicy
+
+
+def build_candidate_batch(
+    queue: dict[str, Any],
+    *,
+    batch_size: int = DEFAULT_BATCH_SIZE,
+    batch_number: int = 1,
+) -> dict[str, Any]:
+    jobs = queue.get("jobs", []) if isinstance(queue, dict) else []
+    selected = jobs[:batch_size]
+    return {
+        "generated": date.today().isoformat(),
+        "batch_number": batch_number,
+        "batch_size": batch_size,
+        "source_queue_count": len(jobs),
+        "count": len(selected),
+        "jobs": selected,
+    }
+
+
+def _applied_title_keys(root: Path) -> set[str]:
+    keys: set[str] = set()
+    jobs_dir = root / "outputs" / "jobs"
+    if jobs_dir.exists():
+        for meta_path in jobs_dir.glob("*/meta.json"):
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+                continue
+            key = _title_key(meta)
+            if key != "::":
+                keys.add(key)
+
+    readme_path = root / "README.md"
+    if readme_path.exists():
+        try:
+            readme = readme_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            readme = readme_path.read_text(encoding="utf-8", errors="replace")
+        for match in re.finditer(r"\[([^\]]+?) @ ([^\]]+?)\]\(https?://", readme):
+            title, company = match.group(1), match.group(2)
+            keys.add(_title_key({"company": company, "title": title}))
+    return keys
+
+
+def _region_config(search_config: dict[str, Any], region: str) -> dict[str, Any]:
+    regions = search_config.get("regions", {}) or {}
+    cfg = regions.get(region, {})
+    return cfg if isinstance(cfg, dict) else {}
+
+
+def screen_candidate_batch(
+    batch: dict[str, Any],
+    *,
+    root: Path | None = None,
+) -> dict[str, Any]:
+    base = _root(root)
+    search_config = get_config("job_hunter") if base == _root() else _read_yaml(base / "config" / "job_hunter.yml")
+    policy = JobPolicy(search_config)
+    title_filters = search_config.get("job_titles", []) or []
+    applied_keys = _applied_title_keys(base)
+
+    retained: list[dict[str, Any]] = []
+    skipped: list[dict[str, Any]] = []
+    for candidate in batch.get("jobs", []):
+        reasons: list[str] = []
+        title = str(candidate.get("title") or "")
+        snippet = str(candidate.get("snippet") or "")
+        region = str(candidate.get("region") or "")
+        if not policy.accepts_job_content(candidate, title_filters):
+            if policy.is_excluded_company(str(candidate.get("company") or "")):
+                reasons.append("excluded_company")
+            if policy.is_excluded_language(title, snippet):
+                reasons.append("excluded_language")
+            if any(term.lower() in title.lower() for term in policy.excluded_title_terms):
+                reasons.append("excluded_title")
+            if policy.is_excluded_industry(snippet):
+                reasons.append("excluded_industry")
+            if not reasons:
+                reasons.append("title_not_matched")
+        if policy.has_wrong_location(candidate, _region_config(search_config, region)):
+            reasons.append("wrong_location")
+        if policy.is_stale_posting(title, snippet):
+            reasons.append("stale_posting")
+        if _title_key(candidate) in applied_keys:
+            reasons.append("duplicate_application")
+
+        row = {
+            "candidate_id": candidate.get("candidate_id"),
+            "queue_index": candidate.get("queue_index"),
+            "title": candidate.get("title"),
+            "company": candidate.get("company"),
+            "url": candidate.get("url"),
+            "reasons": reasons,
+        }
+        if reasons:
+            skipped.append(row)
+        else:
+            retained.append(row)
+
+    return {
+        "generated": date.today().isoformat(),
+        "batch_number": batch.get("batch_number", 1),
+        "batch_size": batch.get("batch_size", DEFAULT_BATCH_SIZE),
+        "loaded": len(batch.get("jobs", [])),
+        "retained_count": len(retained),
+        "skipped_count": len(skipped),
+        "retained": retained,
+        "skipped": skipped,
+    }

job_hunter_kit-0.1/job_hunter/agent_context/briefing.py

@@ -0,0 +1,194 @@
+"""Briefing and LinkedIn weekly context helpers."""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from job_hunter.agent_context._utils import (
+    _read_json_or_yaml,
+    _read_yaml,
+    _root,
+)
+from job_hunter.agent_context.candidates import (
+    _candidate_files,
+    _jobs_from_candidate_file,
+    build_candidate_queue,
+)
+from job_hunter.agent_context.stories import story_index
+from job_hunter.config.defaults import EXCLUDED_LISTING_URL_PATTERNS, STALE_INDICATORS
+from job_hunter.constants import DEFAULT_BATCH_SIZE
+
+
+def _latest_commit_subject(root: Path) -> str:
+    try:
+        result = subprocess.run(
+            ["git", "log", "-1", "--pretty=%s"],  # noqa: S607
+            cwd=root,
+            text=True,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+    except Exception:
+        return "unknown"
+    return result.stdout.strip() or "unknown"
+
+
+def brief_context(*, root: Path | None = None) -> str:
+    base = _root(root)
+    subject = _latest_commit_subject(base)
+    discovery = "yes" if "discovery" in subject.lower() else "no"
+    queue = build_candidate_queue(root=base, today_only=False, limit=10000)
+    candidate_lines = []
+    for path in _candidate_files(base):
+        try:
+            jobs = _jobs_from_candidate_file(path)
+            candidate_lines.append(f"- `{path.name}`: {len(jobs)} candidates")
+        except Exception:
+            candidate_lines.append(f"- `{path.name}`: unreadable")
+    if not candidate_lines:
+        candidate_lines.append("- none")
+
+    today = date.today().isoformat()
+    jobs_dir = base / "outputs" / "jobs"
+    today_rows: list[str] = []
+    if jobs_dir.exists():
+        for folder in sorted(jobs_dir.iterdir()):
+            if not folder.is_dir():
+                continue
+            meta = _read_json_or_yaml(folder / "meta.json") if (folder / "meta.json").exists() else {}
+            if not (folder.name.startswith(today) or meta.get("date") == today):
+                continue
+            score = _read_yaml(folder / "score.yml")
+            today_rows.append(
+                "| {folder} | {company} | {title} | {score} | {decision} |".format(
+                    folder=folder.name,
+                    company=meta.get("company", ""),
+                    title=meta.get("title", ""),
+                    score=score.get("score", ""),
+                    decision=score.get("decision", score.get("status", "")),
+                )
+            )
+
+    jobs_table = "\n".join(today_rows) if today_rows else "No job folders created today."
+    candidate_summary = "\n".join(candidate_lines[:20])
+    if len(candidate_lines) > 20:
+        candidate_summary += f"\n- ... {len(candidate_lines) - 20} more file(s)"
+
+    return f"""# Agent Brief - {today}
+
+Latest commit: {subject}
+Discovery commit: {discovery}
+
+## Candidate Snapshots
+{candidate_summary}
+
+Unprocessed queue: {queue["count"]} candidate(s) from {len(queue["source_files"])} file(s).
+
+## Today's Jobs
+| Folder | Company | Title | Score | Decision |
+|---|---|---|---|---|
+{jobs_table}
+
+Next:
+- Run `/job-hunter batch` when candidates are ready.
+- Run `/job-hunter one <url>` for a single posting.
+"""
+
+
+def _linkedin_job_limit(root: Path, days: int, limit: int | None) -> tuple[int, str]:
+    if limit is not None and limit > 0:
+        return limit, "cli"
+    scoring = _read_yaml(root / "config" / "job_hunter.yml").get("scoring", {})
+    daily_limit = int(scoring.get("batch_size") or 0)
+    if daily_limit > 0:
+        return daily_limit * max(days, 1), "config:scoring.batch_size * days"
+    return 0, "unlimited"
+
+
+def _effective_region_titles(region_config: dict[str, Any], global_titles: list[str]) -> list[str]:
+    titles = region_config.get("job_titles") or global_titles
+    return [str(title) for title in titles if str(title).strip()]
+
+
+def _llm_search_regions(config: dict[str, Any]) -> list[dict[str, Any]]:
+    global_titles = [str(title) for title in config.get("job_titles", []) or [] if str(title).strip()]
+    regions: list[dict[str, Any]] = []
+    for region_name, region_config in (config.get("regions") or {}).items():
+        if not isinstance(region_config, dict) or not region_config.get("enabled", True):
+            continue
+        regions.append(
+            {
+                "region": str(region_name),
+                "country": str(region_config.get("country") or ""),
+                "location": str(region_config.get("location") or ""),
+                "search_lang": str(region_config.get("search_lang") or ""),
+                "primary": bool(region_config.get("primary", False)),
+                "job_titles": _effective_region_titles(region_config, global_titles),
+            }
+        )
+    return regions
+
+
+def llm_search_config(*, root: Path | None = None) -> dict[str, Any]:
+    """Return compact region/title/exclusion context for agent-driven web search."""
+    base = _root(root)
+    config = _read_yaml(base / "config" / "job_hunter.yml")
+    ljs = (config.get("search") or {}).get("llm_search") or {}
+    scoring = config.get("scoring") or {}
+    exclusions = config.get("exclusions") or {}
+    return {
+        "enabled": bool(ljs.get("enabled", False)),
+        "trigger_threshold": int(ljs.get("trigger_threshold", 999)),
+        "max_results_per_run": int(ljs.get("max_results_per_run", 20)),
+        "batch_size": int(scoring.get("batch_size", DEFAULT_BATCH_SIZE)),
+        "searches_per_title_per_region": 5,
+        "regions": _llm_search_regions(config),
+        "exclusions": {
+            "excluded_companies": [str(company) for company in exclusions.get("companies", []) or []],
+            "excluded_title_terms": [str(term) for term in exclusions.get("title_terms", []) or []],
+            "excluded_url_patterns": [str(pattern) for pattern in EXCLUDED_LISTING_URL_PATTERNS],
+            "excluded_languages": [str(language) for language in exclusions.get("languages", []) or []],
+            "stale_indicators": [str(indicator) for indicator in STALE_INDICATORS],
+        },
+    }
+
+
+def linkedin_weekly_context(
+    *,
+    root: Path | None = None,
+    days: int = 7,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    base = _root(root)
+    job_limit, limit_source = _linkedin_job_limit(base, days, limit)
+    cutoff = datetime.now() - timedelta(days=days)
+    jobs: list[dict[str, Any]] = []
+    jobs_dir = base / "outputs" / "jobs"
+    if jobs_dir.exists():
+        for folder in sorted(jobs_dir.iterdir(), key=lambda p: p.stat().st_mtime, reverse=True):
+            if not folder.is_dir() or datetime.fromtimestamp(folder.stat().st_mtime) < cutoff:
+                continue
+            meta = _read_json_or_yaml(folder / "meta.json") if (folder / "meta.json").exists() else {}
+            score = _read_yaml(folder / "score.yml")
+            jobs.append(
+                {
+                    "slug": folder.name,
+                    "company": meta.get("company", ""),
+                    "title": meta.get("title", ""),
+                    "score": score.get("score", ""),
+                    "decision": score.get("decision", score.get("status", "")),
+                }
+            )
+            if job_limit and len(jobs) >= job_limit:
+                break
+    return {
+        "days": days,
+        "job_limit": job_limit or None,
+        "job_limit_source": limit_source,
+        "jobs": jobs,
+        "story_index": story_index(root=base),
+    }