📝 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
+The package exports four factories. Two axes pick one:
-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.
 
-| Factory                          | Return of the matcher            |
+- **Universe** — a _primitive-union_ matcher matches a value that is itself a
-| -------------------------------- | -------------------------------- |
+  finite union (`"yes" | "no"`); a _tagged-union_ matcher matches an object
-| `getPrimitiveUnionMatcher<T>()`  | one common `R`                   |
+  discriminated by a property (`{ kind: … }`).
-| `getPrimitiveUnionMatcherW<T>()` | the union of the handler returns |
+- **Return** — the _strict_ variant gives every handler one common return type
-| `getTaggedUnionMatcher<T>()`     | one common `R`                   |
+  `R`; the _widening_ variant (`W`) widens the return value to the union of the
-| `getTaggedUnionMatcherW<T>()`    | the union of the handler returns |
+  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
 

src/primitive-union.ts

@@ -99,6 +99,9 @@ const dispatch =
 /**
  * Create a matcher for a finite primitive universe, with one common return type.
  *
+ * Use it when the value itself is the union (`"yes" | "no"`) and every handler
+ * returns the same type.
+ *
  * The universe `T` must be a finite union of literals with no
  * value/stringification collision: broad members (`string`, `number`, template
  * literals) and `true | "true"` / `1 | "1"` are rejected at the call site. The
@@ -122,9 +125,10 @@ export const getPrimitiveUnionMatcher = <
  * Create a matcher for a finite primitive universe whose return type is the
  * union of every handler's return type.
  *
- * The widening counterpart of {@link getPrimitiveUnionMatcher}: use it when the
+ * Use it when the value itself is the union (`"yes" | "no"`) and the handlers
- * handlers return different types and the union, not one common `R`, is wanted.
+ * return different types. The `W` (widening) counterpart of
- * The universe constraint and the optional fallback are identical.
+ * {@link getPrimitiveUnionMatcher}; the universe constraint and the optional
+ * fallback are identical.
  *
  * @typeParam T - The finite universe of primitive members to match.
  * @returns A builder for the handler map, or the handler map plus a fallback.

src/tagged-union.ts

@@ -155,6 +155,10 @@ const dispatch =
 /**
  * Create a matcher for a discriminated union, with one common return type.
  *
+ * Use it when the value is an object discriminated by a property
+ * (`{ kind: "circle" } | { kind: "square" }`) and every handler returns the
+ * same type.
+ *
  * The first call fixes the union `T`; the returned function takes the
  * discriminant property's name (`K`, restricted to properties whose values are
  * tags), and that returns the handler-map builder. Supplying a second fallback
@@ -182,9 +186,10 @@ export const getTaggedUnionMatcher = <
  * Create a matcher for a discriminated union whose return type is the union of
  * every handler's return type.
  *
- * The widening counterpart of {@link getTaggedUnionMatcher}: use it when the
+ * Use it when the value is a discriminated object and the handlers return
- * handlers return different types and the union, not one common `R`, is wanted.
+ * different types. The `W` (widening) counterpart of
- * The curried key step and the optional fallback are identical.
+ * {@link getTaggedUnionMatcher}; the curried key step and the optional fallback
+ * are identical.
  *
  * @typeParam T - The discriminated-union type to match.
  * @returns A function that takes the discriminant property's name.