docs: the snapshot deletion note does not say a rosbag recording is outside retain_on_clear, or that a device de-assert is a clear

[bburda]

Summary

Two gaps in docs/tutorials/snapshots.rst. The parameters behave as their reference entries say. The note near the top does not.

1. The note says retain_on_clear keeps snapshots. It keeps value snapshots only.

The note: snapshots are deleted when a fault is cleared, set snapshots.retain_on_clear: true to keep them. The parameter table 70 lines later: the parameter keeps a fault's value snapshots. The code agrees with the table. clear_fault in sqlite_fault_storage.cpp guards only DELETE FROM snapshots. The rosbag recording is deleted by RosbagCapture::on_fault_cleared, gated on snapshots.rosbag.auto_cleanup and snapshots.rosbag.max_bags_per_fault. A reader who follows the note sets retain_on_clear: true and still loses the recording.

Measured on 0.7.0, one fault, one recording, alarm de-asserted with no operator action:

config	after the clear
defaults	Auto-cleanup: deleted bag file for fault 'PLC_JAM_INFEED', bag gone
snapshots.retain_on_clear: true	same log line, bag gone
snapshots.rosbag.max_bags_per_fault: 3	no cleanup line, recording kept

2. The note does not say a device de-assert is a clear.

The note names a REST DELETE and the ~/clear_fault service. The OPC UA plugin calls ~/clear_fault itself when an alarm tag goes false. Its README says only "the fault is automatically cleared". So an intermittent PLC alarm deletes its own recording with nobody touching the API:

[INFO] [plugin.opcua]: Alarm cleared: PLC_JAM_INFEED on load_process
[INFO] [fault_manager]: Fault cleared: PLC_JAM_INFEED (auto-cleared 0 symptoms)
[INFO] [fault_manager]: Auto-cleanup: deleted bag file for fault 'PLC_JAM_INFEED'

That is the intermittent-fault case the tutorial names first as the reason to record.

The note also names DELETE /api/v1/faults/{code}, which the gateway does not serve. The per-fault clear is DELETE /api/v1/{entity-path}/faults/{fault_code}. The bare DELETE /api/v1/faults clears all.

Proposed solution

In the note: say value snapshots, point recordings at snapshots.rosbag.auto_cleanup and max_bags_per_fault (configurable since #623), say that a plugin de-assert is a clear, and fix the route. Mirror the de-assert sentence in the OPC UA plugin README.

Additional context

0.7.0 on Jazzy, Ubuntu 24.04, rosbag capture on, OPC UA plugin bridging an OpenPLC-style controller. After the de-assert the fault still answers 200 with status: cleared and keeps its freeze_frame (#491). The rosbag entry, the rosbag_files row and the bag directory are gone. An operator DELETE on the same fault produces the same log lines, both paths land on the one ~/clear_fault handler. Point 2 also reproduces on the 0.6.0 image.