@avocadostudio-ai/skills 0.17.1 → 0.18.0

package/README.md

@@ -18,7 +18,8 @@ CLAUDE.md          only if absent
 ```
 
 Then ask your agent to add Avocado to the site. It will load `avocado`, which
-routes to one of `avocado-integrate`, `avocado-demo` or `avocado-blocks`.
+routes to one of `avocado-integrate`, `avocado-demo`, `avocado-blocks` or
+`avocado-cms`.
 
 ## Why a package and not a docs page
 

package/dist/index.js

@@ -76,6 +76,7 @@ the job:
 | Wiring Avocado into this site | \`avocado-integrate\` |
 | A demo, or a fresh project | \`avocado-demo\` |
 | Declaring components as editable blocks | \`avocado-blocks\` |
+| Content that comes from a CMS | \`avocado-cms\` |
 
 The rule those skills exist to protect: **a component's props are not editable
 until a schema declares them.** An undeclared prop cannot be reached by any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/skills",
-  "version": "0.17.1",
+  "version": "0.18.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",

package/skills/avocado/SKILL.md

@@ -20,6 +20,7 @@ every path.
 | A Next.js app that already exists, with its own components and content | `avocado-integrate` |
 | 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

package/skills/avocado-blocks/SKILL.md

@@ -102,34 +102,132 @@ Avocado ships twenty built-in types: `Hero`, `FeatureGrid`, `Testimonials`,
 ## Marking up the renderer
 
 A declared field is editable in the panel. It is editable **in the preview**
-only once the element that renders it carries a marker:
+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.
+
+### The block boundary comes first
+
+```tsx
+import { getPreviewWrapperProps } from "@avocadostudio-ai/site-sdk/markers"
+
+<section {...getPreviewWrapperProps(editorMode, blockId, "PricingTier")}>
+```
+
+Selection is built entirely on `[data-block-id]`: a click in the preview
+resolves through `closest("[data-block-id]")`, and no match is read as "clicked
+outside any block", which *clears* the selection. Mark fields without this and
+the preview frames, renders and scrolls correctly and deselects on every click
+— which looks exactly like selection mode being switched off. It returns `{}`
+when `editorMode` is false, so the published page renders the markup it
+rendered before.
+
+### Then each field
 
 ```tsx
 import { editableProps } from "@avocadostudio-ai/site-sdk/markers"
 
