@avocadostudio-ai/orchestrator-core 0.3.0 → 0.3.2

package/dist/agent/sites-agent-tools.js

@@ -19,7 +19,7 @@ import { scopedSessionKey, setPage, bumpVersion, getSiteConfig, setSiteConfig }
 import { listImages as listGdriveImages, downloadImage as downloadGdriveImage, isGdriveConfigured, resolveGdriveFolderId, fileNameToAlt, } from "../image/gdrive-client.js";
 import sharp from "sharp";
 import { sanitizeSiteId, monorepoRoot, findAvailablePort, patchGlobalsCssVars, validateAndCorrectProps, fixFooterLinks, analyzeCodebase, cloneRepo, detectSitePort, startAndWaitForDevServer, getDraftModeSecret, packageJson, nextConfigTs, tsconfigJson, postcssConfig, layoutTsx, globalsCss, defaultsTs, editorApiRoute, pageTsx, hybridPageTsx, blocksRegisterTsx, samplePagesJson, defaultLogoSvg, faviconSvg, } from "./sites-agent-shared.js";
-/** Convert a package name like "villa-puravida-web" → "Villa Puravida Web" */
+/** Convert a package name like "coastal-villa-web" → "Coastal Villa Web" */
 function humanizePkgName(name) {
     return name
         .replace(/^@[^/]+\//, "") // strip scope

package/dist/chat/chat-pipeline.js

@@ -1171,6 +1171,7 @@ export async function runChatPipeline(ctx, body, options) {
                         blockId: entry.blockId,
                         blockType: entry.blockType,
                         propName: entry.propName,
+                        allowedProps: entry.allowedProps,
                         plannerSource: source,
                         modelKey,
                         modelUsed

package/dist/chat/hallucination-validator.d.ts

@@ -15,6 +15,12 @@ export type HallucinatedProp = {
     blockId: string;
     blockType: string;
     propName: string;
+    /**
+     * What the block *does* accept. Present so the log line that records a strip
+     * carries the answer next to the question — the integrator who hit this spent
+     * nine minutes proving the block was fine, and this is the line they read.
+     */
+    allowedProps: string[];
 };
 export type HallucinationValidationResult = {
     plan: EditPlan;

package/dist/chat/hallucination-validator.js

@@ -45,6 +45,22 @@ function findBlockType(args) {
     }
     return undefined;
 }
+/*
+ * Does this key read as a visual/presentational one?
+ *
+ * Deliberately a small allow-list of stems rather than a clever rule: the
+ * default has to be "content", because the expensive mistake is telling
+ * somebody their content edit was a styling limitation, not the reverse.
+ */
+const VISUAL_PROP_STEMS = [
+    "color", "colour", "background", "gradient", "animation", "animate", "shadow",
+    "font", "size", "spacing", "padding", "margin", "border", "radius", "opacity",
+    "align", "theme", "style", "variant", "width", "height", "position", "layout"
+];
+function isVisualPropName(prop) {
+    const lower = prop.toLowerCase();
+    return VISUAL_PROP_STEMS.some((stem) => lower.includes(stem));
+}
 function humanBlockName(blockType) {
     const meta = getBlockMeta(blockType);
     return meta?.displayName ?? blockType;
@@ -81,15 +97,33 @@ export function validateAndStripHallucinatedProps(args) {
             if (allowedKeys.has(key))
                 continue;
             delete patchCandidate[key];
-            hallucinatedProps.push({ blockId: op.blockId, blockType, propName: key });
+            hallucinatedProps.push({
+                blockId: op.blockId,
+                blockType,
+                propName: key,
+                allowedProps: [...allowedKeys].sort()
+            });
         }
     }
     if (hallucinatedProps.length > 0) {
-        // Merge duplicates into a single readable note keyed by blockType. We
-        // intentionally avoid echoing the raw prop name back to the user —
-        // doing so is (a) jargon-y (users don't think in prop keys), and (b)
-        // makes the note trivially collide with eval banned-word checks that
-        // try to prove the planner didn't promise the unsupported behavior.
+        /*
+         * Two different events used to share one sentence, and the wrong one was
+         * the default.
+         *
+         * "Some requested styling isn't available" is true when the planner
+         * promised a colour, a gradient or an animation the block has no field
+         * for. It is false — and actively misleading — when the planner simply
+         * used the wrong *name* for a field the block does have under another
+         * name: nothing about that is styling, and the sentence sends the reader
+         * to look at their design system. An integrator lost nine minutes to
+         * exactly that, on a block whose schema, registry and ops path were all
+         * correct.
+         *
+         * So classify the stripped key. A visual key keeps the original wording,
+         * because that is the case it was written for and the evals that check it
+         * are checking that case. A content key gets a sentence that names it,
+         * which is the one piece of information that ends the search.
+         */
         const byBlockType = new Map();
         for (const entry of hallucinatedProps) {
             const bucket = byBlockType.get(entry.blockType) ?? new Set();
@@ -97,9 +131,16 @@ export function validateAndStripHallucinatedProps(args) {
             byBlockType.set(entry.blockType, bucket);
         }
         const noteParts = [];
-        for (const [blockType] of byBlockType) {
+        for (const [blockType, props] of byBlockType) {
             const name = humanBlockName(blockType);
-            noteParts.push(`Some requested styling isn't available on the ${name} block — applied the supported parts.`);
+            const visual = [...props].filter(isVisualPropName);
+            const content = [...props].filter((prop) => !isVisualPropName(prop));
+            if (visual.length > 0) {
+                noteParts.push(`Some requested styling isn't available on the ${name} block — applied the supported parts.`);
+            }
+            for (const prop of content) {
+                noteParts.push(`The ${name} block has no “${prop}” field, so that part wasn't applied.`);
+            }
         }
         const note = noteParts.join(" ");
         const summary = plan.summary_for_user?.trimEnd() ?? "";

package/dist/cms/adapter.d.ts

@@ -51,6 +51,7 @@ export interface CmsPublishContext {
  */
 export type CmsPublishResult = void | {
     ok: true;
+    written?: boolean;
     unsupported?: string[];
 } | {
     ok: false;

package/dist/cms/bootstrap.d.ts

@@ -43,12 +43,36 @@ export interface CmsBootstrapCache {
      * clone and no extra adapter read. Re-reading upstream at publish time would
      * cost 45 sequential CMS calls on the integration that motivated this.
      *
-     * Bounded and best-effort by construction. It is null after a restart that
-     * reloaded the draft from SQLite (the seed never ran), and it is evicted
-     * FIFO past `maxBaselines`, so a caller must treat null as "no baseline
-     * available" and never as "the site was empty".
+     * Bounded and best-effort by construction. A restart that reloads the draft
+     * from SQLite skips the seed but not the baseline — `ensure` re-reads the
+     * adapter for it, which is sound because nothing was published in between —
+     * but it is still evicted FIFO past `maxBaselines`, and still null when the
+     * adapter read failed. A caller must treat null as "no baseline available"
+     * and never as "the site was empty".
      */
     baselineFor(session: string): PageDoc[] | null;
+    /**
+     * Discard this session's draft and seed it again from the adapter.
+     *
+     * `ensure()` is deliberately once-per-session: it exists to not clobber a
+     * draft that SQLite already holds. That is right for every ordinary request
+     * and wrong for the one case an integrator hits constantly while building an
+     * adapter — they change how their projection shapes pages, and the
+     * orchestrator keeps serving the shapes it read before the change. The only
+     * way out used to be deleting `.data/` and restarting the process, which is
+     * a much larger hammer than the problem.
+     *
+     * **This destroys unpublished edits in the session draft**, which is what
+     * makes it a separate, explicitly-requested call rather than something
+     * `ensure()` could decide to do on its own.
+     *
+     * It discards nothing until the adapter has answered: a failed read rejects
+     * and leaves the draft, the baseline and the attempt marker untouched, so a
+     * reseed against a CMS that happens to be down cannot cost anyone their
+     * work. A read that succeeds and returns no pages *is* an answer, and empties
+     * the draft accordingly.
+     */
+    reseed(session: string, adapter: CmsAdapter | null | undefined, log: Logger): Promise<void>;
     /** Test helper — drop all remembered state. */
     reset(): void;
     /** Inspection — number of remembered attempts (post-eviction). */

package/dist/cms/bootstrap.js

@@ -129,7 +129,31 @@ export function createCmsBootstrapCache(opts = {}) {
             return existing;
         const promise = (async () => {
             const draft = getSessionDraft(session);
-            if (draft.size > 0)
+            /*
+             * A draft that is already populated came from SQLite, not from us, and
+             * for a long time that was the end of the matter: seeding was the only
+             * thing this function did, so a loaded draft meant there was nothing to
+             * do. But the seed also produces the publish baseline, and that made the
+             * early return silently disable publishing. The draft survives a
+             * restart, so `ensure` returned here, so `rememberBaseline` never ran, so
+             * `context.published` was `undefined` for the rest of the process's life
+             * — and a publisher written the documented way (diff against the
+             * baseline, refuse when there is none) can then never publish again.
+             * Restarting to fix it is the one thing guaranteed not to.
+             *
+             * So the two jobs are now separate. A loaded draft still skips the seed;
+             * it no longer skips the baseline. Recovering it costs one
+             * `getPages()` — the same call the seed would have made, usually served
+             * from the warm cache — and it is correct to read upstream for it,
+             * because nothing has been published: the CMS still holds exactly the
+             * pre-edit content the lost baseline was a copy of.
+             *
+             * This is the same shape as the `setSessionCapabilities` hoist above.
+             * Anything the seed produces besides the draft has to survive a restart
+             * that reloads the draft.
+             */
+            const seeded = draft.size > 0;
+            if (seeded && baselines.has(session))
                 return; // finally-block records the attempt
             try {
                 const warmed = warmedPages(adapter);
@@ -139,13 +163,17 @@ export function createCmsBootstrapCache(opts = {}) {
                     return;
                 }
                 /*
-                 * Keep the pre-edit copy. The pages are already being cloned into the
-                 * draft, so a baseline for the eventual publish diff costs one more
+                 * Keep the pre-edit copy. When we are also seeding, the pages are
+                 * already being cloned into the draft, so the baseline costs one more
                  * clone and — the point — no second adapter read. Re-reading upstream
                  * at publish time is 45 sequential CMS calls on the integration that
                  * motivated this.
                  */
                 rememberBaseline(session, pages.map((page) => structuredClone(page)));
+                if (seeded) {
+                    log.info({ session, adapter: adapter.id, count: pages.length }, "cms-bootstrap: recovered publish baseline for a draft reloaded from storage");
+                    return;
+                }
                 for (const page of pages) {
                     const copy = structuredClone(page);
                     ensureHeroImageProps(copy);
@@ -174,9 +202,48 @@ export function createCmsBootstrapCache(opts = {}) {
             inFlight.delete(session);
         }
     }
+    async function reseed(session, adapter, log) {
+        if (!adapter)
+            return;
+        setSessionCapabilities(session, resolveCapabilities(adapter, capabilityOverride));
+        // Wait out a seed already in flight, so the discard below cannot land
+        // between that seed's adapter read and its writes and leave half a draft.
+        const existing = inFlight.get(session);
+        if (existing)
+            await existing.catch(() => { });
+        /*
+         * Read before discarding, not after. Clearing the draft and then calling
+         * `ensure` reads well and fails badly: `ensure` swallows an adapter error
+         * and marks the session attempted on the way out, so an adapter that was
+         * merely down turned a stale draft into an empty one that nothing would
+         * ever retry. The caller asked to replace the draft with what the adapter
+         * says; if the adapter says nothing, there is no replacement to make and
+         * the right answer is to leave the session exactly as we found it.
+         *
+         * This deliberately does not consult the warmed list. That list is a
+         * cold-start bridge and may predate whatever change prompted the reseed —
+         * serving it here would return the exact staleness we were asked to clear.
+         */
+        const pages = await adapter.getPages({ perspective: "draft" });
+        const draft = getSessionDraft(session);
+        const discarded = draft.size;
+        draft.clear();
+        for (const page of pages) {
+            const copy = structuredClone(page);
+            ensureHeroImageProps(copy);
+            draft.set(copy.slug, copy);
+        }
+        rememberBaseline(session, pages.map((page) => structuredClone(page)));
+        markAttempted(session);
+        warmEntry = null;
+        bumpVersion(session);
+        schedulePersistState(log);
+        log.info({ session, adapter: adapter.id, discarded, count: pages.length }, "cms-bootstrap: reseeded session draft from the adapter");
+    }
     return {
         ensure,
         warm,
+        reseed,
         baselineFor(session) {
             return baselines.get(session) ?? null;
         },

package/dist/cms/json-file-adapter.js

@@ -2,7 +2,7 @@
 //
 // Smallest possible adapter. Suitable for sites that keep their content as
 // a checked-in JSON array (the shape the orchestrator + blocks already
-// understand). villa-puravida-web's lib/published-content.json is the
+// understand). A consumer site's lib/published-content.json is the
 // canonical example.
 //
 // If `writeOnPublish` is true, onPublish() will overwrite the file with the

package/dist/handler/create-orchestrator.js

@@ -123,7 +123,7 @@ async function buildRuntime(config) {
      * Start the adapter's page read now rather than on the first request.
      *
      * `ensure()` is lazy, so without this the first caller pays for the whole
-     * CMS read: Paintball Arena Bern's adapter is 45 sequential Sanity reads
+     * CMS read: a tri-lingual site's adapter is 45 sequential Sanity reads
      * behind a dev-server compile, and the `whoami` an MCP agent opens with took
      * four minutes — long enough that the host times out and the agent reports
      * the site as down. Fire-and-forget by contract: a failed warm logs and is
@@ -771,20 +771,31 @@ export function createOrchestrator(config = {}) {
              *
              * This is the copy the bootstrap already took, not a fresh read — a
              * second `getPages()` here is 45 sequential Sanity calls on the
-             * integration that motivated it. It is therefore absent after a restart
-             * that reloaded the draft from SQLite, which is why the contract says to
-             * treat undefined as "no baseline" and never as "the site was empty".
+             * integration that motivated it. It used to be absent for the rest of a
+             * process's life after a restart that reloaded the draft from SQLite,
+             * which quietly disabled publishing for any adapter that refuses without
+             * a baseline; `ensure` now recovers it on the first request instead.
+             *
+             * It can still be undefined — the adapter read can fail, and baselines
+             * are evicted FIFO — so the contract is unchanged: treat undefined as
+             * "no baseline available" and never as "the site was empty".
              */
             const published = runtime.bootstrapCache.baselineFor(scopedSession) ?? undefined;
             const context = body.assets || published
                 ? { ...(body.assets ? { assets: body.assets } : {}), ...(published ? { published } : {}) }
                 : undefined;
             let unsupported = [];
+            // Default true: an adapter that does not mention `written` means what
+            // every adapter written before the field existed meant.
+            let written = true;
             try {
                 const result = await runtime.adapter.onPublish(pages, config, context);
                 if (result && typeof result === "object" && Array.isArray(result.unsupported)) {
                     unsupported = result.unsupported;
                 }
+                if (result && typeof result === "object" && result.ok === true && result.written === false) {
+                    written = false;
+                }
                 if (result && typeof result === "object" && result.ok === false) {
                     const message = result.error ?? "adapter.onPublish returned not-ok";
                     runtime.log.warn({ session: scopedSession, adapter: runtime.adapter.id, error: result.error }, "library-publish: adapter.onPublish() returned not-ok");
@@ -810,13 +821,15 @@ export function createOrchestrator(config = {}) {
              * image beside it — that is neither a plain success, which claims the
              * whole edit shipped, nor an error, which claims none of it did.
              */
-            const summary = buildPublishSummary({ changedSlugs: [], removedSlugs: [], totalPages: pages.length, hasDiff: false });
+            const summary = written
+                ? buildPublishSummary({ changedSlugs: [], removedSlugs: [], totalPages: pages.length, hasDiff: false })
+                : `Computed ${pages.length} ${pages.length === 1 ? "page" : "pages"} — nothing written`;
             record(true, unsupported.length > 0
                 ? `${summary} ${unsupported.length} change${unsupported.length === 1 ? "" : "s"} could not be published.`
                 : summary);
             return jsonResponse({
                 ok: true,
-                written: true,
+                written,
                 count: pages.length,
                 ...(unsupported.length > 0 ? { unsupported } : {})
             }, { status: 200, cors });
@@ -872,10 +885,24 @@ export function createOrchestrator(config = {}) {
             await runtime.ready;
             const session = url.searchParams.get("session") ?? undefined;
             const siteId = url.searchParams.get("siteId") ?? undefined;
-            const slug = url.searchParams.get("slug") ?? undefined;
-            if (!session || !slug) {
+            const slug = url.searchParams.get("slug");
+            if (!session || slug === null) {
                 return jsonResponse({ error: "session and slug are required" }, { status: 400, cors });
             }
+            /*
+             * `?slug=` is a parameter that is present and empty, and answering
+             * "required" sends the integrator to look for a bug in their query
+             * string. What it actually means is that their projection emitted bare
+             * paths: a slug is a leading-slash path and the home page's is `"/"`.
+             * Every other bare slug resolves by string equality, so the home page is
+             * the only one that fails, and it fails as the site's own 404 rendered
+             * inside the editor iframe — which reads as "my site is broken".
+             */
+            if (slug === "") {
+                return jsonResponse({
+                    error: 'slug must not be empty: a page slug is a path beginning with "/", and the home page is "/" rather than ""'
+                }, { status: 400, cors });
+            }
             const scopedSession = scope(session, siteId);
             await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
             const page = getPage(scopedSession, slug);
@@ -915,9 +942,25 @@ export function createOrchestrator(config = {}) {
                 })
             }, { status: 200, cors });
         }
-        // Editor bootstrap probe. In library mode the adapter is the source of
-        // truth (already seeded by ensure), so this is effectively a confirm — we
-        // don't clobber the draft with the posted pages.
+        /*
+         * Editor bootstrap probe. In library mode the adapter is the source of
+         * truth (already seeded by ensure), so this is effectively a confirm — we
+         * don't clobber the draft with the posted pages.
+         *
+         * `force` was accepted by the standalone orchestrator and silently dropped
+         * here: the body was read as `{session, siteId}` and nothing else, so a
+         * caller asking to re-read the adapter got the cached page list back with
+         * a 200 and the word "bootstrapped" on it. That is worse than refusing,
+         * because the shape an integrator is in when they send it is "I changed my
+         * projection and the orchestrator is still serving the old shapes" — and
+         * the answer looks like confirmation that it re-read. The documented
+         * escape was deleting `.data/` and restarting.
+         *
+         * It now does what it says, including the destructive half: the session
+         * draft is discarded and rebuilt from the adapter, so unpublished edits in
+         * it are lost. `forced` comes back in the response so a caller can tell
+         * which of the two things happened.
+         */
         if (request.method === "POST" && path === "/draft/bootstrap") {
             const runtime = await getRuntime();
             await runtime.ready;
@@ -930,9 +973,31 @@ export function createOrchestrator(config = {}) {
             }
             const body = (raw ?? {});
             const scopedSession = scope(body.session, body.siteId);
-            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const force = body.force === true;
+            if (force) {
+                try {
+                    await runtime.bootstrapCache.reseed(scopedSession, runtime.adapter, runtime.log);
+                }
+                catch (err) {
+                    /*
+                     * A forced reseed reaches the adapter and can fail there, and the
+                     * one thing this route must not do is answer "bootstrapped" when it
+                     * did not bootstrap — that is the failure being fixed, in a new
+                     * costume. The reseed discards nothing before the read succeeds, so
+                     * the draft is intact and saying so is the useful half of the reply.
+                     */
+                    return jsonResponse({
+                        error: "reseed failed: the adapter could not be read",
+                        detail: err instanceof Error ? err.message : String(err),
+                        draft: "unchanged"
+                    }, { status: 502, cors });
+                }
+            }
+            else {
+                await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            }
             const pages = getSessionPages(scopedSession);
-            return jsonResponse({ status: "bootstrapped", count: pages.length, slugs: pages.map((p) => p.slug) }, { status: 200, cors });
+            return jsonResponse({ status: "bootstrapped", forced: force, count: pages.length, slugs: pages.map((p) => p.slug) }, { status: 200, cors });
         }
         // Site config — drives the page-level nav-label + SEO fields shown in the
         // property panel when no block is selected.

package/dist/http/screenshot-actions.d.ts

@@ -19,7 +19,7 @@
  * `/preview-draft` is only the *default*, though, and it was hardcoded — which
  * meant this route worked on sites `create-ai-site-editor` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
- * draft route (Paintball Arena Bern's is `/avocado/<lang>/<slug>`), and the
+ * draft route (one such site's is `/avocado/<lang>/<slug>`), and the
  * screenshot an agent took to check its own work photographed that site's 404
  * page. So the path is declarable: per request, per registered site, or via
  * `createOrchestrator({ draftPath })`.

package/dist/http/screenshot-actions.js

@@ -19,7 +19,7 @@
  * `/preview-draft` is only the *default*, though, and it was hardcoded — which
  * meant this route worked on sites `create-ai-site-editor` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
- * draft route (Paintball Arena Bern's is `/avocado/<lang>/<slug>`), and the
+ * draft route (one such site's is `/avocado/<lang>/<slug>`), and the
  * screenshot an agent took to check its own work photographed that site's 404
  * page. So the path is declarable: per request, per registered site, or via
  * `createOrchestrator({ draftPath })`.

package/dist/nlp/deterministic-planner-suggestions.js

@@ -31,7 +31,7 @@ export function promptFromPropKey(propKey, blockType) {
         return CLARIFICATION_LABELS[propKey];
     const human = blockType ? getPropDisplayName(blockType, propKey) : propKey;
     // Fall back to the registry-declared label so host-app overrides (e.g.
-    // villa's TwoColumn adding `sectionId`) surface as "Edit Section id" rather
+    // a host site's TwoColumn adding `sectionId`) surface as "Edit Section id" rather
     // than leaking the raw camelCase key into the UI.
     return human === propKey ? `Edit ${propKey}` : `Edit ${human.toLowerCase()}`;
 }

package/dist/nlp/plan-normalizer.js

@@ -1,6 +1,135 @@
-import { allowedBlockTypes, declaredDefaultPropsForType, defaultPropsForType as sharedDefaultPropsForType } from "@avocadostudio-ai/shared";
+import { allowedBlockTypes, blockSchemas, declaredDefaultPropsForType, defaultPropsForType as sharedDefaultPropsForType, getBlockMeta } from "@avocadostudio-ai/shared";
 import { extractRouteMentions, firstRouteMention, normalizeRouteCandidate, parseCreatePageRequest } from "./intent-helpers.js";
 // ---------------------------------------------------------------------------
+// Prop-name aliasing, asked of the registry rather than of a literal
+// ---------------------------------------------------------------------------
+/*
+ * Models confuse Avocado's own prop names — `heading` for a section that calls
+ * it `title`, `question`/`answer` for FAQ items that call them `q`/`a`. The
+ * aliases below exist to repair that, and they are worth keeping.
+ *
+ * They were applied by comparing the block type against the literal string
+ * "Hero", which is a name only Avocado's own catalogue has. Every other block
+ * in the world is `!== "Hero"`, so a site that brings its own blocks and names
+ * a text prop `heading` had that prop deleted here and replaced with `title` —
+ * a prop its schema does not have. The ops engine then stripped `title` as a
+ * hallucinated prop, the edit vanished, and the user was told that "some
+ * requested styling isn't available" on their block. Nothing in the chain was
+ * wrong about its own job; the first link was answering a question about a name
+ * instead of about a schema.
+ *
+ * So ask the registry. A rename now requires positive evidence in both
+ * directions: the block cannot take the key the planner used, and can take the
+ * one we would rewrite it to. Every other case — unknown block type, a block
+ * that accepts both, a block that accepts neither — leaves the value alone,
+ * which is the answer that loses no data.
+ */
+function blockAcceptsProp(blockType, prop) {
+    if (!blockType)
+        return false;
+    const meta = getBlockMeta(blockType);
+    if (meta?.fields && prop in meta.fields)
+        return true;
+    // Manifest-registered blocks may carry a schema richer than their derived
+    // meta, so the schema gets the second look rather than the first refusal.
+    const shape = blockSchemas[blockType]?.shape;
+    return Boolean(shape && prop in shape);
+}
+/*
+ * Avocado's own `autoplay` / `loop` / `striped` are string enums ("true" /
+ * "false"), not booleans, so a model that emits a real boolean has to be
+ * coerced. That coercion ran on every block type, and a custom block whose
+ * `loop` is a genuine `z.boolean()` had the string `"true"` written into it —
+ * silently, and only on the chat path, so it looked like a CMS problem.
+ *
+ * Coerce only where the block actually declares the prop as a string enum.
+ */
+const BOOLEAN_ENUM_PROPS = ["autoplay", "loop", "striped"];
+/**
+ * Ask the block's own schema, which is the only thing that actually knows:
+ * rewrite a boolean to `"true"`/`"false"` exactly when the schema rejects the
+ * boolean and accepts the string. A block that takes a real boolean keeps it,
+ * a block that takes either keeps what the planner sent, and an unregistered
+ * type is left alone.
+ */
+function coerceBooleanEnumProps(blockType, props) {
+    const shape = blockSchemas[blockType]?.shape;
+    if (!shape)
+        return;
+    for (const key of BOOLEAN_ENUM_PROPS) {
+        const value = props[key];
+        if (typeof value !== "boolean")
+            continue;
+        const field = shape[key];
+        if (typeof field?.safeParse !== "function")
+            continue;
+        const asString = value ? "true" : "false";
+        /*
+         * Round-trip, not merely "parses". Avocado's own `autoplay` is
+         * `z.enum(["true","false"]).default("false").catch("false")`, and `.catch`
+         * means a boolean parses *successfully* — into the wrong value. Accepting
+         * that as "the block wants a boolean" would leave the silent wrong answer
+         * in place. A schema genuinely wants a boolean only when it gives the
+         * boolean back unchanged.
+         */
+        const asBool = field.safeParse(value);
+        if (asBool.success && asBool.data === value)
+            continue;
+        const asStr = field.safeParse(asString);
+        if (!asStr.success || asStr.data !== asString)
+            continue;
+        props[key] = asString;
+    }
+}
+/** Rename `from`→`to` only when the block demonstrably wants `to` and not `from`. */
+function shouldAliasProp(blockType, from, to) {
+    return !blockAcceptsProp(blockType, from) && blockAcceptsProp(blockType, to);
+}
+/*
+ * The same question for a key inside a list item. `listFields[key].itemFields`
+ * is the declared shape; a block with no declared list metadata answers "no"
+ * to both halves and is therefore left alone.
+ */
+function listItemAcceptsKey(blockType, listKey, itemKey) {
+    if (!blockType)
+        return false;
+    const itemFields = getBlockMeta(blockType)?.listFields?.[listKey]?.itemFields;
+    return Boolean(itemFields && itemKey in itemFields);
+}
+function shouldAliasItemKey(blockType, listKey, from, to) {
+    return (!listItemAcceptsKey(blockType, listKey, from) && listItemAcceptsKey(blockType, listKey, to));
+}
+const ITEM_KEY_ALIASES = {
+    question: "q",
+    answer: "a",
+    testimonial: "quote",
+    review: "quote"
+};
+/**
+ * Apply the list-item aliases to one array prop, block-type aware.
+ * Shared by the `update_props` and `add_block` paths so they cannot drift.
+ */
+function aliasListItems(blockType, listKey, value) {
+    return value.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return item;
+        const entry = item;
+        let changed = false;
+        const mapped = {};
+        for (const [k, v] of Object.entries(entry)) {
+            const alias = ITEM_KEY_ALIASES[k.toLowerCase()];
+            if (alias && !(alias in entry) && shouldAliasItemKey(blockType, listKey, k.toLowerCase(), alias)) {
+                mapped[alias] = v;
+                changed = true;
+            }
+            else {
+                mapped[k] = v;
+            }
+        }
+        return changed ? mapped : entry;
+    });
+}
+// ---------------------------------------------------------------------------
 // Op reordering: create_page must precede ops targeting the same slug
 // ---------------------------------------------------------------------------
 function reorderCreatePageFirst(ops) {
@@ -886,38 +1015,17 @@ export function normalizePlanCandidate(input, args) {
             const patch = raw.patch;
             const targetBlock = args?.currentPage?.blocks.find((b) => b.id === raw.blockId);
             const blockType = targetBlock?.type ?? "";
-            if (blockType !== "Hero" && "heading" in patch && !("title" in patch)) {
+            if ("heading" in patch && !("title" in patch) && shouldAliasProp(blockType, "heading", "title")) {
                 patch.title = patch.heading;
                 delete patch.heading;
             }
-            const itemKeyAliases = { question: "q", answer: "a", testimonial: "quote", review: "quote" };
             for (const [propKey, propVal] of Object.entries(patch)) {
                 if (!Array.isArray(propVal))
                     continue;
-                patch[propKey] = propVal.map((item) => {
-                    if (!item || typeof item !== "object" || Array.isArray(item))
-                        return item;
-                    const entry = item;
-                    let changed = false;
-                    const mapped = {};
-                    for (const [k, v] of Object.entries(entry)) {
-                        const alias = itemKeyAliases[k.toLowerCase()];
-                        if (alias && !(alias in entry)) {
-                            mapped[alias] = v;
-                            changed = true;
-                        }
-                        else {
-                            mapped[k] = v;
-                        }
-                    }
-                    return changed ? mapped : entry;
-                });
+                patch[propKey] = aliasListItems(blockType, propKey, propVal);
             }
             // Block-specific prop key remapping and type coercion (mirrors add_block path)
-            for (const k of ["autoplay", "loop", "striped"]) {
-                if (typeof patch[k] === "boolean")
-                    patch[k] = patch[k] ? "true" : "false";
-            }
+            coerceBooleanEnumProps(blockType, patch);
             if (blockType === "Carousel" && Array.isArray(patch.slides) && !patch.items) {
                 patch.items = patch.slides;
                 delete patch.slides;
@@ -1153,36 +1261,20 @@ export function normalizePlanCandidate(input, args) {
             if (block.props && typeof block.props === "object" && !Array.isArray(block.props)) {
                 const bProps = block.props;
                 const blockType = typeof block.type === "string" ? block.type : "";
-                if (blockType !== "Hero" && "heading" in bProps && !("title" in bProps)) {
+                if ("heading" in bProps && !("title" in bProps) && shouldAliasProp(blockType, "heading", "title")) {
                     bProps.title = bProps.heading;
                     delete bProps.heading;
                 }
             }
-            // Remap list item keys inside add_block props (e.g., question→q, answer→a)
+            // Remap list item keys inside add_block props (e.g., question→q, answer→a),
+            // asking the block's own list metadata rather than rewriting every array.
             if (block.props && typeof block.props === "object" && !Array.isArray(block.props)) {
                 const bProps = block.props;
-                const itemKeyAliases = { question: "q", answer: "a", testimonial: "quote", review: "quote" };
+                const blockType = typeof block.type === "string" ? block.type : "";
                 for (const [propKey, propVal] of Object.entries(bProps)) {
                     if (!Array.isArray(propVal))
                         continue;
-                    bProps[propKey] = propVal.map((item) => {
-                        if (!item || typeof item !== "object" || Array.isArray(item))
-                            return item;
-                        const entry = item;
-                        let changed = false;
-                        const mapped = {};
-                        for (const [k, v] of Object.entries(entry)) {
-                            const alias = itemKeyAliases[k.toLowerCase()];
-                            if (alias && !(alias in entry)) {
-                                mapped[alias] = v;
-                                changed = true;
-                            }
-                            else {
-                                mapped[k] = v;
-                            }
-                        }
-                        return changed ? mapped : entry;
-                    });
+                    bProps[propKey] = aliasListItems(blockType, propKey, propVal);
                 }
             }
             // Block-specific prop key remapping and type coercion
@@ -1190,10 +1282,7 @@ export function normalizePlanCandidate(input, args) {
                 const cProps = block.props;
                 const bt = block.type;
                 // Coerce boolean→string for "true"/"false" enum props (Carousel, Video, Table)
-                for (const k of ["autoplay", "loop", "striped"]) {
-                    if (typeof cProps[k] === "boolean")
-                        cProps[k] = cProps[k] ? "true" : "false";
-                }
+                coerceBooleanEnumProps(typeof bt === "string" ? bt : "", cProps);
                 // Carousel: slides→items
                 if (bt === "Carousel" && Array.isArray(cProps.slides) && !cProps.items) {
                     cProps.items = cProps.slides;

package/dist/ops/ops-engine.js

@@ -423,7 +423,7 @@ function _resolveBlockIndex(blocks, blockId, fuzzyMatches) {
  * Drop an adapter's provenance keys from a block that is being copied.
  *
  * A projected block carries the adapter's answer to "which upstream thing is
- * this", and the adapter routes the write by it: Paintball Arena Bern marks a
+ * this", and the adapter routes the write by it: a field-level-i18n CMS marks a
  * block with `props._sectionId` and publishes anything carrying one into the
  * *shared section document* rather than into the page. Copied verbatim onto a
  * duplicate, the first edit to that duplicate's hero is written back into the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -23,8 +23,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.34.5",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "^0.3.0",
-    "@avocadostudio-ai/shared": "^0.3.0"
+    "@avocadostudio-ai/migration-sdk": "^0.3.2",
+    "@avocadostudio-ai/shared": "^0.3.2"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",
@@ -56,7 +56,7 @@
     "visual-editing"
   ],
   "license": "Apache-2.0",
-  "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/orchestrator-core#readme",
+  "homepage": "https://docs.avocadostudio.dev",
   "bugs": {
     "url": "https://github.com/avocadostudio-ai/avocado/issues"
   },