jobhunter-cli 0.0.post1.dev85__tar.gz

jobhunter_cli-0.0.post1.dev85/.env.example

@@ -0,0 +1,6 @@
+# Telegram: create a bot at https://t.me/BotFather and get the bot token, then start a chat with your bot and get the chat ID.
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+
+# OpenAI: create an account at https://platform.openai.com/ and generate an API key.
+LLM_API_KEY=

jobhunter_cli-0.0.post1.dev85/.github/workflows/job-maintenance.yml

@@ -0,0 +1,78 @@
+name: Job Maintenance & Discovery
+
+on:
+  schedule:
+    # Runs once a week: every Sunday at 3:00 AM UTC
+    - cron: '0 3 * * 0'
+  workflow_dispatch:
+    inputs:
+      source:
+        description: 'Run discovery/prune for a specific source only (optional)'
+        type: string
+        required: false
+        default: ''
+
+jobs:
+  maintenance:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up UV and Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+          cache: "uv"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run Discover and Prune if config.json exists
+        run: |
+          if [ ! -f "config/config.json" ]; then
+            echo "config/config.json does not exist. Skipping maintenance tasks."
+            exit 0
+          fi
+
+          SOURCE_FLAG=""
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ] && [ -n "${{ inputs.source }}" ]; then
+            SOURCE_FLAG="--source ${{ inputs.source }}"
+          fi
+
+          echo "Running discovery..."
+          uv run jobhunter discover --write $SOURCE_FLAG
+
+          echo "Running pruning..."
+          uv run jobhunter prune --write $SOURCE_FLAG
+
+      - name: Commit and push updated config.json
+        run: |
+          if [ ! -f "config/config.json" ]; then
+            exit 0
+          fi
+
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git status
+
+          if [ -f "config/config.json" ]; then
+            git add config/config.json
+          fi
+
+          if git diff --staged --quiet; then
+            echo "No changes in config.json to commit."
+          else
+            git commit -m "chore(maintenance): update company board configuration [skip ci]"
+            git push
+          fi

jobhunter_cli-0.0.post1.dev85/.github/workflows/job-pipeline.yml

@@ -0,0 +1,139 @@
+name: Job Pipeline
+
+on:
+  schedule:
+    # 1. First daily run (Aggregators ENABLED)
+    - cron: "0 6 * * *"
+    # 2. Subsequent daily runs (Aggregators DISABLED)
+    - cron: "0 14,22 * * *"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Run pipeline in dry-run mode (no telegram notifications sent)"
+        type: boolean
+        required: false
+        default: false
+      ignore_seen:
+        description: "Ignore seen history cache and re-process recent jobs"
+        type: boolean
+        required: false
+        default: false
+      no_aggregators:
+        description: "Disable aggregator sources (Remotive, RemoteOK, Arbeitnow)"
+        type: boolean
+        required: false
+        default: true
+      source:
+        description: "Run for a specific source/company only (optional)"
+        type: string
+        required: false
+        default: ""
+      limit:
+        description: "Limit maximum candidates per run (optional)"
+        type: number
+        required: false
+        default: 0
+
+jobs:
+  run-pipeline:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up UV and Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Check existing state files before run
+        id: check-state
+        run: |
+          if [ -f "data/candidates.json" ]; then
+            echo "candidates_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "candidates_exists=false" >> $GITHUB_OUTPUT
+          fi
+          if [ -f "data/evaluated.json" ]; then
+            echo "evaluated_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "evaluated_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run JobHunter Pipeline
+        env:
+          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          CONFIG_JSON: ${{ secrets.CONFIG_JSON }}
+          CV: ${{ secrets.CV }}
+          PREFERENCES: ${{ secrets.PREFERENCES }}
+        run: |
+          CMD="uv run jobhunter run"
+
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            if [ "${{ inputs.no_aggregators }}" == "true" ]; then
+              CMD="$CMD --no-aggregators"
+            fi
+            if [ "${{ inputs.dry_run }}" == "true" ]; then
+              CMD="$CMD --dry-run"
+            fi
+            if [ "${{ inputs.ignore_seen }}" == "true" ]; then
+              CMD="$CMD --ignore-seen"
+            fi
+            if [ -n "${{ inputs.source }}" ]; then
+              CMD="$CMD --source ${{ inputs.source }}"
+            fi
+            if [ -n "${{ inputs.limit }}" ] && [ "${{ inputs.limit }}" -gt 0 ]; then
+              CMD="$CMD --limit ${{ inputs.limit }}"
+            fi
+          elif [ "${{ github.event_name }}" == "schedule" ]; then
+            if [ "${{ github.event.schedule }}" == "0 6 * * *" ]; then
+              echo "Morning schedule triggered: Aggregators ENABLED"
+            else
+              echo "Subsequent schedule triggered: Aggregators DISABLED"
+              CMD="$CMD --no-aggregators"
+            fi
+          fi
+
+          echo "Executing: $CMD"
+          eval $CMD
+
+      - name: Commit and push state files
+        env:
+          CANDIDATES_EXISTS: ${{ steps.check-state.outputs.candidates_exists }}
+          EVALUATED_EXISTS: ${{ steps.check-state.outputs.evaluated_exists }}
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git status
+
+          git add data/seen.json
+
+          if [ "$CANDIDATES_EXISTS" == "true" ] && [ -f "data/candidates.json" ]; then
+            git add data/candidates.json
+          fi
+
+          if [ "$EVALUATED_EXISTS" == "true" ] && [ -f "data/evaluated.json" ]; then
+            git add data/evaluated.json
+          fi
+
+          if git diff --staged --quiet; then
+            echo "No state file changes to commit."
+          else
+            git commit -m "chore(pipeline): update jobhunter state files [skip ci]"
+            git push
+          fi

