How do I…?

The rest of the docs are organized by system — editing, your site, customize, automate, self-host. This page is organized by task: what you actually want to do, and where it is written down. If you don’t see your task here, try the demo is usually the right first stop.

​

Edit the site

​

Make my first edit

Turn on the element picker, click the thing you mean, and say what you want. → A tour of the editor · Writing prompts that work

​

Undo something, or go back to this morning

Four different ways back, and they are genuinely different tools. → Review, undo and versions

​

Publish only some of my changes

Every page in the publish dialog has its own checkbox. → Publishing your changes

​

Stop repeating “keep it in our voice” on every request

→ The editorial brief

​

Get started as a developer

​

See it running in two commands

Boot a real nine-page site and the editor, with no API key and no repository. → Try the demo

​

Add it to a Next.js site I already have

→ Add Avocado to your site · Manual setup

​

Understand the model before writing any code

Pages, blocks, props, operations, sessions, snapshots. The mental model that everything else builds on. → Core concepts · How it works · Architecture

​

Bring in your own site

​

Hand the integration to your coding agent (Claude Code, Cursor, Codex)

The recommended path. Your agent already knows your codebase, and the work lands through your normal review flow. → Bring your own coding agent

​

Let the built-in onboarding agent do it

Give the in-editor onboarding agent a URL or GitHub repo. It analyzes, wires the SDK, and registers the site. Early — treat the first pass as a draft. → Onboarding agent

​

Read the integration contract

Every seam the integration has to satisfy, whether you or an agent writes the code. → Integration contract · Next.js integration reference

​

Prove the integration is finished

Run npx avocado qa from the site’s directory with the dev server up. It renders every page the way the editor will, in a frame on the editor’s origin, and exits non-zero until the integration is right. editableCoverage and panelCoverage grade which declared fields the page actually exposes and whether the property panel is usable. → QA gate · Coverage checks

​

Connect a CMS

​

Wire up Contentful, Sanity, or Strapi

All three ship as working examples under examples/ with bootstrap scripts that generate the content model for you. Contentful also has a lens pack, @avocadostudio-ai/site-sdk/lens/contentful, that reads and publishes entries field by field. → CMS adapters · Contentful

​

Write an adapter for a CMS we don’t ship (Hygraph, Payload, Directus, …)

Two functions: getPages({ perspective }) → PageDoc[] and onPublish(pages, config) → CmsPublishResult. How much sits behind them depends on how far your CMS’s shape is from a PageDoc — a JSON-backed site is almost nothing; a CMS that localises per field and stores list rows as their own documents is the real work. → CMS adapters — Writing your own · Field table

​

Edit a site with no CMS, whose copy is in the templates

Move the copy into one JSON file per page, keep the markup and the styles, and publish as a clean git diff. → File-backed sites

​

Customize what’s editable

​

Make your own components editable

On a site that already exists, your components are the blocks. Register one with a Zod schema and field metadata, and the AI planner edits it like any other block. → Custom blocks · Block system

​

Declare a CMS-backed content model once

One field table derives the Zod schema, the panel metadata, the projection out of your CMS, and the merge back into it. Packs ship for Storyblok, Sanity and Contentful. → Field table

​

Pin a section, lock a field, or share a block across pages

fixed: true keeps a block where the site draws it. readOnly: true shows a field with a reason and refuses every write. shared: true makes one block — a promo strip, a contact panel — the same content on every page that holds it. → Fixed blocks and read-only fields · Shared blocks

​

Browse the live catalogue of built-in blocks

20 blocks, each with editable props, in a live workspace with viewport switcher. → avocadostudio.dev/components · Built-in blocks reference

​

Use drag-and-drop instead of (or alongside) chat

Avocado ships a Puck integration that produces the same BlockInstance model from a visual editor. → Puck mode

​

Drive Avocado from outside the editor

​

From any MCP client

Avocado bundles an MCP server with 49 tools over stdio or streamable HTTP. Drop in a config snippet and Claude Code, Claude Desktop, Cursor, or any other MCP host can read and edit your site directly. → MCP server

​

From a Jira ticket

Webhook + REST integration that turns ticket comments into chat messages. It runs on the standalone orchestrator, not in library mode. → Jira integration

​

Deploy

​

Self-host with Docker

The supported production path. Docker image + persistent volume + Render / Fly / Railway / DO / Kubernetes. → Docker deployment

​

Deploy the editor + site to Vercel

Three projects: orchestrator (Docker/Render), editor (Vercel), site (Vercel). → Vercel deployment · Netlify deployment

​

Run a public playground / demo

Locked-down DEMO_MODE=1 with allow-listed ops, per-IP rate limiting, and no AI image gen. → Demo mode

​

Publish to a custom target (S3, GitLab Pages, …)

Implement PublishTarget (two methods) and register it. The route handler picks it up automatically. → Publishing — Building a custom target

​

Lock down a production deployment

Two credentials, three gates, and the one surface that stays off unless you turn it on. → Security and access

​

Back up the drafts that are not published yet

Where the SQLite state lives, what is capped, and what a snapshot restores. → State and backups

​

Tune AI behavior

​

Use Gemini or OpenAI instead of Claude

Set only that provider’s key. The editor’s model picker offers Claude whenever an Anthropic key is set, and lists the other providers on a deployment without one. Image generation is separate: an OpenAI or Gemini key turns it on alongside a Claude planner. → AI providers and model routing

​

Use cheaper models for routine edits, smarter ones for restructures

Per-tier model env vars (*_MODEL_FAST, *_MODEL_BALANCED, *_MODEL_REASONING, *_MODEL_CODEX). Restart the orchestrator after changing one. → AI Providers — Model tiers

​

Add a new language to the editor + AI responses

One new dictionary file, three lines of glue, one entry in the orchestrator’s LOCALE_NAMES. → Internationalization

​

Debug

​

A chat returned the wrong operation (or no operation)

Playbook for investigating prompt failures, wrong ops, and regressions. → Chat troubleshooting

​

See what the planner is spending in tokens

Per-request token usage telemetry with per-provider breakdown. → Token usage tracking

​

Follow one chat request through its phases

Every chat turn emits phase events, from received through planning and apply to result. → Chat telemetry events

​

Find out what an environment variable actually does

Every variable Avocado reads, grouped by what it configures. → Environment reference

​

Look up a command or a package

Every command Avocado ships, every flag each takes, and what each of the twelve packages is for. → CLI and packages