diff --git a/doc/source/operations.rst b/doc/source/operations.rst
new file mode 100644
index 0000000..f744148
--- /dev/null
+++ b/doc/source/operations.rst
@@ -0,0 +1,151 @@
+==================
+reclass operations
+==================
+
+YAML FS storage
+---------------
+While |reclass| has been built to support different storage backends through
+plugins, currently only the ``yaml_fs`` storage backend exists. This is a very
+simple, yet powerful, YAML-based backend, using flat files on the filesystem
+(as suggested by the ``_fs`` postfix).
+
+``yaml_fs`` works with two directories, one for node definitions, and another
+for class definitions. The two directories must not be the same, nor can one
+be a parent of the other.
+
+Files in those directories are YAML-files, specifying key-value pairs. The
+following three keys are read by |reclass|:
+
+============ ================================================================
+Key          Description
+============ ================================================================
+classes      a list of parent classes
+appliations  a list of applications to append to the applications defined by
+             ancestors. If an application name starts with ``~``, it would
+             remove this application from the list, if it had already been
+             added — but it does not prevent a future addition.
+             E.g. ``~firewalled``
+parameters   key-value pairs to set defaults in class definitions, override
+             existing data, or provide node-specific information in node
+             specifications.
+             \
+             By convention, parameters corresponding to an application
+             should be provided as subkey-value pairs, keyed by the name of
+             the application, e.g.::
+
+                applications:
+                - ssh.server
+                parameters:
+                  ssh.server:
+                    permit_root_login: no
+environment  only relevant for nodes, this allows to specify an "environment"
+             into which the node definition is supposed to be place.
+============ ================================================================
+
+Classes files may reside in subdirectories, which act as namespaces. For
+instance, a class ``ssh.server`` will result in the class definition to be
+read from ``ssh/server.yml``. Specifying just ``ssh`` will cause the class
+data to be read from ``ssh/init.yml`` or ``ssh.yml``. Note, however, that only
+one of those two may be present.
+
+Nodes may also be defined in subdirectories. However, node names (filename)
+must be unique across all subdirectories, and |reclass| will exit with an
+error if a node is defined multiple times. Subdirectories therefore really
+only exist for the administrator's local data structuring. They may be used in
+mappings (see below) to tag additional classes onto nodes.
+
+Data merging
+------------
+|reclass| has two modes of operation: node information retrieval and inventory
+listing. The second is really just a loop of the first across all defined
+nodes, and needs not be further described.
+
+When retrieving information about a node, |reclass| first obtains the node
+definition from the storage backend. Then, it iterates the list of classes
+defined for the node and recursively asks the storage backend for each class
+definition (unless already cached).
+
+Next, |reclass| recursively descends each class, looking at the classes it
+defines, and so on, until a leaf node is reached, i.e. a class that references
+no other classes.
+
+Now, the merging starts. At every step, the list of applications and the set
+of parameters at each level is merged into what has been accumulated so far.
+
+Merging of parameters is done "deeply", meaning that lists and dictionaries
+are extended (recursively), rather than replaced. However, a scalar value
+*does* overwrite a dictionary or list value. While the scalar could be
+appended to an existing list, there is no sane default assumption in the
+context of a dictionary, so this behaviour seems the most logical. Plus, it
+allows for a dictionary to be erased by overwriting it with the null value.
+
+After all classes (and the classes they reference) have been visited,
+|reclass| finally merges the applications list and parameters defined for the
+node into what has been accumulated during the processing of the classes, and
+returns the final result.
+
+Wildcard/Regexp mappings
+------------------------
+Using the :doc:`configuration file <configfile>`, it is also possible to
+provide a list mappings between node names and classes. For instance::
+
+  class_mappings:
+    - \* default
+    - /^www\d+/ webserver
+    - \*.ch hosted@switzerland another_class_to_show_that_it_can_take_lists
+
+This will assign the ``default`` class to all nodes (make sure to escape
+a leading asterisk (\*) to keep YAML happy), ``webserver`` to all nodes named
+``www1`` or ``www999``, and ``hosted-in-switzerland`` to all nodes whose names
+end with ``.ch`` (again, note the escaped leading asterisk). Multiple classes
+can be assigned to each mapping by providing a space-separated list (class
+names cannot contain spaces anyway).
+
+.. warning::
+
+  The class mappings do not really belong in the configuration file, as they
+  are data, not configuration inmformation. Therefore, they are likely going
+  to move elsewhere, but I have not quite figured out to where. Most likely,
+  there will be an additional file, specified in the configuration file, which
+  then lists the mappings.
+
+Note that mappings are not designed to replace node definitions. Mappings can
+be used to pre-populate the classes of existing nodes, but you still need to
+define all nodes (and if only to allow them to be enumerated for the
+inventory).
+
+The mapped classes can also contain backreferences when regular expressions
+are used, although they need to be escaped, e.g.::
+
+  class_mappings:
+    - /\.(\S+)$/ tld-\\1
+
+Furthermore, since the outer slashes ('/') are used to "quote" the regular
+expression, *any* slashes within the regular expression must be escaped. For
+instance, the following class mapping assigns a ``subdir-X`` class to all
+nodes that are defined in a subdirectory (using yaml_fs)::
+
+  class_mappings:
+    - /^([^\/]+)\// subdir-\\1
+
+Parameter interpolation
+------------------------
+Parameters may reference each other, including deep references, e.g.::
+
+  parameters:
+    location: Munich, Germany
+    motd:
+      header: This node sits in ${location}
+    for_demonstration: ${motd:header}
+    dict_reference: ${motd}
+
+After merging and interpolation, which happens automatically inside the
+storage modules, the ``for_demonstration`` parameter will have a value of
+"This node sits in Munich, Germany".
+
+Types are preserved if the value contains nothing but a reference. Hence, the
+value of ``dict_reference`` will actually be a dictionary.
+
+You should now be ready to :doc:`use reclass <usage>`!
+
+.. include:: substs.inc