create_document
Creates a rich document. contentMarkdown (optional) — GFM Markdown — is the RECOMMENDED PATH to set an initial content, in preference to content (raw ProseMirror tree, reserved for cases that build it programmatically). Both omitted: the document is born empty, to be filled by a later update_document. cellId (optional) immediately attaches the document to a canvas block; omitted, it is born detached. warnings (ABSENT when nothing is altered) names what the conversion could not carry (code block info after the language, hard break in a heading). REFUSED with their reason: raw HTML, checkboxes, nesting beyond 100 levels; a literal angle bracket outside code is written \<x> or between backticks. A request blocked by the network firewall (a bare HTTP 403 "Forbidden") answers before the application runs, so it carries NO application message; a document body that is read as an attack pattern (for instance a path traversal such as ../../, or a URL whose host is an IPv4 address) can trigger it. The response carries url: the DIRECT LINK of the document (opens the project on this document), which the human follows with one click, unlike the title.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | The FORM of the document. Omitted: 'richtext' — a rich-text tree, editable by hand in the interface, the unchanged default. 'html' makes `htmlSource` the authoritative source: the document becomes a standalone page, rendered as is. ⚠️ IMMUTABLE: a document does not change form after its creation — update_document does not accept this field: the form is set at creation. ⚠️ An html document has NO version history: the three document-revisions tools refuse it by naming it. Its source is authoritative and is read in full with get_document. A revision history only exists for richtext. | |
| title | Yes | Document title (1 to 200 characters). | |
| cellId | No | Attach the document to this block immediately. Omitted: the document is born DETACHED — attach it later with update_document({cellId}). | |
| content | No | ProseMirror tree of the initial content — reserved for cases that build the tree programmatically (import, migration). `contentMarkdown` is the recommended path for an agent. Providing both at once is an explicit REFUSAL (ambiguous, so it is not resolved silently). Both omitted: empty document, to be filled afterwards by update_document. | |
| htmlSource | No | REQUIRED if `kind: 'html'`, FORBIDDEN otherwise — both refusals are explicit and named. The COMPLETE, SELF-CONTAINED HTML document: markup + `<style>` + `<script>` inline, in a single string (maximum 250000 characters). Meant for what a richtext document cannot carry — an overview page, an interactive report, a visualization, a calculator. Long documentation belongs in an ordinary richtext document (`contentMarkdown`), which stays editable by hand. ⚠️ RISK, STATED TO THE USER WHEN THEY CLICK "▶ Run the document": the sandbox protects the user's SESSION (opaque origin, no cookie or storage) but does NOT guarantee that the document's content stays inside OrgGen — the WebRTC channel is not closed (measured in a browser): anything a document embeds can leave OrgGen. ⚠️ SELF-CONTAINED IN THE STRICT SENSE: the document is served in a sandbox WITHOUT ordinary network access (`fetch`, WebSocket, remote resource). Any REMOTE or RELATIVE resource (`<script src>`, `<link rel=stylesheet>`, `<img src="/x.png">`, a Google font, a CSS `@import`) is REFUSED AT WRITE TIME, naming the offending URL — rather than accepting a document half of which would die silently at display time. Images are embedded as `data:`, CSS and JS are written inline. ⚠️ TWO MANDATORY LINES, whose omission raises NO error — it just yields a document that will look broken. (a) `body` EXPLICITLY declares `background` AND `color`: the document is served in an ISOLATED frame, it inherits nothing from the application theme, so without a declared background it displays in WHITE in the middle of a dark panel. The viewer sets `color-scheme` and `data-og-theme` on `<html>`, but `color-scheme` is a hint to the rendering engine, NOT a stylesheet — it invents no color. (b) a `<meta name="viewport" content="width=device-width, initial-scale=1">`, and content that fits in ~390 px: the panel is readable on a phone. The viewer injects this `<meta>` if it is missing, but this safety net designs nothing — a grid in fixed widths will stay off-screen. ⚠️ NINE COMMON CONSTRUCTIONS ARE DEAD in this sandbox, WITHOUT any error being reported (the write succeeds, the document displays, the button stays inert) — including `alert()`, `window.print()`, `localStorage`, forms, `eval`, and `confirm()`, which returns `false` in every case: the "cancel" branch runs, it is the only one whose result is WRONG instead of inert. The nine, with what works instead, are listed in `get_playbook({topic: "html"})`. | |
| visibility | No | 'private' creates the document invisible to EVERYONE EXCEPT ITS CREATOR, from this very call — otherwise it is created 'inherited' (visible to whoever has access to the project/block) and making it private requires a second call (update_document({visibility})), with a window where the content is visible in between. Omitted: 'inherited', unchanged behavior. | |
| contentLocale | No | Language of the content (fr/en/de/es). | |
| contentMarkdown | No | Initial content as Markdown (GFM) — RECOMMENDED PATH. Headings (#), paragraphs, bulleted/numbered lists, tables (| A | B |), quotes (>), code blocks (```), bold/italic/strikethrough/inline code, links ([text](url)), images (), horizontal rules (---). Converted server-side into a ProseMirror tree. An unsupported construct (raw HTML, YAML frontmatter, or a TASK list `- [ ]`/`- [x]` — there is no place for the checkbox) is REFUSED with the offending node type named — it is not silently omitted from the document. A checklist is written as an ordinary list (`- `). | |
| expectedProjectId | No | UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted. |