diff --git a/README.md b/README.md
index 8161dd7..d8ea369 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-object.md) and [FAQ](FAQ.md)
 
 NOTE: this is still experimental - before using it in production,
 please consult me first.
diff --git a/doc/repo-config.md b/doc/GlobalSpec.md
similarity index 100%
rename from doc/repo-config.md
rename to doc/GlobalSpec.md
diff --git a/doc/config-objects.md b/doc/spec-objects.md
similarity index 53%
rename from doc/config-objects.md
rename to doc/spec-objects.md
index c4ee1f9..8d10161 100644
--- a/doc/config-objects.md
+++ b/doc/spec-objects.md
@@ -1,10 +1,13 @@
-Configuration objects
+Specification objects
 =====================
 
-The configuration scheme is comprised of several objects, with tree-structured attributes,
-which are loaded from YAML files. Some attributes have intrinsic defaults, resolved at runtime.
-Various objects also have references to other objects *(e.g. the global config)*, which also
-are added as intrinsics.
+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
 ---------------------
@@ -33,9 +36,18 @@ Path addressing also works through intrinsic object references:
 Object types
 ------------
 
-* global config / repo config
+* [GlobalSpec](GlobalSpec.md)
   * represents the global configuration for a set of target repositories
   * linked into other objects under the `GLOBAL` key
 
-* package config
+* [PkgSpec](PkgSpec.md)
   * represents individual packages
+
+* [PoolSpec](PoolSpec.md)
+  * represents a pool
+
+* [TargetSpec](TargetSpec.md)
+  * build target
+
+* [DutSpec](DutSpec.md)
+  * device under test