.cursorrules

# JoystickPushTask — Project Plan

Merged 29 Sep 2026 so the Mac planning history and the rig-PC session notes live in one force-tracked `.cursorrules`. The path stays listed in `.gitignore`; because the file is already tracked, later edits still commit and reach the other machine. Do not keep a second untracked copy.

## How to read this file
- The sections from "DAQ overrun" through "Push-task status" came from the rig PC on 27–29 Sep 2026. They are the current operational record.
- "Historical plan" is the Mac copy through 27 Sep 2026: hardware decisions, LabVIEW architecture, training progression, and driver procurement. Keep it. Where it disagrees with the rig notes, follow the rig notes for what is true on the rig today.
- Current overrides (user-confirmed 29 Sep 2026, evening — see the next section):
  - Acquisition Read stays at **10 samples**. Buffer **100000** is installed. The in-loop `stop in` Value property node is deleted. Do not switch the Read to 100.
  - Rest-pad hardware is the **29 Sep** state: tape, 3.15 mm puck, **1 MΩ** divider, threshold about **1 V**, joystick X ghosting onto `ai2`. The 8 Sep "working, ~10 kΩ, tape only" description is obsolete.
  - SingleTact Quartzy request 1 submitted 29 Sep evening: RobotShop calibrated `CS8-1N` (`RB-Pre-11`) only. No tail extender ordered. It is not on the rig yet.
  - Home voltage depends on whether the joystick shaft and object are fitted. Current object-on files are the 28 Sep day-one file and the two FSR shaping files, not the 2.50 V set.
  - The 27-column file order is correct. White/push goes in the columns named X. The historical table that calls X lateral is obsolete.
  - At Run, `Session start spout (V)` is **3.0 V** and the day-one file holds extend and retract at **3.00 V**, so the spout stays extended. Normal Stop still retracts.
  - PVA 1.6 unpowered preflight passed (`H–G` ~105 kΩ, coil ~21 Ω, supply +12 V). Powered testing is blocked: the lab has no 1 A inline fuse, and one must be ordered. Never power the Ledex coil from AO0.

## Live status confirmed by user (29 Sep 2026, evening)

- Full-system bench preset added 30 Sep 2026:
  `parameters/push_bench_full-system.txt` has 20 identical 27-column rows for
  the no-joystick/base-movement test. User clarified that home and start must
  match the older expert-mouse files, not the current object-on day-one file.
  Both zones now exactly match `training/07_expert.txt`: X/push
  2.46–2.54 V, Y/lateral 2.40–2.65 V, `home TO=250 ms`, and
  `start TO=0`. The bench success criterion remains push voltage
  0.00–2.22 V with no end dwell. Each success commands a 50 ms cue,
  500 ms reward delay, spout 0→3 V with 2000 ms settle, 185 ms water
  (~6 µl), 1500 ms consumption, then retracts to 0 V. ITI and movement
  window are both 5000 ms. `mag=0` and `light=0`; this file must not be used
  to energise or commission the unfused Ledex/PVA. Set front-panel
  `Session start spout (V)` to 0 V for this bench test so protraction and
  retraction are visible. The operator can deliberately withhold rest-pad
  contact, withhold the push for one movement window, then complete pushes
  to exercise the gate, timeout/failure path, joystick criterion, complete
  reward path and repeated cycles. `parameters/README.md` now gives the
  no-animal preflight and ordered test procedure, including normal-Stop tests
  from idle and from an active reward sequence. Static validation passed:
  exactly 20 rows, exactly 27 tab-separated columns on every row, and
  `mag=0` throughout before the calibration change; revalidation of the
  revised expert-calibration rows is pending. `parameters/README.md` now
  identifies this as a no-joystick/base-movement test, gives the expert home
  box for manual positioning, and distinguishes its wide 0.00–2.22 V bench
  success range from the narrow expert target. Revised validation passed:
  20 rows, 27 columns each, every row's first 10 fields exactly match
  `07_expert.txt`, and every row retains `mag=0`. At the 30 Sep commit
  checkpoint, `Push Behaviour_MCHALABI.vi` was also modified in the working
  tree. The user explicitly requested committing and pushing everything, so
  that saved binary was included with the bench preset and documentation in
  commit `77065bd` (`Add a full-system bench test preset.`), pushed to GitHub
  `master` on 30 Sep 2026.
- Acquisition loop in `avg joystick and frame trig lick3.vi`: the user rejected the 100-sample read. Logged resolution stays 1 kHz (Read = **10** samples). The sentence below that says to confirm a constant-100 Read was a mistake; ignore it. The input buffer **is** 100000. The in-loop `Bool (strict)` Value property node on `stop in` **is** deleted; `stop all` drives that loop. The `AvailSampPerChan` indicator was not added. A ~25–30 min no-animal run with rewards, stopped without -200279, is still not reported.
- Rest pad: the 29 Sep description is the live one. Tape covers the FSR. A rigid puck, 2 mm tall and 3.15 mm diameter, is glued on the tape over the centre of the active circle. The divider is **1 MΩ** (the 100 kΩ step was skipped). Unloaded `ai2` reads about **0.6–0.825 V** and follows joystick X. Light finger contact does not cross the **1 V** threshold; a slightly stronger touch does. A resting mouse paw did not trigger. Pre-change baselines (0–0.005 V unloaded, ~0.1 V lightest touch, 0.01 V threshold) do not apply.
- Next sensor: Quartzy request 1 for the SingleTact was submitted 29 Sep evening (RobotShop `RB-Pre-11` / `CS8-1N`; no tail extender). Not installed yet. Leave the FSR circuit as it is until that sensor is in hand. Load-cell notes stay fallbacks only.
- Joystick rest voltage changes if the shaft or the object is attached or removed. Remeasure home before loading an older file. For the current object-on setup, the later files are the ones to use:
  `parameters/training/02_micro_push_day1_5s_8ul.txt` (rest about 2.25 V, home 2.225–2.350, `home TO` 1 ms, reward 0.00–2.22, move time 5000 ms, water 240 ms, spout held at 3 V),
  `parameters/training/01_fsr_contact_shaping.txt`, and
  `parameters/training/01_fsr_contact_shaping_0ms.txt`.
  `02_micro_push.txt` and stages 03–08 still use the 2.50 V / `home TO` 250 ms calibration. Do not treat those voltages as the live rest.
- Spout at Run: the later day-one notes are correct. Set `Session start spout (V)` to **3.0 V** before Run so the spout is already extended. In `02_micro_push_day1_5s_8ul.txt`, extend and retract are both **3.00 V**, settle is 0 ms, and consumption is 1500 ms. Normal Stop still commands retract to 0 V. The startup write of 500 (`-200561`) was the cluster-order bug and is treated as fixed.
- Ledex / PVA: commissioning stopped at the fuse. The lab does not have a 1 A inline fuse; the user will order one (preferred: 5×20 mm inline holder plus a separate **1 A** fuse). Do not energise the coil, the PVA, or `MagnetPush_Dev1` until that fuse is in the 12 V positive lead. Unpowered checks already passed and do not need to be repeated for this reason.

## Sync note (29 Sep 2026)
This Mac fast-forwarded `8c93c8c`..`fc9ce7e` (`7ff5f9f` FSR shaping presets and DAQ loop, `79156cd` 1 MΩ / SingleTact plan, `9fba141` SingleTact order links, `fc9ce7e` non-capacitive alternatives). Both `.cursorrules` copies were merged into this file afterward.

## DAQ overrun on `joysticklickframe_push` (29 Sep 2026)

- Live symptom: joystick/FSR indicators sometimes freeze during a run. Stopping
  the push VI then shows NI-DAQmx **-200279**: "The application is not able to
  keep up with the hardware acquisition," task `joysticklickframe_push`,
  RelativeTo = Current Read Position, Offset = 0.
- That RelativeTo/Offset pair is the normal DAQmx Read request for the next
  unread samples. It means unread samples were overwritten. It is not a
  separately configured read-position property.
- After -200279 the task stays faulted, so acquisition does not resume until
  the VI is stopped and started again. The dialog often appears only on Stop
  because that is when the latched error cluster is displayed.
- Task configuration: continuous analog input, 10 kHz, three channels
  (`ai1` Y, `ai0` X, `ai2` FSR). At 10 kHz the default software buffer is about
  10,000 samples, roughly 1 s. `avg joystick and frame trig lick3.vi` reads
  with Analog 2D NChan NSamp, averages, and enqueues `joystick pos`.
- NI-MAX "10 samples/read" applies to the MAX test panel. An unwired LabVIEW
  DAQmx Read "number of samples per channel" is -1 (read all available) and is
  the failure mode named in the error text. On a continuous task, the Timing
  "samples per channel" input sets buffer size; a value of 10 there requests
  about 1 ms of buffer and will overflow whenever the loop jitters.
- Likely stall: the acquisition loop blocks on a finite `joystick pos` enqueue
  while the main loop is inside a reward/consumption wait, a file write, or a
  front-panel update. Highlight execution, probes, and an open helper front
  panel produce the same overflow.
- Plain procedure given 29 Sep, bench-only, no animal, and no second analog
  task running (`rest_pad_test_Dev1` and `joysticklickframe` share the
  PCIe-6321 analog timing engine). Edit `avg joystick and frame trig lick3.vi`:
  1. Before DAQmx Start, insert DAQmx Configure Input Buffer with buffer size
     100000 (~10 s at 10 kHz).
  2. On the DAQmx Read inside the loop, wire number of samples per channel to
     100 (a fixed 10 ms chunk, 100 loops/s). Leave it at 10 only if that loop
     contains the Read, a mean, and a non-blocking enqueue.
  3. Replace the blocking Enqueue in that loop with Lossy Enqueue Element, or
     wire Enqueue timeout 0 and discard the timeout so a full `joystick pos`
     queue cannot stall the Read. Keep charts and file writes out of this loop.
  4. Run idle for several minutes, then through repeated reward cycles. Values
     must keep updating, and Stop must return without -200279.
- Diagram screenshot 29 Sep 15:10 (repo copy last saved 22 Sep; none of the
  above changes applied). Actual cause: a DAQmx Timing property node READS
  `SampQuant.SampPerChan` (10, from NI-MAX) and wires it into DAQmx Read, so
  the loop must run 1000 times/s. Every iteration it also does 4 index/sum/
  divide means, an Enqueue, a global read and two Write-to-Binary-File calls.
  Any Windows/disk hiccup longer than the ~1 s default buffer overflows it.
  The queue is unlimited, so Enqueue is not the blocker.
- Specific fix given: remove that wire, wire constant 100 into Read
  `number of samples per channel`; add DAQmx Configure Input Buffer = 100000
  on the task wire before DAQmx Start. Consequence: joystick file logs one
  averaged sample per 10 ms (100 Hz, same as camera) instead of 1 kHz.
- User rejected the 100-sample read: the 1 kHz logged resolution must stay.
  Revised fix keeps Read = 10 samples and the file format unchanged:
  1. DAQmx Configure Input Buffer = 100000 before DAQmx Start (10 s slack).
  2. Delete the `Bool (strict)` Value property node on `stop in` from the
     acquisition loop. Value property nodes run in the LabVIEW UI thread, so
     front-panel activity can stall a 1000-iteration/s loop; `stop all`
     global alone must drive the loop Stop terminal.
  3. Diagnostic: DAQmx Read property node `Status.AvailSampPerChan` to an
     indicator in the loop. If it stays near 0–10, the loop keeps up. If it
     climbs steadily, the loop is too slow per iteration and a buffer only
     delays failure. If it jumps then recovers, stalls are occasional.
  4. If it still climbs: move the two Write-to-Binary-File calls into a
     separate consumer loop fed by a queue (producer/consumer). This keeps
     one averaged 1 ms sample plus frame count per record.
- User requested beginner steps for the buffer change (29 Sep 17:51). Given:
  Quick Drop (Ctrl+Space) or palette Measurement I/O → DAQmx → DAQmx Advanced
  Task Options → DAQmx Configure Input Buffer; insert it in the purple task
  wire just before DAQmx Start Task (task in/out, error in/out), right-click
  `buffer size` → Create → Constant → 100000, confirm Run arrow unbroken,
  then save.
