From 39b0ab03fe0cbfff892cc8adb4a134b18885a8f0 Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Mon, 2 Nov 2026 14:13:11 -0500
Subject: [PATCH] =?UTF-8?q?docs(admin):=20users=20page=20=E2=80=94=20accou?=
 =?UTF-8?q?nts,=20roles,=20last-admin=20guards?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Eighth admin page. Documents the hidden-by-default create form (and why:
admin creation stays available with registration disabled — the form's
own design comment), live password requirements from active settings,
the card controls with their guards (last admin cannot be demoted or
deleted, dropdowns/buttons disable themselves with explanations), the
admin Edit User Profile modal (profile fields + role + Change Password
without current password — the admin-only difference), and delete
semantics (account + everything owned: devices, sessions, reading
data). Closes the loop on roles: admins get the Administration section;
users see only libraries visible to them, linking libraries.md for the
visibility story. Glossary gains + Create User and Edit User Profile.
(Settings referenced in prose only until that page lands — the first
amend of this commit briefly carried the same forward-link mistake the
dashboard page's amend fixed; pipefail is now the rule.)
---
 docs/admin/users.md           | 65 +++++++++++++++++++++++++++++++++++
 docs/developer/ui-controls.md |  8 +++++
 2 files changed, 73 insertions(+)
 create mode 100644 docs/admin/users.md

diff --git a/docs/admin/users.md b/docs/admin/users.md
new file mode 100644
index 00000000..2a1a9910
--- /dev/null
+++ b/docs/admin/users.md
@@ -0,0 +1,65 @@
+<!-- Ground truth: templates/admin_users.templ (create form, user cards,
+     last-admin guards), templates/profile_form.templ + profile_modal.templ
+     (admin edit fields), internal/router/auth.go (admin user endpoints),
+     internal/router/frontend.go (profile-modal route), user delete cascade
+     (reading data is owned by the account and goes with it). Re-verify
+     against these when the page changes. -->
+
+# Users
+
+User Management is where accounts are created, roles are assigned, and
+accounts are removed. Changes here are immediate — there is no approval
+flow.
+
+## Creating an account
+
+**+ Create User** opens the creation form (it stays hidden until clicked,
+so the page doesn't shout account creation at you — and so admins can
+still create accounts even when public self-registration is switched off
+on the Settings page).
+
+Fields: **Username** (3–50 characters), **Email**, **Password** plus a
+confirm, optional **First name** / **Last name**, and a **Role** of User
+or Admin. The **Password Requirements** list is generated from the
+password rules currently configured in Settings — the same rules users
+face when changing their own passwords — and the **Create User** button
+stays disabled until everything validates.
+
+## The user cards
+
+Every account renders as a card: username (with a **You** badge on your
+own), email, the creation date shown in your timezone, and the controls:
+
+### Role
+
+A dropdown — **User** or **Admin** — that applies the moment you change
+it. One guard exists: the **last admin cannot be demoted** (the dropdown
+disables itself with that explanation while only one admin exists).
+
+Admins see and use the entire Administration section — libraries,
+scans, settings, this page.
+
+### Edit
+
+Opens an **Edit User Profile** modal with the same fields the user
+controls on their own profile — username, email, first/last name,
+**Theme**, **Default Playback Speed**, **Resume Rewind** — plus the Role
+dropdown, and a **Change Password** section. The admin version doesn't
+ask for the user's current password (only the user's own profile does).
+
+### Delete
+
+Removes the account permanently — and with it everything the account
+owns: devices, sessions, and reading data (progress, annotations,
+collections). The confirm dialog makes the irreversibility explicit.
+Same last-admin guard as the role dropdown: the final admin cannot be
+deleted.
+
+## Roles, briefly
+
+- **User** — browses, reads, listens, syncs devices; sees only the
+  libraries visible to them (visibility is set per-library on the
+  [Libraries](libraries.md) page).
+- **Admin** — everything a user has, plus the Administration section:
+  libraries and scanning, users, system settings, hash conflicts,
+  podcasts maintenance.
diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md
index 3c91f5fc..52a71426 100644
--- a/docs/developer/ui-controls.md
+++ b/docs/developer/ui-controls.md
@@ -300,6 +300,14 @@ label: Remove
 where: Admin → All Podcasts → a feed row
 does: Admin-wide feed removal — episode rows, downloaded files, and every user's subscription are deleted. Instance-wide, unlike a user's own unsubscribe.
 
+label: + Create User
+where: Admin → Users → page header
+does: Opens the account-creation form (hidden until clicked). Available even when public registration is disabled; password rules mirror the live Settings.
+
+label: Edit User Profile
+where: Admin → Users → a user card → Edit
+does: The admin edit modal — profile fields, role, and Change Password without requiring the user's current password.
+
 label: Resume rewind
 where: audio player → player settings; profile settings
 does: Rewinds playback a configured few seconds when you resume.