` a crawler sees, and the scaffold's 404 page exports metadata — a correct 404 previously still had no title. * **`scripts/scaffold-serve-check.mjs`, in `pnpm test:build`.** The only thing in the repo that built a real app and read the HTML built an example in `mode: "static"`. The scaffolder emits `mode: "auto"` — a different branch of `createSitePage`, and the one every new user runs. The new check generates the scaffold from its own templates, overlays the working tree, then builds and serves it in **both** modes and asserts on the bytes: metadata and a real 404 in development, and in production the closed gate naming itself. * **A gate that fires the editor's own chips at the planner that answers them.** The chip builder lives in the editor and the keyless planner lives in the orchestrator; nothing connected them, so nothing noticed when they drifted apart — and they had. ## 0.9.0 There was no way to see Avocado without cloning it. ### New: `npm create avocado-site` ```bash theme={null} npm create avocado-site@latest my-site cd my-site && npm run dev ``` One command starts the site and the editor beside it, on a nine-page demo — the Avocado Hub — with every renderer in the library on screen at once. **No API key is needed to look around.** Rendering, click-to-select, the property panel, undo and publish all work without one; chat is the single thing that does not, and it says so rather than failing. The orchestrator runs inside the scaffolded Next.js app at `/api/avocado`, in library mode. There is no third service and nothing to deploy separately. <Note> The package existed before under a name it could never have been invoked by: `npm create` requires a `create-*` package name, and it was published under none. So this is the first release in which the repository's own front door actually works. </Note> ### New: `siteName` and `demoContent` on `createOrchestrator` The editor asks the orchestrator what it is mounted on. It used to guess. `siteName` is what the editor greets you with; without it the site id gets title-cased, so a mount called `my-shop` is introduced as "My Shop". Reasonable for an id that is a name, wrong for one that is a directory. `demoContent: true` says this mount serves Avocado's shipped demo pages, and turns on the first-run suggestions written against them. Those suggestions — and the demo greeting, and the site's own name — were previously keyed on a hardcoded list of four site ids, all of which live in the Avocado repository. Any site anyone else stood up was excluded by construction from the onboarding written for it. Both are reported on `/status/planner`. Neither is required. ### Fixed: a keyless editor that looked broken rather than keyless With no provider key, chat falls back to a rule-based planner that handles a slice of literal edits. Everything outside that slice used to come back as "I need one clarification: what section should I change and what exactly should be updated?" — which reads as a planner that cannot understand plain English, not as one that was never given a key. It now says which variable to set and where. The header badge says so too. ### Fixed: "review this page" never reached a model Two detectors claimed the message and the deterministic one was tested first, so a judgement question was answered from a template in twelve milliseconds. The template was written against every block type registered in the process — which, because importing anything from `@avocadostudio-ai/shared` registers the built-ins transitively, is Avocado's own type names and not yours. A site rendering its own fourteen types was told it was missing Hero, CTA and FAQ, and advised to add three blocks it has no renderer for. `add_block` for one of those applies cleanly, reports success and draws nothing. Judgement questions route to the model now, with the page's real props in context. What survives from the template is `pageObservations`: facts that were looked up rather than inferred — a declared image field with nothing in it, a page nothing links out of, a missing meta description. The same leak is fixed in two more places: the block catalogue answer no longer suggests adding types your site cannot draw, and neither does the planner's specify-a-type clarification. ### Also in 0.9.0 * The overlay's missing-editable-targets warning is withdrawn. Every block wrapped and no field marked is not a fault, and reporting it through `console.error` painted a red Console Error over a working integration. `site-sdk/coverage` still measures it for anyone who asks. * The editor's unreachable-orchestrator screen retries on its own, backing off to fifteen seconds. An orchestrator is unreachable for a few seconds on every restart, and the screen could previously only be left by clicking *Try again* at the right moment. * The model dropdown offers Claude only. The planner's prompts, its structured-output path and the eval set are all tuned against it. UI only — the orchestrator still advertises and accepts all three providers. * Inline editing is its own documented step rather than step 2 of the Next.js integration, where it was deferred and forgotten. * The demo content is one coherent nine-page site rather than six narrower authored pages, with the dead CTA, the nav entry pointing at `/be-shorter-unsplash` and the alt attributes holding image-generation prompts all fixed at the source. ## 0.8.0 A tenth package, and a field kind for the markup most templates actually store. ### New: `@avocadostudio-ai/astro` Avocado now integrates with Astro. Your `.astro` components keep doing the rendering — no React, no islands, nothing ported. Avocado supplies the schema, the draft props, the editable markers and publishing. ```bash theme={null} npm install @avocadostudio-ai/astro @avocadostudio-ai/site-sdk @avocadostudio-ai/shared ``` ```ts astro.config.ts theme={null} integrations: [ avocado({ siteId: 'my-site', content: './src/avocado/content.ts', editablePages: ['src/pages/index.astro'], }), ] ``` That is the wiring. See the [Astro integration guide](/integration/astro-integration) for the content module, why `editablePages` is a list, and what a build does with all of it (nothing — the output stays as static as it was). <Note> Astro support shipped from one pilot integration. It renders, edits, previews and publishes; what it has not yet had is a second site. Expect gaps around anything the pilot did not exercise. </Note> ### New: `kind: 'html'` for fields whose stored value is markup A component that takes a prop either as a value or as a slot renders it with `set:html` — or `dangerouslySetInnerHTML`, or `v-html` — and what is stored is a string of markup. The closest kind that existed was `richtext`, which means a *document*, so the property panel rendered the markup literally: ``` Free template for <span class="hidden xl:inline">creating websites with</span> … ``` Nobody can edit that without breaking it, and editing it anyway writes the broken version back to your source. `html` stores the string your template renders, edits it as a document, and converts both ways — preserving the elements and attributes it cannot model rather than dropping them. ```ts theme={null} const HEADLINE = { title: { kind: 'html', label: 'Title' }, } ``` See [when the stored value is HTML](/integration/field-table#when-the-stored-value-is-html). ### New: `stringList` and `imageList` field kinds Both were declarable and neither was drawn — a declared, schema-valid field reached the property panel as nothing at all. They now have controls: rows of inputs for a string array, and the image widget per row for an image array, so the asset picker and alt text behave the same whether an image is on its own or one of twelve. <Warning> **What you have to change.** `registerFieldTable` now **refuses a kind it does not know** instead of silently emitting `text`. If your field table has a typo in a `kind`, registration throws and names it. That is the failure this release converts from invisible into loud — the field had been reaching the panel as nothing. </Warning> ### New: the editor API and page render without Next.js Three things `createSitePage` used to decide and throw away are now values any host can consume: `resolvePageRender` (`page` / `not-found` / `draft-unavailable`), `decideEditorRewrite`, and `renderPageMetadata`. `createEditorApiHandlerCore` and `site-sdk/routes/core` are the editor API with no framework in them, and `preview-adapter/bridge-controller` is the live-preview protocol with no React — which is why **React is no longer a mandatory peer** of `preview-adapter`. Nothing about the Next.js path changes. These are the seams every non-Next host was reimplementing from the source. ### Fixed: a list the property panel could not draw A field table declaring `{ kind: 'list' }` emitted a schema saying only "array of objects", so the panel showed neither rows nor an Add control — and 0.7.0's check that a new row must name its type was inert for the same reason. The metadata was correct all along; the panel re-derives from the manifest's JSON schema, and a key the schema does not expose is discarded rather than refined. ### Fixed: the editor could push one site's pages under another site's id The editor bootstrapped its draft before the site registry answered, so for every site but the build-time default, the first push carried the *default* site's pages — which then stayed, counted in the Publish badge, one click from being written to your repository. The editor now waits for the registry, and `/draft/bootstrap` refuses a push whose stated origin contradicts the site's registered `previewUrl`. <Warning> **What you have to change.** Nothing, unless you drive `/draft/bootstrap` yourself. Only a *contradiction* is refused: a caller that sends no origin, and a site registered without a `previewUrl`, are both unaffected. </Warning> ### Fixed: a publish diff describing a different site When a site's `/api/editor/pages` did not mention a `siteConfig` — an Astro site answers `{pages}` and nothing else — the bundled demo's header config was used to fill the gap, so the publish diff reported the demo's name, logo and navigation as your "before". Absent now means "no header change", which is what it meant. ### Also in 0.8.0 * `site-sdk/draft/core` no longer throws at module load where Next.js is not installed. It imported one four-line helper from the module beside it, whose first line is `import { draftMode, cookies } from "next/headers"`. * `site-sdk` and the CLI no longer ship compiled test modules in their tarballs. * The demo content the editor seeds in demo mode is one coherent site again, rather than sediment from old chat sessions. * Package manifests no longer link to a repository that answers 404. There is no public repository, so npm renders no *Repository* link at all; `bugs` points here. ## 0.7.0 ### Breaking: `add_item` requires a list row's discriminator A polymorphic list declares which prop names a row's type and which types it admits. `add_item` used to accept a row that left that prop out. It now rejects it, naming the admissible types. <Warning> **What you have to change.** If you call `POST /ops` with `add_item` by hand — from a test, a script or an agent — check that every new row for a polymorphic list sets its discriminator prop. A row that omits it used to be created and then fail downstream, or write a typeless row into your CMS. Only *omission* is rejected. A value that names no declared branch is still accepted, because your manifest may enumerate fewer types than your CMS has. Chat-driven edits are unaffected — the planner always sets it. </Warning> ### New: field-table lenses for CMS-backed sites Four things have to agree about every block on a CMS-backed site: the Zod schema an AI edit is validated against, the metadata the property panel draws with, the projection that turns a CMS document into props, and the merge that writes edited props back. Written separately, they disagree within a week. `@avocadostudio-ai/site-sdk/lens` derives all four from one table: ```ts theme={null} registerFieldTable(TABLE, { primitives }) // schema + panel metadata const lens = createLens({ table, locale, primitives }) // projection + merge ``` Packs ship for Storyblok (`site-sdk/lens/storyblok`) and Sanity (`site-sdk/lens/sanity`). Another CMS answers six questions and inherits the rest. `roundTrip` is part of the API: run a projection through its own inverse over your real content, and anything that moves is a codec that is not its own inverse for some value in *your* documents — invisible in the editor, and visible later as a publish wanting to rewrite pages nobody opened. See the [field table guide](/integration/field-table) for the shape, the wiring and the two write rules. <Warning> **One sharp edge.** `localized: false` means **the bare key**, not the default language's path. Those coincide on a CMS that localises into a suffixed sibling and diverge on one that localises into an object under the key. There is deliberately no implicit fallback — a read that fell back would pair with a write that did not, which is how a lens corrupts a document. </Warning> ### New: keep third-party scripts out of the preview `isEditorRender()` tells a layout whether it is rendering inside the editor's preview iframe. A layout receives no `searchParams`, so consent banners, analytics and chat widgets could not be gated the way a page can — they loaded inside the preview and sat on top of the content being edited. The preview rewrite now stamps a header a layout can read. ### Fixed: the optional peer dependency from 0.6.0, completed 0.6.0 declared `@anthropic-ai/claude-agent-sdk` as an optional peer of `orchestrator-core` — twice, in two blocks of the same manifest, and JSON parsing keeps the last one. The 245 MB really did leave library-mode installs, but a consumer of `orchestrator-core/agent/*` got a bare `MODULE_NOT_FOUND` instead of a package manager naming what to install. Fixed in 0.7.0. ### Also in 0.7.0 * `editableScopeProps({ display: "contents" })`, for a list whose rows map straight into a flex column and have no ancestor to hang an editable scope on. Off by default — a row already inside an `<li>` should carry the scope there. <Note> The bundled editor did not change in this release, so the CLI's editor bytes are 0.6.0's. The package moves to 0.7.0 with the rest for the lockstep reason above. </Note> ## 0.6.0 ### Breaking: the Claude Agent SDK is an optional peer, not a dependency `@anthropic-ai/claude-agent-sdk` used to be a dependency of `orchestrator-core`, which library mode puts into your public site's dependency tree. The SDK is 4 MB; its platform package is a 245 MB binary — larger than every other dependency put together. <Warning> **What you have to change.** Nothing, if you mount `createOrchestrator` and nothing else — that path never imports it, and your install gets smaller. If you import `@avocadostudio-ai/orchestrator-core/agent/sites-agent-tools` or `.../migration/migration-tools`, install `@anthropic-ai/claude-agent-sdk` alongside Avocado yourself. The standalone orchestrator declares it directly and is unaffected. </Warning> The rest of that finding was "state the number, so nobody discovers it at deploy time". The library-mode install footprint, per dependency rather than as one total, because two of the five are native and the figure differs by platform: | Dependency | Size | What it buys | | - | - | - | | `better-sqlite3` | \~27 MB | draft state, history, version log | | `sharp` + libvips | \~16 MB | image resizing | | `@anthropic-ai/sdk` | \~10 MB | planning | | `openai` | \~7 MB | planning | | MCP SDK | \~6 MB | the MCP surface | Roughly 66 MB on darwin-arm64. If the footprint decides it for you, the standalone orchestrator is the other shape. ### Breaking: internal props now appear in the field manifest `resolveManifestFieldMeta` used to omit `_`-prefixed props. It now emits them as fields carrying `internal: true`. <Warning> **What you have to change.** If you iterate `meta.fields` to build your own UI, skip entries where `internal === true`. Everything Avocado ships already does. If you use the built-in property panel, there is nothing to do. </Warning> ### New: `kind: "reference"` for CMS references A CMS stores an internal link as an object — a Storyblok story link, a Contentful entry link, a Sanity reference — and renders it to a different href per language. Declaring such a prop as `kind: "link"` flattens the object to an href, and two things go wrong. The publish diff reports the reference as changed on every page forever, because the rendered href never equals the stored object. And writing the href back replaces the pointer with a hardcoded URL: the page renders identically, and the link silently stops following renames, which is the one thing the reference was for. `kind: "reference"` is deliberately opaque. The panel shows where it points and offers no control. The planner is not told the prop exists, and an `update_props` naming one is dropped with a note saying the change belongs in the CMS. A new list row gets `null` rather than placeholder text. Use `referenceLabelKey` to name a readable key so the panel shows something better than an id. There is no reference picker. Re-pointing a reference needs your CMS's own document ids, which only your integration has. ### New: Storyblok rich text `fromStoryblok` and `toStoryblok` join the converters in `@avocadostudio-ai/richtext`, which now covers four CMSes: Storyblok, Contentful, Sanity Portable Text and Strapi. Without a converter, the cheap thing to do with a rich-text field is flatten it to a string, and you lose every mark, link and list on the first publish with nothing logging it. ### New: `context.baseline` replaces `context.published` The publish diff's baseline was always your CMS's *draft* content, not the live site. The name said otherwise, and integrators either designed around a problem that did not exist or took a second read of the published perspective and created one. <Note> **What you should change.** Read `context.baseline` in your publish handler. `context.published` still holds the same array and still works — it is deprecated, not removed. `undefined` means "no baseline available" and never "the site was empty"; publishing every field on that assumption is the overwrite a baseline exists to prevent. </Note> ### Fixed in 0.6.0 * **Every successful library-mode publish was reported as a failure.** The response carried no `status` field, and the editor reads exactly that field before its error branch. A CMS publish that had already written every document told the person who pressed the button "Failed to trigger publish.", over HTTP 200\. * **Avocado's own block migrations ran against sites that had re-registered a built-in name.** Registering your own `Hero` — which the CMS adapter docs tell you to do — used to invite Avocado's migrations to invent props on it: a placeholder image URL, an English alt string on a German page, a `variant` overwritten with `"default"`. None of it showed in the preview, because your renderer ignores props it does not use. It showed at publish, on pages nobody opened. Whoever registers a name last now owns it. * **Generated list-row ids leaked into publish diffs.** Avocado stamps a stable `id` on every declared list row so the panel can reorder and the planner can address a row by name. It lives in `props`, so an adapter comparing its draft against freshly read CMS content saw every block with a list as changed, from the first load and forever — a one-field edit could produce a publish that wanted to rewrite every document with a list on it. `withoutGeneratedItemIds`, from `site-sdk/publish`, is the inverse. It strips only the ids Avocado generated, so a row carrying your CMS's own key keeps it. * **`trailingSlashRedirect` and `editorPreviewRewrite`** are exported from both `site-sdk/proxy` and `site-sdk/middleware`. The hand-written trailing-slash redirect, built from `request.nextUrl.clone()` as every Next example invites, strips the slash it just added and sends every page into an infinite redirect — visible only in a browser, since `curl` without `-L` sees one ordinary 308. * **A bare `data-editable-target` on a list row resolved against the enclosing block,** so an edit to a headline inside a column patched a prop the section does not have. Silent and wrong, rather than silent and absent. * **`panelCoverage` no longer reports a CMS's own `_uid` as an orphan prop** — on a CMS that stamps one, that was a finding per block per page, burying every real one. * **`notes?: string[]` on `CmsPublishResult`,** so a dry run, a queue or a review-before-write publisher can say what it did. It had one channel before, `unsupported`, which renders as failure. * **Two more multilingual traps documented.** A container is not localised — the fields inside it are. And on a CMS that localises per field, the component schema decides in both directions, so a document can keep a translated value your site has not rendered in years. See [multilingual](/integration/multilingual), rules 3 and 4. ## 0.5.1 Three defects found by integrating a real site. No breaking changes. * Alt text outranks the image filename as a list-row label, and a list field inside a list row is no longer reported as unmarked. Both were coverage findings a site could only clear by renaming its image files or by marking an element that draws nothing. * A relative image URL is resolved against the site's own origin before it goes to a vision model, and a URL source is only ever https. Library-mode image selection used to fail the whole chat turn with the provider's own 400. * `registerBlock` no longer warns that a correct polymorphic list is unbacked, and a row whose only content is rich text is labelled by its first text node rather than `Item N` or `[object Object]`. ## 0.5.0 Minor rather than patch: this adds entry points and changes behaviour an existing integration can observe. ### New entry points The install line every guide shipped could not satisfy the imports those same guides required — `@avocadostudio-ai/shared` is a dependency of the SDK, not of your site, so under pnpm the documented import did not resolve at all. | Subpath | What it gives you | | - | - | | `site-sdk/blocks` | `registerBlock`, `z`, the block-meta types, the name helpers | | `site-sdk/markers` | the preview attribute helpers, with no React behind them | | `site-sdk/coverage` | `editableCoverage` and `panelCoverage` | <Note> **What you should change.** Import from `@avocadostudio-ai/site-sdk/*` rather than from `@avocadostudio-ai/shared` or `@avocadostudio-ai/preview-adapter`. Installing the SDK alone is then enough, which is what every guide told you. `site-sdk/markers` also matters for bundle size: the marker helpers used to ship from the same entry as the editor overlay, which added 66 kB of First Load JS to every public page that marked up a shared component. </Note> ### New: `panelCoverage` `editableCoverage` asks whether the rendered page offers each declared field. Nothing asked whether the **property panel** is intelligible — so a site could compile cleanly, serve a valid manifest, pass every marker check, and still hand a person a panel they cannot use. `panelCoverage` resolves metadata and rows through the same functions the panel itself uses, and compares them against your real content. No browser, no screenshot, no model call. Seven findings, ordered so the cause is read before its symptoms: `colliding_type`, `incomplete_polymorphism`, `unmatched_branch`, `unlabelled_row`, `orphan_prop`, `filename_row_label`, `phantom_field`. Three surfaces, because an adopter and an agent need different things: `site-sdk/coverage` for your own check script, `avocado-check-editing-surface` over MCP for an agent to call before reporting an integration done, and a formatted report for a human. See [coverage checks](/integration/coverage). `FieldMeta` also gained `panelOnly`, which takes fields nothing can draw out of the coverage denominator — so 100% is reachable and anything less is actionable. ### Behaviour an existing integration will notice * **The property panel now prefers your field metadata over Avocado's built-in registry** on a colliding type name. If you register your own `Hero`, you were being shown Avocado's labels for it — one integration collides on seven of its eight types and read `Left column items` where it had declared `Left column`. A field your manifest declares explicitly now wins; a field it only derives from its JSON schema still takes the registry's richer entry. The merge also stopped silently dropping `discriminator` and `itemFieldsByType`, which meant polymorphic lists were measured against the union of all branches and rows fell back to `Item 4`, `Item 5`. * **A mounted `createOrchestrator` publishes its own address.** The draft fetch used to default to a standalone orchestrator on `:4200` that a library-mode site does not run — silent when nothing is listening there, and worse when something is, because the preview then renders a foreign process's content and answers 200. * **`withAvocado` writes the framing CSP pair** from the same allowlist the editor API uses, so you no longer hand-write `frame-ancestors` next to your CORS origin. Getting it wrong failed in two unrelated-looking ways: the Sites page reporting your site offline (CORS), and a blank rectangle where the preview should be (CSP). Your own `headers()` come first and win; `framing: false` opts out. * **The legacy `../../.data` database path now requires proof of workspace membership.** It used to ask only whether that file exists — and since the original bug is what created it, one mistaken write re-targeted every project under the same parent directory, forever. One integration's drafts landed in a database already holding twelve sessions from four unrelated projects, while reporting `persistence: { ok: true }` throughout. * **A successful `next build` no longer prints a red error about production auth.** It was describing a request that was not being served, on a machine that was not the deployment. ## Earlier releases 0.4.0 and 0.3.3 are recorded in `CHANGELOG.md` at the root of the repository. Highlights: files as a content type alongside images, `editableCoverage`, publishing a subset of a draft, discarding changes from the version log (0.4.0); and site health checks, a durable store, and `link` as a field kind (0.3.3). ## Upgrading <Steps> <Step title="Move every package at once"> Set all `@avocadostudio-ai/*` dependencies to the same version. A mixed set will resolve, then fail at runtime in ways that point nowhere useful. </Step> <Step title="Read the breaking notes between your version and the target"> Every breaking change on this page carries a "what you have to change" note. Minor bumps are where they live. </Step> <Step title="Re-run your coverage checks"> `editableCoverage` and `panelCoverage` are the fastest way to see whether an upgrade moved something in your integration. See [coverage checks](/integration/coverage). </Step> <Step title="Round-trip your projection, if you have a CMS"> If you use a lens or a hand-written projection, run `roundTrip` over real content before you publish. A codec that is not its own inverse is invisible in the editor and shows up as a publish rewriting pages nobody opened. </Step> </Steps> This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

