Document the --volume three-part form and mount option behavior

Sources/Services/ContainerAPIService/Client/Flags.swift

@@ -344,7 +344,11 @@ public struct Flags {
         )
         public var virtualization: Bool = false
 
-        @Option(name: [.customLong("volume"), .short], help: "Bind mount a volume into the container")
+        @Option(
+            name: [.customLong("volume"), .short],
+            help:
+                "Bind mount a volume into the container. Formats: container-path (anonymous volume), name:container-path[:options], or host-path:container-path[:options], where options is a comma-separated list of mount options (e.g. ro)"
+        )
         public var volumes: [String] = []
 
         public func validate() throws {

docs/command-reference.md

@@ -72,7 +72,7 @@ container run [<options>] <image> [<arguments> ...]
 *   `--ssh`: Forward SSH agent socket to container
 *   `--shm-size <shm-size>`: Size of `/dev/shm` (e.g. 64M, 1G)
 *   `--tmpfs <tmpfs>`: Add a tmpfs mount to the container at the given path
-*   `-v, --volume <volume>`: Bind mount a volume into the container
+*   `-v, --volume <volume>`: Bind mount a volume into the container. Formats: `container-path` (anonymous volume), `name:container-path[:options]`, or `host-path:container-path[:options]`, where `options` is a comma-separated list of mount options (e.g. `ro`)
 *   `--virtualization`: Expose virtualization capabilities to the container (requires host and guest support)
 
 **Registry Options**
@@ -245,7 +245,7 @@ container create [<options>] <image> [<arguments> ...]
 *   `--ssh`: Forward SSH agent socket to container
 *   `--shm-size <shm-size>`: Size of `/dev/shm` (e.g. 64M, 1G)
 *   `--tmpfs <tmpfs>`: Add a tmpfs mount to the container at the given path
-*   `-v, --volume <volume>`: Bind mount a volume into the container
+*   `-v, --volume <volume>`: Bind mount a volume into the container. Formats: `container-path` (anonymous volume), `name:container-path[:options]`, or `host-path:container-path[:options]`, where `options` is a comma-separated list of mount options (e.g. `ro`)
 *   `--virtualization`: Expose virtualization capabilities to the container (requires host and guest support)
 
 **Registry Options**

docs/how-to.md

@@ -51,6 +51,16 @@ total 4
 
 The argument to `--volume` in the example consists of the full pathname for the host folder and the full pathname for the mount point in the container, separated by a colon.
 
+You can append a third colon-separated component containing a comma-separated list of mount options. For example, use `ro` to make the mount read-only in the container:
+
+<pre>
+% container run --volume ${HOME}/Desktop/assets:/content/assets:ro docker.io/python:alpine touch /content/assets/test
+touch: /content/assets/test: Read-only file system
+</pre>
+
+> [!NOTE]
+> For host directory mounts, only the `ro` option is currently guaranteed to take effect. Other mount options, such as `nosuid`, are applied only when combined with `ro`; without `ro`, they are silently ignored.
+
 The `--mount` option uses a comma-separated `key=value` syntax to achieve the same result:
 
 <pre>