# Exotic Vehicle Scout — Implementation Notes

Specific implementation details for the Apex Track Experience vehicle database cron job.

## Database

**Location:** `/root/portal-mockup/vehicles.json` (dev/mockup copy) and `/var/www/static/vehicles.json` (live, served via core.itpropartner.com/vehicles.json)

**Schema:** `{Make: {Model: {Year: HP, ...}, ...}}`
- Makes are top-level keys (capitalized: "Ferrari", "Mercedes-AMG")
- Models are sub-keys (capitalized: "296 Speciale", "Mustang GTD")
- Years are string keys (not integers): `{"2025": 819, "2026": 819}`
- Years span from 2015 onward (the database covers 2015+ per initial requirement)

**Duplicates exist:** There are TWO copies — `/root/portal-mockup/vehicles.json` (flat format with single-line years, ~234 lines, simpler) and `/root/docker/docuseal/data/vehicles.json` (pretty-printed, ~2,277 lines, comprehensive). The DocuSeal copy is the canonical one.

## De-duplication Check Pattern

In Python:
```python
import json
v = json.load(open('/root/portal-mockup/vehicles.json'))

def is_in_db(make, model):
    """Check if a make+model combination exists in the vehicle database."""
    if make in v:
        models = v[make]
        if model in models:
            return True
        # Also check partial matches (e.g., 'Mustang GTD' vs 'Mustang GT')
        matches = [m for m in models.keys() if model.lower() in m.lower()]
        if matches:
            return True
    return False
```

For partial matches, be precise: "Corvette ZR1X" vs "Corvette ZR1" — these are DIFFERENT models. Use python to list ALL models under a make and manually review ambiguous cases.

## Prior-Report Cross-Reference

Use `session_search(query="exotic-vehicle-scout", limit=5, sort="newest")` to find prior cron runs. Each run delivers a full report with a table of findings. Extract those findings and check each one against the live DB:

```python
# For each prior report's claimed new-find list:
for item in prior_findings:
    still_missing = not is_in_db(item['make'], item['model'])
    # If still missing, include in the "accumulated" section
```

## Key Sources for Vehicle Research

- **Exa Search (MCP via `web_search_exa`)** — best single source for niche/boutique brands (Zenvo, Denza, McMurtry). Semantic search catches what keyword search misses. Returns publication dates for recency filtering. Set `numResults=10`. Use natural-language page descriptions, not keyword lists.
- **Goodwood Festival of Speed entry lists** (July, annual) — catches boutique/hypercar debuts
- **motor1.com** — good factory-style coverage of all industry events
- **CarThrottle** — catches niche/meme-worthy debuts (Ruf B8, Apollo Evo)
- **roadandtrack.com / thedrive.com** — performance-focused journalism
- **Manufacturer press sites** — for official HP figures (ferrari.com, pagani.com, audi-mediacenter.com, lamborghini.com/news, ford.com/performance)
- **carscoops / carnewschina** — Chinese-market vehicles (BYD/Denza, Xiaomi, Nio)
- **caranddriver.com/future-cars** — aggregated future vehicle guide

## Known Model Name Variations

When checking the DB, you need to account for inconsistencies in model naming:
- "Corvette Stingray" != "Stingray" — always use full manufacturer model names
- "M5" in DB currently ends at 2024/617hp — the 2025+ G90 generation (717hp) needs separate entries
- "GT 63 S 4-Door" is in the DB but "GT 63 S E Performance Coupe" (2-door, 805hp) is NOT
- "Ioniq 5 N" vs "IONIQ 5 N" — capitalization differs but python dict check is case-sensitive; check `.lower()` on both sides

## Apex Track Experience Event

- Date: September 19, 2026
- Invites: Any vehicle 500+ HP regardless of body style or drivetrain
- Registration form: DocuSeal-based, fetches make/model from vehicles.json dropdown
- Known gaps: "custom/homebuilt" option needed for prototype/low-volume builds

## Database Corrections (Known)

- Aston Martin Valhalla: DB says 998 hp, actual is 1,064 hp (1,079 PS)
- BMW M5 (G90): 2025+ entries at 717 hp are missing (DB ends at 2024/617hp)
- Polestar 6 (884 hp, 2026): missing — DB only has Polestar 1