   the code to use the action-suffixed load instead. To learn more about the dangers of loads and lifecycle methods, see
   the [reference on loading data]().
 
-  ### How reads work : `untangled/load`
+  ### Using `untangled/load` Directly
 
   The helper functions described above simply trigger a built-in Untangled mutation called `untangled/load`, which you are
-  allowed (and sometimes encouraged) to use directly. It is the Untangled method of doing follow-on reads after a remote
-  mutation:
-
-  ```
-  (om/transact! this '[(app/do-some-thing) (untangled/load {:query [:a]})])
-  ```
-
-  The normal form of follow-on keywords (for re-rendering the UI) works fine, it will just never trigger remote
-  reads.
+  allowed (and sometimes encouraged) to use directly. The arguments to this mutation include:
+
+  - `query`: The specific query you'd like to send to the server
+  - `post-mutation`: A symbol indicating a mutation to run after the load completes
+  - `without`: A set of keywords that should be (recursively) removed from `query`
+  - `refresh`: A vector of keywords that should cause re-rendering after the load.
+  - `parallel`: True or false. If true, bypasses the sequential network queue
+  - `ident`: An ident. Used if you want the query to be morphed into an ident join. Used by
+  `load-field`.
+  - `field`: A keyworkd. Used if you want to focus the query to a specific single item. Used by
+  `load-field`.
+  - `marker`: True or false. If true, places a loading marker in place of the first top-level key in the query,
+    of in place of the given database object if `ident` and `field` are set (e.g. by `load-field`)
+
+  For most direct use-cases you'll probably skip using the `load-field` specific parameters. You can read
+  the source of `load-field` if you'd like to simulate it by hand.
+
+  The most common use for a direct call to the `untangled/load` mutation is obtaining a value from the server
+  after running some mutation that had a (potential) remote effect.
+
+  #### Getting a Remote Value after a Mutation
+
+  The most common direct use of `untangled/load` is doing remote follow-on reads after a mutation (which itself may
+  be remote).
+
+  Note the difference. The following follow-on read is *always* just a local re-render in Untangled (in stock Om,
+  the `:something` keyword can also trigger a remote read, though you'd have to write logic into the parser
+  to figure it out):
+
+  ```
+  (om/transact! this '[(app/do-some-thing) :something])
+  ```
+
+  If what you want instead is `do-some-thing` and the read `:something` from the server, you instead want:
+
+  ```
+  (om/transact! this '[(app/do-some-thing) (untangled/load {:query [:something] :refresh [:something})])
+  ```
+
+  This has both a clear benefit and cost with respect to stock Om:
+
+  - The benefits are:
+      - Non-opaque reasoning
+      - No need to write parser logic to figure out if you want to do remote reads
+  - The costs are:
+      - The UI is aware of what is remote, and what is local (in stock Om, the UI is completely unconcerned
+        about remoting.)
+
+  In practice, we've found that the idea that something involves a server is pretty clear-cut, so the ability
+  to completely abstract it away really isn't that necessary pragmatically, and the cost of writing
+  the behind-the-scenes logic related making a parser trigger remote reads is somewhat high.
+
+  #### A bit More About How it Works
 
   The `untangled/load` mutation does a very simple thing: It puts a state marker in a well-known location in your app state
   to indicate that you're wanting to load something (and returns `:remote true`). This causes the network

(ns untangled-tutorial.H-Server-Interactions
  (:require-macros [cljs.test :refer [is]])
  (:require [om.next :as om :refer-macros [defui]]
            [om.dom :as dom]
            [devcards.core :as dc :refer-macros [defcard defcard-doc]]))

; TODO: Explain Om's HATEOS (keyword listing in :keys)
; see: https://github.com/omcljs/om/wiki/Quick-Start-%28om.next%29

  lead to out-of-order execution, and impossible-to-reason-about recovery from errors).
  - You may provide fallbacks that indicate error-handling mutations to run on failures

  ## General Theory of Operation

  Untangled uses the primitives of Om Next, but one of the primary contributions it makes to that model is the
  realization that the following use-cases are by far the most common:

  - Reading data on initial app startup
  - Triggering loads on user-based events (or perhaps timeouts)

  In both cases, the implementation of the remoting in Om Next is very similar:

  - Write something into your application state database the indicates you want to do some remote operation
      - This triggers an internal parsing that you would normally have to interact with in order to decide
        what to ask the server.
      - Note that 'writing something to your app state' is a *mutation*.
  - Morph the UI query into something your server would rather see (you don't want to write server queries for
    every darn UI tree you can think of on the client side)
  - Morph the response *back into UI shape*, and normalize it. Note this is a data transform aided by Om primitives.

  So, the key realization is the *in practice Om reads requires some kind of **mutation** before a read can occur*! The
  additional realization is the after the read run, and you've normalized data into the database, you often *want* to
  morph the database into something special on your UI that the server need not understand.

  So, Untangled provides the 'triggering' mutations, and gives you a way to hook into the result so that you can
  do this post-transform when the remote read is complete.

  ## The `untangled/load` Mutation

  Untangled has a built-in mutation called `untangled/load`. This mutation *can* be used directly from `om/transact!` (and often is).

  The `load` mutation does the following basic things:

  - Places your query onto a built-in queue in your app state of things to load
  - The mutation is marked `remote`, so it will cause the networking side of Om to trigger.
  - The networking plumbing of Untangled looks in the queue when it sees a `load` mutation. It elides the `load` from the remote request itself, and
    instead sends the desired query/queries, then properly merges the results.
  - It may (optionally) place load markers in your app state so you can show in-progress indicators
  - It may (optionally) run post-mutation transforms on the database (if you supply them)

  The mutation can be used from application startup or anywhere you'd run a mutation (`transact!`). This covers almost
  all of the possible remote data integration needs!

  First, let's cover some helper functions that make using this mechanism a bit easier.

  ## Load helpers

  Untangled includes a few helper functions that can assist you in invoking the `untangled/load` mutation.

  1. `load-data` and `load-data-action`
  2. `load-field` and `load-field-action`

  The former of each pair are methods the directly invoke a `transact!` to place load requests into a load queue.

  The latter of each pair are low-level implementation method that can be used to *compose* remote reads with your
  own mutations (e.g. you want to switch to a new area of the UI (local mutation), but also trigger a *remote read* to load the
  content of that UI at the same time).

  ### Load Data vs. Load Field

