docs: add ABP Suite guidance for Mapperly migration

docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md

@@ -174,6 +174,16 @@ public partial class IdentityUserToIdentityUserDtoMapper : MapperBase<IdentityUs
 }
 ```
 
+## ABP Suite Compatibility Note
+
+If you still use [ABP Suite](../../suite/index.md) to generate CRUD pages after migrating to Mapperly, keep the main Suite-managed mapper files reserved for Suite updates.
+
+- Keep the conventional files such as `*ApplicationMappers.cs`, `*BlazorMappers.cs` and `*WebMappers.cs` as the files that ABP Suite updates.
+- Move manual or AI-generated Mapperly classes into separate files.
+- Avoid creating extra manual files with the same conventional suffixes that ABP Suite scans, because Suite may pick the wrong file when generating or updating mappings.
+
+For example, names like `IdentityUserMapperlyMappings.cs`, `CustomObjectMappings.cs` or `ManualOrderMappings.cs` are safer for your hand-written mappers.
+
 ## AI Prompt for Migrating AutoMapper to Mapperly
 
 If you have AI tools like Cursor, you can use the following prompt to migrate your AutoMapper mappings to Mapperly automatically:
@@ -187,6 +197,8 @@ Please help me migrate AutoMapper Profile classes to Mapperly. I have AutoMapper
 
 1. **Convert AutoMapper Profile to Mapperly Mappers**: Transform each `CreateMap` into a separate Mapperly mapper class
 2. **Rename the file**: Change from `XXXAutoMapperProfile.cs` to `XXXMappers.cs`
+
+   > If you still use **ABP Suite**, keep Suite-managed mapper files separate from your manual/AI-generated mapper files. See the **ABP Suite Compatibility Note** section above.
 3. **Use proper Mapperly attributes**: 
    - `[Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)]` for each mapper class
    - `[MapExtraProperties]` for classes that need extra properties mapping

docs/en/suite/generating-crud-page.md

@@ -323,6 +323,17 @@ There are some adjustments you may need to make before generating CRUD pages for
   - Project key is in kebab case. E.g. `book-store`.
   - Project is defined as `defaultProject`.
 
+### What to Check If CRUD Generation Fails After Migrating to Mapperly
+
+If you migrated an existing solution from AutoMapper to Mapperly and ABP Suite starts appending mappings to the wrong file or generating duplicate/inconsistent mapper classes, check your mapper file layout.
+
+- Keep the main Suite-managed files, such as `*ApplicationMappers.cs`, `*BlazorMappers.cs` and `*WebMappers.cs`, reserved for ABP Suite updates.
+- Move manual or AI-generated Mapperly classes to separate files.
+- Avoid naming those manual files with the same conventional suffixes that ABP Suite scans, otherwise Suite may choose the wrong file while generating CRUD pages.
+- If you temporarily excluded a Suite-managed mapper file from the build, add it back after reorganizing your mappings.
+
+After reorganizing the files, clean the solution, rebuild it, and try generating the entity again.
+
 ## Generating CRUD Pages via Command Line
 
 You can generate CRUD pages via [ABP CLI](../cli), without opening ABP Suite's user interface.