📝 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.

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
- * handlers return different types and the union, not one common `R`, is wanted.
- * The universe constraint and the optional fallback are identical.
+ * Use it when the value itself is the union (`"yes" | "no"`) and the handlers
+ * return different types. The `W` (widening) counterpart of
+ * {@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.