honestly its been months, i found unstaged changes and forgot

docs/proxmox-template.md

@@ -10,11 +10,67 @@ Expected VM defaults:
 - CPU type `host`
 - QEMU Guest Agent enabled
 - Cloud-Init drive attached
+- Serial console attached as `serial0: socket`
+- Display set to `vga: serial0` for Proxmox xterm.js console access
 - 2 vCPU, 2 GB RAM, 32 GB disk unless a service needs more
 
+Use the helper script on a Proxmox node to create the base template:
+
+```sh
+scripts/create-proxmox-template.sh
+```
+
+The script prompts for VMID, name, storage, bridge, CPU, memory, disk size, and
+image source. Press Enter to accept the displayed defaults. It downloads the
+Debian 13 GenericCloud qcow2 image unless a local `--image-file` is provided,
+imports it into Proxmox storage, attaches a Cloud-Init drive, configures serial
+console support, and converts the VM to a template.
+
+For automation or previews:
+
+```sh
+scripts/create-proxmox-template.sh --dry-run --yes
+scripts/create-proxmox-template.sh --non-interactive --vmid 9000 --storage local-lvm --bridge vmbr0
+```
+
+If a PBS storage/datastore ID is supplied, the template's main disk is created
+with the Proxmox disk `backup=1` flag. Leaving it empty keeps the main disk at
+`backup=0`.
+
+```sh
+scripts/create-proxmox-template.sh --pbs-storage pbs-main
+```
+
+To initialise all VMs declared in `host_vars/*.yml`, run:
+
+```sh
+scripts/init-proxmox-vms.sh
+```
+
+The VM initialiser checks whether the template VMID exists. If it does not, it
+runs `scripts/create-proxmox-template.sh` first. Each host var file with a
+`proxmox_vmid` is cloned from the template and configured from its `proxmox_*`
+hardware settings.
+
 Cloud-Init is only responsible for Day 0 bootstrap: user creation, SSH
 hardening, Docker installation, baseline packages, firewall defaults, directory
-layout, PKI directory preparation, and `ansible-pull`.
+layout, PKI directory preparation, enabling `serial-getty@ttyS0.service`, and
+`ansible-pull`.
+
+Proxmox hardware settings must be applied outside Cloud-Init. For a VM or
+template, set:
+
+```sh
+qm set <vmid> --serial0 socket --vga serial0
+```
+
+The Cloud-Init template enables `serial-getty@ttyS0.service` by default and sets
+`TERM=xterm-256color` for that getty. Override these variables if needed:
+
+```yaml
+cloud_init_serial_console_enabled: true
+cloud_init_serial_console_tty: ttyS0
+cloud_init_serial_console_term: xterm-256color
+```
 
 Applications and durable service configuration belong in Ansible roles.
-