ReadMassive

<how_it_works>
Each page is a square image (kept small enough that the reader does NOT downscale it,
so the tiny font stays crisp) filled edge-to-edge with the file's characters — no
wasted whitespace. Whitespace is encoded as two tinted marker glyphs so it costs
almost nothing; you MUST decode them to recover the exact original text.
</how_it_works>

<symbols>
Each source line is shown as  ¶<number>│<code>  :
- red "¶"   = the START of a source line. (A visual row edge is NOT a line break —
              only "¶" is; a long line simply wraps onto the next row until the next "¶".)
- green "N│" = that line's LINE NUMBER, ending with "│". Use it to cite file:line.
- blue "→"  = exactly 4 SPACES of indentation. One "→" per 4 spaces ("→→" = 8); any
              leftover 1-3 spaces are literal.
- Every other glyph is the file's literal character.
RECONSTRUCT: split the stream on "¶"; in each piece the digits before "│" are the
line number and the rest is the code; replace each "→" with 4 spaces. BLANK lines are
omitted — a gap in the line numbers (e.g. 12 then 15) means those lines (13, 14) were
blank. Content flows left-to-right, top-to-bottom, wrapping to fill every row.
</symbols>

<how_to_read>
- VIEW the returned image pages DIRECTLY with your own vision — the same way your
  built-in Read / image-viewing tool shows you a PNG. You are a vision model; just
  LOOK at the pixels and read the text off them.
- DO NOT try to OCR the image with code, an image/vision library, a subprocess, or by
  decoding the base64 by hand. That defeats the entire purpose (it re-expands the
  content back into text tokens) and is slower and less accurate than simply looking.
  If your harness surfaces the page as a file path or attachment, open it with your
  existing Read/image tool — do not write a script to parse it.
- Treat the image as the file's ACTUAL content. Read the glyphs, decode the symbols
  above, and reason about the code/text exactly as if you had read the raw file — do
  NOT merely describe the picture.
- The header bar names the file and repeats this legend.
- Every line carries its own green "N│" line number, so you can cite file:line and
  plan edits directly from the image — you do NOT need a separate text read first.
</how_to_read>

<when_to_use>
CHOOSE ReadMassive when ALL hold:
  1. the reader is a HIGH-RESOLUTION vision model (Claude Fable 5, Opus 4.8, Sonnet 5)
     — it reads the dense square page at native resolution;
  2. the file is non-trivial (roughly >800 tokens) OR you are loading MANY files at
     once — that is where the token saving outweighs the image's fixed overhead.
Highest-value cases: reading/understanding or reviewing large source files, logs,
JSON, generated/minified code, lockfiles, docs; surveying a whole codebase in one
call; long sessions that would otherwise exhaust the context window. Line numbers are
included, so this is fine to use even when you intend to edit afterwards.

PREFER A NORMAL TEXT READ when ANY hold:
  - the file is small (a few hundred tokens) — the image costs MORE than the text
    (the summary says "NOTE: ... CHEAPER" when this happens);
  - the reader is GPT-5.6 Sol or any model that downscales images to a small short
    edge (it may misread this density), or a non-vision model.
</when_to_use>

<optimal_strategy>
- Pass MANY paths in ONE call to survey a codebase cheaply — files render concurrently
  and are cached by path+mtime, so unchanged re-reads are free.
- Call ReadMassiveEstimate first when unsure whether a specific file is worth imaging.
- If a summary says "TRUNCATED", raise max_pages_per_file or split the file — content
  past the cap is NOT shown, never silently guessed.
</optimal_strategy>

Args:
    paths: A single file path or a list of file paths.
    max_pages_per_file: Safety cap on image pages per file; truncation past this is
        reported, never silent.
    include_summary: Prepend a one-line token/cost summary before each file.

Returns:
    Interleaved text summaries and PNG image content, in path order.