@avocadostudio-ai/orchestrator-core 0.13.1 → 0.14.0

package/dist/chat/chat-pipeline.js

@@ -4,12 +4,13 @@ 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, 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 { versions, pendingClarificationBySession, chatHistoryBySession, continuationChainBySession, imageSourcePreferenceBySession, getSessionDraft, getPage, setPage, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, pushChatHistory, schedulePersistState, removePage, getSuggestionMemory, recordSuggestionsShown, recordSuggestionClicked } from "../state/session-state.js";
 import { getSiteAssets } from "../state/site-assets.js";
 import { loadPendingPlan, savePendingPlan, clearPendingPlan } from "../durable/pending-plan-store.js";
 import { envFlag } from "../env-flags.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 { buildSuggestions, toLegacySuggestions } from "../nlp/suggestion-engine.js";
 import { clarificationSuggestions, postEditSuggestions, keepDemoExecutable, 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";
@@ -186,17 +187,49 @@ export function setGeneratePlanWithAnthropicForTests(fn) {
     generatePlanWithAnthropicImpl = fn ?? generatePlanWithAnthropic;
 }
 /**
- * Suggestions, narrowed to what will answer when there is no key.
+ * Rank, validate and record the pills for one turn.
  *
- * A no-op the moment any provider is configured — with a model behind the chat,
- * every phrasing these generators produce is answerable, which is what they
- * were written against. Without one the answer comes from a substring matcher
- * that knows a handful of literal phrases, and the rest are dead buttons.
+ * Replaces `usableSuggestions`, which did one job — drop the chips a keyless
+ * demo planner cannot answer — and did it only on the keyless path. That left
+ * the strongest instrument in the file pointed at the path that matters least:
+ * the demo chips were verified executable, and the keyed chips almost every
+ * real user sees went to the wire exactly as the model wrote them.
+ *
+ * Now every candidate — model, page gap, refinement, structure, site context —
+ * passes the same validator and competes on the same scale, the keyless
+ * executability filter still runs last on the path that needs it, and what was
+ * shown is recorded so the next turn can stop offering it.
  */
-function usableSuggestions(suggestions, source, slug, body) {
-    if (source !== "demo")
-        return suggestions;
-    return keepDemoExecutable(suggestions, slug, body.activeBlockId, body.activeBlockType);
+function resolveSuggestions(args) {
+    const memory = args.session ? getSuggestionMemory(args.session) : { shown: [], clicked: [] };
+    let ranked = buildSuggestions({
+        page: args.page,
+        mode: args.mode,
+        plan: args.plan,
+        modelSuggestions: args.modelSuggestions,
+        fallbackSuggestions: args.fallbackSuggestions,
+        shown: new Set(memory.shown),
+        clicked: new Set(memory.clicked),
+        availableSlugs: args.availableSlugs,
+        sitePurpose: args.body.sitePurpose,
+        siteTone: typeof args.body.siteContext === "object" ? args.body.siteContext?.tone : undefined
+    });
+    /*
+     * The keyless path, last. With no provider the answer comes from
+     * `demoPlanFromMessage`, a short list of literal English matchers, and a pill
+     * is sent verbatim on click — so a phrasing the matcher does not know is a
+     * dead button on the first screen of an install whose banner promises "no API
+     * key needed to look around". Returning fewer, or none, is the intended
+     * outcome.
+     */
+    if (args.source === "demo") {
+        const executable = new Set(keepDemoExecutable(ranked.map((entry) => entry.prompt), args.slug, args.body.activeBlockId, args.body.activeBlockType));
+        ranked = ranked.filter((entry) => executable.has(entry.prompt));
+    }
+    if (args.session && ranked.length > 0) {
+        recordSuggestionsShown(args.session, ranked.map((entry) => entry.id));
+    }
+    return { suggestions: toLegacySuggestions(ranked), suggestionsV2: ranked };
 }
 let demoPlanFromMessageImpl = demoPlanFromMessage;
 export function setDemoPlanFromMessageForTests(fn) {
@@ -739,7 +772,22 @@ export async function runChatPipeline(ctx, body, options) {
                         promptHash,
                         promptExcerpt,
                         promptLength: plannerMessage.length,
-                        totalDurationMs: doneAtMs
+                        totalDurationMs: doneAtMs,
+                        /*
+                         * Read straight off the payload rather than plumbed through the
+                         * pipeline: this is the one place that sees every finished turn,
+                         * and `suggestionsV2` is already on the object. `clickedSuggestionId`
+                         * on the same row is what closes the loop — it says this turn was a
+                         * click on a pill offered earlier, and the `opCount` recorded for
+                         * the turn says whether that click was worth making.
+                         */
+                        ...(payload.suggestionsV2?.length
+                            ? {
+                                suggestionIds: payload.suggestionsV2.map((entry) => entry.id),
+                                suggestionSources: payload.suggestionsV2.map((entry) => entry.source)
+                            }
+                            : {}),
+                        ...(body.clickedSuggestionId ? { clickedSuggestionId: body.clickedSuggestionId } : {})
                     });
                 }
                 return stageTimeline.slice();
@@ -779,6 +827,15 @@ export async function runChatPipeline(ctx, body, options) {
         promptLength: plannerMessage.length,
         totalDurationMs: 0
     });
