@mvriu5/payload-ai 1.2.0 → 1.3.2

package/dist/handlers/chatHandler.js

@@ -46,7 +46,7 @@ const createDebugPayload = ({ activeLocale, debug, proposalCount, selectedLocale
     });
 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);
@@ -241,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}`);
             }
@@ -258,7 +267,9 @@ 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,
@@ -293,19 +304,28 @@ const getCollectionBlockTypes = (fields)=>{
         ...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 && availableBlockTypes.includes(mention.slug)) {
+        if (mention.type === "block" && mention.slug && availableBlockTypeSet.has(mention.slug)) {
             requestedBlockTypes.add(mention.slug);
         }
     }
-    for (const blockType of availableBlockTypes){
-        const escapedBlockType = blockType.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const blockPattern = new RegExp(`\\b${escapedBlockType}\\b(?:\\s+block)?`, "i");
-        if (blockPattern.test(normalizedPrompt)) {
-            requestedBlockTypes.add(blockType);
+    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 [
@@ -320,6 +340,10 @@ const collectProposalBlockTypes = ({ data, fields })=>{
             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;
@@ -327,7 +351,7 @@ const collectProposalBlockTypes = ({ data, fields })=>{
                         foundBlockTypes.add(blockType);
                     }
                     if (blockType) {
-                        const blockConfig = field.blocks?.find((candidate)=>candidate.slug === blockType);
+                        const blockConfig = blocksBySlug.get(blockType);
                         if (blockConfig?.fields?.length) {
                             visitFields(blockConfig.fields, blockItem);
                         }
@@ -410,11 +434,15 @@ const collectRelationshipTargets = ({ data, fields, path = "" })=>{
             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 = field.blocks?.find((candidate)=>candidate.slug === blockType);
+                const blockConfig = blocksBySlug.get(blockType);
                 if (!blockConfig?.fields?.length) return;
                 targets.push(...collectRelationshipTargets({
                     data: item,
@@ -426,13 +454,91 @@ const collectRelationshipTargets = ({ data, fields, path = "" })=>{
     }
     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 invalidTargets = [];
-    for (const target of targets){
+    const targetResults = await Promise.all(targets.map(async (target)=>{
         try {
             await req.payload.findByID({
                 collection: target.collection,
@@ -441,11 +547,19 @@ const validateRelationshipTargetsExist = async ({ data, fields, req })=>{
                 overrideAccess: false,
                 req
             });
+            return null;
         } catch  {
-            invalidTargets.push(target);
+            return target;
         }
-    }
-    return invalidTargets;
+    }));
+    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,
@@ -453,6 +567,39 @@ const getMentionSummary = (mentions)=>mentions?.map((mention)=>({
             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){
@@ -500,9 +647,19 @@ const createCollectionAliasMap = (collections)=>{
 };
 const getLikelyCollectionMatches = ({ aliasMap, prompt })=>{
     const normalizedPrompt = prompt.toLowerCase();
-    const matches = Object.entries(aliasMap).filter(([alias])=>normalizedPrompt.includes(alias)).map(([, slug])=>slug);
+    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 [
-        ...new Set(matches)
+        ...matches
     ];
 };
 const hasWriteIntent = (prompt)=>{
@@ -517,15 +674,17 @@ const getIntentToolChoice = (prompt)=>{
             type: "tool"
         };
     }
-    if (/\b(create|build|generate|write|draft|make|add)\b/.test(normalizedPrompt)) {
+    // Update existing document (add block, modify content, etc.)
+    if (/\b(update|edit|change|modify|einfügen|hinzufügen|addieren)\b/.test(normalizedPrompt)) {
         return {
-            toolName: "proposeCreateDoc",
+            toolName: "proposeUpdateDoc",
             type: "tool"
         };
     }
-    if (/\b(update|edit|change|revise|refine|rewrite|translate)\b/.test(normalizedPrompt)) {
+    // 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: "proposeUpdateDoc",
+            toolName: "proposeCreateDoc",
             type: "tool"
         };
     }
@@ -544,7 +703,13 @@ 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()) {
@@ -655,8 +820,18 @@ export const createChatHandler = (options = {})=>async (req)=>{
                 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,
@@ -673,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,
@@ -686,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)
@@ -722,7 +909,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
             });
             const writeIntent = hasWriteIntent(prompt);
             const inferredCollectionSlug = mentionedCollectionSlugs.length === 1 ? mentionedCollectionSlugs[0] : mentionedCollectionSlugs.length === 0 && likelyCollectionMatches.length === 1 ? likelyCollectionMatches[0] : undefined;
-            const inferredCollectionConfig = inferredCollectionSlug ? allowedCollections.find((collection)=>collection.slug === inferredCollectionSlug) : undefined;
+            const inferredCollectionConfig = inferredCollectionSlug ? allowedCollectionsBySlug.get(inferredCollectionSlug) : undefined;
             if (inferredCollectionConfig && !mentionContext.some((item)=>item.type === "collection" && item.slug === inferredCollectionConfig.slug)) {
                 mentionContext.push({
                     ...describeCollectionLikeConfig({
@@ -763,7 +950,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
             };
             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)
@@ -782,13 +969,13 @@ 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);
+                            const collection = allowedCollectionsBySlug.get(slug);
                             if (!collection) {
                                 return createToolError({
                                     message: `Unknown collection: ${slug}`,
@@ -810,12 +997,12 @@ 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);
+                        const globalConfig = globalConfigsBySlug.get(slug);
                         if (!globalConfig) {
                             return createToolError({
                                 message: `Unknown global: ${slug}`,
@@ -835,14 +1022,13 @@ 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);
+                            const global = globalConfigsBySlug.get(slug);
                             if (!global) {
                                 return createToolError({
                                     message: `Unknown global: ${slug}`,
@@ -855,14 +1041,14 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 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(),
@@ -874,7 +1060,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     execute: async ({ collection, data, label, localizedData })=>{
                         const permissionError = getDisallowedCollectionActionError(collection, "create");
                         if (permissionError) return permissionError;
-                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
                         const collectionFields = collectionConfig?.fields || [];
                         const preparedData = prepareProposalWriteData({
                             collectionConfig: collectionConfig,
@@ -935,6 +1121,31 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 });
                             }
                         }
+                        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,
@@ -978,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),
@@ -1000,7 +1211,7 @@ 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(),
@@ -1013,7 +1224,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                     execute: async ({ collection, data, id, label, localizedData })=>{
                         const permissionError = getDisallowedCollectionActionError(collection, "update");
                         if (permissionError) return permissionError;
-                        const collectionConfig = allowedCollections.find((item)=>item.slug === collection);
+                        const collectionConfig = allowedCollectionsBySlug.get(collection);
                         const collectionFields = collectionConfig?.fields || [];
                         const preparedData = prepareProposalWriteData({
                             collectionConfig: collectionConfig,
@@ -1055,6 +1266,31 @@ export const createChatHandler = (options = {})=>async (req)=>{
                                 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,
@@ -1073,7 +1309,7 @@ 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),
@@ -1083,7 +1319,7 @@ export const createChatHandler = (options = {})=>async (req)=>{
                         message: "Either data or localizedData is required."
                     }),
                     execute: async ({ data, label, localizedData, slug })=>{
-                        const globalConfig = req.payload.config.globals?.find((global)=>global.slug === slug);
+                        const globalConfig = globalConfigsBySlug.get(slug);
                         if (!globalConfig) {
                             return createToolError({
                                 message: `Unknown global: ${slug}`,
@@ -1129,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]: {
@@ -1184,6 +1425,9 @@ 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.",
+                    "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.",

package/dist/handlers/mediaUploadHandler.d.ts

@@ -0,0 +1,7 @@
+import { type PayloadHandler } from "payload";
+export type MediaUploadOptions = {
+    acceptedMimeTypes?: string[];
+    collectionSlug: string;
+    maxFileSize?: number;
+};
+export declare const createMediaUploadHandler: ({ acceptedMimeTypes, collectionSlug, maxFileSize }: MediaUploadOptions) => PayloadHandler;