# Archetype OS — integration guide

> A brand's design system — tokens, logos, components, templates, icon systems,
> asset library and voice documents — authored by the people who own the brand
> and served to AI tools so everything gets generated on-brand by default.

Archetype does not infer a brand from a rendered page. A scrape can enumerate
every computed value on a homepage; it cannot say which of them were decisions.
Archetype serves what the brand's owners authored — which white is *the* white,
which components exist, what the brand claims and how it says it — including the
parts no page shows.

## The serving model

RAG-style, index → detail. Orient first, then fetch only what you need by
handle:

1. `get_brand` with no arguments returns the brief: all tokens and logo usage
   rules inline, the voice documents, and an inventory of components,
   artifacts, templates and library files, each carrying the handle that
   fetches it. `{"domain": "info"}` is the cheaper version when you only want
   counts.
2. `{"domain": "<domain>"}` returns that domain's index, and the same call
   with `"handle"` returns one item's full detail. The domains are
   brief, info, tokens, assets, components, icons, artifacts, templates, files, voice, schema.
3. `search_brand` locates anything by keyword when you don't know where it
   lives. Every hit carries the exact call that fetches its detail.

This matters because the response is charged as your context. Pull the index,
pick the handle, fetch that one thing — not the whole domain.

One tool covers every domain rather than one tool each, because a host asks
permission per tool: ten names meant ten approval dialogs before any work
appeared. The v2 names (`get_brand_tokens`, `get_brand_components`, and the
rest) still answer if you already learned them — they map to the matching
domain — but they are no longer advertised.

## Reuse what the brand already owns

Never reproduce something this brand already owns from its name, its description, or a summary of it. An index entry identifies an item; only its detail call defines it. Fetch it first with get_brand and the handle the index gave you — artifacts by handle, components by key, templates by key, assets by name, icons by slug — and use what comes back verbatim. If get_brand isn't in your tool list yet, look it up by name before deciding you can't fetch it. If you genuinely can't reuse the real thing on the surface you're building for, port it from the source it does have and say so in your output; never present an approximation as the brand's own.

## When the brand has no answer

When this brand has no value for something you need — a step the scale can't express, a pairing that isn't defined, a component that doesn't exist — do not invent one silently and do not stall. Use the nearest value the brand does define, then say so in your output: what was missing, what you used instead, and where. Report the gap; never paper over it.

## Connect the MCP server

Authentication is OAuth 2.1. An access token is bound to exactly one brand, and
the server names that brand in `serverInfo` and in every tool description, so a
model can always see whose design system it is holding.

Endpoint: `https://www.heyarchetype.com/api/mcp/<brand-slug>` — Settings → Agents shows each brand's full
address. Each brand is its own server, so someone with several brands registers
one per brand and chooses between them in the client: Claude's connector
toggle, per chat or per Project; a project-scoped config in Claude Code or
Cursor. A token for one brand is refused at another's address. The bare `https://www.heyarchetype.com/api/mcp` still works and asks which brand to
connect when you sign in.

**Claude** — In Claude (web or desktop), open Settings → Connectors → Add custom connector, name it after the brand, and paste:

```text
https://www.heyarchetype.com/api/mcp/<brand-slug>
```

**Claude Code** — In a terminal, run:

```shell
claude mcp add archetype-<brand-slug> --scope user --transport http https://www.heyarchetype.com/api/mcp/<brand-slug>
```

**Cursor** — Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

```json
{
  "mcpServers": {
    "archetype-<brand-slug>": {
      "url": "https://www.heyarchetype.com/api/mcp/<brand-slug>"
    }
  }
}
```

**Codex** — In a terminal, run:

```shell
codex mcp add archetype-<brand-slug> --url https://www.heyarchetype.com/api/mcp/<brand-slug>
```

**ChatGPT** — In ChatGPT on the web, turn on Developer mode in Settings, then create a new MCP app with OAuth, name it after the brand, and paste:

```text
https://www.heyarchetype.com/api/mcp/<brand-slug>
```

**v0** — In v0, click Add MCP (in Settings or the prompt form), choose a custom server, and paste this URL:

```text
https://www.heyarchetype.com/api/mcp/<brand-slug>
```

**Lovable** — In Lovable, open Connectors, click + and choose MCP server, name it after the brand, keep OAuth, and paste:

```text
https://www.heyarchetype.com/api/mcp/<brand-slug>
```

**Other** — Point any MCP client that supports remote (HTTP) servers with OAuth at:

```text
https://www.heyarchetype.com/api/mcp/<brand-slug>
```

Three tools read. The fourth, `update_brand`, changes one item at a time — a
token, a voice document, the brand's info, a logo and its usage rules, a
library file, an icon system or a custom icon, a component example, an
artifact, a template's copy — and only on a
connection the user approved with "Allow edits" (the `brand:write` scope) while
able to edit the brand. Every change is logged and returns a `changeId` that
undoes it. Use it when the user asks to change the brand itself, never to make
the brand match something you built.

Every asset URL the tools return is a stable `embedUrl`: safe to put in
generated output, and it keeps resolving, because it always redirects to the
current file.

## Tools

### `get_brand`

Read your brand's design system. Pick a `domain`; call it bare for that domain's index, then again with the `handle` the index gave you for the detail. The index identifies an item, only the detail defines it. No arguments returns the brief, which is where to start.

