added to docs, diagram

Gemfile

@@ -16,3 +16,4 @@ gem 'adsf'
 gem 'builder'
 gem 'tent-schemas', :git => 'git://github.com/tent/tent-schemas.git', :branch => 'master'
 gem 'pygments.rb', :git => 'git://github.com/akzhan/pygments.rb.git', :branch => 'rubypython-0.6'
+gem 'fssm', :groups => :development

Gemfile.lock

@@ -27,6 +27,7 @@ GEM
     cri (2.3.0)
       colored (>= 1.2)
     ffi (1.0.11)
+    fssm (0.2.9)
     json-schema (1.0.9)
     mime-types (1.19)
     nanoc (3.4.0)
@@ -56,6 +57,7 @@ DEPENDENCIES
   adsf
   builder
   clogger
+  fssm
   mime-types
   nanoc
   nanoc-cachebuster

content/docs/app-auth.md

@@ -5,17 +5,16 @@ title: App Authentication
 ## App Authentication
 
 Tent uses [OAuth 2](http://tools.ietf.org/html/draft-ietf-oauth-v2-31) for app
-authentication. Because of the distributed nature of Tent, it is necessary for
+authentication. Because of the distributed nature of Tent,
-apps to register with the Tent entity before doing the authentication flow.
+apps must register with the Tent entity before starting the authentication flow.
 
-After the authentication flow, requests are authenticated using the credentials
+After the authentication flow is complete, requests are authenticated using the credentials
 with [MAC Access
 Authentication](http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01).
 
 
 ### App Registration
 
-
 Before authenticating a user, the application must be registered with the
 specified Tent entity. The first step is to perform discovery on the provided
 entity url.

content/docs/index.md

@@ -1,14 +1,6 @@
 ---
 title: Protocol Introduction
 ---
-
-## The Tent Protocol
-
-Tent is a protocol for decentralized social networking. It allows you to control your data, who has access to it, and what can be done with it. 
-
-Anyone can run a Tent server or write a Tent app. There are Tent hosts for users who do not want to manage a server. 
-
-
 ### API Overview
 
 Tent is a social layer over HTTP using [JSON](http://en.wikipedia.org/wiki/JSON).
@@ -30,8 +22,8 @@ a Tent profile (e.g. `https://tent.johnsmith.me/profile`)
 
 ### Servers
 
-Tent servers are the protocol core. They represent the users and maintain their data and relationships. Servers also handle these responsibilities:
+Tent **servers** are the protocol core. They represent the users and maintain their data and relationships. Servers also handle these responsibilities:
-
+ 
 - Persisting data
 - Notifying other servers about new data
 - Ensuring content is only pushed to recipients accepting associated licences
@@ -40,40 +32,60 @@ Tent servers are the protocol core. They represent the users and maintain their
 - Authorizing apps to access data
 - Notifying apps about new or modified data to which they have access
 
-tentd is the current reference Tent server.
+[tentd](https://github.com/tent/tentd) is the current reference Tent server.
 
 ### Apps
 
-Users create and view content on apps. Apps must authenticate with the user's server before content can be posted or viewed.
+Users create and view **posts** and **profiles** on **apps**. Apps must authenticate with the user's server before content can be posted or viewed.
 
-For example:
+The Process:
 
-1. ian-hanson.me (Ian) posts a status update (post) from a micro blogging app authenticated with his server.
+1. User A creates a `status` post on her app.
-2. The app publishes the post to his server.
+2. App sends posts to user A's server.
-3. His server sends a notification to every server following him or mentioned in the post with permission to see the post.
+3. User A's Server sends post notifications to all users who follow User A's `status` posts and users mentioned in this post. The server will not send notifications to users not allowed in the post's permissions.
-4. If anna-collins.me (Anna) is following Ian, her server will receive a notification from Ian’s server containing the post.
+4. The servers operated by user A's followers each receive this notification.
-5. If Anna has an app setup for consuming status updates, her server will send it a notification with Ian’s post.
+5. These servers each send the post to the appropriate app(s).
-6. Anna can now read Ian’s post from the status app.
+6. The following users can view the post on their apps.
-7. If Anna decides to reply, her response will follow a path inverse to Ian’s post.
 
 TentStatus is an open source Tent app for creating and viewing status posts.
 
 ### Posts
 
-Posts are at the core of Tent. They are sent to followers immediately after being created. Users set permissions on each post that determine which other users can access them. Other users can fetch public posts individually or over a date range. Posts each have a post type which describes its data. Tent posts can be used to describe anything, and developers can create new post types for different kinds of media, interactions, or applications. This documentation describes four basic post types: **status**, short messages of 140 characters or less, **essay**, longer form writing, **photo**, pictures, and **album**, a collection of **photo** posts. 
+**Posts** are at the core of Tent. Posts are sent to followers immediately after being created. 
+
+Users set permissions on each post that determine which other users can access them. Other users can fetch public posts individually or over a date range. 
+
+Post types describe the format and content of each post. Tent posts can be used for almost anything, and developers can create new post types for different kinds of media, interactions, or applications. 
+
+This documentation describes four basic post types: `status`, short messages of 140 characters or less, `essay`, longer form writing, `photo`, pictures, and `album`, a collection of `photo` posts. 
 
 ### Profiles
 
-Every Tent entity's server has a profile JSON file describing it. They store information about the user, specifically static information that should always be accessible.
+Every Tent entity's server has a **profile** JSON file describing it. Profiles store information about the user, specifically static information that should always be accessible.
 
-The most basic profile
+The most basic profile has a single object containing the Tent version, the entity name (e.g.
-has a single object containing the Tent version, the entity name (e.g.
 johnsmith.me), an array of supported licences, and an array of servers
 containing canonical API roots.
 
-A user may have multiple versions of the same info type in your profile.
+A user may have multiple versions of the same info type in their profile.
 
 ### Notifications
 
-Tent notifications are used when a server needs to let another server or app
+Tent **notifications** are used when a server needs to let another server or app
-know about new content updates. This includes new posts and profile changes. Notifications are JSON POST requests containing posts.
+know about new content updates. This includes new posts and profile changes. Notifications are JSON POST requests containing posts. A new notification is sent for event (post, following event, profile change).
+
+### Example
+
+https://cloudmir.com/ (Lindsay) and https://titanous.com (Jonathan) are both following https://daniel.tent.is (Daniel) and have requested all his status posts. 
+
+2. https://daniel.tent.is creates a `status` post on TentStatus in which he mentions another user, https://jesse.tent.is (Jesse). 
+
+3. TentStatus sends this post to Daniel's server.
+
+4. Daniel's server sends post notifications to Lindsay and Jonathan, because they follow Daniel and requested all `status` posts he creates, and Jesse, because the post mentions him.
+
+5. Lindsay, Jonathan, and Jesse's servers receive the post and send a copy of the post to TentStatus, the application they each have configures to read `status` posts.
+
+6. Lindsay, Jonathan, and Jesse can each read, reply to, repost, or ignore the post as they wish.
+
+![diagram](/assets/images/diagram.png)

content/docs/server-protocol.md

@@ -3,7 +3,7 @@
 This document describes the protocol that Tent servers use to communicate with
 each other.
 
-###Basics
+### Basics
 
 Every Tent user is represented by a server. Servers establish and maintain relationships and exchange content between users. 
 
@@ -28,7 +28,10 @@ Link: <https://tent.titanous.com/profile>; rel="https://tent.io/rels/profile"
 ```
 or
 ```text
-Link: <https://tent.titanous.com/profile>; rel="https://tent.io/rels/profile", <https://titanous.tent.is/profile>; rel="https://tent.io/rels/profile", <https://tent.jonathan.cloudmir.com/profile>; rel="https://tent.io/rels/profile"
+Link: <https://tent.titanous.com/profile>; rel="https://tent.io/rels/profile", 
+<https://titanous.tent.is/profile>; rel="https://tent.io/rels/profile", 
+
+<https://tent.jonathan.cloudmir.com/profile>; rel="https://tent.io/rels/profile"
 ```
 
 #### HTML `link` tag

layouts/doc.slim

@@ -16,6 +16,8 @@ html lang='en'
             li == nav_link_with_active 'Post Types', '/docs/post-types'
             li == nav_link_with_active 'Profile Info Types', '/docs/info-types'
         .span8
+          .lead
+            p Tent is a protocol for decentralized social networking.
           .alert.alert-block
             h4 Alpha Documentation 
             p These docs are very rough, incorrect, and incomplete. They will be modified heavily over the next few weeks.