getPages() reads it out, onPublish() writes it back. A JSON file is
almost nothing; a CMS that localises per field is the real work.
CMS adapters
Block — one typed section of a page. On a site built from scratch it is one
of the twenty built-in types; on a site that already exists it is your own
component, registered with a schema. Block system
Block manifest — the JSON the site serves at GET /api/editor/blocks,
telling the editor and the planner what blocks exist and what fields they have.
When it is missing or broken the editor shows a Limited badge.
Coverage — two numbers that grade an integration. editableCoverage asks how
many of the declared fields a rendered page actually marks; panelCoverage asks
whether the property panel is intelligible. The number is what says the
integration is done. Coverage checks
Draft — your unpublished work. Held on the server, per site, surviving
reloads and restarts. The live site keeps serving the published version until
somebody publishes. Pages and drafts
Draft mode — the Next.js cookie-based mechanism that makes a page render the
draft instead of the published content. Entered through
/api/editor/draft?secret=…, which is why the site and the editor must share
DRAFT_MODE_SECRET.
Editor — the chat UI. A React app that talks to the orchestrator and frames
your real site in a live preview.
Editorial brief — a site’s standing instructions for generated copy:
overview, tone, constraints, and named page templates.
The editorial brief
Field table — one declaration per block that derives four things at once: the
Zod schema, the property-panel metadata, the projection out of your CMS and the
merge back into it. The alternative is four declarations that drift apart.
Field table
Library mode — running the orchestrator inside your Next.js app as a route,
rather than as a separate service. The shape most integrations use, and the one
npm create avocado-site produces. Gated by default in production.
Manifest — see block manifest.
Marker — the data- attributes your renderer emits so a click on the
rendered page resolves back to a block and a field. Written for you by
editableProps and editableScopeProps. A field with no marker still renders,
still appears in the panel, and cannot be clicked on the page.
Inline editing
Operation (op) — one schema-validated content change. There are 19 of
them — update_props, add_block, reorder_items, update_page_meta and so
on — and none of them can change a file. Everything the chat and the visual
editor do is expressed in this vocabulary. Core concepts
Orchestrator — the backend. Session state, AI planning, the operations
engine, publishing. Runs either as a standalone service or inside your app.
PageDoc — what a page is to Avocado: an id, a slug, a title, metadata, and
an ordered list of BlockInstances.
Plan — the set of operations the planner produced for one request. Ordinary
plans apply as they stream; destructive ones are held for Apply changes or
Discard.
Planner — the part of the orchestrator that turns a sentence into a plan.
With no API key configured a small deterministic planner answers a short list of
literal phrases instead.
Property panel — the second tab beside Chat. Lists the selected block’s real
fields and writes real values, with no model involved.
Puck mode — the optional drag-and-drop visual editor, built on
Puck, producing the same blocks through the same
pipeline. Puck mode
Session — the scope a draft belongs to. Usually dev locally; the editor and
the site have to agree on it, along with the site id.
Site — a set of pages plus the configuration that describes them: name, logo,
navigation, theme, hosting target, media source, editorial brief.
Site health — rules that read your published pages and report what is wrong —
missing metadata, broken links, images with no alt text.
Site health
Site id — the string identifying a site to the orchestrator. It must be the
same in the page route, the orchestrator mount and the editor URL; when it is
not, the demo still appears to work, which is what makes the mismatch expensive.
SPI — Service Provider Interface. The REST contract for integrating a
framework the SDK has no adapter for. Other frameworks
Standalone — running the orchestrator as its own service, typically in
Docker, rather than inside your app. Needed by the built-in onboarding agent.
Variant — several alternative versions of a block generated at once, to pick
between. Variants
Version history — the ordered record of every change, with revert, selective
discard, and published snapshots.
Review and undo