docs(omny): make the sample storage widget the primary workflow, CLI a reference section

The "Managing sample storage" section documented dev.omny_samples.*
calls as the normal way to view/edit storage, but day-to-day usage is
now the OMNY Sample Storage GUI widget (added from BEC Widgets' widget
palette) -- documented this session's right-click actions (Change
sample.../Clear/New sample.../Set parking slot...), the measured-status
badges, and that measured status is intentionally CLI/scan-only, not
settable from the widget.

Split into three subsections: widget usage (primary), sample transfer
(still CLI -- the widget only edits the record, it doesn't drive
hardware), and a "CLI reference for sample storage" section for
scripting/GUI-unavailable cases, updated with the owner parameter and
the measured-status+account otransfer_* commands added this session.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Mupip8x7Hean6E3FFvpbj

docs/user/ptychography/omny.md

@@ -62,14 +62,8 @@ If this error happens after a sample was mounted or unmounted, it is important t
 (user.ptychography.omny.samples)=
 ### Sample storage and transfer
 
-Following commands will provide help within BEC:  
-- `omny.otransfer_help()`	print help related to sample transfer
-- `dev.omny_samples.help()` print help related to sample storage
-
-#### Managing sample storage
-
-The sample holders used are [OMNY pins](https://www.dora.lib4ri.ch/psi/islandora/object/psi:4528). These are instsalled in sample transfer shuttles, which can load up to six pins. These shuttles are transferred via a vacuum load lock to the vacuum chamber. The loading procedure can be handled at room temperature or under cryogenic conditions.  
-The thee __shuttles__ that exist are named __“A”, “B”, “C”__. The __pin positions__ within a shuttle are number __1 to 6__ according to the following sketch:
+The sample holders used are [OMNY pins](https://www.dora.lib4ri.ch/psi/islandora/object/psi:4528). These are installed in sample transfer shuttles, which can load up to six pins. These shuttles are transferred via a vacuum load lock to the vacuum chamber. The loading procedure can be handled at room temperature or under cryogenic conditions.  
+The three __shuttles__ that exist are named __“A”, “B”, “C”__. The __pin positions__ within a shuttle are numbered __1 to 6__ according to the following sketch:
 
 ```{figure} omny_shuttle.png
 OMNY sample shuttle
@@ -83,34 +77,27 @@ Each shuttle can be placed in a __parking slot__ in OMNY. The parking slots are
 OMNY parking station
 ```
 
-The status of the sample storage has to be correct in BEC. This means that the status of OMNY pins within OMNY ("O") as well as the shuttles has to be correct, the pin status within the shuttles ("A", "B", "C"), as well as the status of the shuttles within the OMNY parking.  
-This loading status is handled via a OMNY samples device: `dev.omny_samples`
+The status of the sample storage has to be correct in BEC. This means that the status of OMNY pins within OMNY ("O") as well as the shuttles has to be correct, the pin status within the shuttles ("A", "B", "C"), as well as the status of the shuttles within the OMNY parking.
 
-Within the BEC client session `dev.omny_samples.help()` will display all required commands with a short explanation.
+#### Viewing and adjusting sample storage (widget)
 
-To get an overview use `dev.omny_samples.show_all()` or `omny.otransfer_show_all()`
+Day to day, sample storage is viewed and adjusted through the __OMNY Sample Storage__ widget in the BEC GUI, not the CLI — add it from BEC Widgets' widget palette if it isn't already part of your layout.
 
-Modify a slot position of systems "A", "B", "C", "O":  
-`dev.omny_samples.unset_sample_slot('system',position)` free a sample position.  
-`dev.omny_samples.set_sample_slot('system',position,'name')` set a sample position. The sample has to get a _name_.  
+The widget shows every position (shuttle pins A/B/C, fixed "O" positions, the gripper, and the sample stage) with its occupied state, sample name, owner, and measured status (unmeasured / ◐ started / ✓ completed). The parking-carousel view also shows which shuttle is in which parking slot and marks the currently __ACTIVE__ one (oparkz is physically sitting there, ready for transfer).
 
-There are two __special sample slots__:  
-If a sample is in the __gripper__ and the information has to be manually changed use  
-`dev.omny_samples.unset_sample_in_gripper()`  
-`dev.omny_samples.set_sample_in_gripper('name')`
+Right-click a slot for:
+- __Change sample…__ — set a new name and owner for an occupied slot (replaces the sample record, including resetting its measured status back to unmeasured — use this when a physically different sample is now there, not to correct a typo in the current one's account).
+- __Clear (set empty)__ — mark a slot empty after physically removing the sample. Only offered for shuttle slots, since only samples in a shuttle can leave vacuum: this also offers to print a P-touch label for the sample that was just removed.
+- __New sample…__ — occupy an empty slot with a name and owner.
+- __Set parking slot…__ / __Clear parking assignment__ (shuttle labels) — record which parking slot a shuttle occupies; a slot already held by a different shuttle is rejected, clear it there first.
 
-In the case of the sample stage position, the commands are  
-`dev.omny_samples.unset_sample_in_samplestage()`  
-`dev.omny_samples.set_sample_in_samplestage('name')`
+Measured status itself (unmeasured/started/completed) is set automatically as part of a tomographic scan, or from the CLI (see reference below) — it is intentionally not settable from the widget.
 
-The shuttles are mounted in the parking station. Typically oparkz slot 3 is used for shuttle A, slot 4 for shuttle B, slot 5 for shuttle C. If that status has to be modified, the following commands can be used:  
-`dev.omny_samples.unset_shuttle_slot(slot_nr)`  
-`dev.omny_samples.set_shuttle_slot(container, slot_nr)`  
-Here is an _example_: dev.omny_samples.set_shuttle_slot('A',2)
+Use `omny.otransfer_show_all()` from the CLI for the same overview as plain text (useful when the GUI isn't available).
 
 #### Sample transfer
 
-Once the sample places are set correctly and checked by using `omny.otransfer_show_all()`, the following commands are available for sample change. To pick a sample from a parking slot, the parking slot stage has to be moved to the correct parking slot position. If a parking position is active, this information is displayed in sample storage overview.
+Physically moving samples still goes through the CLI — the widget only edits the storage record, it does not drive hardware. Once the storage record is correct (check with the widget or `omny.otransfer_show_all()`), the following commands are available for sample change. To pick a sample from a parking slot, the parking slot stage has to be moved to the correct parking slot position first. If a parking position is active, this is shown in the widget (and in `otransfer_show_all()`'s text overview).
 
 | Command | Explanation |
 | --- | --- |
@@ -132,6 +119,33 @@ Advanced commands ... in case something goes wrong
 
 When closing a shuttle of the shield, the gripper will be moved to the parking position prior closing.
 
+#### CLI reference for sample storage
+
+Not part of the normal workflow above (that's the widget) — kept here for scripting, and for the rare case the GUI isn't available. All of it lives on the OMNY samples device, `dev.omny_samples`; `dev.omny_samples.help()` prints the same reference with argument details from within a BEC session, and `omny.otransfer_help()` includes it too.
+
+Modify a slot position of systems "A", "B", "C", "O" (owner is optional, defaults to empty; setting a slot resets its measured status to unmeasured):  
+`dev.omny_samples.unset_sample_slot('system', position)` free a sample position.  
+`dev.omny_samples.set_sample_slot('system', position, 'name', 'owner')` set a sample position.
+
+There are two __special sample slots__:  
+If a sample is in the __gripper__ and the information has to be manually changed use  
+`dev.omny_samples.unset_sample_in_gripper()`  
+`dev.omny_samples.set_sample_in_gripper('name', 'owner')`
+
+In the case of the sample stage position, the commands are  
+`dev.omny_samples.unset_sample_in_samplestage()`  
+`dev.omny_samples.set_sample_in_samplestage('name', 'owner')`
+
+The shuttles are mounted in the parking station. Typically oparkz slot 3 is used for shuttle A, slot 4 for shuttle B, slot 5 for shuttle C. If that status has to be modified, the following commands can be used:  
+`dev.omny_samples.unset_shuttle_slot(slot_nr)`  
+`dev.omny_samples.set_shuttle_slot(container, slot_nr)`  
+Here is an _example_: dev.omny_samples.set_shuttle_slot('A',2)
+
+Measured status/account (normally set automatically during a tomographic scan) can be read and, if really needed, corrected manually via the `omny.otransfer_*` wrappers, e.g.:  
+`omny.otransfer_get_sample_status('system', position)` / `otransfer_get_sample_status_in_gripper()` / `otransfer_get_sample_status_in_samplestage()`  
+`omny.otransfer_set_sample_status('system', position, status, account)` (`status` is one of `"none"`/`"started"`/`"completed"`) and the matching `_in_gripper`/`_in_samplestage` variants  
+`omny.otransfer_get_sample_account(...)` and its `_in_gripper`/`_in_samplestage` variants read back the account tied to a "started"/"completed" status.
+
 ### Status of OMNY
 
 To see the status of the insrument, following commands can be used. Most of the components mentioned below are controlled via devices with naming starting with omny. TAB completion on dev.omny can be a quick way to find the commands.