> ## Documentation Index > Fetch the complete documentation index at: https://docs.avocadostudio.dev/llms.txt > Use this file to discover all available pages before exploring further. # Hand the change to an agent. The design system holds. > Avocado Studio is the agentic operations layer for a website that already exists. An agent plans your change and applies it as typed content operations — from chat, from a click on the live page, from a Jira ticket, or from any MCP client — and never as a code change. Your components are the blocks, so what comes back is built out of your own design system and publishes into the CMS you already run.

## Building a website is the solved part The hard part starts after launch. Someone has to change the pricing copy, swap the hero image, add a testimonial, ship the French version, and fix the CTA that tested badly — every week, forever, on a site that a developer built and a marketer owns. Today that work goes one of three ways. It becomes a ticket queue, and the developer is the bottleneck for a headline change. It goes to a coding agent, and now a marketing request can produce a deploy. Or somebody stands up ContentOps — a platform, a console, a governance workflow — and the content leaves your repository for a vendor's model of it, with your components rebuilt as theirs. Avocado Studio is the fourth answer: **the same agents, pointed at your content instead of your codebase.** Your team — or an agent acting for them, in Jira, in Claude Code, in any MCP client — describes the change, and an agent plans it, applies it as **typed content operations against a boundary you declared in your own repo**, and shows it on the real page before anything ships.

Marketing gets an editor. You get a type signature. Your git log stays about your code.

