diff --git a/CHANGELOG.md b/CHANGELOG.md
index f7390d8..1632b73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,13 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- restore the README's Synopsis and Examples sections: a quick-start recipe plus
-  real-world examples (primitive-union dispatch, a fallback, a property union
-  narrowed by the tagged-union matcher, and a widening variant)
-- 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
+## [0.8.2] - 2026-09-25
+
+- write the README's Synopsis and Examples sections
+- document the public API in the README
 - add TSDoc to the four public matcher factories
+- document alternatives
 
 ## [0.8.1] - 2026-09-23
 
@@ -109,7 +108,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - basic setup
 
-[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.2...main
+[0.8.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...0.8.2
 [0.8.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.0...0.8.1
 [0.8.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.1...0.8.0
 [0.7.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.0...0.7.1
diff --git a/package-lock.json b/package-lock.json
index 25c740d..0cfea7f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.8.1",
+    "version": "0.8.2",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "tiny-pattern-ts",
-            "version": "0.8.1",
+            "version": "0.8.2",
             "license": "MIT",
             "dependencies": {
                 "type-fest": "^5.9.0"
diff --git a/package.json b/package.json
index 1ef108b..bc0ad89 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.8.1",
+    "version": "0.8.2",
     "description": "Exhaustive, type-safe pattern matching for TypeScript",
     "keywords": [
         "adt",