diff --git a/docs/user/ptychography/flomni.md b/docs/user/ptychography/flomni.md
index 37bae2d..fd3d8da 100644
--- a/docs/user/ptychography/flomni.md
+++ b/docs/user/ptychography/flomni.md
@@ -416,12 +416,16 @@ selected per tomo-queue job, so the whole modulated tomogram runs unattended alo
 with any other queued jobs.
 
 A hook is a function `func(flomni, angle)`, called once per projection angle instead
-of the normal acquisition:
+of the normal acquisition. Acquire the actual projection(s) inside it the same way
+`tomo_scan()` would on its own — `tomo_scan_projection(angle)` for a normal
+(Fermat-scan) measurement, or `tomo_acquire_at_angle(angle)` if `tomo_parameters()`
+has single-point mode enabled for this job (see the warning below for why it matters
+which one you call):
 ```python
 def polarizer_modulation(flomni, angle):
-    flomni.tomo_scan_projection(angle, _internal=True)
+    flomni.tomo_scan_projection(angle)
     umv(dev.polarizer, "in")
-    flomni.tomo_scan_projection(angle, _internal=True)
+    flomni.tomo_scan_projection(angle)
     umv(dev.polarizer, "out")
 ```
 
@@ -459,6 +463,22 @@ clear error rather than silently running a plain scan; re-run
 `register_at_each_angle_hook()` for that hook, then call `tomo_queue_execute()`
 again to resume.
 
+**Editing a hook after registering it:** `register_at_each_angle_hook()` stores
+whichever function object you pass it at that moment — it is not a live link to the
+function's name. If you edit the function's source and re-run the `def` in your
+session but do **not** call `register_at_each_angle_hook()` again, the *old* version
+keeps running. Always re-register after an edit.
+
+**`tomo_scan_projection()` vs `tomo_acquire_at_angle()`:** these are not
+interchangeable. `tomo_scan_projection(angle)` always runs a full Fermat-scan
+projection; `tomo_acquire_at_angle(angle)` always runs a single-point acquisition.
+Use whichever matches how `tomo_parameters()` has this job configured
+(`single_point_instead_of_fermat_scan`) — calling the wrong one for the job's mode
+produces the wrong kind of data, and calling `tomo_scan_projection()` directly while
+single-point mode is on prints a warning and asks for confirmation, which will hang
+an unattended queue run. Both `flomni.tomo_parameters()` (CLI) and the params panel
+(GUI) show a reminder of which one to use whenever single-point mode is enabled.
+
 **GUI:** the tomo parameters panel has an "At-each-angle hook" dropdown, listing
 whatever is currently registered from the CLI (`register_at_each_angle_hook()`) —
 the GUI process can't register hooks itself, only select one by name for the job