From 14eeba1beb93ceaac5ba7edda9e35896f00d65ef Mon Sep 17 00:00:00 2001
From: Kevin Adams <kevin.adams@ksatechnologies.com>
Date: Sun, 23 Aug 2026 14:32:36 -0400
Subject: [PATCH] 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>
---
 README.md               | 117 ++++++++++++++++++++++++++++++++--------
 docs/getting-started.md |  16 ++++++
 docs/upgrade-paths.md   |  20 ++++++-
 3 files changed, 131 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 1039d9b..eef75c1 100644
--- a/README.md
+++ b/README.md
@@ -126,15 +126,30 @@ curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
   | gpg --dearmor \
   | sudo tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null
 
-# Add the v3 repository track
-echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
-https://thegrandwazoo.github.io/freenas-proxmox v3 main" \
-  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+# Add the v3 repository track (deb822 format — recommended for 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: v3
+Components: main
+Signed-By: /etc/apt/keyrings/truenas-proxmox.gpg
+SOURCES
 
 # Install
 sudo apt update && sudo apt install truenas-proxmox
 ```
 
+<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 v3 main" \
+  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+```
+
+</details>
+
 `apt upgrade` will deliver v3.x point releases automatically. You will never be
 automatically promoted to a future v4 — that requires changing the dist track in
 your `sources.list` to `v4`.
@@ -165,14 +180,29 @@ curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
   | gpg --dearmor \
   | sudo tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null
 
-# Add the v2 repository track
-echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
-https://thegrandwazoo.github.io/freenas-proxmox main main" \
-  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+# Add the v2 repository track (deb822 format — recommended for 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: main
+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 main main" \
+  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+```
+
+</details>
+
 ### Migrating from Cloudsmith
 
 > Cloudsmith is being phased out. GitHub Pages is the permanent home for this project's packages.
@@ -191,14 +221,29 @@ curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
   | gpg --dearmor \
   | sudo tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null
 
-# Point to the v3 dist track
-echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
-https://thegrandwazoo.github.io/freenas-proxmox v3 main" \
-  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+# Point to the v3 dist track (deb822 format — recommended for 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: v3
+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 v3 main" \
+  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+```
+
+</details>
+
 **On v2.x (Cloudsmith stable) — staying on v2:**
 
 ```bash
@@ -211,14 +256,29 @@ curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
   | gpg --dearmor \
   | sudo tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null
 
-# Point to the v2 dist track (v2.x only — you will never receive a v3 package)
-echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
-https://thegrandwazoo.github.io/freenas-proxmox main main" \
-  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+# Point to the v2 dist track (deb822 format — recommended for PVE 9 / Debian trixie; v2.x only, you will never receive a v3 package)
+cat << 'SOURCES' | sudo tee /etc/apt/sources.list.d/truenas-proxmox.sources
+Types: deb
+URIs: https://thegrandwazoo.github.io/freenas-proxmox
+Suites: main
+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 main main" \
+  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+```
+
+</details>
+
 For a full upgrade path matrix — including what to do when v4 ships — see [docs/upgrade-paths.md](docs/upgrade-paths.md).
 
 ---
@@ -234,15 +294,30 @@ curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
   | gpg --dearmor \
   | sudo tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null
 
-# Add the testing dist track
-echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
-https://thegrandwazoo.github.io/freenas-proxmox testing main" \
-  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+# Add the testing dist track (deb822 format — recommended for 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: testing
+Components: main
+Signed-By: /etc/apt/keyrings/truenas-proxmox.gpg
+SOURCES
 
 sudo apt update && sudo apt install truenas-proxmox
 ```
 
-To switch back to stable, replace `testing` with `v3` in your sources.list and run `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 testing main" \
+  | sudo tee /etc/apt/sources.list.d/truenas-proxmox.list
+```
+
+</details>
+
+To switch back to stable, replace `Suites: testing` with `Suites: v3` in `truenas-proxmox.sources` (or `testing` with `v3` in `truenas-proxmox.list` if using the one-liner format) and run `apt update`.
 
 ---
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 7a12756..86d7429 100644
--- a/docs/getting-started.md
+++ b/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
diff --git a/docs/upgrade-paths.md b/docs/upgrade-paths.md
index 16c581d..fc72802 100644
--- a/docs/upgrade-paths.md
+++ b/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.
 
 ---