Explain the various scenarios

Signed-off-by: Dimitris Karakasilis <dimitris@karakasilis.me>

README.md

@@ -138,9 +138,17 @@ Implement a "selective enrollment mode" with two distinct behaviors:
 - Enables full security verification for subsequent attestations
 
 #### **Selective Re-enrollment** (SealedVolume exists with specific fields)
-- **Empty values** (`""`) = Accept any value, update the stored value
-- **Set values** (`"abc123..."`) = Enforce exact match
-- **Omitted fields** = Skip verification entirely (allows flexibility)
+- **Empty values** (`""`) = Accept any value, update the stored value (re-enrollment mode)
+- **Set values** (`"abc123..."`) = Enforce exact match (enforcement mode)  
+- **Omitted fields** = Skip verification entirely (ignored mode)
+
+**Selective Enrollment Behavior Summary:**
+
+| Field State | Verification | Updates | Use Case |
+|-------------|-------------|---------|----------|
+| **Empty** (`""`) | ✅ Accept any value | ✅ Update with current | Re-learn after TPM/firmware changes |
+| **Set** (`"abc123"`) | ✅ Enforce exact match | ❌ No updates | Strict security enforcement |
+| **Omitted** (deleted) | ❌ Skip entirely | ❌ Never re-enrolled | Ignore volatile PCRs (e.g., PCR 11) |
 
 ### Required Implementation Changes
 
@@ -203,6 +211,135 @@ spec:
 6. **Flexible Boot Stages**: Omit PCR 11 entirely so users can decrypt during boot AND after full system startup
 7. **Kernel Updates**: Omit PCR 11 to avoid quarantine on routine Kairos upgrades
 
+### Practical Operator Workflows
+
+#### **Scenario 1: Reusing Existing Passphrases After SealedVolume Recreation**
+
+**Problem**: An operator needs to recreate a SealedVolume (e.g., after accidental deletion or configuration changes) but wants to keep using the existing passphrase to avoid re-encrypting the disk.
+
+**Solution**: The system automatically reuses existing Kubernetes secrets when available:
+
+```bash
+# 1. Operator accidentally deletes SealedVolume
+kubectl delete sealedvolume my-encrypted-volume
+
+# 2. Original secret still exists in cluster
+kubectl get secret my-encrypted-volume-encrypted-data
+# NAME                                  TYPE     DATA   AGE
+# my-encrypted-volume-encrypted-data    Opaque   1      5d
+
+# 3. When TPM client reconnects, system detects existing secret
+# and reuses the passphrase instead of generating a new one
+```
+
+**Behavior**: The system will:
+- Detect the existing secret with the same name
+- Log: "Secret already exists, reusing existing secret"
+- Use the existing passphrase for decryption
+- Recreate the SealedVolume with current TPM attestation data
+- Maintain continuity without requiring disk re-encryption
+
+#### **Scenario 2: Deliberately Skipping PCRs After Initial Enrollment**
+
+**Problem**: An operator initially enrolls with PCRs 0, 7, and 11, but later realizes PCR 11 changes frequently due to kernel updates and wants to ignore it permanently.
+
+**Solution**: Remove the PCR from the SealedVolume specification:
+
+```bash
+# 1. Initial enrollment created SealedVolume with:
+# pcrValues:
+#   pcrs:
+#     "0": "abc123..."
+#     "7": "def456..."  
+#     "11": "ghi789..."
+
+# 2. Operator edits SealedVolume to remove PCR 11 entirely
+kubectl edit sealedvolume my-encrypted-volume
+# Remove the "11": "ghi789..." line completely
+
+# 3. Result - omitted PCR 11:
+# pcrValues:
+#   pcrs:
+#     "0": "abc123..."
+#     "7": "def456..."
+#     # PCR 11 omitted = ignored entirely
+```
+
+**Behavior**: The system will:
+- Skip PCR 11 verification entirely (no enforcement)
+- Never re-enroll PCR 11 in future attestations
+- Log: "PCR verification successful using selective enrollment" (without mentioning PCR 11)
+- Continue enforcing PCRs 0 and 7 normally
+
+#### **Scenario 3: Manual PCR Selection During Initial Setup**
+
+**Problem**: An operator knows certain PCRs will be unstable and wants to exclude them from the beginning.
+
+**Solution**: Create the initial SealedVolume manually with only desired PCRs:
+
+```yaml
+# Create SealedVolume with selective PCR enforcement from the start
+apiVersion: keyserver.kairos.io/v1alpha1
+kind: SealedVolume
+metadata:
+  name: selective-pcr-volume
+spec:
+  TPMHash: "known-tpm-hash"
+  partitions:
+    - label: "encrypted-data"
+      secret:
+        name: "my-passphrase"
+        path: "passphrase"
+  attestation:
+    ekPublicKey: ""          # Re-enrollment mode
+    akPublicKey: ""          # Re-enrollment mode  
+    pcrValues:
+      pcrs:
+        "0": ""              # Re-enrollment mode (will learn)
+        "7": ""              # Re-enrollment mode (will learn)
+        # "11": omitted      # Skip PCR 11 entirely
+```
+
+**Behavior**: The system will:
+- Learn and enforce PCRs 0 and 7 on first attestation
+- Completely ignore PCR 11 (never verify, never store)
+- Allow flexible boot stages without PCR 11 interference
+
+#### **Scenario 4: Kernel Upgrade - Temporary PCR Re-enrollment**
+
+**Problem**: An operator is performing a kernel upgrade and knows PCR 11 will change, but wants to continue enforcing it after the upgrade (unlike permanent omission).
+
+**Solution**: Set the PCR value to empty string to trigger re-enrollment mode:
+
+```bash
+# 1. Before kernel upgrade - PCR 11 is currently enforced
+kubectl get sealedvolume my-volume -o jsonpath='{.spec.attestation.pcrValues.pcrs.11}'
+# Output: "abc123def456..."  (current PCR 11 value)
+
+# 2. Set PCR 11 to empty string to allow re-enrollment
+kubectl patch sealedvolume my-volume --type='merge' \
+  -p='{"spec":{"attestation":{"pcrValues":{"pcrs":{"11":""}}}}}'
+
+# 3. Perform kernel upgrade and reboot
+
+# 4. After reboot, TPM client reconnects and system learns new PCR 11 value
+# Log will show: "Updated PCR value during selective enrollment, pcr: 11"
+
+# 5. Verify new PCR 11 value is now enforced
+kubectl get sealedvolume my-volume -o jsonpath='{.spec.attestation.pcrValues.pcrs.11}'
+# Output: "new789xyz012..."  (new PCR 11 value after kernel upgrade)
+```
+
+**Behavior**: The system will:
+- Accept any PCR 11 value on next attestation (re-enrollment mode)
+- Update the stored PCR 11 with the new post-upgrade value
+- Resume strict PCR 11 enforcement with the new value
+- Log: "Updated PCR value during selective enrollment"
+
+**Key Difference from Scenario 2:**
+- **Scenario 2 (Omit PCR)**: PCR 11 permanently ignored, never verified again
+- **Scenario 4 (Empty PCR)**: PCR 11 temporarily re-enrolled, then enforced with new value
+
 ### Critical Implementation Notes
 
 - **TPM Hash MUST remain mandatory** - without it, multiple clients would match the same SealedVolume
