# Hermes Owner Hunter Workflow

This zip contains the owner-hunter workflow for `multi-source-owner-evidence` / `owner-first-v4`.

The owner-hunter path does this:

1. Turns a niche and location into owner-visible search angles.
2. Finds business seeds from public sources.
3. Scrapes public websites, directories, social pages, articles, and profile pages.
4. Proves a real person owner with source evidence.
5. Searches that owner's public contact trail.
6. Exports CSV, JSON, run JSON, and a portfolio report.

## Requirements

- Node.js 18.17 or newer.
- Python 3.9-3.12 for scraping environments.
- Python 3.12 or newer is preferred for the optional OSINT tool environment.
- `git`, `npm`, and internet access for package dependencies and browser runtimes.
- A MiniMax API key is recommended for owner-agent planning and repair guidance.

## Setup

```bash
cd Hermes-Owner-Hunter-Workflow
cp .env.empty .env
npm install
bash scripts/bootstrap_tools.sh
```

Open `.env` and fill at least:

```bash
MINIMAX_API_KEY=your-key-here
```

Optional LinkedIn modes need either:

```bash
HERMES_LINKEDIN_LI_AT=
HERMES_LINKEDIN_SESSION_JSON=
```

Leave those blank unless you already have valid authorized LinkedIn session values.

## Run Owner Hunter

Run directly from the command line:

```bash
npm run owner:run -- --niche "nail salon" --location "Austin, TX" --target 5
```

Or use the input file:

```bash
npm run owner:run -- --input examples/owner-hunter-input.empty.json
```

The empty input file is `examples/owner-hunter-input.empty.json`. Fill `niche` and `location` before using it.

## Outputs

Each run writes exports under:

```text
exports/<run-id>/
```

The export folder contains:

- `leads.csv` with qualified owner leads.
- `leads.json` with structured lead data.
- `portfolio.md` with a client-facing report.
- `run.json` with full evidence, counters, failures, and agent decisions.

## Included Tools

The zip includes project wrappers plus vendored source for:

- `zohaibbashir/Google-Maps-Scrapper` for business seed discovery.
- `D4Vinci/Scrapling` for public page extraction.
- `joeyism/linkedin_scraper` for optional authenticated LinkedIn profile scraping.
- `speedyapply/JobSpy` for lightweight LinkedIn job/company corroboration.
- `josephlimtech/linkedin-profile-scraper-api` for optional LinkedIn profile API mode.
- `spinlud/py-linkedin-jobs-scraper` for optional LinkedIn job scraping.
- `theHarvester` and `Photon` for website/domain evidence expansion.
- `Maigret`, `Sherlock`, and `Social Analyzer` for public username/profile expansion.
- `Reacher` as a reserved owner email verification integration.

The zip does not include local virtual environments, browser binaries, `node_modules`, saved run data, logs, or private `.env` secrets. `scripts/bootstrap_tools.sh` builds those runtime dependencies on the target machine from the packaged tool sources where possible.

## Dashboard Note

The included browser dashboard is useful for the broader Hermes project, but its current start button is wired to the non-owner `lead-scraper` path. For this exported package, use `npm run owner:run` as the canonical owner-hunter entrypoint.

## Safety Rules

- Use public business and public profile data only.
- Do not guess personal contact data.
- Treat business phone/email as seed evidence unless it is tied back to the proven owner.
- Review outputs before any outbound campaign.
