docs: updated docs

README.md

@@ -35,7 +35,10 @@ The WSLC backend is built directly against the `Microsoft.WSL.Containers` NuGet
 
 ## Prerequisites
 
-Pick a backend — see [Backends: WSLC or Docker](docs/wiki/Backends.md) for the comparison.
+Pick a backend — see [Backends: WSLC or Docker](docs/wiki/Backends.md) for the comparison — or skip the
+choice: reference the umbrella `Purview.Containers` and it brings the abstractions plus both backends,
+selecting WSLC on Windows and Docker elsewhere automatically. Pick a single backend below only when you
+want to fix the runtime.
 
 **WSL Containers backend**
 

docs/wiki/Backends.md

@@ -2,14 +2,30 @@
 
 `Purview.Containers` has **one API and two interchangeable backends**. The same test code, the same service
 modules (`Purview.Containers.PostgreSql`, `Redis`, `MsSql`, `RabbitMq`, `Azurite`, `Nats`, `MySql`), and
-the same connection-string accessors run on either runtime — you choose which one, in code or from the
-environment.
+the same connection-string accessors run on either runtime — you choose which one by the package you
+reference, and can override it in code or from the environment.
 
+- `**Purview.Containers**` — the umbrella: `Core` plus both backends, for one reference with automatic
+  selection.
+- `**Purview.Containers.Core**` — the backend-neutral abstractions (the API you code against); usually
+  arrives transitively.
 - `**Purview.Containers.Wsl**` — throwaway containers on **Microsoft WSL Containers (WSLC)**, the Windows
   runtime with no Docker installation.
 - `**Purview.Containers.Docker**` — throwaway containers on **any reachable Docker daemon**, driven by
   Testcontainers.
 
+## Which package do I reference?
+
+| Package | Use it when |
+| --- | --- |
+| `Purview.Containers` | The umbrella: `Core` + both backends. One reference, zero config — WSLC on Windows, Docker elsewhere (auto). **Recommended default.** |
+| `Purview.Containers.Core` | The backend-neutral abstractions (the API). Reference it explicitly with one or both backends when you want a minimal dependency surface; otherwise it arrives transitively. |
+| `Purview.Containers.Wsl` | WSL Containers only — a Windows dev machine with no Docker. |
+| `Purview.Containers.Docker` | Docker only — any platform, CI, Linux/macOS. |
+
+Service modules (`Purview.Containers.PostgreSql`, `Redis`, …) are backend-neutral: add any backend package
+(or the umbrella) alongside one to run it.
+
 ## At a glance
 
 |  | WSL Containers | Docker |
@@ -117,7 +133,7 @@ public class CacheTests
 
 The **package reference** decides which runtime executes it. Three project shapes cover every case.
 
-### Option 1 — WSLC on a Windows machine, Docker elsewhere (one project)
+### Option 1 — WSLC only (Windows)
 
 ```bash
 dotnet add package Purview.Containers.Wsl
@@ -126,7 +142,7 @@ dotnet add package Purview.Containers.Wsl
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
 	<PropertyGroup>
-		<TargetFramework>net10.0</TargetFramework><!-- auto: WSLC on Windows, Docker elsewhere -->
+		<TargetFramework>net10.0</TargetFramework><!-- WSLC only -->
 		<Nullable>enable</Nullable>
 		<ImplicitUsings>enable</ImplicitUsings>
 	</PropertyGroup>
@@ -136,13 +152,16 @@ dotnet add package Purview.Containers.Wsl
 </Project>
 ```
 
-A platform-neutral `net10.0` project binds the portable facade, so it selects WSLC on a Windows host
-and Docker everywhere else. A Windows target framework (`net10.0-windows10.0.19041.0`, x64 or arm64)
-binds the implementation directly. `WindowsSdkPackageVersion` is supplied by the package. A project
-older than .NET 10 fails the build with `PCC0001`, and a 32-bit Windows consumer with `PCC0002`; see
+This project runs WSLC on a Windows host. A platform-neutral `net10.0` project binds the portable
+facade; a Windows target framework (`net10.0-windows10.0.19041.0`, x64 or arm64) binds the
+implementation directly. `WindowsSdkPackageVersion` is supplied by the package. A project older than
+.NET 10 fails the build with `PCC0001`, and a 32-bit Windows consumer with `PCC0002`; see
 [Consumer Requirements](Consumer-Requirements.md).
 