- User reports the Configure Input Buffer (100000) change is done. Next given:
  delete the in-loop `Bool (strict)` Value property node only (keep the
  `stop in` terminal, which is on the caller's connector pane), Ctrl+B,
  confirm `stop all` → loop Stop terminal, add `AvailSampPerChan` indicator,
  save, then run 10 min idle plus rewards with no animal.
- User reports (29 Sep 18:05) the property node was removed and the VI runs
  normally. The AvailSampPerChan indicator was not added. Because the fault
  was intermittent, treat as provisionally fixed. Before animal use, run a
  no-animal session at least as long as a real session (~25–30 min) with
  rewards, and Stop without error.
- Frame count is read from a global once per loop iteration, so it is
  software-polled rather than hardware-timed to each AI sample. True per-sample
  alignment would need a buffered counter task on `ai/SampleClock`.
- CORRECTED 29 Sep evening by the user: Read stays at **10** samples. Do not
  wire constant 100. Buffer 100000 and deletion of the in-loop `stop in`
  Value property node are both done. The helper binary on `master`
  (`7ff5f9f`, 28229 → 28505 bytes) is that edit. Ignore any instruction in
  this section to confirm or restore a 100-sample Read.
- Repo sync 29 Sep: `.cursorrules` is listed in `.gitignore` but is now
 force-tracked so these notes reach other machines via git. Commit it together
 with rig changes; tracked files are unaffected by the ignore rule.
- Row index 3 of the 2D read does not exist (task has 3 channels), so the 4th
  queue/file value is an empty-array mean (NaN). Pre-existing; not the cause.
- The 100-sample-read idea is withdrawn. It would have turned the 1 ms home
  gate into one 10 ms chunk and dropped the joystick log from 1 kHz to 100 Hz.
  The user kept Read = 10.

## First animal pilot (28 Sep 2026): FSR gate problem

- The first mouse did not reliably activate the rest-pad FSR gate. The push
  requirement was stopped; the session was finished with manual rewards, each
  preceded by the established auditory cue.
- Do not interpret this as demonstrated weakness. Earlier documentation listed
  a provisional 0.10 V starting threshold; the value actually used during the
  28 Sep pilot was 0.01 V and still requires animal-mounted calibration.
- Before the next mouse, with the manual-reward VI stopped, put the push VI in
  Case 0 and record stable FSR voltage ranges for no contact and gentle
  finger/light contact. Confirm the Boolean responds and can remain true for
  at least the pilot file's 100 ms home hold.
- Choose a threshold only if the no-contact and light-contact ranges are
  clearly separated: above baseline/noise and below reliable light contact.
  If finger contact produces no response, troubleshoot sensor/wiring/DAQ. If
  finger contact works but natural paw contact does not separate from baseline,
  inspect pad position/contact mechanics and continue manual cue/reward
  habituation rather than requiring forceful paw pressure.
- For each next animal, observe no-paw and naturally resting-paw voltage before
  allowing push trials. Never press the animal's paw down to satisfy the gate.
- Empty-pad measurement: approximately 0–0.005 V with the live threshold at
  0.01 V. Very light fingertip contact produces no apparent response; the
  lightest manually achievable activation is about 0.1 V, while hard pressure
  trends toward 5 V. This confirms useful electrical dynamic range but shows
  that threshold reduction alone is unlikely to detect a naturally resting
  paw reliably.
- Do not use the FSR-gated push task for the next animal until contact
  sensitivity is improved and validated. Immediate sessions should remain
  manual cue followed by reward.
- First mechanical check: inspect whether protective tape bridges the active
  circle or prevents direct loading. Bench-test a small, rigid, centered
  paw-contact puck/cap that transmits load into the active circle while tape
  and strain relief remain on the inactive perimeter/tail; do not preload or
  glue the sensing circle. Then characterize unloaded noise and light-load
  response again with repeatable small test weights.
- If the centered puck still has an unusable low-force dead zone, bench-test a
  more sensitive divider value or a different sensing technology before
  animal use. Any circuit change requires rechecking 0–5 V range, baseline
  noise, saturation and a threshold with margin; do not improvise it during an
  animal session.
- Before the next pilot, the user repositioned the FSR and requested a minimal
  1 ms home/FSR hold. The live white push-axis rest value is now approximately
  2.25 V. The day-one pilot preset has therefore been revised on 28 Sep:
  push-axis home box 2.225–2.350 V, disabled legacy start box mirrored to the
  same bounds, `home TO = 1 ms`, and rewarded forward zone 0.00–2.22 V
  (operational threshold at 2.22 V). This retains a 5 mV separation between
  the home-box lower edge and reward boundary.
- Treat the 1 ms gate as contact detection rather than a meaningful hold. It
  still requires a stable FSR Boolean for at least one control-loop evaluation;
  bench-test that the repositioned pad starts trials reliably without unloaded
  false starts before using the preset with another mouse.
- Parameter-file validation passed after editing: 250 rows, 27 columns per row,
  and one consistent row definition. `parameters/README.md` now documents the
  revised 28 Sep home bounds, 1 ms gate and 2.22 V reward boundary.
- The next mouse activated the repositioned FSR twice, demonstrating that paw
  activation is possible but currently too difficult for reliable joystick
  training. Proposed intermediate stage: teach FSR contact before introducing
  the joystick requirement.
- Preferred long-term implementation: do not rely solely on a parameter-file
  end box covering the entire joystick range. Although that can produce
  immediate success after Case 0, a paw held on the pad can retrigger rewards
  whenever the state machine returns to Case 0. A robust contact-only mode
  should reward one false-to-true FSR transition and require confirmed release
  below threshold before rearming.
- Implement the intermediate stage in LabVIEW, either as an explicit
  `FSR shaping mode` in the push VI or a dedicated VI that uses the same
  cue-before-water sequence. Joystick position must not be part of its success
  criterion. Include contact debounce/hold, release debounce, a minimum
  inter-reward interval, one cue/water pulse per contact, and normal Stop
  cleanup. Do not run it concurrently with the push VI, manual-reward VI or
  standalone FSR test task.
- User accepts the held-contact retrigger risk for a short, closely supervised
  shaping pilot because FSR activation is currently rare. Added
  `parameters/training/01_fsr_contact_shaping.txt`: 125 identical rows, all
  home/start/end joystick boxes 0–5 V, `home TO = 1 ms`, `end TO = 0`,
  240 ms water (~8 µl), 2 s Case-0 timeout/ITI, 5 s movement window, 50 ms cue,
  fixed 3 V spout and 1500 ms consumption. Within the expected 0–5 V joystick
  range, FSR contact is therefore the only meaningful initiation requirement
  and success should follow without joystick movement.
- This preset is an explicitly supervised fallback, not equivalent to a
  release-to-rearm implementation. Bench-test with hand contact before animal
  use: no contact must give no reward, a brief contact should give one reward,
  arbitrary joystick position within 0–5 V must not matter, and held contact
  may give another reward after each 2 s ITI. Monitor reward count and approved
  water limits; 125 successful rows at ~8 µl cap file-delivered water near
  1.0 ml. Use normal Stop if behavior differs.
- File validation passed: 125 rows, 27 columns per row, one consistent row
  definition and no whitespace errors. Git status also shows
  `Push Behaviour_MCHALABI.vi` modified outside this parameter-file edit;
  preserve that live LabVIEW change and do not overwrite it.
- First live use of the FSR-contact shaping preset produced only two detected
  activations in approximately 15 minutes. This event rate is too low for
  effective contingency learning and confirms that the remaining limitation is
  contact sensitivity/geometry, not the joystick boxes or parameter-file hold.
- Current-session action: stop the FSR contingency with normal Stop rather than
  extending the session, finish with manual cue-before-water rewards if needed,
  and record the two detected contacts. Never press the animal's paw onto the
  FSR.
- Before another animal, observe voltage during an ordinary visible paw contact.
  If it rises reproducibly above unloaded baseline but remains below 0.01 V,
  recalibrate the threshold with measured noise margin. If it remains within
  the 0–0.005 V unloaded range, lowering the threshold cannot separate contact
  from noise; change the mechanical interface or sensing technology.
- Bench priority: center a smooth rigid paw-contact puck smaller than the FSR
  active circle, ensure tape is not bridging the active area, and position the
  pad where the paw naturally bears downward load. Recharacterize unloaded
  noise and light-force response. If naturalistic light loads still cannot be
  distinguished, replace the force gate with a touch/contact method such as a
  validated capacitive or optical sensor before resuming shaping.
- FSR-retention options reviewed against the Interlink 400-series integration
  guide. The FSR 402 has a mechanics-dependent break/activation force around
  0.2 N in the current official guide (older sheets report as low as 0.1 N),
  equivalent to approximately 20.4 g-force and 10.2 g-force respectively,
  explaining why a passively resting paw may leave it open-circuit. The
  manufacturer characterizes it with a centered silicone-rubber actuator; the
  actuator geometry materially affects turn-on force.
- Preferred rescue sequence, bench-only and one variable at a time:
  1. Replace the tape-only contact face with a secured, smooth, centered
     silicone/rubber dome or puck roughly 4–10 mm across, smaller than the
     active circle, without gluing or preloading the active area.
  2. If necessary, use a hinged/levered paw platform with the FSR near the
     fulcrum to mechanically amplify a small paw load while preserving the FSR.
  3. Only if light loading produces some finite resistance, increase the
     divider measuring resistance from the current 10 kΩ under bench
     measurement to improve low-force voltage separation. A larger source
     impedance may require an op-amp voltage follower for reliable multiplexed
     DAQ acquisition; validate baseline, settling/crosstalk and 0–5 V range.
  Software threshold changes cannot detect a genuinely open-circuit sensor.
- Controlled-preload option added after user review: a deliberately engineered,
  adjustable spring-loaded paw platform may preload the centered actuator just
  into the FSR's conductive region, allowing a small additional paw force to
  cross a higher software threshold. This supersedes the blanket prohibition
  only for a bench-characterized mechanism; tape tension, loose weights,
  adhesive on the active circle and uncontrolled clamping remain prohibited.
- Preload validation must be animal-free: increase preload gradually, record
  unloaded output and drift/creep over at least 15–30 minutes, then measure
  repeated very-light added loads. Set the contact threshold only between the
  highest stable preloaded baseline and the lowest repeated added-load value.
  Require clear margin, add a mechanical over-travel stop, and reject the
  design if baseline drifts across threshold, added load does not separate
  reliably, output approaches saturation, or the platform binds.
- Recommended load path: mouse contacts a broad, smooth paw platform; a
  centered 4–10 mm rounded silicone/rubber nub on the platform underside
  contacts the middle of the FSR active circle; the FSR lies flat on a rigid
  backing. The platform must not bottom out elsewhere, and guides/flexures must
  prevent lateral shear. This improves force transfer but does not increase
  total force.
- For true mechanical amplification, hinge the paw platform and put the
  FSR/nub closer to the pivot than the paw-contact region. Approximate gain is
  paw distance from pivot divided by FSR distance from pivot; for example,
  15 mm versus 3 mm gives about 5× FSR force. Combine only with measured,
  adjustable preload and a hard stop, then validate drift and repeated
  light-load separation before animal use.
- Design choice after the failed passive-contact sessions: the levered broad
  paw platform is the better likely final solution because the simple centered
  nub improves force transfer but cannot multiply a paw force that is below the
  FSR break force. Prototype the simple nub first only as a quick bench screen;
  if light test loads still do not register, proceed directly to a low-friction
  lever with a hard stop, adding controlled preload only if amplification alone
  is insufficient.
- Space-constrained lever concepts prepared for physical fit review:
  1. Rail-clamped flexure cantilever: lowest profile and no hinge pin, but gain
     and repeatability depend on strip stiffness.
  2. Side-pivot rigid rocker: easiest lever-ratio adjustment and preferred when
     there is room for a side bracket and long paw arm.
  3. Side-mounted bell crank: moves the FSR off the crowded top surface onto a
     rail side, but requires a precise low-friction pivot.
  4. Remote-sensor pushrod: keeps only a small paw plate near the mouse and
     locates the FSR elsewhere, but adds linkage friction/play and is a last
     choice.
- Final design requires measured available length along the rail, height above
  and below the paw surface, clearance on both rail sides, usable attachment
  faces/holes, and the desired paw-contact location. Use photos from top and
  side with a ruler before fixing dimensions or fabricating.
- Alternative under review: replace the analog FSR with a low-force momentary
  switch beneath a broad paw paddle. This would eliminate FSR threshold,
  nonlinearity and drift and provide a clean digital contact, but switch size
  does not imply low force. Typical tactile and membrane buttons require about
  30–100+ gf and may be substantially harder than the current FSR.
- Suitable category is an ultra-low-force detector/basic switch, momentary
  normally open, preferably micro-load rated. One documented reference is the
  Omron D2MV-01-1C1 pin-plunger model at 0.10 N / 10 gf maximum operating
  force. Ten gf may still be too high for passive paw rest, so mount the switch
  close to the pivot under a broad hinged paddle; a 4:1 external lever would
  reduce nominal paw force to roughly 2.5 gf while retaining a crisp digital
  transition. Verify current availability and the exact datasheet suffix
  before ordering.
- Current DAQ inventory lists P0.2–P0.7 as unused candidates, but select and
  continuity-check one line before wiring. A switch conversion requires a
  defined pull-up/pull-down, digital-input configuration, software debounce,
  replacement of the analog FSR comparison with the digital Boolean, and
  confirmation that the chosen terminal is not driven by any existing task.
  Do not connect or test it while the laser is enabled.
- User clarified that a custom lever/paddle mechanism is not desired because it
  is too difficult to fit and fabricate. Reassess direct replacements only.
  A direct Omron D2MV 10 gf plunger is still approximately the lower published
  FSR activation force and therefore may remain too hard for a passively
  resting paw; common flat tactile buttons are much harder (typically
  100–250 gf), and low-force basic switches commonly remain around 25 gf.
- Preferred no-lever candidate is now a flat capacitive touch electrode/module:
  no moving parts or actuation force, a thin insulated/cleanable paw surface,
  and a digital output suitable for the same logical gate after validation.
  Bench-test sensitivity to a mouse-sized contact area, release detection,
  moisture/lick false triggers, cable movement, nearby grounded metal and
  long-term baseline before animal use. A mechanical button remains acceptable
  only if the intended behavior changes from passive paw rest to a deliberate
  press and its specified operating force is demonstrated achievable.
- Lower-force thin force-sensor search identified a stronger no-lever candidate:
  SingleTact S8-1N / calibrated CS8-1N. It is an 8 mm, 0.30 mm-thick capacitive
  force sensor with 1 N / approximately 100 gf full scale and <0.2% full-scale
  resolution, corresponding to about 0.2 gf nominal resolution—far below the
  current FSR 402's roughly 10–20 gf break force. It is not a resistive FSR,
  but preserves force-based paw gating without a lever.
- The calibrated CS8-1N bundle includes its matched electronics and exposes an
  analog output with a valid 0.5–1.5 V range plus I²C. The analog output could
  potentially replace the present FSR signal on `Dev1/ai2` while keeping an
  analog threshold architecture, subject to a wiring/common-ground review and
  bench validation. Supply specification is 3.7–5 V at about 2.7 mA. Current
  EU reference price is approximately €124.50 direct or €149.54 from
  RobotShop; the uncalibrated standard sensor is approximately €34.50 but still
  requires compatible interface electronics.
- Other conventional resistive FSRs found generally remain around 10–20 gf
  actuation, so they offer little guaranteed improvement. Tekscan FlexiForce
  can be configured for lighter forces but needs a suitable puck and more
  sensitive analog front end. Prefer evaluating the calibrated SingleTact
  bundle first if force—not mere touch—must remain the behavioral criterion.
- Cost correction: the calibrated SingleTact bundle is likely unnecessary for
  a binary paw gate. The uncalibrated S8-1N sensor is €34.50 and requires a
  separate standard electronics board (US reference $43.95), putting a basic
  working set around €75–80 rather than €125–150. Calibration is not needed if
  the only goal is a stable per-animal threshold.
- Cheapest next experiment should precede any sensor purchase: the present
  divider uses 9.88 kΩ, while low-force FSR guidance recommends roughly
  100 kΩ–1 MΩ reference resistance for light-touch applications. Animal-free,
  substitute 100 kΩ first and remeasure unloaded versus very-light loads; this
  should increase high-resistance-region voltage sensitivity by roughly an
  order of magnitude. If trying still larger values, account for NI multiplexed
  analog-input settling/source-impedance error and add a unity-gain buffer if
  necessary. Validate joystick-channel crosstalk, baseline drift and saturation
  before animal use.
- Electrical clarification: changing 10 kΩ to 100 kΩ does not reduce the
  FSR's physical membrane break/activation force. It can reduce the
  *system-level detectable force* only if a light paw already changes the FSR
  from open circuit to a finite but very high resistance. With a 5 V divider,
  an example 5 MΩ FSR gives about 0.010 V through 10 kΩ but about 0.098 V
  through 100 kΩ. A truly open-circuit sensor still produces no signal with
  either resistor.
- The larger resistor also raises leakage/unloaded voltage and makes the output
  approach 5 V sooner at higher force, so the existing 0.01 V threshold cannot
  be retained automatically. After the resistor change, remeasure unloaded
  range, light-load range, drift and channel interaction, then choose a new
  threshold only if those ranges separate cleanly.
- User selected the 100 kΩ divider-resistor experiment as the next step. Perform
  it animal-free with the rig powered down for rewiring. Replace only the
  measured 9.88 kΩ FSR signal-to-ground resistor, verify the connections before
  power-up, then record unloaded, barely-touching and firm-press voltage ranges.
  Do not reuse the 0.01 V threshold. Also watch joystick X/Y while exercising
  the FSR to screen for multiplexed-input settling/crosstalk before animal use.
- Added `parameters/training/01_fsr_contact_shaping_0ms.txt` on 29 Sep at user
  request. It copies the supervised 125-row contact-shaping preset but changes
  column 5 `home TO` from 1 ms to 0 ms. All other values remain unchanged,
  including full-range 0–5 V joystick boxes, 2 s ITI, 240 ms water, 50 ms cue
  and fixed 3 V spout. Zero removes the explicit timed dwell but cannot bypass
  the requirement that FSR contact be sampled/visible during a LabVIEW loop.
  Validation passed: 125 rows, 27 columns per row and `home TO = 0` throughout.
- If force magnitude is not required, a low-cost capacitive touch module is the
  least expensive replacement path. Decision ladder: resistor sensitivity test
  first; inexpensive capacitive touch if contact-only is acceptable; then
  uncalibrated SingleTact plus board only if true low-force measurement remains
  necessary.
- Quartzy/expedited sourcing review on 29 Sep:
  - Fastest publicly evidenced stock: RobotShop Europe lists manufacturer
    `CS8-1N`, RobotShop SKU `RB-Pre-11`, calibrated 8 mm / 1 N sensor plus
    matched I²C/analog board, at €149.54 including tax, with only one unit shown
    in stock and Switzerland available as a shipping destination.
  - Lower-cost official route: PPS/SingleTact EU store sells `S8-1N` for €34.50
    plus the `Standard Electronics` I²C/analog board for €40.00, total €74.50
    before shipping/import costs. Public pages do not state stock or delivery
    time, so request same-day confirmation and express shipping from PPS UK.
  - DigiKey, Mouser, Farnell and RS did not show this part in current searches.
- For the likely Swiss/European lab, Quartzy Shop purchasing is not publicly
  supported (Quartzy documents Shop purchasing as US-labs-only). Add an
  external request in Quartzy using exact manufacturer/catalog numbers and
  vendor URLs, mark “no substitutions,” and ask the lab admin to confirm stock,
  use DHL/UPS express and record the external order in Quartzy. If a Quartzy
  offer/quote appears, expedited shipping can be requested via
  `orders@quartzy.com` before placement.
- Delivery estimate clarification: RobotShop's European logistics location is
  in Venlo, Netherlands and it states orders are generally handled within
  24 hours; exact Swiss delivery is only shown by its cart estimator after a
  postcode and carrier are entered. If the displayed one-unit stock is local
  and express service is selected, use roughly 2–5 business days as a planning
  estimate, subject to customs. Quartzy/lab approval can add unknown time, so
  request immediate approval and explicit express service; do not promise an
  arrival date until the vendor quote/cart confirms it.
- Calibrated CS8-1N replacement scope:
  - Remove the FSR and its 9.88 kΩ divider; do not leave the pulldown loading
    the SingleTact board output.
  - Power the matched board from verified 3.7–5 V and common ground; route its
    0.5–1.5 V analog output to the existing `Dev1/ai2` terminal 65, with common
    ground at AI GND terminal 64, only after a powered-off wiring review.
  - Existing `ai2` RSE 0–5 V acquisition and analog-threshold LabVIEW path can
    remain. Recalibrate baseline/contact threshold; do not reuse 0.01 V.
  - Mechanically mount the 8 mm head flat with a smooth cleanable contact
    surface, protect the 0.30 mm sensor and FFC tail from claws/shear, respect
    the tail bend limit, and strain-relieve/mount the interface board.
  - The board updates at >120 Hz, so DAQ sampling at 10 kHz oversamples it and
    sub-millisecond events are not meaningful; passive paw contacts should be
    long enough.
- Expected effort for the calibrated bundle is moderate rather than a full VI
  redesign: approximately 30–60 minutes electrical replacement, 1–3 hours
  mechanical mounting, then threshold/crosstalk/drift and repeated-contact
  bench validation. Reserve about half a day if connectors and mounting fit.
  The uncalibrated sensor/board may require I²C scaling setup and is therefore
  less suitable when fastest deployment matters.
- Mechanical change reported 29 Sep (corrected): the FSR is covered with tape
  and a rigid puck, 2 mm tall and 3.15 mm diameter, is glued onto the tape
  over the centre of the active circle. Glue does not touch the sensor
  directly. Remaining risks: tape tension can preload the membrane or carry
  load to the inactive rim; a 3.15 mm target is small relative to a mouse
  paw, so the paw may rest on the tape around the puck instead of on it.
- Electrical change reported 29 Sep: the FSR divider resistor was already
  changed from 9.88 kΩ to 1 MΩ (the planned 100 kΩ step was skipped). Mice
  still struggle to activate the gate. Pre-change baselines (0–0.005 V
  unloaded, ~0.1 V lightest manual activation) no longer apply; unloaded,
  light-touch and paw readings with 1 MΩ have not been recorded yet, and the
  threshold currently used with 1 MΩ is unconfirmed.
- 1 MΩ DAQ concern: the PCIe-6321 multiplexes one ADC; NI recommends low
  source impedance (roughly ≤1 kΩ) for full-rate multiplexed scans. The scan
  order is ai1 (Y), ai0 (X), ai2 (FSR) at 10 kHz, and a 1 MΩ source cannot
  settle the ADC sampling capacitor, so ai2 may show ghosting/crosstalk from
  ai0 (a false offset tracking joystick X) and slowed response. Animal-free
  check: with the FSR untouched, sweep the joystick across its range and see
  whether ai2 follows; also compare ai2 with a DMM at the terminal. If it
  does, add a unity-gain op-amp buffer (rail-to-rail, low input bias, e.g.
  0–5 V single-supply) between divider and ai2, or reduce aggregate rate.
- 1 MΩ results, 29 Sep: joystick movement CONFIRMED to change ai2 (ghosting
  from ai0). Unloaded ai2 reads 0.6–0.825 V, mostly carried-over joystick X
  voltage rather than real FSR signal. Light finger touch never triggers;
  slightly stronger touch does. A resting mouse paw did not trigger. Live
  threshold set to 1 V. Output appears to jump straight from baseline to
  above 1 V, with no reachable in-between value: the FSR switches abruptly
  from open circuit to conducting at its break force, so the divider value no
  longer limits sensitivity.
- Conclusion: the resistor route is exhausted. The paw's resting force is
  below the FSR break force even with the tape+puck; no resistor or threshold
  change can detect it. Remaining paths: mechanical (broad plate on puck,
  lever) or a sensor that needs no force (capacitive touch) or much less
  (SingleTact).
- 1 MΩ side effect is a live hazard: because baseline tracks joystick X
  (~30% carry-over), a large X excursion could push ai2 over 1 V and give a
  false FSR contact. Before any further animal use either revert to the
  original ~10 kΩ divider (1 MΩ gives no detection benefit, see above) or add
  a unity-gain op-amp buffer before ai2. Slowing the convert clock cannot fix
  it: 1 MΩ needs roughly millisecond settling. After the change, sweep the
  joystick with the FSR untouched and confirm ai2 stays near 0 V.
- Decision 29 Sep: simple contact is the criterion; Mackenzie vetoed a
  capacitive touch sensor, so the SingleTact S8-1N (8 mm, 1 N) is the chosen
  FSR replacement. Note SingleTact measures force via internal capacitance;
  make sure Mackenzie's objection does not also apply to it.
- SingleTact facts verified from the official manual/quick start: interface
  board pin 1 = Vcc 3.7–5 V, pin 2 = analog out, pin 8 = GND (pins 3/6 = I²C,
  unused for analog). Analog out swings 0–2 V; 0.5 V = no force, 1.5 V =
  rated force, saturates at 2 V; below 0.5 V means tension on the sensor
  (avoid; can damage it). Load on analog out must be >5 kΩ. Update rate up to
  120 Hz, 10-bit (~2 mV steps). Baseline is registered at power-on, so the
  sensor must be unloaded when the board powers up; re-tare = power-cycle the
  board. Overload limit <3× full scale. FFC tail is 50 mm (150 mm extender
  available); insert with contact pads facing up; do not kink the tail, do
  not touch it during operation, and keep grounded metal shields away from it.
  Uncalibrated sensor + standard board works on analog without Arduino; the
  I²C demo app is only needed to change scaling/tare. Force estimate
  ≈ V × rated force / 1.5 (uncalibrated: estimate only).
- Planned wiring (reuses FSR terminals from RIG_INVENTORY): +5 V terminal 8 →
  board pin 1; board pin 8 → AI GND terminal 64; board pin 2 → ai2 terminal
  65. Remove the FSR and the 1 MΩ resistor completely. Add an inline
  connector/switch on the 5 V lead so the board can be power-cycled
  (re-tared) without rebooting the PC. No VI code change expected: only a new
  absolute ai2 threshold. Existing ai2 0–5 V/RSE range already covers 0–2 V.
- Morning procedure (about 3.5 h): 1) bench check on the loose sensor
  (0.5 V unloaded, rises with press); 2) rig powered down: remove FSR and
  1 MΩ, wire board; 3) mount sensor flat on rigid backing with untensioned
  thin cover, tail routed away from paw, board secured, insulated and away
  from water; 4) validate in NI MAX with the push VI stopped: baseline and
  noise, 15–30 min drift, joystick sweep (ai2 must not follow), repeatable
  light weights, finger near/touching tail, wet finger; 5) set threshold
  between highest baseline+noise and lowest light-weight reading; 6) hand
  test in the push VI with the shaping preset, then normal Stop. Expected
  paw signal is small (a few gf ≈ tens of mV above 0.5 V), so the threshold
  margin must come from measured noise/drift, not assumed.
