From ae57447e6f6bf04c442d9ff31aae1e80edc3863d Mon Sep 17 00:00:00 2001
From: Amir Husayn Panahifar <ahp@panahifar.ir>
Date: Sun, 18 Oct 2026 16:42:33 +0330
Subject: [PATCH] docs: document image builds and VM usage

---
 .gitignore |  8 ++++++
 README.md  | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 84 insertions(+), 2 deletions(-)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..46b5931
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,8 @@
+/output/
+/tmp/
+/terraform/.terraform/
+/terraform/terraform.tfstate
+/terraform/terraform.tfstate.*
+/terraform/*.tfvars
+/terraform/*.tfvars.json
+/terraform/crash.log
diff --git a/README.md b/README.md
index f162284..2603294 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,77 @@
-# parchlinux-cloud
+# Parch Linux Cloud Images
 
-Parch Linux Cloud & QCOW2 appliance images
\ No newline at end of file
+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>