@mvriu5/payload-ai 1.1.1 → 1.3.2

package/dist/handlers/chatHandler.js

@@ -5,8 +5,13 @@ import { isAIProvider } from "../ai/providerOptions.js";
 import { getModel, getProviderConfig } from "../ai/providerRuntime.js";
 import { containsSensitiveData } from "../ai/sensitiveData.js";
 import { isCollectionActionAllowed } from "../payload/collectionPermissions.js";
+import { prepareProposalWriteData } from "../payload/proposalData.js";
 import { buildPromptWithMentionContext, collectBlocks, describeCollectionLikeConfig, describeCollectionLikeSummary, getAllowedCollectionSlugs, getMentionContext } from "../payload/schemaContext.js";
-import { getOptionValue, getSafeProposalLabel, hasLocalizedData, hasValueAtPath, setValueAtPath } from "../payload/shared.js";
+import { getLogPreview, logHandlerEvent } from "../payload/logging.js";
+import { getOptionValue, getSafeProposalLabel, hasLocalizedData, hasValueAtPath, isRecord, setValueAtPath } from "../payload/shared.js";
+const nonEmptyLocalizedDataSchema = z.record(z.string(), z.record(z.string(), z.unknown())).refine((value)=>Object.keys(value).length > 0, {
+    message: "localizedData must include at least one locale entry."
+});
 const e2eModeEnabled = ()=>process.env.PAYLOAD_AI_E2E_MODE === "true";
 const createSSEEventStream = (events)=>{
     const encoder = new TextEncoder();
@@ -19,9 +24,29 @@ const createSSEEventStream = (events)=>{
         }
     });
 };
+const getChatCompletionReason = ({ proposalCount, toolFailures, writeIntent })=>{
+    if (proposalCount > 0) return "proposal_created";
+    if (toolFailures.length > 0) return "tool_validation_failed";
+    if (writeIntent) return "write_intent_without_tool_call";
+    return "model_did_not_call_tool";
+};
+const createDebugPayload = ({ activeLocale, debug, proposalCount, selectedLocales, toolFailures, usage, writeIntent })=>({
+        activeLocale,
+        model: debug.model,
+        proposalCount,
+        provider: debug.provider,
+        reason: getChatCompletionReason({
+            proposalCount,
+            toolFailures,
+            writeIntent
+        }),
+        selectedLocales,
+        toolFailures,
+        usage
+    });
 const createE2EChatResponse = ({ prompt, selectedLocales })=>{
     const normalizedPrompt = prompt.toLowerCase();
-    const wantsCreatePost = normalizedPrompt.includes("post") && (normalizedPrompt.includes("create") || normalizedPrompt.includes("erstell"));
+    const wantsCreatePost = normalizedPrompt.includes("post") && (normalizedPrompt.includes("create") || normalizedPrompt.includes("erstell") || normalizedPrompt.includes("apply flow") || normalizedPrompt.includes("locale review") || normalizedPrompt.includes("proposal review"));
     const mentionsMars = normalizedPrompt.includes("mars");
     const multipleLocales = selectedLocales.length > 1;
     const activeLocale = selectedLocales.at(-1);
@@ -56,6 +81,22 @@ const createE2EChatResponse = ({ prompt, selectedLocales })=>{
         } : {}
     }) : null;
     const responseText = proposal ? "Prepared one draft post proposal." : "No content change was proposed.";
