diff --git a/auth.md b/auth.md
index a15cf2e..df28f12 100644
--- a/auth.md
+++ b/auth.md
@@ -1,7 +1,8 @@
**A warm welcome to DNS**
-
+
Note: this page is part of the
'[hello-dns](https://powerdns.org/hello-dns/)' documentation effort.
diff --git a/basic.md b/basic.md
index 89eefea..45d7a2f 100644
--- a/basic.md
+++ b/basic.md
@@ -1,21 +1,23 @@
**A warm welcome to DNS**
-
+
Note: this page is part of the
'[hello-dns](https://powerdns.org/hello-dns/)' documentation effort.
-# DNS Basics
In this section we will initially ignore optional extensions that were added
to DNS later, specifically EDNS and DNSSEC.
This file corresponds roughly to the fundamental parts of RFCs 1034, 1035,
2181, 2308, 3596, 4343, 5452, 6604, 7766 and 8020.
-**This file, which describes DNS basics, absolutely must be read from
+**This page, which describes DNS basics, absolutely must be read from
beginning to end in order for the rest of the documents (or DNS) to make
sense.**
+# DNS Basics
+
DNS is mostly used to serve IP addresses and mailserver details, but it can
contain arbitrary data. DNS is all about names. Every name can have data
of several *types*. The most well known externally useful types are *A* for
diff --git a/resolver.md b/resolver.md
index c24d230..ee14dc4 100644
--- a/resolver.md
+++ b/resolver.md
@@ -30,8 +30,76 @@ Excellent resolvers that are freely available and open source include:
So in short, before attempting to write a DNS resolver, ponder if you really
need to.
-# Resolver algorithm
+As part of this project a [`teaching resolver`](tres.md.html) (or `tres`)is
+provided. Understanding `tres` and its source code is easier after reading
+this page.
+
+# Resolver algorithm
+## In-zone nameservers, no CNAMEs
+There are various strategies to resolve names. The most basic form is to
+send the same query for the full query name to a series of ever more
+specific nameservers.
+
+So, to resolve `www.powerdns.com`, send a query for that name to one of the
+26 root-server IP address. The root-servers will return a non-authoritative
+answer ('aa=0') with the NS records of the `COM` servers, and helpfully also
+provide IP addresses for those servers.
+
+The resolver can believe these NS records and even the 'glue' - we trust the
+root-servers to serve the root and everything under it.
+
+Based on the IP addresses provided in the glue, the same `www.powerdns.com`
+query can now be sent to one of the `COM` servers, which in turn replies
+with another non-authoritative answer that does however list the names & IP
+addresses for the `powerdns.com` zones.
+
+Finally, the `www.powerdns.com` query can get sent to one of the
+`powerdns.com` nameserver IP addresses, and finally an answer arrives.
+
+This is the simplest case where resolution can proceed iteratively - each
+response carries full information where the next query can get sent.
+
+## Out-of-zone nameservers
+To resolve `www.powerdns.org`, the situation is more difficult. The
+root-servers again provide the first help by telling us about the `ORG`
+nameservers & their IP addresses.
+
+When we then ask the `ORG` nameservers for `www.powerdns.org`, these return
+with a set of nameservers for `powerdns.org`.. but no IP addresses. This is
+because the `powerdns.org` nameservers do not reside in the `ORG` zone.
+
+This means that the same algorithm we are using to resolve
+`www.powerdns.org` now needs to be started in parallel for finding the IP
+address of `ns1.ds9a.nl`. Luckily, resolving `ns1.ds9a.nl` proceeds as
+described in the previous section, without the need to resolve further
+nameserver names.
+
+Once we have an IP address for a `powerdns.org` nameserver, we can ask it
+about `www.powerdns.org`.
+
+## CNAMEs
+CNAMEs complicate this process slightly but not fundamentally. A CNAME
+redirects our query to a new name. This means that once a CNAME is hit, the
+initial algorithm terminates, and gets restarted for the new CNAME target.
+
+Frequently, a CNAME points to a name that is also within the same zone, for
+example `www.powerdns.org. IN CNAME powerdns.org`. Authoritative servers
+then typically also include the requested type for `powerdns.org` in the
+same DNS response. As an optimization, a resolver can use this CNAME record
+and terminate the algorithm.
+
+# Security
+At every point a resolver must be vigilant to not store data coming from an
+authoritative server that can not be trusted to provide that data.
+
+In addition, if a cache is used, care must be taken that an authoritative
+server must not be allowed to 'extend its own authority' infinitely. This is
+a problem when a domain gets assigned new nameservers, but a resolver
+'sticks' to the old one.
+
+There are many many other security pitfalls within a resolver, which is why
+we recommend not writing another one unless this is really really necessary
+somehow.
-TBC..
diff --git a/stub.md b/stub.md
index b864dc7..2b03e21 100644
--- a/stub.md
+++ b/stub.md
@@ -23,10 +23,11 @@ good care to fully randomize source port and ID fields. It must also guard
against sending out multiple equivalent queries at the same time as this
would allow a 'birthday attack' that could spoof in harmful answers.
-If a resolver sends out two different questions in parallel, like for A and
-AAAA of a name, it should be prepared to receive responses out of order.
-
It is also important to actually test the TC=1 response path, something that
may be triggered when sending queries that lead to huge answers.
+If a resolver sends out two different questions in parallel, like for A and
+AAAA of a name, it should be prepared to receive responses out of order -
+even over TCP!
+