How It Works

Documentation Index

Fetch the complete documentation index at: https://avocadostudioai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​

The Editing Pipeline

​

Step 1: Intent Detection

• Structural edit — Add, remove, move, or update blocks
• Page operation — Create, duplicate, or delete a page
• Clarification needed — The request is ambiguous (“make it better” → which block?)
• Off-topic — Not a content editing request

​

Step 2: AI Planning

• System prompt — Instructions for generating structured edit operations
• Block schemas — Zod schemas for all available block types, so the AI knows what fields exist and what values are valid
• Current page state — The full PageDoc with all existing blocks
• User message — The natural language request
• Conversation history — Previous messages for context

​

Step 3: Validation

• Are the props valid for this block type?
• Does the target block exist (for updates/removes)?
• Is the position valid (for adds/moves)?

​

Step 4: Apply Operations

1. Updates the in-memory draft PageDoc
2. Records itself in the undo/redo history
3. Bumps the preview version number

​

Step 5: Stream to Content Studio

event: op_candidate    → An operation parsed from the LLM's streaming response
event: plan_meta       → Plan metadata (status, intent, opCount)
event: op_applied      → Each operation successfully applied (progressive UI updates)
event: image_progress  → Image resolution updates (when image lookup is deferred)
event: final           → Final result, including summary_for_user and change log

​

Step 6: Live Preview Update

1. Orchestrator notifies via draft version bump
2. Site re-fetches draft pages from orchestrator
3. React re-renders only the changed blocks
4. Site sends postMessage to Content Studio confirming the update

​

Step 7: User Review

• Approve — Keep the changes in the draft
• Undo — Roll back the last operation (or the entire plan)
• Continue editing — Send another message to refine the changes
• Publish — Push the draft to production

​

Streaming & Progressive Updates

​

Undo / Redo

​

Publishing

​

The PublishTarget Interface

interface PublishTarget {
  readonly name: string
  canHandle?(ctx: PublishContext): boolean
  publish(ctx: PublishContext): Promise<PublishOutcome>
}

• name — Stable identifier used by the registry and the PUBLISH_TARGET env var.
• canHandle() — Optional selection hint. The registry iterates targets on each POST /publish and picks the first whose canHandle(ctx) returns true.
• publish() — Receives the full PublishContext (session, scopedSession, pages, siteConfig, siteOrigin, generatedImageDir, logger) and returns a PublishOutcome (ok, httpStatus, tracker, response body).

​

Built-in Targets

1. Serializes all draft pages to apps/site/lib/published-content.json
2. Copies any generated images to apps/site/public/generated-images/
3. Rewrites localhost image URLs to relative paths
4. Commits and pushes to the configured branch (PUBLISH_GIT_BRANCH, defaults to main)
5. If a Vercel deploy hook is configured, the push triggers a rebuild automatically

1. Calls VERCEL_DEPLOY_HOOK_URL to trigger a Vercel rebuild
2. Tracks deployment status by polling the Vercel API (VERCEL_TOKEN)
3. Reports back to the Content Studio: triggered → building → ready (or failed)

​

Environment Variables

​

Implementing a Custom Publish Target

import type { PublishTarget, PublishContext, PublishOutcome } from "./publish/publish-target.js"
import { registerPublishTarget } from "./publish/publish-target-registry.js"

class S3PublishTarget implements PublishTarget {
  readonly name = "s3"

  canHandle(ctx: PublishContext): boolean {
    // Claim publishes routed at a specific siteId, for example.
    return ctx.siteId === "my-s3-site"
  }

  async publish(ctx: PublishContext): Promise<PublishOutcome> {
    const { session, pages, slugs, logger } = ctx
    // Example: upload to S3
    const res = await fetch("https://my-bucket.s3.amazonaws.com/publish", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ pages })
    })

    const now = new Date().toISOString()
    return {
      ok: res.ok,
      httpStatus: res.ok ? 200 : 400,
      tracker: {
        session,
        status: res.ok ? "triggered" : "failed",
        startedAt: now,
        updatedAt: now,
        slugs,
        vercelState: res.ok ? "READY" : "ERROR"
      },
      response: {
        status: res.ok ? "ready" : "failed",
        session,
        slugs,
        message: res.ok ? "Published to S3" : `S3 returned ${res.status}`
      }
    }
  }
}

registerPublishTarget(new S3PublishTarget())

​

CMS Publishing (via Site SDK)

1. Resolve image URLs (rewrite localhost references, upload to CMS)
2. SSRF validation on external image URLs
3. Deduplicate image uploads within a single publish
4. Push page content to the CMS API