# Read Manual

> File pagination, truncation and long-line recovery: `next_offset` continuation, `line_truncated`, default/hard-cap limits, and when to switch to bash/grep/sed instead. Use when ordinary `file.read` cannot expose complete content.

- Skill: `lingtai-ai/read-manual` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lingtai-ai/read-manual`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lingtai-ai/read-manual/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lingtai-ai (https://skillmd.com/u/lingtai-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lingtai-ai/read-manual

---


# Read depth

This is `file-manual`'s nested reference for read depth, not a separate action. Load it
for a large/complete read, a capped or spilled result, or
`line_truncated`; routine small reads can use the schema directly. After the
one-time manual lookup, resume the ordinary read; repeating the same manual
call is an error loop.

## Caps and bounded windows

The ordinary per-call `max_chars` budget is **100 000** characters. The runtime
hard ceiling is **200 000**; a smaller positive Host cap lowers the effective
ceiling. Larger requests are clamped; File exposes no setting to raise it. A read-level cap returns `truncated=true`; the runtime ceiling may
instead spill a result before it reaches the model. The effective cap appears as
`cap_chars` when read pagination truncates.

For an unknown or large file, start with a narrow `limit` (for example 100–200)
and an explicit `offset`/`max_chars`. To inspect cheap metadata first (not a
`read(dry_run=true)` mode):

```bash
python - <<'PY'
from pathlib import Path
p = Path('/path/to/file')
count = longest = 0
with p.open('r', encoding='utf-8') as f:
    for count, line in enumerate(f, 1):
        longest = max(longest, len(line))
print({'bytes': p.stat().st_size, 'lines': count, 'longest_chars': longest})
PY
```

## Complete reads

`truncated` means the character cap cut the requested window, not that the file
has more lines. For complete stable-file reads, stop only past `total_lines`;
handle errors, spills and partial physical lines before consuming content:

```python
offset = 1
while True:
    result = file(action="read", input={"file_path": path, "offset": offset,
        "limit": 200, "max_chars": None}, reasoning="page through the file")
    if result.get("status") in ("error", "spilled") or result.get("line_truncated"):
        raise RuntimeError("Use targeted processing; this is not a complete page")
    process(result["content"])
    offset = result.get("next_offset", offset + result["lines_shown"])
    if offset > result["total_lines"]:
        break
```

Truncated results also report `cap_chars`, `returned_chars`,
`requested_offset`, `requested_limit`, `last_returned_line`, and
`remaining_lines_estimate`; use them to detect gaps or an unexpectedly narrow
window. `next_offset` is the next physical line, so this loop has no overlap.

`line_truncated=true` is different: one physical line exceeded the cap, so the
result contains only its bounded prefix and `next_offset` skips to the next
line. The hidden tail cannot be recovered by another `read`; inspect that line
with targeted `sed`, `awk`, or `grep` instead.

## Spill recovery

If the runtime returns `status="spilled"`, inspect its `spill_path` artifact and
its `original_char_count`; a `preview` is not complete content. If the artifact
is unavailable or the result is still too large, repeat with a smaller
`limit`/`max_chars` or process the artifact with `bash`/`grep`/Python. Do not
interpret a spill or a capped page as the whole file.