octocode-scraping - Claude MCP Skill

# Octocode Scraping

Flow: `FRAME → POLICY → ROUTE → FETCH → CORPUS → SEARCH → CITE → RECOVER`.

FRAME before the first fetch: fix target URL/domain, goal, depth, and output shape — vague ask → `references/user-inputs.md`.

Defaults: one public URL, `--mode html`, omit `--provider` (keyless `cdp`→`direct`), session `.octocode/tmp/scrape/{sessionId}`, compact stdout. Search corpus before refetch. Live interaction → chrome-devtools on one port, then `har-ingest` + `corpus-run` into the same session. Ask before auth, hosted spend, crawl widen, CAPTCHA/MFA, destructive actions. Cite paths + URL metadata — not raw dumps.

Stop when: two same-class failures (report evidence, route tried, sanitized status, next approval); hosted `403` (wrong key or credits gone — status only, no retry); CAPTCHA/MFA, auth wall, or cookie/profile transfer needed; still blocked after one `cdp` try (ask before `--provider scrapingant`); personal data, form submits, purchases, sends, deletes, or account changes in scope; the saved corpus already proves the claim (cite it, do not refetch); crawl widen before `reports/summary.md` is useful. Recovery table: `references/failure-recovery.md`.

## Route (pick one)
| Need | Do | Skip |
|---|---|---|
| Vague scrape | `--mode html`, omit `--provider` | markdown / auto hosted |
| See auto pick | `scripts/provider-check.mjs` | guessing |
| Fetch/crawl | `scripts/fetch.mjs` | deprecated `scrapingant-fetch` |
| Corpus on disk | `corpus-inspect` → find helpers → `corpus-run` | blind refetch |
| Live click/DOM/auth | chrome-devtools | `--provider cdp` alone for interaction |
| Page health | chrome measure + `measure-query` | hosted scrape for scores |
| CDP → corpus | `scripts/har-ingest.mjs --from-cdp-dir` | new sessionId |
| Prove field | `scripts/corpus-run.mjs --regex\|--script` | reopen browser |
| Still blocked | evidence + ask → `--provider scrapingant` | silent spend |

## Scripts (Node, no install; every one takes `--help`)
| When | Run |
|---|---|
| fetch / crawl / extract a URL — the owner of every network call | `scripts/fetch.mjs --url <u> [--mode html] [--crawl --same-domain --max-pages <n>] [--no-raw]` |
| want the fetch plus an immediate corpus brief in one shot | `scripts/fetch-and-brief.mjs --url <u>` (wraps `fetch.mjs` → `corpus-inspect.mjs`) |
| before routing or hosted spend: which provider auto-wins, credits left | `scripts/provider-check.mjs [--provider <p>]`, `scripts/provider-usage.mjs` — sanitized, never prints the key |
| read a saved session first, then search it | `scripts/corpus-inspect.mjs --session-dir <d> [--page <n>]`, then `scripts/corpus-find.mjs --session-dir <d> --query <t>` |
| pull static DOM, assets, or graph paths out of the corpus (live DOM → chrome-devtools) | `scripts/dom-find.mjs --kind form/button/table`, `scripts/resource-list.mjs --kind asset/external`, `scripts/graph-navigate.mjs --from <nodeId>` — each with `--session-dir <d>` |
| prove one field locally instead of reopening a browser | `scripts/corpus-run.mjs --session-dir <d> --roots cdp,extracts --regex <re>` (or `--script <file>`, `--concat-parts`) |
| bridge chrome-devtools artifacts into this session, or hand a packet back | `scripts/har-ingest.mjs --session-dir <d> --from-cdp-dir <run>`; reverse with `--export-packet` |
| need field names before an extraction | `scripts/schema-helper.mjs --intent "extract pricing and features"` |
| an old transcript uses the legacy names | deprecated shims `scripts/scrapingant-fetch.mjs`, `scripts/scrapingant-check.mjs`, `scripts/scrapingant-usage.mjs` forward to `fetch.mjs` / `provider-check.mjs` / `provider-usage.mjs` — call the new names |
| editing or extending a script | shared modules in `scripts/lib/` (`providers` registry, `client` fetch, `corpus`, `analyzers`, `extractors`, `text`, `args`, `bridge`); env/key resolution vendored in `scripts/octocode-config.mjs`; JSON contracts in `scripts/schemas/` |

Full flags, roles, and the library map: read `scripts/README.md` before adding a flag or a vendor.

## References
| When | Load |
|---|---|
| frame a vague scope | `references/user-inputs.md` |
| legal/safety/privacy policy | `references/scraping-policy.md` |
| cost / keyless vs hosted route | `references/route-selection.md` |
| provider registry / add a vendor | `references/providers.md` |
| hosted API, after approval | `references/scrapingant.md` |
| search a saved session corpus | `references/session-corpus.md` |
| site graph / navigation / workflows | `references/website-analysis.md` |
| stdout and corpus file shapes | `references/data-contract.md` |
| extract quality and citations | `references/extraction-quality.md` |
| live browser bridge playbook | `references/browser-scraping.md` |
| blocked, thin, or oversized results | `references/failure-recovery.md` |