# Authoring content

An agent that can call `create_system` is not yet an agent that produces *good* systemHUB documents. This page is the authoring contract: which HTML survives, which is silently changed, and the conventions that make a document genuinely usable. It is extracted from the live editor configuration (a custom CKEditor 5 build) and verified by round-trip audit — not guessed.

## The rule that matters most

**The MCP/REST layer stores your HTML verbatim. The editor is the filter.** Content outside the supported set is not rejected at write time — it is silently removed or downgraded the first time a human opens the document in the editor and saves. No error is raised. So author *within* the supported set, or your content will change under the user's feet later.

## The four content fields

Every system, policy, and training document has four content areas. All except Title are rich text with the same formatting rules:

| Field | API parameter | Purpose |
|---|---|---|
| Title | `title` | Plain text, max 255 chars. |
| Overview | `description` | One or two sentences: what this is and why it matters. Not the steps. |
| Details (body) | `content` | The main content. Steps live here. |
| Notes | `note` | Internal notes for editors and reviewers. |

## Supported formatting (survives the editor)

- **Headings:** `<h1>`, `<h2>`, `<h3>` **only**. Use one `<h3>` per step.
- **Inline:** `<strong>`, `<i>`, `<u>`, `<s>`.
- **Highlights:** exactly four — `<mark class="marker-yellow">`, `marker-green`, `marker-blue`, `marker-pink`.
- **Text colour / font:** inline styles only — `style="color:#e74c3c"`, `font-size`, `font-family` (arbitrary values allowed).
- **Alignment / indent:** inline styles only — `style="text-align:center|right|justify"`, `style="margin-left:40px"` (40px steps).
- **Lists:** `<ul>` / `<ol>`, nesting fine. Checklists: `<ul class="todo-list"><li><label class="todo-list__label"><input type="checkbox" disabled><span class="todo-list__label__description">Task</span></label></li></ul>` (add `checked` for ticked).
- **Blocks:** `<blockquote>`, `<hr>`, code blocks `<pre><code class="language-python">` (24 languages incl. bash, javascript, sql, json, yaml).
- **Links:** `<a href>` — every link is forced to open in a new tab (`target="_blank"` added automatically).
- **Tables:** full support incl. header rows, `colspan`/`rowspan`, cell background colour, captions.
- **Video embeds:** paste the plain share URL, or write `<figure class="media"><oembed url="https://www.loom.com/share/abc"></oembed></figure>`. Auto-embed providers: YouTube, Vimeo, Wistia, Loom, Google Drive, ScribeHow, Pickaxe, Zoom clips, SharePoint, Dropbox mp4. NOT supported: Instagram, Twitter/X, Facebook, Maps, Flickr.
- **Emoji and unicode:** all fine.

## Silently stripped (do not use)

| Don't write | What happens / do instead |
|---|---|
| `<h4>` `<h5>` `<h6>` | Downgraded to plain paragraph. Only H1–H3 exist. |
| Inline `<code>` | Removed, text kept. Use a `<pre><code>` block instead. |
| `<sup>` / `<sub>` | Removed entirely. |
| `<mark>` without a `marker-*` class, or `pen-*` classes | Removed. Only the 4 markers survive. |
| `background-color` on a `<span>` | Removed. Use a marker highlight. |
| Formatting via CSS class (e.g. `class="text-center"`) | Ignored. Inline `style` only. |
| External images `<img src="https://…">` | **Removed entirely.** Images must be uploaded through the editor UI — the API cannot inject images. Mark the spot instead: `<p><mark class="marker-yellow">[Upload screenshot of the dashboard here]</mark></p>` |

**Auto-normalised (harmless):** `<b>`→`<strong>`, `<em>`→`<i>`, `<del>`→`<s>`; raw `<iframe>` becomes a responsive media wrapper.

## Structured fields are not body content

Email templates and video/media lists are structured data, not HTML:

- **Templates** (`{title, subject, details}`) — use `add_document_templates` / `edit_document_templates` / `remove_document_templates`.
- **Videos and media** (`{title, videoLink}`) — use `add_document_videos_and_media` / `remove_document_videos_and_media`.

Do not jam these into the `content` HTML; use the dedicated tools so they render in the app's Templates and Video & Media sections.

## Size limit

Edits above roughly **126KB of content can fail with a 502**. Split very large documents, or write in sections.

## Conventions for a good system (the SYSTEMology house format)

1. **Overview = context** (what and why, 1–2 sentences). **Body = numbered steps, each an `<h3>`**, action-first ("Send the welcome email", not "Welcome email").
2. **Yellow-highlight every genuine gap** the owner must fill (a name, link, threshold): `<p><mark class="marker-yellow">[Add the exact email template link here]</mark></p>`. Never invent specifics.
3. **End with a "record it being done" note** — the best version of a system is screen-recorded while someone runs it, then refined.
4. **First drafts get state ORANGE (`state: 1`, needs review)** so the owner knows to check and green-light it.

## Quick example

What an unbriefed agent writes (half disappears on first human save):

```html
<h4>Step 1</h4>
<p>Open the <code>CRM</code> and click <span style="background-color:yellow">New Deal</span>.</p>
<img src="https://example.com/screenshot.png">
```

systemHUB-ready:

```html
<h3>1. Create the new deal</h3>
<p>Open the CRM and click <strong>New Deal</strong>.</p>
<p><mark class="marker-yellow">[Upload a screenshot of the New Deal button here]</mark></p>
```

Next: **[Tool reference →](/docs/tool-reference)**