Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Make recovery help distinguish backup evidence from safe restore

pulse-triage[bot]2201fd59b472
diff --git a/docs/RECOVERY.md b/docs/RECOVERY.md
index 2d90ee95ed..1ffc4b15b2 100644
--- a/docs/RECOVERY.md
+++ b/docs/RECOVERY.md
@@ -1,173 +1,188 @@
# Recovery
-Pulse v6 includes a **provider-neutral recovery view** that aggregates backup, snapshot, and replication artifacts across all connected platforms into a single interface.
+Pulse collects backup, snapshot and replication evidence from connected
+providers. Use it to find recorded artifacts, identify gaps in protection and
+check the source of a backup before using the provider's own recovery tools.
+Pulse does not restore workloads from these views.
-## Overview
+## Where to look
-Recovery is event-first and answers two questions:
+There is no top-level Recovery page. Open the existing platform view:
-1. **"What happened?"** → The **Recovery events** table shows individual recovery points (artifacts) with timestamps, outcomes, and sizes.
-2. **"What can I actually recover?"** → **Protection coverage** shows the canonical posture for each resource: protected, attention, unprotected, or unknown.
+- **Proxmox → Backups** (`/proxmox/backups`): **By date** lists recorded
+ artifacts; **Coverage** groups them by workload. Expand a coverage row to
+ inspect its posture reason and individual artifacts. Backup servers have
+ their own rows on the same page.
+- **TrueNAS → Protection** (`/truenas/protection`): snapshots and replication
+ activity reported by the TrueNAS connection.
+- **Kubernetes**: recovery records depend on the agent reporting VolumeSnapshot
+ or Velero inventory. An installed agent or a connected cluster does not
+ establish that either is available.
-## Supported Providers
+Provider collection is separate from presentation. Not every platform displays
+the same columns or filters, and a missing reading is not proof that no backup
+exists. [Check missing evidence](#missing-or-inconsistent-evidence) before
+changing the provider or Pulse's stored data.
-| Provider | Recovery Point Types |
-|---|---|
-| **Proxmox Backup Server (PBS)** | Full and incremental backups, sync jobs, verify tasks |
-| **Proxmox VE (PVE)** | Local dump-style backups (`vzdump`) |
-| **TrueNAS** | ZFS snapshots, replication tasks |
-| **Kubernetes** | VolumeSnapshots, Velero backups (when available) |
-
-## Concepts
-
-### Subject (What Was Protected)
-
-A subject is the thing being protected:
-
-- A Proxmox VM or container
-- A TrueNAS dataset (e.g., `tank/apps/postgres`)
-- A Kubernetes PVC (e.g., `monitoring/prometheus-pvc`)
-
-Subjects link to unified resources via `subjectResourceId` when possible.
-
-### Recovery Point (An Artifact / Event)
-
-A recovery point is a single concrete artifact:
-
-- A PBS backup snapshot
-- A local `vzdump` backup file
-- A ZFS snapshot
-- A replication run result
-
-### Rollup (A Subject Summary)
-
-A rollup groups recovery points for a subject to show:
+## What the evidence means
-- **Protection status** — is this subject actively protected?
-- **Latest point** — when was the most recent successful backup/snapshot?
-- **Health** — are there recent failures or warnings?
+Keep these observations separate:
-### Protection Posture (A Trust Decision)
-
-A protection posture combines subject-linked recovery points with the latest
-provider collection evidence. It deliberately keeps four operator-facing
-states:
-
-- **Protected** — a qualifying current recovery point is linked to the resource
+| Observation | What it establishes | What it does not establish |
+|---|---|---|
+| Successful task or `success` outcome | A provider-reported result or collected artifact | Guest thaw, application health or a tested restore |
+| Running task or partial artifact | Work or an incomplete artifact is observed | A completed recovery point, even if a size is shown |
+| Verified backup | The provider's verification result for that artifact | A successful application restore or guest thaw |
+| Recent snapshot | A point on the source system | An independent copy that survives loss of that system |
+| Protected posture | Current, linked evidence meets Pulse's protection policy | A recovery guarantee or permission to discard other backups |
+
+**A backup task's OK status is not confirmation that the guest has thawed.**
+For freeze-enabled Proxmox backups, stop Pulse before the backup and restart it
+only after independently confirming guest thaw. Pulse monitoring and alert
+delivery are unavailable while it is stopped. Do not send additional
+guest-agent commands during freeze/thaw to diagnose the problem, or disable
+filesystem freezing merely to make a task look successful. Follow the
+[backup safety precaution](VM_DISK_MONITORING.md#backup-safety); it is not a
+claim that Pulse has repaired or reproduced a native thaw failure.
+
+Before relying on an artifact, confirm its provider, repository, workload
+identity and time in the provider's own tools. For recovery assurance, test a
+restore to an isolated destination using that provider's procedure and check
+the restored application's data and operation. Do not overwrite the live
+workload as a diagnostic test, delete older backups, or change retention to
+hide a Pulse display problem.
+
+### Artifacts and subjects
+
+A **recovery point** is a collected backup, snapshot or replication result.
+Its **subject** is the protected workload, dataset or PVC; its **repository**
+is the storage location. Pulse links subjects to monitored resources where it
+can, and retains provider-local references when it cannot.
+
+Independent Proxmox installations can reuse a VMID. Compare the connection,
+node, guest type/ID, datastore, namespace and artifact time; matching names or
+VMIDs alone are not sufficient to identify a duplicate or the right restore.
+Direct PBS observations and PBS-through-PVE observations can differ in detail.
+See [PBS data sources](PBS.md#data-source-indicator).
+
+### Outcomes and verification
+
+Recorded outcomes are `success`, `warning`, `failed`, `running` or `unknown`.
+An unknown outcome is not success; an error fetching records is not an empty
+history. Where available, the API returns `startedAt`, `completedAt`,
+`sizeBytes` and provider-specific `details`. Missing times and sizes are not
+zero-valued measurements. A source backup timestamp is not necessarily the
+completion time of a later copy or sync task.
+
+The `verified` field is optional: `true` is a positive provider verification
+observation; `false` supplies no positive verification, so inspect the
+provider's detailed state; an omitted value supplies no verification result.
+Do not interpret an omitted field as a failed verification. Rollups may also
+report `verifyIntent` (`verified`, `stale` or `unknown`) and `lastVerifiedAt`;
+these summarise observed verification recency, not an end-to-end restore test.
+
+### Protection posture
+
+Pulse combines subject-linked artifacts with current provider collection
+evidence:
+
+- **Protected**: a qualifying current recovery point is linked to the resource
and complete provider evidence does not invalidate the claim.
-- **Attention** — evidence exists, but it is stale, failing, incomplete, or
- unverified when verification is expected.
-- **Unprotected** — complete evidence confirms that no qualifying protection
+- **Attention**: evidence is stale, failing, incomplete or unverified when
+ verification is expected.
+- **Unprotected**: complete evidence confirms that no qualifying protection
exists.
-- **Unknown** — identity, permissions, provider history, or collection
- completeness cannot support a stronger claim.
-
-A backup or snapshot artifact may still be shown while posture is unknown.
-Artifacts answer what Pulse found; posture answers what Pulse can safely claim.
-Snapshot presence alone is never presented as independent recovery.
-
-## Navigating Recovery
-
-### Recovery Events
-
-Shows individual recovery points. Key columns:
-
-| Column | Description |
-|---|---|
-| Time | When the point was created (started/completed) |
-| Subject | What was backed up |
-| Method | Kind + mode of the backup |
-| Outcome | success / warning / failed / running |
-| Size | Size of the artifact (when available) |
-| Verified | Whether the backup has been verified (tri-state) |
-
-### Protection Coverage
-
-The Proxmox **Backups → Coverage** view shows one row per workload. The default
-table stays compact; expanding a row reveals the plain-language posture reason,
-provider evidence quality, and individual restore artifacts.
-
-| Column | Description |
-|---|---|
-| Item | The protected resource (VM name, dataset path, etc.) |
-| Item Type | Canonical resource category |
-| Posture | Protected, attention, unprotected, or unknown |
-| Restore | Most recent successful recovery point timestamp |
-| Provider columns | Latest PBS, PVE, or guest-snapshot artifact where available |
-
-### Filtering
-
-Both workspaces support:
-
-- **Platform filter** — show only points from a specific platform
-- **Outcome filter** — show only failed, successful, or running points
-- **Time range** — filter to a specific time window
-- **Search** — full-text search across items and details
-
-## API Reference
-
-| Method | Endpoint | Description |
+- **Unknown**: identity, permissions or collection completeness cannot support
+ a stronger claim.
+
+A retained artifact can remain visible while posture is unknown. A running
+backup is not a new completed recovery point; inspect any earlier completed
+point separately rather than treating current activity as protection.
+
+## Missing or inconsistent evidence
+
+1. Open the relevant platform view, clear its search and filters, and check the
+ selected connection and organisation. Record the route that is affected.
+2. Inspect connection health, the latest observation time and any collection
+ error. Wait for that provider's configured polling interval, not a fixed
+ 30-second assumption. A green connection badge does not prove that every
+ history or backup read succeeded.
+3. Check the expected artifact in the provider's own inventory using an
+ existing authorised session. Verify its identity, location and permissions;
+ do not grant write or restore permissions merely to fill a monitoring row.
+4. For an **Unknown** posture, expand the coverage row and use the specific
+ limiting evidence. Resolve that collection or identity gap; do not turn
+ retained artifacts into a protection claim by clearing Pulse history.
+
+If the guest stopped responding during backup, preserve the task's warning or
+thaw error and the observations already available. Do not repeat the backup,
+reset the guest, or run active guest-agent probes just to reproduce it. Use
+the provider's recovery procedure and a separate trusted guest console to
+assess guest liveness and thaw, not Pulse's backup badge.
+
+When reporting missing records, share the failing view, running Pulse version,
+affected provider, time range, expected reading and relevant redacted error.
+Use consistent placeholders for private hostnames, datasets and IDs. Do not
+share full backup inventories, request headers, tokens, cookies or recovery
+keys. See [safe issue reporting](TROUBLESHOOTING.md#getting-help).
+
+## API reference
+
+These are read-only monitoring endpoints. Use an existing authenticated browser
+session or a `monitoring:read` token supplied through a private header file,
+never a token in a URL or diagnostic command argument. See [API access](API.md).
+
+| Method | Endpoint | Result |
|---|---|---|
-| `GET` | `/api/recovery/points` | List individual recovery points |
-| `GET` | `/api/recovery/rollups` | List subject rollups (protection coverage) |
-| `GET` | `/api/recovery/postures` | List canonical per-resource protection postures |
-| `GET` | `/api/recovery/series` | Time-series data for recovery charts |
-| `GET` | `/api/recovery/facets` | Available filter facets (providers, kinds, outcomes) |
+| `GET` | `/api/recovery/points` | Paged recovery points |
+| `GET` | `/api/recovery/rollups` | Paged subject summaries |
+| `GET` | `/api/recovery/series` | Completed-point counts grouped by day |
+| `GET` | `/api/recovery/facets` | Filter values from matching points |
+| `GET` | `/api/recovery/postures` | Canonical resource postures and limiting evidence |
-### Query Parameters
+### Point and rollup filters
-All recovery endpoints support:
+Points, rollups, series and facets accept these filters:
-| Parameter | Description |
+| Parameter | Values or meaning |
|---|---|
-| `provider` | Filter by provider (`pve`, `pbs`, `truenas`, `k8s`) |
-| `kind` | Filter by kind (`backup`, `snapshot`, `replication`) |
-| `outcome` | Filter by outcome (`success`, `failed`, `warning`, `running`) |
-| `since` | ISO 8601 timestamp — only points after this time |
-| `until` | ISO 8601 timestamp — only points before this time |
-| `subject` | Filter by subject reference |
-| `limit` | Max results (default: 500) |
-
-`/api/recovery/postures` has a deliberately bounded table contract. Supply one
-or more repeated `resourceId` parameters for a resource or batch lookup (at
-most 200), or omit them for a paged list. It also accepts `state`, `page`, and
-`limit`; `state=attention` returns the actionable attention list. The response
-includes the posture policy and provider evidence states so clients do not
-re-derive trust from raw artifacts.
-
-## Troubleshooting
-
-### No recovery data showing
-
-1. Verify at least one data source provides backup/snapshot data:
- - **PBS**: Ensure a PBS connection exists in Settings → Infrastructure.
- - **TrueNAS**: Ensure a TrueNAS connection exists in Settings → TrueNAS.
- - **PVE**: Local backups from PVE are included automatically.
-2. Wait one polling cycle (~30 seconds) for data to appear.
-3. Check the source filter — make sure you're not filtering to an empty source.
-
-### PBS backups showing but not TrueNAS snapshots (or vice versa)
-
-Check the **Source** filter on the Recovery page. Each provider surfaces its recovery points independently. Clear all filters to see everything.
-
-### Recovery points showing as "failed"
-
-Click the row to expand the details drawer, which shows the provider-specific error message. Common causes:
-
-- **PBS**: Datastore unreachable, verification failed, prune job errors
-- **TrueNAS**: Replication target unreachable, dataset locked, insufficient space
-- **PVE**: Backup storage full, vzdump process error
-
-### Current backups show an unknown posture
-
-Expand the workload row and inspect the limiting evidence. Pulse uses unknown
-when the current poll cannot prove provider-history completeness, permission
-scope, or subject identity. Fix the reported collection or access gap and wait
-for the next provider poll; Pulse does not promote retained backup artifacts to
-protected while that uncertainty remains.
-
-## See Also
-
-- [PBS Integration](PBS.md) — Proxmox Backup Server monitoring
-- [TrueNAS Integration](TRUENAS.md) — TrueNAS snapshot and replication monitoring
-- [Unified Resource Model](UNIFIED_RESOURCES.md) — how recovery integrates with the unified model
+| `platform` | `proxmox-pve`, `proxmox-pbs`, `truenas` or `kubernetes`; `provider` is an alias |
+| `kind` | `backup`, `snapshot` or `other`; TrueNAS replication results use `backup` |
+| `mode` | `local`, `remote` or `snapshot` |
+| `outcome` | `success`, `warning`, `failed`, `running` or `unknown` |
+| `from` | Lower time bound in RFC3339, for example `2026-10-01T00:00:00Z` |
+| `to` | Upper time bound in RFC3339 |
+| `subjectResourceId` | Exact linked resource identity; `itemResourceId` is an alias |
+| `rollupId` | Exact subject summary identity |
+| `q` | Text search; `query` is an alias |
+
+For example, this relative browser request selects PBS backup records within
+the stated time bounds without putting a credential in the URL:
+
+```text
+/api/recovery/points?platform=proxmox-pbs&kind=backup&from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z&page=1&limit=100
+```
+
+Use `from`/`to`, not `since`/`until`, and `subjectResourceId`, not `subject`.
+Unrecognised query names do not apply those filters. Invalid `from` or `to`
+values return an error rather than an empty result.
+
+Points and rollups accept `page` (starting at 1) and `limit` (default **100**,
+maximum **500**). Their response has a `data` array and `meta` pagination;
+inspect every required page rather than assuming the first is the inventory.
+Series and facets return aggregate data, not that paged-list contract.
+
+### Posture lookup
+
+`/api/recovery/postures` uses a separate filter contract. Repeat `resourceId`
+for a batch of at most **200** resource IDs, or omit it for a paged list.
+`state=attention` selects attention postures; `page` and `limit` control list
+pagination. Its response includes policy and provider evidence states. Do not
+apply point filters to this endpoint or re-derive posture from artifact count.
+
+## See also
+
+- [PBS integration](PBS.md) — access, data sources and host History
+- [TrueNAS integration](TRUENAS.md) — snapshots and replication monitoring
+- [VM disk monitoring](VM_DISK_MONITORING.md) — guest-agent and backup safety
+- [Migrating Pulse](MIGRATION.md) — configuration transfer versus a full-state backup of Pulse itself
diff --git a/frontend-modern/public/docs/RECOVERY.md b/frontend-modern/public/docs/RECOVERY.md
index 2d90ee95ed..1ffc4b15b2 100644
--- a/frontend-modern/public/docs/RECOVERY.md
+++ b/frontend-modern/public/docs/RECOVERY.md
@@ -1,173 +1,188 @@
# Recovery
-Pulse v6 includes a **provider-neutral recovery view** that aggregates backup, snapshot, and replication artifacts across all connected platforms into a single interface.
+Pulse collects backup, snapshot and replication evidence from connected
+providers. Use it to find recorded artifacts, identify gaps in protection and
+check the source of a backup before using the provider's own recovery tools.
+Pulse does not restore workloads from these views.
-## Overview
+## Where to look
-Recovery is event-first and answers two questions:
+There is no top-level Recovery page. Open the existing platform view:
-1. **"What happened?"** → The **Recovery events** table shows individual recovery points (artifacts) with timestamps, outcomes, and sizes.
-2. **"What can I actually recover?"** → **Protection coverage** shows the canonical posture for each resource: protected, attention, unprotected, or unknown.
+- **Proxmox → Backups** (`/proxmox/backups`): **By date** lists recorded
+ artifacts; **Coverage** groups them by workload. Expand a coverage row to
+ inspect its posture reason and individual artifacts. Backup servers have
+ their own rows on the same page.
+- **TrueNAS → Protection** (`/truenas/protection`): snapshots and replication
+ activity reported by the TrueNAS connection.
+- **Kubernetes**: recovery records depend on the agent reporting VolumeSnapshot
+ or Velero inventory. An installed agent or a connected cluster does not
+ establish that either is available.
-## Supported Providers
+Provider collection is separate from presentation. Not every platform displays
+the same columns or filters, and a missing reading is not proof that no backup
+exists. [Check missing evidence](#missing-or-inconsistent-evidence) before
+changing the provider or Pulse's stored data.
-| Provider | Recovery Point Types |
-|---|---|
-| **Proxmox Backup Server (PBS)** | Full and incremental backups, sync jobs, verify tasks |
-| **Proxmox VE (PVE)** | Local dump-style backups (`vzdump`) |
-| **TrueNAS** | ZFS snapshots, replication tasks |
-| **Kubernetes** | VolumeSnapshots, Velero backups (when available) |
-
-## Concepts
-
-### Subject (What Was Protected)
-
-A subject is the thing being protected:
-
-- A Proxmox VM or container
-- A TrueNAS dataset (e.g., `tank/apps/postgres`)
-- A Kubernetes PVC (e.g., `monitoring/prometheus-pvc`)
-
-Subjects link to unified resources via `subjectResourceId` when possible.
-
-### Recovery Point (An Artifact / Event)
-
-A recovery point is a single concrete artifact:
-
-- A PBS backup snapshot
-- A local `vzdump` backup file
-- A ZFS snapshot
-- A replication run result
-
-### Rollup (A Subject Summary)
-
-A rollup groups recovery points for a subject to show:
+## What the evidence means
-- **Protection status** — is this subject actively protected?
-- **Latest point** — when was the most recent successful backup/snapshot?
-- **Health** — are there recent failures or warnings?
+Keep these observations separate:
-### Protection Posture (A Trust Decision)
-
-A protection posture combines subject-linked recovery points with the latest
-provider collection evidence. It deliberately keeps four operator-facing
-states:
-
-- **Protected** — a qualifying current recovery point is linked to the resource
+| Observation | What it establishes | What it does not establish |
+|---|---|---|
+| Successful task or `success` outcome | A provider-reported result or collected artifact | Guest thaw, application health or a tested restore |
+| Running task or partial artifact | Work or an incomplete artifact is observed | A completed recovery point, even if a size is shown |
+| Verified backup | The provider's verification result for that artifact | A successful application restore or guest thaw |
+| Recent snapshot | A point on the source system | An independent copy that survives loss of that system |
+| Protected posture | Current, linked evidence meets Pulse's protection policy | A recovery guarantee or permission to discard other backups |
+
+**A backup task's OK status is not confirmation that the guest has thawed.**
+For freeze-enabled Proxmox backups, stop Pulse before the backup and restart it
+only after independently confirming guest thaw. Pulse monitoring and alert
+delivery are unavailable while it is stopped. Do not send additional
+guest-agent commands during freeze/thaw to diagnose the problem, or disable
+filesystem freezing merely to make a task look successful. Follow the
+[backup safety precaution](VM_DISK_MONITORING.md#backup-safety); it is not a
+claim that Pulse has repaired or reproduced a native thaw failure.
+
+Before relying on an artifact, confirm its provider, repository, workload
+identity and time in the provider's own tools. For recovery assurance, test a
+restore to an isolated destination using that provider's procedure and check
+the restored application's data and operation. Do not overwrite the live
+workload as a diagnostic test, delete older backups, or change retention to
+hide a Pulse display problem.
+
+### Artifacts and subjects
+
+A **recovery point** is a collected backup, snapshot or replication result.
+Its **subject** is the protected workload, dataset or PVC; its **repository**
+is the storage location. Pulse links subjects to monitored resources where it
+can, and retains provider-local references when it cannot.
+
+Independent Proxmox installations can reuse a VMID. Compare the connection,
+node, guest type/ID, datastore, namespace and artifact time; matching names or
+VMIDs alone are not sufficient to identify a duplicate or the right restore.
+Direct PBS observations and PBS-through-PVE observations can differ in detail.
+See [PBS data sources](PBS.md#data-source-indicator).
+
+### Outcomes and verification
+
+Recorded outcomes are `success`, `warning`, `failed`, `running` or `unknown`.
+An unknown outcome is not success; an error fetching records is not an empty
+history. Where available, the API returns `startedAt`, `completedAt`,
+`sizeBytes` and provider-specific `details`. Missing times and sizes are not
+zero-valued measurements. A source backup timestamp is not necessarily the
+completion time of a later copy or sync task.
+
+The `verified` field is optional: `true` is a positive provider verification
+observation; `false` supplies no positive verification, so inspect the
+provider's detailed state; an omitted value supplies no verification result.
+Do not interpret an omitted field as a failed verification. Rollups may also
+report `verifyIntent` (`verified`, `stale` or `unknown`) and `lastVerifiedAt`;
+these summarise observed verification recency, not an end-to-end restore test.
+
+### Protection posture
+
+Pulse combines subject-linked artifacts with current provider collection
+evidence:
+
+- **Protected**: a qualifying current recovery point is linked to the resource
and complete provider evidence does not invalidate the claim.
-- **Attention** — evidence exists, but it is stale, failing, incomplete, or
- unverified when verification is expected.
-- **Unprotected** — complete evidence confirms that no qualifying protection
+- **Attention**: evidence is stale, failing, incomplete or unverified when
+ verification is expected.
+- **Unprotected**: complete evidence confirms that no qualifying protection
exists.
-- **Unknown** — identity, permissions, provider history, or collection
- completeness cannot support a stronger claim.
-
-A backup or snapshot artifact may still be shown while posture is unknown.
-Artifacts answer what Pulse found; posture answers what Pulse can safely claim.
-Snapshot presence alone is never presented as independent recovery.
-
-## Navigating Recovery
-
-### Recovery Events
-
-Shows individual recovery points. Key columns:
-
-| Column | Description |
-|---|---|
-| Time | When the point was created (started/completed) |
-| Subject | What was backed up |
-| Method | Kind + mode of the backup |
-| Outcome | success / warning / failed / running |
-| Size | Size of the artifact (when available) |
-| Verified | Whether the backup has been verified (tri-state) |
-
-### Protection Coverage
-
-The Proxmox **Backups → Coverage** view shows one row per workload. The default
-table stays compact; expanding a row reveals the plain-language posture reason,
-provider evidence quality, and individual restore artifacts.
-
-| Column | Description |
-|---|---|
-| Item | The protected resource (VM name, dataset path, etc.) |
-| Item Type | Canonical resource category |
-| Posture | Protected, attention, unprotected, or unknown |
-| Restore | Most recent successful recovery point timestamp |
-| Provider columns | Latest PBS, PVE, or guest-snapshot artifact where available |
-
-### Filtering
-
-Both workspaces support:
-
-- **Platform filter** — show only points from a specific platform
-- **Outcome filter** — show only failed, successful, or running points
-- **Time range** — filter to a specific time window
-- **Search** — full-text search across items and details
-
-## API Reference
-
-| Method | Endpoint | Description |
+- **Unknown**: identity, permissions or collection completeness cannot support
+ a stronger claim.
+
+A retained artifact can remain visible while posture is unknown. A running
+backup is not a new completed recovery point; inspect any earlier completed
+point separately rather than treating current activity as protection.
+
+## Missing or inconsistent evidence
+
+1. Open the relevant platform view, clear its search and filters, and check the
+ selected connection and organisation. Record the route that is affected.
+2. Inspect connection health, the latest observation time and any collection
+ error. Wait for that provider's configured polling interval, not a fixed
+ 30-second assumption. A green connection badge does not prove that every
+ history or backup read succeeded.
+3. Check the expected artifact in the provider's own inventory using an
+ existing authorised session. Verify its identity, location and permissions;
+ do not grant write or restore permissions merely to fill a monitoring row.
+4. For an **Unknown** posture, expand the coverage row and use the specific
+ limiting evidence. Resolve that collection or identity gap; do not turn
+ retained artifacts into a protection claim by clearing Pulse history.
+
+If the guest stopped responding during backup, preserve the task's warning or
+thaw error and the observations already available. Do not repeat the backup,
+reset the guest, or run active guest-agent probes just to reproduce it. Use
+the provider's recovery procedure and a separate trusted guest console to
+assess guest liveness and thaw, not Pulse's backup badge.
+
+When reporting missing records, share the failing view, running Pulse version,
+affected provider, time range, expected reading and relevant redacted error.
+Use consistent placeholders for private hostnames, datasets and IDs. Do not
+share full backup inventories, request headers, tokens, cookies or recovery
+keys. See [safe issue reporting](TROUBLESHOOTING.md#getting-help).
+
+## API reference
+
+These are read-only monitoring endpoints. Use an existing authenticated browser
+session or a `monitoring:read` token supplied through a private header file,
+never a token in a URL or diagnostic command argument. See [API access](API.md).
+
+| Method | Endpoint | Result |
|---|---|---|
-| `GET` | `/api/recovery/points` | List individual recovery points |
-| `GET` | `/api/recovery/rollups` | List subject rollups (protection coverage) |
-| `GET` | `/api/recovery/postures` | List canonical per-resource protection postures |
-| `GET` | `/api/recovery/series` | Time-series data for recovery charts |
-| `GET` | `/api/recovery/facets` | Available filter facets (providers, kinds, outcomes) |
+| `GET` | `/api/recovery/points` | Paged recovery points |
+| `GET` | `/api/recovery/rollups` | Paged subject summaries |
+| `GET` | `/api/recovery/series` | Completed-point counts grouped by day |
+| `GET` | `/api/recovery/facets` | Filter values from matching points |
+| `GET` | `/api/recovery/postures` | Canonical resource postures and limiting evidence |
-### Query Parameters
+### Point and rollup filters
-All recovery endpoints support:
+Points, rollups, series and facets accept these filters:
-| Parameter | Description |
+| Parameter | Values or meaning |
|---|---|
-| `provider` | Filter by provider (`pve`, `pbs`, `truenas`, `k8s`) |
-| `kind` | Filter by kind (`backup`, `snapshot`, `replication`) |
-| `outcome` | Filter by outcome (`success`, `failed`, `warning`, `running`) |
-| `since` | ISO 8601 timestamp — only points after this time |
-| `until` | ISO 8601 timestamp — only points before this time |
-| `subject` | Filter by subject reference |
-| `limit` | Max results (default: 500) |
-
-`/api/recovery/postures` has a deliberately bounded table contract. Supply one
-or more repeated `resourceId` parameters for a resource or batch lookup (at
-most 200), or omit them for a paged list. It also accepts `state`, `page`, and
-`limit`; `state=attention` returns the actionable attention list. The response
-includes the posture policy and provider evidence states so clients do not
-re-derive trust from raw artifacts.
-
-## Troubleshooting
-
-### No recovery data showing
-
-1. Verify at least one data source provides backup/snapshot data:
- - **PBS**: Ensure a PBS connection exists in Settings → Infrastructure.
- - **TrueNAS**: Ensure a TrueNAS connection exists in Settings → TrueNAS.
- - **PVE**: Local backups from PVE are included automatically.
-2. Wait one polling cycle (~30 seconds) for data to appear.
-3. Check the source filter — make sure you're not filtering to an empty source.
-
-### PBS backups showing but not TrueNAS snapshots (or vice versa)
-
-Check the **Source** filter on the Recovery page. Each provider surfaces its recovery points independently. Clear all filters to see everything.
-
-### Recovery points showing as "failed"
-
-Click the row to expand the details drawer, which shows the provider-specific error message. Common causes:
-
-- **PBS**: Datastore unreachable, verification failed, prune job errors
-- **TrueNAS**: Replication target unreachable, dataset locked, insufficient space
-- **PVE**: Backup storage full, vzdump process error
-
-### Current backups show an unknown posture
-
-Expand the workload row and inspect the limiting evidence. Pulse uses unknown
-when the current poll cannot prove provider-history completeness, permission
-scope, or subject identity. Fix the reported collection or access gap and wait
-for the next provider poll; Pulse does not promote retained backup artifacts to
-protected while that uncertainty remains.
-
-## See Also
-
-- [PBS Integration](PBS.md) — Proxmox Backup Server monitoring
-- [TrueNAS Integration](TRUENAS.md) — TrueNAS snapshot and replication monitoring
-- [Unified Resource Model](UNIFIED_RESOURCES.md) — how recovery integrates with the unified model
+| `platform` | `proxmox-pve`, `proxmox-pbs`, `truenas` or `kubernetes`; `provider` is an alias |
+| `kind` | `backup`, `snapshot` or `other`; TrueNAS replication results use `backup` |
+| `mode` | `local`, `remote` or `snapshot` |
+| `outcome` | `success`, `warning`, `failed`, `running` or `unknown` |
+| `from` | Lower time bound in RFC3339, for example `2026-10-01T00:00:00Z` |
+| `to` | Upper time bound in RFC3339 |
+| `subjectResourceId` | Exact linked resource identity; `itemResourceId` is an alias |
+| `rollupId` | Exact subject summary identity |
+| `q` | Text search; `query` is an alias |
+
+For example, this relative browser request selects PBS backup records within
+the stated time bounds without putting a credential in the URL:
+
+```text
+/api/recovery/points?platform=proxmox-pbs&kind=backup&from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z&page=1&limit=100
+```
+
+Use `from`/`to`, not `since`/`until`, and `subjectResourceId`, not `subject`.
+Unrecognised query names do not apply those filters. Invalid `from` or `to`
+values return an error rather than an empty result.
+
+Points and rollups accept `page` (starting at 1) and `limit` (default **100**,
+maximum **500**). Their response has a `data` array and `meta` pagination;
+inspect every required page rather than assuming the first is the inventory.
+Series and facets return aggregate data, not that paged-list contract.
+
+### Posture lookup
+
+`/api/recovery/postures` uses a separate filter contract. Repeat `resourceId`
+for a batch of at most **200** resource IDs, or omit it for a paged list.
+`state=attention` selects attention postures; `page` and `limit` control list
+pagination. Its response includes policy and provider evidence states. Do not
+apply point filters to this endpoint or re-derive posture from artifact count.
+
+## See also
+
+- [PBS integration](PBS.md) — access, data sources and host History
+- [TrueNAS integration](TRUENAS.md) — snapshots and replication monitoring
+- [VM disk monitoring](VM_DISK_MONITORING.md) — guest-agent and backup safety
+- [Migrating Pulse](MIGRATION.md) — configuration transfer versus a full-state backup of Pulse itself
diff --git a/frontend-modern/src/utils/__tests__/recoveryHelp.test.ts b/frontend-modern/src/utils/__tests__/recoveryHelp.test.ts
new file mode 100644
index 0000000000..6af454d0ad
--- /dev/null
+++ b/frontend-modern/src/utils/__tests__/recoveryHelp.test.ts
@@ -0,0 +1,108 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+import { renderDocMarkdown } from '@/features/docs/docMarkdown';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const read = (relative: string): string => readFileSync(path.join(repoRoot, relative), 'utf8');
+const guide = read('docs/RECOVERY.md');
+
+describe('recovery help', () => {
+ it('separates backup evidence from thaw and tested recovery in the shipped guide', () => {
+ expect(read('frontend-modern/public/docs/RECOVERY.md')).toBe(guide);
+ expect(guide).toContain('Pulse does not restore workloads from these views.');
+ expect(guide).toContain('OK status is not confirmation that the guest has thawed.');
+ expect(guide).toContain('only after independently confirming guest thaw');
+ expect(guide).toContain('Pulse monitoring and alert\ndelivery are unavailable');
+ expect(guide).toContain('restore to an isolated destination');
+ expect(guide).toContain('Do not overwrite the live\nworkload');
+ expect(guide).toContain('an omitted value supplies no verification result');
+ expect(guide).toContain('An unknown outcome is not success');
+ expect(guide).not.toContain('What can I actually recover?');
+ });
+
+ it('points to existing platform views and a usable backup-safety heading', () => {
+ expect(guide).toContain('There is no top-level Recovery page.');
+ expect(guide).toContain('**Proxmox → Backups** (`/proxmox/backups`)');
+ expect(guide).toContain('**TrueNAS → Protection** (`/truenas/protection`)');
+ const proxmox = read('frontend-modern/src/features/proxmox/ProxmoxBackupsTable.tsx');
+ expect(proxmox).toContain("label: 'By date'");
+ expect(proxmox).toContain("label: 'Coverage'");
+ expect(read('frontend-modern/src/features/truenas/truenasPageModel.ts')).toContain(
+ "path: '/truenas/protection'",
+ );
+ const rendered = document.createElement('article');
+ rendered.innerHTML = renderDocMarkdown(guide, 'RECOVERY');
+ const safety = rendered.querySelector('a[href="/docs/VM_DISK_MONITORING#backup-safety"]');
+ expect(safety?.textContent).toBe('backup safety precaution');
+ const target = document.createElement('article');
+ target.innerHTML = renderDocMarkdown(read('docs/VM_DISK_MONITORING.md'), 'VM_DISK_MONITORING');
+ expect(target.querySelector('#backup-safety')?.textContent).toBe('Backup safety');
+ });
+
+ it('documents actual point filters and an example the handlers consume', () => {
+ const handlers = read('internal/api/recovery_handlers.go');
+ const model = read('internal/recovery/model/types.go');
+ const section = guide.split('### Point and rollup filters')[1].split('### Posture lookup')[0];
+ const table = section.split('For example,')[0];
+ const parameters = [...table.matchAll(/^\| `([^`]+)` \|/gm)].map((match) => match[1]);
+ expect(parameters).toEqual([
+ 'platform',
+ 'kind',
+ 'mode',
+ 'outcome',
+ 'from',
+ 'to',
+ 'subjectResourceId',
+ 'rollupId',
+ 'q',
+ ]);
+ for (const parameter of parameters) {
+ expect(handlers).toContain(`qs.Get("${parameter}")`);
+ }
+ const example = section.match(/```text\n([^\n]+)\n```/)?.[1];
+ expect(example).toBeDefined();
+ const request = new URL(example!, 'https://pulse.example.invalid');
+ expect(request.pathname).toBe('/api/recovery/points');
+ expect([...request.searchParams.keys()]).toEqual([
+ 'platform',
+ 'kind',
+ 'from',
+ 'to',
+ 'page',
+ 'limit',
+ ]);
+ expect(request.searchParams.get('platform')).toBe('proxmox-pbs');
+ expect(model).toContain('ProviderProxmoxPBS Provider = "proxmox-pbs"');
+ expect(model).toContain('DefaultListPageLimit = 100');
+ expect(model).toContain('MaxListPageLimit = 500');
+ expect(section).toContain('default **100**');
+ expect(section).toContain('maximum **500**');
+ expect(section).toContain('Unrecognised query names do not apply those filters');
+ expect(request.searchParams.has('token')).toBe(false);
+ });
+
+ it('keeps read-only endpoints and posture batch lookup distinct from point filters', () => {
+ const routes = read('internal/api/router_routes_monitoring.go');
+ const handlers = read('internal/api/recovery_handlers.go');
+ const endpoints = [...guide.matchAll(/^\| `GET` \| `([^`]+)` \|/gm)].map((match) => match[1]);
+ expect(endpoints).toEqual([
+ '/api/recovery/points',
+ '/api/recovery/rollups',
+ '/api/recovery/series',
+ '/api/recovery/facets',
+ '/api/recovery/postures',
+ ]);
+ for (const endpoint of endpoints) {
+ expect(routes).toContain(`HandleFunc("${endpoint}", RequireAuth`);
+ }
+ expect(guide).toContain('`monitoring:read` token supplied through a private header file');
+ const posture = guide.split('### Posture lookup')[1].split('## See also')[0];
+ expect(posture).toContain('Repeat `resourceId`');
+ expect(posture).toContain('at most **200**');
+ expect(handlers).toContain('const maxProtectionPostureResourceIDs = 200');
+ expect(posture).toContain('Do not\napply point filters to this endpoint');
+ });
+});