--- a/docs/introduction.rst	Wed May 05 01:41:01 2021 +0200
+++ b/docs/introduction.rst	Wed May 05 09:22:00 2021 +0200
@@ -278,13 +278,19 @@
 Variable Namespaces
 -------------------
 
-Currently there are 5 namespaces:
+Currently there are 6 namespaces:
 
 1. The unnamed namespace (which is also default).
 
    All the configuration variables are part of this namespace.
 
-2. The namespace ``OS``
+2. The namespace ``ref`` to be used for configuration references.
+
+   This is a namespace that is handled special within "ConfigMix".
+
+   Must be Filters are **not** supported.
+
+3. The namespace ``OS``
 
    Available functions:
 
@@ -295,12 +301,12 @@
          Contains the current node's computername (or whatever
          :py:func:`platform.node` returns)
 
-3. The namespace ``ENV``
+4. The namespace ``ENV``
 
    This namespace contains all the environment variables as they are
    available from :py:data:`os.environ`.
 
-4. The namespace ``PY``
+5. The namespace ``PY``
 
    Contains selected values from the running Python:
 
@@ -317,7 +323,7 @@
      ``implementation``
          The return value of :py:func:`platform.python_implementation`
 
-5. The namespace ``AWS``
+6. The namespace ``AWS``
 
    Contains some metadata for AWS instances when running from within
    AWS:
@@ -426,6 +432,18 @@
 interpreter written in C.
 
 
+Configuration tree references
+-----------------------------
+
+With ``{{ref:my.other.key}}``
+
+- special namespace ``ref``
+- No special handling when merging is done
+- Keys within `.getvar_s()` and `.getvar()` are handled
+- in `.getvar()` only, when it is the directly referenced value
+- recursive expandion in `.getvar_s()` expands
+
+
 Custom filename extensions and custom loaders
 ---------------------------------------------