@agent-native/core 0.92.10 → 0.92.12

package/corpus/templates/content/app/components/editor/DocumentEditor.tsx

@@ -477,6 +477,18 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     canEdit && !bodyHydrationPending && (isLocalFileDocument || !collabLoading);
   canEditRef.current = editorCanEdit;
 
+  // Viewers intentionally join awareness so they receive live cursors, but
+  // only an editor runs the app-state flush poller below. Publish that exact
+  // capability so server-side pull/push/conflict actions do not wait on a
+  // read-only tab that can never acknowledge their request.
+  useEffect(() => {
+    if (!awareness || !collabEnabled) return;
+    awareness.setLocalStateField("canFlushDocument", editorCanEdit);
+    return () => {
+      awareness.setLocalStateField("canFlushDocument", false);
+    };
+  }, [awareness, collabEnabled, editorCanEdit]);
+
   // Initialize from fetched document, reset on document switch
   useEffect(() => {
     if (!document) return;
@@ -813,6 +825,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
           try {
             const next = await pushDocumentToNotion.mutateAsync({
               documentId,
+              // The exact editor value was persisted immediately above. Avoid
+              // a redundant live-editor flush handshake on every auto-sync
+              // save; manual pushes/conflict choices keep the safe default.
+              flushOpenEditor: false,
             });
             queryClient.setQueryData(
               documentSyncStatusQueryKey(documentId, { autoSync }),
@@ -1030,8 +1046,21 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       try {
         const res = await fetch(flushPath);
         if (res.ok) {
-          const pending = (await res.json()) as { id?: string } | null;
+          const pending = (await res.json()) as {
+            id?: string;
+            ts?: number;
+            requestId?: string;
+            status?: "pending" | "success" | "error";
+            error?: string;
+          } | null;
           if (pending && active) {
+            // A terminal acknowledgement waits for the requesting action to
+            // read and clear it. Retrying here could hide a failed flush or
+            // replace the explicit success signal before the server sees it.
+            if (pending.status === "error" || pending.status === "success") {
+              if (active) setTimeout(poll, 600);
+              return;
+            }
             const title = localTitleRef.current;
             const content = localContentRef.current;
             const updates: Record<string, string> = {};
@@ -1043,30 +1072,60 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             try {
               if (Object.keys(updates).length > 0) {
                 const saved = await persistDocumentUpdates(updates);
-                // A CAS conflict here means a newer write landed between this
-                // editor's last reconcile and the flush; leave watermarks
-                // alone so the external-change effects reconcile this editor
-                // to the winning server content instead of us claiming the
-                // now-discarded flush content as saved.
-                if (!isDocumentUpdateConflict(saved)) {
-                  const savedAt = saved?.updatedAt ?? new Date().toISOString();
-                  adoptConfirmedSaveWatermarks({
-                    saved,
-                    savedAt,
-                    title,
-                    content,
-                    updates,
-                    lastSavedTitleRef,
-                    lastSavedContentRef,
-                  });
+                if (isDocumentUpdateConflict(saved)) {
+                  // Do not acknowledge a CAS loss as a successful flush. The
+                  // requester must stop instead of pushing/replacing stale SQL.
+                  throw new Error(
+                    "The document changed while preparing it for sync.",
+                  );
                 }
+                const savedAt = saved?.updatedAt ?? new Date().toISOString();
+                adoptConfirmedSaveWatermarks({
+                  saved,
+                  savedAt,
+                  title,
+                  content,
+                  updates,
+                  lastSavedTitleRef,
+                  lastSavedContentRef,
+                });
               }
-            } finally {
-              // Acknowledge the flush even if nothing changed — the SQL row is
-              // already current, and pull-document is waiting on this delete.
+              // Explicitly acknowledge this exact request only after the live
+              // editor state is confirmed in SQL (or nothing needed saving).
+              // A delete is ambiguous with a transient app-state read failure.
               await fetch(flushPath, {
-                method: "DELETE",
-                headers: { "X-Agent-Native-CSRF": "1" },
+                method: "PUT",
+                headers: {
+                  "Content-Type": "application/json",
+                  "X-Agent-Native-CSRF": "1",
+                },
+                body: JSON.stringify({
+                  id: pending.id ?? documentId,
+                  ts: pending.ts ?? Date.now(),
+                  requestId: pending.requestId,
+                  status: "success",
+                }),
+              }).catch(() => {});
+            } catch (error) {
+              // Keep a durable negative acknowledgement so the requesting
+              // Notion action can fail closed instead of timing out and using a
+              // stale documents row. The server clears this after reading it.
+              await fetch(flushPath, {
+                method: "PUT",
+                headers: {
+                  "Content-Type": "application/json",
+                  "X-Agent-Native-CSRF": "1",
+                },
+                body: JSON.stringify({
+                  id: pending.id ?? documentId,
+                  ts: pending.ts ?? Date.now(),
+                  requestId: pending.requestId,
+                  status: "error",
+                  error:
+                    error instanceof Error
+                      ? error.message
+                      : t("editor.liveDocumentSaveBeforeSyncFailed"),
+                }),
               }).catch(() => {});
             }
           }
@@ -1082,7 +1141,13 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       active = false;
       clearTimeout(timer);
     };
-  }, [documentId, editorCanEdit, isLocalFileDocument, persistDocumentUpdates]);
+  }, [
+    documentId,
+    editorCanEdit,
+    isLocalFileDocument,
+    persistDocumentUpdates,
+    t,
+  ]);
 
   const handleTitleChange = useCallback(
     (newTitle: string) => {

package/corpus/templates/content/app/components/editor/VisualEditor.tsx

@@ -822,6 +822,28 @@ export function shouldSeedCollaborativeContent({
   return !!content.trim() && (fragmentLength === 0 || !semanticMarkdown);
 }
 
+/**
+ * Parse authoritative Content NFM with Content's exact NFM parser before the
+ * shared reconcile computes its top-level surgical diff.
+ *
+ * Falling back to the shared CommonMark parser is lossy here: canonical NFM
+ * stores one Notion block per line without blank paragraph separators, while
+ * CommonMark merges those consecutive lines into one paragraph. That made
+ * external replacements such as Notion conflict resolution and version
+ * restores look correct in the non-collaborative history preview, then collapse
+ * into one wrapped paragraph when reconciled into the live Y.Doc.
+ */
+export function parseNfmForCollabReconcile(
+  editor: CoreEditor,
+  value: string,
+): ProseMirrorNode | null {
+  try {
+    return editor.schema.nodeFromJSON(nfmToDoc(value) as any);
+  } catch {
+    return null;
+  }
+}
+
 export function shouldApplyExternalContentSync({
   docChanged,
   content,
@@ -1669,10 +1691,14 @@ export function VisualEditor({
   // Clean up awareness on unmount
   useEffect(() => {
     return () => {
-      localAwareness?.setLocalState(null);
+      // Only the fallback instance is owned by this editor. A provided
+      // awareness belongs to the shared useCollaborativeDoc connection; clearing
+      // it here races StrictMode/remounts and can erase the tab's durable
+      // presence while the shared connection is still active.
+      fallbackAwareness?.setLocalState(null);
       fallbackAwareness?.destroy();
     };
-  }, [fallbackAwareness, localAwareness]);
+  }, [fallbackAwareness]);
 
   const extensions = useMemo(
     () =>
@@ -1941,6 +1967,10 @@ export function VisualEditor({
       e.commands.setContent(doc);
     },
     normalizeValue: canonicalizeNfm,
+    // The shared fallback parser is CommonMark. Content stores canonical NFM,
+    // whose adjacent lines are separate Notion blocks, so always provide the
+    // exact NFM parser for the surgical reconcile path.
+    parseValue: parseNfmForCollabReconcile,
     shouldSeed: ({ value, currentMarkdown, fragmentLength }) =>
       editable &&
       shouldSeedCollaborativeContent({

package/corpus/templates/content/app/hooks/use-notion.ts

@@ -253,12 +253,12 @@ export function usePullDocumentFromNotion(documentId: string) {
 
 export function usePushDocumentToNotion(documentId: string) {
   const queryClient = useQueryClient();
-  return useActionMutation<DocumentSyncStatus, { documentId: string }>(
-    "push-notion-page",
-    {
-      onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
-    },
-  );
+  return useActionMutation<
+    DocumentSyncStatus,
+    { documentId: string; flushOpenEditor?: boolean }
+  >("push-notion-page", {
+    onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
+  });
 }
 
 export function useResolveDocumentSyncConflict(documentId: string) {

package/corpus/templates/content/app/i18n/zh-TW.ts

@@ -94,6 +94,7 @@ const messages = {
     couldNotReadLocalSourceFile: "無法讀取本機來源檔案",
     couldNotSaveLocalFile: "無法儲存本機檔案",
     collabConnectingReadOnly: "正在連接即時編輯器。顯示唯讀快照。",
+    liveDocumentSaveBeforeSyncFailed: "即時文件無法在同步前儲存。",
     documentTitle: "檔案標題",
     builderBodySyncing: "內容仍在從 Builder 同步",
     builderBodySyncingDescription:

package/corpus/templates/content/app/i18n-data.ts

@@ -2463,6 +2463,8 @@ const enUS = {
     couldNotSaveLocalFile: "Could not save local file",
     collabConnectingReadOnly:
       "Connecting live editor. Showing a read-only snapshot.",
+    liveDocumentSaveBeforeSyncFailed:
+      "The live document could not be saved before syncing.",
     documentTitle: "Document title",
     builderBodySyncing: "Content is still syncing from Builder",
     builderBodySyncingDescription:
@@ -4843,6 +4845,7 @@ const editorMessagesByLocale = {
   "zh-CN": {
     noDocumentSelected: "未选择文档",
     collabConnectingReadOnly: "正在连接实时编辑器。显示只读快照。",
+    liveDocumentSaveBeforeSyncFailed: "实时文档无法在同步前保存。",
     builderBodySyncing: "内容仍在从 Builder 同步",
     builderBodySyncingDescription:
       "同步 Builder 正文完成前会暂停编辑，避免覆盖现有文章内容。",
@@ -5169,6 +5172,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Ningún documento seleccionado",
     collabConnectingReadOnly:
       "Conectando el editor en vivo. Mostrando una instantánea de solo lectura.",
+    liveDocumentSaveBeforeSyncFailed:
+      "No se pudo guardar el documento activo antes de sincronizarlo.",
     builderBodySyncing: "El contenido aún se está sincronizando desde Builder",
     builderBodySyncingDescription:
       "La edición está en pausa hasta que el cuerpo de Builder termine de sincronizarse, para no sobrescribir el contenido existente del artículo.",
@@ -5506,6 +5511,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Aucun document sélectionné",
     collabConnectingReadOnly:
       "Connexion de l'éditeur en direct. Affichage d'un instantané en lecture seule.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Le document actif n’a pas pu être enregistré avant la synchronisation.",
     builderBodySyncing:
       "Le contenu est encore en cours de synchronisation depuis Builder",
     builderBodySyncingDescription:
@@ -5846,6 +5853,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Kein Dokument ausgewählt",
     collabConnectingReadOnly:
       "Live-Editor wird verbunden. Schreibgeschützte Momentaufnahme wird angezeigt.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Das aktive Dokument konnte vor der Synchronisierung nicht gespeichert werden.",
     builderBodySyncing: "Inhalte werden noch von Builder synchronisiert",
     builderBodySyncingDescription:
       "Die Bearbeitung ist pausiert, bis der Builder-Textkörper fertig synchronisiert ist, damit der bestehende Artikelinhalt nicht überschrieben wird.",
@@ -6190,6 +6199,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "ドキュメントが選択されていません",
     collabConnectingReadOnly:
       "ライブエディターに接続中。読み取り専用のスナップショットを表示しています。",
+    liveDocumentSaveBeforeSyncFailed:
+      "同期前にライブドキュメントを保存できませんでした。",
     builderBodySyncing: "コンテンツはまだ Builder から同期中です",
     builderBodySyncingDescription:
       "既存の記事内容を上書きしないよう、Builder 本文の同期が完了するまで編集は一時停止されます。",
@@ -6524,6 +6535,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "선택한 문서가 없습니다.",
     collabConnectingReadOnly:
       "라이브 편집기에 연결하는 중입니다. 읽기 전용 스냅샷을 표시합니다.",
+    liveDocumentSaveBeforeSyncFailed:
+      "동기화하기 전에 실시간 문서를 저장하지 못했습니다.",
     builderBodySyncing: "콘텐츠가 아직 Builder에서 동기화되는 중입니다",
     builderBodySyncingDescription:
       "기존 문서 내용을 덮어쓰지 않도록 Builder 본문 동기화가 완료될 때까지 편집이 일시 중지됩니다.",
@@ -6857,6 +6870,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Nenhum documento selecionado",
     collabConnectingReadOnly:
       "Conectando o editor ao vivo. Exibindo um instantâneo somente leitura.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Não foi possível salvar o documento ativo antes da sincronização.",
     builderBodySyncing: "O conteúdo ainda está sincronizando do Builder",
     builderBodySyncingDescription:
       "A edição fica pausada até o corpo do Builder terminar de sincronizar, para não sobrescrever o conteúdo existente do artigo.",
@@ -7196,6 +7211,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "कोई दस्तावेज़ चयनित नहीं",
     collabConnectingReadOnly:
       "लाइव संपादक कनेक्ट हो रहा है। केवल-पठन स्नैपशॉट दिखाया जा रहा है।",
+    liveDocumentSaveBeforeSyncFailed:
+      "सिंक करने से पहले लाइव दस्तावेज़ सहेजा नहीं जा सका।",
     builderBodySyncing: "सामग्री अभी भी Builder से सिंक हो रही है",
     builderBodySyncingDescription:
       "Builder का मुख्य भाग सिंक पूरा होने तक संपादन रोका गया है, ताकि मौजूदा लेख सामग्री अधिलेखित न हो।",
@@ -7525,6 +7542,7 @@ const editorMessagesByLocale = {
     noDocumentSelected: "لم يتم تحديد أي مستند",
     collabConnectingReadOnly:
       "جارٍ الاتصال بالمحرر المباشر. يتم عرض لقطة للقراءة فقط.",
+    liveDocumentSaveBeforeSyncFailed: "تعذّر حفظ المستند المباشر قبل المزامنة.",
     builderBodySyncing: "لا يزال المحتوى قيد المزامنة من Builder",
     builderBodySyncingDescription:
       "يتم إيقاف التحرير مؤقتًا حتى تكتمل مزامنة نص Builder، حتى لا يتم استبدال محتوى المقالة الحالي.",

package/corpus/templates/content/changelog/2026-07-09-builder-source-refreshes-now-keep-mapped-fields-such-as-topi.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Builder source refreshes now keep mapped fields such as topics and tags, preserve existing rows when a read unexpectedly returns empty, and load large databases more reliably.

package/corpus/templates/content/changelog/2026-07-09-notion-conflict-choices-and-version-restores-preserve-docume.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Notion conflict choices and version restores preserve document paragraphs and protect live edits.

package/corpus/templates/content/server/lib/notion-sync.ts

@@ -2,7 +2,6 @@
 // in pnpm's node_modules. Logic is correct; types just don't unify across instances.
 import crypto from "node:crypto";
 
-import { deleteCollabState, releaseDoc } from "@agent-native/core/collab";
 import { and, eq, inArray, isNull, lt, or } from "drizzle-orm";
 import type { InferSelectModel } from "drizzle-orm";
 
@@ -37,6 +36,56 @@ function nanoid(size = 12): string {
   return Array.from(bytes, (byte) => chars[byte % chars.length]).join("");
 }
 
+async function replaceDocumentFromExternal(args: {
+  document: DocumentRow;
+  expectedUpdatedAt: string;
+  title: string;
+  content: string;
+  icon: string | null;
+  updatedAt: string;
+}): Promise<boolean> {
+  const db = getDb();
+  return db.transaction(async (tx) => {
+    const applied = await tx
+      .update(schema.documents)
+      .set({
+        title: args.title,
+        content: args.content,
+        icon: args.icon,
+        updatedAt: args.updatedAt,
+      })
+      .where(
+        and(
+          eq(schema.documents.id, args.document.id),
+          eq(schema.documents.ownerEmail, args.document.ownerEmail),
+          eq(schema.documents.updatedAt, args.expectedUpdatedAt),
+        ),
+      )
+      .returning({ id: schema.documents.id });
+
+    if (!applied || applied.length === 0) return false;
+
+    if (
+      args.title !== args.document.title ||
+      args.content !== args.document.content
+    ) {
+      // Keep the recovery snapshot in the same transaction as the replacement:
+      // a lost CAS creates no phantom version, and a snapshot failure rolls the
+      // destructive replacement back instead of leaving it unrecoverable.
+      await tx.insert(schema.documentVersions).values({
+        id: nanoid(),
+        ownerEmail: args.document.ownerEmail,
+        documentId: args.document.id,
+        title: args.document.title,
+        content: args.document.content,
+        createdAt: nowIso(),
+      });
+    }
+
+    return true;
+  });
+}
+
 /**
  * Hash of the canonical content. Two documents with the same hash are
  * byte-identical once canonicalized, so this is the authoritative "did the
@@ -827,8 +876,6 @@ async function pullDocumentFromNotionInner(
     remotePageDocumentIdByPageId?: RemotePageDocumentLookup;
   },
 ): Promise<DocumentSyncStatus> {
-  const db = getDb();
-  const document = await getDocument(documentId, owner);
   const link = await getSyncLink(documentId, owner);
   if (!link) throw new Error("Document is not linked to a Notion page.");
   const connection = await getNotionConnectionForOwner(owner);
@@ -935,28 +982,18 @@ async function pullDocumentFromNotionInner(
   // check will mistake the unchanged document for a fresh local edit.
   const updatedAt = contentChanged ? nowIso() : freshDocument.updatedAt;
   if (contentChanged) {
-    // Compare-and-swap: only apply the pulled content if the row is still at
-    // the snapshot we just re-read. If a concurrent save landed in between,
-    // 0 rows match and we fall through to the conflict path instead of
-    // clobbering the newer local write.
-    const applied = await db
-      .update(schema.documents)
-      .set({
-        title: newTitle,
-        content: newContent,
-        icon: newIcon,
-        updatedAt,
-      })
-      .where(
-        and(
-          eq(schema.documents.id, documentId),
-          eq(schema.documents.ownerEmail, owner),
-          eq(schema.documents.updatedAt, freshDocument.updatedAt),
-        ),
-      )
-      .returning({ id: schema.documents.id });
+    // Snapshot + compare-and-swap are one transaction: only the winning
+    // replacement gets a recovery version, and snapshot failure rolls it back.
+    const applied = await replaceDocumentFromExternal({
+      document: freshDocument,
+      expectedUpdatedAt: freshDocument.updatedAt,
+      title: newTitle,
+      content: newContent,
+      icon: newIcon,
+      updatedAt,
+    });
 
-    if (!applied || applied.length === 0) {
+    if (!applied) {
       // A newer local save raced in after our re-read. Do not adopt the
       // pulled content or advance the hash baseline — surface a conflict so
       // the user resolves it explicitly instead of silently losing the edit.
@@ -986,16 +1023,10 @@ async function pullDocumentFromNotionInner(
       });
     }
 
-    // Reset the Yjs collaborative state so it no longer holds the pre-sync
-    // content. Connected clients re-seed their Y.XmlFragment from the new
-    // `documents.content` value via VisualEditor's content-sync effect, and
-    // a fresh page load starts from an empty server state and seeds from SQL.
-    try {
-      await deleteCollabState(documentId);
-      releaseDoc(documentId);
-    } catch {
-      // Non-fatal — the client-side sync will still reconcile via setContent.
-    }
+    // Keep the Y.Doc intact. The live editor's updatedAt-gated reconcile applies
+    // this authoritative SQL snapshot as a minimal Yjs transaction. Deleting
+    // collab state here races connected clients (which can re-persist the stale
+    // pre-pull state) and briefly makes later flush handshakes miss the editor.
   }
 
   await upsertSyncLink({
@@ -1193,7 +1224,6 @@ async function pushDocumentToNotionInner(
   // the rare case Notion normalizes a construct differently, immediately
   // converging instead of ping-ponging. Re-read the row first so a local save
   // that landed during the multi-round-trip push isn't clobbered below.
-  const db = getDb();
   const freshDocument = await getDocument(documentId, owner);
   const newContent = remote.content ?? document.content;
   const newTitle = remote.title || document.title;
@@ -1211,39 +1241,25 @@ async function pushDocumentToNotionInner(
   // exactly what we pushed, since contentChanged is false).
   let baselineContent = document.content;
   if (contentChanged) {
-    // Compare-and-swap against the pre-push snapshot: if a concurrent save
-    // changed the row since `document` was read, skip adopting Notion's
-    // normalized content so the newer local edit is never overwritten. The
-    // hash baseline is still advanced to the *pushed* content below so the
-    // concurrent edit continues to show as localChanged and gets re-pushed on
-    // the next sync cycle.
-    const applied = await db
-      .update(schema.documents)
-      .set({
-        title: newTitle,
-        content: newContent,
-        icon: newIcon,
-        updatedAt: pushedAt,
-      })
-      .where(
-        and(
-          eq(schema.documents.id, documentId),
-          eq(schema.documents.ownerEmail, owner),
-          eq(schema.documents.updatedAt, document.updatedAt),
-        ),
-      )
-      .returning({ id: schema.documents.id });
+    // Snapshot + compare-and-swap are atomic. If a concurrent save changed the
+    // row since `document` was read, skip both the provider readback adoption
+    // and its recovery version; the newer local edit remains localChanged.
+    const applied = await replaceDocumentFromExternal({
+      document: freshDocument,
+      expectedUpdatedAt: document.updatedAt,
+      title: newTitle,
+      content: newContent,
+      icon: newIcon,
+      updatedAt: pushedAt,
+    });
 
-    if (applied && applied.length > 0) {
+    if (applied) {
       // The CAS landed — the row now holds Notion's normalized readback, so
       // the baseline must match that, not the pre-push content we sent.
       baselineContent = newContent;
-      try {
-        await deleteCollabState(documentId);
-        releaseDoc(documentId);
-      } catch {
-        // Non-fatal — the client reconciles via setContent.
-      }
+      // Preserve the live Y.Doc and let the updatedAt-gated editor reconcile
+      // apply this provider-normalized snapshot. Clearing collab persistence
+      // here can race a connected client's stale update and resurrect it.
     }
     // else: CAS raced and lost — the row holds the concurrent edit's content,
     // not `newContent` and not `document.content`. Keep baselineContent as

package/corpus/templates/content/shared/api.ts

@@ -618,6 +618,7 @@ export interface ContentDatabaseSource {
     lastReadPartial?: boolean;
     lastReadHasMore?: boolean;
     lastReadNextOffset?: number;
+    lastReadSuspiciousEmpty?: boolean;
     sourceFetchState?: "idle" | "fetching" | "error";
     allowDraftWrites?: boolean;
     allowPublishWrites?: boolean;

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -173,7 +173,7 @@ defaults. The banned-defaults list above still applies, plus:
 
 ## Generation Workflow — the canonical 5-phase flow
 
-This flow mirrors Claude Design's UX: ask → show variants → user picks → refine. Don't skip phases for new designs.
+This flow mirrors Claude Design's UX: clarify only what's unclear → show variants → user picks → refine. Don't collapse phases into one shot for new, open-ended designs.
 
 ### Phase 1 — Create the project + ask before generating
 
@@ -187,7 +187,28 @@ application state. External MCP hosts should surface the `create-design`
 returned "Open design" link, then use `present-design-variants` to open the
 visual picker.
 
-Then, for any non-trivial first prompt, call `show-design-questions` BEFORE generating. The editor renders a full-canvas overlay; answers come back as a chat message. Skip the questions only when the prompt is unambiguous ("re-skin this with my brand colors") or the user said "decide for me".
+Then, for a brief or ambiguous first prompt to a **new** design, call
+`show-design-questions` BEFORE generating. The editor renders a full-canvas
+overlay; answers come back as a chat message. Size the question count to how
+much is actually unresolved — most prompts warrant 2-4 questions, not the full
+1-8 range — and never ask about something the prompt already specified (a
+stated color, audience, or layout is settled; don't re-ask it as a choice).
+
+Skip the questions entirely when:
+- the prompt is already specific enough to generate from (names the audience,
+  purpose, and a visual direction, e.g. "a dark, data-dense analytics
+  dashboard for ops engineers" or "re-skin this with my brand colors");
+- it's a tweak/edit/refinement to an existing design rather than a new one —
+  go straight to `edit-design` (see Phase 3 and "Making edits" below);
+- the user already answered a question set for this design and is now
+  iterating — don't re-ask settled ground on follow-up prompts for the same
+  design; or
+- the user says "decide for me," "surprise me," "just build it," or similar.
+
+Asking on every prompt is as much a failure mode as never asking: a detailed
+prompt that already answers the obvious questions should generate
+immediately, and a design already in flight should not be interrupted with a
+second questionnaire.
 
 ```bash
 pnpm action show-design-questions \
@@ -196,6 +217,12 @@ pnpm action show-design-questions \
   --questions '[{"id":"form_factor","type":"text-options","question":"What form factor?","options":[{"label":"Desktop web app","value":"desktop"},{"label":"Mobile app","value":"mobile"},{"label":"Both / responsive","value":"responsive"},{"label":"Decide for me","value":"decide"}],"allowOther":true}]'
 ```
 
+Favor choice-first questions (2-5 concrete options, `allowOther: true`, and a
+"Decide for me" option when any answer is acceptable) over open-ended
+`freeform` text, and avoid `multiSelect` unless the question genuinely allows
+combining multiple answers — stacking multi-select questions multiplies
+follow-up ambiguity instead of resolving it.
+
 **Carry the form-factor answer through to generation — do not just ask and discard it.** A "Desktop web app" answer means the generated screen's canvas frame must be desktop-sized (~1440×1024), not left at whatever a screen with no placement falls back to. Map the answer to real frame geometry: pass `deviceType` (`"mobile"` / `"tablet"` / `"desktop"`) per screen to `generate-screens`, explicit `width`/`height` per variant to `present-design-variants`, or an explicit `canvasFrames` entry to `generate-design` — see Phase 2 and Phase 3 below. For "Both / responsive," generate at desktop width and rely on the responsive breakpoint system (see `responsive-breakpoints` skill) rather than guessing a size.
 
 ### Phase 2 — Generate side-by-side variations (2-5, three by default)