docs: update README with new sections and adjust BLUEPRINT column list

Author: FAAQJAVED

BLUEPRINT.md

@@ -420,7 +420,7 @@ Adds `Email`, `Phone`, `Lead Quality`, and `Keyword Match %` columns. The `lead_
 ### Step 1: Installation
 
 ```bash
-git clone https://github.com/FAAQJAVED/leadhunter-pro
+git clone https://github.com/<<GITHUB_USERNAME>>/leadhunter-pro
 cd leadhunter-pro
 pip install -r requirements.txt
 python -m playwright install chromium

README.md

@@ -1,35 +1,26 @@
+## Readme** · **MD
+
+Copy
+
 # LeadHunter Pro
 
 **Multi-engine search scraper + contact enricher. Finds business leads, extracts emails & phones, scores lead quality.**
 
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://claude.ai/chat/LICENSE)
-[![CI](https://github.com/FAAQJAVED/Leadhunter_Pro/actions/workflows/ci.yml/badge.svg)](https://github.com/FAAQJAVED/Leadhunter_Pro/actions)
-[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](https://github.com/FAAQJAVED/Leadhunter_Pro)
+[Show Image](https://python.org)
+[Show Image](LICENSE)
+[Show Image](https://github.com/FAAQJAVED/Leadhunter_Pro/actions)
+[Show Image](https://github.com/FAAQJAVED/Leadhunter_Pro)
 
 ---
 
 ## What It Does
 
 LeadHunter Pro searches four independent search engines simultaneously to find real business websites matching your query. It then visits each website to extract a contact email address and phone number, and scores every lead as HOT, WARM, COLD, or NOISE based on how closely the page content matches what you searched for. The final output is a colour-coded Excel spreadsheet, ready to use.
 
----
-
-## Preview
-
-> Add your screenshots to the `assets/` folder and they will appear here automatically.
->
-> See [assets/README.md](https://claude.ai/chat/assets/README.md) for the recommended screenshot guide.
 
-| Phase 1 — Scraping                                                              | Phase 2 — Enrichment                                                            |
-| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| ![Phase 1 scraping in progress](https://claude.ai/chat/assets/phase1-scraping.png) | ![Phase 2 enrichment running](https://claude.ai/chat/assets/phase2-enrichment.png) |
+---
 
-| Excel Output                                                                      | Diagnose Output                                                              |
-| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| ![Colour-coded Excel output](https://claude.ai/chat/assets/excel-output-sample.png) | ![Diagnose terminal output](https://claude.ai/chat/assets/diagnose-output.png) |
 
----
 
 ## How It Works
 
@@ -90,6 +81,8 @@ LeadHunter Pro searches four independent search engines simultaneously to find r
 
 ## Quick Start
 
+bash
+
 ```bash
 git clone https://github.com/FAAQJAVED/Leadhunter_Pro.git
 cd leadhunter-pro
@@ -111,6 +104,8 @@ python main.py
 
 ## Or Run Phases Separately
 
+bash
+
 ```bash
 # Phase 1 only — specific engines, specific query
 python main.py --query "letting agents Manchester" --mojeek --ddg
@@ -136,16 +131,20 @@ python enricher.py --input outputs/leads_2026-05-01.csv
 
 **Bing proxy options:**
 
+python
+
 ```python
 # Authenticated residential proxy
-BING_PROXY = 'http://user:pass@uk.residential.proxy:8080'
+BING_PROXY ='http://user:pass@uk.residential.proxy:8080'
 
 # SOCKS5
-BING_PROXY = 'socks5://user:pass@proxy-host:1080'
+BING_PROXY ='socks5://user:pass@proxy-host:1080'
 ```
 
 ### `config.yaml` — Phase 2 (enricher) settings
 
+bash
+
 ```bash
 cp config.example.yaml config.yaml
 ```
@@ -210,6 +209,8 @@ Key settings: `http_timeout`, `playwright_timeout`, `stop_at`, `contact_paths`,
 
 ## Diagnose Your Engines
 
+bash
+
 ```bash
 python diagnose.py              # test Mojeek, DDG, Yahoo (default)
 python diagnose.py --bing       # test Bing (run with VPN/proxy active)
@@ -240,20 +241,13 @@ Launching a headless browser for every site would take 3–5 s per site versus ~
 
 ## Part of the B2B Lead Toolkit
 
-LeadHunter Pro is the **search and discovery layer** of a three-tool pipeline. Each tool can be used independently, or run in sequence end-to-end.
-
-```
-Google Maps  ──►  LeadHunter Pro  ──►  Email Enricher
-(raw listings)    (verified websites)   (emails + phones)
-```
-
-| Repo                                                                                                         | Role in pipeline                                                                         |
-| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| **[google-maps-scraper](https://github.com/FAAQJAVED/google-maps-scraper)**                               | Extracts raw business listings — name, address, phone, website — from Google Maps      |
-| **[Leadhunter_Pro](https://github.com/FAAQJAVED/Leadhunter_Pro)**←*you are here*                       | Scrapes 4 search engines to find verified company websites, deduplicates and scores them |
-| **[Email-Phone-Number-Enrichment-Tool](https://github.com/FAAQJAVED/Email-Phone-Number-Enrichment-Tool)** | Visits each website to extract contact emails and phone numbers (standalone enricher)    |
+This scraper is one component of a broader B2B lead generation pipeline targeting UK property management companies, letting agents, block managers, and HMO landlords.
 
-> **Note:** LeadHunter Pro includes its own built-in Phase 2 enrichment — so you can run the full pipeline with this tool alone. The standalone enricher is useful if you already have a list of websites from another source (e.g. Google Maps) and just need the contact extraction step.
+| Repo                                                                                                         | What it does                                                                                |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| **[Leadhunter_Pro](https://github.com/FAAQJAVED/Leadhunter_Pro)**←*you are here*                       | Scrapes 4 search engines to find verified company websites, scores and deduplicates results |
+| **[Email-Phone-Number-Enrichment-Tool](https://github.com/FAAQJAVED/Email-Phone-Number-Enrichment-Tool)** | Scrapes contact emails + phones from company websites                                       |
+| **[google-maps-scraper](https://github.com/FAAQJAVED/google-maps-scraper)**                               | Extracts business listings (name, address, phone, website) from Google Maps                 |
 
 ---
 
@@ -272,6 +266,8 @@ If engines return no results, return HTTP 202 / 403, or the tool stops early, it
 
 ### Quick checks first
 
+bash
+
 ```bash
 python diagnose.py --all    # confirms which engines are healthy right now
 ```
@@ -311,16 +307,20 @@ Bing is the most aggressively geo-blocked engine. If you have a residential prox
 
 **Option A — `.env` file (recommended, keeps credentials out of code):**
 
+bash
+
 ```bash
 # .env
 BING_PROXY=http://user:pass@your-proxy-host:8080
 ```
 
 **Option B — `config.py` directly:**
 
+python
+
 ```python
-BING_PROXY = 'http://user:pass@your-proxy-host:8080'   # HTTP proxy
-BING_PROXY = 'socks5://user:pass@your-proxy-host:1080' # SOCKS5 proxy
+BING_PROXY ='http://user:pass@your-proxy-host:8080'# HTTP proxy
+BING_PROXY ='socks5://user:pass@your-proxy-host:1080'# SOCKS5 proxy
 ```
 
 Leave `BING_PROXY` empty to skip Bing entirely and run only the other three engines — they work well without a proxy on most residential connections.
@@ -331,10 +331,12 @@ Leave `BING_PROXY` empty to skip Bing entirely and run only the other three engi
 
 If you are hitting limits frequently, edit `config.py`:
 
+python
+
 ```python
-DELAY_BETWEEN_REQUESTS = (8, 15)   # seconds between individual HTTP requests (default 3–8)
-DELAY_BETWEEN_QUERIES  = (30, 60)  # seconds between queries (default 20–45)
-DELAY_BETWEEN_ENGINES  = (90, 150) # seconds between engines (default 60–120)
+DELAY_BETWEEN_REQUESTS =(8,15)# seconds between individual HTTP requests (default 3–8)
+DELAY_BETWEEN_QUERIES  =(30,60)# seconds between queries (default 20–45)
+DELAY_BETWEEN_ENGINES  =(90,150)# seconds between engines (default 60–120)
 ```
 
 The tool will still run — it just paces itself more cautiously.
@@ -343,4 +345,4 @@ The tool will still run — it just paces itself more cautiously.
 
 ## License
 
-MIT — see [LICENSE](https://claude.ai/chat/LICENSE)
+MIT — see [LICENSE](LICENSE)

assets/README.md

@@ -0,0 +1,15 @@
+# Screenshots
+
+Place your preview images here and reference them in the main README.md using:
+
+![Phase 1 — scraping in progress](assets/phase1-scraping.png)
+![Phase 2 — enrichment running](assets/phase2-enrichment.png)
+![Excel output](assets/excel-output-sample.png)
+![Diagnose output](assets/diagnose-output.png)
+
+## Recommended screenshots
+
+- `phase1-scraping.png` — tqdm progress bar during a live Phase 1 run in VS Code terminal
+- `phase2-enrichment.png` — enricher running with live HOT/WARM/COLD output visible
+- `excel-output-sample.png` — the colour-coded Excel output open in Excel/LibreOffice
+- `diagnose-output.png` — diagnose.py terminal output showing all engines passing

config.py

@@ -1,7 +1,8 @@
 # config.py — LeadHunter Pro: All Tuneable Settings
 
-from os import path as os_path
 import os
+from os import path as os_path
+
 try:
     from dotenv import load_dotenv
     load_dotenv()

core/__init__.py

@@ -10,35 +10,35 @@
   relevance     — query-keyword lead quality scoring
 """
 
+from core.browser_utils import dismiss_cookie_banner, enrich_one_browser, launch_browser
+from core.controls import (
+    AutoSaver,
+    ControlListener,
+    State,
+    check_cmd_file,
+    check_disk,
+    has_internet,
+    should_stop,
+    wait_for_internet,
+    wait_if_paused,
+)
 from core.email_utils import (
-    extract_emails_raw,
-    extract_emails_full,
+    best_email,
     decode_cloudflare_email,
+    extract_emails_full,
+    extract_emails_raw,
     extract_phones,
     score_email,
-    best_email,
 )
-from core.http_utils import fetch_url, enrich_one_http
-from core.browser_utils import launch_browser, dismiss_cookie_banner, enrich_one_browser
+from core.http_utils import enrich_one_http, fetch_url
+from core.relevance import score_relevance
 from core.storage import (
-    save_checkpoint,
+    get_output_path,
     load_checkpoint,
-    save_output,
     load_existing_output,
-    get_output_path,
-)
-from core.controls import (
-    State,
-    ControlListener,
-    AutoSaver,
-    check_cmd_file,
-    wait_if_paused,
-    should_stop,
-    has_internet,
-    wait_for_internet,
-    check_disk,
+    save_checkpoint,
+    save_output,
 )
-from core.relevance import score_relevance
 
 __all__ = [
     # email_utils

core/_log.py

@@ -16,10 +16,9 @@
 from __future__ import annotations
 
 import time
-from typing import Optional
 
 _start_time: float = time.time()
-_active_bar: Optional[object] = None
+_active_bar: object | None = None
 
 
 def set_start_time(t: float) -> None:
@@ -28,7 +27,7 @@ def set_start_time(t: float) -> None:
     _start_time = t
 
 
-def set_active_bar(bar: Optional[object]) -> None:
+def set_active_bar(bar: object | None) -> None:
     """
     Register (or clear) the active tqdm progress bar.
 

core/browser_utils.py

@@ -26,14 +26,13 @@
 from __future__ import annotations
 
 import time
-from typing import List, Tuple
 
 from core._log import log
 from core.email_utils import (
+    best_email,
     extract_emails_full,
     extract_phones,
     score_email,
-    best_email,
 )
 from core.http_utils import _rate_limit, random_ua
 
@@ -119,7 +118,7 @@ def dismiss_cookie_banner(page, cfg: dict) -> None:  # noqa: ANN001
             pass
 
 
-def enrich_one_browser(page, target: dict, cfg: dict) -> Tuple[str, str]:
+def enrich_one_browser(page, target: dict, cfg: dict) -> tuple[str, str]:
     """
     Pass 2: find a contact email **and** phone using a Playwright-rendered page.
 
@@ -147,8 +146,8 @@ def enrich_one_browser(page, target: dict, cfg: dict) -> Tuple[str, str]:
     base          = target["website"].rstrip("/")
     contact_paths = cfg.get("contact_paths", ["/contact", "/about"])
     pw_timeout    = cfg.get("playwright_timeout", 8000)
-    emails: List[str] = []
-    phones: List[str] = []
+    emails: list[str] = []
+    phones: list[str] = []
 
     urls_to_visit = [base] + [base + p for p in contact_paths[:2]]
 

core/controls.py

@@ -17,8 +17,6 @@
 
 from __future__ import annotations
 
-from datetime import datetime
-
 import os
 import platform
 import select
@@ -27,11 +25,11 @@
 import sys
 import threading
 import time
+from datetime import datetime
 
 from core._log import log
 from core.storage import save_output
 
-
 # ── Shared run state ──────────────────────────────────────────────────────────
 
 class State:
@@ -113,15 +111,19 @@ def _handle(self, key: str) -> None:
         if key == "P":
             s.paused = not s.paused
             if s.paused:
-                log("PAUSED — press P or R to resume", "warn");  _beep("stop")
+                log("PAUSED — press P or R to resume", "warn")
+                _beep("stop")
             else:
-                log("RESUMED", "good");                           _beep("resume")
+                log("RESUMED", "good")
+                _beep("resume")
         elif key == "R" and s.paused:
             s.paused = False
-            log("RESUMED", "good");                               _beep("resume")
+            log("RESUMED", "good")
+            _beep("resume")
         elif key == "Q":
             s.stop = True
-            log("QUIT — saving and exiting …", "warn");           _beep("stop")
+            log("QUIT — saving and exiting …", "warn")
+            _beep("stop")
         elif key == "S":
             log(
                 f"status → found:{self._ctx.get('found', 0)} "
@@ -277,11 +279,17 @@ def check_cmd_file(state: State, cmd_file: str, checkpoint_file: str) -> None:
             _f.write("")
 
         if cmd == "pause":
-            state.paused = True;  log("PAUSED (cmd file)", "warn");   _beep("stop")
+            state.paused = True
+            log("PAUSED (cmd file)", "warn")
+            _beep("stop")
         elif cmd in ("resume", "r"):
-            state.paused = False; log("RESUMED (cmd file)", "good");   _beep("resume")
+            state.paused = False
+            log("RESUMED (cmd file)", "good")
+            _beep("resume")
         elif cmd in ("stop", "q"):
-            state.stop = True;    log("STOP — saving …", "warn");      _beep("stop")
+            state.stop = True
+            log("STOP — saving …", "warn")
+            _beep("stop")
         elif cmd == "fresh":
             if os.path.exists(checkpoint_file):
                 os.remove(checkpoint_file)