diff --git a/README.md b/README.md
index c6e7870a1..2781230f4 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,5 @@
-This is a super-repository skeleton containing a [Tup](http://gittup.org/tup) 
-build system for Genode components and packages. It requires a Genode SDK to be 
-present and the PKG_CONFIG_PATH variable to be set appropriately, most likely to
-`/opt/genode-sdk-x86_64/pkgconfig`. See http://github.com/ehmry/genode/releases 
-for an SDK. A the `pkg-config` tool and copy of the Genode toolchain is required 
-as well, see https://genode.org/download/tool-chain.
+This is a super-repository containing a [Tup](http://gittup.org/tup) build 
+system and submodules containing Genode components and runtime metadata.
 
-To use this build-system, edit the `tup.config` to match your depot user and PGP 
-key as well as the version of the SDK. Unfortunately the build-system lacks any 
-knowledge about what packages are available in external depots, so external 
-package versions must be explicitly stated in `archives` file templates or 
-within `tup.config`. All `archives` files are treated as a template by 
-convention and and `@...@` string will be replaced by a corresponding CONFIG_... 
-value defined in `tup.config`.
-
-Please refer to the the [Tup documentation](http://gittup.org/tup/) for details 
-on how the build-system works.
-
-See http://github.com/ehmry/genode-ehmry as an example.
+See http://github.com/ehmry/genode-tup-super for a super-repo skeleton, please 
+forward any pull requests for the build-system there.
diff --git a/libretro/README.md b/libretro/README.md
new file mode 100644
index 000000000..a76c01c31
--- /dev/null
+++ b/libretro/README.md
@@ -0,0 +1,3 @@
+This directory contains submodules for the Libretro frontend, a version of 
+libretro-common that is know to work with Genode, and a collection of cores and 
+build rules.
diff --git a/libretro/cores/README.md b/libretro/cores/README.md
new file mode 100644
index 000000000..b18405942
--- /dev/null
+++ b/libretro/cores/README.md
@@ -0,0 +1,25 @@
+This directory contains core submodules and Genode-specific build rules. To port 
+a core to Genode, add a minimal Tupfile to the upsteam repository, add a new 
+directory containing the upstream Git repository here as submodule, then add a 
+Tuprules.tup file in the local directory containg Genode build rules.
+
+The upstream `Tupfile` should be as simple as possible. It must mirror the core 
+*TARGET_NAME* defined in the Libretro makefile, the *CORE_DIR* if defined by 
+Make as well, and the *include_rules* directive.
+
+```tup
+TARGET_NAME=2048
+CORE_DIR=$(TUP_CWD)
+include_rules
+```
+
+The local `Tuprules.tup` file contains the actual build rules. Typically a core 
+repository contains `Makefile` and `Makefile.common` files, the later containing 
+a list of sources files relative to a `CORE_DIR` variable, which can usually be 
+included and parsed by Tup. Note that Tup cannot include files relative to a 
+variable, `Tuprules.tup` must include `Makefile.common` relative to itself. 
+Please refer to a `Tuprules.tup` in any of the core directories here as an 
+example.
+
+Unfortunately not all cores are trivally compatible with Tup, in particular 
+those with makefiles that wrap a pre-Libretro Make build system.