@@ -211,5 +348,34 @@ spec:
 - **Consider rate limiting** to prevent abuse of enrollment mode
 - **Update documentation** with operational procedures for each use case
 
+### Quick Reference for Documentation
+
+**Common Operations:**
+
+```bash
+# Skip a PCR permanently (never verify again)
+kubectl edit sealedvolume my-volume
+# Remove the PCR line entirely from pcrValues.pcrs
+
+# Temporarily allow PCR re-enrollment (e.g., before kernel upgrade)
+kubectl patch sealedvolume my-volume --type='merge' -p='{"spec":{"attestation":{"pcrValues":{"pcrs":{"11":""}}}}}'
+
+# Re-learn a PCR after hardware change (e.g., PCR 0 after BIOS update)  
+kubectl patch sealedvolume my-volume --type='merge' -p='{"spec":{"attestation":{"pcrValues":{"pcrs":{"0":""}}}}}'
+
+# Re-learn AK after TPM replacement
+kubectl patch sealedvolume my-volume --type='merge' -p='{"spec":{"attestation":{"akPublicKey":""}}}'
+
+# Check current PCR enforcement status
+kubectl get sealedvolume my-volume -o jsonpath='{.spec.attestation.pcrValues.pcrs}' | jq .
+```
+
+**Log Messages to Expect:**
+
+- `"Secret already exists, reusing existing secret"` - Passphrase reuse scenario
+- `"Updated PCR value during selective enrollment"` - Re-enrollment mode active
+- `"PCR verification successful using selective enrollment"` - Omitted PCRs ignored
+- `"PCR enforcement mode verification passed"` - Strict enforcement active
+
 ### Priority: High
 This blocks current test failures and addresses fundamental operational challenges for production deployments.