--- title: "Book writer" description: "Use when you want your agent to create or edit a book or manuscript in Trove. Covers how the book writer edits safely when other agents share the book, the page model, size caps, and how to recover a version." url: https://docs.heytrove.ai/subagents/book-writer updated: 2026-10-06 --- # Book writer > Load this page when: you need to know how books are written, edited or recovered ## For agents - Use `trove items append` to add content and `trove items put :` to change one page. - Always pass `--expect-version N` to `put`, with the version from `trove items get --json`. - After a refused write, read the book again, merge your change, and retry at most 3 times. The book writer creates and edits Markdown [books](https://docs.heytrove.ai/concepts/library-and-books.md) and [manuscripts](https://docs.heytrove.ai/concepts/manuscripts.md). It edits so that it never overwrites another writer's work. | Signal | What happens | |---|---| | You say "write a book about..." | The writer drafts an outline, then the book | | You confirm a manuscript entry | The writer adds the entry | | The manuscript is marked auto-update | The writer adds the entry, then your agent shows a one-line notice | | A write is refused | The writer reads again, merges, and retries | ## What it does The writer creates new books with `trove items create` and `trove items import `. It edits existing books page by page. It shares the book with other writers, such as other sessions or a teammate's agent. ## When it starts - You use a writing phrase, such as "write a book about", "add a section to" or "draft a manuscript". - You confirm a manuscript entry that your agent proposed. - A manuscript is marked auto-update. The writer gets the entry directly. See [Manuscripts](https://docs.heytrove.ai/concepts/manuscripts.md). ## How it edits without losing work Another writer can change the book between your read and your write. A whole-book `put` would then delete their work. The writer follows three rules, in this order: 1. Use `trove items append` to add content. An append is spliced in on the server, so it cannot conflict. 2. Use `trove items put :` to change one page. Other pages stay untouched. 3. Always pass `--expect-version N` to `put`. The version comes from `trove items get --json`. ### When a write is refused A refusal means nothing was written. The writer then: 1. Reads the book again. 2. Applies its change to the fresh copy and keeps the other writer's content. 3. Retries with the new version. It retries at most 3 times. If the book still conflicts, the writer stops and tells you. ## Check and undo The writer compares `trove items toc ` before and after a write. Every title present before must still be present. To undo, ask your agent: "Show the version history of my book, and restore the version before the last edit." A restore saves the current text first, so you can undo a restore too. ## How a book is split into pages Each `# ` heading starts a new page. Headings at level two and below stay inside their page. A file sent to `put :` must hold exactly one `# ` section. ## Size caps These caps are fixed. They are not plan limits. - A whole-document `put` is refused above 1 MB (HTTP 413). Use a page-level `put` or `append` instead. - A book holds at most 30 MB. Split a larger file into several parts, and ask your agent to import each part as its own book. For upload limits per plan, see [Plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md). ## Auto-update manuscripts An auto-update manuscript carries its own writing instructions. The writer reads them with `trove ms show --json` and follows them exactly. It writes with page-level operations. It never deletes existing wiki content. It supersedes old content with a dated note. ## What it never does - It never overwrites a book without a version check. - It never changes a book without your approval, except an auto-update manuscript. - It never hides a failed write. It reports the failure and the exact command. ## Errors and fixes | Error | Fix | |---|---| | Item not found | Ask your agent to list your library and check the id. | | `trove: command not found` | The shell PATH is stale. Open a new terminal or run `trove setup`. | | Not authenticated | Run `trove auth login`. | | No content provided | The file is empty. Check the file, then ask your agent to try again. | | 413 Payload Too Large on `put ` | The book is over the 1 MB cap. Use `put :` or `append`. | | Content would split into N pages | The page file has more than one `# ` heading. Demote extra headings to `##`, or use `append`. | | 409 modified concurrently | Another session wrote at the same moment. Ask your agent to read the page again and retry. | | Page N not found | Ask your agent to show the table of contents of the book, to see the current page numbers. | ## Model and tools The book writer runs on Opus. It uses Bash, Read and Write. ## Best practice Write each chapter as an explanation followed by "Rules for agents", with RULE, WHY and APPLY lines. Use one `# ` heading per page. Ask your agent to edit one page at a time, so that each edit has a version check. See [Write books agents can read](https://docs.heytrove.ai/best-practices/write-books-agents-can-read.md) and [Write a book](https://docs.heytrove.ai/usage/write-a-book.md). For manuscripts, each manuscript sets its own approval rule. See [Manuscripts that stay useful](https://docs.heytrove.ai/best-practices/manuscripts-that-stay-useful.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. | Task | Command | |---|---| | Create a book from a file | `trove items import ` | | Add content | `trove items append --file ` | | Change one page | `trove items put : --expect-version N` | | See the version | `trove items get --json` | | See the page numbers | `trove items toc ` | | Review and undo edits | `trove items history `, then `trove items restore --version N` | See the [CLI reference](https://docs.heytrove.ai/reference/cli.md). ## Related - [Manuscripts](https://docs.heytrove.ai/concepts/manuscripts.md) - [Library and books](https://docs.heytrove.ai/concepts/library-and-books.md) - [Book enricher](https://docs.heytrove.ai/subagents/book-enricher.md)