@gavin-hu/my-pi-agent 0.15.1 → 0.16.0

package/extensions/{document → file-read}/README.md

@@ -1,6 +1,6 @@
-# document — read local PDF, DOCX, DOC, ODT, RTF, and XLSX files as text
+# file-read — read local PDF, DOCX, DOC, ODT, RTF, and XLSX files as text
 
-`document` adds a `read_doc` tool that extracts plain text from a local `.pdf`,
+`file-read` adds a `read_doc` tool that extracts plain text from a local `.pdf`,
 `.docx`, `.doc`, `.odt`, `.rtf`, or `.xlsx` file, paged with `startIndex` /
 `maxChars`. Extraction runs in process through JavaScript libraries (`unpdf`,
 `mammoth`, `word-extractor`, `fflate` + `fast-xml-parser`, `rtf-parser`,
@@ -8,34 +8,30 @@
 the effective working directory with the same symlink-aware guard the built-in
 path tools use.
 
-## Tool rendering
-
-How the `read_doc` call and its result look in the transcript — the call line as a headline and the body indented under it:
-
-<img src="../../assets/tools/read_doc.png" alt="The read_doc tool's result: the call line and an indented body with the file path, format, size, and the extracted text preview" width="100%">
-
 ## Quickstart
 
 ```bash
-pi --extension ./extensions/document   # this extension only
+pi --extension ./extensions/file-read   # this extension only
 pi -e .                                # the package from this checkout
 pi install ./                          # install the package for a user
 ```
 
 The extraction libraries are ordinary dependencies, so a normal install brings
-them along. Then ask the model to read a document, or call the tool directly:
+them along. Then ask the model to read a document or a workbook, or call the
+tool directly:
 
 ```jsonc
 { "path": "docs/spec.pdf" }
 { "path": "docs/spec.pdf", "startIndex": 40000, "maxChars": 40000 }
+{ "path": "report.xlsx" }
 ```
 
 ## What it does
 
 - Extracts plain text from `.pdf`, `.docx`, `.doc`, `.odt`, `.rtf`, and `.xlsx`
   files for the model to read.
-- Pages long documents: when output is truncated, call again with the
-  `startIndex` named in the note.
+- Pages long files: when output is truncated, call again with the `startIndex`
+  named in the note.
 - Slices by code point, so CJK and emoji stay well-formed.
 - Reads only inside the effective working directory, resolving symlinks so a
   link cannot escape it.
@@ -47,6 +43,11 @@ them along. Then ask the model to read a document, or call the tool directly:
 `read_doc` — direct exposure, active by default, read-only, closed-world
 (no network).
 
+How the call and its result look in the transcript — the call line as a headline
+and the body indented under it:
+
+<img src="../../assets/tools/read_doc.png" alt="The read_doc tool's result: the call line and an indented body with the file path, format, size, and the extracted text preview" width="100%">
+
 | Parameter | Type | Meaning |
 |---|---|---|
 | `path` | string, required, 1–4096 chars | Path to a `.pdf`, `.docx`, `.doc`, `.odt`, `.rtf`, or `.xlsx`, relative to the working directory (or absolute inside it). |
@@ -67,7 +68,9 @@ Result (`details` / `structuredContent`):
 | `text` | The clean slice, without the header or truncation note. |
 
 The model-facing `content` is a header (`Path:`, `Format:`, `Size:`), a blank
-line, the slice, and a truncation note when applicable.
+line, the slice, and a truncation note when applicable. A workbook reads as one
+`[Sheet]` heading per worksheet followed by tab-separated rows, so the shape of
+the text says what the file was.
 
 Errors are thrown for: a missing or non-file path, a path outside the root, an
 unsupported extension (with a targeted hint for legacy `.xls`), a disabled
@@ -116,7 +119,7 @@ sanitized error path.
 
 ## Configuration
 
-The `document` section of the shared `bytefly.json`, loaded from
+The `file-read` section of the shared `bytefly.json`, loaded from
 `~/.pi/agent/bytefly.json` then `<cwd>/.pi/bytefly.json` (project wins), each
 merged over the defaults and clamped:
 
@@ -128,12 +131,13 @@ merged over the defaults and clamped:
 | `formats` | `{ "pdf": true, "docx": true, "doc": true, "odt": true, "rtf": true, "xlsx": true }` | — | Per-format on/off, merged over each registry entry's default; unknown keys are ignored. |
 
 ```jsonc
-// bytefly.json → "document"
+// bytefly.json → "file-read"
 { "maxChars": 80000, "extractTimeoutMs": 60000, "formats": { "docx": false } }
 ```
 
-`doc.json` is not read, and neither is the old per-extension `document.json`;
-run `bun run config:migrate` to move a `document.json` into the shared file.
+The section was named `document` before this extension was renamed; the loader
+reads only `file-read`, and `bun run config:migrate` renames an existing
+`document` section and moves a legacy `document.json` into it.
 
 ## Security
 
@@ -145,14 +149,14 @@ run `bun run config:migrate` to move a `document.json` into the shared file.
   parser receives.
 - **Size-capped and time-bounded.** Files larger than `maxFileBytes` are rejected
   before any parser runs, and a parser that outlasts `extractTimeoutMs` is
-  abandoned so the turn is not held open by one document.
+  abandoned so the turn is not held open by one file.
 - **No subprocesses.** Extraction never spawns a process, so it grants no
   privileges beyond the current process.
-- **Untrusted text.** Extracted document text is treated as untrusted: it is
-  returned as model-facing `content` and data. The collapsed transcript draws
-  only a sanitized summary; the expanded transcript draws a sanitized,
-  line-capped preview (`PREVIEW_LINES`). Control characters are stripped before
-  a theme colour is applied, so raw document bytes never reach the terminal.
+- **Untrusted text.** Extracted text is treated as untrusted: it is returned as
+  model-facing `content` and data. The collapsed transcript draws only a
+  sanitized summary; the expanded transcript draws a sanitized, line-capped
+  preview (`PREVIEW_LINES`). Control characters are stripped before a theme
+  colour is applied, so raw file bytes never reach the terminal.
 - **Worktree guard.** Under the `worktree` extension, `read_doc` is in the
   worktree guard's path-tool map, so `blockReadEscapes` / `blockSymlinkEscapes`
   apply to it exactly as to the built-in `read`.
@@ -171,11 +175,11 @@ Each extractor builds a plain-text document from the format's bytes:
 | XLSX | `exceljs` | One `[Sheet]` heading per non-empty worksheet, then tab-separated rows. Dates and numbers use the workbook's displayed text; formulas show their computed value. Cell formatting is dropped. |
 
 The tool is pageable across the whole extracted text, so a word-processing
-document or workbook is read in the same `startIndex` / `maxChars` way as a PDF.
+document or a workbook is read in the same `startIndex` / `maxChars` way as a PDF.
 
 Each call is bounded by `extractTimeoutMs` (30 s by default). A parser that
 outlasts the deadline is abandoned — the read fails with the limit named, and a
-late result is discarded — so a pathological document cannot park the turn.
+late result is discarded — so a pathological file cannot park the turn.
 
 ## Supported formats
 
@@ -194,13 +198,13 @@ The format table in `formats.ts` is the single source of truth; the handler,
 config defaults, and error listing all derive from it.
 
 1. Add the extraction library to `dependencies` in `package.json`.
-2. Add `extensions/document/extract/<fmt>.ts` exporting a `DocExtractor` that
-   `await import(...)`s its library, reads the bytes with `readDocBytes`, and
+2. Add `extensions/file-read/extract/<fmt>.ts` exporting a `FormatExtractor` that
+   `await import(...)`s its library, reads the bytes with `readFormatBytes`, and
    normalizes the output. Keep the parsing in a pure, exported helper so it is
    testable without a real file.
-3. Add a `DocumentFormat` entry to `FORMATS` and widen the `id` union.
-4. Add `extract/<fmt>.test.ts` with a real minimal fixture, and extend
-   `formats.test.ts` / `config.test.ts`.
+3. Add a `ReadFormat` entry to `FORMATS` and widen the `id` union.
+4. Add the new extractor to `extract/extract.test.ts` with a real minimal
+   fixture, and extend `tool.test.ts` for format selection and config.
 5. Add a row to the tables above.
 
 `tool.ts`, `paging.ts`, and the config normalizer need no changes.
@@ -235,51 +239,63 @@ config defaults, and error listing all derive from it.
 
 | Aspect | Contract |
 |---|---|
-| Registration | `document(pi)` in `index.ts` calls `registerDocTool(pi)`, which registers `read_doc`. The factory only registers; no parser loads until a read needs it. |
+| Registration | `fileRead(pi)` in `index.ts` calls `registerReadTool(pi)`, which registers `read_doc`. The factory only registers; no parser loads until a read needs it. |
 | Tool | `read_doc`, direct exposure and active on registration (the defaults), default (`parallel`) execution, `annotations: { readOnlyHint: true, openWorldHint: false }`, TypeBox `parameters` and `outputSchema`, and `renderCall`/`renderResult` (reuse `context.lastComponent`; read `context.cwd` and `context.isError`). |
 | State | None persisted. Per-result state lives in the tool-result `details` / `structuredContent`; the renderer reads only that. |
 | Lifecycle | No `session_start` / `session_shutdown` hooks: each read imports a parser, runs it, and holds no long-lived resources. |
 | Host seams | `resolveEffectiveCwd` (`lib/env.ts`), `isInsideReal` / `realPathOfNearest` (`lib/path.ts`), `loadConfigSection` (`lib/config.ts`), `stripControlChars` / `sanitize` / `formatTokens` (`lib/format.ts`), `SEPARATORS` (`lib/tui/glyphs.ts`). |
-| Config | The `document` section of the shared `bytefly.json` via `loadConfigSection` (`~/.pi/agent`, `<cwd>/.pi`). |
+| Config | The `file-read` section of the shared `bytefly.json` via `loadConfigSection` (`~/.pi/agent`, `<cwd>/.pi`). |
 
 ## Design notes
 
-A separate tool rather than an overload of the built-in `read`: the worktree
+**A separate tool rather than an overload of the built-in `read`.** The worktree
 extension owns the built-in path tools and re-registers them, so overloading
-`read` would fight that machinery. A table-driven registry keeps future formats
-additive, and extracting in process means the tool works on any host without a
-per-format install step and without spawning a child process per read.
+`read` would fight that machinery. The tool also stays one tool for all six
+formats, the way Pi's `read` covers text and images: the split would be a choice
+the model can get wrong (and an extra entry in the worktree guard's path map) in
+exchange for prompt copy, while the workbook-specific guidance fits in one
+`promptGuidelines` bullet. A second tool becomes worth it only when it carries
+behaviour a document read must not have, such as reading named worksheets.
+
+**The name.** `document` stopped describing the job once XLSX joined the table:
+the extension reads any local file whose bytes the built-in `read` cannot decode,
+and `file-read` sits beside `file-browse` and `file-open`.
+
+**A table-driven registry** keeps future formats additive, and extracting in
+process means the tool works on any host without a per-format install step and
+without spawning a child process per read.
 
 **Parsers load lazily.** The extension registers on every session, so a static
 top-level import of `exceljs`, `mammoth`, and `unpdf` would tax every startup,
-whether or not a document is ever read. Each extractor therefore imports its
+whether or not a file is ever read. Each extractor therefore imports its
 library inside the call (`await import(...)`), matching `web-access`'s lazy
 `unpdf` import.
 
-**The XLSX format is rebuilt, not passed through.** `exceljs` exposes worksheets
-as objects; the extractor walks every worksheet and reassembles `[Sheet]` + tab
-rows so `read_doc`'s model-facing format is stable across extractor changes and
-every worksheet is included, not just the first.
+**The XLSX text is rebuilt, not passed through.** `exceljs` exposes worksheets as
+objects; the extractor walks every worksheet and reassembles `[Sheet]` + tab rows
+so the model-facing format is stable across extractor changes and every worksheet
+is included, not just the first.
 
-The renderer is unchanged and reuses `context.lastComponent` (`Text.setText`),
-binding the expand hint to `app.tools.expand`. Path shortening lives in
-`render.ts` (not `lib/`): `lib/` helpers are for two or more extensions, and the
-built-in-style `~`/boundary rule here is document-only. The result line
-deliberately omits the path: Pi stacks the call and result lines in one row, so
-repeating it would be pure duplication.
+The renderer reuses `context.lastComponent` (`Text.setText`), binding the expand
+hint to `app.tools.expand`. Path shortening lives in `render.ts` (not `lib/`):
+`lib/` helpers are for two or more extensions, and the built-in-style
+`~`/boundary rule here is this extension's only. The result line deliberately
+omits the path: Pi stacks the call and result lines in one row, so repeating it
+would be pure duplication.
 
 ## Files
 
 | File | Responsibility |
 |---|---|
 | `index.ts` | Factory; registers the tool. |
-| `formats.ts` | `DocumentFormat`, the `FORMATS` registry, `FormatId`, `detectFormat`, `supportedExtensions`, `unsupportedHint`. |
-| `tool.ts` | The tool definition, handler, path guard, extractor override seam, and renderer wiring. Re-exports `TOOL_NAME`. |
+| `formats.ts` | `ReadFormat`, the `FORMATS` registry, `FormatId`, `detectFormat`, `supportedExtensions`, `unsupportedHint`. |
+| `tool.ts` | The tool definition, handler, path guard, extractor override seam, and renderer wiring. |
 | `render.ts` | Theme-aware transcript formatting: call/result lines, `~` + OSC-8 path, expand hint, sanitized preview, and the shared rejection/error path. The call reuses `ToolCallText` (one line, middle clip); the result reuses `Text`. |
-| `schema.ts` | `TOOL_NAME`, `DocParams`, `DocOutput`, limits, result type. |
-| `config.ts` | `DocConfig`, registry-derived defaults, `normalizeConfig`, `loadConfig`, `isFormatEnabled`. |
-| `paging.ts` | `formatDoc`: code-point slicing and header/truncation formatting; `summarizeDoc`: the theme-free transcript summary. |
-| `extract/file.ts` | `DocFile` / `DocExtractor`, `readDocBytes` (abort-aware read), `normalizeBodyText`. |
+| `schema.ts` | `TOOL_NAME`, `ReadParams`, `ReadOutput`, limits, result type. |
+| `config.ts` | `ReadConfig`, registry-derived defaults, `normalizeConfig`, `loadConfig`, `isFormatEnabled`. |
+| `paging.ts` | `formatPage`: code-point slicing and header/truncation formatting; `summarizeRead`: the theme-free transcript summary. |
+| `deadline.ts` | `withDeadline`: abandons a parser that outlasts `extractTimeoutMs` and discards its late result. |
+| `extract/file.ts` | `ExtractInput` / `FormatExtractor`, `readFormatBytes` (abort-aware read), `normalizeBodyText`. |
 | `extract/vendor.d.ts` | Ambient types for `word-extractor` and `rtf-parser` (no bundled declarations). |
 | `extract/pdf.ts` | Adapter over the shared `lib/pdf.ts` seam, plus the PDF body normalization. |
 | `extract/docx.ts` | `mammoth` extractor. |
@@ -291,12 +307,12 @@ repeating it would be pure duplication.
 ## Testing
 
 ```bash
-bun test extensions/document
+bun test extensions/file-read
 ```
 
 Extractor tests run against real minimal files (`test/helpers/fixtures/documents.ts`
 builds a genuine PDF, DOCX, and ODT; XLSX is written with `exceljs`; legacy `.doc`
 reads the committed `files/legacy.doc`), so the libraries are exercised, not
 stubbed. `tool.test.ts` injects fake extractors for behavioural cases and reads a
-real PDF and a real `.doc` end to end; `test/helpers/fixtures/document.ts`
-provides the scratch root and an escape symlink.
+real PDF and a real `.doc` end to end; `test/helpers/fixtures/file-read.ts`
+provides the scratch root and an escape symlink.

package/extensions/{document → file-read}/config.ts

@@ -1,8 +1,8 @@
 /**
- * Configuration for the `document` extension.
+ * Configuration for the `file-read` extension.
  *
  * `formats` defaults are derived from the format registry, so a new format needs
- * no config edit. The `document` section of the shared `bytefly.json` is read
+ * no config edit. The `file-read` section of the shared `bytefly.json` is read
  * from the global document and the project document (project wins), and every
  * field is clamped.
  */
@@ -10,7 +10,7 @@
 import { clampInteger, loadConfigSection } from "../../lib/config.ts";
 import { FORMATS, type FormatId } from "./formats.ts";
 
-export interface DocConfig {
+export interface ReadConfig {
 	/** Reject files larger than this many bytes. */
 	maxFileBytes: number;
 	/** Default character budget for the returned slice. */
@@ -21,7 +21,7 @@ export interface DocConfig {
 	formats: Record<FormatId, boolean>;
 }
 
-export const DEFAULT_CONFIG: DocConfig = {
+export const DEFAULT_CONFIG: ReadConfig = {
 	maxFileBytes: 20 * 1024 * 1024,
 	maxChars: 40_000,
 	extractTimeoutMs: 30_000,
@@ -41,7 +41,10 @@ function normalizeFormats(raw: unknown, base: Record<FormatId, boolean>): Record
 }
 
 /** Validate and clamp a raw config object over the running base. */
-export function normalizeConfig(raw: Record<string, unknown> | undefined, base: DocConfig = DEFAULT_CONFIG): DocConfig {
+export function normalizeConfig(
+	raw: Record<string, unknown> | undefined,
+	base: ReadConfig = DEFAULT_CONFIG,
+): ReadConfig {
 	if (!raw) return base;
 	return {
 		maxFileBytes: clampInteger(raw.maxFileBytes, base.maxFileBytes, 1_024, 512 * 1024 * 1024),
@@ -51,12 +54,12 @@ export function normalizeConfig(raw: Record<string, unknown> | undefined, base:
 	};
 }
 
-/** Effective config from the shared `document` section (defaults, global, project, env). */
-export function loadConfig(cwd: string): DocConfig {
-	return loadConfigSection(cwd, "document", DEFAULT_CONFIG, normalizeConfig);
+/** Effective config from the shared `file-read` section (defaults, global, project, env). */
+export function loadConfig(cwd: string): ReadConfig {
+	return loadConfigSection(cwd, "file-read", DEFAULT_CONFIG, normalizeConfig);
 }
 
 /** Whether a format is enabled in the effective config. */
-export function isFormatEnabled(config: DocConfig, id: FormatId): boolean {
+export function isFormatEnabled(config: ReadConfig, id: FormatId): boolean {
 	return config.formats[id] !== false;
 }

package/extensions/{document → file-read}/extract/doc.ts

@@ -6,10 +6,10 @@
  * is only wired to the `.doc` extension.
  */
 
-import { normalizeBodyText, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, type FormatExtractor } from "./file.ts";
 
 /** Extract the body text from a legacy OLE `.doc` file. */
-export const extractDocText: DocExtractor = async (file) => {
+export const extractDocText: FormatExtractor = async (file) => {
 	file.signal?.throwIfAborted();
 	const module = await import("word-extractor");
 	const extractor = new module.default();

package/extensions/{document → file-read}/extract/docx.ts

@@ -6,11 +6,11 @@
  * part of the body and so are not included.
  */
 
-import { normalizeBodyText, readDocBytes, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** Extract the body text from a DOCX file. */
-export const extractDocxText: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractDocxText: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	const module = await import("mammoth");
 	const mammoth = module.default;
 	const { value } = await mammoth.extractRawText({ buffer: Buffer.from(bytes) });

package/extensions/{document → file-read}/extract/file.ts

@@ -1,9 +1,9 @@
 /**
  * The in-process extractor contract for `read_doc`.
  *
- * Each document format is extracted by a JavaScript library that reads the file
- * itself. This module owns the file read, the abort check, and the
- * {@link DocExtractor} type, so the format modules stay tiny and testable
+ * Each format is extracted by a JavaScript library that reads the file itself.
+ * This module owns the file read, the abort check, and the
+ * {@link FormatExtractor} type, so the format modules stay tiny and testable
  * through real fixtures.
  *
  * Imports of the extraction libraries are lazy (`await import(...)` inside each
@@ -14,7 +14,7 @@
 import { readFile } from "node:fs/promises";
 
 /** What an extractor receives: the real, root-confined absolute path. */
-export interface DocFile {
+export interface ExtractInput {
 	/** Absolute, symlink-resolved path inside the effective working root. */
 	path: string;
 	/** The active turn's abort signal, checked before any work. */
@@ -22,13 +22,13 @@ export interface DocFile {
 }
 
 /** Extract plain text for one file. */
-export type DocExtractor = (file: DocFile) => Promise<string>;
+export type FormatExtractor = (input: ExtractInput) => Promise<string>;
 
 /** Read the whole file, refusing to start once the turn is aborted. */
-export async function readDocBytes(file: DocFile): Promise<Uint8Array> {
-	file.signal?.throwIfAborted();
-	const bytes = await readFile(file.path);
-	file.signal?.throwIfAborted();
+export async function readFormatBytes(input: ExtractInput): Promise<Uint8Array> {
+	input.signal?.throwIfAborted();
+	const bytes = await readFile(input.path);
+	input.signal?.throwIfAborted();
 	return new Uint8Array(bytes);
 }
 

package/extensions/{document → file-read}/extract/odt.ts

@@ -10,7 +10,7 @@
 
 import { strFromU8, unzipSync } from "fflate";
 import { XMLParser } from "fast-xml-parser";
-import { normalizeBodyText, readDocBytes, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** Elements that end a line. */
 const BLOCK_ELEMENTS = new Set(["text:p", "text:h", "text:list-item"]);
@@ -93,8 +93,8 @@ export function odtXmlToText(xml: string): string {
 }
 
 /** Extract the body text from an ODT file. */
-export const extractOdtText: DocExtractor = async (file) => {
-	const archive = unzipSync(await readDocBytes(file));
+export const extractOdtText: FormatExtractor = async (file) => {
+	const archive = unzipSync(await readFormatBytes(file));
 	const content = archive["content.xml"];
 	if (!content) throw new Error("ODT archive has no content.xml.");
 	return odtXmlToText(strFromU8(content));

package/extensions/{document → file-read}/extract/pdf.ts

@@ -7,11 +7,11 @@
  */
 
 import { extractPdfText } from "../../../lib/pdf.ts";
-import { readDocBytes, type DocExtractor } from "./file.ts";
+import { readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** Extract text from every page of a PDF. */
-export const extractPdfDocument: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractPdfDocument: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	const text = await extractPdfText(bytes);
 	return text.replace(/\r\n?/g, "\n").replace(/\n+$/, "");
 };

package/extensions/{document → file-read}/extract/rtf.ts

@@ -6,7 +6,7 @@
  * within a paragraph, paragraphs separated by newlines. Formatting is dropped.
  */
 
-import { normalizeBodyText, readDocBytes, type DocExtractor } from "./file.ts";
+import { normalizeBodyText, readFormatBytes, type FormatExtractor } from "./file.ts";
 
 interface RtfNode {
 	value?: string;
@@ -39,7 +39,7 @@ async function parseRtf(input: string): Promise<RtfDocument> {
 }
 
 /** Extract the body text from an RTF file. */
-export const extractRtfText: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractRtfText: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	return rtfDocumentToText(await parseRtf(new TextDecoder().decode(bytes)));
 };

package/extensions/{document → file-read}/extract/xlsx.ts

@@ -9,7 +9,7 @@
  */
 
 import { stripControlChars } from "../../../lib/format.ts";
-import { readDocBytes, type DocExtractor } from "./file.ts";
+import { readFormatBytes, type FormatExtractor } from "./file.ts";
 
 /** One sheet as the text builder consumes it. */
 interface Sheet {
@@ -60,11 +60,11 @@ export function sheetsToText(value: unknown): string {
 }
 
 /** Extract text from a workbook, one `[Sheet]` section per non-empty worksheet. */
-export const extractXlsxText: DocExtractor = async (file) => {
-	const bytes = await readDocBytes(file);
+export const extractXlsxText: FormatExtractor = async (file) => {
+	const bytes = await readFormatBytes(file);
 	const { Workbook } = await import("exceljs");
 	const workbook = new Workbook();
-	// `readDocBytes` copies into a fresh `Uint8Array`, so its buffer is exactly
+	// `readFormatBytes` copies into a fresh `Uint8Array`, so its buffer is exactly
 	// the file bytes; narrow it for exceljs, which types `load` as ArrayBuffer.
 	const { buffer } = bytes;
 	if (!(buffer instanceof ArrayBuffer)) {

package/extensions/{document → file-read}/formats.ts

@@ -1,14 +1,14 @@
 /**
- * The supported document formats, in one table.
+ * The supported formats, in one table.
  *
  * The tool handler, the config defaults, the `formats` merge, and the
- * unsupported-file error all derive from `FORMATS`, so adding a format is a
- * local change: one extractor module plus one entry here. See the README's
- * "Adding a format" section.
+ * unsupported-file error all derive from `FORMATS`, so a format is a local
+ * change: one extractor module plus one entry here. See the README's "Adding a
+ * format" section.
  */
 
 import { extname } from "node:path";
-import type { DocExtractor } from "./extract/file.ts";
+import type { FormatExtractor } from "./extract/file.ts";
 import { extractDocText } from "./extract/doc.ts";
 import { extractDocxText } from "./extract/docx.ts";
 import { extractOdtText } from "./extract/odt.ts";
@@ -16,17 +16,17 @@ import { extractPdfDocument } from "./extract/pdf.ts";
 import { extractRtfText } from "./extract/rtf.ts";
 import { extractXlsxText } from "./extract/xlsx.ts";
 
-export interface DocumentFormat {
-	/** Stable id, also the `document.formats` key in `bytefly.json` and the output `format`. */
+export interface ReadFormat {
+	/** Stable id, also the `file-read.formats` key in `bytefly.json` and the output `format`. */
 	id: "pdf" | "docx" | "doc" | "odt" | "rtf" | "xlsx";
 	/** Human label for messages. */
 	label: string;
 	/** Lower-case extensions, with the dot, that select this format. */
 	extensions: readonly string[];
-	/** Enabled unless `document.formats[id]` in `bytefly.json` says otherwise. */
+	/** Enabled unless `file-read.formats[id]` in `bytefly.json` says otherwise. */
 	defaultEnabled: boolean;
 	/** Extractor; runs the format's parser and throws a readable error when it fails. */
-	extract: DocExtractor;
+	extract: FormatExtractor;
 }
 
 export const FORMATS = [
@@ -36,7 +36,7 @@ export const FORMATS = [
 	{ id: "odt", label: "ODT", extensions: [".odt"], defaultEnabled: true, extract: extractOdtText },
 	{ id: "rtf", label: "RTF", extensions: [".rtf"], defaultEnabled: true, extract: extractRtfText },
 	{ id: "xlsx", label: "XLSX", extensions: [".xlsx"], defaultEnabled: true, extract: extractXlsxText },
-] as const satisfies readonly DocumentFormat[];
+] as const satisfies readonly ReadFormat[];
 
 export type FormatId = (typeof FORMATS)[number]["id"];
 
@@ -46,7 +46,7 @@ export function supportedExtensions(): string[] {
 }
 
 /** The format selected by a path's extension, or undefined when unsupported. */
-export function detectFormat(path: string): DocumentFormat | undefined {
+export function detectFormat(path: string): ReadFormat | undefined {
 	const ext = extname(path).toLowerCase();
 	return FORMATS.find((format) => (format.extensions as readonly string[]).includes(ext));
 }

package/extensions/file-read/index.ts

@@ -0,0 +1,17 @@
+/**
+ * The `file-read` extension entrypoint.
+ *
+ * Registers `read_doc`, which extracts text from a local document or workbook
+ * under the effective working root using in-process parsers. The factory only
+ * registers; a parser library loads lazily on the first read of its format, so
+ * the extension costs nothing at startup.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { registerReadTool } from "./tool.ts";
+
+export default function fileRead(pi: ExtensionAPI): void {
+	if (!isExtensionEnabled("file-read")) return;
+	registerReadTool(pi);
+}

package/extensions/{document → file-read}/paging.ts

@@ -1,7 +1,7 @@
 /**
  * Model-facing text formatting and slicing for `read_doc`.
  *
- * `formatDoc` slices extracted text by code point from `startIndex`, so CJK and
+ * `formatPage` slices extracted text by code point from `startIndex`, so CJK and
  * emoji stay well-formed, and names the offset of the next chunk. The body is
  * the clean slice; the text adds a header and any truncation note.
  */
@@ -9,7 +9,9 @@
 import { formatCount } from "../../lib/format.ts";
 import type { FormatId } from "./formats.ts";
 
-export interface DocPageInput {
+export interface PageInput {
+	/** The tool that produced this page; named in the truncation note. */
+	tool: string;
 	path: string;
 	format: FormatId;
 	bytes: number;
@@ -18,8 +20,8 @@ export interface DocPageInput {
 	maxChars: number;
 }
 
-export interface FormattedDoc {
-	/** The requested slice of the document text. */
+export interface FormattedPage {
+	/** The requested slice of the extracted text. */
 	body: string;
 	/** Header, body, and any truncation note. */
 	text: string;
@@ -30,13 +32,13 @@ export interface FormattedDoc {
 	chars: number;
 }
 
-export function formatDoc(input: DocPageInput): FormattedDoc {
+export function formatPage(input: PageInput): FormattedPage {
 	const points = Array.from(input.text);
 	const total = points.length;
 	const header = `Path: ${input.path}\nFormat: ${input.format.toUpperCase()}\nSize: ${input.bytes} bytes`;
 
 	if (total === 0) {
-		const text = `${header}\n\n(no extractable text; the document may be scanned or image-only)`;
+		const text = `${header}\n\n(no extractable text; the file may be empty or contain no readable text)`;
 		return { body: "", text, truncated: false, nextIndex: input.startIndex, chars: 0 };
 	}
 
@@ -52,14 +54,14 @@ export function formatDoc(input: DocPageInput): FormattedDoc {
 
 	let text = `${header}\n\n${body}`;
 	if (truncated) {
-		text += `\n\n… (truncated at ${nextIndex} of ${total} characters; call read_doc again with startIndex=${nextIndex})`;
+		text += `\n\n… (truncated at ${nextIndex} of ${total} characters; call ${input.tool} again with startIndex=${nextIndex})`;
 	}
 
 	return { body, text, truncated, nextIndex, chars: total };
 }
 
-/** Inputs for `summarizeDoc`, the fields the transcript summary reads. */
-export interface DocSummaryInput {
+/** Inputs for `summarizeRead`, the fields the transcript summary reads. */
+export interface SummaryInput {
 	format: FormatId;
 	/** Total characters in the extracted text. */
 	chars: number;
@@ -69,7 +71,7 @@ export interface DocSummaryInput {
 }
 
 /** Theme-free transcript summary: the format, the range detail, and any note. */
-export interface DocSummary {
+export interface PageSummary {
 	/** Uppercase format id, e.g. `PDF`. */
 	format: string;
 	/** Range detail, e.g. `chars 1–40,000 of 42,478`. */
@@ -81,13 +83,13 @@ export interface DocSummary {
 }
 
 /**
- * Describe a `read_doc` result for the transcript, without theme colours.
+ * Describe a file-read result for the transcript, without theme colours.
  *
  * A complete first read shows the total; a paged read shows the returned range
  * and where to continue, so a truncated result is never mistaken for the whole
- * document.
+ * file.
  */
-export function summarizeDoc(input: DocSummaryInput): DocSummary {
+export function summarizeRead(input: SummaryInput): PageSummary {
 	const format = input.format.toUpperCase();
 	if (input.chars === 0) return { format, detail: "no extractable text", truncated: false };
 	if (input.startIndex >= input.chars) {