docs: clarify subuid/subgid mapping in rootless vs userns-remap

content/manuals/engine/security/rootless/_index.md

@@ -20,14 +20,16 @@ with `userns-remap` mode, the daemon itself is running with root privileges,
 whereas in rootless mode, both the daemon and the container are running without
 root privileges.
 
+The two modes also differ in how they map container UIDs and GIDs to the
+host: see [UID/GID mapping](uid-gid-mapping/) for details.
+
 Rootless mode does not use binaries with `SETUID` bits or file capabilities,
 except `newuidmap` and `newgidmap`, which are needed to allow multiple
 UIDs/GIDs to be used in the user namespace.
 
-
 ## Prerequisites
 
--  You must install `newuidmap` and `newgidmap` on the host. These commands
+- You must install `newuidmap` and `newgidmap` on the host. These commands
   are provided by the `uidmap` package on most distributions.
 
 - `/etc/subuid` and `/etc/subgid` should contain at least 65,536 subordinate
@@ -53,13 +55,15 @@ when the prerequisites are not satisfied.
 > [!NOTE]
 >
 > If the system-wide Docker daemon is already running, consider disabling it:
->```console
->$ sudo systemctl disable --now docker.service docker.socket
->$ sudo rm /var/run/docker.sock
->```
+>
+> ```console
+> $ sudo systemctl disable --now docker.service docker.socket
+> $ sudo rm /var/run/docker.sock
+> ```
+>
 > Should you choose not to shut down the `docker` service and socket, you will need to use the `--force`
 > parameter in the next section. There are no known issues, but until you shutdown and disable you're
-> still running rootful Docker. 
+> still running rootful Docker.
 
 {{< tabs >}}
 {{< tab name="With packages (RPM/DEB)" >}}
@@ -128,6 +132,7 @@ The binaries will be installed at `~/bin`.
 {{< /tabs >}}
 
 Run `docker info` to confirm that the `docker` client is connecting to the Rootless daemon:
+
 ```console
 $ docker info
 Client: Docker Engine - Community
@@ -144,4 +149,4 @@ Server:
 ...
 ```
 
-See [Troubleshooting](./troubleshoot.md) if you faced an error.
+See [Troubleshooting](./troubleshoot.md) if you faced an error.

content/manuals/engine/security/rootless/uid-gid-mapping.md

@@ -0,0 +1,22 @@
+---
+description: How container UIDs and GIDs are mapped to the host in rootless mode
+keywords: security, namespaces, rootless, uid, gid, subuid, subgid
+title: UID/GID mapping
+weight: 15
+---
+
+Rootless mode and [`userns-remap` mode](../userns-remap.md) map container UIDs
+and GIDs to the host differently.
+
+- In `userns-remap` mode, container UID `0` is mapped to the first subordinate
+  UID listed in `/etc/subuid` for the remap user, and container UID `n` is
+  mapped to `subuid + n`.
+- In rootless mode, container UID `0` is mapped to the host UID of the user
+  running rootless Docker (the result of `id -u`); container UID `n` (for
+  `n >= 1`) is mapped to `subuid + (n - 1)`.
+
+GIDs follow the same rules using `/etc/subgid`.
+
+This difference matters when setting file permissions on bind-mounted
+directories: in rootless mode, files owned by your host user appear as owned
+by `root` inside the container.