From 552d9a41dfa8f42d120449a84fe977777806f5db Mon Sep 17 00:00:00 2001
From: Jonathan Rudenberg <jonathan@titanous.com>
Date: Sun, 7 Oct 2012 13:40:38 -0400
Subject: [PATCH] Add documentation for permissions, notifications

---
 content/docs/post-types.md      | 26 ++++++++++++++++++++++++++
 content/docs/server-protocol.md | 20 ++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/content/docs/post-types.md b/content/docs/post-types.md
index 9267748..a1dd024 100644
--- a/content/docs/post-types.md
+++ b/content/docs/post-types.md
@@ -29,6 +29,29 @@ Each mention must have an entity and can also specify an optional post
 identifier, which allows replying to posts.
 
 
+### Permissions
+
+Tent posts are not always public. The creator of a post can set permissions
+limiting which entities have access. Possible permissions include completely
+public, completely private, shared with one other user, and shared with a group
+of other users.
+
+```json
+{
+  "public": false,
+  "groups": [
+    {
+        "id": "23lkbn7"
+    }
+  ],
+  "entities": {
+    "https://jonathan.tent.is": true,
+    "https://daniel.tent.is": true
+  }
+}
+```
+
+
 ### Types
 
 The post type describes the schema and semantics of the `content` object. Types
@@ -78,6 +101,9 @@ An **album** is a collection of `photo`s. Albums may optionally list a cover pho
 
 A **repost** is a post that points to a post created by another entity.
 
+The repost should also include a mention of the original post so that the
+publisher can see who is reposting her content.
+
 {post_repost schema}
 
 
diff --git a/content/docs/server-protocol.md b/content/docs/server-protocol.md
index bb1f5d9..137429f 100644
--- a/content/docs/server-protocol.md
+++ b/content/docs/server-protocol.md
@@ -81,6 +81,26 @@ the credentials.
 {create_follower example}
 
 
+## Notifications
+
+Tent entities communicate with each other using notifications. Notifications are
+sent out when a new post is created. New post notifications are sent out to all
+entities who subscribed to the post type before the post was published and have
+permission to see it. They are also sent to any entities who are mentioned in
+the post.
+
+If the entity being notified is following the publishing entity, the
+notification will be sent to the `notification_path` that was configured when
+the following was created and signed with the exchanged credentials.
+
+If the entity being notified is not following the publishing entity, the
+notification will be sent to `/posts`. The notification will be signed if the
+publishing entity is following the notification recipient.
+
+A notification is a `POST` request with a body that contains a post in JSON
+format.
+
+
 ## Authentication