document-editor

Write and edit long-form documents using the built-in rich text editor. Documents open in workspace mode with chat docked to the side. When a request is about writing prose (an article, blog post, report, essay, story, or similar), create it here rather than writing it into the chat response.

## Tools

- **document_create** - Opens a new document editor with an optional title and initial Markdown content. Returns a `surface_id` for subsequent updates. This is the entry point for any new piece of writing.
- **document_update** - Updates content in an open document editor by `surface_id`. Supports `replace` (overwrite) and `append` (add to end) modes.
- **document_read** - Reads the current content of a document by `surface_id` when it belongs to the current conversation, or when the current actor is the guardian/local user. Use to verify content before editing.
- **document_find** - Searches a document for text or regex patterns. Returns matching lines with line numbers, match positions, and matched text.
- **document_replace_text** - Targeted find-and-replace within a document. Supports literal and regex patterns (with backreferences). Optionally limit the number of replacements.
- **document_list** - Lists documents. Without `query`, lists the current conversation's documents. With `query`, searches by title; guardian/local users can search across conversations, while other actors are scoped to the current conversation.
- **document_open** - Opens an existing document in the editor panel by `surface_id`. Use this when a document exists but isn't visible in the editor — for example after the user switches devices, refreshes the page, or when the editor panel was closed. Fetches the document from storage and sends it to the client.
- **document_delete** - Deletes a document by `surface_id`. Use to clean up unwanted documents.

## Creating a new document

This is the default path when the user asks you to write something.

1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble. Capture the `surface_id` from the response — every subsequent `document_update` call must reference it.
2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, _italic_, code blocks, tables, lists, blockquotes as appropriate.
3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.

### Recovering from a failed update

If a `document_update` call fails with an `Invalid input` error (for example because `surface_id` was missing), do NOT call `document_create` again. The `surface_id` you need is in the tool result of the most recent `document_create` call in this turn. Retry `document_update` with that `surface_id` and the same content. Creating a second document with the same title produces a duplicate for the user.

## Editing an existing document

When the user requests changes to a document:

1. Find the `surface_id` from the `<active_documents>` context block.
2. Use `document_update` with the existing `surface_id` — do NOT call `document_create` again.
3. **Choose the right editing tool:**
   - `document_update` with `mode: "append"` — adding new content to the end.
   - `document_update` with `mode: "replace"` — ONLY for full rewrites where the majority of the document is changing.
   - `document_find` + `document_replace_text` — **for everything else**. Fixing typos, renaming terms, swapping sections, reordering content, adjusting formatting, or any edit that touches only part of the document. This is the default choice for edits. It avoids rewriting the entire document and eliminates the risk of accidentally dropping content.
4. **Do NOT use `document_update` with `mode: "replace"` for targeted edits.** Rewriting the entire document to change a few words or rearrange sections is wasteful and error-prone.

## Retrieving existing documents

When the user asks to see, open, or pull up a document:

1. Check the `<active_documents>` block in your context — it lists all documents in this conversation with their `surface_id` and title.
2. If the document is NOT in `<active_documents>`, call `document_list` with a `query` matching the document title. For guardian/local users, this searches across previous conversations and sessions.
3. Once you have the `surface_id`, call `document_open` to open the editor panel. This surfaces the editor on the client and returns document metadata (`surface_id`, `title`, `word_count`) — not the full content. If you need the actual document text, follow up with `document_read`.

**Never** search the filesystem, conversation history, or archives to find a document. Always use `document_list` with a `query`.

**If the user says they can't see a document you know exists** (e.g. after switching from macOS to web, or after a page refresh), call `document_open` with the `surface_id` to re-surface the editor panel on their current client.

## Find & Replace

Use `document_find` and `document_replace_text` for surgical edits that target specific text patterns without rewriting the entire document.

### document_find

Search a document for literal text or regex patterns. Parameters:

- `surface_id` (required) — the document to search
- `query` (required) — the search string or regex pattern
- `regex` (optional, default `false`) — treat `query` as a regular expression
- `case_sensitive` (optional, default `false`) — match case exactly

Returns a list of matches with line numbers, line content, match positions, and matched text. Use this to preview what will be affected before making replacements.

### document_replace_text

Targeted find-and-replace within a document. Parameters:

- `surface_id` (