> ## 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.

# Core Concepts

> Key terms and mental model for understanding Avocado Studio.

## Pages, Blocks, and Props

Avocado Studio manages website content as structured data, not raw HTML.

* **Page** (`PageDoc`) — A single page on your website (e.g., `/about`, `/pricing`). Contains metadata (title, slug) and an ordered list of blocks.
* **Block** (`BlockInstance`) — A content section on a page. Each block has a **type** (e.g., `Hero`, `CTA`, `FAQAccordion`) and **props** — the structured data that controls what it renders.
* **Props** — The fields that make up a block's content. A Hero block has `heading`, `subheading`, `imageUrl`, `imageAlt`, `ctaText`, and `ctaHref` (plus a few optional fields). Every prop is defined by a Zod schema, so the system knows exactly what values are valid.

```
PageDoc
├── slug: "/about"
├── title: "About Us"
└── blocks:
    ├── BlockInstance { type: "Hero", props: { heading: "About Us", ... } }
    ├── BlockInstance { type: "FeatureGrid", props: { items: [...] } }
    └── BlockInstance { type: "CTA", props: { label: "Get Started", ... } }
```

## Operations

An **operation** is a structured, schema-validated edit action. When a user says *"change the hero heading to Welcome"*, the AI doesn't modify HTML — it generates an operation like:

```json theme={null}
{
  "op": "update_props",
  "pageSlug": "/about",
  "blockId": "hero-1",
  "patch": { "heading": "Welcome" }
}
```

Operations are the unit of change in Avocado Studio. They can be:

| Operation            | What it does                                         |
| -------------------- | ---------------------------------------------------- |
| `add_block`          | Insert a new block at a specific position            |
| `update_props`       | Change one or more props on an existing block        |
| `remove_block`       | Delete a block from the page                         |
| `move_block`         | Reorder a block within the page                      |
| `duplicate_block`    | Copy a block within or across pages                  |
| `add_item`           | Add an item to a list field (e.g. a new testimonial) |
| `update_item`        | Update a list item by index                          |
| `remove_item`        | Delete a list item by index                          |
| `move_item`          | Reorder a list item                                  |
| `create_page`        | Create a new page                                    |
| `duplicate_page`     | Copy an existing page                                |
| `rename_page`        | Change a page's slug and/or title                    |
| `remove_page`        | Delete a page                                        |
| `move_page`          | Reorder a page in the site nav                       |
| `update_page_meta`   | Update SEO meta fields (title, description, ogImage) |
| `update_site_config` | Update global site settings (name, logo, nav)        |

Every operation is validated against the block's Zod schema before it's applied. If the AI generates an invalid edit (e.g., setting a `heading` to a number), it's rejected automatically.

## Plans and Approval

When a user sends a chat message, the AI generates an **edit plan** — a list of one or more operations. The plan is presented to the user for review before it's applied.

```
User: "Add a testimonials section below the hero with 3 customer quotes"

→ Edit Plan:
  1. add_block { type: "Testimonials", position: after "hero-1", props: { items: [...] } }

→ User approves → Operations applied → Live preview updates
```

Plans can be **approved**, **rejected**, or **modified**. The user always has the final say.

## Draft Mode

**Draft mode** is how the Content Studio shows unpublished changes on your live site. When the Content Studio is active, the site switches into draft mode — it fetches the latest draft content from the orchestrator instead of the published content.

* **Published content** — What your visitors see. Stored in your CMS, database, or static files.
* **Draft content** — What you see in the Content Studio. Stored in the orchestrator's session state. Not visible to site visitors.
* **Publishing** — Promoting draft content to published. Triggered by the user after reviewing changes.

Draft mode uses Next.js cookies under the hood. The Content Studio iframe sets the cookie automatically — your site just needs to check for it and fetch from the orchestrator when present.

## The Three Services

Avocado Studio runs as three services that communicate via HTTP and postMessage:

| Service            | Role                                                                                               | Tech         |
| ------------------ | -------------------------------------------------------------------------------------------------- | ------------ |
| **Orchestrator**   | The brain. Handles AI planning, operation validation, session state, undo/redo, and publishing.    | Fastify API  |
| **Content Studio** | The UI. Chat interface, model picker, plan review, and settings. Embeds the site in an iframe.     | Vite + React |
| **Site**           | Your website. Renders pages from block data. In draft mode, fetches content from the orchestrator. | Next.js      |

The Content Studio embeds your site in an iframe. When the user clicks a block, the site sends a `postMessage` to the Content Studio identifying which block was selected. When an operation is applied, the orchestrator notifies the site to re-fetch and re-render.

## Block Manifest

When the Content Studio connects to your site, it fetches the **block manifest** from `/api/editor/blocks`. This tells the Content Studio what block types are available and what props each one accepts.

```json theme={null}
{
  "version": 1,
  "blocks": [
    {
      "type": "Hero",
      "displayName": "Hero",
      "editablePaths": ["heading", "subheading", "imageUrl", "ctaText", "ctaHref"],
      "propsSchema": {
        "type": "object",
        "properties": {
          "heading":    { "type": "string" },
          "subheading": { "type": "string" },
          "imageUrl":   { "type": "string" },
          "ctaText":    { "type": "string" },
          "ctaHref":    { "type": "string" }
        },
        "required": ["heading", "ctaText", "ctaHref"]
      },
      "defaultProps": {
        "heading": "Welcome",
        "ctaText": "Get started",
        "ctaHref": "/contact"
      }
    }
  ]
}
```

The AI planner uses the manifest to understand what blocks exist and what edits are possible. This is why every block needs a complete schema — it's not just for validation, it's the AI's instruction manual.

## Multi-Model AI

The orchestrator supports three AI providers:

* **Anthropic** — Claude Haiku (fast), Sonnet (balanced), Opus (complex reasoning). Most battle-tested.
* **OpenAI** — GPT-4o-mini (fast), GPT-4o (balanced), o1/o3 (reasoning).
* **Google Gemini** — Gemini Flash (fast), Gemini Pro (reasoning).

Users select the provider and model tier in the Content Studio's settings panel. The orchestrator routes the request to the appropriate provider. You can also override model names via environment variables for each tier.