## Read first — everything a straightforward document needs

**Publish before you polish** — make the FIRST call a SKELETON: the real title,
the theme and template you picked, the document's section headings, stubbed.
Its response carries the `id` and the url `https://artifactbin.dev/a/<id>`: hand it over at
once and say it is live and still filling in. It is — an edit reaches an open
reader in seconds, so they watch the sections land.
**The reading path never precedes the first publish**; each section then lands
as one targeted `edit_artifact`.

```bash
curl -X POST https://artifactbin.dev/api/artifacts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"…","markup":"…","theme":"industry","template":"deck"}'
```

Every write answers `markup_changed`: true = storing rewrote it (formatting, a
hoisted `<Helmet>`) and the canonical `markup` rides back — edit against that.
A 400 names exactly what to fix.
**`title` is what a browser tab and link previews show** — always set it; the
on-page heading is not it.

**Every `/api` call, `GET` included, sends `Authorization: Bearer <token>`.**

**Editing a published document** — send the CHANGE, not the whole file: `GET https://artifactbin.dev/api/artifacts/<id>` returns the current `markup` and an
`edit_id`; pass it back with the exact text to swap:

```bash
curl -X POST https://artifactbin.dev/api/artifacts/<id>/edits \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"edit_id":"…","old_string":"exact text once in the document","new_string":"replacement"}'
```

`old_string` must appear EXACTLY ONCE. Prefer it to replacing the whole
document: smaller, and a human may be reading the page live.

**markup** is JSX treated as data: ordinary HTML tags for everything including
prose (`h1 h2 p ul li blockquote table figure img`, inline `svg`) plus the
component kit (`Card`, `Tabs`, `Badge`, `Grid`/`GridItem`,
`SlideDeck`/`Slide`, `Icon`, and the data embeds `Question`,
`DataTable`, `Number`), styled ONLY with Tailwind utilities via
`className` — inline `style=` is rejected. There is no markdown.

**Guess rather than look up.** An unknown HTML tag is refused with a 400
carrying the allowed set (`allowed_html_tags`), an unknown component the
registry: a wrong guess costs one cheap round trip. One exception:
`script iframe object embed base meta link form frame frameset applet noscript` are refused with NO list — never guess them
(`<form>` and `<iframe>` most often). Custom CSS and JS live in ONE `<Helmet>`,
which also holds `<title>`:

