# Reading long documents

Inspect first, search for specific terms, then follow the returned read options to get surrounding context. Outlines and bookmarks are hints; a search miss does not prove absence.

## CLI

- Inspect: `betterfilings document inspect --file report.html --json`
- Search: `betterfilings document search --file report.html --queries liquidity --json`
- Continue HTML text: `betterfilings document extract --file report.html --text --text-offset 0 --text-limit 12000`
- Read selected PDF text: `betterfilings document extract --file report.pdf --pages 12,13 --text-limit 12000`
- Render one local PDF page to PNG when layout matters: `betterfilings document render --file report.pdf --page 12 --output page-12.png`

Use `--artifact KEY` with a filing ID instead of `--file` for automatic acquisition. Follow `nextTextOffset` until the selected scope is complete.

Here is a local PDF walkthrough. Run the search first and inspect search.json. The following extract/render commands assume the illustrative hit shown below; replace page 12 and offset 340 with your actual returned values before running them. Run the continuation command only when nextTextOffset is non-null:

```sh
betterfilings document search --file report.pdf --queries liquidity --json > search.json
betterfilings document extract --file report.pdf --pages 12 --text-offset 340 --text-limit 12000 --json > extract-1.json
betterfilings document extract --file report.pdf --pages 12 --text-offset RETURNED_NEXT_TEXT_OFFSET --text-limit 12000 --json > extract-2.json
betterfilings document render --file report.pdf --page 12 --output page-12.png --json
```

The following search fragment is illustrative of processor output, not a claim about `report.pdf`:

```json
{
  "query": "liquidity",
  "start": 340,
  "end": 349,
  "provenance": { "page": 12 },
  "readOptions": { "pages": [12], "textOffset": 340, "textLimit": 12000 }
}
```

Copy the returned `readOptions.pages`, `readOptions.textOffset`, and `readOptions.textLimit` into the first extract command; the numbers above only show the mapping. If extraction returns a non-null `data.nextTextOffset`, substitute that number for `RETURNED_NEXT_TEXT_OFFSET` and keep the same pages. The returned `provenance.page` is the page locator for optional local rendering. Rendering saves the whole selected page; inspect that PNG with an image-capable tool when layout matters.

## Hosted MCP

Use `filing_inspect`, `document_search`, and `filing_extract`; poll unfinished work with `filing_job_get`. Follow returned `nextCall` and `contentNextCall` unchanged. Hosted extraction reads selected PDF pages or an HTML section/text range. Hosted PDF rendering is not exposed, and hosted OCR is unavailable. Corpus-wide full-text search is unavailable.