docs: add deb822-format repo instructions for PVE 9 / Debian trixie

Debian trixie recommends deb822-style .sources files over the one-liner
.list format, and PVE 9 ships on trixie. Show deb822 as the primary form
in README (stable, v2 track, Cloudsmith migration, testing) and
getting-started.md/upgrade-paths.md, keeping the one-liner .list format
as a fallback for PVE 8 / bookworm users.

Fixes #285

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/getting-started.md

@@ -97,12 +97,28 @@ curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
 
 ### Step 2 — Add the Package Repository
 
+**PVE 9 / Debian trixie (recommended — deb822 format):**
+
+```bash
+cat << 'SOURCES' | tee /etc/apt/sources.list.d/truenas-proxmox.sources
+Types: deb
+URIs: https://thegrandwazoo.github.io/freenas-proxmox
+Suites: v3
+Components: main
+Signed-By: /etc/apt/keyrings/truenas-proxmox.gpg
+SOURCES
+```
+
+**PVE 8 / Debian bookworm (one-liner `.list` format):**
+
 ```bash
 echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
 https://thegrandwazoo.github.io/freenas-proxmox v3 main" \
   | tee /etc/apt/sources.list.d/truenas-proxmox.list
 ```
 
+Both formats resolve to the same packages — pick whichever matches your Proxmox VE version. Do not add both; apt would see the repository twice.
+
 ### Step 3 — Install the Package
 
 ```bash

docs/upgrade-paths.md

@@ -77,16 +77,34 @@ When v4.0 ships, this section will be updated with:
 - Step-by-step migration from v3.x
 - Step-by-step migration from v2.x (if a direct v2→v4 path is supported)
 
-**To receive v4.x packages when they ship**, you will need to change your `sources.list` dist track from `v3` to `v4`:
+**To receive v4.x packages when they ship**, you will need to change your dist track from `v3` to `v4`:
 
 ```bash
 # When v4.0 is released — do NOT run this until the v4 migration guide is published
+
+# deb822 format (recommended — PVE 9 / Debian trixie)
+cat << 'SOURCES' | sudo tee /etc/apt/sources.list.d/truenas-proxmox.sources
+Types: deb
+URIs: https://thegrandwazoo.github.io/freenas-proxmox
+Suites: v4
+Components: main
+Signed-By: /etc/apt/keyrings/truenas-proxmox.gpg
+SOURCES
+sudo apt update
+```
+
+<details>
+<summary>PVE 8 / Debian bookworm — one-liner <code>.list</code> format</summary>
+
+```bash
 echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
 https://thegrandwazoo.github.io/freenas-proxmox v4 main" \
   | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
 sudo apt update
 ```
 
+</details>
+
 `apt upgrade` on the `v3` dist track will never pull in a v4 package — you must explicitly change the dist track. This is intentional.
 
 ---