Finish documenting big picture

1 files changed, 34 insertions, 0 deletions

diff --git a/docs/04-big-picture-behaviour.md b/docs/04-big-picture-behaviour.md
index 17513c4..f655eb9 100644
--- a/docs/04-big-picture-behaviour.md
+++ b/docs/04-big-picture-behaviour.md
@@ -1,3 +1,37 @@
 [[back to main docs]](../README.md#documentation-map)
 
 # Big-Picture Behaviour
+
+This document describes the general behaviour of the `IRC::Client` clients.
+
+## Connection Maintenance
+
+The client is designed with the goal of being run indefinitely. As such, it
+will restart server connections if they close.
+
+If a connection fails or a disconnect happens, the client will wait
+10 seconds (non-blockingly) and attempt to reconnect, repeating the process
+if the reconnect fails too. This loop will continue indefinitely until either
+the connection is established or the client explicitly quits the server
+using the `.quit` method on the Client Object.
+
+The described process applies to individual servers, regardless of how many
+servers the client is asked to connect to. Thus, it's possible that one
+server will be in the reconnect loop, while others will be connected and
+functioning like normal. It's also possible for the user to `.quit` some
+servers, while maintaining connection to others. The client object's
+`.run` method will return only when *all* servers have been `.quit`
+
+## Nickname Maintenance
+
+If the first nickname assigned to the bot at the start (or one set
+using `.nick` method) is in use, the bot will automatically use the next one
+in the list. If *all* of the nicks are in use, it will wait a short period
+of time, before retrying all nicks again.
+
+Note: the same system will be applied if the proposed nick is an erroneous
+one that cannot be used on the server—for example, it can contain invalid
+characters or be too long. This means the bot will never succeed
+in connecting to the server or changing a nick if the entire list of nicks it
+possesses are invalid ones. Be sure to turn the debug output on and inspect
+output for any suspect messages if you're having issues connecting.