working on todo.md features

src/help/02-source.txt

@@ -6,8 +6,19 @@ interface. Pass it on the command line, or let udpscope ask.
 <b>How to reach it</b>
 
 Run with <tt>--server</tt> and the app connects straight away. Run <i>without</i>
-<tt>--server</tt> and a chooser appears first: the sessions udpscope has stored, newest
-first, plus a <b>New host…</b> form for one it has not seen. The chooser runs before any
+<tt>--server</tt> and a chooser appears first: one row per stored <i>configuration</i>
+(<tt>host:port · name</tt>, its note, and the settings it carries), newest first, plus a
+<b>New host…</b> form that takes the address <i>and</i> the configuration it belongs to — its name
+and note, the <b>buffer size</b>, and whether time is relative or absolute. A row's pencil button
+opens the same form on that configuration, pre-filled, and changes to its name or address move it
+(the old file is deleted).
+
+The second page, <b>Waveforms</b>, opens an <i>exported</i> run instead of a live source: the files
+opened before (newest first; one that has since been deleted is marked <i>missing</i>) and an
+<b>Open…</b> button for a new one. The same file can be opened straight from the command line with
+<tt>--open FILE</tt>. A waveform is a source that never arrives — no socket, no acquisition, no
+starvation notice — and every instrument works on it: cursors, measurements, math channels and
+another export. Only <tt>.npy</tt> files are read. form for one it has not seen. The chooser runs before any
 buffer is allocated and before any socket is opened, so declining it costs nothing.
 
 <b>Worth knowing</b>

src/help/03-signals.txt

@@ -13,6 +13,9 @@ the overflow menu opens the editor where the unit and the calibration live.
 
 • Signals start disabled, and enabling one is what starts acquiring it. A trigger on a signal
   nobody acquires can never fire, so arming a trigger enables its signal for you.
+• <b>Calibrate</b> in a signal's row menu opens the gain and offset it is <i>currently</i> drawn
+  through, so a trace already scaled by a gain of 2 shows 2 — pressing <i>Apply</i> confirms it
+  rather than resetting it. A signal nobody calibrated shows the identity, 1 and 0.
 • Calibration is applied <i>at ingest</i>, so changing it re-plans the buffer and drops the
   history. So does enabling or disabling a signal, and so does a new CONFIG. An empty plot
   for a second after one of those is the ring refilling, not a fault.

src/help/04-layout.txt

@@ -16,6 +16,10 @@ corner leaves it.
 
 <b>Worth knowing</b>
 
+• A plot's own <b>right-click menu</b> (the same compact rows as the app's menu) holds the
+  y-axis scale, the two fits, and <b>Remove signal</b>, which swaps the menu to that plot's traces
+  plus <i>All traces on this plot</i> — with a <b>Back</b> row to return. That is how a trace comes
+  off a row without going through the layout editor.
 • A drop <i>adds</i> a trace to the row's next free slot; it does not replace one. With four
   traces already on a row the drop is refused.
 • Inserting a row moves the rows below it <i>with their contents</i>. Inserting above row 1

src/help/08-trigger.txt

@@ -14,6 +14,27 @@ share. <b>Arm</b> starts watching; <tt>a</tt> arms and disarms from the keyboard
 
 <b>Worth knowing</b>
 
+• <b>Every triggered acquisition is kept.</b> Latches are written to the event cache
+  (<tt>~/.cache/udpscope/&lt;source&gt;/events/</tt>) as a <tt>.npy</tt> of the event, a
+  <tt>.txt</tt> of what it was, and a <tt>.bmp</tt> picture drawn from the samples. The
+  <b>Events</b> pane on the left -- opened from the toolbar's event-history button, which appears
+  while recording is enabled, and collapsed until you ask for it -- lists the last 32 newest first
+  (time, duration, signals, rate), each row with its own picture beside the numbers. Clicking a row
+  <i>replays</i> it: the stored event is loaded exactly like an exported file, <b>without changing the
+  layout</b> -- the rows, the colours, the window, the cursors and the measurements stay where they
+  are and read the stored data instead. A replay leaves trigger mode, because a file has no edge to
+  wait for, and the pane stays open. Drag the pane's edge to resize it. <b>Live</b> goes back to the
+  stream; the status bar names the file until you do.
+  Select two or more events in the list and the two buttons under the header act on them:
+  <b>Compare</b> puts two events in two plots side by side, keeping the layout you have -- one plot per
+  event, the axes synchronised, so zooming a row in one zooms the same row in the other -- and
+  <b>Accumulate</b> overlays up to four of them in the same traces, translucent, so where they agree
+  the trace is brighter. Your own traces stay where they are in both. They need events with the same
+  signals and the same length. A single click selects, a <i>double</i> click replays.
+  <b>Record events</b>, in the trigger panel with the trigger's other options, is what decides whether
+  anything is kept. It is <b>off by default</b> -- nothing is written to disk until you ask -- and
+  with it off the history button goes with it.
+
 • Arming <i>enables</i> the signal if it was off, because a trigger on a signal nobody acquires
   can never fire.
 • The pre-trigger share is a share of the <i>display window</i>, not of the ring. A 2 s window

