@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.0

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

@@ -18,7 +18,7 @@ const BLOCK_VISUAL_GUIDE = {
     CTA: { layout: "Centered section with headline, description, and one CTA button", whenToUse: "Drive conversions — sign-up, purchase, contact" },
     FAQAccordion: { layout: "Collapsible question-and-answer list", whenToUse: "FAQ sections, knowledge base summaries" },
     Stats: { layout: "Horizontal row of large numbers with labels", whenToUse: "Social proof, key metrics (e.g. '10K+ Users')" },
-    RichText: { layout: "Freeform markdown/HTML text block", whenToUse: "Long-form content, articles, legal text, any prose" },
+    RichText: { layout: "Freeform prose; the body prop is rendered as markdown", whenToUse: "Long-form content, articles, legal text, any prose" },
     Testimonials: { layout: "Grid of quote cards with author names", whenToUse: "Customer reviews, social proof", confusedWith: "Quote (Quote is a single pull-quote; Testimonials is a grid of many)" },
     TwoColumn: { layout: "Two side-by-side columns with typed child components (heading, paragraph, image, CTA, video, list)", whenToUse: "Mixed content layouts — text beside image, features beside demo" },
     Table: { layout: "Data table with column headers and rows", whenToUse: "Pricing comparisons, feature matrices, structured data" },
@@ -290,7 +290,8 @@ Write the final summary using the format from "Output Formatting" above. This is
 - **Respect scope**: If the user specifies "homepage only" or specific pages, create ONLY those pages. Do NOT create additional pages.${intent === "migrate" ? `
 - **VERIFY custom blocks before bootstrap_pages**: After block-coder finishes, run \`pnpm --filter @ai-site-editor/{siteId} build\` to catch import resolution failures. Also check that \`apps/{siteId}/blocks/register.ts\` contains for EACH custom block: (1) \`import "./{kebab}/schema.ts"\`, (2) \`import { BlockName } from "./{kebab}/renderer.tsx"\` (WITH .tsx extension!), (3) \`registerCustomRenderer("BlockName", BlockName)\`. If the build fails or any import is missing, tell block-coder to fix it before proceeding.
 - **CRITICAL: Preserve original text exactly.** Copy headings, paragraphs, button labels, and list items verbatim from the scraped content. Do NOT paraphrase, translate, summarize, or rewrite any text. The migrated site must contain the exact same copy as the original. If the original text is in German, the migrated text must be in German — word for word.
-- **Plain text only in block props** — \`description\`, \`subtitle\`, \`body\`, and similar text fields are rendered as plain text, not markdown. Never use markdown syntax (\`**bold**\`, \`_italic_\`, \`# heading\`, \`- list\`) in these fields. Write the text exactly as it appears on the source page without any formatting markers.
+- **Plain text in every prop except the rich-text ones.** Most props — \`description\`, \`subtitle\`, headings, labels — render as plain text, so markdown syntax there shows up literally on the page. Write those exactly as they appear on the source page, with no formatting markers.
+  The exceptions are the props each block contract lists under \`richTextProps\` (RichText \`body\`, FAQAccordion \`items[].a\`, Quote \`quote\`, Tabs \`tabs[].content\`). Those ARE rendered as markdown, so when the source page has bold, italic, links, lists, headings or blockquotes inside a passage of prose, carry that formatting over rather than flattening it — flattening loses structure the original had. Use \`##\`–\`######\` for headings (never a single \`#\`), \`- \` / \`1. \` for lists, \`> \` for quotes, and a blank line between paragraphs.
 - **Navigation**: Extract nav item labels from the original site's \`<nav>\` links — use the EXACT original text (e.g. "Über uns" not "About"). Pass as \`navLabels\` in \`bootstrap_pages\`. If the original nav has dropdowns (parent → children), pass as \`navGroups\`.
 - **Site logo**: Download the original site's logo image and pass the local path as \`siteLogo\` in \`bootstrap_pages\`.
 - **Custom blocks — use them!** Spawn the **block-coder** subagent when a section needs a layout that standard blocks can't represent well. **NEVER use RichText as a fallback for structured data** — if the source has pricing tiers, event cards, team members, timelines, or any structured/tabular content, you MUST create a custom block. RichText is only for freeform prose.

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

@@ -463,6 +463,7 @@ const nextConfig: NextConfig = {
     "@avocadostudio-ai/site-sdk",
     "@avocadostudio-ai/blocks",
     "@avocadostudio-ai/shared",
+    "@avocadostudio-ai/richtext",
   ],
   images: {
     remotePatterns: [

package/dist/chat/anthropic-planner.js

@@ -1,5 +1,5 @@
 import Anthropic from "@anthropic-ai/sdk";
-import { allowedBlockTypes, editPlanSchema } from "@avocadostudio-ai/shared";
+import { catalogueBlockTypes, editPlanSchema } from "@avocadostudio-ai/shared";
 import { buildIntentParserSystemPrompt, buildPlannerSystemPromptSegments } from "./prompts.js";
 import { GENERATING_IMAGE_PLACEHOLDER, SEARCHING_IMAGE_PLACEHOLDER } from "./chat-pipeline.js";
 import { extractAudienceTarget, fetchImageAsBase64, resolveAttachmentsForLlm, intentSchema } from "../nlp/deterministic-planner.js";
@@ -78,7 +78,7 @@ export async function parseIntentWithAnthropic(args) {
         activeBlockId: args.activeBlockId ?? null,
         activeBlockType: args.activeBlockType ?? null,
         activeEditablePath: args.activeEditablePath ?? null,
-        availableBlockTypes: allowedBlockTypes,
+        availableBlockTypes: catalogueBlockTypes(),
         blocks: args.currentPage.blocks.map((b) => ({ id: b.id, type: b.type, props: Object.keys(b.props) }))
     };
     const response = await client.messages.create({
@@ -170,7 +170,7 @@ export async function generatePlanWithAnthropic(args) {
     const effectiveSignal = args.signal
         ? AbortSignal.any([args.signal, AbortSignal.timeout(LLM_TIMEOUT_MS)])
         : AbortSignal.timeout(LLM_TIMEOUT_MS);
-    const effectiveBlockTypes = args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : allowedBlockTypes;
+    const effectiveBlockTypes = args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : catalogueBlockTypes();
     const batchOverride = isBatchAddRequest(args.message) || isBatchRemoveRequest(args.message) || isBatchReorderRequest(args.message) || isPageWideRewriteRequest(args.message) || isDuplicateAndModifyRequest(args.message);
     const pageWideRewrite = isPageWideRewriteRequest(args.message);
     const planFirstMode = requestsPlanFirst(args.message);

package/dist/chat/chat-pipeline.js

@@ -9,7 +9,23 @@ import { evaluateDestructiveActions } from "../ops/destructive-action-gate.js";
 import { clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, plannerContextPack, compileDeterministicPlan, inferDeterministicIntent, isHighConfidenceDeterministicCase, tryCompoundDeterministicPlan, resolveImageUrlForAltField } from "../nlp/deterministic-planner.js";
 import { generatePlanWithOpenAI, isPlannerOutputError, isStrictJsonResponseEnabled, parseIntentWithOpenAI } from "./planner.js";
 import { isDemoModeEnabled, splitDemoOps, getDemoAllowedBlockTypes } from "../demo-mode.js";
-import { isCancelError as _isCancelError } from "../errors.js";
+import { isCancelError as _isCancelError, OperationError } from "../errors.js";
+import { acquireSessionLock } from "../state/session-lock.js";
+const ERROR_CATEGORIES = [
+    "schema_violation",
+    "ambiguity",
+    "not_found",
+    "no_effective_change",
+    "planner_refusal",
+    "incomplete_output",
+    "malformed_output",
+    "internal_error",
+    "canceled",
+    "operation_failed"
+];
+function isErrorCategory(value) {
+    return value !== undefined && ERROR_CATEGORIES.includes(value);
+}
 // `isCancelError` is used directly (without underscore) in runChatPipeline
 const isCancelError = _isCancelError;
 import { isMultiStepCandidate, decomposeRequest } from "./decomposer.js";
@@ -1768,6 +1784,29 @@ export async function runChatPipeline(ctx, body, options) {
         if (resolvedPlan.ops.length === 0) {
             pendingClarificationBySession.delete(body.session);
             pendingApprovalPlanBySession.delete(body.session);
+            /*
+             * Zero ops is not the same fact as "already correct".
+             *
+             * The branch above this one earns that phrasing: it has a dry-run and can
+             * see that every op was skipped as `unchanged_value`. Here there is no
+             * plan to inspect — the planner returned none. Saying the content is up
+             * to date asserts a reason nothing established, and it reads as success,
+             * so a request that was silently dropped looks like a request that was
+             * honoured. "rewrite the copy to be punchier" answered with "already up
+             * to date" is the shape of the complaint.
+             *
+             * An `edit_plan` intent carrying no operations is the planner failing to
+             * express an edit it meant to make, so say that, and prefer its own
+             * summary when it wrote one — it is usually closer to what happened than
+             * anything canned.
+             */
+            const plannerIntendedAnEdit = resolvedPlan.intent === "edit_plan";
+            const plannerSummary = resolvedPlan.summary_for_user?.trim();
+            const emptyPlanSummary = plannerIntendedAnEdit
+                ? (plannerSummary && plannerSummary.length > 0
+                    ? plannerSummary
+                    : "I didn't manage to turn that into an edit. Try naming the block or the field you want changed.")
+                : "No changes needed. That content is already up to date.";
             ctx.chatTelemetry.push({
                 id: chatRequestId,
                 at: new Date().toISOString(),
@@ -1781,7 +1820,11 @@ export async function runChatPipeline(ctx, body, options) {
                 promptHash,
                 promptExcerpt,
                 promptLength: plannerMessage.length,
-                outcome: "no_effective_change",
+                // Distinct from `no_effective_change`: nothing was even proposed. The
+                // two were indistinguishable in telemetry, which is why a planner that
+                // silently produced nothing looked like a planner correctly doing
+                // nothing.
+                outcome: plannerIntendedAnEdit ? "empty_edit_plan" : "no_effective_change",
                 intent: resolvedPlan.intent,
                 opCount: 0,
                 opTypes: [],
@@ -1795,14 +1838,17 @@ export async function runChatPipeline(ctx, body, options) {
                     code: 200,
                     payload: withDebugPayload({
                         status: "applied",
-                        summary: "No changes needed. That content is already up to date.",
+                        summary: emptyPlanSummary,
                         changes: [],
                         mentionedSlugs: [effectiveSlug],
                         previewVersion: versions.get(body.session) ?? 0,
                         plannerSource: source,
                         modelUsed,
                         modelKey
-                    }, { outcome: "no_effective_change", plannerTier })
+                    }, {
+                        outcome: plannerIntendedAnEdit ? "empty_edit_plan" : "no_effective_change",
+                        plannerTier
+                    })
                 }
             };
         }
@@ -1876,19 +1922,64 @@ export async function runChatPipeline(ctx, body, options) {
                 applyStartedAtMs = Date.now();
                 const hasPageStructuralOps = resolvedPlan.ops.some((op) => op.op === "create_page" || op.op === "rename_page" || op.op === "remove_page" || op.op === "move_page" || op.op === "duplicate_page");
                 if (incrementalApplyEnabled && options?.onOpApplied && !hasPageStructuralOps) {
-                    // Snapshot the entire session draft so we can restore it wholesale after preflight.
-                    const sessionDraft = getSessionDraft(body.session);
-                    const preFlightSnapshot = new Map();
-                    for (const [slug, page] of sessionDraft) {
-                        preFlightSnapshot.set(slug, structuredClone(page));
-                    }
-                    // Validate the whole plan from the current state before progressive apply.
-                    const preflight = await applyOpsAtomically(body.session, resolvedPlan.ops, { componentsManifest });
+                    /*
+                     * Validate the whole plan before touching anything, then apply it once.
+                     *
+                     * This used to *apply* the plan for real as its preflight, clear the
+                     * live session draft by reference, restore it from a snapshot, and then
+                     * replay every operation individually with a pause between steps. Three
+                     * things followed, and all three ran on the default production path
+                     * because both flags default on:
+                     *
+                     *   - every operation's side effects happened twice;
+                     *   - the clear-and-restore sat between two locked calls rather than
+                     *     inside one, so there was a window in which the session held zero
+                     *     pages and a concurrent draft fetch rendered an empty site;
+                     *   - a failure mid-replay rolled back the *whole session* from that
+                     *     snapshot, destroying any write that had landed meanwhile.
+                     *
+                     * `dryRun` does what the preflight was reaching for: it runs every op
+                     * against a clone under the session lock, reports per-op outcomes, and
+                     * never commits. So the plan is still validated as a whole before the
+                     * first visible change, and the ops are applied exactly once.
+                     */
+                    const touchedSlugs = new Set(resolvedPlan.ops
+                        .map((op) => ("pageSlug" in op ? op.pageSlug : undefined))
+                        .filter((slug) => typeof slug === "string" && slug.length > 0));
+                    const preflight = await applyOpsAtomically(body.session, resolvedPlan.ops, {
+                        componentsManifest,
+                        dryRun: true
+                    });
                     skippedOps = preflight.skippedOps;
-                    // Restore pre-apply state wholesale so we can replay ops progressively.
-                    sessionDraft.clear();
-                    for (const [slug, page] of preFlightSnapshot) {
-                        setPage(body.session, structuredClone(page));
+                    // A dry run reports a hard failure instead of throwing, so that the
+                    // publish preview can say "3 of 4 will apply". Here the whole point is
+                    // to refuse before anything is visible, so the first failure is raised.
+                    const failedOp = preflight.opResults.find((result) => result.status === "failed");
+                    if (failedOp) {
+                        throw new OperationError(failedOp.reason ?? `Operation ${failedOp.op} cannot be applied`, {
+                            // `OpResult.category` is a plain string; keep only the values the
+                            // error type actually knows, rather than widening that type to
+                            // accept whatever an op happened to report.
+                            category: isErrorCategory(failedOp.category) ? failedOp.category : "operation_failed"
+                        });
+                    }
+                    // Likewise the no-effective-change check, which dryRun skips.
+                    if (preflight.appliedCount === 0) {
+                        throw new OperationError(skippedOps.length > 0
+                            ? "No effective prop change across plan. All update patches matched existing values."
+                            : "Edit plan produced no changes", { category: "no_effective_change" });
+                    }
+                    /*
+                     * Snapshot only the pages this plan can touch. Structural page ops are
+                     * excluded from this branch, so no slug appears or disappears — which
+                     * means a rollback can put those pages back without clearing the map,
+                     * and a concurrent edit to an untouched page survives it.
+                     */
+                    const preFlightSnapshot = new Map();
+                    for (const slug of touchedSlugs) {
+                        const page = getSessionDraft(body.session).get(slug);
+                        if (page)
+                            preFlightSnapshot.set(slug, structuredClone(page));
                     }
                     const total = resolvedPlan.ops.length;
                     try {
@@ -1953,10 +2044,21 @@ export async function runChatPipeline(ctx, body, options) {
                         if (isCancelError(progressiveError))
                             throw progressiveError;
                         options?.onRollbackStarted?.({ appliedCount: total, reason: toErrorDetail(progressiveError) });
-                        // Roll back to pre-plan state so we don't leave a partially-applied plan.
-                        sessionDraft.clear();
-                        for (const [slug, page] of preFlightSnapshot) {
-                            setPage(body.session, structuredClone(page));
+                        /*
+                         * Roll back the pages this plan touched, under the session lock, and
+                         * leave every other page alone. Clearing the whole draft and
+                         * rewriting it from a session-wide snapshot — which is what this did
+                         * — discarded concurrent writes to pages the plan never mentioned,
+                         * and briefly published an empty site while it ran.
+                         */
+                        const release = await acquireSessionLock(body.session);
+                        try {
+                            for (const [, page] of preFlightSnapshot) {
+                                setPage(body.session, structuredClone(page));
+                            }
+                        }
+                        finally {
+                            release();
                         }
                         options?.onRollbackDone?.({ restoredVersion: versions.get(body.session) ?? 0 });
                         throw progressiveError;

package/dist/chat/gemini-planner.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { allowedBlockTypes, editPlanSchema } from "@avocadostudio-ai/shared";
+import { catalogueBlockTypes, editPlanSchema } from "@avocadostudio-ai/shared";
 import { buildIntentParserSystemPrompt, buildPlannerSystemPrompt } from "./prompts.js";
 import { extractAudienceTarget, fetchImageAsBase64, resolveAttachmentsForLlm, intentSchema } from "../nlp/deterministic-planner.js";
 import { isBatchAddRequest, isBatchRemoveRequest, isBatchReorderRequest, isPageWideRewriteRequest, requestsPlanFirst } from "../nlp/intent-detection.js";
@@ -94,7 +94,7 @@ export async function parseIntentWithGemini(args) {
         activeBlockId: args.activeBlockId ?? null,
         activeBlockType: args.activeBlockType ?? null,
         activeEditablePath: args.activeEditablePath ?? null,
-        availableBlockTypes: allowedBlockTypes,
+        availableBlockTypes: catalogueBlockTypes(),
         blocks: args.currentPage.blocks.map((b) => ({ id: b.id, type: b.type, props: Object.keys(b.props) }))
     };
     const response = await raceWithAbort(ai.models.generateContent({
@@ -134,7 +134,7 @@ export async function generatePlanWithGemini(args) {
     const effectiveSignal = args.signal
         ? AbortSignal.any([args.signal, AbortSignal.timeout(LLM_TIMEOUT_MS)])
         : AbortSignal.timeout(LLM_TIMEOUT_MS);
-    const effectiveBlockTypes = args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : allowedBlockTypes;
+    const effectiveBlockTypes = args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : catalogueBlockTypes();
     const batchOverride = isBatchAddRequest(args.message) || isBatchRemoveRequest(args.message) || isBatchReorderRequest(args.message) || isPageWideRewriteRequest(args.message);
     const pageWideRewrite = isPageWideRewriteRequest(args.message);
     const planFirstMode = requestsPlanFirst(args.message);

package/dist/chat/planner.js

@@ -1,6 +1,6 @@
 import OpenAI from "openai";
 import { z } from "zod";
-import { allowedBlockTypes, blockSchemas, editPlanSchema } from "@avocadostudio-ai/shared";
+import { catalogueBlockTypes, blockSchemas, editPlanSchema } from "@avocadostudio-ai/shared";
 import { buildIntentParserSystemPrompt, buildPlannerSystemPrompt } from "./prompts.js";
 // ---------------------------------------------------------------------------
 // Singleton OpenAI client — reuses connection pool across requests.
@@ -117,7 +117,9 @@ function bytesForPayload(value) {
     }
 }
 function uniqueBlockTypes(values) {
-    const known = new Set(allowedBlockTypes.map((type) => type.toLowerCase()));
+    // Read once: `catalogueBlockTypes()` filters on every call.
+    const catalogue = catalogueBlockTypes();
+    const known = new Set(catalogue.map((type) => type.toLowerCase()));
     const out = [];
     const seen = new Set();
     for (const value of values) {
@@ -127,7 +129,7 @@ function uniqueBlockTypes(values) {
         if (!known.has(normalized) || seen.has(normalized))
             continue;
         seen.add(normalized);
-        const canonical = allowedBlockTypes.find((type) => type.toLowerCase() === normalized);
+        const canonical = catalogue.find((type) => type.toLowerCase() === normalized);
         if (canonical)
             out.push(canonical);
     }
@@ -1066,7 +1068,7 @@ export async function parseIntentWithOpenAI(args) {
         activeBlockId: args.activeBlockId ?? null,
         activeBlockType: args.activeBlockType ?? null,
         activeEditablePath: args.activeEditablePath ?? null,
-        availableBlockTypes: allowedBlockTypes,
+        availableBlockTypes: catalogueBlockTypes(),
         blocks: args.currentPage.blocks.map((b) => ({ id: b.id, type: b.type, props: Object.keys(b.props) }))
     };
     const completion = await client.chat.completions.create({
@@ -1105,7 +1107,7 @@ export async function generatePlanWithOpenAI(args) {
     const effectiveSignal = args.signal
         ? AbortSignal.any([args.signal, AbortSignal.timeout(LLM_TIMEOUT_MS)])
         : AbortSignal.timeout(LLM_TIMEOUT_MS);
-    const effectiveBlockTypes = args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : allowedBlockTypes;
+    const effectiveBlockTypes = args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : catalogueBlockTypes();
     const batchOverride = isBatchAddRequest(args.message) || isBatchRemoveRequest(args.message) || isBatchReorderRequest(args.message) || isPageWideRewriteRequest(args.message) || isDuplicateAndModifyRequest(args.message);
     const pageWideRewrite = isPageWideRewriteRequest(args.message);
     const planFirstMode = requestsPlanFirst(args.message);

package/dist/chat/prompts.js

@@ -88,6 +88,11 @@ function localeInstruction(locale) {
 // ---------------------------------------------------------------------------
 const RULE_ROLE = "You are an editing planner for a website builder.";
 const RULE_JSON_ONLY = "Return ONLY one JSON object matching EditPlan.";
+const RULE_RICH_TEXT_PROPS = [
+    "A few props are rendered as markdown rather than plain text. Each block contract lists them under richTextProps, as `key` or `listKey[].key` (e.g. RichText `body`, FAQAccordion `items[].a`).",
+    "In those props you may use: **bold**, *italic*, ~~strikethrough~~, `inline code`, [label](url), headings from ## to ###### (never a single # — the page already has its top-level heading), bullet lists (- item) and numbered lists (1. item) including nested ones (indent the nested item by two spaces), blockquotes (> quoted), fenced code blocks and thematic breaks (---). Separate paragraphs with a blank line.",
+    "Everywhere else — every prop not listed in richTextProps, and summary text the user reads — markdown characters render literally, so write plain text. Never put markdown in a heading, label, button text, or a delimited value such as Footer `links`."
+].join(" ");
 const RULE_NO_MARKDOWN = "Never output markdown or code fences.";
 const RULE_NO_OP_PATCH = "Do not return no-op updates: patch must change at least one effective value.";
 const RULE_STRICT_SCHEMA_DISCIPLINE = "STRICT SCHEMA DISCIPLINE: Only promise changes to props that exist in the block's contract. When a request has some supported parts AND some unsupported parts (e.g. 'add icons and colors' on a block with icon but no color), APPLY the supported parts and mention in summary_for_user that the unsupported part isn't available — don't bail out. Only return needs_clarification when NOTHING in the request maps to the schema. Do NOT generate summary_for_user or change_log text that describes changes your ops don't actually make.";
@@ -236,7 +241,7 @@ function sectionVoice(opts, hasNativeTools) {
     if (hasNativeTools) {
         lines.push("For edit_plan intent: summary_for_user must be ONE short sentence (max ~20 words) describing what the plan will do. Do NOT elaborate, explain why, or describe the content being added — let change_log carry the detail. Bad: 'Updated the hero heading with a punchier tone.' Good: 'Will add a **text section** about blueberry varieties after the features grid.'", "change_log coverage is MANDATORY: emit exactly one change_log entry per op, in the same order as ops[], describing what that specific op does. If ops has N entries, change_log must have N entries — never cluster multiple ops into one entry, never skip an op, never leave an op undescribed. The user reads change_log to decide whether to approve; a missing entry is a silent bait-and-switch.", "change_log entries should add specific detail NOT already in summary_for_user — e.g. list the actual content, items, or values being set. Do not paraphrase the summary.");
     }
-    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types in blockContracts / blockCatalogue (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video) or SEO/site-config edits. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
+    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the prop is a rich-text prop (see below) or the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", RULE_RICH_TEXT_PROPS, "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types in blockContracts / blockCatalogue (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video) or SEO/site-config edits. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
     return lines;
 }
 function sectionOperationCatalog() {

package/dist/cms/adapter.d.ts

@@ -25,6 +25,24 @@ export interface CmsPublishContext {
      * in block props, and emit the resulting public URL.
      */
     assets?: Record<string, CmsInlineAsset>;
+    /**
+     * The pages as the adapter last reported them, if the orchestrator has them.
+     *
+     * Without a baseline, `onPublish(pages)` can only be implemented as "store
+     * these documents", which is exactly what a real CMS cannot accept: every
+     * read is a projection — an asset reference flattened to a URL, a document
+     * reference resolved to one language's href — and writing the projection back
+     * destroys what it was projected from. A publisher has to diff, and it cannot
+     * diff against nothing.
+     *
+     * Absent when the session was never bootstrapped from the adapter, so treat
+     * `undefined` as "no baseline available" and not as "the site was empty" —
+     * publishing every field on that assumption is the overwrite this exists to
+     * prevent. An integration that embeds its own source snapshot in block props
+     * (the more precise approach, since only it knows what it projected) can
+     * ignore this.
+     */
+    published?: PageDoc[];
 }
 /**
  * Result of an `onPublish` call. `void` means "success, nothing to report";
@@ -33,22 +51,77 @@ export interface CmsPublishContext {
  */
 export type CmsPublishResult = void | {
     ok: true;
+    unsupported?: string[];
 } | {
     ok: false;
     error?: string;
+    unsupported?: string[];
 };
+/**
+ * Which side of a CMS's draft/published split a read wants.
+ *
+ * Most content stores keep two versions of a document: the one visitors see,
+ * and the one an editor is working on. Sanity calls them perspectives,
+ * Contentful splits them across the Delivery and Preview APIs, Strapi calls
+ * them published and draft entries. The vocabulary differs; the split does not.
+ *
+ * `getPages()` had no way to say which one it meant, so an adapter had to pick
+ * one for every caller at once — and the two callers want opposite things.
+ */
+export type CmsPerspective = 
+/**
+ * The editor's working copy: unpublished edits included, falling back to the
+ * published version of any document that has none. This is what seeds a
+ * session, because it is the content someone is actually working on.
+ */
+"draft"
+/**
+ * What is live for visitors right now. This is the publish diff's baseline:
+ * "what will change on the site" is a question about the live version and
+ * nothing else.
+ */
+ | "published";
+/** Options for a read. An options bag rather than a positional flag, so a later read hint costs no signature change. */
+export interface CmsReadOptions {
+    perspective: CmsPerspective;
+}
 export interface CmsAdapter {
     /**
      * Stable identifier for telemetry and per-adapter bootstrap caches.
      * Keep it short and DNS-safe: `json-file`, `editor-api`, `sanity`, etc.
      */
     readonly id: string;
+    /**
+     * Whether `getPages` honours `options.perspective`.
+     *
+     * Silence means no, which is the opposite default from `capabilities` below
+     * and deliberately so: those are permissions, where the safe answer is to
+     * allow what nobody has forbidden, and this is an ability, where the safe
+     * answer is not to claim one nobody has implemented. An adapter wrongly
+     * believed to read drafts makes the publish diff assert that unpublished
+     * work is live.
+     *
+     * Set it `true` only when both perspectives are genuinely reachable — often
+     * a runtime condition rather than a constant, since reading drafts usually
+     * needs a token the deployment may not have: `perspectives: Boolean(token)`
+     * is the honest form.
+     */
+    readonly perspectives?: boolean;
     /**
      * Return every page the orchestrator should know about for this site.
      * Called lazily on the first chat for a fresh session. Failures are
      * logged but non-fatal — the session simply starts empty.
+     *
+     * `options` is optional and every existing implementation may ignore it: an
+     * adapter that reads one perspective is not wrong, it is just blind to the
+     * other, and that is exactly what `perspectives` reports. Ignoring the
+     * argument reproduces the pre-perspective behaviour byte for byte.
+     *
+     * Callers always pass it. That is the guarded half of the contract — a
+     * caller that omits it silently re-collapses the two questions into one, and
+     * `cms/read-perspective.test.ts` fails the build if one does.
      */
-    getPages(): Promise<PageDoc[]>;
+    getPages(options?: CmsReadOptions): Promise<PageDoc[]>;
     /**
      * Optional publish hook. If present, called when the editor publishes
      * a session's draft. If absent, publish remains a no-op against the
@@ -59,4 +132,89 @@ export interface CmsAdapter {
      * collected during the session.
      */
     onPublish?(pages: PageDoc[], config: SiteConfig, context?: CmsPublishContext): Promise<CmsPublishResult>;
+    /**
+     * What this site can actually honour, for the operations where "applied
+     * successfully" and "publishable" are different questions.
+     *
+     * A CMS-backed site typically cannot mint pages: Avocado assigns a new page
+     * an id and a slug, the CMS has no document behind either, and the op
+     * applies cleanly, previews correctly and reports success — then fails the
+     * whole publish transaction. An agent told "this site cannot create pages"
+     * is strictly more useful than one that can create a broken one.
+     *
+     * Static, deliberately: `/whoami` must be able to answer this with the CMS
+     * unreachable, so it cannot be a method that reads upstream.
+     */
+    readonly capabilities?: CmsCapabilities;
 }
+/**
+ * Per-operation capability declaration. Every field is tri-state, and the
+ * third state is the important one: `undefined` means *the adapter did not
+ * say*, which is not the same as `false`.
+ *
+ * Unknown resolves to permitted. That is not optimism, it is the only
+ * non-breaking default: no adapter shipped so far declares anything, the
+ * standalone orchestrator has no adapter at all, and both bundled adapters
+ * genuinely can create pages. A restrictive default would silently withdraw
+ * working operations from every existing install on upgrade, with no way to
+ * opt back in short of editing the adapter. So a capability is enforced only
+ * where an adapter has explicitly said `false`.
+ */
+export interface CmsCapabilities {
+    /**
+     * Whether a new page can exist upstream. Gates `create_page` and
+     * `duplicate_page` — the latter mints an identity just as surely as the
+     * former.
+     */
+    createPages?: boolean;
+    /** Whether a page can be removed upstream. A patch-only publisher emits nothing for a deletion, so the page survives it. */
+    deletePages?: boolean;
+    /**
+     * Whether the *set and order* of blocks on a page can change.
+     *
+     * Separate from editing a block's props, because for many integrations they
+     * are genuinely different: a site whose three language variants share one
+     * block structure can accept every text edit and no insertion.
+     *
+     * Deliberately narrower than the engine's own `isStructuralOperation`, which
+     * also counts list-item ops. Adding a row to a list is an ordinary array
+     * write inside one block's props, and any adapter that projects the CMS's
+     * own keys can publish it.
+     */
+    structuralEdits?: boolean;
+}
+/** Capabilities with the unknowns resolved, plus what we can derive ourselves. */
+export interface ResolvedCapabilities {
+    createPages: boolean;
+    deletePages: boolean;
+    structuralEdits: boolean;
+    /** True when the adapter has an `onPublish`; derived, never declared. */
+    publishesUpstream: boolean;
+    /**
+     * True when the adapter reads the CMS's draft perspective; derived from
+     * `adapter.perspectives`, never declared as a capability.
+     *
+     * False is the interesting value and the reason this is reported at all: it
+     * means a document edited in the CMS and not yet published is invisible to
+     * Avocado — the session was seeded from the live version, and the publish
+     * diff will call it unchanged. That is a true statement about a page whose
+     * author can see their unsaved-to-live edits in their own CMS, which is the
+     * most confusing shape a correct answer can take. An agent reading this
+     * knows not to conclude "nothing is pending" from an empty diff.
+     */
+    readsDraftPerspective: boolean;
+    /**
+     * The subset the adapter actually declared. A caller that needs to
+     * distinguish "this site says no" from "nobody said" reads this; everything
+     * else reads the resolved booleans above.
+     */
+    declared: CmsCapabilities;
+}
+/**
+ * Resolve an adapter's declaration, treating silence as permission.
+ *
+ * `null` — the standalone multi-site orchestrator, which wires no adapter at
+ * all — resolves fully capable, because it is: its pages live in Avocado's own
+ * store and nothing upstream can refuse them.
+ */
+export declare function resolveCapabilities(adapter: CmsAdapter | null | undefined, override?: CmsCapabilities): ResolvedCapabilities;

package/dist/cms/adapter.js

@@ -1 +1,19 @@
-export {};
+/**
+ * Resolve an adapter's declaration, treating silence as permission.
+ *
+ * `null` — the standalone multi-site orchestrator, which wires no adapter at
+ * all — resolves fully capable, because it is: its pages live in Avocado's own
+ * store and nothing upstream can refuse them.
+ */
+export function resolveCapabilities(adapter, override) {
+    const declared = { ...adapter?.capabilities, ...override };
+    return {
+        createPages: declared.createPages !== false,
+        deletePages: declared.deletePages !== false,
+        structuralEdits: declared.structuralEdits !== false,
+        publishesUpstream: typeof adapter?.onPublish === "function",
+        // `=== true`, not truthiness: an adapter that says nothing has not said yes.
+        readsDraftPerspective: adapter?.perspectives === true,
+        declared
+    };
+}

package/dist/cms/bootstrap.d.ts

@@ -1,11 +1,54 @@
-import type { CmsAdapter } from "./adapter.ts";
+import type { PageDoc } from "@avocadostudio-ai/shared";
+import type { CmsAdapter, CmsCapabilities } from "./adapter.ts";
 import type { Logger } from "../logger.ts";
 export interface CmsBootstrapCacheOptions {
     /** Soft cap on remembered "already-attempted" sessions. Default 5000. */
     maxAttempted?: number;
+    /**
+     * How long a warmed page list stays usable, in milliseconds.
+     * Default 60000 — see `DEFAULT_WARM_TTL_MS`.
+     */
+    warmTtlMs?: number;
+    /**
+     * Capability declaration from the host, merged over the adapter's own.
+     * Lets a site using a stock adapter (`jsonFileAdapter`, `editorApiAdapter`)
+     * declare what it can honour without writing an adapter class of its own.
+     */
+    capabilities?: CmsCapabilities;
+    /**
+     * How many sessions' publish baselines to retain. Default 50 — a library-mode
+     * process serves one site and a handful of sessions; the cap exists so a
+     * long-lived multi-session host cannot accumulate page sets forever.
+     */
+    maxBaselines?: number;
 }
 export interface CmsBootstrapCache {
     ensure(session: string, adapter: CmsAdapter | null | undefined, log: Logger): Promise<void>;
+    /**
+     * Start the adapter's page fetch ahead of the first request. Fire-and-forget:
+     * returns immediately, never throws, and never leaves an unhandled rejection.
+     * A failed warm is logged at warn and forgotten, so `ensure()` retries the
+     * fetch itself rather than inheriting the failure. Calling it twice for the
+     * same adapter inside the TTL does not issue a second fetch.
+     */
+    warm(adapter: CmsAdapter | null | undefined, log: Logger): void;
+    /**
+     * What the adapter reported for this session when it was bootstrapped, or
+     * null if this process never seeded it.
+     *
+     * A publisher has to diff — `onPublish(pages)` as "store these documents" is
+     * only implementable when the CMS shape is the editor shape — and it cannot
+     * diff against nothing. This is the cheap baseline: the pages are already
+     * being cloned into the draft, so keeping the pre-edit copy costs one more
+     * 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".
+     */
+    baselineFor(session: string): PageDoc[] | null;
     /** Test helper — drop all remembered state. */
     reset(): void;
     /** Inspection — number of remembered attempts (post-eviction). */
@@ -13,5 +56,7 @@ export interface CmsBootstrapCache {
 }
 export declare function createCmsBootstrapCache(opts?: CmsBootstrapCacheOptions): CmsBootstrapCache;
 export declare function ensureSessionBootstrapped(session: string, adapter: CmsAdapter | null | undefined, log: Logger): Promise<void>;
+/** Warm the process-default cache. Runtime-scoped caches own their own `warm()`. */
+export declare function warmSessionBootstrap(adapter: CmsAdapter | null | undefined, log: Logger): void;
 /** Test helper — clears the default process cache. Runtime-scoped caches own their own `reset()`. */
 export declare function _resetCmsBootstrapCache(): void;