Domains:
- brief: Start here. Tokens and logo rules inline, the voice docs, and an inventory of everything with the handle that fetches it.
- info: Name, slug and a count of everything served.
- tokens: Design tokens as W3C DTCG JSON; semantic colours carry a value per mode. handle: one of color, typography, spacing, radius, shadow.
- assets: Logos and favicons: SVG or a stable URL, plus usage rules. handle: asset name.
- components: The UI kit. Bare: every component's properties and example names. handle: a component key, for each example's real HTML + CSS; reproduce it as given.
- icons: The icon systems to use, never arbitrary icons. handle: set slug.
- artifacts: Bespoke brand code: backgrounds, patterns, generative graphics, motion. handle: artifact handle, for source to use verbatim.
- templates: Finished layouts the brand ships (social, email, ads, pages, slides): start from one; if several fit and the user hasn't picked, ask which. handle: template key.
- files: Asset library: photos, illustrations, PDFs, filtered by tag or search. handle: file name; a PDF returns its text.
- voice: Voice and messaging docs: the source for any copy. handle: slug, or "all".
- schema: How to write with update_brand: each domain's value shapes, the component model (properties, tags, one instance per example) and every limit. Read it before writing.

Arguments:
  - `domain?` (brief | info | tokens | assets | components | icons | artifacts | templates | files | voice | schema) — Which part of the brand to read. Defaults to "brief".
  - `handle?` (string) — The item to fetch within the domain, as the index gave it: a token category, an asset name, a component key, an icon set slug, an artifact handle, a template key, a library file name, or a voice document slug. Omit it for that domain's index. Ignored by the domains that have no detail call (brief, info).
  - `example?` (string) — domain=components only. Example name or id, to narrow a component to one example.
  - `mode?` (string) — domain=tokens, or components and templates with a handle. Where the brand has modes, the one to resolve colours in (e.g. "dark"): $value and :root become that mode's, the others still served beside them. Omit it for the default.
  - `include_tokens?` (boolean) — domain=components with a handle only. false leaves out the `tokens` :root block, which is the same for every component — fetch it once, then read components without it.
  - `variant?` (string) — Deprecated alias for `example`.
  - `intent?` (string) — domain=icons only. What the icon needs to mean, to pick one from a custom set (e.g. "download").
  - `include_code?` (boolean) — domain=artifacts only, with no handle: include full source for every artifact (large).
  - `type?` (social | web | app | files) — domain=templates only, with no handle: only templates of this kind.
  - `frame?` (string | number | (string | number)[]) — domain=templates with a handle only. Only these frames, by name or number from 1 — the pages you picked from a page library.
  - `tag?` (string | string[]) — domain=files only. Match assets carrying this tag. Give several to narrow further — an asset must carry all of them.
  - `search?` (string) — domain=files only. Substring match over name, description, usage, and tags.
  - `pages?` (string) — domain=files with a handle only. Which pages of a PDF to read, e.g. "3" or "5-12". Omit it for as much of the document as fits in one response, starting at page 1.

### `search_brand`

Keyword search across everything your brand has: token names/roles, logo usage, component and variant names, artifact names/descriptions/code, library file names/tags/descriptions and the text inside PDF documents, and voice document content. Returns typed hits, each with the exact tool call that fetches its full detail. Use it to locate the right item without loading whole domains. Which items are *found* is keyword matching rather than meaning: a multi-word query that matches nothing as a phrase is retried term by term, and a thin or empty result carries a hint naming the browse calls to use instead of rewording. The order they come back in is a separate judgment — when the response carries a `ranking` note, the hits are sorted by how useful each one is for the query, so the top hit is the best answer and not merely the first match.

Arguments:
  - `query` (string) — Case-insensitive keyword or phrase.
  - `domains?` ((tokens | assets | components | icons | artifacts | templates | files | voice)[]) — Limit the search to these domains; omit for all.

### `check_against_brand`

Grade code, CSS, markup or a style object against your brand's authored values, and get back a worst-first fix list. Two kinds of finding, and the difference matters: a **lookup** is exact — a colour or typeface your brand did not author — and names the token to use instead; a **judgment** carries a confidence and covers what no lookup can reach, chiefly a control rebuilt out of raw elements where the kit already has it. Every finding says whether it is drift (the brand has a value; fix it to that), a hardcoded literal (the brand has this exact value; reference it), or a gap (the brand has no value for this — report it, never invent one). With `kind` set to copy, each sentence is also checked against the brand's voice documents, and a contradiction is reported against the line it is on. Pass `url` instead of `subject` to check a live page — a deployed preview, a landing page — as a visitor sees it: it is drawn in a browser, its colours, type and copy are graded, and its logo, components, sections and imagery are looked at against the brand's. That takes up to a minute, spends the brand's AI credits, and returns a `reportUrl` to hand a person. Call this after producing anything the brand will be seen in, and before opening a pull request.

Arguments:
  - `subject?` (string) — The code, CSS, markup or copy to grade. One file at a time — a whole bundle is refused rather than truncated, because a silently half-read subject would report the rest clean.
  - `kind?` (code | copy) — What the subject is. Defaults to "code". Pass "copy" for prose somebody will read — a landing page, an email, a brand document — and each sentence is also checked against the brand's voice documents. Do not pass it for source files: prose cannot be picked out of code reliably, and a wrong voice finding is worse than a missing one.
  - `url?` (string) — A live page to check instead of a subject — the whole page as drawn, not its source. Use it for a deployed preview or a published page. Pass `subject` or `url`, never both.
  - `gaps?` (string[]) — What you had to invent because the brand didn't define it — a component it lacks, a step its scale can't express, a colour for a state — one short sentence each. They reach the brand's team, who decide what the brand should say. Leave it out when nothing was missing.

### `update_brand`

Change one thing in your brand's design system, only when the person who connected it has asked for that change — never to make the brand match something you built. Read get_brand {"domain": "schema"} before the first write: it is the contract for every domain's `value`, the component model and the limits, and none of it is repeated here.