```jsx
<Helmet><title>What the tab shows</title><style>{`:root { --primary: #ff6a1f }`}</style></Helmet>
```

**A document is a CONTAINER, and a reader may be on a phone (390px).** Use
container prefixes — `@2xl:`, `@3xl:` — never the viewport ones
(`sm:`/`md:`/`lg:` do not apply). Multi-column layouts start at
one column and widen: `grid-cols-1 @2xl:grid-cols-3`, and so does display
type — `text-4xl @2xl:text-6xl`, never a bare `text-6xl` (60px type breaks a
phone). Never a fixed pixel width.

Rules a document lives by: one self-contained document — no CDN `<script src>`,
no external stylesheet (hard 400s at publish); a runtime `fetch()` is
blocked by the sandbox; images are a `data:` URI or
any `https://` URL (publish copies it, your URL stays); web fonts: a Google family via
`<meta name="font-display" content="Lobster" />`.

**Data in a document** — three moves: upload the rows, declare a `<Query>` over
them in the `<Helmet>`, bind an embed by `$name`. The rows are their own
artifact (`{"dataset":"month,revenue\n2026-01,120"}`); its response echoes a ready-to-paste Query+Question.

```jsx
<Helmet><Query name="sales">{`select region, sum(revenue) revenue from ref_<datasetId> group by 1`}</Query></Helmet>
<Question data="$sales" viz={{"kind":"vega-lite","spec":{"mark":"bar","encoding":{"x":{"field":"region","type":"nominal"},"y":{"field":"revenue","type":"quantitative"}}}}} />
```

`<DataTable data="$sales" />` tables the same rows; a
`<Select value="$region" options="$regions" />` writes into a `<Value>` and
re-runs its queries live. **For ANY dataviz — charts, KPIs, tables, controls —
read `references/markup-data.md` first, and ALWAYS chart with these embeds,
never a hand-rolled `<svg>` chart**: `<Question viz>` speaks full vega-lite,
the kit adds theme palettes, tooltips, responsive sizing and live re-runs
for free.

**theme** — the palette and fonts; author with token classes
(`bg-background`, `text-muted-foreground`) and it follows:

- `modernist` — Stark Swiss editorial — white and near-black with one red accent, inverted to ink-black in dark
- `organic` — Warm, soft, playful — sage green, terracotta, leafy chart tones
- `industry` — Professional, square — slate and industrial blue, safety-orange for the one exception
- `terminal` — Terminal — mono type throughout, near-black with neon green by default
- `manuscript` — Serif editorial — cream paper, sepia ink, oxblood accent
- `pop` — Playful and loud — candy magenta, cyan and amber over near-white, chunky radii, heavy Bricolage Grotesque headings

`colorMode`: `light` | `dark`.

**template** — the genre. Pick by the ask; deviating deliberately is
first-class:

- `deck` — slides for PRESENTING: one idea per slide, ~40% empty space.
- `dashboard` — an operating view: `<Grid>` tiles wall to wall, KPI numbers as
  the only big type, almost no prose.
- `editorial` — a report or long read: ONE centered `max-w-2xl` column,
  numbered `<h2>` section claims.
- `scrolly` — data stories (pudding-style) and fun use cases: one conceit the
  whole page commits to, chapter bands, evidence revealed on scroll. The
  strongest default when nothing above fits.

**The reading path — the skeleton is published; before writing its content, read
in order:** `references/design.md` (craft), `references/markup.md` (vocabulary),
then the `references/templates-<name>.md` and `references/themes-<name>.md` you
picked — their frame is what makes it come out right (a deck without it ships
text flush to the viewport edge). The table below carries the rest.

A 200 already validated the document. `GET https://artifactbin.dev/a/<id>/export`
renders it as a PNG (`?slide=2` for one deck slide, 1-based) — fetch it only if
you can actually view images; otherwise read the stored markup back.

**Prose, sections and a one-dataset chart are fully covered above**; anything
more follows the reading path. Beyond both, each ask has ONE file under
`references/` (`https://artifactbin.dev/docs` lists them all):
| when the ask involves | read |
|---|---|
| the API in full — replace, `expectedVersion`, visibility, forking, the error table | `publishing.md` |
| tokens — no token, expiry, saved config, claiming, a 401 | `publishing-auth.md` |
| uploading assets — CSV/sheet rows, images, PDFs (`<File>`), viz recipes | `publishing-datasets.md` |
| pinned human feedback — reply, resolve, the anchor attribute | `publishing-annotations.md` |
| connecting an MCP client — OAuth or bearer, the tool list | `publishing-mcp.md` |
| history — versions, revert, delete, export options | `publishing-versions.md` |
| design craft — hierarchy, type, spacing, color, motifs | `design.md` |
| the complete tag + component allowlists, `<Helmet>` in depth, layout rules | `markup.md` |
| dataviz & charts (vega specs), controls, writable datasets, `<Mutation>`, formats | `markup-data.md` |
| scroll reveals and ambient motion classes | `markup-motion.md` |
| video embeds — the click-to-open card | `markup-video.md` |
| inline SVG motifs and the allowed subset | `markup-svg.md` |
| a long/intricate genre piece — act structure, full skeleton | `templates-<name>.md` (index: `templates.md`) |
| the picked theme — tokens, accent class, chart palette | `themes-<name>.md` (index: `themes.md`) |
Fetch `https://artifactbin.dev/docs/artifactbin/references/<file>`; the whole folder:
`curl -s "https://artifactbin.dev/docs?download=true" | tar xz`, then `grep -rl` it.
No OpenAPI, no Swagger, no `/api/docs`: a guess is a 404.