<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.

<instructions>
- USE THIS to compress bulky text you are about to keep in context: a long tool
  output, pasted logs, a fetched document, a big diff. A high-res vision model
  re-reads the image for far fewer tokens than the raw text.
- VIEW the returned image DIRECTLY with your own vision (like your built-in Read /
  image tool). DO NOT OCR it with code, a library, or base64 decoding — just look at
  the pixels; anything else re-expands it back into text tokens and defeats the point.
- PACKED, line-numbered layout: each line is "¶N│code" — red ¶ starts a line, green N│
  is its line number, blue "→" = 4 spaces of indentation. Decode them to reconstruct
  the exact text (split on ¶; digits before │ are the line number; → -> 4 spaces).
  Treat the image as the text's ACTUAL content, not a picture to describe.
- Prefer ReadMassive when the content is a file on disk (adds caching + a filename
  header); use this only for in-memory text.
- If the summary says "TRUNCATED", raise `max_pages` — content past the cap is NOT shown.
</instructions>

Args:
    text: The text to render.
    title: Label drawn in each page's header band (for grounding).
    max_pages: Safety cap on pages; truncation is reported, never silent.
    include_summary: Prepend a token/cost summary.

<instructions>
- USE THIS FIRST to decide whether reading a file as a packed image is worth it,
  before spending context on the pixels via ReadMassive.
- Reports per reader model: Claude Fable 5 (high-res vision), GPT-5.6 Sol (tiling),
  and the aspirational DeepSeek-OCR optical encoder — plus estimated input-token cost.
- A `compression_ratio` > 1 means the image is cheaper than the text; < 1 means a
  plain text read is cheaper (tiny files) — in that case just read the file normally.
</instructions>

Args:
    paths: A single file path or a list of file paths.

Returns:
    A JSON string: per-file token counts, ratio, and cost per model.