- One call changes one item, named by the `handle` get_brand gave it (a token path, a voice slug, a logo or file name, an icon set slug, a component key, an artifact handle, a template key). Read it first.
- `value` is an object of only the fields to change, or a bare value (a hex, px, a ref). `find` + `replace` edit text in place and must match once.
- Components: `value` {name, description, platforms, properties, nested} on the component; add `example` for one example, `value` {name, html, css, tags}. An example is ONE instance of the component, and each interaction state is its own example. `tags` place it on the declared properties and are checked against them.
- `create: true` adds the item at the handle (a template takes `value.frames`; `frame` + `create` adds a frame); without it an unknown handle is refused. `delete: true` removes it.
- Artwork (logos, library files, custom icons): `value` {source} (a URL the server fetches), {svg} or {data} (base64). Adopt an icon system by creating its catalog key ("lucide").
- Bulk: tokens, components and a custom icon set take `import` — {"source": "<URL of a JSON file>"} or {"document": …}; tokens read DTCG, Tokens Studio and Style Dictionary. Validated first, written together, one changeId. Add "dryRun": true to preview, and "duplicates" when it lists any.
- Every change returns a `changeId`; `{"undo": "<changeId>"}` (or "last") reverses it if nothing has changed the item since. `{"undo": {"since": "<changeId>"}}` rolls back that change and everything you did after it.
- Needs a connection approved with "Allow edits"; the refusal says how to enable it.

Arguments:
  - `domain?` (tokens | voice | info | assets | files | icons | components | artifacts | templates | designs) — What kind of thing to change. Required unless `undo` is given. designs: save a document made from a template's pages (create only).
  - `handle?` (string) — Which item: a token path ("color.brand.500", or "modes" for the brand's light/dark modes), a voice document slug, a logo name, a library file name, an icon set slug ("lucide", or a custom set's), a component key, an artifact handle, or a template key. Not used for info.
  - `example?` (string) — domain=components only. The example to edit, add or delete, by name. Name it by the component's properties ("Primary · Compact · Hover") and it is placed on them.
  - `icon?` (string) — domain=icons only. An icon's key within a custom set, to add, edit or delete it.
  - `frame?` (string | number) — domain=templates only. The frame to edit or delete, by name or by its number from 1 — or, with `create`, the new frame's name.
  - `value?` (any) — What the item becomes — a bare value (a hex, a number of px, a ref, a family name) or an object of only the fields to change. Artwork goes in as {source}, {svg} or {data}. Each domain's shape is in get_brand {"domain": "schema"}.
  - `find?` (string) — The exact text to change — in a voice document, a component example's html/css, an artifact's code, or a template frame's html/css. Must occur exactly once, so copy it from what get_brand returned.
  - `replace?` (string) — What `find` becomes ("" removes it).
  - `create?` (boolean) — Add a new item at `handle` instead of changing an existing one.
  - `delete?` (boolean) — Remove the item at `handle`. It can be put back with `undo`.
  - `import?` (object) — domain=tokens, components or icons, instead of value: many items in one call (icons: `handle` names the custom set, the JSON is {"icons": [{key, name, svg}]}). {"source": "<https URL of a JSON file>"} or {"document": <the JSON>}; "dryRun": true previews without writing. Tokens also take "sets" (Tokens Studio set names); components take "replaceExamples": true to remove examples the import doesn't list. Shapes are in get_brand {"domain": "schema"}.
  - `undo?` (string | object) — A changeId from an earlier update_brand, "last" for your most recent change, or {"since": "<changeId>"} for that change and every later one you made — the checkpoint to roll an import back to. Pass it on its own.

### `get_brand` domains in full

The tool description carries one line per domain, because clients cut a
description at about 2,000 characters. The full version:

