diff --git a/README.md b/README.md
new file mode 100644
index 0000000..50383d5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,12 @@
+# Promiscuity
+
+## Microservices
+- Auth Microservice Swagger: https://pauth.ranaze.com/swagger/index.html
+- Character Microservice Swagger: https://pchar.ranaze.com/swagger/index.html
+- Microservices README: microservices/README.md
+
+## Test users
+- `SUPER/SUPER` - Super User
+- `test1/test1` - Super User
+- `test3/test3` - User
+  
diff --git a/README.txt b/README.txt
deleted file mode 100644
index 8e7535c..0000000
--- a/README.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-Auth Microservice swagger is accessible at https://pauth.ranaze.com/swagger/index.html
-Character Microservice swagger is accessible at https://pchar.ranaze.com/swagger/index.html
-
-Test Users: 
-  SUPER/SUPER - Super User
-  test1/test1 - Super User
-  test3/test3 - User
-  
\ No newline at end of file
diff --git a/microservices/AuthApi/DOCUMENTS.md b/microservices/AuthApi/DOCUMENTS.md
new file mode 100644
index 0000000..7aa9a40
--- /dev/null
+++ b/microservices/AuthApi/DOCUMENTS.md
@@ -0,0 +1,49 @@
+# AuthApi document shapes
+
+This service expects JSON request bodies for its auth endpoints and stores user
+documents in MongoDB.
+
+Inbound JSON documents
+- RegisterRequest (`POST /api/auth/register`)
+  ```json
+  {
+    "username": "string",
+    "password": "string",
+    "email": "string (optional)"
+  }
+  ```
+- LoginRequest (`POST /api/auth/login`)
+  ```json
+  {
+    "username": "string",
+    "password": "string"
+  }
+  ```
+- RefreshRequest (`POST /api/auth/refresh`)
+  ```json
+  {
+    "username": "string",
+    "refreshToken": "string"
+  }
+  ```
+- ChangeRoleRequest (`POST /api/auth/role`)
+  ```json
+  {
+    "username": "string",
+    "newRole": "USER | SUPER"
+  }
+  ```
+
+Stored documents (MongoDB)
+- User
+  ```json
+  {
+    "id": "string (ObjectId)",
+    "username": "string",
+    "passwordHash": "string",
+    "role": "USER | SUPER",
+    "email": "string (optional)",
+    "refreshToken": "string (optional)",
+    "refreshTokenExpiry": "string (optional, ISO-8601 datetime)"
+  }
+  ```
diff --git a/microservices/AuthApi/README.md b/microservices/AuthApi/README.md
new file mode 100644
index 0000000..68cb79b
--- /dev/null
+++ b/microservices/AuthApi/README.md
@@ -0,0 +1,12 @@
+# AuthApi
+
+## Document shapes
+See `DOCUMENTS.md` for request payloads and stored document shapes.
+
+## Endpoints
+- `POST /api/auth/register` Register a new user.
+- `POST /api/auth/login` Issue access and refresh tokens.
+- `POST /api/auth/refresh` Refresh an access token.
+- `POST /api/auth/logout` Revoke the current access token.
+- `POST /api/auth/role` Update a user's role (SUPER only).
+- `GET /api/auth/users` List users (SUPER only).
diff --git a/microservices/CharacterApi/DOCUMENTS.md b/microservices/CharacterApi/DOCUMENTS.md
new file mode 100644
index 0000000..c75b3da
--- /dev/null
+++ b/microservices/CharacterApi/DOCUMENTS.md
@@ -0,0 +1,23 @@
+# CharacterApi document shapes
+
+This service expects JSON request bodies for character creation and stores
+character documents in MongoDB.
+
+Inbound JSON documents
+- CreateCharacterRequest (`POST /api/characters`)
+  ```json
+  {
+    "name": "string"
+  }
+  ```
+
+Stored documents (MongoDB)
+- Character
+  ```json
+  {
+    "id": "string (ObjectId)",
+    "ownerUserId": "string",
+    "name": "string",
+    "createdUtc": "string (ISO-8601 datetime)"
+  }
+  ```
diff --git a/microservices/CharacterApi/README.md b/microservices/CharacterApi/README.md
new file mode 100644
index 0000000..4c9db47
--- /dev/null
+++ b/microservices/CharacterApi/README.md
@@ -0,0 +1,9 @@
+# CharacterApi
+
+## Document shapes
+See `DOCUMENTS.md` for request payloads and stored document shapes.
+
+## Endpoints
+- `POST /api/characters` Create a character.
+- `GET /api/characters` List characters for the current user.
+- `DELETE /api/characters/{id}` Delete a character owned by the current user.
diff --git a/microservices/LocationsApi/DOCUMENTS.md b/microservices/LocationsApi/DOCUMENTS.md
new file mode 100644
index 0000000..d60c923
--- /dev/null
+++ b/microservices/LocationsApi/DOCUMENTS.md
@@ -0,0 +1,29 @@
+# LocationsApi document shapes
+
+This service expects JSON request bodies for location creation and updates and
+stores location documents in MongoDB.
+
+Inbound JSON documents
+- CreateLocationRequest (`POST /api/locations`)
+  ```json
+  {
+    "name": "string"
+  }
+  ```
+- UpdateLocationRequest (`PUT /api/locations/{id}`)
+  ```json
+  {
+    "name": "string"
+  }
+  ```
+
+Stored documents (MongoDB)
+- Location
+  ```json
+  {
+    "id": "string (ObjectId)",
+    "ownerUserId": "string",
+    "name": "string",
+    "createdUtc": "string (ISO-8601 datetime)"
+  }
+  ```
diff --git a/microservices/LocationsApi/README.md b/microservices/LocationsApi/README.md
new file mode 100644
index 0000000..a5d759b
--- /dev/null
+++ b/microservices/LocationsApi/README.md
@@ -0,0 +1,10 @@
+# LocationsApi
+
+## Document shapes
+See `DOCUMENTS.md` for request payloads and stored document shapes.
+
+## Endpoints
+- `POST /api/locations` Create a location (SUPER only).
+- `GET /api/locations` List locations for the current user.
+- `DELETE /api/locations/{id}` Delete a location (SUPER only).
+- `PUT /api/locations/{id}` Update a location name (SUPER only).
diff --git a/microservices/README.md b/microservices/README.md
index d15458a..f849d14 100644
--- a/microservices/README.md
+++ b/microservices/README.md
@@ -1,2 +1,12 @@
-# micro-services
+# micro-services
+
+## Document shapes
+- AuthApi: `AuthApi/DOCUMENTS.md` (auth request payloads and user document shape)
+- CharacterApi: `CharacterApi/DOCUMENTS.md` (character create payload and stored document)
+- LocationsApi: `LocationsApi/DOCUMENTS.md` (location create/update payloads and stored document)
+
+## Service READMEs
+- AuthApi: `AuthApi/README.md`
+- CharacterApi: `CharacterApi/README.md`
+- LocationsApi: `LocationsApi/README.md`