diff --git a/README.md b/README.md
new file mode 100644
index 0000000..07eec16
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# identcasing
+
+Small Nim library for converting between common identifier casing styles.
+
+Supported styles:
+
+- `upperSnakeCase`
+- `lowerSnakeCase`
+- `titleSnakeCase`
+- `lowerKebabCase`
+- `upperKebabCase`
+- `trainCase`
+- `headerCase` as an alias for `trainCase`
+- `dotCase`
+- `lowerCamelCase`
+- `pascalCase`
+
+## Example
+
+```nim
+import identcasing
+
+echo convertCase("user_profile_id", lowerSnakeCase, lowerCamelCase)
+# userProfileId
+
+echo convertCase("HTTP_SERVER_PORT", upperSnakeCase, lowerKebabCase)
+# http-server-port
+
+let words = parseWords("oauth2ClientId", lowerCamelCase)
+echo words
+# @["oauth2", "client", "id"]
+
+echo renderWords(words, titleSnakeCase)
+# Oauth2_Client_Id
+
+echo lowerKebabCaseToLowerCamelCase("questionnaire-response-id")
+# questionnaireResponseId
+```
+
+## Notes
+
+- The library parses identifiers into lowercase words and renders those words
+  into a target style.
+- Camel parsing keeps digits attached to the preceding word, so identifiers
+  like `oauth2Client`, `utf8String`, and `ipv6Address` stay intact.
+- Because of that rule, some values do not round-trip through camel case. For
+  example, `PBM-123` becomes `pbm123`, and converting that back to
+  `upperKebabCase` yields `PBM123`.