- Quartzy order links checked 29 Sep (fast delivery to Switzerland needed):
  - Preferred single shipment, RobotShop Europe (Venlo NL):
    CS8-1N calibrated 8 mm/1 N sensor + I²C board, SKU RB-Pre-11, €149.54
    incl. EU VAT, "only 1 unit left":
    https://eu.robotshop.com/products/calibrated-capacitive-force-sensor-8mm-1n-022lb
    SingleTact Tail Extender, €30.25:
    https://eu.robotshop.com/products/singletact-tail-extender
    (RobotShop lists its length as 75 mm; the manufacturer's extender is
    150 mm. Confirm length and EU stock before ordering.)
  - Fallback from the manufacturer (PPS UK, Glasgow, EU store): CS8-1N
    https://www.singletact.com/micro-force-sensors/calibrated-sensors/p/cs8-1n
    or cheaper uncalibrated S8-1N €34.50
    https://www.eu.singletact.com/micro-force-sensors/standard-sensors/p/s8-1n
    + Standard Electronics €40.00
    https://www.eu.singletact.com/micro-force-sensor/singletact-electronics/p/electronics-board
    + Tail Extender 150 mm €25.00
    https://www.eu.singletact.com/micro-force-sensor/singletact-electronics/p/singletact-tail-extender
    Stock and delivery times are not shown publicly; request confirmation.
  - Both vendors ship from outside Switzerland, so Swiss import VAT/customs
    apply; the EU-VAT-inclusive prices should drop on export. Request
    DHL/UPS express, "no substitutions".
- 29 Sep, SingleTact ORDER ON HOLD: user points out SingleTact is capacitive,
  which Mackenzie rejected (reason unclear). Distinction to raise with
  Mackenzie: capacitive TOUCH sensors sense the animal's own capacitance
  (proximity, moisture, grounding, cable-movement false triggers);
  SingleTact senses compression of its own internal plates, though the manual
  still warns that touching the tail or nearby grounded metal affects it.
  Clarify the actual objection before ordering either option.
- User decision later 29 Sep: SingleTact is considered fine (it senses its
  own plate compression, not the animal). It remains the preferred sensor;
  the load-cell and other options below are kept only as documented
  alternatives in case Mackenzie's objection turns out to cover it.
- User confirmed 29 Sep evening: they will order the SingleTact. It is not
  installed. The live pad remains the 29 Sep FSR (tape, 3.15 mm puck, 1 MΩ).
- Quartzy request 1 submitted 29 Sep evening (~20:02): RobotShop `RB-Pre-11` /
  manufacturer `CS8-1N`, qty 1, unit price CHF 141.50 (€149.54 incl. EU VAT at
  ~0.946). No tail extender ordered; the sensor's own 50 mm tail is enough for
  now. Admin still places the external order on RobotShop; confirm the one
  listed unit is still in the cart, ex-VAT Swiss export price, and DHL/UPS
  express.
- Non-capacitive alternative with equal or better precision: miniature
  strain-gauge (resistive) single-point load cell under a small paw plate.
  Candidates: Phidgets 3139_0 / CZL639HD, 100 g, about 35×12×4 mm, 3.2 g,
  0.6 mV/V, repeatability ±50 mg, creep 100 mg/h, 3–10 V excitation,
  single-point (shear) type so reading is largely independent of where the
  paw sits on the plate; SparkFun TAL221 100 g, 47×12×6 mm, 0.6 mV/V,
  M3 holes. Mount: bolt the cable end to the rail, small cleanable paw plate
  on the free end, hard over-travel stop (150% safe overload for TAL221,
  120 g max for Phidgets). It is a cantilevered platform, not a pivoting
  lever, so no hinge or friction.
- Load cell output is only ~3 mV full scale at 5 V excitation (~30 µV/g), so
  it needs an analog amplifier to feed ai2 at 0–5 V. Checked options:
  Mantracourt ICA2H (19.5 mm dia, 0.1–5.1 V out, 8.5–28 V supply, 1 kHz
  bandwidth, bridge 0.5–150 mV/V) or Tacuna EMBSGB200-M (0–5 V out, 6–16 V
  supply, selectable gain, ~60 Hz low-pass, 1.3×3.3 in). Both need a separate
  DC supply; do not share the Ledex 12 V supply. With ~50 mV/g after gain, a
  2 g resting paw is ~100 mV, easily thresholded. Reading the bare bridge
  differentially on the DAQ's ±0.2 V range is possible but not recommended
  (few LSB per gram, multiplexed range switching).
- Rejected non-capacitive options: piezo film (detects only changing force,
  not a resting paw); MEMS piezoresistive force sensors such as Honeywell
  FMA (lowest range around 5 N, needs a point-load ball, marginal at a few
  gf). IR reflective/break-beam remains the no-force, non-capacitive backup
  if only paw presence is needed.
- Diagnostic decision for 1 MΩ: if ordinary paw contact still leaves ai2
  within the unloaded range at 1 MΩ, the FSR is effectively open-circuit
  under paw load and further resistor increases cannot help. Then the
  remaining options are mechanical (broad plate on puck, lever) or a
  different sensor (capacitive touch, SingleTact).
- Low-profile, no-lever extension of the puck: a thin, broad, rigid paw plate
  resting only on the puck (guided against tilt/shear, not touching anything
  else) routes all paw load through the puck regardless of where the paw sits.
  It improves force capture but does not multiply force.
- 29 Sep: user now plans to also try the lever idea despite the earlier
  spatial objection; the difficulty is fitting it around the rig. The
  rail-clamped flexure cantilever remains the lowest-profile concept. Design
  still needs measured available length, height above/below the paw surface,
  side clearances, attachment points and paw-contact location (top and side
  photos with a ruler). Test lever gain only after the puck-alone result is
  recorded, one variable at a time.

## Session-data synchronization audit (28 Sep 2026)

Example output set from the 27 Sep test:
`TRIAL_test76666`, `joystick_test76666`, and `REWARD_test76666`.
- `TRIAL_test76666` and `REWARD_test76666` are empty.
- Therefore this example reveals neither file's record format; it only shows
  that no trial or reward records were written during this test.
- `joystick_test76666` is 85,200 bytes, but every byte is zero.
- None of these files contains an embedded start time, end time, elapsed-time
  series, or usable frame-count records.
- Their NTFS creation times are from 12 Aug, showing that creation time is not
  a session-start marker when names are reused. Last-modified times span
  27 Sep 17:51:43.461–17:51:46.210 and provide only a rough filesystem window,
  not precise video synchronization. Each file has one creation timestamp and
  one last-modified timestamp—not separate start- and end-modification times.
  The three creation timestamps are within about 33 ms of one another, which
  is consistent with LabVIEW creating the outputs sequentially at startup.
- The rig already has `frame counter_Dev1` on `PFI8`. Before experimental
  recording, verify that its value is written with each joystick sample and
  map that counter to camera frame number; add explicit session/event timing
  to the output if it is not.
- At 100 Hz, one frame is 10 ms, so the observed 33 ms output-file creation
  spread is already 3.3 frames and is unsuitable for frame-accurate alignment.
  Preferred synchronization is one camera exposure/frame TTL pulse per frame
  into `PFI8`, with the resulting counter value saved beside joystick,
  trial, and reward records. If the camera cannot output TTL, use a DAQ-driven
  LED visible in the video and log the same pulse in LabVIEW; filesystem or
  software timestamps are only a coarse fallback.
- Clarification: NTFS creation timestamps precisely date the OS file-creation
  events, but those events are not proven to coincide with the first LabVIEW
  sample. Camera file creation/frame timestamps likewise must be shown to use
  the same synchronized clock and represent exposure time before absolute-time
  alignment can be treated as frame-accurate. Validate metadata-only alignment
  over repeated starts with an event visible in both streams before relying on
  it.
- Video timestamp example
  `TIMESTAMPS_VIDEO_Rig_Anaconda_2026-09-25_1.npy` contains 6,639 absolute
  Unix timestamps (`float64`), from local 14:52:09.288 to 14:53:15.863
  (66.575 s). Median frame interval is 10 ms (~100 Hz), although several
  irregular intervals occur, including an initial 160 ms gap. These per-frame
  timestamps are suitable for absolute-time alignment if the LabVIEW timing
  reference is tied to the same synchronized clock and the LabVIEW
  file-creation-to-first-sample offset is measured. The `.npy` file itself was
  created near video completion, so its filesystem creation time must not be
  substituted for its first embedded frame timestamp.

## Training decision (27 Sep 2026): first reach-to-push stage

User confirmed 29 Sep evening: rest voltage depends on whether the shaft and
object are fitted. The 2.275–2.425 V / `home TO` 100 ms figures in this
section were an intermediate review. The files to use for the current
object-on setup are the later ones (`02_micro_push_day1_5s_8ul.txt` at about
2.25 V rest, plus the two FSR shaping files). Do not revive the 2.50 V files
for that setup.

