# Search Workflow

Use this reference when running dealer discovery so the agent behaves like a lead researcher rather than a blind crawler.

## Default Funnel

1. Load existing workbook links first unless the user asks for `--no-excel`.
2. Search high-signal channel terms and collect page/company/place URLs only.
3. Normalize and de-duplicate links across the current run and existing workbook.
4. Score candidates before opening homepages, company About pages, Google Maps place details, or merchant websites.
5. Reject or hold candidates that look like OEM local branches or official brand-country pages.
6. Save a candidate preview JSON for human review.
7. Deep scrape only candidates above the score threshold or explicitly selected by the user. For Google Maps, deep scrape the place detail and then public merchant website pages for email evidence. For local auto websites, deep scrape source listings and merchant websites, but write only real companies, not category/listing/search/add-company pages.
8. Write to Excel only when the user asks for confirmed output or passes `--write-excel`.

## Morocco-Wide Discovery

Default to `摩洛哥全国` when the user asks for Moroccan dealers without naming a city. Use national channel keywords first, then city waves for large and small dealers. City waves are search coverage tools; do not assume the city field is known unless the page itself confirms it.

The active Facebook search script uses national dealer/importer/showroom/group queries plus these city waves: Casablanca, Rabat, Marrakech, Tanger, Fes, Agadir, Meknes, Oujda, Kenitra, Tetouan, Nador, and Safi.

## Candidate Scoring

Prioritize candidates with these signals:

- Independent dealer, distributor, importer, showroom, automotive group, used-car, or commercial-vehicle channel terms.
- China-brand or commercial-vehicle brand appears inside a dealer/group context, not as the whole page identity.
- Import, multibrand, concessionnaire, groupe, showroom, stock, or used-car business terms.
- URL/page slug that looks like an automotive channel or Moroccan dealer.
- A candidate seen from more than one search query.

Down-rank or hold for manual review when these signals dominate:

- diagnostics, repair-only, spare parts, insurance, rental-only, personal profile, add-company pages, platform category pages, directory-only pages, or unrelated page names.
- weak URL slug with no automotive channel signal.
- already present in the workbook.

## OEM Brand-Branch Rejection

Reject candidates before deep scraping when the company/page identity is just an automotive brand plus country or official marker. Examples:

- `BYD Maroc`, `BYD Morocco`, `bydmaroc`
- `BMW Maroc`, `bmwmaroc`
- `JAC Motors Maroc`, `jacmotorsmaroc`
- `Jetour Maroc`, `jetour-maroc`
- `Chery Maroc`, `Volkswagen Maroc`, `Mercedes-Benz Maroc`

Set `recommended_action` to `skip_brand_branch` or keep it as a low-priority preview item. Do not write these pages to the outreach workbook as customers.

Use official brand pages only as clue sources: inspect them lightly only if needed to identify the actual independent distributor, dealer group, showroom, or importer behind the brand. For example, keep `La Continentale Auto` if it distributes Geely/KIA/Fiat because the entity is a dealer; reject `Geely Maroc` if the entity is only the brand-country page.



## Local Auto Website Funnel

Use `scripts/scraper/search_auto_websites.py` for local automotive websites and directories. The default source set is OtoMoto, Wandaloo, Kerix, Kompass, Maroc Annuaire, and Telecontact.

1. Connect to the already-open AdsPower profile.
2. Visit source entry pages and run limited source-specific searches.
3. Keep only candidates that point to a real company, importer, dealer, showroom, fleet/rental operator, or commercial-vehicle channel.
4. Extract public phones/emails from directory text, source listing pages, `mailto:` links, and merchant website Contact/About pages.
5. Score batch-sales fit from multiple-branch, stock, `professionnel`, `importation`, `véhicules neufs`, `location`, `utilitaire`, MPV, microvan, truck, bus, fleet, or distributor signals.
6. Write to `汽车网站精选线索` only when `--write-excel` is used. This sheet has `来源网站`; duplicates within the sheet must merge sources and append evidence to `备注`.

If a source only produces category pages or low-quality pages in the current run, record that in the JSON report but do not write those pages as customer rows.

## Output Rules

Candidate preview output should include:

- `url`
- `source_queries`
- `score`
- `score_reasons`
- `risk_flags`
- `recommended_action`

Deep-scraped records may then be written to the workbook. Candidate previews should not be written to the outreach workbook as final leads. Local auto website records must include `来源网站` when written to `汽车网站精选线索`. For Google Maps, do not fabricate emails; leave `邮箱` blank when no public email is found and explain that in `备注`.