Keep missing guest disk guidance out of unsafe setup assumptions

Explain that the shared Proxmox unavailable status is not an installation diagnosis. Keep setup behind backup recovery and supported guest-OS checks in the existing shipped guide; pin the rendered safety/setup fragments and preserve every covered filesystem and prior-active restoration requirements.

Contract-Neutral: Clarifies existing collection limits and backup-safe setup without changing collection, runtime UI, actions or permissions.
Change-source: pulse-maintainer

docs/VM_DISK_MONITORING.md

@@ -146,6 +146,29 @@ custom monitoring role if the required read privileges are absent.
 
 ## 🔧 Troubleshooting
 
+### A missing reading is not an installation diagnosis
+
+Pulse's **“agent not running”** disk explanation means Proxmox could not query
+the guest agent. It can also cover a general guest-agent HTTP 500 response; it
+does not establish whether an agent is absent or stopped. An unknown explanation
+establishes neither. **Do not install, enable or restart an agent solely to clear
+a disk dash.**
+
+Read [Backup safety](#backup-safety) before changing anything. During a backup,
+freeze/thaw or an unresponsive-guest incident, defer setup and live probes and
+use the guest/platform's established recovery procedure. A running VM, an absent
+lock or an OK backup does not prove thaw. Keep the monitoring-outage precaution
+until independent checks confirm thaw, fresh successful writes to **every
+filesystem covered by the backup** and workload liveness. Restore only services
+and timers that were previously active.
+
+When the guest is responsive and outside those conditions, review its existing
+agent configuration and guest-local service through your normal console. Use
+[Setup](#-setup) only if it actually needs configuration and the guest OS has a
+supported QEMU Guest Agent. The Linux package name is not a Windows or Android
+installation instruction. If no supported agent is available, use the guest's
+own filesystem tools; missing Pulse usage is unknown, not zero.
+
 | Observation | Useful next check |
 | --- | --- |
 | **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |

frontend-modern/public/docs/VM_DISK_MONITORING.md

@@ -146,6 +146,29 @@ custom monitoring role if the required read privileges are absent.
 
 ## 🔧 Troubleshooting
 
+### A missing reading is not an installation diagnosis
+
+Pulse's **“agent not running”** disk explanation means Proxmox could not query
+the guest agent. It can also cover a general guest-agent HTTP 500 response; it
+does not establish whether an agent is absent or stopped. An unknown explanation
+establishes neither. **Do not install, enable or restart an agent solely to clear
+a disk dash.**
+
+Read [Backup safety](#backup-safety) before changing anything. During a backup,
+freeze/thaw or an unresponsive-guest incident, defer setup and live probes and
+use the guest/platform's established recovery procedure. A running VM, an absent
+lock or an OK backup does not prove thaw. Keep the monitoring-outage precaution
+until independent checks confirm thaw, fresh successful writes to **every
+filesystem covered by the backup** and workload liveness. Restore only services
+and timers that were previously active.
+
+When the guest is responsive and outside those conditions, review its existing
+agent configuration and guest-local service through your normal console. Use
+[Setup](#-setup) only if it actually needs configuration and the guest OS has a
+supported QEMU Guest Agent. The Linux package name is not a Windows or Android
+installation instruction. If no supported agent is available, use the guest's
+own filesystem tools; missing Pulse usage is unknown, not zero.
+
 | Observation | Useful next check |
 | --- | --- |
 | **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |

frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts

@@ -19,6 +19,42 @@ function render(markdown: string, name: string): HTMLElement {
 }
 
 describe('manual backup safety help', () => {
+  it('makes missing-reading guidance observational, OS-specific and safe before setup', () => {
+    const rendered = render(guide, 'VM_DISK_MONITORING');
+    const troubleshooting = rendered.querySelector(
+      '#a-missing-reading-is-not-an-installation-diagnosis',
+    );
+    expect(troubleshooting?.textContent).toBe('A missing reading is not an installation diagnosis');
+    const explanation = guide
+      .split('### A missing reading is not an installation diagnosis')[1]
+      .split('| Observation |')[0];
+    const text = render(explanation, 'VM_DISK_MONITORING').textContent?.replace(/\s+/g, ' ');
+    expect(text).toContain('does not establish whether an agent is absent or stopped');
+    expect(text).toContain(
+      'Do not install, enable or restart an agent solely to clear a disk dash',
+    );
+    expect(text).toContain('defer setup and live probes');
+    expect(text).toContain('every filesystem covered by the backup');
+    expect(text).toContain('workload liveness');
+    expect(text).toContain('Restore only services and timers that were previously active');
+    expect(text).toContain('not a Windows or Android installation instruction');
+    expect(text).toContain('missing Pulse usage is unknown, not zero');
+    expect(render(explanation, 'VM_DISK_MONITORING').querySelector('pre')).toBeNull();
+    for (const fragment of ['backup-safety', '-setup']) {
+      const link = render(explanation, 'VM_DISK_MONITORING').querySelector(
+        `a[href="#${fragment}"]`,
+      );
+      expect(link).not.toBeNull();
+      expect(rendered.querySelector(`#${fragment}`)).not.toBeNull();
+    }
+    // This broad status comes from the current collector, not a reproduced
+    // native failure or a new diagnosis of the guest's service state.
+    const classifier = read('internal/monitoring/guest_disk_stability.go');
+    expect(classifier).toMatch(
+      /case strings.Contains\(errStr, "500"\):\s+return "agent-not-running"/,
+    );
+  });
+
   it('ships the complete precaution and makes it reachable from troubleshooting', () => {
     expect(read('frontend-modern/public/docs/VM_DISK_MONITORING.md')).toBe(guide);
     const troubleshooting = read('docs/TROUBLESHOOTING.md');