--- title: "Item reader" description: "Use when you need to know how Trove reads books and cites them. Covers which pages an item reader opens, the citation format, the report it returns, and how it handles read limits and broken books." url: https://docs.heytrove.ai/subagents/item-reader updated: 2026-10-06 --- # Item reader > Load this page when: you need to know how books are read and cited, or why a read failed ## For agents - Start one item reader per angle, all at the same time, each with its books and page ranges. - Never run `trove items read` yourself in the main conversation; the item reader does it. - When a reader reports READ LIMIT REACHED, stop and relay the message with its billing link. The item reader reads the [books](https://docs.heytrove.ai/concepts/library-and-books.md) for one angle, compares them, and cites every claim. You do not start readers yourself. The [librarian](https://docs.heytrove.ai/subagents/librarian.md) starts them on its own. To start the librarian, ask your agent explicitly: "Search my Trove library for how we handle retries." We are actively working on making this start automatically and reliably, but today you should not rely on it. | Signal | What happens | |---|---| | The librarian returned a list | One reader starts per angle | | The project notebook has a book for the topic | One reader starts directly, with no librarian | | No list and no notebook entry | The reader chooses up to 5 books itself | | `READ LIMIT REACHED` | The reader stops and relays the message | ## What it does The reader opens the books and pages it was given. It synthesizes across the books: it notes where they agree and where they disagree. It cites both when two books cover the same point. ## When it starts The librarian starts one reader for each angle on its list. All readers run at the same time. A reader ignores books that belong to other angles. After an Auto mode notebook hit, one reader can start directly. See [Plan mode and Auto mode](https://docs.heytrove.ai/concepts/plan-and-auto-mode.md). ## How it reads 1. The reader opens a research session. The session records what you asked. 2. It runs `trove items list --json` to check that its book ids exist. 3. It runs `trove items toc `. It skips this step when the list already gives page ranges, because each TOC call uses [read quota](https://docs.heytrove.ai/reference/plans-and-limits.md). 4. It runs `trove items read` on the target pages. 5. It writes the answer with citations. 6. It closes the session. ## How it cites The reader uses two formats. A direct quote: ```text "Direct quote from the document" — Document Title, Page X ``` A paraphrase: ```text The document explains that [paraphrased content] (Document Title, pp. 10-12). ``` See [Citations](https://docs.heytrove.ai/concepts/citations.md). ## What its report contains The report has these sections: - Sources consulted - Core findings - Additional insights - Professional-restricted notice, only when a restricted book helped the answer - Citation summary The last line is `COVERAGE:`. It takes one of four values: - `hit`: the assigned books answered the question. - `partial`: a book was on topic, but a sub-topic was missing. - `none`: the pages held nothing relevant. - `not-in-library`: an assigned book is not in your library, so nothing was read. ## Reporting a missing topic The reader reports a missing sub-topic to the book's author. It reports only when all four conditions are true: 1. The book's scope claims to cover the sub-topic, or an adjacent one. 2. The reader read the most likely chapters in full. 3. No relevant passage remained after that reading. 4. Your need was specific enough to check against the text. It reports at most once per read. The topic is abstracted, because the author reads it, and the author can be a third-party seller. See [Knowledge gaps](https://docs.heytrove.ai/concepts/knowledge-gaps.md). ## Broken and partly imported books Flagging a book only queues it for metadata enrichment. It does not re-import the book. For a `partial` book, the reader offers to reprocess it. To accept, ask your agent: "Reprocess this book." It never offers a reprocess for an `unreadable` book. The fix for those is to upload a copy that has a text layer. ## What it never does - It never subscribes to a book. - It never reads books outside its angle. - It never changes a book. - It never lets a failed report change your answer. ## Errors and fixes | Message | What happens and the fix | |---|---| | `⚠ Pro-only book — showing N/M preview pages` | You are on the Personal plan, so you get a preview only. Upgrade on the billing page to read the full book. | | `READ LIMIT REACHED` | The reader stops at the first one and relays the message with the billing link. Wait for the monthly reset or upgrade. | | `Items not found` | The id is a [marketplace](https://docs.heytrove.ai/concepts/marketplace.md) listing you have not subscribed to. Accept the Offer box. | | This book is locked on the Personal plan (`ITEM_LOCKED`) | Upgrade, or choose your usable books. | | Not authenticated | Run `trove auth login`. | ## Model and tools The item reader runs on Sonnet. It uses Bash, Read and Write. ## Best practice When two books disagree, or a book is stale, the reader reports both with citations. Your agent says which is newer or more specific, recommends one and asks you. See [Answers you can trust](https://docs.heytrove.ai/best-practices/answers-you-can-trust.md) and [Research a topic](https://docs.heytrove.ai/usage/research-a-topic.md). ## Direct CLI Your agent runs these through the `trove` command. You can run them yourself in a terminal, but asking your agent is the recommended way: it picks the right flags, waits for processing and checks the result. The reader uses three forms to read pages: ```text trove items read ":140-162" trove items read ":1-5,:all" trove items read --pages 1,3,5 ``` Inline, each id takes one range or `all`. Comma lists work only with `--pages`. - Reprocess a partly imported book: `trove items reprocess ` - Queue a book for metadata enrichment: `trove items flag ` See the [CLI reference](https://docs.heytrove.ai/reference/cli.md). ## Related - [Librarian](https://docs.heytrove.ai/subagents/librarian.md) - [Citations](https://docs.heytrove.ai/concepts/citations.md) - [Plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md)