@avocadostudio-ai/orchestrator-core 0.8.0 → 0.9.0

package/dist/chat/chat-pipeline-context.d.ts

@@ -55,6 +55,7 @@ export declare function compactPlannerContextPack(args: {
         }>;
     }[];
     pageMeta: import("@avocadostudio-ai/shared").PageMeta | null;
+    pageObservations: import("../nlp/intent-detection.ts").PageObservation[];
     pageIntent: string;
     recentSuccessfulEdits: {
         at: string;
@@ -132,6 +133,7 @@ export declare function minimalPlannerContextPack(args: {
         }>;
     }[];
     pageMeta: import("@avocadostudio-ai/shared").PageMeta | null;
+    pageObservations: import("../nlp/intent-detection.ts").PageObservation[];
     pageIntent: string;
     recentSuccessfulEdits: {
         at: string;

package/dist/chat/chat-pipeline.js

@@ -1,14 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { blockManifestSchema } from "@avocadostudio-ai/shared";
 import { GENERATING_IMAGE_PLACEHOLDER, SEARCHING_IMAGE_PLACEHOLDER, isGeneratingPlaceholder, cleanupImagePlaceholders, buildPageDirectory, isVariationRequestMessage, variationVerbIntent, resolveEffectiveSlug, throwIfCanceled, raceCancel, sleepMs, suppressCancelOnly } from "./chat-pipeline-shared.js";
-import { siteCapabilitiesSchema, isBatchAddRequest, isDuplicateBlockRequest, isBlockCatalogQuery, isInfoQuery, isAdviceQuery, adviceResponse, isContentQuery, isPageListQuery, requestsPlanFirst, plannerMessageWithPendingContext, buildSiteContextBlock, infoResponse } from "../nlp/intent-detection.js";
+import { siteCapabilitiesSchema, isBatchAddRequest, isDuplicateBlockRequest, isBlockCatalogQuery, isInfoQuery, isContentQuery, isPageListQuery, requestsPlanFirst, plannerMessageWithPendingContext, buildSiteContextBlock, infoResponse } from "../nlp/intent-detection.js";
 import { isLikelyClarificationFollowUp } from "../nlp/intent-helpers.js";
 import { versions, pendingClarificationBySession, chatHistoryBySession, continuationChainBySession, imageSourcePreferenceBySession, getSessionDraft, getPage, setPage, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, pushChatHistory, schedulePersistState, removePage } from "../state/session-state.js";
 import { getSiteAssets } from "../state/site-assets.js";
 import { loadPendingPlan, savePendingPlan, clearPendingPlan } from "../durable/pending-plan-store.js";
 import { toErrorDetail, isNoEffectiveChangeError, isAlreadyCurrentError, classifyGuardrailError, formatValidationError, isRepairEligibleCategory, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
 import { evaluateDestructiveActions } from "../ops/destructive-action-gate.js";
-import { clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, plannerContextPack, compileDeterministicPlan, inferDeterministicIntent, isHighConfidenceDeterministicCase, tryCompoundDeterministicPlan, resolveImageUrlForAltField } from "../nlp/deterministic-planner.js";
+import { clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, withKeylessNotice, 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, OperationError, OrchestrationError } from "../errors.js";
@@ -919,11 +919,17 @@ export async function runChatPipeline(ctx, body, options) {
         const info = infoResponse({ body, current, plannerSource, modelUsed, modelKey });
         return { code: info.code, payload: withDebugPayload(info.payload, { outcome: "info" }) };
     }
-    if (body.message && isAdviceQuery(body.message) && !isBatchAddRequest(body.message)) {
-        activePlannerTier = "deterministic";
-        const advice = adviceResponse({ body, current, plannerSource, modelUsed, modelKey });
-        return { code: advice.code, payload: withDebugPayload(advice.payload, { outcome: "advice" }) };
-    }
+    /*
+     * There is no deterministic branch for "review this page" any more.
+     *
+     * There was, and it answered in twelve milliseconds from a template — which
+     * is why a page review read like a linter. The planner prompt already has the
+     * rule (PAGE FEEDBACK -> content_answer, "specific, reasoned recommendations
+     * based on the page topic and content, not a generic checklist"); it was
+     * never reached, because two detectors claimed the same message and the
+     * canned one was tested first. What survives is `pageObservations`, which the
+     * context pack carries so the model reviews with the checked facts in hand.
+     */
     if (body.message && isPageListQuery(body.message)) {
         const directory = buildPageDirectory(body.session);
         const draft = getSessionDraft(body.session);
@@ -2961,7 +2967,7 @@ export async function runChatPipeline(ctx, body, options) {
         markPlanningStart();
         try {
             emitStatusTone("planning");
-            const demoPlan = demoPlanFromMessageImpl(plannerMessage, effectiveSlug, planningActiveBlockId, body.activeBlockType);
+            const demoPlan = withKeylessNotice(demoPlanFromMessageImpl(plannerMessage, effectiveSlug, planningActiveBlockId, body.activeBlockType));
             markPlanningFinish();
             const outcome = await respondFromPlan(demoPlan, "demo", applyMode, undefined, "demo");
             if (outcome.done)

package/dist/handler/create-orchestrator.d.ts

@@ -97,6 +97,27 @@ export interface CreateOrchestratorConfig {
      *   - no adapter: explicit `siteId` wins; otherwise `body.siteId` is used.
      */
     siteId?: string;
+    /**
+     * Human-readable name for this site, reported on `/status/planner`.
+     *
+     * The editor otherwise title-cases the site id, so a project scaffolded into
+     * `my-shop/` is greeted as "My Shop". That is a reasonable guess and a poor
+     * one for anything whose directory name is not its name.
+     */
+    siteName?: string;
+    /**
+     * Whether this mount is serving the shipped Avocado Hub demo content rather
+     * than a real site's, reported on `/status/planner`.
+     *
+     * The editor's curated first-run suggestions — the ones written against the
+     * demo's actual pages — used to be keyed on a hardcoded allowlist of site
+     * ids that only ever matched sites inside this monorepo. A scaffolded
+     * project's id is whatever the user called their directory, so the new front
+     * door was structurally excluded from the onboarding written for it. The
+     * question the editor was really asking is "is this the demo content?", so
+     * that is the question the orchestrator now answers.
+     */
+    demoContent?: boolean;
     /**
      * Register the site's block schemas before the orchestrator's first chat
      * request. Use this instead of relying on side-effect import order: in
@@ -150,7 +171,7 @@ export interface CreateOrchestratorConfig {
      * The route this site renders orchestrator drafts on. Either a prefix the
      * page slug is appended to (`/avocado`) or a template naming where the slug
      * goes (`/preview/{slug}/draft`). Defaults to `/preview-draft`, which is what
-     * `create-ai-site-editor` scaffolds.
+     * `create-avocado-site` scaffolds.
      *
      * A site that wired Avocado into its own app almost certainly has its own
      * route here — declare it, or every draft screenshot photographs a 404.

package/dist/handler/create-orchestrator.js

@@ -1054,6 +1054,17 @@ export function createOrchestrator(config = {}) {
             return jsonResponse({
                 plannerSource: providers[0] ?? "demo",
                 availableProviders: providers,
+                /*
+                 * Identity, so the editor's onboarding copy can be keyed on what
+                 * this mount actually is rather than on a list of ids it was
+                 * compiled with. `demoContent` is what `create-avocado-site` sets on
+                 * a scaffolded project.
+                 */
+                site: {
+                    ...(config.siteId ? { id: config.siteId } : {}),
+                    ...(config.siteName ? { name: config.siteName } : {}),
+                    demoContent: config.demoContent === true
+                },
                 features: {
                     googleDrive: false,
                     unsplash: Boolean(process.env.UNSPLASH_ACCESS_KEY),

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

@@ -17,7 +17,7 @@
  * instead (useful for before/after comparisons).
  *
  * `/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
+ * meant this route worked on sites `create-avocado-site` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
  * 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

package/dist/http/screenshot-actions.js

@@ -17,7 +17,7 @@
  * instead (useful for before/after comparisons).
  *
  * `/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
+ * meant this route worked on sites `create-avocado-site` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
  * 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

package/dist/nlp/deterministic-planner-context.d.ts

@@ -133,6 +133,7 @@ export declare function plannerContextPack(args: {
         }>;
     }[];
     pageMeta: import("@avocadostudio-ai/shared").PageMeta | null;
+    pageObservations: import("./intent-detection.ts").PageObservation[];
     pageIntent: string;
     recentSuccessfulEdits: {
         at: string;

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

@@ -1,6 +1,7 @@
 import { getSessionDraft, getRecentEdits, getSiteConfig, orderSlugsHomeFirst } from "../state/session-state.js";
 import { getLibraryMount } from "../handler/library-mount.js";
 import { resolveReferencesFromMessage } from "./deterministic-planner-refs.js";
+import { pageObservations } from "./intent-detection.js";
 // ---------------------------------------------------------------------------
 // Path traversal
 // ---------------------------------------------------------------------------
@@ -411,6 +412,13 @@ export function plannerContextPack(args) {
             return { id: b.id, type: b.type, props: textHints, arrayProps: arrProps };
         }),
         pageMeta: currentPage.meta ?? null,
+        /*
+         * Facts about this page that reading props does not reveal: a declared
+         * image field with nothing in it, a page nothing links out of, a missing
+         * meta description. Cheap to compute and impossible to infer from the
+         * outline above, so a review is grounded in them rather than guessing.
+         */
+        pageObservations: pageObservations(currentPage),
         pageIntent: pageIntentSummary({ slug, currentPage }),
         recentSuccessfulEdits: getRecentEdits(session, slug),
         resolvedReferences: resolveReferencesFromMessage({ message, currentPage, activeBlockId }),

package/dist/nlp/deterministic-planner-suggestions.d.ts

@@ -56,4 +56,23 @@ type BlockContract = {
  * get a contract derived from their JSON schema.
  */
 export declare function blockContractsSummary(manifest?: BlockManifest): Record<string, BlockContract>;
+/**
+ * With no provider key in the environment `resolvePlannerSource` answers
+ * "demo", and every request is planned by the rule-based planner above. It
+ * handles a useful slice of literal edits — `change the hero headline to "X"` —
+ * and answers everything else with a clarifying question.
+ *
+ * That question was the defect. Someone who scaffolds the demo, types "Rewrite
+ * the hero headline" and is asked "what section should I change and what
+ * exactly should be updated?" reads it as a planner that cannot understand
+ * plain English — not as a planner that was never given a key. Shipping the
+ * demo keyless is deliberate, so that you can look around before spending
+ * anything; nothing in the product ever said so, which turned the most likely
+ * first action into a dead end.
+ *
+ * So when the rules produce no operations, say why. The suggestions are kept:
+ * they are the phrasings this planner *can* execute without a key.
+ */
+export declare const KEYLESS_PLANNER_NOTICE: string;
+export declare function withKeylessNotice(plan: EditPlan): EditPlan;
 export {};

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

@@ -603,3 +603,27 @@ export function blockContractsSummary(manifest) {
     }
     return result;
 }
+/**
+ * With no provider key in the environment `resolvePlannerSource` answers
+ * "demo", and every request is planned by the rule-based planner above. It
+ * handles a useful slice of literal edits — `change the hero headline to "X"` —
+ * and answers everything else with a clarifying question.
+ *
+ * That question was the defect. Someone who scaffolds the demo, types "Rewrite
+ * the hero headline" and is asked "what section should I change and what
+ * exactly should be updated?" reads it as a planner that cannot understand
+ * plain English — not as a planner that was never given a key. Shipping the
+ * demo keyless is deliberate, so that you can look around before spending
+ * anything; nothing in the product ever said so, which turned the most likely
+ * first action into a dead end.
+ *
+ * So when the rules produce no operations, say why. The suggestions are kept:
+ * they are the phrasings this planner *can* execute without a key.
+ */
+export const KEYLESS_PLANNER_NOTICE = "There's no AI key configured, so I'm running on the built-in demo planner — it only handles simple, literal edits. " +
+    "Add ANTHROPIC_API_KEY (or OPENAI_API_KEY) to .env.local and restart the dev server to chat for real.";
+export function withKeylessNotice(plan) {
+    if (plan.ops.length > 0)
+        return plan;
+    return { ...plan, summary_for_user: KEYLESS_PLANNER_NOTICE };
+}

package/dist/nlp/deterministic-planner.d.ts

@@ -78,7 +78,7 @@ export declare function compileDeterministicPlan(args: {
     locale?: string;
 }): EditPlan | null;
 export { extractAudienceTarget, extractAudienceTargets, titleCaseWords, addAudienceSuffix, audiencePatchForBlock, coercePatchForBlock, parseIndexedPath, inferSimpleFieldPatchFromMessage, isRewriteRequest, isTranslationRequest, shouldKeepRichTextTitleOnTranslate, inferFieldHintFromMessage, rewriteFromExisting, coercePatchForEditablePath, quotedText, buildListAppendPatch } from "./deterministic-planner-patches.ts";
-export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.ts";
+export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, withKeylessNotice, KEYLESS_PLANNER_NOTICE, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.ts";
 export { nextAvailableSlug, createPageBlocks, buildCreatePagePlan, isPageRouteRenameRequest } from "./deterministic-planner-pages.ts";
 export { readPathValue, resolveImageUrlForAltField, fetchImageAsBase64, resolveAttachmentsForLlm, selectedBlockSnapshot, arrayPropLengths, pageIntentSummary, plannerContextPack } from "./deterministic-planner-context.ts";
 export type { ResolvedLlmAttachment } from "./deterministic-planner-context.ts";

package/dist/nlp/deterministic-planner.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { allowedBlockTypes, getBlockMeta, IMAGE_PLACEHOLDER } from "@avocadostudio-ai/shared";
+import { allowedBlockTypes, catalogueBlockTypes, getBlockMeta, IMAGE_PLACEHOLDER } from "@avocadostudio-ai/shared";
 import { extractRouteMentions, normalizeRouteCandidate, parseCreatePageRequest, requestsContentGeneration, toSeedSlug } from "./intent-helpers.js";
 import { isBatchAddRequest, isFieldContentUpdateRequest, stripSiteContextEnvelope, stripPositionalAnchorPhrase, extractMentionedBlockTypes, hasCrossPageScope } from "./intent-detection.js";
 import { defaultPropsForType, inferBlockTypeFromText, nextBlockId } from "./plan-normalizer.js";
@@ -1521,7 +1521,10 @@ export function compileDeterministicPlan(args) {
             }
             return {
                 intent: "needs_clarification",
-                summary_for_user: st(args.locale, "add.specifyType", { types: allowedBlockTypes.map(blockLabel).join(", ") }),
+                // The types this site can draw, not every type registered in the process —
+                // the built-ins register transitively, so `allowedBlockTypes` would ask a
+                // person to pick from blocks their site has no renderer for.
+                summary_for_user: st(args.locale, "add.specifyType", { types: catalogueBlockTypes().map(blockLabel).join(", ") }),
                 change_log: assumptions,
                 ops: []
             };
@@ -1625,7 +1628,7 @@ export function compileDeterministicPlan(args) {
 // Re-exports from split files (preserve public API)
 // ---------------------------------------------------------------------------
 export { extractAudienceTarget, extractAudienceTargets, titleCaseWords, addAudienceSuffix, audiencePatchForBlock, coercePatchForBlock, parseIndexedPath, inferSimpleFieldPatchFromMessage, isRewriteRequest, isTranslationRequest, shouldKeepRichTextTitleOnTranslate, inferFieldHintFromMessage, rewriteFromExisting, coercePatchForEditablePath, quotedText, buildListAppendPatch } from "./deterministic-planner-patches.js";
-export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.js";
+export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, withKeylessNotice, KEYLESS_PLANNER_NOTICE, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.js";
 export { nextAvailableSlug, createPageBlocks, buildCreatePagePlan, isPageRouteRenameRequest } from "./deterministic-planner-pages.js";
 export { readPathValue, resolveImageUrlForAltField, fetchImageAsBase64, resolveAttachmentsForLlm, selectedBlockSnapshot, arrayPropLengths, pageIntentSummary, plannerContextPack } from "./deterministic-planner-context.js";
 export { inferAddedBlockTypeFromMessage, resolveBlockRef, ordinalToIndex, resolveByDescriptor, resolveReferencesFromMessage } from "./deterministic-planner-refs.js";

package/dist/nlp/intent-detection.d.ts

@@ -269,17 +269,13 @@ export declare function isPageListQuery(message: string): boolean;
  */
 export declare function hasCrossPageScope(message: string): boolean;
 export declare function isContentQuery(message: string): boolean;
-export declare function isAdviceQuery(message: string): boolean;
-export declare function adviceResponse(args: {
-    body: ChatRequestBody;
-    current: PageDoc;
-    plannerSource: "openai" | "anthropic" | "gemini" | "demo";
-    modelUsed: string;
-    modelKey: ModelKey;
-}): {
-    code: number;
-    payload: ChatResult;
+export type PageObservation = {
+    /** What is true, stated so a reader can check it. */
+    fact: string;
+    /** The edit that would resolve it, phrased as a command the planner can run. */
+    fix: string;
 };
+export declare function pageObservations(current: PageDoc): PageObservation[];
 export declare function plannerMessageWithPendingContext(session: string, message: string): string;
 /** Build the site context lines without wrapping in a message. Returns null if empty. */
 /** How many documents ride along in a planner request. */

package/dist/nlp/intent-detection.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { allowedBlockTypes, getBlockMeta, getPropDisplayName } from "@avocadostudio-ai/shared";
+import { catalogueBlockTypes, getBlockMeta, getPropDisplayName } from "@avocadostudio-ai/shared";
 import { isLikelyClarificationFollowUp, isStandalonePageOperation } from "./intent-helpers.js";
 import { versions, pendingClarificationBySession } from "../state/session-state.js";
 import { UNIT, BLOCK_CATALOG_PATTERNS, BATCH_ADD_PATTERNS, BATCH_UPDATE_PATTERNS, BATCH_PAGE_CREATE_PATTERNS, COUNTED_MULTI_BLOCK_ADD_PATTERN, ADD_ACTION_PATTERN, BLOCK_TYPE_KEYWORDS, KEYWORD_TO_BLOCK_TYPE, EACH_BLOCK_TYPE_PATTERN, PAGE_WIDE_REWRITE_PATTERNS, BATCH_REORDER_PATTERNS, PAGE_LIST_PATTERNS, CONTENT_QUERY_PATTERNS, FIELD_CONTENT_UPDATE_PATTERN, CROSS_PAGE_SCOPE_PATTERN } from "./intent-patterns.js";
@@ -297,151 +297,143 @@ export function isContentQuery(message) {
         return false;
     return CONTENT_QUERY_PATTERNS.some((re) => re.test(m));
 }
-export function isAdviceQuery(message) {
-    const m = normalizeForIntent(message);
-    // Exclude structural action requests that happen to contain "should we/I"
-    if (/\b(reorder|reorganize|restructure|rearrange|sort|move)\b/.test(m) && /\bpages?\b/.test(m))
-        return false;
-    // Exclude explicit edit verbs — "review copy for clarity" is an edit, not advice
-    // But allow "should we/I add X?" phrasing — those are advice, not commands
-    if (!/\bshould\s+(we|i)\b/.test(m) && /\b(?:add|create|remove|delete|update|change|replace|move|rewrite|translate|rename)\b/.test(m))
-        return false;
-    return (/\b(is it good|is this good|should (we|i)|do you recommend|would you recommend)\b/.test(m) ||
-        /\bwhat do you think\b/.test(m) ||
-        /\bwhat (can|should) be improved\b/.test(m) ||
-        /\bhow can (this|the) page be improved\b/.test(m) ||
-        /\bhow (can|should) i improve (this|the) page\b/.test(m) ||
-        /\bimprovements?\b/.test(m) ||
-        /\bis faq\b/.test(m) ||
-        /\bshould .*faq\b/.test(m) ||
-        /\bgood idea\b/.test(m) ||
-        /\b(?:audit|review|check|inspect|analyze)\s+(?:the\s+)?(?:this\s+)?(?:page|site|content|copy|text)\b/.test(m));
-}
-export function adviceResponse(args) {
-    const { body, current, plannerSource, modelUsed, modelKey } = args;
-    const message = (body.message ?? "").toLowerCase();
-    const pageLabel = current.slug === "/" ? "this home page" : `this page (${current.slug})`;
-    const hasFaq = current.blocks.some((block) => block.type === "FAQAccordion");
-    const hasHero = current.blocks.some((block) => block.type === "Hero");
-    const hasCta = current.blocks.some((block) => block.type === "CTA");
-    if (/\bfaq\b/.test(message)) {
-        const summary = hasFaq
-            ? `Yes, FAQ can work on ${pageLabel}, but keep it concise and near the bottom so it supports decisions without distracting from the main content.`
-            : `FAQ is usually a good fit on ${pageLabel} when visitors may have objections (pricing, process, trust, support).`;
-        const changes = hasFaq
-            ? ["Current state: FAQ already exists on this page.", "Recommendation: keep 3-6 high-intent questions."]
-            : ["Current state: no FAQ block detected on this page.", "Recommendation: add a compact FAQ section near the bottom."];
-        return {
-            code: 200,
-            payload: {
-                status: "advice",
-                summary,
-                changes,
-                suggestions: hasFaq
-                    ? ["Move FAQ to bottom", "Rewrite FAQ questions for this audience", "Keep FAQ, but reduce to 4 questions"]
-                    : ["Add FAQ section with 4 questions at the bottom", "Add FAQ below testimonials", "Skip FAQ on this page"],
-                mentionedSlugs: [current.slug],
-                previewVersion: versions.get(body.session ?? "dev") ?? 0,
-                plannerSource,
-                modelUsed,
-                modelKey
-            }
-        };
-    }
-    // Analyze existing blocks on the page
-    const existingTypes = new Set(current.blocks.map((b) => b.type));
-    const presentList = current.blocks.map((b) => {
-        const meta = getBlockMeta(b.type);
-        return meta ? `${meta.displayName}` : b.type;
-    });
-    const missingTypes = allowedBlockTypes.filter((t) => !existingTypes.has(t));
-    const changes = [];
-    changes.push(`Current blocks (${current.blocks.length}): ${presentList.join(", ") || "none"}.`);
-    if (!hasHero)
-        changes.push("Missing: Hero — consider adding a headline section at the top.");
-    if (!hasCta)
-        changes.push("Missing: CTA — add a call-to-action to drive conversions.");
-    if (!existingTypes.has("Testimonials") && !existingTypes.has("Stats"))
-        changes.push("Missing: social proof (Testimonials or Stats) — builds trust.");
-    if (!existingTypes.has("FAQAccordion"))
-        changes.push("Missing: FAQ — addresses objections and improves SEO.");
-    // Build contextual suggestions based on what's actually missing
-    const suggestions = [];
-    const suggestionPriority = [
-        { type: "Hero", label: "Add a Hero section at the top" },
-        { type: "CTA", label: "Add a CTA section to drive conversions" },
-        { type: "Testimonials", label: "Add Testimonials for social proof" },
-        { type: "Stats", label: "Add Stats to highlight key numbers" },
-        { type: "FAQAccordion", label: "Add FAQ at the bottom" },
-        { type: "FeatureGrid", label: "Add a Feature Grid to list benefits" },
-        { type: "CardGrid", label: "Add a Card Grid for related content" },
-        { type: "ContactForm", label: "Add a Contact Form" },
-        { type: "Footer", label: "Add a Footer with links" }
-    ];
-    for (const item of suggestionPriority) {
-        if (!existingTypes.has(item.type) && suggestions.length < 4)
-            suggestions.push(item.label);
-    }
-    // If page has all common blocks, suggest content improvements based on actual props
-    if (suggestions.length === 0) {
-        for (const block of current.blocks) {
-            if (suggestions.length >= 4)
-                break;
-            const p = block.props;
-            if (!p)
+/** `imageUrl` -> `image url`, for a field whose site never gave it a label. */
+function humanizePropKey(key) {
+    return key
+        .replace(/\[\]\./g, " ")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+export function pageObservations(current) {
+    const observations = [];
+    if (current.blocks.length === 0)
+        return observations;
+    const metaFor = (type) => getBlockMeta(type);
+    const nameOf = (type) => metaFor(type)?.displayName ?? type;
+    const categoryOf = (type) => metaFor(type)?.category;
+    const presentTypes = new Set(current.blocks.map((block) => block.type));
+    const addableTypes = catalogueBlockTypes().filter((type) => !presentTypes.has(type) && !metaFor(type)?.chrome);
+    /** Every declared field value on a block, list items included. */
+    const eachField = (block, visit) => {
+        const meta = metaFor(block.type);
+        if (!meta)
+            return;
+        const props = (block.props ?? {});
+        for (const [key, field] of Object.entries(meta.fields)) {
+            if (!field.internal)
+                visit(key, field, props[key]);
+        }
+        for (const [listKey, listMeta] of Object.entries(meta.listFields ?? {})) {
+            const items = props[listKey];
+            if (!Array.isArray(items))
                 continue;
-            if (block.type === "Hero") {
-                const heading = (p.heading ?? p.title ?? "");
-                if (!p.imageUrl && !p.backgroundImage) {
-                    suggestions.push("Add a hero image");
-                }
-                else if (heading && heading.length > 60) {
-                    suggestions.push("Shorten the hero headline to under 60 characters");
-                }
-                else if (heading) {
-                    suggestions.push("Rewrite the hero headline to be more action-oriented");
-                }
-            }
-            if (block.type === "Stats") {
-                const items = (p.items ?? p.stats);
-                if (items?.some((it) => (it.label ?? it.description ?? "").length > 30)) {
-                    suggestions.push("Rewrite the stats labels to be shorter and number-driven");
+            for (const item of items) {
+                if (!item || typeof item !== "object")
+                    continue;
+                const row = item;
+                const branch = listMeta.discriminator
+                    ? listMeta.itemFieldsByType?.[String(row[listMeta.discriminator])] ?? listMeta.itemFields
+                    : listMeta.itemFields;
+                for (const [key, field] of Object.entries(branch)) {
+                    if (!field.internal)
+                        visit(`${listKey}[].${key}`, field, row[key]);
                 }
             }
-            if (block.type === "CTA") {
-                const btn = (p.buttonText ?? p.ctaText ?? "");
-                if (btn.length > 20) {
-                    suggestions.push("Shorten the CTA button text");
-                }
+        }
+    };
+    const filled = (value) => typeof value === "string" && value.trim().length > 0;
+    let hasImageAnywhere = false;
+    let hasLinkAnywhere = false;
+    /*
+     * Keyed by block type + field rather than pushed per occurrence: an empty
+     * avatar on every row of a testimonials list is one finding about one field,
+     * and the first version of this reported it once per row.
+     */
+    const emptyImages = new Map();
+    for (const block of current.blocks) {
+        eachField(block, (key, field, value) => {
+            // `getPropDisplayName` takes (blockType, propKey) in that order, and falls
+            // back to the raw key when a field declares no label — so a site that
+            // never labelled its props would otherwise be told about "imageUrl".
+            const fieldLabel = field.label ?? humanizePropKey(getPropDisplayName(block.type, key));
+            if (field.kind === "image" || field.kind === "imageList") {
+                if (filled(value) || (Array.isArray(value) && value.length > 0))
+                    hasImageAnywhere = true;
                 else {
-                    suggestions.push("Strengthen the CTA copy to create urgency");
+                    const id = `${block.type}:${key}`;
+                    const seen = emptyImages.get(id);
+                    if (seen)
+                        seen.count += 1;
+                    else
+                        emptyImages.set(id, { block: nameOf(block.type), label: fieldLabel, count: 1 });
                 }
             }
-        }
-        // Fallback if no content-specific suggestions were derived
-        if (suggestions.length === 0) {
-            if (hasHero)
-                suggestions.push("Rewrite the hero headline");
-            if (hasCta)
-                suggestions.push("Strengthen the CTA copy");
-            suggestions.push("Tighten the copy across all sections");
-        }
+            if ((field.kind === "url" || field.kind === "link") && filled(value))
+                hasLinkAnywhere = true;
+        });
     }
-    const summary = `For ${pageLabel} with ${current.blocks.length} block${current.blocks.length === 1 ? "" : "s"}: ${missingTypes.length > 0 ? `consider adding ${missingTypes.slice(0, 3).join(", ")}` : "all major sections are covered — focus on refining content"}.`;
-    return {
-        code: 200,
-        payload: {
-            status: "advice",
-            summary,
-            changes,
-            suggestions,
-            mentionedSlugs: [current.slug],
-            previewVersion: versions.get(body.session ?? "dev") ?? 0,
-            plannerSource,
-            modelUsed,
-            modelKey
-        }
-    };
+    /*
+     * A structural gap is only worth raising when the page really lacks the thing
+     * *and* this site has something to fill it with. The filler types are
+     * alternatives, so they are offered as a choice.
+     *
+     * The category is read off the *catalogue*, never off the page: an earlier
+     * version asked "is any block on this page of category media" and told a home
+     * page carrying a hero with a photograph that it was all text. A block's
+     * category says what kind of block it is. Only the value says what is on the
+     * page.
+     */
+    const addableIn = (category) => addableTypes.filter((type) => categoryOf(type) === category);
+    const orList = (types) => types.slice(0, 3).map(nameOf).join(" or ");
+    if (!hasImageAnywhere) {
+        const media = addableIn("media");
+        observations.push({
+            fact: media.length > 0
+                ? `No image anywhere on this page — every block is text. This site can add: ${orList(media)}.`
+                : "No image anywhere on this page — every block is text.",
+            fix: media.length > 0 ? `Add ${nameOf(media[0])}` : "Add an image to the first section"
+        });
+    }
+    if (!hasLinkAnywhere) {
+        const conversion = addableIn("conversion");
+        observations.push({
+            fact: conversion.length > 0
+                ? `Nothing on this page links anywhere — no button or link has a destination. This site can add: ${orList(conversion)}.`
+                : "Nothing on this page links anywhere — no button or link has a destination.",
+            fix: conversion.length > 0 ? `Add ${nameOf(conversion[0])}` : "Give the buttons a destination"
+        });
+    }
+    /*
+     * Only worth saying when the page has images elsewhere. On a page with none,
+     * "no image anywhere" above is the finding, and one "this block's image is
+     * empty" per block underneath it is the same fact restated per row.
+     */
+    for (const hole of hasImageAnywhere ? [...emptyImages.values()].slice(0, 3) : []) {
+        const many = hole.count > 1 ? ` (${hole.count} of them)` : "";
+        observations.push({
+            fact: `${hole.block} declares ${hole.label.toLowerCase()} and it is empty${many}.`,
+            fix: `Add ${hole.label.toLowerCase()} to ${hole.block}`
+        });
+    }
+    const meta = current.meta;
+    if (!filled(meta?.description)) {
+        observations.push({
+            fact: "This page has no meta description — search results and link previews fall back to whatever text comes first.",
+            fix: "Write a meta description for this page"
+        });
+    }
+    /*
+     * No length check, and there was one for an afternoon. It flagged any
+     * single-line `text` field over sixty characters as an overlong headline, and
+     * the first thing it found on a real page was the hero's *subheading* at 160
+     * characters — which is prose, and fine. Nothing in the manifest says which
+     * text field is a headline and which is a paragraph, so the check asserted a
+     * role it could not know. Judging whether a sentence is too long is the
+     * model's job, and the model can now see the sentence.
+     */
+    return observations;
 }
 // A pending clarification only contextualizes the answer that immediately follows it.
 // One left unanswered for longer than this is stale (a prior session's leftover, or the
@@ -676,19 +668,37 @@ export function infoResponse(args) {
         };
     }
     if (isBlockCatalogQuery(body.message ?? "")) {
+        /*
+         * "What can I add?" is a question about this site, and it used to be
+         * answered with `allowedBlockTypes` — every type registered in the process,
+         * which importing `@avocadostudio-ai/shared` at all fills with the
+         * built-ins. A site rendering its own types was handed a list of thirty-two
+         * and five worked examples naming blocks it does not have, down to the
+         * placement anchors ("add Testimonials below Hero" on a page with neither).
+         * Every name here now comes from the catalogue, and the anchor from a block
+         * that is actually on the page.
+         */
+        const catalogue = catalogueBlockTypes().filter((type) => !getBlockMeta(type)?.chrome);
+        const nameOf = (type) => getBlockMeta(type)?.displayName ?? type;
+        const presentTypes = new Set(current.blocks.map((block) => block.type));
+        const addable = catalogue.filter((type) => !presentTypes.has(type));
+        // A real block on this page, to anchor an example against. Undefined on an
+        // empty page, where "at the end" is the only placement that means anything.
+        const anchor = current.blocks.length > 0 ? nameOf(current.blocks[current.blocks.length - 1].type) : undefined;
+        const examples = (addable.length > 0 ? addable : catalogue).slice(0, 5).map((type, i) => anchor && i % 2 === 1 ? `Add ${nameOf(type)} below ${anchor}` : `Add ${nameOf(type)} at the end`);
         return {
             code: 200,
             payload: {
                 status: "info",
-                summary: `You can add these block types: ${allowedBlockTypes.join(", ")}.`,
-                changes: ["Tip: specify position, e.g. \u201cadd Testimonials below Hero\u201d."],
-                suggestions: [
-                    "Add Testimonials below Hero",
-                    "Add CardGrid at the end",
-                    "Add FeatureGrid after Hero",
-                    "Add FAQAccordion before CTA",
-                    "Add CTA at the end"
+                summary: catalogue.length > 0
+                    ? `You can add these block types: ${catalogue.map(nameOf).join(", ")}.`
+                    : "This site has not registered any block types yet, so there is nothing to add.",
+                changes: [
+                    anchor
+                        ? `Tip: specify position, e.g. \u201cadd ${nameOf((addable[0] ?? catalogue[0]))} below ${anchor}\u201d.`
+                        : "Tip: specify position, e.g. \u201cadd it at the end\u201d."
                 ],
+                suggestions: examples,
                 previewVersion: versions.get(body.session ?? "dev") ?? 0,
                 plannerSource,
                 modelUsed,

package/dist/nlp/intent-patterns.js

@@ -210,7 +210,18 @@ export const CONTENT_QUERY_PATTERNS = [
     /\bsummarize\s+(?:this|the)\s+(?:page|content)\b/,
     /\bwhat\s+(?:blocks?|sections?)\s+(?:are|is)\s+(?:on|in)\s+(?:this|the)\s+page\b/,
     /\b(?:list|show|tell me)\b.*\b(?:all|every)\b.*\b(?:blocks?|sections?|components?)\b.*\b(?:on|in)\b/,
-    /\b(?:audit|review|check|inspect|analyze)\s+(?:the\s+)?(?:page|content|copy|text|links?|images?|buttons?|hero|cta|testimonials?|faq|feature\s*grid|card\s*grid|stats?|footer|contact\s*form|rich\s*text|two\s*column|carousel|gallery|tabs?|table|quote|video|embed|banner|section|block)\b/,
+    /\b(?:audit|review|check|inspect|analyze)\s+(?:the\s+|this\s+|my\s+)?(?:page|site|content|copy|text|links?|images?|buttons?|hero|cta|testimonials?|faq|feature\s*grid|card\s*grid|stats?|footer|contact\s*form|rich\s*text|two\s*column|carousel|gallery|tabs?|table|quote|video|embed|banner|section|block)\b/,
+    /*
+     * Page-feedback questions. These used to be intercepted by `isAdviceQuery`
+     * and answered from a template; they are judgement questions, so they belong
+     * to the model, and matching them here is what gets the model the full props
+     * it needs to answer about actual copy rather than about block names.
+     */
+    /\b(?:what do you think|any (?:thoughts|feedback|suggestions)|is (?:it|this) good)\b/,
+    /\bwhat\s+(?:can|should)\s+(?:be\s+)?improve/,
+    /\bhow\s+(?:can|should)\s+(?:i|we)?\s*improve\b/,
+    /\bimprovements?\b/,
+    /\b(?:do|would)\s+you\s+recommend\b/,
     /\bdescribe\s+(?:this|the|that)\s+(?:image|photo|picture|icon|logo|illustration|page|site|content|section)\b/,
 ];
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -20,10 +20,10 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
     "openai": "^4.87.1",
-    "sharp": "^0.34.5",
+    "sharp": "^0.35.4",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/shared": "^0.8.0",
-    "@avocadostudio-ai/migration-sdk": "^0.8.0"
+    "@avocadostudio-ai/shared": "^0.9.0",
+    "@avocadostudio-ai/migration-sdk": "^0.9.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",