Merge pull request #1992 from shimat/docs/expand-migration-guide

Expand the 4-to-5 migration guide and spotlight it from the README

Author: shimat

.github/copilot-instructions.md

@@ -150,7 +150,7 @@ From `namespace OpenCvSharp.Internal`, types in `namespace OpenCvSharp` are dire
 Free functions are exposed as static methods on `Cv2`, mirroring the C++ namespace structure:
 
 - `Cv2` = `cv::` — e.g. `Cv2.CvtColor` ↔ `cv::cvtColor`.
-- `Cv2.<Sub>` (a nested `public static partial class` under `Cv2`) = `cv::<sub>::` — e.g. `Cv2.Dnn.ReadNetFromOnnx` ↔ `cv::dnn::readNet`, matching the Python `cv2.dnn.*` submodules. In scope: `Dnn`, `Aruco`, `XImgProc`, `XPhoto`, `OptFlow`, `Text`, `Detail`.
+- `Cv2.<Sub>` (a nested `public static partial class` under `Cv2`) = `cv::<sub>::` — e.g. `Cv2.Dnn.ReadNetFromONNX` ↔ `cv::dnn::readNetFromONNX`, matching the Python `cv2.dnn.*` submodules. In scope: `Dnn`, `Aruco`, `XImgProc`, `XPhoto`, `OptFlow`, `Text`, `Detail`.
 
 Place each submodule facade in its module folder as `Cv2.<Sub>.cs` (e.g. `Modules/dnn/Cv2.Dnn.cs`). The file uses `namespace OpenCvSharp;` and `using OpenCvSharp.<Sub>;` (the wrapper *types* stay in their `OpenCvSharp.<Sub>` namespaces). Where a sub-namespace type name collides with one in `OpenCvSharp` root (e.g. `InpaintTypes`), fully-qualify it in the signature (`OpenCvSharp.XPhoto.InpaintTypes`). Functions that live directly in `cv::` (no sub-namespace, e.g. the shape `Create…` factories) go on `Cv2` itself, not a nested class. The `CvExtensions` *extension methods* (`OpenCvSharp.Extensions`) are not part of this and keep their name.
 

README.md

@@ -13,7 +13,9 @@ OpenCvSharp is published in two parallel package families:
 | **OpenCvSharp5** | 5.0.x | .NET 8+ | Active development — recommended for new projects |
 | **OpenCvSharp4** | 4.13.0 | .NET Framework 4.6.1+, .NET Standard 2.0/2.1, .NET 8+ | Maintenance — for .NET Framework, Unity, or older runtimes |
 
-Both families share the same package layout: every `OpenCvSharp5.*` package has an `OpenCvSharp4.*` counterpart. The examples below use **OpenCvSharp5**; replace `5` with `4` for the OpenCvSharp4 family. Migrating from 4 to 5? See the [migration guide](docs/migration-4-to-5.md).
+Both families share the same package layout: every `OpenCvSharp5.*` package has an `OpenCvSharp4.*` counterpart. The examples below use **OpenCvSharp5**; replace `5` with `4` for the OpenCvSharp4 family.
+
+> 🔄 **Already using OpenCvSharp4?** See the **[Migration Guide (4 → 5)](docs/migration-4-to-5.md)** for target framework changes, package/namespace renames, and OpenCV 5 API changes.
 
 ## Quick Start