The 25 Sep Basecamp plan for the first mouse push session is:
- object about 2 mm from the rest pad;
- object home plus FSR contact held for 100 ms;
- minimal forward displacement within 5 s;
- immediate 50 ms success cue and 8 µl reward;
- maximum 25 minutes per mouse.

The repository's `parameters/training/02_micro_push.txt` does not implement
that exact plan. It currently uses `home TO = 250 ms`, `move time = 30000 ms`,
and `watertime = 185 ms` (~6 µl), with 200 trials. Its discovery target is
otherwise suitable: X-slot push band 2.15–2.45 V, `end TO = 0`, no reward
delay, no magnet and a 50 ms cue.

Recommendation for tomorrow is a separate day-1 Stage 2 variant rather than
silently changing the canonical file: retain the Stage 2 geometry and 200
rows, but use `home TO = 100 ms`, `move time = 5000 ms`, and
`watertime = 240 ms` (~8 µl). Keep the 5 s window for initial discovery unless
pilot observations show many unrelated delayed movements are being rewarded;
then shorten one variable at a time, initially to 2–3 s. Do not assume a
shorter window will accelerate learning if it sharply reduces the number of
reinforced trials. Final file choice remains conditional on the current pilot
results, which were not included in the pasted Basecamp update.

Interactive parameter review for the day-1 variant:
- Columns 1–4 home box: confirmed push/white bounds 2.275–2.425 V after the
  user checked the current live rig; the old ~2.50 V rest calibration is no
  longer applicable to tomorrow's setup. Lateral/red bounds are 0.00–5.00 V.
  Apply the same lateral bounds to the end box when columns 11–14 are reviewed.
- Column 5 `home TO`: confirmed 100 ms. Object-home and FSR contact must both
  remain valid continuously for 100 ms before trial onset.
- Columns 6–10 legacy start box: confirmed to mirror the current home box,
  `2.275, 0.00, 2.425, 5.00`, with `start TO = 0 ms`. Zero dwell keeps this
  legacy stage disabled; the object-home plus FSR gate now initiates trials.
- Columns 11–14 end box: confirmed as `0.00, 0.00, 2.27, 5.00`, a one-sided
  forward threshold with no lateral constraint and no overshoot penalty.
  The 5 mV gap below the 2.275 V home edge is intentionally permissive and
  must be bench-tested for untouched/noise-triggered false successes before
  any animal session.
- Column 15 `end TO`: confirmed 0 ms for day-one discovery, so merely entering
  the end box triggers success; no target hold is required.
- Columns 16–17 magnet settings: confirmed `mag = 0` and `magtime = 25 ms`.
  Resistance remains disabled; 25 ms is an inert placeholder while magnitude
  is zero.
- Column 18 `watertime`: confirmed 240 ms, calibrated to approximately 8 µl
  on the training rig.
- Column 19 `timeout` (Case 0 ITI): user selected 500 ms. With the 100 ms home
  hold, a new trial may begin about 600 ms after success, while the reward loop
  can still be inside its 1500 ms consumption wait. Treat 500 ms as conditional
  on bench validation: force rapid successive successes and verify one cue and
  one water pulse per success with no lost/coalesced occurrence. Do not use it
  with animals if that test fails. Long-term, separate success and failure ITIs
  or a reward-complete gate would be cleaner.
- Column 20 `move time`: confirmed 5000 ms for initial discovery. The clock
  begins after the home/FSR criterion completes, not at paw lift.
- Column 21 `light`: confirmed 0; no light stimulus is used in this stage.
- Column 22 `reward delay`: confirmed 0 ms; reward sequencing proceeds
  immediately when the success cue ends.
- Column 23 `cue duration`: confirmed 50 ms, matching the cue used during
  head-fixation habituation.
- Day-one spout mode: user confirms the spout must already be extended before
  the first trial and remain extended throughout the session. For the trial
  rows, provisionally set both column 24 `spout extend` and column 27 `spout
  retract` to 3.00 V; column 25 settling can then be 0 ms. This alone may not
  override the VI's safe-start retraction command, so bench-test startup and
  establish how 3.00 V is applied before trial 1.
- Proposed VI control for review: add a front-panel DBL such as `Session start
  spout (V)`, default 0.00 V and constrained/clamped to the actuator's 0–5 V
  range. The one-shot startup sequence should write this value instead of a
  hardcoded 0 V and allow the actuator to settle before enabling trial 1.
  Tomorrow's setting is 3.00 V. Water/cue remain LOW and magnet remains 0 V
  during startup; normal Stop must still command a hardcoded 0 V/retract.
- User reports the `Session start spout (V)` front-panel control is now
  implemented. Tomorrow set the FP control to 3.00 V. Columns 24 and 27 are
  confirmed at 3.00 V, so each reward write preserves the extended position.
  Bench-test initial extension before trial 1 and normal-Stop retraction.
- Startup FP-control test failed with NI-DAQmx error `-200561` on
  `LickSpoutMotor_Dev1`: the startup analog write received `500.0`, outside its
  configured 0–5 V range. Stop rather than Continue and do not rerun until the
  startup write's data wire is traced. The value exactly matches tomorrow's
  column-19 timeout (500 ms), strongly suggesting the timeout value/terminal
  was wired or unbundled into the spout write instead of the new 3.00 V FP
  control. Verify the FP value and direct wire at the DAQmx Write data input.
- User observes apparent protraction followed by retraction and suspects file
  column order. The generated row has been validated as 27 columns in the
  documented order; column 19 is 500 and columns 24/27 are both 3.00. Diagnose
  at the loaded `exp para array`: if its labelled fields show timeout=500,
  spout extend=3, settle=0, consumption=1500, retract=3, the loader is correct
  and the DAQ write is miswired. If a spout-labelled field shows 500, fix the
  loader case/Bundle By Name mapping. Establish whether the error appears at
  Run startup or only after a simulated success.
- Correction after block-diagram screenshots: loader case 21 already bundles
  `reward delay` and case 26 already bundles `spout retract`; do not change
  them. The prior loader-swap diagnosis was incorrect. The mismatch between
  the generated file tail (`light=0, delay=0, cue=50, extend=3, settle=0,
  consumption=1500, retract=3`) and the displayed cluster (`delay=3,
  retract=0`) now points to a wrong/stale selected file, manually changed
  values, or a label/caption/cluster issue. Verify the exact loaded path and
  exact last seven values before modifying loader code. The separate 500 V
  error still indicates the startup DAQ write received timeout=500.
- User confirms the exact file is correct and the 500 V error has not recurred,
  but the displayed delay/retract values remain exchanged. Next diagnostic:
  inspect both cluster numerics for underlying Label versus visible Caption.
  Bundle/Unbundle By Name uses the Label; swapped captions or copied-control
  labels can make case 21/26 wiring correct while the front panel appears
  reversed. Also distinguish retraction during an active reward cycle from
  expected 0 V retraction on Stop/error cleanup.
- Root cause identified from Bundle/Unbundle dropdowns: the loader-side and
  water-loop-side parameter clusters have different cluster element orders.
  Their four middle new fields align, but `reward delay` and `spout retract`
  occupy opposite endpoint positions. Because all elements are DBLs, LabVIEW
  can transfer the clusters positionally even though names differ, swapping
  these two values. Do not alter the text-file order or case mappings. Save a
  backup, identify the boundary between the two cluster types, and make the
  water-loop cluster order exactly match the loader cluster. Long-term, use
  one shared typedef for the parameter cluster to prevent recurrence.
- User reports the cluster-order mismatch has been fixed in LabVIEW. Before
  animal use, save the VI and reload the pilot file; verify the loaded/reward
  values are reward delay=0, cue=50, extend=3, settle=0, consumption=1500 and
  retract=3, then trigger repeated successes and confirm the spout stays
  extended, each success gives exactly one cue and one 240 ms water pulse, and
  the 500 V error does not recur.
- Rig test now behaves correctly (0 ms functional reward delay and 3 V
  functional no-retract command), but the FP `exp para array` display still
  shows reward delay=3 and spout retract=0 because its visual cluster layout
  remains positional/old. Do not reorder the now-working functional cluster or
  rename underlying Bundle/Unbundle labels. For a quick safe UI correction,
  use captions only on those two FP numerics and swap the displayed captions;
  long-term, replace duplicate clusters with one shared typedef.
- User reports the two front-panel captions have been corrected without
  changing the now-working underlying labels/cluster mapping.
- Final bench status reported good: the 2.27 V target does not false-trigger
  when the object is untouched, the corrected rig VI executes the intended
  fixed-extended-spout reward path, and the FP captions are accurate. The
  repository now contains the modified `Push Behaviour_MCHALABI.vi`, the
  250-row pilot file and parameter documentation. User requested committing
  and pushing all current tracked task changes to GitHub.
- Commit `f347f72` (`Add the day-one push training preset.`) was pushed to
  GitHub `master`. Immediately afterward, the still-open LabVIEW VI changed
  again (binary size 251779 → 251771 bytes), leaving the working tree dirty.
  Do not claim everything is pushed until the user saves/closes the VI and the
  final binary is committed in a new commit and pushed.
- User saved and closed the VI. Final binary commit `8c93c8c` (`Finalize the
  day-one push VI controls.`) was pushed to GitHub `master`; the repository is
  clean and synchronized with `origin/master`.
- Git for Windows was upgraded at the user's request from 2.16.1.windows.4 to
  2.55.0.windows.3 and verified.
- Column 25 `spout settle`: confirmed 0 ms because the spout is pre-positioned
  and remains stationary at 3.00 V throughout the session.
- Column 26 `consumption`: confirmed 1500 ms. With no spout retraction this is
  not an access-duration control, but it keeps the occurrence-driven reward
  loop occupied for 1.5 s after water; coordinate column 19 so a new success
  cannot arrive before that loop is ready.
- File row count: revised to 250 trial rows so the user can monitor reward
  count manually rather than letting file exhaustion end the session. At
  approximately 8 µl per reward, 125 successes are ~1.0 ml and 250 successes
  would be ~2.0 ml; rows are attempts, not rewards. The 25-minute and approved
  animal-specific water limits still apply independently.
- Created `parameters/training/02_micro_push_day1_5s_8ul.txt` with 250
  identical 27-column trial rows using all confirmed values, including the
  user-selected 500 ms timeout. Added it to `parameters/README.md`. The file
  remains bench-test-only until rapid-success reward-loop behavior, untouched
  false triggering, FP 3 V startup extension and normal-Stop retraction pass.

## Current session (27 Sep 2026): Ledex / PVA 1.6 commissioning

Goal: commission the Ledex `195224-230` and Hydraulik-Kompetenz PVA 1.6
0–10 V driver one checkpoint at a time, following `MAGNET_COMMISSIONING.md`.
Sunday's successful endpoint is a repeatable short, low-duty pull at a known
measured current, with clean release. Do not claim force calibration today.

Current checkpoint: **Checkpoint 1 — unpowered preflight**.
- The commissioning plan and rig inventory have been reviewed.
- No driver, coil or power wiring has yet been changed in this session.
- User confirms a 12 V supply with male barrel plug, a female barrel-to-screw
  adapter, and a multimeter with probes are available.
- Ledex photos received and visually reviewed. Label confirms part number
  `195224-230`; coil body, plunger, retaining nut and two white leads are
  present and currently disconnected.
- PVA photos received. Front identifies `PVA-1.6`; expected terminal lettering
  `A–F` and `G–M` is present. No visible marking in the supplied photos confirms
  whether the unit is the required 0–10 V rather than 4–20 mA variant. User
  reports that the ordered article was the intended variant, but the shipped
  unit remains physically unverified.
- Manufacturer datasheet checked: PVA-1.6 is offered as 0–10 V differential,
  0–20 mA and 4–20 mA configurations in the same enclosure. Use the unpowered
  `H–G` resistance screen as additional identification evidence; stop if below
  2 kohm.
- Multimeter photo reviewed: Fluke 87V; black lead is correctly in `COM`, red
  lead correctly in `VΩ`, and meter was off. User reports separated-probe `OL`
  and shorted-probe near-zero resistance sanity checks behaved as expected;
  exact shorted-probe value was not recorded.
- Unpowered PVA `H–G` resistance measured about 105 kohm in both probe
  polarities. This passes the 2 kohm AO-loading screen and strongly supports
  the ordered 0–10 V differential-input configuration.
- First Ledex coil attempt varied about 23–26 ohm due to poor alligator-clip
  contact. Repeat with reliable direct contact was stable at about 21 ohm,
  inside the 18–22 ohm acceptance band. Coil-resistance screen passed.
- User reports both disconnected coil-lead-to-metal-case checks passed (`OL`);
  no case short was detected.
- Barrel-to-screw adapter polarity passed: user reports approximately +12 V
  with red on marked `+` and black on marked `−`. Exact decimal value was not
  recorded. Correction: `250 mA` is the adapter's 100–240 VAC mains-input
  rating. Its selectable 12 VDC output is rated 1.0 A / 12.0 W. With 12 V
  selected and positive polarity measured, the supply passes.
- User did not recognize the inline fuse, so its availability is unconfirmed.
  Online examples were supplied for a 5x20 mm inline cartridge-fuse holder and
  an automotive blade-fuse holder. Preferred lab option is a 5x20 mm inline
  holder with a separate 1 A fuse. A holder's higher maximum rating is
  acceptable, but the installed fuse itself must be 1 A. Stop after unpowered
  work if no suitable holder and fuse are available.
- CONFIRMED 29 Sep evening: the lab has no 1 A fuse. That is why powered
  commissioning stopped. Order a 1 A fuse (and a holder if needed) before any
  powered PVA/Ledex test. Do not improvise an unfused connection.
- Keep all power disconnected until the unpowered checks are complete and
  recorded.

Session safety:
- Keep the Class 3B laser keyed off.
- No animal and no experimental parameter file.
- Do not run the push VI or energise `MagnetPush_Dev1`.
- Never power the coil from AO0; AO0 is only the 0–10 V command.
- Install a 1 A inline fuse in the 12 V positive lead before powered testing.
- Secure the driver and Ledex before power; keep fingers, steel tools and the
  washer target away during first energisation.
- Use only short pulses with long cool-downs.
- Stop for failed/unstable measurements, blown fuse, heating, odour/smoke,
  binding, unexpected LED state, incorrect force direction, or failure to
  release at 0 V.

Checkpoint 1 measurements still required:
1. PVA identification provisionally passed: ordered as 0–10 V and `H–G`
   measured about 105 kohm in both directions; casing itself is unmarked.
2. Ledex coil resistance passed at about 21 ohm with reliable probe contact.
3. Coil-to-case insulation screen passed: user reports `OL` from each lead to case.
4. Supply passed: 12 V selected, output rated 1.0 A / 12.0 W, and adapter
   polarity measured at about +12 V across marked `+`/`−`.
5. Screen PVA `H–G` resistance; stop if below 2 kohm.
6. Secure the PVA and Ledex mechanically.

## Push-task status (do not change today)

Working path already bench-tested:
cue HIGH → cue wait → cue LOW → reward delay → spout extend → settle →
water HIGH → watertime → water LOW → consumption → spout retract.

Loader reads columns 21–26 (`reward delay`, `cue duration`, `spout extend`,
`spout settle`, `consumption`, `spout retract`) on the rig copy. The repo
`.vi` still needs to be replaced with that tested copy when the user uploads it.

- Correction at the 29 Sep 2026 Mac merge: that upload already happened.
  `master` includes `ff68c15`, `f347f72`, `8c93c8c`, and the 29 Sep rig
  commits that update `Push Behaviour_MCHALABI.vi`,
  `avg joystick and frame trig lick3.vi`, and the FSR shaping presets.
  Do not treat the sentence above as a pending upload.

## Historical plan (Mac copy through 27 Sep 2026)

The checklist below was written on the Mac before the 28–29 Sep animal and DAQ notes above. Items marked done describe bench status at that time. The overrides at the top of this file supersede them.

