docs: document image builds and VM usage

README.md

@@ -1,3 +1,77 @@
-# parchlinux-cloud
+# Parch Linux Cloud Images
 
-Parch Linux Cloud & QCOW2 appliance images
+Build and run Parch Linux virtual machine images for x86_64 QEMU/KVM.
+
+## Images
+
+| Image | Description |
+| --- | --- |
+| Cloud | Cloud-init enabled image for automated setup. |
+| Basic | Image for interactive use. |
+| Libvirt executor | Image with GitLab Runner and libvirt tools. |
+
+Generated images and SHA-256 checksums are saved in `output/`
+
+## Requirements
+
+- Arch Linux x86_64 to build images
+- QEMU/KVM and libvirt to run virtual machines
+- Terraform to provision a VM with the included configuration
+
+Install the build dependencies with:
+
+```sh
+make install-deps
+```
+
+## Build
+
+Build all image variants:
+
+```sh
+make build
+```
+
+Build only the cloud image:
+
+```sh
+make build-cloud
+```
+
+Set a version explicitly if needed:
+
+```sh
+make build-cloud VERSION=20261018.1
+```
+
+## Run
+
+Create an SSH key if needed, then build and start the cloud VM:
+
+```sh
+ssh-keygen -t ed25519
+make build-cloud
+make qemu-up
+```
+
+Connect to the VM:
+
+```sh
+make qemu-ip
+make qemu-ssh
+```
+
+The VM is configured with Terraform in `terraform/`. Adjust its settings there as needed.
+
+## Useful commands
+
+```sh
+make help       # list available commands
+make qemu-plan  # preview VM changes
+make qemu-down  # remove the VM
+make clean      # remove generated files
+```
+
+## Contributors
+
+- Core Developer: Amir Husayn Panahifar <ahp@panahifar.ir>