- `brief` — The brand brief for your brand, as Markdown: all design tokens and logo usage rules inline, the written voice docs, and an inventory of components, templates, artifacts, icons and library files with the handle that fetches each one. The default, and the place to start.
- `info` — your brand's name and slug plus a count inventory of everything this server serves. The cheap orientation call when all you need is what exists and how much of it.
- `tokens` — your brand's design tokens — colors and gradients, typography, spacing, radius and shadows — as W3C Design Tokens (DTCG) JSON. Use these values verbatim. `handle` filters to one category (color, typography, spacing, radius, shadow); omit it for all five. Where the brand has modes (light and dark), each semantic colour's value in the others is in its $extensions, and `mode` returns the whole set resolved in one.
- `assets` — your brand's logos, favicons and other identity assets: SVG source (when stored inline) or a stable file URL, plus usage rules — when to use, clearspace, min size, misuse. The URL is durable: it always redirects to the current file, so it is safe to embed in generated output. `handle` is one asset name (e.g. "Logo Dark"); omit it for all of them.
- `components` — your brand's UI kit. Bare: a lightweight index — every component's key, name and the names of its examples. `handle` is a component key (e.g. "button") and returns the full detail: each example is this brand's REAL HTML + CSS, with values as var(--token) custom properties resolved by a `tokens` :root block served alongside. Reproduce the markup as given — its structure is the component's anatomy — rather than approximating it from a description. Add `example` to narrow to one.
- `icons` — The icon systems your brand uses — use the brand's set(s) rather than picking icons arbitrarily. Bare: an index of adopted sets, each with its slug, name, kind (a referenced popular system, or the brand's own custom set), Iconify prefix, style variant and default size. `handle` is a set slug (e.g. "lucide"): for a referenced set you get the reference/import syntax (Iconify id + package import), license and homepage, and you use that system's own icon names; for a custom set you get the full inventory with inline SVG. Add `intent` to ask a custom set which of its icons means something.
- `artifacts` — your brand's Artifacts — bespoke brand code the standard component library can't represent: animated and static backgrounds, backdrops, patterns, textures, tiles, generative and procedural graphics, canvas/SVG effects, hero and banner artwork, motion presets, custom interactive elements. Reach for this whenever a design calls for one of this brand's own graphics, and never redraw one from its description — the description names an artifact, the source defines it. Bare: an index (name, handle, description, when-to-use, parameters with the brand's tuned defaults — no source). `handle` returns one artifact's full source code, usage snippet and runtime contract, plus `authoringControls`, the contract to follow when writing or extending an artifact so Archetype can render its controls. Use the code verbatim and apply the brand defaults. `include_code` dumps the source of every artifact at once (large).
- `templates` — your brand's Templates — the finished layouts it publishes over and over: social posts and stories, email and newsletter banners and headers, ads, website pages, app screens, slides, covers, one-pagers and other documents. Check here first for any fixed-size artefact this brand ships repeatedly, and prefer starting from a template over composing a layout: it is what this brand actually ships. When more than one fits and the user hasn't picked, ask them which to start from, or whether to build from scratch, before you build. Bare: an index (name, key, type, frames with their sizes and how many slots each has), narrowable with `type`. `handle` is a template key and returns that template's finished markup — every binding already resolved, so the logo, images and colours in it are the brand's real ones — plus a `slots` list saying which parts are meant to vary.
- `files` — your brand's asset library — uploaded files (photos, illustrations, textures, and documents such as product handbooks, price sheets and decks as PDFs) organised by tag, each with documented tags/description/usage, dimensions, dominant colors, and a stable `embedUrl` that is safe to embed in generated pages and durable output. Every response leads with the tag vocabulary and how many files carry each tag, so call it bare once to see the vocabulary, then again with `tag` or `search` to narrow instead of pulling everything. `handle` is one file's name (or id) and returns that file alone — for a PDF, with its full text page by page, which is the brand's own material on its products, prices and facts: read it before writing about any of them, and quote it rather than paraphrasing from memory. A long document comes back in parts; `pages` picks which.
- `voice` — your brand's voice & messaging documents (Positioning, Audience, Differentiation, Messaging, Voice & Tone, plus custom docs) — the source of truth for what this brand says and how it says it when writing any copy. Bare: an index with each doc's slug, status, word count and excerpt. `handle` is one slug, or "all" for the full corpus.
- `schema` — How to change your brand with update_brand, as Markdown: what every domain's `value` takes, how a component is modelled — declared properties, examples placed on them by tags or by name, one instance per example, interaction states as their own examples — how an example is drawn, which token variables exist, every limit, and what the brand can't hold yet. Read it before the first write, not after the first refusal.

## Writing to your brand

How `update_brand` changes your brand: what each domain takes, how a component is modelled, and every limit. Use it only when the user asks you to change the brand itself — never to make the brand match something you built.

### Every write

- One call changes one item, named by the same `handle` get_brand serves it under. Read it with get_brand first, so you change what is there now. To bring in many tokens or components at once, use an import (below).
- `create: true` adds a new item at the handle; without it an unknown handle is refused, so a typo can't add something. `delete: true` removes it.
- Every change returns a `changeId`. `{"undo": "<changeId>"}` (or `"last"`) reverses it, provided nothing has changed the item since.
- A refusal says what was wrong and what the call should have been. Fix that and retry; don't work around it with a different domain.
- Only works on a connection approved with "Allow edits", by someone who can edit the brand.

### Domains and their values

- **tokens** — `handle` is the token's path from get_brand {"domain": "tokens"}. Paths are lowercase and dot-separated.
  - `color.<group>.<step>` takes a hex.
  - `color.<group>` takes {name, role, base} (base regenerates the ramp from one colour) or {shades: [{step, hex}]}. A step is a string, at most 20 characters.
  - `color.semantic.<name>` takes a ref like "{color.brand.500}", or {ref, description, modes}. `ref` is its value in the default mode; `modes` sets it in the others, `{"Dark": "{color.ink.900}"}`, and only the modes you name change — `null` puts one back to the default's value.
  - `modes` is the brand's modes, light and dark the way Figma's variable modes are: the whole list, default first, `["Light", "Dark"]`. It also takes {modes, rename: {"Dark": "Night"}, default: "Dark"}; renaming a mode, removing one or changing the default carries every semantic colour's values with it, in one change. `delete: true` goes back to one mode, keeping the default's values. Only semantic colours change by mode — pairings and gradients follow them; a palette shade is the same in every mode. At most 8 modes, 32 characters a name; a mode is switched in CSS with `data-mode` and its name as a slug ("High Contrast" → `data-mode="high-contrast"`).
  - `pairing.<name>` takes {background, foreground, usage}. The background may be a gradient ("{gradient.<name>}"); its contrast is then graded at the gradient's worst point.
  - `gradient.<name>` takes {type: "linear" | "radial" | "conic", angle, stops, description}. `stops` is at least two {color, position, alpha}: color a ref or hex, position and alpha 0–1.
  - `typography.<family>` takes a family name. A new family starts with one Body style (16/24px, 400); reshape it or add the rest with the next calls.
  - `typography.<family>.<style>` takes {fontSize, fontWeight, lineHeight, letterSpacing, role, name, textTransform, textDecoration, fontStyle}. Pixels; a lineHeight of 4 or less is read as a ratio.
  - `spacing.<name>` and `radius.<name>` take px, 0 or more.
  - `shadow.<name>` takes {x, y, blur, spread, color}: one layer.
  - A role is at most 60 characters. Fields you leave out keep their value.
