docs: explain disk sizing, virtual vs actual size, and auto-shrink behavior

README.md

@@ -240,6 +240,32 @@ curl -X POST http://10.2.0.2:9000/api/v1/jobs \
 6. **Poll progress** → real-time status bar updates every 2 seconds
 7. **Reuse or cleanup** → create another VM from same source, or delete staging files
 
+### Disk sizing and auto-shrink
+
+Virtual disk images (VMDK, QCOW2) have two sizes:
+
+| | Meaning | Example |
+|---|---|---|
+| **Virtual size** | Maximum the disk *could* grow to | 500 GB |
+| **Actual size** | Real data in the image (sparse file) | ~7 GB |
+
+During analysis, the UI shows the virtual size (e.g. *"500.0 GB detected. Omit to
+auto-shrink to 30 GB"*). This is because the source image was created with a
+large virtual disk, but only a fraction is used.
+
+**Target Disk Size field — what happens:**
+
+| You enter | Result |
+|-----------|--------|
+| **Blank** (default) | Auto-shrinks to 30 GB if the source is larger. Uses `virt-resize --shrink --resize-force` to safely reduce the disk container. |
+| **A number** (e.g. `500`) | Uses that exact size. No shrinking. |
+| **A number < virtual** (e.g. `40`) | Shrinks the disk to 40 GB. |
+| **A number > virtual** (e.g. `600`) | Expands the disk. Safe operation. |
+
+> **Tip:** For most Linux VMs (Debian, Ubuntu, etc.), 30 GB is plenty.
+> You can always expand the disk later in Proxmox if you need more space.
+> If you plan to store large datasets inside the VM, set a higher value.
+
 ## Configuration
 
 | Variable | Default | Description |