# How agents edit The model under an agent's edits in Entz, from XML reads, block ids and fingerprints to the six ops and their targets, guards, placeholders, chips and the answer to a write. An agent never sends a document back whole. It reads it as XML, then sends a list of small edits, called ops, each naming what it changes by a block's id or by quoted words. This page describes that model for the curious, and for anyone writing their own prompts or agents on top of the connector. The agent reads the same rules in the connector's guide, the `index` topic of the `guide` tool, and [The eight tools](/docs/mcp/tools/) lists each tool's parameters. ## Reads `read` gives a document, or one of its tabs, as one line of XML, in one of six kinds: | Kind | Takes | Shows | |---|---|---| | `outline` | | Every block, its text cut at 80 characters, tables folded. The default, and where the agent starts. | | `view` | `id` | One block in full: for a table, its rows and cells. | | `search` | `text` | The blocks holding the words, case ignored, each match wrapped in ``, the rest folded. A table shows only the rows and cells with a match. | | `since` | `rev` | The blocks changed since that revision, in full and where they now stand; the rest folded; removed blocks as ``. | | `at` | `rev` | The whole document as it was at that revision. | | `full` | | Every block in full. For short documents. | Folded blocks show as ``. The agent is told to start a later turn with a `since` read of its last revision, which shows at once what people changed in between. To bring back words someone deleted, it reads them with `at` and inserts them again, as a new block. An outline of a new document, broken into lines here: ```xml Q3 launch plan Q3 ships the connector to every workspace. ``` The block tags are `paragraph`, `heading` (with its `level`), `list_item` (with `list`, which is `bullet`, `ordered` or `task`, and `indent` and `checked` when set), `quote`, `code` (with its `language`), `table` (with `rows` and `cols`, holding `row` and `cell` elements, a cell with its `background`), `image`, `equation`, `divider`, `drawing` and `pending` (with its `intent`). Inside text, marks read as ``, ``, ``, ``, ``, ``, `` (a highlight), `` (a text colour) and ``. A date chip reads as its label inside ``, and a dropdown as its pick inside ``, with its `set`, `name`, `index` and `options`. ## Ids, fingerprints and revisions - **Ids.** Every block has an id of the form `.`, such as `2kx9q1.15`: the session label of whoever made the block, then a counter. The id stays with the block through edits, moves and changes of kind; splitting a block makes a new one. A read shortens a run of ids from one session to `.N` after the first full one, so `2kx9q1.15` followed by `.16` means `2kx9q1.16`. Writes always take the full id. - **Fingerprints.** Every block carries `h`, eight hexadecimal digits computed from its kind, its attributes, its text with its marks, and its rows. Any change to the block's words, marks, attributes or cells changes it; a move does not. - **Revisions.** A revision, `rev`, counts the versions of a tab the connector has seen. It starts at 1 and rises whenever the tab changed since the connector last looked. Every read and every write's answer names the current one. The connector keeps the newest 256 for each tab, and starts again at 1 when it restarts, or when it reopens a document it closed after 10 minutes unused. A revision it no longer holds is refused as `rev_expired`, and the agent reads the outline again. ## Writes `update` takes 1 to 64 ops for one tab. They apply in order and land as one change: when a call holds several ops, the connector tries them on a copy of the document first, so a refusal anywhere means nothing lands. The change is signed as the agent's, with its name and the time, which is how editors know to fade its words in. ### Ops | Op | Fields | What it does | |---|---|---| | `insert` | `target`, `side`, `source` | Adds blocks at the start or end of the tab, before or after a block, at the end of a heading's section, or into a table cell. With quoted words as the target and a source `as: "text"`, adds words before or after them. | | `replace` | `target`, `with`, a guard | Swaps whole blocks for the source's blocks, re-words one block in place, changes quoted words, or replaces a cell's contents. | | `delete` | `target`, a guard | Removes whole blocks, or quoted words. A tab keeps at least one block. | | `move` | `target`, `to` | Moves top-level blocks to a place given as `{"target": …, "side": …}`. | | `set` | `target`, `attrs` | Sets attributes on blocks, such as `{"kind": "heading", "level": 2}`, `{"list": "task"}` or `{"checked": true}`; `null` removes one. On a cell, sets its `background`. | | `format` | `target`, `add`, `remove` | Adds or removes marks on blocks or quoted words: `bold`, `italic`, `underline`, `strike`, `code`, `link`, `highlight`, `color`, `math`. A mark with a value is written `{"link": "https://…"}` or `{"highlight": "yellow"}`, and any mark may be written `{"type": "bold"}`. | A few rules keep the ops predictable: - **Sides.** On the tab (`root`), `side` is `start` or `end`. Next to a block it is `before` or `after`, and `end` on a heading means the end of its section: up to the next heading of the same or a higher level. Into a cell it is `start` or `end`, and next to quoted words `before` or `after`. - **Re-wording in place.** Replacing one block `as: "text"` keeps the block: its id, its unchanged words and the comments on them stay. One paragraph replaced by one paragraph as Markdown is re-worded the same way, then takes the new paragraph's marks and chips. A heading, a list, or several blocks are replaced as new blocks. - **Quoted words.** Replaced words keep the marks of the first word replaced. Deleted words are quoted exactly, a leading space included. - **Tables.** A table never goes inside a cell. Blocks inside cells do not move: the table moves. A move's place cannot be one of the blocks moved, a block inside a table or a cell. - **Not marks.** Dates and dropdowns are [chips](#chips), and comments are made with the `comments` tool. ### Targets | Target | Names | |---|---| | `{"kind": "blocks", "ids": ["2kx9q1.16"]}` | Blocks, by full id. | | `{"kind": "find", "text": "every workspace"}` | Words within one block, quoted exactly as a read shows them, without Markdown and with the same capitals. `nth`, counted from 1, picks one of several matches; `within` limits the search to one block, a table or one cell; `parentId` limits it to the section under a heading, or to one block. | | `{"kind": "root"}` | The tab itself, for inserts at its start or end. | | `{"kind": "cell", "table": "2kx9q1.30", "row": 1, "col": 2}` | A table cell by position, counted from 0 with row 0 the header row, or from the end with -1 for the last. A cell takes `replace` (its contents), `insert` and `set` (its `background`: `gray`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink` or `#rrggbb`, `null` for none). | ### Sources The content an op writes is a source: `{"from": {"kind": "inline", "content": …}, "as": …}`, where `as` is one of: - `markdown`: headings, lists, task lists, quotes, tables, code blocks and links. A `mermaid` code block is drawn as its diagram and a `latex` code block as its formula. Markdown also carries chips. - `text`: plain text. - `blocks`: blocks in Entz's own JSON form. ### Chips A chip is a `` token in Markdown, with its entry under the source's `blocks` (for `create` and a new tab, the call's own `blocks`), one key per chip. Every token needs an entry, and every entry a token. - **Block chips** stand alone on their line: `{"type": "pending", "intent": "…"}`, a placeholder; `{"type": "paragraph"}`, an empty paragraph; and `{"type": "divider"}`. - **Date chips** go anywhere in text, table cells included: `{"type": "date", "value": "2026-10-06"}`, shown as its label, such as Oct 6, 2026. - **Dropdown chips** go anywhere in text too: `{"type": "dropdown", "enum": "status", "name": "Status", "options": ["Not started", "In progress", "Done"], "index": 1}`. - `index` is the pick, counted from 0; it is left out when people will pick. - An option is a name or `{"name": …, "color": …}`, the colour one of those a cell takes. An option without one takes the colour of its place in the list. - Chips naming the same `enum` form one set: its `options` and `name` are given once, and later chips name the `enum` alone. A chip nobody picked from reads as the set's name, or Select when the set has none. - The agent changes a pick by replacing the chip. ### Guards A `replace` or `delete` of whole blocks, and a `replace` of a whole cell by position, needs a guard, or it is refused as `missing_guard`: | Guard | On | Refused when | |---|---|---| | `"ifHash": ""` | one block | The block's fingerprint is no longer that one. | | `"ifRev": ` | blocks | Any of them changed since that revision. A move does not count. | | `"ifRev": ` | a cell by position | The table's rows or columns changed since that revision (the position may name another cell now), or the cell's words changed. | | `"force": true` | blocks or a cell | Never. The agent is told to use it only when you asked it to overwrite whatever is there. | Placeholders and quoted words need no guard: a quote touches only its own words, and is refused if they are gone. Beside the ops, a write-level `ifRev` refuses the whole write unless the tab is still at that revision. ### Placeholders A placeholder is a block of kind `pending` with an `intent`, which the editor draws as the intent in grey brackets. The agent plants one per section, usually through `create`, then replaces each with its section, one `update` per section. Replacing one needs no guard, and the answer lists it under `pending_ended`. The guide asks the agent to fill them in reading order, the prose first and the diagrams after: a diagram takes longer to write, and its placeholder tells readers it is coming. An intent can plan the picture, as in "Rollout: a gantt of the milestones by team". Placeholders are left out of Markdown, HTML, Typst and plain text exports. ## What a write answers ```json { "rev": 3, "session": "2kx9q1", "xml": "GoalsShip to every workspace500 weekly active teams", "notices": [{ "notice": "pending_ended", "ids": ["2kx9q1.17"] }], "last": "2kx9q1.44", "synced": true, "link": "https://entz.app/doc/…" } ``` | Field | Holds | |---|---| | `rev` | The tab's revision after the write. | | `session` | The writer's session label, which starts every id it made. | | `xml` | The blocks each op wrote, as a read shows them, op by op. | | `keys` | Each block chip's key and the full ids it became, such as `{"s1": ["2kx9q1.40"]}`. Dates and dropdowns are marks on their label, so they have none. | | `notices` | `pending_ended`, with the placeholders the write replaced, and `detached`, with the comment threads left without their words. | | `last` | The last block written, where the agent's caret rests. | | `synced` | Whether Entz confirmed the write within 15 seconds. | | `link` | The document's link. | The agent aims its next op at the ids in the answer, without reading again between its own writes. ## Limits | What | Limit | |---|---| | Ops in one `update` | 64 | | Text an outline shows per block | 80 characters | | Revisions kept for each tab | the newest 256 | | Time a write waits for Entz to confirm it | 15 seconds | | Words that fade in per write | 300; the rest appear at once | | A document the connector leaves unused | closed after 10 minutes | | The agent's presence after its last work on a document | 90 seconds | | One write's changes on the server | 1 MiB | | A comment's text | 4,096 bytes | | Comment threads on one document or tab | 1,000, resolved ones included | | Comments in one thread | 100 | | A tab's name | 200 characters |