Add documentation for permissions, notifications

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}
 
 

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