feat(3201): swarmctl user update — change an existing subject's attributes

`user add` refuses on an existing name, so the `--group` flag it takes at
creation time could not be added afterwards at all: repairing an account
meant hand-editing both users.json and the rendered users.yml as root.
mara, on #3167: "i will not edit those files by hand, we will have the
same issues elsewhere".

The merge rules live in users.rs as a pure function over a UserUpdate, so
they are testable without a command line, a container or a running
authelia — main.rs's arm only loads, applies, publishes and prints.

Removals are strict and everything else is idempotent, which is the one
asymmetry here and is deliberate: a --remove-group naming a group the
user does not have fails, because a revocation that reports success
without revoking is the outcome nobody re-checks; while refusing an
already-satisfied set would make the multi-attribute call this verb
exists for break whenever one of the values was already right.

A command that changes nothing at all still fails — it would otherwise
rewrite both files and restart the SSO provider to no effect.

Passwords are out of scope: regenerating a credential is a different
intent from editing an attribute, and folded together an attribute edit
can invalidate a login by accident.

Extracts publish() from user_add so both verbs share the
render -> store -> users.yml -> restart ordering and the comment that
explains why that order, rather than the second verb copying it.

docs/swarm/sso.md

@@ -57,6 +57,37 @@ non-interactively means a secret arriving from somewhere — a file, an
 env var, a nix expression — and every one of those is worse than an
 operator typing one command once.
 
+### Changing a subject afterwards
+
+`user add` only ever adds: on a name that already exists it refuses,
+rather than resurfacing as a second account or a silent overwrite.
+Editing an existing subject is `user update`, and the flags compose, so
+one call can change several things:
+
+```console
+# swarmctl user update mara --add-group admins --email mara@example.com
+added to group "admins"
+email: unset -> "mara@example.com"
+mara is now in groups: admins
+```
+
+Two behaviours worth knowing before you rely on them:
+
+- **`--remove-group` fails if the user is not in that group.** Every
+  other flag is idempotent — setting what is already set is fine, so a
+  "make these four things true" call does not break when one of them
+  already was. Revocation is the exception on purpose: a typo'd group
+  name that reported success would leave an account holding access you
+  believe you took away, and that is the one outcome nobody re-checks.
+- **The resulting group list is printed** because group names have no
+  registry anywhere. A misspelled `--add-group` creates a real group that
+  no access-control rule mentions, so the user gains nothing and no error
+  is possible — reading the line back is the only check there is.
+
+Passwords are deliberately out of scope here: regenerating a credential
+is a different intent from editing an attribute, and folding them means
+an attribute edit can invalidate a login by accident.
+
 ## What secrets exist, and where each one lives
 
 | secret | generated by | rests in | read by |

docs/tools/swarmctl-cli.md

@@ -7,6 +7,7 @@ This document contains the help content for the `swarmctl` command-line program.
 * [`swarmctl`↴](#swarmctl)
 * [`swarmctl user`↴](#swarmctl-user)
 * [`swarmctl user add`↴](#swarmctl-user-add)
+* [`swarmctl user update`↴](#swarmctl-user-update)
 
 ## `swarmctl`
 
@@ -37,6 +38,7 @@ Manage subjects in the swarm's SSO provider
 ###### **Subcommands:**
 
 * `add` — Add a user, generating a password for them
+* `update` — Change an existing user's attributes
 
 
 
@@ -58,6 +60,27 @@ Add a user, generating a password for them
 
 
 
+## `swarmctl user update`
+
+Change an existing user's attributes.
+
+Every flag is optional and they compose, so one call can set several things at once. Deliberately does **not** touch the password: regenerating a credential is a different intent from editing an attribute, and folded together an attribute edit can invalidate a login by accident.
+
+**Usage:** `swarmctl user update [OPTIONS] <USERNAME>`
+
+###### **Arguments:**
+
+* `<USERNAME>` — Login name of an existing user
+
+###### **Options:**
+
+* `--display-name <TEXT>` — Name shown in the SSO UI
+* `--email <ADDRESS>`
+* `--add-group <GROUP>` — Repeatable. Adding a group the user is already in is not an error
+* `--remove-group <GROUP>` — Repeatable. Fails if the user is not in the group — a revocation that reports success without revoking is the failure nobody re-checks
+
+
+
 <hr/>
 
 <small><i>