@avocadostudio-ai/skills 0.21.0 → 0.22.0

package/NOTICE

@@ -0,0 +1,8 @@
+Avocado Studio
+Copyright 2026 Avocado Studio Contributors
+
+This product includes software developed by the Avocado Studio
+Contributors (https://www.avocadostudio.dev).
+
+Licensed under the Apache License, Version 2.0. See LICENSE for the
+full license text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/skills",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Install Avocado Studio's agent skills into a project, so a coding agent reads instructions that match the version you have",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,9 @@
   "files": [
     "dist",
     "skills",
-    "README.md"
+    "README.md",
+    "LICENSE",
+    "NOTICE"
   ],
   "keywords": [
     "avocado",

package/skills/avocado/SKILL.md

@@ -17,14 +17,18 @@ every path.
 
 | The user has | Load |
 |---|---|
-| A Next.js app that already exists, with its own components and content | `avocado-integrate` |
+| A Next.js site that already exists, with its own components and content | `avocado-integrate` — its Next.js branch |
+| An Astro site that already exists | `avocado-integrate` — its Astro branch |
+| A Next.js or Astro site whose copy is written into its templates rather than held in a CMS or data files | `avocado-integrate`, plus the file-backed recipe it links: https://docs.avocadostudio.dev/integration/file-backed-sites |
 | Nothing yet, or wants to see it working before committing | `avocado-demo` |
 | Either, and you are now declaring their components as editable blocks | `avocado-blocks` |
 | Either, and the content those blocks render comes from a CMS | `avocado-cms` |
 
-Before deciding, if the site is live, `npx avocado-scope <url>` will tell you
-what one of its pages would become as blocks without installing or writing
-anything. It is read-only, deterministic and free.
+Before deciding, `npx -p @avocadostudio-ai/migration-sdk avocado-scope <url>`
+will tell you what one of the site's pages would become as blocks without
+installing or writing anything — add `--allow-localhost` for a site on a local
+dev server. It is read-only, deterministic and free. The command lives in
+`migration-sdk`, so a bare `npx avocado-scope` is a 404 from the registry.
 
 If it is ambiguous, ask one question: *"Is this going onto a site you already
 have, or do you want a demo first?"* Do not guess — the two paths write
@@ -47,9 +51,16 @@ edit go through without telling the user.
 
 - **Install with the package manager the project already uses.** The lockfile
   says which. Do not introduce a second one.
-- **Import only from `@avocadostudio-ai/site-sdk`.** `registerBlock` and `z`
-  come from `@avocadostudio-ai/site-sdk/blocks`; the attribute helpers from
-  `@avocadostudio-ai/site-sdk/markers`. Never import `@avocadostudio-ai/shared`,
+- **Import only from `@avocadostudio-ai/site-sdk`** — and, on Astro, from
+  `@avocadostudio-ai/astro`. The types (`PageDoc`, `BlockInstance`,
+  `SiteConfig`) come from the SDK's root as `import type { PageDoc } from
+  "@avocadostudio-ai/site-sdk"`; `registerBlock` and `z` from
+  `@avocadostudio-ai/site-sdk/blocks`. The attribute helpers come from
+  `@avocadostudio-ai/site-sdk/markers` on React and Next, and from
+  `@avocadostudio-ai/astro/markers` on Astro: `editorMarkers(Astro)` there
+  emits Astro's `class` and a style string where the React helpers emit
+  `className` and a style object, which spread onto an `.astro` element as
+  attributes nothing matches. Never import `@avocadostudio-ai/shared`,
   `@avocadostudio-ai/blocks`, `@avocadostudio-ai/preview-adapter` or a bare
   `zod` from the user's source. Under pnpm they will not resolve; under npm's
   flat hoisting they resolve today and break the first time something
@@ -67,13 +78,17 @@ edit go through without telling the user.
 - **`PUBLISH_TOKEN` is not optional in production.** `/api/editor/publish`
   overwrites the site's content. With no `publishSecret` configured it answers
   401 and names the variable rather than running open.
-- **Wrap the Next config.** `withAvocado` from
+- **On Next, wrap the Next config.** `withAvocado` from
   `@avocadostudio-ai/site-sdk/next-config` sets `transpilePackages`,
   `serverExternalPackages`, the matching server externals and
   `skipTrailingSlashRedirect` together. Setting one of them by hand looks right
-  and fails quietly on the native dependencies.
+  and fails quietly on the native dependencies. Wrap the exported value as the
+  file's last expression — `export default withAvocado(existingConfig)` — and
+  leave the config body as it was, so the diff stays reviewable.
 - **Finish on a number, not on "it builds."** Every path ends with a
-  verification step that produces a count. Report it.
+  verification step that produces a count. Report it. An integration of an
+  existing site is not done until `npx avocado qa` passes and the manual pass
+  in `avocado-integrate` is checked off.
 
 ## Versions
 

package/skills/avocado-blocks/SKILL.md

@@ -72,7 +72,8 @@ export const { GET, POST, OPTIONS } = createEditorApiHandler({
 | **A string of markup** rendered with `dangerouslySetInnerHTML` | `html` |
 | An image path or URL | `image` |
 | A list of plain strings | `stringList` |
-| A list of images | `imageList` |
+| A list of images, each only an image and its alt text | `imageList` — rows are `{ image, alt }` |
+| Rows that are an image plus anything else — a caption, a link | a list field: `listFields` with `itemFields` |
 
 `richtext` and `html` are the one people get wrong. `richtext` means a
 *document*. Declare a markup string as `richtext` and the panel renders the tags
@@ -83,6 +84,56 @@ editor and preserves the elements and attributes it cannot model.
 Declare presentation props — variants, spacing, feature flags — **nowhere**. If
 it is not content, leaving it out is the point.
 
+## What the site cannot store: `fixed` and `readOnly`
+
+Declare them, or the editor offers controls that can only end in a refused
+publish.
+
+- **`fixed: true`** in the block's `meta` — for a section that is a **slice of
+  one CMS entry rendered in a fixed order** (a blog post's hero, body and
+  related-articles grid are three blocks and one entry). The editor hides move,
+  delete and add on it, and the ops engine refuses to move, remove or duplicate
+  it — for chat and MCP too. Its fields stay editable.
+- **`readOnly: true`** plus **`readOnlyReason`** on a field — for **asset alt
+  text shared across entries**, **slugs**, **dates**: anything the publisher
+  refuses to write. The panel shows it disabled with the reason; an edit is
+  refused with the reason.
+
+```ts
+meta: {
+  displayName: "Article hero",
+  fixed: true,
+  fields: {
+    imageAlt: { kind: "imageAlt", readOnly: true, readOnlyReason: "It is the asset's title, shared by every entry." },
+    slug: { kind: "text", readOnly: true },
+  },
+}
+```
+
+## Site-wide content: `shared`
+
+A header, footer, business details or a closing CTA that every page carries is
+**one block with `shared: true`** in its `meta` (or on its field-table spec),
+placed on every page under **the same block id**. Do not model it as a
+separate block per page, and do not leave it inline in the layout.
+
+- An edit on any page is applied to every page holding that id, in the same
+  step; undo reverts it everywhere; the publish review lists it once as
+  "Footer — affects 5 pages". The planner is told it is site-wide.
+- Adding, moving and removing stay per page.
+- Identity is the id plus the type. A page-owned instance of the same type
+  needs an id no other page uses, or it becomes part of the shared content.
+
+```ts
+meta: {
+  displayName: "Footer",
+  shared: true,
+  fields: { copyright: { kind: "text" } },
+}
+```
+
+`avocado-integrate` covers injecting it into every page and writing it back once.
+
 ## Names that collide with the built-ins
 
 Avocado ships twenty built-in types: `Hero`, `FeatureGrid`, `Testimonials`,
@@ -106,6 +157,12 @@ only once the markup says where it is. Three attributes do that, all from
 `@avocadostudio-ai/site-sdk/markers` — never from `/editor`, see the rule in the
 `avocado` skill about the public bundle.
 
+**On Astro, take them from `@avocadostudio-ai/astro/markers` instead:**
+`const { block, field, scope } = editorMarkers(Astro)` gives the same three in
+Astro's spelling (`class`, a style string), reads the editor flag off the
+component's own `Astro`, and returns `{}` on a visitor's render. The rules below
+are the same; only the spelling of the calls differs.
+
 ### The block boundary comes first
 
 ```tsx
@@ -212,7 +269,10 @@ import {
 ```
 
 - **`editableCoverage`** reports `marked/expected` — of the fields the manifest
-  declares, how many the rendered page actually carries a marker for.
+  declares, how many the rendered page actually carries a marker for. Read the
+  page with `extractMarkedBlocks(html, { blocks: page.blocks })`: the page's
+  blocks attach each block's props, and without them a field that is empty on
+  every page is reported as a gap nobody can close.
 - **`panelCoverage`** reports `rowsLabelled/rowsExamined` plus findings: list
   rows nobody can tell apart, polymorphic branches that never narrow, props in
   the content that nothing describes, and type names colliding with the
@@ -222,11 +282,18 @@ import {
 you cannot reach it, do not quietly stop — list every remaining gap with the
 block type, the field path and why.
 
-Markers are emitted only on an **editor render**. Run the check against
-`next dev` through the editor path: pointed at a production build it finds no
-blocks and reports zero, which reads exactly like an integration that marks
-nothing. When building the page URL, use `new URL(page.slug, origin)` — a slug
-already starts with `/`, and string-joining it onto the origin fetches
+Markers are emitted only on an **editor render**. Run the check against the
+dev server — `next dev`, `astro dev` — through the editor path
+(`?__editor=1&siteId=…`): pointed at a production build it finds no blocks and
+reports zero, which reads exactly like an integration that marks nothing.
+
+**Pass the page's blocks to `extractMarkedBlocks`** —
+`extractMarkedBlocks(html, { blocks: page.blocks })`, with the page from
+`GET /api/editor/pages` — so each marked block carries its `props`. Without them an optional field that is empty on this page is still
+expected to carry a marker, nothing drew it, and the gap can never close.
+
+When building the page URL, use `new URL(page.slug, origin)` — a slug already
+starts with `/`, and string-joining it onto the origin fetches
 `http://localhost:3000//` and measures nothing.
 
 Cross-check the manifest directly too — `GET /api/editor/blocks` should list

package/skills/avocado-cms/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: avocado-cms
-description: Make a CMS-backed site editable in Avocado Studio — the field table, the lens that projects documents into block props and merges edits back, the Storyblok and Sanity primitive packs, and the write rules that stop a publish corrupting content. Use when the site's content lives in Sanity, Storyblok, Contentful, Strapi or another headless CMS rather than in files.
+description: Make a CMS-backed site editable in Avocado Studio — the field table, the lens that projects documents into block props and merges edits back, the Storyblok, Sanity and Contentful primitive packs, the read-only fixture to develop against, and the write rules that stop a publish corrupting content. Use when the site's content lives in Sanity, Storyblok, Contentful, Strapi or another headless CMS rather than in files.
 ---
 
 # Editing a CMS through Avocado
@@ -62,6 +62,15 @@ export const TABLE: FieldTable = {
   because the merge patches the source document rather than replacing it. That
   is the lever for scope: declare what an editor should change, leave the layout
   and behaviour switches out.
+- **`fixed: true`** on a block spec marks a section that is a slice of one
+  entry, drawn by the template in a fixed order. Declare **one block per
+  rendered section** even when several share an entry, and mark those fixed:
+  the editor then hides move/delete/add on them and the ops engine refuses the
+  change, instead of the publish refusing it later.
+- **`readOnly: true`** with a **`readOnlyReason`** marks a value the merge must
+  not write — a slug, a date. For an image whose alt text is the shared asset's
+  title (Contentful), use `alt: { readOnly: true, readOnlyReason }` on the image
+  field: the image stays swappable, the alt is shown disabled with the reason.
 - **`localized: false`** marks a field that has one value for every language —
   an anchor, a slug fragment, an icon name. It is not decoration: without it the
   lens looks for a per-language value and writes one.
@@ -84,7 +93,13 @@ registerLens(lens)
 ```
 
 Sanity is the same with `sanityPrimitives()` and `sanityLocale(…)` from
-`@avocadostudio-ai/site-sdk/lens/sanity`.
+`@avocadostudio-ai/site-sdk/lens/sanity`. Contentful uses `contentfulPrimitives()`
+and `contentfulLocale(…)` from `@avocadostudio-ai/site-sdk/lens/contentful`, and
+needs more than a lens: read section 8 before writing any of it.
+
+The rich-text converters (`fromContentful`, `toPortableText`, `fromStoryblok`, …)
+are re-exported from `@avocadostudio-ai/site-sdk/lens` and from each pack. Do not
+add `@avocadostudio-ai/richtext` as a direct dependency just for them.
 
 **Prefer `registerLens(lens)`.** The older two-call form —
 `registerFieldTable(TABLE, { primitives })` beside `createLens({ …, primitives })`
@@ -187,6 +202,111 @@ right slot, and never let two languages of the same document share a page id.
 Read `https://docs.avocadostudio.dev/integration/multilingual` before writing a
 single CMS write path. A wrong projection corrupts content invisibly.
 
+## 7. Develop against a read-only fixture
+
+Credentials usually arrive after the work starts. Do not wait for them, and do
+not point a half-written write path at a real space to find out whether it works.
+Give the adapter a **read-only fixture source** behind one env var: the CMS's own
+export format (a Contentful `space export`, a Sanity `dataset export` NDJSON, a
+Storyblok stories dump), read in place.
+
+```ts
+export const source = process.env.CONTENTFUL_EXPORT_FILE
+  ? contentfulExportSource(async () => JSON.parse(await readFile(process.env.CONTENTFUL_EXPORT_FILE!, "utf8")))
+  : createContentfulDelivery({ spaceId, accessToken, preview: true })
+```
+
+It must have **no write path**. A fixture that accepts a publish lets a broken
+publish look like it worked. On one integration this fixture reached 100%
+`editableCoverage` and a clean `roundTrip` on every entry before any space
+existed. Everything in section 4 and in Verify can run against it. The only
+thing it cannot prove is the publish itself.
+
+A starter template's own export (`export.json`, `seed.ndjson`) is the usual first
+fixture. Replace it with an export of the real space as soon as there is one:
+fixtures are how the bugs in section 4 got shipped.
+
+## 8. Contentful
+
+Use the pack; do not write it again. Two integrations each wrote the same
+~190 lines before it existed. `@avocadostudio-ai/site-sdk/lens/contentful`
+provides:
+
+- `contentfulPrimitives()` and `contentfulLocale(default, locales, { localized, contentTypeOf })`.
+- `localizedFields(contentTypes)`: which fields are localised, read from the space's
+  `/content_types` **at runtime**. Do not set `localized` in a Contentful table.
+  That would be a second copy of the content model, and it goes wrong the day
+  someone toggles localisation in the web app.
+- `readEntry(entry, { defaultLocale, localized, includes })`: a `locale=*` entry as a
+  lens document. Non-localised fields (which Contentful stores under the default
+  locale) are unwrapped to the bare key, and Links are annotated with the asset
+  URL and title or the target's slug.
+- `entryPatch(source, merged, { defaultLocale, localized, contentType })`: only
+  the locale slots that changed, wrapped again.
+- `createContentfulDelivery({ …, preview })` and `contentfulExportSource(json)`
+  for reads, both always `locale=*`. `createContentfulManagement(…).publishEntries(writes, opts)`
+  for writes: it fetches the live entry, applies the patch on top of it, sends an
+  update only if something differs, and publishes.
+
+What the codecs do:
+
+- **Images** project the asset's URL and title. A new URL is written as an upload
+  sentinel, which the publisher turns into a new asset and a Link. **Alt text is
+  the asset title, shared by every entry that uses the asset**, so an alt edit on
+  its own is refused with a warning. Say so to the user; do not work around it.
+- **References** project the target's slug. A new slug is a lookup sentinel. At
+  publish it resolves to a Link, or the whole publish is refused if no published
+  entry has that slug.
+- **Rich text** goes through `fromContentful` / `toContentful`, and "unchanged" is
+  judged against the stored value's own canonical round trip. Without that, every
+  publish rewrites every body.
+
+**Publishing in Contentful is per entry, not per field.** `PUT …/published`
+makes the entry's whole current draft live, including anything a person has
+saved in the web app and not yet published. `publishEntries` therefore
+**refuses the whole publish, before writing anything**, when any entry in it has
+unpublished changes (`onUnpublishedChanges: "refuse"`, the default). `"draft"`
+writes into the existing draft without publishing it. `"publish"` takes the
+pending changes live, and is only for a space where Avocado is the only writer.
+Never switch the policy yourself; ask the user and tell them what it means.
+
+Content-model and seeding traps, each of which has broken a real integration:
+
+- **Limit embedded entries in rich text.** Put `size: { max: 10 }` (or another
+  realistic number) on every rich-text field's `embedded-entry-block` validation.
+  Without it, Contentful's GraphQL API prices the field at the maximum. On one
+  site every post page returned 500 `TOO_COMPLEX_QUERY` (cost 101,700 against a
+  limit of 11,000) while the home page rendered fine.
+- **Seed in two passes.** An entry cannot be published while it links to
+  unpublished entries. Create and publish the linked entries first, then add the
+  links (related posts, authors) in a second pass and publish again.
+- **Check that the space holds the content model** the site queries. Some
+  templates ship without one, because Contentful's sign-up flow creates it.
+- **Render every page after seeding, not just the home page.** Both the query-cost
+  failure and a missing content type show up only on the pages that use them.
+
+Map **one block per rendered section**, even when the sections are slices of one
+entry: a blog post is `articleHero` + `articleBody`, not one `pageBlogPost` block.
+Give `contentfulLocale` a `contentTypeOf` for the section types, and merge every
+section of a page into the same document before taking one `entryPatch`.
+
+**Preview by overlaying, not by re-rendering.** Keep the site's own data layer:
+the public route runs its own query, then calls
+`applyDraftBlocks(siteData, draft?.blocks, OVERLAY)` from
+`@avocadostudio-ai/site-sdk/lens`. `OVERLAY` maps each block prop to its path in
+that object (`featuredImageUrl: "featuredImage.url"`,
+`body: { path: "content.json", to: toContentful }`). With no draft, which is
+every public render, the call returns its input unchanged. Do not write a
+second preview route that re-implements the page composition, because it drifts
+from the public one. Do not rewrite the templates to read projected props
+either, because that orphans the site's data layer. Either one needs the user's
+say-so. The overlay works for any CMS, not only Contentful.
+
+Locales: one page per entry × locale, following
+`https://docs.avocadostudio.dev/integration/multilingual`. The full Contentful
+walkthrough, including a complete publish handler, is
+`https://docs.avocadostudio.dev/integration/contentful`.
+
 ## Verify
 
 Report all of these as numbers, not as "it works":
@@ -200,6 +320,8 @@ Report all of these as numbers, not as "it works":
    its own inverse.
 4. The coverage figures from `avocado-blocks` — the table gives the manifest,
    the renderers still have to carry the markers.
+5. On Contentful, whether `publishEntries` refused, and which entries it named.
+   A refusal there is the policy working, not a bug to route around.
 
 ## What not to do
 
@@ -210,3 +332,7 @@ Report all of these as numbers, not as "it works":
 - Do not skip `roundTrip` because the fixtures pass. Fixtures are how these bugs
   got shipped.
 - Do not report success on a publish diff nobody read.
+- Do not set `onUnpublishedChanges: "publish"` without the user's say-so. It
+  takes other people's drafts live.
+- Do not declare `localized` in a Contentful table; read `localizedFields` from
+  the space.

package/skills/avocado-integrate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: avocado-integrate
-description: Wire Avocado Studio into a Next.js site that already exists — its own components, its own content or CMS, its own routes. Use when adding chat-driven editing to a real site rather than scaffolding a demo.
+description: Wire Avocado Studio into a Next.js or Astro site that already exists — its own components, its own content or CMS, its own routes. Use when adding chat-driven editing to a real site rather than scaffolding a demo, on Next.js 15–16 (App Router) or Astro 5+.
 ---
 
 # Adding Avocado to a site that already exists
@@ -11,50 +11,161 @@ wrote without saying so.**
 
 Work on a branch. Produce a diff the user reviews.
 
-## 1. Survey, and report before touching anything
+The steps are the same for both frameworks. Where they differ, a step has a
+**Next.js** and an **Astro** branch; follow the one step 1 found and skip the
+other.
 
-Answer these from the repo, not from assumption, and tell the user the answers:
+## 1. Survey, and report before touching anything
 
-- **Next version and router.** 15 or 16; App Router or Pages. Pages Router is
-  not supported — stop and say so.
-- **Where content lives.** A JSON file, a local CMS module, Contentful, Sanity,
+Answer these from the repo, not from assumption, and tell the user the answers.
+
+**The toolchain — record it before the first install.**
+
+- **Framework and version.** Next.js 15 or 16 on the App Router, or Astro 5+.
+  Pages Router is not supported — stop and say so. An older major (Next 14,
+  Astro 3/4) is an upgrade *before* this job, not during it; an archived
+  starter template is the same, plus nobody upstream to ask. Say which, and
+  how big the upgrade looks.
+- **Node version** (`node -v`) against the project's `engines` field.
+- **Package manager**, from the lockfile, and **corepack state**: a
+  `packageManager` field here or in a parent directory's `package.json` pins
+  one, and with corepack strict every other manager's command fails. Write down
+  the exact install command that works *before* running it, including any
+  `COREPACK_ENABLE_STRICT=0` it needs.
+- **Free disk** (`df -h .`) against what the install adds: `site-sdk` and its
+  dependencies are small; library mode's `@avocadostudio-ai/orchestrator-core`
+  adds about 66 MB. An install that fills the disk takes every tool down with
+  it, including the one you would use to recover — stop and say so if there is
+  not comfortably more free than that.
+
+**The content.**
+
+- **Where content lives.** A JSON file, a local module, Contentful, Sanity,
   Strapi, Storyblok, something bespoke. Name the module that reads it.
-- **What renders a page today.** Usually a catch-all route plus a renderer that
-  switches on a block/section type. Name both files.
+- **Whether the CMS already holds the content model** the site queries. A
+  template that ships queries but no model (Contentful's Next.js blog starter
+  is one) renders nothing until the model and seed exist, and that is a job of
+  its own. Check every page after seeding, not only the home page.
+- **Locales.** If the CMS reports more than one locale, read
+  [Multilingual content](https://docs.avocadostudio.dev/integration/multilingual)
+  before designing anything — one editable page per (entry × locale), and four
+  rules that stop the round trip corrupting content. Either way, note the
+  locale list: step 3 declares it.
+
+**What renders, section by section.**
+
+- **The routes, and the components each one renders**, in order, for every
+  route that serves content. Name the files.
+- **Map one block per rendered section by default** — even when several
+  sections read the same CMS entry. A blog post that is one entry rendered as
+  `ArticleHero`, `ArticleContent` and `ArticleTileGrid` is three blocks, not
+  one: a single `pageBlogPost` block makes a click anywhere select the whole
+  post and the panel show every field at once, and the first person to open the
+  Studio asks why. Merge sections only when they really are one visual unit.
+  Sections the template always draws in the same order get `fixed: true`.
+- **Which sections are site-wide** — a header, footer, business details or CTA
+  rendered on every page from one source. Each becomes one `shared: true` block,
+  not one block per page.
 - **Which components are content-bearing**, and what their props are called.
-- **Which route files exist**, and which of them serve URLs the content also
-  describes.
-- **The package manager**, from the lockfile.
 
-If the site already renders from a list of typed sections with props, this is a
-short job. If content is embedded in JSX, it is a long one — say that before
-starting, not halfway through.
+**Known blockers — look for each one and report what you found.**
+
+- **Frame headers.** `X-Frame-Options` or a CSP `frame-ancestors` that does not
+  include the editor's origin blocks the editor frame. On Next, `withAvocado`
+  writes framing headers for editor requests; if the site sets its own, pass
+  `withAvocado(config, { framing: false })` and add the editor origins to the
+  site's `frame-ancestors` yourself.
+- **An existing CMS live-preview SDK.** Contentful's
+  `ContentfulLivePreviewProvider` throws "The current origin is not supported"
+  when framed by anything but `app.contentful.com` —
+  `enableInspectorMode={false}` does not skip that check. In the layout Avocado's
+  preview uses, pass `targetOrigin={[editorOrigin]}`, or do not mount the
+  provider on editor renders. Sanity's and Storyblok's bridges have the same
+  shape of problem.
+- **Existing `draftMode()` use** (Next). Next has one draft cookie,
+  `__prerender_bypass`, and Avocado's rewrite keys on it by default — so every
+  preview request of the site's own CMS preview gets rewritten into Avocado's.
+  Stop keying on the shared cookie: `createEditorProxy({ draftCookie: false })`
+  (or `createEditorMiddleware` on Next 15) rewrites on `__editor=1` alone, or
+  pass Avocado's own session cookie, `draftCookie: "editor_draft_session"`, as
+  the Contentful blog integration did. Either way, internal links rendered on
+  an editor request must carry the editor query, since the shared cookie no
+  longer does it for them.
+- **A CSS reset that strips rich text.** Tailwind's preflight sets
+  `list-style: none` and flattens headings, so a bulleted list renders as plain
+  paragraphs — invisible until real content has a list in it. If the site
+  renders rich text inside a reset, add a `.rich-text` class on the container
+  that restores list markers, heading sizes, link underlines and blockquote
+  styling, and use it wherever rich text renders.
+- **Image components that assume the CMS.** An image the editor chooses can be
+  relative or on another host. A bare `new URL(url)`, a CDN-only loader or a
+  blur placeholder built from the CMS's image API crashes on it. Note every
+  such component; step 3 makes it tolerant.
 
-If the site is reachable at a URL, run `npx avocado-scope <url>` on two or
-three of its pages first. It reports how many sections each page has and what
-each would become as blocks, without installing or writing anything, and it is
-the fastest way to tell the user how large this job is before agreeing to it. A
+If the site already renders from a list of typed sections with props, this is a
+short job. If content is embedded in JSX or templates, it is a long one — say
+that before starting, not halfway through — and read
+[File-backed sites](https://docs.avocadostudio.dev/integration/file-backed-sites)
+before step 3. It is the recipe for that case: the copy moves into one JSON
+file per page plus a `global.json`, the site's own data files stay the source of
+truth, the markup and styles stay as they are, and a publish is a clean git
+diff.
+
+If the site is reachable at a URL, run
+`npx -p @avocadostudio-ai/migration-sdk avocado-scope <url>` on two or three of
+its pages first (`--allow-localhost` when the URL is a local dev server). It
+reports how many sections each page has and what each would become as blocks,
+without installing or writing anything, and it is the fastest way to tell the
+user how large this job is before agreeing to it. A
 page that comes back mostly `RichText` is telling you its structure lives in
-JSX rather than in data.
+markup rather than in data.
+
+## 2. Choose the mode, install and mount
+
+**Split mode or library mode.** Split mode runs the orchestrator as its own
+process (`:4200` by default) and adds only `site-sdk` to the site. Library mode
+mounts the orchestrator inside the site's own app — one process, one deploy —
+and adds `@avocadostudio-ai/orchestrator-core`, about 66 MB of dependencies.
+Library mode is Next.js only. Say which you chose and why; on a tight disk or a
+site that must stay lean, split mode is the answer.
 
-## 2. Install and mount
+### Next.js
 
 ```bash
 npm install @avocadostudio-ai/site-sdk    # or the project's own manager
 ```
 
-Add `@avocadostudio-ai/orchestrator-core` as well if the orchestrator is to run
-inside this app ("library mode") rather than as a separate process.
+Add `@avocadostudio-ai/orchestrator-core` as well for library mode.
 
-**Wrap the Next config.** Whatever shape it is in — `next.config.ts`,
-`next.config.js`, ESM or CommonJS — wrap the existing exported object; do not
-create a second config file beside it:
+**Wrap the Next config — as its last expression, without re-indenting it.**
+Whatever shape it is in — `next.config.ts`, `next.config.js`, ESM or CommonJS,
+a `withPlugins(...)` or `withBundleAnalyzer(...)` chain — leave the body
+exactly as it is and wrap the value that is exported:
 
 ```ts
 import { withAvocado } from "@avocadostudio-ai/site-sdk/next-config"
 export default withAvocado(existingConfig)
 ```
 
+A CommonJS `next.config.js` cannot `require()` the ESM helper, so there the
+last lines become an async export — Next accepts one:
+
+```js
+const existingConfig = withPlugins([/* unchanged */], nextConfig) // what module.exports was
+
+module.exports = async (phase, context) => {
+  const { withAvocado } = await import("@avocadostudio-ai/site-sdk/next-config")
+  const resolved = typeof existingConfig === "function" ? await existingConfig(phase, context) : existingConfig
+  return withAvocado(resolved)
+}
+```
+
+Bind whatever `module.exports` was assigned to a name, unchanged, and wrap that
+name. `withAvocado` takes a config *object*; composers like `withPlugins` return
+a function of the build phase, which is why it is resolved first. Never move `withAvocado` inside an existing chain and re-indent it: on one
+integration that turned a 15-line change into a 121-line diff nobody could
+review. Do not create a second config file beside the first.
+
 **The editor API, as one catch-all route** at
 `app/api/editor/[...path]/route.ts`:
 
@@ -65,6 +176,7 @@ import { registerBlocks } from "@/avocado/blocks"
 
 export const { GET, POST, OPTIONS } = createEditorApiHandler({
   getPages: () => getPages(),
+  getSiteConfig: () => ({ locales: ["en-US", "de-DE"], defaultLocale: "en-US" }),
   registerBlocks,
   blockTypes: ["PricingTier", "LogoWall"],
   onPublish: async (pages, config) => { await publishPages(pages, config); return { ok: true } },
@@ -97,13 +209,70 @@ renders that process's content.
 `createEditorMiddleware` from `@avocadostudio-ai/site-sdk/middleware`; Next 16
 uses `proxy.ts` with `createEditorProxy` from
 `@avocadostudio-ai/site-sdk/proxy`, and its `config` must be a static object
-literal.
+literal. If the site already uses `draftMode()`, pass the `draftCookie` option
+from the survey.
+
+### Astro
+
+Follow [Astro integration](https://docs.avocadostudio.dev/integration/astro-integration)
+for the full contract; this is the order and the traps.
+
+```bash
+npm install @avocadostudio-ai/astro @avocadostudio-ai/site-sdk
+```
+
+- Add the integration to `astro.config.*` — `avocado({ siteId, content,
+  editablePages })` in `integrations`. Wrap nothing else; leave the rest of the
+  config as it is.
+- `content` is a path to a module whose default export is
+  `{ getPages, registerBlocks, blockTypes, onPublish }` (plus `getSiteConfig`
+  for locales). `registerBlocks` is a function called per request, not a module
+  side effect.
+- `editablePages` names the page files the editor may preview. A page built
+  from `getStaticPaths` cannot render on demand; name the pages that can.
+- Every editable page reads `Astro.locals.avocado.getDraftPage()` and falls back
+  to its published content. Skip it and the preview never updates while every
+  other check reports success.
+- On editor renders: turn off `<ClientRouter />` (client-side navigation inside
+  the frame is not draft-aware), keep the editor query on internal links, and
+  set `devToolbar: { enabled: false }` so the toolbar does not cover the footer
+  inside the frame.
+- Check how the installed version reads `DRAFT_MODE_SECRET`, `ORCHESTRATOR_URL`
+  and `PUBLISH_TOKEN`: Astro fills `import.meta.env` from `.env`, not
+  `process.env`. The docs page says what the integration does for you; do not
+  assume.
+- Check the install did not pull `next` or `react` into an Astro project — they
+  are the SDK's Next-only peers. If they arrived, say so rather than shipping
+  them.
+- On Astro 7, `astro dev` started without a terminal daemonises itself and
+  returns: read its output with `npx astro dev logs` and stop it with
+  `npx astro dev stop`, not by redirecting or killing the process you launched.
+  `astro check` there needs `@astrojs/check` and TypeScript 6; TypeScript 7
+  lacks the API it calls.
 
 ## 3. Declare the components
 
 Load `avocado-blocks` and follow it. On an existing site the block names are
 usually already decided by the stored content, which is the case that skill's
-"names that collide with the built-ins" section is about.
+"names that collide with the built-ins" section is about. Use the section map
+from step 1: one block per rendered section.
+
+Declare what the site cannot store, so the editor never offers it:
+`fixed: true` on a section block the template draws in a fixed position, and
+`readOnly: true` with a `readOnlyReason` on a field the publisher refuses to
+write — shared asset alt text, slugs, dates. `avocado-blocks` has the details.
+
+**Site-wide content is one shared block, injected everywhere, written once.**
+For each section step 1 found on every page (header, footer, business info, a
+closing CTA): declare its type `shared: true`; have `getPages()` append the same
+block — same fixed id such as `global-footer`, same props — to every `PageDoc`;
+and have `onPublish` write page-owned blocks to their page and each shared id
+once, from any page carrying it. The orchestrator keeps the draft copies
+identical (an edit on one page reaches all of them, undo reverts all of them),
+so there is nothing to reconcile; do not write per-page copies back. Keep the
+block inside the element a preview refresh swaps (`<main>`, or
+`data-avocado-root` when the footer sits outside it). Details:
+[Site-wide content](https://docs.avocadostudio.dev/integration/cms-adapters#site-wide-content).
 
 **If step 1 found a CMS, load `avocado-cms` as well, and before writing any
 write path.** A CMS-backed site declares one field table and derives the schema,
@@ -114,7 +283,41 @@ perspective read feeding a write path must never be the CMS's visual-editing
 client, whose strings carry invisible stega markers that get written back into
 the dataset as real characters.
 
-## 4. Decide about the page route — carefully
+**Overlay the draft; do not replace the site's data layer.** Keep the site's
+own queries and its components' own prop shapes, and replace only the fields
+Avocado edits — fetch the page the way the site already does, then lay the
+draft's block props over that object (`applyDraft(siteData, blockProps,
+mapping)` from the SDK where the installed version exports it; the same few
+lines by hand where it does not). Do not rewrite public templates to consume
+Avocado's projected props, and do not leave the site's original data module
+orphaned: that makes every production read depend on the lens, for a site whose
+visitors never see the editor.
+
+**On Next with a separate preview route**, that route re-implements the page
+composition the public route already has. Say so in the report and keep the two
+in step — a later change to the public page that is not mirrored makes the
+editor preview a different page from the one visitors get. `npx avocado qa`
+renders both with no draft applied and diffs them.
+
+**Markers need no plumbing.** On Next, the marker helpers from
+`@avocadostudio-ai/site-sdk/markers` emit nothing outside an editor render. On
+Astro, take them from `editorMarkers(Astro)` in `@avocadostudio-ai/astro/markers`
+— Astro's attribute spelling, read off the component's own `Astro`, and `{}` on
+a visitor's render. Either way, call them directly in shared components. Do not
+thread an `editable` prop, or a hand-written conditional `mark()` wrapper,
+through the component tree.
+
+**Make image components tolerate editor-chosen URLs** — relative paths and
+other hosts. Parse defensively (no bare `new URL(url)`), and fall back to a
+plain image when the CMS-specific loader or blur placeholder cannot apply.
+
+**Declare the site's locales** in `getSiteConfig` —
+`{ locales: ["en-US"], defaultLocale: "en-US" }`, as the CMS reports them, even
+when there is only one. The editor forwards them to the orchestrator, and the
+planner then asks before writing text in a language the page is not in, instead
+of translating an `en-US` page into Russian because someone asked it to.
+
+## 4. Decide about the page route — carefully (Next.js)
 
 `createSitePage` from `@avocadostudio-ai/site-sdk/page` is a full page factory:
 it renders registered blocks, supplies `generateStaticParams` and
@@ -140,12 +343,16 @@ so those URLs go on serving the old component and the integration looks dead
 while being perfectly wired. List every route removed and every one left, with
 the reason.
 
+On Astro the site always renders itself; this step is `getDraftPage()` in each
+editable page, from step 2.
+
 ## 5. Keep the public bundle clean
 
-Import the attribute helpers from `@avocadostudio-ai/site-sdk/markers`. Check
-the First Load JS before and after: an unchanged number is the expected result.
-If it jumped by tens of kilobytes, something on a public page imported from
-`/editor`.
+Import the attribute helpers from `@avocadostudio-ai/site-sdk/markers` (Next)
+or `@avocadostudio-ai/astro/markers` (Astro). Check the public JavaScript before
+and after: an unchanged number is the expected result. On Next, if the First
+Load JS jumped by tens of kilobytes, something on a public page imported from
+the SDK's editor entry — never import it there. On Astro, check the preview bridge is not in the script every visitor downloads.
 
 ## 6. Register the site with the orchestrator
 
@@ -160,22 +367,29 @@ npx avocado-register --name "My Site" --orchestrator http://localhost:3000/api/a
 single most common way this step goes wrong: it either cannot connect, or it
 registers against whatever else is on that port.
 
-The command does two separable things. Locally, it generates a
-`DRAFT_MODE_SECRET` into `.env.local` if there is not one and fills in
-`NEXT_PUBLIC_DEFAULT_SITE_ID`, `NEXT_PUBLIC_SITE_NAME` and
-`NEXT_PUBLIC_EDITOR_ORIGIN` — that half always runs. Then it POSTs the site
-config to `/sites/register` and writes `ORCHESTRATOR_URL` once that POST has
-been answered, because an address nothing replied at is a guess. Other flags:
-`--id`, `--port`, `--secret`, `--session`, `--purpose`, `--preview-url`,
-`--token`.
+The command detects the framework and package manager. It POSTs the site
+config and the draft secret (`--secret`, else `DRAFT_MODE_SECRET` from `.env` or
+`.env.local`, else a generated one) to `/sites/register`, and the orchestrator
+answers whether that secret matches its own. Then it writes the env file the
+framework reads — `.env.local` with `DRAFT_MODE_SECRET`, `ORCHESTRATOR_URL` and
+the `NEXT_PUBLIC_*` names on Next; `.env` with `DRAFT_MODE_SECRET`,
+`ORCHESTRATOR_URL` and `AVOCADO_SITE_ID` on Astro. Other flags: `--id`,
+`--port`, `--session`, `--purpose`, `--preview-url`, `--token`.
+
+**If it stops on a secret mismatch, it wrote nothing.** The editor sends its
+secret to the site with every preview, and a site holding a different one shows
+published content. Get the orchestrator's value — for a standalone orchestrator
+run from an Avocado checkout, `DRAFT_MODE_SECRET` in that checkout's `.env` —
+ask the user for it if you cannot read it, and re-run with `--secret <value>`.
+Do not generate or invent one.
 
 If it reports that it could not reach an orchestrator, that is a report and not
-a failure — it exits 0 and the local half has already happened. Re-run with the
-right `--orchestrator` to finish the registry entry. Either way, do not register
-by hand-editing `.env.local`.
+a failure — it exits 0 and the env file has still been written, with a secret it
+could not check. Re-run with the right `--orchestrator` to finish the registry
+entry. Either way, do not register by hand-editing the env file.
 
-**One `siteId`, spelled identically in three places:** `createSitePage` (or
-whatever supplies the page), the `createOrchestrator` mount, and
+**One `siteId`, spelled identically everywhere:** `createSitePage` or the Astro
+integration's `siteId`, the `createOrchestrator` mount, and
 `avocado-register --id`. When they disagree the page asks for a draft session
 the orchestrator never seeded, which looks like the editor showing published
 content for no reason.
@@ -189,22 +403,26 @@ printed `The site is NOT registered`; say which URL it tried.
 
 Do all of these and report the figures:
 
-1. `next build` succeeds, and the route list still shows the site's own pages.
+1. The production build succeeds (`next build` / `astro build`), and the route
+   list still shows the site's own pages.
 2. `GET /api/editor/blocks` lists exactly the site's types, with the expected
    `fields` and `listFields`.
 3. **Both coverage figures**, from `@avocadostudio-ai/site-sdk/coverage`:
    `editableCoverage` per page and `panelCoverage` overall. The target is 100%
    editable coverage on every page and zero panel findings. If you cannot reach
    it, list every remaining gap with the block type and the field path — do not
-   quietly stop. Run it against `next dev` through the editor path: markers are
-   emitted only on an editor render, so a production build reports zero and
-   reads exactly like an integration that marks nothing.
+   quietly stop. Run it against the dev server through the editor path: markers
+   are emitted only on an editor render, so a production build reports zero and
+   reads exactly like an integration that marks nothing. That is `next dev` or
+   `astro dev` with `?__editor=1&siteId=…`, and each marked block's `props` set
+   from `GET /api/editor/pages` before `editableCoverage` runs — without them an
+   optional field that is empty is still counted as a gap.
 4. A page still renders the site's own markup — diff the HTML against the
    pre-integration build if you can.
-5. Every migrated page is served by the catch-all and not by a leftover route
-   file: its HTML under `next dev` carries `data-block-id`. "The URL still
-   works" does not prove this — a shadowing route makes it work by serving the
-   old component.
+5. Every migrated page is served by the route you meant and not by a leftover
+   route file: its HTML on an editor render carries `data-block-id`. "The URL
+   still works" does not prove this — a shadowing route makes it work by
+   serving the old component.
 6. An unknown slug still answers a real 404, and each page has its own
    `<title>` and description.
 
@@ -221,11 +439,48 @@ hand-written — check them rather than assuming the handler did:
 
 No `DRAFT_MODE_SECRET` or `PUBLISH_TOKEN` value appears in any committed file.
 
+## 8. QA — the integration is not done until this passes
+
+Type-check, build and `curl` are where the checks above stop, and every problem
+found after hand-off on the integrations this step comes from lived past them:
+in a browser, inside the editor frame, with edited content, or across a schema
+change. So the last step is the one that goes there.
+
+```bash
+npx avocado qa
+```
+
+It runs against the running site and a throwaway orchestrator session, never
+the user's, and writes a JSON report plus a one-screen summary. **Do not report
+the integration as done until it passes.** If it fails, fix what it names and
+run it again; if a check cannot pass on this site, say which one and why, in
+the report, in those words. If the installed version has no `qa` command yet,
+say that too, and do its checks by hand: render every page × locale in an
+iframe on the editor origin and look for uncaught errors, compare the preview
+and public routes with no draft applied, render a rich-text fixture with every
+node type, and publish one page to a scratch environment.
+
+Then do the manual pass — ten minutes in the Studio, with the user if they are
+there — and report each line as checked or not:
+
+- [ ] Clicking each visible section selects a block with a sensible name and
+      only its fields
+- [ ] Fields that cannot be written (asset alt text, slugs, dates) are not
+      offered as editable
+- [ ] A chat edit and a panel edit both update the preview within a few seconds
+- [ ] Rich text in the panel looks like rich text on the page (lists, headings,
+      links)
+- [ ] Asking for a language the site does not have produces a question, not an
+      overwrite
+- [ ] Publishing one page changes only that page in the CMS, and the public site
+      shows it after reload
+
 ## What not to do
 
-- Do not overwrite the user's `next.config`, page route or `globals.css`
+- Do not overwrite the user's framework config, page routes or global styles
   wholesale. Wrap, extend, or ask.
 - Do not rename stored block types to avoid a collision. Register over the name.
+- Do not map a whole CMS entry to one block because it is one entry.
 - Do not declare presentation props to make something editable.
 - Do not add `allowDelete` to get past the publish guard.
 - Do not report success on "it builds."