-export function PricingTier({ blockId, name, blurb }) {
+export function PricingTier({ blockId, name, blurb, photoUrl }) {
   return (
-    <section>
-      <h3 {...editableProps(blockId, "name")}>{name}</h3>
-      <p {...editableProps(blockId, "blurb")}>{blurb}</p>
+    <section {...getPreviewWrapperProps(editorMode, blockId, "PricingTier")}>
+      <h3 {...editableProps("name")}>{name}</h3>
+      <p {...editableProps("blurb", { kind: "richtext" })}>{blurb}</p>
+      <div {...editableProps("photoUrl", { kind: "image" })}>
+        <img src={photoUrl} alt="" />
+      </div>
     </section>
   )
 }
 ```
 
-Import from `/markers`, never from `/editor` — see the rule in the `avocado`
-skill about the public bundle.
+The signature is `editableProps(path, { label?, kind? })` — **one path, then
+options**. It is not `editableProps(blockId, field)`: the block id belongs to
+the wrapper above, and passing it here marks a field literally named after the
+id.
+
+- **The path is the same grammar an operation uses** — `title`,
+  `cards[0].title`, `links[0].children[1].label` — because it is the same path.
+  What the overlay reads here is what it sends back as the field to patch.
+- **Pass `kind`.** Without it the overlay guesses an image from the prop name
+  against Avocado's own naming (`imageUrl`, `*.src`), so a field called
+  `photoUrl` or `heroSrc` gets a picker in the property panel and no button in
+  the preview, with no error on either side. Pass the same word the manifest
+  uses and the guess never runs.
+- **For an image, mark the wrapper, not the `<img>`.** The overlay appends its
+  Change button *into* the marked element, and nothing can be appended into an
+  `<img>`.
+- **The marker goes on the element that renders the text**, not on its wrapper.
+
+### Rows drawn by their own component need a scope
+
+The path is scoped from the block down, which a renderer can only write if it
+knows where it sits. That holds while one component draws the whole block and
+stops the moment a list row is a component of its own: the child knows it has a
+`question` and cannot know it is `items[3]`.
+
+```tsx
+import { editableScopeProps } from "@avocadostudio-ai/site-sdk/markers"
+
+<div className="flex flex-col gap-6">
+  {props.items.map((item, i) => (
+    <div key={item.id} {...editableScopeProps(`items[${i}]`, { display: "contents" })}>
+      <FaqRow item={item} />   {/* marks a bare "question"; needs no prefix */}
+    </div>
+  ))}
+</div>
+```
+
+Forgetting the scope is silent and **wrong**, not silent and absent: the child
+marks a bare `question`, the overlay resolves it against the enclosing block,
+and an edit to a headline inside a column patches a prop the section does not
+have. Be systematic — every renderer, every field.
+
+Pass `{ display: "contents" }` whenever the wrapper exists only to carry the
+scope. Without it the wrapper becomes the flex or grid item and the layout the
+rows had silently becomes the layout of a column of wrappers: gaps land in
+different places, `align-items` applies to the wrong box, and a grid's rows stop
+being the grid's children at all. Leave it off when the wrapper is one you were
+going to render anyway — a row that already has an `<li>` or a card `<div>`
+should carry the scope on that rather than gain a second element to hold it.
+
+Scopes nest and compose outermost first. A block boundary ends the composition,
+so a scope outside a block never reaches into it.
 
 Two things this costs on a real site, so plan for them: subcomponents factored
-for rendering often do not know their own position and need a path argument
-threaded in, and the marker has to go on the element that actually renders the
-text, not its wrapper.
+for rendering often do not know their own position and need either a scope
+wrapper or a path threaded in, and marking up a design system is the long pole
+of the whole integration.
 
-## Verify on a number
+## Verify on numbers
+
+`@avocadostudio-ai/site-sdk/coverage` exports both halves. Run both and report
+the figures — "it builds" is not a result, because a site can build perfectly
+with every field unreachable.
+
+```ts
+import {
+  extractMarkedBlocks, editableCoverage, formatEditableCoverage,
+  panelCoverage, formatPanelCoverage,
+} from "@avocadostudio-ai/site-sdk/coverage"
+```
 
-`@avocadostudio-ai/site-sdk/coverage` measures which declared fields a rendered
-page actually marks. Run it and report the figure. "It builds" is not a result:
-a site can build perfectly with every field unreachable.
+- **`editableCoverage`** reports `marked/expected` — of the fields the manifest
+  declares, how many the rendered page actually carries a marker for.
+- **`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
+  built-ins.
+
+**Target: 100% editable coverage on every page, and zero panel findings.** If
+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
+`http://localhost:3000//` and measures nothing.
 
 Cross-check the manifest directly too — `GET /api/editor/blocks` should list
 exactly the site's types, with the expected `fields` and `listFields` on each.

package/skills/avocado-cms/SKILL.md

@@ -0,0 +1,212 @@
+---
+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.
+---
+
+# Editing a CMS through Avocado
+
+Read the `avocado` skill first. Load this once the survey in `avocado-integrate`
+has established that content comes from a CMS rather than from files.
+
+The job is one declaration, not four. A CMS-backed integration has to agree
+about the same fields in four places — the Zod schema, the panel metadata, the
+projection out of the CMS, and the merge back into it. Written by hand they
+drift, and every way they drift is silent. Declare a **field table** and derive
+all four.
+
+**Writes go back into somebody's production content.** More of this page is
+about not corrupting it than about making it work, and that ratio is correct.
+
+## 1. The table
+
+Key it by the CMS's own name for each type — `hero_section`, not
+`SiteHeroSection`. `BlockType` is a free string, and one name across the CMS,
+the manifest and a publish diff makes the adapter an identity map rather than a
+translation nobody can grep for.
+
+```ts
+// avocado/table.ts
+import type { FieldTable } from "@avocadostudio-ai/site-sdk/lens"
+
+export const TABLE: FieldTable = {
+  hero_section: {
+    displayName: "Hero",
+    topLevel: true,
+    fields: {
+      title: { kind: "text" },
+      body: { kind: "richtext" },
+      background_image: { kind: "image", label: "Background" },
+      cta_link: { kind: "link" },
+      alignment: { kind: "enum", options: ["left", "center"] },
+      anchor: { kind: "text", localized: false },
+      buttons: { kind: "list", of: ["button"] },
+    },
+  },
+  button: {
+    displayName: "Button",
+    topLevel: false,
+    fields: { label: { kind: "text" }, variant: { kind: "enum", options: ["solid", "outline"] } },
+  },
+}
+```
+
+- **`topLevel: false` for row types.** A card or a button is declared so the
+  panel can draw it and the merge can construct it, and must never appear in the
+  block picker.
+- **A list is `of` or `itemFields`, never both.** `of` names child types that
+  are their own documents and carry their own type key; `itemFields` describes a
+  row that is a plain object. Every type named in `of` must itself be in the
+  table, and the pack must supply a `rowTypeKey`.
+- **A field the table does not declare is invisible to Avocado and untouched by
+  it.** It never reaches the planner or the panel, and it survives every publish
+  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.
+- **`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.
+
+## 2. Register it with `registerLens`, not `registerFieldTable`
+
+```ts
+// avocado/lens.ts
+import { createLens, registerLens } from "@avocadostudio-ai/site-sdk/lens"
+import { storyblokPrimitives, storyblokLocale } from "@avocadostudio-ai/site-sdk/lens/storyblok"
+import { TABLE } from "./table"
+
+export const lens = createLens({
+  table: TABLE,
+  locale: storyblokLocale("de", ["de", "en", "fr"]),
+  primitives: storyblokPrimitives(),
+})
+
+registerLens(lens)
+```
+
+Sanity is the same with `sanityPrimitives()` and `sanityLocale(…)` from
+`@avocadostudio-ai/site-sdk/lens/sanity`.
+
+**Prefer `registerLens(lens)`.** The older two-call form —
+`registerFieldTable(TABLE, { primitives })` beside `createLens({ …, primitives })`
+— is two declarations that have to agree, and when they disagreed about what an
+image field's two props are called, the panel drew `image` / `image_alt` while
+the projection emitted `imageUrl` / `imageAlt`, and every image on the site was
+both invisible and uneditable with nothing erroring. `registerLens` takes the
+table *and* the primitives off the lens, so it cannot disagree with itself.
+
+`registerFieldTable` now refuses a table that declares an image when no image
+naming was given, so the old shape fails loudly rather than silently. It remains
+correct for a table with **no lens** — a site registering blocks without
+projecting a CMS through them. If you are writing `createLens`, use
+`registerLens`.
+
+For a CMS with no pack, write the primitives yourself — do not skip the table
+and hand-roll a projection. A pack supplies the codecs, the image naming, the
+row id and type keys, and the locale lens.
+
+## 3. Read and write through the lens
+
+```ts
+const props = lens.project(doc, "hero_section", "fr")
+const { doc: next, changed, warnings } = lens.merge(doc, editedProps, "hero_section", "fr")
+```
+
+**`merge` takes the LIVE CMS document as its source**, never a snapshot Avocado
+holds. That is what makes every undeclared field survive by construction.
+Preserve the property. If you find yourself writing a whole document out of
+Avocado props, stop and ask the user.
+
+Two write rules govern every field, and neither was reasoned out from the
+shapes — both came from running a projection through its own inverse over a real
+dataset:
+
+- **Unchanged means untouched.** A CMS with per-language fallback resolves a
+  missing translation to the default language: correct on screen, a lie in
+  storage. Merge a projection back wholesale and every fallback becomes a real,
+  fabricated translation — dozens per publish, each identical to what the page
+  already showed, so nothing looks wrong.
+- **Empty means absent.** Writing `""` into a slot that had no value for this
+  language is a no-op on screen and a diff in the document, so a publish that
+  touched one field reports every page as modified.
+
+A **`reference`** field is a pointer, not a link. The href is a *render* of it —
+the same stored reference serves `/faq` and `/fr/faq` — so a projection can
+never be its own inverse, and writing the rendered href back replaces the
+reference with a hard-coded URL that stops following renames. Declare it
+`reference`, not `link`.
+
+## 4. Prove the round trip before anyone publishes
+
+```ts
+const { clean, fields, warnings } = lens.roundTrip(doc, "hero_section", "fr")
+```
+
+Project, merge the projection straight back, and report what moved. **Nothing
+should.** A non-empty `fields` is a codec that is not the inverse of itself for
+some value in *this* dataset — invisible in the editor, harmless in the preview,
+and visible later as a publish wanting to rewrite documents nobody opened.
+
+Run it over **real content, not fixtures**, across every type in the table and
+every language. Every rule above exists because a fixture round-tripped and a
+dataset did not. Report the count of types checked and the fields that moved.
+
+## 5. Never read a write path through a visual-editing client
+
+If the site already uses the CMS's visual-editing tooling — Sanity's
+Presentation tool, Contentful's Content Source Maps, the Storyblok bridge — its
+draft client **stega-encodes** every string: hundreds of zero-width characters
+encoding which field produced the text. Invisible everywhere a human looks.
+
+Avocado's path is adapter read → session draft → planner edit → publish diff →
+**write back**, so an encoded string poisons four things at once: the planner
+reasons over text that is mostly invisible padding, the panel shows text that
+looks right and is not, the publish diff compares an encoded string against a
+clean one and reports **every field on the site as changed**, and a real publish
+writes the markers into the dataset as real characters.
+
+The client an integrator reaches for first is the one already lying around, and
+that is the wrong one. Give the adapter a **second, machine-read client** — same
+token, same `perspective: "drafts"`, `stega: false` — and keep the encoded one
+for rendering:
+
+```ts
+const avocadoClient = client.withConfig({ stega: false })
+```
+
+The rule is category-level: **a perspective read that feeds a write path must be
+the machine read, never the visual-editing read.**
+
+## 6. One page per (document × language)
+
+A field-level-i18n CMS stores every language inside one document; Avocado edits
+one page at a time. So the adapter presents one `PageDoc` per document *and*
+language, and the lens is told which language it is projecting. Keep the
+language in the page id and slug so a publish can route the merge back to the
+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.
+
+## Verify
+
+Report all of these as numbers, not as "it works":
+
+1. `lens.roundTrip` clean over real content — how many types and languages, and
+   every field that moved.
+2. `GET /api/editor/blocks` lists exactly the table's `topLevel` types, with the
+   `fields` and `listFields` the table implies.
+3. A publish diff on an untouched page is **empty**. A diff that reports
+   everything changed is the stega symptom in section 5, or a codec that is not
+   its own inverse.
+4. The coverage figures from `avocado-blocks` — the table gives the manifest,
+   the renderers still have to carry the markers.
+
+## What not to do
+
+- Do not hand-write the projection or the merge beside a table. Derive both.
+- Do not pass the site's visual-editing client to the adapter.
+- Do not write a whole document back from Avocado props.
+- Do not declare a `reference` as a `link`.
+- 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.

package/skills/avocado-integrate/SKILL.md

@@ -105,6 +105,15 @@ 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.
 
+**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,
+the panel metadata, the projection and the merge from it, rather than
+hand-writing four things that have to agree. That skill also carries the rules
+that stop a publish corrupting the user's content — chief among them that a
+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
 
 `createSitePage` from `@avocadostudio-ai/site-sdk/page` is a full page factory:
@@ -138,17 +147,79 @@ 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`.
 
-## 6. Verify on numbers
+## 6. Register the site with the orchestrator
+
+With the user's dev server running, from the project directory:
+
+```bash
+npx avocado-register --name "My Site" --orchestrator http://localhost:3000/api/avocado
+```
+
+**Pass `--orchestrator`.** The default is `http://localhost:4200`, which is the
+*standalone* server and not what a library-mode project runs. Omitting it is the
+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`.
+
+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`.
+
+**One `siteId`, spelled identically in three places:** `createSitePage` (or
+whatever supplies the page), 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.
+
+Registration is optional in library mode — the mount already knows the one site
+it is in and reports it from `GET /sites`. What registration adds is the name,
+preview URL and purpose in the registry. Do not report the step as done if it
+printed `The site is NOT registered`; say which URL it tried.
+
+## 7. Verify on numbers
 
 Do all of these and report the figures:
 
 1. `next build` succeeds, 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. The field coverage figure from `@avocadostudio-ai/site-sdk/coverage`.
+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.
 4. A page still renders the site's own markup — diff the HTML against the
    pre-integration build if you can.
-5. An unknown slug still answers a real 404.
+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.
+6. An unknown slug still answers a real 404, and each page has its own
+   `<title>` and description.
+
+And the four security seams, which are the reason the routes are not
+hand-written — check them rather than assuming the handler did:
+
+- `GET /api/editor/draft?secret=<secret>&redirect=/` is a 307 and sets the
+  draft cookie.
+- The same call with a wrong secret is rejected.
+- The same call with `redirect=https://evil.example` does **not** redirect
+  off-site.
+- `POST /api/editor/publish` with `{"pages":[]}` answers 409 and leaves the
+  content store untouched.
+
+No `DRAFT_MODE_SECRET` or `PUBLISH_TOKEN` value appears in any committed file.
 
 ## What not to do