- **voice** — `handle` is a document slug. Prefer `find` + `replace` for one passage (find must match exactly once). `value` {title, icon}, or {content} to rewrite the whole document.
- **info** — no handle. `value` {name, description, website}.
- **assets** — the logos. `handle` is a logo's name. `value` {name, background, whenToUse, clearspace, minSize, minDimensions, misuse}; lists replace the old list. Add a logo with `create: true`, its artwork and any rules: `{"domain": "assets", "handle": "Logo Dark", "create": true, "value": {"svg": "<svg …>", "background": "dark"}}`. Artwork in an edit replaces the logo's.
- **files** — the asset library: photographs, illustrations, a mascot's poses, PDFs. `handle` is a file's name. `value` {name, tags, description, usage}; tags replace the old list. Add a file with `create: true`, its artwork, and its documentation — tag it, so it can be found: `{"domain": "files", "handle": "verner-wave.svg", "create": true, "value": {"svg": "…", "tags": ["Mascot"], "description": "Verner waving", "usage": "Greetings, empty states"}}`. A file's bytes aren't replaced in place; add the new one and delete the old.
- **icons** — the icon systems. `handle` is a set's slug.
  - Adopt a popular system by creating it at its catalog key: `{"domain": "icons", "handle": "lucide", "create": true}`. Keys: `lucide`, `material-symbols`, `mdi`, `ph`, `tabler`, `heroicons`, `feather`. Its icons are the system's own, by their own names.
  - `value` {name, style, shape, strokeWidth, defaultSize, whenToUse}: style and shape are the system's weights or styles (get_brand {"domain": "icons", "handle": "<slug>"} lists them); strokeWidth only where the system has one.
  - The brand's own icons go in a custom set: `{"handle": "payper-icons", "create": true, "value": {"custom": true, "name": "Payper Icons"}}`. Then add, edit or delete one icon with `icon` (its key) and `value` {svg | source, name, tags, usage}, or many at once with `import` (below). An icon is at most 24,000 characters of SVG; anything bigger is an illustration and goes in files.
  - The first set is the brand's primary one.
- **components** — see the next section.
- **artifacts** — `handle` is an artifact handle. `find` + `replace` over its code, or `value` {name, description, whenToUse, dependencies, code, defaults: {"<control>": value}}. Defaults are the brand's tuned control values; null resets one.
- **templates** — see the section after Components.
- **designs** — a document made from a template's pages, kept in the app; see Templates.

### Artwork

A logo, a library file and a custom icon arrive in `value` one of three ways:

- `source` — an https URL the server fetches itself (a raw GitHub file, a CDN). Prefer it: no bytes pass through you, so nothing is retyped. A github.com/…/blob/… link is read as its raw file.
- `svg` — the markup, as a string. Right for a logo or an icon you have just read from a file. Scripts, event handlers and `<foreignObject>` are stripped.
- `data` — base64 or a `data:` URL, for a raster you hold but can't link to. Capped at 1.5 MB; every byte of it is output you have to write.

What the bytes are is read from the bytes: SVG, PNG, JPEG, WebP, GIF or AVIF, and PDF in the library only. A local file has no URL — read it and pass `svg`, or `data` for a small raster. If you can do neither, say which files are left for the person to add rather than leaving them out silently.

### Components

A component is a name, a description, its **properties**, and its **examples**. An example is one instance of the component, as HTML + CSS.

#### How an example is drawn

Each example renders alone, in its own sandboxed frame: centred, scaled down to fit its tile, over a minimal reset and the brand's `:root` block of tokens. Scripts are stripped and the frame takes no pointer events, so `:hover`, `:active` and `:focus` never fire there. That gives the rules:

1. **One instance per example.** No row of variants, no caption, no label beside it, no wrapper that exists only to lay out a demo.
2. **Each interaction state is its own example**, with that state's look written as its resting CSS: the Hover example's button is drawn hovered. Pointing at a component on the canvas plays its `Hover` and `Pressed` examples, so use those two names for those two states.
3. **Reference tokens as `var(--…)`** — the names get_brand's components detail serves in `tokens`. Type styles are `--text-<family>-<style>`, with `--line-height`, `--letter-spacing` and `--font-weight` hung off it (`--text-inter-body--line-height`). Literal values that match a token are bound to it on save.
4. **Mark an instance of another component** with `data-component="<its key>"` on its root element. That is what `uses` and `usedIn` are read from; nothing else declares composition. Set `nested: true` on a component that is only ever a part of others.

#### Properties

Declare the axes the examples vary along, in order, with `value` {properties} on the component:

```json
{"domain": "components", "handle": "button", "value": {"properties": {
  "Appearance": ["Default", "Primary", "Subtle", "Warning", "Danger"],
  "Spacing": ["Default", "Compact"],
  "State": ["Default", "Hover", "Pressed", "Disabled"]
}}}
```