jobhunter_cli-0.0.post1.dev85/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Auto Publish & Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build, Release, and Publish
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/jobhunter-cli
+
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: false
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v1.0-${{ github.run_number }}
+          name: Release 1.0 (Build ${{ github.run_number }})
+          generate_release_notes: true
+          files: dist/*

jobhunter_cli-0.0.post1.dev85/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+_version.py
+*.egg-info
+.locks
+logs
+todo.txt
+
+# Virtual environments
+.venv
+
+# Secrets and personal files
+.env
+config/*
+!config/.gitkeep
+
+# Generated by the tool. Only data/seen.json is meant to be committed (the GitHub Actions workflow does it).
+data/*
+!data/.gitkeep
+!data/seen.json

jobhunter_cli-0.0.post1.dev85/.python-version

@@ -0,0 +1 @@
+3.14

jobhunter_cli-0.0.post1.dev85/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ziad Aboughaleb
+
+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.

jobhunter_cli-0.0.post1.dev85/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: jobhunter-cli
+Version: 0.0.post1.dev85
+Summary: An AI-powered, zero-database Python CLI that automates job hunting. It scrapes ATS boards, evaluates candidate-job fit using LLMs against your CV, and dispatches real-time Telegram alerts.
+Author-email: ziad-aboughaleb <ziadaboughaleb@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: ddgs>=9.16.1
+Requires-Dist: filelock>=4.2.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: openai>=3.41.0
+Requires-Dist: pydantic-settings>=2.16.1
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.3
+Description-Content-Type: text/markdown
+
+# JobHunter 🎯
+
+> **AI-Powered, Highly Concurrent, Zero-Database Automated Job Hunting Pipeline**
+
+`JobHunter` is a robust, production-grade Python CLI application designed to fully automate the job search and filtering lifecycle. It continuously scrapes Applicant Tracking Systems (ATS) and job boards, filters opportunities against precise regex and keyword criteria, evaluates candidate-job fit using Large Language Models (LLMs) with strict JSON schemas, and dispatches rich real-time alerts directly to Telegram.
+
+---
+
+## 🚀 Key Features
+
+- **High Concurrency & Rate Limiting**: Powered by `concurrent.futures` with dynamic worker bounds, exponential backoff retries on transient network errors, and intelligent request pacing.
+- **ATS WAF & API Bypass**: Bypasses heavy frontend anti-bot walls by querying official public underlying JSON/XML board APIs directly (Greenhouse, Lever, Personio, Workable, Recruitee, Ashby, plus aggregators like Remotive, RemoteOK, and Arbeitnow).
+- **Multi-Stage Filtering**: Filters jobs through regex word-boundary matching for titles, excluded companies, location rules, remote requirements, posting age, and minimum tech stack keyword hits (`stack_hits`).
+- **AI-Driven Evaluation**: Evaluates shortlisted candidates against your exact CV (`config/cv.md`) and preferences (`config/preferences.md`) using OpenAI-compatible LLMs, enforcing hard gates, scoring rubrics, and anti-hallucination guardrails.
+- **Telegram Rich Alerts**: Dispatches beautifully formatted HTML notifications featuring VIP priority badges, score color-coding, AI reasoning, score breakdowns, professional pitches, and direct links.
+- **Autonomous Maintenance Tools**: Includes built-in CLI commands to automatically discover new company career boards via DuckDuckGo and prune dead or broken board URLs.
+- **Zero-Database State Management**: Uses atomic file writes with file locking (`filelock`) and a rolling 90-day retention cache (`seen.json`) to prevent duplicate processing without requiring an external database.
+
+---
+
+## 🛠️ Quickstart Guide
+
+### Prerequisites
+
+- **Python >= 3.14**
+- **uv** (recommended Python package and project manager)
+
+### 1. Install
+
+Install the CLI globally via PyPI using `uv` (recommended) or `pip`:
+
+```bash
+uv tool install jobhunter-cli
+# OR
+pip install jobhunter-cli
+```
+
+### 2. Initialize Your Workspace
+
+Create a dedicated folder for your job search and run the `init` command to automatically download the configuration templates:
+
+```bash
+mkdir my-job-search && cd my-job-search
+jobhunter init
+```
+
+### 3. Configure
+
+The `init` command creates a `.env` file and a `config/` directory.
+
+1. Open `.env` and add your API keys:
+   ```env
+   TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+   TELEGRAM_CHAT_ID=your_telegram_chat_id_here
+   LLM_API_KEY=your_openai_or_compatible_api_key_here
+   ```
+2. Edit the templates in the `config/` folder (`config.json`, `cv.md`, `preferences.md`) with your specific details.
+
+> **💡 Note on GitHub Actions:** `JobHunter` automatically falls back to environment variables (`CONFIG_JSON`, `CV`, `PREFERENCES`) if physical files do not exist on disk. This allows deploying via GitHub Actions on public repositories using GitHub Secrets.
+
+### 4. Run the Pipeline
+
+Execute the full pipeline (Fetch -> Evaluate -> Send) from within your workspace directory:
+
+```bash
+jobhunter run
+```
+
+---
+
+## 🔄 The 5-Stage Pipeline
+
+```
+[Discover / Configure] ──> [Fetch & Filter] ──> [AI Evaluate] ──> [Send to Telegram] ──> [State Purge & Seen Sync]
+```
+
+1. **Discover / Configure**: Resolve targets from `config.json` or discover new company boards using `jobhunter discover`.
+2. **Fetch**: Scrape raw job postings concurrently across configured ATS boards and aggregators.
+3. **Filter & Prune**: Discard duplicates, previously seen jobs, and postings failing title, location, age, or stack keyword criteria. Rank candidates by VIP priority and stack keyword hits.
+4. **Evaluate**: Submit shortlisted candidates to the LLM. Enforce hard gates and score against your CV and preferences.
+5. **Send & Purge**: Dispatch passing job alerts to Telegram. Log processed jobs to `seen.json` with a 90-day retention window and purge completed items from active state files.
+
+---
+
+## 📖 Documentation Deep Dives
+
+For comprehensive technical documentation, consult the downloaded `docs/` folder or view them on GitHub:
+
+- **[Architecture Guide](docs/architecture.md)**: Detailed breakdown of the decoupled pipeline modules, concurrency model, and zero-database state lifecycle.
+- **[Configuration & Settings](docs/configuration.md)**: Comprehensive guide to `config.json`, Pydantic settings, environment variables, and prompt engineering setup (`cv.md` / `preferences.md`).
+
+---
+
+## 💻 CLI Commands Reference
+
+| Command              | Description                                                 | Key Options                                                                                                                                                                                                                    |
+| :------------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jobhunter init`     | Scaffolds a new workspace by downloading templates and docs | `[TARGET_DIR]` (Target directory to initialize)                                                                                                                                                                                |
+| `jobhunter run`      | Runs the full pipeline (fetch -> evaluate -> send)          | `-s, --source` (Specific ATS/aggregator to fetch from)<br>`--no-aggregators` (Skip aggregators)<br>`--ignore-seen` (Ignore seen cache)<br>`-l, --limit` (Override max candidates)<br>`--dry-run` (Alert without cache updates) |
+| `jobhunter fetch`    | Scrapes and filters jobs from configured boards             | `-s, --source`, `--no-aggregators`, `--ignore-seen`, `-l, --limit`                                                                                                                                                             |
+| `jobhunter evaluate` | Scores and evaluates pending candidates using AI            | `-j, --job` (Evaluate specific job UID), `-l, --limit`                                                                                                                                                                         |
+| `jobhunter send`     | Dispatches passing job evaluations to Telegram              | `--dry-run`                                                                                                                                                                                                                    |
+| `jobhunter discover` | Discovers new company ATS slugs via DuckDuckGo              | `-w, --write` (Persist to config), `-s, --source`, `-t, --titles` (Comma-separated titles)                                                                                                                                     |
+| `jobhunter prune`    | Validates and prunes broken company slugs from config       | `-w, --write`, `-s, --source`                                                                                                                                                                                                  |
+| `jobhunter prompt`   | Prints the compiled AI evaluation system prompt             | None                                                                                                                                                                                                                           |
+
+---
+
+## 🏗️ Building from Source (Development)
+
+If you want to contribute or modify the source code directly:
+
+```bash
+git clone https://github.com/ziad-aboughaleb/job-hunter.git
+cd job-hunter
+uv sync
+uv run jobhunter init
+uv run jobhunter run
+```

jobhunter_cli-0.0.post1.dev85/README.md

@@ -0,0 +1,119 @@
+# JobHunter 🎯
+
+> **AI-Powered, Highly Concurrent, Zero-Database Automated Job Hunting Pipeline**
+
+`JobHunter` is a robust, production-grade Python CLI application designed to fully automate the job search and filtering lifecycle. It continuously scrapes Applicant Tracking Systems (ATS) and job boards, filters opportunities against precise regex and keyword criteria, evaluates candidate-job fit using Large Language Models (LLMs) with strict JSON schemas, and dispatches rich real-time alerts directly to Telegram.
+
+---
+
+## 🚀 Key Features
+
+- **High Concurrency & Rate Limiting**: Powered by `concurrent.futures` with dynamic worker bounds, exponential backoff retries on transient network errors, and intelligent request pacing.
+- **ATS WAF & API Bypass**: Bypasses heavy frontend anti-bot walls by querying official public underlying JSON/XML board APIs directly (Greenhouse, Lever, Personio, Workable, Recruitee, Ashby, plus aggregators like Remotive, RemoteOK, and Arbeitnow).
+- **Multi-Stage Filtering**: Filters jobs through regex word-boundary matching for titles, excluded companies, location rules, remote requirements, posting age, and minimum tech stack keyword hits (`stack_hits`).
+- **AI-Driven Evaluation**: Evaluates shortlisted candidates against your exact CV (`config/cv.md`) and preferences (`config/preferences.md`) using OpenAI-compatible LLMs, enforcing hard gates, scoring rubrics, and anti-hallucination guardrails.
+- **Telegram Rich Alerts**: Dispatches beautifully formatted HTML notifications featuring VIP priority badges, score color-coding, AI reasoning, score breakdowns, professional pitches, and direct links.
+- **Autonomous Maintenance Tools**: Includes built-in CLI commands to automatically discover new company career boards via DuckDuckGo and prune dead or broken board URLs.
+- **Zero-Database State Management**: Uses atomic file writes with file locking (`filelock`) and a rolling 90-day retention cache (`seen.json`) to prevent duplicate processing without requiring an external database.
+
+---
+
+## 🛠️ Quickstart Guide
+
+### Prerequisites
+
+- **Python >= 3.14**
+- **uv** (recommended Python package and project manager)
+
+### 1. Install
+
+Install the CLI globally via PyPI using `uv` (recommended) or `pip`:
+
+```bash
+uv tool install jobhunter-cli
+# OR
+pip install jobhunter-cli
+```
+
+### 2. Initialize Your Workspace
+
+Create a dedicated folder for your job search and run the `init` command to automatically download the configuration templates:
+
+```bash
+mkdir my-job-search && cd my-job-search
+jobhunter init
+```
+
+### 3. Configure
+
+The `init` command creates a `.env` file and a `config/` directory.
+
+1. Open `.env` and add your API keys:
+   ```env
+   TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+   TELEGRAM_CHAT_ID=your_telegram_chat_id_here
+   LLM_API_KEY=your_openai_or_compatible_api_key_here
+   ```
+2. Edit the templates in the `config/` folder (`config.json`, `cv.md`, `preferences.md`) with your specific details.
+
+> **💡 Note on GitHub Actions:** `JobHunter` automatically falls back to environment variables (`CONFIG_JSON`, `CV`, `PREFERENCES`) if physical files do not exist on disk. This allows deploying via GitHub Actions on public repositories using GitHub Secrets.
+
+### 4. Run the Pipeline
+
+Execute the full pipeline (Fetch -> Evaluate -> Send) from within your workspace directory:
+
+```bash
+jobhunter run
+```
+
+---
+
+## 🔄 The 5-Stage Pipeline
+
+```
+[Discover / Configure] ──> [Fetch & Filter] ──> [AI Evaluate] ──> [Send to Telegram] ──> [State Purge & Seen Sync]
+```
+
+1. **Discover / Configure**: Resolve targets from `config.json` or discover new company boards using `jobhunter discover`.
+2. **Fetch**: Scrape raw job postings concurrently across configured ATS boards and aggregators.
+3. **Filter & Prune**: Discard duplicates, previously seen jobs, and postings failing title, location, age, or stack keyword criteria. Rank candidates by VIP priority and stack keyword hits.
+4. **Evaluate**: Submit shortlisted candidates to the LLM. Enforce hard gates and score against your CV and preferences.
+5. **Send & Purge**: Dispatch passing job alerts to Telegram. Log processed jobs to `seen.json` with a 90-day retention window and purge completed items from active state files.
+
+---
+
+## 📖 Documentation Deep Dives
+
+For comprehensive technical documentation, consult the downloaded `docs/` folder or view them on GitHub:
+
+- **[Architecture Guide](docs/architecture.md)**: Detailed breakdown of the decoupled pipeline modules, concurrency model, and zero-database state lifecycle.
+- **[Configuration & Settings](docs/configuration.md)**: Comprehensive guide to `config.json`, Pydantic settings, environment variables, and prompt engineering setup (`cv.md` / `preferences.md`).
+
+---
+
+## 💻 CLI Commands Reference
+
+| Command              | Description                                                 | Key Options                                                                                                                                                                                                                    |
+| :------------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jobhunter init`     | Scaffolds a new workspace by downloading templates and docs | `[TARGET_DIR]` (Target directory to initialize)                                                                                                                                                                                |
+| `jobhunter run`      | Runs the full pipeline (fetch -> evaluate -> send)          | `-s, --source` (Specific ATS/aggregator to fetch from)<br>`--no-aggregators` (Skip aggregators)<br>`--ignore-seen` (Ignore seen cache)<br>`-l, --limit` (Override max candidates)<br>`--dry-run` (Alert without cache updates) |
+| `jobhunter fetch`    | Scrapes and filters jobs from configured boards             | `-s, --source`, `--no-aggregators`, `--ignore-seen`, `-l, --limit`                                                                                                                                                             |
+| `jobhunter evaluate` | Scores and evaluates pending candidates using AI            | `-j, --job` (Evaluate specific job UID), `-l, --limit`                                                                                                                                                                         |
+| `jobhunter send`     | Dispatches passing job evaluations to Telegram              | `--dry-run`                                                                                                                                                                                                                    |
+| `jobhunter discover` | Discovers new company ATS slugs via DuckDuckGo              | `-w, --write` (Persist to config), `-s, --source`, `-t, --titles` (Comma-separated titles)                                                                                                                                     |
+| `jobhunter prune`    | Validates and prunes broken company slugs from config       | `-w, --write`, `-s, --source`                                                                                                                                                                                                  |
+| `jobhunter prompt`   | Prints the compiled AI evaluation system prompt             | None                                                                                                                                                                                                                           |
+
+---
+
+## 🏗️ Building from Source (Development)
+
+If you want to contribute or modify the source code directly:
+
+```bash
+git clone https://github.com/ziad-aboughaleb/job-hunter.git
+cd job-hunter
+uv sync
+uv run jobhunter init
+uv run jobhunter run
+```