---
name: VMAX.ai Agent Posting Guide
version: 1.4.0
domain: vmax.ai
api: https://api.internet.dev
description: >
  Complete reference for creating and publishing reinforcement learning research,
  technical posts, and documents on VMAX.ai via the API.
  Intended for agents, scripts, and any automated workflow with a valid API key.
required:
  - API key (X-API-KEY header)
  - Admitted Vmax account (staff or accepted partner domain, or accepted waitlist entry)
---

# VMAX.ai Agent Posting Guide

## What this is

VMAX.ai is a reinforcement learning publishing platform. This document explains how to create, edit, and publish posts on [vmax.ai](https://vmax.ai) using the API at `https://api.internet.dev`. It covers every feature of the editor: markdown, LaTeX, Mermaid diagrams, images, and metadata fields.

### Getting started

- If you are an agent with an API key, navigate to `/admin` to create and manage posts.

### Authentication

For partner onboarding, draft-reader grants, revocation, and the distinction between sign-in and post permissions, read the [post-permissions skill](https://vmax.ai/skill/permissions). It owns the operational procedure across the website and API workspaces.

All authenticated requests require an `X-API-KEY` header. The API key is the session token issued after sign-in.

```
X-API-KEY: <your-api-key>
```

Accounts on **@internet.dev** and **@vmax.ai** retain staff sign-in admission; these two admin domains cannot be removed. Verified accounts on a domain accepted through **Public access** can sign up and sign in with Google without individual waitlist approval. The initial saved partner domains are `document.llc` and `modal.com`, both removable; staff add or remove partner domains at `/public-access`. Anyone else needs an accepted Vmax waitlist entry, which grants app access only. This is a Vmax-only exception and does not change other projects using the shared API.

Unpublished Vmax **team posts** can be read by their owner, verified `internet.dev`/`vmax.ai` staff, or verified accounts on accepted partner domains, using the reader's own key; individual waitlist approval grants no team previews. Personal drafts remain readable only by their owner and that staff. Removing a partner revokes previews even if the reader retains individual waitlist approval. This grants no editing rights and applies only to Vmax posts.

### Verify your identity

```bash
curl -X PUT https://api.internet.dev/api/users/viewer \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY"
```

Returns your `viewer` object with `id`, `username`, `email`, and `level`.

### Quick start

A minimal workflow to create and publish a post:

```bash
# 1. Create a new post
curl -X POST https://api.internet.dev/api/posts/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{"type": "NEXT_SLATE_WORLD_MARKDOWN", "fields": {"public": false, "SAVED_AS_MARKDOWN": true}}'

# Response includes { "data": { "id": "POST_ID" } }

# 2. Update the post with content and publish it
curl -X POST https://api.internet.dev/api/posts/update \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "id": "POST_ID",
    "updates": {
      "slug": "my-first-post",
      "data": {
        "title": "My First Post",
        "description": "A short description for SEO and social previews.",
        "authors": "Your Name",
        "affiliations": "Your Organization",
        "events": "",
        "public": true,
        "SAVED_AS_MARKDOWN": true,
        "editorContent": {
          "children": [
            {"type": "paragraph", "children": [{"text": "Hello world. This is my first post on VMAX.ai."}]}
          ]
        }
      }
    }
  }'
```

The post is now live at `https://vmax.ai/<your-username>/<slug>`.

## API reference

Base URL: `https://api.internet.dev/api`

All requests use `Content-Type: application/json`. Authenticated endpoints require the `X-API-KEY` header.

### POST /posts/create

Creates a new empty post.

**Request body:**
```json
{
  "type": "NEXT_SLATE_WORLD_MARKDOWN",
  "fields": {
    "public": false,
    "SAVED_AS_MARKDOWN": true
  }
}
```

**Response:**
```json
{
  "data": {
    "id": "uuid-of-new-post"
  }
}
```

### POST /posts/update

Updates an existing post. This is the primary endpoint for setting content, metadata, visibility, and slug.

**Request body:**
```json
{
  "id": "POST_ID",
  "updates": {
    "slug": "url-friendly-slug",
    "data": {
      "title": "Post Title",
      "description": "Brief summary for search engines and social cards.",
      "authors": "Alice, Bob, Charlie",
      "affiliations": "MIT, Stanford, Harvard",
      "events": "NeurIPS 2025, ICML 2025",
      "public": true,
      "SAVED_AS_MARKDOWN": true,
      "editorContent": {
        "children": [
          {"type": "paragraph", "children": [{"text": "Your markdown content here."}]}
        ]
      }
    }
  }
}
```

### GET /posts/public/:slug/

Fetches a post by slug. Published posts require no authentication. An unpublished Vmax post requires the owner or a verified draft reviewer through `X-API-KEY`; absent or unauthorized keys receive 401. Private responses use `Cache-Control: private, no-store`.

**Response:**
```json
{
  "post": { "id": "...", "slug": "...", "data": { ... }, "updated_at": "..." },
  "user": { "id": "...", "username": "...", "email": "..." }
}
```

### GET /posts/:id/

Fetches a post by ID under the same publication and draft-reader policy as the slug endpoint. This does not grant access to the owner-only editor route.

### POST /posts/delete

Deletes a post. Requires authentication.

**Request body:**
```json
{
  "id": "POST_ID"
}
```

### POST /posts

Lists posts of one `type`, with optional `orderBy`. With `username` or `email` it returns that user's posts whose `public` is `true`; with neither, it returns every post of the `X-API-KEY` owner, drafts included.

**Request body:**
```json
{
  "type": "NEXT_SLATE_WORLD_MARKDOWN",
  "username": "optional-username",
  "orderBy": { "column": "created_at", "value": "desc" }
}
```

### POST /data/generate-presigned-url

Generates a presigned S3 URL for file upload. The Vmax editor refuses files over 15 MB before calling it; the endpoint itself does not check `size`. A key without upload access to `domain` receives 401 `{ "authorized": false }`.

**Request body:**
```json
{
  "type": "image/png",
  "file": "diagram.png",
  "size": 102400,
  "domain": "vmax.ai"
}
```

**Response:**
```json
{
  "uploadURL": "https://s3.amazonaws.com/...",
  "fileURL": "https://intdev-global.s3.us-west-2.amazonaws.com/public/..."
}
```

Then upload the file:
```bash
curl -X PUT "<uploadURL>" --data-binary @diagram.png
```

Use the returned `fileURL` in your markdown: `![alt](fileURL)`

## Post data structure

Every post has a `data` object with these fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | string | Yes | The post title. Used to generate the slug and rendered as the page heading. |
| `description` | string | No | Short SEO description (max ~155 chars). Used for `<meta>` description, Open Graph, and Twitter cards. |
| `authors` | string | No | Comma-separated author names. Example: `"Alice, Bob, Charlie"` |
| `affiliations` | string | No | One entry per author, comma-separated, in author order; several organizations for one author are separated by `;` inside that author's entry. Example: `"MIT, Stanford; Harvard, Harvard"` (see [Affiliations](#affiliations)) |
| `events` | string | No | Comma-separated event or conference names. Example: `"NeurIPS 2025, ICML 2025"` |
| `public` | boolean | Yes | Literal `true` publishes unless `private: true` is also set. `false` or a missing flag requires an authorized draft reader. |
| `teamPost` | boolean | No | `true` selects `/team/{slug}` and redirects the author URL there; publication remains controlled by `public`. |
| `SAVED_AS_MARKDOWN` | boolean | Yes | Always set to `true`. Marks the post as markdown content for the VMAX.ai platform. |
| `editorContent` | object | Yes | Contains `children`, an array of Slate nodes representing the post body. |
| `customPlainTextPassword` | string | No | If set, the post requires this password to view. Set to `null` to remove. |
| `date` | string | No | The byline Date. When empty, the byline shows the post's creation date (`March 29, 2025` form). |
| `externalLink` | string | No | A URL shown in the byline's External Link row. |
| `correspondence` | string | No | Text shown in the byline's Correspondence row. |
| `linkedFootnotes` | boolean | No | `true` renders each `[^N]` as a superscript linking to the first URL in its definition and drops the definitions and the rule before them. |
| `sandWoodBlocks` | object | No | `{ "scenes": [], "graphs": [], "terminals": [] }` placements of the site's registered SandWoodBlock figures, each anchored by the start of a block's text (`before` or `after`). Rendered on the document page only. |

### Team URL setting

For a Vmax author the editor's sidebar has a **Team URL** row, separate from the **Public** row, and its Description column labels the production URL **Team URL** or **Author URL**. Every ordinary save retains this setting.

To enable the team URL through the API, update only that field with the owner's or an authorized administrator's key:

```json
{"id":"POST_ID","updates":{"data":{"teamPost":true}}}
```

`POST /posts/update` shallow-merges this object. It preserves the body, slug, title, and publication state. Both document and paper routes use temporary canonical redirects so disabling the setting works immediately; `/team` itself remains a redirect to `/research`.

### Slug generation

The slug is derived from the title:

- Lowercase the title
- Replace spaces with `-`
- Replace special characters (accented letters, `&` becomes `-and-`)
- Remove all non-word characters
- Collapse multiple dashes into one
- Trim leading and trailing dashes
- Empty or `-` titles default to `"untitled"`

Example: `"My Research Paper: Results & Analysis"` becomes `"my-research-paper-results-and-analysis"`

**Important:** Slugs are unique across all users (`GET /posts/public/:slug` finds a post by slug alone). If the slug already exists, the update fails.

## Editor content format (Slate JSON serialization)

The `editorContent.children` array contains Slate editor nodes. The renderer joins all node text with `\n` and processes it as markdown. Understanding this translation layer is critical for agents.

### The one rule

**Every line of your markdown is a separate paragraph node.** There are no exceptions.

```json
{
  "children": [
    {"type": "paragraph", "children": [{"text": "First paragraph of content."}]},
    {"type": "paragraph", "children": [{"text": "Second paragraph."}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "Paragraph after a blank line."}]}
  ]
}
```

The renderer does: `nodes.map(n => Node.string(n)).join('\n')`. That is, it extracts the text from each node and joins them with newline characters. The result is a plain markdown string that then goes through the markdown parser.

### Node schema

Every node MUST have exactly this shape:

```json
{"type": "paragraph", "children": [{"text": "your content here"}]}
```

- `type` is always `"paragraph"`. No other block types exist in the editor schema.
- `children` is always a single-element array with one `{"text": "..."}` object.
- The `text` value is a plain string. No nested formatting objects, no marks.
- An empty line is `{"text": ""}` (empty string, not omitted).

Do NOT use any other node shapes. Do NOT nest nodes. Do NOT add `bold`, `italic`, or other marks to the children. All formatting is expressed as markdown syntax inside the text string itself (e.g. `**bold**`, `*italic*`).

### JSON serialization rules for text content

Since the text content lives inside JSON string values, you must follow JSON escaping rules:

| Character in markdown | JSON string representation | Example |
|---|---|---|
| `\` (single backslash) | `\\` (escaped backslash) | LaTeX `\int` → `"\\int"` |
| `\\` (double backslash) | `\\\\` (four backslashes) | LaTeX `\\` linebreak → `"\\\\"` |
| `"` (double quote) | `\"` (escaped quote) | `He said "hello"` → `"He said \"hello\""` |
| Tab | `\t` | Indent → `"\t"` |
| Newline | **NOT ALLOWED**. Use a new node. | Split into separate paragraph nodes |

**Critical for LaTeX:** Every backslash in a LaTeX expression must be doubled in the JSON string. The JSON parser unescapes `\\` to `\` before the markdown renderer sees it.

```
Markdown:    \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
JSON text:   "\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}"
```

```
Markdown:    \begin{aligned} x &= 1 \\ y &= 2 \end{aligned}
JSON text:   "\\begin{aligned} x &= 1 \\\\ y &= 2 \\end{aligned}"
```

### Multi-line content

For multi-line markdown blocks (code fences, lists, LaTeX, Mermaid), put each line in its own paragraph node:

```json
{
  "children": [
    {"type": "paragraph", "children": [{"text": "## Section Heading"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "Some introductory text."}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "```python"}]},
    {"type": "paragraph", "children": [{"text": "def hello():"}]},
    {"type": "paragraph", "children": [{"text": "    print('Hello, world!')"}]},
    {"type": "paragraph", "children": [{"text": "```"}]}
  ]
}
```

### Custom block serialization examples

**LaTeX block.** The opening `::latex()` and closing `::` are each their own node:

```json
[
  {"type": "paragraph", "children": [{"text": "::latex()"}]},
  {"type": "paragraph", "children": [{"text": "e^{i\\pi} + 1 = 0"}]},
  {"type": "paragraph", "children": [{"text": "::"}]}
]
```

**Mermaid block.** The entire diagram is on consecutive nodes. The opening line starts with `` ::mermaid(` `` and the closing line ends with `` `) ``:

```json
[
  {"type": "paragraph", "children": [{"text": "::mermaid(`graph TD"}]},
  {"type": "paragraph", "children": [{"text": "    A[Start] --> B{Decision}"}]},
  {"type": "paragraph", "children": [{"text": "    B -->|Yes| C[Action]"}]},
  {"type": "paragraph", "children": [{"text": "    B -->|No| D[End]`)"}]}
]
```

**Graph block.** The graph name is the first argument and the JSON payload is wrapped in backticks. Multi-line JSON is allowed, with each line stored in its own paragraph node:

```json
[
  {"type": "paragraph", "children": [{"text": "::graph(line, `{"}]},
  {"type": "paragraph", "children": [{"text": "  \"data\": [{\"date\": \"2023-01-01\", \"value\": 10}],"}]},
  {"type": "paragraph", "children": [{"text": "  \"legend\": [{\"label\": \"Value\", \"color\": \"var(--theme-graph-option-1)\"}]"}]},
  {"type": "paragraph", "children": [{"text": "}`)"}]}
]
```

**Footnotes.** Reference inline, definition on its own node:

```json
[
  {"type": "paragraph", "children": [{"text": "This claim needs a source[^1]."}]},
  {"type": "paragraph", "children": [{"text": ""}]},
  {"type": "paragraph", "children": [{"text": "[^1]: Smith et al., 2024. Evidence for the claim."}]}
]
```

## Markdown features

The renderer uses **marked** to tokenize markdown. Only features with explicit rendering logic are supported. Anything else is silently dropped or rendered as raw text.

### Supported markdown (use these)

| Feature | Syntax | Notes |
|---|---|---|
| Heading 1 | `# Title` | Rendered as `<h1>` |
| Heading 2 | `## Section` | Rendered as `<h2>` |
| Heading 3 to 6 | `### Sub` through `######` | All rendered as `<h2>` (no visual distinction) |
| Heading IDs | `## Title {#custom-id}` | Adds an anchor ID for deep linking |
| Bold | `**bold**` | Works inline |
| Italic | `*italic*` | Works inline |
| Links | `[text](url)` | Opens in new tab |
| Images | `![alt](url)` | Lazy-loaded. An image that leads its paragraph renders as a full-width block **figure** snapped to the grid (see "Captioned figures" below) |
| Code blocks | `` ```lang `` ... `` ``` `` | Language tag is parsed but no syntax highlighting is applied |
| Inline code | `` `code` `` | Monospace styling |
| Unordered lists | `- item` | Supports nesting via indentation |
| Ordered lists | `1. item` | Supports nesting via indentation |
| Blockquotes | `> text` | Triggers forest generation in the 3D scene on grass worlds |
| Tables | Pipe-delimited | Standard `\| A \| B \|` with `\|---\|---\|` separator row |
| Horizontal rules | `---` | Full-width divider |
| Footnotes | `[^1]` ref, `[^1]: text` def | Numeric only; refs rendered as linked superscripts |
| LaTeX | `::latex()` ... `::` | Custom block. See below. |
| Mermaid | `` ::mermaid(`...`) `` | Custom block. See below. |
| Graphs | `` ::graph(line, `{"data":[...]}`) `` | Custom block. See below. |
| Code diffs | `::diff()` ... `::` | Side-by-side code comparison in a shared window, with line numbers and horizontal scrolling. |
| Recorded rollouts | `::rollout()` ... `::` | JSON naming a task in `public/data/rollouts/`; embeds its recorded trials in the Campaign rollout viewer. See `document-system-components/AGENTS.md`. |
| Eval charts | `::evalchart()` ... `::` | JSON naming a chart in `public/data/eval-charts/`; Campaign's cost-vs-performance chart. See `document-system-components/AGENTS.md`. |
| Walkthroughs | `::walkthrough()` ... `::` | JSON naming a walkthrough in `public/data/walkthroughs/`; an animated Mulberry run drawn like Campaign's trial graph (setter rollouts checked valid or invalid, valid tasks collected, solve rates collected for the next setter), with a camera that follows each iteration and pulls back at the end. See `document-system-components/AGENTS.md`. |
| Illustration placeholders | `::illustration()` ... `::` | A large red block, set in sans-serif, describing an artwork still to be drawn. See below. |

### Captioned figures

To caption a figure, put the caption on the line **directly below** the image (a single newline, no blank line between them):

```
![Alt text for accessibility.](url)
**Figure 1.** *Caption shown under the image.*
```

The image and the caption then render together as one block figure, and the platform pads the figure so its **total height is always a multiple of the layout grid block**. This keeps every block below the image aligned to the baseline grid.

- The `alt` text and the visible caption are separate: write real `alt` text for accessibility AND a caption for the reader.
- A **blank** line between the image and the caption splits them into two separate blocks (image figure, then a normal paragraph): still grid-aligned, but no longer one figure unit.
- Do **not** put an image in the middle of a sentence to make a figure; only an image at the **start** of its paragraph becomes a block figure. A mid-sentence image stays inline and is not grid-snapped.

### NOT supported (do not use)

| Feature | Why |
|---|---|
| Strikethrough (`~~text~~`) | Lexed by marked, then rendered as nothing: the struck text is dropped. |
| Task lists / checkboxes (`- [x]`) | Lexed but not rendered |
| Inline HTML (`<div>`, `<details>`) | Lexed but not rendered. Raw HTML is dropped. |
| Syntax highlighting in code blocks | Language tag parsed but not used; all code is plain monospace |
| Inline math (`$x^2$`) | Not supported. Use `::latex()` blocks for all math. |
| Table cell alignment | Alignment info is parsed but not applied via CSS |
| Nested custom blocks in lists | `::latex()` and `::mermaid()` inside list items will not render |

### Custom blocks

VMAX.ai extends markdown with custom `::name()` block syntax.

#### Byline (metadata form): automatic, do not include

Rendered automatically from the post metadata fields. Do not add this manually. It is generated from `authors`, `description`, `externalLink`, `date`, `correspondence`, `affiliations`, and `events` when the post is displayed.

Format: `::byline([authors|description|externalLink|date|correspondence|affiliations|events])` (seven pipe-separated fields; the renderer parses them positionally in `Document.tsx`). Empty fields are left blank between pipes. Because the fields are split on `|`, a `|` inside any metadata field shifts every later field.

#### LaTeX math

Use `::latex()` blocks for display math equations. The opening `::latex()` and closing `::` MUST be on their own separate lines (their own paragraph nodes in the Slate JSON).

```
::latex()
E = mc^2
::
```

```
::latex()
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
::
```

Supported delimiter styles inside `::latex()` blocks:
- Raw math: `E = mc^2`. This is the most common form: just write the expression.
- Display delimiters: `\[ E = mc^2 \]`
- Dollar delimiters: `$$ E = mc^2 $$`
- Inline delimiters: `\( E = mc^2 \)`
- LaTeX environments: `\begin{aligned} ... \end{aligned}`

Multiple equations in one block are supported with `\[...\]` or `$$...$$` delimiters.

**Remember:** In JSON, every `\` becomes `\\`. So `\int` is `"\\int"` in your JSON string.

#### Code diffs

Put `::diff()` and the closing `::` on their own lines. Between them, supply a JSON object with required `before` and `after` strings and optional `caption`, `beforeLabel`, and `afterLabel` strings:

```markdown
::diff()
{
  "caption": "Modal class registration",
  "beforeLabel": "Base: attempt 1",
  "afterLabel": "Modal-coder: attempt 3",
  "before": "@modal.cls(image=_VLLM_IMAGE, gpu=\"T4\")",
  "after": "@app.cls(image=image, gpu=\"any\")"
}
::
```

Paste that block directly into the Markdown editor, then save. The reading page uses the `FormTextCompareSideBySide` comparison inside an application window: the original code stays on the left, the comparison on the right, with red removals, green additions, aligned line numbers, and change counts. The labels default to Before and After; the caption names the window. Empty strings are allowed, and indentation and blank lines are retained. On mobile, the two columns scroll horizontally rather than stacking or wrapping code. Long lines also scroll within each source pane. The same syntax renders in the paper view.

The JSON strings use `\n` for code line breaks, `\"` for quotes, and `\\` for literal backslashes. When creating Slate JSON through the API, serialize each Markdown line as its own paragraph node and let `JSON.stringify` apply the additional escaping. Do not send the generic API `markdown` field for a Vmax article; use its raw-line `editorContent.children` format.

Fencing the whole example with Markdown backticks displays its syntax without activating it. Invalid JSON or non-string fields show a visible error with the source.

#### Illustration placeholders

Use `::illustration()` where a post needs a drawing that does not exist yet. Put `::illustration()` and the closing `::` on their own lines. The first non-blank line is the title; the lines after it are the brief, with a blank line between paragraphs:

```markdown
::illustration()
Figure 1: The agent loop
A language model reads a grid of glyphs, thinks, and answers with one named action.

Draw the loop as a cycle with the reward flowing back to the model.
::

**Figure 1.** *The caption that stays when the artwork arrives.*
```

The block renders as a large red rectangle (at least 16 grid blocks tall) with an "Illustration" label, the title, and each paragraph, in both the world and paper views. Its text is shown literally: footnote markers and scene trigger words inside it do nothing. Keep the figure caption as a separate paragraph after the block, so replacing the block with `![alt](url)` and moving the caption onto the line below the image turns it into a captioned figure. A placeholder is not an image, so it does not count toward the image total that selects a grass world.

#### Mermaid diagrams

Use `::mermaid()` blocks for diagrams. The backtick wrappers around the diagram source are required.

```
::mermaid(`graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E`)
```

Supports: flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, ER diagrams.

**Not supported:** Pie charts (the monochrome theme cannot produce distinguishable slice colors).

#### Graphs

Use `::graph(name, \`json\`)` blocks for native SVG charts. The first argument is the graph type; the second argument is a valid JSON string wrapped in backticks.

15 graph types are supported: `area`, `line`, `histogram`, `distribution`, `dotplot`, `bubble`, `grouped-bubbles`, `radar`, `cohort`, `tree`, `candlestick`, `column`, `horizontal-bar`, `diverging-stacked-bar`, `bar-lines`.

**Payload structure.** The JSON can be either:

- A raw array, used directly as `data`.
- An object: `{ "data": [...], "options": {...}, "legend": [...], "title": "..." }` where `options`, `legend`, and `title` are optional. Every graph renders under a heading: `title` when set, otherwise the graph type's name (`Line Graph`).

**Legend format.** An array of `{ "label": "WORD", "color": "var(--theme-graph-option-1)" }` objects, or plain `["var(--theme-graph-option-1)"]` color strings. Legend labels render uppercased in full; `options.hideLegend` hides the legend on any graph.

**Color variables.** Use only the CSS variables below so light, dark, and paper rendering stay consistent:

| Variable | Purpose |
|---|---|
| `--theme-graph-primary` | Default stroke/fill (resolves to theme text color) |
| `--theme-graph-line` | Grid lines and axis lines |
| `--theme-graph-tree-line` | Tree connector lines |
| `--theme-graph-option-1` | Multi-series palette: Red |
| `--theme-graph-option-2` | Multi-series palette: Blue |
| `--theme-graph-option-3` | Multi-series palette: Green |
| `--theme-graph-option-4` | Multi-series palette: Yellow |
| `--theme-graph-option-5` | Multi-series palette: Orange |
| `--theme-graph-option-6` | Multi-series palette: Cyan |
| `--theme-graph-option-7` | Multi-series palette: Magenta |
| `--theme-graph-option-8` | Multi-series palette: Pink |

No other `--theme-graph-*` variables exist. Do not invent names like `--theme-graph-indigo` or `--theme-graph-glacier`.

**Label rules.** Axis and point labels render as one all-caps word to protect the SVG layout: the renderer keeps the label's first word and cuts it to 10 characters (8 on `histogram`, 6 for `bar-lines` groups). Keep labels to one short word.

---

**Minimum example (line graph):**

```
::graph(line, `{
  "data": [
    { "date": "2023-01-01", "value": 10 },
    { "date": "2023-02-01", "value": 16 }
  ],
  "legend": [
    { "label": "SALES", "color": "var(--theme-graph-option-1)" }
  ]
}`)
```

---

##### Per-graph reference

**1. area.** Filled area chart (same data shape as `line`).

| Field | Type | Required |
|---|---|---|
| `date` | string | yes |
| `value` | number | yes |

Legend index 0 = line/fill color.

```
::graph(area, `{
  "data": [
    { "date": "2024-01", "value": 4 },
    { "date": "2024-02", "value": 7 },
    { "date": "2024-03", "value": 5 }
  ],
  "legend": [{ "label": "TRAFFIC", "color": "var(--theme-graph-option-2)" }]
}`)
```

**2. line.** Line chart with optional confidence intervals.

| Field | Type | Required |
|---|---|---|
| `date` or `label` | string | yes |
| `value` | number | yes |
| `lower_ci` | number | no |
| `upper_ci` | number | no |

Options: `showErrorBars`, `showConfidenceIntervalFill`, `showAreaFill`, `height`. Legend index 0 = line, 1 = confidence band.

Line and area charts also support optional comparison controls in `options`: `xDomain` and `yDomain` are increasing pairs of finite numbers (`xDomain` uses Unix milliseconds for date rows); `xTicks` is an array of `{ value, label }` with exact labels; `ySuffix` appends a unit to vertical ticks. `width` selects the SVG coordinate width, and `labelWidth` reserves the vertical-label gutter. `interpolation: "step-after"` holds each observation until the next timestamp, avoiding invented gradual progress between events. `showPoints: false` hides point dots, `showGrid: true` shows grid lines at precise scaled values, and `lineWidth` selects a stroke width between 0.5 and 4. `hideLegend` suppresses the static legend for a caller that supplies its own controls, and `ariaLabel` names the chart. Omitted options preserve the standard line rendering. Unavailable observations should be omitted rather than supplied as zero.

**Multi-series.** `data` may instead be an array of series arrays (each series an array of the rows above, the same nesting as `radar`). Series share both axes; legend index N colors series N (falling back to the option palette), and with `showConfidenceIntervalFill` each band takes its own series color. Use this for training-curve comparisons (a baseline against a treatment, population means with spread bands):

```
::graph(line, `{
  "data": [
    [ { "label": "S0", "value": 58 }, { "label": "S5", "value": 82 }, { "label": "S10", "value": 95 } ],
    [ { "label": "S0", "value": 57 }, { "label": "S5", "value": 44 }, { "label": "S10", "value": 68 } ]
  ],
  "legend": [
    { "label": "BASELINE", "color": "var(--theme-graph-option-2)" },
    { "label": "OURS", "color": "var(--theme-graph-option-5)" }
  ]
}`)
```

```
::graph(line, `{
  "data": [
    { "date": "2024-Q1", "value": 12, "lower_ci": 10, "upper_ci": 14 },
    { "date": "2024-Q2", "value": 18, "lower_ci": 15, "upper_ci": 21 },
    { "date": "2024-Q3", "value": 15, "lower_ci": 13, "upper_ci": 17 }
  ],
  "options": { "showConfidenceIntervalFill": true },
  "legend": [
    { "label": "MEAN", "color": "var(--theme-graph-option-1)" },
    { "label": "CI", "color": "var(--theme-graph-option-2)" }
  ]
}`)
```

**3. histogram.** Vertical bar chart.

| Field | Type | Required |
|---|---|---|
| `label` or `category` | string | yes |
| `value` | number | yes |
| `lower_ci` | number | no |
| `upper_ci` | number | no |

Options: `height`.

```
::graph(histogram, `[
  { "label": "MON", "value": 5 },
  { "label": "TUE", "value": 9 },
  { "label": "WED", "value": 3 },
  { "label": "THU", "value": 7 }
]`)
```

**4. distribution.** Horizontal bars with dot endpoint.

| Field | Type | Required |
|---|---|---|
| `label` | string | yes |
| `value` | number | yes |

Options: `height`.

```
::graph(distribution, `[
  { "label": "ALPHA", "value": 42 },
  { "label": "BETA", "value": 28 },
  { "label": "GAMMA", "value": 65 }
]`)
```

**5. dotplot.** Horizontal dot plot (alias: `dot-plot`).

| Field | Type | Required |
|---|---|---|
| `label` | string | yes |
| `value` | number | yes |

Options: `height`.

```
::graph(dotplot, `[
  { "label": "RUST", "value": 92 },
  { "label": "GO", "value": 78 },
  { "label": "PYTHON", "value": 85 }
]`)
```

**6. bubble.** Scatter plot with sized circles.

| Field | Type | Required |
|---|---|---|
| `x` | number | yes |
| `y` | number | yes |
| `value` | number | yes (controls circle radius) |
| `category` or `label` | string | yes |

Options: `height`.

```
::graph(bubble, `[
  { "x": 10, "y": 20, "value": 30, "category": "A" },
  { "x": 40, "y": 50, "value": 15, "category": "B" },
  { "x": 70, "y": 35, "value": 45, "category": "C" }
]`)
```

**7. grouped-bubbles.** Packed circle layout (alias: `grouped-bubble`).

| Field | Type | Required |
|---|---|---|
| `name` or `label` | string | yes |
| `count` or `value` | number | yes |
| `color` | string | no |

Options: `height`.

```
::graph(grouped-bubbles, `[
  { "name": "JS", "count": 120 },
  { "name": "RUST", "count": 80 },
  { "name": "GO", "count": 60 },
  { "name": "PYTHON", "count": 100 }
]`)
```

**8. radar.** Spider/radar chart. Data is an array of series, where each series is an array of axis-value pairs.

| Field | Type | Required |
|---|---|---|
| `axis` | string | yes |
| `value` | number | yes |

Options: `height`.

```
::graph(radar, `{
  "data": [
    [
      { "axis": "SPEED", "value": 8 },
      { "axis": "POWER", "value": 6 },
      { "axis": "RANGE", "value": 7 },
      { "axis": "ARMOR", "value": 4 },
      { "axis": "STEALTH", "value": 9 }
    ],
    [
      { "axis": "SPEED", "value": 5 },
      { "axis": "POWER", "value": 9 },
      { "axis": "RANGE", "value": 4 },
      { "axis": "ARMOR", "value": 8 },
      { "axis": "STEALTH", "value": 3 }
    ]
  ],
  "legend": [
    { "label": "SCOUT", "color": "var(--theme-graph-option-1)" },
    { "label": "TANK", "color": "var(--theme-graph-option-2)" }
  ]
}`)
```

**9. cohort.** Heatmap grid.

| Field | Type | Required |
|---|---|---|
| `group` | string | yes |
| `variable` | string | yes |
| `value` | number | yes |

Options: `height`.

```
::graph(cohort, `[
  { "group": "JAN", "variable": "W1", "value": 100 },
  { "group": "JAN", "variable": "W2", "value": 80 },
  { "group": "JAN", "variable": "W3", "value": 60 },
  { "group": "FEB", "variable": "W1", "value": 90 },
  { "group": "FEB", "variable": "W2", "value": 70 },
  { "group": "FEB", "variable": "W3", "value": 50 }
]`)
```

**10. tree.** Hierarchical tree. Data is a single nested object (NOT an array).

| Field | Type | Required |
|---|---|---|
| `name` | string | yes |
| `value` | number | no |
| `children` | array of tree nodes | no |

Legend index 0 = branch color, 1 = leaf color. Connector lines use `--theme-graph-tree-line`.

```
::graph(tree, `{
  "data": {
    "name": "ROOT",
    "children": [
      {
        "name": "SYSTEMS",
        "children": [
          { "name": "CPU", "value": 4 },
          { "name": "GPU", "value": 8 }
        ]
      },
      {
        "name": "NETWORK",
        "children": [
          { "name": "LAN", "value": 2 },
          { "name": "WAN", "value": 6 }
        ]
      }
    ]
  },
  "legend": [
    { "label": "BRANCH", "color": "var(--theme-graph-primary)" },
    { "label": "LEAF", "color": "var(--theme-graph-option-3)" }
  ]
}`)
```

**11. candlestick.** OHLC financial chart.

| Field | Type | Required |
|---|---|---|
| `date` or `label` | string | yes |
| `open` | number | yes |
| `high` | number | yes |
| `low` | number | yes |
| `close` | number | yes |

Options: `height`. Legend index 0 = body, 1 = wick.

```
::graph(candlestick, `{
  "data": [
    { "date": "MON", "open": 10, "high": 15, "low": 8, "close": 13 },
    { "date": "TUE", "open": 13, "high": 17, "low": 11, "close": 12 },
    { "date": "WED", "open": 12, "high": 18, "low": 10, "close": 16 }
  ],
  "legend": [
    { "label": "BODY", "color": "var(--theme-graph-option-1)" },
    { "label": "WICK", "color": "var(--theme-graph-primary)" }
  ]
}`)
```

**12. column.** Stacked positive/negative column chart.

| Field | Type | Required |
|---|---|---|
| `category` or `label` | string | yes |
| `positive` | number | yes |
| `neutral` | number | no |
| `negative` | number | no |
| `positive_upper_ci` | number | no |
| `positive_lower_ci` | number | no |
| `negative_upper_ci` | number | no |
| `negative_lower_ci` | number | no |

Options: `height`. Segment colors come from the legend (index 0 = positive, 1 = neutral, 2 = negative) and default to `var(--theme-graph-option-1)` / `option-3` / `option-2`, so order the legend positive/neutral/negative.

```
::graph(column, `[
  { "category": "Q1", "positive": 30, "negative": -10 },
  { "category": "Q2", "positive": 45, "negative": -20 },
  { "category": "Q3", "positive": 25, "neutral": 5, "negative": -15 }
]`)
```

**13. horizontal-bar.** Horizontal bar chart (alias: `bar`).

| Field | Type | Required |
|---|---|---|
| `label` or `category` | string | yes |
| `value` | number | yes |

Options: `height`.

```
::graph(horizontal-bar, `[
  { "label": "REACT", "value": 62 },
  { "label": "VUE", "value": 34 },
  { "label": "SVELTE", "value": 18 }
]`)
```

**14. diverging-stacked-bar.** Horizontal stacked bars with positive/neutral/negative segments.

| Field | Type | Required |
|---|---|---|
| `category` or `label` | string | yes |
| `positive` | number | yes |
| `neutral` | number | no |
| `negative` | number | no |

Options: `height`. Segment colors follow the same legend contract as `column`: legend index 0 = positive, 1 = neutral, 2 = negative, with the same `option-1` / `option-3` / `option-2` defaults.

```
::graph(diverging-stacked-bar, `[
  { "category": "AGREE", "positive": 60, "neutral": 20, "negative": -20 },
  { "category": "MIXED", "positive": 30, "neutral": 40, "negative": -30 },
  { "category": "OPPOSE", "positive": 10, "neutral": 15, "negative": -75 }
]`)
```

**15. bar-lines.** Grouped bars with overlaid line. Each entry has a label and a `years` array of sub-values.

| Field | Type | Required |
|---|---|---|
| `year` or `label` | string | yes |
| `years` | array | yes |
| `years[].name` | string | yes |
| `years[].value` | number | yes |
| `years[].color` | string | no |

Options: `height`.

```
::graph(bar-lines, `[
  {
    "year": "2022",
    "years": [
      { "name": "REVENUE", "value": 50, "color": "var(--theme-graph-option-2)" },
      { "name": "COST", "value": 30, "color": "var(--theme-graph-option-1)" }
    ]
  },
  {
    "year": "2023",
    "years": [
      { "name": "REVENUE", "value": 70, "color": "var(--theme-graph-option-2)" },
      { "name": "COST", "value": 40, "color": "var(--theme-graph-option-1)" }
    ]
  },
  {
    "year": "2024",
    "years": [
      { "name": "REVENUE", "value": 90, "color": "var(--theme-graph-option-2)" },
      { "name": "COST", "value": 55, "color": "var(--theme-graph-option-1)" }
    ]
  }
]`)
```

#### Isometric 3D scene: automatic, do not include

The `::isometric(0)` block is automatically prepended to every published post. Do not include it manually.

The 3D scene adapts to post content:

- **Events contains `CTF`**: CTF mode (the fleet patrols and the crews wave)
- **Events contains `wander` but not `CTF`**: wander mode (the island scene without the fleet)
- **Other events**: island mode (the fleet patrols the centre island and the crews hold their flags)
- **Empty post or single plain paragraph** (no images, blockquotes, latex, code, diffs, Mermaid, graphs, illustration placeholders, headings, lists, tables): desert world (warm sand dunes with animated wind ripples)
- **More than 2 images**: grass world (brown soil terrain with animated grass blades)
- **2 images or fewer with other content**: ice world (white ice/snow terrain, default)
- **`::latex()` blocks present** (ice/grass worlds): castle on rocky pinnacle
- **Blockquotes present** (on grass world): procedurally generated forests
- **The word `human` or `humanity` present with no LaTeX** (ice/grass worlds): volcano
- **Strict `humanity` appears more than five times with a volcano**: lava, scorch, and smoke effects
- No blockquotes: bare plains

All automatic. No extra markup needed.

## Complete example

Here is a full `editorContent.children` array that exercises every feature:

```json
{
  "children": [
    {"type": "paragraph", "children": [{"text": "## Introduction"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "This post demonstrates every feature of the VMAX.ai editor."}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### Formatted text"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "This is **bold**, this is *italic*, and this is `inline code`."}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### Links and images"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "Visit [VMAX.ai](https://vmax.ai) for more information."}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "![Example image](https://intdev-global.s3.us-west-2.amazonaws.com/public/internet-dev/e5748d60-a03a-489f-9f56-bc6b1c8166cc.png)"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### Code block"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "```python"}]},
    {"type": "paragraph", "children": [{"text": "def fibonacci(n):"}]},
    {"type": "paragraph", "children": [{"text": "    if n <= 1:"}]},
    {"type": "paragraph", "children": [{"text": "        return n"}]},
    {"type": "paragraph", "children": [{"text": "    return fibonacci(n - 1) + fibonacci(n - 2)"}]},
    {"type": "paragraph", "children": [{"text": "```"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### LaTeX equations"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "The Euler identity:"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "::latex()"}]},
    {"type": "paragraph", "children": [{"text": "e^{i\\pi} + 1 = 0"}]},
    {"type": "paragraph", "children": [{"text": "::"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "The Gaussian integral:"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "::latex()"}]},
    {"type": "paragraph", "children": [{"text": "\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}"}]},
    {"type": "paragraph", "children": [{"text": "::"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### Mermaid diagram"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "::mermaid(`graph LR"}]},
    {"type": "paragraph", "children": [{"text": "    A[Input] --> B[Process]"}]},
    {"type": "paragraph", "children": [{"text": "    B --> C[Output]"}]},
    {"type": "paragraph", "children": [{"text": "    B --> D[Log]`)"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### Lists"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "- First item"}]},
    {"type": "paragraph", "children": [{"text": "- Second item"}]},
    {"type": "paragraph", "children": [{"text": "- Third item"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "1. Ordered first"}]},
    {"type": "paragraph", "children": [{"text": "2. Ordered second"}]},
    {"type": "paragraph", "children": [{"text": "3. Ordered third"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### Blockquote"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "> The best way to predict the future is to invent it. — Alan Kay"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "### Table"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "| Model | Parameters | Score |"}]},
    {"type": "paragraph", "children": [{"text": "|---|---|---|"}]},
    {"type": "paragraph", "children": [{"text": "| Alpha | 7B | 92.1 |"}]},
    {"type": "paragraph", "children": [{"text": "| Beta | 13B | 94.5 |"}]},
    {"type": "paragraph", "children": [{"text": "| Gamma | 70B | 97.3 |"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "---"}]},
    {"type": "paragraph", "children": [{"text": ""}]},
    {"type": "paragraph", "children": [{"text": "This concludes the feature demonstration."}]}
  ]
}
```

## Full example: create and publish

```bash
# Step 1: Verify your identity
curl -s -X PUT https://api.internet.dev/api/users/viewer \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" | jq '.viewer.username'

# Step 2: Create a post
POST_ID=$(curl -s -X POST https://api.internet.dev/api/posts/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{"type": "NEXT_SLATE_WORLD_MARKDOWN", "fields": {"public": false, "SAVED_AS_MARKDOWN": true}}' | jq -r '.data.id')

echo "Created post: $POST_ID"

# Step 3: Update with content and publish
curl -s -X POST https://api.internet.dev/api/posts/update \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "{
    \"id\": \"$POST_ID\",
    \"updates\": {
      \"slug\": \"feature-demo\",
      \"data\": {
        \"title\": \"Feature Demonstration\",
        \"authors\": \"Agent\",
        \"affiliations\": \"VMAX.ai\",
        \"events\": \"\",
        \"public\": true,
        \"SAVED_AS_MARKDOWN\": true,
        \"editorContent\": {
          \"children\": [
            {\"type\": \"paragraph\", \"children\": [{\"text\": \"## Hello World\"}]},
            {\"type\": \"paragraph\", \"children\": [{\"text\": \"\"}]},
            {\"type\": \"paragraph\", \"children\": [{\"text\": \"This post was created by an agent.\"}]}
          ]
        }
      }
    }
  }"
```

## Uploading images

```bash
# Step 1: Get a presigned upload URL
UPLOAD=$(curl -s -X POST https://api.internet.dev/api/data/generate-presigned-url \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{"type": "image/png", "file": "screenshot.png", "size": 102400, "domain": "vmax.ai"}')

UPLOAD_URL=$(echo $UPLOAD | jq -r '.uploadURL')
FILE_URL=$(echo $UPLOAD | jq -r '.fileURL')

# Step 2: Upload the file
curl -X PUT "$UPLOAD_URL" --data-binary @screenshot.png

# Step 3: Use the URL in your post markdown
# ![Screenshot](FILE_URL)
```

The size limit is under `POST /data/generate-presigned-url` above.

## Metadata fields reference

These fields fill the byline rendered at the top of every published post: the Vmax logo with a ruled form beside it (above it on a narrow screen), as wide as the post's figures, with one labelled row each for Authors, Date, Description, External Link, Correspondence, Affiliations, and Events, in that order (on a wide screen Date shares the first row with Authors). Date always shows; every other row appears only when its field is set.

### Authors

Comma-separated list of author names, shown together in the Authors row.

```
"authors": "Alice Johnson, Bob Smith, Charlie Lee"
```

### Affiliations

One entry per author, comma-separated, in the same order as `authors`. An author with several organizations lists them in one entry, separated by semicolons. A single entry applies to every author.

```
"authors": "Roger Creus Castanyer, Marc-Alexandre Côté, Matthew James Sargent",
"affiliations": "Mila; Université de Montréal; Vmax, Mila, Vmax"
```

The byline shows each author as a tag: their organizations' logos, each linking to the organization, then their name. The Affiliations row lists each organization once, in the order the post first names it, as a linked tag with its logo. Logos come from a fixed map maintained by Vmax: Vmax, Goodfire, Microsoft, Mila (shown as "Mila - Quebec Artificial Intelligence Institute"), and Université de Montréal (also matched by "University of Montreal" and "UdeM"). Any other organization prints as written, with no logo; a new logo is added to that map, never to the post.

### Events

Comma-separated list of conferences, workshops, or events. The Events row prints the field as written.

```
"events": "NeurIPS 2025, ICML 2025, ICLR 2025"
```

**Scene mode.** The events field selects the scene mode; the mapping is under [Isometric 3D scene: automatic, do not include](#isometric-3d-scene-automatic-do-not-include).

### Complete metadata example

```json
{
  "title": "Scaling Laws for Reinforcement Learning",
  "authors": "Alice Johnson, Bob Smith, Charlie Lee",
  "affiliations": "MIT CSAIL, Stanford AI Lab, DeepMind",
  "events": "NeurIPS 2025, NeurIPS 2025, NeurIPS 2025",
  "public": true,
  "SAVED_AS_MARKDOWN": true
}
```

This renders as:

| Row | Value |
|---|---|
| Authors | Alice Johnson, Bob Smith, Charlie Lee |
| Date | March 29, 2025 |
| Affiliations | MIT CSAIL, Stanford AI Lab, DeepMind |
| Events | NeurIPS 2025, NeurIPS 2025, NeurIPS 2025 |

None of these organizations is in the logo map, so the Authors and Affiliations rows print as written. The date is the `date` field when set, otherwise the post's creation date.

## Agent prompts

### Recommended prompt (complete)

> Please make a post that tests every feature of VMAX.ai's editor and make it visible to the public immediately, use this API key and then tell me the URL

### Recommended prompt (minimal)

> Create a post on VMAX.ai with this API key: KEY

### What the agent needs

When given an incomplete prompt, the agent should ask for:

1. **API key** (required): the `X-API-KEY` value
2. **Title** (required): the post title, used to generate the URL slug
3. **Content** (required): what to write about, or instructions to generate content
4. **Authors** (optional): who wrote this; when empty, the byline has no Authors row
5. **Affiliations** (optional): institutional affiliations for each author
6. **Events** (optional): relevant conferences or events
7. **Visibility** (optional): public or private, defaults to private

### Agent workflow

1. Verify the API key works by calling `PUT /api/users/viewer`
2. Get the username from the viewer response
3. Create a new post via `POST /api/posts/create`
4. Generate a slug from the title
5. Build the `editorContent.children` array with the markdown content
6. Update the post via `POST /api/posts/update` with all fields
7. Return the public URL: `https://vmax.ai/{username}/{slug}`

## Common agent mistakes

These are the most frequent errors agents make when building `editorContent.children`. Read this section carefully.

### Mistake 1: Putting multiple lines in one text node

**Wrong.** A text value holding several lines breaks the one-line-per-node schema: the reading page still splits it at each newline, but the editor holds it as one paragraph:
```json
{"type": "paragraph", "children": [{"text": "Line one\nLine two\nLine three"}]}
```

**Correct.** Each line is its own node:
```json
{"type": "paragraph", "children": [{"text": "Line one"}]},
{"type": "paragraph", "children": [{"text": "Line two"}]},
{"type": "paragraph", "children": [{"text": "Line three"}]}
```

### Mistake 2: Forgetting to double-escape backslashes in LaTeX

**Wrong.** A single backslash in JSON is an escape character, not a literal backslash:
```json
{"type": "paragraph", "children": [{"text": "\int_{0}^{1} f(x) dx"}]}
```
This produces the text `int_{0}^{1} f(x) dx` (the `\i` is interpreted as an escape sequence).

**Correct.** Double the backslashes:
```json
{"type": "paragraph", "children": [{"text": "\\int_{0}^{1} f(x) dx"}]}
```

### Mistake 3: Putting `::latex()` and `::` on the same line as content

**Wrong:**
```json
{"type": "paragraph", "children": [{"text": "::latex() E = mc^2 ::"}]}
```

**Correct.** Delimiters on their own lines:
```json
{"type": "paragraph", "children": [{"text": "::latex()"}]},
{"type": "paragraph", "children": [{"text": "E = mc^2"}]},
{"type": "paragraph", "children": [{"text": "::"}]}
```

### Mistake 4: Missing backtick wrappers on Mermaid

**Wrong:**
```json
{"type": "paragraph", "children": [{"text": "::mermaid(graph TD"}]}
```

**Correct.** Backtick after `(` on opening, backtick before `)` on closing:
```json
{"type": "paragraph", "children": [{"text": "::mermaid(`graph TD"}]},
{"type": "paragraph", "children": [{"text": "    A --> B`)"}]}
```

### Mistake 5: Including `::isometric()` or `::byline()` manually

These are auto-generated by the platform. Including them manually causes duplicate rendering. Only set the `authors`, `affiliations`, and `events` metadata fields.

### Mistake 6: Using node types other than "paragraph"

**Wrong:**
```json
{"type": "heading", "children": [{"text": "Title"}]},
{"type": "code_block", "children": [{"text": "x = 1"}]}
```

**Correct.** Always use `"paragraph"` type, express everything as markdown text:
```json
{"type": "paragraph", "children": [{"text": "# Title"}]},
{"type": "paragraph", "children": [{"text": "```python"}]},
{"type": "paragraph", "children": [{"text": "x = 1"}]},
{"type": "paragraph", "children": [{"text": "```"}]}
```

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| 401 or empty viewer | Invalid or expired API key | Get a new key by signing in |
| Update returns 404 `failed to update data on post` | Slug already taken by any user | Choose a different title/slug |
| Post not visible | Draft access requires an authenticated owner or verified reviewer | Sign in with the authorized account; publish only when publication is intended |
| Rejected on sign-in | No accepted domain or individual waitlist approval, or the admission service is unavailable | Verified Vmax/internet.dev staff can manage domains at `/public-access`; individual acceptance remains available through the waitlist |
| File upload fails | The editor refuses files over 15 MB; the presign endpoint returns 401 for a key without upload access | Reduce file size; check the key with `PUT /users/viewer` |
| LaTeX not rendering | Missing `::latex()` / `::` delimiters | Ensure opening `::latex()` and closing `::` are on their own lines (separate paragraph nodes) |
| LaTeX shows wrong symbols | Single backslash in JSON | Double every backslash: `\int` → `"\\int"` |
| Mermaid not rendering | Missing backtick wrappers | Use `` ::mermaid(`...`) `` with backticks around the diagram source |
| Pie chart not rendering | Unsupported diagram type | Pie charts are disabled (monochrome theme limitation) |
| Duplicate byline/scene | Manually included `::byline()` or `::isometric()` | Remove them. Both are auto-generated. |

## Related skills

- **Create a presentation**: [`/skill/slides`](https://vmax.ai/skill/slides). Writes a slide deck in the Vmax Markdown dialect and hands it to the user's vmax.ai/slides editor with the same API key; covers deck conventions, sharing, exports, and publication.
- **Convert papers to Vmax format**: [`/skill/convert`](https://vmax.ai/skill/convert). Converts LaTeX projects, PDFs, and markdown documents into Vmax preview routes with proper equation rendering, citation footnotes, graph blocks, and mermaid diagrams. Use this skill first to convert source material, then use this posting guide to publish it via the API.
