should have commited more often oops

docs/APIs/Server-Client API/index.md

@@ -0,0 +1,12 @@
+# Server-Client API
+
+The following pages document the server-client API of polyproto. Each file represents a group of 
+routes, organizing them by their purpose.
+
+---
+
+--8<-- "snippets/api.md"
+
+---
+
+--8<-- "snippets/glossary.md"

docs/Server-Client API/federation.md → docs/APIs/Server-Client API/routes/federation.md

@@ -4,20 +4,22 @@
 
 Routes concerning the creation, deletion and management of federation tokens.
 
-### <p class="request-h"><span class="request request-get">GET</span> Generate Federation Token</p>
+---
+
+### <p class="request-h"><span class="request request-get">GET</span> Generate Federation Token [:material-pail-outline:](../../rate-limits.md "Bucket: federation-token-generation") [:material-lock-outline:](#authorization "Authorization required") </p> 
 
 `http://localhost:3001/api/federation/token`
 
-Ask your home server to generate a federation token for you. You can use this token to authenticate on another server.
+Ask your home server to generate a federation token for you. You can use this token to identify yourself on another server.
 
-The token is signed using the home server's public signing key, so that other servers can verify its authenticity.
+Federation tokens are signed using the home server's public signing key, so that other servers can verify its authenticity.
 
 #### Body
 
 ```json
 {
     "server": "https://server.example.com"
-}
+
 ```
 
 #### Response
@@ -41,7 +43,9 @@ The token is signed using the home server's public signing key, so that other se
     }
     ```
 
-### <p class="request-h"><span class="request request-get">GET</span> Get token generation status</p>
+---
+
+### <p class="request-h"><span class="request request-get">GET</span> Get token generation status [:material-pail-outline:](../../rate-limits.md "Bucket: ip") [:material-lock-open-outline:](#authorization "Authorization not required")</p>
 
 `http://localhost:3001/api/federation/generation`
 

docs/APIs/errors.md

@@ -0,0 +1 @@
+# Errors

docs/APIs/rate-limits.md

@@ -0,0 +1 @@
+# Rate limits

docs/index.md

@@ -1,5 +1,23 @@
-# Start
+---
+title: Home
+---
 
-## polyproto
+
+# polyproto
 
 Advanced, secure and scalable protocol for federated chat services.
+
+The core of the protocol lies in the [protocol specification](./specification.md) and in the federation
+API routes, which are used to negotiate and establish connections between foreign servers and
+clients. 
+
+Theoretically, the polyproto-core federation protocol can be used with a different set of chat-APIs 
+However, a full implementation of the protocol requires the use of the
+polyproto-chat routes. 
+
+!!! info
+    polyproto provides no chat-interoperability if you do not use the polyproto-chat API.
+
+---
+
+--8<-- "snippets/glossary.md"

docs/specification.md

@@ -1,3 +1,8 @@
-<!--Do not remove the #-->
-#
---8<-- "SPECIFICATION.md"
+---
+title: Protocol Specification
+---
+
+
+--8<-- "SPECIFICATION.md"
+
+--8<-- "snippets/glossary.md"

snippets/glossary.md

@@ -1,5 +1,8 @@
 ## Glossary
 
-- **polyproto-core** - The core federation protocol and APIs of polyproto. It is used to establish connections between servers and clients. It is independent of the chat-API used.
+- **polyproto-core** - The core federation protocol and APIs of polyproto, enabling identification and authorization on 'foreign' servers. It is independent of the chat-API used.
 - **polyproto-chat** - The chat-API used by polyproto. It defines the routes and capabilities of the chat-API used by polyproto.
-- **polyproto** - The combination of the polyproto-core and polyproto-chat protocols and APIs.
+- **polyproto** - The combination of the polyproto-core and polyproto-chat protocols and APIs.
+- **Home server** - The server that a user is registered on.
+- **User** - An individual person that is registered on a server.
+- **Client** - A device that is used by a user to connect to a server.