+    const debugPayload = createDebugPayload({
+        debug: {
+            model: "e2e-model",
+            provider: "openai",
+            tools: []
+        },
+        proposalCount: proposal ? 1 : 0,
+        selectedLocales,
+        toolFailures: [],
+        usage: {
+            inputTokens: 42,
+            outputTokens: 27,
+            totalTokens: 69
+        },
+        writeIntent: wantsCreatePost
+    });
     return new Response(createSSEEventStream([
         {
             data: {
@@ -76,6 +117,10 @@ const createE2EChatResponse = ({ prompt, selectedLocales })=>{
             },
             event: "proposals"
         },
+        {
+            data: debugPayload,
+            event: "debug"
+        },
         {
             data: {},
             event: "done"
@@ -196,14 +241,23 @@ const getMissingCreateFields = ({ data, localizedData, requiredFields })=>{
             ];
         }
         const missing = [];
+        const localizedRequiredFields = [];
+        const sharedRequiredFields = [];
+        for (const field of requiredFields){
+            if (field.localized) {
+                localizedRequiredFields.push(field);
+            } else {
+                sharedRequiredFields.push(field);
+            }
+        }
         for (const [locale, localeData] of locales){
-            for (const field of requiredFields.filter((item)=>item.localized)){
+            for (const field of localizedRequiredFields){
                 if (!hasValueAtPath(localeData, field.path)) {
                     missing.push(`${locale}:${field.path}`);
                 }
             }
         }
-        for (const field of requiredFields.filter((item)=>!item.localized)){
+        for (const field of sharedRequiredFields){
             if (!hasValueAtPath(firstLocale[1], field.path)) {
                 missing.push(`${firstLocale[0]}:${field.path}`);
             }
@@ -213,7 +267,428 @@ const getMissingCreateFields = ({ data, localizedData, requiredFields })=>{
     if (!data) return [
         "data is required"
     ];
-    return requiredFields.filter((field)=>!hasValueAtPath(data, field.path)).map((field)=>field.path);
+    return requiredFields.flatMap((field)=>hasValueAtPath(data, field.path) ? [] : [
+            field.path
+        ]);
+};
+const getProposalSummary = (proposal)=>({
+        action: proposal.action,
+        collection: "collection" in proposal ? proposal.collection : undefined,
+        hasData: "data" in proposal && Boolean(proposal.data),
+        hasLocalizedData: "localizedData" in proposal && Boolean(proposal.localizedData),
+        id: "id" in proposal ? proposal.id : undefined,
+        label: proposal.label,
+        locale: proposal.locale,
+        locales: "localizedData" in proposal && proposal.localizedData ? Object.keys(proposal.localizedData) : undefined,
+        slug: "slug" in proposal ? proposal.slug : undefined
+    });
+const getCollectionBlockTypes = (fields)=>{
+    const blockTypes = new Set();
+    const visitFields = (items)=>{
+        for (const field of items){
+            if (field.type === "blocks" && field.blocks) {
+                for (const block of field.blocks){
+                    blockTypes.add(block.slug);
+                    if (block.fields?.length) {
+                        visitFields(block.fields);
+                    }
+                }
+            }
+            if (field.fields?.length) {
+                visitFields(field.fields);
+            }
+        }
+    };
+    visitFields(fields);
+    return [
+        ...blockTypes
+    ];
+};
+const regexSpecialCharactersPattern = /[.*+?^${}()|[\]\\]/g;
+const getRequestedBlockTypes = ({ availableBlockTypes, mentions, prompt })=>{
+    const requestedBlockTypes = new Set();
+    const normalizedPrompt = prompt.toLowerCase();
+    const availableBlockTypeSet = new Set(availableBlockTypes);
+    const blockTypesByNormalizedSlug = new Map(availableBlockTypes.map((blockType)=>[
+            blockType.toLowerCase(),
+            blockType
+        ]));
+    const escapedBlockTypes = availableBlockTypes.map((blockType)=>blockType.replace(regexSpecialCharactersPattern, "\\$&")).join("|");
+    const blockPattern = escapedBlockTypes ? new RegExp(`\\b(${escapedBlockTypes})\\b(?:\\s+block)?`, "gi") : null;
+    for (const mention of mentions || []){
+        if (mention.type === "block" && mention.slug && availableBlockTypeSet.has(mention.slug)) {
+            requestedBlockTypes.add(mention.slug);
+        }
+    }
+    if (blockPattern) {
+        for (const match of normalizedPrompt.matchAll(blockPattern)){
+            const blockType = match[1] ? blockTypesByNormalizedSlug.get(match[1].toLowerCase()) : null;
+            if (blockType) {
+                requestedBlockTypes.add(blockType);
+            }
+        }
+    }
+    return [
+        ...requestedBlockTypes
+    ];
+};
+const collectProposalBlockTypes = ({ data, fields })=>{
+    const foundBlockTypes = new Set();
+    const visitFields = (items, value)=>{
+        for (const field of items){
+            if (!field.name) continue;
+            const fieldValue = value[field.name];
+            if (fieldValue === undefined || fieldValue === null) continue;
+            if (field.type === "blocks" && Array.isArray(fieldValue)) {
+                const blocksBySlug = new Map(field.blocks?.map((block)=>[
+                        block.slug,
+                        block
+                    ]));
+                for (const blockItem of fieldValue){
+                    if (!isRecord(blockItem)) continue;
+                    const blockType = typeof blockItem.blockType === "string" ? blockItem.blockType : typeof blockItem.type === "string" ? blockItem.type : typeof blockItem.slug === "string" ? blockItem.slug : null;
+                    if (blockType) {
+                        foundBlockTypes.add(blockType);
+                    }
+                    if (blockType) {
+                        const blockConfig = blocksBySlug.get(blockType);
+                        if (blockConfig?.fields?.length) {
+                            visitFields(blockConfig.fields, blockItem);
+                        }
+                    }
+                }
+                continue;
+            }
+            if (field.type === "group" && isRecord(fieldValue) && field.fields?.length) {
+                visitFields(field.fields, fieldValue);
+                continue;
+            }
+            if (field.type === "array" && Array.isArray(fieldValue) && field.fields?.length) {
+                for (const item of fieldValue){
+                    if (isRecord(item)) {
+                        visitFields(field.fields, item);
+                    }
+                }
+            }
+        }
+    };
+    visitFields(fields, data);
+    return foundBlockTypes;
+};
+const collectRelationshipTargets = ({ data, fields, path = "" })=>{
+    const targets = [];
+    for (const field of fields){
+        if (!field.name) continue;
+        const fieldPath = path ? `${path}.${field.name}` : field.name;
+        const fieldValue = data[field.name];
+        if (fieldValue === undefined || fieldValue === null) continue;
+        if (field.type === "relationship" || field.type === "upload") {
+            const relationTargets = Array.isArray(field.relationTo) ? field.relationTo.filter((item)=>typeof item === "string") : typeof field.relationTo === "string" ? [
+                field.relationTo
+            ] : [];
+            const collectSingle = (value, itemPath)=>{
+                if (typeof value === "string" || typeof value === "number") {
+                    if (relationTargets.length === 1) {
+                        targets.push({
+                            collection: relationTargets[0],
+                            id: value,
+                            path: itemPath
+                        });
+                    }
+                    return;
+                }
+                if (!isRecord(value)) return;
+                const relationTo = typeof value.relationTo === "string" ? value.relationTo : relationTargets[0];
+                const id = typeof value.id === "string" || typeof value.id === "number" ? value.id : typeof value.value === "string" || typeof value.value === "number" ? value.value : undefined;
+                if (!relationTo || id === undefined) return;
+                targets.push({
+                    collection: relationTo,
+                    id,
+                    path: itemPath
+                });
+            };
+            if (field.hasMany && Array.isArray(fieldValue)) {
+                fieldValue.forEach((item, index)=>collectSingle(item, `${fieldPath}.${index}`));
+            } else {
+                collectSingle(fieldValue, fieldPath);
+            }
+            continue;
+        }
+        if (field.type === "group" && isRecord(fieldValue) && field.fields?.length) {
+            targets.push(...collectRelationshipTargets({
+                data: fieldValue,
+                fields: field.fields,
+                path: fieldPath
+            }));
+            continue;
+        }
+        if (field.type === "array" && Array.isArray(fieldValue) && field.fields?.length) {
+            fieldValue.forEach((item, index)=>{
+                if (!isRecord(item)) return;
+                targets.push(...collectRelationshipTargets({
+                    data: item,
+                    fields: field.fields,
+                    path: `${fieldPath}.${index}`
+                }));
+            });
+            continue;
+        }
+        if (field.type === "blocks" && Array.isArray(fieldValue) && field.blocks?.length) {
+            const blocksBySlug = new Map(field.blocks.map((block)=>[
+                    block.slug,
+                    block
+                ]));
+            fieldValue.forEach((item, index)=>{
+                if (!isRecord(item)) return;
+                const blockType = typeof item.blockType === "string" ? item.blockType : typeof item.type === "string" ? item.type : typeof item.slug === "string" ? item.slug : null;
+                if (!blockType) return;
+                const blockConfig = blocksBySlug.get(blockType);
+                if (!blockConfig?.fields?.length) return;
+                targets.push(...collectRelationshipTargets({
+                    data: item,
+                    fields: blockConfig.fields,
+                    path: `${fieldPath}.${index}`
+                }));
+            });
+        }
+    }
+    return targets;
+};
+const collectUploadTargets = ({ data, fields, path = "" })=>{
+    const targets = [];
+    for (const field of fields){
+        if (!field.name) continue;
+        const fieldPath = path ? `${path}.${field.name}` : field.name;
+        const fieldValue = data[field.name];
+        if (fieldValue === undefined || fieldValue === null) continue;
+        if (field.type === "upload") {
+            const relationTargets = Array.isArray(field.relationTo) ? field.relationTo.filter((item)=>typeof item === "string") : typeof field.relationTo === "string" ? [
+                field.relationTo
+            ] : [];
+            const collectSingle = (value, itemPath)=>{
+                if (typeof value === "string" || typeof value === "number") {
+                    if (relationTargets.length === 1) {
+                        targets.push({
+                            collection: relationTargets[0],
+                            id: value,
+                            path: itemPath
+                        });
+                    }
+                    return;
+                }
+                if (!isRecord(value)) return;
+                const relationTo = typeof value.relationTo === "string" ? value.relationTo : relationTargets[0];
+                const id = typeof value.id === "string" || typeof value.id === "number" ? value.id : typeof value.value === "string" || typeof value.value === "number" ? value.value : undefined;
+                if (!relationTo || id === undefined) return;
+                targets.push({
+                    collection: relationTo,
+                    id,
+                    path: itemPath
+                });
+            };
+            if (field.hasMany && Array.isArray(fieldValue)) {
+                fieldValue.forEach((item, index)=>collectSingle(item, `${fieldPath}.${index}`));
+            } else {
+                collectSingle(fieldValue, fieldPath);
+            }
+            continue;
+        }
+        if (field.type === "group" && isRecord(fieldValue) && field.fields?.length) {
+            targets.push(...collectUploadTargets({
+                data: fieldValue,
+                fields: field.fields,
+                path: fieldPath
+            }));
+            continue;
+        }
+        if (field.type === "array" && Array.isArray(fieldValue) && field.fields?.length) {
+            fieldValue.forEach((item, index)=>{
+                if (!isRecord(item)) return;
+                targets.push(...collectUploadTargets({
+                    data: item,
+                    fields: field.fields,
+                    path: `${fieldPath}.${index}`
+                }));
+            });
+            continue;
+        }
+        if (field.type === "blocks" && Array.isArray(fieldValue) && field.blocks?.length) {
+            const blocksBySlug = new Map(field.blocks.map((block)=>[
+                    block.slug,
+                    block
+                ]));
+            fieldValue.forEach((item, index)=>{
+                if (!isRecord(item)) return;
+                const blockType = typeof item.blockType === "string" ? item.blockType : typeof item.type === "string" ? item.type : typeof item.slug === "string" ? item.slug : null;
+                if (!blockType) return;
+                const blockConfig = blocksBySlug.get(blockType);
+                if (!blockConfig?.fields?.length) return;
+                targets.push(...collectUploadTargets({
+                    data: item,
+                    fields: blockConfig.fields,
+                    path: `${fieldPath}.${index}`
+                }));
+            });
+        }
+    }
+    return targets;
+};
+const validateRelationshipTargetsExist = async ({ data, fields, req })=>{
+    const targets = collectRelationshipTargets({
+        data,
+        fields
+    });
+    const targetResults = await Promise.all(targets.map(async (target)=>{
+        try {
+            await req.payload.findByID({
+                collection: target.collection,
+                depth: 0,
+                id: String(target.id),
+                overrideAccess: false,
+                req
+            });
+            return null;
+        } catch  {
+            return target;
+        }
+    }));
+    return targetResults.filter((target)=>Boolean(target));
+};
+const getUploadTargetsOutsideAttachments = ({ allowedAttachmentKeys, data, fields })=>{
+    if (allowedAttachmentKeys.size === 0) return [];
+    return collectUploadTargets({
+        data,
+        fields
+    }).filter((target)=>!allowedAttachmentKeys.has(`${target.collection}:${String(target.id)}`));
+};
+const getMentionSummary = (mentions)=>mentions?.map((mention)=>({
+            collection: "collection" in mention ? mention.collection : undefined,
+            id: "id" in mention ? mention.id : undefined,
+            slug: mention.slug,
+            type: mention.type
+        })) || [];
+const getMediaAttachmentContext = async ({ allowedCollectionsBySlug, attachments, collections, req })=>{
+    if (!attachments?.length) return [];
+    const contexts = [];
+    const seen = new Set();
+    for (const attachment of attachments.slice(0, 8)){
+        if (attachment.type !== "media" || !attachment.collection || !attachment.id) continue;
+        const key = `${attachment.collection}:${attachment.id}`;
+        if (seen.has(key)) continue;
+        const collectionConfig = allowedCollectionsBySlug.get(attachment.collection);
+        if (!collectionConfig?.upload) continue;
+        const doc = await req.payload.findByID({
+            collection: attachment.collection,
+            depth: 1,
+            id: attachment.id,
+            overrideAccess: false,
+            req
+        }).catch(()=>null);
+        if (!doc) continue;
+        seen.add(key);
+        contexts.push({
+            attachment,
+            collection: attachment.collection,
+            doc,
+            schema: describeCollectionLikeConfig({
+                config: collectionConfig,
+                permissions: collections,
+                type: "collection"
+            }),
+            type: "mediaAttachment"
+        });
+    }
+    return contexts;
+};
+const formatProposalIssuesForRetry = (issues)=>{
+    return issues.slice(0, 6).map((issue)=>{
+        switch(issue.code){
+            case "invalid_block_type":
+                return `${issue.path}: use an exact blockType from the schema`;
+            case "invalid_blocks":
+                return `${issue.path}: blocks fields must be arrays of objects with blockType and exact field names`;
+            case "invalid_array":
+                return `${issue.path}: array fields must be arrays of complete objects`;
+            case "missing_required_field":
+                return `${issue.path}: required field missing`;
+            case "unknown_field":
+                return `${issue.path}: unknown field, use exact schema field names only`;
+            case "invalid_relationship":
+                return `${issue.path}: use relationship IDs or { relationTo, value }, not free text`;
+            default:
+                return `${issue.path}: ${issue.message}`;
+        }
+    }).join("; ");
+};
+const createCollectionAliasMap = (collections)=>{
+    const aliasMap = new Map();
+    const addAlias = (alias, slug)=>{
+        const normalizedAlias = alias?.trim().toLowerCase();
+        if (!normalizedAlias) return;
+        if (!aliasMap.has(normalizedAlias)) {
+            aliasMap.set(normalizedAlias, slug);
+        }
+    };
+    for (const collection of collections){
+        addAlias(collection.slug, collection.slug);
+        addAlias(collection.slug.replace(/-/g, " "), collection.slug);
+        const singular = typeof collection.labels?.singular === "string" ? collection.labels.singular : undefined;
+        const plural = typeof collection.labels?.plural === "string" ? collection.labels.plural : undefined;
+        addAlias(singular, collection.slug);
+        addAlias(plural, collection.slug);
+        if (singular?.endsWith("s")) {
+            addAlias(singular.slice(0, -1), collection.slug);
+        }
+        if (plural?.endsWith("s")) {
+            addAlias(plural.slice(0, -1), collection.slug);
+        }
+    }
+    return Object.fromEntries(aliasMap.entries());
+};
+const getLikelyCollectionMatches = ({ aliasMap, prompt })=>{
+    const normalizedPrompt = prompt.toLowerCase();
+    const matches = new Set();
+    const aliases = Object.keys(aliasMap).sort((a, b)=>b.length - a.length);
+    const aliasPattern = aliases.length > 0 ? new RegExp(aliases.map((alias)=>alias.replace(regexSpecialCharactersPattern, "\\$&")).join("|"), "g") : null;
+    if (!aliasPattern) return [];
+    for (const match of normalizedPrompt.matchAll(aliasPattern)){
+        const alias = match[0];
+        const slug = aliasMap[alias];
+        if (slug) {
+            matches.add(slug);
+        }
+    }
+    return [
+        ...matches
+    ];
+};
+const hasWriteIntent = (prompt)=>{
+    const normalizedPrompt = prompt.toLowerCase();
+    return /\b(create|build|generate|write|draft|make|add|update|edit|change|revise|refine|rewrite|translate|delete|remove)\b/.test(normalizedPrompt);
+};
+const getIntentToolChoice = (prompt)=>{
+    const normalizedPrompt = prompt.toLowerCase();
+    if (/\b(delete|remove)\b/.test(normalizedPrompt)) {
+        return {
+            toolName: "proposeDeleteDoc",
+            type: "tool"
+        };
+    }
+    // Update existing document (add block, modify content, etc.)
+    if (/\b(update|edit|change|modify|einfügen|hinzufügen|addieren)\b/.test(normalizedPrompt)) {
+        return {
+            toolName: "proposeUpdateDoc",
+            type: "tool"
+        };
+    }
+    // Create a new document
+    if (/\b(create|build|generate|write|draft|make|add|füge|einfügen|hinzufügen|addieren)\b/.test(normalizedPrompt)) {
+        return {
+            toolName: "proposeCreateDoc",
+            type: "tool"
+        };
+    }
+    return undefined;
 };
 export const createChatHandler = (options = {})=>async (req)=>{
         if (!req.user) return Response.json({
@@ -228,8 +703,15 @@ export const createChatHandler = (options = {})=>async (req)=>{
         }, {
             status: 400
         });
-        const selectedLocales = (body?.mentions?.filter((mention)=>mention.type === "locale" && mention.slug).map((mention)=>mention.slug) || []).filter((locale, index, array)=>array.indexOf(locale) === index);
+        const selectedLocales = [];
+        const selectedLocaleSet = new Set();
+        for (const mention of body?.mentions || []){
+            if (mention.type !== "locale" || !mention.slug || selectedLocaleSet.has(mention.slug)) continue;
+            selectedLocaleSet.add(mention.slug);
+            selectedLocales.push(mention.slug);
+        }
         const activeLocale = selectedLocales.at(-1);
+        const mentionSummary = getMentionSummary(body?.mentions);
         if (e2eModeEnabled()) {
             return createE2EChatResponse({
                 prompt,
@@ -266,7 +748,23 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 "searchDocs"
             ]
         };
+        logHandlerEvent(req, "info", {
+            activeLocale,
+            debug,
+            mentionCount: mentionSummary.length,
+            mentions: mentionSummary,
+            msg: "AI chat started",
+            promptPreview: getLogPreview(prompt),
+            selectedLocales
+        });
         if (!providerConfig.apiKey) {
+            logHandlerEvent(req, "warn", {
+                activeLocale,
+                debug,
+                msg: "AI chat blocked: missing provider API key",
+                promptPreview: getLogPreview(prompt),
+                selectedLocales
+            });
             return Response.json({
                 error: options.allowUserApiKeys === false ? `Configure a ${provider} API key in the server environment first.` : `Add a ${provider} API key to your account settings or configure it in the server environment first.`
             }, {
@@ -275,25 +773,70 @@ export const createChatHandler = (options = {})=>async (req)=>{
         }
         try {
             const proposals = [];
+            const toolFailures = [];
+            const registerToolFailure = (failure)=>{
+                toolFailures.push(failure);
+                logHandlerEvent(req, "warn", {
+                    debug,
+                    ...failure,
+                    msg: "AI tool validation failed",
+                    promptPreview: getLogPreview(prompt)
+                });
+            };
+            const createToolError = ({ collection, details, message, slug, tool })=>{
+                registerToolFailure({
+                    collection,
+                    details,
+                    message,
+                    slug,
+                    tool
+                });
+                return {
+                    error: message
+                };
+            };
             const addSignedProposal = (proposal)=>{
                 if ("data" in proposal && proposal.data && containsSensitiveData(proposal.data)) {
-                    return {
-                        error: "Proposal contains sensitive fields and cannot be created."
-                    };
+                    return createToolError({
+                        details: getProposalSummary(proposal),
+                        message: "Proposal contains sensitive fields and cannot be created.",
+                        tool: `propose${proposal.action[0]?.toUpperCase()}${proposal.action.slice(1)}`
+                    });
                 }
                 if ("localizedData" in proposal && hasLocalizedData(proposal.localizedData) && Object.values(proposal.localizedData).some((value)=>containsSensitiveData(value))) {
-                    return {
-                        error: "Proposal contains sensitive fields and cannot be created."
-                    };
+                    return createToolError({
+                        details: getProposalSummary(proposal),
+                        message: "Proposal contains sensitive fields and cannot be created.",
+                        tool: `propose${proposal.action[0]?.toUpperCase()}${proposal.action.slice(1)}`
+                    });
                 }
                 const signedProposal = signAIActionProposal(proposal);
                 proposals.push(signedProposal);
+                logHandlerEvent(req, "info", {
+                    debug,
+                    msg: "AI proposal created",
+                    proposal: getProposalSummary(signedProposal)
+                });
                 return signedProposal;
             };
             const collectionSlugs = getAllowedCollectionSlugs(req, options.collections);
-            const globalSlugs = req.payload.config.globals?.map((global)=>global.slug) || [];
-            const allowedCollections = req.payload.config.collections.filter((collection)=>collectionSlugs.includes(collection.slug));
+            const collectionSlugSet = new Set(collectionSlugs);
+            const globalConfigs = req.payload.config.globals || [];
+            const globalSlugs = globalConfigs.map((global)=>global.slug);
+            const globalConfigsBySlug = new Map(globalConfigs.map((global)=>[
+                    global.slug,
+                    global
+                ]));
+            const allowedCollections = req.payload.config.collections.filter((collection)=>collectionSlugSet.has(collection.slug));
+            const allowedCollectionsBySlug = new Map(allowedCollections.map((collection)=>[
+                    collection.slug,
+                    collection
+                ]));
             if (collectionSlugs.length === 0) {
+                logHandlerEvent(req, "warn", {
+                    debug,
+                    msg: "AI chat blocked: no AI-enabled collections configured"
+                });
                 return Response.json({
                     error: "No AI-enabled collections are configured."
                 }, {
@@ -305,10 +848,10 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         fields: collection.fields,
                         parent: collection.slug
                     })),
-                ...req.payload.config.globals?.flatMap((global)=>collectBlocks({
+                ...globalConfigs.flatMap((global)=>collectBlocks({
                         fields: global.fields,
                         parent: global.slug
-                    })) || []
+                    }))
             ];
             const mentionContext = await getMentionContext({
                 blockContexts,
@@ -318,15 +861,27 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 mentions: body?.mentions,
                 req
             });
-            const mentionedCollectionSlugs = (body?.mentions?.flatMap((mention)=>{
-                if (mention.type === "collection" && mention.slug) return [
-                    mention.slug
-                ];
-                if (mention.type === "doc" && mention.collection) return [
-                    mention.collection
-                ];
-                return [];
-            }).filter((slug)=>collectionSlugs.includes(slug)) || []).filter((slug, index, array)=>array.indexOf(slug) === index);
+            const mediaAttachmentContext = await getMediaAttachmentContext({
+                allowedCollectionsBySlug,
+                attachments: body?.attachments,
+                collections: options.collections,
+                req
+            });
+            const allowedAttachmentKeys = new Set(mediaAttachmentContext.flatMap((context)=>{
+                const attachment = context.attachment;
+                return isRecord(attachment) && typeof attachment.collection === "string" && typeof attachment.id === "string" ? [
+                    `${attachment.collection}:${attachment.id}`
+                ] : [];
+            }));
+            mentionContext.push(...mediaAttachmentContext);
+            const mentionedCollectionSlugs = [];
+            const mentionedCollectionSlugSet = new Set();
+            for (const mention of body?.mentions || []){
+                const slug = mention.type === "collection" && mention.slug ? mention.slug : mention.type === "doc" && mention.collection ? mention.collection : null;
+                if (!slug || !collectionSlugSet.has(slug) || mentionedCollectionSlugSet.has(slug)) continue;
+                mentionedCollectionSlugSet.add(slug);
+                mentionedCollectionSlugs.push(slug);
+            }
             const createRequiredFieldsByCollection = Object.fromEntries(allowedCollections.map((collection)=>[
                     collection.slug,
                     getRequiredFieldInfos(collection.fields, collection.admin?.useAsTitle)
@@ -347,6 +902,38 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         titleFieldByCollection[slug]
                     ]
                 ] : []));
+            const collectionAliasMap = createCollectionAliasMap(allowedCollections);
+            const likelyCollectionMatches = getLikelyCollectionMatches({
+                aliasMap: collectionAliasMap,
+                prompt
+            });
+            const writeIntent = hasWriteIntent(prompt);
+            const inferredCollectionSlug = mentionedCollectionSlugs.length === 1 ? mentionedCollectionSlugs[0] : mentionedCollectionSlugs.length === 0 && likelyCollectionMatches.length === 1 ? likelyCollectionMatches[0] : undefined;
+            const inferredCollectionConfig = inferredCollectionSlug ? allowedCollectionsBySlug.get(inferredCollectionSlug) : undefined;
+            if (inferredCollectionConfig && !mentionContext.some((item)=>item.type === "collection" && item.slug === inferredCollectionConfig.slug)) {
+                mentionContext.push({
+                    ...describeCollectionLikeConfig({
+                        config: inferredCollectionConfig,
+                        permissions: options.collections,
+                        type: "collection"
+                    }),
+                    inferredFromPrompt: true
+                });
+            }
+            const intentToolChoice = inferredCollectionConfig ? getIntentToolChoice(prompt) : undefined;
+            logHandlerEvent(req, "info", {
+                activeLocale,
+                allowedCollectionCount: allowedCollections.length,
+                collectionSlugs,
+                focusedCollections: mentionedCollectionSlugs,
+                globalSlugs,
+                inferredCollectionSlug,
+                intentToolChoice,
+                likelyCollectionMatches,
+                msg: "AI chat context prepared",
+                selectedLocales,
+                writeIntent
+            });
             const collectionSlugSchema = z.enum(collectionSlugs);
             const getDisallowedCollectionActionError = (collection, action)=>{
                 if (isCollectionActionAllowed({
@@ -355,13 +942,15 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     req,
                     slug: collection
                 })) return null;
-                return {
-                    error: `${action} is not enabled for collection: ${collection}`
-                };
+                return createToolError({
+                    collection,
+                    message: `${action} is not enabled for collection: ${collection}`,
+                    tool: "collectionPermissionCheck"
+                });
             };
             const tools = {
                 getDoc: {
-                    description: "Read one document by collection slug and document id.",
+                    description: "Read a document by collection and id.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         id: z.string().min(1)
@@ -380,16 +969,20 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 listCollections: {
-                    description: "List AI-enabled Payload collections. Omit slug for compact summaries; pass slug to get full field schema for one collection.",
+                    description: "List collections; pass slug for one full schema.",
                     inputSchema: z.object({
                         slug: collectionSlugSchema.optional()
                     }),
                     execute: async ({ slug })=>{
                         if (slug) {
-                            const collection = allowedCollections.find((item)=>item.slug === slug);
-                            if (!collection) return {
-                                error: `Unknown collection: ${slug}`
-                            };
+                            const collection = allowedCollectionsBySlug.get(slug);
+                            if (!collection) {
+                                return createToolError({
+                                    message: `Unknown collection: ${slug}`,
+                                    slug,
+                                    tool: "listCollections"
+                                });
+                            }
                             return describeCollectionLikeConfig({
                                 config: collection,
                                 permissions: options.collections,
@@ -404,15 +997,19 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 getGlobal: {
-                    description: "Read one Payload CMS global by slug.",
+                    description: "Read a global by slug.",
                     inputSchema: z.object({
                         slug: z.string().min(1)
                     }),
                     execute: async ({ slug })=>{
-                        const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
-                        if (!globalConfig) return {
-                            error: `Unknown global: ${slug}`
-                        };
+                        const globalConfig = globalConfigsBySlug.get(slug);
+                        if (!globalConfig) {
+                            return createToolError({
+                                message: `Unknown global: ${slug}`,
+                                slug,
+                                tool: "getGlobal"
+                            });
+                        }
                         return req.payload.findGlobal({
                             depth: 2,
                             ...activeLocale ? {
@@ -425,71 +1022,164 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 listGlobals: {
-                    description: "List Payload globals. Omit slug for compact summaries; pass slug to get full field schema for one global.",
+                    description: "List globals; pass slug for one full schema.",
                     inputSchema: z.object({
                         slug: z.string().optional()
                     }),
                     execute: async ({ slug })=>{
-                        const globals = req.payload.config.globals || [];
                         if (slug) {
-                            const global = globals.find((item)=>item.slug === slug);
-                            if (!global) return {
-                                error: `Unknown global: ${slug}`
-                            };
+                            const global = globalConfigsBySlug.get(slug);
+                            if (!global) {
+                                return createToolError({
+                                    message: `Unknown global: ${slug}`,
+                                    slug,
+                                    tool: "listGlobals"
+                                });
+                            }
                             return describeCollectionLikeConfig({
                                 config: global,
                                 type: "global"
                             });
                         }
-                        return globals.map((global)=>describeCollectionLikeSummary({
+                        return globalConfigs.map((global)=>describeCollectionLikeSummary({
                                 config: global,
                                 type: "global"
                             }));
                     }
                 },
                 proposeCreateDoc: {
-                    description: "Prepare a CMS document creation proposal. This does not write to the database. Use exact field names from listCollections. Include every required field for the target collection. For localizedData, include every localized required field in every locale entry, and include non-localized required fields in the first locale entry. For array fields, provide arrays of objects matching their child fields. For richText fields, prefer plain text or omit if unsure. Use localizedData when writing multiple locales in one proposal.",
+                    description: "Propose document creation. Use exact schema fields; include required fields. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         data: z.record(z.string(), z.unknown()).optional(),
                         label: z.string().min(1),
-                        localizedData: z.record(z.string(), z.record(z.string(), z.unknown())).optional()
+                        localizedData: nonEmptyLocalizedDataSchema.optional()
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ collection, data, label, localizedData })=>{
                         const permissionError = getDisallowedCollectionActionError(collection, "create");
                         if (permissionError) return permissionError;
-                        const completedCreatePayload = fillMissingCreateFields({
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
+                        const collectionFields = collectionConfig?.fields || [];
+                        const preparedData = prepareProposalWriteData({
+                            collectionConfig: collectionConfig,
                             data,
+                            inferenceText: prompt,
                             label,
                             localizedData,
-                            requiredFields: createRequiredFieldsByCollection[collection] || []
-                        });
-                        const missingFields = getMissingCreateFields({
-                            data: completedCreatePayload.data,
-                            localizedData: completedCreatePayload.localizedData,
-                            requiredFields: createRequiredFieldsByCollection[collection] || []
+                            mode: "create"
                         });
-                        if (missingFields.length > 0) {
+                        if (preparedData.issues.length > 0) {
                             const titleFieldName = titleFieldByCollection[collection];
-                            const missingTitleField = titleFieldName ? missingFields.some((field)=>field === titleFieldName || field.endsWith(`:${titleFieldName}`)) : false;
-                            return {
-                                error: missingTitleField ? `Create proposal is missing the required title field "${titleFieldName}" for ${collection}. Infer a concise title from the user request and retry.` : `Create proposal is missing required fields for ${collection}: ${missingFields.join(", ")}`
-                            };
+                            const missingTitleField = titleFieldName ? preparedData.issues.some((issue)=>issue.path === titleFieldName || issue.path.endsWith(`.${titleFieldName}`)) : false;
+                            return createToolError({
+                                collection,
+                                details: {
+                                    issues: preparedData.issues,
+                                    titleFieldName
+                                },
+                                message: missingTitleField ? `Create proposal is missing the required title field "${titleFieldName}" for ${collection}. Infer a concise title from the user request and retry.` : `Create proposal for ${collection} is invalid. Retry with exact schema fields and complete array/block objects: ${formatProposalIssuesForRetry(preparedData.issues)}`,
+                                tool: "proposeCreateDoc"
+                            });
                         }
-                        const proposal = completedCreatePayload.localizedData ? {
+                        const requestedBlockTypes = getRequestedBlockTypes({
+                            availableBlockTypes: getCollectionBlockTypes(collectionFields),
+                            mentions: body?.mentions,
+                            prompt
+                        });
+                        if (requestedBlockTypes.length > 0) {
+                            const proposalBlockTypes = new Set();
+                            if (preparedData.data) {
+                                for (const blockType of collectProposalBlockTypes({
+                                    data: preparedData.data,
+                                    fields: collectionFields
+                                })){
+                                    proposalBlockTypes.add(blockType);
+                                }
+                            }
+                            if (preparedData.localizedData) {
+                                for (const localeData of Object.values(preparedData.localizedData)){
+                                    for (const blockType of collectProposalBlockTypes({
+                                        data: localeData,
+                                        fields: collectionFields
+                                    })){
+                                        proposalBlockTypes.add(blockType);
+                                    }
+                                }
+                            }
+                            const missingBlockTypes = requestedBlockTypes.filter((blockType)=>!proposalBlockTypes.has(blockType));
+                            if (missingBlockTypes.length > 0) {
+                                return createToolError({
+                                    collection,
+                                    details: {
+                                        missingBlockTypes,
+                                        requestedBlockTypes
+                                    },
+                                    message: `Create proposal for ${collection} is missing required block types from the request: ${missingBlockTypes.join(", ")}. Add them to the appropriate blocks field using exact blockType values and complete required fields.`,
+                                    tool: "proposeCreateDoc"
+                                });
+                            }
+                        }
+                        const uploadTargetsOutsideAttachments = [
+                            ...preparedData.data ? getUploadTargetsOutsideAttachments({
+                                allowedAttachmentKeys,
+                                data: preparedData.data,
+                                fields: collectionFields
+                            }) : [],
+                            ...preparedData.localizedData ? Object.values(preparedData.localizedData).flatMap((localeData)=>getUploadTargetsOutsideAttachments({
+                                    allowedAttachmentKeys,
+                                    data: localeData,
+                                    fields: collectionFields
+                                })) : []
+                        ];
+                        if (uploadTargetsOutsideAttachments.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    allowedAttachments: [
+                                        ...allowedAttachmentKeys
+                                    ],
+                                    uploadTargetsOutsideAttachments
+                                },
+                                message: `Create proposal for ${collection} uses upload references that are not in the uploaded attachments: ${uploadTargetsOutsideAttachments.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}. Use only uploaded media attachment IDs for upload fields.`,
+                                tool: "proposeCreateDoc"
+                            });
+                        }
+                        const invalidRelationshipTargets = [
+                            ...preparedData.data ? await validateRelationshipTargetsExist({
+                                data: preparedData.data,
+                                fields: collectionFields,
+                                req
+                            }) : [],
+                            ...preparedData.localizedData ? (await Promise.all(Object.values(preparedData.localizedData).map((localeData)=>validateRelationshipTargetsExist({
+                                    data: localeData,
+                                    fields: collectionFields,
+                                    req
+                                })))).flat() : []
+                        ];
+                        if (invalidRelationshipTargets.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    invalidRelationshipTargets
+                                },
+                                message: `Create proposal for ${collection} contains relationship or upload references that do not exist: ${invalidRelationshipTargets.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}.`,
+                                tool: "proposeCreateDoc"
+                            });
+                        }
+                        const proposal = preparedData.localizedData ? {
                             action: "create",
                             collection,
                             label: getSafeProposalLabel(label),
-                            localizedData: completedCreatePayload.localizedData,
+                            localizedData: preparedData.localizedData,
                             ...activeLocale ? {
                                 locale: activeLocale
                             } : {}
                         } : {
                             action: "create",
                             collection,
-                            data: completedCreatePayload.data || {},
+                            data: preparedData.data || {},
                             label: getSafeProposalLabel(label),
                             ...activeLocale ? {
                                 locale: activeLocale
@@ -499,7 +1189,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 proposeDeleteDoc: {
-                    description: "Prepare a CMS document deletion proposal. This does not write to the database.",
+                    description: "Propose document deletion.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         id: z.string().min(1),
@@ -521,26 +1211,93 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 proposeUpdateDoc: {
-                    description: "Prepare a CMS document update proposal. This does not write to the database. Use exact field names from listCollections. For array fields, provide arrays of objects matching their child fields. For richText fields, prefer plain text or omit if unsure. Use localizedData when writing multiple locales in one proposal.",
+                    description: "Propose document update. Use exact schema fields. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         data: z.record(z.string(), z.unknown()).optional(),
                         id: z.string().min(1),
                         label: z.string().min(1),
-                        localizedData: z.record(z.string(), z.record(z.string(), z.unknown())).optional()
+                        localizedData: nonEmptyLocalizedDataSchema.optional()
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ collection, data, id, label, localizedData })=>{
                         const permissionError = getDisallowedCollectionActionError(collection, "update");
                         if (permissionError) return permissionError;
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
+                        const collectionFields = collectionConfig?.fields || [];
+                        const preparedData = prepareProposalWriteData({
+                            collectionConfig: collectionConfig,
+                            data,
+                            inferenceText: prompt,
+                            label,
+                            localizedData,
+                            mode: "update"
+                        });
+                        if (preparedData.issues.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    issues: preparedData.issues
+                                },
+                                message: `Update proposal for ${collection} is invalid. Retry with exact schema fields and complete array/block objects: ${formatProposalIssuesForRetry(preparedData.issues)}`,
+                                tool: "proposeUpdateDoc"
+                            });
+                        }
+                        const invalidRelationshipTargets = [
+                            ...preparedData.data ? await validateRelationshipTargetsExist({
+                                data: preparedData.data,
+                                fields: collectionFields,
+                                req
+                            }) : [],
+                            ...preparedData.localizedData ? (await Promise.all(Object.values(preparedData.localizedData).map((localeData)=>validateRelationshipTargetsExist({
+                                    data: localeData,
+                                    fields: collectionFields,
+                                    req
+                                })))).flat() : []
+                        ];
+                        if (invalidRelationshipTargets.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    invalidRelationshipTargets
+                                },
+                                message: `Update proposal for ${collection} contains relationship or upload references that do not exist: ${invalidRelationshipTargets.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}.`,
+                                tool: "proposeUpdateDoc"
+                            });
+                        }
+                        const uploadTargetsOutsideAttachments = [
+                            ...preparedData.data ? getUploadTargetsOutsideAttachments({
+                                allowedAttachmentKeys,
+                                data: preparedData.data,
+                                fields: collectionFields
+                            }) : [],
+                            ...preparedData.localizedData ? Object.values(preparedData.localizedData).flatMap((localeData)=>getUploadTargetsOutsideAttachments({
+                                    allowedAttachmentKeys,
+                                    data: localeData,
+                                    fields: collectionFields
+                                })) : []
+                        ];
+                        if (uploadTargetsOutsideAttachments.length > 0) {
+                            return createToolError({
+                                collection,
+                                details: {
+                                    allowedAttachments: [
+                                        ...allowedAttachmentKeys
+                                    ],
+                                    uploadTargetsOutsideAttachments
+                                },
+                                message: `Update proposal for ${collection} uses upload references that are not in the uploaded attachments: ${uploadTargetsOutsideAttachments.map((target)=>`${target.path} -> ${target.collection}:${target.id}`).join(", ")}. Use only uploaded media attachment IDs for upload fields.`,
+                                tool: "proposeUpdateDoc"
+                            });
+                        }
                         const proposal = {
                             action: "update",
                             collection,
-                            ...localizedData ? {
-                                localizedData
+                            ...preparedData.localizedData ? {
+                                localizedData: preparedData.localizedData
                             } : {
-                                data: data || {}
+                                data: preparedData.data || {}
                             },
                             id,
                             label: getSafeProposalLabel(label),
@@ -552,26 +1309,51 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 proposeUpdateGlobal: {
-                    description: "Prepare a Payload global update proposal. This does not write to the database. Use localizedData when writing multiple locales in one proposal.",
+                    description: "Propose global update. Use localizedData for multi-locale writes.",
                     inputSchema: z.object({
                         data: z.record(z.string(), z.unknown()).optional(),
                         label: z.string().min(1),
-                        localizedData: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+                        localizedData: nonEmptyLocalizedDataSchema.optional(),
                         slug: z.string().min(1)
                     }).refine((value)=>Boolean(value.data || value.localizedData), {
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ data, label, localizedData, slug })=>{
-                        const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
-                        if (!globalConfig) return {
-                            error: `Unknown global: ${slug}`
-                        };
+                        const globalConfig = globalConfigsBySlug.get(slug);
+                        if (!globalConfig) {
+                            return createToolError({
+                                message: `Unknown global: ${slug}`,
+                                slug,
+                                tool: "proposeUpdateGlobal"
+                            });
+                        }
+                        const preparedData = prepareProposalWriteData({
+                            collectionConfig: {
+                                fields: globalConfig.fields || [],
+                                slug: globalConfig.slug
+                            },
+                            data,
+                            inferenceText: prompt,
+                            label,
+                            localizedData,
+                            mode: "update"
+                        });
+                        if (preparedData.issues.length > 0) {
+                            return createToolError({
+                                details: {
+                                    issues: preparedData.issues
+                                },
+                                message: `Update proposal for global ${slug} is invalid. Retry with exact schema fields and complete array/block objects: ${formatProposalIssuesForRetry(preparedData.issues)}`,
+                                slug,
+                                tool: "proposeUpdateGlobal"
+                            });
+                        }
                         const proposal = {
                             action: "updateGlobal",
-                            ...localizedData ? {
-                                localizedData
+                            ...preparedData.localizedData ? {
+                                localizedData: preparedData.localizedData
                             } : {
-                                data: data || {}
+                                data: preparedData.data || {}
                             },
                             label: getSafeProposalLabel(label),
                             ...activeLocale ? {
@@ -583,19 +1365,24 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     }
                 },
                 searchDocs: {
-                    description: "Search documents in one collection. Use query for a loose text search where possible.",
+                    description: "Search documents in one collection.",
                     inputSchema: z.object({
                         collection: collectionSlugSchema,
                         limit: z.number().int().min(1).max(10).default(5),
                         query: z.string().optional()
                     }),
                     execute: async ({ collection, limit, query })=>{
-                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
-                        const searchableFields = collectionConfig?.fields.filter((field)=>"name" in field && [
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
+                        const searchableFields = collectionConfig?.fields.flatMap((field)=>{
+                            if (!("name" in field) || ![
                                 "email",
                                 "text",
                                 "textarea"
-                            ].includes(field.type)).map((field)=>"name" in field ? field.name : null).filter(Boolean) || [];
+                            ].includes(field.type) || !field.name) return [];
+                            return [
+                                field.name
+                            ];
+                        }) || [];
                         const where = query && searchableFields.length > 0 ? {
                             or: searchableFields.map((field)=>({
                                     [field]: {
@@ -638,12 +1425,25 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     "You are a Payload CMS assistant. Inspect schema/content with tools before proposing writes.",
                     "Mentions define the active CMS scope. Locale mentions define active locale; multiple locales require localizedData keyed by locale.",
                     "Writes are proposals only. Never claim changes were applied before user confirmation.",
-                    "For create/update/delete use proposal tools. Put concrete field values only in tool data, not visible text.",
-                    "If schema details are missing, call listCollections/listGlobals with a slug before proposing.",
+                    "Uploaded media attachments appear in context as mediaAttachment entries. Use their exact IDs for upload fields.",
+                    "If an uploaded media document has editable descriptive fields, propose an update to that media document with suitable values.",
+                    "If a collection has a required `slug` field and the user does not provide it, generate a URL‑friendly slug from the title or from the first meaningful word of the prompt.",
+                    "For create/update/delete requests, you must use proposal tools. Do not end with plain text if the user asked for a content change.",
+                    "If the user asks to create, update, refine, translate, remove, or delete content, produce at least one proposal tool call unless blocked by missing schema information or permissions.",
+                    "Put concrete field values only in tool data, not visible text.",
+                    "For blocks fields: use exact blockType values from schema, exact field names, and complete objects for required block fields.",
+                    "For arrays: every item must be an object matching the child field schema, not free text.",
+                    "If schema details are missing, call listCollections/listGlobals with a slug before proposing. If an inferred collection schema is already present in context, use it directly.",
+                    `Collection aliases: ${JSON.stringify(collectionAliasMap)}.`,
+                    `Likely collection matches for this prompt: ${JSON.stringify(likelyCollectionMatches)}.`,
                     `Focused required create fields: ${JSON.stringify(focusedRequiredFieldsByCollection)}.`,
                     `Focused title fields: ${JSON.stringify(focusedTitleFieldByCollection)}. Infer concise titles when needed.`,
+                    `Preferred proposal tool for this prompt: ${intentToolChoice?.toolName || "none"}.`,
                     "Visible response: plain text, under 40 words, no Markdown, no proposed content."
                 ].join("\n"),
+                ...intentToolChoice ? {
+                    toolChoice: intentToolChoice
+                } : {},
                 tools
             });
             const stream = new ReadableStream({
@@ -668,19 +1468,75 @@ export const createChatHandler = (options = {})=>async (req)=>{
                             if (part.type === "finish") {
                                 const finishPart = part;
                                 usage = finishPart.totalUsage || finishPart.usage || null;
+                                const reason = getChatCompletionReason({
+                                    proposalCount: proposals.length,
+                                    toolFailures,
+                                    writeIntent
+                                });
+                                const debugPayload = createDebugPayload({
+                                    activeLocale,
+                                    debug,
+                                    proposalCount: proposals.length,
+                                    selectedLocales,
+                                    toolFailures,
+                                    usage,
+                                    writeIntent
+                                });
+                                logHandlerEvent(req, proposals.length > 0 ? "info" : "warn", {
+                                    activeLocale,
+                                    debug,
+                                    msg: proposals.length > 0 ? "AI chat completed with proposals" : "AI chat completed without proposals",
+                                    proposalCount: proposals.length,
+                                    proposals: proposals.map((proposal)=>getProposalSummary(proposal)),
+                                    promptPreview: getLogPreview(prompt),
+                                    reason,
+                                    selectedLocales,
+                                    toolFailureCount: toolFailures.length,
+                                    toolFailures,
+                                    usage
+                                });
                                 sendEvent(controller, "proposals", {
                                     proposals,
                                     usage
                                 });
+                                sendEvent(controller, "debug", debugPayload);
                                 sendEvent(controller, "done", {});
                                 didSendTerminalEvent = true;
                             }
                         }
                         if (!didSendTerminalEvent) {
+                            const reason = getChatCompletionReason({
+                                proposalCount: proposals.length,
+                                toolFailures,
+                                writeIntent
+                            });
+                            const debugPayload = createDebugPayload({
+                                activeLocale,
+                                debug,
+                                proposalCount: proposals.length,
+                                selectedLocales,
+                                toolFailures,
+                                usage,
+                                writeIntent
+                            });
+                            logHandlerEvent(req, proposals.length > 0 ? "info" : "warn", {
+                                activeLocale,
+                                debug,
+                                msg: proposals.length > 0 ? "AI chat completed with proposals" : "AI chat completed without proposals",
+                                proposalCount: proposals.length,
+                                proposals: proposals.map((proposal)=>getProposalSummary(proposal)),
+                                promptPreview: getLogPreview(prompt),
+                                reason,
+                                selectedLocales,
+                                toolFailureCount: toolFailures.length,
+                                toolFailures,
+                                usage
+                            });
                             sendEvent(controller, "proposals", {
                                 proposals,
                                 usage
                             });
+                            sendEvent(controller, "debug", debugPayload);
                             sendEvent(controller, "done", {});
                         }
                     } catch (err) {