docs: update README for xUnit v3 (async data pipeline, usage examples, upgrade guidance)

Author: perkops

README.md

@@ -1,13 +1,46 @@
-[![NuGet Version](https://img.shields.io/nuget/v/Atc.Test.svg?logo=nuget&style=for-the-badge)](https://www.nuget.org/packages/atc.test)
-
 # ATC Test
 
-Common tools for writing tests using XUnit, AutoFixture, NSubstitute and FluentAssertions.
+![NuGet Version](https://img.shields.io/nuget/v/Atc.Test.svg?logo=nuget&style=for-the-badge)
+
+Common tools for writing tests using xUnit, AutoFixture, NSubstitute and FluentAssertions.
+
+## Package References
+
+Add `Atc.Test` to the project containing your tests or to a shared test utilities project.
+
+Typical test project (excerpt):
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <OutputType>Exe</OutputType>
+    <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit.v3" Version="3.0.1" />
+    <PackageReference Include="Atc.Test" Version="$(LatestOrPinned)" />
+  </ItemGroup>
+  <!-- Remove legacy AutoFixture.Xunit2 using if brought transitively -->
+  <ItemGroup>
+    <Using Remove="AutoFixture.Xunit2" />
+  </ItemGroup>
+</Project>
+```
 
-> **Version Notes:**  
-> If you are using the `MemberAutoNSubstituteData` attribute, ensure that both `xunit` and `xunit.extensibility.core` packages are set to version **2.9.0**.
-> This is because the latest versions of xUnit are currently incompatible with `MemberAutoNSubstituteData` due to an unresolved issue. Although [xunit/xunit#3031](https://github.com/xunit/xunit/issues/3031) has been closed, the problem remains unresolved.  
-> Upgrading beyond version 2.9.0 may result in test failures or unexpected behavior.
+`Atc.Test` depends on `xunit.v3.extensibility.core` for the extensibility APIs, but it intentionally does NOT bring in the `xunit.v3` meta-package for you.
+
+### Why you must still reference xUnit directly
+
+We do not make `xunit.v3` transitive because:
+
+- The `xunit.v3` meta-package pulls in runner-related assets that are not targeted for `netstandard2.1`; this causes NU1701 framework fallback warnings if we referenced it from the multi-targeted library.
+- Consumers should control the exact xUnit version (pin or float) in their test project without the library forcing an upgrade cadence.
+- Keeping test framework + runner packages at the application (test project) layer avoids unexpected breaking changes when updating `Atc.Test`.
+- Separation of concerns: `Atc.Test` provides data attributes/utilities; the test project owns the choice of framework + runner configuration.
+
+If you need a different xUnit patch/minor version, just adjust the `<PackageReference Include="xunit.v3" ... />` in your test project.
 
 
 ## Test Attributes
@@ -18,8 +51,45 @@ Common tools for writing tests using XUnit, AutoFixture, NSubstitute and FluentA
 | `InlineAutoNSubstituteData` | Provides a data source for a data theory, with the data coming from inline values combined with auto-generated data specimens generated by AutoFixture and NSubstitute.|
 | `MemberAutoNSubstituteData` | Provides a data source for a data theory, with the data coming from one of the following sources and combined with auto-generated data specimens generated by AutoFixture and NSubstitute.|
 
+### Usage Examples
+
+```csharp
+public class CalculatorTests
+{
+    [Theory]
+    [AutoNSubstituteData]
+    public void AutoData_Generates_Specimens(int a, int b, Calculator sut)
+    {
+        var result = sut.Add(a, b);
+        result.Should().Be(a + b);
+    }
+
+    [Theory]
+    [InlineAutoNSubstituteData(2, 3)]
+    public void InlineAutoData_Mixes_Inline_And_Auto(int a, int b, Calculator sut)
+    {
+        sut.Add(a, b).Should().Be(5);
+    }
+
+    public static IEnumerable<object?[]> MemberSource()
+    {
+        yield return new object?[] { 1, 2 };
+        yield return new object?[] { 10, 20 };
+    }
+
+    [Theory]
+    [MemberAutoNSubstituteData(nameof(MemberSource))]
+    public void MemberAutoData_Augments_Member_Data(int a, int b, Calculator sut)
+    {
+        sut.Add(a, b).Should().Be(a + b);
+    }
+}
+```
+
+All remaining parameters (after those satisfied by inline/member data) are populated using an AutoFixture `IFixture` customized with NSubstitute for interfaces/abstract classes.
+
 > **Note:**
-> NSubstitute is used when the type being created is abstract, or when the `[Substitute]` is applied.
+> NSubstitute is used when the type being created is an interface or abstract class.
 
 ## Test Helpers
 
@@ -33,7 +103,7 @@ Common tools for writing tests using XUnit, AutoFixture, NSubstitute and FluentA
 
 ## Extensibility
 
-The default `Fixture` returned by the `FixtrueFactory.Create()` method is used for all the `Attributes` mentioned above.
+The default `Fixture` returned by the `FixtureFactory.Create()` method is used for all the attributes mentioned above.
 
 To add customizations to this, you can add the `AutoRegisterAttribute` to any custom `ICustomization` or `ISpecimenBuilder` to have it automatically added to the Fixture.