docs(user): the module's README and the busctl escaping note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 30 insertions, 0 deletions

diff --git a/desktop/modules/user/README.md b/desktop/modules/user/README.md
new file mode 100644
index 0000000..7a09c07
--- /dev/null
+++ b/desktop/modules/user/README.md
@@ -0,0 +1,30 @@
+# user
+
+The drawer's greeting row (avatar, `Hello <login>`, real name) and the page
+it opens, which edits the user's details where other programs read them.
+
+| Field | Written to |
+| --- | --- |
+| name | AccountsService `RealName` (which also rewrites the passwd GECOS that LibreOffice prefills from), `~/.config/emaildefaults` `FullName`, git `user.name` with the surname as an initial |
+| email | AccountsService `Email`, emaildefaults `EmailAddress`, git `user.email` |
+| avatar | AccountsService `IconFile`; the daemon copies the file in and SDDM shows it |
+| language, location | AccountsService |
+| signing key | git `user.signingkey`; None unsets it |
+
+`userctl` does all reading and writing; the page only calls it. Polkit lets a
+user edit their own AccountsService entry without a prompt. A new detail is
+one entry in `UserPage.qml`'s `fields` and one `case` in `userctl`.
+
+When AccountsService cannot be read, `userctl get` prints one `error=`
+line instead of blank fields; the page shows it and disables Save. The
+signing key list skips revoked, expired and non-signing keys, and every
+write passes its value after `--`, so one starting with a dash is not
+taken for an option.
+
+Checks: `./test-userctl.sh` (stubs every store) and
+`node desktop/modules/user/test_user.js`.
+
+Not here: the password (`passwd` in a terminal; changing it also leaves the
+login keyring on the old one), `~/.face.icon` (SDDM reads the
+AccountsService icon), social links (nothing reads them). Values are read
+when the page opens, not watched.