-### Option 2 — Docker anywhere
+> On a non-Windows host this project has **no usable backend** (the facade reports `wsl` unavailable).
+> To also run on Docker there, add `Purview.Containers.Docker` or use the umbrella — see Option 3.
+
+### Option 2 — Docker only (any platform)
 
 ```bash
 dotnet add package Purview.Containers.Docker
@@ -164,14 +183,13 @@ dotnet add package Purview.Containers.Docker
 That project restores and builds on Linux, macOS and Windows — no Windows target framework, no
 `WindowsSdkPackageVersion`, no Docker Desktop licence requirement beyond the daemon you already run.
 
-### Option 3 — one project, both backends (auto)
+### Option 3 — both backends, automatic selection (recommended)
 
-Reference both backends from a single **platform-neutral** project. `auto` selects WSLC on a machine that
-can run it and Docker otherwise — no multi-targeting and no conditional references:
+Add the umbrella `Purview.Containers`: it brings `Core` plus both backends, so `auto` selects WSLC on a
+machine that can run it and Docker otherwise — no multi-targeting and no conditional references:
 
 ```bash
-dotnet add package Purview.Containers.Wsl
-dotnet add package Purview.Containers.Docker
+dotnet add package Purview.Containers
 ```
 
 ```xml
@@ -182,16 +200,23 @@ dotnet add package Purview.Containers.Docker
 		<ImplicitUsings>enable</ImplicitUsings>
 	</PropertyGroup>
 	<ItemGroup>
-		<PackageReference Include="Purview.Containers.Wsl" Version="1.0.0-prerelease.1" />
-		<PackageReference Include="Purview.Containers.Docker" Version="1.0.0-prerelease.1" />
+		<PackageReference Include="Purview.Containers" Version="1.0.0-prerelease.1" />
 	</ItemGroup>
 </Project>
 ```
 
-`auto` probes both in priority order (`wsl` before `docker`) and uses the first that is usable, so this
-one project runs on WSLC on a developer's Windows machine and on Docker in a Linux CI job. A Windows
-target framework is still supported when you want the implementation bound at compile time, but it is not
-required.
+`auto` probes the registered backends in priority order (`wsl` before `docker`) and uses the first that is
+usable, so this one project runs on WSLC on a developer's Windows machine and on Docker in a Linux CI job.
+A Windows target framework is still supported when you want the implementation bound at compile time, but
+it is not required.
+
+Prefer the explicit form? Reference `Purview.Containers.Core` plus both backends instead of the umbrella:
+
+```bash
+dotnet add package Purview.Containers.Core
+dotnet add package Purview.Containers.Wsl
+dotnet add package Purview.Containers.Docker
+```
 
 If your code needs a Windows-only API the portable facade does not expose (for example `WslContainer`, or
 `WslContainerBackend(runtime)` to pin a specific WSLC session), guard it with `#if WINDOWS` — defined by
@@ -216,7 +241,7 @@ A module is backend-neutral, so only the backend package line changes:
 
 ```bash
 dotnet add package Purview.Containers.PostgreSql   # the module
-dotnet add package Purview.Containers.Wsl          # ...or Purview.Containers.Docker
+dotnet add package Purview.Containers              # ...or Purview.Containers.Wsl / Purview.Containers.Docker
 ```
 
 ```csharp

docs/wiki/Consumer-Requirements.md

@@ -9,9 +9,10 @@ The WSL Containers backend package is **multi-target**. It ships a Windows build
 (`net10.0-windows10.0.19041.0`, the implementation, built on the `Microsoft.WSL.Containers`
 projection) and a platform-neutral build (`net10.0`, a facade). A Windows-targeting project binds the
 implementation directly; any other project binds the facade, which builds on **every** platform and, on
-a Windows host, loads the implementation at run time. That is what lets the *same* `net10.0` test
-project run on WSLC on a developer's Windows machine and on Docker in a Linux CI job with no
-configuration change. This page is the authoritative statement of that contract, of the workarounds
+a Windows host, loads the implementation at run time. That is what lets a `net10.0` test project that
+references the WSL backend (or the umbrella `Purview.Containers`, which also brings Docker) run on WSLC on
+a developer's Windows machine and on Docker in a Linux CI job with no configuration change. This page is
+the authoritative statement of that contract, of the workarounds
 that exist for it, and of how each of them is verified.
 
 ## Which package requires what

docs/wiki/Getting-Started.md

@@ -28,24 +28,34 @@ Everything runs on one of two backends; pick the one that matches your machine 
 
 ## 1. Reference a package
 
-Reference a backend package for generic containers:
+| Package | Use it when |
+| --- | --- |
+| `Purview.Containers` | The umbrella: `Core` + both backends. One reference, zero config — WSLC on Windows, Docker elsewhere (auto). **Recommended default.** |
+| `Purview.Containers.Wsl` | WSL Containers only — a Windows dev machine with no Docker. |
+| `Purview.Containers.Docker` | Docker only — any platform, CI, Linux/macOS. |
+
+Start with the umbrella:
+
+```bash
+dotnet add package Purview.Containers
+```
+
+or pick a single backend:
 
 ```bash
-dotnet add package Purview.Containers.Wsl      # WSL Containers (WSLC on Windows, Docker elsewhere)
-dotnet add package Purview.Containers.Docker   # Docker / Testcontainers (any platform)
+dotnet add package Purview.Containers.Wsl      # WSLC only (Windows)
+dotnet add package Purview.Containers.Docker   # Docker only (any platform)
 ```
 
-or a service module, which is backend-neutral and needs a backend package alongside it:
+A service module is backend-neutral, so it needs any backend (or the umbrella) alongside it:
 
 ```bash
 dotnet add package Purview.Containers.PostgreSql
