📝 Document when to use each matcher

Add the universe/return axes and a "Use when" column to the README API
table, and the same one-liner to each of the four factory JSDoc blocks.

README.md

@@ -21,17 +21,21 @@ for the design decisions and [Caveats](#caveats) for the limits.
 
 ## API
 
-The package exports four factories. Each comes in a _strict_ variant (one common
-return type `R`) and a _widening_ variant: the `W` suffix means **widening** —
-the return value is widened from one common `R` to the union of every handler's
-return type.
+The package exports four factories. Two axes pick one:
 
-| Factory                          | Return of the matcher            |
-| -------------------------------- | -------------------------------- |
-| `getPrimitiveUnionMatcher<T>()`  | one common `R`                   |
-| `getPrimitiveUnionMatcherW<T>()` | the union of the handler returns |
-| `getTaggedUnionMatcher<T>()`     | one common `R`                   |
-| `getTaggedUnionMatcherW<T>()`    | the union of the handler returns |
+- **Universe** — a _primitive-union_ matcher matches a value that is itself a
+  finite union (`"yes" | "no"`); a _tagged-union_ matcher matches an object
+  discriminated by a property (`{ kind: … }`).
+- **Return** — the _strict_ variant gives every handler one common return type
+  `R`; the _widening_ variant (`W`) widens the return value to the union of the
+  handler returns.
+
+| Factory                          | Use when                                                                  | Return                |
+| -------------------------------- | ------------------------------------------------------------------------- | --------------------- |
+| `getPrimitiveUnionMatcher<T>()`  | the value is the union and all handlers return the same type              | one common `R`        |
+| `getPrimitiveUnionMatcherW<T>()` | the value is the union and handlers return different types                | union of the handlers |
+| `getTaggedUnionMatcher<T>()`     | the value is a discriminated object and all handlers return the same type | one common `R`        |
+| `getTaggedUnionMatcherW<T>()`    | the value is a discriminated object and handlers return different types   | union of the handlers |
 
 ### Primitive-union matchers