## Safety that is structural, not procedural Everyone now agrees that agents need governed content before they can be trusted to act on a website. That is the right answer, and it has stopped being a differentiator. The question worth putting to any vendor selling it is narrower: **what is the governance made of, and where does it live?** Avocado's answer is a type, in your repository. This is the design decision everything else follows from, so it is worth being precise about. Tools that let an AI agent edit your site by writing code are safe because of **process**: a pull request, a reviewer, a role, an approval, an audit log. Every one of those is a human step that can be tired, rushed, or skipped, and the blast radius when it is skipped is your production deploy. Avocado is safe because of **structure**. Every edit the system can make is one of a fixed set of typed operations — `update_props`, `add_block`, `reorder_items`, `update_page_meta`, and so on. That vocabulary has no verb for "change a file." A model driving Avocado at full confidence with every guardrail disabled still cannot modify a component, add a dependency, alter a route, or touch your build. It is not that we review the dangerous edit; it is that the dangerous edit is not expressible. Block props, list items, block order, page metadata, pages, navigation, theme tokens — all validated against your Zod schemas before they are applied, and all undoable. Your components. Your routes. Your dependencies. Your middleware. Your build config. Not by policy — the operation vocabulary cannot encode it. A process is weaker than a type. That is the whole product. ## Four ways in, one set of operations Describe it, click it, drag it, or send it from somewhere else entirely. All four produce the same typed operations against the same content, and every one of them renders your real pages — not an approximation of them in someone else's canvas. **The default surface.** Describe the change in plain language — *"add a testimonials section to /pricing"*, *"make the hero CTA say Book a demo"*, *"translate this page into German"* — and the AI plans it, streams the operations into a live preview as they arrive, and holds anything destructive for approval. English and German today. Turn on the element picker and click a heading, a card or an image on the live page. The property panel lists that block's real fields and writes real values with no model involved — free, instant, and impossible to misread. Reorder sections by hand, or add blocks from your catalogue, in a [Puck](https://puckeditor.com/)-based visual editor with the AI chat in the sidebar alongside. Enabled per site. Drive the same edits from outside the editor: 49 tools over Model Context Protocol for Claude Code, Cursor or any MCP host, or [a Jira ticket](/integration/jira) that plans the change and posts back a preview link. Around all four sit the things that make them safe to hand out: a live preview of the real page, server-side undo, a version log you can revert or pick individual changes out of, and a publish step that shows you the field-level diff before anything goes live. ## Your components are the blocks Avocado does not ask you to rebuild your site out of its parts. A **block** is a component you already have, registered with a schema that says which of its props are content. ```ts theme={null} import { registerBlock, z } from "@avocadostudio-ai/site-sdk/blocks" registerBlock("PricingTier", { schema: z.object({ name: z.string().min(1), price: z.string().min(1), blurb: z.string(), }), meta: { displayName: "Pricing tier", fields: { name: { kind: "text" }, price: { kind: "text" }, blurb: { kind: "richtext" }, }, }, }) ``` That registration is the boundary. `name`, `price` and `blurb` are editable by marketing; `badgeVariant` — which you did not declare — is not, and no amount of asking will make it so. When someone needs a field that is not there, you add a line. See [custom blocks](/integration/custom-blocks) and the [field table](/integration/field-table). Twenty built-in block types (Hero, CTA, FAQ, Testimonials, Gallery, Stats, Carousel, Table, and more) ship as a starting catalogue for sites built from scratch — but on an existing site, the blocks are yours. ## Your content stays where it lives Avocado is **not a CMS** and does not store your content. It reads and writes through an adapter to whatever you already chose. ```mermaid theme={null} flowchart TB People["Your team
marketers · content owners · founders"] subgraph Avocado["Avocado Studio"] direction TB Chat["AI chat editor"] Visual["Visual editor"] AI["AI orchestrator
(your Anthropic / OpenAI / Gemini keys)"] Ops["Operations engine
(typed ops, validated, undoable)"] Draft["Draft state + live preview of your real pages"] end subgraph Stack["Your stack — unchanged"] direction TB Code["Your codebase
Next.js or Astro · your components · your design system"] CMS["Your CMS
Sanity · Storyblok · Contentful · Strapi · JSON files"] DAM["Your assets
Cloudinary · S3 · your CMS's media · /public"] Deploy["Your hosting
Vercel · Netlify · Cloudflare · your VPS"] end People -- "chat / click" --> Avocado Avocado -- "typed content ops only" --> Stack style People fill:#1F7A3A,stroke:#14532D,color:#fff style Avocado fill:#7ED957,stroke:#14532D,color:#0a0a0a style Stack fill:#f1f5f9,stroke:#64748b,color:#0a0a0a ``` The arrow out of Avocado is narrow on purpose. It carries content operations and nothing else. **Multilingual is first-class**, because the sites this was built for are. Avocado handles CMSes that localise per field — a `title` with a German, English and French value under one document — including the [two rules and two traps](/integration/multilingual) that silently corrupt a dataset if an adapter gets the projection wrong. Rich text converts through a shared pivot with converters for [four CMSes](/integration/cms-adapters). ## Bring your own keys Avocado runs on **your** Anthropic, OpenAI or Google API keys. We never resell you tokens and there is no per-seat model markup — what you pay is your cloud bill plus your own token spend, billed by your own provider. The planner is tuned and evaluated on Claude Sonnet 5.5, and the editor offers Claude models whenever an Anthropic key is set. OpenAI and Google Gemini also drive the per-edit chat, on a deployment that has only their key. The onboarding agent is Claude-only today. See [AI providers](/ai-providers). ## Getting your site in **Be realistic about what this costs.** On a real site — one with a CMS behind it, or shipping in several languages — expect a developer and an agent to spend a few days, not an afternoon. The work is declaring your content model and marking up your renderers; it is bounded, mechanical, and mostly one-time, but it is real. **The path we recommend.** You already run Claude Code, Codex or Cursor, and it already knows your codebase. Point it at these docs, and the work lands in your repo through your normal review flow. An agent inside the editor that migrates a public URL, integrates a GitHub repo, or scaffolds a new site. Early — treat its first pass as a draft. **Needs the standalone orchestrator; not available on an npm install.** The integration reference: every seam, every helper, what each one is for. Whether you or an agent writes the code, this is what it has to satisfy. `npx avocado qa` 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 exposes and whether the property panel is usable. **Avocado Studio is a research preview.** It is real software doing real work — the demo below is a nine-page site you can edit and publish in about a minute — but expect rough edges, and expect things to move. If you hit one, tell us: at this stage a specific report is worth more than a feature request. ## Start here ```bash theme={null} npm create avocado-site@latest my-site cd my-site && npm run dev ``` That is the whole thing: a nine-page demo site and a working editor, in about a minute, with no API key and nothing to configure. **[First run](/first-run)** walks through what to click, what a key costs when you add one, and which of the surprises are deliberate. ## Which path are you on? Three different people read these docs, and they want different things first. You write the copy and own the pages, and someone has already wired Avocado up for you. **[A tour of the editor](/editing)** — what is on screen, the one button that makes the page clickable, and how to undo anything. You have a codebase and a CMS, and you need Avocado to reach them. Start at **[bring your site in](/sites)** for the three honest paths, or **[add it to your site](/quickstart)** to see the loop end to end first. You are deploying this. **[Security and access](/reference/security)** is the page to read first — the production gate is closed by default, and that surprises people. Then **[environment](/reference/environment)** and **[state and backups](/operations/state-and-backups)**. Or jump by task: **[How do I…?](/recipes)** is the index organised by what you are trying to get done. If you would rather read before you type: One command, a real site to click through, and an honest account of what it does and does not do yet. Start here if you are still deciding. Pages, blocks, operations, draft mode — the mental model. The pipeline from a sentence to an applied, reviewable change. The services, the packages, and the data flow between them. 49 tools over Model Context Protocol — stdio or HTTP. Works with Claude Code, Claude Desktop, Cursor, and any other MCP host. Move a ticket to Review; Avocado plans the change, applies it to draft, posts a preview link, and waits for an approval comment. ## What you get * **Open source, self-hostable, no per-seat licence** — run the whole stack on your own infrastructure. [Apache 2.0](#license), published to npm as `@avocadostudio-ai/*`. * **Typed operations** — 19 op types, each validated against your Zod schemas. Malformed AI output is rejected before it reaches your content. * **Review and rollback** — every plan is previewable, approvable, undoable, and recorded in a version log. Destructive operations are held for explicit approval. * **Live preview of your real pages** — edits stream into the actual site as the plan is generated, not into a mock. * **Publish what you chose** — publish a subset of changed pages, diffed field by field against the baseline, so a target that writes diffs writes nothing for pages nobody touched. A publish through the site's publish contract that would remove every page is refused unless the request says so in as many words, because what usually produces one is a client that failed to load its own state rather than somebody deleting a site. See [publishing](/integration/publishing). * **Your CMS, adapted once** — working examples for JSON files, Contentful, Sanity and Strapi, plus [field-table lens packs](/integration/field-table) for Storyblok, Sanity and [Contentful](/integration/contentful) that derive the schema, the panel, the projection and the merge from one declaration. * **AI images built in** — Google Gemini or OpenAI, plus Unsplash search. See [asset manager](/features/asset-picker). * **Site health checks** — [rules that read your pages](/features/site-health) and report metadata, structure, link and image problems. * **MCP server** — 49 tools, any MCP host. **Scope.** Avocado Studio is in active development. Next.js 15 and 16 on the App Router is the tested path; Astro 5+ has its own integration package, [`@avocadostudio-ai/astro`](/integration/astro-integration), with a fixture site and two gates — one of them a real browser — driving it on every push. Other frameworks can be wired through the framework-agnostic [`/core` primitives](/integration/non-nextjs), but you would be a first mover. The orchestrator self-hosts via [Docker](/operations/docker-deployment). ## License Avocado Studio is open source under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). That covers every `@avocadostudio-ai/*` package and `create-avocado-site` — the AI engine (`orchestrator-core`) and the editor included. * **Use it commercially**, on your own sites or your clients'. * **Modify it, and self-host it.** No licence key and no seat count. * **Keep the notices** when you redistribute it, which is all Apache 2.0 asks. Every package on npm carries its readable source. The GitHub repository is not public yet. ## Also worth knowing * **[The editorial brief](/editing/brief)** — tell the site how it should sound, once, instead of in every prompt. * **[Environment reference](/reference/environment)** — every variable Avocado reads, in one table. * **[CLI and packages](/reference/cli)** — every command Avocado ships, and what each of the twelve packages is for. * **[Glossary](/reference/glossary)** — for the meeting where a marketer and a developer are describing the same thing differently. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.