doc: finish NodeBuilder docs; more internal links.

And add godoc links.

And some quick words about the fluent APIs.
Signed-off-by: Eric Myhre <hash@exultant.us>

doc/README.md

 - [IPLD Big Picture](./big-picture.md)
-- Nodes
-	- Node interface overview
-	- Node implementation diversity
-	- how to use NodeBuilder
-	- intro to typed nodes
-- using the fluent API
+- [Nodes](./nodes.md)
+	- [Node interface overview](./nodes.md#the-node-interface)
+	- [Node implementation diversity](./nodes.md#node-implementations)
+	- [how to use NodeBuilder](./nodes.md#using-nodebuilder)
+	- [intro to typed nodes](./nodes.md#typed-nodes)
+- [using the fluent API](./fluent.md)
 - operationals
 	- focus & paths
 	- traverse & selectors

doc/fluent.md

+Fluent APIs
+===========
+
+The "fluent" APIs are replicates of most of the core interfaces -- e.g. Node,
+NodeBuilder, etc -- which return single values.  This makes things easier
+to compose in a functional/point-free style.
+
+Errors in the fluent interfaces are handled by panicking.  These errors are
+boxed in a `fluent.Error` type, which can be unwrapped into the original error.
+`fluent.Recover` can wrap any function with automatic recovery of these errors,
+and returns them back to normal flow.  Thus, we can write large blocks of code
+using the fluent APIs, and handle all the errors in one place.  Just as easily,
+we can use nested sets of `fluent.Recover` as desired for granular handling.

doc/nodes.md

@@ -13,6 +13,7 @@ Nodes are trees.  It is not permissible to make a cycle of Node references.
 (Go programmers already familiar with the standard library `reflect` package
 may find it useful to think of `ipld.Node` as similar to `reflect.Value`.)
 
+
 Overview of Important Types
 ---------------------------
 
@@ -21,7 +22,7 @@ Overview of Important Types
 - `ipld.ReprKind` -- this enumeration describes all the major kinds at the Data Model layer.
 - `fluent.Node` -- similar to `ipld.Node`, but methods don't return errors, instead
   carrying them until actually checked and/or using panics, making them easy to compose
-  in long expressions.
+  in long expressions.  See the full page for [Fluent APIs](./fluent.md) for more.
 
 
 the Node interface
@@ -30,11 +31,14 @@ the Node interface
 Node is an interface for inspecting single values in IPLD.
 It has methods for
 extracting go primitive values for all the scalar node kinds,
-'traverse' methods for maps and lists which return further nodes,
+'traverse' methods for maps and lists which return individual child nodes,
 and iterator methods for maps.
 
 Node exposes only reader methods -- A Node is immutable.
 
+See the [godocs for Node](https://godoc.org/github.com/ipld/go-ipld-prime#Node).
+
+
 ### kinds
 
 The `Node.Kind()` method returns an `ipld.ReprKind` enum value describing what
@@ -44,6 +48,8 @@ The validity of many other methods can be anticipated by switching on the kind:
 for example, `AsString` is definitely going to error if `Kind() == ipld.ReprKind_Map`,
 and `TraverseField` is definitely going to error if `Kind() == ipld.ReprKind_String`.
 
+See the [godocs for ReprKind](https://godoc.org/github.com/ipld/go-ipld-prime#ReprKind).
+
 
 Node implementations
 --------------------
@@ -63,7 +69,8 @@ In go-ipld-prime, we have several implementations:
   a bulk parse of cbor data, this can effectively defer parsing of values until
   they're actually inspected, sometimes enabling considerable processing saving.
 - `typed` -- Typed nodes add a few more features onto the base Node interface
-  and add additional logical constraints to their contents -- more on this later.
+  and add additional logical constraints to their contents -- more on this later
+  in the [Typed Nodes](#typed-nodes) section.
 
 Different Node implementations can be mixed freely!
 
@@ -84,7 +91,31 @@ byte slices from the very first read -- in other words, zero copy operation
 using NodeBuilder
 -----------------
 
-TODO
+NodeBuilder is an interface that describes creating new Node instances.
+NodeBuilders are a typical builder pattern: they are mutable and stateful.
+
+See the [godocs for NodeBuilder](https://godoc.org/github.com/ipld/go-ipld-prime#NodeBuilder).
+
+Each package exporting a `Node` implementation will generally also export a
+corresponding `NodeBuilder()` factory func which can be used to start producing
+nodes of that implementation type.
+
+Also note the `Node.NodeBuilder()` method, which returns a NodeBuilder from any Node.
+NodeBuilder instances obtained from these methods produce new nodes of the same
+implementation type (e.g., if it's an `ipldcbor.Node`, it'll give you an
+`ipldcbor.NodeBuilder`).
+
+NodeBuilder instances derived from `Node.NodeBuilder()` have several uses:
+
+1. In the `traversal.Transform` system, this mechanism for getting a NodeBuilder
+  is how we pick an implementation for creating new nodes as we propagate
+  updates through the parents of mutation point.
+2. For typed nodes, NodeBuilder instances obtained from `Node.NodeBuilder()`
+  also continue to carry type constraints matching the node they came from.
+3. Finally, builders from `Node.NodeBuilder()` have some interesting powers
+  for the recursive kinds (maps and lists): they can "append"!  Such appends
+  are still copy-on-write (e.g., won't mutate the original Node), but can often
+  save on memory use.
 
 
 Typed Nodes
@@ -95,3 +126,10 @@ TODO
 Everything in the IPLD *Schema* layer is *also* a node.
 This sometimes means you'll jump over *several* nodes in the raw Data Model
 representation of the data when traversing one link in the Schema layer.
+
+NodeBuilder for typed nodes functions the same as other NodeBuilder instances,
+but again with more constraints on correct usage: NodeBuilder for typed nodes
+will enforce the constraint of their associated type when used.
+`typed.Type` has a `Type.NodeBuilder` method to yield appropriately constrained
+builder instances; and `Node.NodeBuilder` on existing nodes will continue to
+carry on the same constraints as the node its derived from.