src/help/13-sessions.txt

@@ -1,34 +1,60 @@
 <b>Sessions and settings</b>
 
-udpscope stores one session file per source, so reopening a source gives you the scope you
-closed. There is no global preferences file: the session <i>is</i> the settings.
+udpscope stores named sessions — <i>configurations</i> — per source, so reopening a source gives
+you the scope you closed, and one source can hold several arrangements for different experiments.
+There is no global preferences file: the session <i>is</i> the settings.
 
 <b>How to reach it</b>
 
 Nothing to open — the file is written as you work. Its path is in the About dialog, and the
 directory is <tt>$XDG_CONFIG_HOME/udpscope</tt>, or <tt>~/.config/udpscope</tt> when that is
-unset. Each file is named <tt>&lt;host&gt;_&lt;port&gt;.toml</tt>.
+unset. Each source has a directory <tt>&lt;host&gt;_&lt;port&gt;/</tt> holding one
+<tt>&lt;name&gt;.toml</tt> per configuration and an <tt>active</tt> file naming the one it is on.
+
+<b>Configurations</b>
+
+<b>Configurations…</b> in the menu lists the running source's configurations: click a row to open
+it, <tt>×</tt> to delete it, or type a name and a note and press <i>Save this session</i> to keep
+the current arrangement under a new one. Opening a configuration saves the current session first,
+so switching never loses what it switches from.
+
+The startup chooser (start with no <tt>--server</tt>) lists one row per configuration, with its
+note and its settings, so two arrangements of one source are told apart before they open.
+
+A configuration also carries the settings that can only be decided when the buffers are
+allocated: the <b>buffer size</b> (<tt>--buffer-mb</tt>), relative time, and the packet capture's
+ring size. Opening a configuration from the chooser applies all three; switching inside a running
+app applies the rest and says in the status line that these take effect on the next start.
+
+The chooser's form sets the first two for a new host, and its pencil button edits them on an
+existing configuration — along with the name and the note. Renaming a configuration, or editing
+the address it points at, moves it: the old file is removed rather than left behind.
 
 <b>Worth knowing</b>
 
-• What a session persists: the time window, the rows and each row's slot signals, the
-  calibration, which signals are enabled, the math channels with their graphs, and the
-  measurements pane.
+• What a configuration persists: the time window, the rows and each row's slot signals, the
+  calibration, the trace colours, which signals are enabled, the math channels with their graphs,
+  the measurements pane — and the startup settings: buffer size, relative time and the packet
+  capture's ring size.
 • Signal identity is the <i>name</i> throughout, because a new CONFIG renumbers the channels.
 • A file written by a run against a source whose streamer was down would name no signals at all,
   so such a run does <b>not</b> write: a configured session is never overwritten by a run that
-  configured nothing.
+  configured nothing. (The chooser hides such a file for the same reason.)
 • The multicast group and the interface live <i>inside</i> the file, because its name cannot
   carry them. A file from an older build has neither key and loads as unicast on the default
   route.
-• The startup chooser lists only files that name at least one signal, which is what keeps it the
-  sources you configured rather than every port you have ever tested against.
-• Deleting a file is a supported way to start a source over; the chooser's <tt>×</tt> does
-  exactly that.
+• The chooser lists only configurations that name at least one signal, which is what keeps it the
+  sessions you configured rather than every port you have ever tested against.
+• Deleting a configuration is a supported way to start over; the chooser's <tt>×</tt> and the
+  dialog's do exactly that.
+• A session from before configurations existed is imported once as the configuration
+  <tt>default</tt>, and the old file is kept beside the directory as
+  <tt>&lt;host&gt;_&lt;port&gt;.toml.imported</tt>.
 
 <b>Example</b>
 
-Connect to <tt>127.0.0.1:8000</tt>, drop three signals on row 1 and set a 2 s window.
-<tt>~/.config/udpscope/127.0.0.1_8000.toml</tt> now holds <tt>rows=1 window_s=2</tt> with
-<tt>signals = ["sine", "ramp", "noise", ""]</tt>, and the next run reports
-<tt>layout loaded from …/127.0.0.1_8000.toml</tt> with those signals already acquired.
+Connect to <tt>127.0.0.1:8000</tt>, drop three signals on row 1, set a 2 s window, and save the
+session as <tt>bench</tt> with a note. <tt>~/.config/udpscope/127.0.0.1_8000/bench.toml</tt> now
+holds <tt>window_s=2 comment="…"</tt> with <tt>signals = ["sine", "ramp", "noise", ""]</tt>, and
+the next run reports <tt>layout loaded from …/127.0.0.1_8000/bench.toml</tt> with those signals
+already acquired.