` never updated in the preview, `Astro.locals.avocado` had no type under `astro/tsconfigs/strict` (which is what `astro create` writes), and a site that named its production editor origin could not be opened from a local one. See the [Astro integration](/integration/astro-integration) page, whose Production section now covers the three settings that are inert in development. A minor bump rather than a patch: an option left the options type and a production deployment answers differently. Both are corrections, and both can change what a deployment does at upgrade time. ## 0.12.1 **A real customer's filename shipped to npm inside a JSDoc comment.** Three built files — `shared/dist/links.js`, its `.d.ts`, and `orchestrator-core/dist/checks/rules-draft.js` — each carried a doc block that used a real customer's PDF filename as a worked example of fuzzy path matching. The example works *because* such a filename is long and easy to mistype, which is why a real one got reached for. The build does not strip comments, so every release from 0.4.0 onward carried it. This is the first version you can install that does not. Comments only — no API, no behaviour, no contract change — so a patch. If you are pinned below this, upgrading is the only way to stop redistributing it. ## 0.12.0 **Prompt caching was off for everyone who never set it.** `ANTHROPIC_PROMPT_CACHE` defaulted to `false`, and for this setting the default was the whole story: only this repository's own `.env` ever named it — not `.env.example`, not either dispatch workflow, not any integrator's environment. Every Anthropic request from the package sends the same large stable system prefix and the same `submit_edit_plan` schema, which is exactly the shape caching exists for, and it billed at full price everywhere the default applied. It is on by default now. **The 5-minute TTL is deliberate and should not be raised.** Replaying 651 real planner calls from telemetry, most sit under a minute apart; only 44 fell in the 5-to-60-minute window that a 1-hour entry would rescue. At 2x to write against 1.25x, buying those back came out **20–32% more expensive** across the set. The reasoning now sits next to the code, so the next reader does not "fix" it upward. **Two package defaults that were also wrong for everyone.** Library-mode planning still named models retired a year ago, now resolved through one `defaultModelLookup()` exported from the public API; and a published package wrote `[create_site]` progress onto whoever's stdout it happened to find. ## 0.11.9 **The announcement bar reads as one.** The Banner's `info` variant was a near-white mint between a white header and a pale hero — three washed-out bands stacked, with the one carrying the announcement reading as the gap between the other two. It is solid brand now, with an inverted CTA. **Follow-up chips no longer ask questions.** "Edit heading", "Edit CTA" and the rest sent a field name with no value, so the only possible reply was "edit it to what?" — zero operations, and real money on a keyed plan. What remains names complete actions. **Setup recommends Anthropic** as the best-tested planner rather than listing three providers as equals, and says that Avocado Studio is a research preview — which the docs now say too. **The demo points at where to onboard your own site**, and points at [Bring your site in](/sites) rather than the Next.js wiring guide, which is the right page only once you have decided. **`avocado-register` stopped sending people after a service they do not need.** It defaults to `http://localhost:4200`, the standalone orchestrator's address, while most integrations mount the orchestrator inside their own Next app — so it failed and told the reader to run `pnpm dev:orchestrator`, a script in Avocado's repo and not in theirs. The failure now names library mode and the exact `--orchestrator` URL to pass, `.env.local` outranks the built-in default so a second run does not fall back to 4200, an unreachable orchestrator reports itself and exits 0 rather than calling a mostly successful run a failure, and `ORCHESTRATOR_URL` is written only once something has answered there. ## 0.11.8 **Setup offers to start the project for you.** It had already chosen ports, generated secrets, installed everything and written your key — then handed back two commands to type. It now asks `Start it now?` and, on yes, runs the dev server for you. Declining prints the commands as before. **The key prompt says what it is and which keys it takes.** On the directory-argument path there was no intro at all, so the first thing a stranger met was an unexplained request for a secret. It now names the product, says that everything except chat works without a key, lists the three accepted variables, and — when you paste one — says *why* it chose the variable it did and how to change it. **The site list no longer shows the same site twice.** A scaffolded project was seeded with a built-in demo preset it had never owned, which since 0.11.5 also rendered under the same name. ## 0.11.7 **Production editing works again.** The editor could not select, edit or inspect anything once a site was built for production — no block markers, no overlay, no messages. The SDK requires the site's `DRAFT_MODE_SECRET` on the preview URL there, and the CLI had no way to send it: no flag, no environment variable, no field. `avocadostudio start` now takes `--draft-secret` (or reads `DRAFT_MODE_SECRET` from the environment), the scaffold forwards it automatically, and the banner warns when it is missing. **The most likely first message works.** `Change the headline to "…"` produced no operations on the keyless planner — "headline" was not among its keywords, and the branch required a block to already be selected. It now finds the page's first heading itself. **The setup asks whether you want to add an API key**, and Enter skips it. Everything except chat works without one; the reason to ask early is that keys are read at startup, so a key added during setup needs no restart. ## 0.11.6 Publish was impossible from the editor, and the cause was a secret baked into the published CLI. **If you installed `@avocadostudio-ai/cli@0.11.4` or `@0.11.5`, rotate your publish token.** Both were built where a developer `.env.local` was present, and Vite inlines every `VITE_*` variable at build time — so both bundles carried a real publish token, the draft-mode secret, and the agent-CLI opt-in switched on. 0.11.3 and earlier are unaffected. A release build now reads no local env files, and a check in the publish step fails if anything is inlined. **Publish works again.** `x-publish-token` was missing from `Access-Control-Allow-Headers`, so the browser refused the preflight and the request never left it — the server logged a successful `OPTIONS` and nothing else, and the editor said only "Failed to trigger publish". The allowed headers are now derived from one list that is checked against the editor's own source. **The publish review shows page metadata.** Title, description and Open Graph image had no representation in the diff, so the panel that exists to say what will change omitted every SEO edit — a page whose only change was its title reported none. **Also:** uploaded attachments no longer render as broken images; production no longer offers chips the planner cannot execute; voice input is hidden where it cannot work; the keyless notice can be reopened after dismissing; and Settings says when no model is available instead of naming one. ## 0.11.5 The paperclip on the first screen of every new project answered `405`. **Chat attachments work in library mode.** `POST /attachment/upload` existed only in the standalone orchestrator, while the editor posts every chat attachment to it unconditionally — so the composer's **Attach file** button shipped enabled on the first keyless screen of every scaffolded project and rendered `Method POST /attachment/upload not handled by createOrchestrator()` in red underneath it. The route is implemented now rather than hidden: the storage and the serving route already existed, only the route was missing. PDFs are accepted and servable. **A missing asset can fail legibly.** The CLI's static server answered any unknown path with `200 text/html`, so a renamed or cache-busted asset came back as the app and the browser threw `SyntaxError: Unexpected token '<'` naming no file. Paths with an extension now `404`; extensionless paths still get the SPA fallback. **The `/ops` envelope is discoverable from its own first error.** It now names the key it wanted and carries a valid minimal example, instead of taking three round trips to reveal the envelope, the discriminator and the shape one at a time. **Nothing to change in your project.** Every change here is additive: a route that did not exist, a `404` where a misleading `200` used to be, and a longer error body on a request that was already failing. ## 0.11.4 The third CORS defect in three releases, and the reason there were three. **The editor was dead to the origin the CLI prints first.** `localhost` and `127.0.0.1` are the same machine and two different origins. The CLI binds `127.0.0.1` and its banner leads with it; every doc and generated `.env.local` says `localhost`. A production site that named one allowed only that one, so a browser at the other had every request answered `200` with no `access-control-allow-origin` and thrown away before any code could see it — while the `frame-ancestors` list, which had expanded both spellings since it was written, allowed the preview frame. The editor painted and was inert, and `curl` reported everything working the whole time. Everything that decides whether a browser may talk to a site now expands both spellings: the SDK's editor routes, every orchestrator route, and the `ORCHESTRATOR_CORS_ORIGINS` check behind `publish/diff`. **Nothing to change in your project.** If you already set `EDITOR_CORS_ORIGINS` or `NEXT_PUBLIC_EDITOR_ORIGIN`, both spellings of what you wrote now work. Only these two loopback names, and only when the origin you configured already uses one — it is not a normaliser and not a wildcard. **The editor showed the wrong site name and the wrong first-screen suggestions.** Two symptoms of one cause: identity that arrives after the screen is drawn, and nothing that redraws it. `GET /sites` now reports the configured `siteName` and `demoContent`; the editor's registry fills a name that is only the id in title case (and still never one you typed); and the welcome message is re-derived when the site's identity changes rather than frozen at first render. A project in `demo-a/` configured as "The Avocado Hub" was called "Demo A" everywhere, and a deployed demo offered three suggestions its own keyless planner cannot execute while the same build in `next dev` did not. ## 0.11.3 A production deployment with an access gate configured could not load the editor's component manifest. The editor stamps its access token on every request whose *origin* matches the orchestrator's — not whose path does. In library mode `/api/avocado/*` and `/api/editor/*` share an origin, so both route groups receive the `x-access-token` header. The orchestrator's preflight listed it; the SDK's editor-route preflight did not. So once a gate was configured and a token minted, the browser refused the preflight for `/api/editor/blocks` and `/api/editor/pages` — the manifest the whole editing surface is derived from — and the requests never left the browser. The server saw nothing and logged nothing. Development was unaffected, because with no gate there is no token to stamp. ## 0.11.2 Every route answered `200` in production and the browser discarded all of them. The orchestrator route `create-avocado-site` generates was never told which origin the editor is served from, so with `NODE_ENV=production` it answered every request with no `access-control-allow-origin` at all. The editor reported that it could not reach a server that was answering `200` to `curl`. A project scaffolded on 0.11.2 or later writes three variables into `.env.local`, each read by different code: | Variable | Read by | | - | - | | `EDITOR_CORS_ORIGINS` | the generated orchestrator route, as `corsOrigins` | | `NEXT_PUBLIC_EDITOR_ORIGIN` | the browser, and the SDK's editor-route CORS | | `ORCHESTRATOR_CORS_ORIGINS` | the `siteOrigin` check behind `publish/diff` | **An older project needs these added by hand.** The values are not interchangeable — the first two name the *editor's* origin, the third names the *site's*. The generated `.env.local` carries a comment for each explaining which code reads it. Without the first, a production deployment's editor cannot reach its own orchestrator; without the third, the Publish panel's diff answers `400 siteOrigin is not an allowed URL`. ## 0.11.1 Two buttons nobody had ever pressed, both of which answered `ok: true`. 0.11.0 tested publishing and fixed what that found. This release comes from a run against the published tarballs that pressed two more: a publish carrying nothing, and a login against a mount configured to refuse everything. Neither was a hole an attacker could walk through. Both were the system saying yes while doing something else. ### Breaking: a publish that removes every page is refused `POST /api/editor/publish` checked the shape of `pages` and nothing else. `[]` is an array, so a publish that deleted the entire site was indistinguishable from one that fixed a heading — authenticated, under `NODE_ENV=production`, `{"pages":[]}` returned `{"ok":true,"slugs":[]}` and every URL on the site became a 404. The reason this is a guard and not a warning is what actually produces an empty array. It is rarely somebody deleting their site one page at a time; it is a client publishing what it thinks it has after its own state failed to load. Losing a site to a failed fetch is not a decision anyone made. The rule is the narrowest one that holds: **a publish may not remove every page.** Removing one page of three stays an ordinary edit. Emptying the site needs `"allowDelete": true` in the body, which is something somebody types on purpose and cannot arrive at by omission, and the refusal is a `409` naming it: ```json theme={null} { "ok": false, "error": "refused", "reason": "This publish would remove every page from the site. … The site currently has 3 pages." } ``` A site that is *already* empty may still publish empty — that removes nothing, and refusing it would fail a new integration on its first publish. `createEditorApiHandler` passes its own `getPages` as the baseline, which is how the refusal can say what it protected; a baseline that throws, a CMS read that timed out, does not open the gate, because not knowing what is there is not a reason to overwrite it with nothing. `maxPagesRemoved` bounds it further for sites that want tighter than "not all of them", and the rule itself is exported as `checkDestructivePublish` from `site-sdk/routes`. **What you have to change.** Nothing, unless something you own publishes an empty page set on purpose — a migration script, an agent, a test fixture. Those need `"allowDelete": true` in the request body now, and otherwise get a `409` whose `reason` says so. A publish that changes or removes *some* pages is unaffected. ### Breaking: `POST /auth/verify` refuses on a closed mount A library-mode orchestrator under `NODE_ENV=production` with no credential configured resolves to `closed` — there is no password and no token to check one against, so every route behind the gate answers 401. `/auth/verify` answered `{"ok":true,"accessToken":"..."}`, to any body at all, including `{}`. It was never exploitable: all three transports (`Authorization: Bearer`, `x-access-token`, `?accessToken=`) were checked, and the token opened nothing. That is what made it expensive. A login that says yes while the system is shut leaves the operator holding a token and 401ing everywhere with no way to connect the two. The route now answers `503` with `error: "unavailable"` and the same `reason` string `/auth/status` already returns, which names the two variables that fix it. **What you have to change.** Nothing if your mount is configured. A client that treats every non-200 from `/auth/verify` as a wrong password should tell the `503` apart: it means the server has no credential to verify against, not that the one you sent was wrong. Set `ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`, or pass `auth` to `createOrchestrator()`. ### Fixed: a refused publish now explains itself in the editor The two refusals `/api/editor/publish` gained across this release and the last one — the `409` above and the unconfigured-publish `401` below — each carry a machine-readable verdict in `error` and the sentence a person can act on in `reason`. The orchestrator's publish target read only `error`, so the second half died one hop from the person who tripped it: the editor showed the word `unauthorized` and nothing about `PUBLISH_TOKEN`, and would have shown `refused` and nothing about `allowDelete`. ### Also in 0.11.1 * The keyless "chat is running without a key" panel rendered two of its paragraphs at 1.65:1 contrast — effectively invisible. Not a colour choice: the panel mounts inside the chat header, whose `.chat-header p { color: var(--muted) }` outranks a bare class and painted the header's grey onto the panel's near-black ground. Only the two `

