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

# Manual Integration

> Add a site to Avocado Studio by hand — no AI, full control. Same end state as the Onboarding agent, every line of code is yours.

This page is the human path. You'll wire your site into Avocado Studio yourself by following our existing integration guides in order. There's no automation involved — you read, you copy, you adapt.

**End state**: a site registered with the orchestrator, your existing pages serving from your existing routes, the editor able to apply AI-generated edits via Draft Mode.

**Time**: \~30 minutes for a vanilla Next.js 15 project. Add 30–60 minutes per non-trivial customization (custom block types, non-default content store, custom auth).

## Prerequisites

* Node 20+ and pnpm
* A Next.js 15 project (App Router) — or any framework where you're willing to wire up the editor API contract by hand using the SDK's `/core` primitives ([Non-Next.js Integration](/integration/non-nextjs))
* The Avocado orchestrator running locally or remotely (`pnpm dev:orchestrator`)
* One of: `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`

## Steps

<Steps>
  <Step title="Read the concepts">
    Start with **[Core concepts](/concepts)** so the rest of the docs make sense. Pages, blocks, operations, draft mode — five minutes, save yourself an hour later.
  </Step>

  <Step title="Run the editor quickstart">
    Follow **[Content Studio Quickstart](/integration/editor-quickstart)** to get the editor talking to your local orchestrator. Confirm you can open the editor at `http://localhost:4100` and see a session.
  </Step>

  <Step title="Wire the SDK into your Next.js site">
    Follow **[Next.js Integration](/integration/nextjs-integration)**. This is the meat — two SDK helpers do almost all the work: `createEditorApiHandler` mounts the `/api/editor/*` catch-all (blocks, pages, draft, draft/disable, publish) and `createSitePage` provides a drop-in `app/[[...slug]]/page.tsx` with draft mode, navigation, and the editor overlay already wired up.

    At the end of this step you should be able to load your site inside the editor's iframe and see Draft Mode toggle.
  </Step>

  <Step title="Register your blocks">
    If you're using the built-in block library, you're done — skip this step. If you have custom React components you want the editor to manage, follow **[Custom Blocks](/integration/custom-blocks)** to register them with the SDK so the AI knows about their props and the editor can render them.
  </Step>

  <Step title="(Optional) Enable Puck mode">
    For visual drag-and-drop editing, follow **[Puck mode](/integration/puck-mode)**. This is opt-in per site.
  </Step>

  <Step title="Register the site with the orchestrator">
    From your project directory, run:

    ```bash theme={null}
    npx avocado-register --name "My Site"
    ```

    This bin script (shipped with `@ai-site-editor/site-sdk`) generates a `DRAFT_MODE_SECRET` if one isn't already set, fills in the rest of the env vars, and POSTs the site config to the orchestrator's `/sites/register` endpoint. After it succeeds, the site appears in the editor's dashboard automatically.

    See `npx avocado-register --help` for all available flags (`--id`, `--port`, `--orchestrator`, `--secret`, `--session`, `--purpose`, `--preview-url`).
  </Step>

  <Step title="Verify it works">
    From the editor's chat panel, send a simple edit like *"change the hero headline to 'Hello world'"*. You should see the AI generate an operation, the preview update, and an undo entry appear in the history. If anything's broken, see [Chat troubleshooting](/observability/chat-troubleshooting).
  </Step>
</Steps>

## What you skipped vs the agent path

The Onboarding agent does a few extras that the manual path doesn't:

| Step                                              | Agent does it                             | Manual                                                              |
| ------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
| Register the site with the orchestrator           | Yes (`register_site` MCP tool, automatic) | Run `npx avocado-register --name "..."` from your project directory |
| Bootstrap initial pages from a URL or description | Yes                                       | You start with whatever pages your project already has              |
| Extract and apply a theme automatically           | Yes                                       | You configure your own theme tokens                                 |
| Download remote images into your project          | Yes                                       | Bring your own assets                                               |

If any of those would save you meaningful time, consider running the Onboarding agent for the first 80% and finishing the remaining 20% by hand — the two paths are compatible.

## When to escape to AI

You should drop into the **[Onboarding agent](/sites/site-agent)** or hand off to your **[own coding agent](/sites/coding-agent)** if:

* The integration takes longer than an hour and you're stuck
* Your project has unusual conventions and the docs assume vanilla Next.js
* You're migrating content from a CMS or live URL and don't want to hand-author 50 pages

There's no penalty for switching paths halfway — the orchestrator only sees the final result.