diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..aaa9310
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## Unreleased
+
+### Changed
+
+- README documents exit-code semantics, rename refusal, and security expectations.
+- Worker pool, streaming rewrites, and other reliability/performance fixes are landing via open PRs—see GitHub issues #7–#23.
+
+### Fixed
+
+- Non-fatal walk errors are collected and surfaced as a non-zero exit code (#6).
diff --git a/README.md b/README.md
index 88a761d..2e05a0d 100644
--- a/README.md
+++ b/README.md
@@ -13,11 +13,17 @@ Renaming ./alphabet to betabet
 ```
 
 * Files with matching contents in the current working directory are atomically rewritten.
-* Files and directories are renamed.
+* Files and directories are renamed (depth-first: contents before names).
 * Searches are performed recursively from the current working directory.
 * Searches are case sensitive.
 * `.git/` directories are skipped.
-* Binary files are ignored.
+* Binary-looking files are ignored.
+* Rename is refused when the destination path already exists.
+* Errors are logged per file or directory; the process exits with status 1 if any operation failed.
+
+## Security model
+
+`find-replace` is intended for batch find/replace in a working tree you control. It performs atomic rewrites via a temporary file in the same directory and does not overwrite an existing destination during rename. Run it only in trusted directories; symlink hardening is not a current guarantee—see open issues for planned improvements.
 
 ## Goal