# Atelier CMS by AIncient Labs — full documentation
# Accessibility & contrast (https://aincient-labs.com/docs/accessibility)
As you and the agent shape colours in the **Design System** studio, the studio checks them for legibility — so a beautiful palette is also a readable one.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Contrast is checked as you go [#contrast-is-checked-as-you-go]
Whenever the agent proposes colours — or you set them by hand — the **Design System** studio measures them against **WCAG AA** contrast. It checks the combinations that matter for reading:
* Text against the surface it sits on.
* Accent colours used as text or links.
If a combination falls short, the studio surfaces an **advisory warning** right where the colour lives, so a low-contrast brand doesn't quietly slip through.
## The agent steers toward legible choices [#the-agent-steers-toward-legible-choices]
The agent reads the same contrast feedback you see. When Fernway Botanical Studio asks for "a deeper forest green for links," the agent uses the check to keep the result readable against the page — and flags it if a request would push a colour below AA.
## Advisory, not a wall [#advisory-not-a-wall]
Contrast warnings are **advisory** — you stay in control. Atelier won't overrule your choice, and nothing publishes on its own. But the warnings are there for a reason: heed them unless you have a deliberate one to look past them.
## Alt text keeps pages accessible too [#alt-text-keeps-pages-accessible-too]
Colour contrast is only part of the picture. Describe your images with **alt text** so people using screen readers — and search engines — understand what each image shows. It's a short, plain description you add in the **Library**.
When a warning appears, the fastest fix is usually to darken the text or lighten the surface by a step — then watch the advisory clear in place.
Adjust colours by hand with a live contrast check on every one.
Write descriptions that keep your pages accessible.
# Your account (https://aincient-labs.com/docs/account)
The account flyout lets you check your identity and manage your profile right inside the console.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Your identity card [#your-identity-card]
Open the flyout from your avatar in the top-right. It shows a read-only identity card with your name, email, roles, and status — a quick check of who you're signed in as.
## Manage account [#manage-account]
**Manage account** opens an in-console pane where you can:
* Change your email.
* Change your password.
* Set your timezone.
* Upload or remove your avatar.
There's no need to leave the console for a Drupal form.
Changing your email or password re-verifies your current password on the server for safety. One
exception: right after you sign in with a one-time link (for example **Edit my site** in the Atelier
manager, or `atelier app open`), you can set a password without entering a current one. Use this to get back to password
sign-in when email password reset isn't set up on your site.
## One-time sign-in links [#one-time-sign-in-links]
Opening a one-time sign-in link while you're already signed in:
* **As the same user** — takes you straight to the console.
* **As someone else** — asks **Switch account?**. Choose **Sign out and continue** to sign in as the
link's user, or stay signed in as yourself; the link stays usable until it expires.
## Other doors in the menu [#other-doors-in-the-menu]
The same menu holds two more entries:
* **Set up AI providers** — reopens the onboarding wizard.
* **System** — for site administrators, a door to the technical back office at `/admin`.
Reconnect providers or rebind a model to a role.
# Generating & editing images with AI (https://aincient-labs.com/docs/ai-images)
With an image provider connected, you can create and edit images by chatting — no photo shoot or design tool required.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Connect an image provider first [#connect-an-image-provider-first]
Image generation runs on a connected provider. A Google Gemini key powers Nano Banana image generation, which you connect during setup — see [onboarding](/onboarding). Once a provider is connected, the AI rail appears in the [Library](/media-studio) and in the section you're working on.
## Generate an image from a prompt [#generate-an-image-from-a-prompt]
Describe what you want and Atelier creates it. For Fernway Botanical Studio you might ask for "a sunlit shelf of trailing pothos in terracotta pots." The new image lands in your [Library](/media-studio) and drops into the section you're working on, ready to preview.
## Edit an existing image in plain language [#edit-an-existing-image-in-plain-language]
Point the agent at an image and describe the change — for example:
* "make it warmer"
* "remove the background"
* "crop to a square"
Atelier produces a **new** image from your request. It never overwrites the original, so you can keep both and compare. If you prefer the edited version, use **Replace original with this** to swap it in.
## Where generated images are saved [#where-generated-images-are-saved]
A generated or edited image is saved to your **Library** the moment it's ready — as a new item, opened in the editor for you to review. This is deliberate, and it's different from how the agent edits pages or your brand.
Image generation runs on your connected provider and costs real money each time. So instead of holding the result somewhere temporary that a refresh or a wrong turn could wipe out, Atelier keeps what you paid to create. You'll never lose an image to a stray click.
Saved to your **Library** is not the same as live on your **site**. A Library image is private to your console. It reaches visitors only when you place it on a page and click **Publish** — the same guarantee that applies everywhere in Atelier.
## It's still your decision, not the agent's [#its-still-your-decision-not-the-agents]
Saving the image to your Library doesn't take the choice away from you. You stay in control:
* **Nothing is ever overwritten.** Every generation and every edit is a *new* item. The agent doesn't touch, replace, or delete anything you already have.
* **Keep it, or don't.** Review the result in the editor. Keep it, ask for another variation, or click **Delete** to discard it — deleting a freshly generated image is safe and removes it completely.
* **Swap it in only if you choose.** For an edit, **Replace original with this** repoints the original — and only when you press it.
Iterate freely. Because every edit makes a new image instead of replacing the last one, you can try "warmer," then "brighter," then go back — nothing is lost, and nothing you don't want sticks around.
Where your images live and get edited.
Set up the key that powers image generation.
# Alt text for accessibility (https://aincient-labs.com/docs/alt-text)
**Alt text** is a short description of what an image shows. Add it once, and Atelier uses it automatically wherever the image appears.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Write it once, on the image [#write-it-once-on-the-image]
Open an image in the [Library](/media-studio) and add its alt text in the editor rail. You describe the image on the image itself — not on every page that uses it. For Fernway Botanical Studio, the shop-front photo might read "Fernway's storefront window filled with hanging ferns and monstera."
Because the description travels with the image, every page that shows it inherits the same alt text automatically. Reuse the photo on the homepage and the About page, and both stay described.
## Why it matters [#why-it-matters]
* **Screen readers** read your alt text aloud, so people who can't see the image still understand it.
* **Search engines** use it to understand what your images show, which helps your pages surface.
* **Fallback text** appears if an image ever fails to load.
## Let the agent draft it [#let-the-agent-draft-it]
The agent can help you describe an image. Ask it to look at an image and it drafts alt text into the editor rail for you to review and save. It can also propose a friendly name for the image at the same time.
The agent proposes; you approve. A drafted description sits in the editor rail until you review and **save** it — you stay in control of the words that describe your site.
Good alt text describes what the image shows and why it's there, in a sentence — not "image123.jpg." Let the agent draft it, then tighten it in your own voice.
Where you add and edit alt text.
How images are placed and served across your site.
# AI proposes, you approve (https://aincient-labs.com/docs/approval-model)
Atelier's defining stance is simple: the agent proposes, and you approve. Nothing reaches your live site until you say so.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
This is architectural, not a setting you can switch off. The agent never changes your live site on its own. It works on an unsaved draft and shows you a live preview — and your site changes only when you press **Publish**.
**The guarantee:** the agent only ever edits an unsaved draft and shows a live preview. Your live site changes solely when you click **Publish**. The agent cannot publish for you.
Two mechanisms enforce this.
## Drafts and Publish [#drafts-and-publish]
In the **Design System** and **Pages** studios, the agent only edits a draft.
You describe a change; the agent updates the draft and renders a live preview.
Look over the preview until it's right — keep refining with the agent as needed.
Press **Publish** to make it live, or **Discard** to throw the draft away. Discard asks you to confirm, so you can't wipe work by accident.
## Generated images: saved, but still yours to decide [#generated-images-saved-but-still-yours-to-decide]
One thing works a little differently. When you generate or edit an image, it's saved to your **Library** right away — because generation costs real money and Atelier won't discard what you paid to create. That's a private Library item, not a change to your live site: it reaches visitors only when you place it on a page and **Publish**. And it's still your call — every image is a new item, nothing is overwritten, and you can **Delete** it. See [generating & editing images](/ai-images).
## Approval pauses [#approval-pauses]
When a conversation reaches a step that would change your site, it pauses and asks you to approve before continuing.
You approve, and only then does the step run — exactly once. Nothing happens behind your back, and nothing runs twice.
## Why it matters [#why-it-matters]
You get the speed of an agent with the control of a human editor. The agent does the heavy lifting; you stay the one who decides what goes live.
See where drafts and previews live.
Compose pages section by section on a draft.
# Editing your brand by hand (https://aincient-labs.com/docs/brand-editor)
You don't have to do everything in chat — the **Design System** studio's editor groups every brand choice into four cards you can adjust by hand.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Where the editor lives [#where-the-editor-lives]
Open the **Site** menu in the top nav and choose **Design System**. This studio sets your brand — the colours, type, and shapes every page inherits. The editor sits beside a live preview, so you watch each change land as you make it.
## The four cards [#the-four-cards]
Set your brand, accent, and page colours. Each one carries a live contrast check so you can see at a glance whether text stays legible on it.
Pick a font pairing from a gallery — every option is previewed in its real typeface. Then set your body text size and heading weight.
Dial in corner roundness, spacing density, and the shadow. The shadow is built from independent dials rather than a fixed preset.
Fine-tune individual elements — buttons, cards, and the like — once the foundations feel right.
### Shadows are dials, not presets [#shadows-are-dials-not-presets]
The **Shape & depth** card sets the shadow through independent controls: distance, blur, strength, colour, and the direction the light falls from. Because each is its own dial, you can ask for "softer" or "light from the left" and only that single quality changes — the rest of the shadow stays put.
## High-level first, precise controls behind Advanced [#high-level-first-precise-controls-behind-advanced]
Every card leads with the high-level choices most brands need. The precise, per-token controls tuck behind an **Advanced** section on each card, so the surface stays calm until you want to go deeper.
## Preview, revert, publish [#preview-revert-publish]
Adjust a colour, font, or dial and the preview updates live. A dirty-count badge tracks how many unsaved edits you have.
Roll back a single field on its own, or **Discard** the whole draft to return to what's currently live.
Nothing is saved until you click **Publish**. Only then does your brand go live across the site.
The agent never publishes on its own. Whether you edit by hand or by chat, you're working on an **unsaved draft** — your brand changes go live only when you press **Publish**.
## Edit by hand, by chat, or both [#edit-by-hand-by-chat-or-both]
The agent reaches for these exact same choices when you describe a change in chat. Ask Fernway Botanical Studio's assistant to "warm up the accent green," then open the **Color** card and nudge it further by hand. The two ways of working share one draft, so you can move between them freely.
Watch the dirty-count badge before you leave the studio — it's your reminder that there are unsaved edits waiting for a **Publish** or a **Discard**.
See how the agent proposes brand changes from a conversation.
Learn how the studio checks your colours for legibility.
# Overview (https://aincient-labs.com/docs/brand-studio)
The Design System studio is where you set your site's identity by talking to the agent. You describe
the look you want, the agent proposes a brand direction, and you see it applied live across
real components. **Nothing changes your site until you click Publish.** It is the brand
counterpart of the [Pages studio](/page-studio): the agent previews, you decide.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
The agent never sets your brand on its own. It proposes a **draft** brand and renders it in
the preview. Your site's brand changes only when **you** press **Publish** in the studio.
## Open the studio [#open-the-studio]
Go to the Atelier console at `/atelier`.
Pick **Design System** from the studio switcher in the top breadcrumb. The studio pane opens
beside the chat with a live preview of your current brand.
Tell the agent the feel you're after — for example, *"a warm, editorial look for a
neighbourhood bakery"* or *"clean and techy, deep blue."* The agent proposes a brand
direction and applies it to the preview.
## How your brand is set [#how-your-brand-is-set]
Your brand is a set of **design tokens** — colours, typography, and surface treatments — that
every page and component reads from. The agent proposes values for these tokens and the
preview reskins instantly so you can judge the result on real components, not swatches.
You refine in chat (*"warmer accent"*, *"more contrast on the headings"*, *"try a softer
surface"*) and the preview updates with each change. You can also start from a curated
**preset** and adjust from there.
Because the whole site reads from these tokens, a brand change flows everywhere at once —
every page, every component, your site chrome and login screen included.
## Edit by hand [#edit-by-hand]
You don't have to do everything in chat. The studio's editor panel groups every choice into
four cards, so you can find what you want without wading through raw settings:
* **Color** — your brand, accent, and page colours, each shown with a live contrast check.
* **Typography** — pick a **font pairing** from the gallery (each previewed in its real
typeface), then set body text size and heading weight.
* **Shape & depth** — corner roundness, spacing density, and the **shadow**. The shadow is set
by independent dials — **distance**, **blur**, **strength**, **colour**, and the **direction**
it falls — rather than a fixed "style", so you (or the assistant) can say "softer", "bigger",
or "light from the left" and only that one thing changes; the rest of the look stays put.
* **Components** — fine-tune individual elements like buttons and cards.
Each card leads with these high-level choices and tucks the precise per-token controls behind
an **Advanced** section, so the full design system is there when you need it and out of the way
when you don't. Every change previews live, and nothing is saved until you **Publish**.
The agent reaches for the same choices — ask for *"the editorial pairing with softer corners"*
and it sets them for you. Edit in chat, by hand, or both.
## Built-in accessibility checks [#built-in-accessibility-checks]
As the agent proposes colours, the studio checks them for legibility — text against its
surface, and accent colours used as text or links — against WCAG AA contrast. If a
combination fails, the studio surfaces an advisory warning so a low-contrast brand doesn't
slip through. The agent uses the same feedback to steer toward legible choices — and it only
tells you a colour pair passes when the measured ratio says so. If a change you asked for fails
contrast, the reply names the ratio (for example *3.4:1, needs 4.5:1*) and offers a fix.
Accessibility warnings are advisory — you stay in control. But they're there for a reason:
a brand that fails contrast is hard to read for everyone.
## Publish or discard [#publish-or-discard]
When the preview looks right:
* **Publish** saves the brand and creates a revision. The new identity goes live across your
whole site immediately.
* **Discard** throws the draft away and keeps your current brand. You're asked to confirm
first, so a published brand is never replaced by accident.
Because every publish creates a revision, your brand has a history you can fall back on.
## Brand and pages [#brand-and-pages]
Pages always render with your published brand — there's no per-page colour or preset lever.
You set the identity once, here, and every page stays consistent with it. If a page's colours
aren't what you want, change them in the Design System studio, not on the page. See [Pages always
respect the brand](/page-studio#pages-always-respect-the-brand).
# Bring your own components (https://aincient-labs.com/docs/bring-your-own-components)
The [component library](/components) is deliberately curated: the agent composes from a
closed set of sections so every page it produces looks designed. But agencies and teams
with their own design system usually want one thing first: **keep the grammar, swap the
markup**. That is supported today, with ordinary Drupal tools and no fork.
This page is for developers. Everything here happens in a module and a Dockerfile —
nothing in the console changes, and editors keep working exactly as before.
## The shape: a derived image [#the-shape-a-derived-image]
The appliance is a versioned Docker image. Your customisation is a second, *derived* image:
a five-line Dockerfile that starts from a pinned Atelier release and copies one module in.
```dockerfile
FROM ghcr.io/aincient-labs/atelier-cms:v0.10.0
COPY my_components /opt/drupal/web/modules/custom/my_components
```
Deploying is then an image tag, upgrades are a PR that bumps the `FROM` pin, and a
rollback restores code and content together — the same lifecycle as a stock appliance.
Never edit the running container or mount code into production: anything outside the
image is invisible to snapshots and reappears differently after an upgrade.
## Replace a built-in's markup [#replace-a-built-ins-markup]
Drupal's component system has first-class replacement: a single-directory component in
your module can declare that it **replaces** one of ours. Same name, same props, same
place in the agent's grammar — your HTML.
```yaml title="my_components/components/hero/hero.component.yml"
name: Hero
replaces: 'aincient_pages:hero'
props:
# Copy the original's props schema verbatim — the replacement must accept
# exactly what the validator sends the original.
```
Copy the original component's `.component.yml` props from the
`aincient_pages/components/` directory of the release you pinned, keep the schema
identical, and write your own Twig. The page agent, the validator, and every existing
page keep working: they speak in component names and props, and the renderer picks up
your implementation.
In the Components studio, a replaced component shows a **Replaced by** badge with your
module's name. The site owner can preview your version and the original side by side
(**Compare**), and switch one back with **Use original instead** — your module stays
installed, the site just renders the original until they switch it on again.
Component replacement is core Drupal — see the official
[single-directory components documentation](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components)
for the mechanics.
## The token contract [#the-token-contract]
Every built-in styles itself through the site's **design tokens** — CSS custom properties
the Design System studio writes (`--brand-primary`, `--brand-accent`,
`--neutral-surface`, `--neutral-ink`, `--font-family-display`, the radius and shadow
scales, and so on). That is the whole reason a rebrand reskins the entire site with zero
component edits.
Your replacement markup must honour the same contract:
* **Colours come from tokens, never raw values.** `color: var(--neutral-ink)`, not
`color: #111`. A hardcoded hex survives the first rebrand looking wrong.
* **Fonts come from `--font-family-base` / `--font-family-display`.** The brand's
self-hosted web fonts only apply to markup that asks for them.
* **Never dim text with `opacity`.** Use the muted foreground token
(`--neutral-muted-foreground`) — opacity-dimmed text breaks contrast in one theme or
the other, and the accessibility checks will flag it.
* **Respect the `tone` prop.** Sections render on `default`, `muted`, `brand`, or
`inverted` surfaces; your markup should key its surface and on-colours off the tone it
is given, like the originals do.
## Adding new components: packs [#adding-new-components-packs]
Replacement changes how a section *looks*, not which sections exist. To add **new**
components to the agent's palette — placed, validated, and governed like the built-ins —
build a [component pack](/component-packs): an ordinary Drupal module with a small
manifest, a local dev loop with live reload and a component gallery, and a CI reference
pipeline that ships your pack as a deployable image.
## What's not supported (yet) [#whats-not-supported-yet]
* **Component JavaScript.** The contract is CSS-only for now: server-rendered Twig,
styled through the tokens. Interactive behaviour beyond what the built-ins ship has no
supported channel yet.
* **New agent capabilities.** A module may add components, page kinds and providers —
and, ahead, console studios — but never a new verb for the AI to call.
`atelier pack validate` rejects a `src/Plugin/AiCapability/` directory: the capability
roster is reviewed as a whole so that everything the agent can reach stays reversible
and internal.
If you're building against this, we'd like to hear about it — the roadmap is shaped by
real client component libraries. Reach us via [aincient-labs on GitHub](https://github.com/aincient-labs).
# Checking page health (https://aincient-labs.com/docs/checks)
The **Checks** studio reviews a page's health and helps you fix what it finds.
Checks is available when it's enabled for your site. If you don't see it in the console, it may not be turned on for your install.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## What Checks looks at [#what-checks-looks-at]
Checks runs deterministic checks on a page and reports what it finds. It covers:
* **SEO** — the signals that help search engines understand your page.
* **Meta tags** — the title and description that show up in search results and shares.
* **Internal-link integrity** — whether links to your other pages actually resolve.
Findings are grouped **worst-first**: fails first, then warnings, then passes. For Fernway Botanical Studio's care-guide page, that might surface a missing meta description at the top and a healthy internal link near the bottom.
## Fix with AI [#fix-with-ai]
For anything Checks flags, a repair agent can stage a minimal fix into your draft. You can apply it at three scopes:
* **A single finding** — fix just one flagged item.
* **A whole check** — resolve every finding under one category at once.
* **Fix all issues** — let the agent work through everything it can.
The repair agent proposes; it stages a **minimal** fix into your **draft**. You review it and nothing changes on your live site until you click **Publish**.
## Review what changed [#review-what-changed]
Fixes are staged into your draft, and Checks grades that draft straight away, before you save. A finding the fix cleared shows **Fixed in draft**. Each row starts with a line giving its status, its area (meta, content or structure), and who changed it: **Atelier** or **You**. Below that come the finding and the field's current value. Click a row to open it: the explanation, where the issue sits, and its **Fix with AI** and **Edit** buttons appear there. A passing or fixed row shrinks to a single line until you open it.
When changes are staged, a banner at the top of the findings sums them up, for example "4 changes staged · 1 needs you":
* **Filters**: **Needs you** lists issues you sent to Atelier that still fail after its fix. **Changed** lists every field that changed since your last save. **All** shows the full report. After a fix, Checks opens on **Changed**.
* **Previous / Next**: walk through the rows with the arrows, or press **J** and **K**. Opening a row shows what changed word by word, plus a **Revert** button that puts back the value from your last save.
* **Reviewed meter**: counts the changed rows you've opened. It's only a reading aid: you can save or publish at any time.
On a row that still needs you, **See Atelier's reply** jumps to the agent's answer in the chat, which usually says why it couldn't make the fix.
The fix card in the chat lists the fields that changed. Click one to jump to its row in Checks.
When you save, the revision message records who changed which field, for example "Atelier: Meta description · You: Page title".
## See it in context [#see-it-in-context]
The preview next to the findings has three views, picked in its top bar:
* **Page**: the page itself. A pin marks each section with an issue or a staged change, for example "1 fail · changed". Click a pin to open its row in the findings.
* **Search result**: how the page shows up in search, with your last saved version beside your draft.
* **Share card**: how a link to the page unfurls on social media and in chat apps, again saved beside draft.
The number on a view counts the open issues it shows. Opening a row switches to the view that shows it: a meta description opens **Search result**, an Open Graph tag opens **Share card**, and a broken link scrolls the page to the section that contains it.
## One row per fix [#one-row-per-fix]
Findings that one edit fixes share a row:
* **Share card**: when two or more Open Graph tags need work, they fold into one row. Open it to see each tag's value, what changed, and its own **Edit** and **Revert**. **Fix the card with AI** sends all of them in one request.
* **Broken links**: a page that links to the same missing page from several places gets one row, which says how many links go there and lists every place the link is written. Click a place to scroll the page to it. **Fix with AI** asks Atelier to point every copy at the same working page in one edit.
## Edit inline and re-run [#edit-inline-and-re-run]
You can also edit the page directly here:
* Adjust the **page title** or a **meta tag** inline.
* A live **character-range gauge** shows whether your text sits in the ideal length range as you type.
* **Re-run** (at the top of the findings) recomputes them after a change.
Saving and publishing work exactly as they do in the Pages studio: the same buttons sit in the
same place at the top right, and they follow your site's review steps. If the page is in review
and you can't approve it, Checks won't offer Publish either.
To open Checks from the Pages studio, use the **Checks** row in the editing panel. It shows how
many checks the saved page fails or warns on. Unsaved edits aren't checked until you save them.
Work top-down: fix the fails first, re-run, then clear the warnings. Let **Fix all issues** handle the routine repairs, and reserve your attention for the wording that only you can get right.
Where the page you're checking gets built and published.
# One writer at a time (https://aincient-labs.com/docs/collaboration)
When you open a page in the Pages studio, Atelier hands you the pen for that page.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Who holds the pen [#who-holds-the-pen]
Editing is granted one writer at a time, **per page and per language**. When you open a page
in the **Pages** studio, you hold the pen for it and can edit its draft.
If the same page is already open somewhere else — another browser tab, or a teammate — that
session holds the pen instead. Your studio goes read-only and shows a banner naming who has
it and since when:
* *"Alex is editing this page in Pages, since 2:14 pm."* — a teammate holds the pen.
* *"You're editing this page in another tab."* — it's you, elsewhere.
Because the lock is per language, someone editing the English version of Fernway Botanical
Studio's care guide doesn't block you from editing its German translation.
## Take over the pen [#take-over-the-pen]
Click **Take over** to move the pen to this studio. The other session immediately goes
read-only and can no longer save.
**Take over discards unsaved changes in the other session.** If the pen is held by your own
other tab, switch to it and save your draft or **Publish** first — anything unsaved there is
lost the moment you take over here.
The pen follows the **page**, not the conversation. Open the same page in a second tab and
you'll be asked to take over — even in the same chat. Keep one tab per page to avoid taking
over from yourself.
## Reload the latest version [#reload-the-latest-version]
If someone else saved while you were editing, Atelier doesn't blindly overwrite their work.
Instead it shows a **Reload latest** banner — a rebase — so you pull in their saved changes
and continue from the current version. Your live site is never quietly clobbered by a stale
draft.
Where the pen is handed out, and where you preview and publish.
# Component packs (https://aincient-labs.com/docs/component-packs)
A **component pack** adds new sections to the [component library](/components): components
your editors and the page agent can place, validated and governed exactly like the
built-ins. A pack is an ordinary Drupal module whose components carry a small block of
Atelier metadata — there is no plugin API to learn beyond Drupal's own
[single-directory components](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components).
This page is for developers. If you only want to restyle the built-in sections, start
with [Bring your own components](/bring-your-own-components) — replacement is simpler
and may be all you need. Packs require Atelier CMS `0.10.0` or later.
## Start from the template [#start-from-the-template]
Two equivalent starting points:
* Run `atelier pack new my_pack` with the [Atelier CLI](https://github.com/aincient-labs/manager) —
it scaffolds the whole pack with your module name in place.
* Or use the [`atelier-pack-template`](https://github.com/aincient-labs/atelier-pack-template)
repository on GitHub ("Use this template") and rename `my_pack` throughout.
The scaffold is a complete, shippable pack: one example component, the pack manifest, a
CSS build, a dev compose overlay, and a CI workflow that produces your deployable image.
## What makes a module a pack [#what-makes-a-module-a-pack]
Two files, beyond ordinary module structure:
```yaml title="atelier.pack.yml"
api: 1
name: my_pack
requires:
atelier: '^0.10'
provides: [components]
owns: []
```
And Atelier metadata on each component:
```yaml title="components/spotlight/spotlight.component.yml"
name: Spotlight
props:
# your JSON-schema props, like any single-directory component
thirdPartySettings:
atelier:
tier: section
use: 'A wide editorial spotlight with one strong claim and a supporting image.'
examples:
- '{"component": "spotlight", "props": {"heading": "…", "claim": "…"}}'
```
The `use:` line and `examples:` are how the agent decides when to place your component —
they travel into its prompt verbatim, so write them like you mean them. Every pack
component passes the same **admission gate** the built-ins pass before it reaches the
palette; a component the gate rejects is excluded and reported, never half-admitted.
## The dev loop [#the-dev-loop]
```bash
atelier pack dev
```
brings up a pinned Atelier appliance with your pack mounted and developer overlays
enabled: edit a Twig or CSS file, refresh, see it — no container restart. A Tailwind
watcher rebuilds your stylesheet, and the pack **gallery** at
`/atelier/packs/my_pack/gallery` renders every declared example at three widths, in
light and inverted tones.
* `atelier pack validate` — the admission gate, the manifest check, and a CSS lint;
exactly what a production boot runs. The lint reads the CSS you wrote — `build/input.css`
and the files it imports, such as `build/pack.css` — not the compiled
`assets/my_pack.css`, so a fresh scaffold validates without warnings. A pack with no
build step is linted on its stylesheet directly.
* `atelier mcp` — a stdio MCP server exposing the ground truth (catalog, gate, prompt
manifest, rendered examples, design tokens) to coding agents like Claude Code:
```json
{ "mcpServers": { "atelier": { "command": "atelier", "args": ["mcp"] } } }
```
`atelier pack dev` also syncs the appliance's token/utility preset into your repo, so
your CSS builds against the exact Atelier version you develop against.
## The contract [#the-contract]
* **Tokens, not hex.** Route every colour and size through the design tokens
(`var(--…)`) so a rebrand reaches your markup — the same
[token contract](/bring-your-own-components#the-token-contract) replacements follow.
* **CSS only, for now.** There is no JavaScript channel yet: server-rendered Twig,
styled through the tokens.
* **A pack is a module.** It runs with full Drupal power. Installing a pack is exactly
as much trust as installing any Drupal module — there is no sandbox.
* **A pack brings no new agent verbs.** A pack ships components, page kinds, providers
and (later) console studios — never a new capability for the AI to call. Atelier's
capability roster is reviewed as a whole: every verb the agent can reach is reversible
and internal, which is what makes it safe for the agent to act on content it did not
write. `atelier pack validate` **rejects** a pack containing a
`src/Plugin/AiCapability/` directory. If your pack needs an action the agent can take,
talk to us — that is a change to the product's security floor, not a directory you add.
## Ship: an image, not a deployment script [#ship-an-image-not-a-deployment-script]
Your pack bakes into a derived image, the same shape as
[markup replacement](/bring-your-own-components#the-shape-a-derived-image):
```dockerfile
FROM ghcr.io/aincient-labs/atelier-cms:v0.10.0
COPY . /opt/drupal/web/modules/custom/my_pack
COPY dev/pack.yml /opt/drupal/packs.d/my_pack.yml
```
The `packs.d/` file is the enablement declaration — the appliance enables declared packs
on every boot, idempotently, after config import. The scaffold's GitHub workflow is the
full reference pipeline: it rebuilds your CSS and fails on drift, builds the image, boots
it against a throwaway database, runs the admission gate and `atelier:kind-check` inside
the booted appliance, smokes the gallery, and pushes the validated image to your
registry. Deployment is that image tag; an Atelier upgrade is a PR bumping the `FROM`
pin, which the same pipeline proves your pack against before anything ships.
## Governance: kinds and constraints [#governance-kinds-and-constraints]
Adding components widens the space the agent composes in; two console surfaces narrow it
again per site:
* **Page kinds** scope which components, tones, and variants each kind of page may use —
a blog post doesn't offer the landing-page palette.
* The **Components studio** in the console can turn any component off site-wide; it
leaves the agent's palette and can't be placed again, while sections that already use
it are kept (see [Choose which components your site uses](/components#choose-which-components-your-site-uses)).
Changing a kind after pages exist is checked, not guessed: `drush atelier:kind-check`
reports every slot a narrowing would affect, per page and block, before you deploy it — it never
rewrites content.
If you're building a pack, we'd like to hear about it — the roadmap is shaped by real
client component libraries. Reach us via
[aincient-labs on GitHub](https://github.com/aincient-labs).
# Component library (https://aincient-labs.com/docs/components)
Every page you build in the [Pages studio](/page-studio) is assembled from a curated
component library. The agent never writes HTML or CSS — it arranges these named
**sections**, and each one is individually designed and reskins automatically from your
brand. The set is deliberately broad: you can build a marketing site, a company site, or a
news/blog site from it without custom components.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
Every component renders with your live brand tokens. Change a colour or font in the Design
System studio and the whole library reskins — see [Pages always respect the
brand](/page-studio#pages-always-respect-the-brand). Developers can extend this set with
their own sections — see [Component packs](/component-packs).
## Sections [#sections]
Sections stack top to bottom to make a page. You ask for them in plain language ("add a
pricing section", "put testimonials after the features") and the agent places them.
### Opening and structure [#opening-and-structure]
* **`hero`** — the top-of-page opener, the only full-viewport section. Centered or split
with an image. Open every page with one.
* **`logos`** — a quiet row of partner or customer logos for instant "trusted by"
credibility.
* **`divider`** — a light separator between sections: a rule, breathing space, or a small
centered label.
### Telling your story [#telling-your-story]
* **`content`** — a prose block paired with an image (or text-only). Alternate the image
side as you stack these.
* **`markdown`** — a block of long-form body text you author in Markdown (headings, lists,
links, bold/italic, blockquotes), rendered with a reading-optimised prose measure. Reach
for it when you have free-form formatted copy that no structured section models.
* **`features`** — a heading plus a grid of feature cards with icons.
* **`stats`** — a row of headline numbers for social proof.
* **`gallery`** — a grid of images.
* **`image`** — a single standalone image with an optional caption (a figure). Reach for it
to place one picture on its own — a screenshot, photo, diagram, or chart — when `content`
(image *with* text) and `gallery` (a *grid* of images) don't fit.
* **`banner`** — a short, bold full-width statement band.
### Building trust [#building-trust]
* **`testimonials`** — customer quotes, one strong quote or a grid of several.
* **`team`** — the people behind the company, with head-shots, names, and roles.
* **`faq`** — frequently-asked questions in an expand-to-read list (plain-text answers).
* **`accordion`** — an expand-to-read list whose panels hold **rich** content (formatted
copy, lists, links — and a figure), not just plain text. Each panel can mix Markdown text
and a single image. Reach for it for layered detail — documentation, how-tos, spec
breakdowns. Set it to open one panel at a time, or allow several at once.
### Converting [#converting]
* **`pricing`** — plan tiers side by side, with one tier highlighted.
* **`newsletter`** — an email sign-up band.
* **`cta`** — a closing call-to-action band. Close every page with one.
## Layout [#layout]
* **`grid`** — a bounded grid of equal **card** tiles. Reach for it only when no named
section fits — for example a set of resource links or related items. You set the number
of columns and the tiles reflow.
You rarely place a `grid` directly — most layouts are better served by a named section
like `features` or `gallery`. The agent picks the right one for what you describe.
## Choose which components your site uses [#choose-which-components-your-site-uses]
Open **Site → Components** in the console to see every component your site offers and
decide which ones it uses. Only administrators see this studio.
* **The centre shows each component, live.** Every component renders from a built-in
example in your published brand, so you see what you are offering before anyone places
it. Click one to look at it alone, switch its tone, and check it at phone (375),
tablet (768) and desktop (1280) widths.
* **The rail on the right is where you decide.** Components are grouped by what they do
(Openers, Story, Media, Social proof, Conversion, Structure, From your site), and each
row shows how many pages and blocks use it. Search, or filter to **Unused**, **Off** or
**Packs**.
* **Expand a row** to read what the component is for, turn off individual variants or
tones for that component alone, and see the pages and blocks that use it.
* **Nothing changes until you Publish.** Untick freely, then **Publish** to apply it, or
**Discard** to drop the changes. **Tones everywhere** turns a tone off for
every component at once; at least one tone always stays on.
### Page types and blocks [#page-types-and-blocks]
The **Applies to** menu at the top of the rail switches what you are deciding for:
**Everywhere** (the whole site), one **page type** such as Landing page, or **Block**
under *Reusable* (the reusable blocks you place on pages). A component turned off everywhere shows as
locked in every page type, with a link back to Everywhere.
For a page type you also choose:
* **New components from packs** — *Allowed automatically* offers a newly installed pack's
components on this page type straight away; *Off until I allow them* keeps them off
until you tick them.
* **Opener** — the section every new page of this type starts with, such as a hero.
* **Max per page** — in a component's expanded row, how many of it one page may hold.
A page type with a fixed layout, such as a blog post, has nothing to place, so it shows
a notice instead of components.
### Publishing shows what it affects [#publishing-shows-what-it-affects]
When a change touches pages or blocks that already use something you turned off,
**Publish** first lists them, grouped by page, and asks you to **Publish anyway** or
**Cancel**. Nothing on those pages changes; the list is so you know where the
**No longer offered** markers will appear.
### Ask the Components agent [#ask-the-components-agent]
The chat beside the studio can **review your components** — which ones fit what your site
is for, which are unused, and which tones read poorly with your published brand — and
make changes you ask for, everywhere or for one page type ("we never sell online, turn
off pricing", "landing pages should open with a hero"). It never publishes: a change it
makes appears in the rail as unsaved, and you review the affected pages and **Publish**
it yourself, or **Discard** it.
### Components from packs [#components-from-packs]
Components that come from a [component pack](/component-packs) show the pack's name and
sit under **Other**. A pack component that doesn't meet Atelier's rules is listed under
**Can't be used**, with the reason. When a pack replaces one of the built-in components,
the row shows **Replaced by** and the pack's name: select it to see the pack's version,
the original, or both side by side (**Compare**), and use **Use original instead** to
go back to the original on this site. Like every change here, it applies when you
Publish.
### Turning a component off keeps existing sections [#turning-a-component-off-keeps-existing-sections]
A component you turn off can't be added again — the agent stops offering it and it is
gone from the section picker — but **sections already on your pages stay and keep
rendering**. The same goes for a variant or tone you turn off. In the
[Pages studio](/page-studio) those sections show a **No longer offered** marker; you can
still edit them, and **Replace…** swaps one for a component your site still offers, in
the same spot.
## How sections stay consistent [#how-sections-stay-consistent]
* **Tone** — every section accepts a tone (`default`, `muted`, `brand`, `inverted`) that
picks its surface colour from your brand. Adjacent sections alternate automatically so a
page never blurs together.
* **Columns** — grids (features, gallery, team, pricing, the `grid` container) take a
column count; the items reflow responsively on smaller screens.
* **Variant** — some sections offer a named arrangement, such as a `centered` or `split`
hero, or a left/right image on a content section.
* **Anchors** — every section accepts an `anchor`: a short slug such as `pricing` that makes
the section reachable as `#pricing` from any link on the page (or `/plans#pricing` from
another page). Headings inside a `markdown` section get one automatically from their
text — "## Our team" is reachable as `#our-team`. Ask for it ("add a *See pricing* button
that jumps to the pricing section") or set it in the section's Appearance fields.
* **Inline formatting** — longer text fields (a subheading, body copy, a bio, quote,
answer, pricing description, or caption) accept light Markdown: links `[text](url)`,
`**bold**`, `*italic*`, and `` `code` ``. Just ask for it ("link *Oxford* to their site")
and the agent writes it in. Short labels (headings, button text, names) stay plain.
Inline formatting is intentionally limited to text marks. For a full block of formatted
copy — headings, lists, blockquotes — use the `markdown` section instead.
Because the palette is curated and every option is a good one, any page the agent composes
looks designed — on your brand, every time.
# Overview (https://aincient-labs.com/docs/console)
The console is where you run Atelier. It's a chat workspace at `/atelier`: you talk to an
agent, it does the work, and a live preview shows you the result. You're always in exactly
one **studio** — a focused workspace for one kind of task — and you switch between them as
your work changes.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Studios [#studios]
A studio pairs a chat with the right agent and the right preview for one job. You move between
studios from the top bar, and the Atelier wordmark always takes you home to the **General**
chat.
The home studio for everyday content work — creating, updating, and finding content by
asking. This is where the wordmark returns you.
Build pages section by section, rendered live on your brand.
Your reusable ingredients — media and reusable blocks. Upload, organise, and generate
images.
Set your site's visual identity. The agent previews brand directions; you publish.
Shape the site header, footer, identity, and menus. The agent previews the chrome; you
publish.
In the top bar, **Pages** and **Library** sit alongside a **Site** menu that groups the
site-wide studios — **Design System** and **Globals** — since you visit those less often. Each
studio keeps its own chat history and its own new conversations, so switching studios doesn't
tangle your work. When a studio offers more than one agent, a picker at the top of the chat
lets you choose which one a new conversation uses.
How the studio switcher, deep links, and jumps to your live site fit together.
## How a conversation works [#how-a-conversation-works]
You describe what you want in plain language. The agent replies with one short framing
sentence and gets to work — it doesn't narrate every step. As it works:
* The **preview** updates live so you see the real result, not a description of it.
* The agent works on an **unsaved draft**, never your live site.
* You keep refining in chat, or edit the draft directly in the studio's structured editor.
Each conversation is a **thread**. When its work is done — for example when you publish a new
page — the thread wraps up and you start a fresh one for the next change.
Threads, the agent picker, voice dictation, and wrapping up finished work.
## The approval model [#the-approval-model]
The console is built around one rule: **the agent proposes, you approve.** Nothing reaches
your live site without an explicit action from you.
The agent has no power to publish on its own. Brand directions and page layouts stay drafts
until you press **Publish**.
Drafts and previews keep the agent fast while you stay the publisher, and any step that would
change your site pauses for your approval first.
The full picture: drafts, Publish and Discard, and approval pauses.
## Moving between the console and your site [#moving-between-the-console-and-your-site]
The console is your workspace; the live site is what it produces. A jump to the live site
opens a **new tab** (so your unsaved draft and open conversation stay put), while moving
around inside the workspace stays in the **same tab**. The globe in the top bar opens your
live site any time, and on the live site an operator sees a small **Edit in Console** pill to
jump back. The account menu (your avatar, top-right) also has a **System** door to the
technical back office at `/admin` — you rarely need it; the console is home.
The identity card, managing your account in-console, and the System door.
## What you can do here [#what-you-can-do-here]
On a fresh install the [onboarding wizard](/onboarding) walks you through connecting a
provider and choosing your models.
Open the [Design System studio](/brand-studio) and describe the identity you want.
Preview, then publish — it flows through to every page.
Under **Pages**, click **New page**, give it a title, and you land in the [Pages
studio](/page-studio) ready to build. Describe the page and the agent composes it from the
[component library](/components), live on your brand.
In the General studio, ask the agent to create, update, or find content. The same
approval model applies to anything that changes your site.
# Host your exported site (https://aincient-labs.com/docs/deploy)
You've [exported your site](/static-export) as plain files. Now put it on the web. A static export is
ordinary HTML, CSS, images, and assets, so it runs on **any** static host — pick whichever you already use.
The steps below all start from the same folder Atelier produced.
## Build the export first [#build-the-export-first]
If you run the appliance with the [`atelier` CLI](/quickstart), one command exports your site and drops the
files on your machine, ready to deploy:
```bash
atelier site export
```
By default this writes the site to `aincient-export/` in the current directory and runs a link check so you
know the snapshot is self-contained.
**Set your final domain with `--base-url`.** Page canonicals, `og:` tags, and the sitemap bake in the
address you render against. Export for the domain you'll publish to:
```bash
atelier site export --base-url https://your-domain.com
```
For a first test deploy you can skip this and fix it before you point a custom domain at the site.
Prefer a single file to upload or hand off? `atelier site export --zip` also packages `aincient-export.zip`.
Add `--include-config --include-users` for a full "own your data" bundle (see [Export a static site](/static-export)).
Re-run `atelier site export` any time you publish changes and re-deploy — every host below supports that.
## Fastest: the deploy template [#fastest-the-deploy-template]
Don't want to configure a host by hand? The [**atelier-deploy-template**](https://github.com/aincient-labs/atelier-deploy-template)
repo is pre-wired for every host below. Put your export in its `site/` folder and push — start from any of
these one-click links:
* [**Use this template**](https://github.com/aincient-labs/atelier-deploy-template/generate) — create your own copy on GitHub (best for GitHub Pages)
* [**Deploy to Netlify**](https://app.netlify.com/start/deploy?repository=https://github.com/aincient-labs/atelier-deploy-template)
* [**Deploy to Cloudflare**](https://deploy.workers.cloudflare.com/?url=https://github.com/aincient-labs/atelier-deploy-template)
* [**Deploy with Vercel**](https://vercel.com/new/clone?repository-url=https://github.com/aincient-labs/atelier-deploy-template)
The buttons deploy the template's placeholder first; connect the host, then push your export to `site/` and
it redeploys automatically. Prefer to set a host up by hand? Keep reading.
## Netlify [#netlify]
Open [app.netlify.com/drop](https://app.netlify.com/drop) and drop your `aincient-export` folder onto the
page. It's live in seconds on a `*.netlify.app` address.
```bash
npm i -g netlify-cli
netlify deploy --prod --dir=aincient-export
```
Commit the export to a repo and add a `netlify.toml` so Netlify serves the folder as-is (no build step —
Atelier already built it):
```toml
[build]
publish = "aincient-export"
```
Official docs: [Netlify — create deploys](https://docs.netlify.com/site-deploys/create-deploys/) · [Netlify CLI](https://docs.netlify.com/cli/get-started/).
## Cloudflare Pages [#cloudflare-pages]
In the Cloudflare dashboard: **Workers & Pages → Create → Pages → Upload assets**, then upload the
`aincient-export` folder.
```bash
npm i -g wrangler
wrangler pages deploy aincient-export
```
Point a Pages project at your repo, leave the **build command empty**, and set the **build output
directory** to `aincient-export`.
Official docs: [Cloudflare Pages — Git integration](https://developers.cloudflare.com/pages/get-started/git-integration/) · [direct upload](https://developers.cloudflare.com/pages/get-started/direct-upload/).
## Vercel [#vercel]
```bash
npm i -g vercel
vercel deploy aincient-export --prod
```
Import the repo, choose framework preset **Other**, leave the build command empty, and set the **output
directory** to `aincient-export`. Optionally commit a `vercel.json`:
```json
{
"outputDirectory": "aincient-export"
}
```
Official docs: [Vercel — Git deploys](https://vercel.com/docs/deployments/git) · [Vercel CLI](https://vercel.com/docs/cli).
## GitHub Pages [#github-pages]
Copy the contents of `aincient-export/` into a new repository. **Add an empty `.nojekyll` file** at the
root — without it, GitHub Pages' Jekyll step strips folders that start with an underscore.
Commit this workflow as `.github/workflows/pages.yml`. It publishes the whole repo (adjust `path:` if your
files live in a subfolder):
```yaml
name: Deploy to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- uses: actions/upload-pages-artifact@v3
with:
path: .
- id: deployment
uses: actions/deploy-pages@v4
```
In the repo, go to **Settings → Pages** and set the source to **GitHub Actions**. Your site publishes on
each push to `main`.
Official docs: [GitHub Pages — custom Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages).
On a project site the URL includes a subpath (`username.github.io/repo`). Export with a matching
`--base-url` (e.g. `https://username.github.io/repo`) so links and canonicals resolve correctly, or use a
[custom domain](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site).
## Any static host [#any-static-host]
The export is just files, so it works on everything else too — no framework required:
* **Your own server:** copy `aincient-export/` into your web root (nginx, Apache, Caddy). Point the server
at the folder and you're done.
* **Object storage + CDN:** sync to an S3 bucket, Cloudflare R2, Google Cloud Storage, etc. and front it
with a CDN. For example: `aws s3 sync aincient-export s3://your-bucket --delete`. Official guides:
[AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html) ·
[Cloudflare R2](https://developers.cloudflare.com/r2/buckets/public-buckets/) ·
[Google Cloud Storage](https://cloud.google.com/storage/docs/hosting-static-website).
* **Anything that serves a folder** — even a USB stick or a local `python -m http.server` for a quick look.
What a static export includes and how "own your data" works.
Get canonicals, sitemaps, and metadata right before you publish.
# Drafts, revisions & publishing (https://aincient-labs.com/docs/editorial-workflow)
Atelier separates saving your work from taking it live.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
Saving a draft never touches your live site. A page changes only when you — or a reviewer —
choose to publish it. The agent never publishes on its own.
## Save draft vs. Publish [#save-draft-vs-publish]
Two actions, two very different effects:
* **Save draft** records a forward revision of your work without touching the live site. Your
in-progress Fernway Botanical Studio spring-sale page is saved, but visitors still see the
current version.
* **Publish** saves the page as a node, creates a revision, gives you its URL, and takes it
live. The published page renders chrome-free at its own address.
Publishing a brand-new page also wraps up the conversation, since the work that thread set
out to do is done.
## Where the buttons are [#where-the-buttons-are]
The buttons that move a page sit together at the top right, and they look the same in every
studio that edits a page, including **Pages** and **Checks**:
* A **status badge** shows where the page stands: **Draft**, **In review**, **Live**, **Live ·
draft pending**, or **Archived**. While you have unsaved edits it says so. Hover it for a short
line on why editing is blocked, when it is.
* **Save draft** saves your edits without going live.
* One main button is the next step for this page: **Publish** on a draft, **Submit for review**
if you can't publish yourself, **Approve & publish** for a reviewer.
* The arrow beside it opens everything else you're allowed to do, grouped as **Move forward**,
**Send back** (such as **Reject** or **Restore**) and **Take offline** (**Archive**). Taking a
page offline asks you to confirm first.
You only see the steps your role allows. So if Fernway's care guide is **In review** and you
aren't a reviewer, there's no Publish button. The badge tells you it's waiting for approval.
If your site has its own review steps (a legal check, say, or translation), they appear in the
same menu. The main button is always the step that takes the page live, or failing that, the
next step forward.
The same state follows you into chat: ask the assistant *"what pages do I have?"* and the page
list shows each page's state for the language you're working in, and every page thread in the
sidebar carries a **Draft** / **In review** / **Live** marker.
## A history you can fall back on [#a-history-you-can-fall-back-on]
Every publish creates a revision, so your page carries a history. If a change doesn't land
the way you hoped, you have earlier versions to fall back on rather than a single
overwrite-in-place copy.
## Reusable blocks [#reusable-blocks]
You can also author **reusable blocks** — sections-only fragments you place by reference
across many pages. A Fernway "Visit the shop" block, for instance, can appear on every care
guide, and updating the block updates it everywhere it's referenced. Blocks follow the same
draft/publish lifecycle as pages, so nothing changes on your live pages until you publish the
block.
Where drafts are created, previewed, and published.
How Atelier keeps one writer at a time so revisions don't collide.
# Email delivery (https://aincient-labs.com/docs/email)
Atelier sends transactional email on your behalf: password resets, account
notices, and update alerts. Where those messages actually go is up to you — pick
a delivery method that suits your setup.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
A fresh install sends nothing to the outside world. Until you connect a
transport, email is written to your site's log so nothing is lost — and nothing
is silently delivered.
While email is log-only, password reset by email can't work, so the sign-in page
says so and the **Reset your password** page explains how to get back in instead
of offering to send a link: use **Edit my site** in the Atelier manager (or `atelier app open`), then set
a password under [My account](/account).
## Choose how email is delivered [#choose-how-email-is-delivered]
Open **System** from your account menu, then go to **Configuration → Mail
delivery** (`/admin/config/aincient/mail`). You have three options.
The default. Messages are recorded in your site's log instead of being sent.
Good for trying Atelier out before you connect real delivery.
Send through any SMTP server — your own, or a provider that gives you SMTP
credentials. Enter the host, port, username, and password.
Send through a hosted email API (SendGrid or Postmark). Enter the provider's
API key.
## Connect a transport [#connect-a-transport]
From the console, open your account menu, choose **System**, then
**Configuration → Mail delivery**.
Choose **SMTP server** or **API provider**. The fields you need appear
below your choice.
Fill in the server details or API key. Your key is stored securely on your
site and is never written to your exported configuration or to version
control.
Enter a recipient under **Send a test email** and click **Send test email**.
Atelier sends a real message using the values on screen — even before you
save — so you can confirm delivery works.
Click **Save configuration**. From now on, Atelier's transactional email
goes through your transport.
Changing your delivery method later never re-exposes a stored key. Leave the
key or password field blank to keep the one you already saved.
## Who your email is from [#who-your-email-is-from]
The sender name and address don't live here — they come from your site
identity. Atelier sends as the name and email address set in **Site
information**, so there's one place to manage your brand's identity.
If you ever need a different sender for email specifically, set a **From address
override** on the Mail delivery page. Leave it blank to send as your Site
information address.
If you haven't set a sender address yet, add one in **Site information** —
otherwise email falls back to a placeholder address that may be filtered by
recipients.
## API providers [#api-providers]
SendGrid and Postmark are supported with a single API key. Some providers need
an extra package installed before they can send; if a test fails with a
transport error, that package isn't available on your install yet. SMTP works on
every install with no extra setup.
# Freeze & Live (https://aincient-labs.com/docs/freeze-and-live)
Atelier can serve your visitors in two ways. **Live** is the default: every visit is rendered from your published content, so a change reaches visitors the moment you publish it. **Frozen** serves a snapshot instead — a fixed copy of the whole site from the moment you froze it, stored as plain files.
While the site is frozen, nothing you publish reaches visitors until you freeze again. You, and anyone else who is logged in, always see the live site — on the public pages and in the console — so you check your edits on the real URLs.
## Why freeze [#why-freeze]
* **Release a whole version at once.** Edit and publish many pages over a week, then freeze once. Visitors go from the old site to the new one in a single step.
* **Undo in one click.** Every snapshot is kept. If a release goes wrong, serve the previous snapshot. No export, no restore.
* **Faster, calmer pages.** A frozen page is a file. It is served with cache headers a CDN understands, and nothing about your visitors' requests touches the database.
## Freeze the site [#freeze-the-site]
In the console, open **Settings** and find **Snapshots**.
1. Optionally give the snapshot a name, such as *Spring launch*.
2. Choose **Freeze now**. Atelier renders every published page — this takes a few seconds on a small site, longer with many images.
3. When it finishes, visitors see the new snapshot. The status line reads *Visitors see snapshot Spring launch. You see the live site.*
If the export finds a problem — usually a link to a page that does not exist — the snapshot is taken but **not** served, and the problems are listed. Fix them and freeze again, or choose **Serve it anyway**.
## Switch between versions [#switch-between-versions]
The Snapshots list shows **Live** at the top, then every snapshot, newest first. The one visitors currently see is marked.
* **Serve this** switches visitors to that snapshot immediately. Nothing restarts.
* **Serve live** goes back to rendering every visit. Snapshots are kept.
* **View** opens a snapshot so you can see exactly what visitors see, or look at an older version before serving it.
* **Keep** marks a snapshot as permanent. Housekeeping never removes a kept snapshot.
Publishing a page while the site is frozen saves it and shows it to you, but visitors keep seeing the snapshot until you freeze again. The console shows *Visitors see snapshot …* whenever this is the case.
## From the command line [#from-the-command-line]
The same verbs exist in the `atelier` CLI:
```bash
atelier site freeze --label "Spring launch" # snapshot the site and serve it
atelier site snapshots # list snapshots; ● marks what visitors see
atelier site use 20260910-1102-spring-launch # serve that snapshot
atelier site live # back to live
atelier site prune --keep 10 # delete old snapshots (kept and served ones stay)
```
Inside the appliance these are `drush aincient:freeze`, `aincient:snapshots`, `aincient:use`, `aincient:live` and `aincient:prune`.
## Good to know [#good-to-know]
* **Backups include snapshots.** `atelier data backup` bundles them, and a restore brings back both the snapshots and which one was being served.
* **Disk.** Each snapshot holds a full copy of the site's pages, stylesheets and resized images. Housekeeping keeps the ten most recent snapshots plus everything you marked as kept.
* **A page missing from the snapshot** shows the snapshot's own "not found" page. While a snapshot is served, visitors never reach the live application at all — which is also why the public site stays up while Atelier updates itself.
* **Behind a CDN.** Frozen pages are sent with `Cache-Control: public, max-age=300` and an `X-Atelier-Served: frozen` header; logged-in responses stay private. After switching snapshots, allow up to five minutes for cached pages to refresh, or purge your CDN.
Take a snapshot with you and host it anywhere.
How publishing individual pages works.
# Overview (https://aincient-labs.com/docs/globals-studio)
The Globals studio is where you shape the **chrome** that wraps every page: the site
**header** and **footer**, and the brand **identity** they carry (name, tagline, logo, voice).
You can edit it directly in the rail, or describe what you want and let the agent preview it —
and, like the other studios, **nothing goes live until you click Publish**.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
The agent never publishes on its own. It edits an **unsaved draft** held in your browser.
Your chrome goes live only when you press **Publish** in the studio.
## Open the studio [#open-the-studio]
Switch to **Globals** from the studio switcher in the console breadcrumb (`/atelier`). The
studio opens with a live preview of your header and footer wrapping a placeholder page, a chat
beside it, and a tabbed editor rail.
## The editor tabs [#the-editor-tabs]
The site name, tagline, description, voice/tone, logo, favicon, and footer note — the identity
the header and footer display (and the favicon shown in the browser tab; until you upload one,
the tab shows the Atelier mark). This tab decides
*which* image is your logo; how large it renders is set per bar in the **Header** and
**Footer** tabs.
Core site details: the site email address and which pages serve as the **front page** and the
**not-found (404)** / **access-denied (403)** pages. Anything left empty falls back to the
shipped default.
Logo position (left or centre), **logo size** (small, medium or large), whether the header
sticks on scroll, nav alignment, and the header menu.
Footer layout (inline or stacked), **logo size**, whether the tagline shows, whether the
"Made with Atelier" credit shows, and the footer menu.
How brand fonts reach your public pages — the one setting that decides whether visitors see
a consent banner. See [Privacy](/privacy).
## Site details and error pages [#site-details-and-error-pages]
The **Site** tab is where the site stops being anonymous: set the email address system mail
(password resets, notifications) is sent from, and point the **front page**, **404**, and
**403** slots at pages you've built — pick any published page from the same picker used
everywhere else in the console. On Publish the choice takes effect immediately: your chosen
page serves at the site root, and visitors who hit a missing or restricted URL see your page
instead of a bare error.
Every field here is optional. An empty field means "use the default", and clearing a field
later puts the default back — deleting a page that a slot points at also safely resets that
slot.
## Editing by chat [#editing-by-chat]
Describe what you want and the agent previews it instantly — for example:
* *"Rename the site to Lumen with the tagline 'Light, organised'."*
* *"Centre the logo and stop the header sticking."*
* *"Make the logo bigger."*
* *"Make the footer stacked and hide its tagline."*
The agent applies its change to the **same draft** the rail edits, so the live preview
re-renders and the edited fields light up in the rail with an unsaved-change count. Keep
refining in chat or tweak the fields directly — then **Publish** when you're happy, or
**Discard** to revert to the saved chrome.
## Menus are yours to edit [#menus-are-yours-to-edit]
The agent shapes layout and identity, but it does **not** edit your navigation **menus** — you
manage header and footer links yourself in the inline menu editor on the **Header** and
**Footer** tabs (add, rename, re-point, reorder, or remove a link). If you ask the agent to
change a link, it points you to the menu editor.
### Link to a page, or to any URL [#link-to-a-page-or-to-any-url]
Each link targets one of two things — flip the **URL ｜ Page** switch under its label:
* **Page** — pick one of your published pages. The link then **tracks that page**: it always
points at the page's current published URL, so renaming or re-aliasing the page keeps the
menu correct with no extra work.
* **URL** — type any address yourself: a path on your own site (`/about`, `/pricing`) or a full
external link (`https://…`).
### Nested menus (sub-menus) [#nested-menus-sub-menus]
Menus can nest as deep as you like. To give a link sub-items, use its **go-in** control
(the chevron with a child-count badge) — the editor drills into that link and shows just its
children, with a breadcrumb (e.g. `Header menu › Products`) to step back up. You edit one level
at a time, which keeps the rail readable however deep the menu goes.
On the published site, nesting renders automatically: in the **header** a parent link opens a
drop-down (on hover and on keyboard focus) with its children flying out; in the **footer**
children group as a column under their parent.
## How it relates to the other studios [#how-it-relates-to-the-other-studios]
Globals sits in the same family as the [Design System studio](/brand-studio) and the
[Pages studio](/page-studio): an agent previews, you decide, and Publish is the only thing that
changes the live site. Identity set here (name, tagline, logo) is the single source the header,
footer, and page metadata all read.
# Images (https://aincient-labs.com/docs/images)
Most sections take an image — the [`hero`](/components#opening-and-structure), a
[`content`](/components#telling-your-story) block, a [`gallery`](/components#telling-your-story),
the cards in a [`grid`](/components#layout). You add the image once; Atelier handles
how it looks and loads everywhere it appears.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Adding an image [#adding-an-image]
You have two ways, both in the [Pages studio](/page-studio):
When a section has an image, choose one from your media library or upload a new
file. The [preview](/page-studio) updates immediately.
Describe what you want — "use the warehouse photo for the hero" — and the agent
finds a matching image in your library and places it. As always, it edits the
**draft**; nothing changes on the live site until you **Publish**.
Images follow the same promise as everything else in the studio: the agent
proposes, you review the preview, and **you** publish. See [AI proposes, you
approve](/page-studio).
## They're responsive automatically [#theyre-responsive-automatically]
You never set sizes, crops, or formats. Once an image is in a section, Atelier:
* **Right-sizes it for where it sits** — a full-width hero, a half-width content
image, and a small gallery tile each get an appropriately sized image, so a phone
never downloads a desktop-sized file.
* **Adapts to the layout** — change a gallery from three columns to four, or rearrange
the page, and each image resizes to its new place. It always fits its spot.
* **Stays crisp on every screen** — high-resolution (retina) displays get a sharper
version; ordinary screens don't pay for pixels they can't show.
* **Loads fast** — images are served in modern, compact formats and sized to the
device, so pages stay quick.
Because sizing and quality are handled for you, you can move sections and images
around freely — the result always looks right and loads well. Focus on the story,
not the image settings.
## Describe your images for accessibility [#describe-your-images-for-accessibility]
Add **alt text** to an image in your media library — a short description of what it
shows. Atelier uses it automatically wherever the image appears, so your pages stay
accessible to screen readers and clearer to search engines. You write it once, on the
image, not on every page that uses it.
# Introduction (https://aincient-labs.com/docs)
Atelier CMS by AIncient Labs is an AI-first, chat-driven site builder built on
[Drupal](https://www.drupal.org). You build and brand your site by talking to an agent in a
console, watch every change render live, and publish only what you approve.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
It is a full CMS underneath — Drupal core, your content as real nodes, config as code — with
a modern chat console layered on top. You don't fill in admin forms. You describe what you
want, and the agent assembles it from a curated component library on your brand.
## AI proposes, you approve [#ai-proposes-you-approve]
Most agentic tools race to act on their own: run with broad permissions, change live
configuration, mutate the running system, and ask forgiveness later. Atelier is the
deliberate opposite.
The agent **never changes your live site on its own.** It works on an unsaved draft and
shows you a live preview. Your site changes only when **you** press **Publish**.
This is an architectural stance, not a setting you can switch off:
* **No autonomous writes.** The agent proposes brand directions and page layouts as drafts.
Persisting them is always a human action.
* **Everything is previewed first.** You see the real result, rendered in your brand, before
anything is saved.
* **A person is always in the loop.** Actions that change your site pause for your explicit
approval — nothing ships while you're looking away.
The result is the speed of an agent with the control of a human editor. AI does the
assembling; you stay the publisher.
## Start here [#start-here]
Install Atelier and reach your console in a few minutes.
How the chat console, studios, and the approval model fit together.
Set your site's identity by chatting — preview, then publish.
Build pages section by section, live on your brand.
***
Drupal is a registered trademark of Dries Buytaert. Atelier CMS by AIncient Labs is an
independent product of AIncient Labs, built on Drupal — it is not affiliated with, endorsed
by, or sponsored by the Drupal project, the Drupal Association, or Dries Buytaert.
# Overview (https://aincient-labs.com/docs/media-studio)
The **Library** is home to your site's reusable ingredients: media and reusable blocks.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Browse the shelf [#browse-the-shelf]
Open **Library** from the console at `/atelier` to see everything you have in one place. Every image you have uploaded or generated lives here, alongside the reusable blocks you can drop into pages. Think of it as the pantry for Fernway Botanical Studio — one place to keep the shop photos, the logo, and the seasonal banner you reuse across pages.
## Open an image [#open-an-image]
Select any image and an editor rail opens beside it. From there you can:
* **Rename it** — give the file a friendly, findable name.
* **Edit its alt text** — write a short description of what the image shows, once, for accessibility. See [alt text](/alt-text).
* **Replace the file** — swap in a new file while keeping the same reference.
* **Delete it** — remove an image you no longer need.
Replacing a file keeps its reference, so every page that uses the image updates at once. Swap the Fernway hero photo for a fresh one and each page showing it picks up the new photo — no page-by-page editing.
## Generate and edit with AI [#generate-and-edit-with-ai]
When an image provider is connected, an optional AI rail appears in the Library. From there you can generate brand-new images from a prompt and edit existing ones in plain language, right where your media lives. See [generating and editing images with AI](/ai-images) for the full walkthrough.
As always, the agent proposes and you decide. An AI edit produces a new image rather than overwriting the original, so you keep both unless you choose to replace.
Because images are reused by reference, the Library is the fastest place to make a change ripple across your whole site — fix one file, and every page that uses it follows.
How images get placed, right-sized, and served fast.
Generate and edit images by chatting.
# Header & footer menus (https://aincient-labs.com/docs/menus)
The agent shapes your layout and identity, but it doesn't touch your navigation — you manage the header and footer links yourself in the inline menu editor in the **Navigation & Pages** studio, or add a page straight from the page itself.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
Menus are yours to edit. The agent won't add, rename, or reorder navigation links — it shapes the page content and brand around them.
## Open the menu editor [#open-the-menu-editor]
From the top nav, open the **Site** menu, choose **Navigation & Pages**, then switch to the **Header** or **Footer** tab. Each tab holds an inline editor for that menu.
## Manage links [#manage-links]
In either tab you can:
* **Add** a new link.
* **Rename** its label.
* **Re-point** it at a different destination.
* **Reorder** links by dragging them, or with move up / move down.
* **Nest** a link under another by dropping it on that link's submenu button, or with **Nest under previous link**. **Move out of submenu** (or dropping it on a breadcrumb) takes it back up a level.
* **Show or hide** a link with the **Shown** toggle.
* **Remove** a link entirely.
## Point a link at a page or a URL [#point-a-link-at-a-page-or-a-url]
Each link targets one of two things. Flip the **URL ｜ Page** switch under its label to choose:
Pick one of your published pages. The link then **tracks** that page — it always points at the page's current published URL, so renaming or re-aliasing the page keeps the menu correct on its own.
Type any address — a path like `/workshops`, or a full external link like `https://…`.
For Fernway Botanical Studio, you might set a **Page** link to your Care Guides page and a **URL** link to your Instagram — side by side in the same header.
## Nest menus as deep as you like [#nest-menus-as-deep-as-you-like]
Menus can nest to any depth. Use a link's **go-in** control — the chevron with a child-count badge — to drill into its children. Drag a link onto another link's go-in control to nest it there. A breadcrumb like `Header menu › Workshops` shows where you are, and you step back up through it.
On the published site, nesting renders automatically:
* A **header** parent opens a drop-down of its children.
* **Footer** children group as a column under their parent.
## Add a page from the page itself [#add-a-page-from-the-page-itself]
The common case — "put this page in the menu" — doesn't need the menu editor. Open the page in the **Pages** studio and use **Add to menu** in its side panel: pick the **Main** or **Footer** menu, and where it goes (top level, or under one of the links already there). The link is added to the menu's **draft**, not published: choose **Review in Navigation** to see it in place, then publish from there. If the page is already in that menu, it tells you instead of adding it twice.
The draft lives in your browser tab until you publish or discard it, so publish before you reload the page.
## Publish [#publish]
Add, reorder, and re-point links in the Header or Footer tab. Your changes stay in an unsaved draft.
Click **Publish**. The header and footer update **site-wide** immediately.
Use **Page** links wherever you can. Because they follow the page, you can rename or re-alias a page later without ever coming back to fix a broken menu item.
See the full studio — header, footer, and special-page routing in one place.
# Finding your way around (https://aincient-labs.com/docs/navigation)
Atelier gives you clear, predictable ways to move between your studios, your live site, and the technical back office.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## The studio switcher [#the-studio-switcher]
The switcher in the top bar moves you between studios:
* **Pages** — your page and content studio.
* **Library** — your media.
* **Site** — a menu holding **Design System** and **Globals**.
The Atelier wordmark returns you home to the General chat.
## Deep links [#deep-links]
Every studio, page, and item has its own shareable, reload-safe URL. A Fernway page might open at a URL like `/atelier/content/node/5`, so you can bookmark or share exactly where you are and come back to the same spot.
## Moving between the console and your live site [#moving-between-the-console-and-your-live-site]
Three affordances follow one rule: a jump to the live site opens a **new tab** — so your unsaved draft and open conversation stay put — while moving around inside the workspace stays in the **same tab**.
The globe in the top bar opens your live site in a new tab.
On the live site, an operator sees a small pill. On one of your pages it reads **Edit in Console** and jumps to that page in the **Pages** studio; elsewhere it reads **Open Console**. Visitors never see it.
The account menu has a **System** door to the technical back office at `/admin`.
## When a link can't open [#when-a-link-cant-open]
If you open a deep link to a page you can't access or that no longer exists, the console shows a short recovery screen with a way to start fresh — never a blank editor.
A tour of the studios and the top bar.
# Connect AI & choose models (https://aincient-labs.com/docs/onboarding)
The first-run wizard connects your AI providers and picks the models Atelier uses, so a fresh install is ready to work in a couple of minutes.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
A fresh install ships keyless, so the wizard runs automatically the first time you open the console. It has two steps.
## 1. Connect your AI [#1-connect-your-ai]
Connect one provider or several:
Paste each provider's API key (or, for Ollama, your server URL). Each credential is validated against the provider before anything is saved — Atelier asks it for its model list, so "Connected" means a real answer came back — and it is stored on your own server, never in code or git.
Atelier runs in a container, so `localhost` points at the container itself — not the machine where Ollama runs. To reach an Ollama server on the host, use `http://host.docker.internal:11434` instead of `http://localhost:11434`.
Ollama needs no key at all — the server URL is the whole credential, and nothing leaves your infrastructure. Atelier asks your server what each pulled model can do, so embedding models are kept out of the picker and a model that can't call tools is labelled as such. The chat studios drive tools, so prefer a tool-capable model for the *task* and *high thinking* roles.
### Something else that speaks the OpenAI API [#something-else-that-speaks-the-openai-api]
DeepSeek, Groq, OpenRouter, a LiteLLM proxy, vLLM, LM Studio — Atelier serves all of them through the **OpenAI-compatible endpoint** row. It's the one provider that asks for two things: the **base URL** to call, and an **API key**.
Give it the service's root address — `https://api.deepseek.com`, or wherever your own proxy lives. Atelier appends `/v1` itself, so leave that off. Then, exactly as with any other provider, it asks the endpoint for its model list before saving anything: connect succeeds only if a real catalogue comes back.
A self-hosted proxy usually runs on the same machine as Atelier — and inside the container, `localhost` is the container. Use `http://host.docker.internal:` to reach a server on the host.
(OpenAI and Mistral don't need this row — they have their own above, and Atelier speaks each vendor's native API rather than the compatibility shim.)
Connecting Google Gemini also turns on image generation. One Google AI Studio key powers both Gemini chat and Nano Banana image generation.
## 2. Choose your models [#2-choose-your-models]
Atelier works in **roles**, not per-chat model picks. There are three chat roles — *high thinking*, *task*, and *fast* — plus *image description* and *image generation*.
You only have to answer one question: **what matters most to you?**
* **Best value** — the cheapest models that still do the job. Good for high volume and low stakes.
* **Balanced** — good results at a sensible price. The right choice for most sites.
* **Best quality** — the most capable models available. Costs more per turn.
Atelier fills in every role from the profile you pick, choosing only models the providers you connected can actually serve. Nothing is bound that your key can't run.
Want to decide each role yourself? **Choose per role** opens a picker for every one. Touching any of them switches you out of the profile and into your own selection — nothing is overwritten behind your back.
Because you bind a model to a role (never to a single conversation), swapping one model rebinds every studio that uses that role. Choose once, and the whole console follows.
### Keeping the suggestions current [#keeping-the-suggestions-current]
Which model is the right one changes on roughly a weekly cadence — models get retired, prices move, a provider's fast tier overtakes another's mid tier. So the profiles come from a document we publish and keep up to date at
[aincient-labs.com/atelier/models.yml](https://aincient-labs.com/atelier/models.yml) (plain text — read it before you trust it).
Your install ships with a snapshot of that document, which is what you see by default and what keeps a fully offline install working. **Check for updates**, under the profiles, fetches the current one. That fetch is the only time Atelier contacts us, it happens only when you click, and it sends nothing about your site — see [Privacy](/privacy).
## Supplying a key from the environment [#supplying-a-key-from-the-environment]
You can hand Atelier a provider key through an environment variable instead of the wizard. There are two forms, and **the name you choose decides who owns the key afterwards.**
### A key the server owns [#a-key-the-server-owns]
```bash
ATELIER_ANTHROPIC_API_KEY=sk-…
```
This key is read fresh on every request and **never written to the database** — it survives no backup, appears in no dump, and rotates by changing the variable and restarting. Use it when the secret must not live in the database at all: a platform with managed secrets, a Kubernetes cluster, or any image you build from a database dump.
This form wins over anything stored through the wizard, so the provider shows as **Set by this server** in the connect step, with no key field and no Disconnect. That's deliberate: Atelier can't out-rank a variable it doesn't own, and a button that silently did nothing would be worse than no button. To change or remove such a provider, change the variable and restart.
### A starting key the site owner owns [#a-starting-key-the-site-owner-owns]
```bash
ATELIER_DEFAULT_ANTHROPIC_API_KEY=sk-…
```
This one is a **default, not a rule**. It's copied into the site's credential store once, on the first boot after you set it, and from then on it's an ordinary key: it appears in the wizard normally, the owner can replace it, and if they disconnect it, it stays disconnected — the next restart won't put it back.
Because it's applied exactly once, changing the value later has no effect; the site already has its copy. And unlike the form above, this key **does** live in the database, so it will appear in backups and dumps.
### The pattern [#the-pattern]
Both forms use the provider's id in capitals — `ATELIER_MISTRAL_API_KEY`, `ATELIER_DEFAULT_OPENAI_COMPATIBLE_API_KEY`, and so on. Providers that need a base URL as well take `ATELIER__ENDPOINT` (or `ATELIER_DEFAULT__ENDPOINT`); for Ollama, where the URL *is* the credential, that variable is all you need.
Seeds are applied automatically when the container starts. On an install that doesn't use the Atelier container, apply them yourself:
```bash
drush aincient:seed-credentials
```
## Changing providers or models later [#changing-providers-or-models-later]
You can revisit the wizard any time:
* Open the avatar menu (top-right) and choose **Set up AI providers**, or visit `/atelier?onboarding=1`.
* Already-connected providers show as **Connected**, so you only fill in what's new.
To rebind a role without the wizard:
* Reopen the wizard from the avatar menu → **Set up AI providers**.
* Or from your terminal: `atelier ai model set `.
Get from install to your first published change.
Learn your way around the studios.
# Overview (https://aincient-labs.com/docs/page-studio)
The Pages studio is where you build a page by talking to the Atelier agent. The agent
proposes a layout, you see every change rendered live in your site's brand, and **nothing
goes live until you click Publish**. It is the page counterpart of the Design System studio: the
agent previews, you decide.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
The agent never publishes on its own. It edits an **unsaved draft** held in your browser.
Your page goes live only when you press **Publish** in the studio.
## Open the studio [#open-the-studio]
The studio opens whenever you create a page or open an existing one.
Go to the Atelier console at `/atelier`.
Under **Content** in the sidebar, click **New page**, give it a title, and pick its type —
a **landing page** (built from sections: hero, features, calls to action) or a **blog
post** (a written article in a fixed reading layout). (To keep working on an existing
page, open it from the **All pages** list instead.) The studio pane opens beside the
chat, showing a live preview.
Tell the agent what you want — for example, *"Build a landing page for a neighbourhood
coffee shop."* The agent replies with one short framing sentence and applies its work
to the preview.
A page's **type is fixed when you create it.** A landing page and a blog post are built
from different things — sections versus an article body — so one cannot be turned into the
other, by you or by the agent. If you picked the wrong one, create a new page of the right
type; the studio shows the current type under the page title.
## How a page is built [#how-a-page-is-built]
You and the agent edit the **same draft**. The agent works in incremental section
operations — it adds a hero, then a features section, then a call to action — and each
operation re-renders the live preview. It composes from a curated [component
library](/components) broad enough to build marketing, company, and news/blog sites. You can keep refining in chat (*"make the hero
headline punchier"*, *"add a stats section after the features"*) or edit the draft yourself
in the structured editor.
The structured editor lists the page's sections. For each section you can:
* **Add**, **remove**, and **reorder** sections.
* Edit each section's props, including enum controls for tone and variant.
Every edit — from chat or from the editor — updates the same draft and re-renders the
preview immediately.
## Pages always respect the brand [#pages-always-respect-the-brand]
The preview renders with your site's live brand — the design tokens, colours, and chrome set
in the Design System studio. A page **cannot** override the brand: there is no per-page colour or
preset lever. This keeps every page consistent with the identity you established once.
If the colours aren't what you want, change them in the **Design System studio**, not per page.
The change flows through to every page automatically.
## One writer at a time [#one-writer-at-a-time]
When you open a page in the studio, Atelier hands you the pen for that page. If the same
page is already open somewhere else — another browser tab, or a teammate — that session
holds the pen instead, and your studio shows a banner naming who has it and when they
started:
* *"Alex is editing this page in content, since 2:14 pm."* — someone else holds the pen.
* *"You're editing this page in another tab (opened 2:14 pm)."* — it's you, elsewhere.
Click **Take over** to move the pen to this studio. The other session immediately loses it
and can no longer save.
**Take over discards unsaved changes in the other session.** If the pen is held by your own
other tab, switch to it and **Publish** (or save your draft) first — anything unsaved there
is lost the moment you take over here.
The pen follows the **page**, not the conversation. Open the same page in a second tab and
you'll be asked to take over — even when it's the same chat. Keep one tab per page to avoid
taking over from yourself.
## Publish or discard [#publish-or-discard]
When the draft looks right:
* **Publish** saves the page as a node, creates a revision, and gives you its URL. The
published page renders chrome-free at its own address.
* **Discard** throws the draft away. You're asked to confirm first, so an unpublished page
is never wiped by accident.
Re-opening a published page in the studio loads its current content as a fresh draft, so you
can iterate and publish again.
**Publishing a brand-new page wraps up the conversation.** Once the page is live, that chat is
finished — it stays in your sidebar (marked **Done**) so you can re-read it, but you start a
**new thread** for your next change. This keeps each conversation focused and avoids running up
usage on a thread whose work is done. You can choose **Keep editing** if you're not done yet,
and any thread can be wrapped up (or reopened) from its **⋯** menu.
# Privacy & consent (https://aincient-labs.com/docs/privacy)
Atelier is built for an EU-first world, so it never quietly sends your visitors' data to a
third party. Anything that would reach an outside service — web fonts today, analytics and
embeds later — is either served from your own site or gated behind the visitor's consent.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
Nothing non-essential loads until a visitor opts in. Until then, your pages use the system
font and make no third-party request.
## Choose how your brand fonts load [#choose-how-your-brand-fonts-load]
When you pick a Google font in the Design System studio, you decide how it reaches your public pages.
Atelier downloads the font to your own site, so visitors load it from your origin. No
request ever goes to Google, and no cookie banner is needed.
The font loads from Google Fonts, which shares the visitor's IP address with Google — so
visitors are asked for consent first. Until they accept, the system font is shown.
You set this in the Design System studio under **Web fonts** → **Font delivery**. Self-host is the
strongest privacy choice; it fetches the font once when you publish.
## The consent banner [#the-consent-banner]
When your site loads something from a third party (right now, that's Google-delivered fonts),
visitors see a privacy banner the first time they arrive.
A visitor can **Accept all**, choose **Only necessary**, or **Customize** which categories
to allow. Nothing non-essential loads until they choose.
The decision is stored on the visitor's own device for a year. A quiet **Privacy & cookies**
button lets them change it any time.
It only appears when something third-party is actually in use. If all your fonts are
self-hosted, visitors never see a banner at all.
The banner uses **your** brand's colours and typography, so it looks like part of your site.
### Categories [#categories]
| Category | What it covers |
| ------------------ | -------------------------------------------------------------------------------- |
| **Necessary** | Essential for the site to work. Always on. |
| **External fonts** | Brand typefaces loaded from Google Fonts (only when you choose Google delivery). |
| **Analytics** | Anonymous usage measurement. Reserved for a future feature. |
| **Embeds** | Third-party embeds such as video or maps. Reserved for a future feature. |
Want zero banners? Set your brand fonts to **Self-host** in the Design System studio. With no
third-party requests, there's nothing to consent to.
## What Atelier itself sends us [#what-atelier-itself-sends-us]
Nothing, unless you ask it to. Your installation does not phone home: there is no telemetry, no
usage ping, no licence check, and no background call on install or on a schedule.
There is exactly one exception, and it is a button you press. **Check for updates**, next to the
model presets in [Connect AI & choose models](/onboarding), downloads the current model
recommendations from `aincient-labs.com/atelier/models.yml`. It is a plain GET of a plain text
file:
* **Sent:** nothing about your site — no identifier, no configuration, no content, no list of
which providers you connected. Only the request itself, which necessarily carries your server's
IP address the way any download does.
* **Counted:** we count the download in aggregate, the same way we count a page view on our
website, so we can tell the recommendations are being used. It is not tied to you or your site.
* **Skippable:** your install ships with a snapshot of that document. Never press the button and
Atelier still works, offline and indefinitely — the suggestions just stay as of your release.
Your AI provider keys are a separate matter: those are stored on your own server and are used to
talk to the provider you chose (Anthropic, OpenAI, Google, your own Ollama). They never reach us.
# Quickstart (https://aincient-labs.com/docs/quickstart)
Atelier ships as a single self-installing container image. You run it locally with Docker,
and the image installs and configures Drupal itself on first boot. When it finishes, you open
the console and start building by chatting.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Prerequisites [#prerequisites]
Before you begin, you need:
* **Docker** with the **Compose** plugin — Docker Desktop on Mac/Windows, or Docker Engine
plus `docker compose` on Linux. Check with `docker compose version`.
* A credential for **an AI provider** — an API key from [Anthropic](https://console.anthropic.com/),
[OpenAI](https://platform.openai.com/api-keys), [Google Gemini](https://aistudio.google.com/apikey)
(a Gemini key also unlocks image generation) or [Mistral](https://console.mistral.ai/api-keys), or
the URL of a local [Ollama](https://ollama.com/) server, which needs no key at all. You can also
add these later in the in-app onboarding wizard, which lets you connect one provider or several.
## Install [#install]
Pick whichever path fits. All three land the **same appliance** under `~/.atelier`, and
each is safe to re-run (re-running is an in-place, idempotent upgrade). No AI key is needed
here — you connect an AI provider in the console's first-run onboarding wizard.
**A · Desktop app (easiest).** A double-click manager that installs, updates, and backs
up your site — no terminal needed. The macOS build is Apple-signed & notarized, so it
opens with no security warning. [Download for macOS or Linux from the latest
release](https://github.com/aincient-labs/manager/releases/latest) and grab the file for
your system (`.dmg` on macOS; AppImage / `.deb` / `.rpm` on Linux). *A Windows app is on
the way — use Homebrew or the one-liner there for now.*
**B · Homebrew (macOS & Linux).** The same manager as a CLI — install once, then operate
with short commands:
```bash
brew install aincient-labs/tap/atelier
atelier app install
```
**C · One-line installer (any Docker host).** No CLI to install first; lays down the
Compose stack and starts it. Ideal for servers and headless hosts:
```bash
curl -fsSL https://aincient-labs.com/atelier/install.sh | bash
```
First boot takes a minute or two while the container installs and configures itself.
Visit **[http://localhost:41221/](http://localhost:41221/)** and log in, then go to **/atelier** for the operator
console.
Prefer to manage the stack yourself? The installer writes a `compose.yaml` and a `.env`
template to `~/.atelier`, so you can run it directly instead. Set `HASH_SALT` in `.env`
(run `openssl rand -hex 32`), then run `docker compose up -d` — connect an AI provider in
the console's onboarding wizard afterward.
## Admin login [#admin-login]
The admin username is `admin`. If you didn't set a password, a random one is generated on
first boot and saved with your install, so you can always recover it. Manage it with the
`atelier` CLI:
```bash
# Show the password generated on first boot
atelier app password
# Set a new password
atelier app password --set 'YourNewPassword'
# Open the console in your browser
atelier app open
```
Locked out, and your site can't send password-reset email yet? Choose **Edit my site** in
the Atelier manager (or run `atelier app open`): it signs you in with a one-time link, no
password needed. Then set a
new password under [My account](/account).
## First run [#first-run]
Once you're in the console, the onboarding wizard runs first if AI isn't connected yet. It
walks you through two quick steps:
Connect one provider or several — **Anthropic**, **OpenAI**, **Google Gemini**,
**Mistral**, or a local **Ollama** server. Paste each API key (or, for Ollama, your
server URL); it's validated against the provider before anything is saved, and stored
on your own server — never in code or git. You can run chat on one provider and images
on another. DeepSeek, Groq, OpenRouter, a LiteLLM proxy and anything else that speaks
the OpenAI API connect through the **OpenAI-compatible endpoint** row, which asks for a
base URL as well as a key — see [Connect AI & choose models](/onboarding).
Connecting **Google Gemini** turns on image generation too: one Google AI Studio key
powers both Gemini chat and Nano Banana image generation.
Atelier works in **roles** — *high thinking*, *task*, and *fast* for chat, plus *image
description* and *image generation*. Pick a model for each from any provider you
connected; the wizard suggests sensible defaults. Change any of them now, or come back
anytime — see **Changing providers later** below.
Each studio uses the role that fits its work: the Design System and Pages studios reason with
*high thinking*, while the everyday assistant runs on *task*. You never pick a model
per chat — the role does it for you, so swapping one model rebinds every studio that
uses it at once.
### Changing providers later [#changing-providers-later]
To add a provider, rotate a key, or change which model a role uses, reopen the wizard from
the console: click your avatar (top-right) → **Set up AI providers**, or visit
`/atelier?onboarding=1` directly. It opens pre-filled with your current providers and model
choices — already-connected providers show as **Connected**, and finishing without changes
leaves your existing setup (and your name) untouched. Only site administrators see this
option.
After that, you're in the [console](/console) — pick a studio and start chatting:
* Open the [Design System studio](/brand-studio) to set your site's identity.
* Open the [Pages studio](/page-studio) to build your first page.
You can change providers or rebind a role to a different model any time — open the avatar
menu (top-right) and choose **Set up AI providers** to revisit the wizard. Already-connected
providers show as **Connected**, so you only fill in what's new. See
[Onboarding](/onboarding#changing-providers-or-models-later) for the details.
## Upgrade [#upgrade]
To move to a newer build, re-run the installer — it pulls the newer image and recreates the
app, which converges in place:
```bash
curl -fsSL https://aincient-labs.com/atelier/install.sh | bash
```
The app snapshots its database, runs any pending updates, health-checks, and automatically
rolls back if something fails. Your database and uploaded files live in Docker volumes and
survive upgrades.
Your own settings are kept across upgrades. An update never resets your site name, your
chosen AI provider, or your model choices — it only ships new features and fixes.
### Upgrading from a much older version [#upgrading-from-a-much-older-version]
Most upgrades are one step. Occasionally a new version can't move a very old site straight to
the newest one — when a release removes something, it can only upgrade sites that have already
been through the version that removed it. When that applies to you, Atelier routes you through
the versions in between rather than failing:
```bash
$ atelier app update
This upgrade takes more than one step
from 0.1.1
1. 0.3.0 (0.4.0 can't migrate a site this old directly)
2. 0.4.0
```
Each step updates and health-checks your site before the next one starts, and a full backup is
taken before the first. `atelier app check-update` shows the same route beforehand, so you know
whether an update is a minute or a coffee break. The desktop app asks the same question.
You don't have to work any of this out. If you upgrade by hand — `docker compose pull`, or
re-running the installer — and your site is too old for the image you pulled, Atelier stops
**before changing anything** and tells you which version to go through first. Nothing is
migrated, so starting the previous image again puts you exactly back.
### Which builds you get [#which-builds-you-get]
**Stable is the supported channel, and the only one the desktop app offers.** It is the image tagged
`:latest`, retagged each time we cut a release.
There is also **edge** — every build off our main branch (`:edge`), unreleased and liable to break.
It exists for testing a fix before it ships, not for a site you care about, so it is reached
deliberately from the CLI and never by picking a menu item:
```bash
atelier app channel # which channel am I on?
atelier app channel stable # follow released versions
atelier app channel edge --now # follow unreleased builds (asks you to confirm)
```
In the desktop app, it's **Settings → Your installation → Updates**. If an install is already on
edge, the row says so and lets you move back to released versions.
Edge can run ahead of the newest release, and a site's database only ever migrates *forward*.
Moving from edge back to stable is therefore a step backwards: Atelier takes a snapshot first
and rolls the database back if the switch fails, but take your own backup
(`atelier data backup`) before doing it on a site you care about.
To pin one exact version instead — no updates at all until you change it:
```bash
AINCIENT_IMAGE=ghcr.io/aincient-labs/atelier-cms:v0.1.2 \
curl -fsSL https://aincient-labs.com/atelier/install.sh | bash
```
## Manage the stack [#manage-the-stack]
Run these from your install directory:
```bash
docker compose stop # stop, keep data
docker compose up -d # start again
docker compose down # remove containers, keep data
docker compose down -v # remove containers AND wipe all data (fresh start)
```
This setup is for **local evaluation**. The container answers any host header and is meant
for `localhost`. Don't expose it on a public address without setting
`AINCIENT_TRUSTED_HOSTS`. No data leaves your machine except calls to your chosen AI
provider for the AI features, using the credential you provide (and nothing at all if you
run a local model server like Ollama).
# Read these docs with AI (https://aincient-labs.com/docs/read-with-ai)
You already build your site by talking to an agent. It would be odd if the manual for
that were locked up in a format only a browser can read.
So it isn't. Every page here is published twice: once as the page you're reading, and
once as plain text meant for a machine. Point your own AI assistant at it and ask your
question there instead of hunting through the sidebar.
## Three sizes, depending on what you're asking [#three-sizes-depending-on-what-youre-asking]
| If you're… | Give your assistant |
| ------------------------------------ | -------------------------------------------------------- |
| already on the page that covers it | the **Copy Markdown** button at the top of it |
| not sure which page holds the answer | `aincient-labs.com/llms-full.txt` — every page, one file |
| happy to let the assistant choose | `aincient-labs.com/llms.txt` — an index of every page |
### One page [#one-page]
Every page has a **Copy Markdown** button at the top, next to the title. It puts that
page — clean text, no navigation, no styling — on your clipboard, ready to paste into a
chat. The button beside it opens the same page as a raw file if you'd rather link to it
than paste it.
Reach for this when you're already looking at the right page and want to ask something
it doesn't quite answer.
### Everything [#everything]
The complete documentation, every page concatenated into one file:
```
https://aincient-labs.com/llms-full.txt
```
Paste that URL into an assistant that can fetch links and ask it to read the file first.
It's a single request, so there's nothing to crawl and nothing to miss — useful when you
don't yet know which part of Atelier your question belongs to.
### Just the map [#just-the-map]
An index of every page, with a one-line description of each:
```
https://aincient-labs.com/llms.txt
```
Give an assistant this and it can choose the page that matches your question and fetch
only that one. Lighter than the full file, and usually enough.
## What to actually ask [#what-to-actually-ask]
The docs describe how Atelier works. Your assistant can turn that into something
specific to what you're doing:
* "Read this file, then tell me how to move my finished site onto Cloudflare Pages."
* "Which provider should I connect if I want image generation, and what does it cost?"
* "I want a second language on the site. What order do I do things in?"
* "Explain the approval model — what exactly is live and what's still a draft?"
Answers get better when the assistant can quote the docs back to you. If it says
something that doesn't match what you see in your console, ask it which page that came
from — the docs move, and a model's memory of them may be older than this file.
## Where this comes from [#where-this-comes-from]
`llms.txt` is a small shared convention for publishing a site in a form language models
can read — see [llmstxt.org](https://llmstxt.org) for the specification. Both files
above are generated from these same pages at build time, so they're never a stale copy:
if it's in the sidebar, it's in the text.
The marketing site publishes its own [`/llms.txt`](https://aincient-labs.com/llms.txt)
describing the product and how to install it, and links onward to both files here.
The same idea, applied to your site: take the whole thing with you as plain files.
Set up the providers Atelier itself uses to build your site.
# How your page appears elsewhere (https://aincient-labs.com/docs/seo-presence)
A page isn't only what visitors read on it — it's also how it shows up when it's referenced somewhere else.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
Editing presence works like every other change in Atelier: you edit an **unsaved draft**,
and it goes live only when you click **Publish**. The agent never publishes on its own.
## Body and Presence [#body-and-presence]
In the **Pages** studio, a **Body ｜ Presence** facet sits above your work and switches what
you're editing:
* **Body** — the page itself: the sections visitors read when they open it.
* **Presence** — how the page represents itself when it's referenced somewhere else.
Switch to **Presence** and the studio stops editing the page's sections and starts editing
its metadata instead.
## What presence covers [#what-presence-covers]
Presence gathers everything about how the page looks off the page:
* **SEO** — the page's title and description, used by search engines and browsers.
* **Social** — its Open Graph card, shown when the page is shared on social platforms and in
chat apps.
* **Search** — how the page appears as a result on a search engine.
For Fernway Botanical Studio's care-guide page, that's the SEO title that shows in a browser
tab, the description a search engine quotes, and the image and text that appear when someone
pastes the link into a message.
## Preview the real result [#preview-the-real-result]
When you switch to **Presence**, the preview swaps too. Instead of the page body, it shows
the actual cards your metadata produces:
* a **teaser** card,
* a **social** (Open Graph) card,
* and a **search** result.
So you're never guessing how a change will land — you see the real teaser, the real social
card, and the real search snippet update as you type. Trim Fernway's description to fit and
you watch the search card stop truncating in front of you.
Presence lives alongside the page body in the same studio, on the same draft.
# Several sites on one machine (https://aincient-labs.com/docs/several-sites)
One Atelier installation can run several independent sites side by side — a blog next to your company site, a client's site next to your own. Each site is its own appliance with its own containers, database, uploaded files, port and backups. Nothing is shared between them.
## Create and list sites [#create-and-list-sites]
```bash
atelier sites add blog --label "Blog"
atelier sites list
```
`sites add` creates the site in `~/.atelier/sites/blog`, gives it the first free console port (41222, 41223, …) and installs it. Pass `--port ` to choose the port yourself. `sites list` shows each site's name, port, whether it is running, and its version. The active site is marked with `*`.
If you already had Atelier installed, your existing site appears as `default`. It stays in `~/.atelier` with all of its data — it is never moved.
## Choose which site a command acts on [#choose-which-site-a-command-acts-on]
Every `atelier` command accepts `--site `:
```bash
atelier --site blog app status
atelier --site blog data backup
atelier --site blog app open
```
Without `--site`, commands use the **active** site. Change it with:
```bash
atelier sites use blog
```
The order is: `--site`, then the `ATELIER_HOME` environment variable, then the active site, then `~/.atelier`.
## Rename or remove a site [#rename-or-remove-a-site]
```bash
atelier sites rename blog "The Blog"
atelier sites remove blog
```
`rename` changes only the display name; the site's folder and data are unchanged. `remove` stops the site and takes it off the list, but **deletes nothing**: its folder, database and uploaded files are kept. Run `atelier sites add blog` to bring it back with its data. The `default` site in `~/.atelier` can't be removed.
## Update every site [#update-every-site]
```bash
atelier app update --all
```
Updates each installed site in turn, each along its own upgrade route. If one site fails, the others still update, and the command tells you which one failed.
## Things to know [#things-to-know]
* Every running site runs its own containers, including its own database, so each extra site uses more memory.
* Each site has its own AI provider keys: connect AI in each new site's onboarding.
* `atelier doctor` warns if two sites are set up on the same port, since only one of them can run at a time, and shows the command that moves one to a free port.
* The desktop app works on the active site — choose it with `atelier sites use`.
# Site details & error pages (https://aincient-labs.com/docs/site-settings)
The **Globals** studio's **Site** tab is where your site stops being anonymous — you set the address system mail comes from, and you choose which pages serve at the site root and when something goes wrong.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Open the Site tab [#open-the-site-tab]
From the top nav, open the **Site** menu, choose **Globals**, then switch to the **Site** tab. You'll find the system email field and the three page slots.
## System email [#system-email]
Set the address system mail is sent **from** — password resets, account notices, and other notifications. This is the "from" identity your visitors see on those messages.
## Front page, 404, and 403 [#front-page-404-and-403]
Point each slot at a page you've already built:
The page that serves at your site root — the first thing visitors see.
Shown when someone hits a URL that doesn't exist.
Shown when someone tries to reach a page they're not allowed to see.
Pick any published page from the same picker used everywhere else in the console — for example, Fernway Botanical Studio's welcome page for the front page slot. If you'd rather, paste a token like `entity:node:` instead.
## Every field is optional [#every-field-is-optional]
Each slot falls back gracefully:
* An **empty field** means "use the shipped default."
* **Clearing** a field puts the default back.
* **Deleting** a page that a slot points at safely resets that slot — no broken site root, no dead error page.
## What happens on publish [#what-happens-on-publish]
The agent never publishes on its own. Your changes live in an unsaved **draft** until you press **Publish** — only then do they take effect.
On **Publish**, the choice takes effect immediately. Your chosen page serves at the site root, and visitors who hit a missing or restricted URL see **your** page — styled in your brand — instead of a bare system error.
Build a friendly 404 that links back to your best pages. A lost visitor on Fernway Botanical Studio's site is one plant guide away from staying.
Shape the header, footer, and identity that wrap every page.
Choose how the mail from your system address actually gets sent.
# Export a static site (https://aincient-labs.com/docs/static-export)
Atelier can export your entire public site as a **static snapshot** — plain HTML, CSS, images, and assets you can host anywhere, with no running server needed.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## What a static export is [#what-a-static-export-is]
A static export is a self-contained copy of your published site as ordinary files. Drop the folder onto any static host — or a plain web server, or even a USB stick — and it just works. Nothing needs to keep running behind it.
## What the export includes [#what-the-export-includes]
When Atelier builds the snapshot, it:
* **Renders every published page** into finished HTML.
* **Warms the right-sized image versions** so photos load fast on every device.
* **Checks internal links** along the way, so you know the snapshot hangs together.
You can also **bundle your configuration and users** alongside the site, so the export carries not just the pages but the setup behind them.
## You own your data [#you-own-your-data]
Your content in Atelier is real, structured content — not locked inside a page builder — and your configuration travels with it. That means you can take the whole thing with you at any time:
* Move Fernway Botanical Studio to a different host without a migration project.
* Keep an offline archive of the site as it looked on a given day.
* Hand a client a complete, hostable copy of their site.
## Put it online [#put-it-online]
Once you have the export, host it anywhere static files are served — Netlify, Cloudflare Pages, Vercel, GitHub Pages, your own server, or object storage. The [Host your exported site](/deploy) guide walks through each one, step by step.
A static export is a snapshot of your **published** site. Keep editing in the console as usual; export again whenever you want a fresh copy.
Want the appliance itself to serve a snapshot to visitors while you keep editing? That is [Freeze & Live](/freeze-and-live): the same export, kept as versions inside Atelier, switchable in one click.
Owning your data is a feature, not a formality. Because your content and configuration both travel, you're never locked in — Atelier is a place to work, not a place your site is trapped.
How Atelier treats your content and who can see it.
Where the technical settings behind your site live.
# Editing sections by hand (https://aincient-labs.com/docs/structured-editor)
You and the agent edit the same draft, and you don't have to use chat to do it.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
The agent never publishes on its own. Every edit — from chat or from the editor — updates
an **unsaved draft** and re-renders the preview. Your page goes live only when you click
**Publish**.
## The structured editor [#the-structured-editor]
In the **Pages** studio, the structured editor lists your page's sections in order. Each
section is a collapsible card: expand one to edit its fields, collapse it to scan the whole
page. It sits beside the live preview, so you always see what your change does.
Reach for the editor when you know exactly what to change — a headline, a price, the order
of two sections — and want to change it directly instead of describing it in chat.
## Add, remove, and reorder sections [#add-remove-and-reorder-sections]
You shape the page from the editor as well as from chat:
* **Add** a section from the component library at any position.
* **Remove** a section you no longer want.
* **Reorder** sections with the move buttons, or by dragging a card up or down.
* **Collapse** or **expand** each card to focus on the section you're working on.
The preview re-renders the moment you make a change, so reordering the Fernway Botanical
Studio hero above its "Meet the growers" story is instant and visible.
## Edit a section's props [#edit-a-sections-props]
Open a card and you edit that section's fields directly. Depending on the section, you'll
find:
* **Tone** — an enum control with `default`, `muted`, `brand`, and `inverted`. Adjacent
sections auto-alternate so a page never blurs together.
* **Variant** — an enum control for a section's named arrangement, such as a split or
centered hero.
* **Anchor** — a slug (`pricing`) that makes the section a link target: any link field can
point at it as `#pricing`. Available on every section, under Appearance.
* **Repeatable rows** — add, remove, and reorder items like feature cards or pricing tiers.
* **Accordion panels** — the expandable panels of an accordion section.
* **Media and block pickers** — choose an image or a reusable block by reference.
* **Multiline text** — longer copy fields such as a subheading or body paragraph.
* **Toggles** — on/off switches for a section's options.
For example, set the Fernway hero's **variant** to split, its **tone** to `brand`, and add
two rows to the features grid ("Repotting clinic", "Plant-sitting") — all without typing a
sentence of chat.
## Click the preview to jump to a section [#click-the-preview-to-jump-to-a-section]
You don't have to hunt through the card list. Click any section in the live preview and its
card opens and scrolls into view in the editor, ready to edit. It's the fastest way to go
from "that band looks wrong" to changing it.
## Track and revert unsaved changes [#track-and-revert-unsaved-changes]
Every unsaved edit is marked so you always know what you've touched:
* A per-field **accent dot** marks a field you've changed but not yet published.
* You can **revert a single field** back to its published value without losing your other
edits.
* Each card shows its own **dirty count**, and the studio shows a **total** across the page.
Nothing is saved until you **Publish**. Until then the live site is untouched, and you can
revert field by field or **Discard** the whole draft.
See how chat and the structured editor share one draft — and how to publish it.
Every section you add or edit comes from this curated set, and reskins from your brand.
# The System back-office (https://aincient-labs.com/docs/system)
Almost everything you do lives in the console. A few technical settings live in the **System** back-office, and Atelier keeps that on purpose small.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Where it is [#where-it-is]
Open the System back-office at `/admin`, reachable from your **account menu**. When you're done, a **← Console** link jumps you straight back to `/atelier`. You'll rarely need to visit — the console is home.
## What lives there [#what-lives-there]
Atelier keeps the back-office to just the technical settings that don't belong in a studio:
Manage accounts and roles — who can sign in and what they can do.
See your AI usage and cost per turn, plus its settings.
Configure how your site sends email. See [email](/email).
Add and manage the languages your site is available in. See [multilingual pages](/translation).
The back-office is intentionally minimal. Building pages, media, brand, and everything day-to-day happens in the console — not here.
## Which version am I running? [#which-version-am-i-running]
Open **Reports → Status report** at `/admin/reports/status` and look for the **Atelier version** row.
Atelier ships as a container image that updates itself when you pull a newer one, so this row — not the date you installed — is what tells you which Atelier you're actually running. **Include it whenever you report a problem**: it's the difference between a bug we've already fixed in a newer image and one we haven't heard about.
You'll see one of three things:
* **A version like `v0.1.0`** — a released image. This is the normal answer.
* **A version with `+edge.` and a short code**, like `v0.5.1+edge.a1b2c3d` — a rolling build off our main branch rather than a release. The version in front is the last release it contains; the code after it identifies the exact build. Newer, but less settled — include the whole string. (Builds published before August 2026 read `edge+` and a code, with no version in front.) Edge is for testing; see [channels](/quickstart#which-builds-you-get) to move back to released versions.
* **"Development"** — not a released image at all, which is expected if you're running Atelier from source. If you installed from a release and still see this, mention that too.
The same page lists your PHP and database versions and flags anything Atelier thinks needs attention — so it's a good screenshot to attach to a bug report as-is.
If you're not sure where a setting lives, start in the console. Only reach for `/admin` when you need People, AI metering, Mail, or Languages — then use **← Console** to get back to work.
Set up how Fernway sends its email.
Manage your own profile and access.
# Conversations & threads (https://aincient-labs.com/docs/threads)
Every studio keeps its own chat history and its own new conversations, so switching studios never tangles your work.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Start a new thread for a new task [#start-a-new-thread-for-a-new-task]
Each new task deserves a **new thread** — a clean context the agent can focus on. When you're helping Fernway Botanical Studio, you might keep the homepage rewrite in one thread and a new care-guide page in another.
The thread sidebar lists your live conversations, date-grouped into **Today**, **This week**, and **Earlier**.
A thread about a page shows that page's state beside its name — **Draft**, **In review**, or **Live** — in the thread's own language, so you can pick the right conversation without opening it. Hover the marker for the full detail, such as *Draft · published copy live* when a newer draft sits on top of the live page.
## Manage a thread [#manage-a-thread]
Every thread has a **⋯** menu. From it you can:
* **Rename** the thread — though threads auto-name themselves from what you're working on.
* **Archive** a thread to tuck it out of the list.
* **Delete** a thread you no longer need.
* **Wrap up** or **reopen** a thread manually.
## Wrapped-up conversations [#wrapped-up-conversations]
When you publish a brand-new page, its conversation is **wrapped up** — marked **Done** and made read-only. That keeps a thread whose work is already live from running on. Start a new thread for the next change.
Publishing a new page finishes that thread on purpose. If you want to keep iterating on the same page, start a fresh thread — its live URL stays exactly where it is.
## Choosing an agent [#choosing-an-agent]
On rooms that offer more than one agent, an **agent picker** at the top of the chat chooses which agent a new conversation uses.
## Dictate instead of typing [#dictate-instead-of-typing]
Press the **mic** button to dictate your message using your browser's voice-to-text, then send it like any other message.
How drafts and approval keep every conversation safe.
# Multilingual pages (https://aincient-labs.com/docs/translation)
Atelier is multilingual: add a second language, translate your pages, and let visitors switch between them on the live site.
{/* VIDEO PLACEHOLDER (hidden) — walkthrough pending; see docs/demo/video-index.md.
When filmed, restore the embed:
*/}
## Add a language [#add-a-language]
First, add the language you want to publish in.
Go to **Languages** in the [System back-office](/system).
For Fernway Botanical Studio, that might be German alongside English. Once added, it becomes available to translate into.
## Translate a page [#translate-a-page]
With a second language available, open a page and translate it into that language. Atelier offers two modes:
* **Symmetric translation** shares the source page's layout, so only the words change. The German page mirrors the English page's structure — you just swap the text.
* **Asymmetric translation** gives the translation its own independent layout. You can let it diverge from the source — a different hero, an extra section for a local promotion — or bring it back in line with the source when you want them to match.
Translations follow the same promise as everything else: the agent proposes and previews, and the page goes live only when **you** click **Publish**.
## Each language publishes on its own [#each-language-publishes-on-its-own]
Every language keeps its own draft. Publishing the German page puts only the German changes live — an English draft you're still working on stays a draft until you publish it in English.
## Translate a block [#translate-a-block]
Reusable blocks translate the same way. Open the block, pick a language from the language menu, and translate its words. A block translation always keeps the source block's layout, and every page that uses the block shows it in the visitor's language.
## Switching languages on the live site [#switching-languages-on-the-live-site]
Once your site has more than one language, a **language switcher** appears in the site header — visitors tap a language code (e.g. `EN` / `DE`) to move between languages, landing on the same page in the language they choose. On a single-language site the switcher stays hidden; it lights up automatically the moment you add a second language.
Start with **symmetric** translation when you just need the same page in another language — it's the least work. Reach for **asymmetric** only when a language really needs its own layout.
How pages are built before you translate them.
Where you add and manage languages.
# When something's wrong (https://aincient-labs.com/docs/troubleshooting)
Atelier runs on your own computer, which means when something breaks, the answer is usually
on your machine rather than on a server you can't reach. The manager has a **checkup** that
looks at everything in order and tells you what it found — and can repair most of it for you.
## Run a checkup [#run-a-checkup]
**In the desktop app**, go to **System → Troubleshoot** and choose **Run a checkup**. You'll get
a list grouped into *your computer*, *Atelier itself*, and *your website*, with a note under
anything that needs attention. If the problems are ones Atelier can fix, a **Repair what you
can** button appears.
**In the terminal**, the same checkup is one command:
```bash
atelier doctor
```
That only looks — it never changes anything. To repair what it found:
```bash
atelier doctor --fix
```
## What it checks [#what-it-checks]
The checkup works outward-in, because a problem in one layer makes the next one impossible to
judge. If it can't get past a layer, everything below is marked **skipped** rather than failed —
"we couldn't look" and "we looked and it's broken" are different answers, and you'd chase the
wrong thing if they looked the same.
Docker is installed and running, the Compose plugin is there, nothing else has taken
Atelier's port, and there's enough free disk space.
Atelier's own setup files are intact, both of its parts are running, and neither is stuck
restarting over and over.
Your site starts up, no half-finished update is left over, your uploaded images are still
writable, the site passes its own health check, and an AI model is connected.
## What a repair does [#what-a-repair-does]
Repairs go from gentlest to strongest, and stop as soon as your site is well again — so if
clearing a cache was all it took, nothing further runs.
If one of Atelier's own files is damaged, it's rewritten. Your old file is kept alongside
rather than deleted, in case you'd customised it.
Then it waits until your site genuinely answers, rather than assuming it's ready the moment
it starts.
The single most common cure for a site that's behaving strangely after an update.
If an upgrade stopped partway, this completes it.
Occasionally a restore leaves your images owned by the wrong account, which quietly breaks
new uploads while everything else looks fine.
The strongest step. It takes a snapshot of your site first and puts it straight back if the
repair doesn't help.
**A repair never deletes anything.** Every step is reversible — the worst case is that it
takes a few minutes and doesn't help. Removing Atelier, reinstalling it, and restoring a
backup are *not* part of a repair; if one of those is what you need, the checkup says so and
leaves the decision to you.
## If it still isn't fixed [#if-it-still-isnt-fixed]
If your site itself is damaged rather than just stuck, go to **Backups** and restore the
most recent one. See [keeping your work safe](/static-export).
Include the checkup's output — from the terminal, `atelier doctor --json` gives a complete
report you can paste in. Add the **Atelier version** from
[Reports → Status report](/system#which-version-am-i-running) too.
The checkup is safe to run anytime, and safe to suggest to someone else — on its own it only
reads. Nothing changes until you ask for a repair.
The one detail worth including in every bug report.
Setting Atelier up, and keeping it current.