diff --git a/.github/copilot-instructions/upgrade-net10-supplement.md b/.github/copilot-instructions/upgrade-net10-supplement.md
index b224241..2683910 100644
--- a/.github/copilot-instructions/upgrade-net10-supplement.md
+++ b/.github/copilot-instructions/upgrade-net10-supplement.md
@@ -91,17 +91,33 @@ Verify all Microsoft.IdentityModel.* packages are at the same version. If misali
## xUnit v3 Migration
-If upgrading to xunit.v3 (v3.x), replace the v2 core package while preserving VSTest compatibility (required for `dotnet test` in VSTest mode, used by CI pipelines):
+If upgrading to xunit.v3 (v3.x), replace the v2 packages entirely. xunit v3 uses Microsoft Testing Platform — it does NOT use VSTest, so VSTest-era packages must be removed:
- Remove `xunit` (the v2 core package).
+- Remove `xunit.runner.visualstudio` — not compatible with v3.
+- Remove `Microsoft.NET.Test.Sdk` — not needed; xunit v3 is a standalone executable.
- Add `xunit.v3` (latest stable, currently 3.2.2).
-- Keep `Microsoft.NET.Test.Sdk` — required as the VSTest test host for `dotnet test`.
-- Keep `xunit.runner.visualstudio` — update it to the latest stable 3.x version. This is the VSTest adapter that enables xUnit test discovery and execution.
- Add `Exe` to each test project's ``. xunit v3 test projects must be executable.
- Check for transitive dependency breakage. Packages that were pulled in transitively by xunit v2 (e.g., Newtonsoft.Json) will no longer be available. If build errors reference missing types, replace usage with built-in alternatives (e.g., `System.Text.Json`) or add an explicit PackageReference.
-- After migration, run `dotnet test --configuration Release` and verify tests are discovered and passing.
+- After migration, run `dotnet run --project ` to verify tests are discovered and passing. Do NOT use `dotnet test` — VSTest will not discover xunit v3 tests.
- If any test project cannot migrate to v3 due to a dependency that requires xunit v2 abstractions, keep that project on the latest xunit v2 and add an inline comment in the project file explaining why.
+### xUnit v3 CI Integration (unit-tests.sh / coverlet)
+
+If the repo has a `unit-tests.sh` that uses coverlet to run tests:
+
+- Update `TEST_DLL` and `TEST_EXE` paths to the new TFM (e.g., `net10.0`).
+- Use **full paths** for dotnet global tools (e.g., `/root/.dotnet/tools/coverlet`) — the tools directory is not on PATH in CI containers.
+- coverlet 10.x uses System.CommandLine which re-parses `--targetargs` values. You MUST use equals-sign syntax to prevent arguments like `-trx` from being misinterpreted as the `-t` short option:
+ ```sh
+ # WRONG — System.CommandLine splits "-trx" into "-t" + "rx":
+ --targetargs "-trx /tmp/tests/results.trx"
+
+ # CORRECT — equals syntax keeps the value as a single token:
+ --targetargs="-trx /tmp/tests/results.trx"
+ ```
+- The CI pipeline template's "Publish Unit Test Results" step looks for `*.trx` files. If coverlet fails to run the test executable (exit 0 with no output), no `.trx` is produced and the build will show 0 tests — but will NOT fail. Verify that tests actually ran by checking for the `.trx` file or non-zero test count in the coverlet output.
+
## .NET 10 Breaking Changes
- X509Certificate2 constructors obsolete (SYSLIB0057). Replace with X509CertificateLoader:
diff --git a/.github/copilot-instructions/upgrade-net10.md b/.github/copilot-instructions/upgrade-net10.md
index ac2eb47..f470fdf 100644
--- a/.github/copilot-instructions/upgrade-net10.md
+++ b/.github/copilot-instructions/upgrade-net10.md
@@ -97,7 +97,7 @@ If infrastructure.yaml has a "lambdaFunctions" section, apply these rules only t
1. `dotnet restore` — no errors
2. `dotnet build --configuration Release` — 0 errors
-3. `dotnet test --configuration Release` — 100% pass rate
+3. Run tests — 100% pass rate. Use `dotnet test --configuration Release` for VSTest-based projects (xunit v2), or `dotnet run --project --configuration Release` for xunit v3 projects.
4. `dotnet list package --deprecated` — none actionable
## Documentation