Add more about posts and follow auth.

Gemfile.lock

@@ -8,7 +8,7 @@ GIT
 
 GIT
   remote: git://github.com/tent/tent-schemas.git
-  revision: 634fc909d1b33f5fb55a391b026334f4d9eaba30
+  revision: ac4cba68209d74267dd2d2c5b36768d8a2919c7b
   branch: master
   specs:
     tent-schemas (0.0.1)

content/docs/app-server.md

@@ -95,6 +95,6 @@ Apps can create a new post with an attachment and send both to the server. Files
 
 #### GET /posts/:post_id/attachments/:name
 
-Apps can retrieve attachments from a specific post by name from the server.
+Apps can retrieve attachments from a specific post by name and content-type from the server.
 
 {get_post_attachment example}

content/docs/post-types.md

@@ -1,10 +1,41 @@
 ---
-title: Post Types
+title: Posts
 ---
 
-## Post Types
+## Posts
 
-### Status
+Posts are the core of Tent. A post consists of these fields:
+
+{post schema}
+
+### Mentions
+
+Mentions mark a post as mentioning one or more entities and posts. A `mentions`
+array looks like this:
+
+```json
+[
+  {
+    "entity": "https://daniel.tent.is"
+  },
+  {
+    "entity": "https://jonathan.tent.is",
+    "post": "aa123b3"
+  }
+]
+```
+
+Each mention must have an entity and can also specify an optional post
+identifier, which allows replying to posts.
+
+
+### Types
+
+The post type describes the schema and semantics of the `content` object. Types
+are referenced by a url, the last part of the url must be the version of the
+type (ex: `/v0.1.0`).
+
+#### Status
 
 `https://tent.io/types/post/status/v0.1.0`
 
@@ -14,7 +45,7 @@ title: Post Types
 {post_status schema}
 
 
-### Essay
+#### Essay
 
 `https://tent.io/types/post/essay/v0.1.0`
 
@@ -23,7 +54,7 @@ title: Post Types
 
 {post_essay schema}
 
-### Photo
+#### Photo
 
 `https://tent.io/types/post/photo/v0.1.0`
 
@@ -32,7 +63,7 @@ title: Post Types
 {post_photo schema}
 
 
-### Album
+#### Album
 
 `https://tent.io/types/post/album/v0.1.0`
 
@@ -41,7 +72,7 @@ An **album** is a collection of `photo`s. Albums may optionally list a cover pho
 {post_album schema}
 
 
-### Repost
+#### Repost
 
 `https://tent.io/types/post/repost/v0.1.0`
 
@@ -50,7 +81,7 @@ A **repost** is a post that points to a post created by another entity.
 {post_repost schema}
 
 
-### Profile
+#### Profile
 
 `https://tent.io/types/post/profile/v0.1.0`
 
@@ -60,7 +91,7 @@ profile.
 {post_profile schema}
 
 
-### Delete
+#### Delete
 
 `https://tent.io/types/post/delete/v0.1.0`
 
@@ -70,12 +101,12 @@ profile.
 
 
 
-## Creating New Post Types
+### Creating New Post Types
 
 Tent highly extensible and allows developers to create new post types to support new kinds of media, interactions, and functionality.
 
-### Guidelines
-#### Do
+#### Guidelines
+##### Do
 
  - **Use snake case for JSON key names.**
  - **Use existing types when possible.** Consider whether a new type is really necessary. Would an existing type work? Contact the maintainer of the type to suggest changes for a future version. Type-creep makes everyone's lives worse. Avoid proliferation.
@@ -86,9 +117,9 @@ Tent highly extensible and allows developers to create new post types to support
  - **Keep it simple.** Users and developers alike benefit from a small set of simple post types. With a small number of types, users can find apps that suit their specific needs and know their data is portable. Developers can build interoperable, compliant apps without reinventing the wheel. Avoid NIH (Not Invented Here) Syndrome and the desire to start from scratch.
  - **Publish your type.** If you have created a new type, publish it to a popular Tent community site (like this one) so other developers can add support for it into their apps.
  
-#### Do Not
+##### Do Not
 
- - **Create duplicate post types** Multiple post types with the same purpose will create a fragmented ecosystem. Tent was designed to avoid this problem
+ - **Create duplicate post types** Multiple post types with the same purpose will create a fragmented ecosystem. Tent was designed to avoid this problem.
  - **Create proprietary post types** Users and other developers expect to be able to view posts in different applications. Limiting which apps can use a post type is against the spirit of Tent.
  - **Create post types with identical names.** Names should disambiguate post types, not confuse them. Choose a different name for your type when possible.
  - **Use deeply nested data structures.** They make querying difficult.

content/docs/server-protocol.md

@@ -46,7 +46,22 @@ with the Tent entity.
 
 ### Follow an entity
 
-To follow a user, send a POST request with acceptable licenses, post types, and views. Accepted requests will respond 200 OK and provide authentication credentials
+To follow a user, send a POST request with acceptable licenses, post types, and
+views, and a path to send post notifications to.
+
+To verify the following, the server will first perform discovery on the
+`entity`, then send a GET request to the `notification_path` with a `challenge`
+parameter that must be returned as the response to the request with a 200 status
+code. Subsequent signed GET requests to the notification path with a challenge
+must return the challenge as the response body with a 200 in order to verify
+that the follow is still active.
+
+Accepted follow requests will respond 200 OK and provide authentication
+credentials.
+
+All post notifications will be POSTed to the notification path and signed with
+the credentials.
+
 ### POST /followers
 
 {create_follower example}
@@ -109,9 +124,3 @@ There are a number of parameters available to limit the scope of the request.
 It is also possible to retrieve a single post by that post's id. This is useful in retrieving reposted content and 
 
 {follower_get_post example}
-
-
-## Notifications
-
-New content is sent as a POST request to `/posts` and
-authenticated using the negotiated credentials.