feat(snipe): eBay trust scoring MVP — search, filters, enrichment, comps

Core trust scoring:
- Five metadata signals (account age, feedback count/ratio, price vs market,
  category history), composited 0–100
- CV-based price signal suppression for heterogeneous search results
  (e.g. mixed laptop generations won't false-positive suspicious_price)
- Expanded scratch/dent title detection: evasive redirects, functional problem
  phrases, DIY/repair indicators
- Hard filters: new_account, established_bad_actor
- Soft flags: low_feedback, suspicious_price, duplicate_photo, scratch_dent,
  long_on_market, significant_price_drop

Search & filtering:
- Browse API adapter (up to 200 items/page) + Playwright scraper fallback
- OR-group query expansion for comprehensive variant coverage
- Must-include (AND/ANY/groups), must-exclude, category, price range filters
- Saved searches with full filter round-trip via URL params

Seller enrichment:
- Background BTF /itm/ scraping for account age (Kasada-safe headed Chromium)
- On-demand enrichment: POST /api/enrich + ListingCard ↻ button
- Category history derived from Browse API categories field (free, no extra calls)
- Shopping API GetUserProfile inline enrichment for API adapter

Market comps:
- eBay Marketplace Insights API with Browse API fallback (catches 403 + 404)
- Comps prioritised in ThreadPoolExecutor (submitted first)

Infrastructure:
- Staging DB fields: times_seen, first_seen_at, price_at_first_seen, category_name
- Migrations 004 (staging tracking) + 005 (listing category)
- eBay webhook handler stub
- Cloud compose stack (compose.cloud.yml)
- Vue frontend: search store, saved searches store, ListingCard, filter sidebar

Docs:
- README fully rewritten to reflect MVP status + full feature documentation
- Roadmap table linked to all 13 Forgejo issues

CLAUDE.md

@@ -0,0 +1,97 @@
+# Snipe — Developer Context
+
+> eBay listing monitor with seller trust scoring and auction sniping.
+
+## Stack
+
+| Layer | Tech | Port |
+|-------|------|------|
+| Frontend | Vue 3 + Pinia + UnoCSS + Vite (nginx) | 8509 |
+| API | FastAPI (uvicorn, `network_mode: host`) | 8510 |
+| Scraper | Playwright + playwright-stealth + Xvfb | — |
+| DB | SQLite (`data/snipe.db`) | — |
+| Core | circuitforge-core (editable install) | — |
+
+## CLI
+
+```bash
+./manage.sh start|stop|restart|status|logs|open|build|test
+```
+
+## Docker
+
+```bash
+docker compose up -d          # start
+docker compose build api web  # rebuild after Python/Vue changes
+docker compose logs -f api    # tail API logs
+```
+
+`compose.override.yml` bind-mounts `./tests` and `./app` for hot reload.
+
+nginx proxies `/api/` → `172.17.0.1:8510` (Docker bridge IP — api uses host networking).
+
+## Critical Gotchas
+
+**Kasada bot protection:** eBay blocks `requests`, `curl_cffi`, headless Playwright, and all `/usr/` and `/fdbk/` seller profile pages. Only headed Chromium via Xvfb passes. `/itm/` listing pages DO load and contain a BTF (below the fold) seller card with "Joined {Mon} {Year}" — use this for account age enrichment.
+
+**Xvfb display counter:** Module-level `itertools.cycle(range(200, 300))` issues unique display numbers (`:200`–`:299`) per `_get()` call to prevent lock file collisions when multiple Playwright sessions run in parallel.
+
+**HTML cache:** 5-minute in-memory cache keyed by full URL. Prevents duplicate 15s Playwright scrapes within one session. Cleared on restart.
+
+**SQLite thread safety:** Each concurrent thread (search + comps run in parallel) must have its own `Store` instance — `sqlite3.connect()` is not thread-safe across threads. See `api/main.py`.
+
+**nginx rebuild gotcha:** nginx config is baked into the image at build time. After editing `docker/web/nginx.conf`, always `docker compose build web`.
+
+**Playwright imports are lazy:** `sync_playwright` and `Stealth` import inside `_get()` — not at module level — so the pure parsing functions (`scrape_listings`, `scrape_sellers`) can be imported on the host without Docker's browser stack installed.
+
+## DB Migrations
+
+Auto-applied by `Store.__init__()` via `circuitforge_core.db.run_migrations`.
+Migration files: `app/db/migrations/001_init.sql`, `002_buying_format.sql`, `003_nullable_account_age.sql`
+
+## Tests
+
+```bash
+# Host (no Docker needed — pure parsing tests)
+conda run -n job-seeker python -m pytest tests/ -v --ignore=tests/test_integration.py
+
+# In container
+./manage.sh test
+```
+
+48 tests. Scraper tests run on host thanks to lazy Playwright imports.
+
+## Trust Scoring Architecture
+
+```
+TrustScorer
+  ├── MetadataScorer   → 5 signals × 0–20 = 0–100 composite
+  │     account_age, feedback_count, feedback_ratio,
+  │     price_vs_market (vs sold comps), category_history
+  ├── PhotoScorer      → phash dedup (free); vision analysis (paid stub)
+  └── Aggregator       → composite score, red flags, hard filters
+```
+
+**Red flag sentinel gotcha:** `signal_scores` uses `None` for missing data; `clean` dict substitutes `None → 0` for arithmetic. Always check `signal_scores.get("key")` (not `clean["key"]`) when gating hard-filter flags — otherwise absent data fires false positives.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `api/main.py` | FastAPI endpoint — parallel search+comps, serialization |
+| `app/platforms/ebay/scraper.py` | Playwright scraper, HTML cache, page parser |
+| `app/trust/aggregator.py` | Composite score, red flags, hard filters |
+| `app/trust/metadata.py` | 5 metadata signals |
+| `app/db/store.py` | SQLite read/write (batch methods) |
+| `web/src/views/SearchView.vue` | Filter sidebar + results layout |
+| `web/src/stores/search.ts` | Pinia store — API calls, result state |
+| `web/src/components/ListingCard.vue` | Listing card + auction dim style |
+| `web/src/assets/theme.css` | Central theme (CSS custom properties) |
+
+## Pending Work
+
+- **Seller enrichment** — BTF `/itm/` scrape for `account_age_days` + `_ssn` search page scrape for `category_history_json` both implemented as a combined background daemon thread (`_trigger_scraper_enrichment`). For the API adapter, `enrich_sellers_shopping_api()` fills `account_age_days` inline via Shopping API `GetUserProfile` (app-level Bearer token, no user OAuth). Second search gets full scores. "Jump the queue" on-demand enrichment: `POST /api/enrich` + ↻ button on ListingCard.
+- **SSE/WebSocket live score push** — currently enriched data only appears on re-search. Future: background enrichment threads emit events via SSE or WebSocket; frontend updates scores live without re-search. Tracked: Circuit-Forge/snipe#1.
+- **"Connect eBay Account" OAuth** — Trading API `GetUser` returns `RegistrationDate` + `sellerFeedbackSummary.feedbackByCategory` for any public seller, but only with a **User Access Token** (OAuth Authorization Code flow). Defer until eBay OAuth is generalized across the menagerie. Tracked: Circuit-Forge/snipe#2.
+- **Scammer database + batch eBay Trust & Safety reporting** — local blocklist, batch report deep-links, CF community blocklist (cloud). Tracked: Circuit-Forge/snipe#4.
+- **Snipe scheduling** — configurable bid-time offset, human approval gate

docs/superpowers/specs/2026-03-25-snipe-circuitforge-core-design.md

@@ -0,0 +1,322 @@
+# Snipe MVP + circuitforge-core Extraction — Design Spec
+**Date:** 2026-03-25
+**Status:** Approved
+**Products:** `snipe` (new), `circuitforge-core` (new), `peregrine` (updated)
+
+---
+
+## 1. Overview
+
+This spec covers two parallel workstreams:
+
+1. **circuitforge-core extraction** — hoist the shared scaffold from Peregrine into a private, locally-installable Python package. Peregrine becomes the first downstream consumer. All future CF products depend on it.
+2. **Snipe MVP** — eBay listing monitor + seller trust scorer, built on top of circuitforge-core. Solves the immediate problem: filtering scam accounts when searching for used GPU listings on eBay.
+
+Design principle: *cry once*. Pay the extraction cost now while there are only two products; every product after this benefits for free.
+
+---
+
+## 2. circuitforge-core
+
+### 2.1 Repository
+
+- **Repo:** `git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core` (private)
+- **Local path:** `/Library/Development/CircuitForge/circuitforge-core/`
+- **Install method:** `pip install -e ../circuitforge-core` (editable local package; graduate to Forgejo Packages private PyPI at product #3)
+- **License:** BSL 1.1 for AI features, MIT for pipeline/utility layers
+
+### 2.2 Package Structure
+
+```
+circuitforge-core/
+  circuitforge_core/
+    pipeline/       # SQLite staging DB, status machine, background task runner
+    llm/            # LLM router: fallback chain, BYOK support, vision-aware routing
+    vision/         # Vision model wrapper — moondream2 (local) + Claude vision (cloud) [NET-NEW]
+    wizard/         # First-run onboarding framework, tier gating, crash recovery
+    tiers/          # Tier system (Free/Paid/Premium/Ultra) + Heimdall license client
+    db/             # SQLite base class, migration runner
+    config/         # Settings loader, env validation, secrets management
+  pyproject.toml
+  README.md
+```
+
+### 2.3 Extraction from Peregrine
+
+The following Peregrine modules are **extracted** (migrated from Peregrine, not net-new):
+
+| Peregrine source | → Core module | Notes |
+|---|---|---|
+| `app/wizard/` | `circuitforge_core/wizard/` | |
+| `scripts/llm_router.py` | `circuitforge_core/llm/router.py` | Path is `scripts/`, not `app/` |
+| `app/wizard/tiers.py` | `circuitforge_core/tiers/` | |
+| SQLite pipeline base | `circuitforge_core/pipeline/` | |
+
+**`circuitforge_core/vision/`** is **net-new** — no vision module exists in Peregrine to extract. It is built fresh in core.
+
+**Peregrine dependency management:** Peregrine uses `requirements.txt`, not `pyproject.toml`. The migration adds `circuitforge-core` to `requirements.txt` as a local path entry: `-e ../circuitforge-core`. Snipe is greenfield and uses `pyproject.toml` from the start. There is no requirement to migrate Peregrine to `pyproject.toml` as part of this work.
+
+### 2.4 Docker Build Strategy
+
+Docker build contexts cannot reference paths outside the context directory (`COPY ../` is forbidden). Both Peregrine and Snipe resolve this by setting the compose build context to the parent directory:
+
+```yaml
+# compose.yml (snipe or peregrine)
+services:
+  app:
+    build:
+      context: ..                          # /Library/Development/CircuitForge/
+      dockerfile: snipe/Dockerfile
+```
+
+```dockerfile
+# snipe/Dockerfile
+COPY circuitforge-core/ ./circuitforge-core/
+RUN pip install -e ./circuitforge-core
+COPY snipe/ ./snipe/
+RUN pip install -e ./snipe
+```
+
+In development, `compose.override.yml` bind-mounts `../circuitforge-core` so local edits to core are immediately live without rebuild.
+
+---
+
+## 3. Snipe MVP
+
+### 3.1 Scope
+
+**In (v0.1 MVP):**
+- eBay listing search (Browse API + Seller API)
+- Metadata trust scoring (free tier)
+- Perceptual hash duplicate photo detection within a search result set (free tier)
+- Faceted filter UI with dynamic, data-driven filter options and sliders
+- On-demand search only
+- `SavedSearch` DB schema scaffolded but monitoring not wired up
+
+**Out (future versions):**
+- Background polling / saved search alerts (v0.2)
+- Photo analysis via vision model — real vs marketing shot, EM bag detection (v0.2, paid)
+- Serial number consistency check (v0.2, paid)
+- AI-generated image detection (v0.3, paid)
+- Reverse image search (v0.4, paid)
+- Additional platforms: HiBid, CT Bids, AuctionZip (v0.3+)
+- Bid scheduling / snipe execution (v0.4+)
+
+### 3.2 Repository
+
+- **Repo:** `git.opensourcesolarpunk.com/Circuit-Forge/snipe` (public discovery layer)
+- **Local path:** `/Library/Development/CircuitForge/snipe/`
+- **License:** MIT (discovery/pipeline), BSL 1.1 (AI features)
+- **Product code:** `CFG-SNPE`
+- **Port:** 8506
+
+### 3.3 Tech Stack
+
+Follows Peregrine as the reference implementation:
+
+- **UI:** Streamlit (Python)
+- **DB:** SQLite via `circuitforge_core.db`
+- **LLM/Vision:** `circuitforge_core.llm` / `circuitforge_core.vision`
+- **Tiers:** `circuitforge_core.tiers`
+- **Containerisation:** Docker + `compose.yml`, managed via `manage.sh`
+- **Python env:** `conda run -n job-seeker` (shared CF env)
+
+### 3.4 Application Structure
+
+```
+snipe/
+  app/
+    platforms/
+      __init__.py         # PlatformAdapter abstract base class
+      ebay/
+        adapter.py        # eBay Browse API + Seller API client
+        auth.py           # OAuth2 client credentials token manager
+        normaliser.py     # Raw API response → Listing / Seller schema
+    trust/
+      __init__.py         # TrustScorer orchestrator
+      metadata.py         # Account age, feedback, price vs market, category history
+      photo.py            # Perceptual hash dedup (free); vision analysis (paid, v0.2+)
+      aggregator.py       # Weighted composite score + red flag extraction
+    ui/
+      Search.py           # Main search + results page
+      components/
+        filters.py        # Dynamic faceted filter sidebar
+        listing_row.py    # Listing card with trust badge + red flags + error state
+    db/
+      models.py           # Listing, Seller, Search, TrustScore, SavedSearch schemas
+      migrations/
+    wizard/               # First-run onboarding (thin wrapper on core wizard)
+    snipe/                # Bid engine placeholder (v0.4)
+  manage.sh
+  compose.yml
+  compose.override.yml
+  Dockerfile
+  pyproject.toml
+```
+
+### 3.5 eBay API Credentials
+
+eBay Browse API and Seller API require OAuth 2.0 app-level tokens (client credentials flow — no user auth needed, but a registered eBay developer account and app credentials are required).
+
+**Token lifecycle:**
+- App token fetched at startup and cached in memory with expiry
+- `auth.py` handles refresh automatically on expiry (tokens last 2 hours)
+- On token fetch failure: search fails with a user-visible error; no silent fallback
+
+**Credentials storage:** `.env` file (gitignored), never hardcoded.
+```
+EBAY_CLIENT_ID=...
+EBAY_CLIENT_SECRET=...
+EBAY_ENV=production   # or sandbox
+```
+
+**Rate limits:** eBay Browse API — 5,000 calls/day (sandbox), higher on production. Completed sales comps results are cached in SQLite with a 6-hour TTL to avoid redundant calls and stay within limits. Cache miss triggers a fresh fetch; fetch failure degrades gracefully (price vs market signal skipped, score noted as partial).
+
+**API split:** `get_seller()` uses the eBay Seller API (different endpoint, same app token). Rate limits are tracked separately. The `PlatformAdapter` interface does not expose this distinction; it is an internal concern of the eBay adapter.
+
+### 3.6 Data Model
+
+**`Listing`**
+```
+id, platform, platform_listing_id, title, price, currency,
+condition, seller_id, url, photo_urls (JSON), listing_age_days,
+fetched_at, trust_score_id
+```
+
+**`Seller`**
+```
+id, platform, platform_seller_id, username,
+account_age_days, feedback_count, feedback_ratio,
+category_history_json, fetched_at
+```
+
+**`TrustScore`**
+```
+id, listing_id, composite_score,
+account_age_score, feedback_count_score, feedback_ratio_score,
+price_vs_market_score, category_history_score,
+photo_hash_duplicate (bool),
+photo_analysis_json (paid, nullable),
+red_flags_json, scored_at, score_is_partial (bool)
+```
+
+**`MarketComp`** *(price comps cache)*
+```
+id, platform, query_hash, median_price, sample_count, fetched_at, expires_at
+```
+
+**`SavedSearch`** *(schema scaffolded in v0.1; monitoring not wired until v0.2)*
+```
+id, name, query, platform, filters_json, created_at, last_run_at
+```
+
+**`PhotoHash`** *(perceptual hash store for cross-search dedup, v0.2+)*
+```
+id, listing_id, photo_url, phash, first_seen_at
+```
+
+### 3.7 Platform Adapter Interface
+
+```python
+class PlatformAdapter:
+    def search(self, query: str, filters: SearchFilters) -> list[Listing]: ...
+    def get_seller(self, seller_id: str) -> Seller: ...
+    def get_completed_sales(self, query: str) -> list[Listing]: ...
+```
+
+Adding HiBid or CT Bids later = new adapter, zero changes to trust scorer or UI.
+
+### 3.8 Trust Scorer
+
+#### Metadata Signals (Free)
+
+Five signals, each scored 0–20, equal weight. Composite = sum (0–100).
+
+| Signal | Source | Red flag threshold | Score 0 condition |
+|---|---|---|---|
+| Account age | eBay Seller API | < 30 days | < 7 days (also hard-filter) |
+| Feedback count | eBay Seller API | < 10 | < 3 |
+| Feedback ratio | eBay Seller API | < 95% | < 80% with count > 20 |
+| Price vs market | Completed sales comps | > 30% below median | > 50% below median |
+| Category history | Seller past sales | No prior electronics sales | No prior sales at all |
+
+**Hard filters** (auto-hide regardless of composite score):
+- Account age < 7 days
+- Feedback ratio < 80% with feedback count > 20
+
+**Partial scores:** If any signal's data source is unavailable (API failure, rate limit), that signal contributes 0 and `score_is_partial = True` is set on the `TrustScore` record. The UI surfaces a "⚠ Partial score" indicator on affected listings.
+
+#### Photo Signals — Anti-Gotcha Layer
+
+| Signal | Tier | Version | Method |
+|---|---|---|---|
+| Perceptual hash dedup within result set | **Free** | v0.1 MVP | Compare phashes across all listings in the current search response; flag duplicates |
+| Real photo vs marketing shot | **Paid / Local vision** | v0.2 | Vision model classification |
+| Open box + EM antistatic bag (proof of possession) | **Paid / Local vision** | v0.2 | Vision model classification |
+| Serial number consistency across photos | **Paid / Local vision** | v0.2 | Vision model OCR + comparison |
+| AI-generated image detection | **Paid** | v0.3 | Classifier model |
+| Reverse image search | **Paid** | v0.4 | Google Lens / TinEye API |
+
+**v0.1 dedup scope:** Perceptual hash comparison is within the current search result set only (not across historical searches). Cross-session dedup uses the `PhotoHash` table and is a v0.2 feature. Photos are not downloaded to disk in v0.1 — hashes are computed from the image bytes in memory during the search request.
+
+### 3.9 Tier Gating
+
+Photo analysis features use `LOCAL_VISION_UNLOCKABLE` (analogous to `BYOK_UNLOCKABLE` in Peregrine's `tiers.py`) — they unlock for free-tier users who have a local vision model (moondream2) configured. This is distinct from BYOK (text LLM key), which does not unlock vision features.
+
+| Feature | Free | Paid | Local vision unlock |
+|---|---|---|---|
+| Metadata trust scoring | ✓ | ✓ | — |
+| Perceptual hash dedup (within result set) | ✓ | ✓ | — |
+| Photo analysis (real/marketing/EM bag) | — | ✓ | ✓ |
+| Serial number consistency | — | ✓ | ✓ |
+| AI generation detection | — | ✓ | — |
+| Reverse image search | — | ✓ | — |
+| Saved searches + background monitoring | — | ✓ | — |
+
+Locked features are shown (disabled) in the filter sidebar so free users see what's available. Clicking a locked filter shows a tier upgrade prompt.
+
+### 3.10 UI — Results Page
+
+**Search bar:** keywords, max price, condition selector, search button. Sort: trust score (default), price ↑/↓, listing age.
+
+**Filter sidebar** — all options and counts generated dynamically from the result set. Options with 0 results are hidden (not greyed):
+- Trust score — range slider (min/max from results); colour-band summary (safe/review/skip + counts)
+- Price — min/max text inputs + market avg/median annotation
+- Seller account age — min slider
+- Feedback count — min slider
+- Positive feedback % — min slider
+- Condition — checkboxes (options from data: New, Open Box, Used, For Parts)
+- Photo signals — checkboxes: Real photo, EM bag visible, Open box, No AI-generated (locked, paid)
+- Hide if flagged — checkboxes: New account (<30d), Marketing photo, >30% below market, Duplicate photo
+- Shipping — Free shipping, Local pickup
+- Reset filters button
+
+**Listing row (happy path):** thumbnail · title · seller summary (username, feedback count, ratio, tenure) · red flag badges · trust score badge (colour-coded: green 80+, amber 50–79, red <50) · `score_is_partial` indicator if applicable · price · "Open eBay ↗" link. Left border colour matches score band.
+
+**Listing row (error states):**
+- Seller data unavailable: seller summary shows "Seller data unavailable" in muted text; affected signals show "–" and partial score indicator is set
+- Photo URL 404: thumbnail shows placeholder icon; hash dedup skipped for that photo
+- Trust scoring failed entirely: listing shown with score "?" badge in neutral grey; error logged; "Could not score this listing" tooltip
+
+**Hidden results:** count shown at bottom ("N results hidden by filters · show anyway"). Clicking reveals them in-place at reduced opacity.
+
+---
+
+## 4. Build Order
+
+1. **circuitforge-core** — scaffold repo, extract wizard/llm/tiers/pipeline from Peregrine, build vision module net-new, update Peregrine `requirements.txt`
+2. **Snipe scaffold** — repo init, Dockerfile, compose.yml (parent context), manage.sh, DB migrations, wizard first-run, `.env` template
+3. **eBay adapter** — OAuth2 token manager, Browse API search, Seller API, completed sales comps with cache
+4. **Metadata trust scorer** — all five signals, aggregator, hard filters, partial score handling
+5. **Perceptual hash dedup** — in-memory within-result-set comparison
+6. **Results UI** — search page, listing rows (happy + error states), dynamic filter sidebar
+7. **Tier gating** — lock photo signals, `LOCAL_VISION_UNLOCKABLE` gate, upsell prompts in UI
+
+---
+
+## 5. Documentation Locations
+
+- Product spec: `snipe/docs/superpowers/specs/2026-03-25-snipe-circuitforge-core-design.md` *(this file)*
+- Internal copy: `circuitforge-plans/snipe/2026-03-25-snipe-circuitforge-core-design.md`
+- Roadmap: `Circuit-Forge/roadmap` issues #14 (snipe) and #21 (circuitforge-core)
+- Org-level context: `/Library/Development/CircuitForge/CLAUDE.md`