diff --git a/README.md b/README.md
index 6a2d3df..6bd8517 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,22 @@ Validates the shape of a DCQL query. Throws `DcqlValidationError` with a `code`
 
 Finds credentials that satisfy each query. Returns `{ satisfied, matches, unmatched }`. Never throws.
 
+Each entry in `unmatched` carries an `UnmatchedReason`:
+
+| Reason | Meaning |
+| --- | --- |
+| `format_mismatch` | candidate's `format` did not equal the query's `format` |
+| `vct_mismatch` | candidate's `vct` was not in the query's `meta.vct_values` (sd-jwt-vc only) |
+| `doctype_mismatch` | candidate's `doctype` was not equal to the query's `meta.doctype_value` (mso_mdoc only) |
+| `missing_claims` | candidate is missing one or more claim paths required by the query |
+| `value_mismatch` | a required claim is present but its value is not in the query's `values:` filter |
+| `trusted_authority_mismatch` | none of the candidate's `trusted_authority_ids` are in the query's `trusted_authorities` filter |
+| `no_credential_found` | the candidate credentials list was empty for this query (reserved for the empty-input case only since 0.2.0) |
+
+When a query has multiple candidate credentials, `matchQuery` reports the LAST candidate's failure (DCQL does not specify candidate ordering — see the `matchQuery` JSDoc for details).
+
+> **0.2.0 BREAKING:** prior to 0.2.0 every failure collapsed to `'no_credential_found'`. Callers reading `unmatched[].reason` need to switch on the new specific values.
+
 ### `buildSubmission(query: DcqlQuery, result: DcqlMatchResult): DcqlSubmission`
 
 Builds a spec-shaped `{ [queryId]: credentialId | credentialId[] }` map. Throws `DcqlMatchError` if the result is not satisfied.
diff --git a/SECURITY.md b/SECURITY.md
index 28932b5..c832b35 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -4,7 +4,8 @@
 
 | Version | Supported |
 | ------- | --------- |
-| 0.1.x   | Yes       |
+| 0.2.x   | Yes       |
+| 0.1.x   | No (superseded by 0.2.0; 0.2.0 is BREAKING — see CHANGELOG) |
 
 Only the latest release receives security updates.
 
diff --git a/src/types.ts b/src/types.ts
index 64be354..735d8ea 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -47,13 +47,29 @@ export type DecodedCredential = {
     trusted_authority_ids?: string[];
 };
 
+/**
+ * Reason a query did not match against the supplied credentials.
+ *
+ * Returned per-query in `DcqlMatchResult.unmatched[].reason`. When a query has
+ * multiple candidate credentials, `matchQuery` reports the LAST candidate's
+ * failure (DCQL does not specify candidate ordering — see `matchQuery` JSDoc).
+ *
+ * @see {@link matchQuery}
+ */
 export type UnmatchedReason =
+    /** The candidate credentials list was empty for this query. */
     | 'no_credential_found'
+    /** Candidate's `format` did not equal the query's `format`. */
     | 'format_mismatch'
+    /** Candidate's `vct` was not in the query's `meta.vct_values` (sd-jwt-vc only). */
     | 'vct_mismatch'
+    /** Candidate's `doctype` was not equal to the query's `meta.doctype_value` (mso_mdoc only). */
     | 'doctype_mismatch'
+    /** Candidate is missing one or more claim paths required by the query. */
     | 'missing_claims'
+    /** A required claim is present, but its value is not in the query's `values:` filter. */
     | 'value_mismatch'
+    /** None of the candidate's `trusted_authority_ids` are in the query's `trusted_authorities` filter. */
     | 'trusted_authority_mismatch';
 
 export type DcqlMatchResult = {