- A list's first value is the default; or give {"values": [...], "default": "..."}. `null` clears the declaration.
- The page groups by the kind property (the one named Variant, else the first that isn't a size, a state or an on/off toggle), sections by the next, and shows a tile per combination of the rest.
- A property named Size or State is the kit's size or state. An example at the State default is the component at rest.
- At most 8 properties, 40 values each, 40 characters per value.
- Declaring properties on a component that has examples places them at once: by their existing tags where those fit, otherwise by their names. The reply lists any it couldn't place. One undo reverts the declaration and every tag it wrote.

#### Placing an example

- **`tags`** — `value` {"tags": {"Appearance": "Primary", "Spacing": "Compact", "State": "Hover"}}, keyed by property name. Every value is checked against the declaration; an unknown property or value is refused, all of them listed at once. A property left out sits at its default.
- **By name** — without `tags`, a new or renamed example is placed by its name when the name follows the declaration: `Primary · Compact · Hover` (one segment per property, in order), a shorter `Primary · Hover` where each segment belongs to exactly one property, or Figma's `Appearance=Primary, Spacing=Compact, State=Hover`. A name that could mean two things (`Default` when two properties have one) places nothing; a new example whose name can't be placed is refused. Explicit `tags` always win over the name.
- Name examples by that convention anyway — it is what the page and every agent read.

#### Calls

- Create a component: `{"domain": "components", "handle": "<key>", "create": true, "value": {name, description, platforms, properties, nested}}`.
- `platforms` says which surfaces it is built for: a list from `universal`, `app`, `mobile`, `website`, `marketing`, `email` ("universal" stands alone), or [] to clear.
- Create an example: add `"example": "<name>"` and `"create": true`, with `value` {html, css, tags}.
- Edit an example: `"example": "<name>"` with `value` {name, html, css, tags}, or `find` + `replace` over its html and css. An edit carries into every component that draws this one.
- A component's key can't change; it is how every agent and host refers to it.

### Bulk import

Bringing a design system in? Don't write it one item at a time — that is hundreds of calls, and values get dropped and mistyped on the way. `tokens` and `components` take `import` in place of `handle` and `value`, and a custom icon set takes it in place of `value`:

- `{"source": "<https URL>"}` — the server fetches the JSON itself (a raw GitHub file, unpkg, a CDN; a github.com/…/blob/… link is read as its raw file). Prefer this: nothing passes through you, so nothing is retyped.
- `{"document": …}` — the JSON inline, as an object or a string, when there is no URL.
- `"dryRun": true` — answers with what the import would do and writes nothing. Show it to the user before a large import.
- `"duplicates": "merge" | "skip" | "keep"` — what to do with items that repeat what the brand already holds under **another name** (the same colours as an existing ramp, the same value as an existing semantic colour, spacing, radius or shadow, a component the brand already has under another key). Every import checks for them and lists them in `duplicates`, with what each matches and why. `merge` writes them into the existing items and keeps those names (a ramp's shades replace the existing group's at the same steps, and references to it follow); `skip` leaves them out; `keep` adds them anyway. An import that finds duplicates and wasn't told what to do refuses, so run it with `dryRun` first, show the user the list, and pass their choice.

Everything is validated before anything is written, and every problem comes back in one refusal. The writes land together; one that fails partway is rolled back. The whole import is **one change with one changeId**, so a single undo takes it back.

#### Tokens

`{"domain": "tokens", "import": {"source": "https://…/tokens.json"}}` reads W3C DTCG (`$value`, `$type`, `$description`), Tokens Studio and Style Dictionary (`value`, `type`). A Tokens Studio file's sets are merged in `$metadata.tokenSetOrder`; pass `"sets": ["global", "light"]` to choose them. At most 5,000 tokens per file. How each token lands:

- Literal colours keyed like steps (`blue.500`, or `Blue500` beside `Blue600`) become a ramp per group, and the group's `$description` its role.
- Colours that alias another (`{color.blue.700}`) become semantic colours named by their path (`background.brand.bold` → `background-brand-bold`), referencing the shade. An alias of an alias points straight at the shade underneath. Other literal colours become semantic colours holding the value.
- Typography composites become styles, grouped into one family per font family. A new family holds only the styles the file gives it.
- Dimensions under a spacing word (space, gap, inset…) become spacing; under a radius word (radius, rounded, corner…) radius. px and rem (read at 16px).
- One-layer shadows become shadows.
- Modes: Archetype's own export (`os.archetype.modes`) and a Tokens Studio file's `$themes` (a mode per theme, unless `sets` is given) become the brand's modes, joined onto any it has. Only semantic colours take a value per mode.
- Existing tokens with the same name are updated; nothing the file doesn't mention is removed.
- Everything else is skipped and listed by reason: multi-layer and inset shadows, negative or em/% values, sizes and border widths, font weights, motion and opacity tokens. Report those as gaps.

#### Components

`{"domain": "components", "import": {"source": "https://…/kit.json"}}`, where the file is `{"components": [...]}`, a list, or one component:

```json
{"components": [{
  "key": "button", "name": "Button", "description": "…", "nested": false,
  "properties": {"Appearance": ["Default", "Primary"], "State": ["Default", "Hover"]},
  "examples": [
    {"name": "Default · Default", "html": "<button class=\"btn\">Save</button>", "css": ".btn { … }"},
    {"name": "Primary · Hover", "html": "…", "css": "…"}
  ]
}]}
```

- Components are matched by key and examples by name: a match is updated, anything new is added. Every rule for a single example applies to each one, including placement on the properties.
- Examples the import doesn't name are kept, unless `"replaceExamples": true`. If the import declares properties, the kept ones are placed on them too.
- An import doesn't carry markup changes into other components that draw these.

#### Icons

`{"domain": "icons", "handle": "<custom set slug>", "import": {"document": {"icons": [{"key": "arrow-right", "name": "Arrow Right", "svg": "<svg …>"}]}}}` — or a `source` URL of that JSON. Each icon takes `svg` or its own `source`, plus `tags` and `usage`. Icons whose key the set already has are updated; none are removed. At most 200 per call and 2,500 per set.

#### Rolling back

`{"undo": "<changeId>"}` takes back one import. To return to before a session of changes, `{"undo": {"since": "<changeId of the first one>"}}` undoes that change and every later one you made, newest first, stopping at any that something else has changed since.

### Templates

A template is a finished layout the brand ships over and over, made of **frames**: fixed-size artboards of HTML + CSS — one per slide, page or screen. `handle` is a template key.

- **Add one** with `create: true` and its frames, all in one call:

```json
{"domain": "templates", "handle": "launch-story", "create": true, "value": {
  "name": "Launch story", "description": "Product launch announcement", "format": "instagram-story",
  "frames": [{"name": "Cover", "html": "<div class=\"story\">…</div>", "css": ".story{…}",
    "bindings": {"headline": {"text": "Meet the new app"}, "logo": {"logo": "Logo Light"}, "photo": {"file": "hero.jpg"}}}]
}}
```

- `type` is social, web, app, files; a `format` implies it. A format id sets the size and says what the frame is for — social: instagram-post, instagram-portrait, instagram-story, instagram-reel, facebook-post, facebook-portrait, facebook-story, facebook-link, facebook-cover, facebook-event, linkedin-post, linkedin-portrait, linkedin-landscape, linkedin-carousel, linkedin-article, linkedin-event, linkedin-page-cover, linkedin-banner, x-post, x-square, x-portrait, x-header, tiktok-video, tiktok-photo, youtube-thumbnail, youtube-short, youtube-post, youtube-banner, pinterest-pin, pinterest-square, pinterest-story; web: website-desktop, website-laptop, website-tablet, website-mobile, email-newsletter, email-header, display-ads-medium-rectangle, display-ads-large-rectangle, display-ads-leaderboard, display-ads-half-page, display-ads-skyscraper, display-ads-billboard, display-ads-mobile-banner, link-preview-og; app: desktop-web-app, desktop-laptop, ios-iphone, ios-iphone-max, ios-ipad, android-phone, android-tablet, app-store-iphone, app-store-ipad, google-play-screenshot, google-play-feature; files: presentation-wide, presentation-standard, document-a4, document-a4-landscape, document-letter, print-flyer, print-poster, print-business-card. Several ids that share a size can go in a list. With no format, give `width` and `height` in px.
- `format` on the template applies to every frame; a frame's own `format`, `width` and `height` win. A frame with neither is the size of the one before it.
- **Slots** are the parts meant to change between uses: mark the element with `data-ax-slot="headline"`, then bind it in `bindings` — `{"text": "copy"}` (editable copy), `{"logo": "<logo name>"}`, `{"file": "<library image name>"}`, `{"artifact": "<handle>"}`, `{"token": "<path>"}` (exposed to the slot's CSS as `var(--ax-slot)`), `"region"` (the content area a design fills), or `"static"` (stays as drawn). A bound logo, image or artifact replaces what the element drew, so draw a placeholder of the right size.
- **A frame** — `frame` is its name, or its number from 1. `value` {slots: {"<slot>": "new text"}} changes copy and is the edit to prefer; {name, html, css, bindings, format, width, height} or `find` + `replace` change the rest. In `bindings`, `null` unbinds a slot.
- Add a frame with `frame` (its new name) and `create: true`, `value` {html, css, bindings, format, width, height}. `delete: true` removes a frame, or the template with no `frame`.
- A template's `value` {name, description} edits it; its key and type are fixed.

#### Page libraries and designs

A `files` template with more than 6 fillable frames is a **page library**: a cover, a contents page, chapter dividers, content and data pages, often in several drafts — page types to build documents from, not one design to fill whole. To build a document, pick the pages it needs in the order it needs them, using a page as often as it helps, and fetch only those: get_brand {"domain": "templates", "handle": "<key>", "frame": ["Cover A", "Contents", …]}.

Save the result as a **design** — it opens in the app, stays linked to the template, and exports as one PDF:

```json
{"domain": "designs", "handle": "brochure-pages", "create": true, "value": {
  "name": "SedumMax mounting guide", "brief": "What the document is for",
  "pages": [{"frame": "Cover A", "slots": {"title": "Mounting guide", "photo": {"file": "roof.jpg"}}},
    {"frame": "Chapter divider", "slots": {"number": "01", "title": "Before you start"}},
    {"frame": "Chapter divider", "slots": {"number": "02", "title": "Laying the rolls"}}]
}}
```

- `pages` is the document in order, at most 24. `frame` is a frame's name or its number from 1; only a page library's frames may repeat.
- `slots` fills the slots get_brand marks `editable`: copy for a text slot, {"file": "<library image name>"} for a photo. A slot left out shows the template's own.
- A design is created only. It is changed, exported and deleted on its page in Archetype, and isn't undone from here.

### Limits

| What | Limit |
| --- | --- |
| Components per brand | 200 |
| Examples per component | 240 |
| Example html / css | 120,000 / 200,000 characters |
| Component or example name | 80 characters |
| Component description | 400 characters |
| Properties per component / values per property | 8 / 40 |
| Token role / colour step | 60 / 20 characters |
| Tokens per import / import file | 5,000 / 8 MB |
| Templates per brand / frames per template | 200 / 60 |
| Frame html / css | 1,500,000 / 1,000,000 characters |
| Frame size | 16–16,000 px a side |
| Artwork by `source` / `data` | 20 MB / 1.5 MB |
| Icon SVG / icons per set | 24,000 characters / 2,500 |

### What the brand can't hold yet

Report these as gaps rather than approximating them silently: percentage, em and rem values; negative spacing; shadows with more than one layer; font-weight, border-width, opacity and motion tokens; a palette shade, a type style or a spacing step that changes by mode (only semantic colours do).

## Resources

The server also exposes MCP resources for clients that prefer them:
`archetype://context` (the brief, Markdown), `archetype://tokens` (DTCG JSON),
and one per voice document, artifact, component and icon set.

## Agent skills

The MCP server gives an agent the tools. A skill gives it the judgment about
when to reach for them and what counts as done. Skills follow the `SKILL.md`
convention, so the same file works across Claude Code, Codex, Cursor and other
agents that support it.

- **`brand-build`** — Build inside the brand: orient, fetch by handle, use the brand's own values verbatim, check the result, report every gap.
  Install: `https://www.heyarchetype.com/skills/brand-build/SKILL.md`
- **`brand-audit`** — Grade work against the brand's authored values and return a worst-first fix list with exact targets.
  Install: `https://www.heyarchetype.com/skills/brand-audit/SKILL.md`
- **`brand-import`** — Bring a repo's tokens and real rendered components into the brand in one reviewed bulk import.
  Install: `https://www.heyarchetype.com/skills/brand-import/SKILL.md`

Install one into Claude Code:

```shell
mkdir -p ~/.claude/skills/brand-build && \
  curl -sL https://www.heyarchetype.com/skills/brand-build/SKILL.md \
  -o ~/.claude/skills/brand-build/SKILL.md
```

For Codex, use `~/.agents/skills/` instead. The skills drive the MCP tools, so
connect the server first — without it they have nothing to call.

## HTTP endpoints

For tools that can't speak MCP. These are authenticated by an API key (not
OAuth): create one in Settings → Agents → API and send it as
`Authorization: Bearer <token>`. Each is scoped to the one brand in its path.

- `GET https://www.heyarchetype.com/api/brands/{slug}/brand.md` — the brand brief as Markdown: tokens and logo usage inline, voice documents, and an inventory of everything else.
- `GET https://www.heyarchetype.com/api/brands/{slug}/tokens.json` — all design tokens as W3C Design Tokens (DTCG) JSON.
- `GET https://www.heyarchetype.com/api/brands/{slug}/fonts.css` — `@font-face` rules for the brand's typefaces.
- `GET https://www.heyarchetype.com/api/brands/{slug}/bundle.zip` — the whole design system as a downloadable bundle.
- `GET https://www.heyarchetype.com/api/brands/{slug}/bundle.json` — the same files as JSON (`{ brand, generatedAt, files: [{ path, content }] }`), which is what the CLI reads.
- `POST https://www.heyarchetype.com/api/brands/{slug}/check` — grade code, CSS or markup against the brand. Send `{ "subject": "<the file>" }`; get back a verdict and a worst-first list of findings, each naming the exact token to use. One file per call: an over-long subject is refused rather than truncated, because a half-read file would report the rest clean.

## Keeping the files in a repository

The bundle is the brand as files an agent reads without a connection — and
the build can import: `tokens.css`, a Tailwind 4 `tailwind.css`,
`AGENTS.md` rules, components and voice. The `archetype-os` CLI (Node 20+, no
dependencies) keeps a repository's copy current:

```sh
npx archetype-os init --url https://www.heyarchetype.com --brand <slug>   # once, at the repo root
npx archetype-os pull                                   # whenever the brand changes
npx archetype-os pull --check                           # in CI: exit 1 if archetype/ is behind
```

`init` signs in through the browser (the same OAuth consent as an MCP client,
read-only), saves the brand to `archetype.json`, pulls it into `archetype/`
and points the repository's `AGENTS.md` at the rules. `pull` rewrites only the
files that changed, so an unchanged brand leaves an empty diff. In CI, set
`ARCHETYPE_TOKEN` to an API key instead of signing in.

- `https://www.heyarchetype.com/ci/archetype-pull.yml` — a GitHub Actions workflow that opens a
  pull request whenever the brand changes.

## Checking work as it is built

The same check, run by the agent's own harness at the moment it tries to call
the work done — so it happens on a session that drifted, a session that forgot,
and a session that was sure it was already fine.

- `https://www.heyarchetype.com/hooks/archetype-hook.mjs` — the hook. Node 20+, no dependencies.
- `https://www.heyarchetype.com/hooks/archetype-hooks.json` — the `hooks` and `env` blocks to
  merge into `.claude/settings.json`.

A `PostToolUse` hook notes every file written; a `Stop` hook grades those files
and, on a finding at or above the fail-at line, hands the worst-first fix list
back to the agent instead of letting it stop. The agent fixes the drift in the
session that caused it, against exact target values, rather than leaving it for
a reviewer who has to go and look up what the token was.

This is the surface the MCP server cannot be: the server never sees what was
produced, so asking the model to grade its own output is
an instruction it is free to skip. The harness is not.

Grading stops after two rounds, and any misconfiguration — a missing token, an
unreachable API — prints a notice and lets the session end. A check that traps a
session is a check that gets deleted.

## Checking work in CI

The same check again, run over what a pull request changed. It catches what
reaches a repository; the hook catches what an agent builds, including the work
that never becomes a commit.

- `https://www.heyarchetype.com/ci/archetype-check.mjs` — the checker. Node 20+, no dependencies.
- `https://www.heyarchetype.com/ci/archetype-check.yml` — a GitHub Actions workflow to copy.

**Commit both into the repository rather than fetching them at build time.** A
pipeline that downloads and runs a remote script on every push executes whatever
that URL returns today; vendored, it is auditable and pinned like any other
dependency.

It fails the build on *drift* — a value the brand has already answered and the
code got wrong — and reports gaps and hardcoded-but-correct values without
blocking. `--fail-at` moves that line; `--all` grades every tracked file
instead of the diff, which is the way to see where a codebase stands on day one.

## Notes

- Tools are pure reads. Nothing in this API writes to a brand — including the
  check, which stores neither the subject nor its findings.
- A brand is edited by its owners at https://www.heyarchetype.com, not by an agent. If you find
  something missing, report it — that is how the brand's owners learn what it
  doesn't cover yet.