+    /*
+     * A clicked pill is one the user acted on: it must not be offered again, and
+     * the ranker drops a clicked id outright. Recorded here, before any branch
+     * can return, so it holds for every outcome — including the ones that answer
+     * without planning anything.
+     */
+    if (body.session && body.clickedSuggestionId) {
+        recordSuggestionClicked(body.session, body.clickedSuggestionId);
+    }
     if (executionMode === "auto") {
         const existingPendingPlan = await loadPendingPlan(body.session);
         const normalizedIncomingMessage = typeof body.message === "string" ? body.message.trim() : "";
@@ -1127,7 +1184,15 @@ export async function runChatPipeline(ctx, body, options) {
                     summary: "I need one more detail before applying this safely.",
                     changes: [],
                     mentionedSlugs: [effectiveSlug],
-                    suggestions: usableSuggestions(clarificationSuggestions({ body, current, selected }), args.source, effectiveSlug, body),
+                    ...resolveSuggestions({
+                        fallbackSuggestions: clarificationSuggestions({ body, current, selected }),
+                        mode: "clarification",
+                        page: current,
+                        source: args.source,
+                        slug: effectiveSlug,
+                        session: body.session,
+                        body
+                    }),
                     previewVersion: versions.get(body.session) ?? 0,
                     plannerSource: args.source,
                     modelUsed,
@@ -1751,7 +1816,16 @@ export async function runChatPipeline(ctx, body, options) {
                         summary: resolvedPlan.summary_for_user,
                         changes: resolvedPlan.change_log,
                         mentionedSlugs: collectMentionedSlugsFromPlan(resolvedPlan, effectiveSlug),
-                        suggestions: usableSuggestions(resolvedPlan.suggested_next_actions ?? clarificationSuggestions({ body, current, selected }), source, effectiveSlug, body),
+                        ...resolveSuggestions({
+                            modelSuggestions: resolvedPlan.suggested_next_actions,
+                            fallbackSuggestions: clarificationSuggestions({ body, current, selected }),
+                            mode: "clarification",
+                            page: current,
+                            source,
+                            slug: effectiveSlug,
+                            session: body.session,
+                            body
+                        }),
                         previewVersion: versions.get(body.session) ?? 0,
                         plannerSource: source,
                         modelUsed,
@@ -2655,7 +2729,20 @@ export async function runChatPipeline(ctx, body, options) {
                         summary: futureToPastTense(resolvedPlan.summary_for_user),
                         changes: [...opChangeLogEntries, ...metaChangeLogEntries, ...aiInsightChanges, ...skippedSummary],
                         mentionedSlugs: collectMentionedSlugsFromPlan(resolvedPlan, updatedSlug ?? effectiveSlug),
-                        suggestions: usableSuggestions(resolvedPlan.suggested_next_actions ?? postEditSuggestions({ plan: resolvedPlan, current, body }), plannerSource, updatedSlug ?? effectiveSlug, body),
+                        ...resolveSuggestions({
+                            modelSuggestions: resolvedPlan.suggested_next_actions,
+                            fallbackSuggestions: postEditSuggestions({ plan: resolvedPlan, current, body }),
+                            mode: "followup",
+                            // The post-apply page, not `current`: a gap the edit just filled
+                            // must not still be offered as a suggestion, and `current` is the
+                            // pre-apply snapshot.
+                            page: getSessionDraft(body.session).get(updatedSlug ?? effectiveSlug) ?? current,
+                            plan: resolvedPlan,
+                            source: plannerSource,
+                            slug: updatedSlug ?? effectiveSlug,
+                            session: body.session,
+                            body
+                        }),
                         previewVersion,
                         focusBlockId,
                         updatedSlug,

package/dist/chat/prompts.js

@@ -134,7 +134,23 @@ function buildLightweightPlannerPrompt(opts) {
         RULE_ICON_FORMAT,
         "Use future tense in summary_for_user and change_log — your output streams to the user while the plan is still being generated, before any ops have been applied. Say 'Will update the heading…' or 'Will replace the Hero image…', never 'Updated…' or 'Updating…'. The system flips to past tense automatically once ops are applied.",
         "For edit_plan: summary_for_user must be ONE short sentence (max ~20 words).",
-        "After planning ops, include suggested_next_actions: 2-4 short imperative phrases the user could type next (max 6 words each). Every suggestion must be an action the user can perform inside this editor (editing content, adding/removing sections, changing images, rewriting copy) — restricted to the block types listed in the block catalogue provided in context (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video). NEVER suggest unsupported features like forms, email capture, contact forms, subscribe boxes, newsletter signups, popups, modals, or anything requiring custom code. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy. 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', 'Use a warmer opening'). Remaining suggestions can target neighboring fields or blocks. NEVER suggest undoing, reverting, or restoring earlier content. You cannot read the undo history, so such a suggestion resolves to either a refusal or an invented replacement presented as the original — the editor's own Undo button is the affordance for that, and it already works.",
+        /*
+         * The block list here used to be the twenty Avocado built-ins, spelled out
+         * verbatim, on every request — including requests from sites whose
+         * catalogue is entirely their own. On those the prompt was actively
+         * steering the model toward blocks the site has no renderer for, and
+         * `add_block` for one of those applies cleanly, reports success and draws
+         * nothing. `opts.effectiveBlockTypes` is the list that is true for THIS
+         * site, and it was already on the options object.
+         *
+         * The long tail of "NEVER suggest forms / popups / A/B tests / undo" is
+         * shortened, not because the model may now do those things but because
+         * saying it at length three times across two prompts never stopped it:
+         * nothing checked the output. `suggestion-engine.ts` now rejects every one
+         * of them on every candidate whatever its source. What is left is the short
+         * form, which still saves the model from spending a slot on one.
+         */
+        `After planning ops, include suggested_next_actions: 2-4 short imperative phrases the user could type next (max 6 words each). Each must be a complete instruction the editor can execute \u2014 name the change, not just the field ("Make it shorter", not "Edit heading"). The only block types on this site are: ${opts.effectiveBlockTypes.join(", ")}. Never suggest a section outside that list, anything needing custom code (forms, popups, checkout), anything outside the editor (A/B tests, analytics), or undoing/reverting. When the plan contains exactly one update_props op on a text field, the first 1-2 suggestions MUST refine that same field.`,
         opts.selectedBlockId.length > 0
             ? `Selected block is ${opts.selectedBlockId}. Target only this block in ops when the request edits the current page. IGNORE this selection when the request operates on a different scope — creating, duplicating, renaming, removing, or moving a page; editing site config; or naming a different page — and emit ops only for the requested scope. Never add bonus ops on the selected block to satisfy this rule.`
             : "Respect explicit user target references when present.",
@@ -250,7 +266,24 @@ 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 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', 'Use a warmer opening'). 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 listed in blockContracts / blockCatalogue for THIS site, or SEO/site-config edits. Never suggest adding a section this site has no block for; the catalogue is the whole list, not a sample of a larger one. 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. NEVER suggest undoing, reverting, or restoring earlier content. You cannot read the undo history, so such a suggestion resolves to either a refusal or an invented replacement presented as the original — the editor's own Undo button is the affordance for that, and it already works.");
+    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", 
+    /*
+     * Shortened from about 1,900 characters, and the deleted half was all
+     * prohibition: no forms, no email capture, no popups, no chat widgets, no
+     * payment, no A/B tests, no analytics, no user research, no undo, no block
+     * outside the catalogue. Every one of those was also stated in the
+     * lightweight prompt, and none of them was ever checked \u2014
+     * `suggested_next_actions` went to the wire exactly as written.
+     *
+     * They are predicates now, in `suggestion-engine.ts`, applied to every
+     * candidate whatever produced it. The short form stays so the model does
+     * not spend a slot on a suggestion that will be dropped; what it no longer
+     * has to do is carry the enforcement.
+     *
+     * What is kept in full is the part no validator can check: that a good
+     * suggestion is a follow-up to THIS edit rather than a generic next move.
+     */
+    "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 \u2014 not a generic action. 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', 'Use a warmer opening'). After rewriting stats labels, refine the same section ('Make the numbers bigger', 'Add a stat about X') \u2014 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. Each must name the change and not just the field: 'Make it shorter', never 'Edit heading' \u2014 the planner knows the field and not the value, so the latter can only be answered with a question. NEVER suggest 'Open /X' or any navigation to a page the current plan is still creating; suggestions are sent verbatim as the next chat command and there is no navigation handler. Restricted to the block types in blockContracts / blockCatalogue for THIS site, or SEO/site-config edits \u2014 the catalogue is the whole list, not a sample. No forms, popups, checkout or anything else needing custom code; nothing outside the editor such as A/B testing or analytics; never undo, revert or restore.");
     return lines;
 }
 /*

package/dist/handler/create-orchestrator.js

@@ -31,7 +31,9 @@ import { runChatPipeline, collectMentionedSlugsFromOps } from "../chat/chat-pipe
 import { createChatTelemetryStore } from "../telemetry/chat-telemetry.js";
 import { createToolRuntime } from "../tools/runtime.js";
 import { envFlag } from "../env-flags.js";
-import { loadStateFromDisk, scopedSessionKey, getSessionPages, getPage, getSiteConfig, setSiteConfig, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, schedulePersistState, normalizeSiteId, publishStatusBySession, pushPublishLogEntry, persistenceHealth, persistenceWarning } from "../state/session-state.js";
+import { loadStateFromDisk, scopedSessionKey, getSessionPages, getPage, getSiteConfig, setSiteConfig, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, schedulePersistState, normalizeSiteId, publishStatusBySession, pushPublishLogEntry, persistenceHealth, persistenceWarning, getSuggestionMemory } from "../state/session-state.js";
+import { buildSuggestions } from "../nlp/suggestion-engine.js";
+import { keepDemoExecutable } from "../nlp/deterministic-planner-suggestions.js";
 import { defaultModelLookup, defaultProviders } from "../chat/model-defaults.js";
 import { historyStatus, historyLog, historyUndoAction, historyRedoAction, historyRestoreAction, historyDiscardAction } from "../http/history-actions.js";
 import { whoamiAction } from "../http/session-actions.js";
@@ -261,6 +263,7 @@ const SUPPORTED_ROUTES = [
     "POST /publish",
     "GET /status/planner",
     "GET /draft/pages",
+    "GET /suggestions",
     "GET /draft/slugs",
     "POST /draft/bootstrap",
     "GET+PUT /draft/site-config",
@@ -1208,6 +1211,62 @@ export function createOrchestrator(config = {}) {
                 return jsonResponse({ error: "not found" }, { status: 404, cors });
             return jsonResponse(structuredClone(page), { status: 200, cors });
         }
+        /*
+         * The pills for a page nobody has chatted about yet.
+         *
+         * The editor used to derive its opening suggestions in the browser, from
+         * the list of block *types* on the page and a table of translated strings.
+         * It could not see what was in those blocks, so it offered "Add an FAQ
+         * section" to a page that already had one until a guard was written for
+         * that specific case, and it had no way at all to notice that the hero's
+         * image was empty or that the page had no meta description.
+         *
+         * The engine can see all of that, and it is the same engine that ranks the
+         * pills after every later turn — so the first screen and the tenth now
+         * answer "what next?" the same way.
+         */
+        if (request.method === "GET" && path === "/suggestions") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const session = url.searchParams.get("session") ?? undefined;
+            const siteId = url.searchParams.get("siteId") ?? undefined;
+            const slug = url.searchParams.get("slug");
+            if (!session || !slug) {
+                return jsonResponse({ error: "session and slug are required" }, { status: 400, cors });
+            }
+            const scopedSession = scope(session, siteId);
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const page = getPage(scopedSession, slug);
+            if (!page)
+                return jsonResponse({ error: "not found" }, { status: 404, cors });
+            const memory = getSuggestionMemory(scopedSession);
+            let suggestionsV2 = buildSuggestions({
+                page,
+                shown: new Set(memory.shown),
+                clicked: new Set(memory.clicked),
+                siteTone: url.searchParams.get("tone") ?? undefined
+            });
+            /*
+             * With no provider configured a pill is answered by `demoPlanFromMessage`
+             * — a short list of literal English matchers — and the pill text is sent
+             * verbatim on click, so anything the matcher does not know is a dead
+             * button. These are the first three a new user sees, under a banner
+             * promising no API key is needed to look around. The caller says whether
+             * that is the situation; the editor is already showing that badge.
+             */
+            if (url.searchParams.get("keyless") === "true") {
+                const executable = new Set(keepDemoExecutable(suggestionsV2.map((entry) => entry.prompt), slug));
+                suggestionsV2 = suggestionsV2.filter((entry) => executable.has(entry.prompt));
+            }
+            /*
+             * Deliberately NOT recorded as shown. The welcome row is re-fetched
+             * whenever the site's identity resolves late — which in production is
+             * every load, because the auth handshake makes `/status/planner` lose the
+             * race — so recording here would decay a pill on the same screen that
+             * first drew it.
+             */
+            return jsonResponse({ suggestions: suggestionsV2.map((entry) => entry.prompt), suggestionsV2 }, { status: 200, cors });
+        }
         // Page list. Also flips the editor's `hasBootstrapped` gate — until this
         // returns a non-empty list, the property panel never enables its fetch.
         if (request.method === "GET" && path === "/draft/slugs") {

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, Cm
 export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel, type JsonFileAdapterOptions, type EditorApiAdapterOptions, type CmsMediaSource, type CmsMediaUploader, type CmsMediaSourceConfig } from "./cms/index.ts";
 export { registerPublishTarget, selectPublishTarget, getPublishTarget, listPublishTargets } from "./publish/publish-target-registry.ts";
 export type { PublishTarget, PublishContext, PublishOutcome, PublishStatus, PublishResult } from "./publish/publish-target.ts";
+export { buildSuggestions, validateSuggestion, toLegacySuggestions, suggestionId, SUGGESTION_LIMIT } from "./nlp/suggestion-engine.ts";
+export type { Suggestion, SuggestionCandidate, SuggestionContext, SuggestionKind, SuggestionMode, SuggestionSource, ValidationFailure } from "./nlp/suggestion-engine.ts";
 export { SqliteDurableStore, InMemoryDurableStore, getDurableStore, resetDurableStore, setDurableStore, durableStoreIsEphemeral, type SqliteDurableStoreOptions, type InMemoryDurableStoreOptions, type DurableStore, type FindingInput, type FindingRecord, type FindingQuery, type FindingSeverity, type FindingStatus, type FindingEvidence, type CheckRunInput, type CheckRunRecord, type CheckRunPatch, type CheckRunTrigger, type MemoryInput, type MemoryRecord, type MemoryQuery, type MemoryScope, type MemoryKind, type MemorySource, type MemoryStatus, type CorrectionInput, type CorrectionRecord, type CorrectionQuery, type CorrectionOutcome, type ProposalInput, type ProposalRecord, type ProposalQuery, type ProposalStatus } from "./durable/index.ts";
 export { runDraftChecks, runChecksForSession, scheduleChecksAfterApply, scheduleChecksAfterPublish, cancelScheduledChecks, fingerprintFor, DRAFT_RULES, walkPageFields, fieldText, type RunChecksArgs, type CheckRule, type CheckContext, type RuleFinding, type FieldEntry, type SiteView } from "./checks/index.ts";
 export { runChecksAction, listFindingsAction, listCheckRunsAction, updateFindingAction, type RunChecksParams, type ListFindingsParams, type UpdateFindingParams, type ChecksScope } from "./http/checks-actions.ts";

package/dist/index.js

@@ -40,6 +40,17 @@ export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource,
 // integration point for "S3, GitLab Pages, Netlify, a CMS API, a custom CI/CD
 // pipeline". Only the export was missing.
 export { registerPublishTarget, selectPublishTarget, getPublishTarget, listPublishTargets } from "./publish/publish-target-registry.js";
+// The suggestion engine. `Suggestion` is public because it is a field on
+// `ChatResult` — a consumer installing from the registry that reads
+// `suggestionsV2` off a chat response has no other specifier that reaches the
+// type, and an unreachable type on a public response shape is the defect this
+// file's header describes.
+//
+// `validateSuggestion` and `buildSuggestions` are public for the other half:
+// a library-mode host rendering its own pill UI should be able to rank and
+// check candidates with the same rules the orchestrator applies, rather than
+// reimplementing the list of things the editor cannot build.
+export { buildSuggestions, validateSuggestion, toLegacySuggestions, suggestionId, SUGGESTION_LIMIT } from "./nlp/suggestion-engine.js";
 // The durable substrate for findings, memory, corrections and proposals. It is
 // public because the implementation is meant to be replaceable: a library-mode
 // host on a serverless platform has no persistent disk for a SQLite file, and

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type BlockType, type EditPlan, type PageDoc, type PublishDiff, type Operation } from "@avocadostudio-ai/shared";
+import type { Suggestion } from "./suggestion-engine.ts";
 import { type ModelKey } from "../state/session-state.ts";
 import { type GuardrailErrorCategory } from "../errors.ts";
 export type { GuardrailErrorCategory };
@@ -97,6 +98,7 @@ export declare const chatRequestBodySchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         bytes: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+    clickedSuggestionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ChatRequestBody = z.infer<typeof chatRequestBodySchema>;
 /** Per-op outcome surfaced to the editor for the plan-preview card. Mirrors the engine's OpResult. */
@@ -113,6 +115,17 @@ export type ChatResult = {
     changes: string[];
     mentionedSlugs?: string[];
     suggestions?: string[];
+    /**
+     * The same suggestions, with the structure the pills are actually ranked and
+     * measured with: a stable id to join telemetry on, a label that can be
+     * shorter than the command it sends, and the source and evidence behind it.
+     *
+     * Additive on purpose. `suggestions: string[]` is part of this package's
+     * published surface and site-sdk and every other integrator read it;
+     * it stays, and it is a projection of this field
+     * (`suggestionsV2.map(s => s.prompt)`), so the two cannot disagree.
+     */
+    suggestionsV2?: Suggestion[];
     validationErrors?: unknown;
     previewVersion: number;
     focusBlockId?: string;

package/dist/nlp/intent-detection.js

@@ -54,6 +54,18 @@ export const chatRequestBodySchema = z.object({
     pendingPlanId: z.string().optional(),
     continuationChainId: z.string().optional(),
     attachments: z.array(chatAttachmentSchema).max(6).optional(),
+    /**
+     * Set when this message came from clicking a suggestion pill rather than from
+     * typing.
+     *
+     * Carried on the request the click already sends, rather than through a
+     * separate endpoint: the click *is* a chat turn, so there is nothing to
+     * correlate afterwards and no extra round trip to lose. It is what makes a
+     * pill measurable — until now nothing recorded which suggestions were shown,
+     * which were clicked, or whether a click produced any operations, so the
+     * question "are the pills any good" had no answer at all.
+     */
+    clickedSuggestionId: z.string().max(64).optional(),
 });
 // ---------------------------------------------------------------------------
 // Shared normaliser used by all intent detectors below.

package/dist/nlp/suggestion-engine.d.ts

@@ -0,0 +1,191 @@
+/**
+ * One engine for suggestion pills.
+ *
+ * A pill is the only thing in this product that speaks first. Everything else
+ * the editor does, it does because somebody typed it. That makes a pill worth
+ * more than its size on screen and also more dangerous: `onSuggestionClick` is
+ * `text => submitChat(text)`, so the label is the prompt, sent verbatim, and a
+ * pill the planner cannot answer is a button that does nothing.
+ *
+ * Five separate pieces of code used to answer "what next?" — the editor's
+ * welcome builder, the model's `suggested_next_actions`, three deterministic
+ * fallbacks, six hardcoded arrays, and the property panel's field pills. They
+ * shared no type, no vocabulary and no quality bar, and every one of them ended
+ * in `.slice(0, 4)` over an append-ordered list, so the order a pill appeared
+ * in was the order somebody had typed it into a source file.
+ *
+ * This module replaces the ranking half of that. Candidates arrive from several
+ * cheap sources — the model among them, with a high prior but no privilege —
+ * pass one validator, and are scored against each other. The model can lose.
+ *
+ * The validator is the other half of the point. The planner prompts carry about
+ * 1,400 characters of "NEVER suggest forms / popups / A/B tests / undo /
+ * questions / blocks this site cannot draw", stated three times across two
+ * prompts and enforced nowhere: `suggested_next_actions` went to the wire
+ * untouched. Every one of those rules is a predicate here, applied to every
+ * candidate regardless of where it came from.
+ */
+import { type EditPlan, type PageDoc } from "@avocadostudio-ai/shared";
+export type SuggestionKind = 
+/** Refines the thing the last edit just touched. */
+"refine"
+/** Fills a hole the page actually has — an empty image, a missing description. */
+ | "fill-gap"
+/** Adds a section this site has a renderer for. */
+ | "add-section"
+/** Page/site structure: new pages, ordering, navigation. */
+ | "structure"
+/** Search metadata. */
+ | "seo" | "other";
+export type SuggestionSource = "model" | "page-gap" | "refinement" | "structure" | "context";
+export type Suggestion = {
+    /**
+     * Stable across turns for the same prompt — this is the join key that session
+     * memory dedupes on and that telemetry reports, so it must not embed a
+     * timestamp, a turn index or anything else that moves.
+     */
+    id: string;
+    /** What the pill reads. Short enough to fit a chip. */
+    label: string;
+    /**
+     * What is sent on click. May be longer and more specific than the label —
+     * splitting the two is what lets a pill read "Add author photos" while
+     * sending a command the planner can actually execute. Before this existed,
+     * one string had to be both good chip copy and a complete instruction, and
+     * that tension is why the "Edit heading"-shaped pills had to be deleted
+     * outright rather than reworded.
+     */
+    prompt: string;
+    kind: SuggestionKind;
+    source: SuggestionSource;
+    score: number;
+    /** Why this was offered. Carried into telemetry; never shown to the user. */
+    evidence?: string;
+};
+export type SuggestionCandidate = {
+    label: string;
+    prompt?: string;
+    kind: SuggestionKind;
+    source: SuggestionSource;
+    /** Source-level confidence before page-state scoring. 0..1. */
+    prior: number;
+    evidence?: string;
+};
+/**
+ * What kind of turn these pills belong to — which changes what a good pill is.
+ *
+ * A `followup` pill is a standalone command: it is sent verbatim and has to
+ * stand on its own, so "Edit heading" is a dead button.
+ *
+ * A `clarification` pill is an *answer to a question the assistant just asked*.
+ * It does not travel alone: `plannerMessageWithPendingContext` composes it with
+ * the request that triggered the clarification, so "Edit heading" arrives at
+ * the planner as the original sentence plus "Clarification from user: Edit
+ * heading" — which resolves. Applying the follow-up rules here would delete
+ * every answer to the question and leave the user a row of unrelated
+ * suggestions instead.
+ */
+export type SuggestionMode = "followup" | "clarification";
+export type SuggestionContext = {
+    page: PageDoc;
+    mode?: SuggestionMode;
+    /** The plan that just ran (or is held for approval), when there was one. */
+    plan?: EditPlan;
+    /** `suggested_next_actions` as the model returned them. */
+    modelSuggestions?: string[];
+    /**
+     * The path's own deterministic fallback — `clarificationSuggestions` or
+     * `postEditSuggestions`. A candidate source like any other, so it competes
+     * instead of being used only when the model said nothing.
+     */
+    fallbackSuggestions?: string[];
+    /** Ids already shown to this session. */
+    shown?: ReadonlySet<string>;
+    /** Ids this session has clicked. */
+    clicked?: ReadonlySet<string>;
+    /** Free-text site purpose / tone, when the user has filled it in. */
+    sitePurpose?: string;
+    siteTone?: string;
+    /** Slugs that exist on the site, for structure candidates. */
+    availableSlugs?: string[];
+    limit?: number;
+};
+/** Three, not four. See `rank`. */
+export declare const SUGGESTION_LIMIT = 3;
+/**
+ * A content hash of the prompt, normalized so that casing and trailing
+ * punctuation do not mint a new id for the same suggestion. Deliberately not a
+ * cryptographic hash — this is a dedupe key, not a security boundary, and a
+ * short stable string is easier to read in a telemetry row.
+ */
+export declare function suggestionId(prompt: string): string;
+export type ValidationFailure = "empty" | "too_long" | "question_or_offer" | "undo" | "unsupported_feature" | "underspecified" | "unrenderable_block";
+export declare function validateSuggestion(text: string, opts?: {
+    mode?: SuggestionMode;
+}): ValidationFailure | null;
+/**
+ * The model's own suggestions, as candidates.
+ *
+ * A high prior — the model is the only source that read the user's sentence and
+ * the page's topic, and when it is right it is more specific than anything
+ * derivable. But it competes, and when it returns four variations on "add a
+ * section" the diversity rule in `rank` will keep one of them.
+ */
+export declare function modelCandidates(raw: string[] | undefined): SuggestionCandidate[];
+/**
+ * Holes the page actually has.
+ *
+ * `pageObservations` already walks every declared field and returns
+ * `{ fact, fix }`, where `fix` is phrased as a command the planner can run. It
+ * was computed on every turn and handed to the model as prose — the one
+ * candidate source grounded in what is wrong with the page in front of the
+ * user, and the pill builders never saw it.
+ */
+export declare function pageGapCandidates(page: PageDoc): SuggestionCandidate[];
+/**
+ * Refinements of the field the last edit just touched.
+ *
+ * The planner prompt asks for this in so many words — "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" — and nothing has ever
+ * guaranteed it. Deriving it costs nothing and does.
+ */
+export declare function refinementCandidates(plan: EditPlan | undefined, page: PageDoc): SuggestionCandidate[];
+/**
+ * Sections this site can draw and this page does not have.
+ *
+ * Read off `catalogueBlockTypes()` — never off the built-in names. A site's
+ * catalogue is the whole list, not a sample of a larger one.
+ */
+export declare function structureCandidates(page: PageDoc, availableSlugs?: string[]): SuggestionCandidate[];
+/**
+ * The site's own voice, when the user has told us what it is.
+ *
+ * `sitePurpose` and tone reach the planner's context pack already; until now
+ * the only pills that used them were the welcome ones, and only as a template.
+ */
+export declare function contextCandidates(args: {
+    sitePurpose?: string;
+    siteTone?: string;
+}): SuggestionCandidate[];
+/**
+ * Score, deduplicate, diversify, cap.
+ *
+ * The cap is three rather than four, and returning fewer than three — or none —
+ * is a valid answer. Three real suggestions beat six of which one works, and an
+ * empty row leaves whatever the assistant said as the thing on screen, which is
+ * usually the more useful object anyway.
+ */
+export declare function rank(candidates: SuggestionCandidate[], ctx: SuggestionContext): Suggestion[];
+/**
+ * The path's own deterministic fallback, as candidates.
+ *
+ * Given a slightly lower prior than the model's: when both have an opinion the
+ * model read the user's sentence and this did not. It still competes, and on
+ * the clarification path — where it is answering a specific question — it
+ * routinely wins.
+ */
+export declare function fallbackCandidates(raw: string[] | undefined): SuggestionCandidate[];
+export declare function buildSuggestions(ctx: SuggestionContext): Suggestion[];
+/** The legacy wire shape: what `suggestions: string[]` has always carried. */
+export declare function toLegacySuggestions(suggestions: Suggestion[]): string[];

package/dist/nlp/suggestion-engine.js

@@ -0,0 +1,477 @@
+/**
+ * One engine for suggestion pills.
+ *
+ * A pill is the only thing in this product that speaks first. Everything else
+ * the editor does, it does because somebody typed it. That makes a pill worth
+ * more than its size on screen and also more dangerous: `onSuggestionClick` is
+ * `text => submitChat(text)`, so the label is the prompt, sent verbatim, and a
+ * pill the planner cannot answer is a button that does nothing.
+ *
+ * Five separate pieces of code used to answer "what next?" — the editor's
+ * welcome builder, the model's `suggested_next_actions`, three deterministic
+ * fallbacks, six hardcoded arrays, and the property panel's field pills. They
+ * shared no type, no vocabulary and no quality bar, and every one of them ended
+ * in `.slice(0, 4)` over an append-ordered list, so the order a pill appeared
+ * in was the order somebody had typed it into a source file.
+ *
+ * This module replaces the ranking half of that. Candidates arrive from several
+ * cheap sources — the model among them, with a high prior but no privilege —
+ * pass one validator, and are scored against each other. The model can lose.
+ *
+ * The validator is the other half of the point. The planner prompts carry about
+ * 1,400 characters of "NEVER suggest forms / popups / A/B tests / undo /
+ * questions / blocks this site cannot draw", stated three times across two
+ * prompts and enforced nowhere: `suggested_next_actions` went to the wire
+ * untouched. Every one of those rules is a predicate here, applied to every
+ * candidate regardless of where it came from.
+ */
+import { catalogueBlockTypes, getBlockMeta } from "@avocadostudio-ai/shared";
+import { pageObservations } from "./intent-detection.js";
+/** Three, not four. See `rank`. */
+export const SUGGESTION_LIMIT = 3;
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+/**
+ * A content hash of the prompt, normalized so that casing and trailing
+ * punctuation do not mint a new id for the same suggestion. Deliberately not a
+ * cryptographic hash — this is a dedupe key, not a security boundary, and a
+ * short stable string is easier to read in a telemetry row.
+ */
+export function suggestionId(prompt) {
+    const normalized = prompt.trim().toLowerCase().replace(/[.!?]+$/, "").replace(/\s+/g, " ");
+    let h1 = 0x811c9dc5;
+    let h2 = 0x01000193;
+    for (let i = 0; i < normalized.length; i += 1) {
+        const c = normalized.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+        h2 = Math.imul(h2 + c, 0x85ebca6b) >>> 0;
+    }
+    return `s_${h1.toString(36)}${h2.toString(36)}`;
+}
+/**
+ * Phrased as a question or an offer rather than a command.
+ *
+ * The prompt has told the model "NEVER phrase suggestions as questions
+ * ('Would you like me to…?')" since the page-feedback rule was written. A pill
+ * that reads "Would you like me to shorten it?" sends that string to the
+ * planner, which answers the question instead of doing the thing.
+ */
+const QUESTION_OR_OFFER = /^\s*(would|should|shall|could|can|do|does|did|is|are|want|how|what|why|when|where|which|who)\b|^\s*i\s+(can|could|will|would|might)\b|^\s*(let me|let's|maybe|perhaps|consider)\b/i;
+/**
+ * Undo, revert, restore.
+ *
+ * The model cannot read the undo history, so such a suggestion resolves to
+ * either a refusal or an invented replacement presented as the original. The
+ * editor's own Undo button is the affordance, and it works.
+ */
+const UNDO_REQUEST = /\b(undo|revert|restore|roll\s?back|rolled back|put\s+(?:it|them|that|the\s+\w+)\s+back|bring\s+back|go back to the (?:previous|old|earlier))\b/i;
+/**
+ * Capabilities the editor does not have. Each of these requires code the block
+ * pipeline cannot produce, so the planner's only honest answer is a refusal —
+ * after the user has spent a click and, on a keyed plan, a model call finding
+ * that out.
+ */
+const UNSUPPORTED_FEATURE = new RegExp([
+    // interactive widgets requiring custom code
+    "\\bforms?\\b", "\\bcontact form\\b", "\\bemail capture\\b", "\\bsubscribe\\b",
+    "\\bnewsletter\\b", "\\bsign[- ]?up form\\b", "\\bpop[- ]?ups?\\b", "\\bmodals?\\b",
+    "\\bchat widget\\b", "\\blive chat\\b", "\\bpayments?\\b", "\\bcheckout\\b",
+    "\\bshopping cart\\b", "\\bbooking (?:system|engine)\\b", "\\blogin\\b",
+    // out-of-scope activities
+    "\\ba/?b test", "\\bsplit test", "\\banalytics\\b", "\\bheat ?maps?\\b",
+    "\\bperformance monitoring\\b", "\\buser research\\b", "\\bmarketing strategy\\b",
+    "\\bconversion tracking\\b", "\\bemail campaign\\b"
+].join("|"), "i");
+/**
+ * Names the target and not the change.
+ *
+ * "Edit heading", "Edit CTA", "Update link" — the planner knows the field and
+ * not the value, so the only possible answer is "edit it to what?". Three
+ * clean-room runs measured the same outcome: zero operations, and on a keyed
+ * plan about $0.012 and five seconds to be asked a question the pill existed to
+ * avoid. `postEditSuggestions` learned this and stopped emitting the shape; the
+ * model never did, because nothing checked its output.
+ *
+ * Verbs that already imply "produce new content" — rewrite, shorten, punch up —
+ * are not caught: those are complete instructions on their own. Only the pure
+ * mutation verbs need a direction to be actionable.
+ */
+const MUTATION_VERB = /^\s*(edit|change|update|modify|adjust|tweak|set|customi[sz]e)\b/i;
+const DIRECTION_MARKER = /\b(to|into|so|with|for|as|using|toward|towards|about|around|more|less|fewer|shorter|longer|bolder|warmer|punchier|friendlier|clearer|simpler|stronger|tighter|bigger|smaller)\b|["'“”]|\d/i;
+/**
+ * Words a user would read as the name of a section, mapped to the built-in type
+ * behind them.
+ *
+ * This vocabulary exists to answer one question: is this pill proposing to add
+ * a block this site has no renderer for? `add_block` for an unregistered type
+ * applies cleanly, reports success and draws nothing — so the suggestion is not
+ * merely unhelpful, it is a trap, and `advice-catalogue.test.ts` documents the
+ * same trap being sprung on the advice path for months.
+ *
+ * Checked ONLY in an add/create context. A site whose hero is called
+ * `adv_heroSplit` still has a hero, and "Rewrite the hero headline" is a fine
+ * suggestion there — the planner resolves that by position and content, not by
+ * type name. It is only *adding* that needs a renderer to exist.
+ */
+const BUILTIN_SECTION_WORDS = [
+    [/\btestimonials?\b/i, "Testimonials"],
+    [/\bfaq\b|\bfrequently asked\b|\baccordion\b/i, "FAQAccordion"],
+    [/\bfeature grid\b|\bfeatures grid\b|\bfeature section\b/i, "FeatureGrid"],
+    [/\bcard grid\b|\bcards? section\b/i, "CardGrid"],
+    [/\bcall[- ]to[- ]action\b|\bcta\b/i, "CTA"],
+    [/\bhero\b/i, "Hero"],
+    [/\bbanner\b/i, "Banner"],
+    [/\bcarousel\b|\bslider\b/i, "Carousel"],
+    [/\bgallery\b/i, "Gallery"],
+    [/\bquote\b/i, "Quote"],
+    [/\bstats?\b|\bstatistics\b/i, "Stats"],
+    [/\btable\b/i, "Table"],
+    [/\btabs\b/i, "Tabs"],
+    [/\bvideo\b/i, "Video"],
+    [/\bfooter\b/i, "Footer"],
+    [/\brich ?text\b|\btext section\b/i, "RichText"],
+    [/\btwo[- ]column\b/i, "TwoColumn"],
+    [/\bembed\b/i, "Embed"]
+];
+const ADD_INTENT = /^\s*(add|create|insert|include|append|put in|drop in)\b/i;
+/**
+ * Does this site have something that answers to this name?
+ *
+ * Checked against the catalogue's own display names and types first, so a site
+ * that calls its testimonials block `pba_voices` with display name "Voices"
+ * still matches a suggestion that says "voices". Only when nothing in the
+ * catalogue answers do we fall back to asking whether the phrase names an
+ * Avocado built-in that this site does not have.
+ */
+function catalogueAnswersTo(text) {
+    const lower = text.toLowerCase();
+    for (const type of catalogueBlockTypes()) {
+        const meta = getBlockMeta(type);
+        if (meta?.chrome)
+            continue;
+        const display = meta?.displayName;
+        if (display && lower.includes(display.toLowerCase()))
+            return true;
+        // Split camelCase / snake-prefixed type names into words: `adv_eventCards`
+        // reads as "event cards", which is how a suggestion would spell it.
+        const words = type
+            .replace(/^[a-z]{2,4}_/, "")
+            .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+            .toLowerCase();
+        if (words.length > 2 && lower.includes(words))
+            return true;
+    }
+    return false;
+}
+function namesUnrenderableBlock(text) {
+    if (!ADD_INTENT.test(text))
+        return false;
+    if (catalogueAnswersTo(text))
+        return false;
+    const catalogue = new Set(catalogueBlockTypes());
+    for (const [pattern, builtinType] of BUILTIN_SECTION_WORDS) {
+        if (pattern.test(text) && !catalogue.has(builtinType))
+            return true;
+    }
+    return false;
+}
+/** Longest a pill may be before it stops reading as a pill. */
+const MAX_LABEL_CHARS = 60;
+export function validateSuggestion(text, opts) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return "empty";
+    if (trimmed.length > MAX_LABEL_CHARS * 2)
+        return "too_long";
+    if (trimmed.endsWith("?") || QUESTION_OR_OFFER.test(trimmed))
+        return "question_or_offer";
+    if (UNDO_REQUEST.test(trimmed))
+        return "undo";
+    if (UNSUPPORTED_FEATURE.test(trimmed))
+        return "unsupported_feature";
+    // Skipped in clarification mode: the pill is an answer composed with the
+    // pending request, not a standalone command. See `SuggestionMode`.
+    if (opts?.mode !== "clarification" && MUTATION_VERB.test(trimmed) && !DIRECTION_MARKER.test(trimmed)) {
+        return "underspecified";
+    }
+    if (namesUnrenderableBlock(trimmed))
+        return "unrenderable_block";
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Candidate sources
+// ---------------------------------------------------------------------------
+/**
+ * The model's own suggestions, as candidates.
+ *
+ * A high prior — the model is the only source that read the user's sentence and
+ * the page's topic, and when it is right it is more specific than anything
+ * derivable. But it competes, and when it returns four variations on "add a
+ * section" the diversity rule in `rank` will keep one of them.
+ */
+export function modelCandidates(raw) {
+    if (!raw || raw.length === 0)
+        return [];
+    return raw.slice(0, 6).map((text) => ({
+        label: text.trim(),
+        kind: inferKind(text),
+        source: "model",
+        prior: 0.8,
+        evidence: "planner suggested_next_actions"
+    }));
+}
+function inferKind(text) {
+    if (/\bmeta description\b|\bseo\b|\bsearch result\b|\bpage title\b/i.test(text))
+        return "seo";
+    if (/\bpage\b/i.test(text) && /^\s*(add|create|rename|delete|reorder|move)\b/i.test(text))
+        return "structure";
+    if (/^\s*(add|create|insert|include)\b/i.test(text))
+        return "add-section";
+    if (/^\s*(rewrite|shorten|lengthen|punch|polish|make|try|use)\b/i.test(text))
+        return "refine";
+    return "other";
+}
+/**
+ * Holes the page actually has.
+ *
+ * `pageObservations` already walks every declared field and returns
+ * `{ fact, fix }`, where `fix` is phrased as a command the planner can run. It
+ * was computed on every turn and handed to the model as prose — the one
+ * candidate source grounded in what is wrong with the page in front of the
+ * user, and the pill builders never saw it.
+ */
+export function pageGapCandidates(page) {
+    return pageObservations(page).map((observation) => ({
+        label: observation.fix,
+        kind: /meta description|search result/i.test(observation.fact) ? "seo" : "fill-gap",
+        source: "page-gap",
+        // Below the model's prior: a gap is real but it is not necessarily what the
+        // user is thinking about right now. It wins when the model offers nothing
+        // better, which on a page with holes in it is often.
+        prior: 0.65,
+        evidence: observation.fact
+    }));
+}
+/**
+ * Refinements of the field the last edit just touched.
+ *
+ * The planner prompt asks for this in so many words — "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" — and nothing has ever
+ * guaranteed it. Deriving it costs nothing and does.
+ */
+export function refinementCandidates(plan, page) {
+    if (!plan)
+        return [];
+    const updates = plan.ops.filter((op) => op.op === "update_props");
+    if (updates.length !== 1)
+        return [];
+    const [op] = updates;
+    if (!op || op.op !== "update_props")
+        return [];
+    const patch = op.patch;
+    const textKeys = Object.entries(patch)
+        .filter(([, value]) => typeof value === "string" && value.trim().length > 0)
+        .map(([key]) => key);
+    if (textKeys.length === 0)
+        return [];
+    const block = page.blocks.find((entry) => entry.id === op.blockId);
+    const noun = describeField(block?.type, textKeys[0]);
+    return [
+        { label: "Make it shorter", kind: "refine", source: "refinement", prior: 0.75, evidence: `refines ${noun}` },
+        { label: "Try a bolder tone", kind: "refine", source: "refinement", prior: 0.7, evidence: `refines ${noun}` },
+        { label: `Rewrite ${noun} again`, kind: "refine", source: "refinement", prior: 0.6, evidence: `refines ${noun}` }
+    ];
+}
+function describeField(blockType, key) {
+    const meta = blockType ? getBlockMeta(blockType) : undefined;
+    const label = meta?.fields?.[key]?.label;
+    if (label)
+        return `the ${label.toLowerCase()}`;
+    const humanized = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+    return `the ${humanized}`;
+}
+/**
+ * Sections this site can draw and this page does not have.
+ *
+ * Read off `catalogueBlockTypes()` — never off the built-in names. A site's
+ * catalogue is the whole list, not a sample of a larger one.
+ */
+export function structureCandidates(page, availableSlugs) {
+    const present = new Set(page.blocks.map((block) => block.type));
+    const candidates = [];
+    const addable = catalogueBlockTypes().filter((type) => !present.has(type) && !getBlockMeta(type)?.chrome);
+    /*
+     * Conversion first, then content, then media. On a page that has no way to
+     * convert, adding one is the change most likely to matter; layout and
+     * navigation blocks are chrome-adjacent and rarely what someone wants
+     * suggested. Without this the order is registration order, which is not a
+     * ranking — it is the order somebody wrote the imports in.
+     *
+     * The category is read off the catalogue, which is the only list that knows
+     * what this site can draw.
+     */
+    const byCategory = (category) => addable.filter((type) => getBlockMeta(type)?.category === category);
+    const ordered = [...byCategory("conversion"), ...byCategory("content"), ...byCategory("media")];
+    for (const type of ordered.slice(0, 3)) {
+        const name = getBlockMeta(type)?.displayName ?? type;
+        candidates.push({
+            label: `Add ${name}`,
+            prompt: `Add a ${name} section to this page`,
+            kind: "add-section",
+            source: "structure",
+            prior: 0.5,
+            evidence: `${type} is in this site's catalogue and not on this page`
+        });
+    }
+    if (availableSlugs && availableSlugs.length > 0 && !availableSlugs.includes("/about")) {
+        candidates.push({
+            label: "Create an /about page",
+            kind: "structure",
+            source: "structure",
+            prior: 0.35,
+            evidence: "site has no /about"
+        });
+    }
+    return candidates;
+}
+/**
+ * The site's own voice, when the user has told us what it is.
+ *
+ * `sitePurpose` and tone reach the planner's context pack already; until now
+ * the only pills that used them were the welcome ones, and only as a template.
+ */
+export function contextCandidates(args) {
+    const candidates = [];
+    const tone = args.siteTone?.trim();
+    if (tone && tone.length < 30) {
+        candidates.push({
+            label: `Rewrite this page to sound more ${tone}`,
+            kind: "refine",
+            source: "context",
+            prior: 0.45,
+            evidence: `site tone is "${tone}"`
+        });
+    }
+    return candidates;
+}
+// ---------------------------------------------------------------------------
+// Ranking
+// ---------------------------------------------------------------------------
+/**
+ * Score, deduplicate, diversify, cap.
+ *
+ * The cap is three rather than four, and returning fewer than three — or none —
+ * is a valid answer. Three real suggestions beat six of which one works, and an
+ * empty row leaves whatever the assistant said as the thing on screen, which is
+ * usually the more useful object anyway.
+ */
+export function rank(candidates, ctx) {
+    const shown = ctx.shown ?? new Set();
+    const clicked = ctx.clicked ?? new Set();
+    const limit = ctx.limit ?? SUGGESTION_LIMIT;
+    const scored = [];
+    const seenIds = new Set();
+    for (const candidate of candidates) {
+        const label = candidate.label.trim();
+        const prompt = (candidate.prompt ?? label).trim();
+        const failure = validateSuggestion(prompt, { mode: ctx.mode });
+        if (failure)
+            continue;
+        const id = suggestionId(prompt);
+        if (seenIds.has(id))
+            continue;
+        seenIds.add(id);
+        /*
+         * Novelty. A pill the user was already offered and did not click is one
+         * they have declined once; offering it again every turn is how "Add
+         * Testimonials" came to appear on turn 1 and turn 9 of the same session.
+         * A clicked pill is dropped outright — it has been acted on, and the page
+         * has moved past it.
+         */
+        if (clicked.has(id))
+            continue;
+        const score = shown.has(id) ? candidate.prior - 0.3 : candidate.prior;
+        scored.push({
+            id,
+            label: label.length > MAX_LABEL_CHARS ? `${label.slice(0, MAX_LABEL_CHARS - 1).trimEnd()}…` : label,
+            prompt,
+            kind: candidate.kind,
+            source: candidate.source,
+            score,
+            evidence: candidate.evidence
+        });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    /*
+     * Diversity. Three pills that all say "add a section" are one suggestion
+     * wearing three hats — the user's choice is not between them, it is between
+     * doing that and doing something else. At most one per kind until every kind
+     * has had a turn.
+     */
+    const picked = [];
+    const usedKinds = new Set();
+    for (const suggestion of scored) {
+        if (picked.length >= limit)
+            break;
+        if (usedKinds.has(suggestion.kind))
+            continue;
+        picked.push(suggestion);
+        usedKinds.add(suggestion.kind);
+    }
+    for (const suggestion of scored) {
+        if (picked.length >= limit)
+            break;
+        if (picked.some((entry) => entry.id === suggestion.id))
+            continue;
+        picked.push(suggestion);
+    }
+    return picked;
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * The path's own deterministic fallback, as candidates.
+ *
+ * Given a slightly lower prior than the model's: when both have an opinion the
+ * model read the user's sentence and this did not. It still competes, and on
+ * the clarification path — where it is answering a specific question — it
+ * routinely wins.
+ */
+export function fallbackCandidates(raw) {
+    if (!raw || raw.length === 0)
+        return [];
+    return raw.map((text) => ({
+        label: text.trim(),
+        kind: inferKind(text),
+        source: "structure",
+        prior: 0.7,
+        evidence: "deterministic fallback for this path"
+    }));
+}
+export function buildSuggestions(ctx) {
+    /*
+     * A clarification asked a question. The only useful pills are answers to it,
+     * which is what the model's suggestions and the path's own fallback are —
+     * page gaps and section nudges are follow-ups to a *completed* edit and would
+     * change the subject while the question is still on screen.
+     */
+    if (ctx.mode === "clarification") {
+        return rank([...modelCandidates(ctx.modelSuggestions), ...fallbackCandidates(ctx.fallbackSuggestions)], ctx);
+    }
+    const candidates = [
+        ...modelCandidates(ctx.modelSuggestions),
+        ...fallbackCandidates(ctx.fallbackSuggestions),
+        ...refinementCandidates(ctx.plan, ctx.page),
+        ...pageGapCandidates(ctx.page),
+        ...structureCandidates(ctx.page, ctx.availableSlugs),
+        ...contextCandidates({ sitePurpose: ctx.sitePurpose, siteTone: ctx.siteTone })
+    ];
+    return rank(candidates, ctx);
+}
+/** The legacy wire shape: what `suggestions: string[]` has always carried. */
+export function toLegacySuggestions(suggestions) {
+    return suggestions.map((suggestion) => suggestion.prompt);
+}

package/dist/state/session-state.d.ts

@@ -164,6 +164,30 @@ export declare const pendingApprovalPlanBySession: Map<string, PendingApprovalPl
  */
 export type ImageSourcePreference = "unsplash" | "genai" | "either";
 export declare const imageSourcePreferenceBySession: Map<string, ImageSourcePreference>;
+/**
+ * Which suggestion pills this session has already been shown, and which it
+ * clicked.
+ *
+ * A pill offered and not clicked is one the user has declined once. Nothing
+ * recorded that, so the same three chips were re-derived from the same page
+ * state every turn and "Add Testimonials" appeared on turn 1 and again on turn
+ * 9 of the same conversation. The ranker reads these to decay a repeat and to
+ * drop a suggestion that has been acted on.
+ *
+ * Ephemeral, like its neighbours above: a chat session is the right lifetime
+ * for "have I already offered you this", and there is nothing here worth
+ * carrying across a restart. Capped so a long session cannot grow it without
+ * bound.
+ */
+export declare const SUGGESTION_MEMORY_CAP = 60;
+export type SuggestionMemory = {
+    shown: string[];
+    clicked: string[];
+};
+export declare const suggestionMemoryBySession: Map<string, SuggestionMemory>;
+export declare function getSuggestionMemory(session: string): SuggestionMemory;
+export declare function recordSuggestionsShown(session: string, ids: string[]): void;
+export declare function recordSuggestionClicked(session: string, id: string): void;
 export declare const publishStatusBySession: Map<string, PublishTracker>;
 /**
  * What the adapter behind a session says it can honour, recorded when the

package/dist/state/session-state.js

@@ -99,6 +99,44 @@ export const pendingClarificationBySession = new Map();
 export const chatHistoryBySession = new Map();
 export const pendingApprovalPlanBySession = new Map();
 export const imageSourcePreferenceBySession = new Map();
+/**
+ * Which suggestion pills this session has already been shown, and which it
+ * clicked.
+ *
+ * A pill offered and not clicked is one the user has declined once. Nothing
+ * recorded that, so the same three chips were re-derived from the same page
+ * state every turn and "Add Testimonials" appeared on turn 1 and again on turn
+ * 9 of the same conversation. The ranker reads these to decay a repeat and to
+ * drop a suggestion that has been acted on.
+ *
+ * Ephemeral, like its neighbours above: a chat session is the right lifetime
+ * for "have I already offered you this", and there is nothing here worth
+ * carrying across a restart. Capped so a long session cannot grow it without
+ * bound.
+ */
+export const SUGGESTION_MEMORY_CAP = 60;
+export const suggestionMemoryBySession = new Map();
+export function getSuggestionMemory(session) {
+    return suggestionMemoryBySession.get(session) ?? { shown: [], clicked: [] };
+}
+function rememberSuggestionIds(session, field, ids) {
+    if (ids.length === 0)
+        return;
+    const memory = suggestionMemoryBySession.get(session) ?? { shown: [], clicked: [] };
+    // Newest last, deduplicated, oldest evicted first — so a suggestion that
+    // scrolled out of memory long ago can legitimately be offered again.
+    const merged = [...memory[field].filter((id) => !ids.includes(id)), ...ids];
+    suggestionMemoryBySession.set(session, {
+        ...memory,
+        [field]: merged.slice(-SUGGESTION_MEMORY_CAP)
+    });
+}
+export function recordSuggestionsShown(session, ids) {
+    rememberSuggestionIds(session, "shown", ids);
+}
+export function recordSuggestionClicked(session, id) {
+    rememberSuggestionIds(session, "clicked", [id]);
+}
 export const publishStatusBySession = new Map();
 /**
  * What the adapter behind a session says it can honour, recorded when the
@@ -178,6 +216,7 @@ export function forgetSession(sessionKey) {
     // left behind here would rehydrate into the *next* session with this id.
     discardPendingProposalsForSession(sessionKey);
     imageSourcePreferenceBySession.delete(sessionKey);
+    suggestionMemoryBySession.delete(sessionKey);
     publishStatusBySession.delete(sessionKey);
     capabilitiesBySession.delete(sessionKey);
     return existed;
@@ -1134,7 +1173,12 @@ export function evictStaleEphemeralMaps() {
         }
     }
     // Maps without timestamps — cap at EPHEMERAL_MAP_CAP, drop oldest-inserted entries
-    for (const map of [continuationChainBySession, pendingClarificationBySession, imageSourcePreferenceBySession]) {
+    for (const map of [
+        continuationChainBySession,
+        pendingClarificationBySession,
+        imageSourcePreferenceBySession,
+        suggestionMemoryBySession
+    ]) {
         if (map.size > EPHEMERAL_MAP_CAP) {
             const excess = map.size - EPHEMERAL_MAP_CAP;
             let dropped = 0;

package/dist/telemetry/chat-telemetry.d.ts

@@ -49,6 +49,20 @@ export type ChatTelemetryEntry = {
     toolAttempts?: number;
     toolErrorCode?: string;
     correlationId?: string;
+    /**
+     * Suggestion pills: what was offered on this turn, and whether this turn was
+     * itself a click on one.
+     *
+     * There was no telemetry of any kind on pills before this — `grep suggestion`
+     * across this directory returned nothing — so which chips get clicked, which
+     * are ignored, and whether a click produced any operations were all unknown.
+     * That made "the suggestions should be smarter" an unfalsifiable claim.
+     * `suggestionIds` joins to `clickedSuggestionId` on a later turn, and the
+     * `opCount` already on that turn says whether the click was worth the click.
+     */
+    suggestionIds?: string[];
+    suggestionSources?: string[];
+    clickedSuggestionId?: string;
 };
 type Logger = {
     info: (payload: Record<string, unknown>, message?: string) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -22,8 +22,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.35.4",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "^0.13.1",
-    "@avocadostudio-ai/shared": "^0.13.1"
+    "@avocadostudio-ai/migration-sdk": "^0.14.0",
+    "@avocadostudio-ai/shared": "^0.14.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",