diff --git a/README.md b/README.md
index b782b5a..0632647 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,18 @@
 # libpEpDatatypes – A C++ wrapper for the basic C datatypes defined by the pEpEngine.
 
+## Resources
+* Repository: https://gitea.pep.foundation/pEp.foundation/libpEpDatatypes/
+* Change management: <TODO: JIRA link here>
+
+## Requirements & Platforms
+* License: GPL3
+* C++ standard: C++11
+* supported compilers: at least gcc and clang (both have to work)
+
+* Build sytem: GNU Make – Platforms: Linux, macOS
+** Target: static library libpEpDatatypes.a
+* Windows and Android builds will be done separatly
+
 ## Design goals & principles
 
 * implement move c'tor & operator for cheep moves
@@ -8,10 +21,66 @@
 * Ownership of the member pointees: rule of thumb: "const" pointees are non-owned, non-const pointees are owned by the data structure. Exceptional cases are documented explicitly.
 
 ## Public API
-* defined in `namespace pEp` – Beware: it is shared with libpEpAdapter!)
+* defined in `namespace pEp::DT` 
 * header files are installed in `PREFIX/include/pEp/` and are used via `#include <pEp/filename.hh>` – (Also shared with libpEpAdapter!)
 * the linked list datatypes implement the API of [`std::forward_list`](https://en.cppreference.com/w/cpp/container/forward_list)
 
-## Implementation details
-* internal stuff is in `namespace pEp::datatypes`
+### Example usage
+
+The following API is the target we're heading to:
+
+```
+#include <pEp/Types.hh>
+#include <pEp/Adapter.hh>
+
+int main()
+{
+    pEp::Message msg = "From: Alice Cooper <alice@mail.com>\n"
+                       "To: Bob Smith <bob@mail.com>\n"
+                       "Subject: Meeting\n"
+                       "\n"
+                       "Dear Bob,\n"
+                       "\n"
+                       "I will come.\n"
+                       "\n"
+                       "Alice.\n"_CRLF;
 
+    try {
+        auto enc = msg.encrypt();
+        enc.send();
+    }
+    catch (pEp::err& e)
+    {
+    }
+
+    return 0;
+}
+```
+
+As an intermediate step the p≡p API in the engine must be fully
+supported:
+
+```
+#include <pEp/message_api.h> // from pEpEngine
+#include <pEp/Types.hh>      // from libpEpDatatypes
+#include <pEp/Adapter.hh>    // from libpEpDatatypes
+
+int main()
+{
+    pEp::Message msg_plain =
+            "From: Alice Cooper <alice@mail.com>\nTo: Bob "
+            "Smith <bob@mail.com>\nSubject: Meeting\n\n"
+            "Dear Bob,\n\nI will come.\n\nAlice."_CRLF;
+     
+    ::message* msg_enc = nullptr;
+    PEP_STATUS status = encrypt_message(msg_plain, enc_enc, ...);
+    pEp::Message msg{std::move(msg_enc)}; // ownership of the pointee goes to 'msg'
+    
+    return 0;
+}
+```
+
+
+## Implementation details
+* Code-formatting: clang-format. Please try and use .clang-format from libpEpAdapter
+* Include guards: #ifdef/#define style (not #pragma once), naming style: `LIBPEPDATATYPES_FILENAME_HH`