diff --git a/README.md b/README.md
index 8161dd7..c0dad2c 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ dck-buildpackage tool) and puts them into installable apt repos.
 
 Configuration is done via yaml. (see packages.yml for an example)
 
-See [FAQ](FAQ.md)
+See [specification objects](doc/spec-objects.md) and [FAQ](FAQ.md)
 
 NOTE: this is still experimental - before using it in production,
 please consult me first.
diff --git a/doc/GlobalSpec.md b/doc/GlobalSpec.md
new file mode 100644
index 0000000..9bc68cd
--- /dev/null
+++ b/doc/GlobalSpec.md
@@ -0,0 +1,90 @@
+GlobalSpec (repository config)
+==============================
+
+The repository config (also called the global config) is the central starting point for all
+operations. It basically declares what should be built into the final installable package
+repository. Usually placed under `cf/repos/`.
+
+### Root level keys:
+
+key | description
+---|---
+targets  | Lists the target distros that will be built for
+defaults | Global defaults for certain config items
+packages | Lists the packages that can be built
+pools    | The repo pools and their packages
+
+
+Internally, this config is stored into the global scope. It's fields can be referenced from
+other scopes via the `GLOBAL::` prefix.
+
+Targets section
+---------------
+
+We can build installable repos for several distros in one pass. The `targets` list
+*(list of strings)* defines which targets shall be used. Settings for individual targets defined
+under `cf/targets`.
+
+If predefined targets aren't sufficient, additional ones can be configured by adding appropriate
+target config yaml files.
+
+Note that different cpu architectures also imply different targets. In order to support classic
+multiarch repos *(as most dpkg based distros do)*, the predefined targets are configured to place
+their output into the same, per-distro, repository.
+
+Example: the targets `devuan/daedalus/i386` and `devuan/deadalus/amd64` will both use target repo
+name `devuan/daedalus`
+
+Pools section
+-------------
+
+In order to support different building multiple repos with different package subsets, we can
+configure separate pools. These are listed as subkeys under the `pools` root key. Each pool
+defines a list of primary packages *(key "packages")* it should contain. If those also define
+dependencies, these will be added automatically, thus being built and landing the repo.
+
+Most cases *(for now)* should be sufficient w/ just one pool, named `default`.
+
+The path of the finally installable repo will be a subdir, named by the pool, under the
+per-target directory.
+
+For future releases it is planned to support importing of pools into others: in this case, the
+per-package build job will also add the imported pool's target repo *(so it's packages can be
+directly used)* and skip building dependencies that are already supplied by the imported pools.
+This allows better separation, eg. when some packages have some special build-only dependencies,
+that shouldn't be shipped in the same target repo. *(classic case: golang packages often require
+newer toolchain than shipped by the distro)*
+
+Packages section:
+-----------------
+
+Under the `packages` section, all packages are defined - one subkey per package. The package key
+may either be just the package name, or package name + `"@"` + version string. Inside the package
+config, the fields `package.name` and `package.version` are automatically set.
+
+The packages defined here are only built, when explicitly pulled in by a pool's package list or
+as some other package's dependency.
+
+See [PkgSpec](doc/PkgSpec.md)
+
+Package config:
+---------------
+
+The package config defines everyhing needed for an individual package, which is loaded into a
+separate object *(thus: separate variable namespace)*. When loaded from the global config, the
+fields `package.fqname` *(the key)* `package.name` *(package name w/o version suffix)* and
+`package.version` *(if version is present)* are automatically set from the package key.
+
+Most of the common data, eg. source repo locations, is loaded from CSDB - looked up by the package
+*name* *(w/o the version qualifier)*. See topic CSDB for details.
+
+### Important fields:
+
+variable | description
+---|---
+package.name    | *(intrinsic)* the name of the package, w/o version qualifier
+package.version | *(intrinsic)* the version string *(if present)*
+package.fqname  | *(intrinsic)* full package name, including version suffix
+skip-on-targets | list of targets which skips the package
+depends         | list of dependency packages
+autobuild-ref   | git ref to check out by default
diff --git a/doc/PkgSpec.md b/doc/PkgSpec.md
new file mode 100644
index 0000000..a451dc8
--- /dev/null
+++ b/doc/PkgSpec.md
@@ -0,0 +1,25 @@
+PkgSpec
+=======
+
+Package specs everyhing needed for an individual package. It's usually loaded from individual
+entries of [GlobalSpec](doc/GlobalSpec.md)'s `packages` section - the key from there is stored
+in the `package.fqname` intrinsic.
+
+When loaded from the global config, the
+fields `package.name` and `package.version` *(if version is present)* are automatically set from
+the package key.
+
+Most of the common data, eg. source repo locations, is loaded from CSDB - looked up by the package
+*name* *(w/o the version qualifier)*. See topic CSDB for details.
+
+Important fields:
+---------------------
+
+variable | description
+---|---
+package.name    | *(intrinsic)* the name of the package, w/o version qualifier
+package.version | *(intrinsic)* the version string *(if present)*
+package.fqname  | *(intrinsic)* full package name, including version suffix
+skip-on-targets | list of targets which skips the package
+depends         | list of dependency packages
+autobuild-ref   | git ref to check out by default
diff --git a/doc/spec-objects.md b/doc/spec-objects.md
new file mode 100644
index 0000000..c585171
--- /dev/null
+++ b/doc/spec-objects.md
@@ -0,0 +1,59 @@
+Specification objects
+=====================
+
+The configuration of the build process is comprised of several specification objects - these
+have tree-structured attributes, loaded from YAML files. Some attributes have intrinsic defaults,
+resolved at runtime *(when the value is retrieved)*.
+
+Spec objects also may have references to other ones *(via intrinsics)*, all have a reference to
+the GlobalSpec *(as `GLOBAL::`).
+
+Variable substitution
+---------------------
+
+Scalar **values** *(single items, list entries, but not struct keys)* support variable substitution:
+
+    foo: x-${bar}
+
+    list:
+      - ${foo}
+      - y-${bar}
+
+Nested variables may be addressed by a path:
+
+    one:
+      two:
+        three: ABC
+
+    foo: ${one::two::three}
+
+Path addressing also works through intrinsic object references:
+
+    ${GLOBAL::config.basedir}/cf
+    ${GLOBAL::pathes::github::current}oss-qm/
+
+Defaults and intrinsics
+-----------------------
+
+Spec objects may have defaults set by other places. Intrinsics are defaults defined by the objects
+themselves, usually functions or references to other SpecObject's.
+
+
+Object types
+------------
+
+* [GlobalSpec](GlobalSpec.md)
+  * represents the global configuration for a set of target repositories
+  * linked into other objects under the `GLOBAL` key
+
+* [PkgSpec](PkgSpec.md)
+  * represents individual packages
+
+* [PoolSpec](PoolSpec.md)
+  * represents a pool
+
+* [TargetSpec](TargetSpec.md)
+  * build target
+
+* [DutSpec](DutSpec.md)
+  * device under test