Replace a workspace's doc body. Takes EITHER TipTap JSON (`content`) OR Markdown (`markdown`): pass markdown when you're producing prose from scratch (CommonMark + GFM is the format every LLM emits natively), pass TipTap JSON when you need structural edits to an existing doc (round-trip from get_doc, mutate, write back). Beyond CommonMark + GFM, the markdown layer recognizes:
- **** → inline image. Use an HTTPS URL (HTTP fires browser mixed-content warnings; data: URIs are rejected by `allowBase64: false`). For an image on your own machine, put it in a `files` surface of THIS workspace with `upload_file` (for a file on your machine or over ~3 MB, `create_file_upload` first and pass its `url` to `upload_file`; make the surface with `create_surface` kind `files` if there is none), then embed the `url` that `upload_file` returns. Never embed a `create_file_upload` url in a doc: that staged link is temporary and is deleted once the file is uploaded or left unused, so the image would break. Never ask for a public host. Renders block-feeling via CSS (max-width 100%, rounded corners, drop shadow) even though the underlying node is inline. The `alt` text is the accessible label and shows in place of the image if the URL fails to load — always include it.
- A **lone video-file URL on its own line** (extension `.mp4` / `.m4v` / `.webm` / `.mov` / `.mkv`, signed-params + timestamp fragments tolerated) → native HTML5 `<video controls preload="metadata">` player. Source URL is referenced directly: no iframe, no transcoding, no quality loss. Any HTTPS URL to the video file works. For a video on your own machine, call `create_video_upload` (one file, up to 100 MB), run the curl it returns and use the `url` from its response. Sample shape: a paragraph containing only that URL. Mid-paragraph URLs stay as plain links — surrounding prose disqualifies the auto-promotion (matches the oEmbed convention).
- **```mermaid** fenced code → diagram (15 sub-types: flowchart, sequence, gantt, ER, state, class, mindmap, timeline, pie, quadrant, sankey, XY-chart, packet, block, journey)
- **$x$** inline math, **$$x$$** block math (LaTeX, KaTeX-rendered, scripts/href disabled)
- **> [!NOTE]** / **[!TIP]** / **[!IMPORTANT]** / **[!WARNING]** / **[!CAUTION]** GFM-style callouts
- **```svg** fenced code → sanitized SVG embed (the universal escape hatch for custom diagrams; scripts and event handlers stripped at write time)
- **<details><summary>X</summary>BODY</details>** → collapsible toggle
- **[[slug]]** / **[[org/slug]]** / **[[slug#surface-slug]]** / **[[slug#row-id]]** / **[[slug|display]]** → cross-references to another workspace, surface, or row. `[[slug#surface-slug]]` opens that surface, linking to `/<org>/<slug>?surface=<surface-slug>`. Resolved against your accessible workspace set; targets you can't see render as plain text on the reader's side (no info leak). Every cross-ref creates a Backlink row so the target's 'referenced from' sidebar shows this doc.
- **[@Label](dock:mention/<kind>/<id>)** → @-mention of a user or agent. `<kind>` is `agent` or `human`; `<id>` is the principal id. Optional query params `?org=<slug>` (agents) or `?email=<addr>` (humans) for renderer hints. Mentioning a human writes a `doc_mention` row to their inbox + sends a deep-link email; mentioning an agent fires the `doc.mention_added` webhook so the agent service can wake up and reply. Re-saving a doc that already mentions someone does NOT re-fire — only newly-added mentions notify (computed from a diff against the previous body). Use this to ping a person or agent when a doc you wrote needs their eyes.
- A **lone URL on its own line** from a safelisted provider (YouTube, Vimeo, Loom, Figma, CodePen, GitHub gists) → sandboxed iframe embed. Other URLs stay as regular links. Surrounding prose disqualifies the auto-embed.
Per-format caps: max 50 Mermaid diagrams (30 KB source each), max 500 math expressions (8 KB source each), max 50 SVG blocks (100 KB source each post-sanitize), max 200 cross-refs per doc, max 500 @-mentions per doc, max 20 embeds per doc, max 20 videos per doc, max 200 images per doc. Last-write-wins; no CRDT merge. Emits doc.updated + doc.heading_added + doc.mention_added events as applicable. Requires editor role. Multi-surface workspaces optionally accept `surface_slug` to write to a specific doc surface; omitted writes the primary doc surface. Append-only updates have a dedicated `append_doc_section` tool that doesn't require fetching the body first.