docs: add volume templates, cloning, and shared volumes sections

pages/platform/volumes.mdx

@@ -224,6 +224,122 @@ kraft cloud volume detach <volume-name>
 kraft cloud volume remove <volume-name>
 ```
 
+## Volume templates
+
+A volume template is a volume in the `TEMPLATE` state.
+Once a volume transitions to template state, it's immutable: you can clone it but not write to it or delete it while active clones exist.
+
+The platform creates volume templates automatically when you convert an instance into an [instance template](/platform/instances#instance-templates): the platform converts all volumes attached to that instance into volume templates as an atomic operation.
+
+Volume templates have their own create, read, update, and delete endpoints at `/v1/volumes/templates`.
+They support [delete locks](/platform/delete-locks) and [tags](/platform/tagging).
+
+## Volume cloning
+
+A volume clone is an independent copy of an existing volume.
+The clone operation is **asynchronous**: the platform creates the new volume immediately in a pending state, and the data copy completes in the background.
+
+To clone a volume directly:
+
+```bash title=""
+POST /v1/volumes/{name}/clone
+```
+
+The platform also clones volumes implicitly when you clone an instance or create one from a template.
+It clones each attached volume and attaches the clone to the new instance.
+
+You can't delete a source volume or template while it has active clones (`nactive_clones > 0`).
+
+## Shared volumes
+
+More than one instance can mount the same volume simultaneously as long as all mounts are in read-only mode.
+Read-only sharing is always permitted regardless of how many other instances have the volume mounted.
+
+A read-write mount is exclusive.
+You can't add one while any other mount exists on that volume, and a volume can't have two read-write mounts at once.
+
+Specify `readonly: true` when attaching a volume at instance creation or via the attach endpoint:
+
+```json title="POST /v1/instances"
+{
+  "volumes": [
+    {
+      "name": "my-shared-volume",
+      "at": "/data",
+      "readonly": true
+    }
+  ]
+}
+```
+
+### Quota policy
+
+Volumes support two quota policies that control how the platform allocates storage space:
+
+| Policy | Description |
+|--------|-------------|
+| `static` | The platform allocates a fixed quota up front |
+| `dynamic` | The platform scales the quota with actual usage |
+
+### Discard / `TRIM` support
+
+Block-device volumes support `TRIM`/discard commands, which allow the guest to notify the host about blocks that are no longer in use.
+The platform enables discard by default and it applies to volumes backed by a block device (for example, `ext4`-formatted volumes).
+Virtiofs-hosted volumes don't use discard.
+
+This allows guest-initiated `fstrim` runs to release unused blocks, which is useful for reclaiming space in long-lived volumes.
+
+## Custom filesystems
+
+By default, volumes use a platform-configured filesystem (typically `ext4` for block volumes and `virtiofs` for hosted volumes).
+If the platform operator has registered more named filesystems, you can select one by passing its name in the `filesystem` field when creating a volume:
+
+```json title="POST /v1/volumes"
+{
+  "name": "my-volume",
+  "size_mb": 512,
+  "filesystem": "xfs"
+}
+```
+
+Available filesystem names depend on the deployment.
+An unsupported filesystem name returns an error.
+
+The operator defines volume operation hooks (format, delete, fscheck) per filesystem via scripts placed under `UKP_STOR_FS_CONFIG_PATH`.
+The `args` field passes named string arguments to these scripts:
+
+```json title="POST /v1/volumes"
+{
+  "name": "my-volume",
+  "size_mb": 512,
+  "filesystem": "custom-fs",
+  "args": {
+    "key": "value"
+  }
+}
+```
+
+## Managed volumes
+
+A managed volume points to an existing directory on the host rather than a platform-allocated storage file.
+This is an advanced feature that requires the `VOLUME_MANAGER` permission.
+
+Create a managed volume with a `host_path` field instead of `size_mb`:
+
+```json title="POST /v1/volumes"
+{
+  "name": "my-managed-volume",
+  "host_path": "/srv/data/mydir",
+  "uid": 1000,
+  "gid": 1000
+}
+```
+
+- `host_path` must be an absolute, normalised path to an existing directory on the host (no `.`, `..`, or `:` components).
+- `uid` and `gid` set the ownership used when accessing the volume from the guest. Both default to `0` if not specified.
+- `size_mb` and `template` are mutually exclusive with `host_path`.
+- The platform doesn't create, format, resize, or delete the backing directory for managed volumes.
+
 ## Learn more
 
 * The `kraft cloud` [CLI reference](/cli/), in particular the [deploy](/cli/deploy) and [volume](/cli/volume) subcommands