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

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

3 files changed, 37 insertions, 2 deletions

diff --git a/AGENTS.md b/AGENTS.md
index fcdd1e9..bd2b80c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,8 +11,8 @@ stay separate shells, each complete on its own: any of them runs alone, and
 running one does not require the others. `desktop/` is itself a host for
 modules.
 
-    desktop/          the drawer (SUPER alone): sound, mail, VMs, status, performance,
-                      clipboard, updates, appearance
+    desktop/          the drawer (SUPER alone): user details, sound, mail, VMs, status,
+                      performance, clipboard, updates, appearance
       island/         top-centre pills on DP-1: clock, volume, tray, layout, privacy,
                       calendar
     appearance/       wallpaper picker and colour scheme switcher
@@ -342,6 +342,10 @@ changing that component. The ones that generalise:
   GPU. Pass `autoload=false`, which answers 400 `model is not loaded` instead.
   Checking `/models` for `loaded` first is not enough on its own, because the
   model can unload between the two requests.
+- **`busctl get-property` escapes non-ASCII as octal.** A name with an
+  accented letter reads `s "Do\303\250r"`-style, which no shell builtin
+  decodes. `busctl --json=short` returns real UTF-8; `userctl` pipes it
+  through `jq -r .data`.
 
 ## Theme
 
diff --git a/desktop/README.md b/desktop/README.md
index be22c48..d10769d 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -34,6 +34,7 @@ the IPC layer rejects. The page-less grid entry is therefore the zero-argument
     modules/appearance/  a tile that opens the separate appearance shell
     modules/ai/          local AI engines, start/stop for the apps using them
     modules/perf/        CPU, temperatures, GPU, network, disks, ~/.cache
+    modules/user/        the greeting row and the user's details page
     modules/clipboard/   cliphist history: search, copy, delete, clear all
 
 Sound, mail, vm, network, bluetooth, kdeconnect and ai each carry their own README.
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.