diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,17 @@
+# hextream
+
+This library provides Haskell-native, streaming-friendly XML parsers.
+
+Parsers are organized into 3 layers of increasing abstraction level: low, middle and high. Applications will most probably want to rely on the high-level layer.
+
+The library does not define a data type nor parser for a whole XML document. Instead, parsers operate on XML tokens of various sizes, to allow for a usage in a streaming context (e.g. using [`streaming-attoparsec`](https://hackage.haskell.org/package/streaming-attoparsec)).
+
+
+## Caveats
+
+The following parts of the XML standard are not supported:
+- [external entities](https://www.w3.org/TR/REC-xml/#sec-external-ent)
+- [parameter entities](https://www.w3.org/TR/REC-xml/#dt-PE)
+- the doctype [internal subset](https://www.w3.org/TR/REC-xml/#NT-intSubset), except for [general entity declarations](https://www.w3.org/TR/REC-xml/#NT-GEDecl)
+
+
diff --git a/hextream.cabal b/hextream.cabal
--- a/hextream.cabal
+++ b/hextream.cabal
@@ -1,7 +1,7 @@
 cabal-version:       2.4
 
 name:                hextream
-version:             0.1.0.0
+version:             0.1.0.1
 synopsis:            Streaming-friendly XML parsers
 description:         Cf README file
 homepage:            https://github.com/k0ral/hextream
@@ -12,7 +12,7 @@
 maintainer:          mail@cmoreau.info
 category:            Parsing, XML
 build-type:          Custom
-extra-source-files:  test/*.xml, test/*.golden
+extra-source-files:  README.md, test/*.xml, test/*.golden
 tested-with:         GHC <8.10 && >=8.6
 
 source-repository head