## Current task: Adapt fork into 1D forelimb object-push task
- [x] Absorb prior planning chat + LabVIEW walkthrough into `.cursorrules`
- [x] Absorb Weekly Update 29/06/26 design evolution (PI-approved)
- [x] Fork Mathis `JoystickControlSystem` → this working repo (`JoystickPushTask`)
- [x] Rename main VI filesystem name → `Push Behaviour_MCHALABI.vi` (internal name corrected via LabVIEW Save As)
- [x] Recover VI after binary-edit load failure; avoid direct `.vi` binary edits going forward
- [x] Install local commit-message hook to strip `Co-authored-by: Cursor <cursoragent@cursor.com>` from future commits in this clone
- [ ] Learn LabVIEW basics (front panel / block diagram, state machines, occurrences, DAQmx)
- [x] Deep-read current VI architecture against notes below (Cases 0–4, magnet/water loops)
- [x] Order missing hardware — DONE 09/07/26: FSR 402 solder tabs (30-81794), Actuonix L12-30-50-12-I, Adafruit #1536 buzzer
- [x] Rewrite README for forelimb push task; refreshed 20/08/26 after VI import to distinguish
  bench-validated features from planned mechanics, parameter plumbing, perturbations and safety tests;
  pushed to `master` as `3e163ac`
- [ ] Complete live-rig inventory — SUBSTANTIALLY MAPPED; actual card is PCIe-6321 and breakout is **SCB-68A** (`rig1`). Current AO split: Actuonix occupies AO1/terminal 21; AO0/terminal 22 remains unwired for the received Ledex magnet. Remaining checks are inline DAQmx channels, PFI8/PFI13 attachment state, `testing1blox_2labviews` references, and S1/S2 switch positions. Full terminal map in `RIG_INVENTORY.md`
- [x] Install FSR rest pad — REPLACED 08/09/26: new FSR 402 soldered/installed on the existing
  inline harness (`+5V` 8, `ai2` 65, AI GND 64), fixed on the rail, protective tape over the
  contact face, and working with no reported issues (no splice of the 04/09/26 ripped tail).
  Prior electrical/LabVIEW gating remains: `joysticklickframe_push`, threshold UI and first-trial
  Case 0 gate. Still calibrate threshold/hysteresis on the taped surface; a dedicated cleanable
  puck can wait if tape stays stable and does not preload the baseline.
  SUPERSEDED 28–29 Sep 2026 by the animal-pilot notes at the top of this file:
  paw contact was not reliable, the divider is now 1 MΩ and ghosts joystick X
  onto ai2, and SingleTact S8-1N is the preferred replacement.
- [x] Correct `joysticklickframe_push` channel order — DONE 20/08/26: reordered the task from
  `[ai0, ai1, ai2]` to `[ai1, ai0, ai2]` (`Y_POS`, `X_POS`, `rest_pad`) to match the inherited
  LabVIEW array-index convention; live X/Y test confirmed the swap is fixed.
- [ ] Install auditory cue — ELECTRICAL + LABVIEW PULSE COMPLETE; Adafruit #1536 on `P0.1` terminal 17/D GND 15, `SuccessCue_Dev1`, 50 ms HIGH/LOW sequence runtime-tested. Direct drive remains provisional near possible P0 current limit; fixed mount and event logging remain
- [ ] Install Actuonix spout — ELECTRICAL + MECHANICAL + LABVIEW SUCCESS PATH COMPLETE: AO1 split from magnet AO0, `LickSpout_Dev1`, extend/settle/water/consume/retract sequence and three spaced full trials passed 18/08/26. Water volume vs `watertime` measured 08/09/26 (`calibration/water-volume.md`; 130/185/240 ms → 4/6/8 µl). Still calibrate mouse-relative extend voltage, exact settle time, cable cleanup and repeated-cycle reliability within 20% duty
- [ ] **SAFETY**: terminal 42 (`PFI3`/`P1.3`) drives a Class 3B 635 nm 200 mW laser (`MDL-III-635L-200mW`) via no saved NI-MAX task — keep laser keyed off during bench work and never toggle PFI3 blind
- [x] **RIG TOPOLOGY CONFIRMED 12/08/26**: split on-demand AO ownership: magnet=`ao0`, Actuonix=`ao1`; `Magnets_Dev1` must no longer include AO1. Mesoscope rig already has the original Mathis tubular solenoid (`69905K25`). Training-rig magnet is the Swiss/EU equivalent **Ledex `195224-230`** (pull-type), ordered 27/08/26 via Quartzy from Contact Evolution SA (Payerne) and arrived 02/09/26. AO0 LabVIEW path (`MagnetPush_Dev1`) is ready; terminal 22 is still unwired
- [ ] Install training-rig perturbation magnet — ARRIVED 02/09/26: **Ledex `195224-230`** STA 75L **pull**, 12 VDC, 7 W. Use as an electromagnet attracting a ferromagnetic target (Mathis: “small steel ring” on an aluminum handle base; no catalog SKU). Mesoscope-ring measurements obtained 03/09/26: ~4.1 mm thick, ~9.48 mm OD, ~4.12 mm ID; a ~3.1 mm ID variant would also suit the prototype. **Target washers ORDERED from SFS Switzerland on 04/09/26:** M4 article `111952`, DIN 125-1-A / ~ISO 7089, 140 HV zinc-plated-blue steel, 4.3 × 9 × 0.8 mm, 200 pieces at CHF 2.86 per 100 pieces incl. VAT (CHF 5.72 before shipping); M3 article `132845`, DIN 9021 / ~ISO 7093-1, 140 HV zinc-plated-blue steel, 3.2 × 9 × 0.8 mm, 200 pieces at CHF 2.70 per 100 pieces incl. VAT (CHF 5.40 before shipping). These replace the unfulfilled Würth requests, whose Swiss account pricing was hidden. On arrival, stack five matching washers for a 4.0 mm target; build and force-calibrate both bore options. Explicitly avoid substitution with stainless steel A2/A4, aluminium, brass, plastic or neodymium magnets. Mount the solenoid on the **home side** of the object so attraction pulls backward and **opposes** the push. Land on `Dev1/ao0` / terminal 22 using a coil driver (AO is a command, not the coil supply). Keep `mag = 0` until the unperturbed task is stable. **INSTALL KICKOFF 04/09/26:** holder/positioning is already designed; focus only on the electrical chain. The PCIe-6321 AO limit is ±5 mA, while the 12 V / 20.7 Ω Ledex draws ~0.58 A—over 100× more—so direct connection is prohibited. A driver is the power switch/current stage between AO0 and the coil and must include inductive flyback suppression. Mesoscope-driver copying was ruled out on 04/09/26 because its termination box is physically inaccessible and the user was explicitly instructed not to touch or move the mesoscope rig; do not revisit that route. A second Goobay-type 12 V / 1 A supply identical to the Actuonix supply is available and reserved exclusively for the magnet; user multimeter-verified its 12 V output on 04/09/26, so supply voltage is no longer a blocker. Keep it unplugged and labelled for magnet use. The remaining procurement blocker is an independent proportional/current-regulated driver accepting 0–10 V AO input and supporting at least 0.58 A output. Keep the Class 3B laser keyed off and all rig power off during installation.
  - DRIVER PROCUREMENT CORRECTED 04/09/26: user confirmed random perturbation sessions require
    genuinely variable magnetic-force magnitudes, not merely random on/off presence. Therefore
    **do not order/use the Adafruit 5648** for this requirement; it is only a binary MOSFET switch,
    and intermediate AO gate voltages are not calibrated proportional force. Conrad's suitable
    current-regulated Bürkert `316532` showed delivery only on 28/09/26. Faster Swiss candidate:
    Proportional-Verstärker `LCA 1.6`, Hydraulik-Kompetenz AG article `15103`, 12–36 V supply,
    differential 0–10 V input, adjustable minimum/maximum current, current output up to 3 A and
    listed as available from remaining stock within one week:
    `https://www.hydraulikshop.ch/proportional-verst%C3%A4rker-lca-16`.
    Before Mioara orders, obtain written vendor confirmation that it is compatible with the Ledex
    `195224-230` (12 V, 20.7 Ω, nominal 0.58 A), can regulate 0–0.58 A from the available 12 V
    supply, and includes the required inductive freewheel/flyback path; ask price and actual ship
    date. Also ask Bürkert Switzerland (`info.ch@burkert.com`, article `316532`) for local stock in
    parallel. The common-vendor H-Tronic/Kemo motor PWM modules are open-loop rather than
    temperature-stable current regulators and are not preferred for calibrated experimental force.
  - MINIMUM BENCH-TEST BOM remains: one confirmed proportional/current-regulated 0–10 V driver,
    ordinary insulated wire for supply, AO command/ground and coil, wire stripper and small
    screwdriver. DIN rail is never electrically required; it is only needed if the selected
    driver's housing uses it. Final enclosure, fuse/switch, heat-shrink, labels and strain relief
    remain later permanent-rig items.
  - DRIVER DECISION PENDING 04/09/26: choose between the Swiss `LCA 1.6` article `15103` and
    Bürkert Type 8605 article `316532` after receiving confirmed Ledex compatibility, integrated
    flyback/freewheel behavior, price and actual delivery date. Do not order either until those
    answers are compared; prioritize current regulation and compatibility over mounting format.
  - DRIVER TECHNICAL REVIEW 07/09/26: Bürkert `316532` is the better-documented/lowest-risk match.
    Its verified specifications are 12–24 V supply, 200–1000 mA current-regulated PWM output,
    selectable 0–10 V input with >20 kΩ impedance (≤0.5 mA load on the PCIe-6321 AO), adjustable
    80 Hz–6 kHz PWM, 0–10 s ramp including disabled/0 s, zero-current cutoff, and directly wired
    coil output. Set cutoff active, LO to the lowest allowed current, HI near 580 mA, ramp 0, then
    force-calibrate; nonzero commands may be limited to ≥200 mA. Downsides: Conrad delivery quoted
    28/09/26, higher cost, DIN-rail form, and its presets target Bürkert valves so PWM frequency must
    be tuned for the Ledex.
    The `LCA 1.6` is a plausible faster Swiss option and explicitly supports generic electromagnetic
    components: regulated temperature-/coil-independent PWM current, 12–36 V supply, differential
    0–10 V input, 70–500 Hz PWM, adjustable Imin/Imax/ramp, separate enable input and direct coil
    terminals; remaining stock was listed within one week. However its datasheet does not state
    input impedance, flyback/freewheel implementation or regulator voltage headroom, and gives
    ambiguous current scaling (`≤3 A` table, `up to 4 A` text, Imax adjustable only 50–100% of
    nominal). Do not select it unless Hydraulik-Kompetenz confirms a configuration mapping 0–10 V
    to 0–0.58 A for the 20.7 Ω Ledex without loading AO0 above 5 mA. Conditional recommendation:
    choose LCA only with those written confirmations; otherwise choose Bürkert and accept the delay.
  - LCA ONLINE FOLLOW-UP 07/09/26: exhaustive searches found only the same manufacturer
    `LCA_1.6.pdf`; no second manual or circuit specification publishes input impedance, output-stage
    voltage drop/headroom, explicit freewheel/flyback protection, or the article `15103` nominal
    current (`INom`). The PDF does confirm a regulated PWM current output for generic electromagnetic
    loads, direct coil terminals A/B, power C/D, enable E, +10 V reference F, signal ground G and
    0–10 V command H; PWM 70–500 Hz; mapping
    `Iout = Imin + Uin*(Imax-Imin)/10`; and that enable bypasses the ramp. The unresolved scaling is
    material: P2 only adjusts Imax over 50–100% of unspecified `INom`, so it is not yet proven that
    10 V can be calibrated to 0.58 A rather than saturating the 20.7 Ω coil early. Online evidence
    therefore narrows but does not eliminate the need for one vendor confirmation; do not infer
    missing safety/electrical values from the block diagram.
  - DRIVER ORDER + DECEMBER SLIP 22/09/26: Bürkert Type 8605 / `316532` was ordered (Quartzy /
    Tameson path). Vendor now quotes arrival **2 December 2026**, which is too late for the
    mid-October need. This is a factory-wide 8605 lead time, not a single-shop delay: Tameson
    still shows ~65-day ship, and other `8605` variants (`316531`/`316533`) are similarly
    backordered. Do **not** wait for another Bürkert 316532 listing; Best4Automation's 2–3 day
    placeholder is not real stock. Keep the December unit if already paid (spare / later
    calibration), and order a Swiss in-stock current-regulated 0–10 V driver now.
    Fastest confirmed listings on Hydraulikshop.ch (Hydraulik-Kompetenz AG, Rufi; call
    `+41 55 619 52 00` / `info@hydraulik.ch` immediately — all stock is
    Zwischenverkauf-vorbehalten):
    1. **Preferred drop-in:** `PVA 1.6` 0–10 V, CHF 260, **2 pcs ab Lager**, DIN-rail screw
       terminals, 12–36 V, differential 0–10 V, PWM current to 3 A, adjustable Imin/Imax/ramps/
       dither, enable pin. Same shop/family as LCA.
       `https://www.hydraulikshop.ch/proportional-verst%C3%A4rker-pva-16-0-10v`
    - PVA ELECTRICAL FIT 22/09/26: the two unpublished items are **not blockers** if the
      **0–10 V SKU** is ordered (not the 4–20 mA SKU). Voltage-input Z is unpublished, but
      that SKU is a differential voltage front-end (wired from a 10 kΩ pot or a PLC 0–10 V
      AO in the datasheet). NI 6321 AO0 is safe above ~2 kΩ (10 V / 5 mA); typical voltage
      inputs in this class are 10–200 kΩ (~0.05–1 mA). The dangerous case is a current-loop
      shunt (~200–250 Ω → ~40 mA). Measure H–G with a DMM before connecting AO0. PWM
      current regulation of a solenoid **requires** an internal freewheel path or the output
      FET dies on the first off-edge; the datasheet’s low-loss PWM claim implies that path
      exists even though no diode is drawn. If paranoid, add an external flyback diode across
      the Ledex (cathode to coil +, ≥1 A). Wire Enable (J) to +12 V or the module will stay
      off. Set Imin=0, Imax≈580 mA, ramps fastest / bypass via Enable, dither as low as it
      will go (this is a static electromagnet, not a valve spool). 12 V into 20.7 Ω has
      almost no regulator headroom, so max current may land a bit under 0.58 A — same
      12 V-supply limit as Bürkert, not a PVA-specific defect.
    - BUY CLEARED 22/09/26: user may order the **0–10 V** `PVA 1.6` now (not 4–20 mA).
      Call Hydraulik-Kompetenz to reserve remaining stock. Keep the December Bürkert as
      spare if cancellation has a fee; cancel it if Tameson waives the fee. Do **not**
      switch the late Bürkert to Conrad — same 316532, same factory 65-day lead. Mioara
      asked 22/09/26 what to do; tell her: ask cancellation policy, do not reorder
      Conrad, place PVA 1.6 0–10 V with Hydraulik-Kompetenz.
    - QUARTZY SUBMITTED 22/09/26: user filed the Hydraulik-Kompetenz `PVA 1.6` 0–10 V
      request (CHF 260, urgent, needed mid-October). Waiting on Mioara to order/reserve
      the 2 remaining shelf units and on the Tameson Bürkert cancellation answer.
    - PVA ARRIVED / COMMISSIONING HANDOFF 27/09/26: the Hydraulik-Kompetenz `PVA 1.6`
      **0–10 V** (CHF 260, Quartzy) is physically at the training rig. This is the selected
      Ledex coil driver; not the 4–20 mA SKU. Do not also order XMD-01, LCA 1.6 or
      Murrelektronik. A tracked step-by-step rig-PC handoff is now
      `MAGNET_COMMISSIONING.md`. Critical pre-power blocker: install a 1 A inline fuse in
      the reserved 12 V Goobay positive lead. Terminal map from the manufacturer datasheet:
      D=+12 V, F=power ground, J=Enable, H/G=0–10 V differential command, C/A=coil,
      K/M unused for the DAQ command. Keep J open until AO0 is initialized/measured at 0 V.
      Measure cold Ledex resistance (~20.7 Ω), screen H–G input impedance, set Imin=0 and
      measured current ceiling ≤0.58 A using short pulses. Do not guess bonds among F/G/M,
      improvise E/mains earth or add an unconfirmed external flyback diode. Sunday endpoint
      is electrical/functional low-duty validation only; force calibration still requires a
      force gauge/load cell and thermal characterization. The December Bürkert `316532`
      remains the spare unless cancellation is free.
    2. **Better-documented regulation:** SUN Hydraulics `XMD-01`, CHF 215, **ab Lager**.
       9–32 V, 0–10 V command, current-regulated PWM 35–3000 mA ±1 mA, integrated flyback,
       ramp can be 0, phone-app setup. Voltage-mode input Z is unpublished; do **not** leave
       the input in 4–20 mA mode (~200 Ω, would overload AO0). Needs a Deutsch DT06-12SA
       harness (shop lists 3 m XMD-02 cable `991-712-300` at CHF 146; XMD-01 cable is
       `991-711-300`). `https://www.hydraulikshop.ch/elektrohydrverst%C3%A4rker-f-1-spule-xmd-01`
    3. `LCA 1.6` article `15103` still listed as remaining stock within 1 week.
    Common-vendor fallback: Murrelektronik `7000-31261-0000000` (RS 137-0320), 0–10 V /
    200 kΩ / current-regulated 0.02–2.5 A, DIN rail — but **18–32 V only**, so it cannot use
    the reserved 12 V Goobay; would need a 24 V PSU. Do not substitute Adafruit 5648 / Kemo /
    H-Tronic.
