Book writer

The book writer creates and edits Markdown books and manuscripts. It edits so that it never overwrites another writer's work.

What it does#

The writer creates new books with trove items create and trove items import <file>. 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.

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 <id>:<page> to change one page. Other pages stay untouched.
3. Always pass --expect-version N to put. The version comes from trove items get <id> --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 <id> 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 <id>:<page> 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.

Auto-update manuscripts#

An auto-update manuscript carries its own writing instructions. The writer reads them with trove ms show <id> --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#

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 and Write a book. For manuscripts, each manuscript sets its own approval rule. See Manuscripts that stay useful.

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.

See the CLI reference.

Related#

• Manuscripts
• Library and books
• Book enricher