` elements were affected, which is why the panel looked half-rendered rather than broken. ## 0.11.0 Publishing, which nothing had ever tested. A clean-room run took the same path as the one before it and went a step further: it pressed Publish. Three defects, and they compound — the path the editor uses wrote nothing, the path that writes was unauthenticated, and what it wrote the site could not read. Nothing in the repository referenced `createJsonFilePublishHandler`; `writeOnPublish` appeared only in the adapter that defines it. ### Breaking: the publish route refuses to run unconfigured in production `publishSecret` was optional on a route that overwrites a site's content, and every scaffold and example wired it to `process.env.PUBLISH_TOKEN` against a variable none of them ever wrote — not set, not commented, not mentioned. So the value was always `undefined`, the guard was dead code, and one unauthenticated `curl` replaced every page on the site. The deployment that proved it had `ACCESS_PASSWORD_HASH` set exactly as its own README instructs, and was correctly answering 401 on `/api/avocado/*` at the same moment: the two route groups are different handlers, and only one had ever been asked about auth. Under `NODE_ENV=production` with no secret configured, the route now answers `401` with a `reason` naming the variable. Development is unchanged — publishing to your own machine is the point — and warns once, through the same code path that ships. **What you have to change.** If you publish to a production site, set `PUBLISH_TOKEN` there and give the orchestrator the same value: it sends it as the `x-publish-token` header. Supplying `publishSecret` to `createEditorApiHandler()` directly does the same thing. With neither, every publish to that deployment is refused, and the 401 says which variable is missing. `npm create avocado-site` generates a token into `.env.local` rather than leaving the line blank. ### Breaking: `createJsonFilePublishHandler` writes `PageDoc[]` by default It wrote `{ pages, siteConfig }`, three lines beneath a docstring saying it wrote an array, and three of its four call sites read the file back as one. So a successful publish broke the site that had just published: a reader doing `JSON.parse(...) as PageDoc[]` throws on an object — the `try`/`catch` around the read catches a parse error, never this — and a reader expecting a slug-keyed object silently found no pages at all. `array` is the default now, because it is what the readers and the adapter expect. ```ts theme={null} createJsonFilePublishHandler(path) // PageDoc[] createJsonFilePublishHandler(path, { shape: "wrapper" }) // { pages, siteConfig } ``` **What you have to change.** If whatever reads your published JSON expects `{ pages, siteConfig }`, pass `shape: "wrapper"`. A reader that wants `siteConfig` in the same file needs it: a plain array has nowhere to put one, so site-level settings — name, logo, navigation — are dropped on publish. If your reader expects an array, you were already broken and this fixes it. ### Fixed: publishing from the editor wrote nothing and reported success `jsonFileAdapter({ path })` without `writeOnPublish` defaults to `false`, so the adapter had no `onPublish` at all, and the scaffolded README stated plainly that publishing from the editor rewrites the content file. After dozens of chat edits through the real pipeline the file was byte-identical to the scaffolded original. The demo publishes for real now. The summary under the green tick also read `adapter has no onPublish; publish is a no-op` — two audiences given one sentence, and the first-run user got the developer's. The API keeps that `reason`; the editor prints a sentence written for the person who pressed the button. ### Fixed: a deployed site cannot rewrite its own content file `writeOnPublish` works on your machine and fails on a serverless host and in any container built from an image, because the runtime filesystem is read-only. That is now said where it is relevant rather than discovered on the first production publish. Publishing from a deployment goes to something that persists. ### Also in 0.11.0 * The editor no longer asks for CMS media on first load from a server that has already reported `features.cmsMedia: false` on `/status/planner`. A new user's first impression of their own log was a red 404 on `POST /media/cms`. * **"Add an API key" is a button.** It was a `` with a `title` attribute — hover-only, on an element with nothing marking it interactive — and it was the only permanently visible place in the editor naming `.env.local`. It now opens a panel naming the file, the folder it lives in, the variables and what each one buys, and the restart. * The scaffold's build gate probes `POST /api/editor/publish` under a production server with no token configured and asserts the 401, that the refusal names `PUBLISH_TOKEN`, and that the content on disk is unchanged. It then runs a publish round trip in development: publish through the editor's path and assert it wrote, publish through the other path and assert the shape, then re-read the file the way the site does and ask the site for the page. ## 0.10.0 The first run, as a stranger performs it. 0.9.0 shipped `npm create avocado-site` and verified it the way the person who built it would: scaffold, boot, click the thing you know works. A clean-room review then ran it the way a new user does — `npm run dev`, `npm run build`, `npm start`, click the buttons the product puts on screen — and found eight defects, every one of them in a path no test could see, because no test had ever built and served what the scaffolder emits. ### Fixed: a production build served an editor that could load nothing Library mode is closed under `NODE_ENV=production` with no credential, which is the right default. What was wrong is that nothing said so. Two questions had been collapsed into one flag: `gateEnabled` answers *"should I prompt for a password?"*, and a closed mount has no password to prompt for, so it answered `false`. The editor read that as "open", rendered itself, and 401'd on every request behind it — no password box, and no way to reach one. `/auth/status` now also reports `mode`, and a closed mount's 401 carries a `reason` naming the variable to set. Withholding that was protecting nobody: in this state no credential exists, so there is no caller to withhold it from — only the operator, looking at a 401 on their own deployment. `error: "unauthorized"` is unchanged, because that exact value is what the editor's fetch shim matches on to re-prompt. `mode` is additive and `gateEnabled` keeps its meaning and its value. The values `mode` can take are `token`, `hook`, `open-dev` and `closed`; only `closed` carries a `reason`. ### Fixed: in development, no page had a title and no unknown slug 404'd A configured `siteId` is the site's own identity. It was being read as evidence that *the editor* was asking — and since every integration configures one, every anonymous request in development resolved an editor context. `generateMetadata` short-circuits to `noindex` and nothing else for an editor render, and the render took the draft path, where a missing page is "draft unavailable" at HTTP 200 rather than `notFound()`. So titles, social cards and 404 behaviour were all unobservable in the only mode anyone develops in. An editor render now requires a signal that the editor sent the request: `siteId`, `session`, `editorOrigin` or `__editor` on the URL, draft mode, the draft cookies, or a valid secret. Production behaviour is unchanged by construction — every way of passing the existing authorization gate is itself one of those signals. ### New: `createSitePage({ siteUrl })` Three tags cannot be derived from a page's own content, because none of them is knowable without knowing where the site lives: ``, `og:url`, and an `og:image` resolved to an absolute URL. A page that stores its image as a relative path is correct in an `` and ignored by every social crawler, so a site can pass a "has an og:image" check and still render a blank card. ```ts theme={null} createSitePage({ siteId: 'my-site', siteUrl: process.env.NEXT_PUBLIC_SITE_URL, // https://example.com getPage, getSlugs, }) ``` Unset, the SDK still emits none of the three: a wrong canonical is worse than an absent one. Reading it from an environment variable at the call site is the intended shape, so preview deployments describe themselves instead of all claiming to be production. ### Fixed: suggestion chips that did nothing Eight of nine chips did nothing on a keyless install, including all three on the first screen, under a banner reading "No API key needed to look around". A chip's label *is* the prompt — it is sent verbatim — so a phrasing the answering planner cannot parse is a button that does nothing. The chips were written against a model; with no key the answer comes from a short list of English substring matchers. The first-screen trio is now chosen against the planner that will answer it, and the follow-up chips are filtered through that planner itself rather than against a second list of blessed phrasings — so if the matcher stops answering something, the chip for it stops being offered in the same commit. Returning fewer chips, or none, is the intended outcome. The curated chips also look at the page now, instead of offering "Add an FAQ section" on a page that already ships one. ### Also in 0.10.0 * **A keyless reply no longer credits a model that did not run.** With no provider key configured at all, the per-message model chip reported the lookup's default. Narrow on purpose: a *deterministic* plan produced while a key **is** configured still names the model, because that model would genuinely have run. * **The assistant no longer offers to revert an edit it cannot revert.** Two planner prompts instructed the model, in as many words, to suggest "Revert to previous". It has no access to the undo stack, so the suggestion resolved to a refusal or to fabricated copy presented as a restoration, while the editor's own working Undo button sat in the toolbar. * Every demo page declares an `ogImage`, three of them no longer carry a different product name in the `` a crawler sees, and the scaffold's 404 page exports metadata — a correct 404 previously still had no title. * **`scripts/scaffold-serve-check.mjs`, in `pnpm test:build`.** The only thing in the repo that built a real app and read the HTML built an example in `mode: "static"`. The scaffolder emits `mode: "auto"` — a different branch of `createSitePage`, and the one every new user runs. The new check generates the scaffold from its own templates, overlays the working tree, then builds and serves it in **both** modes and asserts on the bytes: metadata and a real 404 in development, and in production the closed gate naming itself. * **A gate that fires the editor's own chips at the planner that answers them.** The chip builder lives in the editor and the keyless planner lives in the orchestrator; nothing connected them, so nothing noticed when they drifted apart — and they had. ## 0.9.0 There was no way to see Avocado without cloning it. ### New: `npm create avocado-site` ```bash theme={null} npm create avocado-site@latest my-site cd my-site && npm run dev ``` One command starts the site and the editor beside it, on a nine-page demo — the Avocado Hub — with every renderer in the library on screen at once. **No API key is needed to look around.** Rendering, click-to-select, the property panel, undo and publish all work without one; chat is the single thing that does not, and it says so rather than failing. The orchestrator runs inside the scaffolded Next.js app at `/api/avocado`, in library mode. There is no third service and nothing to deploy separately. <Note> The package existed before under a name it could never have been invoked by: `npm create` requires a `create-*` package name, and it was published under none. So this is the first release in which the repository's own front door actually works. </Note> ### New: `siteName` and `demoContent` on `createOrchestrator` The editor asks the orchestrator what it is mounted on. It used to guess. `siteName` is what the editor greets you with; without it the site id gets title-cased, so a mount called `my-shop` is introduced as "My Shop". Reasonable for an id that is a name, wrong for one that is a directory. `demoContent: true` says this mount serves Avocado's shipped demo pages, and turns on the first-run suggestions written against them. Those suggestions — and the demo greeting, and the site's own name — were previously keyed on a hardcoded list of four site ids, all of which live in the Avocado repository. Any site anyone else stood up was excluded by construction from the onboarding written for it. Both are reported on `/status/planner`. Neither is required. ### Fixed: a keyless editor that looked broken rather than keyless With no provider key, chat falls back to a rule-based planner that handles a slice of literal edits. Everything outside that slice used to come back as "I need one clarification: what section should I change and what exactly should be updated?" — which reads as a planner that cannot understand plain English, not as one that was never given a key. It now says which variable to set and where. The header badge says so too. ### Fixed: "review this page" never reached a model Two detectors claimed the message and the deterministic one was tested first, so a judgement question was answered from a template in twelve milliseconds. The template was written against every block type registered in the process — which, because importing anything from `@avocadostudio-ai/shared` registers the built-ins transitively, is Avocado's own type names and not yours. A site rendering its own fourteen types was told it was missing Hero, CTA and FAQ, and advised to add three blocks it has no renderer for. `add_block` for one of those applies cleanly, reports success and draws nothing. Judgement questions route to the model now, with the page's real props in context. What survives from the template is `pageObservations`: facts that were looked up rather than inferred — a declared image field with nothing in it, a page nothing links out of, a missing meta description. The same leak is fixed in two more places: the block catalogue answer no longer suggests adding types your site cannot draw, and neither does the planner's specify-a-type clarification. ### Also in 0.9.0 * The overlay's missing-editable-targets warning is withdrawn. Every block wrapped and no field marked is not a fault, and reporting it through `console.error` painted a red Console Error over a working integration. `site-sdk/coverage` still measures it for anyone who asks. * The editor's unreachable-orchestrator screen retries on its own, backing off to fifteen seconds. An orchestrator is unreachable for a few seconds on every restart, and the screen could previously only be left by clicking *Try again* at the right moment. * The model dropdown offers Claude only. The planner's prompts, its structured-output path and the eval set are all tuned against it. UI only — the orchestrator still advertises and accepts all three providers. * Inline editing is its own documented step rather than step 2 of the Next.js integration, where it was deferred and forgotten. * The demo content is one coherent nine-page site rather than six narrower authored pages, with the dead CTA, the nav entry pointing at `/be-shorter-unsplash` and the alt attributes holding image-generation prompts all fixed at the source. ## 0.8.0 A tenth package, and a field kind for the markup most templates actually store. ### New: `@avocadostudio-ai/astro` Avocado now integrates with Astro. Your `.astro` components keep doing the rendering — no React, no islands, nothing ported. Avocado supplies the schema, the draft props, the editable markers and publishing. ```bash theme={null} npm install @avocadostudio-ai/astro @avocadostudio-ai/site-sdk @avocadostudio-ai/shared ``` ```ts astro.config.ts theme={null} integrations: [ avocado({ siteId: 'my-site', content: './src/avocado/content.ts', editablePages: ['src/pages/index.astro'], }), ] ``` That is the wiring. See the [Astro integration guide](/integration/astro-integration) for the content module, why `editablePages` is a list, and what a build does with all of it (nothing — the output stays as static as it was). <Note> Astro support shipped from one pilot integration. It renders, edits, previews and publishes; what it has not yet had is a second site. Expect gaps around anything the pilot did not exercise. </Note> ### New: `kind: 'html'` for fields whose stored value is markup A component that takes a prop either as a value or as a slot renders it with `set:html` — or `dangerouslySetInnerHTML`, or `v-html` — and what is stored is a string of markup. The closest kind that existed was `richtext`, which means a *document*, so the property panel rendered the markup literally: ``` Free template for <span class="hidden xl:inline">creating websites with</span> … ``` Nobody can edit that without breaking it, and editing it anyway writes the broken version back to your source. `html` stores the string your template renders, edits it as a document, and converts both ways — preserving the elements and attributes it cannot model rather than dropping them. ```ts theme={null} const HEADLINE = { title: { kind: 'html', label: 'Title' }, } ``` See [when the stored value is HTML](/integration/field-table#when-the-stored-value-is-html). ### New: `stringList` and `imageList` field kinds Both were declarable and neither was drawn — a declared, schema-valid field reached the property panel as nothing at all. They now have controls: rows of inputs for a string array, and the image widget per row for an image array, so the asset picker and alt text behave the same whether an image is on its own or one of twelve. <Warning> **What you have to change.** `registerFieldTable` now **refuses a kind it does not know** instead of silently emitting `text`. If your field table has a typo in a `kind`, registration throws and names it. That is the failure this release converts from invisible into loud — the field had been reaching the panel as nothing. </Warning> ### New: the editor API and page render without Next.js Three things `createSitePage` used to decide and throw away are now values any host can consume: `resolvePageRender` (`page` / `not-found` / `draft-unavailable`), `decideEditorRewrite`, and `renderPageMetadata`. `createEditorApiHandlerCore` and `site-sdk/routes/core` are the editor API with no framework in them, and `preview-adapter/bridge-controller` is the live-preview protocol with no React — which is why **React is no longer a mandatory peer** of `preview-adapter`. Nothing about the Next.js path changes. These are the seams every non-Next host was reimplementing from the source. ### Fixed: a list the property panel could not draw A field table declaring `{ kind: 'list' }` emitted a schema saying only "array of objects", so the panel showed neither rows nor an Add control — and 0.7.0's check that a new row must name its type was inert for the same reason. The metadata was correct all along; the panel re-derives from the manifest's JSON schema, and a key the schema does not expose is discarded rather than refined. ### Fixed: the editor could push one site's pages under another site's id The editor bootstrapped its draft before the site registry answered, so for every site but the build-time default, the first push carried the *default* site's pages — which then stayed, counted in the Publish badge, one click from being written to your repository. The editor now waits for the registry, and `/draft/bootstrap` refuses a push whose stated origin contradicts the site's registered `previewUrl`. <Warning> **What you have to change.** Nothing, unless you drive `/draft/bootstrap` yourself. Only a *contradiction* is refused: a caller that sends no origin, and a site registered without a `previewUrl`, are both unaffected. </Warning> ### Fixed: a publish diff describing a different site When a site's `/api/editor/pages` did not mention a `siteConfig` — an Astro site answers `{pages}` and nothing else — the bundled demo's header config was used to fill the gap, so the publish diff reported the demo's name, logo and navigation as your "before". Absent now means "no header change", which is what it meant. ### Also in 0.8.0 * `site-sdk/draft/core` no longer throws at module load where Next.js is not installed. It imported one four-line helper from the module beside it, whose first line is `import { draftMode, cookies } from "next/headers"`. * `site-sdk` and the CLI no longer ship compiled test modules in their tarballs. * The demo content the editor seeds in demo mode is one coherent site again, rather than sediment from old chat sessions. * Package manifests no longer link to a repository that answers 404. There is no public repository, so npm renders no *Repository* link at all; `bugs` points here. ## 0.7.0 ### Breaking: `add_item` requires a list row's discriminator A polymorphic list declares which prop names a row's type and which types it admits. `add_item` used to accept a row that left that prop out. It now rejects it, naming the admissible types. <Warning> **What you have to change.** If you call `POST /ops` with `add_item` by hand — from a test, a script or an agent — check that every new row for a polymorphic list sets its discriminator prop. A row that omits it used to be created and then fail downstream, or write a typeless row into your CMS. Only *omission* is rejected. A value that names no declared branch is still accepted, because your manifest may enumerate fewer types than your CMS has. Chat-driven edits are unaffected — the planner always sets it. </Warning> ### New: field-table lenses for CMS-backed sites Four things have to agree about every block on a CMS-backed site: the Zod schema an AI edit is validated against, the metadata the property panel draws with, the projection that turns a CMS document into props, and the merge that writes edited props back. Written separately, they disagree within a week. `@avocadostudio-ai/site-sdk/lens` derives all four from one table: ```ts theme={null} registerFieldTable(TABLE, { primitives }) // schema + panel metadata const lens = createLens({ table, locale, primitives }) // projection + merge ``` Packs ship for Storyblok (`site-sdk/lens/storyblok`) and Sanity (`site-sdk/lens/sanity`). Another CMS answers six questions and inherits the rest. `roundTrip` is part of the API: run a projection through its own inverse over your real content, and anything that moves is a codec that is not its own inverse for some value in *your* documents — invisible in the editor, and visible later as a publish wanting to rewrite pages nobody opened. See the [field table guide](/integration/field-table) for the shape, the wiring and the two write rules. <Warning> **One sharp edge.** `localized: false` means **the bare key**, not the default language's path. Those coincide on a CMS that localises into a suffixed sibling and diverge on one that localises into an object under the key. There is deliberately no implicit fallback — a read that fell back would pair with a write that did not, which is how a lens corrupts a document. </Warning> ### New: keep third-party scripts out of the preview `isEditorRender()` tells a layout whether it is rendering inside the editor's preview iframe. A layout receives no `searchParams`, so consent banners, analytics and chat widgets could not be gated the way a page can — they loaded inside the preview and sat on top of the content being edited. The preview rewrite now stamps a header a layout can read. ### Fixed: the optional peer dependency from 0.6.0, completed 0.6.0 declared `@anthropic-ai/claude-agent-sdk` as an optional peer of `orchestrator-core` — twice, in two blocks of the same manifest, and JSON parsing keeps the last one. The 245 MB really did leave library-mode installs, but a consumer of `orchestrator-core/agent/*` got a bare `MODULE_NOT_FOUND` instead of a package manager naming what to install. Fixed in 0.7.0. ### Also in 0.7.0 * `editableScopeProps({ display: "contents" })`, for a list whose rows map straight into a flex column and have no ancestor to hang an editable scope on. Off by default — a row already inside an `<li>` should carry the scope there. <Note> The bundled editor did not change in this release, so the CLI's editor bytes are 0.6.0's. The package moves to 0.7.0 with the rest for the lockstep reason above. </Note> ## 0.6.0 ### Breaking: the Claude Agent SDK is an optional peer, not a dependency `@anthropic-ai/claude-agent-sdk` used to be a dependency of `orchestrator-core`, which library mode puts into your public site's dependency tree. The SDK is 4 MB; its platform package is a 245 MB binary — larger than every other dependency put together. <Warning> **What you have to change.** Nothing, if you mount `createOrchestrator` and nothing else — that path never imports it, and your install gets smaller. If you import `@avocadostudio-ai/orchestrator-core/agent/sites-agent-tools` or `.../migration/migration-tools`, install `@anthropic-ai/claude-agent-sdk` alongside Avocado yourself. The standalone orchestrator declares it directly and is unaffected. </Warning> The rest of that finding was "state the number, so nobody discovers it at deploy time". The library-mode install footprint, per dependency rather than as one total, because two of the five are native and the figure differs by platform: | Dependency | Size | What it buys | | - | - | - | | `better-sqlite3` | \~27 MB | draft state, history, version log | | `sharp` + libvips | \~16 MB | image resizing | | `@anthropic-ai/sdk` | \~10 MB | planning | | `openai` | \~7 MB | planning | | MCP SDK | \~6 MB | the MCP surface | Roughly 66 MB on darwin-arm64. If the footprint decides it for you, the standalone orchestrator is the other shape. ### Breaking: internal props now appear in the field manifest `resolveManifestFieldMeta` used to omit `_`-prefixed props. It now emits them as fields carrying `internal: true`. <Warning> **What you have to change.** If you iterate `meta.fields` to build your own UI, skip entries where `internal === true`. Everything Avocado ships already does. If you use the built-in property panel, there is nothing to do. </Warning> ### New: `kind: "reference"` for CMS references A CMS stores an internal link as an object — a Storyblok story link, a Contentful entry link, a Sanity reference — and renders it to a different href per language. Declaring such a prop as `kind: "link"` flattens the object to an href, and two things go wrong. The publish diff reports the reference as changed on every page forever, because the rendered href never equals the stored object. And writing the href back replaces the pointer with a hardcoded URL: the page renders identically, and the link silently stops following renames, which is the one thing the reference was for. `kind: "reference"` is deliberately opaque. The panel shows where it points and offers no control. The planner is not told the prop exists, and an `update_props` naming one is dropped with a note saying the change belongs in the CMS. A new list row gets `null` rather than placeholder text. Use `referenceLabelKey` to name a readable key so the panel shows something better than an id. There is no reference picker. Re-pointing a reference needs your CMS's own document ids, which only your integration has. ### New: Storyblok rich text `fromStoryblok` and `toStoryblok` join the converters in `@avocadostudio-ai/richtext`, which now covers four CMSes: Storyblok, Contentful, Sanity Portable Text and Strapi. Without a converter, the cheap thing to do with a rich-text field is flatten it to a string, and you lose every mark, link and list on the first publish with nothing logging it. ### New: `context.baseline` replaces `context.published` The publish diff's baseline was always your CMS's *draft* content, not the live site. The name said otherwise, and integrators either designed around a problem that did not exist or took a second read of the published perspective and created one. <Note> **What you should change.** Read `context.baseline` in your publish handler. `context.published` still holds the same array and still works — it is deprecated, not removed. `undefined` means "no baseline available" and never "the site was empty"; publishing every field on that assumption is the overwrite a baseline exists to prevent. </Note> ### Fixed in 0.6.0 * **Every successful library-mode publish was reported as a failure.** The response carried no `status` field, and the editor reads exactly that field before its error branch. A CMS publish that had already written every document told the person who pressed the button "Failed to trigger publish.", over HTTP 200\. * **Avocado's own block migrations ran against sites that had re-registered a built-in name.** Registering your own `Hero` — which the CMS adapter docs tell you to do — used to invite Avocado's migrations to invent props on it: a placeholder image URL, an English alt string on a German page, a `variant` overwritten with `"default"`. None of it showed in the preview, because your renderer ignores props it does not use. It showed at publish, on pages nobody opened. Whoever registers a name last now owns it. * **Generated list-row ids leaked into publish diffs.** Avocado stamps a stable `id` on every declared list row so the panel can reorder and the planner can address a row by name. It lives in `props`, so an adapter comparing its draft against freshly read CMS content saw every block with a list as changed, from the first load and forever — a one-field edit could produce a publish that wanted to rewrite every document with a list on it. `withoutGeneratedItemIds`, from `site-sdk/publish`, is the inverse. It strips only the ids Avocado generated, so a row carrying your CMS's own key keeps it. * **`trailingSlashRedirect` and `editorPreviewRewrite`** are exported from both `site-sdk/proxy` and `site-sdk/middleware`. The hand-written trailing-slash redirect, built from `request.nextUrl.clone()` as every Next example invites, strips the slash it just added and sends every page into an infinite redirect — visible only in a browser, since `curl` without `-L` sees one ordinary 308. * **A bare `data-editable-target` on a list row resolved against the enclosing block,** so an edit to a headline inside a column patched a prop the section does not have. Silent and wrong, rather than silent and absent. * **`panelCoverage` no longer reports a CMS's own `_uid` as an orphan prop** — on a CMS that stamps one, that was a finding per block per page, burying every real one. * **`notes?: string[]` on `CmsPublishResult`,** so a dry run, a queue or a review-before-write publisher can say what it did. It had one channel before, `unsupported`, which renders as failure. * **Two more multilingual traps documented.** A container is not localised — the fields inside it are. And on a CMS that localises per field, the component schema decides in both directions, so a document can keep a translated value your site has not rendered in years. See [multilingual](/integration/multilingual), rules 3 and 4. ## 0.5.1 Three defects found by integrating a real site. No breaking changes. * Alt text outranks the image filename as a list-row label, and a list field inside a list row is no longer reported as unmarked. Both were coverage findings a site could only clear by renaming its image files or by marking an element that draws nothing. * A relative image URL is resolved against the site's own origin before it goes to a vision model, and a URL source is only ever https. Library-mode image selection used to fail the whole chat turn with the provider's own 400. * `registerBlock` no longer warns that a correct polymorphic list is unbacked, and a row whose only content is rich text is labelled by its first text node rather than `Item N` or `[object Object]`. ## 0.5.0 Minor rather than patch: this adds entry points and changes behaviour an existing integration can observe. ### New entry points The install line every guide shipped could not satisfy the imports those same guides required — `@avocadostudio-ai/shared` is a dependency of the SDK, not of your site, so under pnpm the documented import did not resolve at all. | Subpath | What it gives you | | - | - | | `site-sdk/blocks` | `registerBlock`, `z`, the block-meta types, the name helpers | | `site-sdk/markers` | the preview attribute helpers, with no React behind them | | `site-sdk/coverage` | `editableCoverage` and `panelCoverage` | <Note> **What you should change.** Import from `@avocadostudio-ai/site-sdk/*` rather than from `@avocadostudio-ai/shared` or `@avocadostudio-ai/preview-adapter`. Installing the SDK alone is then enough, which is what every guide told you. `site-sdk/markers` also matters for bundle size: the marker helpers used to ship from the same entry as the editor overlay, which added 66 kB of First Load JS to every public page that marked up a shared component. </Note> ### New: `panelCoverage` `editableCoverage` asks whether the rendered page offers each declared field. Nothing asked whether the **property panel** is intelligible — so a site could compile cleanly, serve a valid manifest, pass every marker check, and still hand a person a panel they cannot use. `panelCoverage` resolves metadata and rows through the same functions the panel itself uses, and compares them against your real content. No browser, no screenshot, no model call. Seven findings, ordered so the cause is read before its symptoms: `colliding_type`, `incomplete_polymorphism`, `unmatched_branch`, `unlabelled_row`, `orphan_prop`, `filename_row_label`, `phantom_field`. Three surfaces, because an adopter and an agent need different things: `site-sdk/coverage` for your own check script, `avocado-check-editing-surface` over MCP for an agent to call before reporting an integration done, and a formatted report for a human. See [coverage checks](/integration/coverage). `FieldMeta` also gained `panelOnly`, which takes fields nothing can draw out of the coverage denominator — so 100% is reachable and anything less is actionable. ### Behaviour an existing integration will notice * **The property panel now prefers your field metadata over Avocado's built-in registry** on a colliding type name. If you register your own `Hero`, you were being shown Avocado's labels for it — one integration collides on seven of its eight types and read `Left column items` where it had declared `Left column`. A field your manifest declares explicitly now wins; a field it only derives from its JSON schema still takes the registry's richer entry. The merge also stopped silently dropping `discriminator` and `itemFieldsByType`, which meant polymorphic lists were measured against the union of all branches and rows fell back to `Item 4`, `Item 5`. * **A mounted `createOrchestrator` publishes its own address.** The draft fetch used to default to a standalone orchestrator on `:4200` that a library-mode site does not run — silent when nothing is listening there, and worse when something is, because the preview then renders a foreign process's content and answers 200. * **`withAvocado` writes the framing CSP pair** from the same allowlist the editor API uses, so you no longer hand-write `frame-ancestors` next to your CORS origin. Getting it wrong failed in two unrelated-looking ways: the Sites page reporting your site offline (CORS), and a blank rectangle where the preview should be (CSP). Your own `headers()` come first and win; `framing: false` opts out. * **The legacy `../../.data` database path now requires proof of workspace membership.** It used to ask only whether that file exists — and since the original bug is what created it, one mistaken write re-targeted every project under the same parent directory, forever. One integration's drafts landed in a database already holding twelve sessions from four unrelated projects, while reporting `persistence: { ok: true }` throughout. * **A successful `next build` no longer prints a red error about production auth.** It was describing a request that was not being served, on a machine that was not the deployment. ## Earlier releases 0.4.0 and 0.3.3 are recorded in `CHANGELOG.md` at the root of the repository. Highlights: files as a content type alongside images, `editableCoverage`, publishing a subset of a draft, discarding changes from the version log (0.4.0); and site health checks, a durable store, and `link` as a field kind (0.3.3). ## Upgrading <Steps> <Step title="Move every package at once"> Set all `@avocadostudio-ai/*` dependencies to the same version. A mixed set will resolve, then fail at runtime in ways that point nowhere useful. </Step> <Step title="Read the breaking notes between your version and the target"> Every breaking change on this page carries a "what you have to change" note. Minor bumps are where they live. </Step> <Step title="Re-run your coverage checks"> `editableCoverage` and `panelCoverage` are the fastest way to see whether an upgrade moved something in your integration. See [coverage checks](/integration/coverage). </Step> <Step title="Round-trip your projection, if you have a CMS"> If you use a lens or a hand-written projection, run `roundTrip` over real content before you publish. A codec that is not its own inverse is invisible in the editor and shows up as a publish rewriting pages nobody opened. </Step> </Steps> This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.