docs: add user-management documentation

- CLI workflows for creating users and groups
- Troubleshooting guide (nscd, cache invalidation)
- Home directory behavior (UUID-based with symlinks)
- Update auth-system-replacement plan with progress

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

docs/user-management.md

@@ -21,61 +21,113 @@ kanidm login --name idm_admin --url https://auth.home.2rjus.net
 
 ## User Management
 
-### Creating Users
+POSIX users are managed imperatively via the `kanidm` CLI. This allows setting
+all attributes (including UNIX password) in one workflow.
 
-Users are provisioned declaratively in `services/kanidm/default.nix`:
-
-```nix
-services.kanidm.provision.persons.username = {
-  displayName = "Display Name";
-  groups = [ "admins" "users" "ssh-users" ];
-};
-```
-
-### Enabling POSIX for Users
-
-For PAM/NSS integration, users need POSIX attributes and a UNIX password:
+### Creating a POSIX User
 
 ```bash
-# Check if user has POSIX enabled
-kanidm person get <username>
+# Create the person
+kanidm person create <username> "<Display Name>"
 
-# Set UNIX password (required for SSH login)
+# Add to groups
+kanidm group add-members ssh-users <username>
+
+# Enable POSIX (UID is auto-assigned)
+kanidm person posix set <username>
+
+# Set UNIX password (required for SSH login, min 10 characters)
 kanidm person posix set-password <username>
+
+# Optionally set login shell
+kanidm person posix set <username> --shell /bin/zsh
+```
+
+### Example: Full User Creation
+
+```bash
+kanidm person create testuser "Test User"
+kanidm group add-members ssh-users testuser
+kanidm person posix set testuser
+kanidm person posix set-password testuser
+kanidm person get testuser
+```
+
+After creation, verify on a client host:
+```bash
+getent passwd testuser
+ssh testuser@testvm01.home.2rjus.net
+```
+
+### Viewing User Details
+
+```bash
+kanidm person get <username>
+```
+
+### Removing a User
+
+```bash
+kanidm person delete <username>
 ```
 
 ## Group Management
 
-### Creating Groups
+Groups for POSIX access are also managed via CLI.
 
-Groups are provisioned declaratively:
-
-```nix
-services.kanidm.provision.groups = {
-  admins = { };
-  users = { };
-  ssh-users = { };
-};
-```
-
-### Enabling POSIX for Groups
-
-Groups must have POSIX enabled to be resolved via NSS:
+### Creating a POSIX Group
 
 ```bash
-# Enable POSIX on a group with a specific GID
-kanidm group posix set <group-name> --gidnumber <gid>
+# Create the group
+kanidm group create <group-name>
 
-# Example: enable ssh-users group
-kanidm group posix set ssh-users --gidnumber 68000
+# Enable POSIX with a specific GID
+kanidm group posix set <group-name> --gidnumber <gid>
 ```
 
+### Adding Members
+
+```bash
+kanidm group add-members <group-name> <username>
+```
+
+### Viewing Group Details
+
+```bash
+kanidm group get <group-name>
+kanidm group list-members <group-name>
+```
+
+### Example: Full Group Creation
+
+```bash
+kanidm group create testgroup
+kanidm group posix set testgroup --gidnumber 68010
+kanidm group add-members testgroup testuser
+kanidm group get testgroup
+```
+
+After creation, verify on a client host:
+```bash
+getent group testgroup
+```
+
+### Current Groups
+
+| Group | GID | Purpose |
+|-------|-----|---------|
+| ssh-users | 68000 | SSH login access |
+| admins | 68001 | Administrative access |
+| users | 68002 | General users |
+
 ### UID/GID Allocation
 
+Kanidm auto-assigns UIDs/GIDs from its configured range. For manually assigned GIDs:
+
 | Range | Purpose |
 |-------|---------|
-| 65,536 - 67,999 | Users |
-| 68,000 - 69,999 | Groups |
+| 65,536+ | Users (auto-assigned) |
+| 68,000 - 68,999 | Groups (manually assigned) |
 
 ## PAM/NSS Client Configuration
 
@@ -89,6 +141,12 @@ This configures:
 - `services.kanidm.enablePam = true`
 - Client connection to auth.home.2rjus.net
 - Login authorization for `ssh-users` group
+- Short usernames (`torjus` instead of `torjus@home.2rjus.net`)
+- Home directory symlinks (`/home/torjus` → UUID-based directory)
+
+### Enabled Hosts
+
+- testvm01, testvm02, testvm03 (test tier)
 
 ### Options
 
@@ -100,6 +158,17 @@ homelab.kanidm = {
 };
 ```
 
+### Home Directories
+
+Home directories use UUID-based paths for stability (so renaming a user doesn't
+require moving their home directory). Symlinks provide convenient access:
+
+```
+/home/torjus -> /home/e4f4c56c-4aee-4c20-846f-90cb69807733
+```
+
+The symlinks are created by `kanidm-unixd-tasks` on first login.
+
 ## Testing
 
 ### Verify NSS Resolution
@@ -153,12 +222,46 @@ kanidm group posix set ssh-users --gidnumber 68000
    systemctl status kanidm-unixd
    ```
 
-2. Check client can reach server:
+2. Check unixd can reach server:
+   ```bash
+   kanidm-unix status
+   # Should show: system: online, Kanidm: online
+   ```
+
+3. Check client can reach server:
    ```bash
    curl -s https://auth.home.2rjus.net/status
    ```
 
-3. Check user has POSIX enabled on server:
+4. Check user has POSIX enabled on server:
    ```bash
    kanidm person get <username>
    ```
+
+5. Restart nscd to clear stale cache:
+   ```bash
+   systemctl restart nscd
+   ```
+
+6. Invalidate kanidm cache:
+   ```bash
+   kanidm-unix cache-invalidate
+   ```
+
+### Changes not taking effect after deployment
+
+NixOS uses nsncd (a Rust reimplementation of nscd) for NSS caching. After deploying
+kanidm-unixd config changes, you may need to restart both services:
+
+```bash
+systemctl restart kanidm-unixd
+systemctl restart nscd
+```
+
+### Test PAM authentication directly
+
+Use the kanidm-unix CLI to test PAM auth without SSH:
+
+```bash
+kanidm-unix auth-test --name <username>
+```