diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa2779d..d1278c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,8 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- document the public API in the README: the four factories, when to use each,
+  what the `W` (widening) suffix means, and examples that bind the handler-map
+  function once
 - add TSDoc to the four public matcher factories
-- document the public API in the README
 
 ## [0.8.1] - 2026-09-23