From a4a750b35c2efb01cfd5f80600f4a35759d54f8f Mon Sep 17 00:00:00 2001
From: Andy Burke <andy.burke@mailbox.earth>
Date: Tue, 24 Jun 2025 16:25:07 -0700
Subject: [PATCH] docs: improve some READMEs

---
 public/api/auth/README.md      |  3 +--
 public/api/users/:id/README.md | 21 +++++++++++++++++++++
 public/api/users/README.md     | 27 +++++++++++++++++++++++++++
 3 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 public/api/users/:id/README.md
 create mode 100644 public/api/users/README.md

diff --git a/public/api/auth/README.md b/public/api/auth/README.md
index 0aea2b1..8b980dc 100644
--- a/public/api/auth/README.md
+++ b/public/api/auth/README.md
@@ -8,8 +8,7 @@ Log into the service.
 
 ```
 {
-	email?: string; // either email or username must be specified
-	username?: string;
+	username: string;
 	password_hash: string; //should be a base64-encoded SHA-256 hash of the user's client-entered pw
 	totp?: string; // TOTP if configured on account
 }
diff --git a/public/api/users/:id/README.md b/public/api/users/:id/README.md
new file mode 100644
index 0000000..c1c6c4e
--- /dev/null
+++ b/public/api/users/:id/README.md
@@ -0,0 +1,21 @@
+# /api/users/:id
+
+Interact with a specific user.
+
+## GET /api/users/:id
+
+Get the user specified by `:id`. (user match/admin)
+
+## PUT /api/users/:id
+
+Update the user specified by `:id`. (user match/admin)
+
+```
+{
+	username?: string; // update username
+}
+```
+
+## DELETE /api/users/:id
+
+Delete the user specified by `:id`. (user match/admin)
diff --git a/public/api/users/README.md b/public/api/users/README.md
new file mode 100644
index 0000000..f78c604
--- /dev/null
+++ b/public/api/users/README.md
@@ -0,0 +1,27 @@
+# /api/users
+
+Interact with users.
+
+## POST /api/users
+
+Create a new user.
+
+```
+{
+	// set the user's username
+	username: string;
+
+	// set the user's password, will be hashed and discarded server-side
+	password?: string;
+
+	// can send an already-hashed password if we want to keep this client-side
+	// should be a base64-encoded SHA-256 hash of the user's client-entered pw
+	password_hash?: string;
+}
+```
+
+## GET /api/users
+
+Get users. (admin)
+
+TODO: document this