diff --git a/legion.cabal b/legion.cabal
--- a/legion.cabal
+++ b/legion.cabal
@@ -2,15 +2,15 @@
 -- documentation, see http://haskell.org/cabal/users-guide/
 
 name:                legion
-version:             0.4.0.0
+version:             0.5.0.0
 synopsis:            Distributed, stateful, homogeneous microservice framework.
 description:         Legion is a framework for writing distributed,
                      homogeneous, stateful microservices in Haskell.
-homepage:            https://github.com/taphu/legion
+homepage:            https://github.com/owensmurray/legion#readme
 license:             Apache-2.0
 license-file:        LICENSE
 author:              Rick Owens
-maintainer:          rick@owenssoftware.com
+maintainer:          rick@owensmurray.com
 copyright:           2015-2016 Rick Owens
 category:            Concurrency, Network
 stability:           experimental
@@ -20,7 +20,7 @@
 
 source-repository head
   type: git
-  location: git@github.com:taphu/legion.git
+  location: git@github.com:owensmurray/legion.git
 
 library
   exposed-modules:
diff --git a/src/Network/Legion.hs b/src/Network/Legion.hs
--- a/src/Network/Legion.hs
+++ b/src/Network/Legion.hs
@@ -194,9 +194,13 @@
 
 -- $startup
 -- While this section is being worked on, you can check out the
--- [legion-cache](https://github.com/taphu/legion-cache) project for a
--- working example of how to build a basic distributed key-value store
--- using Legion.
+-- [legion-discovery](https://github.com/owensmurray/legion-discovery)
+-- project for an example of a stateful web services that advantage of
+-- Legion's ability to define your own operations on your data. Take a look at
+-- [`Network.Legion.Discovery.App`](https://github.com/owensmurray/legion-discovery/blob/master/src/Network/Legion/Discovery/App.hs)
+-- to see where the magic of defining a Legion application happens. The rest
+-- of the code is mostly just standard HTTP-interface-written-in-Haskell,
+-- and requests sent to the Legion runtime.
 
 --------------------------------------------------------------------------------
 
diff --git a/src/Network/Legion/Application.hs b/src/Network/Legion/Application.hs
--- a/src/Network/Legion/Application.hs
+++ b/src/Network/Legion/Application.hs
@@ -51,7 +51,7 @@
 
       Given a request and a state, returns a response to the request.
     -}
-    handleRequest :: PartitionKey -> i -> s -> o,
+    handleRequest :: i -> s -> o,
 
     {- | The user-defined persistence layer implementation. -}
     persistence :: Persistence i s,
diff --git a/src/Network/Legion/Distribution.hs b/src/Network/Legion/Distribution.hs
--- a/src/Network/Legion/Distribution.hs
+++ b/src/Network/Legion/Distribution.hs
@@ -126,6 +126,12 @@
     _rebalance = error "rebalance undefined"
     rebuild =
       let
+        {- |
+          Figure out if there are any under-served partitions and also
+          figure out if this peer is the best candidate to service
+          them. "Under served" means that the partition isn't replicated
+          enough times, where "enough" is the magic number 3.
+        -}
         underserved = [
             (ks, ps)
             | (ks, ps) <- dist
@@ -137,7 +143,16 @@
         [] -> Nothing
         (ks, ps):_ ->
           let
+            {- |
+              Any peer that is not currently servicing the keyspace
+              segment is a candidate.
+            -}
             candidateHosts = toList (allPeers Set.\\ ps)
+
+            {- |
+              The best candidate is the one that currently has the
+              least load.
+            -}
             bestHosts = sort [(weightOf p, p) | p <- candidateHosts]
           in case bestHosts of
             {- we are the best host -}
diff --git a/src/Network/Legion/StateMachine.hs b/src/Network/Legion/StateMachine.hs
--- a/src/Network/Legion/StateMachine.hs
+++ b/src/Network/Legion/StateMachine.hs
@@ -181,7 +181,7 @@
     then do
       partition <- unSM $ getPartition key
       let
-        response = handleRequest key request (P.ask partition)
+        response = handleRequest request (P.ask partition)
         partition2 = P.delta request partition
       unSM $ savePartition key partition2
       return (Respond response)
@@ -325,7 +325,13 @@
   (lift . put) ns {
       cluster = case action of
         Nothing -> cluster
-        Just (Invite ks) -> C.claimParticipation self ks cluster
+        Just (Invite ks) ->
+          {-
+            This 'claimParticipation' will be enforced by the remote
+            peers, because those peers will see the change in distribution
+            and then perform a 'migrate'.
+          -}
+          C.claimParticipation self ks cluster
     }