- [ ] Audit the VI for inline DAQmx channels (saved NI-MAX tasks are demonstrably incomplete)
- [ ] **NEXT MAJOR MILESTONE:** load `parameters/push_bench_wide-zone.txt` on the
  rig and hand-test (push-only success; miss Y; overshoot Y past 2.20 and come
  back). Loader Case 2 is **no ×2** (09/09/26: only the `home X2` label).
  09/09/26: X slots = white/push confirmed — Tests 1–3 passed. User dropped
  the Case 5 / FSR lift-off LabVIEW edit. Use a long file `move time` instead
  (column 20; bench file **30000 ms**). `home TO` **250 ms** (was 500). Do not
  change the Case 2 constant 3 (next state, not seconds). Stage files are in
  `parameters/training/` (27-col). Next: extend the loader to cases 21–26 and
  wire the water loop; then delay files work. Habituation still needs LabVIEW.
  Keep
  21 columns; cue/delay/spout stay on the FP. Remeasure volts-to-mm with a
  ruler before freezing training numbers.
  New CAD prints wait until **Monday 21/09/26**. FSR is replaced and taped. Water
  volume vs pulse is recorded in `calibration/water-volume.md` (130/185/240 ms →
  4/6/8 µl). Still add spring return (if missing) and a steel-ring target;
  Success sequences and some miss-fails passed 08/09/26. Loaded file was
  `Full_shoterPull_Training_Task_RIG1.txt` (shorter-pull, identical rows):
  home (2.39,2)–(2.8,3), home TO 500, start TO 0, end (1.8,2.45)–(2.34,2.55),
  end TO 50, mag 0, watertime 200, clocks 1000 and 400. End box is ~5–23 mm
  forward at 0.030 V/mm with a 0.10 V lateral sliver; a 2.20 V push is still
  inside the long axis, so “overshoot” was not past the far edge. Miss →
  Case 0 is the designed fail. Axis map CONFIRMED 08/09/26: push = white =
  `Dev1/ai1` = **Y** (queue index 0); lateral = red = `Dev1/ai0` = **X**
  (queue index 1). Home 2.50 / 2.525 V. The shorter-pull `end` box is therefore
  X 1.80–2.34 (lateral; rest 2.525 is outside) and Y 2.45–2.55 (push; a 2.20 V
  push is outside). That file rewards an old sideways pull, not a forward push.
  See `calibration/joystick-volts-mm.md`.
  - CAD added 05/09/26: imported `joystick_89mm.step` plus two interchangeable tip-mounted handles
    (`mechanical/3d-print/joystick/`, `joystick-handle-bar/`, `joystick-handle-cube/`). The bar is
    a 38 mm contact bar. The rounded cube is the current push-object candidate and has three holes
    to set front-face distance to the mouse/rest pad and to shift object weight relative to the
    joystick beneath it. User already has one printed joystick, one handle and the 1D-axis
    constrainer fitted on the rig (confirmed 08/09/26); further prints wait until 21/09/26.
  - CAD added 03/09/26: STEP models for the joystick 1D-axis constrainer
    (`mechanical/3d-print/joystick-1d-axis-constrainer/`) and Ledex `195224-230`
    holder (`mechanical/3d-print/ledex-holder/`). The Ledex holder/positioning design is complete;
    immediate magnet work is electrical connection and functional validation, not holder redesign.
    Mechanical files are organized one folder per part.
  - Repository documentation synchronized 03/09/26: README and rig inventory record the
    received-but-uninstalled Ledex; Jupyter Book metadata/TOC now target
    this fork and its live rig/mechanical docs. Removed obsolete Python-package setup inherited from
    Teensy Task and updated the documentation workflow to install `requirements.txt` directly.
    Local Jupyter Book 1.x HTML build passed without warnings after validating all mechanical links.
  - Mechanical cleanup 23/09/26: removed the obsolete 2D prototype and its documentation/TOC
    references. The five active 3D-print designs are the only mechanical CAD sources retained.
  - STL exports added 23/09/26 for all five active STEP models: joystick shaft, bar handle,
    rounded-cube handle, 1D-axis constrainer and Ledex holder. STEP remains the editable source;
    matching STL files are the slicer-ready derivatives documented in each part README. All five
    STLs were read back with OpenCascade and match their STEP bounding boxes within 0.003 mm.
    Jupyter Book 1.0.4 rebuilt successfully with all STEP/STL download links and no warnings.
    Committed and pushed to `master` as `edb32af`.
  - Follow-up audit 03/09/26: corrected AO occupancy (AO1 Actuonix occupied; AO0 magnet empty),
    standardized “1D-axis constrainer” terminology, marked old water/FSR notes as historical, and
    promoted the Würth washer-target specifications into tracked mechanical documentation.
- [x] Begin LabVIEW mods — CORE SUCCESS PATH BENCH-FUNCTIONAL 18/08/26: rest-pad gate, cue, spout sequence and water delivery integrated
- [x] Absorb 07/09/26 training-protocol planning (work-AI chat + old pull-task parameter files from the rig PC). Shaft/handle/constrainer are now fitted; still do **not** write numerical push files until home voltage, volts-to-mm, push-axis index and ROM are measured. Keep the 21-wide format; session-constant cue/delay/spout/FSR controls stay on the front panel until the live unbundle map is confirmed. Split FSR vs joystick **log files** later if needed; do **not** split them into two simultaneous NI-MAX AI tasks (PCIe-6321 has one AI timing engine).
- [x] Live parameter unbundle mapped 08/09/26 (indices 0–20; `timeout`=18, `move time`=19, `light`=20)
- [x] First push bench file drafted: `parameters/push_bench_wide-zone.txt` (wide X, Y end 2.20–2.35, move time 3000, watertime 185). Not a training stage; load and hand-test.
- [x] Training-stage files written 09/09/26 under `parameters/training/` (micro →
  proximal → 3 translates → refine → delay 0/250/500/1000 → expert → shadow).
  Widened to 27 columns (reward delay, cue, spout). Loader/water-loop 27-wide
  on rig PC 09/09/26 and imported into repository 21/09/26. Habituation and
  mag≠0 experiment are still not file-only. See `parameters/README.md`.
- [x] Import rig-tested VI hierarchy into repository — DONE 21/09/26: four binaries
  from rig transfer; SHA-256 verified; main VI carries 27-column loader + water loop;
  pushed `ff68c15`; rig PC `git pull` + dependency smoke test passed same day
- [ ] Generate Baseline → Random → Fixed → Washout session parameter files
- [ ] Decide sensible defaults (trial counts, perturbation magnitudes, reward delay, etc.) — draft list absorbed 07/09/26; numerical values remain TBD until calibration
- [ ] Adapt LabVIEW UI branding/controls for push task
- [x] Configure/export NI-MAX tasks for new channels — full NI-DAQmx 17.0 `.nce` backup exported
  after X/Y-order correction on 20/08/26 and imported at
  `ni-max/JoystickPushTask_NIMAX_2026-08-20.nce`
- [ ] Bench-test full success/fail/stop-abort sequences — success path and normal Stop from
  idle/reward-delay/spout-extended phases passed 20/08/26; 08/09/26 success sequences and
  some 2D miss-fails passed on the fitted handle. Miss → Case 0 rest-pad re-gate is the
  designed fail path. Overshoot-and-correct not validated (wrong/unknown param file;
  possible 400 ms `move time`). Repeated-cycle tests remain. Toolbar Abort remains
  emergency-only by design.
- [x] **SAFE STARTUP + NORMAL STOP COMPLETE 20/08/26:** startup commands cue LOW, water LOW,
  magnet 0 V and spout retract; shared `PushTask Globals.vi` Boolean stops every asynchronous loop.
  Idle, reward-delay and spout-extended Stop tests returned the Run arrow to idle without DAQ errors.
- Stop-path screenshot audit 20/08/26: normal Stop is evaluated at the While Loop boundary, so an
  active water iteration must finish its sequence through cue LOW, water LOW and spout retract before
  exit; the magnet sequence likewise reaches its reset write. Therefore implement a one-shot startup
  initializer and verify normal Stop empirically rather than adding redundant post-loop writes.
- [x] One-shot safe startup initializer added and runtime-tested 20/08/26: Water LOW,
  SuccessCue LOW, LickSpoutMotor 0 V and MagnetPush 0 V. User used toolbar Abort once; no fault was
  reported, but Abort bypasses all remaining sequence/reset frames and remains emergency-only.
  Normal Stop tests during idle/reward-delay/spout-extended phases subsequently passed.
- Normal Stop test 20/08/26 exposed runtime DAQmx error `-200428`: stale task names remain in
  non-success paths. `DAQmx Stop Task.vi` receives `Magnets` instead of `MagnetPush_Dev1`, and
  `DAQmx Start Task.vi` receives `frame counter` instead of saved task `frame counter_Dev1`.
  Correct those task constants/references and repeat Stop tests before declaring cleanup complete.
- Stale task references were corrected and Stop now produces no DAQ errors, but one front-panel STOP
  leaves the main Run arrow in the running state. The two similarly named STOP controls likely govern
  different parallel loop groups. Map both controls and consolidate all loop conditional terminals
  onto one canonical normal-stop control before cleanup is considered complete.
- Stop mapping 20/08/26: Find results items 21, 27 and 29 confirm the water, magnet and main
  state-machine loop conditionals all read the same lowercase `stop` control. Do not alter them.
  The remaining live execution must be in the acquisition/helper hierarchy; inspect the two main-VI
  control-reference objects (Find items 19 and 22) and ensure helper `stop in` references the same
  canonical `stop`, not the ineffective `stop 2`.
- Control-reference mapping confirmed 20/08/26: `avg joystick and frame trig lick3.vi` receives the
  canonical `stop` reference, while `frame counter.vi` receives `stop 2`. Replace only the
  frame-counter call's `stop 2` reference with a copy of the existing `stop` reference, then test
  that one Stop ends all loops and returns the Run arrow to idle.
- Replacing the frame-counter input with a newly created canonical Stop reference did not end the
  remaining execution. Live helper front panels show red-X `Not a Refnum` values for acquisition
  `stop in` and frame-counter `stop ref`; both helper stop-reference inputs are invalid at runtime.
  Do not continue changing button mechanical actions. Safe output loops stop correctly; graceful
  helper shutdown needs the fragile UI-reference mechanism replaced or repaired separately.
- Chosen graceful-shutdown fix: add repository-local LabVIEW global `PushTask Globals.vi` containing
  Boolean `stop all`. Reset it False in the one-shot startup sequence; write the canonical main
  `stop` value to it from the main task loop; read it at the acquisition-helper and frame-counter
  loop conditionals instead of their invalid UI-ref Property Nodes. Retain old ref inputs until the
  shared-global path passes testing, then mark them obsolete.
- [x] Shared-global idle Stop test PASSED 20/08/26: one canonical main Stop now terminates the main,
  water, magnet, acquisition-helper and frame-counter loops, returns the Run arrow to idle and
  produces no DAQ errors. Reward-delay and spout-extended Stop tests also passed; normal shutdown is
  fully validated. Updated main/helper/global VIs and documentation were imported, SHA-256 verified
  and pushed to `master` as commit `b43b003`.
- [x] Rig-PC GitHub-copy smoke test — PASSED 20/08/26: repository main VI opened with a healthy
  Run arrow after installing the compatible frame-counter dependency and completed the full
  non-animal bench sequence
- [x] Fresh GitHub-copy dependency fix 20/08/26: Error List confirmed
  `avg joystick and frame trig lick3.vi` is non-executable because its `frame counter.vi` subVI is
  missing. Replacing the repository's retained binary with the working-hierarchy copy fixed the
  load and passed bench testing. The exact compatible copy was imported from the transferred
  Downloads hierarchy into the Mac repository and SHA-256 verified; pushed with the NI-MAX backup
  and 20/08/26 validation documentation as commit `ff13cb6`.

## Source context (do not re-derive from scratch)
- Planning export: `/Users/maxchalabiprat/Documents/GitHub/JoystickControlSystem/exports/forelimb-push-chat-export/`
  - Prefer `chat-export.md` + `attachments/` for LLM context
  - `02_full_bundle.pdf` = chat PDF + ChatGPT `LabVIEW-Code-Review.pdf`
  - Key LabVIEW screenshots live in `attachments/image-*.png` (Cases 0–4, magnet/water loops, task schematic)
- Design authority: Weekly Update 29/06/26 (Max Chalabi) — Mackenzie Mathis approved (“let’s go for it”)
- Upstream paper/rig: Mathis et al. 2017 (2D joystick pull / lateral magnet perturbation)
- This fork’s main VI: `Push Behaviour_MCHALABI.vi` (+ `avg joystick and frame trig lick3.vi`,
  `frame counter.vi`, `PushTask Globals.vi`)
- The behavioural rig's edited hierarchy was imported into this repository on 18/08/26; the
  untouched `Pull Behavior_march2020.vi` remains the operational fallback on the rig PC.
- Do not attempt to Git-merge independently edited `.vi` binaries. After the rig-PC clone smoke test,
  treat the repository `Push Behaviour_MCHALABI.vi` hierarchy as the only canonical editable copy.
- Do not delete `LabView files - PushVersion - working` yet. Rename/archive it read-only first, then
  validate a brand-new clone of commit `ff13cb6` while the old working path is unavailable and audit
  parameter/data-file dependencies. Keep both the untouched original hierarchy and dated working
  archive at least through the first successful animal pilot.
- Clean-clone load on 20/08/26 resolves all three relocated dependencies into the clone root
  (`avg joystick and frame trig lick3.vi` and `frame counter.vi`) and shows only
  "Dependency loaded from new path" warnings, not missing/broken dependencies. LabVIEW Save All
  rewrote all three VIs; the resulting clean-clone copies were transferred to Mac, imported into
  the repository and SHA-256 verified on 20/08/26. Pushed as commit `45f8e8a`.
- Live screenshots 12/08/26 confirm the rig VI retains the expected occurrence-driven water loop,
  five-case trial state machine, parameter loader, and a lower occurrence loop that combines
  `Magnets_Dev1` AO writes with `Dev1/ctr1` laser-pulse generation. Preserve both code paths. Adapt
  the magnet path from its original two-channel task to an AO0-only on-demand task; leave the laser
  counter path unchanged.
