Docs/revamp

.github/ISSUE_TEMPLATE/bug_report.md

@@ -9,7 +9,7 @@ What went wrong?
 
 ## Output logs
 
-Please include the command line output log file and migration protocol generated for your `Migration.Tool.CLI.exe migrate` command.
+Please include the command line output log file generated for your `Migration.Tool.CLI.exe migrate` command.
 
 ### Repro steps
 

KVA/Migration.Tool.Source/README.md

@@ -0,0 +1,31 @@
+# Migration.Tool.Source (KVA/)
+
+> **Advanced Customization:** This is an internal abstraction layer. Most users do not need to modify this project. Only modify this if you are contributing to the migration tool itself or need to customize advanced features like [automatic image optimization during migration](https://docs.kentico.com/x/optimize_images_during_upgrade_guides).
+
+## Purpose
+
+Provides version-agnostic abstractions and shared interfaces used by all version-specific Core projects (K11/KX12/KX13). This acts as a bridge between the core infrastructure (Common) and version-specific implementations.
+
+Located in the `KVA/` solution folder to indicate it's part of the Kentico Version Abstraction layer.
+
+## Key Components
+
+- **Source Entity Abstractions** - Interfaces defining common properties across K11/KX12/KX13 entities
+- **Repository Patterns** - Shared patterns for querying source databases
+- **Source API Contracts** - Common interfaces for source instance API calls (e.g., widget metadata discovery)
+- **Mapping Helpers** - Utility functions used across all version-specific implementations
+- **Source Configuration** - Source instance connection and configuration models
+
+## Architecture Role
+
+```
+Migration.Tool.Common
+        ↓
+Migration.Tool.Source  ← Abstraction layer (this project)
+        ↓
+Core.K11 / Core.KX12 / Core.KX13  ← Version-specific implementations
+        ↓
+K11 / KX12 / KX13  ← Source database models
+```
+
+This allows Core projects to share common logic while implementing version-specific behavior where source CMS versions differ.

KX13.Extensions/README.md

@@ -0,0 +1,26 @@
+# KX13.Extensions
+
+> **Minimal User Interaction:** This project provides API controllers that you deploy to your KX13 source instance for widget metadata discovery. Most users only need to copy the controller file to their source instance - no modification required.
+
+## Purpose
+
+Required when migrating **Page Builder widgets** from KX13. Provides ASP.NET Core API controllers that expose widget metadata (available properties, data types, default values) from your source instance. The migration tool calls these APIs to retrieve Page Builder widget configurations that are not stored in the database.
+
+## Setup
+
+For complete setup instructions, see [Source instance API discovery](../Migration.Tool.CLI/README.md#api-discovery-setup) in the Migration.Tool.CLI README.
+
+**Quick summary:**
+1. Copy `ToolApiController.cs` to your KX13 source instance's `Controllers` folder
+2. Register the controller route in `Startup.cs` or `Program.cs`
+3. Set a secret value in the controller
+4. Configure the migration tool's `appsettings.json` with the matching secret
+
+## Technical Details
+
+- ASP.NET Core 3.1+ compatible (use `ToolApiController.NET48.cs` for .NET Framework 4.8 projects)
+- Reads widget registrations from the Kentico API
+- Returns JSON metadata consumed by the migration tool
+- Requires matching secret between controller and migration tool configuration
+
+Most users will not need to modify this code. Contributors may extend it to expose additional widget metadata or handle custom widget registration patterns.

KX13.NET48.Extensions/README.md

@@ -0,0 +1,26 @@
+# KX13.NET48.Extensions
+
+> **Minimal User Interaction:** This project provides API controllers for .NET Framework 4.8 KX13 instances. Most users only need to copy the controller file to their source instance - no modification required.
+
+## Purpose
+
+Required when migrating **Page Builder widgets** from KX13 instances running on **.NET Framework 4.8** (not ASP.NET Core). Provides ASP.NET MVC API controllers that expose widget metadata (available properties, data types, default values) from your source instance. If your KX13 instance runs on ASP.NET Core, use the `KX13.Extensions` project instead.
+
+## Setup
+
+For complete setup instructions, see [Source instance API discovery](../Migration.Tool.CLI/README.md#api-discovery-setup) in the Migration.Tool.CLI README.
+
+**Quick summary:**
+1. Copy `ToolApiController.NET48.cs` to your KX13 source instance's `Controllers` folder
+2. Register the controller route in `/App_Start/RouteConfig.cs`
+3. Set a secret value in the controller
+4. Configure the migration tool's `appsettings.json` with the matching secret
+
+## Technical Details
+
+- ASP.NET MVC (not Core) - for .NET Framework 4.8
+- Uses `System.Web.Http` instead of `Microsoft.AspNetCore.Mvc`
+- Returns JSON metadata consumed by the migration tool
+- Requires matching secret between controller and migration tool configuration
+
+Most users will not need to modify this code. Use this project only if your KX13 source instance runs on .NET Framework 4.8 instead of ASP.NET Core.