docs: explain the P2P diagnostic workflow

Guide users through Diagnostic summary, Diag logging, transfer progress,
symptom checks, and evidence collection from both devices. Link the guide
from the P2P, troubleshooting, reporting, and documentation entry points.
Keep transport compatibility and observation limits explicit.

Validated with the troubleshooting documentation Inspector, 145 local
references, 34 heading anchors, and current English UI labels. Runtime
source and translations are unchanged.

docs/README.md

@@ -14,7 +14,7 @@ A document's original date and reviewed-version fields describe its baseline. Re
 | Find hosting services proposed by the community | [Third-party hosting listings](../README.md#hosting-services-proposed-by-the-community) |
 | Set up S3-compatible storage | [Object Storage Setup](setup_object_storage.md) and [transfers and service costs](setup_object_storage_costs.md) |
 | Set up peer-to-peer synchronisation | [P2P communication model](p2p.md), then [Peer-to-Peer Setup](setup_p2p.md) |
-| Diagnose P2P connectivity | [Browser-assisted check](../src/apps/webpeer/README.md#p2p-connection-check), [network tips](tips/p2p-sync-tips.md), and [self-hosted TURN](../docker/coturn/README.md) |
+| Diagnose P2P connectivity or transfer activity | [Diagnostic summary and logs](tips/p2p-diagnostics.md), [browser-assisted check](../src/apps/webpeer/README.md#p2p-connection-check), [network tips](tips/p2p-sync-tips.md), and [self-hosted TURN](../docker/coturn/README.md) |
 | Understand a setting or command | [Settings reference](settings.md) |
 | Read or customise synchronisation status | [Status indicators and CSS snippets](tips/status-display.md) |
 | Investigate or recover from a problem | [Troubleshooting](troubleshooting.md), then the relevant [recovery procedure](recovery.md) |

docs/p2p.md

@@ -2,11 +2,11 @@
 
 Peer-to-peer (P2P) synchronisation transfers Vault data between LiveSync devices through WebRTC. It does not require a central database containing a copy of the Vault. It does require a signalling relay so that devices can discover one another and establish a connection.
 
-For the procedure for the first and additional devices, see [Set up peer-to-peer synchronisation](setup_p2p.md). For connection problems, see [Peer-to-Peer Synchronisation Tips](tips/p2p-sync-tips.md).
+For the procedure for the first and additional devices, see [Set up peer-to-peer synchronisation](setup_p2p.md). For connection problems, see [Peer-to-Peer Synchronisation Tips](tips/p2p-sync-tips.md). Use the [P2P diagnostic guide](tips/p2p-diagnostics.md) to investigate discovery and transfer problems with the summary, logs, and progress indicators.
 
 ## Updating a P2P group
 
-The unreleased transport update uses Trystero 0.26.0, whose data format is
+The Trystero 0.26.0 transport uses a data format which is
 incompatible with the previous transport. Update every device in the P2P
 group, including CLI and WebPeer clients, before resuming P2P synchronisation.
 Keeping the same Group ID, passphrase, and relay settings does not make mixed

docs/tips/p2p-diagnostics.md

@@ -0,0 +1,130 @@
+# Diagnose P2P synchronisation
+
+Use **P2P Status** to distinguish peer discovery, authentication, and data
+transfer before changing connection or database settings.
+
+Participating devices must use
+[compatible P2P transport versions](../p2p.md#updating-a-p2p-group).
+If your version does not show **Diagnostic summary**, use
+[Peer-to-Peer Synchronisation Tips](p2p-sync-tips.md) and include the installed
+versions in your report.
+
+## Capture one attempt
+
+1. Keep both devices online, with Obsidian visible and the devices awake.
+   Record which device originates the change and which should receive it.
+2. Open **P2P Status** on both devices, using
+   **Self-hosted LiveSync: P2P Sync : Open P2P Status** in the command palette.
+3. Expand **Diagnostic summary** below **Stats**. It starts collapsed. Record
+   all three rows and their observation times before reconnecting or changing
+   settings.
+4. Turn **Diag** on, then select **Open log**. Clear **Pause** before
+   reproducing the problem. New diagnostic lines contain `[P2P Diag]`;
+   **Verbose Log** is not required for these lines.
+5. Select **Replicate now** for the intended peer to test a manual round trip.
+   Check **P2P Connection Request** prompts on both devices.
+   For a problem with later automatic changes, first establish that the manual
+   operation works, then make a small, non-private test edit on the source.
+   Observe the receiving device as well as the source.
+6. Record the last relevant messages and progress on both devices, then
+   [collect a report](#collect-a-report) before restarting or retrying.
+
+The summary continues updating with **Diag** off. **Diag** controls new detailed
+output in the Log Pane; enabling it does not replay earlier hidden lines.
+Diagnostic messages also enter the existing recent report history while
+**Diag** is off. Opening the Log Pane displays messages already in its display
+buffer. Repeated unchanged non-failure observations may be omitted, so the log
+is not a record of every network message. **Pause** affects only the log display;
+replication and the summary continue updating.
+
+## Read the summary
+
+Each row holds the latest recorded observation in one category on this device.
+A new event from another peer can replace that row. Evidence can remain after
+a peer leaves or a connection closes; use the peer identifier and timestamp
+rather than reading the rows as a current connection-health checklist. The
+summary is held in memory and does not preserve history across a restart.
+
+| Row       | Examples                                                                                                        | What it establishes                                                                                                                                                                   |
+| --------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Relay** | `Room opening`, `Room opened`, `Room could not open`, `Room closed`                                             | The local room lifecycle. `Room opened; relay replies not observed` does not prove that a relay accepted announcements, that a peer was discovered, or that a WebRTC data path works. |
+| **Peer**  | `Peer advertised`, `Peer left`, `Authentication accepted`, `Authentication refused`, `Authentication timed out` | Discovery or the observed authentication outcome for the identified peer. A timeout means the request did not finish in time; it is not an explicit refusal.                          |
+| **Sync**  | `Pull started`, `Pull completed`, `Watching peer changes`, `Announcing changes`, `Change notification received` | The latest observed pull, watch, announcement, or notification activity. A notification asks a peer to fetch; it does not itself carry Vault data.                                    |
+
+- **Not observed** means no event has been recorded for that category. It does
+  not mean success, failure, or a measured zero.
+- **Unavailable** means the diagnostic capability is unavailable in the
+  current implementation. Include the installed version in the report.
+- `Authentication failed; authentication response not observed` and
+  `Automatic watch skipped; peer announcement state not observed` identify an
+  unavailable response, rather than claiming refusal or disabled announcements.
+- Summary times are local observation times. `[P2P Diag]` lines also include an
+  `observed` UTC timestamp. Account for device-clock differences when comparing
+  reports. A timestamp is not a heartbeat or a continuously refreshed health check.
+
+Relay rejection details are not available through this diagnostic summary.
+Some existing RTC diagnostics also lack peer or room attribution and are not
+assigned to a peer in these rows. **Stats** describes connection activity,
+not transferred document or Vault file totals. If the summary cannot explain a
+failure, preserve the logs and state what remains unobserved in the report.
+
+## Understand transfer progress
+
+| Indicator     | Meaning                                                                                                                                                                                                                      |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **↑ / ↓**     | Successfully sent or received database document revisions for the observed peer and direction, including both Metadata and Chunks. These are not counts of Vault files written. A new replication attempt starts new counts. |
+| **⏩↑ / ⏩↓** | Changes-feed entries compared in that direction, including entries already held by the receiver. The count can advance while no revisions need transferring.                                                                 |
+| **seq**       | A compatibility display of database sequence progress when document statistics are unavailable. Interpret it as a sequence value, not a document total or percentage.                                                        |
+
+Each directional comparison label disappears three seconds after its count
+last changes. Its disappearance does not establish that replication completed.
+A zero transfer count can be normal when the receiver already has the data.
+
+`Pull completed` records completion of a single database pull. It does not
+establish that the reverse direction completed, that every peer has caught up,
+or that every received revision has been reflected into a Vault file. Check
+the test note on the receiving device. For missing files, follow
+[the corresponding troubleshooting procedure](../troubleshooting.md#files-are-missing-or-excluded).
+
+## Choose the next check
+
+| Symptom or observation                                          | Next check                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The peer does not appear                                        | Capture the **Relay** and **Peer** rows, then check both devices' compatible versions, relay set, Group ID, and passphrase using [discovery checks](p2p-sync-tips.md#a-peer-does-not-appear). `Connected` alone is insufficient.                                                                                                             |
+| Authentication is refused                                       | Confirm the peer identity and intended approval on both devices. The summary records the outcome; it does not grant approval.                                                                                                                                                                                                                |
+| Authentication times out, or a peer appears but cannot transfer | Keep both devices visible and check for an unanswered **P2P Connection Request** before treating a timeout as a network failure. Compare their logs, then use the existing [WebRTC and TURN checks](p2p-sync-tips.md#a-peer-appears-but-synchronisation-cannot-connect) to investigate the data path.                                        |
+| Manual replication works, but later edits do not arrive         | Confirm **Announce changes** on the source and **Follow changes** for that source on the receiver. Compare `Announcing changes`, `Watching peer changes`, and notification events on both devices. `Change notification ignored; peer is not watched` identifies a missing follow on the receiver.                                           |
+| A pull remains the last observation                             | Compare its timestamp, ↑/↓ and ⏩ changes, and both devices' logs. Another operation may have replaced a summary row; an old `Pull started` or a hidden ⏩ label alone does not establish a stalled transfer. For a repeatable network-specific stall, use [message-size checks](p2p-sync-tips.md#a-connection-opens-but-a-transfer-stalls). |
+
+After capturing the original symptom, **Disconnect** followed by
+**Open connection** and **Replicate now** can test reconnection. Disconnecting
+can cancel an active operation, so record whether a cancellation followed that
+action. Reconnection, a changed message-size preset, or a different network
+helps compare conditions; it does not identify or repair every underlying cause.
+
+## Collect a report
+
+Collect evidence from both the source and receiving devices around the same
+attempt. Include:
+
+- the plug-in or client version on each device, and which device originated the change;
+- the **Diagnostic summary** rows and times, plus the surrounding `[P2P Diag]`
+  lines and any other relevant errors;
+- whether the peer appeared, whether manual **Replicate now** worked, and the
+  observed ↑/↓, ⏩, or `seq` values;
+- whether **Announce changes** and **Follow changes** were enabled, and whether
+  either application was in the background or the device had been asleep; and
+- the network types and whether TURN or a VPN was used, especially when the
+  same devices work on one network but not another.
+
+Run **Generate full report for opening the issue with debug info** before the
+recent history is overwritten. It includes up to 1,000 recent log lines,
+including verbose diagnostic messages even when **Verbose Log** is off.
+For a problem which crosses a restart, follow the existing
+[persistent logging procedure](../to_issue_reporting.md#a-problem-which-crosses-a-restart).
+
+Review the complete report using the
+[issue-reporting redaction guidance](../to_issue_reporting.md#full-livesync-report).
+New `[P2P Diag]` messages use fixed descriptions and shortened peer identifiers,
+but other log messages can still contain private information. Keep consistent
+device aliases across the reports when replacing private identifiers.

docs/tips/p2p-sync-tips.md

@@ -67,6 +67,8 @@ Keep Obsidian visible and the device awake during initial transfer, rebuild, or
 
 ## Collect evidence
 
+Use the [P2P diagnostic guide](p2p-diagnostics.md) to capture the latest observations, enable **Diag**, and compare transfer progress and logs on both devices before changing settings.
+
 If the same room works on one network but not another, include both network types in the report. Run `Generate full report for opening the issue with debug info`, remove credentials and private relay details, and state whether:
 
 - both devices reached `Connected`;

docs/to_issue_reporting.md

@@ -11,6 +11,7 @@ If a maintainer requests additional evidence, follow the relevant procedure belo
 | Database integrity, current conflicts, or differences between sources | [Integrity report](#integrity-report) |
 | Local revision and Chunk usage                                        | [Usage report](#usage-report)         |
 | More information about a path pseudonym in an existing report         | [File follow-up](#file-follow-up)     |
+| P2P discovery, authentication, or transfer activity | [P2P summary and logs](tips/p2p-diagnostics.md#collect-a-report) |
 
 Maintainers can link directly to each procedure and adapt the [example requests](#requesting-diagnostics).
 

docs/troubleshooting.md

@@ -270,7 +270,7 @@ Use Safari on a Mac and follow Apple's [Inspecting iOS and iPadOS](https://devel
 
 ## P2P does not connect or transfer changes
 
-Use [Peer-to-Peer Synchronisation Tips](tips/p2p-sync-tips.md). Check signalling discovery separately from the WebRTC data path, and confirm which devices announce and follow changes. P2P is not a repair step for another transport.
+Start with [P2P diagnostic observations, logs, and transfer progress](tips/p2p-diagnostics.md). Use [Peer-to-Peer Synchronisation Tips](tips/p2p-sync-tips.md) for network and configuration checks. Check signalling discovery separately from the WebRTC data path, and confirm which devices announce and follow changes. P2P is not a repair step for another transport.
 
 ## Obsidian or LiveSync remains suspended