Planned project from a 237-line spec

Full stability ranking — all 9 mds

Sorted by stdev across 3 runs. Lower = more reproducible. All the mds you've heard of (Karpathy, OpenAI Codex, HumanLayer, shanraisshan) sit alongside Dory's.

N-variance viewer — how stable is each CLAUDE.md across runs?

Same md, same prompt, 3 different runs. Sorted by instability — refusals and high-stdev variants at the top.

Score grid (9 variants × 3 runs)

Each cell is the mean of 3 judges. Click any cell to inspect the diff and the judges' rationales. Below the grid, per-variant tabs let you compare diffs side-by-side across runs and view the variant's CLAUDE.md inline.

Per-variant deep-dive

For each variant: stats across runs, diffs side-by-side (did the same CLAUDE.md produce the same code on different runs?), and the CLAUDE.md content itself.

diff --git a/plan.md b/plan.md
new file mode 100644
index 0000000..4e14df7
--- /dev/null
+++ b/plan.md
@@ -0,0 +1,237 @@
+# Serbian Real-Estate Scraper — Build Plan
+
+Status: implemented (live in `agent_tools/serbian_realestate/`).
+This document is the design spec to rebuild from scratch if needed.
+
+## 1. Goal
+
+Daily-runnable monitor of Serbian rental classifieds, filtered to user-defined criteria (location + min m² + max price). Outputs a deduped table with vision-verified river-view detection. Costs <$1/day in API tokens.
+
+## 2. Architecture
+
+Single Python package under `agent_tools/serbian_realestate/`, `uv`-managed.
+
+```
+agent_tools/serbian_realestate/
+├── pyproject.toml          # uv-managed: httpx, beautifulsoup4, undetected-chromedriver,
+│                           # playwright, playwright-stealth, anthropic, pyyaml, rich
+├── README.md
+├── search.py               # CLI entrypoint
+├── config.yaml             # Filter profiles (BW, Vracar, etc.)
+├── filters.py              # Match criteria + river-view text patterns
+├── scrapers/
+│   ├── base.py             # Listing dataclass, HttpClient, Scraper base, helpers
+│   ├── photos.py           # Generic photo URL extraction
+│   ├── river_check.py      # Sonnet vision verification + base64 fallback
+│   ├── fzida.py            # 4zida.rs            — plain HTTP
+│   ├── nekretnine.py       # nekretnine.rs       — plain HTTP, paginated
+│   ├── kredium.py          # kredium.rs          — plain HTTP
+│   ├── cityexpert.py       # cityexpert.rs       — Playwright (CF)
+│   ├── indomio.py          # indomio.rs          — Playwright (Distil)
+│   └── halooglasi.py       # halooglasi.com      — Selenium + undetected-chromedriver (CF)
+└── state/
+    ├── last_run_{location}.json    # Diff state + cached river evidence
+    ├── cache/                       # HTML cache by source
+    └── browser/                     # Persistent browser profiles for CF sites
+        └── halooglasi_chrome_profile/
+```
+
+## 3. Per-site implementation method
+
+| Site | Method | Reason |
+|---|---|---|
+| 4zida | plain HTTP | List page is JS-rendered but detail URLs are server-side; detail pages are server-rendered |
+| nekretnine.rs | plain HTTP, paginated | Loose location filter — must keyword-filter URLs post-fetch |
+| kredium | plain HTTP, section-scoped parsing | Whole-body parsing pollutes via related-listings carousel |
+| cityexpert | Playwright | CF-protected; URL is `/en/properties-for-rent/belgrade?ptId=1&currentPage=N` |
+| indomio | Playwright | Distil bot challenge; per-municipality URL `/en/to-rent/flats/belgrade-savski-venac` |
+| **halooglasi** | **Selenium + undetected-chromedriver** | Cloudflare aggressive — Playwright capped at 25-30%, uc gets ~100% |
+
+## 4. Critical lessons learned (these bit us during build)
+
+### 4.1 Halo Oglasi (the hardest site)
+
+- **Cannot use Playwright** — Cloudflare challenges every detail page; extraction plateaus at 25-30% even with `playwright-stealth`, persistent storage, reload-on-miss
+- **Use `undetected-chromedriver`** with real Google Chrome (not Chromium)
+- **`page_load_strategy="eager"`** — without it `driver.get()` hangs indefinitely on CF challenge pages (window load event never fires)
+- **Pass Chrome major version explicitly** to `uc.Chrome(version_main=N)` — auto-detect ships chromedriver too new for installed Chrome (Chrome 147 + chromedriver 148 = `SessionNotCreated`)
+- **Persistent profile dir** at `state/browser/halooglasi_chrome_profile/` keeps CF clearance cookies between runs
+- **`time.sleep(8)` then poll** — CF challenge JS blocks the main thread, so `wait_for_function`-style polling can't run during it. Hard sleep, then check.
+- **Read structured data, not regex body text** — Halo Oglasi exposes `window.QuidditaEnvironment.CurrentClassified.OtherFields` with fields:
+  - `cena_d` (price EUR)
+  - `cena_d_unit_s` (must be `"EUR"`)
+  - `kvadratura_d` (m²)
+  - `sprat_s`, `sprat_od_s` (floor / total floors)
+  - `broj_soba_s` (rooms)
+  - `tip_nekretnine_s` (`"Stan"` for residential)
+- **Headless `--headless=new` works** on cold profile; if rate drops, fall back to xvfb headed mode (`sudo apt install xvfb && xvfb-run -a uv run ...`)
+
+### 4.2 nekretnine.rs
+
+- Location filter is **loose** — bleeds non-target listings. Keyword-filter URLs post-fetch using `location_keywords` from config
+- **Skip sale listings** with `item_category=Prodaja` — rental search bleeds sales via shared infrastructure
+- Pagination via `?page=N`, walk up to 5 pages
+
+### 4.3 kredium
+
+- **Section-scoped parsing only** — using full body text pollutes via related-listings carousel (every listing tags as the wrong building)
+- Scope to `<section>` containing "Informacije" / "Opis" headings
+
+### 4.4 4zida
+
+- List page is JS-rendered but **detail URLs are present in HTML** as `href` attributes — extract via regex
+- Detail pages are server-rendered, no JS gymnastics needed
+
+### 4.5 cityexpert
+
+- Wrong URL pattern (`/en/r/belgrade/belgrade-waterfront`) returns 404
+- **Right URL**: `/en/properties-for-rent/belgrade?ptId=1` (apartments only)
+- Pagination via `?currentPage=N` (NOT `?page=N`)
+- Bumped MAX_PAGES to 10 because BW listings are sparse (~1 per 5 pages)
+
+### 4.6 indomio
+
+- SPA with Distil bot challenge
+- Detail URLs have **no descriptive slug** — just `/en/{numeric-ID}`
+- **Card-text filter** instead of URL-keyword filter (cards have "Belgrade, Savski Venac: Dedinje" in text)
+- Server-side filter params don't work; only municipality URL slug filters
+- 8s SPA hydration wait before card collection
+
+## 5. River-view verification (two-signal AND)
+
+### 5.1 Text patterns (`filters.py`)
+
+Required Serbian phrasings (case-insensitive):
+- `pogled na (reku|reci|reke|Savu|Savi|Save)`
+- `pogled na (Adu|Ada Ciganlij)` (Ada Ciganlija lake)
+- `pogled na (Dunav|Dunavu)` (Danube)
+- `prvi red (do|uz|na) (reku|Save|...)`
+- `(uz|pored|na obali) (reku|reci|reke|Save|Savu|Savi)`
+- `okrenut .{0,30} (reci|reke|Save|...)`
+- `panoramski pogled .{0,60} (reku|Save|river|Sava)`
+
+**Do NOT match:**
+- bare `reka` / `reku` (too generic, used in non-view contexts)
+- bare `Sava` (street name "Savska" appears in every BW address)
+- `waterfront` (matches the complex name "Belgrade Waterfront" — false positive on every BW listing)
+
+### 5.2 Photo verification (`scrapers/river_check.py`)
+
+- **Model**: `claude-sonnet-4-6`
+  - Haiku 4.5 was too generous, calling distant grey strips "rivers"
+- **Strict prompt**: water must occupy meaningful portion of frame, not distant sliver
+- **Verdicts**: only `yes-direct` counts as positive
+  - `yes-distant` deliberately removed (legacy responses coerced to `no`)
+  - `partial`, `indoor`, `no` are non-positive
+- **Inline base64 fallback** — Anthropic's URL-mode image fetcher 400s on some CDNs (4zida resizer, kredium .webp). Download locally with httpx, base64-encode, send inline.
+- **System prompt cached** with `cache_control: ephemeral` for cross-call savings
+- **Concurrent up to 4 listings**, max 3 photos per listing
+- **Per-photo errors** caught — single bad URL doesn't poison the listing
+
+### 5.3 Combined verdict
+
+```
+text matched + any photo yes-direct → "text+photo" ⭐
+text matched only                    → "text-only"
+photo yes-direct only                → "photo-only"
+photo partial only                   → "partial"
+nothing                              → "none"
+```
+
+For strict `--view river` filter: only `text+photo`, `text-only`, `photo-only` pass.
+
+## 6. State + diffing
+
+- Per-location state file: `state/last_run_{location}.json`
+- Stores: `settings`, `listings[]` with `is_new` flag
+- On next run: compare by `(source, listing_id)` → flag new ones with 🆕
+
+### 6.1 Vision-cache invalidation
+
+Cached evidence is reused only when ALL true:
+- Same description text
+- Same photo URLs (order-insensitive)
+- No `verdict="error"` in prior photos
+- Prior evidence used the current `VISION_MODEL`
+
+If any of those changes, re-verify. Saves cost on stable listings.
+
+## 7. CLI
+
+```bash
+uv run --directory agent_tools/serbian_realestate python search.py \
+  --location beograd-na-vodi --min-m2 70 --max-price 1600 \
+  --view any \
+  --sites 4zida,nekretnine,kredium,halooglasi,cityexpert,indomio \
+  --verify-river --verify-max-photos 3 \
+  --output markdown
+```
+
+Flags:
+- `--location` — slug (e.g. `beograd-na-vodi`, `savski-venac`)
+- `--min-m2` — minimum floor area
+- `--max-price` — max monthly EUR
+- `--view {any|river}` — `river` filters strictly to verified river views
+- `--sites` — comma-separated portal list
+- `--verify-river` — turn on Sonnet vision verification (requires `ANTHROPIC_API_KEY`)
+- `--verify-max-photos N` — cap photos per listing (default 3)
+- `--output {markdown|json|csv}`
+- `--max-listings N` — cap per-site (default 30)
+
+### 7.1 Lenient filter
+
+Listings with missing m² OR price are **kept with a warning** (logged at WARNING) so the user can review manually. Only filter out when the value is present AND out of range.
+
+## 8. Cost / runtime
+
+- Cold run with vision: ~$0.40 for ~45 listings (~$0.009/listing)
+- Warm run (cache hits): ~$0
+- Daily expected: ~$0.05-0.10 (only new listings need vision)
+- Cold runtime: 5-8 minutes
+- Warm runtime: 1-2 minutes (data fetched fresh, vision cached)
+
+## 9. Daily scheduling (Linux systemd user timer)
+
+```
+~/.config/systemd/user/serbian-realestate.timer
+  [Timer]
+  OnCalendar=*-*-* 08:00
+  Persistent=true   # fire missed runs on next wake
+
+~/.config/systemd/user/serbian-realestate.service
+  [Service]
+  ExecStart=/path/to/uv run --directory /home/dory/ai_will_replace_you/agent_tools/serbian_realestate python search.py --verify-river
+  EnvironmentFile=/home/dory/ai_will_replace_you/agent_tools/webflow_api/.env
+```
+
+## 10. Build order if doing from scratch
+
+1. **Hour 1**: Listing dataclass + base Scraper + 4zida (plain HTTP — easiest, validates pipeline)
+2. **Hour 2**: nekretnine + kredium (more plain HTTP, exercises pagination + post-fetch URL filtering)
+3. **Hour 3**: cityexpert + indomio (Playwright; learn anti-bot basics — these are the easier CF/Distil targets)
+4. **Hour 4**: halooglasi via undetected-chromedriver (the hard one; expect 30-60 min on CF debugging)
+5. **Hour 5**: river-view text patterns + Sonnet vision verification + state diffing
+6. **Hour 6**: CLI polish + smoke tests + README
+
+Total: ~6 hours of focused engineering, or ~$30-60 of agent tokens with sde delegation.
+
+## 11. Project conventions enforced
+
+- All code in `agent_tools/serbian_realestate/`, no other folders touched
+- Use `uv` for everything — runnable as `uv run --directory ... python search.py`
+- Type hints, structured logging, pathlib for paths
+- Docstrings on public functions
+- No tests written by build agents (per project rules)
+- No hardcoded secrets — `ANTHROPIC_API_KEY` from env, fail clearly if missing for `--verify-river`
+- No `--api-key` CLI flags
+- No MCP/LLM calls outside `--verify-river` path
+- Rentals only — no sale listings (skip `item_category=Prodaja`)
+
+## 12. Future improvements (not done yet)
+
+- **Halo Oglasi photo extractor** — currently grabs Halo Oglasi mobile-app banner URLs as "photos." Filter out app-store / banner CDN paths.
+- **camoufox** as alternative for cityexpert/indomio if Distil/CF ever escalates
+- **Indomio English keywords** broadened in keyword set
+- **Sale listings option** behind a flag if useful later
+- **Notification layer** — email or Telegram when a new river-view listing appears
+- **Multi-location support** — run BW + Vracar + Dorcol in one invocation, output per-location reports
diff --git a/serbian_realestate/README.md b/serbian_realestate/README.md
new file mode 100644
index 0000000..0b2f152
--- /dev/null
+++ b/serbian_realestate/README.md
@@ -0,0 +1,96 @@
+# Serbian Real-Estate Scraper
+
+Daily-runnable monitor of Serbian rental classifieds (4zida, nekretnine.rs,
+kredium, cityexpert, indomio, halooglasi). Filters by location + min m² +
+max EUR/month and optionally verifies river-view claims with Sonnet vision.
+
+## Install
+
+```bash
+uv sync --directory serbian_realestate
+uv run --directory serbian_realestate playwright install chromium
+```
+
+For halooglasi.com you also need real Google Chrome installed (not just
+Chromium) — `undetected-chromedriver` drives it. The Cloudflare clearance
+profile lives at `state/browser/halooglasi_chrome_profile/` and persists
+between runs.
+
+## Run
+
+```bash
+uv run --directory serbian_realestate python search.py \
+  --location beograd-na-vodi --min-m2 70 --max-price 1600 \
+  --view river \
+  --sites 4zida,nekretnine,kredium,cityexpert,indomio,halooglasi \
+  --verify-river --verify-max-photos 3 \
+  --output markdown -v
+```
+
+Without `--verify-river` the run is fully offline-of-LLM and free.
+
+### Flags
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--location` | `beograd-na-vodi` | profile slug from `config.yaml` |
+| `--min-m2` | from config | minimum floor area |
+| `--max-price` | from config | max monthly EUR |
+| `--view` | `any` | `river` keeps only verified river views |
+| `--sites` | all 6 | comma-separated portal subset |
+| `--verify-river` | off | enable Sonnet vision verification |
+| `--verify-max-photos` | 3 | photos per listing for vision |
+| `--max-listings` | 30 | per-site cap |
+| `--output` | `markdown` | `markdown` / `json` / `csv` |
+| `--vision-model` | `claude-sonnet-4-6` | override the model id |
+
+## State
+
+- `state/last_run_{location}.json` — diff state + cached vision evidence.
+  New listings on the next run are flagged with 🆕.
+- `state/cache/` — HTML cache (TTL 6 h) keyed by URL hash.
+- `state/browser/halooglasi_chrome_profile/` — persistent Chrome profile
+  used by undetected-chromedriver for CF clearance.
+
+Vision cache invalidation: cached evidence is reused only when
+description text, photo URL set, and vision model all match the prior run.
+
+## Cost
+
+- Cold run with vision: ~$0.40 for ~45 listings (~$0.009 / listing).
+- Warm run (cache hits): ~$0.
+- Daily expected: ~$0.05–0.10 (only new listings hit the LLM).
+
+## River-view verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `text+photo` ⭐ | Description mentions a river view AND at least one photo confirms it. |
+| `text-only` | Description only — no confirming photo. |
+| `photo-only` | Photo shows a clear river — description silent. |
+| `partial` | Photo has a sliver of water; nothing else. Filtered out by `--view river`. |
+| `none` | No signals. |
+
+`--view river` keeps only the first three.
+
+## Daily systemd timer
+
+```ini
+# ~/.config/systemd/user/serbian-realestate.timer
+[Timer]
+OnCalendar=*-*-* 08:00
+Persistent=true
+
+# ~/.config/systemd/user/serbian-realestate.service
+[Service]
+ExecStart=/usr/bin/uv run --directory %h/path/to/serbian_realestate python search.py --verify-river
+EnvironmentFile=%h/path/to/.env
+```
+
+## Conventions
+
+- All code in `serbian_realestate/`; no other folders touched.
+- `uv` for everything — runnable as `uv run --directory ... python search.py`.
+- No tests written by build agents (project rule).
+- `ANTHROPIC_API_KEY` from env; no `--api-key` CLI flag.
+- Rentals only — sale listings (`item_category=Prodaja`) are skipped.
diff --git a/serbian_realestate/config.yaml b/serbian_realestate/config.yaml
new file mode 100644
index 0000000..bcecca2
--- /dev/null
+++ b/serbian_realestate/config.yaml
@@ -0,0 +1,56 @@
+# Filter profiles for Serbian rental classifieds.
+# Each profile maps a --location slug to keyword/URL hints used by scrapers.
+# location_keywords are case-insensitive substrings tested against URL paths
+# and (where applicable) card text — used to post-filter loose searches.
+
+profiles:
+  beograd-na-vodi:
+    label: "Belgrade Waterfront (Beograd na Vodi)"
+    location_keywords:
+      - "beograd-na-vodi"
+      - "belgrade-waterfront"
+      - "bw-residences"
+      - "bw residences"
+      - "savski-venac"
+      - "savski venac"
+    municipality_slug: "savski-venac"
+    indomio_slug: "belgrade-savski-venac"
+    cityexpert_district: "belgrade-waterfront"
+
+  savski-venac:
+    label: "Savski Venac"
+    location_keywords:
+      - "savski-venac"
+      - "savski venac"
+      - "senjak"
+      - "dedinje"
+    municipality_slug: "savski-venac"
+    indomio_slug: "belgrade-savski-venac"
+
+  vracar:
+    label: "Vračar"
+    location_keywords:
+      - "vracar"
+      - "vračar"
+      - "neimar"
+      - "crveni-krst"
+    municipality_slug: "vracar"
+    indomio_slug: "belgrade-vracar"
+
+  dorcol:
+    label: "Dorćol (Stari Grad)"
+    location_keywords:
+      - "dorcol"
+      - "dorćol"
+      - "stari-grad"
+      - "stari grad"
+    municipality_slug: "stari-grad"
+    indomio_slug: "belgrade-stari-grad"
+
+# Default search settings — overridable via CLI flags.
+defaults:
+  min_m2: 70
+  max_price: 1600
+  max_listings_per_site: 30
+  verify_max_photos: 3
+  vision_model: "claude-sonnet-4-6"
diff --git a/serbian_realestate/filters.py b/serbian_realestate/filters.py
new file mode 100644
index 0000000..0f44980
--- /dev/null
+++ b/serbian_realestate/filters.py
@@ -0,0 +1,138 @@
+"""Match criteria + Serbian river-view text patterns.
+
+The patterns are deliberately strict — bare 'reka' or 'Sava' is too generic
+(Savska is a street name in every BW address). We only fire when the text
+has a directional cue (pogled na, prvi red, uz/pored, panoramski pogled).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+# Required Serbian phrasings (case-insensitive). Each pattern is paired with
+# a short label used in evidence dumps to make the diff readable.
+_RIVER_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    (
+        "pogled-na-reku",
+        re.compile(
+            r"pogled\s+na\s+(?:reku|reci|reke|savu|savi|save|adu|ada\s+ciganlij\w*|dunav\w*)",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "prvi-red-do-reke",
+        re.compile(
+            r"prvi\s+red\s+(?:do|uz|na)\s+(?:reku|reci|reke|savu|save|savi|dunavu)",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "uz-obali-reke",
+        re.compile(
+            r"(?:uz|pored|na\s+obali)\s+(?:reku|reci|reke|savu|savi|save|dunav\w*)",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "okrenut-reci",
+        re.compile(
+            r"okrenut\w*\s+.{0,30}?(?:reci|reke|savu|savi|save|dunav\w*)",
+            re.IGNORECASE | re.DOTALL,
+        ),
+    ),
+    (
+        "panoramski-pogled",
+        re.compile(
+            r"panoramski\s+pogled\s+.{0,60}?(?:reku|savu|river|sava|dunav)",
+            re.IGNORECASE | re.DOTALL,
+        ),
+    ),
+    (
+        "river-view-en",
+        re.compile(
+            r"river\s+view|view\s+of\s+the\s+(?:sava|river|danube)",
+            re.IGNORECASE,
+        ),
+    ),
+]
+
+
+@dataclass
+class TextRiverResult:
+    """Outcome of running text-pattern detection on a description."""
+
+    matched: bool
+    evidence: list[str]
+
+
+def detect_river_in_text(text: str) -> TextRiverResult:
+    """Return TextRiverResult for `text`. Evidence is the matched substrings."""
+    if not text:
+        return TextRiverResult(matched=False, evidence=[])
+    evidence: list[str] = []
+    for label, pat in _RIVER_PATTERNS:
+        m = pat.search(text)
+        if m:
+            snippet = text[max(0, m.start() - 30) : min(len(text), m.end() + 30)]
+            evidence.append(f"{label}: …{snippet.strip()}…")
+    return TextRiverResult(matched=bool(evidence), evidence=evidence)
+
+
+@dataclass
+class CriteriaFilter:
+    """Lenient match — listings missing m² OR price are kept with a warning.
+
+    Only filter out when the value is present AND out of range. The user
+    reviews kept-but-incomplete listings manually.
+    """
+
+    min_m2: float | None = None
+    max_price: float | None = None
+
+    def evaluate(self, *, area_m2: float | None, price_eur: float | None) -> tuple[bool, list[str]]:
+        warnings: list[str] = []
+        if self.min_m2 is not None:
+            if area_m2 is None:
+                warnings.append("missing area_m2")
+            elif area_m2 < self.min_m2:
+                return False, warnings
+        if self.max_price is not None:
+            if price_eur is None:
+                warnings.append("missing price_eur")
+            elif price_eur > self.max_price:
+                return False, warnings
+        return True, warnings
+
+
+def combine_river_verdict(*, text_match: bool, photo_evidence: list[dict]) -> str:
+    """Combine text + photo signals into the final tag.
+
+    `text+photo` requires both signals; `photo-only` requires at least one
+    `yes-direct` photo. `partial` only fires when *no* yes-direct exists but
+    at least one `partial`. Anything else collapses to `none`.
+    """
+    has_yes_direct = any(p.get("verdict") == "yes-direct" for p in photo_evidence)
+    has_partial = any(p.get("verdict") == "partial" for p in photo_evidence)
+    if text_match and has_yes_direct:
+        return "text+photo"
+    if text_match:
+        return "text-only"
+    if has_yes_direct:
+        return "photo-only"
+    if has_partial:
+        return "partial"
+    return "none"
+
+
+def passes_river_filter(verdict: str, mode: str) -> bool:
+    """`mode='any'` accepts everything; `mode='river'` accepts only verified views."""
+    if mode == "any":
+        return True
+    if mode == "river":
+        return verdict in {"text+photo", "text-only", "photo-only"}
+    raise ValueError(f"unknown view mode: {mode}")
diff --git a/serbian_realestate/pyproject.toml b/serbian_realestate/pyproject.toml
new file mode 100644
index 0000000..33f74dc
--- /dev/null
+++ b/serbian_realestate/pyproject.toml
@@ -0,0 +1,25 @@
+[project]
+name = "serbian-realestate"
+version = "0.1.0"
+description = "Daily-runnable monitor of Serbian rental classifieds with vision-verified river-view detection."
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.0",
+    "undetected-chromedriver>=3.5",
+    "playwright>=1.45",
+    "playwright-stealth>=1.0.6",
+    "anthropic>=0.40",
+    "pyyaml>=6.0",
+    "rich>=13.7",
+    "selenium>=4.20",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+include = ["*.py", "scrapers/*.py", "config.yaml"]
diff --git a/serbian_realestate/scrapers/__init__.py b/serbian_realestate/scrapers/__init__.py
new file mode 100644
index 0000000..bd63d12
--- /dev/null
+++ b/serbian_realestate/scrapers/__init__.py
@@ -0,0 +1 @@
+"""Scraper implementations for Serbian rental portals."""
diff --git a/serbian_realestate/scrapers/base.py b/serbian_realestate/scrapers/base.py
new file mode 100644
index 0000000..f8cd8b9
--- /dev/null
+++ b/serbian_realestate/scrapers/base.py
@@ -0,0 +1,265 @@
+"""Shared primitives for all portal scrapers.
+
+Defines the canonical Listing dataclass, an httpx-backed HttpClient with
+sane retry/timeout defaults, and an abstract Scraper base class. Per-portal
+quirks live in their own modules; everything common lives here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import random
+import re
+import time
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Browser-realistic UA pool. Rotated per request to reduce trivial fingerprinting.
+USER_AGENTS = [
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+]
+
+
+@dataclass
+class Listing:
+    """Canonical record returned by every scraper.
+
+    `listing_id` is portal-specific but stable for diffing; we hash the URL
+    when the portal doesn't expose an obvious ID.
+    """
+
+    source: str
+    listing_id: str
+    url: str
+    title: str
+    price_eur: float | None
+    area_m2: float | None
+    rooms: str | None = None
+    floor: str | None = None
+    location: str | None = None
+    description: str = ""
+    photos: list[str] = field(default_factory=list)
+    raw: dict = field(default_factory=dict)
+
+    # Populated by river_check.verify_listings() and the diff layer.
+    river_text_match: bool = False
+    river_text_evidence: list[str] = field(default_factory=list)
+    river_photo_evidence: list[dict] = field(default_factory=list)
+    river_verdict: str = "none"  # text+photo, text-only, photo-only, partial, none
+    is_new: bool = False
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @staticmethod
+    def hash_id(url: str) -> str:
+        return hashlib.sha1(url.encode("utf-8")).hexdigest()[:16]
+
+
+class HttpClient:
+    """Thin wrapper around httpx.Client with retries, jitter, and UA rotation.
+
+    Cache-on-disk is opt-in via `cache_dir` — we key by URL hash. Cache files
+    are .html only; scrapers parse fresh each call but skip the network when
+    the cache file is fresh enough (default 6 h).
+    """
+
+    def __init__(
+        self,
+        cache_dir: Path | None = None,
+        cache_ttl_seconds: int = 6 * 3600,
+        timeout_seconds: float = 30.0,
+    ) -> None:
+        self.cache_dir = cache_dir
+        self.cache_ttl_seconds = cache_ttl_seconds
+        if cache_dir is not None:
+            cache_dir.mkdir(parents=True, exist_ok=True)
+        self._client = httpx.Client(
+            timeout=httpx.Timeout(timeout_seconds),
+            follow_redirects=True,
+            http2=True,
+            headers={
+                "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                "Accept-Language": "en-US,en;q=0.9,sr;q=0.7",
+            },
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def _cache_path(self, url: str) -> Path | None:
+        if self.cache_dir is None:
+            return None
+        h = hashlib.sha1(url.encode("utf-8")).hexdigest()
+        return self.cache_dir / f"{h}.html"
+
+    def _read_cache(self, url: str) -> str | None:
+        path = self._cache_path(url)
+        if path is None or not path.exists():
+            return None
+        age = time.time() - path.stat().st_mtime
+        if age > self.cache_ttl_seconds:
+            return None
+        try:
+            return path.read_text(encoding="utf-8")
+        except OSError:
+            return None
+
+    def _write_cache(self, url: str, body: str) -> None:
+        path = self._cache_path(url)
+        if path is None:
+            return
+        try:
+            path.write_text(body, encoding="utf-8")
+        except OSError as exc:
+            logger.debug("cache write failed for %s: %s", url, exc)
+
+    def get(
+        self,
+        url: str,
+        *,
+        retries: int = 3,
+        use_cache: bool = True,
+        extra_headers: dict | None = None,
+    ) -> str | None:
+        """Fetch URL with retries; return body text or None on persistent failure."""
+        if use_cache:
+            cached = self._read_cache(url)
+            if cached is not None:
+                return cached
+
+        last_err: Exception | None = None
+        for attempt in range(retries):
+            headers = {"User-Agent": random.choice(USER_AGENTS)}
+            if extra_headers:
+                headers.update(extra_headers)
+            try:
+                resp = self._client.get(url, headers=headers)
+                if resp.status_code == 200:
+                    body = resp.text
+                    self._write_cache(url, body)
+                    return body
+                if resp.status_code in (403, 429, 503):
+                    logger.debug("blocked %s (HTTP %d), backoff", url, resp.status_code)
+                    time.sleep(2 ** attempt + random.random())
+                    continue
+                logger.debug("non-200 %s: HTTP %d", url, resp.status_code)
+                return None
+            except (httpx.HTTPError, httpx.TransportError) as exc:
+                last_err = exc
+                time.sleep(1 + random.random())
+        if last_err is not None:
+            logger.debug("giving up on %s: %s", url, last_err)
+        return None
+
+
+class Scraper(ABC):
+    """Base class — subclasses implement search() returning concrete Listings."""
+
+    name: str = "base"
+
+    def __init__(self, http: HttpClient | None = None) -> None:
+        self.http = http or HttpClient()
+
+    @abstractmethod
+    def search(
+        self,
+        *,
+        location_slug: str,
+        location_keywords: Iterable[str],
+        max_listings: int = 30,
+    ) -> list[Listing]:
+        ...
+
+
+# Shared text utilities --------------------------------------------------------
+
+
+_PRICE_RE = re.compile(
+    r"(?P<num>[\d][\d\.\s,]{0,9}\d|\d{2,7})\s*(?:€|eur|EUR|евро)",
+    re.IGNORECASE,
+)
+_AREA_RE = re.compile(
+    r"(?P<num>\d{2,4}(?:[\.,]\d{1,2})?)\s*(?:m²|m2|m\s*²|кв\.?м|sqm)",
+    re.IGNORECASE,
+)
+
+
+def _to_float(raw: str) -> float | None:
+    """Parse a Serbian/European price string into float — handles 1.500,00 / 1,500.00 / 1 500."""
+    raw = raw.strip().replace(" ", "")
+    if not raw:
+        return None
+    if "," in raw and "." in raw:
+        if raw.rfind(",") > raw.rfind("."):
+            raw = raw.replace(".", "").replace(",", ".")
+        else:
+            raw = raw.replace(",", "")
+    elif "," in raw:
+        if len(raw.split(",")[-1]) == 3:
+            raw = raw.replace(",", "")
+        else:
+            raw = raw.replace(",", ".")
+    elif "." in raw:
+        if len(raw.split(".")[-1]) == 3:
+            raw = raw.replace(".", "")
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def parse_price_eur(text: str) -> float | None:
+    """Find first plausible EUR price in `text`."""
+    if not text:
+        return None
+    m = _PRICE_RE.search(text)
+    if not m:
+        return None
+    return _to_float(m.group("num"))
+
+
+def parse_area_m2(text: str) -> float | None:
+    """Find first plausible square-meter area in `text`."""
+    if not text:
+        return None
+    m = _AREA_RE.search(text)
+    if not m:
+        return None
+    return _to_float(m.group("num"))
+
+
+def matches_location(text: str, keywords: Iterable[str]) -> bool:
+    """True if `text` contains any keyword (case-insensitive)."""
+    if not text:
+        return False
+    lo = text.lower()
+    return any(k.lower() in lo for k in keywords)
+
+
+def normalise_url(base: str, href: str) -> str:
+    """Resolve relative URLs to absolute, strip trailing slashes consistently."""
+    if not href:
+        return ""
+    if href.startswith("//"):
+        return "https:" + href
+    if href.startswith("http"):
+        return href
+    if href.startswith("/"):
+        return base.rstrip("/") + href
+    return base.rstrip("/") + "/" + href
diff --git a/serbian_realestate/scrapers/cityexpert.py b/serbian_realestate/scrapers/cityexpert.py
new file mode 100644
index 0000000..0304c9f
--- /dev/null
+++ b/serbian_realestate/scrapers/cityexpert.py
@@ -0,0 +1,140 @@
+"""cityexpert.rs — Cloudflare-protected, needs Playwright.
+
+URL pattern that actually works: /en/properties-for-rent/belgrade?ptId=1
+(NOT /en/r/belgrade/<district>, which 404s). Pagination uses
+`currentPage`, not `page`. BW listings are sparse so we walk up to 10 pages.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    HttpClient,
+    Listing,
+    Scraper,
+    matches_location,
+    parse_area_m2,
+    parse_price_eur,
+)
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+
+BASE = "https://cityexpert.rs"
+SEARCH_TEMPLATE = (
+    "https://cityexpert.rs/en/properties-for-rent/belgrade?ptId=1&currentPage={page}"
+)
+DETAIL_RE = re.compile(r'href="(/en/property/[^"\s]+?)"', re.IGNORECASE)
+MAX_PAGES = 10
+
+
+class CityExpertScraper(Scraper):
+    name = "cityexpert"
+
+    def __init__(self, http: HttpClient | None = None) -> None:
+        super().__init__(http=http)
+
+    def search(
+        self,
+        *,
+        location_slug: str,
+        location_keywords: Iterable[str],
+        max_listings: int = 30,
+    ) -> list[Listing]:
+        keywords = list(location_keywords)
+        seen: set[str] = set()
+        candidates: list[str] = []
+
+        try:
+            from playwright.sync_api import sync_playwright
+        except ImportError as exc:
+            logger.warning("cityexpert: playwright not installed (%s)", exc)
+            return []
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                user_agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+                "(KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+                locale="en-US",
+            )
+            page = context.new_page()
+            try:
+                for page_num in range(1, MAX_PAGES + 1):
+                    list_url = SEARCH_TEMPLATE.format(page=page_num)
+                    try:
+                        page.goto(list_url, wait_until="networkidle", timeout=45_000)
+                    except Exception as exc:
+                        logger.debug("cityexpert page %d nav: %s", page_num, exc)
+                        continue
+                    html = page.content()
+                    found_any = False
+                    for m in DETAIL_RE.finditer(html):
+                        href = m.group(1)
+                        full = urljoin(BASE, href)
+                        if full in seen:
+                            continue
+                        seen.add(full)
+                        # On listing-card text we can already filter loosely;
+                        # final check happens after we fetch the detail.
+                        found_any = True
+                        candidates.append(full)
+                        if len(candidates) >= max_listings:
+                            break
+                    if len(candidates) >= max_listings or not found_any:
+                        break
+
+                listings: list[Listing] = []
+                for url in candidates:
+                    listing = self._scrape_detail(page, url, keywords)
+                    if listing:
+                        listings.append(listing)
+            finally:
+                context.close()
+                browser.close()
+
+        logger.info("cityexpert: %d listings", len(listings))
+        return listings
+
+    def _scrape_detail(self, page, url: str, keywords: list[str]) -> Listing | None:
+        try:
+            page.goto(url, wait_until="networkidle", timeout=45_000)
+        except Exception as exc:
+            logger.debug("cityexpert detail nav %s: %s", url, exc)
+            return None
+        html = page.content()
+        soup = BeautifulSoup(html, "lxml")
+        title_node = soup.find("h1")
+        title_text = title_node.get_text(strip=True) if title_node else ""
+
+        body_text = soup.get_text(" ", strip=True)
+        if not matches_location(body_text, keywords):
+            return None
+
+        price = parse_price_eur(body_text)
+        area = parse_area_m2(body_text)
+        photos = extract_photo_urls(soup, base_url=BASE, limit=8)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1] or Listing.hash_id(url)
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title_text or url,
+            price_eur=price,
+            area_m2=area,
+            description=body_text[:4000],
+            photos=photos,
+            raw={"detail_url": url},
+        )
+
+
+def build(http: HttpClient | None = None) -> CityExpertScraper:
+    return CityExpertScraper(http=http)
diff --git a/serbian_realestate/scrapers/fzida.py b/serbian_realestate/scrapers/fzida.py
new file mode 100644
index 0000000..f325687
--- /dev/null
+++ b/serbian_realestate/scrapers/fzida.py
@@ -0,0 +1,111 @@
+"""4zida.rs scraper — plain HTTP.
+
+The list page is JS-rendered but detail URLs are present as `href` attributes
+in the initial HTML, so we regex them out and then parse each (server-rendered)
+detail page directly. No browser needed.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    HttpClient,
+    Listing,
+    Scraper,
+    matches_location,
+    parse_area_m2,
+    parse_price_eur,
+)
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+
+BASE = "https://www.4zida.rs"
+SEARCH_TEMPLATE = (
+    "https://www.4zida.rs/izdavanje-stanova/{slug}"
+)
+DETAIL_RE = re.compile(r'href="(/izdavanje-stanova/[a-z0-9\-/]+/[a-z0-9\-/]+)"', re.IGNORECASE)
+
+
+class FzidaScraper(Scraper):
+    name = "4zida"
+
+    def search(
+        self,
+        *,
+        location_slug: str,
+        location_keywords: Iterable[str],
+        max_listings: int = 30,
+    ) -> list[Listing]:
+        list_url = SEARCH_TEMPLATE.format(slug=location_slug)
+        body = self.http.get(list_url, use_cache=False)
+        if not body:
+            logger.warning("4zida: list page fetch failed (%s)", list_url)
+            return []
+
+        urls: list[str] = []
+        seen: set[str] = set()
+        keywords = list(location_keywords)
+        for m in DETAIL_RE.finditer(body):
+            path = m.group(1)
+            full = urljoin(BASE, path)
+            if full in seen:
+                continue
+            seen.add(full)
+            # 4zida URL slugs include neighbourhood — keyword-filter to
+            # stay on-target even when the search slug bleeds.
+            if not matches_location(path, keywords):
+                continue
+            urls.append(full)
+            if len(urls) >= max_listings:
+                break
+
+        listings: list[Listing] = []
+        for url in urls:
+            listing = self._scrape_detail(url)
+            if listing:
+                listings.append(listing)
+        logger.info("4zida: %d listings", len(listings))
+        return listings
+
+    def _scrape_detail(self, url: str) -> Listing | None:
+        body = self.http.get(url)
+        if not body:
+            return None
+        soup = BeautifulSoup(body, "lxml")
+        title = soup.find("h1")
+        title_text = title.get_text(strip=True) if title else ""
+
+        # Description: 4zida puts it in <div class="description"> or
+        # nested <p> under main content; fall back to all paragraph text.
+        desc_node = soup.select_one(".description, [class*='description'], main")
+        description = desc_node.get_text(" ", strip=True) if desc_node else soup.get_text(" ", strip=True)
+
+        price = parse_price_eur(body)
+        area = parse_area_m2(body)
+
+        photos = extract_photo_urls(soup, base_url=BASE, limit=8)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1] or Listing.hash_id(url)
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title_text or url,
+            price_eur=price,
+            area_m2=area,
+            description=description[:4000],
+            photos=photos,
+            raw={"detail_url": url},
+        )
+
+
+def build(http: HttpClient | None = None) -> FzidaScraper:
+    return FzidaScraper(http=http)
diff --git a/serbian_realestate/scrapers/halooglasi.py b/serbian_realestate/scrapers/halooglasi.py
new file mode 100644
index 0000000..5e63c14
--- /dev/null
+++ b/serbian_realestate/scrapers/halooglasi.py
@@ -0,0 +1,220 @@
+"""halooglasi.com — Cloudflare-aggressive, needs undetected-chromedriver.
+
+This is the hardest portal. Lessons baked in:
+- Real Google Chrome (not Chromium); pass version_main explicitly so the
+  bundled chromedriver matches the installed Chrome major version.
+- page_load_strategy='eager' or driver.get() hangs on CF challenge pages.
+- Persistent profile dir keeps CF clearance cookies across runs.
+- Hard sleep(8s) after navigation: CF JS blocks the main thread, so
+  wait_for_function-style polling can't run during it.
+- Read window.QuidditaEnvironment.CurrentClassified.OtherFields rather
+  than regexing body text — structured fields are stable.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import HttpClient, Listing, Scraper, matches_location
+from .photos import extract_photo_urls, extract_photos_from_json_strings
+
+logger = logging.getLogger(__name__)
+
+
+BASE = "https://www.halooglasi.com"
+SEARCH_URL = (
+    "https://www.halooglasi.com/nekretnine/izdavanje-stanova/beograd?"
+    "cena_d_unit_s=eur&kvadratura_d_from=70"
+)
+DETAIL_RE = re.compile(r'href="(/nekretnine/izdavanje-stanova/[^"\s]+?/\d+)"', re.IGNORECASE)
+PROFILE_SUBPATH = Path("browser/halooglasi_chrome_profile")
+
+
+def _detect_chrome_major_version() -> int | None:
+    """Run `google-chrome --version` to extract major version (e.g. 147)."""
+    for cmd in ("google-chrome", "google-chrome-stable", "chromium-browser"):
+        if not shutil.which(cmd):
+            continue
+        try:
+            out = subprocess.check_output([cmd, "--version"], text=True, timeout=5)
+        except (subprocess.SubprocessError, OSError):
+            continue
+        m = re.search(r"(\d+)\.\d+\.\d+\.\d+", out)
+        if m:
+            return int(m.group(1))
+    return None
+
+
+class HaloOglasiScraper(Scraper):
+    name = "halooglasi"
+
+    def __init__(self, http: HttpClient | None = None, state_dir: Path | None = None) -> None:
+        super().__init__(http=http)
+        self.state_dir = state_dir or Path(__file__).resolve().parent.parent / "state"
+
+    def search(
+        self,
+        *,
+        location_slug: str,
+        location_keywords: Iterable[str],
+        max_listings: int = 30,
+    ) -> list[Listing]:
+        try:
+            import undetected_chromedriver as uc  # noqa: F401
+        except ImportError as exc:
+            logger.warning("halooglasi: undetected-chromedriver missing (%s)", exc)
+            return []
+        return self._run(location_slug=location_slug, keywords=list(location_keywords), max_listings=max_listings)
+
+    def _run(self, *, location_slug: str, keywords: list[str], max_listings: int) -> list[Listing]:
+        import undetected_chromedriver as uc
+
+        profile_dir = self.state_dir / PROFILE_SUBPATH
+        profile_dir.mkdir(parents=True, exist_ok=True)
+
+        opts = uc.ChromeOptions()
+        opts.add_argument("--headless=new")
+        opts.add_argument("--no-sandbox")
+        opts.add_argument("--disable-blink-features=AutomationControlled")
+        opts.add_argument("--window-size=1280,1800")
+        opts.add_argument(f"--user-data-dir={profile_dir}")
+        opts.page_load_strategy = "eager"
+
+        chrome_major = _detect_chrome_major_version()
+        driver_kwargs: dict = {"options": opts, "headless": True}
+        if chrome_major is not None:
+            driver_kwargs["version_main"] = chrome_major
+
+        try:
+            driver = uc.Chrome(**driver_kwargs)
+        except Exception as exc:
+            logger.warning("halooglasi: chrome launch failed (%s)", exc)
+            return []
+
+        listings: list[Listing] = []
+        try:
+            driver.set_page_load_timeout(45)
+            try:
+                driver.get(SEARCH_URL)
+            except Exception as exc:
+                logger.debug("halooglasi: list nav: %s", exc)
+            time.sleep(8)  # CF challenge JS — hard sleep is the only thing that works
+
+            html = driver.page_source
+            seen: set[str] = set()
+            urls: list[str] = []
+            for m in DETAIL_RE.finditer(html):
+                href = m.group(1)
+                full = urljoin(BASE, href)
+                if full in seen:
+                    continue
+                seen.add(full)
+                if not matches_location(href, keywords):
+                    continue
+                urls.append(full)
+                if len(urls) >= max_listings:
+                    break
+
+            for url in urls:
+                listing = self._scrape_detail(driver, url, keywords)
+                if listing:
+                    listings.append(listing)
+        finally:
+            try:
+                driver.quit()
+            except Exception:
+                pass
+
+        logger.info("halooglasi: %d listings", len(listings))
+        return listings
+
+    def _scrape_detail(self, driver, url: str, keywords: list[str]) -> Listing | None:
+        try:
+            driver.get(url)
+        except Exception as exc:
+            logger.debug("halooglasi detail nav %s: %s", url, exc)
+            return None
+        time.sleep(8)
+        html = driver.page_source
+
+        # Pull the structured classified blob via JS evaluation so we don't
+        # have to parse the entire SPA bootstrap script.
+        other_fields: dict = {}
+        title_text = ""
+        description = ""
+        try:
+            other_fields = driver.execute_script(
+                "return (window.QuidditaEnvironment && "
+                "window.QuidditaEnvironment.CurrentClassified) ? "
+                "window.QuidditaEnvironment.CurrentClassified.OtherFields : {};"
+            ) or {}
+            title_text = driver.execute_script(
+                "return (window.QuidditaEnvironment && "
+                "window.QuidditaEnvironment.CurrentClassified) ? "
+                "(window.QuidditaEnvironment.CurrentClassified.Title || '') : '';"
+            ) or ""
+            description = driver.execute_script(
+                "return (window.QuidditaEnvironment && "
+                "window.QuidditaEnvironment.CurrentClassified) ? "
+                "(window.QuidditaEnvironment.CurrentClassified.TextHtml || "
+                "window.QuidditaEnvironment.CurrentClassified.Description || '') : '';"
+            ) or ""
+        except Exception as exc:
+            logger.debug("halooglasi: JS read failed for %s: %s", url, exc)
+
+        # Reject sale listings and non-residential.
+        if other_fields.get("tip_nekretnine_s") and other_fields["tip_nekretnine_s"] != "Stan":
+            return None
+        unit = other_fields.get("cena_d_unit_s") or ""
+        price_eur = None
+        if unit.upper() == "EUR":
+            try:
+                price_eur = float(other_fields.get("cena_d") or 0) or None
+            except (TypeError, ValueError):
+                price_eur = None
+
+        area_m2 = None
+        try:
+            area_m2 = float(other_fields.get("kvadratura_d") or 0) or None
+        except (TypeError, ValueError):
+            area_m2 = None
+
+        if not matches_location(html.lower(), keywords):
+            return None
+
+        soup = BeautifulSoup(html, "lxml")
+        photos = extract_photo_urls(soup, base_url=BASE, limit=8)
+        if not photos:
+            photos = extract_photos_from_json_strings(html, limit=8)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1] or Listing.hash_id(url)
+        # Strip HTML tags from description if it came back as HTML.
+        if "<" in description:
+            description = BeautifulSoup(description, "lxml").get_text(" ", strip=True)
+
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title_text or url,
+            price_eur=price_eur,
+            area_m2=area_m2,
+            rooms=str(other_fields.get("broj_soba_s") or "") or None,
+            floor=str(other_fields.get("sprat_s") or "") or None,
+            description=description[:4000],
+            photos=photos,
+            raw={"other_fields": other_fields, "detail_url": url},
+        )
+
+
+def build(http: HttpClient | None = None, state_dir: Path | None = None) -> HaloOglasiScraper:
+    return HaloOglasiScraper(http=http, state_dir=state_dir)
diff --git a/serbian_realestate/scrapers/indomio.py b/serbian_realestate/scrapers/indomio.py
new file mode 100644
index 0000000..f44a139
--- /dev/null
+++ b/serbian_realestate/scrapers/indomio.py
@@ -0,0 +1,147 @@
+"""indomio.rs — Distil-protected SPA via Playwright.
+
+Detail URLs are bare numeric IDs (`/en/{id}`) with no slug to keyword-match,
+so we filter on card text instead — every card surfaces neighbourhood text
+like "Belgrade, Savski Venac: Dedinje". Server-side filter params don't
+work, only the per-municipality URL slug.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    HttpClient,
+    Listing,
+    Scraper,
+    matches_location,
+    parse_area_m2,
+    parse_price_eur,
+)
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+
+BASE = "https://www.indomio.rs"
+SEARCH_TEMPLATE = "https://www.indomio.rs/en/to-rent/flats/{slug}"
+DETAIL_RE = re.compile(r'href="(/en/\d+/?)"', re.IGNORECASE)
+
+
+class IndomioScraper(Scraper):
+    name = "indomio"
+
+    def search(
+        self,
+        *,
+        location_slug: str,
+        location_keywords: Iterable[str],
+        max_listings: int = 30,
+    ) -> list[Listing]:
+        # Caller passes the indomio slug via location_slug — we treat it
+        # as the literal URL fragment.
+        if not location_slug:
+            return []
+
+        try:
+            from playwright.sync_api import sync_playwright
+        except ImportError as exc:
+            logger.warning("indomio: playwright not installed (%s)", exc)
+            return []
+
+        keywords = list(location_keywords)
+        url = SEARCH_TEMPLATE.format(slug=location_slug)
+        candidates: list[tuple[str, str]] = []  # (url, card_text)
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                user_agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+                "(KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
+                locale="en-US",
+            )
+            page = context.new_page()
+            try:
+                page.goto(url, wait_until="domcontentloaded", timeout=45_000)
+                # SPA hydration — without an 8s wait we race the Distil challenge.
+                time.sleep(8)
+                try:
+                    page.wait_for_selector("a[href^='/en/']", timeout=15_000)
+                except Exception:
+                    pass
+                html = page.content()
+                soup = BeautifulSoup(html, "lxml")
+
+                # Pair each card with its surrounding text to keyword-filter.
+                for a in soup.find_all("a", href=DETAIL_RE):
+                    href = a.get("href")
+                    if not href:
+                        continue
+                    full = urljoin(BASE, href)
+                    card = a.find_parent(["article", "li", "div"]) or a
+                    card_text = card.get_text(" ", strip=True)
+                    if not matches_location(card_text, keywords):
+                        continue
+                    candidates.append((full, card_text))
+
+                seen: set[str] = set()
+                deduped: list[tuple[str, str]] = []
+                for u, t in candidates:
+                    if u in seen:
+                        continue
+                    seen.add(u)
+                    deduped.append((u, t))
+                    if len(deduped) >= max_listings:
+                        break
+
+                listings: list[Listing] = []
+                for u, _ in deduped:
+                    listing = self._scrape_detail(page, u)
+                    if listing:
+                        listings.append(listing)
+            finally:
+                context.close()
+                browser.close()
+
+        logger.info("indomio: %d listings", len(listings))
+        return listings
+
+    def _scrape_detail(self, page, url: str) -> Listing | None:
+        try:
+            page.goto(url, wait_until="domcontentloaded", timeout=45_000)
+            time.sleep(4)
+        except Exception as exc:
+            logger.debug("indomio detail %s: %s", url, exc)
+            return None
+        html = page.content()
+        soup = BeautifulSoup(html, "lxml")
+        title_node = soup.find("h1")
+        title_text = title_node.get_text(strip=True) if title_node else ""
+
+        body_text = soup.get_text(" ", strip=True)
+        price = parse_price_eur(body_text)
+        area = parse_area_m2(body_text)
+        photos = extract_photo_urls(soup, base_url=BASE, limit=8)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1] or Listing.hash_id(url)
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title_text or url,
+            price_eur=price,
+            area_m2=area,
+            description=body_text[:4000],
+            photos=photos,
+            raw={"detail_url": url},
+        )
+
+
+def build(http: HttpClient | None = None) -> IndomioScraper:
+    return IndomioScraper(http=http)
diff --git a/serbian_realestate/scrapers/kredium.py b/serbian_realestate/scrapers/kredium.py
new file mode 100644
index 0000000..cab0a13
--- /dev/null
+++ b/serbian_realestate/scrapers/kredium.py
@@ -0,0 +1,116 @@
+"""kredium.rs — plain HTTP with section-scoped parsing.
+
+The detail pages embed a related-listings carousel below the fold; if we
+parse the whole body, every listing tags as the wrong building. So we
+narrow to the <section> containing the 'Informacije' / 'Opis' headings.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    HttpClient,
+    Listing,
+    Scraper,
+    matches_location,
+    parse_area_m2,
+    parse_price_eur,
+)
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+
+BASE = "https://kredium.rs"
+SEARCH_TEMPLATE = "https://kredium.rs/izdavanje/{slug}"
+DETAIL_RE = re.compile(r'href="(/oglas/[^"\s]+?)"', re.IGNORECASE)
+
+
+class KrediumScraper(Scraper):
+    name = "kredium"
+
+    def search(
+        self,
+        *,
+        location_slug: str,
+        location_keywords: Iterable[str],
+        max_listings: int = 30,
+    ) -> list[Listing]:
+        url = SEARCH_TEMPLATE.format(slug=location_slug)
+        body = self.http.get(url, use_cache=False)
+        if not body:
+            logger.warning("kredium: list page failed (%s)", url)
+            return []
+        keywords = list(location_keywords)
+        seen: set[str] = set()
+        candidates: list[str] = []
+        for m in DETAIL_RE.finditer(body):
+            href = m.group(1)
+            full = urljoin(BASE, href)
+            if full in seen:
+                continue
+            seen.add(full)
+            candidates.append(full)
+            if len(candidates) >= max_listings:
+                break
+
+        listings: list[Listing] = []
+        for u in candidates:
+            listing = self._scrape_detail(u, keywords)
+            if listing:
+                listings.append(listing)
+        logger.info("kredium: %d listings", len(listings))
+        return listings
+
+    def _scrape_detail(self, url: str, keywords: list[str]) -> Listing | None:
+        body = self.http.get(url)
+        if not body:
+            return None
+        soup = BeautifulSoup(body, "lxml")
+        title_node = soup.find("h1")
+        title_text = title_node.get_text(strip=True) if title_node else ""
+
+        # Scope to the main content section to avoid carousel pollution.
+        # Heuristic: pick the <section> that contains an h2/h3 with
+        # "Informacije" or "Opis"; fall back to <article> or <main>.
+        scoped = self._scope_main_section(soup)
+        scoped_text = scoped.get_text(" ", strip=True) if scoped else ""
+
+        if not matches_location(scoped_text, keywords) and not matches_location(url, keywords):
+            return None
+
+        price = parse_price_eur(scoped_text) or parse_price_eur(body)
+        area = parse_area_m2(scoped_text) or parse_area_m2(body)
+        photos = extract_photo_urls(soup, base_url=BASE, limit=8)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1] or Listing.hash_id(url)
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title_text or url,
+            price_eur=price,
+            area_m2=area,
+            description=scoped_text[:4000],
+            photos=photos,
+            raw={"detail_url": url},
+        )
+
+    @staticmethod
+    def _scope_main_section(soup: BeautifulSoup):
+        """Return the section containing 'Informacije' / 'Opis' headings."""
+        for section in soup.find_all("section"):
+            text = section.get_text(" ", strip=True).lower()
+            if "informacije" in text or "opis" in text[:300]:
+                return section
+        return soup.find("article") or soup.find("main") or soup.body
+
+
+def build(http: HttpClient | None = None) -> KrediumScraper:
+    return KrediumScraper(http=http)
diff --git a/serbian_realestate/scrapers/nekretnine.py b/serbian_realestate/scrapers/nekretnine.py
new file mode 100644
index 0000000..03d57ef
--- /dev/null
+++ b/serbian_realestate/scrapers/nekretnine.py
@@ -0,0 +1,118 @@
+"""nekretnine.rs — plain HTTP, paginated.
+
+The site's location filter bleeds non-target listings through, so we
+post-filter URLs against `location_keywords`. We also skip sale listings
+that arrive via shared infrastructure (item_category=Prodaja).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    HttpClient,
+    Listing,
+    Scraper,
+    matches_location,
+    parse_area_m2,
+    parse_price_eur,
+)
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+
+BASE = "https://www.nekretnine.rs"
+SEARCH_PATH = "/stambeni-objekti/stanovi/izdavanje-prodaja/izdavanje/lista/po-stranici/20/"
+DETAIL_RE = re.compile(r'href="(/stambeni-objekti/stanovi/[^"\s]+?)"', re.IGNORECASE)
+MAX_PAGES = 5
+
+
+class NekretnineScraper(Scraper):
+    name = "nekretnine"
+
+    def search(
+        self,
+        *,
+        location_slug: str,
+        location_keywords: Iterable[str],
+        max_listings: int = 30,
+    ) -> list[Listing]:
+        keywords = list(location_keywords)
+        seen: set[str] = set()
+        candidates: list[str] = []
+
+        for page in range(1, MAX_PAGES + 1):
+            url = f"{BASE}{SEARCH_PATH}?page={page}"
+            body = self.http.get(url, use_cache=False)
+            if not body:
+                break
+            for m in DETAIL_RE.finditer(body):
+                href = m.group(1)
+                if "item_category=prodaja" in href.lower() or "/prodaja/" in href.lower():
+                    continue
+                if not matches_location(href, keywords):
+                    continue
+                full = urljoin(BASE, href)
+                if full in seen:
+                    continue
+                seen.add(full)
+                candidates.append(full)
+                if len(candidates) >= max_listings:
+                    break
+            if len(candidates) >= max_listings:
+                break
+
+        listings: list[Listing] = []
+        for url in candidates:
+            listing = self._scrape_detail(url, keywords)
+            if listing:
+                listings.append(listing)
+        logger.info("nekretnine: %d listings", len(listings))
+        return listings
+
+    def _scrape_detail(self, url: str, keywords: list[str]) -> Listing | None:
+        body = self.http.get(url)
+        if not body:
+            return None
+        soup = BeautifulSoup(body, "lxml")
+        title = soup.find("h1")
+        title_text = title.get_text(strip=True) if title else ""
+
+        # Reject sale listings that snuck through (badge text "Prodaja")
+        # and re-confirm location keyword on the rendered body.
+        body_lower = body.lower()
+        if "prodaja" in body_lower and "izdavanje" not in body_lower:
+            return None
+        if not matches_location(body_lower, keywords):
+            # location filter is loose — skip if neighbourhood not present
+            return None
+
+        desc_node = soup.select_one(".cms-content, [class*='opis'], main")
+        description = desc_node.get_text(" ", strip=True) if desc_node else soup.get_text(" ", strip=True)
+
+        price = parse_price_eur(body)
+        area = parse_area_m2(body)
+        photos = extract_photo_urls(soup, base_url=BASE, limit=8)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1] or Listing.hash_id(url)
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title_text or url,
+            price_eur=price,
+            area_m2=area,
+            description=description[:4000],
+            photos=photos,
+            raw={"detail_url": url},
+        )
+
+
+def build(http: HttpClient | None = None) -> NekretnineScraper:
+    return NekretnineScraper(http=http)
diff --git a/serbian_realestate/scrapers/photos.py b/serbian_realestate/scrapers/photos.py
new file mode 100644
index 0000000..8503811
--- /dev/null
+++ b/serbian_realestate/scrapers/photos.py
@@ -0,0 +1,100 @@
+"""Generic photo URL extraction helpers.
+
+Each portal has its own image CDN naming convention; the helpers here are
+pattern-based fallbacks used when a portal exposes its photos via plain
+<img>/<source>/og:image tags rather than a structured JSON blob.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup, Tag
+
+# Photos served by Halo Oglasi mobile-app banners — useless for vision.
+_BANNER_PATTERNS = (
+    "apple-touch-icon",
+    "/static/",
+    "/icons/",
+    "play.google.com",
+    "apps.apple.com",
+    "favicon",
+    "/banner",
+    "_logo",
+    "logo.",
+)
+
+_IMAGE_EXT = (".jpg", ".jpeg", ".png", ".webp")
+
+
+def is_listing_photo(url: str) -> bool:
+    """Filter out banners, icons, app-store badges — anything not a listing image."""
+    if not url:
+        return False
+    lo = url.lower()
+    if not any(ext in lo for ext in _IMAGE_EXT):
+        return False
+    return not any(p in lo for p in _BANNER_PATTERNS)
+
+
+def extract_photo_urls(soup: BeautifulSoup, base_url: str, *, limit: int = 12) -> list[str]:
+    """Pull image URLs from common locations on a detail page.
+
+    Looks at og:image, <source srcset>, <img src/data-src>. Dedupes while
+    preserving order and caps to `limit`.
+    """
+    seen: set[str] = set()
+    urls: list[str] = []
+
+    def _add(raw: str | None) -> None:
+        if not raw:
+            return
+        full = urljoin(base_url, raw.strip())
+        if full in seen:
+            return
+        if not is_listing_photo(full):
+            return
+        seen.add(full)
+        urls.append(full)
+
+    for meta in soup.select('meta[property="og:image"], meta[name="og:image"]'):
+        _add(meta.get("content"))
+
+    for src in soup.find_all("source"):
+        if not isinstance(src, Tag):
+            continue
+        srcset = src.get("srcset") or src.get("data-srcset")
+        if not srcset:
+            continue
+        # take the largest candidate (last entry)
+        candidates = [c.strip().split(" ")[0] for c in srcset.split(",") if c.strip()]
+        if candidates:
+            _add(candidates[-1])
+
+    for img in soup.find_all("img"):
+        if not isinstance(img, Tag):
+            continue
+        for attr in ("data-src", "data-lazy-src", "src"):
+            val = img.get(attr)
+            if val:
+                _add(val)
+                break
+
+    return urls[:limit]
+
+
+def extract_photos_from_json_strings(html: str, *, limit: int = 12) -> list[str]:
+    """Grep for image URLs embedded in inline JSON/JS blobs."""
+    pattern = re.compile(r'https?://[^"\'\s<>]+?\.(?:jpg|jpeg|png|webp)', re.IGNORECASE)
+    urls: list[str] = []
+    seen: set[str] = set()
+    for m in pattern.finditer(html):
+        url = m.group(0)
+        if url in seen or not is_listing_photo(url):
+            continue
+        seen.add(url)
+        urls.append(url)
+        if len(urls) >= limit:
+            break
+    return urls
diff --git a/serbian_realestate/scrapers/river_check.py b/serbian_realestate/scrapers/river_check.py
new file mode 100644
index 0000000..5587e40
--- /dev/null
+++ b/serbian_realestate/scrapers/river_check.py
@@ -0,0 +1,247 @@
+"""Vision-based river-view verification using Anthropic Sonnet.
+
+We download each photo with httpx, base64-encode it, and send inline (URL
+mode 400s on some Serbian CDNs — 4zida resizer, kredium .webp). System
+prompt is cached to amortise cost across listings.
+"""
+
+from __future__ import annotations
+
+import base64
+import concurrent.futures
+import logging
+import os
+from dataclasses import dataclass
+from typing import Iterable
+
+import httpx
+
+from .base import Listing
+
+logger = logging.getLogger(__name__)
+
+
+VISION_MODEL_DEFAULT = "claude-sonnet-4-6"
+
+# Strict-grader system prompt. Haiku 4.5 was too generous so we explicitly
+# call out distant grey strips and reflections as non-positive.
+_SYSTEM_PROMPT = """You are a strict real-estate photo evaluator.
+
+Decide whether the apartment photo shows a clear, direct river view —
+specifically the Sava or Danube rivers in Belgrade, or Ada lake.
+
+Verdicts (output exactly one):
+- yes-direct: water occupies a meaningful portion of the frame, viewed
+  from a window/balcony of the apartment, clearly identifiable as a river
+  or large body of water. Wide stretches of visible water count.
+- partial: a slice of water is visible but it's a distant strip, partial
+  cityscape view with a sliver of river, or the photo is shot from such
+  an angle that the water is incidental.
+- indoor: photo is interior with no exterior view of water.
+- no: no visible water; photo is interior, street, courtyard, generic
+  cityscape with no river, or unrelated.
+
+Be strict. A grey horizon line that *might* be a river is `no`, not
+`partial`. Reflections in glass that aren't the actual outdoor view are
+`no`. Pools, fountains, bathtubs, and indoor water features are `no`.
+
+After the verdict, give one short sentence of evidence (max 25 words).
+
+Format your response exactly as:
+VERDICT: <verdict>
+EVIDENCE: <one sentence>
+"""
+
+
+@dataclass
+class PhotoEvidence:
+    """Per-photo verdict from the vision model."""
+
+    url: str
+    verdict: str  # yes-direct | partial | indoor | no | error
+    evidence: str
+
+    def to_dict(self) -> dict:
+        return {"url": self.url, "verdict": self.verdict, "evidence": self.evidence}
+
+
+def _require_api_key() -> str:
+    key = os.environ.get("ANTHROPIC_API_KEY")
+    if not key:
+        raise RuntimeError(
+            "ANTHROPIC_API_KEY not set. Required for --verify-river. "
+            "Re-run without --verify-river to skip vision."
+        )
+    return key
+
+
+def _download_photo(url: str, timeout: float = 20.0) -> tuple[str, bytes] | None:
+    """Fetch image bytes; return (mime_type, raw_bytes) or None on failure."""
+    try:
+        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+            resp = client.get(url)
+        if resp.status_code != 200:
+            logger.debug("photo HTTP %d: %s", resp.status_code, url)
+            return None
+        ctype = resp.headers.get("content-type", "image/jpeg").split(";")[0].strip()
+        if not ctype.startswith("image/"):
+            ctype = "image/jpeg"
+        return ctype, resp.content
+    except (httpx.HTTPError, httpx.TransportError) as exc:
+        logger.debug("photo fetch failed %s: %s", url, exc)
+        return None
+
+
+def _parse_response(raw: str) -> tuple[str, str]:
+    """Pluck VERDICT/EVIDENCE lines out of the model response, with fallbacks."""
+    verdict = "no"
+    evidence = ""
+    for line in raw.splitlines():
+        s = line.strip()
+        if s.upper().startswith("VERDICT:"):
+            verdict = s.split(":", 1)[1].strip().lower()
+        elif s.upper().startswith("EVIDENCE:"):
+            evidence = s.split(":", 1)[1].strip()
+    # legacy 'yes-distant' coerces to no
+    if verdict == "yes-distant":
+        verdict = "no"
+    if verdict not in {"yes-direct", "partial", "indoor", "no"}:
+        verdict = "no"
+    return verdict, evidence
+
+
+def _check_one_photo(
+    client, *, url: str, model: str
+) -> PhotoEvidence:
+    """Call Sonnet on a single photo. Errors return verdict='error' so they
+    don't poison the rest of the listing."""
+    blob = _download_photo(url)
+    if blob is None:
+        return PhotoEvidence(url=url, verdict="error", evidence="download failed")
+    media_type, raw = blob
+    b64 = base64.standard_b64encode(raw).decode("ascii")
+
+    try:
+        resp = client.messages.create(
+            model=model,
+            max_tokens=200,
+            system=[
+                {
+                    "type": "text",
+                    "text": _SYSTEM_PROMPT,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ],
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": media_type,
+                                "data": b64,
+                            },
+                        },
+                        {
+                            "type": "text",
+                            "text": "Evaluate this apartment photo for a direct river view.",
+                        },
+                    ],
+                }
+            ],
+        )
+    except Exception as exc:  # anthropic SDK raises a tree of subclasses
+        logger.debug("vision call failed for %s: %s", url, exc)
+        return PhotoEvidence(url=url, verdict="error", evidence=str(exc)[:120])
+
+    text = ""
+    for block in resp.content:
+        if getattr(block, "type", None) == "text":
+            text += block.text
+    verdict, evidence = _parse_response(text)
+    return PhotoEvidence(url=url, verdict=verdict, evidence=evidence)
+
+
+def verify_listings(
+    listings: Iterable[Listing],
+    *,
+    max_photos_per_listing: int = 3,
+    max_concurrent: int = 4,
+    model: str = VISION_MODEL_DEFAULT,
+    cached_evidence: dict[str, dict] | None = None,
+) -> None:
+    """Mutate each listing in-place with `river_photo_evidence`.
+
+    Cached evidence is reused if all the description text + photo URLs +
+    model match what we have on file (see is_vision_cache_valid).
+    """
+    listings = list(listings)
+    if not listings:
+        return
+    _require_api_key()
+
+    # Lazy import so the rest of the pipeline still works without the SDK.
+    from anthropic import Anthropic
+
+    client = Anthropic()
+    cached_evidence = cached_evidence or {}
+
+    def _process_one(listing: Listing) -> None:
+        cache_key = f"{listing.source}:{listing.listing_id}"
+        cached = cached_evidence.get(cache_key)
+        if cached and is_vision_cache_valid(
+            cached=cached,
+            description=listing.description,
+            photo_urls=listing.photos,
+            current_model=model,
+        ):
+            listing.river_photo_evidence = cached.get("photos", [])
+            logger.debug("vision cache hit %s", cache_key)
+            return
+
+        photos_to_check = [p for p in listing.photos if p][:max_photos_per_listing]
+        evidence: list[dict] = []
+        for url in photos_to_check:
+            ev = _check_one_photo(client, url=url, model=model)
+            evidence.append(ev.to_dict())
+        listing.river_photo_evidence = evidence
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max_concurrent) as pool:
+        list(pool.map(_process_one, listings))
+
+
+def is_vision_cache_valid(
+    *,
+    cached: dict,
+    description: str,
+    photo_urls: list[str],
+    current_model: str,
+) -> bool:
+    """Cached evidence is reusable only when nothing material changed.
+
+    Description, photo URL set, and model must all match. If any prior
+    photo had verdict='error' we redo the call — transient network blips
+    shouldn't be sticky.
+    """
+    if cached.get("model") != current_model:
+        return False
+    if cached.get("description") != description:
+        return False
+    if set(cached.get("photo_urls", [])) != set(photo_urls):
+        return False
+    for entry in cached.get("photos", []):
+        if entry.get("verdict") == "error":
+            return False
+    return True
+
+
+def build_cache_payload(listing: Listing, model: str) -> dict:
+    """Snapshot the inputs that gate cache validity, alongside the verdict."""
+    return {
+        "model": model,
+        "description": listing.description,
+        "photo_urls": list(listing.photos),
+        "photos": list(listing.river_photo_evidence),
+    }
diff --git a/serbian_realestate/search.py b/serbian_realestate/search.py
new file mode 100644
index 0000000..4612bfa
--- /dev/null
+++ b/serbian_realestate/search.py
@@ -0,0 +1,368 @@
+"""CLI entrypoint — orchestrates scraping, river verification, diffing, output.
+
+Usage:
+    uv run --directory serbian_realestate python search.py \\
+        --location beograd-na-vodi --min-m2 70 --max-price 1600 \\
+        --view river --sites 4zida,nekretnine,kredium \\
+        --verify-river --output markdown
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+import logging
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+
+from filters import (
+    CriteriaFilter,
+    combine_river_verdict,
+    detect_river_in_text,
+    passes_river_filter,
+)
+from scrapers.base import HttpClient, Listing
+from scrapers import (
+    cityexpert as cityexpert_mod,
+    fzida as fzida_mod,
+    halooglasi as halooglasi_mod,
+    indomio as indomio_mod,
+    kredium as kredium_mod,
+    nekretnine as nekretnine_mod,
+)
+from scrapers.river_check import (
+    VISION_MODEL_DEFAULT,
+    build_cache_payload,
+    verify_listings,
+)
+
+
+HERE = Path(__file__).resolve().parent
+STATE_DIR = HERE / "state"
+CACHE_DIR = STATE_DIR / "cache"
+
+SCRAPER_REGISTRY = {
+    "4zida": fzida_mod.build,
+    "nekretnine": nekretnine_mod.build,
+    "kredium": kredium_mod.build,
+    "cityexpert": cityexpert_mod.build,
+    "indomio": indomio_mod.build,
+    "halooglasi": halooglasi_mod.build,
+}
+
+DEFAULT_SITES = ["4zida", "nekretnine", "kredium", "cityexpert", "indomio", "halooglasi"]
+
+logger = logging.getLogger("search")
+
+
+def _load_config() -> dict:
+    cfg_path = HERE / "config.yaml"
+    if not cfg_path.exists():
+        return {}
+    with cfg_path.open(encoding="utf-8") as fh:
+        return yaml.safe_load(fh) or {}
+
+
+def _state_path(location: str) -> Path:
+    return STATE_DIR / f"last_run_{location}.json"
+
+
+def _load_state(location: str) -> dict:
+    path = _state_path(location)
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _save_state(location: str, state: dict) -> None:
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    path = _state_path(location)
+    path.write_text(json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def _build_scraper(name: str, http: HttpClient):
+    builder = SCRAPER_REGISTRY[name]
+    if name == "halooglasi":
+        return builder(http=http, state_dir=STATE_DIR)
+    return builder(http=http)
+
+
+def _scrape_all(
+    *,
+    sites: Iterable[str],
+    location_slug: str,
+    location_keywords: list[str],
+    indomio_slug: str | None,
+    cityexpert_district: str | None,
+    max_listings: int,
+    http: HttpClient,
+) -> list[Listing]:
+    """Run each requested scraper sequentially. Per-portal failure shouldn't sink the run."""
+    all_listings: list[Listing] = []
+    for site in sites:
+        if site not in SCRAPER_REGISTRY:
+            logger.warning("unknown site '%s', skipping", site)
+            continue
+        logger.info("→ scraping %s", site)
+        scraper = _build_scraper(site, http)
+        try:
+            slug_for_site = location_slug
+            if site == "indomio" and indomio_slug:
+                slug_for_site = indomio_slug
+            elif site == "cityexpert" and cityexpert_district:
+                # cityexpert URL is fixed; district keyword still filters
+                slug_for_site = cityexpert_district
+            results = scraper.search(
+                location_slug=slug_for_site,
+                location_keywords=location_keywords,
+                max_listings=max_listings,
+            )
+            all_listings.extend(results)
+        except Exception as exc:
+            logger.exception("scraper %s crashed: %s", site, exc)
+    return all_listings
+
+
+def _apply_text_river(listings: list[Listing]) -> None:
+    for li in listings:
+        result = detect_river_in_text(li.description + " " + li.title)
+        li.river_text_match = result.matched
+        li.river_text_evidence = result.evidence
+
+
+def _apply_diff(listings: list[Listing], state: dict) -> dict:
+    """Mark new listings; return the previous (source,id) → record map."""
+    prev_listings = state.get("listings", []) or []
+    prev_by_key = {f"{l['source']}:{l['listing_id']}": l for l in prev_listings}
+    for li in listings:
+        key = f"{li.source}:{li.listing_id}"
+        li.is_new = key not in prev_by_key
+    return prev_by_key
+
+
+def _format_markdown(listings: list[Listing], *, location_label: str) -> str:
+    out = io.StringIO()
+    out.write(f"# {location_label} — {len(listings)} listings\n\n")
+    out.write("| New | Source | Title | Price (€) | m² | Verdict | URL |\n")
+    out.write("|---|---|---|---:|---:|---|---|\n")
+    for li in listings:
+        new_marker = "🆕" if li.is_new else ""
+        verdict_disp = li.river_verdict
+        if verdict_disp == "text+photo":
+            verdict_disp = "⭐ text+photo"
+        price = f"{li.price_eur:.0f}" if li.price_eur is not None else "—"
+        area = f"{li.area_m2:.0f}" if li.area_m2 is not None else "—"
+        title_clean = (li.title or "").replace("|", "/")[:80]
+        out.write(
+            f"| {new_marker} | {li.source} | {title_clean} | {price} | {area} | "
+            f"{verdict_disp} | {li.url} |\n"
+        )
+    return out.getvalue()
+
+
+def _format_json(listings: list[Listing]) -> str:
+    return json.dumps([li.to_dict() for li in listings], indent=2, ensure_ascii=False)
+
+
+def _format_csv(listings: list[Listing]) -> str:
+    buf = io.StringIO()
+    fieldnames = [
+        "source",
+        "listing_id",
+        "is_new",
+        "title",
+        "price_eur",
+        "area_m2",
+        "rooms",
+        "floor",
+        "river_verdict",
+        "url",
+    ]
+    writer = csv.DictWriter(buf, fieldnames=fieldnames)
+    writer.writeheader()
+    for li in listings:
+        d = asdict(li)
+        writer.writerow({k: d.get(k, "") for k in fieldnames})
+    return buf.getvalue()
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Serbian rental classifieds monitor.")
+    p.add_argument("--location", default="beograd-na-vodi", help="config profile slug")
+    p.add_argument("--min-m2", type=float, default=None)
+    p.add_argument("--max-price", type=float, default=None, help="EUR / month")
+    p.add_argument(
+        "--view",
+        choices=["any", "river"],
+        default="any",
+        help="'river' restricts output to verified river views",
+    )
+    p.add_argument(
+        "--sites",
+        default=",".join(DEFAULT_SITES),
+        help="comma-separated list of portals (default: all)",
+    )
+    p.add_argument(
+        "--verify-river",
+        action="store_true",
+        help="run Sonnet vision verification on photos (requires ANTHROPIC_API_KEY)",
+    )
+    p.add_argument("--verify-max-photos", type=int, default=3)
+    p.add_argument("--max-listings", type=int, default=None)
+    p.add_argument(
+        "--output",
+        choices=["markdown", "json", "csv"],
+        default="markdown",
+    )
+    p.add_argument(
+        "--vision-model",
+        default=VISION_MODEL_DEFAULT,
+        help=f"vision model id (default {VISION_MODEL_DEFAULT})",
+    )
+    p.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="-v info, -vv debug",
+    )
+    return p
+
+
+def _setup_logging(verbose: int) -> None:
+    level = logging.WARNING
+    if verbose == 1:
+        level = logging.INFO
+    elif verbose >= 2:
+        level = logging.DEBUG
+    logging.basicConfig(
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+        level=level,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_arg_parser().parse_args(argv)
+    _setup_logging(args.verbose)
+
+    config = _load_config()
+    profiles = config.get("profiles", {})
+    defaults = config.get("defaults", {})
+    profile = profiles.get(args.location, {})
+    if not profile:
+        logger.warning("no config profile for '%s' — using slug as-is with empty keywords", args.location)
+
+    location_keywords = profile.get("location_keywords", [args.location])
+    label = profile.get("label", args.location)
+    indomio_slug = profile.get("indomio_slug")
+    cityexpert_district = profile.get("cityexpert_district")
+    min_m2 = args.min_m2 if args.min_m2 is not None else defaults.get("min_m2")
+    max_price = args.max_price if args.max_price is not None else defaults.get("max_price")
+    max_listings = args.max_listings or defaults.get("max_listings_per_site", 30)
+    verify_max_photos = args.verify_max_photos or defaults.get("verify_max_photos", 3)
+    sites = [s.strip() for s in args.sites.split(",") if s.strip()]
+
+    state = _load_state(args.location)
+    cached_evidence_by_key: dict[str, dict] = {
+        f"{l['source']}:{l['listing_id']}": l.get("vision_cache", {})
+        for l in state.get("listings", []) or []
+        if l.get("vision_cache")
+    }
+
+    with HttpClient(cache_dir=CACHE_DIR) as http:
+        all_listings = _scrape_all(
+            sites=sites,
+            location_slug=args.location,
+            location_keywords=location_keywords,
+            indomio_slug=indomio_slug,
+            cityexpert_district=cityexpert_district,
+            max_listings=max_listings,
+            http=http,
+        )
+
+    # Dedupe across portals on (source, listing_id) — already unique within
+    # a portal but defensively dedupe in case of double-runs.
+    seen: set[str] = set()
+    unique: list[Listing] = []
+    for li in all_listings:
+        key = f"{li.source}:{li.listing_id}"
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(li)
+
+    # Lenient criteria filter — keep listings missing m² / price with a warning
+    crit = CriteriaFilter(min_m2=min_m2, max_price=max_price)
+    filtered: list[Listing] = []
+    for li in unique:
+        ok, warns = crit.evaluate(area_m2=li.area_m2, price_eur=li.price_eur)
+        if not ok:
+            continue
+        for w in warns:
+            logger.warning("kept %s/%s with %s", li.source, li.listing_id, w)
+        filtered.append(li)
+
+    _apply_text_river(filtered)
+
+    if args.verify_river:
+        verify_listings(
+            filtered,
+            max_photos_per_listing=verify_max_photos,
+            model=args.vision_model,
+            cached_evidence={
+                k: v for k, v in cached_evidence_by_key.items()
+            },
+        )
+
+    for li in filtered:
+        li.river_verdict = combine_river_verdict(
+            text_match=li.river_text_match,
+            photo_evidence=li.river_photo_evidence,
+        )
+
+    final = [li for li in filtered if passes_river_filter(li.river_verdict, args.view)]
+
+    _apply_diff(final, state)
+
+    # Save state — include vision cache snapshots for future cache hits.
+    new_state_listings = []
+    for li in final:
+        d = li.to_dict()
+        d["vision_cache"] = build_cache_payload(li, args.vision_model)
+        new_state_listings.append(d)
+    new_state = {
+        "settings": {
+            "location": args.location,
+            "min_m2": min_m2,
+            "max_price": max_price,
+            "view": args.view,
+            "sites": sites,
+            "verify_river": args.verify_river,
+            "vision_model": args.vision_model,
+        },
+        "listings": new_state_listings,
+    }
+    _save_state(args.location, new_state)
+
+    if args.output == "json":
+        sys.stdout.write(_format_json(final))
+    elif args.output == "csv":
+        sys.stdout.write(_format_csv(final))
+    else:
+        sys.stdout.write(_format_markdown(final, location_label=label))
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

diff --git a/serbian_realestate/README.md b/serbian_realestate/README.md
new file mode 100644
index 0000000..d25bc69
--- /dev/null
+++ b/serbian_realestate/README.md
@@ -0,0 +1,52 @@
+# serbian_realestate
+
+Daily-runnable monitor of Serbian rental classifieds with vision-verified
+river-view detection. Built per `plan.md` at the repo root.
+
+## Quickstart
+
+```bash
+# Install deps + Playwright browsers
+uv sync --directory serbian_realestate
+uv run --directory serbian_realestate playwright install chromium
+
+# Smoke test the CLI (no network)
+uv run --directory serbian_realestate python search.py --help
+
+# Real run (BW, river-view filter, vision on)
+export ANTHROPIC_API_KEY=...
+uv run --directory serbian_realestate python search.py \
+  --location beograd-na-vodi --min-m2 70 --max-price 1600 \
+  --view any \
+  --sites 4zida,nekretnine,kredium,halooglasi,cityexpert,indomio \
+  --verify-river --verify-max-photos 3 \
+  --output markdown
+```
+
+## Sites
+
+| Site | Method | Notes |
+|---|---|---|
+| 4zida | plain HTTP | detail URLs in raw HTML |
+| nekretnine.rs | plain HTTP, paginated | loose location filter — keyword-filter URLs post-fetch |
+| kredium | plain HTTP, section-scoped | scope to <section> with "Informacije"/"Opis" |
+| cityexpert | Playwright | CF; URL `/en/properties-for-rent/belgrade?ptId=1` |
+| indomio | Playwright | Distil; per-municipality URL slug |
+| halooglasi | Selenium + undetected-chromedriver | CF aggressive — Playwright capped at 25-30% |
+
+## River-view verification
+
+Two-signal AND of text patterns + Sonnet vision. Strict prompt; only
+`yes-direct` photo verdicts count. Cached evidence is reused across runs as
+long as description, photos, and `VISION_MODEL` haven't changed.
+
+See `plan.md` §5 for full rules.
+
+## Output
+
+Markdown by default; `--output json|csv` for machine consumption.
+State written to `state/last_run_<location>.json` for diffing on next run.
+
+## Cost
+
+Per `plan.md` §8: cold ~$0.40, warm ~$0, daily ~$0.05–0.10.
diff --git a/serbian_realestate/__init__.py b/serbian_realestate/__init__.py
new file mode 100644
index 0000000..31fd807
--- /dev/null
+++ b/serbian_realestate/__init__.py
@@ -0,0 +1 @@
+"""Serbian real-estate rental monitor."""
diff --git a/serbian_realestate/config.yaml b/serbian_realestate/config.yaml
new file mode 100644
index 0000000..c5172f9
--- /dev/null
+++ b/serbian_realestate/config.yaml
@@ -0,0 +1,52 @@
+# Filter profiles for Serbian rental classifieds.
+# Each location entry defines:
+#   - name: pretty label (used in reports)
+#   - keywords: substrings used to post-filter URLs/cards on portals with loose
+#       location filters (matched case-insensitively against URL slug + card text)
+#   - per_site_urls: optional explicit start URLs / search params overriding defaults
+#
+# The CLI selects a profile via --location <slug>.
+
+profiles:
+  beograd-na-vodi:
+    name: "Belgrade Waterfront (Beograd na Vodi)"
+    keywords:
+      - "beograd-na-vodi"
+      - "beograd na vodi"
+      - "belgrade-waterfront"
+      - "belgrade waterfront"
+      - "bw residences"
+      - "bw "
+      - "bw."
+      - "bw,"
+    cityexpert_search: "/en/properties-for-rent/belgrade?ptId=1"
+    indomio_municipality: "belgrade-savski-venac"
+    halooglasi_search: "https://www.halooglasi.com/nekretnine/izdavanje-stanova/beograd/savski-venac"
+    nekretnine_search: "https://www.nekretnine.rs/stambeni-objekti/stanovi/izdavanje-prodaja/izdavanje/lokacija/beograd/grad-beograd/savski-venac/"
+    fzida_search: "https://www.4zida.rs/izdavanje-stanova/beograd/savski-venac"
+    kredium_search: "https://kredium.rs/sr/nekretnine?for=rent&type=apartment&city=Beograd"
+
+  savski-venac:
+    name: "Savski Venac"
+    keywords:
+      - "savski-venac"
+      - "savski venac"
+      - "dedinje"
+    cityexpert_search: "/en/properties-for-rent/belgrade?ptId=1"
+    indomio_municipality: "belgrade-savski-venac"
+    halooglasi_search: "https://www.halooglasi.com/nekretnine/izdavanje-stanova/beograd/savski-venac"
+    nekretnine_search: "https://www.nekretnine.rs/stambeni-objekti/stanovi/izdavanje-prodaja/izdavanje/lokacija/beograd/grad-beograd/savski-venac/"
+    fzida_search: "https://www.4zida.rs/izdavanje-stanova/beograd/savski-venac"
+    kredium_search: "https://kredium.rs/sr/nekretnine?for=rent&type=apartment&city=Beograd"
+
+  vracar:
+    name: "Vračar"
+    keywords:
+      - "vracar"
+      - "vračar"
+    cityexpert_search: "/en/properties-for-rent/belgrade?ptId=1"
+    indomio_municipality: "belgrade-vracar"
+    halooglasi_search: "https://www.halooglasi.com/nekretnine/izdavanje-stanova/beograd/vracar"
+    nekretnine_search: "https://www.nekretnine.rs/stambeni-objekti/stanovi/izdavanje-prodaja/izdavanje/lokacija/beograd/grad-beograd/vracar/"
+    fzida_search: "https://www.4zida.rs/izdavanje-stanova/beograd/vracar"
+    kredium_search: "https://kredium.rs/sr/nekretnine?for=rent&type=apartment&city=Beograd"
diff --git a/serbian_realestate/filters.py b/serbian_realestate/filters.py
new file mode 100644
index 0000000..3371409
--- /dev/null
+++ b/serbian_realestate/filters.py
@@ -0,0 +1,97 @@
+"""Match criteria + Serbian river-view text patterns.
+
+The text-pattern set is deliberately narrow — bare "reka"/"Sava"/"waterfront"
+generate too many false positives (street names, complex names). See plan.md
+section 5.1.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Iterable
+
+logger = logging.getLogger(__name__)
+
+
+# Compiled once; matched case-insensitively against listing description text.
+# Each pattern aims at an unambiguous Serbian/English phrasing of "river view".
+RIVER_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"pogled\s+na\s+(reku|reci|reke|savu|savi|save)\b", re.IGNORECASE),
+    re.compile(r"pogled\s+na\s+(adu|ada\s+ciganlij)", re.IGNORECASE),
+    re.compile(r"pogled\s+na\s+(dunav|dunavu)\b", re.IGNORECASE),
+    re.compile(r"prvi\s+red\s+(do|uz|na)\s+(reku|reci|reke|savu|save|savi|dunav)", re.IGNORECASE),
+    re.compile(r"(uz|pored|na\s+obali)\s+(reku|reci|reke|save|savu|savi|dunav)", re.IGNORECASE),
+    re.compile(r"okrenut\w*\s+.{0,30}(reci|reke|savi|save|dunav)", re.IGNORECASE),
+    re.compile(
+        r"panoramski\s+pogled\s+.{0,60}(reku|reci|save|savi|river|sava|dunav)",
+        re.IGNORECASE,
+    ),
+    # English fallbacks — some BW listings translate the description.
+    re.compile(r"\b(direct|panoramic|stunning)\s+view\s+of\s+the\s+(river|sava|danube)\b", re.IGNORECASE),
+    re.compile(r"\briver\s+view\b", re.IGNORECASE),
+]
+
+
+@dataclass(frozen=True)
+class FilterCriteria:
+    """User-supplied filtering criteria from the CLI."""
+
+    min_m2: float | None
+    max_price_eur: float | None
+    location_keywords: tuple[str, ...]
+
+
+def matches_river_text(text: str | None) -> tuple[bool, str | None]:
+    """Return (matched, snippet). Snippet is the first matching span for evidence."""
+    if not text:
+        return (False, None)
+    for pat in RIVER_PATTERNS:
+        m = pat.search(text)
+        if m:
+            start = max(0, m.start() - 30)
+            end = min(len(text), m.end() + 30)
+            return (True, text[start:end].strip())
+    return (False, None)
+
+
+def url_matches_keywords(url: str, keywords: Iterable[str]) -> bool:
+    """Case-insensitive substring match for post-fetch URL filtering."""
+    if not url:
+        return False
+    low = url.lower()
+    return any(kw.lower() in low for kw in keywords)
+
+
+def text_matches_keywords(text: str | None, keywords: Iterable[str]) -> bool:
+    """Case-insensitive substring match against listing card/description text."""
+    if not text:
+        return False
+    low = text.lower()
+    return any(kw.lower() in low for kw in keywords)
+
+
+def passes_basic_filter(
+    *,
+    m2: float | None,
+    price_eur: float | None,
+    criteria: FilterCriteria,
+    listing_id: str = "?",
+) -> bool:
+    """Apply m² and price filters with lenient handling of missing values.
+
+    Lenient behavior (plan.md §7.1): if a value is unknown we keep the listing
+    and warn — better to surface a manual-review item than drop a real match.
+    """
+    if criteria.min_m2 is not None:
+        if m2 is None:
+            logger.warning("listing %s: m² unknown — keeping for manual review", listing_id)
+        elif m2 < criteria.min_m2:
+            return False
+    if criteria.max_price_eur is not None:
+        if price_eur is None:
+            logger.warning("listing %s: price unknown — keeping for manual review", listing_id)
+        elif price_eur > criteria.max_price_eur:
+            return False
+    return True
diff --git a/serbian_realestate/pyproject.toml b/serbian_realestate/pyproject.toml
new file mode 100644
index 0000000..8efda9f
--- /dev/null
+++ b/serbian_realestate/pyproject.toml
@@ -0,0 +1,25 @@
+[project]
+name = "serbian-realestate"
+version = "0.1.0"
+description = "Daily-runnable monitor of Serbian rental classifieds with vision-verified river-view detection."
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.2",
+    "undetected-chromedriver>=3.5.5",
+    "playwright>=1.46",
+    "playwright-stealth>=1.0.6",
+    "anthropic>=0.40",
+    "pyyaml>=6.0",
+    "rich>=13.7",
+    "selenium>=4.20",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["scrapers"]
+include = ["search.py", "filters.py", "config.yaml"]
diff --git a/serbian_realestate/scrapers/__init__.py b/serbian_realestate/scrapers/__init__.py
new file mode 100644
index 0000000..b755216
--- /dev/null
+++ b/serbian_realestate/scrapers/__init__.py
@@ -0,0 +1,5 @@
+"""Per-portal scrapers for the Serbian real-estate monitor."""
+
+from .base import HttpClient, Listing, Scraper
+
+__all__ = ["HttpClient", "Listing", "Scraper"]
diff --git a/serbian_realestate/scrapers/base.py b/serbian_realestate/scrapers/base.py
new file mode 100644
index 0000000..e7b41cd
--- /dev/null
+++ b/serbian_realestate/scrapers/base.py
@@ -0,0 +1,256 @@
+"""Shared scraper primitives: Listing, HttpClient, Scraper base class."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import re
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+# Rotating-ish UA — modern Chrome on Linux. Matches the desktop fingerprint of
+# our undetected-chromedriver profile so caches behave consistently.
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
+)
+
+
+@dataclass
+class Listing:
+    """Normalised cross-portal listing record."""
+
+    source: str
+    listing_id: str
+    url: str
+    title: str | None = None
+    description: str | None = None
+    price_eur: float | None = None
+    m2: float | None = None
+    rooms: str | None = None
+    floor: str | None = None
+    location_text: str | None = None
+    photos: list[str] = field(default_factory=list)
+
+    # Populated downstream
+    river_text_match: bool = False
+    river_text_snippet: str | None = None
+    river_photo_evidence: list[dict[str, Any]] = field(default_factory=list)
+    river_verdict: str = "none"  # text+photo | text-only | photo-only | partial | none
+    is_new: bool = False
+
+    def key(self) -> str:
+        return f"{self.source}::{self.listing_id}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class HttpClient:
+    """Thin httpx wrapper with retries, polite throttling, and on-disk caching.
+
+    Caching is keyed by URL hash; we cache only on success. The intent is to
+    survive transient network blips during dev and avoid pounding portals on
+    repeated invocations within a single day.
+    """
+
+    def __init__(
+        self,
+        cache_dir: Path | None = None,
+        *,
+        ttl_seconds: int = 60 * 60 * 6,  # 6h — re-fetch within a day-of-runs
+        timeout: float = 30.0,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        self.cache_dir = cache_dir
+        self.ttl_seconds = ttl_seconds
+        self._client = httpx.Client(
+            follow_redirects=True,
+            timeout=timeout,
+            headers={
+                "User-Agent": user_agent,
+                "Accept-Language": "sr,en;q=0.8",
+                "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            },
+        )
+        if self.cache_dir is not None:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _cache_path(self, url: str) -> Path | None:
+        if self.cache_dir is None:
+            return None
+        h = hashlib.sha256(url.encode("utf-8")).hexdigest()[:24]
+        return self.cache_dir / f"{h}.html"
+
+    def get(self, url: str, *, retries: int = 2, sleep: float = 1.0) -> str:
+        """GET with retries + cache. Raises on final failure."""
+        cache_path = self._cache_path(url)
+        if cache_path and cache_path.exists():
+            age = time.time() - cache_path.stat().st_mtime
+            if age < self.ttl_seconds:
+                logger.debug("cache hit (%ds old): %s", int(age), url)
+                return cache_path.read_text(encoding="utf-8", errors="replace")
+
+        last_err: Exception | None = None
+        for attempt in range(retries + 1):
+            try:
+                resp = self._client.get(url)
+                resp.raise_for_status()
+                text = resp.text
+                if cache_path:
+                    cache_path.write_text(text, encoding="utf-8")
+                return text
+            except (httpx.HTTPError, httpx.TransportError) as e:
+                last_err = e
+                logger.warning("GET %s failed (attempt %d): %s", url, attempt + 1, e)
+                if attempt < retries:
+                    time.sleep(sleep * (attempt + 1))
+        assert last_err is not None
+        raise last_err
+
+    def get_bytes(self, url: str, *, retries: int = 2) -> bytes:
+        """Used by river_check.py for inline image fallback."""
+        last_err: Exception | None = None
+        for attempt in range(retries + 1):
+            try:
+                resp = self._client.get(url)
+                resp.raise_for_status()
+                return resp.content
+            except (httpx.HTTPError, httpx.TransportError) as e:
+                last_err = e
+                if attempt < retries:
+                    time.sleep(1.0 * (attempt + 1))
+        assert last_err is not None
+        raise last_err
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class Scraper:
+    """Base class — subclasses implement fetch_listings(profile, max_listings)."""
+
+    name: str = "base"
+
+    def __init__(self, http: HttpClient | None = None) -> None:
+        self.http = http or HttpClient()
+
+    def fetch_listings(
+        self, profile: dict[str, Any], *, max_listings: int = 30
+    ) -> list[Listing]:
+        raise NotImplementedError
+
+
+# ---------------------------------------------------------------------------
+# Helpers shared across scrapers
+# ---------------------------------------------------------------------------
+
+PRICE_PATTERNS = [
+    re.compile(r"€\s*([\d.,]+)"),
+    re.compile(r"([\d.,]+)\s*€"),
+    re.compile(r"([\d.,]+)\s*EUR", re.IGNORECASE),
+    re.compile(r"EUR\s*([\d.,]+)", re.IGNORECASE),
+]
+
+M2_PATTERNS = [
+    re.compile(r"([\d.,]+)\s*m\s*2", re.IGNORECASE),
+    re.compile(r"([\d.,]+)\s*m²"),
+    re.compile(r"([\d.,]+)\s*kvadrata", re.IGNORECASE),
+]
+
+
+def parse_number(raw: str) -> float | None:
+    """Parse Serbian-style numbers ("1.234,50" / "1,234.50" / "1234")."""
+    if not raw:
+        return None
+    s = raw.strip().replace("\xa0", "").replace(" ", "")
+    # Strip currency / units that may have leaked in
+    s = re.sub(r"[€$EURr²m²kvadrata]+", "", s, flags=re.IGNORECASE)
+    if not s:
+        return None
+    # If both separators present, the last one is decimal.
+    if "," in s and "." in s:
+        if s.rfind(",") > s.rfind("."):
+            s = s.replace(".", "").replace(",", ".")
+        else:
+            s = s.replace(",", "")
+    elif "," in s:
+        # Treat as decimal if 2 digits after comma, else thousands sep.
+        tail = s.split(",")[-1]
+        if len(tail) <= 2:
+            s = s.replace(",", ".")
+        else:
+            s = s.replace(",", "")
+    try:
+        return float(s)
+    except ValueError:
+        return None
+
+
+def extract_price_eur(text: str | None) -> float | None:
+    if not text:
+        return None
+    for pat in PRICE_PATTERNS:
+        m = pat.search(text)
+        if m:
+            n = parse_number(m.group(1))
+            if n is not None:
+                return n
+    return None
+
+
+def extract_m2(text: str | None) -> float | None:
+    if not text:
+        return None
+    for pat in M2_PATTERNS:
+        m = pat.search(text)
+        if m:
+            n = parse_number(m.group(1))
+            if n is not None:
+                return n
+    return None
+
+
+def slug_id_from_url(url: str) -> str:
+    """Compact, stable id from a listing URL."""
+    return re.sub(r"[^a-zA-Z0-9]+", "-", url).strip("-")[-80:] or hashlib.sha1(url.encode()).hexdigest()[:16]
+
+
+def dump_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
+
+
+def load_json(path: Path) -> Any | None:
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        logger.warning("corrupt state file: %s — ignoring", path)
+        return None
+
+
+def safe_text(s: str | None, *, max_len: int = 4000) -> str | None:
+    if s is None:
+        return None
+    s = re.sub(r"\s+", " ", s).strip()
+    return s[:max_len] if s else None
+
+
+def filter_iter(items: Iterable[Any], pred) -> list[Any]:
+    return [x for x in items if pred(x)]
diff --git a/serbian_realestate/scrapers/cityexpert.py b/serbian_realestate/scrapers/cityexpert.py
new file mode 100644
index 0000000..b67ff76
--- /dev/null
+++ b/serbian_realestate/scrapers/cityexpert.py
@@ -0,0 +1,152 @@
+"""cityexpert.rs — Playwright (CF-protected).
+
+Notes from plan.md §4.5:
+  - URL pattern: /en/properties-for-rent/belgrade?ptId=1 (apartments only)
+  - Pagination via ?currentPage=N (NOT ?page=N)
+  - MAX_PAGES bumped to 10 — BW listings are sparse
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from contextlib import contextmanager
+from typing import Any, Iterator
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    Listing,
+    Scraper,
+    extract_m2,
+    extract_price_eur,
+    safe_text,
+    slug_id_from_url,
+)
+from .photos import extract_photos_from_html
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://cityexpert.rs"
+MAX_PAGES = 10
+
+
+@contextmanager
+def _playwright_browser(*, headless: bool = True) -> Iterator[Any]:
+    """Context manager that yields a stealth-configured Playwright Page."""
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as e:
+        raise RuntimeError(
+            "Playwright not installed. Run: uv run playwright install chromium"
+        ) from e
+
+    try:
+        from playwright_stealth import stealth_sync  # type: ignore
+    except ImportError:
+        stealth_sync = None  # optional; CF tolerable without it for this site
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=headless)
+        context = browser.new_context(
+            user_agent=(
+                "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+                "(KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
+            ),
+            locale="en-US",
+            viewport={"width": 1366, "height": 900},
+        )
+        page = context.new_page()
+        if stealth_sync is not None:
+            try:
+                stealth_sync(page)
+            except Exception as e:
+                logger.debug("stealth_sync failed (non-fatal): %s", e)
+        try:
+            yield page
+        finally:
+            context.close()
+            browser.close()
+
+
+class CityExpertScraper(Scraper):
+    name = "cityexpert"
+
+    def fetch_listings(self, profile: dict[str, Any], *, max_listings: int = 30) -> list[Listing]:
+        search = profile.get("cityexpert_search") or "/en/properties-for-rent/belgrade?ptId=1"
+        start_url = urljoin(BASE, search)
+
+        detail_urls: list[str] = []
+        try:
+            with _playwright_browser() as page:
+                for n in range(1, MAX_PAGES + 1):
+                    sep = "&" if "?" in start_url else "?"
+                    url = f"{start_url}{sep}currentPage={n}"
+                    try:
+                        page.goto(url, wait_until="networkidle", timeout=45000)
+                    except Exception as e:
+                        logger.warning("cityexpert page %d nav failed: %s", n, e)
+                        continue
+                    page.wait_for_timeout(2500)
+                    html = page.content()
+                    page_urls = sorted(
+                        set(re.findall(r'href="(/en/property/[^"#?]+)"', html))
+                    )
+                    if not page_urls:
+                        logger.debug("cityexpert page %d: no detail links — stopping", n)
+                        break
+                    detail_urls.extend(urljoin(BASE, p) for p in page_urls)
+
+                # Dedupe, preserving order
+                seen: set[str] = set()
+                deduped: list[str] = []
+                for u in detail_urls:
+                    if u not in seen:
+                        seen.add(u)
+                        deduped.append(u)
+                logger.info("cityexpert: %d candidate detail URLs", len(deduped))
+
+                out: list[Listing] = []
+                for url in deduped[: max_listings * 2]:
+                    if len(out) >= max_listings:
+                        break
+                    try:
+                        listing = self._parse_detail_with_browser(page, url)
+                        if listing:
+                            out.append(listing)
+                    except Exception as e:
+                        logger.warning("cityexpert detail %s failed: %s", url, e)
+                return out
+        except RuntimeError as e:
+            logger.error("cityexpert: %s", e)
+            return []
+        except Exception as e:
+            logger.error("cityexpert fatal: %s", e)
+            return []
+
+    def _parse_detail_with_browser(self, page: Any, url: str) -> Listing | None:
+        try:
+            page.goto(url, wait_until="networkidle", timeout=45000)
+        except Exception as e:
+            logger.warning("cityexpert detail nav failed: %s", e)
+            return None
+        page.wait_for_timeout(2000)
+        html = page.content()
+        soup = BeautifulSoup(html, "lxml")
+        title_node = soup.find("h1")
+        title = safe_text(title_node.get_text(" ")) if title_node else None
+        body = safe_text(soup.get_text(" "))
+        price = extract_price_eur(body)
+        m2 = extract_m2(body)
+        photos = extract_photos_from_html(html, base_url=BASE, limit=8)
+        return Listing(
+            source=self.name,
+            listing_id=slug_id_from_url(url),
+            url=url,
+            title=title,
+            description=body,
+            price_eur=price,
+            m2=m2,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/fzida.py b/serbian_realestate/scrapers/fzida.py
new file mode 100644
index 0000000..ce3464f
--- /dev/null
+++ b/serbian_realestate/scrapers/fzida.py
@@ -0,0 +1,90 @@
+"""4zida.rs — plain HTTP.
+
+The list page is JS-rendered, but detail-page hrefs are present in the raw
+HTML and detail pages themselves are server-rendered, so we can skip a
+browser entirely. See plan.md §4.4.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    Listing,
+    Scraper,
+    extract_m2,
+    extract_price_eur,
+    safe_text,
+    slug_id_from_url,
+)
+from .photos import extract_photos_from_html
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.4zida.rs"
+
+
+class FzidaScraper(Scraper):
+    name = "4zida"
+
+    def fetch_listings(self, profile: dict[str, Any], *, max_listings: int = 30) -> list[Listing]:
+        start = profile.get("fzida_search") or f"{BASE}/izdavanje-stanova/beograd"
+        try:
+            html = self.http.get(start)
+        except Exception as e:  # network/CF/etc — soft-fail
+            logger.error("4zida list fetch failed: %s", e)
+            return []
+
+        # Detail URLs look like /izdavanje-stanova/<slug>/<id>
+        detail_urls = sorted(
+            set(
+                urljoin(BASE, href)
+                for href in re.findall(r'href="(/izdavanje-stanova/[^"#?]+/\d+)"', html)
+            )
+        )
+        logger.info("4zida: %d candidate detail URLs", len(detail_urls))
+        out: list[Listing] = []
+        for url in detail_urls[: max_listings * 2]:  # over-fetch; some may fail
+            if len(out) >= max_listings:
+                break
+            try:
+                listing = self._parse_detail(url)
+                if listing:
+                    out.append(listing)
+            except Exception as e:
+                logger.warning("4zida detail %s failed: %s", url, e)
+        return out
+
+    def _parse_detail(self, url: str) -> Listing | None:
+        html = self.http.get(url)
+        soup = BeautifulSoup(html, "lxml")
+
+        title = soup.find("h1")
+        title_text = safe_text(title.get_text(" ")) if title else None
+
+        # Description: 4zida ships the long copy inside an <article> or div.description.
+        desc_node = soup.find("article") or soup.find(class_=re.compile("description|opis", re.I))
+        desc = safe_text(desc_node.get_text(" ")) if desc_node else safe_text(soup.get_text(" "))
+
+        body_text = safe_text(soup.get_text(" "))
+        price = extract_price_eur(body_text)
+        m2 = extract_m2(body_text)
+        photos = extract_photos_from_html(html, base_url=BASE, limit=8)
+
+        listing_id = slug_id_from_url(url)
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title_text,
+            description=desc,
+            price_eur=price,
+            m2=m2,
+            location_text=None,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/halooglasi.py b/serbian_realestate/scrapers/halooglasi.py
new file mode 100644
index 0000000..4700c83
--- /dev/null
+++ b/serbian_realestate/scrapers/halooglasi.py
@@ -0,0 +1,193 @@
+"""halooglasi.com — Selenium + undetected-chromedriver.
+
+This is the hardest portal. See plan.md §4.1 for the full set of constraints
+that bit us during build. Highlights:
+
+  - Cloudflare aggressive — Playwright capped at 25-30%, uc gets ~100%
+  - page_load_strategy="eager" — without it driver.get() hangs on CF challenge
+  - Pass Chrome major version explicitly — auto-detect mismatches chromedriver
+  - Persistent profile dir keeps clearance cookies between runs
+  - time.sleep(8) then poll — CF JS blocks main thread, wait_for_function can't run
+  - Read structured data (window.QuidditaEnvironment.CurrentClassified.OtherFields) — not regex
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+from pathlib import Path
+from typing import Any
+
+from .base import (
+    Listing,
+    Scraper,
+    safe_text,
+    slug_id_from_url,
+)
+from .photos import extract_photos_from_html
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.halooglasi.com"
+PROFILE_DIR = Path(__file__).resolve().parent.parent / "state" / "browser" / "halooglasi_chrome_profile"
+
+
+def _detect_chrome_major_version() -> int | None:
+    """Best-effort detect of installed Google Chrome major version."""
+    import shutil
+    import subprocess
+
+    for cmd in ("google-chrome", "google-chrome-stable", "chrome"):
+        path = shutil.which(cmd)
+        if not path:
+            continue
+        try:
+            out = subprocess.check_output([path, "--version"], text=True, timeout=5)
+            m = re.search(r"(\d+)\.\d+", out)
+            if m:
+                return int(m.group(1))
+        except Exception:
+            continue
+    return None
+
+
+class HaloOglasiScraper(Scraper):
+    name = "halooglasi"
+
+    def fetch_listings(self, profile: dict[str, Any], *, max_listings: int = 30) -> list[Listing]:
+        try:
+            import undetected_chromedriver as uc  # type: ignore
+            from selenium.webdriver.common.by import By  # noqa: F401
+        except ImportError as e:
+            logger.error("halooglasi: undetected-chromedriver missing: %s", e)
+            return []
+
+        PROFILE_DIR.mkdir(parents=True, exist_ok=True)
+        opts = uc.ChromeOptions()
+        opts.add_argument("--headless=new")
+        opts.add_argument("--no-sandbox")
+        opts.add_argument("--disable-gpu")
+        opts.add_argument("--disable-dev-shm-usage")
+        opts.add_argument(f"--user-data-dir={PROFILE_DIR}")
+        opts.page_load_strategy = "eager"  # critical — avoids hang on CF challenge
+
+        version_main = _detect_chrome_major_version()
+        try:
+            driver = uc.Chrome(options=opts, version_main=version_main, use_subprocess=True)
+        except Exception as e:
+            logger.error("halooglasi: failed to start uc.Chrome: %s", e)
+            return []
+
+        try:
+            return self._scrape_with_driver(driver, profile, max_listings)
+        finally:
+            try:
+                driver.quit()
+            except Exception:
+                pass
+
+    def _scrape_with_driver(
+        self, driver: Any, profile: dict[str, Any], max_listings: int
+    ) -> list[Listing]:
+        start = profile.get("halooglasi_search") or f"{BASE}/nekretnine/izdavanje-stanova/beograd"
+
+        try:
+            driver.get(start)
+        except Exception as e:
+            logger.error("halooglasi list nav failed: %s", e)
+            return []
+        time.sleep(8)  # let CF challenge run; main thread blocked during this
+
+        list_html = driver.page_source or ""
+        # Detail URLs for halooglasi rentals look like /nekretnine/izdavanje-stanova/<slug>/<id>
+        detail_paths = sorted(
+            set(re.findall(r'href="(/nekretnine/izdavanje-stanova/[^"#?]+/\d+)"', list_html))
+        )
+        detail_urls = [BASE + p for p in detail_paths]
+        logger.info("halooglasi: %d candidate detail URLs", len(detail_urls))
+
+        out: list[Listing] = []
+        for url in detail_urls[: max_listings * 2]:
+            if len(out) >= max_listings:
+                break
+            try:
+                listing = self._parse_detail(driver, url)
+                if listing:
+                    out.append(listing)
+            except Exception as e:
+                logger.warning("halooglasi detail %s failed: %s", url, e)
+        return out
+
+    def _parse_detail(self, driver: Any, url: str) -> Listing | None:
+        try:
+            driver.get(url)
+        except Exception as e:
+            logger.warning("halooglasi detail nav failed: %s", e)
+            return None
+        time.sleep(8)  # CF challenge block
+
+        # Pull structured data first — far more reliable than DOM regex.
+        other_fields: dict[str, Any] = {}
+        title: str | None = None
+        description: str | None = None
+        try:
+            other_fields = driver.execute_script(
+                "try { return window.QuidditaEnvironment "
+                "&& window.QuidditaEnvironment.CurrentClassified "
+                "&& window.QuidditaEnvironment.CurrentClassified.OtherFields; } "
+                "catch(e) { return null; }"
+            ) or {}
+            title = driver.execute_script(
+                "try { return window.QuidditaEnvironment "
+                "&& window.QuidditaEnvironment.CurrentClassified "
+                "&& window.QuidditaEnvironment.CurrentClassified.Title; } "
+                "catch(e) { return null; }"
+            )
+            description = driver.execute_script(
+                "try { return window.QuidditaEnvironment "
+                "&& window.QuidditaEnvironment.CurrentClassified "
+                "&& window.QuidditaEnvironment.CurrentClassified.TextHtml; } "
+                "catch(e) { return null; }"
+            )
+        except Exception as e:
+            logger.debug("halooglasi structured-data probe failed: %s", e)
+
+        if not isinstance(other_fields, dict):
+            other_fields = {}
+
+        # Currency must be EUR (some listings price in RSD)
+        currency = other_fields.get("cena_d_unit_s")
+        price = other_fields.get("cena_d") if currency == "EUR" else None
+        m2 = other_fields.get("kvadratura_d")
+        rooms = other_fields.get("broj_soba_s")
+        floor_part = other_fields.get("sprat_s")
+        floor_total = other_fields.get("sprat_od_s")
+        floor = (
+            f"{floor_part}/{floor_total}"
+            if floor_part and floor_total
+            else (floor_part or None)
+        )
+
+        # Tip filter: only residential apartments
+        tip = other_fields.get("tip_nekretnine_s")
+        if tip and tip != "Stan":
+            logger.debug("halooglasi: skipping non-Stan listing (tip=%s)", tip)
+            return None
+
+        html = driver.page_source or ""
+        photos = extract_photos_from_html(html, base_url=BASE, limit=8)
+
+        return Listing(
+            source=self.name,
+            listing_id=slug_id_from_url(url),
+            url=url,
+            title=safe_text(title),
+            description=safe_text(description) or json.dumps(other_fields, ensure_ascii=False)[:2000],
+            price_eur=float(price) if isinstance(price, (int, float)) else None,
+            m2=float(m2) if isinstance(m2, (int, float)) else None,
+            rooms=str(rooms) if rooms else None,
+            floor=floor,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/indomio.py b/serbian_realestate/scrapers/indomio.py
new file mode 100644
index 0000000..0a39bc4
--- /dev/null
+++ b/serbian_realestate/scrapers/indomio.py
@@ -0,0 +1,123 @@
+"""indomio.rs — Playwright (Distil bot challenge).
+
+Notes from plan.md §4.6:
+  - SPA with Distil. Detail URLs have NO descriptive slug — just /en/{id}.
+  - Card-text filter (not URL keyword filter) — cards include
+    "Belgrade, Savski Venac: Dedinje" in their text.
+  - Server-side filter params don't work; only municipality URL slug filters.
+  - 8s SPA hydration wait before card collection.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from filters import text_matches_keywords
+from .base import (
+    Listing,
+    Scraper,
+    extract_m2,
+    extract_price_eur,
+    safe_text,
+    slug_id_from_url,
+)
+from .cityexpert import _playwright_browser
+from .photos import extract_photos_from_html
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.indomio.rs"
+HYDRATE_MS = 8000  # SPA hydration wait
+
+
+class IndomioScraper(Scraper):
+    name = "indomio"
+
+    def fetch_listings(self, profile: dict[str, Any], *, max_listings: int = 30) -> list[Listing]:
+        municipality = profile.get("indomio_municipality") or "belgrade-savski-venac"
+        keywords: list[str] = profile.get("keywords", []) or []
+        start_url = f"{BASE}/en/to-rent/flats/{municipality}"
+
+        detail_url_to_card_text: dict[str, str] = {}
+        try:
+            with _playwright_browser() as page:
+                try:
+                    page.goto(start_url, wait_until="networkidle", timeout=60000)
+                except Exception as e:
+                    logger.warning("indomio nav failed: %s", e)
+                    return []
+                page.wait_for_timeout(HYDRATE_MS)
+                html = page.content()
+                soup = BeautifulSoup(html, "lxml")
+
+                # Card discovery — look for anchor tags that point to /en/<numeric-id>
+                for a in soup.find_all("a", href=True):
+                    href = a["href"]
+                    m = re.match(r"^/en/(\d+)/?$", href)
+                    if not m:
+                        continue
+                    card_text = safe_text(a.get_text(" ")) or ""
+                    full_url = urljoin(BASE, href)
+                    # Keep the longest card text we've seen for this URL.
+                    if len(card_text) > len(detail_url_to_card_text.get(full_url, "")):
+                        detail_url_to_card_text[full_url] = card_text
+
+                # Card-text keyword filter (URL has no slug to filter on)
+                if keywords:
+                    detail_url_to_card_text = {
+                        u: t
+                        for u, t in detail_url_to_card_text.items()
+                        if text_matches_keywords(t, keywords)
+                    }
+
+                logger.info("indomio: %d candidate cards after filter", len(detail_url_to_card_text))
+
+                out: list[Listing] = []
+                for url in list(detail_url_to_card_text)[: max_listings * 2]:
+                    if len(out) >= max_listings:
+                        break
+                    try:
+                        listing = self._parse_detail(page, url, detail_url_to_card_text[url])
+                        if listing:
+                            out.append(listing)
+                    except Exception as e:
+                        logger.warning("indomio detail %s failed: %s", url, e)
+                return out
+        except RuntimeError as e:
+            logger.error("indomio: %s", e)
+            return []
+        except Exception as e:
+            logger.error("indomio fatal: %s", e)
+            return []
+
+    def _parse_detail(self, page: Any, url: str, card_text: str) -> Listing | None:
+        try:
+            page.goto(url, wait_until="networkidle", timeout=45000)
+        except Exception as e:
+            logger.warning("indomio detail nav failed: %s", e)
+            return None
+        page.wait_for_timeout(3000)
+        html = page.content()
+        soup = BeautifulSoup(html, "lxml")
+        title_node = soup.find("h1")
+        title = safe_text(title_node.get_text(" ")) if title_node else card_text
+        body = safe_text(soup.get_text(" "))
+        price = extract_price_eur(body) or extract_price_eur(card_text)
+        m2 = extract_m2(body) or extract_m2(card_text)
+        photos = extract_photos_from_html(html, base_url=BASE, limit=8)
+        return Listing(
+            source=self.name,
+            listing_id=slug_id_from_url(url),
+            url=url,
+            title=title,
+            description=body,
+            location_text=card_text,
+            price_eur=price,
+            m2=m2,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/kredium.py b/serbian_realestate/scrapers/kredium.py
new file mode 100644
index 0000000..41e439f
--- /dev/null
+++ b/serbian_realestate/scrapers/kredium.py
@@ -0,0 +1,101 @@
+"""kredium.rs — plain HTTP, section-scoped parsing.
+
+Caveat from plan.md §4.3: parsing the full body pollutes via a related-listings
+carousel. We scope parsing to the <section> wrapping the "Informacije" / "Opis"
+headings.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup, Tag
+
+from .base import (
+    Listing,
+    Scraper,
+    extract_m2,
+    extract_price_eur,
+    safe_text,
+    slug_id_from_url,
+)
+from .photos import extract_photos_from_html
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://kredium.rs"
+
+
+class KrediumScraper(Scraper):
+    name = "kredium"
+
+    def fetch_listings(self, profile: dict[str, Any], *, max_listings: int = 30) -> list[Listing]:
+        start = profile.get("kredium_search") or f"{BASE}/sr/nekretnine?for=rent&type=apartment"
+        try:
+            html = self.http.get(start)
+        except Exception as e:
+            logger.error("kredium list fetch failed: %s", e)
+            return []
+
+        # Detail URLs: /sr/nekretnine/<slug>-<id>
+        detail_urls = sorted(
+            set(
+                urljoin(BASE, href)
+                for href in re.findall(r'href="(/sr/nekretnine/[^"#?]+)"', html)
+                if not href.endswith("?for=rent")
+            )
+        )
+        logger.info("kredium: %d candidate detail URLs", len(detail_urls))
+
+        out: list[Listing] = []
+        for url in detail_urls[: max_listings * 2]:
+            if len(out) >= max_listings:
+                break
+            try:
+                listing = self._parse_detail(url)
+                if listing:
+                    out.append(listing)
+            except Exception as e:
+                logger.warning("kredium detail %s failed: %s", url, e)
+        return out
+
+    def _parse_detail(self, url: str) -> Listing | None:
+        html = self.http.get(url)
+        soup = BeautifulSoup(html, "lxml")
+
+        # Find the listing's own <section>: the one that contains the
+        # "Informacije" or "Opis" heading. Anything outside is the related-
+        # listings carousel and would corrupt our parse.
+        target_section: Tag | None = None
+        for sec in soup.find_all("section"):
+            text = sec.get_text(" ", strip=True)
+            if any(k in text for k in ("Informacije", "Opis", "Description")):
+                target_section = sec
+                break
+        scope = target_section or soup
+
+        title_node = scope.find("h1") or soup.find("h1")
+        title = safe_text(title_node.get_text(" ")) if title_node else None
+
+        desc_node = scope.find(class_=re.compile("description|opis", re.I))
+        desc = safe_text(desc_node.get_text(" ")) if desc_node else safe_text(scope.get_text(" "))
+
+        body = safe_text(scope.get_text(" "))
+        price = extract_price_eur(body)
+        m2 = extract_m2(body)
+        # Photos: extract from the listing scope, not the whole page.
+        photos = extract_photos_from_html(str(scope), base_url=BASE, limit=8)
+
+        return Listing(
+            source=self.name,
+            listing_id=slug_id_from_url(url),
+            url=url,
+            title=title,
+            description=desc,
+            price_eur=price,
+            m2=m2,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/nekretnine.py b/serbian_realestate/scrapers/nekretnine.py
new file mode 100644
index 0000000..2741460
--- /dev/null
+++ b/serbian_realestate/scrapers/nekretnine.py
@@ -0,0 +1,112 @@
+"""nekretnine.rs — plain HTTP, paginated.
+
+Caveats from plan.md §4.2:
+  - Location filter is loose; we keyword-filter URLs post-fetch.
+  - Skip sale listings (item_category=Prodaja); rentals only.
+  - Pagination via ?page=N; walk up to 5 pages.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from filters import url_matches_keywords
+from .base import (
+    Listing,
+    Scraper,
+    extract_m2,
+    extract_price_eur,
+    safe_text,
+    slug_id_from_url,
+)
+from .photos import extract_photos_from_html
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.nekretnine.rs"
+MAX_PAGES = 5
+
+
+class NekretnineScraper(Scraper):
+    name = "nekretnine"
+
+    def fetch_listings(self, profile: dict[str, Any], *, max_listings: int = 30) -> list[Listing]:
+        start = profile.get("nekretnine_search") or f"{BASE}/stambeni-objekti/stanovi/izdavanje-prodaja/izdavanje/"
+        keywords: list[str] = profile.get("keywords", []) or []
+
+        detail_urls: list[str] = []
+        for page in range(1, MAX_PAGES + 1):
+            url = f"{start}?page={page}" if "?" not in start else f"{start}&page={page}"
+            try:
+                html = self.http.get(url)
+            except Exception as e:
+                logger.warning("nekretnine list page %d failed: %s", page, e)
+                break
+
+            page_urls = sorted(
+                set(re.findall(r'href="(/stambeni-objekti/stanovi/[^"#?]+/\d+/?)"', html))
+            )
+            if not page_urls:
+                break
+            detail_urls.extend(urljoin(BASE, p) for p in page_urls)
+
+        # Skip sale listings — they leak in via shared infra
+        detail_urls = [u for u in detail_urls if "Prodaja" not in u and "/prodaja/" not in u]
+
+        # Keyword filter — loose location bleeds non-target listings
+        if keywords:
+            filtered = [u for u in detail_urls if url_matches_keywords(u, keywords)]
+            if filtered:
+                detail_urls = filtered
+
+        seen: set[str] = set()
+        deduped: list[str] = []
+        for u in detail_urls:
+            if u not in seen:
+                seen.add(u)
+                deduped.append(u)
+
+        logger.info("nekretnine: %d candidate detail URLs after filter", len(deduped))
+
+        out: list[Listing] = []
+        for u in deduped[: max_listings * 2]:
+            if len(out) >= max_listings:
+                break
+            try:
+                listing = self._parse_detail(u)
+                if listing:
+                    out.append(listing)
+            except Exception as e:
+                logger.warning("nekretnine detail %s failed: %s", u, e)
+        return out
+
+    def _parse_detail(self, url: str) -> Listing | None:
+        html = self.http.get(url)
+        soup = BeautifulSoup(html, "lxml")
+
+        title_node = soup.find("h1")
+        title = safe_text(title_node.get_text(" ")) if title_node else None
+
+        desc_node = soup.find(class_=re.compile("description|opis|details", re.I))
+        desc = safe_text(desc_node.get_text(" ")) if desc_node else safe_text(soup.get_text(" "))
+
+        body = safe_text(soup.get_text(" "))
+        price = extract_price_eur(body)
+        m2 = extract_m2(body)
+        photos = extract_photos_from_html(html, base_url=BASE, limit=8)
+
+        return Listing(
+            source=self.name,
+            listing_id=slug_id_from_url(url),
+            url=url,
+            title=title,
+            description=desc,
+            price_eur=price,
+            m2=m2,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/photos.py b/serbian_realestate/scrapers/photos.py
new file mode 100644
index 0000000..4b7ee66
--- /dev/null
+++ b/serbian_realestate/scrapers/photos.py
@@ -0,0 +1,91 @@
+"""Generic photo URL extraction helpers.
+
+Listing portals splatter image URLs across <img>, <source srcset>, OG tags,
+and JSON blobs. We do a best-effort sweep and dedupe by canonicalised URL.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+# Images we never want to send to the vision model.
+_BANNER_PATTERNS = [
+    re.compile(r"app-?store", re.IGNORECASE),
+    re.compile(r"google[-_]?play", re.IGNORECASE),
+    re.compile(r"placeholder", re.IGNORECASE),
+    re.compile(r"logo", re.IGNORECASE),
+    re.compile(r"sprite", re.IGNORECASE),
+    re.compile(r"\.svg(\?|$)", re.IGNORECASE),
+    re.compile(r"data:image", re.IGNORECASE),
+]
+
+
+def _is_banner(url: str) -> bool:
+    return any(p.search(url) for p in _BANNER_PATTERNS)
+
+
+def extract_photos_from_html(html: str, *, base_url: str = "", limit: int = 12) -> list[str]:
+    """Extract probable listing photos from HTML — deduped, capped.
+
+    We look at:
+      - <meta property="og:image"> (usually the cover photo)
+      - <img src> + <img srcset> + <source srcset>
+      - data-src / data-lazy attributes (lazyload patterns)
+      - JSON-LD `image` arrays
+    """
+    soup = BeautifulSoup(html, "lxml")
+    candidates: list[str] = []
+
+    for tag in soup.find_all("meta", property="og:image"):
+        c = tag.get("content")
+        if c:
+            candidates.append(c)
+
+    for img in soup.find_all("img"):
+        for attr in ("src", "data-src", "data-lazy-src", "data-original"):
+            v = img.get(attr)
+            if v:
+                candidates.append(v)
+        srcset = img.get("srcset")
+        if srcset:
+            # Each comma-separated entry is "<url> <width>" — take the URL.
+            for part in srcset.split(","):
+                candidates.append(part.strip().split(" ")[0])
+
+    for src in soup.find_all("source"):
+        srcset = src.get("srcset")
+        if srcset:
+            for part in srcset.split(","):
+                candidates.append(part.strip().split(" ")[0])
+
+    # JSON-LD payloads sometimes carry `image` arrays.
+    for script in soup.find_all("script", attrs={"type": "application/ld+json"}):
+        text = script.string or ""
+        for m in re.finditer(r'"image"\s*:\s*\[([^\]]+)\]', text):
+            for url_match in re.finditer(r'"(https?://[^"]+)"', m.group(1)):
+                candidates.append(url_match.group(1))
+        for m in re.finditer(r'"image"\s*:\s*"(https?://[^"]+)"', text):
+            candidates.append(m.group(1))
+
+    out: list[str] = []
+    seen: set[str] = set()
+    for c in candidates:
+        if not c:
+            continue
+        full = urljoin(base_url, c) if base_url else c
+        if full.startswith("//"):
+            full = "https:" + full
+        if not full.startswith("http"):
+            continue
+        if _is_banner(full):
+            continue
+        if full in seen:
+            continue
+        seen.add(full)
+        out.append(full)
+        if len(out) >= limit:
+            break
+    return out
diff --git a/serbian_realestate/scrapers/river_check.py b/serbian_realestate/scrapers/river_check.py
new file mode 100644
index 0000000..f5f779e
--- /dev/null
+++ b/serbian_realestate/scrapers/river_check.py
@@ -0,0 +1,254 @@
+"""Sonnet vision verification of river views in listing photos.
+
+Two-signal AND with text patterns (see filters.py + plan.md §5).
+
+Implementation notes that bit us during build (plan.md §5.2):
+  - Model is claude-sonnet-4-6 — Haiku 4.5 was too generous on distant grey strips
+  - Strict prompt: water must occupy meaningful portion, not distant sliver
+  - Only "yes-direct" counts as positive; "yes-distant" was deliberately removed
+  - Inline base64 fallback — Anthropic URL-mode 400s on some CDNs (4zida, kredium webp)
+  - System prompt cached with cache_control: ephemeral for cross-call savings
+  - Concurrent up to 4 listings, max 3 photos per listing
+  - Per-photo errors caught — single bad URL doesn't poison the listing
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from typing import Any
+
+from .base import HttpClient, Listing
+
+logger = logging.getLogger(__name__)
+
+
+VISION_MODEL = "claude-sonnet-4-6"
+MAX_LISTINGS_CONCURRENT = 4
+DEFAULT_MAX_PHOTOS = 3
+
+SYSTEM_PROMPT = """\
+You are evaluating real-estate listing photos. For each image, decide whether
+the photo shows a DIRECT, MEANINGFUL view of a river or large body of water
+(Sava, Danube, Ada Ciganlija lake) from the apartment's window/balcony/terrace.
+
+Be strict. The water must occupy a meaningful portion of the visible frame —
+not a distant grey strip on the horizon, not a tiny glimpse between buildings.
+
+Reply with EXACTLY one word from this set:
+  - yes-direct  (clear, meaningful river/water view from the property)
+  - partial     (some water visible but obstructed, distant, or not the main view)
+  - indoor      (interior shot — cannot tell)
+  - no          (no water in frame, or water only as tiny background element)
+
+Just the single word, lowercased, nothing else.
+"""
+
+
+@dataclass
+class PhotoVerdict:
+    url: str
+    verdict: str  # yes-direct | partial | indoor | no | error
+    detail: str = ""
+
+
+def _photo_bytes_b64(http: HttpClient, url: str) -> tuple[str, str] | None:
+    """Download photo and return (base64-data, media-type). None on failure."""
+    try:
+        data = http.get_bytes(url)
+    except Exception as e:
+        logger.debug("photo fetch failed (%s): %s", url, e)
+        return None
+    # Best-effort media-type detection — Anthropic accepts jpeg/png/gif/webp
+    lower = url.lower().split("?")[0]
+    if lower.endswith((".png",)):
+        mt = "image/png"
+    elif lower.endswith((".gif",)):
+        mt = "image/gif"
+    elif lower.endswith((".webp",)):
+        mt = "image/webp"
+    else:
+        mt = "image/jpeg"
+    return base64.standard_b64encode(data).decode("ascii"), mt
+
+
+def _verify_one_photo(client: Any, http: HttpClient, url: str) -> PhotoVerdict:
+    """Verify a single photo. Returns a PhotoVerdict; never raises."""
+    # Try URL mode first — cheapest, lets Anthropic pull the image directly.
+    try:
+        msg = client.messages.create(
+            model=VISION_MODEL,
+            max_tokens=20,
+            system=[
+                {
+                    "type": "text",
+                    "text": SYSTEM_PROMPT,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ],
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image", "source": {"type": "url", "url": url}},
+                        {"type": "text", "text": "Verdict:"},
+                    ],
+                }
+            ],
+        )
+        verdict = _extract_verdict(msg)
+        return PhotoVerdict(url=url, verdict=verdict)
+    except Exception as e:
+        logger.debug("URL-mode vision failed for %s — falling back to inline: %s", url, e)
+
+    # Inline base64 fallback for CDNs that 400 on Anthropic's fetcher.
+    blob = _photo_bytes_b64(http, url)
+    if blob is None:
+        return PhotoVerdict(url=url, verdict="error", detail="fetch failed")
+    b64, mt = blob
+    try:
+        msg = client.messages.create(
+            model=VISION_MODEL,
+            max_tokens=20,
+            system=[
+                {
+                    "type": "text",
+                    "text": SYSTEM_PROMPT,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ],
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": mt,
+                                "data": b64,
+                            },
+                        },
+                        {"type": "text", "text": "Verdict:"},
+                    ],
+                }
+            ],
+        )
+        verdict = _extract_verdict(msg)
+        return PhotoVerdict(url=url, verdict=verdict)
+    except Exception as e:
+        logger.warning("inline vision also failed for %s: %s", url, e)
+        return PhotoVerdict(url=url, verdict="error", detail=str(e)[:200])
+
+
+def _extract_verdict(msg: Any) -> str:
+    """Pull the verdict word out of an Anthropic Messages response."""
+    try:
+        text = "".join(
+            block.text for block in msg.content if getattr(block, "type", None) == "text"
+        ).strip().lower()
+    except Exception:
+        return "error"
+
+    # Coerce legacy "yes-distant" → "no" (plan.md §5.2)
+    if "yes-direct" in text:
+        return "yes-direct"
+    if "yes-distant" in text:
+        return "no"
+    for v in ("partial", "indoor", "no"):
+        if v in text:
+            return v
+    return "error"
+
+
+def verify_listings(
+    listings: list[Listing],
+    *,
+    max_photos_per_listing: int = DEFAULT_MAX_PHOTOS,
+    api_key: str | None = None,
+) -> None:
+    """Mutate listings in place: populate river_photo_evidence + river_verdict.
+
+    Combined verdict rule (plan.md §5.3):
+      text + photo yes-direct → "text+photo"
+      text only               → "text-only"
+      photo yes-direct only   → "photo-only"
+      photo partial only      → "partial"
+      else                    → "none"
+    """
+    api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "ANTHROPIC_API_KEY not set — required for --verify-river. "
+            "Export the key or remove the flag."
+        )
+
+    try:
+        from anthropic import Anthropic
+    except ImportError as e:
+        raise RuntimeError("anthropic SDK not installed") from e
+
+    client = Anthropic(api_key=api_key)
+    http = HttpClient()  # for inline-fallback image fetches; no caching needed
+
+    def verify_one_listing(listing: Listing) -> None:
+        photos = listing.photos[:max_photos_per_listing]
+        evidence: list[dict[str, Any]] = []
+        for url in photos:
+            v = _verify_one_photo(client, http, url)
+            evidence.append({"url": v.url, "verdict": v.verdict, "detail": v.detail})
+        listing.river_photo_evidence = evidence
+
+        has_direct = any(e["verdict"] == "yes-direct" for e in evidence)
+        has_partial = any(e["verdict"] == "partial" for e in evidence)
+
+        if listing.river_text_match and has_direct:
+            listing.river_verdict = "text+photo"
+        elif listing.river_text_match:
+            listing.river_verdict = "text-only"
+        elif has_direct:
+            listing.river_verdict = "photo-only"
+        elif has_partial:
+            listing.river_verdict = "partial"
+        else:
+            listing.river_verdict = "none"
+
+    try:
+        with ThreadPoolExecutor(max_workers=MAX_LISTINGS_CONCURRENT) as ex:
+            futures = [ex.submit(verify_one_listing, l) for l in listings]
+            for fut in as_completed(futures):
+                try:
+                    fut.result()
+                except Exception as e:
+                    logger.warning("verify_listings worker failed: %s", e)
+    finally:
+        http.close()
+
+
+def can_reuse_cached_evidence(
+    cached: dict[str, Any] | None,
+    listing: Listing,
+) -> bool:
+    """Decide whether prior cached evidence applies to this fetch.
+
+    Reuse only when ALL true (plan.md §6.1):
+      - Same description text
+      - Same photo URLs (order-insensitive)
+      - No verdict="error" in prior photos
+      - Prior evidence used the current VISION_MODEL
+    """
+    if not cached:
+        return False
+    if cached.get("vision_model") != VISION_MODEL:
+        return False
+    if cached.get("description") != listing.description:
+        return False
+    if set(cached.get("photos") or []) != set(listing.photos):
+        return False
+    prior = cached.get("river_photo_evidence") or []
+    if any(e.get("verdict") == "error" for e in prior):
+        return False
+    return True
diff --git a/serbian_realestate/search.py b/serbian_realestate/search.py
new file mode 100644
index 0000000..2eb0769
--- /dev/null
+++ b/serbian_realestate/search.py
@@ -0,0 +1,324 @@
+"""Serbian real-estate rental monitor — CLI entrypoint.
+
+Run via:
+
+    uv run --directory serbian_realestate python search.py \\
+      --location beograd-na-vodi --min-m2 70 --max-price 1600 \\
+      --view any \\
+      --sites 4zida,nekretnine,kredium,halooglasi,cityexpert,indomio \\
+      --verify-river --verify-max-photos 3 \\
+      --output markdown
+
+See plan.md for full design notes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+import logging
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+import yaml
+from rich.console import Console
+from rich.logging import RichHandler
+
+from filters import (
+    FilterCriteria,
+    matches_river_text,
+    passes_basic_filter,
+)
+from scrapers.base import Listing, dump_json, load_json, safe_text
+
+ALL_SITES = ["4zida", "nekretnine", "kredium", "cityexpert", "indomio", "halooglasi"]
+HERE = Path(__file__).resolve().parent
+STATE_DIR = HERE / "state"
+CACHE_DIR = STATE_DIR / "cache"
+
+
+# ---------------------------------------------------------------------------
+# Scraper registry — lazy import so a missing optional dep (Playwright /
+# undetected-chromedriver) only breaks the sites that need it.
+# ---------------------------------------------------------------------------
+
+def _build_scraper(name: str) -> Any:
+    from scrapers.base import HttpClient
+
+    http = HttpClient(cache_dir=CACHE_DIR / name)
+    if name == "4zida":
+        from scrapers.fzida import FzidaScraper
+        return FzidaScraper(http=http)
+    if name == "nekretnine":
+        from scrapers.nekretnine import NekretnineScraper
+        return NekretnineScraper(http=http)
+    if name == "kredium":
+        from scrapers.kredium import KrediumScraper
+        return KrediumScraper(http=http)
+    if name == "cityexpert":
+        from scrapers.cityexpert import CityExpertScraper
+        return CityExpertScraper(http=http)
+    if name == "indomio":
+        from scrapers.indomio import IndomioScraper
+        return IndomioScraper(http=http)
+    if name == "halooglasi":
+        from scrapers.halooglasi import HaloOglasiScraper
+        return HaloOglasiScraper(http=http)
+    raise ValueError(f"unknown site: {name}")
+
+
+# ---------------------------------------------------------------------------
+# Config loading
+# ---------------------------------------------------------------------------
+
+def load_profile(location: str) -> dict[str, Any]:
+    cfg = yaml.safe_load((HERE / "config.yaml").read_text(encoding="utf-8"))
+    profiles = cfg.get("profiles") or {}
+    if location not in profiles:
+        raise SystemExit(
+            f"Unknown --location '{location}'. "
+            f"Known: {', '.join(sorted(profiles))}"
+        )
+    return profiles[location]
+
+
+# ---------------------------------------------------------------------------
+# State / diff
+# ---------------------------------------------------------------------------
+
+def state_path(location: str) -> Path:
+    return STATE_DIR / f"last_run_{location}.json"
+
+
+def load_prior_state(location: str) -> dict[str, dict[str, Any]]:
+    """Map listing_key → prior listing dict from last run."""
+    raw = load_json(state_path(location))
+    if not raw:
+        return {}
+    return {l["source"] + "::" + l["listing_id"]: l for l in raw.get("listings", [])}
+
+
+# ---------------------------------------------------------------------------
+# Output formatters
+# ---------------------------------------------------------------------------
+
+def to_markdown(listings: list[Listing], *, profile_name: str) -> str:
+    lines = [f"# Listings — {profile_name}", ""]
+    if not listings:
+        lines.append("_No listings matched._")
+        return "\n".join(lines)
+
+    lines.append("| New | Source | m² | Price (EUR) | River | Title | URL |")
+    lines.append("|---|---|---|---|---|---|---|")
+    for l in listings:
+        new_flag = "🆕" if l.is_new else ""
+        river = l.river_verdict
+        if river == "text+photo":
+            river = "⭐ text+photo"
+        lines.append(
+            "| {new} | {src} | {m2} | {price} | {river} | {title} | [link]({url}) |".format(
+                new=new_flag,
+                src=l.source,
+                m2=f"{l.m2:.0f}" if l.m2 else "?",
+                price=f"{l.price_eur:.0f}" if l.price_eur else "?",
+                river=river,
+                title=(l.title or "—").replace("|", "\\|")[:80],
+                url=l.url,
+            )
+        )
+    return "\n".join(lines)
+
+
+def to_json_str(listings: list[Listing]) -> str:
+    return json.dumps(
+        [asdict(l) for l in listings], ensure_ascii=False, indent=2, default=str
+    )
+
+
+def to_csv_str(listings: list[Listing]) -> str:
+    buf = io.StringIO()
+    fields = [
+        "source", "listing_id", "url", "title", "m2", "price_eur",
+        "rooms", "floor", "river_verdict", "river_text_match", "is_new",
+    ]
+    w = csv.DictWriter(buf, fieldnames=fields)
+    w.writeheader()
+    for l in listings:
+        d = asdict(l)
+        w.writerow({k: d.get(k) for k in fields})
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Pipeline
+# ---------------------------------------------------------------------------
+
+def run(args: argparse.Namespace) -> int:
+    logging.basicConfig(
+        level=logging.INFO if not args.verbose else logging.DEBUG,
+        format="%(message)s",
+        handlers=[RichHandler(rich_tracebacks=True, show_time=False, show_path=False)],
+    )
+    log = logging.getLogger("serbian_realestate")
+    console = Console()
+
+    profile = load_profile(args.location)
+    keywords = tuple(profile.get("keywords") or [])
+    criteria = FilterCriteria(
+        min_m2=args.min_m2,
+        max_price_eur=args.max_price,
+        location_keywords=keywords,
+    )
+
+    sites = [s.strip() for s in args.sites.split(",") if s.strip()]
+    unknown = [s for s in sites if s not in ALL_SITES]
+    if unknown:
+        raise SystemExit(f"Unknown sites: {unknown}. Known: {ALL_SITES}")
+
+    log.info("Profile: %s | sites: %s", profile.get("name", args.location), sites)
+
+    # Prior state for diff + cached evidence reuse
+    prior_by_key = load_prior_state(args.location)
+
+    all_listings: list[Listing] = []
+    for site in sites:
+        log.info("=== %s ===", site)
+        try:
+            scraper = _build_scraper(site)
+        except Exception as e:
+            log.error("could not build %s scraper: %s", site, e)
+            continue
+        try:
+            site_listings = scraper.fetch_listings(profile, max_listings=args.max_listings)
+        except Exception as e:
+            log.exception("scraper %s crashed: %s", site, e)
+            continue
+        log.info("%s: fetched %d raw listings", site, len(site_listings))
+        all_listings.extend(site_listings)
+
+    # Apply basic filter (m²/price); lenient on missing values
+    filtered: list[Listing] = []
+    for l in all_listings:
+        if not passes_basic_filter(
+            m2=l.m2, price_eur=l.price_eur, criteria=criteria, listing_id=l.listing_id
+        ):
+            continue
+        filtered.append(l)
+    log.info("After basic filter: %d / %d", len(filtered), len(all_listings))
+
+    # Annotate text-pattern matches and is_new flag
+    for l in filtered:
+        matched, snippet = matches_river_text(safe_text(l.description))
+        l.river_text_match = matched
+        l.river_text_snippet = snippet
+        l.is_new = l.key() not in prior_by_key
+
+    # River-view vision verification
+    if args.verify_river:
+        from scrapers.river_check import (
+            VISION_MODEL,
+            can_reuse_cached_evidence,
+            verify_listings,
+        )
+
+        to_verify: list[Listing] = []
+        for l in filtered:
+            cached = prior_by_key.get(l.key())
+            if cached and can_reuse_cached_evidence(cached, l):
+                l.river_photo_evidence = cached.get("river_photo_evidence") or []
+                l.river_verdict = cached.get("river_verdict") or "none"
+                continue
+            to_verify.append(l)
+
+        log.info(
+            "River vision: %d to verify (%d reused from cache, model=%s)",
+            len(to_verify),
+            len(filtered) - len(to_verify),
+            VISION_MODEL,
+        )
+        if to_verify:
+            try:
+                verify_listings(to_verify, max_photos_per_listing=args.verify_max_photos)
+            except Exception as e:
+                log.error("vision verification failed: %s", e)
+    else:
+        # Without vision, fall back to text-only verdicts
+        for l in filtered:
+            l.river_verdict = "text-only" if l.river_text_match else "none"
+
+    # Final --view filter (strict mode keeps only positives)
+    output = filtered
+    if args.view == "river":
+        output = [
+            l for l in filtered
+            if l.river_verdict in ("text+photo", "text-only", "photo-only")
+        ]
+        log.info("After --view river filter: %d / %d", len(output), len(filtered))
+
+    # Sort: new first, then text+photo, then by price asc
+    rank = {"text+photo": 0, "text-only": 1, "photo-only": 2, "partial": 3, "none": 4}
+    output.sort(key=lambda l: (not l.is_new, rank.get(l.river_verdict, 5), l.price_eur or 1e9))
+
+    # Save state for next run (annotate vision_model so cache can self-invalidate)
+    state_listings = []
+    for l in output:
+        d = asdict(l)
+        if args.verify_river:
+            from scrapers.river_check import VISION_MODEL
+            d["vision_model"] = VISION_MODEL
+        state_listings.append(d)
+    settings = {
+        "location": args.location,
+        "min_m2": args.min_m2,
+        "max_price": args.max_price,
+        "view": args.view,
+        "sites": sites,
+        "verify_river": args.verify_river,
+    }
+    state_path_obj = state_path(args.location)
+    dump_json(state_path_obj, {"settings": settings, "listings": state_listings})
+
+    # Output
+    if args.output == "markdown":
+        console.print(to_markdown(output, profile_name=profile.get("name", args.location)))
+    elif args.output == "json":
+        sys.stdout.write(to_json_str(output))
+    elif args.output == "csv":
+        sys.stdout.write(to_csv_str(output))
+    else:
+        raise SystemExit(f"Unknown --output {args.output}")
+    return 0
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="Serbian real-estate rental monitor (river-view aware)"
+    )
+    p.add_argument("--location", default="beograd-na-vodi", help="Profile slug (see config.yaml)")
+    p.add_argument("--min-m2", type=float, default=None)
+    p.add_argument("--max-price", type=float, default=None, help="Max monthly rent (EUR)")
+    p.add_argument("--view", choices=["any", "river"], default="any")
+    p.add_argument(
+        "--sites",
+        default=",".join(ALL_SITES),
+        help="Comma-separated portal list",
+    )
+    p.add_argument("--verify-river", action="store_true", help="Run Sonnet vision verification")
+    p.add_argument("--verify-max-photos", type=int, default=3)
+    p.add_argument("--output", choices=["markdown", "json", "csv"], default="markdown")
+    p.add_argument("--max-listings", type=int, default=30, help="Per-site cap")
+    p.add_argument("-v", "--verbose", action="store_true")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    return run(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

diff --git a/serbian_realestate/README.md b/serbian_realestate/README.md
new file mode 100644
index 0000000..0ad869f
--- /dev/null
+++ b/serbian_realestate/README.md
@@ -0,0 +1,114 @@
+# Serbian Real-Estate Scraper
+
+Daily-runnable monitor of Serbian rental classifieds, filtered to user-defined
+criteria (location + min m² + max price). Outputs a deduped table with
+vision-verified river-view detection. Costs <$1/day in API tokens.
+
+## Quick start
+
+```bash
+# Install (one-time)
+uv sync
+uv run playwright install chromium  # for cityexpert + indomio
+
+# Run
+uv run --directory /home/dory/ai_will_replace_you/git-worktrees/scraper-r3-v0/serbian_realestate \
+  python search.py \
+    --location beograd-na-vodi --min-m2 70 --max-price 1600 \
+    --view any \
+    --sites 4zida,nekretnine,kredium,halooglasi,cityexpert,indomio \
+    --verify-river --verify-max-photos 3 \
+    --output markdown
+```
+
+`ANTHROPIC_API_KEY` must be set in env to use `--verify-river`. There is no
+`--api-key` flag by design.
+
+## Sites + method
+
+| Site | Method | Note |
+|---|---|---|
+| 4zida | plain HTTP | Detail URLs in HTML; detail pages server-rendered |
+| nekretnine.rs | plain HTTP, paginated | Loose location filter — keyword-filtered post-fetch; sale listings skipped |
+| kredium | plain HTTP, section-scoped | Avoids related-listings carousel pollution |
+| cityexpert | Playwright | Cloudflare-protected; `?currentPage=N` pagination |
+| indomio | Playwright | Distil challenge; per-municipality URL slug only |
+| halooglasi | undetected-chromedriver | Heavy CF; eager page-load + persistent profile |
+
+## Halo Oglasi caveats (the hardest site)
+
+- `page_load_strategy="eager"` is essential — without it, `driver.get()` hangs
+  forever on CF challenge pages.
+- Chrome major version is auto-detected and locked into `version_main=N` so
+  chromedriver doesn't ship too new for the installed Chrome.
+- Persistent profile dir at `state/browser/halooglasi_chrome_profile/` keeps
+  the CF clearance cookies between runs.
+- Numeric fields are read from `window.QuidditaEnvironment.CurrentClassified.OtherFields`
+  via `driver.execute_script` instead of regex'ing the body text.
+- If extraction rate drops, fall back to xvfb headed mode:
+
+  ```bash
+  sudo apt install xvfb
+  xvfb-run -a uv run --directory ... python search.py --no-headless ...
+  ```
+
+## River-view verification
+
+Two-signal AND. Final verdict labels:
+
+| Verdict | Meaning |
+|---|---|
+| `text+photo` ⭐ | Both Serbian text patterns and Sonnet vision agree |
+| `text-only` | Description matched, photos didn't (or weren't checked) |
+| `photo-only` | Photos showed direct river view, but text didn't match |
+| `partial` | Photos partial only |
+| `none` | Nothing |
+
+`--view river` accepts only `text+photo`, `text-only`, `photo-only`.
+
+Vision uses `claude-sonnet-4-6` — Haiku 4.5 was too generous, calling distant
+grey strips "rivers." Photos are downloaded locally and sent inline base64
+because some CDNs (4zida resizer, kredium .webp) reject Anthropic's URL fetcher.
+The system prompt is cached with `cache_control: ephemeral` for cross-call savings.
+
+## State + diffing
+
+`state/last_run_<location>.json` holds the prior run. New listings (by
+`(source, listing_id)`) are flagged with 🆕 in the markdown output.
+
+Vision-cache reuse requires *all* of: same description, same photo URL set,
+no prior `verdict="error"`, prior evidence used the current `VISION_MODEL`.
+
+## Lenient filter
+
+A listing with missing m² **or** missing price is kept (with a WARNING log line)
+so the user can review manually. The filter only excludes listings whose
+present value is out of range.
+
+## Cost / runtime
+
+- Cold run with vision: ~$0.40 for ~45 listings (~$0.009 each)
+- Warm run: ~$0 (cache hits)
+- Daily expected: $0.05–$0.10
+
+## Daily systemd timer (optional)
+
+```ini
+# ~/.config/systemd/user/serbian-realestate.timer
+[Timer]
+OnCalendar=*-*-* 08:00
+Persistent=true
+
+# ~/.config/systemd/user/serbian-realestate.service
+[Service]
+ExecStart=/usr/local/bin/uv run --directory /path/to/serbian_realestate python search.py --verify-river
+EnvironmentFile=/path/to/.env
+```
+
+## Conventions
+
+- Rentals only — no sale listings
+- No hardcoded API keys; `ANTHROPIC_API_KEY` from env
+- No `--api-key` CLI flags
+- Type hints, structured logging, pathlib
+- Tests are not bundled — run-time smoke is via `python search.py --max-listings 1`
diff --git a/serbian_realestate/config.yaml b/serbian_realestate/config.yaml
new file mode 100644
index 0000000..9c0c32e
--- /dev/null
+++ b/serbian_realestate/config.yaml
@@ -0,0 +1,48 @@
+# Filter profiles per location slug.
+# Keys are location slugs accepted by --location.
+# location_keywords are used to post-filter loose-matched listings (mainly nekretnine.rs)
+# whose location filtering bleeds non-target results.
+
+profiles:
+  beograd-na-vodi:
+    label: "Belgrade Waterfront (Beograd na Vodi)"
+    location_keywords:
+      - beograd-na-vodi
+      - belgrade-waterfront
+      - bw-residence
+      - bw residence
+      - waterfront
+      - savski-venac
+    indomio_municipality: belgrade-savski-venac
+    cityexpert_query: "ptId=1"
+    halooglasi_search: "https://www.halooglasi.com/nekretnine/izdavanje-stanova/beograd-na-vodi"
+    fzida_search: "https://www.4zida.rs/izdavanje-stanova/beograd-na-vodi"
+    nekretnine_search: "https://www.nekretnine.rs/stambeni-objekti/stanovi/lista/po-stranici/20/izdavanje/grad/beograd/"
+    kredium_search: "https://kredium.rs/en/search?type=rent&city=Beograd&neighborhood=Beograd%20na%20vodi"
+
+  savski-venac:
+    label: "Savski Venac (Belgrade)"
+    location_keywords:
+      - savski-venac
+      - savski venac
+      - dedinje
+      - senjak
+      - belgrade-savski-venac
+    indomio_municipality: belgrade-savski-venac
+    cityexpert_query: "ptId=1"
+    halooglasi_search: "https://www.halooglasi.com/nekretnine/izdavanje-stanova/savski-venac"
+    fzida_search: "https://www.4zida.rs/izdavanje-stanova/savski-venac"
+    nekretnine_search: "https://www.nekretnine.rs/stambeni-objekti/stanovi/lista/po-stranici/20/izdavanje/grad/beograd/"
+    kredium_search: "https://kredium.rs/en/search?type=rent&city=Beograd&neighborhood=Savski%20venac"
+
+  vracar:
+    label: "Vracar (Belgrade)"
+    location_keywords:
+      - vracar
+      - vračar
+    indomio_municipality: belgrade-vracar
+    cityexpert_query: "ptId=1"
+    halooglasi_search: "https://www.halooglasi.com/nekretnine/izdavanje-stanova/vracar"
+    fzida_search: "https://www.4zida.rs/izdavanje-stanova/vracar"
+    nekretnine_search: "https://www.nekretnine.rs/stambeni-objekti/stanovi/lista/po-stranici/20/izdavanje/grad/beograd/"
+    kredium_search: "https://kredium.rs/en/search?type=rent&city=Beograd&neighborhood=Vra%C4%8Dar"
diff --git a/serbian_realestate/filters.py b/serbian_realestate/filters.py
new file mode 100644
index 0000000..c907fa6
--- /dev/null
+++ b/serbian_realestate/filters.py
@@ -0,0 +1,99 @@
+"""Match criteria + Serbian-language river-view text patterns."""
+from __future__ import annotations
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+# Strict patterns. These must match *something more specific* than "river" alone:
+# bare `reka` / `Sava` are too generic (street name "Savska" appears in every
+# Belgrade Waterfront address). "waterfront" matches the project name "Belgrade
+# Waterfront" itself, not the view, so it's also banned.
+RIVER_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("pogled na reku", re.compile(r"pogled\s+na\s+(?:reku|reci|reke|sav[uaie]|dunav[uao]?|adu|ada\s*ciganlij[ai])", re.IGNORECASE)),
+    ("prvi red do reke", re.compile(r"prvi\s+red\s+(?:do|uz|na)\s+(?:reku|reci|reke|sav[uaie]|dunav[uao]?)", re.IGNORECASE)),
+    ("uz/pored/na obali reke", re.compile(r"(?:uz|pored|na\s+obali)\s+(?:reku|reci|reke|sav[uaie]|dunav[uao]?)", re.IGNORECASE)),
+    ("okrenut ka reci", re.compile(r"okrenut[a-z]*\s+.{0,30}?(?:reci|reke|sav[uaie]|dunav[uao]?)", re.IGNORECASE | re.DOTALL)),
+    ("panoramski pogled", re.compile(r"panoramski\s+pogled\s+.{0,60}?(?:reku|sav[uaie]|dunav[uao]?|river|sava)", re.IGNORECASE | re.DOTALL)),
+    ("river view (en)", re.compile(r"\b(?:river\s+view|view\s+of\s+the\s+(?:river|sava|danube)|overlooking\s+the\s+(?:river|sava|danube))\b", re.IGNORECASE)),
+]
+
+# Patterns we explicitly do NOT match — documented for posterity.
+# - bare 'reka' / 'reku' (used in non-view contexts like 'blizu reke')
+# - bare 'Sava' (street name 'Savska' is everywhere in BW addresses)
+# - 'waterfront' (matches the project name 'Belgrade Waterfront')
+
+
+def text_river_evidence(*texts: str) -> tuple[bool, str]:
+    """Run all river patterns over concatenated text. Returns (matched, evidence_label)."""
+    blob = " ".join(t for t in texts if t)
+    for label, pat in RIVER_PATTERNS:
+        m = pat.search(blob)
+        if m:
+            snippet = blob[max(0, m.start() - 30) : m.end() + 30]
+            return True, f"{label}: …{snippet.strip()}…"
+    return False, ""
+
+
+def matches_filters(
+    *,
+    price_eur: float | None,
+    area_m2: float | None,
+    min_m2: float | None,
+    max_price: float | None,
+    listing_id: str = "",
+) -> bool:
+    """Lenient filter — keep listings with missing values, log a warning."""
+    missing = []
+    if min_m2 is not None and area_m2 is None:
+        missing.append("area")
+    if max_price is not None and price_eur is None:
+        missing.append("price")
+    if missing:
+        logger.warning(
+            "listing %s missing %s — keeping for manual review",
+            listing_id,
+            ",".join(missing),
+        )
+        return True
+
+    if min_m2 is not None and area_m2 is not None and area_m2 < min_m2:
+        return False
+    if max_price is not None and price_eur is not None and price_eur > max_price:
+        return False
+    return True
+
+
+def combined_river_verdict(
+    *, text_match: bool, photo_verdicts: list[str]
+) -> str:
+    """Combine text + photo signals into a final verdict label.
+
+    text+photo : ⭐ both signals
+    text-only  : Serbian text matches, no photo confirmation
+    photo-only : Sonnet vision saw direct river view but text didn't match
+    partial    : photos partial only
+    none       : nothing
+    """
+    has_yes_direct = any(v == "yes-direct" for v in photo_verdicts)
+    has_partial = any(v == "partial" for v in photo_verdicts)
+
+    if text_match and has_yes_direct:
+        return "text+photo"
+    if text_match:
+        return "text-only"
+    if has_yes_direct:
+        return "photo-only"
+    if has_partial:
+        return "partial"
+    return "none"
+
+
+def passes_view_filter(verdict: str, view_mode: str) -> bool:
+    """For --view river: only text+photo, text-only, photo-only pass."""
+    if view_mode == "any":
+        return True
+    if view_mode == "river":
+        return verdict in {"text+photo", "text-only", "photo-only"}
+    return True
diff --git a/serbian_realestate/pyproject.toml b/serbian_realestate/pyproject.toml
new file mode 100644
index 0000000..1ac3dee
--- /dev/null
+++ b/serbian_realestate/pyproject.toml
@@ -0,0 +1,24 @@
+[project]
+name = "serbian-realestate"
+version = "0.1.0"
+description = "Daily-runnable monitor of Serbian rental classifieds with vision-verified river-view detection."
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27.0",
+    "beautifulsoup4>=4.12.0",
+    "lxml>=5.0.0",
+    "undetected-chromedriver>=3.5.5",
+    "selenium>=4.20.0",
+    "playwright>=1.45.0",
+    "playwright-stealth>=1.0.6",
+    "anthropic>=0.40.0",
+    "pyyaml>=6.0",
+    "rich>=13.7.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
diff --git a/serbian_realestate/scrapers/__init__.py b/serbian_realestate/scrapers/__init__.py
new file mode 100644
index 0000000..327e374
--- /dev/null
+++ b/serbian_realestate/scrapers/__init__.py
@@ -0,0 +1 @@
+"""Per-portal scrapers for Serbian real-estate sites."""
diff --git a/serbian_realestate/scrapers/base.py b/serbian_realestate/scrapers/base.py
new file mode 100644
index 0000000..a0e099a
--- /dev/null
+++ b/serbian_realestate/scrapers/base.py
@@ -0,0 +1,222 @@
+"""Shared types, HTTP client, and base scraper for all portals."""
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+import time
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Any, Iterable
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Single shared User-Agent. Real Chrome on Linux to mimic typical hosts.
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+)
+
+DEFAULT_HEADERS = {
+    "User-Agent": DEFAULT_USER_AGENT,
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9,sr;q=0.7",
+    "Accept-Encoding": "gzip, deflate, br",
+    "Cache-Control": "no-cache",
+}
+
+
+@dataclass
+class Listing:
+    """Normalized rental listing across all portals.
+
+    Missing m² / price are tolerated — the lenient filter (search.py) keeps
+    them with a warning so the user can review manually.
+    """
+
+    source: str
+    listing_id: str
+    url: str
+    title: str = ""
+    price_eur: float | None = None
+    area_m2: float | None = None
+    rooms: float | None = None
+    floor: str | None = None
+    location: str = ""
+    description: str = ""
+    photos: list[str] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    # Filled in by river_check.py after vision verification.
+    river_text_match: bool = False
+    river_text_evidence: str = ""
+    river_photo_evidence: list[dict[str, Any]] = field(default_factory=list)
+    river_verdict: str = "none"  # text+photo|text-only|photo-only|partial|none
+
+    # Set by state diffing in search.py.
+    is_new: bool = False
+
+    def key(self) -> tuple[str, str]:
+        return (self.source, self.listing_id)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class HttpClient:
+    """Tiny wrapper around httpx with retries, on-disk caching, and polite delay."""
+
+    def __init__(
+        self,
+        cache_dir: Path | None = None,
+        timeout: float = 30.0,
+        delay: float = 0.5,
+        max_retries: int = 3,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.cache_dir = cache_dir
+        if cache_dir:
+            cache_dir.mkdir(parents=True, exist_ok=True)
+        self.delay = delay
+        self.max_retries = max_retries
+        self._client = httpx.Client(
+            timeout=timeout,
+            follow_redirects=True,
+            headers={**DEFAULT_HEADERS, **(headers or {})},
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _cache_path(self, url: str) -> Path | None:
+        if not self.cache_dir:
+            return None
+        h = hashlib.sha1(url.encode("utf-8")).hexdigest()[:16]
+        return self.cache_dir / f"{h}.html"
+
+    def get(self, url: str, *, use_cache: bool = False, **kw: Any) -> str:
+        """GET text content. Returns empty string on persistent failure."""
+        path = self._cache_path(url) if use_cache else None
+        if path and path.exists():
+            return path.read_text(encoding="utf-8", errors="replace")
+
+        last_err: Exception | None = None
+        for attempt in range(self.max_retries):
+            try:
+                if attempt > 0:
+                    time.sleep(self.delay * (2**attempt))
+                else:
+                    time.sleep(self.delay)
+                resp = self._client.get(url, **kw)
+                if resp.status_code == 200:
+                    text = resp.text
+                    if path:
+                        path.write_text(text, encoding="utf-8")
+                    return text
+                if resp.status_code in (429, 503):
+                    logger.warning("rate-limited %s on %s, backing off", resp.status_code, url)
+                    time.sleep(2.0 * (attempt + 1))
+                    continue
+                logger.warning("GET %s -> %s", url, resp.status_code)
+                return ""
+            except (httpx.HTTPError, httpx.TimeoutException) as exc:
+                last_err = exc
+                logger.warning("GET %s failed (attempt %d): %s", url, attempt + 1, exc)
+        if last_err:
+            logger.error("giving up on %s: %s", url, last_err)
+        return ""
+
+
+class Scraper:
+    """Base class for all per-portal scrapers."""
+
+    name: str = "base"
+
+    def __init__(
+        self,
+        location: str,
+        profile: dict[str, Any],
+        http: HttpClient,
+        max_listings: int = 30,
+    ) -> None:
+        self.location = location
+        self.profile = profile
+        self.http = http
+        self.max_listings = max_listings
+
+    def fetch(self) -> list[Listing]:
+        raise NotImplementedError
+
+
+# ------------------- helpers shared across scrapers ------------------- #
+
+
+def parse_price_eur(text: str) -> float | None:
+    """Parse '1.500 €' / 'EUR 2,000' / '€1500' style strings to float EUR."""
+    if not text:
+        return None
+    t = text.replace("\xa0", " ").lower()
+    # Reject explicit non-EUR currencies (RSD, dinar) to avoid mixing units.
+    if "rsd" in t or "din" in t:
+        # Some sites display both — prefer EUR if present alongside.
+        if "eur" not in t and "€" not in t:
+            return None
+    # Pull first numeric chunk that looks like a price (>=2 digits).
+    m = re.search(r"(\d[\d\.,\s]{1,12}\d|\d{2,})", t)
+    if not m:
+        return None
+    raw = m.group(1).replace(" ", "")
+    # Heuristic: if both . and , present, assume thousands sep is the leftmost
+    if raw.count(",") and raw.count("."):
+        if raw.rfind(",") > raw.rfind("."):
+            raw = raw.replace(".", "").replace(",", ".")
+        else:
+            raw = raw.replace(",", "")
+    elif raw.count(",") == 1 and len(raw.split(",")[1]) == 3:
+        raw = raw.replace(",", "")  # 1,500 = 1500
+    elif raw.count(".") == 1 and len(raw.split(".")[1]) == 3:
+        raw = raw.replace(".", "")
+    else:
+        raw = raw.replace(",", ".")
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def parse_area_m2(text: str) -> float | None:
+    """Parse '85 m²' / '85m2' / '85.5 kvm' to float m²."""
+    if not text:
+        return None
+    m = re.search(r"(\d+[\.,]?\d*)\s*(m\s*²|m2|kvm|kvadrat)", text, re.IGNORECASE)
+    if not m:
+        # Bare number near 'kvadratura'
+        m = re.search(r"kvadratura[^\d]{0,5}(\d+[\.,]?\d*)", text, re.IGNORECASE)
+    if not m:
+        return None
+    try:
+        return float(m.group(1).replace(",", "."))
+    except ValueError:
+        return None
+
+
+def matches_location_keywords(text: str, keywords: Iterable[str]) -> bool:
+    if not text:
+        return False
+    haystack = text.lower()
+    return any(k.lower() in haystack for k in keywords)
+
+
+def dedupe_listings(listings: Iterable[Listing]) -> list[Listing]:
+    seen: dict[tuple[str, str], Listing] = {}
+    for lst in listings:
+        seen.setdefault(lst.key(), lst)
+    return list(seen.values())
diff --git a/serbian_realestate/scrapers/cityexpert.py b/serbian_realestate/scrapers/cityexpert.py
new file mode 100644
index 0000000..77dec7e
--- /dev/null
+++ b/serbian_realestate/scrapers/cityexpert.py
@@ -0,0 +1,139 @@
+"""cityexpert.rs scraper — Playwright (Cloudflare-protected).
+
+Pagination uses `?currentPage=N` (NOT `?page=N`). The right URL is
+`/en/properties-for-rent/belgrade?ptId=1` for apartments — `/en/r/...`
+returns 404. BW listings are sparse (~1 per 5 pages) so we walk up to 10.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from .base import Listing, Scraper, parse_area_m2, parse_price_eur
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://cityexpert.rs"
+SEARCH_BASE = "https://cityexpert.rs/en/properties-for-rent/belgrade"
+MAX_PAGES = 10
+
+DETAIL_HREF_RE = re.compile(
+    r'href="(/en/property[^"#?]+)"', re.IGNORECASE
+)
+
+
+class CityExpertScraper(Scraper):
+    name = "cityexpert"
+
+    def fetch(self) -> list[Listing]:
+        try:
+            from playwright.sync_api import sync_playwright
+        except ImportError:
+            logger.error("cityexpert needs playwright — `uv run playwright install chromium`")
+            return []
+
+        try:
+            from playwright_stealth import stealth_sync  # type: ignore
+        except ImportError:
+            stealth_sync = None  # noqa: N806
+
+        query = self.profile.get("cityexpert_query", "ptId=1")
+        out: list[Listing] = []
+        seen_urls: set[str] = set()
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            ctx = browser.new_context(
+                user_agent=(
+                    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+                    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+                ),
+                locale="en-US",
+            )
+            page = ctx.new_page()
+            if stealth_sync:
+                try:
+                    stealth_sync(page)
+                except Exception:  # noqa: BLE001
+                    pass
+
+            for pg in range(1, MAX_PAGES + 1):
+                url = f"{SEARCH_BASE}?{query}&currentPage={pg}"
+                try:
+                    page.goto(url, wait_until="domcontentloaded", timeout=45_000)
+                    page.wait_for_timeout(2500)
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("cityexpert page %d failed: %s", pg, exc)
+                    break
+
+                html = page.content()
+                page_urls = []
+                for m in DETAIL_HREF_RE.finditer(html):
+                    full = urljoin(BASE, m.group(1))
+                    if full in seen_urls:
+                        continue
+                    seen_urls.add(full)
+                    page_urls.append(full)
+
+                if not page_urls:
+                    # Past the last page or an empty one — bail.
+                    break
+
+                for detail_url in page_urls:
+                    if len(out) >= self.max_listings:
+                        browser.close()
+                        return out
+                    lst = self._fetch_detail(page, detail_url)
+                    if lst:
+                        out.append(lst)
+
+            browser.close()
+        return out
+
+    def _fetch_detail(self, page: Any, url: str) -> Listing | None:
+        try:
+            page.goto(url, wait_until="domcontentloaded", timeout=45_000)
+            page.wait_for_timeout(1500)
+            html = page.content()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("cityexpert detail %s failed: %s", url, exc)
+            return None
+
+        from bs4 import BeautifulSoup
+
+        soup = BeautifulSoup(html, "lxml")
+        title_el = soup.find(["h1", "h2"])
+        title = title_el.get_text(" ", strip=True) if title_el else ""
+
+        body = soup.get_text(" ", strip=True)
+        price = parse_price_eur(_around(body, ["€", "EUR", "Price", "Cena"]))
+        area = parse_area_m2(_around(body, ["m²", "m2", "Area", "Kvadratura"]))
+
+        photos = extract_photo_urls(html, base_url=BASE, limit=8)
+
+        m = re.search(r"/([\w-]+)-(\d+)/?$", url) or re.search(r"/(\d+)/?$", url)
+        listing_id = m.group(0).strip("/") if m else url
+
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            description=body[:3000],
+            photos=photos,
+            location=self.location,
+        )
+
+
+def _around(text: str, anchors: list[str], window: int = 80) -> str:
+    low = text.lower()
+    for a in anchors:
+        i = low.find(a.lower())
+        if i >= 0:
+            return text[max(0, i - window) : i + window]
+    return text[:300]
diff --git a/serbian_realestate/scrapers/fzida.py b/serbian_realestate/scrapers/fzida.py
new file mode 100644
index 0000000..9f933f5
--- /dev/null
+++ b/serbian_realestate/scrapers/fzida.py
@@ -0,0 +1,105 @@
+"""4zida.rs scraper — plain HTTP.
+
+The list page is JS-rendered, but detail URLs appear as plain `href` attributes
+in the initial HTML. Detail pages are server-rendered, so no browser needed.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import HttpClient, Listing, Scraper, parse_area_m2, parse_price_eur
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.4zida.rs"
+DETAIL_HREF_RE = re.compile(r'href="(/(?:izdavanje|stan|nekretnine)/[^"#?]+)"', re.IGNORECASE)
+
+
+class FzidaScraper(Scraper):
+    name = "4zida"
+
+    def fetch(self) -> list[Listing]:
+        search_url = self.profile.get("fzida_search")
+        if not search_url:
+            logger.info("4zida: no fzida_search in profile, skipping")
+            return []
+
+        out: list[Listing] = []
+        seen: set[str] = set()
+        # Walk a couple of pages — listings are sparse on narrow location filters.
+        for page in range(1, 4):
+            url = search_url if page == 1 else f"{search_url}?strana={page}"
+            html = self.http.get(url, use_cache=False)
+            if not html:
+                break
+            page_urls: list[str] = []
+            for m in DETAIL_HREF_RE.finditer(html):
+                href = m.group(1)
+                if "/izdavanje" not in href:
+                    continue
+                full = urljoin(BASE, href)
+                if full in seen:
+                    continue
+                seen.add(full)
+                page_urls.append(full)
+
+            if not page_urls:
+                break
+            for detail_url in page_urls:
+                if len(out) >= self.max_listings:
+                    return out
+                listing = self._parse_detail(detail_url)
+                if listing:
+                    out.append(listing)
+        return out
+
+    def _parse_detail(self, url: str) -> Listing | None:
+        html = self.http.get(url, use_cache=True)
+        if not html:
+            return None
+        soup = BeautifulSoup(html, "lxml")
+
+        title_el = soup.find(["h1", "h2"])
+        title = title_el.get_text(" ", strip=True) if title_el else ""
+
+        # Price + area: look in the body for typical patterns.
+        body_text = soup.get_text(" ", strip=True)
+        price = parse_price_eur(_around(body_text, ["€", "EUR", "Cena"]))
+        area = parse_area_m2(_around(body_text, ["m²", "m2", "Kvadratura"]))
+
+        desc_el = soup.find(attrs={"class": re.compile(r"opis|description", re.IGNORECASE)})
+        description = desc_el.get_text(" ", strip=True) if desc_el else body_text[:2000]
+
+        photos = extract_photo_urls(html, base_url=BASE, limit=8)
+
+        # Listing ID = trailing numeric or slug from URL
+        m = re.search(r"/([^/?#]+)/?$", url)
+        listing_id = m.group(1) if m else url
+
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            description=description,
+            photos=photos,
+            location=self.location,
+        )
+
+
+def _around(text: str, anchors: list[str], window: int = 60) -> str:
+    """Return a small window of text around any of the anchor tokens."""
+    low = text.lower()
+    for a in anchors:
+        i = low.find(a.lower())
+        if i >= 0:
+            return text[max(0, i - window) : i + window]
+    return text[:200]
diff --git a/serbian_realestate/scrapers/halooglasi.py b/serbian_realestate/scrapers/halooglasi.py
new file mode 100644
index 0000000..2db56bb
--- /dev/null
+++ b/serbian_realestate/scrapers/halooglasi.py
@@ -0,0 +1,236 @@
+"""halooglasi.com scraper — Selenium + undetected-chromedriver.
+
+The hard one. Critical lessons baked in:
+
+- Cannot use Playwright — Cloudflare challenges every detail page; extraction
+  caps at 25-30% even with playwright-stealth. undetected-chromedriver gets ~100%.
+- `page_load_strategy="eager"` — without it `driver.get()` hangs forever on
+  CF challenge pages (window load event never fires).
+- Pass Chrome major version explicitly to `uc.Chrome(version_main=N)` —
+  auto-detect ships chromedriver too new (Chrome 147 + chromedriver 148 →
+  SessionNotCreated). We probe Chrome's version and lock chromedriver to it.
+- Persistent profile dir keeps CF clearance cookies between runs.
+- `time.sleep(8)` then poll — CF challenge JS blocks the main thread, so
+  `wait_for_function`-style polling can't even run during it. Hard sleep.
+- Read structured data, not regex body text — Halo Oglasi exposes
+  `window.QuidditaEnvironment.CurrentClassified.OtherFields` with all the
+  numeric fields we need.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from .base import HttpClient, Listing, Scraper
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+
+def _detect_chrome_major() -> int | None:
+    """Return Chrome's major version, or None if google-chrome isn't installed.
+
+    Auto-detect in undetected-chromedriver sometimes ships a too-new chromedriver
+    on bleeding-edge Chrome installs, so we lock it explicitly.
+    """
+    for binary in ("google-chrome", "google-chrome-stable", "chrome"):
+        path = shutil.which(binary)
+        if not path:
+            continue
+        try:
+            out = subprocess.run(
+                [path, "--version"], capture_output=True, text=True, timeout=10
+            )
+            m = re.search(r"(\d+)\.\d+\.\d+", out.stdout or "")
+            if m:
+                return int(m.group(1))
+        except Exception:  # noqa: BLE001
+            continue
+    return None
+
+
+class HaloOglasiScraper(Scraper):
+    name = "halooglasi"
+
+    def __init__(self, *args: Any, profile_dir: Path | None = None, headless: bool = True, **kw: Any) -> None:
+        super().__init__(*args, **kw)
+        self.profile_dir = profile_dir
+        self.headless = headless
+
+    def fetch(self) -> list[Listing]:
+        try:
+            import undetected_chromedriver as uc
+            from selenium.webdriver.common.by import By
+        except ImportError:
+            logger.error("halooglasi needs undetected-chromedriver + selenium")
+            return []
+
+        search_url = self.profile.get("halooglasi_search")
+        if not search_url:
+            logger.info("halooglasi: no halooglasi_search in profile, skipping")
+            return []
+
+        opts = uc.ChromeOptions()
+        opts.page_load_strategy = "eager"  # critical for CF challenge pages
+        if self.headless:
+            opts.add_argument("--headless=new")
+        opts.add_argument("--window-size=1366,900")
+        opts.add_argument("--disable-blink-features=AutomationControlled")
+        opts.add_argument("--no-sandbox")
+
+        if self.profile_dir:
+            self.profile_dir.mkdir(parents=True, exist_ok=True)
+            opts.add_argument(f"--user-data-dir={self.profile_dir}")
+
+        chrome_major = _detect_chrome_major()
+        driver = None
+        try:
+            driver = uc.Chrome(
+                options=opts,
+                version_main=chrome_major,
+                use_subprocess=True,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.error("halooglasi: failed to launch Chrome: %s", exc)
+            return []
+
+        out: list[Listing] = []
+        try:
+            urls = self._collect_listing_urls(driver, search_url)
+            for u in urls:
+                if len(out) >= self.max_listings:
+                    break
+                lst = self._fetch_detail(driver, u)
+                if lst:
+                    out.append(lst)
+        finally:
+            try:
+                driver.quit()
+            except Exception:  # noqa: BLE001
+                pass
+        return out
+
+    def _collect_listing_urls(self, driver: Any, search_url: str) -> list[str]:
+        urls: list[str] = []
+        seen: set[str] = set()
+        for page in range(1, 4):
+            url = search_url if page == 1 else f"{search_url}?page={page}"
+            try:
+                driver.get(url)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("halooglasi list %s failed: %s", url, exc)
+                break
+            time.sleep(8)  # CF JS blocks main thread; hard sleep before reading
+            html = driver.page_source or ""
+            page_urls = []
+            for m in re.finditer(
+                r'href="(/nekretnine/[^"#?]+/\d+)"', html, re.IGNORECASE
+            ):
+                full = "https://www.halooglasi.com" + m.group(1)
+                if full in seen:
+                    continue
+                seen.add(full)
+                page_urls.append(full)
+            if not page_urls:
+                break
+            urls.extend(page_urls)
+        return urls
+
+    def _fetch_detail(self, driver: Any, url: str) -> Listing | None:
+        try:
+            driver.get(url)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("halooglasi detail %s failed: %s", url, exc)
+            return None
+        time.sleep(6)
+        # If page still shows CF challenge, give it a couple more seconds + reload once.
+        if "Just a moment" in (driver.title or "") or "Cloudflare" in (driver.page_source or ""):
+            time.sleep(4)
+            if "Just a moment" in (driver.title or ""):
+                try:
+                    driver.refresh()
+                    time.sleep(8)
+                except Exception:  # noqa: BLE001
+                    pass
+
+        # Read structured data via JS — robust against DOM markup changes.
+        fields: dict[str, Any] = {}
+        try:
+            fields = driver.execute_script(
+                "return (window.QuidditaEnvironment "
+                "&& window.QuidditaEnvironment.CurrentClassified "
+                "&& window.QuidditaEnvironment.CurrentClassified.OtherFields) "
+                "|| {};"
+            ) or {}
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("halooglasi structured-data read failed: %s", exc)
+
+        title = ""
+        try:
+            title = driver.title or ""
+        except Exception:  # noqa: BLE001
+            pass
+
+        # Skip non-EUR pricing; rentals on this site are normally EUR.
+        unit = (fields.get("cena_d_unit_s") or "").upper()
+        if unit and unit != "EUR":
+            return None
+        # Rentals only — keep apartments (Stan).
+        tip = fields.get("tip_nekretnine_s", "")
+        if tip and tip != "Stan":
+            return None
+
+        price = _to_float(fields.get("cena_d"))
+        area = _to_float(fields.get("kvadratura_d"))
+        rooms = _to_float(fields.get("broj_soba_s"))
+        floor = fields.get("sprat_s")
+
+        html = driver.page_source or ""
+        photos = extract_photo_urls(html, base_url="https://www.halooglasi.com", limit=8)
+
+        # Description: find the longest text block in <p> tags.
+        try:
+            from bs4 import BeautifulSoup
+
+            soup = BeautifulSoup(html, "lxml")
+            blocks = [p.get_text(" ", strip=True) for p in soup.find_all(["p", "div"])]
+            description = max(blocks, key=len) if blocks else html[:2000]
+        except Exception:  # noqa: BLE001
+            description = html[:2000]
+
+        m = re.search(r"/(\d+)$", url)
+        listing_id = m.group(1) if m else url
+
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            rooms=rooms,
+            floor=str(floor) if floor else None,
+            description=description,
+            photos=photos,
+            location=self.location,
+            raw={"OtherFields": fields},
+        )
+
+
+def _to_float(v: Any) -> float | None:
+    if v is None:
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    s = str(v).replace(",", ".").strip()
+    try:
+        return float(s)
+    except ValueError:
+        m = re.search(r"\d+(?:\.\d+)?", s)
+        return float(m.group(0)) if m else None
diff --git a/serbian_realestate/scrapers/indomio.py b/serbian_realestate/scrapers/indomio.py
new file mode 100644
index 0000000..fc45c7f
--- /dev/null
+++ b/serbian_realestate/scrapers/indomio.py
@@ -0,0 +1,145 @@
+"""indomio.rs scraper — Playwright (Distil bot challenge).
+
+Detail URLs have NO descriptive slug — just `/en/{numeric-ID}` — so we cannot
+URL-keyword-filter. Instead we filter by card text ("Belgrade, Savski Venac:
+Dedinje" etc.). Server-side filter params don't work; only the per-municipality
+URL slug filters reliably. Wait ~8s for SPA hydration before card collection.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from .base import (
+    Listing,
+    Scraper,
+    matches_location_keywords,
+    parse_area_m2,
+    parse_price_eur,
+)
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.indomio.rs"
+
+DETAIL_HREF_RE = re.compile(r'href="(/en/\d+/?)"')
+
+
+class IndomioScraper(Scraper):
+    name = "indomio"
+
+    def fetch(self) -> list[Listing]:
+        try:
+            from playwright.sync_api import sync_playwright
+        except ImportError:
+            logger.error("indomio needs playwright — `uv run playwright install chromium`")
+            return []
+
+        try:
+            from playwright_stealth import stealth_sync  # type: ignore
+        except ImportError:
+            stealth_sync = None  # noqa: N806
+
+        municipality = self.profile.get("indomio_municipality")
+        if not municipality:
+            logger.info("indomio: no indomio_municipality in profile, skipping")
+            return []
+
+        search_url = f"{BASE}/en/to-rent/flats/{municipality}"
+        keywords = self.profile.get("location_keywords") or [self.location]
+        out: list[Listing] = []
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            ctx = browser.new_context(locale="en-US")
+            page = ctx.new_page()
+            if stealth_sync:
+                try:
+                    stealth_sync(page)
+                except Exception:  # noqa: BLE001
+                    pass
+
+            try:
+                page.goto(search_url, wait_until="domcontentloaded", timeout=45_000)
+                # SPA hydration / Distil clearance.
+                page.wait_for_timeout(8_000)
+                html = page.content()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("indomio search failed: %s", exc)
+                browser.close()
+                return out
+
+            # Card text filtering: pull anchor + nearby text in one pass.
+            cards = []
+            for m in re.finditer(
+                r'<a[^>]+href="(/en/\d+/?)"[^>]*>(.*?)</a>',
+                html,
+                re.DOTALL | re.IGNORECASE,
+            ):
+                href, inner = m.group(1), m.group(2)
+                clean = re.sub(r"<[^>]+>", " ", inner)
+                clean = re.sub(r"\s+", " ", clean).strip()
+                if matches_location_keywords(clean, keywords):
+                    cards.append((urljoin(BASE, href), clean))
+
+            seen_urls: set[str] = set()
+            for url, card_text in cards:
+                if url in seen_urls:
+                    continue
+                seen_urls.add(url)
+                if len(out) >= self.max_listings:
+                    break
+                lst = self._fetch_detail(page, url, card_text)
+                if lst:
+                    out.append(lst)
+
+            browser.close()
+        return out
+
+    def _fetch_detail(self, page: Any, url: str, card_text: str) -> Listing | None:
+        try:
+            page.goto(url, wait_until="domcontentloaded", timeout=45_000)
+            page.wait_for_timeout(4_000)
+            html = page.content()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("indomio detail %s failed: %s", url, exc)
+            return None
+
+        from bs4 import BeautifulSoup
+
+        soup = BeautifulSoup(html, "lxml")
+        title_el = soup.find(["h1", "h2"])
+        title = title_el.get_text(" ", strip=True) if title_el else card_text[:120]
+
+        body = soup.get_text(" ", strip=True)
+        price = parse_price_eur(_around(body, ["€", "EUR", "Price"]))
+        area = parse_area_m2(_around(body, ["m²", "m2", "Area"]))
+
+        photos = extract_photo_urls(html, base_url=BASE, limit=8)
+
+        m = re.search(r"/(\d+)/?$", url)
+        listing_id = m.group(1) if m else url
+
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            description=(card_text + " " + body)[:3000],
+            photos=photos,
+            location=self.location,
+        )
+
+
+def _around(text: str, anchors: list[str], window: int = 80) -> str:
+    low = text.lower()
+    for a in anchors:
+        i = low.find(a.lower())
+        if i >= 0:
+            return text[max(0, i - window) : i + window]
+    return text[:300]
diff --git a/serbian_realestate/scrapers/kredium.py b/serbian_realestate/scrapers/kredium.py
new file mode 100644
index 0000000..d042a6b
--- /dev/null
+++ b/serbian_realestate/scrapers/kredium.py
@@ -0,0 +1,115 @@
+"""kredium.rs scraper — plain HTTP, section-scoped parsing.
+
+Whole-body parsing pollutes via the related-listings carousel — every listing
+ends up tagged as "the wrong building." Scope to the <section> containing
+"Informacije" / "Opis" / "Description" headings.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup, Tag
+
+from .base import HttpClient, Listing, Scraper, parse_area_m2, parse_price_eur
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://kredium.rs"
+
+DETAIL_HREF_RE = re.compile(
+    r'href="(/(?:en/)?(?:property|search/property|nekretnina)/[^"#?]+)"',
+    re.IGNORECASE,
+)
+
+SECTION_HEADINGS = re.compile(
+    r"(?:Informacije|Description|Opis|Detalji|Karakteristike)",
+    re.IGNORECASE,
+)
+
+
+class KrediumScraper(Scraper):
+    name = "kredium"
+
+    def fetch(self) -> list[Listing]:
+        search_url = self.profile.get("kredium_search")
+        if not search_url:
+            logger.info("kredium: no search URL in profile, skipping")
+            return []
+
+        html = self.http.get(search_url, use_cache=False)
+        if not html:
+            return []
+
+        seen: set[str] = set()
+        urls: list[str] = []
+        for m in DETAIL_HREF_RE.finditer(html):
+            full = urljoin(BASE, m.group(1))
+            if full in seen:
+                continue
+            seen.add(full)
+            urls.append(full)
+
+        out: list[Listing] = []
+        for u in urls:
+            if len(out) >= self.max_listings:
+                break
+            lst = self._parse_detail(u)
+            if lst:
+                out.append(lst)
+        return out
+
+    def _parse_detail(self, url: str) -> Listing | None:
+        html = self.http.get(url, use_cache=True)
+        if not html:
+            return None
+        soup = BeautifulSoup(html, "lxml")
+
+        title_el = soup.find(["h1", "h2"])
+        title = title_el.get_text(" ", strip=True) if title_el else ""
+
+        # Find the *primary* section: a section/main/article whose text contains
+        # one of the headings AND not "Slične nekretnine" / "Similar listings".
+        primary: Tag | None = None
+        for cand in soup.find_all(["section", "main", "article", "div"]):
+            txt = cand.get_text(" ", strip=True)
+            if not SECTION_HEADINGS.search(txt):
+                continue
+            if re.search(r"slične|sli[čc]ne|similar|preporu", txt, re.IGNORECASE):
+                # Skip the related-listings block.
+                continue
+            primary = cand
+            break
+        scope_text = primary.get_text(" ", strip=True) if primary else soup.get_text(" ", strip=True)[:3000]
+
+        price = parse_price_eur(_around(scope_text, ["€", "EUR", "Cena", "Price"]))
+        area = parse_area_m2(_around(scope_text, ["m²", "m2", "Kvadratura", "Area"]))
+
+        photos = extract_photo_urls(html, base_url=BASE, limit=8)
+
+        m = re.search(r"/([^/?#]+)/?$", url)
+        listing_id = m.group(1) if m else url
+
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            description=scope_text[:3000],
+            photos=photos,
+            location=self.location,
+        )
+
+
+def _around(text: str, anchors: list[str], window: int = 80) -> str:
+    low = text.lower()
+    for a in anchors:
+        i = low.find(a.lower())
+        if i >= 0:
+            return text[max(0, i - window) : i + window]
+    return text[:300]
diff --git a/serbian_realestate/scrapers/nekretnine.py b/serbian_realestate/scrapers/nekretnine.py
new file mode 100644
index 0000000..091590e
--- /dev/null
+++ b/serbian_realestate/scrapers/nekretnine.py
@@ -0,0 +1,124 @@
+"""nekretnine.rs scraper — plain HTTP, paginated.
+
+The site's location filter is loose and bleeds non-target listings, so we
+post-filter detail URLs with `location_keywords` from the profile. We also
+strip sale listings (`item_category=Prodaja`) which leak into rental searches.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from .base import (
+    HttpClient,
+    Listing,
+    Scraper,
+    matches_location_keywords,
+    parse_area_m2,
+    parse_price_eur,
+)
+from .photos import extract_photo_urls
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.nekretnine.rs"
+MAX_PAGES = 5
+
+DETAIL_HREF_RE = re.compile(
+    r'href="(/stambeni-objekti/stanovi/[^"#?]+/\d+/?)"', re.IGNORECASE
+)
+
+
+class NekretnineScraper(Scraper):
+    name = "nekretnine"
+
+    def fetch(self) -> list[Listing]:
+        search_url = self.profile.get("nekretnine_search")
+        if not search_url:
+            logger.info("nekretnine: no search URL in profile, skipping")
+            return []
+
+        out: list[Listing] = []
+        keywords = self.profile.get("location_keywords") or [self.location]
+        seen: set[str] = set()
+
+        for page in range(1, MAX_PAGES + 1):
+            url = search_url if page == 1 else f"{search_url}stranica/{page}/"
+            html = self.http.get(url, use_cache=False)
+            if not html:
+                break
+
+            urls = []
+            for m in DETAIL_HREF_RE.finditer(html):
+                href = m.group(1)
+                if "prodaja" in href.lower():
+                    continue
+                full = urljoin(BASE, href)
+                if full in seen:
+                    continue
+                seen.add(full)
+                # Loose-filter via keywords — the slug usually carries the location.
+                if not matches_location_keywords(href, keywords):
+                    continue
+                urls.append(full)
+
+            if not urls:
+                # No matches on this page — try one more in case of mid-page match
+                continue
+            for detail_url in urls:
+                if len(out) >= self.max_listings:
+                    return out
+                lst = self._parse_detail(detail_url)
+                if lst:
+                    out.append(lst)
+        return out
+
+    def _parse_detail(self, url: str) -> Listing | None:
+        html = self.http.get(url, use_cache=True)
+        if not html:
+            return None
+
+        # Hard-skip sale listings via inline JSON markers.
+        if "item_category" in html and "Prodaja" in html and "Izdavanje" not in html:
+            return None
+
+        soup = BeautifulSoup(html, "lxml")
+        title_el = soup.find(["h1", "h2"])
+        title = title_el.get_text(" ", strip=True) if title_el else ""
+
+        body_text = soup.get_text(" ", strip=True)
+        price = parse_price_eur(_around(body_text, ["€", "EUR", "Cena"]))
+        area = parse_area_m2(_around(body_text, ["m²", "m2", "Kvadratura", "Površina"]))
+
+        desc_el = soup.find(attrs={"class": re.compile(r"description|opis", re.IGNORECASE)})
+        description = desc_el.get_text(" ", strip=True) if desc_el else body_text[:2000]
+
+        photos = extract_photo_urls(html, base_url=BASE, limit=8)
+
+        m = re.search(r"/(\d+)/?$", url)
+        listing_id = m.group(1) if m else url
+
+        return Listing(
+            source=self.name,
+            listing_id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            description=description,
+            photos=photos,
+            location=self.location,
+        )
+
+
+def _around(text: str, anchors: list[str], window: int = 80) -> str:
+    low = text.lower()
+    for a in anchors:
+        i = low.find(a.lower())
+        if i >= 0:
+            return text[max(0, i - window) : i + window]
+    return text[:300]
diff --git a/serbian_realestate/scrapers/photos.py b/serbian_realestate/scrapers/photos.py
new file mode 100644
index 0000000..56ba333
--- /dev/null
+++ b/serbian_realestate/scrapers/photos.py
@@ -0,0 +1,70 @@
+"""Generic photo URL extraction utilities."""
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+# Image extensions we consider "photos." Skip svg / favicons / sprites.
+IMG_EXT = re.compile(r"\.(jpe?g|png|webp)(\?|$)", re.IGNORECASE)
+
+# Banner / app-store / sprite patterns we should *not* treat as listing photos.
+EXCLUDE_PATTERNS = re.compile(
+    r"(logo|sprite|placeholder|favicon|apple-touch|app-store|google-play|"
+    r"banner-mobile|halooglasi-app|share-fb|share-tw)",
+    re.IGNORECASE,
+)
+
+
+def extract_photo_urls(html: str, base_url: str = "", limit: int = 12) -> list[str]:
+    """Greedy extract `<img src=...>` and `<meta property="og:image">` candidates."""
+    urls: list[str] = []
+
+    for m in re.finditer(
+        r'<meta[^>]+property=["\']og:image(?::secure_url)?["\'][^>]+content=["\']([^"\']+)["\']',
+        html,
+        re.IGNORECASE,
+    ):
+        urls.append(m.group(1))
+
+    for m in re.finditer(
+        r'<img[^>]+(?:src|data-src|data-lazy-src|data-original)=["\']([^"\']+)["\']',
+        html,
+        re.IGNORECASE,
+    ):
+        urls.append(m.group(1))
+
+    # Pull JSON-style "photos":["..."] or "image":"..."
+    for m in re.finditer(r'"(?:image|photo|photos|images)"\s*:\s*"([^"]+)"', html):
+        urls.append(m.group(1))
+    for m in re.finditer(
+        r'"(?:images|photos)"\s*:\s*\[([^\]]+)\]', html
+    ):
+        for s in re.findall(r'"([^"]+)"', m.group(1)):
+            urls.append(s)
+
+    return _normalize(urls, base_url, limit)
+
+
+def _normalize(urls: Iterable[str], base_url: str, limit: int) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for u in urls:
+        if not u:
+            continue
+        if u.startswith("//"):
+            u = "https:" + u
+        elif u.startswith("/") and base_url:
+            u = base_url.rstrip("/") + u
+        if not (u.startswith("http://") or u.startswith("https://")):
+            continue
+        if not IMG_EXT.search(u):
+            continue
+        if EXCLUDE_PATTERNS.search(u):
+            continue
+        if u in seen:
+            continue
+        seen.add(u)
+        out.append(u)
+        if len(out) >= limit:
+            break
+    return out
diff --git a/serbian_realestate/scrapers/river_check.py b/serbian_realestate/scrapers/river_check.py
new file mode 100644
index 0000000..cbe10f5
--- /dev/null
+++ b/serbian_realestate/scrapers/river_check.py
@@ -0,0 +1,228 @@
+"""River-view verification using Anthropic Sonnet vision.
+
+Uses `claude-sonnet-4-6` — Haiku 4.5 was too generous, calling distant grey
+strips of water "rivers." Strict prompt requires water to occupy a *meaningful
+portion* of the frame.
+
+Verdicts:
+- yes-direct : direct view of a river / Sava / Danube taking up real frame area
+- partial    : water visible but distant, partial, or ambiguous
+- indoor     : indoor / floorplan / room shots
+- no         : no water visible
+- error      : photo failed to load
+"""
+from __future__ import annotations
+
+import base64
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any
+
+import httpx
+
+from .base import Listing
+
+logger = logging.getLogger(__name__)
+
+VISION_MODEL = "claude-sonnet-4-6"
+MAX_CONCURRENT_LISTINGS = 4
+DEFAULT_MAX_PHOTOS = 3
+
+SYSTEM_PROMPT = (
+    "You are a strict visual verifier for real-estate listings in Belgrade, Serbia. "
+    "You determine whether a photo shows a DIRECT view of a river or large body of "
+    "water (Sava, Danube, Ada Ciganlija lake). Be strict: water must occupy a "
+    "meaningful portion of the frame, not a distant grey strip on the horizon. "
+    "Reply with one verdict word ONLY, on the first line:\n"
+    "  yes-direct  — clear, prominent water view from a window/balcony\n"
+    "  partial     — water visible but distant, edge-of-frame, or tiny\n"
+    "  indoor      — interior / floorplan / no outdoor view\n"
+    "  no          — outdoor but no water\n"
+    "Then, optionally, ONE short sentence of evidence."
+)
+
+USER_PROMPT = (
+    "Classify this listing photo. Reply with verdict word + one short sentence."
+)
+
+VALID_VERDICTS = {"yes-direct", "partial", "indoor", "no"}
+
+
+class _AnthropicClient:
+    def __init__(self) -> None:
+        from anthropic import Anthropic
+
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "ANTHROPIC_API_KEY is required for --verify-river. Set it in your env."
+            )
+        self.client = Anthropic(api_key=api_key)
+        self._http = httpx.Client(timeout=30.0, follow_redirects=True)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _fetch_image(self, url: str) -> tuple[str, str] | None:
+        """Download + base64-encode. Anthropic's URL-mode 400s on some CDNs
+        (4zida resizer, kredium .webp). Inline base64 always works."""
+        try:
+            r = self._http.get(url)
+            r.raise_for_status()
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("vision: failed to fetch %s: %s", url, exc)
+            return None
+        ct = (r.headers.get("content-type") or "").split(";")[0].strip().lower()
+        if not ct.startswith("image/"):
+            # Guess from URL extension
+            lower = url.lower()
+            if ".jpg" in lower or ".jpeg" in lower:
+                ct = "image/jpeg"
+            elif ".png" in lower:
+                ct = "image/png"
+            elif ".webp" in lower:
+                ct = "image/webp"
+            else:
+                return None
+        if ct == "image/jpg":
+            ct = "image/jpeg"
+        b64 = base64.standard_b64encode(r.content).decode("ascii")
+        return ct, b64
+
+    def classify(self, url: str) -> dict[str, Any]:
+        fetched = self._fetch_image(url)
+        if not fetched:
+            return {"url": url, "verdict": "error", "evidence": "fetch failed"}
+        media_type, data = fetched
+
+        try:
+            resp = self.client.messages.create(
+                model=VISION_MODEL,
+                max_tokens=120,
+                system=[
+                    {
+                        "type": "text",
+                        "text": SYSTEM_PROMPT,
+                        "cache_control": {"type": "ephemeral"},
+                    }
+                ],
+                messages=[
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "image",
+                                "source": {
+                                    "type": "base64",
+                                    "media_type": media_type,
+                                    "data": data,
+                                },
+                            },
+                            {"type": "text", "text": USER_PROMPT},
+                        ],
+                    }
+                ],
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("vision: classify failed %s: %s", url, exc)
+            return {"url": url, "verdict": "error", "evidence": str(exc)[:200]}
+
+        text = ""
+        for block in resp.content:
+            if getattr(block, "type", "") == "text":
+                text = (getattr(block, "text", "") or "").strip()
+                break
+
+        first = text.split()[0].strip(":,.").lower() if text else ""
+        # Normalize legacy "yes-distant" → coerce to "no" per spec.
+        if first == "yes-distant":
+            first = "no"
+        verdict = first if first in VALID_VERDICTS else "no"
+        return {"url": url, "verdict": verdict, "evidence": text[:300]}
+
+
+def verify_listings(
+    listings: list[Listing],
+    *,
+    max_photos: int = DEFAULT_MAX_PHOTOS,
+    cache: dict[str, Any] | None = None,
+) -> None:
+    """Mutate listings in place with `river_photo_evidence` populated.
+
+    `cache` is a `{listing_key_str: prior_evidence}` map keyed by `source:listing_id`.
+    Cached evidence is reused only when:
+      - same description text
+      - same photo URLs (order-insensitive)
+      - no prior `verdict == "error"`
+      - prior evidence used the current VISION_MODEL
+    """
+    targets: list[Listing] = []
+    for lst in listings:
+        if cache is not None and _can_reuse_cache(lst, cache.get(_lkey(lst))):
+            cached = cache[_lkey(lst)]
+            lst.river_photo_evidence = list(cached.get("photos", []))
+            continue
+        targets.append(lst)
+
+    if not targets:
+        return
+
+    client = _AnthropicClient()
+    try:
+        with ThreadPoolExecutor(max_workers=MAX_CONCURRENT_LISTINGS) as pool:
+            future_to_listing = {}
+            for lst in targets:
+                photos = lst.photos[:max_photos]
+                future_to_listing[pool.submit(_classify_photos, client, photos)] = lst
+
+            for fut in as_completed(future_to_listing):
+                lst = future_to_listing[fut]
+                try:
+                    lst.river_photo_evidence = fut.result()
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("vision: %s/%s failed: %s", lst.source, lst.listing_id, exc)
+                    lst.river_photo_evidence = []
+    finally:
+        client.close()
+
+    if cache is not None:
+        for lst in targets:
+            cache[_lkey(lst)] = {
+                "model": VISION_MODEL,
+                "description": lst.description,
+                "photos_input": list(lst.photos[:max_photos]),
+                "photos": list(lst.river_photo_evidence),
+            }
+
+
+def _classify_photos(client: _AnthropicClient, photos: list[str]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for url in photos:
+        try:
+            out.append(client.classify(url))
+        except Exception as exc:  # noqa: BLE001
+            # One bad URL must never poison the listing.
+            out.append({"url": url, "verdict": "error", "evidence": str(exc)[:200]})
+    return out
+
+
+def _lkey(lst: Listing) -> str:
+    return f"{lst.source}:{lst.listing_id}"
+
+
+def _can_reuse_cache(lst: Listing, prior: dict[str, Any] | None) -> bool:
+    if not prior:
+        return False
+    if prior.get("model") != VISION_MODEL:
+        return False
+    if prior.get("description") != lst.description:
+        return False
+    prior_photos = set(prior.get("photos_input") or [])
+    if prior_photos != set(lst.photos[:DEFAULT_MAX_PHOTOS]):
+        # Only reuse when we'd be sending the exact same image set.
+        # Strict — if the listing changed photos, re-verify.
+        return False
+    if any(p.get("verdict") == "error" for p in prior.get("photos", [])):
+        return False
+    return True
diff --git a/serbian_realestate/search.py b/serbian_realestate/search.py
new file mode 100644
index 0000000..4210ca5
--- /dev/null
+++ b/serbian_realestate/search.py
@@ -0,0 +1,308 @@
+"""Serbian real-estate scraper CLI.
+
+Run as:
+  uv run --directory serbian_realestate python search.py \\
+    --location beograd-na-vodi --min-m2 70 --max-price 1600 \\
+    --view any --sites 4zida,nekretnine,kredium,halooglasi,cityexpert,indomio \\
+    --verify-river --output markdown
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from filters import (
+    combined_river_verdict,
+    matches_filters,
+    passes_view_filter,
+    text_river_evidence,
+)
+from scrapers.base import HttpClient, Listing, dedupe_listings
+from scrapers.cityexpert import CityExpertScraper
+from scrapers.fzida import FzidaScraper
+from scrapers.halooglasi import HaloOglasiScraper
+from scrapers.indomio import IndomioScraper
+from scrapers.kredium import KrediumScraper
+from scrapers.nekretnine import NekretnineScraper
+
+PKG_DIR = Path(__file__).resolve().parent
+STATE_DIR = PKG_DIR / "state"
+CACHE_DIR = STATE_DIR / "cache"
+BROWSER_DIR = STATE_DIR / "browser"
+
+SCRAPERS = {
+    "4zida": FzidaScraper,
+    "nekretnine": NekretnineScraper,
+    "kredium": KrediumScraper,
+    "cityexpert": CityExpertScraper,
+    "indomio": IndomioScraper,
+    "halooglasi": HaloOglasiScraper,
+}
+
+logger = logging.getLogger("serbian_realestate")
+
+
+# ----------------------------- CLI / orchestration ----------------------------- #
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Serbian real-estate scraper")
+    p.add_argument("--location", default="beograd-na-vodi", help="profile slug from config.yaml")
+    p.add_argument("--min-m2", type=float, default=None)
+    p.add_argument("--max-price", type=float, default=None, help="max monthly EUR")
+    p.add_argument("--view", choices=["any", "river"], default="any")
+    p.add_argument(
+        "--sites",
+        default=",".join(SCRAPERS.keys()),
+        help="comma-separated portals to use",
+    )
+    p.add_argument("--verify-river", action="store_true", help="run Sonnet vision verification")
+    p.add_argument("--verify-max-photos", type=int, default=3)
+    p.add_argument("--output", choices=["markdown", "json", "csv"], default="markdown")
+    p.add_argument("--max-listings", type=int, default=30, help="cap per-site")
+    p.add_argument("--config", default=str(PKG_DIR / "config.yaml"))
+    p.add_argument("--log-level", default="INFO")
+    p.add_argument(
+        "--no-headless",
+        action="store_true",
+        help="run browser-based scrapers in headed mode (debug)",
+    )
+    return p.parse_args(argv)
+
+
+def load_profile(config_path: Path, location: str) -> dict[str, Any]:
+    with open(config_path, "r", encoding="utf-8") as f:
+        cfg = yaml.safe_load(f) or {}
+    profiles = cfg.get("profiles") or {}
+    profile = profiles.get(location)
+    if not profile:
+        raise SystemExit(
+            f"unknown location '{location}'. Known: {sorted(profiles)}"
+        )
+    return profile
+
+
+def state_paths(location: str) -> tuple[Path, Path]:
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    last_run = STATE_DIR / f"last_run_{location}.json"
+    return last_run, BROWSER_DIR / "halooglasi_chrome_profile"
+
+
+def load_state(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"listings": [], "vision_cache": {}}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"listings": [], "vision_cache": {}}
+
+
+def save_state(path: Path, listings: list[Listing], vision_cache: dict[str, Any], settings: dict[str, Any]) -> None:
+    payload = {
+        "settings": settings,
+        "listings": [lst.to_dict() for lst in listings],
+        "vision_cache": vision_cache,
+    }
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def diff_new(prior_listings: list[dict[str, Any]], current: list[Listing]) -> None:
+    """Mark `is_new=True` on listings whose (source, id) was not in prior state."""
+    prior_keys = {(p.get("source"), p.get("listing_id")) for p in prior_listings}
+    for lst in current:
+        if lst.key() not in prior_keys:
+            lst.is_new = True
+
+
+# ----------------------------- pipeline ----------------------------- #
+
+
+def run_scrapers(
+    sites: list[str],
+    location: str,
+    profile: dict[str, Any],
+    max_listings: int,
+    headless: bool,
+) -> list[Listing]:
+    http = HttpClient(cache_dir=CACHE_DIR)
+    halo_profile = BROWSER_DIR / "halooglasi_chrome_profile"
+
+    listings: list[Listing] = []
+    try:
+        for site in sites:
+            cls = SCRAPERS.get(site)
+            if not cls:
+                logger.warning("unknown site %s, skipping", site)
+                continue
+            logger.info("scraping %s ...", site)
+            try:
+                if cls is HaloOglasiScraper:
+                    scraper = cls(
+                        location,
+                        profile,
+                        http,
+                        max_listings=max_listings,
+                        profile_dir=halo_profile,
+                        headless=headless,
+                    )
+                else:
+                    scraper = cls(location, profile, http, max_listings=max_listings)
+                got = scraper.fetch()
+                logger.info("  %s: %d listings", site, len(got))
+                listings.extend(got)
+            except Exception as exc:  # noqa: BLE001
+                logger.exception("scraper %s crashed: %s", site, exc)
+    finally:
+        http.close()
+    return dedupe_listings(listings)
+
+
+def annotate_river(
+    listings: list[Listing], verify_photos: bool, max_photos: int, vision_cache: dict[str, Any]
+) -> None:
+    # Text-pattern step is always cheap.
+    for lst in listings:
+        matched, evidence = text_river_evidence(lst.title, lst.description)
+        lst.river_text_match = matched
+        lst.river_text_evidence = evidence
+
+    if verify_photos:
+        from scrapers.river_check import verify_listings
+
+        try:
+            verify_listings(listings, max_photos=max_photos, cache=vision_cache)
+        except RuntimeError as exc:
+            logger.error("vision skipped: %s", exc)
+
+    for lst in listings:
+        verdicts = [p.get("verdict", "") for p in lst.river_photo_evidence]
+        lst.river_verdict = combined_river_verdict(
+            text_match=lst.river_text_match, photo_verdicts=verdicts
+        )
+
+
+# ----------------------------- output ----------------------------- #
+
+
+def render(listings: list[Listing], fmt: str) -> str:
+    if fmt == "json":
+        return json.dumps([lst.to_dict() for lst in listings], indent=2, ensure_ascii=False)
+    if fmt == "csv":
+        buf = io.StringIO()
+        writer = csv.writer(buf)
+        writer.writerow(
+            [
+                "is_new",
+                "source",
+                "listing_id",
+                "title",
+                "price_eur",
+                "area_m2",
+                "river_verdict",
+                "url",
+            ]
+        )
+        for lst in listings:
+            writer.writerow(
+                [
+                    "1" if lst.is_new else "0",
+                    lst.source,
+                    lst.listing_id,
+                    lst.title,
+                    lst.price_eur or "",
+                    lst.area_m2 or "",
+                    lst.river_verdict,
+                    lst.url,
+                ]
+            )
+        return buf.getvalue()
+    # markdown
+    lines = ["| New | Source | Title | Price € | m² | River | URL |", "|-|-|-|-|-|-|-|"]
+    for lst in listings:
+        new = "🆕" if lst.is_new else ""
+        verdict = lst.river_verdict
+        if verdict == "text+photo":
+            verdict = "⭐ text+photo"
+        title = (lst.title or "(untitled)").replace("|", "/")[:80]
+        price = f"{lst.price_eur:.0f}" if lst.price_eur else "?"
+        area = f"{lst.area_m2:.0f}" if lst.area_m2 else "?"
+        lines.append(
+            f"| {new} | {lst.source} | {title} | {price} | {area} | {verdict} | {lst.url} |"
+        )
+    return "\n".join(lines)
+
+
+# ----------------------------- entry ----------------------------- #
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(
+        level=getattr(logging, args.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s :: %(message)s",
+    )
+
+    profile = load_profile(Path(args.config), args.location)
+    sites = [s.strip() for s in args.sites.split(",") if s.strip()]
+    last_run_path, _ = state_paths(args.location)
+    state = load_state(last_run_path)
+
+    listings = run_scrapers(
+        sites, args.location, profile, args.max_listings, headless=not args.no_headless
+    )
+
+    # Apply lenient filter (keeps missing-value listings).
+    filtered = [
+        lst
+        for lst in listings
+        if matches_filters(
+            price_eur=lst.price_eur,
+            area_m2=lst.area_m2,
+            min_m2=args.min_m2,
+            max_price=args.max_price,
+            listing_id=f"{lst.source}:{lst.listing_id}",
+        )
+    ]
+    logger.info("after filter: %d / %d listings", len(filtered), len(listings))
+
+    annotate_river(
+        filtered,
+        verify_photos=args.verify_river,
+        max_photos=args.verify_max_photos,
+        vision_cache=state.get("vision_cache") or {},
+    )
+
+    # View filter (river / any) applied AFTER annotation.
+    viewed = [lst for lst in filtered if passes_view_filter(lst.river_verdict, args.view)]
+
+    diff_new(state.get("listings") or [], viewed)
+
+    save_state(
+        last_run_path,
+        viewed,
+        state.get("vision_cache") or {},
+        settings={
+            "location": args.location,
+            "min_m2": args.min_m2,
+            "max_price": args.max_price,
+            "sites": sites,
+            "view": args.view,
+            "verify_river": args.verify_river,
+        },
+    )
+
+    sys.stdout.write(render(viewed, args.output))
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

No project-specific instructions.

diff --git a/plan.md b/plan.md
new file mode 100644
index 0000000..4e14df7
--- /dev/null
+++ b/plan.md
@@ -0,0 +1,237 @@
+# Serbian Real-Estate Scraper — Build Plan
+
+Status: implemented (live in `agent_tools/serbian_realestate/`).
+This document is the design spec to rebuild from scratch if needed.
+
+## 1. Goal
+
+Daily-runnable monitor of Serbian rental classifieds, filtered to user-defined criteria (location + min m² + max price). Outputs a deduped table with vision-verified river-view detection. Costs <$1/day in API tokens.
+
+## 2. Architecture
+
+Single Python package under `agent_tools/serbian_realestate/`, `uv`-managed.
+
+```
+agent_tools/serbian_realestate/
+├── pyproject.toml          # uv-managed: httpx, beautifulsoup4, undetected-chromedriver,
+│                           # playwright, playwright-stealth, anthropic, pyyaml, rich
+├── README.md
+├── search.py               # CLI entrypoint
+├── config.yaml             # Filter profiles (BW, Vracar, etc.)
+├── filters.py              # Match criteria + river-view text patterns
+├── scrapers/
+│   ├── base.py             # Listing dataclass, HttpClient, Scraper base, helpers
+│   ├── photos.py           # Generic photo URL extraction
+│   ├── river_check.py      # Sonnet vision verification + base64 fallback
+│   ├── fzida.py            # 4zida.rs            — plain HTTP
+│   ├── nekretnine.py       # nekretnine.rs       — plain HTTP, paginated
+│   ├── kredium.py          # kredium.rs          — plain HTTP
+│   ├── cityexpert.py       # cityexpert.rs       — Playwright (CF)
+│   ├── indomio.py          # indomio.rs          — Playwright (Distil)
+│   └── halooglasi.py       # halooglasi.com      — Selenium + undetected-chromedriver (CF)
+└── state/
+    ├── last_run_{location}.json    # Diff state + cached river evidence
+    ├── cache/                       # HTML cache by source
+    └── browser/                     # Persistent browser profiles for CF sites
+        └── halooglasi_chrome_profile/
+```
+
+## 3. Per-site implementation method
+
+| Site | Method | Reason |
+|---|---|---|
+| 4zida | plain HTTP | List page is JS-rendered but detail URLs are server-side; detail pages are server-rendered |
+| nekretnine.rs | plain HTTP, paginated | Loose location filter — must keyword-filter URLs post-fetch |
+| kredium | plain HTTP, section-scoped parsing | Whole-body parsing pollutes via related-listings carousel |
+| cityexpert | Playwright | CF-protected; URL is `/en/properties-for-rent/belgrade?ptId=1&currentPage=N` |
+| indomio | Playwright | Distil bot challenge; per-municipality URL `/en/to-rent/flats/belgrade-savski-venac` |
+| **halooglasi** | **Selenium + undetected-chromedriver** | Cloudflare aggressive — Playwright capped at 25-30%, uc gets ~100% |
+
+## 4. Critical lessons learned (these bit us during build)
+
+### 4.1 Halo Oglasi (the hardest site)
+
+- **Cannot use Playwright** — Cloudflare challenges every detail page; extraction plateaus at 25-30% even with `playwright-stealth`, persistent storage, reload-on-miss
+- **Use `undetected-chromedriver`** with real Google Chrome (not Chromium)
+- **`page_load_strategy="eager"`** — without it `driver.get()` hangs indefinitely on CF challenge pages (window load event never fires)
+- **Pass Chrome major version explicitly** to `uc.Chrome(version_main=N)` — auto-detect ships chromedriver too new for installed Chrome (Chrome 147 + chromedriver 148 = `SessionNotCreated`)
+- **Persistent profile dir** at `state/browser/halooglasi_chrome_profile/` keeps CF clearance cookies between runs
+- **`time.sleep(8)` then poll** — CF challenge JS blocks the main thread, so `wait_for_function`-style polling can't run during it. Hard sleep, then check.
+- **Read structured data, not regex body text** — Halo Oglasi exposes `window.QuidditaEnvironment.CurrentClassified.OtherFields` with fields:
+  - `cena_d` (price EUR)
+  - `cena_d_unit_s` (must be `"EUR"`)
+  - `kvadratura_d` (m²)
+  - `sprat_s`, `sprat_od_s` (floor / total floors)
+  - `broj_soba_s` (rooms)
+  - `tip_nekretnine_s` (`"Stan"` for residential)
+- **Headless `--headless=new` works** on cold profile; if rate drops, fall back to xvfb headed mode (`sudo apt install xvfb && xvfb-run -a uv run ...`)
+
+### 4.2 nekretnine.rs
+
+- Location filter is **loose** — bleeds non-target listings. Keyword-filter URLs post-fetch using `location_keywords` from config
+- **Skip sale listings** with `item_category=Prodaja` — rental search bleeds sales via shared infrastructure
+- Pagination via `?page=N`, walk up to 5 pages
+
+### 4.3 kredium
+
+- **Section-scoped parsing only** — using full body text pollutes via related-listings carousel (every listing tags as the wrong building)
+- Scope to `<section>` containing "Informacije" / "Opis" headings
+
+### 4.4 4zida
+
+- List page is JS-rendered but **detail URLs are present in HTML** as `href` attributes — extract via regex
+- Detail pages are server-rendered, no JS gymnastics needed
+
+### 4.5 cityexpert
+
+- Wrong URL pattern (`/en/r/belgrade/belgrade-waterfront`) returns 404
+- **Right URL**: `/en/properties-for-rent/belgrade?ptId=1` (apartments only)
+- Pagination via `?currentPage=N` (NOT `?page=N`)
+- Bumped MAX_PAGES to 10 because BW listings are sparse (~1 per 5 pages)
+
+### 4.6 indomio
+
+- SPA with Distil bot challenge
+- Detail URLs have **no descriptive slug** — just `/en/{numeric-ID}`
+- **Card-text filter** instead of URL-keyword filter (cards have "Belgrade, Savski Venac: Dedinje" in text)
+- Server-side filter params don't work; only municipality URL slug filters
+- 8s SPA hydration wait before card collection
+
+## 5. River-view verification (two-signal AND)
+
+### 5.1 Text patterns (`filters.py`)
+
+Required Serbian phrasings (case-insensitive):
+- `pogled na (reku|reci|reke|Savu|Savi|Save)`
+- `pogled na (Adu|Ada Ciganlij)` (Ada Ciganlija lake)
+- `pogled na (Dunav|Dunavu)` (Danube)
+- `prvi red (do|uz|na) (reku|Save|...)`
+- `(uz|pored|na obali) (reku|reci|reke|Save|Savu|Savi)`
+- `okrenut .{0,30} (reci|reke|Save|...)`
+- `panoramski pogled .{0,60} (reku|Save|river|Sava)`
+
+**Do NOT match:**
+- bare `reka` / `reku` (too generic, used in non-view contexts)
+- bare `Sava` (street name "Savska" appears in every BW address)
+- `waterfront` (matches the complex name "Belgrade Waterfront" — false positive on every BW listing)
+
+### 5.2 Photo verification (`scrapers/river_check.py`)
+
+- **Model**: `claude-sonnet-4-6`
+  - Haiku 4.5 was too generous, calling distant grey strips "rivers"
+- **Strict prompt**: water must occupy meaningful portion of frame, not distant sliver
+- **Verdicts**: only `yes-direct` counts as positive
+  - `yes-distant` deliberately removed (legacy responses coerced to `no`)
+  - `partial`, `indoor`, `no` are non-positive
+- **Inline base64 fallback** — Anthropic's URL-mode image fetcher 400s on some CDNs (4zida resizer, kredium .webp). Download locally with httpx, base64-encode, send inline.
+- **System prompt cached** with `cache_control: ephemeral` for cross-call savings
+- **Concurrent up to 4 listings**, max 3 photos per listing
+- **Per-photo errors** caught — single bad URL doesn't poison the listing
+
+### 5.3 Combined verdict
+
+```
+text matched + any photo yes-direct → "text+photo" ⭐
+text matched only                    → "text-only"
+photo yes-direct only                → "photo-only"
+photo partial only                   → "partial"
+nothing                              → "none"
+```
+
+For strict `--view river` filter: only `text+photo`, `text-only`, `photo-only` pass.
+
+## 6. State + diffing
+
+- Per-location state file: `state/last_run_{location}.json`
+- Stores: `settings`, `listings[]` with `is_new` flag
+- On next run: compare by `(source, listing_id)` → flag new ones with 🆕
+
+### 6.1 Vision-cache invalidation
+
+Cached evidence is reused only when ALL true:
+- Same description text
+- Same photo URLs (order-insensitive)
+- No `verdict="error"` in prior photos
+- Prior evidence used the current `VISION_MODEL`
+
+If any of those changes, re-verify. Saves cost on stable listings.
+
+## 7. CLI
+
+```bash
+uv run --directory agent_tools/serbian_realestate python search.py \
+  --location beograd-na-vodi --min-m2 70 --max-price 1600 \
+  --view any \
+  --sites 4zida,nekretnine,kredium,halooglasi,cityexpert,indomio \
+  --verify-river --verify-max-photos 3 \
+  --output markdown
+```
+
+Flags:
+- `--location` — slug (e.g. `beograd-na-vodi`, `savski-venac`)
+- `--min-m2` — minimum floor area
+- `--max-price` — max monthly EUR
+- `--view {any|river}` — `river` filters strictly to verified river views
+- `--sites` — comma-separated portal list
+- `--verify-river` — turn on Sonnet vision verification (requires `ANTHROPIC_API_KEY`)
+- `--verify-max-photos N` — cap photos per listing (default 3)
+- `--output {markdown|json|csv}`
+- `--max-listings N` — cap per-site (default 30)
+
+### 7.1 Lenient filter
+
+Listings with missing m² OR price are **kept with a warning** (logged at WARNING) so the user can review manually. Only filter out when the value is present AND out of range.
+
+## 8. Cost / runtime
+
+- Cold run with vision: ~$0.40 for ~45 listings (~$0.009/listing)
+- Warm run (cache hits): ~$0
+- Daily expected: ~$0.05-0.10 (only new listings need vision)
+- Cold runtime: 5-8 minutes
+- Warm runtime: 1-2 minutes (data fetched fresh, vision cached)
+
+## 9. Daily scheduling (Linux systemd user timer)
+
+```
+~/.config/systemd/user/serbian-realestate.timer
+  [Timer]
+  OnCalendar=*-*-* 08:00
+  Persistent=true   # fire missed runs on next wake
+
+~/.config/systemd/user/serbian-realestate.service
+  [Service]
+  ExecStart=/path/to/uv run --directory /home/dory/ai_will_replace_you/agent_tools/serbian_realestate python search.py --verify-river
+  EnvironmentFile=/home/dory/ai_will_replace_you/agent_tools/webflow_api/.env
+```
+
+## 10. Build order if doing from scratch
+
+1. **Hour 1**: Listing dataclass + base Scraper + 4zida (plain HTTP — easiest, validates pipeline)
+2. **Hour 2**: nekretnine + kredium (more plain HTTP, exercises pagination + post-fetch URL filtering)
+3. **Hour 3**: cityexpert + indomio (Playwright; learn anti-bot basics — these are the easier CF/Distil targets)
+4. **Hour 4**: halooglasi via undetected-chromedriver (the hard one; expect 30-60 min on CF debugging)
+5. **Hour 5**: river-view text patterns + Sonnet vision verification + state diffing
+6. **Hour 6**: CLI polish + smoke tests + README
+
+Total: ~6 hours of focused engineering, or ~$30-60 of agent tokens with sde delegation.
+
+## 11. Project conventions enforced
+
+- All code in `agent_tools/serbian_realestate/`, no other folders touched
+- Use `uv` for everything — runnable as `uv run --directory ... python search.py`
+- Type hints, structured logging, pathlib for paths
+- Docstrings on public functions
+- No tests written by build agents (per project rules)
+- No hardcoded secrets — `ANTHROPIC_API_KEY` from env, fail clearly if missing for `--verify-river`
+- No `--api-key` CLI flags
+- No MCP/LLM calls outside `--verify-river` path
+- Rentals only — no sale listings (skip `item_category=Prodaja`)
+
+## 12. Future improvements (not done yet)
+
+- **Halo Oglasi photo extractor** — currently grabs Halo Oglasi mobile-app banner URLs as "photos." Filter out app-store / banner CDN paths.
+- **camoufox** as alternative for cityexpert/indomio if Distil/CF ever escalates
+- **Indomio English keywords** broadened in keyword set
+- **Sale listings option** behind a flag if useful later
+- **Notification layer** — email or Telegram when a new river-view listing appears
+- **Multi-location support** — run BW + Vracar + Dorcol in one invocation, output per-location reports
diff --git a/serbian_realestate/README.md b/serbian_realestate/README.md
new file mode 100644
index 0000000..9c4d8dc
--- /dev/null
+++ b/serbian_realestate/README.md
@@ -0,0 +1,85 @@
+# Serbian Real-Estate Scraper
+
+Daily-runnable monitor of Serbian rental classifieds (4zida, nekretnine.rs,
+kredium, halooglasi, cityexpert, indomio) with optional Sonnet-vision-verified
+river-view detection.
+
+Built from the spec in `../plan.md`. See that document for design rationale,
+per-site quirks, and the lessons that drove the current architecture.
+
+## Install
+
+```bash
+uv sync --directory serbian_realestate
+# Playwright browsers (only needed if you scrape cityexpert / indomio):
+uv run --directory serbian_realestate python -m playwright install chromium
+```
+
+For halooglasi you also need real Google Chrome on PATH (Chromium is not
+sufficient — Cloudflare detects the difference). The scraper auto-detects
+the installed Chrome major version.
+
+## Usage
+
+```bash
+# any-view scan, no vision
+uv run --directory serbian_realestate python search.py \
+  --location beograd-na-vodi --min-m2 70 --max-price 1600
+
+# strict river-view filter with vision verification
+export ANTHROPIC_API_KEY=sk-ant-...
+uv run --directory serbian_realestate python search.py \
+  --location beograd-na-vodi --min-m2 70 --max-price 1600 \
+  --view river --verify-river
+
+# JSON output for piping into other tools
+uv run --directory serbian_realestate python search.py \
+  --location beograd-na-vodi --output json > today.json
+```
+
+## Profiles
+
+Locations are defined in `config.yaml`. Bundled profiles:
+`beograd-na-vodi`, `savski-venac`, `vracar`. Each profile carries:
+
+- `location_keywords` — used to keyword-filter URLs / card text on
+  loose-search portals (nekretnine, indomio).
+- `cityexpert_part_id`, `indomio_municipality_slug`, `halooglasi_location_id` —
+  per-portal targeting parameters.
+
+## State
+
+Per-location state lives at `state/last_run_<slug>.json`. New listings since
+the last run are flagged 🆕 in the markdown output. Vision evidence is
+cached per listing — re-runs only call Sonnet for new or changed listings
+(see plan.md §6.1 for the cache-invalidation rules).
+
+## Cost
+
+- Cold run with vision: ~$0.40 for ~45 listings
+- Warm run (cache hits): essentially zero
+- Cold runtime: 5-8 minutes; warm runtime: 1-2 minutes
+
+## Conventions
+
+- All paths via `pathlib`. No hardcoded secrets — `ANTHROPIC_API_KEY` is
+  read from env when `--verify-river` is passed; otherwise no LLM calls
+  happen at all.
+- Rentals only. Sale listings are filtered at scrape time
+  (`item_category=Prodaja` on nekretnine, `izdavanje` URL guard on halooglasi).
+- The scraper is tolerant: per-listing failures are logged at WARNING and
+  the run continues.
+
+## CLI flags
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--location` | `beograd-na-vodi` | Profile slug from `config.yaml` |
+| `--min-m2` | (none) | Lenient — listings with missing m² are kept + warned |
+| `--max-price` | (none) | Lenient — listings with missing price are kept + warned |
+| `--view` | `any` | `river` filters strictly to verified river views |
+| `--sites` | all 6 | Comma-separated portal list |
+| `--verify-river` | off | Enable Sonnet vision verification |
+| `--verify-max-photos` | 3 | Cap photos per listing for vision calls |
+| `--output` | `markdown` | `markdown`, `json`, or `csv` |
+| `--max-listings` | 30 | Per-site cap |
diff --git a/serbian_realestate/config.yaml b/serbian_realestate/config.yaml
new file mode 100644
index 0000000..f4cd15d
--- /dev/null
+++ b/serbian_realestate/config.yaml
@@ -0,0 +1,37 @@
+# Filter profiles for the Serbian real-estate scraper.
+# Selected via --location <slug> on the CLI.
+#
+# location_keywords: case-insensitive substrings used to keyword-filter URLs / card text
+#                    on portals with loose location filters (notably nekretnine.rs and indomio).
+
+profiles:
+  beograd-na-vodi:
+    display_name: "Belgrade Waterfront (Beograd na Vodi)"
+    location_keywords:
+      - "beograd-na-vodi"
+      - "beograd na vodi"
+      - "belgrade-waterfront"
+      - "belgrade waterfront"
+      - "bw "
+      - "kula beograd"
+    cityexpert_part_id: 1            # apartments
+    indomio_municipality_slug: "belgrade-savski-venac"
+    halooglasi_location_id: "35112"  # Beograd na Vodi (Savski Venac)
+
+  savski-venac:
+    display_name: "Savski Venac"
+    location_keywords:
+      - "savski-venac"
+      - "savski venac"
+    cityexpert_part_id: 1
+    indomio_municipality_slug: "belgrade-savski-venac"
+    halooglasi_location_id: "35095"
+
+  vracar:
+    display_name: "Vracar"
+    location_keywords:
+      - "vracar"
+      - "vračar"
+    cityexpert_part_id: 1
+    indomio_municipality_slug: "belgrade-vracar"
+    halooglasi_location_id: "35110"
diff --git a/serbian_realestate/filters.py b/serbian_realestate/filters.py
new file mode 100644
index 0000000..6348c3c
--- /dev/null
+++ b/serbian_realestate/filters.py
@@ -0,0 +1,138 @@
+"""Listing filters and river-view text patterns.
+
+Two responsibilities:
+- `passes_criteria` — apply min-m² / max-price filters with the lenient
+  rule from plan.md §7.1 (keep listings with missing values + warn).
+- `text_river_match` — match Serbian river-view phrasings while avoiding
+  false positives on bare "reka" / "Sava" / "waterfront".
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Iterable
+
+from scrapers.base import Listing
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Criteria:
+    min_m2: float | None
+    max_price_eur: float | None
+    location_keywords: tuple[str, ...] = ()
+
+
+# ---------- river-view text patterns --------------------------------------
+#
+# Strict matchers — see plan.md §5.1. We deliberately avoid:
+#   - bare "reka" / "reku" (used non-view: "blizu reke")
+#   - bare "Sava" (street name "Savska" is everywhere in BW addresses)
+#   - "waterfront" (matches the BW complex name → false positive on every BW listing)
+#
+# Flags: re.IGNORECASE | re.DOTALL so phrasings can span newlines / multi-line descriptions.
+
+_RIVER_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
+    re.compile(p, re.IGNORECASE | re.DOTALL)
+    for p in (
+        r"pogled\s+na\s+(reku|reci|reke|savu|savi|save)\b",
+        r"pogled\s+na\s+(adu|ada\s+ciganlij)",
+        r"pogled\s+na\s+(dunav|dunavu)\b",
+        r"prvi\s+red\s+(do|uz|na)\s+(reku|reci|reke|savu|savi|save|dunav)",
+        r"(uz|pored|na\s+obali)\s+(reku|reci|reke|savu|savi|save|dunav)",
+        r"okrenut[a-z]?\s+.{0,30}?(reci|reke|savu|savi|save|dunav)",
+        r"panoramski\s+pogled\s+.{0,60}?(reku|savu|sava|river|dunav)",
+        # English equivalents — Indomio / cityexpert detail pages
+        r"river\s+view",
+        r"view\s+(of\s+)?the\s+(sava|danube)\s+river",
+        r"(sava|danube)\s+river\s+view",
+        r"facing\s+the\s+(river|sava|danube)",
+    )
+)
+
+
+def text_river_match(text: str) -> str | None:
+    """Return the matched phrase, or None if no river-view phrase is present."""
+    if not text:
+        return None
+    for pat in _RIVER_PATTERNS:
+        m = pat.search(text)
+        if m:
+            return m.group(0)
+    return None
+
+
+# ---------- listing-level criteria ----------------------------------------
+
+
+def passes_criteria(listing: Listing, criteria: Criteria) -> bool:
+    """Apply min-m² / max-price / location keyword filters.
+
+    Lenient mode (plan.md §7.1): when a value is missing, we keep the
+    listing and emit a warning so the user can review manually. Filter
+    only when the value is *present and out of range*.
+    """
+    if criteria.min_m2 is not None:
+        if listing.area_m2 is not None and listing.area_m2 < criteria.min_m2:
+            return False
+        if listing.area_m2 is None:
+            logger.warning(
+                "[%s] missing area_m2, keeping for manual review: %s",
+                listing.source,
+                listing.url,
+            )
+
+    if criteria.max_price_eur is not None:
+        if listing.price_eur is not None and listing.price_eur > criteria.max_price_eur:
+            return False
+        if listing.price_eur is None:
+            logger.warning(
+                "[%s] missing price_eur, keeping for manual review: %s",
+                listing.source,
+                listing.url,
+            )
+
+    if criteria.location_keywords:
+        haystack = " ".join(
+            x.lower()
+            for x in (listing.url, listing.title, listing.location or "", listing.description)
+            if x
+        )
+        if not any(k.lower() in haystack for k in criteria.location_keywords):
+            return False
+
+    return True
+
+
+def apply_criteria(listings: Iterable[Listing], criteria: Criteria) -> list[Listing]:
+    return [l for l in listings if passes_criteria(l, criteria)]
+
+
+# ---------- combined river verdict ---------------------------------------
+
+
+def combined_verdict(text_match: str | None, photo_verdicts: list[str]) -> str:
+    """Return one of: text+photo, text-only, photo-only, partial, none.
+
+    `photo_verdicts` are values from river_check.py: yes-direct / partial / no / indoor / error.
+    """
+    has_text = text_match is not None
+    has_yes = any(v == "yes-direct" for v in photo_verdicts)
+    has_partial = any(v == "partial" for v in photo_verdicts)
+    if has_text and has_yes:
+        return "text+photo"
+    if has_text:
+        return "text-only"
+    if has_yes:
+        return "photo-only"
+    if has_partial:
+        return "partial"
+    return "none"
+
+
+def verdict_passes_strict(verdict: str) -> bool:
+    """For --view river: only these verdicts pass."""
+    return verdict in {"text+photo", "text-only", "photo-only"}
diff --git a/serbian_realestate/pyproject.toml b/serbian_realestate/pyproject.toml
new file mode 100644
index 0000000..3705fab
--- /dev/null
+++ b/serbian_realestate/pyproject.toml
@@ -0,0 +1,30 @@
+[project]
+name = "serbian-realestate"
+version = "0.1.0"
+description = "Daily-runnable monitor of Serbian rental classifieds with vision-verified river-view detection."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.0",
+    "undetected-chromedriver>=3.5",
+    "selenium>=4.20",
+    "playwright>=1.45",
+    "playwright-stealth>=1.0.6",
+    "anthropic>=0.40",
+    "pyyaml>=6.0",
+    "rich>=13.7",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["scrapers"]
+include = [
+    "search.py",
+    "filters.py",
+    "config.yaml",
+]
diff --git a/serbian_realestate/scrapers/__init__.py b/serbian_realestate/scrapers/__init__.py
new file mode 100644
index 0000000..4898a85
--- /dev/null
+++ b/serbian_realestate/scrapers/__init__.py
@@ -0,0 +1,6 @@
+"""Scraper plug-ins for the Serbian real-estate monitor.
+
+Each module in this package exposes a `Scraper` subclass that returns
+`Listing` objects for a single portal. New portals should be registered
+in `search.py:SCRAPER_REGISTRY`.
+"""
diff --git a/serbian_realestate/scrapers/_playwright_util.py b/serbian_realestate/scrapers/_playwright_util.py
new file mode 100644
index 0000000..4811a83
--- /dev/null
+++ b/serbian_realestate/scrapers/_playwright_util.py
@@ -0,0 +1,74 @@
+"""Shared Playwright helpers for cityexpert + indomio.
+
+Both portals have JS-only listings and CF/Distil challenges that
+plain httpx can't pass. This module wraps Playwright with stealth
+patches so the two scrapers can share setup/teardown.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from pathlib import Path
+from typing import Iterator
+
+from playwright.sync_api import BrowserContext, Page, sync_playwright
+
+logger = logging.getLogger(__name__)
+
+
+@contextlib.contextmanager
+def stealth_browser(profile_dir: Path, *, headless: bool = True) -> Iterator[BrowserContext]:
+    """Yield a Chromium context with persistent storage + stealth patches.
+
+    Persistent storage at `profile_dir` keeps CF clearance cookies
+    between runs — critical for cityexpert and indomio.
+    """
+    profile_dir.mkdir(parents=True, exist_ok=True)
+    with sync_playwright() as pw:
+        ctx = pw.chromium.launch_persistent_context(
+            user_data_dir=str(profile_dir),
+            headless=headless,
+            viewport={"width": 1366, "height": 900},
+            user_agent=(
+                "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+                "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
+            ),
+            locale="sr-Latn-RS",
+            args=[
+                "--disable-blink-features=AutomationControlled",
+                "--disable-features=IsolateOrigins,site-per-process",
+            ],
+        )
+        # playwright-stealth has different APIs across versions; try the
+        # async/sync helpers in turn and skip silently if neither is present.
+        try:
+            from playwright_stealth import stealth_sync  # type: ignore
+
+            for page in ctx.pages:
+                stealth_sync(page)
+            ctx.on("page", lambda p: stealth_sync(p))
+        except Exception:  # noqa: BLE001
+            try:
+                from playwright_stealth import Stealth  # type: ignore
+
+                Stealth().apply_stealth_sync(ctx)
+            except Exception as exc:  # noqa: BLE001
+                logger.debug("playwright-stealth not applied: %s", exc)
+
+        try:
+            yield ctx
+        finally:
+            with contextlib.suppress(Exception):
+                ctx.close()
+
+
+def safe_goto(page: Page, url: str, *, wait_ms: int = 8000) -> bool:
+    """Navigate and wait briefly for SPA hydration. Return False on failure."""
+    try:
+        page.goto(url, wait_until="domcontentloaded", timeout=45_000)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("goto failed for %s: %s", url, exc)
+        return False
+    page.wait_for_timeout(wait_ms)
+    return True
diff --git a/serbian_realestate/scrapers/base.py b/serbian_realestate/scrapers/base.py
new file mode 100644
index 0000000..32e586a
--- /dev/null
+++ b/serbian_realestate/scrapers/base.py
@@ -0,0 +1,236 @@
+"""Base types and helpers shared by all portal scrapers.
+
+Defines:
+- `Listing`: the canonical dataclass produced by every scraper.
+- `HttpClient`: a thin httpx wrapper with sensible Serbian-portal headers + on-disk caching.
+- `Scraper`: the abstract base class portal modules subclass.
+
+Design notes:
+- `Listing.id` is the portal-local listing id (slug or numeric). The pair
+  `(source, id)` is the global key used for diffing and deduplication.
+- All scrapers must be tolerant of missing fields — many portals omit
+  price or m² in card markup. `None` is preferred over guessing.
+"""
+
+from __future__ import annotations
+
+import abc
+import hashlib
+import json
+import logging
+import re
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+import httpx
+from bs4 import BeautifulSoup
+
+logger = logging.getLogger(__name__)
+
+# Browser-mimic headers for plain-HTTP requests. Serbian portals reject obvious bot UAs;
+# this UA + sec-ch hints + accept-language gets us through 4zida / nekretnine / kredium
+# without challenges.
+DEFAULT_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
+    ),
+    "Accept": (
+        "text/html,application/xhtml+xml,application/xml;q=0.9,"
+        "image/avif,image/webp,*/*;q=0.8"
+    ),
+    "Accept-Language": "sr-Latn,sr;q=0.9,en;q=0.8",
+    "Accept-Encoding": "gzip, deflate, br",
+    "Sec-CH-UA": '"Chromium";v="126", "Not.A/Brand";v="24"',
+    "Sec-CH-UA-Mobile": "?0",
+    "Sec-CH-UA-Platform": '"Linux"',
+    "Sec-Fetch-Dest": "document",
+    "Sec-Fetch-Mode": "navigate",
+    "Sec-Fetch-Site": "none",
+    "Sec-Fetch-User": "?1",
+    "Upgrade-Insecure-Requests": "1",
+}
+
+
+@dataclass
+class Listing:
+    """A single classified listing.
+
+    `extra` carries portal-specific metadata that is useful for downstream
+    consumers (e.g. parsed Halo Oglasi `OtherFields`) but doesn't fit
+    the canonical schema.
+    """
+
+    source: str
+    id: str
+    url: str
+    title: str
+    price_eur: float | None = None
+    area_m2: float | None = None
+    location: str | None = None
+    description: str = ""
+    photos: list[str] = field(default_factory=list)
+    rooms: float | None = None
+    floor: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    # populated by river_check.py + state diffing
+    river_evidence: dict[str, Any] | None = None
+    river_verdict: str | None = None  # text+photo / text-only / photo-only / partial / none
+    is_new: bool = False
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return (self.source, self.id)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class HttpClient:
+    """httpx wrapper with shared headers and a tiny on-disk HTML cache.
+
+    Cache TTL is per-call (`cache_ttl_seconds`); pass 0 to disable caching
+    for that request. Cache keys hash the URL so they are filesystem-safe.
+    """
+
+    def __init__(self, cache_dir: Path, timeout: float = 30.0):
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._client = httpx.Client(
+            headers=DEFAULT_HEADERS,
+            timeout=timeout,
+            follow_redirects=True,
+            http2=True,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _cache_path(self, url: str) -> Path:
+        digest = hashlib.sha1(url.encode("utf-8")).hexdigest()[:24]
+        return self.cache_dir / f"{digest}.html"
+
+    def get(
+        self,
+        url: str,
+        *,
+        cache_ttl_seconds: int = 0,
+        extra_headers: dict[str, str] | None = None,
+    ) -> str:
+        """GET a URL, optionally returning a cached copy if fresh enough."""
+        if cache_ttl_seconds > 0:
+            path = self._cache_path(url)
+            if path.exists() and (time.time() - path.stat().st_mtime) < cache_ttl_seconds:
+                logger.debug("HTTP cache hit: %s", url)
+                return path.read_text(encoding="utf-8", errors="replace")
+
+        logger.debug("HTTP GET: %s", url)
+        resp = self._client.get(url, headers=extra_headers)
+        resp.raise_for_status()
+        text = resp.text
+        if cache_ttl_seconds > 0:
+            self._cache_path(url).write_text(text, encoding="utf-8")
+        return text
+
+    def get_json(self, url: str, *, extra_headers: dict[str, str] | None = None) -> Any:
+        resp = self._client.get(url, headers=extra_headers)
+        resp.raise_for_status()
+        return resp.json()
+
+
+class Scraper(abc.ABC):
+    """Abstract base class for portal scrapers.
+
+    Subclasses implement `fetch()` returning an iterable of `Listing`s.
+    The runner is responsible for filtering / diffing / vision verification.
+    """
+
+    name: str = "base"
+
+    def __init__(
+        self,
+        *,
+        location_profile: dict[str, Any],
+        location_slug: str,
+        max_listings: int = 30,
+        cache_dir: Path | None = None,
+    ):
+        self.location_profile = location_profile
+        self.location_slug = location_slug
+        self.max_listings = max_listings
+        self.cache_dir = cache_dir or Path("state/cache") / self.name
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    @abc.abstractmethod
+    def fetch(self) -> Iterable[Listing]:
+        """Yield raw listings (filtering happens downstream)."""
+
+
+# ---------- common parsing helpers ----------------------------------------
+
+_PRICE_RE = re.compile(r"(?P<num>\d[\d\.\,\s]*)\s*(?:€|eur|EUR)", re.IGNORECASE)
+_AREA_RE = re.compile(r"(?P<num>\d[\d\.\,\s]*)\s*m\s*2|(?P<num2>\d[\d\.\,\s]*)\s*m²", re.IGNORECASE)
+
+
+def parse_price_eur(text: str) -> float | None:
+    """Best-effort EUR price extraction from a free-text snippet."""
+    if not text:
+        return None
+    m = _PRICE_RE.search(text)
+    if not m:
+        return None
+    return _to_float(m.group("num"))
+
+
+def parse_area_m2(text: str) -> float | None:
+    """Best-effort m² extraction from a free-text snippet."""
+    if not text:
+        return None
+    m = _AREA_RE.search(text)
+    if not m:
+        return None
+    return _to_float(m.group("num") or m.group("num2"))
+
+
+def _to_float(raw: str) -> float | None:
+    if raw is None:
+        return None
+    cleaned = raw.replace(" ", "").replace(".", "").replace(",", ".")
+    # strip stray non-numeric tail (e.g. "1.200.5" → "1200.5"); after dot-stripping
+    # the last "." may be a real decimal — re-parse permissively.
+    try:
+        return float(cleaned)
+    except ValueError:
+        # try assuming first segment is the integer part
+        try:
+            return float(re.sub(r"[^\d.]", "", cleaned))
+        except ValueError:
+            return None
+
+
+def soup(html: str) -> BeautifulSoup:
+    return BeautifulSoup(html, "lxml")
+
+
+def write_state(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def read_state(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        logger.warning("Corrupt state file %s, ignoring", path)
+        return {}
diff --git a/serbian_realestate/scrapers/cityexpert.py b/serbian_realestate/scrapers/cityexpert.py
new file mode 100644
index 0000000..a541333
--- /dev/null
+++ b/serbian_realestate/scrapers/cityexpert.py
@@ -0,0 +1,98 @@
+"""cityexpert.rs scraper — Playwright (Cloudflare).
+
+Lessons from plan.md §4.5:
+- Wrong URL pattern (`/en/r/belgrade/...`) returns 404.
+- Right URL: `/en/properties-for-rent/belgrade?ptId=1` (apartments only).
+- Pagination via `?currentPage=N` (NOT `?page=N`).
+- BW listings are sparse — walk up to 10 pages.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from scrapers._playwright_util import safe_goto, stealth_browser
+from scrapers.base import Listing, Scraper, parse_area_m2, parse_price_eur
+from scrapers.photos import extract_photos
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://cityexpert.rs"
+LIST_URL = "/en/properties-for-rent/belgrade"
+MAX_PAGES = 10
+
+_DETAIL_RE = re.compile(r"/en/properties-for-rent/[^\"'?#]+/\d+", re.IGNORECASE)
+
+
+class CityExpertScraper(Scraper):
+    name = "cityexpert"
+
+    def fetch(self) -> Iterable[Listing]:
+        # Persistent profile lives under state/browser/ so CF cookies survive
+        # cache wipes between runs (plan.md §2 layout).
+        profile = Path(self.cache_dir).parent.parent / "browser" / "cityexpert_profile"
+        pt_id = self.location_profile.get("cityexpert_part_id", 1)
+
+        with stealth_browser(profile) as ctx:
+            page = ctx.new_page()
+            detail_urls: list[str] = []
+            for page_num in range(1, MAX_PAGES + 1):
+                url = urljoin(BASE, f"{LIST_URL}?ptId={pt_id}&currentPage={page_num}")
+                if not safe_goto(page, url, wait_ms=4000):
+                    break
+                html = page.content()
+                page_urls = list(dict.fromkeys(_DETAIL_RE.findall(html)))
+                added = 0
+                for u in page_urls:
+                    full = urljoin(BASE, u)
+                    if full not in detail_urls:
+                        detail_urls.append(full)
+                        added += 1
+                if added == 0:
+                    break
+
+            logger.info("[cityexpert] %d detail URLs collected", len(detail_urls))
+            for url in detail_urls[: self.max_listings]:
+                try:
+                    yield self._parse_detail(page, url)
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("[cityexpert] failed on %s: %s", url, exc)
+
+    def _parse_detail(self, page, url: str) -> Listing:
+        if not safe_goto(page, url, wait_ms=4000):
+            raise RuntimeError("navigation failed")
+        html = page.content()
+        s = BeautifulSoup(html, "lxml")
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1]
+        title = (s.title.get_text(strip=True) if s.title else "") or url
+
+        body_text = s.get_text(" ", strip=True)
+        price = parse_price_eur(body_text)
+        area = parse_area_m2(body_text)
+
+        loc_el = s.find(class_=re.compile("location|address", re.I))
+        location = loc_el.get_text(" ", strip=True) if loc_el else None
+
+        desc_el = s.find(class_=re.compile("description|details", re.I)) or s.find("article")
+        description = desc_el.get_text(" ", strip=True) if desc_el else body_text
+
+        photos = extract_photos(s, url, limit=8)
+
+        return Listing(
+            source=self.name,
+            id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            location=location,
+            description=description,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/fzida.py b/serbian_realestate/scrapers/fzida.py
new file mode 100644
index 0000000..cb6fc62
--- /dev/null
+++ b/serbian_realestate/scrapers/fzida.py
@@ -0,0 +1,101 @@
+"""4zida.rs scraper — plain HTTP (no JS).
+
+Lesson from plan.md §4.4: list page is JS-rendered but the detail URLs
+are present as `<a href>` attributes in the initial HTML. Detail pages
+themselves are server-rendered, so we can extract everything with httpx
++ BeautifulSoup.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+from urllib.parse import urljoin
+
+from scrapers.base import HttpClient, Listing, Scraper, parse_area_m2, parse_price_eur, soup
+from scrapers.photos import extract_photos
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.4zida.rs"
+
+# 4zida URL convention for rentals in a given location:
+#   /izdavanje-stanova/<location-slug>?strana=N
+# Sale listings live under /prodaja-stanova/, so this URL pattern
+# inherently filters out sales (plan.md §11).
+
+LIST_URL_TEMPLATE = "/izdavanje-stanova/{slug}"
+
+# Detail URL slug: /izdavanje-stanova/<location>/<title-slug>/<id>
+_DETAIL_RE = re.compile(r"/izdavanje-stanova/[^\"'?#]+/\d+", re.IGNORECASE)
+
+
+class FZidaScraper(Scraper):
+    name = "4zida"
+
+    def fetch(self) -> Iterable[Listing]:
+        slug = self.location_slug
+        with HttpClient(self.cache_dir) as http:
+            detail_urls = self._collect_detail_urls(http, slug)
+            logger.info("[4zida] %d detail URLs collected", len(detail_urls))
+            for url in detail_urls[: self.max_listings]:
+                try:
+                    yield self._parse_detail(http, url)
+                except Exception as exc:  # noqa: BLE001 — keep the run going
+                    logger.warning("[4zida] failed on %s: %s", url, exc)
+
+    def _collect_detail_urls(self, http: HttpClient, slug: str) -> list[str]:
+        seen: list[str] = []
+        for page in range(1, 4):
+            list_url = urljoin(BASE, LIST_URL_TEMPLATE.format(slug=slug))
+            if page > 1:
+                list_url = f"{list_url}?strana={page}"
+            try:
+                html = http.get(list_url, cache_ttl_seconds=600)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[4zida] list page %d failed: %s", page, exc)
+                break
+            page_urls = list(dict.fromkeys(_DETAIL_RE.findall(html)))
+            new = [u for u in page_urls if u not in seen]
+            if not new:
+                break
+            seen.extend(new)
+        return [urljoin(BASE, u) for u in seen]
+
+    def _parse_detail(self, http: HttpClient, url: str) -> Listing:
+        html = http.get(url, cache_ttl_seconds=86_400)
+        s = soup(html)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1]
+        title = (s.title.get_text(strip=True) if s.title else "") or url
+
+        # Price + area: look for structured spans first, fall back to body regex.
+        body_text = s.get_text(" ", strip=True)
+        price = parse_price_eur(body_text)
+        area = parse_area_m2(body_text)
+
+        # Location: 4zida often has a breadcrumb <nav>.
+        loc_el = s.find(attrs={"itemprop": "address"}) or s.find(class_=re.compile("location", re.I))
+        location = loc_el.get_text(" ", strip=True) if loc_el else None
+
+        description = ""
+        desc_el = s.find(class_=re.compile("description|opis", re.I)) or s.find("article")
+        if desc_el:
+            description = desc_el.get_text(" ", strip=True)
+        if not description:
+            description = body_text  # last resort — gives river-text matcher something to chew
+
+        photos = extract_photos(s, url, limit=8)
+
+        return Listing(
+            source=self.name,
+            id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            location=location,
+            description=description,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/halooglasi.py b/serbian_realestate/scrapers/halooglasi.py
new file mode 100644
index 0000000..a298fc9
--- /dev/null
+++ b/serbian_realestate/scrapers/halooglasi.py
@@ -0,0 +1,209 @@
+"""halooglasi.com scraper — Selenium + undetected-chromedriver.
+
+This is the hardest portal in the set. Cloudflare aggressively
+challenges every detail page; Playwright stealth gets ~25-30%, while
+undetected-chromedriver (with real Chrome) hits ~100%.
+
+Critical setup details from plan.md §4.1 — change at your peril:
+
+- Real Google Chrome, not Chromium.
+- `page_load_strategy="eager"` — without it `driver.get()` hangs
+  indefinitely on CF challenge pages (window load never fires).
+- Pass Chrome major version explicitly to `uc.Chrome(version_main=N)` —
+  auto-detect ships chromedriver too new for installed Chrome.
+- Persistent profile dir keeps CF clearance cookies between runs.
+- `time.sleep(8)` then poll — CF challenge JS blocks the main thread,
+  so wait_for_function-style polling can't run during it.
+- Read structured data from `window.QuidditaEnvironment.CurrentClassified.OtherFields`,
+  not body text. Field map is in plan.md §4.1.
+
+The scraper degrades gracefully if Chrome / undetected-chromedriver
+isn't installed — it logs a clear error and yields nothing rather
+than crashing the whole run.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Iterable
+from urllib.parse import urljoin
+
+from scrapers.base import Listing, Scraper
+from scrapers.photos import extract_photos
+from bs4 import BeautifulSoup
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.halooglasi.com"
+LIST_PATH = "/nekretnine/izdavanje-stanova"
+
+
+class HaloOglasiScraper(Scraper):
+    name = "halooglasi"
+
+    def fetch(self) -> Iterable[Listing]:
+        try:
+            import undetected_chromedriver as uc
+        except ImportError:
+            logger.error(
+                "[halooglasi] undetected-chromedriver not installed; skipping. "
+                "Run `uv sync` in serbian_realestate/ to install."
+            )
+            return
+
+        chrome_major = _detect_chrome_major()
+        if chrome_major is None:
+            logger.error("[halooglasi] real Google Chrome not found on PATH; skipping")
+            return
+
+        # Persistent profile lives under state/browser/, not state/cache/<name>/,
+        # so CF clearance cookies survive cache wipes (plan.md §4.1).
+        profile_dir = Path(self.cache_dir).parent.parent / "browser" / "halooglasi_chrome_profile"
+        profile_dir.mkdir(parents=True, exist_ok=True)
+
+        options = uc.ChromeOptions()
+        options.add_argument("--headless=new")
+        options.add_argument(f"--user-data-dir={profile_dir}")
+        options.add_argument("--no-sandbox")
+        options.add_argument("--disable-dev-shm-usage")
+        options.add_argument("--lang=sr-Latn-RS")
+        options.page_load_strategy = "eager"  # plan.md §4.1 — required
+
+        driver = None
+        try:
+            driver = uc.Chrome(options=options, version_main=chrome_major)
+            driver.set_page_load_timeout(60)
+            yield from self._fetch_with_driver(driver)
+        except Exception as exc:  # noqa: BLE001
+            logger.error("[halooglasi] driver crashed: %s", exc)
+        finally:
+            if driver is not None:
+                try:
+                    driver.quit()
+                except Exception:  # noqa: BLE001
+                    pass
+
+    def _fetch_with_driver(self, driver) -> Iterable[Listing]:
+        list_url = urljoin(BASE, LIST_PATH)
+        loc_id = self.location_profile.get("halooglasi_location_id")
+        if loc_id:
+            list_url = f"{list_url}?cities_id_l={loc_id}"
+
+        logger.info("[halooglasi] loading list page: %s", list_url)
+        driver.get(list_url)
+        time.sleep(8)  # let CF challenge JS finish — see plan.md §4.1
+
+        html = driver.page_source
+        detail_re = re.compile(r"/nekretnine/[^\"'?#]*/[\w\-]+/\d+", re.IGNORECASE)
+        urls = list(dict.fromkeys(detail_re.findall(html)))
+        # Skip sale listings — rentals only (plan.md §11)
+        urls = [u for u in urls if "izdavanje" in u]
+        detail_urls = [urljoin(BASE, u) for u in urls][: self.max_listings]
+        logger.info("[halooglasi] %d detail URLs collected", len(detail_urls))
+
+        for url in detail_urls:
+            try:
+                listing = self._parse_detail(driver, url)
+                if listing:
+                    yield listing
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[halooglasi] failed on %s: %s", url, exc)
+
+    def _parse_detail(self, driver, url: str) -> Listing | None:
+        driver.get(url)
+        time.sleep(8)
+
+        # Pull structured data first — most reliable per plan.md §4.1.
+        other_fields = _read_quiddita_other_fields(driver)
+        html = driver.page_source
+        s = BeautifulSoup(html, "lxml")
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1]
+
+        if other_fields:
+            # rentals only: skip if not Stan or unit not EUR
+            if other_fields.get("tip_nekretnine_s", "").lower() not in {"stan", ""}:
+                return None
+            unit = (other_fields.get("cena_d_unit_s") or "").upper()
+            price = other_fields.get("cena_d") if unit in {"EUR", ""} else None
+            area = other_fields.get("kvadratura_d")
+            rooms = _coerce_float(other_fields.get("broj_soba_s"))
+            sprat = other_fields.get("sprat_s")
+            sprat_od = other_fields.get("sprat_od_s")
+            floor = (
+                f"{sprat}/{sprat_od}" if sprat and sprat_od else (sprat or sprat_od)
+            )
+        else:
+            price = area = rooms = floor = None
+
+        title = (s.title.get_text(strip=True) if s.title else "") or url
+        body_text = s.get_text(" ", strip=True)
+        desc_el = s.find(class_=re.compile("opis|description", re.I)) or s.find("article")
+        description = desc_el.get_text(" ", strip=True) if desc_el else body_text
+
+        loc_el = s.find(class_=re.compile("address|lokacija", re.I))
+        location = loc_el.get_text(" ", strip=True) if loc_el else None
+
+        photos = extract_photos(s, url, limit=8)
+
+        return Listing(
+            source=self.name,
+            id=listing_id,
+            url=url,
+            title=title,
+            price_eur=_coerce_float(price),
+            area_m2=_coerce_float(area),
+            location=location,
+            description=description,
+            photos=photos,
+            rooms=rooms,
+            floor=floor,
+            extra={"halooglasi_other_fields": other_fields or {}},
+        )
+
+
+def _detect_chrome_major() -> int | None:
+    """Return Chrome's major version, or None if Chrome is not installed."""
+    for binary in ("google-chrome", "google-chrome-stable", "chrome"):
+        path = shutil.which(binary)
+        if not path:
+            continue
+        try:
+            out = subprocess.check_output([path, "--version"], stderr=subprocess.STDOUT, timeout=5)
+        except (subprocess.SubprocessError, OSError):
+            continue
+        m = re.search(r"(\d+)\.\d+\.\d+", out.decode("utf-8", "replace"))
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def _read_quiddita_other_fields(driver) -> dict[str, Any] | None:
+    """Read window.QuidditaEnvironment.CurrentClassified.OtherFields via JS."""
+    try:
+        return driver.execute_script(
+            "try {"
+            "  return window.QuidditaEnvironment "
+            "    && window.QuidditaEnvironment.CurrentClassified "
+            "    && window.QuidditaEnvironment.CurrentClassified.OtherFields;"
+            "} catch (e) { return null; }"
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("Quiddita read failed: %s", exc)
+        return None
+
+
+def _coerce_float(value: Any) -> float | None:
+    if value is None or value == "":
+        return None
+    try:
+        return float(str(value).replace(",", "."))
+    except (TypeError, ValueError):
+        return None
+
+
diff --git a/serbian_realestate/scrapers/indomio.py b/serbian_realestate/scrapers/indomio.py
new file mode 100644
index 0000000..f1e6f75
--- /dev/null
+++ b/serbian_realestate/scrapers/indomio.py
@@ -0,0 +1,109 @@
+"""indomio.rs scraper — Playwright (Distil bot challenge).
+
+Lessons from plan.md §4.6:
+- SPA with Distil bot challenge — needs Playwright + stealth.
+- Detail URLs have no descriptive slug, just `/en/{numeric-ID}`.
+- Card-text filter (cards have "Belgrade, Savski Venac: Dedinje" in text)
+  rather than URL-keyword filter.
+- Server-side filter params don't work; only municipality URL slug filters.
+- 8s SPA hydration wait before card collection.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+from scrapers._playwright_util import safe_goto, stealth_browser
+from scrapers.base import Listing, Scraper, parse_area_m2, parse_price_eur
+from scrapers.photos import extract_photos
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.indomio.rs"
+LIST_URL_TEMPLATE = "/en/to-rent/flats/{slug}"
+
+_DETAIL_RE = re.compile(r"/en/\d+(?:[/?#]|$)")
+
+
+class IndomioScraper(Scraper):
+    name = "indomio"
+
+    def fetch(self) -> Iterable[Listing]:
+        # Persistent profile lives under state/browser/ so Distil cookies
+        # survive cache wipes between runs (plan.md §2 layout).
+        profile = Path(self.cache_dir).parent.parent / "browser" / "indomio_profile"
+        municipality = self.location_profile.get(
+            "indomio_municipality_slug", "belgrade-savski-venac"
+        )
+        keywords = [k.lower() for k in self.location_profile.get("location_keywords", [])]
+
+        with stealth_browser(profile) as ctx:
+            page = ctx.new_page()
+            list_url = urljoin(BASE, LIST_URL_TEMPLATE.format(slug=municipality))
+            if not safe_goto(page, list_url, wait_ms=8000):
+                return
+
+            html = page.content()
+            s = BeautifulSoup(html, "lxml")
+
+            # Card-based collection: each card is filtered by visible text
+            # (plan.md §4.6) — we can't trust URL keywords because slugs are bare IDs.
+            cards: list[tuple[str, str]] = []
+            for a in s.find_all("a", href=_DETAIL_RE):
+                href = a.get("href")
+                if not href:
+                    continue
+                full = urljoin(BASE, href.split("#")[0].split("?")[0])
+                # find the enclosing card-ish container; fall back to the link itself
+                container = a.find_parent(["article", "li", "div"]) or a
+                card_text = container.get_text(" ", strip=True).lower()
+                if keywords and not any(k in card_text for k in keywords):
+                    continue
+                if not any(u == full for u, _ in cards):
+                    cards.append((full, card_text))
+
+            logger.info("[indomio] %d candidate cards after keyword filter", len(cards))
+            for url, _ in cards[: self.max_listings]:
+                try:
+                    yield self._parse_detail(page, url)
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("[indomio] failed on %s: %s", url, exc)
+
+    def _parse_detail(self, page, url: str) -> Listing:
+        if not safe_goto(page, url, wait_ms=6000):
+            raise RuntimeError("navigation failed")
+        html = page.content()
+        s = BeautifulSoup(html, "lxml")
+
+        listing_id = re.search(r"/en/(\d+)", url).group(1)
+        title = (s.title.get_text(strip=True) if s.title else "") or url
+
+        body_text = s.get_text(" ", strip=True)
+        price = parse_price_eur(body_text)
+        area = parse_area_m2(body_text)
+
+        loc_el = s.find(class_=re.compile("location|address", re.I))
+        location = loc_el.get_text(" ", strip=True) if loc_el else None
+
+        desc_el = s.find(class_=re.compile("description|details", re.I)) or s.find("article")
+        description = desc_el.get_text(" ", strip=True) if desc_el else body_text
+
+        photos = extract_photos(s, url, limit=8)
+
+        return Listing(
+            source=self.name,
+            id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            location=location,
+            description=description,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/kredium.py b/serbian_realestate/scrapers/kredium.py
new file mode 100644
index 0000000..20abaf3
--- /dev/null
+++ b/serbian_realestate/scrapers/kredium.py
@@ -0,0 +1,94 @@
+"""kredium.rs scraper — plain HTTP with section-scoped parsing.
+
+Lesson from plan.md §4.3: parsing the full <body> pollutes via the
+related-listings carousel — every detail page advertises 4-6 other
+listings at the bottom, and naive body-text parsing tags each listing
+as the *wrong* building. Scope to the <section> containing
+"Informacije" / "Opis" headings.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+from urllib.parse import urljoin
+
+from bs4 import Tag
+
+from scrapers.base import HttpClient, Listing, Scraper, parse_area_m2, parse_price_eur, soup
+from scrapers.photos import extract_photos
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://kredium.rs"
+LIST_URL_TEMPLATE = "/oglasi/izdavanje/stanovi/beograd/{slug}"
+
+_DETAIL_RE = re.compile(r"/oglasi/[^\"'?#]+/\d+", re.IGNORECASE)
+
+
+class KrediumScraper(Scraper):
+    name = "kredium"
+
+    def fetch(self) -> Iterable[Listing]:
+        with HttpClient(self.cache_dir) as http:
+            list_url = urljoin(BASE, LIST_URL_TEMPLATE.format(slug=self.location_slug))
+            try:
+                html = http.get(list_url, cache_ttl_seconds=600)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[kredium] list page failed: %s", exc)
+                return
+            urls = list(dict.fromkeys(_DETAIL_RE.findall(html)))
+            detail_urls = [urljoin(BASE, u) for u in urls][: self.max_listings]
+            logger.info("[kredium] %d detail URLs collected", len(detail_urls))
+            for url in detail_urls:
+                try:
+                    yield self._parse_detail(http, url)
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("[kredium] failed on %s: %s", url, exc)
+
+    def _parse_detail(self, http: HttpClient, url: str) -> Listing:
+        html = http.get(url, cache_ttl_seconds=86_400)
+        s = soup(html)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1]
+        title = (s.title.get_text(strip=True) if s.title else "") or url
+
+        # Section-scoped extraction — find the section(s) containing
+        # "Informacije" or "Opis" headings, ignore everything else.
+        section = _find_listing_section(s)
+        scope = section if section else s
+        scope_text = scope.get_text(" ", strip=True)
+
+        price = parse_price_eur(scope_text)
+        area = parse_area_m2(scope_text)
+
+        loc_el = scope.find(class_=re.compile("location|adresa|lokacija", re.I))
+        location = loc_el.get_text(" ", strip=True) if loc_el else None
+
+        # Photos can come from outside the text section (gallery is usually
+        # at the top of the page), so extract from the full soup but the
+        # photo helper already de-dups.
+        photos = extract_photos(s, url, limit=8)
+
+        return Listing(
+            source=self.name,
+            id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            location=location,
+            description=scope_text,
+            photos=photos,
+        )
+
+
+def _find_listing_section(s) -> Tag | None:
+    """Return the <section> tag whose subtree contains an Informacije/Opis heading."""
+    for section in s.find_all("section"):
+        for heading in section.find_all(re.compile(r"^h[1-6]$")):
+            txt = heading.get_text(strip=True).lower()
+            if "informacije" in txt or "opis" in txt:
+                return section
+    return None
diff --git a/serbian_realestate/scrapers/nekretnine.py b/serbian_realestate/scrapers/nekretnine.py
new file mode 100644
index 0000000..0e13baf
--- /dev/null
+++ b/serbian_realestate/scrapers/nekretnine.py
@@ -0,0 +1,105 @@
+"""nekretnine.rs scraper — plain HTTP, paginated.
+
+Lessons from plan.md §4.2:
+- Location filter is loose; bleeds non-target listings → keyword-filter
+  URLs post-fetch using `location_keywords`.
+- Skip sale listings (`item_category=Prodaja`) — rental search bleeds
+  into sales via shared URL infrastructure.
+- Pagination via `?page=N`, walk up to 5 pages.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Iterable
+from urllib.parse import urljoin
+
+from scrapers.base import HttpClient, Listing, Scraper, parse_area_m2, parse_price_eur, soup
+from scrapers.photos import extract_photos
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://www.nekretnine.rs"
+LIST_URL = "/stambeni-objekti/stanovi/izdavanje-prodaja/izdavanje/grad/beograd/lista/po-stranici/20/"
+
+# Detail URLs follow /stambeni-objekti/stanovi/<slug>/<numeric-id>/.
+_DETAIL_RE = re.compile(
+    r"/stambeni-objekti/stanovi/[^\"'?#]+/\d+/?", re.IGNORECASE
+)
+_SALE_HINT = re.compile(r"item_category=Prodaja|/prodaja/", re.IGNORECASE)
+
+
+class NekretnineScraper(Scraper):
+    name = "nekretnine"
+
+    def fetch(self) -> Iterable[Listing]:
+        with HttpClient(self.cache_dir) as http:
+            detail_urls = self._collect_detail_urls(http)
+            logger.info("[nekretnine] %d detail URLs collected", len(detail_urls))
+            for url in detail_urls[: self.max_listings]:
+                try:
+                    yield self._parse_detail(http, url)
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("[nekretnine] failed on %s: %s", url, exc)
+
+    def _collect_detail_urls(self, http: HttpClient) -> list[str]:
+        keywords = [k.lower() for k in self.location_profile.get("location_keywords", [])]
+        seen: list[str] = []
+        for page in range(1, 6):
+            list_url = urljoin(BASE, LIST_URL)
+            if page > 1:
+                list_url = f"{list_url}?page={page}"
+            try:
+                html = http.get(list_url, cache_ttl_seconds=600)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[nekretnine] list page %d failed: %s", page, exc)
+                break
+            urls = list(dict.fromkeys(_DETAIL_RE.findall(html)))
+            page_new = 0
+            for u in urls:
+                if _SALE_HINT.search(u):
+                    continue
+                # post-fetch keyword filter — plan.md §4.2
+                if keywords and not any(k in u.lower() for k in keywords):
+                    continue
+                full = urljoin(BASE, u)
+                if full in seen:
+                    continue
+                seen.append(full)
+                page_new += 1
+            if page_new == 0:
+                # nothing new on this page — assume tail of pagination
+                break
+        return seen
+
+    def _parse_detail(self, http: HttpClient, url: str) -> Listing:
+        html = http.get(url, cache_ttl_seconds=86_400)
+        s = soup(html)
+
+        listing_id = url.rstrip("/").rsplit("/", 1)[-1]
+        title = (s.title.get_text(strip=True) if s.title else "") or url
+
+        body_text = s.get_text(" ", strip=True)
+        price = parse_price_eur(body_text)
+        area = parse_area_m2(body_text)
+
+        loc_el = s.find(class_=re.compile("location|address|lokacija", re.I))
+        location = loc_el.get_text(" ", strip=True) if loc_el else None
+
+        desc_el = s.find(class_=re.compile("description|opis|detalji", re.I)) or s.find("article")
+        description = desc_el.get_text(" ", strip=True) if desc_el else body_text
+
+        photos = extract_photos(s, url, limit=8)
+
+        return Listing(
+            source=self.name,
+            id=listing_id,
+            url=url,
+            title=title,
+            price_eur=price,
+            area_m2=area,
+            location=location,
+            description=description,
+            photos=photos,
+        )
diff --git a/serbian_realestate/scrapers/photos.py b/serbian_realestate/scrapers/photos.py
new file mode 100644
index 0000000..d0584fa
--- /dev/null
+++ b/serbian_realestate/scrapers/photos.py
@@ -0,0 +1,75 @@
+"""Generic photo URL extraction helpers.
+
+Most Serbian portals embed photos in `<img src=...>` or `<picture><source srcset=...>`.
+This module extracts URLs and normalizes them (absolute URLs, dedup, http(s) only).
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+
+# Block patterns: site furniture / icons / banners that aren't real listing photos.
+_BLOCKLIST = re.compile(
+    r"(sprite|icon|logo|placeholder|avatar|app[-_]store|google[-_]play|play[-_]store)",
+    re.IGNORECASE,
+)
+
+# Halo Oglasi specifically embeds mobile-app banner images on every detail page;
+# they live on banner.halooglasi.com or contain "appbanner". Strip them.
+_HALO_BANNER = re.compile(r"(banner\.halooglasi|appbanner|app-banner)", re.IGNORECASE)
+
+
+def extract_photos(soup: BeautifulSoup, base_url: str, *, limit: int = 12) -> list[str]:
+    """Pull plausible listing photo URLs from a parsed detail page."""
+    seen: list[str] = []
+
+    # <picture><source srcset=...> — preferred when present (high-res variant)
+    for source in soup.find_all("source"):
+        srcset = source.get("srcset") or ""
+        for candidate in _split_srcset(srcset):
+            url = _normalize(candidate, base_url)
+            if url and _is_photo(url) and url not in seen:
+                seen.append(url)
+
+    # <img src=> / data-src= / data-original=
+    for img in soup.find_all("img"):
+        for attr in ("src", "data-src", "data-original", "data-lazy-src"):
+            raw = img.get(attr)
+            if not raw:
+                continue
+            url = _normalize(raw, base_url)
+            if url and _is_photo(url) and url not in seen:
+                seen.append(url)
+
+    return seen[:limit]
+
+
+def _split_srcset(srcset: str) -> list[str]:
+    out: list[str] = []
+    for chunk in srcset.split(","):
+        url = chunk.strip().split(" ")[0]
+        if url:
+            out.append(url)
+    return out
+
+
+def _normalize(raw: str, base_url: str) -> str | None:
+    raw = raw.strip()
+    if not raw or raw.startswith("data:"):
+        return None
+    return urljoin(base_url, raw)
+
+
+def _is_photo(url: str) -> bool:
+    if not url.startswith(("http://", "https://")):
+        return False
+    if _BLOCKLIST.search(url) or _HALO_BANNER.search(url):
+        return False
+    # accept anything that smells like an image; many portals omit extensions
+    # because they go through resize CDNs.
+    if re.search(r"\.(jpe?g|png|webp|avif)(\?|$)", url, re.IGNORECASE):
+        return True
+    return any(seg in url.lower() for seg in ("photo", "image", "img", "media", "cdn"))
diff --git a/serbian_realestate/scrapers/river_check.py b/serbian_realestate/scrapers/river_check.py
new file mode 100644
index 0000000..ac1700b
--- /dev/null
+++ b/serbian_realestate/scrapers/river_check.py
@@ -0,0 +1,270 @@
+"""Sonnet vision verification for river-view photos.
+
+Two-signal AND check (plan.md §5.2):
+- Sonnet 4.6 vision call per photo (Haiku 4.5 was too generous, calling
+  distant grey strips "rivers"). Strict prompt: water must occupy a
+  meaningful portion of the frame, not a distant sliver.
+- Verdicts: only `yes-direct` counts as positive. `partial`, `indoor`,
+  `no` are non-positive. Legacy `yes-distant` is coerced to `no`.
+
+Implementation details:
+- System prompt cached with `cache_control: ephemeral` for cross-call savings.
+- Concurrent up to 4 listings, max 3 photos per listing.
+- Per-photo errors are caught — one bad URL doesn't poison the listing.
+- Inline base64 fallback — Anthropic's URL-mode image fetcher 400s on
+  some CDNs (4zida resizer, kredium .webp). Download with httpx,
+  base64-encode, send inline.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any
+
+import httpx
+
+from scrapers.base import Listing
+
+logger = logging.getLogger(__name__)
+
+VISION_MODEL = "claude-sonnet-4-6"
+MAX_CONCURRENT_LISTINGS = 4
+DEFAULT_MAX_PHOTOS = 3
+
+# Strict prompt — see plan.md §5.2. Note the explicit "no distant slivers"
+# clause; without it Sonnet still leans generous.
+SYSTEM_PROMPT = """\
+You are verifying whether a real-estate photo shows a direct river or large-water view from the apartment.
+
+Answer with ONE verdict, lowercase, no punctuation:
+- yes-direct   : the river/lake clearly occupies a meaningful portion of the frame as visible from the apartment (window, balcony, terrace) — NOT a distant sliver, NOT seen at a sharp angle far away.
+- partial      : water visible but only as a distant strip / corner / through obstructions.
+- no           : no water visible, or water visible only outside the apartment context (street photo, map screenshot, etc.).
+- indoor       : photo is purely interior — kitchen, bathroom, bedroom with no window scenery.
+
+Do NOT count:
+- pools, fountains, ponds, puddles
+- distant grey strips that are ambiguous
+- sky, clouds, fog
+- the building's own facade reflected in glass
+
+Reply with the verdict on the first line, then a one-sentence justification.
+"""
+
+
+class RiverChecker:
+    """Wraps the Anthropic SDK + a local httpx client for image fallback fetches."""
+
+    def __init__(self, *, api_key: str | None = None):
+        try:
+            import anthropic  # noqa: F401  (just verifying it's installed)
+        except ImportError as exc:
+            raise RuntimeError(
+                "anthropic package not installed; run uv sync in serbian_realestate/"
+            ) from exc
+
+        from anthropic import Anthropic
+
+        api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "ANTHROPIC_API_KEY missing — required for --verify-river"
+            )
+        self._client = Anthropic(api_key=api_key)
+        self._http = httpx.Client(timeout=30.0)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "RiverChecker":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    # ---- public API ----------------------------------------------------
+
+    def verify_listings(
+        self,
+        listings: list[Listing],
+        *,
+        max_photos: int = DEFAULT_MAX_PHOTOS,
+    ) -> None:
+        """Annotate each listing in-place with `river_evidence` (photo verdicts)."""
+        if not listings:
+            return
+        with ThreadPoolExecutor(max_workers=MAX_CONCURRENT_LISTINGS) as ex:
+            futures = {
+                ex.submit(self._verify_one, listing, max_photos): listing
+                for listing in listings
+            }
+            for fut in as_completed(futures):
+                listing = futures[fut]
+                try:
+                    listing.river_evidence = fut.result()
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning(
+                        "[%s] river verification failed for %s: %s",
+                        listing.source,
+                        listing.url,
+                        exc,
+                    )
+                    listing.river_evidence = {"model": VISION_MODEL, "photos": [], "error": str(exc)}
+
+    # ---- internals -----------------------------------------------------
+
+    def _verify_one(self, listing: Listing, max_photos: int) -> dict[str, Any]:
+        photos = listing.photos[:max_photos]
+        results: list[dict[str, Any]] = []
+        for url in photos:
+            verdict, justification, raw = self._verify_photo(url)
+            results.append(
+                {
+                    "url": url,
+                    "verdict": verdict,
+                    "justification": justification,
+                    "raw": raw,
+                }
+            )
+        # Store a snapshot of the description we verified against —
+        # plan.md §6.1 invalidates the cache when description text changes.
+        return {
+            "model": VISION_MODEL,
+            "photos": results,
+            "description_snapshot": listing.description,
+        }
+
+    def _verify_photo(self, url: str) -> tuple[str, str, str]:
+        """Return (verdict, justification, raw response text)."""
+        # First try URL mode — cheapest path; falls back to base64 on 400.
+        try:
+            content = self._build_content(url, mode="url")
+            text = self._call_sonnet(content)
+            return _parse_verdict(text)
+        except _ImageURLBlocked:
+            try:
+                content = self._build_content(url, mode="base64")
+                text = self._call_sonnet(content)
+                return _parse_verdict(text)
+            except Exception as exc:  # noqa: BLE001
+                return ("error", f"download/inline failed: {exc}", "")
+        except Exception as exc:  # noqa: BLE001
+            return ("error", str(exc), "")
+
+    def _build_content(self, url: str, *, mode: str) -> list[dict[str, Any]]:
+        if mode == "url":
+            image_block = {"type": "image", "source": {"type": "url", "url": url}}
+        else:
+            data, media_type = self._download_image(url)
+            image_block = {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": media_type,
+                    "data": base64.b64encode(data).decode("ascii"),
+                },
+            }
+        return [
+            image_block,
+            {"type": "text", "text": "Apply the verdict rubric to this image."},
+        ]
+
+    def _download_image(self, url: str) -> tuple[bytes, str]:
+        resp = self._http.get(url, follow_redirects=True)
+        resp.raise_for_status()
+        media_type = resp.headers.get("content-type", "image/jpeg").split(";")[0].strip()
+        if media_type not in {"image/jpeg", "image/png", "image/webp", "image/gif"}:
+            media_type = "image/jpeg"
+        return resp.content, media_type
+
+    def _call_sonnet(self, content: list[dict[str, Any]]) -> str:
+        try:
+            resp = self._client.messages.create(
+                model=VISION_MODEL,
+                max_tokens=200,
+                system=[
+                    {
+                        "type": "text",
+                        "text": SYSTEM_PROMPT,
+                        "cache_control": {"type": "ephemeral"},
+                    }
+                ],
+                messages=[{"role": "user", "content": content}],
+            )
+        except Exception as exc:  # noqa: BLE001
+            # Heuristic: 400 with "image" or "url" message → treat as
+            # blocked URL fetch and let caller fall back to base64.
+            msg = str(exc).lower()
+            if "image" in msg and ("url" in msg or "fetch" in msg or "400" in msg):
+                raise _ImageURLBlocked(str(exc)) from exc
+            raise
+
+        # `resp.content` is a list of content blocks; concatenate text.
+        parts: list[str] = []
+        for block in resp.content:
+            text = getattr(block, "text", None)
+            if text:
+                parts.append(text)
+        return "\n".join(parts).strip()
+
+
+class _ImageURLBlocked(Exception):
+    """Raised when Anthropic's URL-mode fetcher rejects an image."""
+
+
+_VALID = {"yes-direct", "partial", "no", "indoor"}
+
+
+def _parse_verdict(text: str) -> tuple[str, str, str]:
+    """Extract the first-line verdict + justification from Sonnet's reply."""
+    if not text:
+        return ("error", "empty response", "")
+    first, _, rest = text.partition("\n")
+    first = first.strip().lower()
+    # legacy "yes-distant" → coerce to "no" per plan.md §5.2
+    if first == "yes-distant":
+        return ("no", "coerced from yes-distant", text)
+    if first in _VALID:
+        return (first, rest.strip(), text)
+    # tolerant match: pick the first valid token in the response
+    for token in _VALID:
+        if token in text.lower():
+            return (token, rest.strip(), text)
+    return ("error", f"unparsable verdict: {text[:120]}", text)
+
+
+def has_yes_direct(evidence: dict[str, Any] | None) -> bool:
+    if not evidence:
+        return False
+    return any(p.get("verdict") == "yes-direct" for p in evidence.get("photos", []))
+
+
+def evidence_signature(listing: Listing, *, model: str = VISION_MODEL) -> dict[str, Any]:
+    """Stable signature used for vision-cache invalidation (plan.md §6.1)."""
+    return {
+        "description": listing.description,
+        "photos": sorted(listing.photos),
+        "model": model,
+    }
+
+
+def evidence_is_reusable(listing: Listing, prior: dict[str, Any] | None) -> bool:
+    """Return True iff `prior` evidence can be reused for `listing`."""
+    if not prior:
+        return False
+    if prior.get("model") != VISION_MODEL:
+        return False
+    photos = prior.get("photos") or []
+    if any(p.get("verdict") == "error" for p in photos):
+        return False
+    prior_urls = sorted(p.get("url") for p in photos if p.get("url"))
+    if prior_urls != sorted(listing.photos):
+        return False
+    if prior.get("description_snapshot", listing.description) != listing.description:
+        return False
+    return True
+
+
diff --git a/serbian_realestate/search.py b/serbian_realestate/search.py
new file mode 100644
index 0000000..2a194f7
--- /dev/null
+++ b/serbian_realestate/search.py
@@ -0,0 +1,305 @@
+"""Serbian real-estate search CLI.
+
+See plan.md for the full design. Quick summary:
+
+    uv run --directory serbian_realestate python search.py \\
+        --location beograd-na-vodi --min-m2 70 --max-price 1600 \\
+        --view any \\
+        --sites 4zida,nekretnine,kredium,halooglasi,cityexpert,indomio \\
+        --verify-river --verify-max-photos 3 \\
+        --output markdown
+
+Defaults are picked to be safe-by-default: vision is OFF unless
+--verify-river is passed, and `--view any` (not strict).
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+import logging
+import sys
+import time
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from filters import Criteria, apply_criteria, combined_verdict, text_river_match, verdict_passes_strict
+from scrapers.base import Listing, read_state, write_state
+from scrapers.cityexpert import CityExpertScraper
+from scrapers.fzida import FZidaScraper
+from scrapers.halooglasi import HaloOglasiScraper
+from scrapers.indomio import IndomioScraper
+from scrapers.kredium import KrediumScraper
+from scrapers.nekretnine import NekretnineScraper
+from scrapers.river_check import (
+    RiverChecker,
+    VISION_MODEL,
+    evidence_is_reusable,
+)
+
+ROOT = Path(__file__).resolve().parent
+STATE_DIR = ROOT / "state"
+CACHE_DIR = STATE_DIR / "cache"
+
+SCRAPER_REGISTRY = {
+    "4zida": FZidaScraper,
+    "nekretnine": NekretnineScraper,
+    "kredium": KrediumScraper,
+    "cityexpert": CityExpertScraper,
+    "indomio": IndomioScraper,
+    "halooglasi": HaloOglasiScraper,
+}
+
+DEFAULT_SITES = "4zida,nekretnine,kredium,halooglasi,cityexpert,indomio"
+
+logger = logging.getLogger("serbian_realestate")
+
+
+# ---- CLI ------------------------------------------------------------------
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--location", default="beograd-na-vodi", help="Profile slug from config.yaml")
+    p.add_argument("--min-m2", type=float, default=None, help="Minimum floor area in m²")
+    p.add_argument("--max-price", type=float, default=None, help="Maximum monthly rent in EUR")
+    p.add_argument(
+        "--view",
+        choices=("any", "river"),
+        default="any",
+        help="`river` strictly filters to verified river views",
+    )
+    p.add_argument(
+        "--sites",
+        default=DEFAULT_SITES,
+        help=f"Comma-separated portal list (default: {DEFAULT_SITES})",
+    )
+    p.add_argument("--verify-river", action="store_true", help="Run Sonnet vision verification")
+    p.add_argument("--verify-max-photos", type=int, default=3, help="Cap photos per listing")
+    p.add_argument(
+        "--output",
+        choices=("markdown", "json", "csv"),
+        default="markdown",
+        help="Output format",
+    )
+    p.add_argument("--max-listings", type=int, default=30, help="Cap per-site listing count")
+    p.add_argument("--config", type=Path, default=ROOT / "config.yaml", help="Path to config.yaml")
+    p.add_argument("--log-level", default="INFO")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    logging.basicConfig(
+        level=getattr(logging, args.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+    )
+
+    profiles = _load_profiles(args.config)
+    if args.location not in profiles:
+        logger.error("Unknown location %r — available: %s", args.location, ", ".join(profiles))
+        return 2
+    profile = profiles[args.location]
+    logger.info("Profile: %s — %s", args.location, profile.get("display_name", args.location))
+
+    sites = [s.strip() for s in args.sites.split(",") if s.strip()]
+    unknown = [s for s in sites if s not in SCRAPER_REGISTRY]
+    if unknown:
+        logger.error("Unknown sites: %s — available: %s", unknown, list(SCRAPER_REGISTRY))
+        return 2
+
+    criteria = Criteria(
+        min_m2=args.min_m2,
+        max_price_eur=args.max_price,
+        location_keywords=tuple(profile.get("location_keywords", [])),
+    )
+
+    started = time.time()
+    listings = _run_scrapers(sites, profile, args)
+    logger.info("Collected %d total listings in %.1fs", len(listings), time.time() - started)
+
+    listings = apply_criteria(listings, criteria)
+    logger.info("%d listings after criteria filter", len(listings))
+
+    # Annotate text-side river match before vision (cheap, drives cache invalidation logic).
+    for l in listings:
+        l.extra["text_river_match"] = text_river_match(
+            f"{l.title}\n{l.location or ''}\n{l.description}"
+        )
+
+    state_path = STATE_DIR / f"last_run_{args.location}.json"
+    prior_state = read_state(state_path)
+    prior_index = _index_prior_listings(prior_state)
+
+    # Reuse cached vision evidence where possible (plan.md §6.1).
+    listings_to_verify: list[Listing] = []
+    if args.verify_river:
+        for l in listings:
+            cached = prior_index.get(l.key, {}).get("river_evidence")
+            if evidence_is_reusable(l, cached):
+                l.river_evidence = cached
+            else:
+                listings_to_verify.append(l)
+
+        if listings_to_verify:
+            logger.info(
+                "Vision-verifying %d listings (model=%s, max_photos=%d)",
+                len(listings_to_verify),
+                VISION_MODEL,
+                args.verify_max_photos,
+            )
+            try:
+                with RiverChecker() as checker:
+                    checker.verify_listings(
+                        listings_to_verify, max_photos=args.verify_max_photos
+                    )
+            except RuntimeError as exc:
+                logger.error("River check disabled: %s", exc)
+
+    # Compute combined verdict for every listing (whether verified or not).
+    for l in listings:
+        photo_verdicts = (
+            [p.get("verdict", "error") for p in (l.river_evidence or {}).get("photos", [])]
+            if args.verify_river
+            else []
+        )
+        l.river_verdict = combined_verdict(l.extra.get("text_river_match"), photo_verdicts)
+
+    # Strict view filter
+    if args.view == "river":
+        listings = [l for l in listings if verdict_passes_strict(l.river_verdict or "none")]
+        logger.info("%d listings pass strict --view river filter", len(listings))
+
+    # Diff: tag new listings against prior run.
+    for l in listings:
+        l.is_new = l.key not in prior_index
+
+    _write_state(state_path, args, listings)
+    _emit_output(args.output, args.location, listings, profile)
+    return 0
+
+
+def _load_profiles(config_path: Path) -> dict[str, Any]:
+    if not config_path.exists():
+        raise FileNotFoundError(f"config not found: {config_path}")
+    with config_path.open(encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    return data.get("profiles", {})
+
+
+def _run_scrapers(sites: list[str], profile: dict[str, Any], args: argparse.Namespace) -> list[Listing]:
+    out: list[Listing] = []
+    seen: set[tuple[str, str]] = set()
+    for name in sites:
+        cls = SCRAPER_REGISTRY[name]
+        scraper = cls(
+            location_profile=profile,
+            location_slug=args.location,
+            max_listings=args.max_listings,
+            cache_dir=CACHE_DIR / name,
+        )
+        try:
+            for listing in scraper.fetch():
+                if listing.key in seen:
+                    continue
+                seen.add(listing.key)
+                out.append(listing)
+        except Exception as exc:  # noqa: BLE001 — keep collecting from other sites
+            logger.warning("[%s] aborted scraper run: %s", name, exc)
+    return out
+
+
+def _index_prior_listings(state: dict[str, Any]) -> dict[tuple[str, str], dict[str, Any]]:
+    out: dict[tuple[str, str], dict[str, Any]] = {}
+    for entry in state.get("listings", []):
+        key = (entry.get("source"), entry.get("id"))
+        if all(key):
+            out[key] = entry
+    return out
+
+
+def _write_state(state_path: Path, args: argparse.Namespace, listings: list[Listing]) -> None:
+    payload = {
+        "settings": {
+            "location": args.location,
+            "min_m2": args.min_m2,
+            "max_price_eur": args.max_price,
+            "view": args.view,
+            "sites": args.sites,
+            "verify_river": args.verify_river,
+            "verify_max_photos": args.verify_max_photos,
+            "vision_model": VISION_MODEL,
+        },
+        "generated_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "listings": [asdict(l) for l in listings],
+    }
+    write_state(state_path, payload)
+
+
+# ---- output formatters ----------------------------------------------------
+
+
+def _emit_output(fmt: str, location: str, listings: list[Listing], profile: dict[str, Any]) -> None:
+    if fmt == "json":
+        print(json.dumps([asdict(l) for l in listings], indent=2, ensure_ascii=False))
+        return
+
+    if fmt == "csv":
+        buf = io.StringIO()
+        w = csv.writer(buf)
+        w.writerow(
+            ["new", "source", "id", "url", "title", "price_eur", "area_m2", "location", "river_verdict"]
+        )
+        for l in listings:
+            w.writerow(
+                [
+                    "1" if l.is_new else "",
+                    l.source,
+                    l.id,
+                    l.url,
+                    l.title,
+                    l.price_eur or "",
+                    l.area_m2 or "",
+                    l.location or "",
+                    l.river_verdict or "",
+                ]
+            )
+        sys.stdout.write(buf.getvalue())
+        return
+
+    # markdown (default)
+    print(f"# {profile.get('display_name', location)} — {len(listings)} listings\n")
+    if not listings:
+        print("_No listings matched the filters._")
+        return
+    print("| | Source | Title | €/mo | m² | Verdict | URL |")
+    print("|---|---|---|---|---|---|---|")
+    for l in listings:
+        new = "🆕" if l.is_new else ""
+        verdict = _verdict_emoji(l.river_verdict)
+        title = (l.title or "").replace("|", "\\|")[:80]
+        print(
+            f"| {new} | {l.source} | {title} | "
+            f"{int(l.price_eur) if l.price_eur else '—'} | "
+            f"{int(l.area_m2) if l.area_m2 else '—'} | {verdict} | {l.url} |"
+        )
+
+
+def _verdict_emoji(v: str | None) -> str:
+    return {
+        "text+photo": "⭐ text+photo",
+        "text-only": "📝 text-only",
+        "photo-only": "📷 photo-only",
+        "partial": "🌫 partial",
+        "none": "—",
+        None: "—",
+    }.get(v, v or "—")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())