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.
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. When you are streaming into the document you just created, surface_id is optional — omit it and pass only content, and the update targets that document. 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, do NOT call document_create again — that produces a duplicate for the user. The most common cause is a missing content field: resend the call with the chunk's Markdown in content. You can omit surface_id to target the document you are currently writing; pass it explicitly only when editing a different existing document.

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: