From e6f427d0fbd53d4d81eccfad67c1c29ad766791f Mon Sep 17 00:00:00 2001
From: Mirko Holler <holler@Mac.fritz.box>
Date: Mon, 13 Jul 2026 09:06:45 +0200
Subject: [PATCH] docs(flomni): document tomo-queue command jobs for operators

Adds a "Command jobs" reference section covering
tomo_queue_add_command(), the move/optimize_idgap action registry, the
mokev/idgap device allow-list, tomo_queue_show() output format, and
the idempotent-vs-prompt crash-resume behaviour, plus a pointer to it
from the quick-start queueing section.
---
 docs/user/ptychography/flomni.md | 52 +++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/docs/user/ptychography/flomni.md b/docs/user/ptychography/flomni.md
index 1bde00c..e43f5d1 100644
--- a/docs/user/ptychography/flomni.md
+++ b/docs/user/ptychography/flomni.md
@@ -86,7 +86,9 @@ Several parameter sets can be queued and run one after another automatically, e.
 1. `flomni.tomo_queue_show()` review the queue before starting.
 1. `flomni.tomo_queue_execute()` run all queued scans in sequence.
 
-If a queued scan is interrupted, the next call to `flomni.tomo_queue_execute()` resumes it automatically rather than starting over, then continues with the remaining entries. See [Tomography](user.ptychography.flomni.tomography) below for the full command reference.
+If a queued scan is interrupted, the next call to `flomni.tomo_queue_execute()` resumes it automatically rather than starting over, then continues with the remaining entries.
+
+The same queue can also hold **command jobs** that reconfigure the beamline between scans (e.g. change energy, then re-peak the undulator gap) instead of running a tomogram, so "scan A, reconfigure, scan B" runs unattended as one queue. See [Tomography](user.ptychography.flomni.tomography) below for the full command reference, including command jobs.
 
 #### If something went wrong…
 
@@ -356,6 +358,54 @@ flomni.tomo_queue_show()
 flomni.tomo_queue_execute()               # runs both, in order, on this sample
 ```
 
+#### Command jobs — reconfiguring the beamline between scans
+
+In addition to tomogram jobs, the same queue can hold **command jobs**: an ordered
+list of beamline reconfiguration steps (move a device, ...) that run instead of a
+scan. This is what lets one queue express *"tomogram A, then reconfigure, then
+tomogram B"* unattended, e.g. change energy and re-peak the undulator gap between
+two tomograms on the same sample.
+
+`flomni.tomo_queue_add_command(steps, label=None, idempotent=None)`
+
+- `steps`: a single `{"action": ..., "kwargs": {...}}` dict, or a list of them run in
+  sequence within that one job.
+- `label`: optional name shown by `tomo_queue_show()`, same as for `tomo_queue_add()`.
+- `idempotent`: normally inferred (safe to blindly re-run after a crash only if every
+  step is); override explicitly if needed.
+
+Only actions from a fixed, reviewed registry can be queued — not arbitrary code:
+
+| action | does | parameters |
+| --- | --- | --- |
+| `move` | Move device(s) to absolute position(s). Only devices on the allow-list below can be targeted. | `positions`: `{device: target}`, e.g. `{"mokev": 6.2}` |
+| `optimize_idgap` | Scan the undulator gap over a range and move to the peak. **Not yet implemented (no-op stub).** | `search_range`: mm, default 0.5, range 0–2 |
+
+Devices allowed for `move`: `mokev` (energy, keV), `idgap` (undulator gap, mm). A
+`move` naming any other device is rejected, both when the job is added and again when
+it actually runs.
+
+Example — change energy, then re-peak idgap, before the next tomogram:
+```
+flomni.tomo_queue_add_command(
+    [{"action": "move", "kwargs": {"positions": {"mokev": 6.2}}},
+     {"action": "optimize_idgap", "kwargs": {"search_range": 0.5}}],
+    label="reconfigure to 6.2 keV",
+)
+```
+
+`tomo_queue_show()` lists command jobs alongside tomogram jobs, e.g.:
+```
+[2]    pending  reconfigure to 6.2 keV  CMD move{'positions': {'mokev': 6.2}} > optimize_idgap{'search_range': 0.5}  [idem]
+```
+
+If a command job is interrupted by a crash, there is no per-step resume point — the
+whole job is either safe to redo from the top or it isn't:
+- If every step is idempotent (the usual case — an absolute move is harmless to
+  repeat), `flomni.tomo_queue_execute()` silently re-runs the whole job from the top.
+- If any step is not idempotent, you are asked whether to re-run the job from the top
+  or mark it done as-is.
+
 ### Sample storage and transfer
 
 [See short version](user.ptychography.flomni.transfer)