tiny-context — efficient file tools by AVRG3

Compare two files and report what changed — works outside git and on PDF/DOCX/PPTX/XLSX/CSV (tables get added/removed/changed row counts + samples; documents diff on extracted text). USE WHEN: "what changed between v1 and v2", "compare these spreadsheets", or "which orders/issues/inventory records changed between two API exports despite shuffled rows" (records mode, explicit key). PREFER OVER: reading both files and comparing in your head; git diff when the files aren't in git or aren't plain text. git diff is fine for tracked plain-text files. DOES NOT: fetch snapshots, infer IDs, remember prior calls, diff directories, merge, or interpret semantic meaning. Records mode supports JSON/JSONL/NDJSON only: 16 MiB and 100000 records per file, nesting 64; rejects duplicate IDs/object keys and numbers that would round. Quote high-precision numbers. Nested array order remains significant. EXAMPLE: diff_files({ a: "/abs/v1/report.docx", b: "/abs/v2/report.docx" }) · diff_files({ a: "/abs/a.csv", b: "/abs/b.csv", mode: "summary" }) Records EXAMPLE: diff_files({ a: "/abs/yesterday.json", b: "/abs/today.json", mode: "records", key: ["/id"], fields: ["/status", "/price"] }) RETURNS: summary/unified: capped sections or diff. records: exact added/removed/changed/unchanged counts within the declared fields, bounded before/after previews and an optional full JSONL report. Capped previews are labeled. Savings line compares response bytes against both whole inputs, not billed tokens or an optimized script.

Extract values with locations: regex, jq, built-in kinds, or reusable document profiles. USE WHEN: emails/URLs/IDs; batch recurring labeled forms using a saved profile (up to 100 txt/md/docx/text-layer PDFs). PREFER OVER: repeated reads/field calls. Read/Grep for one small text file; reuse an existing correct script. DOES NOT: train, infer templates, OCR, verify meaning or guarantee cost savings. Profiles recheck exact anchors/unique labels; mismatches need review. Save rules once with Write/editor; docs/DOCUMENT_PROFILES.md. EXAMPLE: extract({paths:["/abs/*.docx"],profile:"/abs/profile.json",out:"/abs/results.jsonl"}) · extract({path:"/abs/a.pdf",kind:"emails"}) RETURNS: bounded matches; profiles: counts, values/locations, review reasons, optional full local report. Ledger excludes setup/model/schema costs.

Structural outline of a file or directory WITHOUT its contents: headings (md/docx), function/class signatures (code), sheets + column headers + row counts (xlsx), slide titles (pptx), page count + outline + first line per page (pdf), size-annotated tree (directory). USE WHEN: "what's in this file/folder", "outline this document", "which functions are in here", "what sheets and columns does this spreadsheet have", or before deciding what to read. PREFER OVER: reading an entire large document just to learn its structure, or ls+grep+head loops for directories. If the question or section is already known, query_file/read_section directly; mapping is optional. Read is fine — and sufficient — for a small plain-text file (< ~20 KB): just Read it; do not call file_map on a file you have already read. DOES NOT: return contents (use read_section), search inside files (use query_file), or parse code with a real parser (signatures are regex-based, so unusual syntax may be missed). EXAMPLE: file_map({ path: "/abs/project/src", depth: 2 }) · file_map({ path: "/abs/contract.pdf" }) RETURNS: an outline with locations (line / page / sheet / slide / ¶) that read_section accepts, counts and sizes, then a savings line.