- Initial LabVIEW **Duplicate hierarchy** attempt was deleted because the expected VI was absent from
  the destination. The complete containing folder was then manually copied with suffix
  `- PushVersion - working`; edit that hierarchy and preserve the original `LabView files` hierarchy
  containing `Pull Behavior_march2020.vi` as the untouched operational baseline.
- Working hierarchy transferred to Mac at
  `/Users/maxchalabiprat/Downloads/LabView files - PushVersion - working` on 18/08/26. Imported only
  `Push Behaviour_MCHALABI.vi` and the modified nested `avg joystick and frame trig lick3.vi`;
  SHA-256 verification confirmed both repository copies are byte-identical to the transferred files.
  Committed and pushed these two binaries to `master` as `182c498` on 18/08/26; commit identity is
  `maxchalabi` and the message contains no Cursor co-author trailer.
  Transferred `frame counter.vi` also differs from the repository binary but was not edited during
  this work, so leave the repository copy untouched. After import, reopen in LabVIEW and verify the
  main VI resolves the repository-local helper rather than an old/nested absolute Windows path.

## Guiding principle
Keep existing LabVIEW architecture largely intact; only change what is necessary for a clean push paradigm. Task should stay simple for the animal but structured enough that behavioural and neural events are interpretable.

## Locked trial structure (v1)
```text
forepaw on rest pad
  ↓
trial starts
  ↓
reach to object
  ↓
push object forward
  ↓
(perturbation / axial resistance)
  ↓
success distance reached (and held in target band)
  ↓
success cue (auditory, immediate)
  ↓
short fixed delay
  ↓
lick spout extends
  ↓
water reward → spout retracts
```

Clean behavioural epochs for neural alignment:
`rest → movement initiation → object contact → push → perturbation → success cue → post-success delay → spout/lick/reward`

Without the rest pad, the animal could keep the paw on the object between trials (pre-load, continuous tactile feedback) so trial onset would not be a clean event. Rest pad does **not** claim identical posture every trial — it defines a **pre-contact trial start state**. Precedent: Estebanez et al., Voigt et al., Galiñanes et al., Mangin et al. (rest/hold before reach).

Delayed retractable spout separates push completion from licking/reward so those don’t collapse into the same window as movement/perturbation (Guo et al. motorized lickport + delay; Wagner et al. ~1 s delay on robotic manipulandum; licking can dominate cortex — Kondo & Matsuzaki, Murphy et al.; delayed water waiting is learnable — Gao et al.). Training: pair the buzzer with water from the first head-fix session, keep that interval short while the push is being discovered, then lengthen cue-to-spout only after the movement is reliable so the cue remains a discrete CS.

## Behavioural / session design
- 1D forelimb **object-push**: reward only if object **ends and remains** in a target distance band (Case 3 `end` ROI + `end TO` — not merely past a minimum). Overshoot past the far edge is **not** an immediate abort: Case 3 already keeps the trial open until `move time`, so the mouse can release/correct back into the zone. Leaving the band only resets the dwell timer. Immediate-fail-on-overshoot would fight the later SPE/perturbation design.
- Session blocks via parameter file:
  1. Baseline (`mag = 0`)
  2. Random perturbations (unpredictable axial resistance)
  3. Fixed perturbations (learnable axial resistance)
  4. Washout (`mag = 0`) — overshoot / velocity / corrective sub-movements as internal-model readouts
- Perturbation = **axial resistance along push axis** (not lateral force as in original Mathis task)

## Locked training progression (revised 07/09/26; supersedes 14/08/26 threshold-crossing-heavy plan)
Criterion-based, ~3–6 weeks. Teach one component at a time, but chain rest-pad contact into pushing
early. Keep `mag = 0` until the final unperturbed task is stable. Advance after the criterion on
**two consecutive days**, not one lucky session. Change only one important parameter at a time.
Formal table starts at head-fix (no separate “handling / reward familiarisation” stage — Mathis also
did not report one). Handling still happens off-protocol.

Revised stages:
1. **Head-fix habituation + cue–reward association** — ramp ~5 → 10 → 15–20 → 25–30 min; spout
   available; buzzer then free water. Do **not** install the final 500–1000 ms delay on day 1 of
   head-fix if the next stage will reward immediately; keep the cue–reward interval short (0–250 ms)
   until the push is solid, then lengthen in stage 6. Stop free pairings once voluntary pushing starts.
2. **Micro-push discovery** — 20–50 genuine designated-paw forward pushes (~0.5–1 mm, above noise);
   ~1–2 sessions max; no zone/hold. Do not reward rest-pad contact alone, nose/wrong-paw/body hits,
   grasp/pull, or spring-return motion.
3. **Proximal broad target zone** — immediately after discovery. Broad ~3–4 mm zone near the paw,
   inside-zone + ~30–50 ms dwell (dwell already anti-ballistic: 4 mm / 50 ms ⇒ must be slower than
   ~80 mm/s through the zone). Correction allowed until the movement-window timeout.
4. **Progressive zone translation** — shift the same broad zone farther forward (~0.5–1 mm after a
   strong block, not after every trial) to the final ~6–7 mm distance (confirm after measuring
   comfortable ROM with the printed paddle).
5. **Final target-zone refinement** — narrow to ~2–3 mm; dwell 50 ms, 100 ms only if needed.
6. **Spout retraction + final reward sequence** — cue stays at target acquisition; then 0 → 250 →
   500 → possibly 1000 ms cue-to-spout; do not change distance/zone in the same sessions.
7. **Expert stabilisation** — freeze geometry and timing; ≥80% success, ≥90% designated paw, little
   first-to-last-third decline, enough trials for the future session.
8. **Zero-force shadow sessions** — exact 50 / 75 / 100 / 75 block labels with magnet commands
   running at force 0. Tests fatigue, satiety, magnet noise/heating, 300-trial feasibility.
9. **Resistance pilot (separate mice)** then **main experiment**. Do not “calibrate” force on the
   imaging cohort. Random-block definition still TBD (presence vs magnitude vs both). Project already
   requires a proportional driver because random sessions are intended to vary force magnitude.

Optional `Rest only` remains a **fallback** for mice that never touch the pad (50–100 ms contact,
release-to-rearm, leave after ~30 contacts or 1–2 sessions). Not a default stage.

Mathis 2017 closest precedent: random water while first head-fixed ≤15 min → 3–5 days any
touch/pull → >1 s start-box + ~3 mm broad box / 100 ms hold → after >60% for 2 days, ~7 mm target
→ train to >80%, typically 4–5 weeks. Wagner 2020 for daily manipulandum troubleshooting and
animal-specific geometry. Roth lever-push and Linares-García 2025 for “push is less natural than
pull.” Mosberger: early reinforcement biases strategy, so do not linger on ballistic threshold
crossing.

### Parameter-file column map
User confirmed 29 Sep 2026: the **27-column** files have the correct order.
Follow `parameters/README.md`. White/push goes in the columns named X
(indices 0, 2, 10, 12). Red/lateral goes in the columns named Y. The loader
reads cases 0–26, including reward delay, cue, and spout. There is no ×2 on
`home X2`.

The table below is the 08/09/26 21-column map. Its X/Y axis labels are
reversed relative to the live loader. Do not write a new file from it.

| Index | Field | Axis / role |
|------|--------|----------------|
| 0, 2 | `home X1`, `home X2` | OBSOLETE LABEL: this row called X lateral. Live files put **push** here. |
| 1, 3 | `home Y1`, `home Y2` | OBSOLETE LABEL: this row called Y push. Live files put **lateral** here. |
| 4 | `home TO` | ms; AND FSR |
| 5–8 | `start` X/Y | unused while start TO = 0 |
| 9 | `start TO` | keep 0 |
| 10, 12 | `end X1`, `end X2` | OBSOLETE LABEL: live files put the **push** target here. |
| 11, 13 | `end Y1`, `end Y2` | OBSOLETE LABEL: live files put **lateral** here. |
| 14 | `end TO` | ms dwell |
| 15, 16 | `mag`, `magtime` | 0 / 25 until resistance |
| 17 | `watertime` | 130/185/240 → 4/6/8 µl |
| 18 | `timeout` | Case 0 ITI (ms) |
| 19 | `move time` | Case 3 window (ms). The shorter-pull file used **400** |
| 20 | `light` | keep 0 |

Old pull files (typical values): home `2.39 2 2.8 3`, home TO `500`, start TO `0`,
end shaped per filename, end TO `50`, mag `0` or `2.2`, watertime `100`/`200`,
timeout `1000`, move time `400`. **Do not copy those end voltages or `magtime=100`.**

How they actually trained: one **identical-row** file per stage (500–612 lines; one 2964-line
baseline), then swapped files when the mouse was ready. Target “center/bound” lived in the
filename (`2.55center`, `2.3bound`, `.05bound` = ±0.05 V ≈ ±1 mm on the original 0.05 V/mm
assumption). “UNBOXED” files widened the end box so overshoot still counted. Experimental
sessions were concatenated blocks in one file (e.g. Task1 ≈ 157 zero-force + 100 × `mag=2.2` /
`magtime=100`). **Do not copy those voltages or `magtime=100`.** Original perturbation was a
brief lateral kick at trial start, not sustained axial resistance 100 ms after movement onset.
Confirm the live unbundle map on the rig before writing any push file.

### Practical LabVIEW / rig implications from this plan (07/09/26)
Already enough for stages 2–5 once geometry and volts-to-mm exist: `end` box + `end TO` is the
zone+dwell; Case 3 already allows correction until `move time`; `home TO` is the rest-pad hold
(FSR is ANDed into that same timer); `start TO=0` is fine because rest-pad + object-home replaces
Mathis’ start-box wait; `mag=0` throughout training.
- **Need before first mouse, not a new state machine:** shaft+handle+constrainer are fitted and
  the ripped FSR was replaced 08/09/26 with protective tape (working). Water µl/pulse is done
  (`calibration/water-volume.md`; 130/185/240 ms → 4/6/8 µl). Still: spring return without
  bounce into the micro-push threshold, freeze rest-to-object geometry, volts-to-mm, joystick
  noise, actuator settle time, FSR hysteresis on the taped surface, and which logged axis
  actually moves (`Y_POS` index 0 vs `X_POS` index 1).
- **Need for stage 1 (small LabVIEW):** a habituation control that runs `cue → delay → water`
  without a successful push. Manual water exists; the automated pair does not, because the water
  loop only wakes on Case 4.
- **Early-training movement window:** user declined the FSR lift-off Case 5
  edit (09/09/26). Case 3 still does `(now − trail start) > move time` with
  `trail start` written in Case 2. Lengthen column 20 (`move time`) instead;
  bench file is 30000 ms. Do not edit the Case 2 output constant 3.
- **Need before useful training data:** event logging + session metadata (stage, file, every
  front-panel value). Trajectory logging already exists.
- **Nice before animals, not blocking shaping:** FSR hysteresis/debounce; optional paw-release
  before rearm so a planted paw cannot auto-retrigger; session summary of success / wrong-paw
  (wrong-paw is video, not DAQ).
- **Defer until resistance:** movement-onset detector, 100 ms delayed magnet onset, hold `mag`
  until trial end instead of a 100 ms pulse. Do not reuse old `magtime=100`. Velocity-settling
  gate is optional if 50 ms dwell in a 2–4 mm zone already rejects ballistic crossings.
- **Parameter files are 27 columns (09/09/26).** Indices 21–26: `reward delay`,
  `cue duration`, `spout extend`, `spout settle`, `consumption`, `spout retract`.
  Files are updated. Loader 21→27, both FP cluster copies (`exp values` and
  `exp para array`), cases 21–26, and water-loop field wiring were completed
  and reported runtime-working on the rig PC 09/09/26. Keep old FP controls
  temporarily as references/fallbacks. **Repository import DONE 21/09/26:** all
  four rig-tested binaries copied into repo root (`Push Behaviour_MCHALABI.vi`,
  `avg joystick and frame trig lick3.vi`, `PushTask Globals.vi`, `frame counter.vi`);
  SHA-256 verified against Downloads transfer; main VI updated (251539 B, 27-col
  loader + water-loop wiring); three helpers byte-identical to prior repo copies.
  Stage 6 files: `parameters/training/06_delay_{0,250,500,1000}.txt`.

### Training controls to add to the canonical main VI
- Use one main VI with a `Training stage` enum: `Habituation`, `Rest only` (fallback),
  `Micro push`, `Proximal zone`, `Zone translation`, `Zone refine`, `Delay`, `Expert`,
  `Shadow`, `Experiment`. Do not maintain separate stage-specific VIs.
- Adjustable/logged controls: FSR on/off thresholds + hysteresis, rest hold, push threshold, target
  bounds/hold, cue enable/duration, reward delay, spout extend/retract voltages, settle time,
  consumption time.
- Safe manual controls: water, cue test, spout extend/retract, hardware output enable, plus a
  habituation button/mode that runs the full `cue → delay → water` sequence without Case 4.
- Live indicators: task state, FSR voltage/paw state, joystick position, success criterion, cue state,
  commanded spout position.
- Keep hardware calibration values on the VI; use stage-specific parameter files for behavioural
  criteria. Log the selected stage and every adjustable value with each session.

## Current VI architecture (original Mathis code — still the base)
Five-state machine in middle While loop (state in shift register) + async helper loops via occurrences/queues:

| Case | Role |
|------|------|
| 0 | Inter-trial gate: object in `home` ROI held for `home TO` **AND** `timeout` elapsed → Case 1 |
| 1 | Wait for object in `start` ROI held for `start TO` → Case 2 |
| 2 | Stamp trial start; **Set Occurrence** (wakes magnet loop) → Case 3 |
| 3 | Movement window: timeout → fail to Case 0; enter `end` ROI + hold `end TO` → Case 4 |
| 4 | Success: **Set reward occurrence** (wakes water loop); stamp inter-trial clock → Case 0 |

- **Magnet loop:** Wait on Occurrence → AO `Magnets` = `mag` for `magtime`, then 0; increments `Trial #`
- **Water loop:** Wait on Occurrence → DO `water` True for `watertime`, then False (Flat Sequence in occurrence-received / `False` timeout case)
- ROI checks AND X-in-range with Y-in-range; per-trial params from `exp para array` (text file → loader For-loop → cluster array)
- Live rig NI-MAX tasks (04/08/26): `joysticklickframe`, `Magnets_Dev1`, `Water_Dev1`, `frame counter_Dev1`, `MyPulseOutputTask`, `testing1blox_2labviews`
- Confirmed `joysticklickframe`: X=`Dev1/ai0`, Y=`Dev1/ai1`, differential ±10 V, continuous 10 kHz; device is **NI PCIe-6321**

### Already supported (configure via params / minimal code)
1. **Bounded target zone** — Case 3 `end` ROI + `end TO`
2. **Block structure** — one parameter-file line per trial
3. **Washout kinematics** — full trajectory already logged; analyze offline
4. **1D via params + physical constraint** — keep LabVIEW 2D coordinate structure; redefine task-relevant axis in parameter file; **physically constrain lateral axis with the existing 3D-printed 1D-axis constrainer** (no need to delete Y logic for v1)

### Real work remaining
(a) print and fit the joystick shaft plus a chosen handle, then add spring return and the steel
target, (b) finalize the animal-safe FSR cap and hysteresis, (c) calibrate volts-to-mm, joystick
noise, water µl/pulse and spout settle, then write stage parameter files in the existing 21-column
format, (d) add habituation cue–reward triggering, event logging and session metadata, (e) later:
movement-onset-triggered axial resistance and force-calibrate the Ledex, (f) only then Baseline /
Random / Fixed / Washout files.

## Locked hardware & design decisions (Weekly Update 29/06/26)

