> ## Documentation Index
> Fetch the complete documentation index at: https://atlas.rebuildingus.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run discovery with Scout

> Run URLs, files, article corpus recovery, and place-and-issue discovery.

Scout runs discovery locally and stores the results on your computer. You can
review them before deciding whether anything should sync to Atlas.

When you run by place and issue, Scout first checks the local article corpus for
usable source text and turns those articles into normal source-linked entries. If
the target has not been reached and search is connected, Scout then finds more
public sources.

## Known URLs

Pass a public source when you already know what to inspect:

```bash theme={null}
scout run https://example.org/article
```

Add a prompt to focus extraction:

```bash theme={null}
scout run \
  --prompt "Find tenant organizers and legal aid groups mentioned on this page" \
  https://example.org/article
```

## Files Of URLs

Use one URL per line:

```bash theme={null}
scout run --file urls.txt
```

Use standard input for scripts:

```bash theme={null}
cat urls.txt | scout run --file -
```

## Structured Public Resources

Scout can read CSV, TSV, pipe-delimited text, and ZIP files that contain one of
those formats. Use this for public bulk resources where each row already
contains people, places, roles, dates, or other civic context.

Header rows are detected automatically:

```bash theme={null}
scout run https://example.gov/public-roster.csv
```

For headerless files, pass the column names in order:

```bash theme={null}
scout run \
  --structured-columns "id,name,role,organization,city,state,source_url" \
  https://example.gov/public-roster.zip
```

Structured runs still create ordinary local Scout runs, pages, entries, source
URLs, and source context. Review the people sample before syncing:

```bash theme={null}
scout entries list \
  --type person \
  --random \
  --unique-names \
  --limit 100 \
  --format json
```

Structured public records may be historical. A row from an old archive is useful
evidence, but it should not be treated as current contact, employment, role, or
location information unless the source date and row context support that claim.

## Place And Issue Runs

Run against a place and issue set:

```bash theme={null}
scout run \
  --location "Las Vegas, NV" \
  --issues housing_affordability,public_transit \
  --target-count 250
```

If you have already built an article corpus with `scout articles crawl` or
`scout articles import`, this command can extract entries from those stored
articles without a search key.

Connect search when you also want Scout to find new public sources:

```bash theme={null}
scout search connect
```

Then run the same command:

```bash theme={null}
scout run \
  --location "Austin, TX" \
  --issues housing_affordability
```

Use `--refresh` when you want Scout to ignore cached fetches and extractions.

## Crawl Controls

Scout can follow same-domain links from seed pages:

```bash theme={null}
scout run https://example.org --follow-links
```

Limit crawl depth and pages per seed:

```bash theme={null}
scout run https://example.org \
  --max-link-depth 1 \
  --max-pages-per-seed 10
```

Bypass cached fetch and extraction results:

```bash theme={null}
scout run https://example.org --refresh
```

## Headless Browser Fallback

Scout may launch a headless Chromium browser through Playwright when a public
source looks useful but normal HTML fetching cannot read enough text. This is a
bounded fallback for JavaScript-rendered pages, not the primary fetch path.

Defaults:

| Setting                         | Default |
| ------------------------------- | ------: |
| Browser fallback enabled        |  `true` |
| Browser render attempts per run |     `8` |
| Concurrent browser renders      |     `1` |

Scout does not open visible browser windows. Disable the fallback:

```bash theme={null}
scout config set scraper.browser_fallback_enabled false
```

Inspect active limits:

```bash theme={null}
scout config show
```

## Progress And Sync

Use default progress for interactive work. Use quiet mode for scripts:

```bash theme={null}
scout run --quiet https://example.org
```

Sync after a run:

```bash theme={null}
scout run --sync https://example.org
```

For review-first workflows, run locally first, then sync from the saved run.

## Inspect A People Sample

Use run-scoped entry listing to review the people Scout found before syncing:

```bash theme={null}
scout entries list \
  --run-id RUN_ID \
  --run-id ANOTHER_REVIEWED_RUN_ID \
  --type person \
  --random \
  --unique-names \
  --limit 100 \
  --format json
```

JSON output includes the local run id, description, issue areas, source URLs,
and source context fields so reviewers can check why each person belongs in the
result set. Repeat `--run-id` to combine reviewed runs while leaving discarded
or retry runs out of the sample. Add `--unique-names` when overlapping sources
may mention the same person.

## Export Entries

Use `scout export entries` when you need a file instead of an interactive
sample. JSONL is the default and works well for large handoffs:

```bash theme={null}
scout export entries \
  --run-id RUN_ID \
  --type person \
  --unique-names \
  --limit 100000 \
  --output people.jsonl
```

Export CSV when the next review step is a spreadsheet:

```bash theme={null}
scout export entries \
  --run-id RUN_ID \
  --type person \
  --unique-names \
  --format csv \
  --output people.csv
```

Exports include local entry ids, run ids, descriptions, issue areas, source
URLs, source context, dataset markers, source keys, source dates, and local
creation timestamps. Keep those fields attached when sharing or auditing the
file.

## Verify Counts And Currentness

Use `entries stats` before a large export or sync:

```bash theme={null}
scout entries stats \
  --require-type person \
  --min-source-backed 100000 \
  --min-unique-people 100000
```

`--min-source-backed` checks rows with provenance. `--min-unique-people` checks
exact unique person keys so duplicate runs do not inflate the count.

Passing those checks does not certify currentness. Before syncing or exporting a
people list, inspect source dates and source context for the relevant run. If a
source is an archive, old filing, historical roster, or stale page, treat its
entries as historical evidence rather than current outreach data.