Ranked passages matching a query inside one or many files (txt/md/code/pdf/docx/pptx/xlsx/csv), each with its exact location, so the follow-up read is surgical. USE WHEN: "where does the contract discuss termination", "does this deck mention pricing", "find every place the spec talks about retries", "which of these docs cover X". PREFER OVER: Read/cat of a LARGE file (> ~20 KB) just to find one passage; Grep for PDFs/DOCX/PPTX/XLSX (Grep can't open them) and for ranking across many files. Read is fine — and sufficient — for a small plain-text file: if you have already Read a file, you have everything this tool would return; do not call it on that file. Grep is fine for an exact string in one plain-text file. DOES NOT: add anything to a file you have already read, use embeddings/semantic search (BM25 keyword ranking + exact-phrase boost), return whole files, or search binary formats other than the ones listed. EXAMPLE: query_file({ path: "/abs/contract.pdf", query: "termination notice", max_results: 5 }) RETURNS: ranked hits "#1 file · page 12, line 3 (Heading > Sub)" with a short excerpt each, files/passages scanned, skipped files with reasons, then a savings line.

Run SQL (DuckDB) over a CSV/TSV/Parquet/XLSX file without the data ever entering your context. The file is table `t`. USE WHEN: "total sales by region", "how many rows have a negative total", "top 10 customers", "which columns exist and what types", any aggregate/filter/join-free question about a table. PREFER OVER: Read/cat/head of the table, writing a pandas/awk script, or loading rows to count them. Read is fine for a tiny table (< ~50 rows) you need verbatim. LIMITS: one read-only SELECT or DESCRIBE; no SQL file/network access, COPY, extensions, or multiple statements. Input/export cap 64 MB, DuckDB memory 256 MB, worker deadline 15s (timeout_ms up to 60s). Explicit out creates a new CSV without overwriting. DOES NOT: modify the file, join several files (one file = one table), or return more than 200 rows in-context (use `out` to write the full result to CSV). EXAMPLE: query_table({ path: "/abs/sales.csv", sql: "SELECT region, SUM(total) FROM t GROUP BY 1" }) · query_table({ path: "/abs/sales.csv", sql: "DESCRIBE t" }) RETURNS: a markdown table of up to max_rows rows, column names/types, total result rows, the written file path when `out` is set, then a savings line. SQL errors include the table's columns and types so the next attempt succeeds.

The surgical read: returns ONLY the located section of a file — a heading's section, a page range, a line range, DOCX paragraphs, an XLSX sheet range, or PPTX slides — capped at max_tokens. USE WHEN: you know where the content is (from the task, file_map or query_file) and need the actual text of just that part; reading pages of a PDF, a sheet of a workbook, a section of a long doc. PREFER OVER: Read/cat of the whole file when you need a slice, and always for PDF/DOCX/XLSX/PPTX (Read can't slice them). Read is fine for small plain-text files you need in full. DOES NOT: search (use query_file), read whole large files (cap 8000 tokens — narrow the locator instead), or render images. EXAMPLE: read_section({ path: "/abs/contract.pdf", locator: { pages: "3-5" } }) · read_section({ path: "/abs/spec.md", locator: { heading: "Installation" } }) RETURNS: the section text with line/page/¶ markers, word count, a "truncated at N — continue with …" note when capped, then a savings line.

Structure of a log file in ~300 tokens: repeated-message clusters (numbers/ids/paths masked) with counts, first/last time and one sample each, level counts, and a rate timeline — from 80k lines without reading them. USE WHEN: "what's causing the 5xx spike", "summarize this log", "what errors are in here", "when did the failures start", before grepping. PREFER OVER: tail/head/grep loops and Read on any log over a few hundred lines; run this first, then Grep/extract for the specific message. Read is fine for a log under ~100 lines. DOES NOT: follow files live, parse binary logs, correlate across files, or explain root cause (it shows structure and timing so you can). EXAMPLE: summarize_log({ path: "/abs/logs/app.log", focus: "errors", since: "2h" }) RETURNS: totals + time span + level counts, a bucketed timeline (all vs. focused lines), top clusters "#1 ×812 ERROR 10:41→10:52 <template>" with a sample line, then a savings line.

Deterministic checks on a file you (or someone) just wrote: JSON/YAML/XML parse, CSV column-count consistency, JSON Schema conformance, broken relative links/anchors/images in Markdown/HTML, encoding/BOM/NUL/mixed line endings. USE WHEN: after generating or editing JSON/CSV/YAML/HTML/Markdown, "is this file valid", "check the links in this README", before handing a file to another tool or person. PREFER OVER: re-reading your own output to eyeball it, or setting up a linter for one check. A language toolchain (tsc, eslint, pytest) is the right tool for source code — this does not run it. DOES NOT: validate code syntax, check external URLs (use verify.check_links), or fix anything. EXAMPLE: validate_file({ path: "/abs/out/data.json", schema: "/abs/schema.json" }) · validate_file({ path: "/abs/README.md" }) RETURNS: "PASS" with the checks run, or "FAIL" with line-numbered problems and what to do, then a savings line.