-dotnet add package Purview.Containers.Wsl      # ...or Purview.Containers.Docker
+dotnet add package Purview.Containers          # ...or Purview.Containers.Wsl / Purview.Containers.Docker
 ```
 
-> **Want it to just work without choosing a backend?** Add `Purview.Containers` (the umbrella — it brings
-> the abstractions and both backends) to a platform-neutral `net10.0` project and let automatic selection
-> decide — WSLC on a Windows machine, Docker everywhere else, with no code or configuration change. See
-> [Using it in your tests](Using-in-Your-Tests.md).
+The umbrella is the zero-config shape — see [Using it in your tests](Using-in-Your-Tests.md) for the full
+story.
 
 ## 2. Run a generic container
 

docs/wiki/Home.md

@@ -84,8 +84,10 @@ updates WSL on its own.
 
 ## Choosing a backend
 
-Two backends implement the same API. Automatic detection is the default; pin one in code or from the
-environment:
+Two backends implement the same API. The zero-choice default is the umbrella `Purview.Containers` (see the
+Packages table above): one reference brings both backends and automatic selection — WSLC on Windows,
+Docker elsewhere. Reference a single backend only when you want to fix the runtime. Automatic detection is
+the default; pin one in code or from the environment:
 
 ```powershell
 # auto (the default) | wsl | docker | <registered backend name>

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "purview-containers",
-	"version": "1.0.0-prerelease.2",
+	"version": "1.0.0-prerelease.3",
 	"license": "MIT",
 	"author": {
 		"name": "Kieron Lanning",
@@ -14,4 +14,4 @@
 		"type": "git",
 		"url": "git+https://github.com/purview-dev/containers.git"
 	}
-}
+}

samples/getting-started/README.md

@@ -30,7 +30,9 @@ They reference the backends as **projects** so they build from a clone with no p
 consumer uses packages instead:
 
 ```bash
-dotnet add package Purview.Containers.Docker    # or Purview.Containers.Wsl
+dotnet add package Purview.Containers             # umbrella: both backends, auto (recommended)
+dotnet add package Purview.Containers.Wsl         # or WSLC only
+dotnet add package Purview.Containers.Docker      # or Docker only
 ```
 
 Because they are project references, no `buildTransitive` assets apply, so each sample registers its

src/src/Core/Sdk/README.md

@@ -59,8 +59,9 @@ callers that want to apply their own policy.
 ## Requirements
 
 - **.NET 10 or later**, any platform (this package is portable).
-- A **backend package**: `Purview.Containers.Wsl` (WSLC on a Windows host, Docker elsewhere) or
-  `Purview.Containers.Docker` (Docker Engine reachable from the test host).
+- A **backend package**: `Purview.Containers.Wsl` (WSLC on a Windows host),
+  `Purview.Containers.Docker` (Docker Engine reachable from the test host), or both — or the umbrella
+  `Purview.Containers`, which brings this package plus both backends for automatic selection.
 
 ## Related
 

src/src/Wsl/Sdk/README.md

@@ -13,12 +13,14 @@ Reference this package (or a service module) and containers run on WSLC. The pac
 **multi-target**: a `net10.0` build (a portable facade) and a `net10.0-windows10.0.19041.0` build (the
 implementation). A Windows-targeting project binds the implementation; a `net10.0` project binds the
 facade, which loads the implementation at run time on a Windows host and reports `wsl` as unavailable
-elsewhere — so the **same** test project runs on WSLC on your Windows machine and on
-[`Purview.Containers.Docker`](https://www.nuget.org/packages/Purview.Containers.Docker) in Linux CI
-with no configuration change. It registers itself as the `wsl` backend in the consuming assembly.
-
-> **Running in CI, or on a machine without WSL Containers?** With `auto` (the default) the backend is
-> reported unavailable and selection falls through to Docker. Pin instead with
+elsewhere. It registers itself as the `wsl` backend in the consuming assembly. To also run the same test
+code on Docker in Linux CI, reference
+[`Purview.Containers.Docker`](https://www.nuget.org/packages/Purview.Containers.Docker) (or the umbrella
+[`Purview.Containers`](https://www.nuget.org/packages/Purview.Containers), which brings both backends).
+
+> **Running in CI, or on a machine without WSL Containers?** With only this package referenced, `wsl` is
+> reported unavailable and there is **no** backend to fall back to. Add `Purview.Containers.Docker` or use
+> the umbrella `Purview.Containers`, and `auto` (the default) falls through to Docker. Pin instead with
 > `PURVIEW_CONTAINERS_BACKEND=wsl|docker` or `ContainerBackends.Use(...)` — see
 > [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md).