| Role | Choice | DAQ | Notes |
|------|--------|-----|-------|
| 1D constraint | Existing **3D-printed 1D-axis constrainer** | — | Lateral axis may remain in code; physically constrained |
| Push object | 3D-modeled **89 mm joystick shaft** + interchangeable tip-mounted handle (rounded cube or 38 mm bar) | reuse push-axis AI | Position contact surface **below the mouse** in its natural forelimb workspace and close to the rest pad; use a short forgiving reach and push-biased geometry that discourages grasping like the original pull handles. The cube has three holes to set reach and object weight over the joystick. Animal leaves rest → contacts → pushes (not continuous grip across ITI). Spring-loaded return to home. Shape push distance gradually in training. |
| Rest-pad gate | **Both** required: object in home (spring-loaded) **AND** forepaw on rest pad | — | Binary trial-gating, not posture standardization |
| Rest-pad sensor | **FSR** (binary on/off via threshold + hold duration) | spare **AI** → LabVIEW | Not a precision force meter. **Not** real-time DLC for v1 (slower to stand up); revisit vision trigger only if FSR false pos/neg during piloting |
| Retractable lick spout | **Actuonix linear actuator** | new **AO** position command (0–5 V); separate motor PSU, shared GND | Simple reliable in/out; keep existing `water` DO for valve |
| Success cue | **Brief auditory cue** at trial success | new **DO** (or AO) to clicker/speaker driver | **Supersedes** earlier ERM vibration plan (Mackenzie: vibe adds mass, changes object mechanics, imaging movement artefacts). Cue is discrete, timestamped, separated from perturbation onset and reward |
| Axial resistance | Ledex `195224-230` (EU/CH equivalent of Mathis `69905K25`), mounted **axially** | `Dev1/ao0` (`MagnetPush_Dev1`) | Received 02/09/26; not mounted or wired. Copy mesoscope drive electronics. Force-calibrate; do not assume 2.2 V / 100 ms transfers |

### Superseded (do not implement for v1)
- ERM vibration motor on the manipulandum (Adafruit 1201 + MOSFET 5648) — rejected after Mackenzie discussion
- Real-time DLC as primary rest-pad trigger — deferred fallback only

### Hardware selections and status — picks finalized 09/07/26
- **Rest-pad FSR:** Interlink **FSR 402** solder-tab (PN 30-81794), ~$3 — buyinterlinkelectronics.com / Mouser-Digikey (search 30-81794). Backup: FSR 402 Short Tail (34-00015) if pad is tiny; FSR X 402 for durability. + one **10 kΩ** divider resistor + shielded wire → spare **AI** (channel TBD after live inventory; `ai0` and `ai1` are occupied). `paw_on = V > threshold`.
- **Lick spout:** **Actuonix L12-30-50-12-I** (30 mm, 50:1, 12 V, integrated controller, **0–5 V** position mode). EU: noDNA (~€173) / RS stock 202-0768 (~£146). Ships with brackets + clevis/threaded rod ends. Backup MB1 clevis (Firgelli). Avoid -R/-P (PWM / external LAC). + **12 V ≥1 A PSU, shared GND** + 3D-print carriage + blunt lick tube + tubing. Keep existing `water` DO valve.
- **Auditory cue:** start with **Adafruit 5 V active buzzer (#1536, ~$1)** on a **DO** line (fixed ~2 kHz beep, trivial LabVIEW). Upgrade for chosen frequency: passive piezo (TDK PS1240) or small speaker + **Adafruit PAM8302 amp (#2130)** driven by a **6321 counter output** (LabVIEW-native square wave, ~50–100 ms). Teensy+audio only if calibrated tones later needed.
- **Push object:** CAD imported 05/09/26 — 89 mm shaft plus tip-mounted bar or rounded-cube handle. Print/fit still pending. Add a light return spring (auto-return to home) and reuse the push-axis readout. Ferromagnetic target: Mathis used a small steel ring on an aluminum handle base with **no catalog number**. Make one from a **mild-steel DIN 125 washer** (zinc-plated carbon steel OK; not A2/A4 stainless). Solenoid face is ~20 mm; a washer OD of ~12–20 mm (M6–M10) is a starting size. Embed/glue it on the object facing the solenoid. Mount the pull solenoid on the home side so attraction resists the push.
- **Perturbation magnet (ARRIVED 02/09/26):** Ledex / Johnson Electric **`195224-230`**, STA 75L **60° pull**, 12 VDC 7 W 20.7 Ω, Contact Evolution SA (Payerne). ~20 mm × 40 mm tubular body. Used like Mathis: coil as electromagnet attracting a steel target, not as a plunger mechanically linked to the object. Drive via `MagnetPush_Dev1` on `Dev1/ao0`; do not power the coil from the DAQ AO pin.

### RIG CONSTRAINT — AO channels are the bottleneck
Live rig uses **NI PCIe-6321** (not the previously assumed 6251). Actuonix is installed on `Dev1/ao1`. The received training-rig magnet (Ledex `195224-230`) is intended for `Dev1/ao0` but not yet wired. Both outputs are software-timed/on-demand; NI documents support for one such AO task per physical AO channel. Therefore keep magnet support as a one-channel AO0 task and the spout as an independent one-channel AO1 task. Hardware-timed AO would instead require a combined task.

### Target DAQ channel map (post-additions)
Training rig target: AI X=`Dev1/ai0` + AI Y=`Dev1/ai1` + AI rest pad=`Dev1/ai2` · AO magnet=`Dev1/ao0` (`MagnetPush_Dev1`; Ledex `195224-230` received, not yet wired) · AO lick-spout position=`Dev1/ao1` · DO water=`Dev1/port0/line0` · DO success cue=`Dev1/port0/line1` · frame sync=`Dev1/ctr0` input on `PFI8`; pulse output=`Dev1/ctr1` on `PFI13` at 50 Hz. Mesoscope-rig magnet mapping remains to be audited separately.

## LabVIEW edit plan (concrete)

### 1. Collapse to 1D (Cases 0, 1, 3) — mostly params + hardware
- Keep existing coordinate structure; set task-relevant axis bounds in parameter file
- Lateral axis: leave in code; rely on the 3D-printed 1D-axis constrainer
- Optional later cleanup: delete Y comparators

### 2. Rest-pad gate (Cases 0 / optionally 1) — locked: both conditions
- Read FSR; `paw_on = voltage > threshold` (+ minimum hold, reuse existing hold-time pattern)
- Trial start only when: **object in home** AND **forepaw on rest pad**
- AND into home-hold path: `inside_home_ROI AND paw_on_pad`
- Live Case 0 audit 12/08/26 confirms the exact insertion: AND `paw_on_pad` with the existing X/Y
  `inside_home_ROI` Boolean **before** its existing `home TO` hold-timer Case Structure. The held result
  then continues into the existing final AND with the inter-trial timeout condition.
- Live acquisition-subVI audit 12/08/26: `avg joystick and frame trig lick3.vi` reads saved task
  `joysticklickframe` as Analog 2D `NChan NSamp`, averages indexed channels 0–3, builds a four-value
  array, and enqueues it as `joystick pos`. Preserve the original global task; create
  `joysticklickframe_push` with X=`ai0`, Y=`ai1`, rest pad=`ai2` in that order, then select it in the
  working-copy subVI. Rest-pad voltage will be queue element index 2.
- `joysticklickframe_push` created/configured/tested 12/08/26: ordered `ai0`, `ai1`, `ai2`;
  `ai0`/`ai1` differential ±10 V, `ai2` RSE 0–5 V; Continuous Samples, 10 samples/read, 10 kHz.
  NI-MAX simultaneously displayed working joystick X/Y and pressure-responsive FSR signals.
- Working-copy `avg joystick and frame trig lick3.vi` task constant changed from
  `joysticklickframe` to `joysticklickframe_push` and saved 12/08/26.
- Working-copy main VI Case 0 now indexes `element[2]` into a `rest pad voltage` indicator; existing
  state logic now uses it. A `rest pad threshold (V)` control (initial default 0.10 V) and
  `paw on rest pad = rest pad voltage > threshold` indicator feed a new second-stage AND after the
  original X/Y home-ROI AND and before the existing `home TO` hold Case Structure. Timeout logic is
  unchanged. Runtime test passed: FSR voltage and Boolean behaved correctly once the state machine
  returned to Case 0 after reward. The apparent initial failure occurred because indicators inside a
  Case Structure update only while that case executes. Index 2 and its wiring are correct.
- Original state shift-register initializer changed from `1` to `0` in the working VI. Fresh-run
  validation passed 12/08/26: the first trial remains gated until paw contact.

### 3. Axial resistance (Magnet loop)
- Preserve the occurrence-driven magnet logic; change its AO task/write from the original two-channel
  configuration to a one-channel, software-timed/on-demand AO0 task so AO1 remains exclusive to the
  spout. Do not delete magnet support while the received hardware awaits installation
- Live loop audit 18/08/26 confirms two `Analog 1D DBL NChan 1Samp` writes using `Magnets_Dev1`:
  an activation write and a later reset-to-zero write. Convert both to single-channel AO0 writes
  using a new `MagnetPush_Dev1` task; leave the separate counter/laser path unchanged
- `MagnetPush_Dev1` created and saved 18/08/26: `Dev1/ao0` only, ±10 V, 1 Sample (On Demand);
  not physically run because no magnet was connected at that time
- Working-copy magnet-loop task constant changed from `Magnets_Dev1` to `MagnetPush_Dev1` on
  18/08/26. Both writes converted to `Analog DBL 1Chan 1Samp`: activation receives scalar `mag`,
  reset receives scalar `0`, and both retain auto-start=True. AO1 is no longer touched by the
  magnet path; Run arrow remained solid after saving. Physical magnet validation remains until
  the received Ledex is installed and force-calibrated
- Training-rig magnet RECEIVED 02/09/26: Ledex `195224-230` from Contact Evolution SA
  (Payerne). Mount axially, opposing the push. Copy the mesoscope-rig coil-drive electronics;
  never wire the solenoid coil directly to the PCIe-6321 AO pin
- Mesoscope rig: audit its DAQ/magnet wiring before enabling imaging perturbation trials
- Prefer **constant load** for adaptation/aftereffect science
- Minimal: `magtime ≈ move time` in param file; sign opposes push
- Cleaner: hold `mag` until trial-end occurrence from Case 4 and Case 3 timeout
- Random block: **pre-script** `mag` in parameter file

### 4. Auditory success cue + delayed spout reward (Water loop)
Insert into water loop **occurrence-received (`False`) case**, inside the existing Flat Sequence:

- Live audit 18/08/26 confirms the current functional frames are exactly:
  `Water_Dev1 HIGH → wait watertime → Water_Dev1 LOW`. Preserve these and add frames around them.
- Final saved tasks created 18/08/26: `SuccessCue_Dev1`=`Dev1/port0/line1`, digital one-sample
  on-demand; `LickSpout_Dev1`=`Dev1/ao1`, 0–5 V, one-sample on-demand
- Three empty cue frames inserted before the original water-HIGH frame on 18/08/26; existing
  water HIGH/wait/LOW sequence remains intact
- Cue frames wired 18/08/26 as `SuccessCue_Dev1 HIGH → Wait cue duration → SuccessCue_Dev1 LOW`;
  front-panel `cue duration (ms)` control added with default 50 ms. Runtime test passed: one brief
  cue occurred per successful trial and stopped cleanly
- Five empty reward/spout frames inserted 18/08/26 in the correct order: three between cue LOW and
  water HIGH (reward delay, extend, settle), two after water LOW (consumption, retract)
- Reward/spout frames wired 18/08/26 with front-panel defaults: reward delay=0 ms;
  `LickSpout_Dev1` extend initially 1.0 V with auto-start; settle initially 3000 ms;
  consumption=2000 ms; retract=0 V with auto-start. First runtime test produced expected coarse extension but also slight
  continued fine extension during the familiar audible post-arrival settling period. Determine
  whether motion/sound consistently stops within the 3000 ms window before classifying as normal
  closed-loop settling versus persistent hunting
- User-selected bench controls updated 18/08/26: cue=50 ms, reward delay=0 ms, spout extend=3.0 V,
  settle=2000 ms, consumption=2000 ms, retract=0 V, rest-pad threshold=0.01 V. Actuator settling
  sound/fine movement accepted provisionally. Automated sequence moves spout but currently delivers
  no water, while manual water delivery still works. `watertime` confirmed nonzero at 200 ms and no
  solenoid click is audible. NI-MAX `Water_Dev1` False→True→False test produces clicks and water;
  LabVIEW close-up confirms HIGH data=True and LOW data=False. Next inspect Water HIGH DAQmx error;
  Water HIGH error indicator remained clear during a failed automated reward. This proves the HIGH
  write executes and strongly indicates LOW follows immediately because the middle duration frame
  lacks an effective wait. Adding Wait(ms)=200 produced a click but no water. Do not assume placement:
  user reports the Wait was already put in a dedicated frame and the original VI delivers water
  without this added node. Obtain readable close-ups of the modified and original
  `HIGH → timing mechanism → LOW` regions and identify the original blue timing object/wiring before
  further edits
- Diagnostic dedicated 1000 ms HIGH duration succeeded 18/08/26: automated valve produced water.
  Therefore task/channel/write sequencing is functional; 200 ms was below the currently reliable
  effective delivery duration or the line required priming. Retest 200 ms immediately after priming,
  then find and volumetrically calibrate the shortest reliable pulse—do not use 1000 ms for animals
- Retest after the 1000 ms prime confirmed automated 200 ms delivery works. User observed multiple
  air bubbles in the tubing; root cause was an unprimed/air-filled water path, not LabVIEW or DAQ.
  Add tubing inspection + manual prime until bubble-free to every pre-session checklist; retain
  200 ms only as a bench value pending gravimetric µL calibration
- Three spaced full-sequence trials passed 18/08/26: one cue, spout extension, one water delivery,
  and retraction each time, without reported persistent motion or missed rewards. Core v1 hardware
  integration is bench-functional. New explicit 200 ms Wait is nominally equivalent to original
  `watertime=200`, but physical pulse equivalence remains unmeasured; compare delivered volume or
  measure P0.0 HIGH duration before claiming exact equivalence

```text
Frame 0: auditory success cue pulse (immediate on reward occurrence)
Frame 1: Wait reward delay (fixed; introduce gradually in training)
Frame 2: AO lick_spout_position = extend
Frame 3: Wait spout settle
Frame 4–5: water ON / OFF (existing)
Frame 6: optional consumption Wait
Frame 7: AO lick_spout_position = retract
```

Training note: early stages may set delay ≈ 0 and/or deliver cue concurrent with water; later stages lengthen delay so cue precedes spout/reward.

### 5. Success cue placement
- Immediate at success: first frame of water-loop False-case sequence (same occurrence as reward) **or** pulse in Case 4 for tightest time-lock
- Must be logged/timestamped for alignment

### 6. Parameter / cluster plumbing
- Extend for: reward delay, spout settle, consumption window, cue duration/params, training-stage values
- Re-check loader ×2 scaling index after column changes
- Build param files for training stages + full Baseline/Random/Fixed/Washout sessions
- Decide defaults (trial N, `mag` magnitudes, delay, etc.)

### 7. Audit `Trial #` off-by-one
- Magnet loop increments at trial **start**; water loop indexes at **success** — verify alignment; schedule length ≥ trial count

## Open decisions (narrowed)
1. Resistance type: constant axial load (preferred) vs velocity-dependent viscous field
2. Exact final reward-delay target within the locked 500–1000 ms range; acquisition ramp is locked at
   0 extra delay initially, then +50–100 ms/session after stable performance
3. Success cue LabVIEW site: Case 4 vs water-loop frame 0
4. Random-block `mag`: pre-scripted file (preferred) vs live RNG

## LabVIEW safety rules (from recovery work)
- Never hand-edit `.vi` binary / internal names in a hex editor
- Rename/internal-name changes only via LabVIEW Save As / File » VI Properties
- Main public filename: `Push Behaviour_MCHALABI.vi`
- `.cursorrules` is gitignored — keep plan local; update after every step

## Notes (recovery history)
- Direct binary/internal-name edit caused Hex 0x2A load failure; restored from good commit; user re-saved in LabVIEW
- Internal name is now `Push Behaviour_MCHALABI` (was historically `Pull Behavior_mwaV10wLICK_2.vi` in recovered binary)
- Expected VI set: `Push Behaviour_MCHALABI.vi`, `avg joystick and frame trig lick3.vi`, `frame counter.vi`