From 7a82fa5f98b7d445f5062e2cbcd50bd9ecbe0418 Mon Sep 17 00:00:00 2001
From: Jemin Kachhadiya <jemin.b.kachhadiya@gmail.com>
Date: Wed, 26 Aug 2026 12:10:38 -0500
Subject: [PATCH 1/3] project re-structured and re-based all docs

---
 .github/workflows/base-station.yml            |  12 +-
 README.md                                     |  50 +-
 {docs => firmware/docs}/DISPENSE_CYCLE.md     |   3 +-
 {docs => firmware/docs}/HARDCODED_VALUES.md   |   4 +-
 {docs => firmware/docs}/WIRING.md             |   0
 {examples => firmware/examples}/Node/Node.ino |   0
 .../DispenseTest/DispenseTest.ino             |   0
 .../ActuatorCalTest/ActuatorCalTest.ino       |   0
 .../CanBusTest/CanBusTest.ino                 |   0
 .../HardwareExamples/LEDTest/LEDTest.ino      |   0
 .../MousePresenceTest/MousePresenceTest.ino   |   0
 .../PhotogateTest/PhotogateTest.ino           |   0
 .../StepperMotorTest/StepperMotorTest.ino     |   0
 .../library.properties                        |   0
 {src => firmware/src}/VFM.cpp                 |   0
 {src => firmware/src}/VFM.h                   |   0
 {src => firmware/src}/hardware/VFMPins.h      |   0
 {src => firmware/src}/services/CanService.cpp |   0
 {src => firmware/src}/services/CanService.h   |   0
 .../src}/services/DispenserService.cpp        |   0
 .../src}/services/DispenserService.h          |   0
 {src => firmware/src}/services/LedService.h   |   0
 .../src}/services/NodeIdentity.cpp            |   0
 {src => firmware/src}/services/NodeIdentity.h |   0
 .../src}/services/PresenceService.cpp         |   0
 .../src}/services/PresenceService.h           |   0
 {src => firmware/src}/services/ServiceTypes.h |   0
 {tools => packages}/dev_gui/README.md         | 139 ++--
 .../dev_gui/base_station/__init__.py          |   0
 .../dev_gui/base_station/app.py               |   0
 .../dev_gui/base_station/can_manager.py       |   0
 .../dev_gui/base_station/dev_settings.py      |   0
 .../dev_gui/base_station/discovery_manager.py |   0
 .../dev_gui/base_station/experiment/README.md | 725 ++++++++++++++++++
 .../base_station/experiment/__init__.py       |   8 +-
 .../base_station/experiment/context.py        |  61 +-
 .../dev_gui/base_station/experiment/events.py |   4 +-
 .../base_station/experiment/gui_controller.py |   8 +-
 .../dev_gui/base_station/experiment/kit.py    |   0
 .../dev_gui/base_station/experiment/runner.py |  58 +-
 .../dev_gui/base_station/experiment/schema.py |   2 +-
 .../dev_gui/base_station/experiment/script.py |   0
 .../experiment/templates/__init__.py          |   0
 .../experiment/templates/fixed_and_random.py  |   5 +-
 .../experiment/templates/free_feeding.py      |   1 -
 .../templates/probability_delivery.py         |   3 +-
 .../experiment/templates/two_armed_bandit.py  |   1 -
 .../dev_gui/base_station/io_manager.py        |   0
 .../dev_gui/base_station/log_manager.py       |   0
 .../dev_gui/base_station/mac_id_registry.py   |   0
 .../dev_gui/base_station/node_registry.py     |   0
 .../dev_gui/base_station/pellet_ledger.py     |   0
 .../dev_gui/base_station/protocol.py          |   0
 .../dev_gui/base_station/storage.py           |   0
 .../dev_gui/deploy/80-can.network             |   0
 {tools => packages}/dev_gui/deploy/README.md  |   8 +-
 .../dev_gui/deploy/boot-config-can.append.txt |   0
 .../dev_gui/deploy/setup-can.sh               |   4 +-
 .../docs}/BASE_STATION_HARDCODED_VALUES.md    |  14 +-
 {docs => packages/dev_gui/docs}/GUI.png       | Bin
 packages/dev_gui/examples/templates/README.md |  41 +
 .../examples/templates/alternation.json       |  37 +
 .../dev_gui/examples/templates/alternation.py |  70 ++
 .../dev_gui/examples/templates/bnc_paced.json |  46 ++
 .../dev_gui/examples/templates/bnc_paced.py   |  73 ++
 .../dev_gui/experiments/fixed_and_random.json |   0
 .../dev_gui/experiments/free_feeding.json     |   0
 .../experiments/probability_delivery.json     |   0
 .../dev_gui/experiments/two_armed_bandit.json |   0
 {tools => packages}/dev_gui/node_simulator.py |   0
 {tools => packages}/dev_gui/pytest.ini        |   0
 {tools => packages}/dev_gui/requirements.txt  |   2 +-
 {tools => packages}/dev_gui/run.py            |   0
 {tools => packages}/dev_gui/run_report.py     |   0
 {tools => packages}/dev_gui/setup_storage.sh  |   0
 {tools => packages}/dev_gui/tests/__init__.py |   0
 {tools => packages}/dev_gui/tests/test_app.py |   0
 .../dev_gui/tests/test_app_pellet_counting.py |   0
 .../tests/test_behavioral_log_names.py        |   0
 .../dev_gui/tests/test_discovery_manager.py   |   0
 .../dev_gui/tests/test_experiment.py          |   4 +-
 .../dev_gui/tests/test_experiment_schema.py   |  22 +
 {tools => packages}/dev_gui/tests/test_hat.py |   4 +-
 .../dev_gui/tests/test_log_manager.py         |   0
 .../dev_gui/tests/test_mac_id_registry.py     |   0
 .../dev_gui/tests/test_node_registry.py       |   0
 .../dev_gui/tests/test_pellet_ledger.py       |   0
 .../dev_gui/tests/test_protocol.py            |   0
 .../dev_gui/tests/test_run_report_shim.py     |   0
 .../dev_gui/tests/test_schedule.py            |   0
 .../dev_gui/tests/test_script.py              |   0
 .../dev_gui/tests/test_two_armed_bandit.py    |   0
 packages/sfm-analysis/README.md               |  31 +-
 packages/sfm-analysis/docs/ANALYSIS_GUIDE.md  | 107 ++-
 .../examples/analysis/exp_events_by_name.py   |  39 +
 .../examples/report_design/README.md          |  36 +
 .../report_design/analyses/alternation.py     |  29 +
 .../report_design/designs/alternation.json    |  23 +
 .../report_design/sections/alternation.py     |  56 ++
 .../sfm-analysis/src/sfm_analysis/__init__.py |   4 +-
 .../sfm-analysis/src/sfm_analysis/logs.py     |  17 +-
 .../sfm-analysis/src/sfm_analysis/protocol.py |   4 +-
 .../src/sfm_analysis/report/loader.py         |   4 +-
 .../sfm-analysis/tests/report_fixtures.py     |   2 +-
 packages/sfm-analysis/tests/test_examples.py  |   8 +
 .../dev_gui/base_station/experiment/README.md | 629 ---------------
 tools/dev_gui/example_experiment.py           |  53 --
 tools/dev_gui/run_experiment.py               | 281 -------
 tools/dev_gui/tests/test_run.py               |  91 ---
 109 files changed, 1507 insertions(+), 1316 deletions(-)
 rename {docs => firmware/docs}/DISPENSE_CYCLE.md (98%)
 rename {docs => firmware/docs}/HARDCODED_VALUES.md (99%)
 rename {docs => firmware/docs}/WIRING.md (100%)
 rename {examples => firmware/examples}/Node/Node.ino (100%)
 rename {examples => firmware/examples}/Troubleshooting/DispenseTest/DispenseTest.ino (100%)
 rename {examples => firmware/examples}/Troubleshooting/HardwareExamples/ActuatorCalTest/ActuatorCalTest.ino (100%)
 rename {examples => firmware/examples}/Troubleshooting/HardwareExamples/CanBusTest/CanBusTest.ino (100%)
 rename {examples => firmware/examples}/Troubleshooting/HardwareExamples/LEDTest/LEDTest.ino (100%)
 rename {examples => firmware/examples}/Troubleshooting/HardwareExamples/MousePresenceTest/MousePresenceTest.ino (100%)
 rename {examples => firmware/examples}/Troubleshooting/HardwareExamples/PhotogateTest/PhotogateTest.ino (100%)
 rename {examples => firmware/examples}/Troubleshooting/HardwareExamples/StepperMotorTest/StepperMotorTest.ino (100%)
 rename library.properties => firmware/library.properties (100%)
 rename {src => firmware/src}/VFM.cpp (100%)
 rename {src => firmware/src}/VFM.h (100%)
 rename {src => firmware/src}/hardware/VFMPins.h (100%)
 rename {src => firmware/src}/services/CanService.cpp (100%)
 rename {src => firmware/src}/services/CanService.h (100%)
 rename {src => firmware/src}/services/DispenserService.cpp (100%)
 rename {src => firmware/src}/services/DispenserService.h (100%)
 rename {src => firmware/src}/services/LedService.h (100%)
 rename {src => firmware/src}/services/NodeIdentity.cpp (100%)
 rename {src => firmware/src}/services/NodeIdentity.h (100%)
 rename {src => firmware/src}/services/PresenceService.cpp (100%)
 rename {src => firmware/src}/services/PresenceService.h (100%)
 rename {src => firmware/src}/services/ServiceTypes.h (100%)
 rename {tools => packages}/dev_gui/README.md (76%)
 rename {tools => packages}/dev_gui/base_station/__init__.py (100%)
 rename {tools => packages}/dev_gui/base_station/app.py (100%)
 rename {tools => packages}/dev_gui/base_station/can_manager.py (100%)
 rename {tools => packages}/dev_gui/base_station/dev_settings.py (100%)
 rename {tools => packages}/dev_gui/base_station/discovery_manager.py (100%)
 create mode 100644 packages/dev_gui/base_station/experiment/README.md
 rename {tools => packages}/dev_gui/base_station/experiment/__init__.py (65%)
 rename {tools => packages}/dev_gui/base_station/experiment/context.py (94%)
 rename {tools => packages}/dev_gui/base_station/experiment/events.py (99%)
 rename {tools => packages}/dev_gui/base_station/experiment/gui_controller.py (95%)
 rename {tools => packages}/dev_gui/base_station/experiment/kit.py (100%)
 rename {tools => packages}/dev_gui/base_station/experiment/runner.py (91%)
 rename {tools => packages}/dev_gui/base_station/experiment/schema.py (99%)
 rename {tools => packages}/dev_gui/base_station/experiment/script.py (100%)
 rename {tools => packages}/dev_gui/base_station/experiment/templates/__init__.py (100%)
 rename {tools => packages}/dev_gui/base_station/experiment/templates/fixed_and_random.py (97%)
 rename {tools => packages}/dev_gui/base_station/experiment/templates/free_feeding.py (99%)
 rename {tools => packages}/dev_gui/base_station/experiment/templates/probability_delivery.py (98%)
 rename {tools => packages}/dev_gui/base_station/experiment/templates/two_armed_bandit.py (99%)
 rename {tools => packages}/dev_gui/base_station/io_manager.py (100%)
 rename {tools => packages}/dev_gui/base_station/log_manager.py (100%)
 rename {tools => packages}/dev_gui/base_station/mac_id_registry.py (100%)
 rename {tools => packages}/dev_gui/base_station/node_registry.py (100%)
 rename {tools => packages}/dev_gui/base_station/pellet_ledger.py (100%)
 rename {tools => packages}/dev_gui/base_station/protocol.py (100%)
 rename {tools => packages}/dev_gui/base_station/storage.py (100%)
 rename {tools => packages}/dev_gui/deploy/80-can.network (100%)
 rename {tools => packages}/dev_gui/deploy/README.md (94%)
 rename {tools => packages}/dev_gui/deploy/boot-config-can.append.txt (100%)
 rename {tools => packages}/dev_gui/deploy/setup-can.sh (95%)
 rename {docs => packages/dev_gui/docs}/BASE_STATION_HARDCODED_VALUES.md (95%)
 rename {docs => packages/dev_gui/docs}/GUI.png (100%)
 create mode 100644 packages/dev_gui/examples/templates/README.md
 create mode 100644 packages/dev_gui/examples/templates/alternation.json
 create mode 100644 packages/dev_gui/examples/templates/alternation.py
 create mode 100644 packages/dev_gui/examples/templates/bnc_paced.json
 create mode 100644 packages/dev_gui/examples/templates/bnc_paced.py
 rename {tools => packages}/dev_gui/experiments/fixed_and_random.json (100%)
 rename {tools => packages}/dev_gui/experiments/free_feeding.json (100%)
 rename {tools => packages}/dev_gui/experiments/probability_delivery.json (100%)
 rename {tools => packages}/dev_gui/experiments/two_armed_bandit.json (100%)
 rename {tools => packages}/dev_gui/node_simulator.py (100%)
 rename {tools => packages}/dev_gui/pytest.ini (100%)
 rename {tools => packages}/dev_gui/requirements.txt (92%)
 rename {tools => packages}/dev_gui/run.py (100%)
 rename {tools => packages}/dev_gui/run_report.py (100%)
 rename {tools => packages}/dev_gui/setup_storage.sh (100%)
 rename {tools => packages}/dev_gui/tests/__init__.py (100%)
 rename {tools => packages}/dev_gui/tests/test_app.py (100%)
 rename {tools => packages}/dev_gui/tests/test_app_pellet_counting.py (100%)
 rename {tools => packages}/dev_gui/tests/test_behavioral_log_names.py (100%)
 rename {tools => packages}/dev_gui/tests/test_discovery_manager.py (100%)
 rename {tools => packages}/dev_gui/tests/test_experiment.py (99%)
 rename {tools => packages}/dev_gui/tests/test_experiment_schema.py (85%)
 rename {tools => packages}/dev_gui/tests/test_hat.py (99%)
 rename {tools => packages}/dev_gui/tests/test_log_manager.py (100%)
 rename {tools => packages}/dev_gui/tests/test_mac_id_registry.py (100%)
 rename {tools => packages}/dev_gui/tests/test_node_registry.py (100%)
 rename {tools => packages}/dev_gui/tests/test_pellet_ledger.py (100%)
 rename {tools => packages}/dev_gui/tests/test_protocol.py (100%)
 rename {tools => packages}/dev_gui/tests/test_run_report_shim.py (100%)
 rename {tools => packages}/dev_gui/tests/test_schedule.py (100%)
 rename {tools => packages}/dev_gui/tests/test_script.py (100%)
 rename {tools => packages}/dev_gui/tests/test_two_armed_bandit.py (100%)
 create mode 100644 packages/sfm-analysis/examples/analysis/exp_events_by_name.py
 create mode 100644 packages/sfm-analysis/examples/report_design/README.md
 create mode 100644 packages/sfm-analysis/examples/report_design/analyses/alternation.py
 create mode 100644 packages/sfm-analysis/examples/report_design/designs/alternation.json
 create mode 100644 packages/sfm-analysis/examples/report_design/sections/alternation.py
 delete mode 100644 tools/dev_gui/base_station/experiment/README.md
 delete mode 100644 tools/dev_gui/example_experiment.py
 delete mode 100644 tools/dev_gui/run_experiment.py
 delete mode 100644 tools/dev_gui/tests/test_run.py

diff --git a/.github/workflows/base-station.yml b/.github/workflows/base-station.yml
index 15589be..82d937e 100644
--- a/.github/workflows/base-station.yml
+++ b/.github/workflows/base-station.yml
@@ -4,12 +4,12 @@ on:
   push:
     branches: [main]
     paths:
-      - "tools/dev_gui/**"
+      - "packages/dev_gui/**"
       - "packages/sfm-analysis/**"
       - ".github/workflows/base-station.yml"
   pull_request:
     paths:
-      - "tools/dev_gui/**"
+      - "packages/dev_gui/**"
       - "packages/sfm-analysis/**"
       - ".github/workflows/base-station.yml"
   workflow_dispatch:
@@ -26,7 +26,7 @@ jobs:
     # everything else is importable and testable on a plain Linux runner.
     # The remaining ~26 tests (test_app.py, test_app_pellet_counting.py,
     # test_schedule.py, test_hat.py) are Pi-only and run manually — see
-    # tools/dev_gui/README.md.
+    # packages/dev_gui/README.md.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -35,9 +35,9 @@ jobs:
           python-version: "3.11"
       - run: pip install -e packages/sfm-analysis pytest python-can
       - name: syntax-check everything, including the GUI modules we cannot import
-        run: python -m compileall -q tools/dev_gui/base_station tools/dev_gui/*.py
+        run: python -m compileall -q packages/dev_gui/base_station packages/dev_gui/*.py
       - name: run the hardware-free base-station tests
-        working-directory: tools/dev_gui
+        working-directory: packages/dev_gui
         run: |
           pytest -q \
             tests/test_protocol.py tests/test_log_manager.py \
@@ -45,4 +45,4 @@ jobs:
             tests/test_pellet_ledger.py tests/test_mac_id_registry.py \
             tests/test_discovery_manager.py tests/test_experiment.py \
             tests/test_experiment_schema.py tests/test_script.py \
-            tests/test_two_armed_bandit.py tests/test_run.py
+            tests/test_two_armed_bandit.py
diff --git a/README.md b/README.md
index 617ea49..3afc8d1 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,23 @@
 # VFM
 
+Spatial Foraging Platform: node firmware, base-station developer GUI, and
+session analysis. Each application lives in its own directory.
+
 ## Launch the GUI
 
 ```
-cd Project/VFM/tools/dev_gui
+cd Project/VFM/packages/dev_gui
 python run.py
 ```
 
 ## Generate a behavior report
 
 ```
-cd Project/VFM/tools/dev_gui
+cd Project/VFM/packages/dev_gui
 python run_report.py
 ```
 
-With no arguments this opens an interactive session picker. For list/combine, date filters, designs, and other use cases, see [Behavior reports](tools/dev_gui/README.md#behavior-reports-session-csv--printable-html) in the GUI README.
+With no arguments this opens an interactive session picker. For list/combine, date filters, designs, and other use cases, see [Behavior reports](packages/dev_gui/README.md#behavior-reports-session-csv--printable-html) in the GUI README.
 
 Report generation itself is cross-platform — it doesn't need a Raspberry Pi or any base-station hardware library. It ships as its own package, [`sfm-analysis`](packages/sfm-analysis/), installable with `pip install sfm-analysis` on Windows, macOS, or Linux; `run_report.py` above is a thin wrapper around its `sfm-report` CLI. See [packages/sfm-analysis/README.md](packages/sfm-analysis/README.md).
 
@@ -22,33 +25,38 @@ Report generation itself is cross-platform — it doesn't need a Raspberry Pi or
 
 VFM is a firmware library for the Spatial Foraging Platform node. It provides non-blocking, service-oriented stepper-driven pellet dispensing, CAN bus communication with a base-station command/event/heartbeat protocol.
 
+The Arduino library is the `firmware/` folder (not the repo root). Copy or symlink `firmware/` into `Arduino/libraries/VFM`, or zip that folder and add it via *Sketch → Include Library → Add .ZIP Library…*.
+
 ## Documentation
 
 | Doc | What it's for |
 |-----|---------------|
-| [tools/dev_gui/README.md](tools/dev_gui/README.md) | Base-station GUI: install, run, CAN bring-up, experiments, session logs, and behavior reports |
-| [tools/dev_gui/deploy/README.md](tools/dev_gui/deploy/README.md) | One-time Raspberry Pi CAN HAT setup (`can0`) before running against real hardware |
-| [tools/dev_gui/base_station/experiment/README.md](tools/dev_gui/base_station/experiment/README.md) | How to author custom experiment templates (Python API + JSON params) |
+| [packages/dev_gui/README.md](packages/dev_gui/README.md) | Base-station GUI: install, run, CAN bring-up, experiments, session logs, and behavior reports |
+| [packages/dev_gui/deploy/README.md](packages/dev_gui/deploy/README.md) | One-time Raspberry Pi CAN HAT setup (`can0`) before running against real hardware |
+| [packages/dev_gui/base_station/experiment/README.md](packages/dev_gui/base_station/experiment/README.md) | How to author custom experiment templates (Python API + JSON params) |
 | [packages/sfm-analysis/README.md](packages/sfm-analysis/README.md) | Cross-platform session analysis and report generation — install, CLI, report design/section architecture, Python API |
 | [packages/sfm-analysis/docs/ANALYSIS_GUIDE.md](packages/sfm-analysis/docs/ANALYSIS_GUIDE.md) | Analysis reference: every log column, event name, derived metric field, and tidy-table column, plus a worked example |
-| [docs/WIRING.md](docs/WIRING.md) | Firmware pin names → physical jobs (motors, sensors, CAN, LEDs, discovery) |
-| [docs/DISPENSE_CYCLE.md](docs/DISPENSE_CYCLE.md) | How a node loads, raises, and reports pellet take / faults during a dispense |
-| [docs/HARDCODED_VALUES.md](docs/HARDCODED_VALUES.md) | Tunable firmware constants checklist (timings, speeds, thresholds) |
-| [docs/BASE_STATION_HARDCODED_VALUES.md](docs/BASE_STATION_HARDCODED_VALUES.md) | Base-station timings and defaults (GUI, experiments, reports) |
+| [firmware/docs/WIRING.md](firmware/docs/WIRING.md) | Firmware pin names → physical jobs (motors, sensors, CAN, LEDs, discovery) |
+| [firmware/docs/DISPENSE_CYCLE.md](firmware/docs/DISPENSE_CYCLE.md) | How a node loads, raises, and reports pellet take / faults during a dispense |
+| [firmware/docs/HARDCODED_VALUES.md](firmware/docs/HARDCODED_VALUES.md) | Tunable firmware constants checklist (timings, speeds, thresholds) |
+| [packages/dev_gui/docs/BASE_STATION_HARDCODED_VALUES.md](packages/dev_gui/docs/BASE_STATION_HARDCODED_VALUES.md) | Base-station timings and defaults (GUI, experiments, reports) |
 
 ## Project structure
 
 ```
 VFM/
-├── src/                  # Arduino library (ESP32-S3 node firmware)
-│   ├── VFM.h / VFM.cpp   # Library entry point
-│   ├── hardware/         # Pin definitions
-│   └── services/         # CAN bus, dispenser, node identity, presence, LED services
-├── examples/             # Arduino sketches
-│   ├── Node/             # Main node firmware sketch
-│   └── Troubleshooting/  # Hardware bring-up / diagnostic sketches
-├── docs/                 # Wiring, dispense cycle, and hardcoded-value reference docs
-├── tools/dev_gui/        # Python base-station GUI + CAN tooling (see tools/dev_gui/README.md)
-├── packages/sfm-analysis/  # Cross-platform session analysis / report SDK (pip install sfm-analysis)
-└── library.properties    # Arduino library metadata
+├── firmware/                 # Arduino library (ESP32-S3 node)
+│   ├── src/                  # VFM.h / services / pin definitions
+│   ├── examples/             # Node sketch + hardware bring-up sketches
+│   ├── docs/                 # Wiring, dispense cycle, firmware tunables
+│   └── library.properties
+├── packages/
+│   ├── dev_gui/              # Raspberry Pi developer GUI + CAN tooling
+│   │   ├── experiments/      # JSON schemas for built-in experiments
+│   │   ├── examples/templates/  # Copy-from custom experiment starters
+│   │   └── base_station/experiment/  # Engine + templates (see its README)
+│   └── sfm-analysis/         # Cross-platform session analysis / report SDK
+│       ├── docs/ANALYSIS_GUIDE.md
+│       └── examples/         # Analysis recipes + a custom report-design starter
+└── README.md
 ```
diff --git a/docs/DISPENSE_CYCLE.md b/firmware/docs/DISPENSE_CYCLE.md
similarity index 98%
rename from docs/DISPENSE_CYCLE.md
rename to firmware/docs/DISPENSE_CYCLE.md
index a2997a0..48ccd1b 100644
--- a/docs/DISPENSE_CYCLE.md
+++ b/firmware/docs/DISPENSE_CYCLE.md
@@ -214,6 +214,7 @@ Node → base on CAN ID `0x300 + nodeId`. Byte 0 is the event code.
 | `0x0E` | `NoFeedPresented` | count LE16 (unchanged)     | A no-feed raise finished; empty plate at the top. `count` does NOT increment |
 | `0x0F` | `Dwelling`        | count LE16                 | Phase entered: holding at the drop position, M1 idle (no-feed cycle)   |
 | `0x10` | `PresenceCalResult` | ok(1), threshold LE32, samples LE16 | Response to a `CalibratePresence` command — see below      |
+| `0x11` | `ConfigApplied`     | configType(1), ok(1), value LE32    | Ack of a `SetConfig` (heartbeat interval, presence factor) |
 
 
 `count` is the node's running total of `Loaded` milestones — `NoFeedPresented` deliberately does not advance
@@ -226,7 +227,7 @@ the number that appears in logs or reports. The base station keeps its own per-r
 at zero when a session opens, and folds the node's counter in as a **delta** so a milestone frame lost to the
 bus is recovered by the next frame carrying the count (or by the next heartbeat) and reported as a gap rather
 than silently dropped. The node counter is the independent witness that makes that detection possible, which
-is why the firmware still sends it. See `tools/dev_gui/base_station/pellet_ledger.py`.
+is why the firmware still sends it. See `packages/dev_gui/base_station/pellet_ledger.py`.
 
 **Presence recalibration.** `CanCmd::CalibratePresence` (`0x09`, no payload, broadcast-friendly) starts a fresh
 5 s idle-pad capture on the presence sensor — the same action as a short `PIN_BTN` click. The node replies with
diff --git a/docs/HARDCODED_VALUES.md b/firmware/docs/HARDCODED_VALUES.md
similarity index 99%
rename from docs/HARDCODED_VALUES.md
rename to firmware/docs/HARDCODED_VALUES.md
index f951102..acd23da 100644
--- a/docs/HARDCODED_VALUES.md
+++ b/firmware/docs/HARDCODED_VALUES.md
@@ -3,7 +3,7 @@
 Living note of firmware constants that may need changing after bench or field tweaks.
 **Update this file when you change a default.** Source of truth remains the code; this is the checklist.
 
-GUI / experiment / report defaults: [BASE_STATION_HARDCODED_VALUES.md](BASE_STATION_HARDCODED_VALUES.md).
+GUI / experiment / report defaults: [BASE_STATION_HARDCODED_VALUES.md](../../packages/dev_gui/docs/BASE_STATION_HARDCODED_VALUES.md).
 
 Pins (`VFMPins.h`) and CAN ID opcodes (`ServiceTypes.h`) are omitted unless they carry timing or motion meaning.
 For what these timers guard and where they sit in the cycle, see [DISPENSE_CYCLE.md](DISPENSE_CYCLE.md).
@@ -67,7 +67,7 @@ Not overrideable via SetConfig CAN yet — only compile-time / setter before beg
 **No tunables.** A no-feed cycle holds at the drop position until it sees a `Raising` event from another
 node on the bus, then raises. There is no dwell constant, no clamp, and no payload on `DispenseNoFeed` —
 the fed node's own raise is the timing reference, so nothing here needs tuning per rig. See
-`docs/DISPENSE_CYCLE.md` § No-feed dispense.
+[DISPENSE_CYCLE.md](DISPENSE_CYCLE.md) § No-feed dispense.
 
 There is also no timeout: a node whose peer never raises holds until `Recover`.
 
diff --git a/docs/WIRING.md b/firmware/docs/WIRING.md
similarity index 100%
rename from docs/WIRING.md
rename to firmware/docs/WIRING.md
diff --git a/examples/Node/Node.ino b/firmware/examples/Node/Node.ino
similarity index 100%
rename from examples/Node/Node.ino
rename to firmware/examples/Node/Node.ino
diff --git a/examples/Troubleshooting/DispenseTest/DispenseTest.ino b/firmware/examples/Troubleshooting/DispenseTest/DispenseTest.ino
similarity index 100%
rename from examples/Troubleshooting/DispenseTest/DispenseTest.ino
rename to firmware/examples/Troubleshooting/DispenseTest/DispenseTest.ino
diff --git a/examples/Troubleshooting/HardwareExamples/ActuatorCalTest/ActuatorCalTest.ino b/firmware/examples/Troubleshooting/HardwareExamples/ActuatorCalTest/ActuatorCalTest.ino
similarity index 100%
rename from examples/Troubleshooting/HardwareExamples/ActuatorCalTest/ActuatorCalTest.ino
rename to firmware/examples/Troubleshooting/HardwareExamples/ActuatorCalTest/ActuatorCalTest.ino
diff --git a/examples/Troubleshooting/HardwareExamples/CanBusTest/CanBusTest.ino b/firmware/examples/Troubleshooting/HardwareExamples/CanBusTest/CanBusTest.ino
similarity index 100%
rename from examples/Troubleshooting/HardwareExamples/CanBusTest/CanBusTest.ino
rename to firmware/examples/Troubleshooting/HardwareExamples/CanBusTest/CanBusTest.ino
diff --git a/examples/Troubleshooting/HardwareExamples/LEDTest/LEDTest.ino b/firmware/examples/Troubleshooting/HardwareExamples/LEDTest/LEDTest.ino
similarity index 100%
rename from examples/Troubleshooting/HardwareExamples/LEDTest/LEDTest.ino
rename to firmware/examples/Troubleshooting/HardwareExamples/LEDTest/LEDTest.ino
diff --git a/examples/Troubleshooting/HardwareExamples/MousePresenceTest/MousePresenceTest.ino b/firmware/examples/Troubleshooting/HardwareExamples/MousePresenceTest/MousePresenceTest.ino
similarity index 100%
rename from examples/Troubleshooting/HardwareExamples/MousePresenceTest/MousePresenceTest.ino
rename to firmware/examples/Troubleshooting/HardwareExamples/MousePresenceTest/MousePresenceTest.ino
diff --git a/examples/Troubleshooting/HardwareExamples/PhotogateTest/PhotogateTest.ino b/firmware/examples/Troubleshooting/HardwareExamples/PhotogateTest/PhotogateTest.ino
similarity index 100%
rename from examples/Troubleshooting/HardwareExamples/PhotogateTest/PhotogateTest.ino
rename to firmware/examples/Troubleshooting/HardwareExamples/PhotogateTest/PhotogateTest.ino
diff --git a/examples/Troubleshooting/HardwareExamples/StepperMotorTest/StepperMotorTest.ino b/firmware/examples/Troubleshooting/HardwareExamples/StepperMotorTest/StepperMotorTest.ino
similarity index 100%
rename from examples/Troubleshooting/HardwareExamples/StepperMotorTest/StepperMotorTest.ino
rename to firmware/examples/Troubleshooting/HardwareExamples/StepperMotorTest/StepperMotorTest.ino
diff --git a/library.properties b/firmware/library.properties
similarity index 100%
rename from library.properties
rename to firmware/library.properties
diff --git a/src/VFM.cpp b/firmware/src/VFM.cpp
similarity index 100%
rename from src/VFM.cpp
rename to firmware/src/VFM.cpp
diff --git a/src/VFM.h b/firmware/src/VFM.h
similarity index 100%
rename from src/VFM.h
rename to firmware/src/VFM.h
diff --git a/src/hardware/VFMPins.h b/firmware/src/hardware/VFMPins.h
similarity index 100%
rename from src/hardware/VFMPins.h
rename to firmware/src/hardware/VFMPins.h
diff --git a/src/services/CanService.cpp b/firmware/src/services/CanService.cpp
similarity index 100%
rename from src/services/CanService.cpp
rename to firmware/src/services/CanService.cpp
diff --git a/src/services/CanService.h b/firmware/src/services/CanService.h
similarity index 100%
rename from src/services/CanService.h
rename to firmware/src/services/CanService.h
diff --git a/src/services/DispenserService.cpp b/firmware/src/services/DispenserService.cpp
similarity index 100%
rename from src/services/DispenserService.cpp
rename to firmware/src/services/DispenserService.cpp
diff --git a/src/services/DispenserService.h b/firmware/src/services/DispenserService.h
similarity index 100%
rename from src/services/DispenserService.h
rename to firmware/src/services/DispenserService.h
diff --git a/src/services/LedService.h b/firmware/src/services/LedService.h
similarity index 100%
rename from src/services/LedService.h
rename to firmware/src/services/LedService.h
diff --git a/src/services/NodeIdentity.cpp b/firmware/src/services/NodeIdentity.cpp
similarity index 100%
rename from src/services/NodeIdentity.cpp
rename to firmware/src/services/NodeIdentity.cpp
diff --git a/src/services/NodeIdentity.h b/firmware/src/services/NodeIdentity.h
similarity index 100%
rename from src/services/NodeIdentity.h
rename to firmware/src/services/NodeIdentity.h
diff --git a/src/services/PresenceService.cpp b/firmware/src/services/PresenceService.cpp
similarity index 100%
rename from src/services/PresenceService.cpp
rename to firmware/src/services/PresenceService.cpp
diff --git a/src/services/PresenceService.h b/firmware/src/services/PresenceService.h
similarity index 100%
rename from src/services/PresenceService.h
rename to firmware/src/services/PresenceService.h
diff --git a/src/services/ServiceTypes.h b/firmware/src/services/ServiceTypes.h
similarity index 100%
rename from src/services/ServiceTypes.h
rename to firmware/src/services/ServiceTypes.h
diff --git a/tools/dev_gui/README.md b/packages/dev_gui/README.md
similarity index 76%
rename from tools/dev_gui/README.md
rename to packages/dev_gui/README.md
index ec63541..aee036f 100644
--- a/tools/dev_gui/README.md
+++ b/packages/dev_gui/README.md
@@ -3,7 +3,7 @@
 Python desktop application (DearPyGui) for the **Spatial Foraging Module (SFM)** —
 a base station plus multiple **VFM** nodes — over the CAN bus on a Raspberry Pi 5.
 
-![SFM Developer GUI](../../docs/GUI.png)
+![SFM Developer GUI](docs/GUI.png)
 
 ## Requirements
 
@@ -18,7 +18,7 @@ controller device tree overlay and bring up `can0`. This only needs to be
 done once per Pi:
 
 ```bash
-cd tools/dev_gui/deploy
+cd packages/dev_gui/deploy
 sudo ./setup-can.sh            # reboots automatically if needed
 sudo ./setup-can.sh --verify   # confirm can0 is healthy after reboot
 ```
@@ -29,14 +29,14 @@ troubleshooting if `--verify` reports a failure.
 ## Install
 
 ```bash
-cd tools/dev_gui
+cd packages/dev_gui
 pip install -r requirements.txt --break-system-packages
 ```
 
 ## Run
 
 ```bash
-cd tools/dev_gui
+cd packages/dev_gui
 
 # Real hardware (can0) — GUI:
 python run.py
@@ -60,7 +60,7 @@ For `run_report.py` options (list sessions, combine cohorts, date filters, desig
 and more), see [Behavior reports](#behavior-reports-session-csv--printable-html).
 
 Timings and parameter defaults used by the GUI, experiments, and reports:
-[docs/BASE_STATION_HARDCODED_VALUES.md](../../docs/BASE_STATION_HARDCODED_VALUES.md).
+[docs/BASE_STATION_HARDCODED_VALUES.md](docs/BASE_STATION_HARDCODED_VALUES.md).
 
 ## CLI options
 
@@ -102,8 +102,8 @@ its own package (see [Behavior reports](#behavior-reports-session-csv--printable
 
 ```bash
 # Base station
-cd tools/dev_gui
-pip install -r requirements.txt   # includes -e ../../packages/sfm-analysis
+cd packages/dev_gui
+pip install -r requirements.txt   # includes -e ../sfm-analysis
 python -m pytest tests/ -v
 
 # Report / analysis SDK
@@ -112,12 +112,14 @@ pip install -e ".[dev]"
 pytest
 ```
 
-## Experiment engine (headless task/session API)
+## Experiment engine
 
-The GUI is for live monitoring and discovery. Behavioral tasks live in a
-separate **event-driven experiment engine** under
-[`base_station/experiment/`](base_station/experiment/). Nodes stay dumb (commands in,
-events out); your script decides what to do next.
+Behavioral tasks live under
+[`base_station/experiment/`](base_station/experiment/). Nodes stay dumb
+(commands in, events out); the template decides what to do next. **You
+always start a session from the GUI** — pick a template, fill the form,
+enter a session name, click Start. The node tiles and event log stay live
+while it runs.
 
 ### Quick start — free feeding against the simulator
 
@@ -125,39 +127,42 @@ events out); your script decides what to do next.
 # Terminal 1 — fake nodes (Linux / Pi; needs vcan0 — see above)
 python node_simulator.py --interface vcan0 --nodes 3 --skip-discovery
 
-# Terminal 2 — run the built-in free-feeding template for 60 s
-python run_experiment.py free_feeding --interface vcan0 --nodes 1,2,3 \
-    --seconds 60 --reload-delay 2 --no-io --log-dir ~/sfm_logs
+# Terminal 2 — GUI on the same bus
+python run.py --interface vcan0 --nodes 3
 ```
 
-On a non-Pi host use `--no-io` so GPIO/BNC setup is skipped.
+On the Experiment panel: choose **Free Feeding**, set Advance / duration
+if you want, enter a session name, Start.
 
 ### Write your own experiment
 
+A GUI-hosted template is two files with the same name: a `build()` factory
+and a JSON parameter schema. File layout and two copy-from starters
+(event-based round-robin, and an `@exp.script` BNC-paced FR1):
+[examples/templates/](examples/templates/). Authoring guide:
+[`base_station/experiment/README.md`](base_station/experiment/README.md).
+
 ```python
-from base_station.experiment import Experiment, EventKind
+from ..runner import Experiment
 
-exp = Experiment(nodes=[1, 2, 3], name="my_task")
+def build(nodes=None, *, name="my_task", delay_s=2.0, **_):
+    exp = Experiment(nodes=list(nodes or [1, 2, 3]), name=name)
 
-@exp.on_start
-def start(control):
-    for n in control.nodes:
-        control.dispense(n)
+    @exp.on_start
+    def start(control):
+        for n in control.nodes:
+            control.dispense(n)
 
-@exp.on_pellet_taken
-def reload(control, event):
-    control.after(2.0, lambda: control.dispense(event.node_id))
+    @exp.on_pellet_taken
+    def reload(control, event):
+        control.after(delay_s, lambda: control.dispense(event.node_id),
+                      node=event.node_id)
 
-exp.end_after(hours=12)
-# exp.run(interface="vcan0")   # or: save as my_task.py and use the CLI
-```
-
-```bash
-python run_experiment.py my_task.py --interface vcan0 --no-io
+    return exp
 ```
 
-A script may expose either `exp = Experiment(...)` or
-`def build(**kwargs) -> Experiment`.
+Copy that to `base_station/experiment/templates/my_task.py` and add
+`experiments/my_task.json`; it appears in the GUI on the next launch.
 
 ### Built-in templates
 
@@ -171,30 +176,34 @@ A script may expose either `exp = Experiment(...)` or
 ### API surface
 
 - **Events** (`EventKind`): `ON_PLATE`, `LOADED`, `PELLET_TAKEN`,
-  `FAULT`, phase events, `PRESENCE_CHANGED`, `PG_CHANGED`, plus derived
-  `DOME_OPENED` / `DOME_CLOSED`, `NODE_ONLINE` / `NODE_OFFLINE`, and
-  base-station `BNC_IN`, `SESSION_START`, `SESSION_END`.
+  `NO_FEED_PRESENTED`, `FEED_SKIPPED`, `FAULT`, phase events,
+  `PRESENCE_CHANGED`, `PG_CHANGED`, plus derived `DOME_OPENED` /
+  `DOME_CLOSED`, `NODE_ONLINE` / `NODE_OFFLINE`, and base-station
+  `BNC_IN`, `SESSION_START`, `SESSION_END`.
 - **Control actions**: `dispense` (pass `feed=False` for a no-pellet motion-only
   cycle), `recover`, `broadcast_dispense`, `broadcast_recover`, `bnc_pulse`,
   `set_heartbeat_interval`, `after` / `every` timers, named `counter` / `incr`, `log`.
 - **Sequential tasks**: `@exp.script` — see `base_station/experiment/README.md` §5.
 - **Lifecycle**: `start_when(condition)`, `end_after(hours=…, pellets=…)`,
   `end_when(condition)`.
-- **Hosting**: `exp.run(interface=…)` (blocking) or
-  `runner = exp.make_runner(…); runner.step(now)` for GUI integration later.
+- **Hosting**: the GUI drives `ExperimentController` →
+  `runner.step(now)` (`gui_controller.py`). Tests use
+  `exp.make_runner(); runner.inject(...); runner.step(now)` with no CAN.
 
-Experiment-level CSV logs go to `--log-dir` as
-`experiment_<name>_YYYYMMDD_HHMMSS.csv` (separate from the raw-CAN session log).
+Every CAN frame, BNC edge, and `control.log(...)` row lands in the unified
+session CSV (`<log_dir>/<session>.csv`).
 
 ## Behavior reports (session CSV → printable HTML)
 
 `run_report.py` turns one or more session CSVs into a self-contained,
-printable HTML behavior report — no server, no JavaScript, no external
-dependencies beyond the standard library. Charts are inline SVG; print
-with Ctrl+P / Cmd+P.
+printable HTML behavior report — no server, no external dependencies
+beyond the standard library. Charts are inline SVG; print with Ctrl+P /
+Cmd+P. An interactive pan/zoom timeline is embedded by default (one
+inline `<script>`); pass `--no-explorer` for a guaranteed script-free
+document.
 
 The report generator itself lives in a separate, cross-platform package —
-[`packages/sfm-analysis`](../../packages/sfm-analysis/README.md), installable
+[`packages/sfm-analysis`](../sfm-analysis/README.md), installable
 on its own with `pip install sfm-analysis` on any OS. `run_report.py`
 below is a thin wrapper around its `sfm-report` CLI that additionally
 plugs in this base station's own log-directory auto-detection (external
@@ -237,7 +246,7 @@ python run_report.py --help
   --open            Open the result in your default browser when done
 ```
 
-See [packages/sfm-analysis/README.md](../../packages/sfm-analysis/README.md#the-interactive-timeline)
+See [packages/sfm-analysis/README.md](../sfm-analysis/README.md#the-interactive-timeline)
 for the interactive timeline every report embeds by default: real
 pan/zoom/brush-to-zoom over the same timeline data the static raster
 panels show, right in the one self-contained report file — `--no-explorer`
@@ -245,26 +254,27 @@ is the escape hatch back to a guaranteed script-free document.
 
 **How it's structured** (mirrors the experiment engine's own
 JSON-schema/Python split): a report **design** —
-[`report/designs/<name>.json`](../../packages/sfm-analysis/src/sfm_analysis/report/designs/)
+[`report/designs/<name>.json`](../sfm-analysis/src/sfm_analysis/report/designs/)
 — declares which **sections** to render and in what order; sections are
 plain Python functions registered under
-[`report/sections/`](../../packages/sfm-analysis/src/sfm_analysis/report/sections/).
+[`report/sections/`](../sfm-analysis/src/sfm_analysis/report/sections/).
 The design is picked automatically from the session's `experiment` field
 (`session_start`'s `fields_json`), falling back to `default.json` for
 anything without a matching design or with no `session_start` at all.
 Metrics (retrieval latency, presence bouts, dispense cycles, bandit
 choice/WSLS/reversal, …) live in
-[`report/analyses/`](../../packages/sfm-analysis/src/sfm_analysis/report/analyses/)
+[`report/analyses/`](../sfm-analysis/src/sfm_analysis/report/analyses/)
 and
-[`report/metrics.py`](../../packages/sfm-analysis/src/sfm_analysis/report/metrics.py),
+[`report/metrics.py`](../sfm-analysis/src/sfm_analysis/report/metrics.py),
 separately from the HTML that renders them, so the numbers themselves are
 testable without parsing HTML.
 
 Add a new comparative view or per-experiment section by writing a
 function returning a `SectionResult` and adding its `module.function` ref
 to the relevant `report/designs/*.json` — no changes to `run_report.py`
-or the render pipeline needed. See
-[packages/sfm-analysis/README.md](../../packages/sfm-analysis/README.md)
+or the render pipeline needed. Copy-from starter:
+[`packages/sfm-analysis/examples/report_design/`](../sfm-analysis/examples/report_design/).
+See [packages/sfm-analysis/README.md](../sfm-analysis/README.md)
 for the full picture, including the Python API for custom analysis.
 
 ## Base station I/O (BNC, AEO, button)
@@ -291,14 +301,20 @@ to a harmless simulation mode automatically when no GPIO backend
 ## File structure
 
 ```
-tools/dev_gui/
+packages/dev_gui/
 ├── requirements.txt           # dearpygui, python-can, RPi.GPIO, gpiod,
-│                               # and -e ../../packages/sfm-analysis
+│                               # and -e ../sfm-analysis
 ├── run.py                    # GUI entry point
-├── run_experiment.py         # Headless experiment CLI
 ├── run_report.py             # Thin wrapper around sfm_analysis.cli.report
 │                              # (see packages/sfm-analysis/ below)
 ├── node_simulator.py         # Fake VFM nodes for vcan0 testing
+├── experiments/              # JSON parameter schemas (drives the GUI form)
+│   ├── free_feeding.json
+│   ├── fixed_and_random.json
+│   ├── probability_delivery.json
+│   └── two_armed_bandit.json
+├── examples/templates/       # Copy-from custom templates (not auto-loaded)
+├── docs/                     # GUI screenshot + base-station tunables
 ├── deploy/                   # One-time Pi setup: MCP2515 device tree overlay,
 │                              # systemd-networkd unit — see deploy/README.md
 ├── tests/
@@ -313,15 +329,18 @@ tools/dev_gui/
     ├── mac_id_registry.py    # Persistent MAC ↔ Node ID dictionary (~/.sfm/…)
     ├── node_registry.py      # Per-node live state (session)
     ├── log_manager.py        # Ring buffer + CSV auto-save (schema from sfm_analysis.logs)
-    ├── storage.py            # Writer-side log-dir resolution (headless-safe; no dearpygui import)
+    ├── storage.py            # Writer-side log-dir resolution (no dearpygui import)
     ├── app.py                # DearPyGui screens + render loop
-    └── experiment/           # Headless event-driven task engine
+    └── experiment/           # Event-driven task engine (GUI-hosted)
+        ├── README.md         # How to author a custom template
         ├── events.py         # EventKind + CAN → NodeEvent normalizer
-        ├── context.py        # ExperimentControl: actions, timers, counters, experiment CSV
+        ├── context.py        # ExperimentControl: actions, timers, counters
         ├── script.py         # @exp.script sequential-generator scheduler
         ├── runner.py         # Experiment API + tick loop
-        ├── kit.py            # Shared template boilerplate (session/trigger/fault logging)
-        └── templates/
+        ├── schema.py         # JSON → build() (resolve_builder, no registry)
+        ├── kit.py            # Shared template boilerplate
+        ├── gui_controller.py # GUI host for the runner
+        └── templates/        # Built-in build() factories (one module per JSON)
             ├── free_feeding.py
             ├── fixed_and_random.py
             ├── probability_delivery.py
@@ -330,7 +349,7 @@ tools/dev_gui/
 
 The behavior-report generator itself — `report/`, its `designs/*.json`,
 `protocol.py`, and `logs.py` — moved to
-[`packages/sfm-analysis/`](../../packages/sfm-analysis/README.md), a
+[`packages/sfm-analysis/`](../sfm-analysis/README.md), a
 separate, cross-platform, independently pip-installable package; see its
 README for that tree and the Python API.
 
diff --git a/tools/dev_gui/base_station/__init__.py b/packages/dev_gui/base_station/__init__.py
similarity index 100%
rename from tools/dev_gui/base_station/__init__.py
rename to packages/dev_gui/base_station/__init__.py
diff --git a/tools/dev_gui/base_station/app.py b/packages/dev_gui/base_station/app.py
similarity index 100%
rename from tools/dev_gui/base_station/app.py
rename to packages/dev_gui/base_station/app.py
diff --git a/tools/dev_gui/base_station/can_manager.py b/packages/dev_gui/base_station/can_manager.py
similarity index 100%
rename from tools/dev_gui/base_station/can_manager.py
rename to packages/dev_gui/base_station/can_manager.py
diff --git a/tools/dev_gui/base_station/dev_settings.py b/packages/dev_gui/base_station/dev_settings.py
similarity index 100%
rename from tools/dev_gui/base_station/dev_settings.py
rename to packages/dev_gui/base_station/dev_settings.py
diff --git a/tools/dev_gui/base_station/discovery_manager.py b/packages/dev_gui/base_station/discovery_manager.py
similarity index 100%
rename from tools/dev_gui/base_station/discovery_manager.py
rename to packages/dev_gui/base_station/discovery_manager.py
diff --git a/packages/dev_gui/base_station/experiment/README.md b/packages/dev_gui/base_station/experiment/README.md
new file mode 100644
index 0000000..a83b441
--- /dev/null
+++ b/packages/dev_gui/base_station/experiment/README.md
@@ -0,0 +1,725 @@
+# Writing Custom Experiment Templates (Python API)
+
+This is the guide for authoring your own experiments for the SFM dev GUI. An
+**experiment** automates the pellet-dispensing nodes over CAN: it decides *when*
+to dispense, *which* node(s), and *how* to react to what the nodes and the BNC
+sync inputs do.
+
+You write experiments in Python. There is **no base class to inherit** — a
+template is just a module with a `build(...)` factory that returns a configured
+`Experiment` object. A small JSON file describes the tunable parameters so the
+GUI can render a form for it.
+
+Everything an experiment does flows through the same CAN bus the manual controls
+use, so **the node tiles always show live status** while an experiment runs — you
+don't have to do anything special to keep them in sync. The same is true of the
+event log: `control.dispense` / `control.recover` (and their broadcast variants)
+show up as **COMMAND**-type rows identical to a manually-clicked button —
+filtering the log by COMMAND shows every command sent, regardless of whether a
+human or a running experiment triggered it. Everything else you log with
+`control.log(...)` (session lifecycle, per-cycle bookkeeping, etc.) shows up as
+**EXPERIMENT** rows.
+
+### Session naming and the unified log
+
+The GUI's Experiment panel requires a **session name** before Start is
+enabled. That name resolves to one CSV, `<log_dir>/<sanitized_name>.csv`
+(non-alphanumeric characters collapse to `_`) — every CAN frame, heartbeat,
+BNC edge, and experiment row lands there with columns `run_id`, `trial`,
+`source`, and a lossless `fields_json` alongside the human-readable
+`details`. Starting a new run under a **name already used** appends rather
+than overwriting, and `run_id` increments so runs can be told apart in
+analysis — this is how a session picks back up across GUI restarts.
+
+At the moment a session actually **activates** (immediately if the template
+has no `start_when`, later otherwise — see `ExperimentControl.on_session_start`),
+the GUI broadcasts `CanCmd.SyncFlash` (every node holds its status LED solid
+for ~500 ms) and fires a coincident BNC OUT pulse, so field-camera footage can
+be aligned to session start without a manual clapperboard. A node latched in
+`Fault` ignores the command (same guard the firmware uses for a solid fault
+indication) and is called out by id in the logged `SYNC` row.
+
+### Trial numbers
+
+Call `control.next_trial()` once per delivery cycle — the built-in templates
+that dispense on a timer/BNC trigger or per-node reload all do this, so
+`trial` (and its mirror `counter("trials")`) means "one delivery decision"
+consistently across templates, not just in `@exp.script`-based tasks like
+`two_armed_bandit`. The GUI mirrors the running `control.trial` onto every
+log row (CAN and experiment alike) each frame, so trial boundaries are
+visible outside `control.log(...)` rows too.
+
+---
+
+
+
+## 1. Anatomy of a template
+
+
+
+### Where files go
+
+A GUI-hosted template is **two files** with the same `<name>`. Dropping them
+in these locations is enough — `schema.resolve_builder()` imports
+`base_station.experiment.templates.<name>.build` dynamically; there is no
+central registry to edit.
+
+```
+packages/dev_gui/
+├── experiments/
+│   └── <name>.json                         # GUI form (parameters, types, defaults)
+└── base_station/experiment/
+    ├── README.md                           # this guide
+    ├── schema.py                           # loads every experiments/*.json
+    ├── kit.py                              # optional helpers (session, advance, faults)
+    ├── templates/
+    │   ├── __init__.py                     # optional re-export only
+    │   └── <name>.py                       # def build(**kwargs) -> Experiment
+    └── ...                                 # engine (events, context, script, runner)
+```
+
+Copy-from starters that already follow this layout (event-based round-robin,
+and an `@exp.script` BNC-paced FR1):
+`[examples/templates/](../../examples/templates/)`. Copy the `.py` into
+`templates/` and the `.json` into `experiments/`, then relaunch the GUI.
+
+Optional extras, same `<name>`:
+
+```
+packages/dev_gui/tests/test_<name>.py                    # make_runner() + inject()
+packages/sfm-analysis/src/sfm_analysis/report/
+├── designs/<name>.json                                  # which report sections to render
+├── analyses/<name>.py                                   # numbers from the log
+└── sections/<name>.py                                   # HTML for those numbers
+```
+
+The report side is optional — without it, `sfm-report` falls back to
+`default.json`. Starter files:
+`[packages/sfm-analysis/examples/report_design/](../../../sfm-analysis/examples/report_design/)`.
+
+The Python module exposes one function:
+
+```python
+from ..runner import Experiment
+
+def build(nodes=None, *, name="<name>", **params) -> Experiment:
+    node_list = list(nodes) if nodes else [1, 2, 3]
+    exp = Experiment(nodes=node_list, name=name)
+
+    @exp.on_start
+    def _start(control):
+        for n in control.nodes:
+            control.dispense(n)
+
+    exp.end_after(minutes=30)
+    return exp
+```
+
+- `nodes` is injected by the GUI from the **node multi-select** in the Experiment
+panel (or defaults inside the template). Templates iterate `control.nodes` —
+never a hard-coded list — so node selection "just works".
+- Register behavior with the `@exp.on_*` decorators (§4), or write the task as
+one sequential generator with `@exp.script` (§5) — you can mix both.
+- Call `exp.end_after(...)` for automatic stop conditions.
+- Return the `Experiment`.
+
+For duration/pellet-cap plumbing, the shared next-trial wait (`fixed_delay` /
+`presence_clear` / `bnc`), and the usual fault/recover logging, see
+`[kit.py](kit.py)` — small helpers the built-in templates share
+(`kit.session(...)`, `kit.wire_advance(...)`, `kit.next_trial_wait(...)`,
+`kit.after_advance(...)`, `kit.log_faults(...)`, `kit.log_cycle_summary(...)`).
+Using them is optional but saves boilerplate.
+
+### Registering the template
+
+Templates need no central registration. `resolve_builder()` in
+`[schema.py](schema.py)` dynamically imports
+`base_station.experiment.templates.<name>.build` — dropping a new
+`templates/<name>.py` (with a matching `experiments/<name>.json`) is enough. If
+you want it importable as `from .templates import my_template`, add one line to
+`[templates/__init__.py](templates/__init__.py)`:
+
+```python
+from .my_template import build as my_template
+```
+
+
+
+### The JSON parameter file
+
+```json
+{
+  "name": "my_template",
+  "label": "My Template",
+  "template": "my_template",
+  "description": "One-line summary shown in the GUI.",
+  "parameters": [
+    { "key": "interval_s", "label": "Interval (s)", "type": "float",
+      "default": 10.0, "min": 0, "max": 3600, "help": "..." }
+  ]
+}
+```
+
+- `template` must match the module name under `templates/`.
+- Each parameter's `key` becomes a keyword argument to `build(...)`.
+- Convention: `max_pellets` and duration-in-`minutes` of `0` mean "no limit".
+
+Every parameter value passes through `coerce_param_value` before reaching
+`build(...)`, so you receive it already typed. **The GUI form is generated
+entirely from this JSON — you never write per-parameter UI code.**
+
+### Parameter types
+
+
+| `type`          | Widget                                         | Value passed to `build(...)`                        |
+| --------------- | ---------------------------------------------- | --------------------------------------------------- |
+| `int` / `float` | number input (honors `min`/`max`)              | `int` / `float`                                     |
+| `bool`          | checkbox                                       | `bool`                                              |
+| `str`           | text input                                     | `str`                                               |
+| `choice`        | dropdown (needs `"options": [...]`)            | `str` (one of the options)                          |
+| `nodes`         | one checkbox per node + **All/None**           | *(drives the* `nodes=` *argument, below)*           |
+| `node_number`   | one number input per node (honors `min`/`max`) | `dict {node_id: number}` — `0` = node inactive      |
+| `node_choice`   | one dropdown per node (needs `"options"`)      | `dict {node_id: str}` — **first option = inactive** |
+
+
+The three node types render **one control per node** automatically — that is how
+`fixed_and_random` (a role dropdown per node) and `probability_delivery` (a %
+per node) are built, with **no template-specific GUI code**.
+
+**Active nodes / the** `nodes=` **argument.** `build(nodes=...)` always receives the
+active node set, derived in this order: a `nodes`-type param's checked list →
+else a `node_number` param's keys with value > 0 → else a `node_choice` param's
+keys whose value ≠ the first (inactive) option → else all nodes. So per-node
+assignment *is* the active/inactive selection — a separate "active nodes" row is
+only needed for templates that have no per-node param (like `free_feeding`,
+which declares a `nodes` param).
+
+### Conditional display — `visible_when`
+
+Any param may declare `"visible_when": {"<other_key>": <value | [values]>}`; it
+is shown (and collected) only when the controlling param currently equals one of
+the values. Hidden params fall back to their JSON `default`. Example — show the
+delay only for `fixed_delay`, the settle time only for `presence_clear`, the
+channel only for BNC:
+
+```json
+{ "key": "next_trial_wait", "type": "choice",
+  "options": ["fixed_delay", "presence_clear", "bnc"], "default": "fixed_delay" },
+{ "key": "fixed_delay_s", "type": "float", "default": 10.0,
+  "visible_when": {"next_trial_wait": "fixed_delay"} },
+{ "key": "iti_quiet_s", "type": "float", "default": 1.0,
+  "visible_when": {"next_trial_wait": "presence_clear"} },
+{ "key": "bnc_channel", "type": "int", "default": 0, "min": 0, "max": 1,
+  "visible_when": {"next_trial_wait": "bnc"} }
+```
+
+A per-node role dropdown looks like:
+
+```json
+{ "key": "node_roles", "label": "Node role", "type": "node_choice",
+  "options": ["off", "fixed", "random"], "default": "random" }
+```
+
+Your `build(node_roles=...)` then receives `{1: "fixed", 2: "off", 3: "random"}`.
+While running, the whole form (template selector + every param) is **locked**;
+it re-enables on Stop or when the run ends on its own.
+
+BNC channels are **0-based**: `0` = first BNC input (IN1), `1` = second (IN2).
+
+---
+
+
+
+## 2. Two styles: loop-based vs event-based
+
+Both use the **same** callback API — the difference is only what drives the
+actions. A third style, sequential scripts, is covered in §5 — reach for it when
+a task is naturally a series of trials rather than an open-loop reaction to
+events.
+
+### Loop-based (timer-driven)
+
+Cycles are paced by timers on the runner clock. `free_feeding` is the canonical
+example: dispense on start, then re-dispense a node some delay after it takes
+the pellet.
+
+```python
+@exp.on_start
+def _start(control):
+    for n in control.nodes:
+        control.dispense(n)
+
+@exp.on_pellet_taken
+def _reload(control, event):
+    # Node-scoped timer: cancelled automatically if this node faults.
+    control.after(2.0, lambda: control.dispense(event.node_id), node=event.node_id)
+```
+
+
+
+### Event-based (reacts to events)
+
+Actions fire off events — a BNC pulse, a pellet loaded, a dome closing, etc.
+
+```python
+@exp.on_bnc_in
+def _on_pulse(control, event):
+    if event.data.get("edge") == "rising":
+        control.dispense(control.nodes[0])   # dispense on every BNC rising edge
+```
+
+You can freely mix both in one template (e.g. a timer heartbeat plus BNC
+overrides).
+
+---
+
+
+
+## 3. The `control` object (`ExperimentControl`)
+
+`control` is passed as the first argument to every callback and to your
+`@exp.script` generator. It is your entire action surface — see
+`[context.py](context.py)`.
+
+### Actions
+
+
+| Call                                                           | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `control.dispense(node)`                                       | Dispense on one node. **No-op while that node is halted, mid-cycle from a previous dispense, or already has a pellet on the plate** (all three logged — see below).                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `control.dispense(node, feed=False)`                           | Run the identical dispense motion with **no pellet**: lower, hold at the drop position, then raise an empty plate. The raise fires when this node hears another node's `Raising` event on the bus, so both plates reach the top together no matter how long the fed node's load took — there is no dwell to set. Use it so an inactive arm still moves/sounds the same as a fed one (e.g. a bandit task where the animal shouldn't be able to tell arms apart by sound). Same vetoes apply. With no fed node in the trial, the mimic has nothing to follow and holds until `recover()`. |
+| `control.recover(node)`                                        | Send Recover to one node (stop motion + clear its fault).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `control.broadcast_dispense()` / `control.broadcast_recover()` | Same, to all nodes. If any node isn't clear (occupied plate or a cycle in flight), `broadcast_dispense()` can't withhold the command from just that one node in a single CAN frame, so it falls back to individual `dispense(n)` calls (each carrying its own vetoes) and returns `False`.                                                                                                                                                                                                                                                                                              |
+| `control.bnc_pulse(duration_us=100)`                           | Pulse the BNC OUT line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `control.set_heartbeat_interval(node, ms)`                     | Reconfigure a node's heartbeat rate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
+
+**Three standardized, top-priority vetoes (system-wide, every template, zero wiring needed).** `dispense()` is the single choke point every dispense in the codebase goes through — templates, scripts, the GUI — so these three checks apply everywhere automatically, in this order, before anything is transmitted:
+
+1. **Halted** (`is_halted(node)`) — a faulted node; logs `dispense_skipped_halted`.
+2. **Cycle in flight** (`is_dispensing(node)`) — a previous `dispense()`/`dispense(feed=False)` on this node hasn't resolved yet (no `LOADED`/`NO_FEED_PRESENTED`/`FEED_SKIPPED`/fault/offline event since it was sent). This is what stops a fast timer/BNC-triggered template from re-picking the *same* node while it's still mid-motion — the plate-occupied check below can't catch that window, since the pellet hasn't reached the plate yet. Logs `dispense_skipped_in_flight` (`warning=1`).
+3. **Pellet already on the plate** (`pellet_on_plate(node)`) — logs `dispense_skipped_pellet_present` (`warning=1`).
+
+All three return `False` with no command sent. Firmware's own occupancy guard (`DispenserService::dispense()`/`dispenseNoFeed()` — see `FeedSkipped`) remains a backstop for the small race between these client-side checks and the command reaching the bus, but the common case never reaches it. `control.pellet_clear(nodes=None)` / `control.is_dispensing(node)` let you gate your own wait on either signal — see `kit.next_trial_wait`'s `"presence_clear"` mode, which checks pellet state first, unconditionally, before presence.
+
+### Per-node fault handling (sticky)
+
+
+| Call                                  | Effect                                                                                                                                              |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `control.halt_node(node_id)`          | Latch a node: cancel its timers, make its `dispense` a no-op. (The engine calls this automatically on a FAULT event — you rarely call it yourself.) |
+| `control.recover_node(node_id)`       | Clear the halt and send Recover (clears the firmware fault).                                                                                        |
+| `control.is_halted(node_id)` → `bool` | Is this node latched?                                                                                                                               |
+| `control.halted_nodes`                | Sorted list of halted node IDs.                                                                                                                     |
+
+
+
+
+### Timers (runner clock, not wall clock)
+
+
+| Call                                                                                                  | Effect                                                                             |
+| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `control.after(seconds, cb, node=0)`                                                                  | One-shot. Pass `node=` to tie it to a node so it is cancelled if that node faults. |
+| `control.every(seconds, cb, node=0)`                                                                  | Repeating.                                                                         |
+| `control.cancel_timer(timer)` / `control.cancel_node_timers(node_id)` / `control.cancel_all_timers()` | Cancel.                                                                            |
+
+
+
+
+### Per-node sensor state (for `@exp.script` conditions, but usable anywhere)
+
+
+| Call                                                                                             | Effect                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `control.quiet_for(seconds, node=None)` → `bool`                                                 | No PG/dome/presence/pellet-taken/BNC activity on the given node(s) — or all session nodes if omitted — for `seconds`. Ignores heartbeats and the node's own dispense-phase events, so it reflects the *animal*, not our own commands.                                              |
+| `control.domes_closed(nodes=None)` → `bool`                                                      | All the given (or all session) domes currently closed.                                                                                                                                                                                                                             |
+| `control.dome_open(node)` / `control.pellet_on_plate(node)` / `control.is_online(node)` → `bool` | Current per-node sensor snapshot.                                                                                                                                                                                                                                                  |
+| `control.pellet_clear(nodes=None)` → `bool`                                                      | No pellet on the plate on every given (or all session) node. Mirrors `presence_clear()`/`domes_closed()` — this is what `dispense()`'s own veto checks.                                                                                                                            |
+| `control.is_dispensing(node)` → `bool`                                                           | True from the moment `dispense(node)` sends a command until that cycle resolves. This is what `dispense()`'s "cycle already in flight" veto checks — see above.                                                                                                                    |
+| `control.presence(node)` → `bool` / `control.presence_clear(nodes=None)` → `bool`                | Animal on the capacitive presence pad; clear on every given (or all session) node. Defaults `False`/clear until the first reading arrives for a node — gate on `is_online(node)` first if you need to tell "confirmed clear" from "not yet known".                                 |
+| `control.presented_pellet(node)` / `control.presented_empty(node)` → `bool`                      | What the last **completed** dispense cycle on this node raised — a real pellet, or an empty plate from `dispense(node, feed=False)`. At most one is ever `True`.                                                                                                                   |
+| `control.presentation(node)` → `str`                                                             | `'pellet'` | `'empty'` | `'none'` (`'none'` while a cycle is in flight).                                                                                                                                                                                                           |
+| `control.presentation_done(node)` → `bool`                                                       | `True` once the cycle has finished raising, either way. Stays `True` through the take — call `clear_presentation()` to reset it. `wait_until` this across several nodes to gate a response window on **all** of them being ready before acting on any (see `two_armed_bandit.py`). |
+| `control.clear_presentation(node)`                                                               | Reset a node's presentation state — call at the start of a new trial so a stale reading can't be mistaken for this trial's result.                                                                                                                                                 |
+
+
+
+
+### Counters, trials, RNG, time, logging, stop
+
+
+| Call                                                                                      | Effect                                                                                                                                         |
+| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `control.counter(name)` / `control.incr(name, amount=1)` / `control.set_counter(name, v)` | Named integer counters.                                                                                                                        |
+| `control.next_trial()` → `int`                                                            | Advance and return the trial counter (also mirrored in `counter("trials")`, logged as a `trial` row). For sequential trial-based tasks.        |
+| `control.trial`                                                                           | Current trial number (0 before the first `next_trial()`).                                                                                      |
+| `control.chance(p)` / `control.pick(seq)` / `control.shuffled(seq)`                       | Session-seeded RNG helpers. See `control.seed` — generated and logged in `session_start` if you didn't supply one, so any run can be replayed. |
+| `control.elapsed()`                                                                       | Seconds since the session became active.                                                                                                       |
+| `control.log(name, node=0, **fields)`                                                     | Write an experiment log row (to the GUI log + CSV).                                                                                            |
+| `control.stop(reason="...")`                                                              | End the whole session as soon as possible (cancels all timers).                                                                                |
+| `control.nodes`                                                                           | The node IDs this session runs on.                                                                                                             |
+
+
+The engine auto-increments the `"pellets"` counter on every `LOADED`
+event (a fully delivered pellet) — a no-feed cycle's `NO_FEED_PRESENTED` does
+**not** increment it, so `end_after(pellets=...)` only counts real deliveries.
+For a per-node tally, keep your own counter:
+
+```python
+@exp.on_loaded
+def _p(control, event):
+    control.incr(f"pellets_{event.node_id}")
+```
+
+---
+
+
+
+## 4. Events you can handle
+
+Register with `@exp.on(EventKind.X)` or the sugar decorators. Handlers receive
+`(control, event)` where `event` is a `NodeEvent(kind, node_id, timestamp, data)`.
+
+
+| Sugar decorator                               | EventKind                       | `event.data` notes                                                      |
+| --------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
+| `@exp.on_start` / `@exp.on_end`               | `SESSION_START` / `SESSION_END` | `(control)` only — no `event`.                                          |
+| `@exp.on_on_plate`                            | `ON_PLATE`                      | `session_pellets`, `session_taken`                                      |
+| `@exp.on_loaded`                              | `LOADED`                        | `session_pellets`, `session_taken`                                      |
+| `@exp.on_pellet_taken`                        | `PELLET_TAKEN`                  | `session_taken`, `session_pellets`, `dome_open`                         |
+| `@exp.on_feed_skipped`                        | `FEED_SKIPPED`                  | plate already occupied when dispensed                                   |
+| `@exp.on_no_feed_presented`                   | `NO_FEED_PRESENTED`             | a no-feed dispense finished raising an empty plate                      |
+| `@exp.on_dome_opened` / `@exp.on_dome_closed` | `DOME_OPENED` / `DOME_CLOSED`   | derived from the dome sensor                                            |
+| `@exp.on_fault`                               | `FAULT`                         | `fault_code` (`FeedTimeout` / `ActuatorTimeout` / `Jam` / `PelletLost`) |
+| `@exp.on_recover`                             | `NODE_RECOVERED`                | fired when an operator recovers a node                                  |
+| `@exp.on_bnc_in`                              | `BNC_IN`                        | `channel` (0/1), `edge` ("rising"/"falling"), `high`                    |
+| `@exp.on_presence_changed`                    | `PRESENCE_CHANGED`              |                                                                         |
+
+
+Other kinds available via `@exp.on(...)`: `LOWERING`, `LOADING`, `DWELLING`,
+`RAISING`, `DOME_OPEN_WARNING`, `PG_CHANGED`, `HEARTBEAT`, `NODE_ONLINE`,
+`NODE_OFFLINE`. See `[events.py](events.py)` for the full list.
+
+### Pellet counts are session-scoped
+
+`session_pellets` and `session_taken` are the base station's own per-node
+counters. They start at zero when a run opens, so the first pellet of a run is
+always number 1 no matter how long the node has been powered.
+
+They are not simply "events I received". Node firmware counts pellets from
+power-on (`pelletCount_` / `takenCount_`) and puts that number on every
+milestone frame and heartbeat. The base station folds in the **delta** of that
+counter, so a `Loaded` frame lost to the bus is recovered by the next frame
+that carries the count — the following `DomeOpened`, `PelletTaken`, or just the
+next heartbeat — and the run total stays right. Gaps are written to the log as
+`Pellet Count Gap` rows so a correction is visible during analysis instead of
+silently smoothing over lost data. See
+`[pellet_ledger.py](../pellet_ledger.py)`.
+
+The node's raw counter is still in the log, as `node_pellets` / `node_taken` in
+`fields_json`. Treat it as a diagnostic, never as the pellet number.
+
+### Start / end conditions
+
+```python
+exp.start_when(lambda control: control.counter("armed") > 0)   # defer SESSION_START
+exp.end_when(lambda control: control.elapsed() > 600)          # custom end
+exp.end_after(hours=0, minutes=30, seconds=0, pellets=100)     # duration and/or cap
+```
+
+---
+
+
+
+## 5. Sequential tasks — `@exp.script`
+
+Some tasks are naturally a series of trials: do something, wait for a specific
+outcome, wait again, repeat — a two-armed bandit is the canonical example. That
+reads far more clearly as one generator than as a handful of `@exp.on_*`
+handlers threading state through a dict. `@exp.script` runs *alongside* the
+callback API (both may be used on the same `Experiment`) — there is exactly one
+script per experiment.
+
+```python
+@exp.script
+def run(control):
+    while True:
+        trial = control.next_trial()
+        control.dispense(fed_node)
+        control.dispense(other_node, feed=False)   # motion, no pellet
+
+        result = yield control.wait_for("pellet_taken", node=fed_node, timeout=30.0)
+        if result.faulted:
+            yield control.wait(5.0)
+            continue
+
+        yield control.wait_until(
+            lambda c: c.domes_closed() and c.quiet_for(5.0),
+            timeout=30.0,
+            label="iti_quiet",
+        )
+```
+
+
+
+### The three things you can `yield`
+
+- `control.wait_for(kind, node=None, timeout=None)` — wait for the next
+matching event. `kind` is an event name (`"pellet_taken"`, case-insensitive)
+or an `EventKind`. `node` restricts to one id or a list; omit for any node.
+- `control.wait_until(predicate, timeout=None, node=None, label=None)` — wait until
+`predicate(control)` returns True (checked every tick). Pass `node=` only if
+this wait should also abort when that node faults. Pass `label=` so
+`script_stalled` / `script_timeout` name the wait (`"plates_clear"`) instead
+of logging an unlabeled lambda as `condition`.
+- `control.wait(seconds)` — wait a fixed duration on the runner clock.
+
+Each `yield` returns the same object, with fields filled in once it resolves:
+`.ok` (`bool` — succeeded cleanly), `.timed_out`, `.faulted` / `.faulted_node`,
+and `.event` (the `NodeEvent` that satisfied a `wait_for`, if any). Ignoring the
+return value is the common case and costs nothing.
+
+### What "wait" actually means
+
+- Two lines like `control.dispense(fed)` then `yield control.wait_for(...)` can
+never race — the engine is single-threaded, so no reply can arrive before the
+next tick regardless of how the two lines are written.
+- `@exp.on_*` handlers for an event always run **before** any script code that
+same event unblocks (they fire earlier in the same dispatch batch).
+- **Faults never raise inside your script.** If the node a pending `wait_for`
+is scoped to faults, the wait resolves with `.faulted=True` instead of
+hanging or throwing — the script decides what to do (usually: log it, wait a
+bit, and move to the next trial). This matches the callback engine's own
+behavior: a fault halts only that node; the rest of the session keeps going.
+- A generator that **returns** ends the session (`stop(reason="script_finished")`
+— when your `run()` function is done, the experiment is done). A generator
+that **raises** also ends the session, with the error and your code's own
+file/line logged as `script_error` — unlike `@exp.on_*` handlers, whose
+errors are isolated so one broken handler can't take down the rest.
+- **Every loop must yield.** `while True:` with no `yield` inside is an
+uninterruptible Python loop and will hang the whole engine — there is no
+runtime protection against this, only against loops that yield awaits which
+keep resolving immediately (bounded to 64 resumes per tick).
+
+See `[script.py](script.py)` for the full scheduler and
+`[templates/two_armed_bandit.py](templates/two_armed_bandit.py)` for a complete
+worked example.
+
+---
+
+
+
+## 6. Faults are sticky, per node
+
+When a node reports a **jam or timeout**:
+
+1. The firmware halts that node's motors and refuses further dispenses until a
+  Recover — it is already sticky at the hardware level.
+2. The engine calls `control.halt_node(node_id)`: cancels that node's timers and
+  makes its `control.dispense(...)` a no-op. **The other nodes keep running.**
+3. The node stays latched until an operator presses **Recover** on its tile (or a
+  BNC IN action / `runner.recover_node`). Recovery sends Recover (clears the fault)
+   and fires your `@exp.on_recover` handler so you can re-arm the node.
+
+This means your template usually needs **no fault bookkeeping** — keep calling
+`control.dispense(n)` for every node and halted ones simply stop receiving
+pellets. Use `@exp.on_recover` to resume a node's cycle (or `kit.log_faults(exp)`
+for the common log-only case):
+
+```python
+@exp.on_fault
+def _fault(control, event):
+    control.log("fault", node=event.node_id, fault_code=event.data.get("fault_code"))
+
+@exp.on_recover
+def _recovered(control, event):
+    control.dispense(event.node_id)   # resume this node
+```
+
+---
+
+
+
+## 7. BNC sync I/O
+
+BNC is a base-station feature (Raspberry Pi GPIO); nodes are not involved.
+
+**BNC IN** — the GUI dispatches an action per **edge** (rising / falling), each
+independently optional. Configure it in the BNC panel (e.g. rising →
+`start_experiment`, falling → `stop_experiment`). Inside a running experiment you
+also get every edge as a `BNC_IN` event, so a template can react directly:
+
+```python
+@exp.on_bnc_in
+def _edge(control, event):
+    if event.data["edge"] == "rising" and event.data["channel"] == 0:
+        control.dispense(control.nodes[0])
+```
+
+**BNC OUT** — set the BNC OUT **Trigger** in the GUI to a CAN event name (e.g.
+`Loaded`) and it pulses whenever that event arrives from any node, during
+manual use *and* during an experiment. To pulse from template code directly, call
+`control.bnc_pulse(width_us)` (e.g. on each dispense).
+
+---
+
+
+
+## 8. Node selection
+
+The Experiment panel has per-node checkboxes plus **All / None**. The checked set
+is passed to `build(nodes=...)`, so `control.nodes` is exactly the subset the
+operator chose. Always iterate `control.nodes`; never assume `[1, 2, 3]`.
+
+---
+
+
+
+## 9. Worked examples in this repo
+
+
+
+### Starter templates (copy these)
+
+Two complete, commented templates live in
+[`examples/templates/`](../../examples/templates/) — they are **not**
+auto-loaded. Copy each pair into `experiments/<name>.json` and
+`templates/<name>.py` to register them; they appear in the GUI on the
+next launch.
+
+
+| Starter       | Style                                                  | What it shows                                                                                                              |
+| ------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `alternation` | Event-based (`@exp.on_start` / `@exp.on_pellet_taken`) | Round-robin reload, `control.after`, `control.next_trial()`, custom EXP rows (`alternation_start` / `alternation_advance`) |
+| `bnc_paced`   | Sequential (`@exp.script`)                             | `yield control.wait_for("bnc_in")` then `"pellet_taken"`, `.faulted` handling, a fixed ITI                                 |
+
+
+Event-based skeleton (the `alternation` idea, shortened):
+
+```python
+from base_station.experiment.kit import log_faults, session
+
+def build(nodes=None, *, delay_s=2.0, minutes=0, max_pellets=None, **_):
+    exp = session("alternation", nodes, minutes=minutes, max_pellets=max_pellets)
+    log_faults(exp)
+
+    @exp.on_start
+    def _start(control):
+        control.next_trial()
+        control.dispense(control.nodes[0])
+
+    @exp.on_pellet_taken
+    def _advance(control, event):
+        roster = list(control.nodes)
+        nxt = roster[(roster.index(event.node_id) + 1) % len(roster)]
+        def _go():
+            control.next_trial()
+            control.dispense(nxt)
+        control.after(delay_s, _go, node=nxt)
+
+    return exp
+```
+
+`@exp.script` skeleton (the `bnc_paced` idea, shortened):
+
+```python
+@exp.script
+def run(control):
+    node = control.nodes[0]
+    while True:
+        edge = yield control.wait_for("bnc_in")
+        if not edge.ok or (edge.event.data or {}).get("edge") != "rising":
+            continue
+        control.next_trial()
+        control.dispense(node)
+        taken = yield control.wait_for("pellet_taken", node=node)
+        if taken.faulted:
+            yield control.wait(1.0)
+            continue
+        yield control.wait(1.0)
+```
+
+
+
+### Built-in templates
+
+- `[templates/free_feeding.py](templates/free_feeding.py)` — loop-based:
+continuous reload after each pellet is taken, using the shared advance
+(`next_trial_wait`: `fixed_delay` default 30 s, or `presence_clear`);
+per-node sticky fault + recover. (`reload_delay_s=` is a legacy alias
+of `fixed_delay_s`.)
+- `[templates/fixed_and_random.py](templates/fixed_and_random.py)` — each
+node has a **role** (`off` / `fixed` / `random`) from a `node_choice` param.
+`fixed` nodes dispense every cycle, `random` nodes dispense with `random_prob`,
+`off` nodes are inactive. `build(node_roles={1:"fixed", 2:"off", ...})`.
+Advance with the same `next_trial_wait` as two-armed bandit (`fixed_delay` /
+`presence_clear`), plus `bnc` for an external rising edge. (A legacy
+`fixed_nodes` string and `trigger="timer"` / `interval_s=` are still
+accepted as `build()` kwargs.)
+- `[templates/probability_delivery.py](templates/probability_delivery.py)` —
+each cycle delivers on **one** node, chosen by an independent **weighted
+random draw** (`random.choices`) — e.g. weights `20,80` mean node 1 has a 20%
+chance and node 2 an 80% chance *on every single cycle*; it is not a fixed
+20-of-100 allocation or round-robin, and over many cycles the observed split
+converges to the configured weights. `0` means that node is never picked.
+A `node_number` param supplies the per-node weights as `{node_id: pct}`
+(a comma-separated string is also accepted). Same shared
+`next_trial_wait` as `fixed_and_random`.
+- `[templates/two_armed_bandit.py](templates/two_armed_bandit.py)` —
+`@exp.script`-based: exactly two nodes (the arms). Each trial, both arms run
+the dispense motion (`control.dispense(fed)` / `control.dispense(empty, feed=False)`), but only one delivers, chosen by a reward probability that
+flips which arm is "rich" every `block_size` trials. Sweeps both plates
+clear before trial 1, gates the response window on **both** arms finishing
+their raise (`presentation_done`) so neither one tips off the animal by
+finishing first, then waits — with no timeout — for the pellet to be taken.
+Advances to the next trial either after a fixed delay or once the animal is
+off both presence pads (`next_trial_wait`). If a no-feed arm's plate turns
+out already occupied (firmware presents the leftover pellet honestly rather
+than discarding it), the trial is logged invalid and the session keeps
+running — see the module docstring for the full mutual-exclusion and sync
+analysis. A good reference for writing your own trial-based `@exp.script`
+template: see `control.presented_pellet`/`presented_empty`/`presentation_done`/
+`clear_presentation`/`presence`/`presence_clear` in `[context.py](context.py)`
+and `kit.next_trial_wait` in `[kit.py](kit.py)`.
+
+Both `fixed_and_random` and `probability_delivery` accept `seed=` for
+reproducible runs (used by the tests); `two_armed_bandit` does too, and also
+logs whatever seed it used (generated if you didn't supply one) so any session
+can be replayed. Because all three use the declarative node param types above,
+none needs any per-template GUI code — the form (per-node dropdowns / % inputs,
+plus the advance-gated delay / settle / BNC fields) is generated entirely from their
+JSON.
+
+---
+
+
+
+## 10. Testing your template
+
+Drive it with synthetic events — no CAN hardware and no GUI needed:
+
+```python
+from base_station.experiment import EventKind, NodeEvent
+from base_station.experiment.templates.my_template import build
+
+exp = build(nodes=[1, 2], interval_s=5.0, seconds=60)
+runner = exp.make_runner()          # no CAN/IO bound → dry-run
+runner.start(now=0.0)
+runner.step(now=5.0)                 # advance the clock; timers fire
+
+# Inject events:
+runner.inject(NodeEvent(EventKind.FAULT, node_id=1, timestamp=6.0,
+                        data={"fault_code": 1}))
+
+# Inspect what was sent:
+print(runner.ctx.commands_sent)      # list of (node_id, CanCmd, payload)
+```
+
+`runner.ctx.commands_sent` records every command in dry-run mode, and
+`runner.ctx.is_halted(...)`, `runner.ctx.counter(...)`, and the log entries let you
+assert behavior. `runner.ctx` and `runner.control` are the same object — use
+whichever reads better. See
+`[../../tests/test_experiment.py](../../tests/test_experiment.py)` and
+`[../../tests/test_script.py](../../tests/test_script.py)` for patterns,
+including how to drive a `@exp.script` template through `inject()`/`step()`.
diff --git a/tools/dev_gui/base_station/experiment/__init__.py b/packages/dev_gui/base_station/experiment/__init__.py
similarity index 65%
rename from tools/dev_gui/base_station/experiment/__init__.py
rename to packages/dev_gui/base_station/experiment/__init__.py
index 3df08f9..ec1e3de 100644
--- a/tools/dev_gui/base_station/experiment/__init__.py
+++ b/packages/dev_gui/base_station/experiment/__init__.py
@@ -1,10 +1,8 @@
 """
-experiment — headless, event-driven experiment engine for SFM.
+experiment — event-driven experiment engine for SFM.
 
-Users write short scripts (or pick a template) whose callbacks decide what
-to do next in response to node events. The engine consumes the CAN event
-stream via CanManager and issues commands; the GUI and JSON templates are
-thin layers over this same API.
+Users write a template whose callbacks decide what to do next in response
+to node events. The GUI hosts the runner; JSON schemas drive the Start form.
 """
 
 from .events import EventKind, NodeEvent
diff --git a/tools/dev_gui/base_station/experiment/context.py b/packages/dev_gui/base_station/experiment/context.py
similarity index 94%
rename from tools/dev_gui/base_station/experiment/context.py
rename to packages/dev_gui/base_station/experiment/context.py
index ad6ed72..ba0d998 100644
--- a/tools/dev_gui/base_station/experiment/context.py
+++ b/packages/dev_gui/base_station/experiment/context.py
@@ -9,16 +9,12 @@
 
 from __future__ import annotations
 
-import csv
 import random
 import time
 from dataclasses import dataclass, field
 from datetime import datetime
-from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Dict, Iterable, List, Optional, Sequence, TypeVar, Union
 
-from sfm_analysis.logs import EXP6_HEADER as _EXP6_HEADER
-
 from ..protocol import CanCmd, build_setconfig_heartbeat
 from .events import EventKind, NodeEvent
 from .script import _as_node_tuple, _Await, _AwaitKind, _node_suffix, _resolve_event_kind, _until_label
@@ -110,18 +106,11 @@ class ExperimentControl:
     timers and counters live on this object.
     """
 
-    # Schema now lives in sfm_analysis.logs.EXP6_HEADER so this writer and
-    # sfm_analysis.report.loader's schema-sniffing (which reads this exact
-    # header) cannot drift apart across the two distributions.
-    CSV_HEADER = _EXP6_HEADER
-
     def __init__(
         self,
         nodes: List[int],
         can: Optional["CanManager"] = None,
         io: Optional["IOManager"] = None,
-        log_dir: Optional[str] = None,
-        session_name: str = "experiment",
         seed: Optional[int] = None,
     ) -> None:
         self.nodes: List[int] = list(nodes)
@@ -135,11 +124,6 @@ def __init__(
         # Nodes latched into a fault; dispense() is a no-op for them until
         # an operator recovers the node (see halt_node / recover_node).
         self._halted: set = set()
-        self._csv_file = None
-        self._csv_writer = None
-        self._log_path: Optional[Path] = None
-        self._session_name = session_name
-        self._log_dir = log_dir
         # Optional sink so a GUI host can mirror experiment log rows.
         self.on_log: Optional[Callable[[ExperimentLogEntry], None]] = None
         # Fired once, right after the "session_start" log row, when the
@@ -187,18 +171,17 @@ def set_now(self, now: float) -> None:
         self._now = now
 
     def begin(self, now: Optional[float] = None) -> None:
-        """Mark session start and open the experiment CSV if configured."""
+        """Mark session start."""
         self._now = now if now is not None else time.time()
         self._start_time = self._now
         # Seed each node's activity timestamp at session start so quiet_for(N)
         # is False for the first N seconds rather than trivially true at t=0.
         for n in self.nodes:
             self._view(n).last_activity_ts = self._now
-        self._open_csv()
 
     def end(self) -> None:
-        """Close the experiment CSV."""
-        self._close_csv()
+        """Session teardown hook."""
+        pass
 
     def stop(self, reason: str = "stopped") -> None:
         """
@@ -790,7 +773,7 @@ def shuffled(self, seq: Iterable[T]) -> List[T]:
     # ------------------------------------------------------------------
 
     def log(self, name: str, node: int = 0, **fields: Any) -> None:
-        """Append an experiment-level log entry (and write to CSV if open)."""
+        """Append an experiment-level log entry (mirrored to the GUI via on_log)."""
         ts = self._now
         entry = ExperimentLogEntry(
             timestamp=ts,
@@ -799,20 +782,6 @@ def log(self, name: str, node: int = 0, **fields: Any) -> None:
             fields=dict(fields),
         )
         self._log_entries.append(entry)
-        if self._csv_writer is not None:
-            field_str = " ".join(f"{k}={v}" for k, v in fields.items())
-            self._csv_writer.writerow(
-                [
-                    entry.timestamp_iso,
-                    int(ts * 1000),
-                    f"{self.elapsed():.3f}",
-                    name,
-                    node,
-                    field_str,
-                ]
-            )
-            if self._csv_file is not None:
-                self._csv_file.flush()
         if self.on_log is not None:
             try:
                 self.on_log(entry)
@@ -823,10 +792,6 @@ def log(self, name: str, node: int = 0, **fields: Any) -> None:
     def log_entries(self) -> List[ExperimentLogEntry]:
         return list(self._log_entries)
 
-    @property
-    def log_path(self) -> Optional[Path]:
-        return self._log_path
-
     # ------------------------------------------------------------------
     # Internal
     # ------------------------------------------------------------------
@@ -843,24 +808,6 @@ def _send(self, node_id: int, cmd: CanCmd, payload: bytes = b"") -> bool:
             return True  # dry-run / test mode
         return self._can.send_command(node_id, cmd, payload)
 
-    def _open_csv(self) -> None:
-        if not self._log_dir:
-            return
-        log_dir = Path(self._log_dir).expanduser()
-        log_dir.mkdir(parents=True, exist_ok=True)
-        stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        safe_name = "".join(c if c.isalnum() or c in "-_" else "_" for c in self._session_name)
-        self._log_path = log_dir / f"experiment_{safe_name}_{stamp}.csv"
-        self._csv_file = open(self._log_path, "w", newline="", encoding="utf-8")
-        self._csv_writer = csv.writer(self._csv_file)
-        self._csv_writer.writerow(self.CSV_HEADER)
-
-    def _close_csv(self) -> None:
-        if self._csv_file is not None:
-            self._csv_file.close()
-            self._csv_file = None
-            self._csv_writer = None
-
 
 # Old name, kept as an alias — existing code and tests import ExperimentContext.
 ExperimentContext = ExperimentControl
diff --git a/tools/dev_gui/base_station/experiment/events.py b/packages/dev_gui/base_station/experiment/events.py
similarity index 99%
rename from tools/dev_gui/base_station/experiment/events.py
rename to packages/dev_gui/base_station/experiment/events.py
index d5917f0..eed68f7 100644
--- a/tools/dev_gui/base_station/experiment/events.py
+++ b/packages/dev_gui/base_station/experiment/events.py
@@ -117,8 +117,8 @@ class EventNormalizer:
     def __init__(self, online_timeout_s: float = DEFAULT_OFFLINE_TIMEOUT_S) -> None:
         self._tracks: Dict[int, _NodeTrack] = {}
         self._online_timeout_s = online_timeout_s
-        # Own one by default so a headless runner still reports session-scoped
-        # numbers; the GUI replaces it with the ledger backing the log rows.
+        # Own one by default so tests still report session-scoped numbers;
+        # the GUI replaces it with the ledger backing the log rows.
         self._pellets = PelletLedger()
 
     def set_online_timeout(self, seconds: float) -> None:
diff --git a/tools/dev_gui/base_station/experiment/gui_controller.py b/packages/dev_gui/base_station/experiment/gui_controller.py
similarity index 95%
rename from tools/dev_gui/base_station/experiment/gui_controller.py
rename to packages/dev_gui/base_station/experiment/gui_controller.py
index 5963cd6..c376131 100644
--- a/tools/dev_gui/base_station/experiment/gui_controller.py
+++ b/packages/dev_gui/base_station/experiment/gui_controller.py
@@ -59,7 +59,6 @@ def start(
         can: Optional["CanManager"] = None,
         io: Optional["IOManager"] = None,
         log: Optional[LogManager] = None,
-        log_dir: Optional[str] = None,
         on_session_start: Optional[Callable[[], None]] = None,
         online_timeout_s: Optional[float] = None,
     ) -> bool:
@@ -81,11 +80,6 @@ def start(
         runner = exp.make_runner(
             can=can,
             io=io,
-            # The GUI path logs everything through the unified LogManager
-            # (see _on_experiment_log below); passing log_dir=None here
-            # keeps ExperimentControl's own CSV writer a no-op so nothing is
-            # written twice.
-            log_dir=None,
             wire_bnc=False,
             online_timeout_s=online_timeout_s,
         )
@@ -98,7 +92,7 @@ def start(
         return True
 
     def stop(self) -> None:
-        """End the session (fires on_end, closes experiment CSV)."""
+        """End the session (fires on_end)."""
         if self._runner is None:
             return
         self._runner.close()
diff --git a/tools/dev_gui/base_station/experiment/kit.py b/packages/dev_gui/base_station/experiment/kit.py
similarity index 100%
rename from tools/dev_gui/base_station/experiment/kit.py
rename to packages/dev_gui/base_station/experiment/kit.py
diff --git a/tools/dev_gui/base_station/experiment/runner.py b/packages/dev_gui/base_station/experiment/runner.py
similarity index 91%
rename from tools/dev_gui/base_station/experiment/runner.py
rename to packages/dev_gui/base_station/experiment/runner.py
index 1479629..57648b1 100644
--- a/tools/dev_gui/base_station/experiment/runner.py
+++ b/packages/dev_gui/base_station/experiment/runner.py
@@ -1,9 +1,9 @@
 """
 runner.py — Experiment registration API and ExperimentRunner tick loop.
 
-Users build an Experiment (decorators + start/end conditions), then either:
-  - exp.run(interface=...) for a headless blocking session, or
-  - runner.step(now) each frame when hosted by the GUI.
+Users build an Experiment (decorators + start/end conditions). The GUI
+hosts it via ``make_runner()`` / ``runner.step(now)`` each frame.
+Tests use the same runner with no CAN bound and ``inject()`` / ``step()``.
 """
 
 from __future__ import annotations
@@ -56,7 +56,8 @@ def taken(control, event):
             control.log("pellet_taken", node=event.node_id)
 
         exp.end_after(hours=12)
-        exp.run(interface="vcan0")
+        # Hosted by the GUI Experiment panel, or in tests:
+        # runner = exp.make_runner(); runner.start(now=0.0); runner.step(now=1.0)
     """
 
     def __init__(
@@ -193,35 +194,10 @@ def end_after(
     # Run helpers
     # ------------------------------------------------------------------
 
-    def run(
-        self,
-        interface: str = "can0",
-        bitrate: int = 250_000,
-        log_dir: Optional[str] = None,
-        use_io: bool = True,
-        poll_hz: float = 50.0,
-    ) -> ExperimentControl:
-        """
-        Blocking headless run against a SocketCAN interface.
-
-        Returns the ExperimentControl after the session ends.
-        """
-        can = CanManager(interface=interface, bitrate=bitrate)
-        io: Optional[IOManager] = None
-        if use_io:
-            try:
-                io = IOManager()
-            except Exception:  # noqa: BLE001
-                io = None
-
-        runner = ExperimentRunner(self, can=can, io=io, log_dir=log_dir)
-        return runner.run_blocking(poll_hz=poll_hz)
-
     def make_runner(
         self,
         can: Optional[CanManager] = None,
         io: Optional[IOManager] = None,
-        log_dir: Optional[str] = None,
         wire_bnc: bool = True,
         online_timeout_s: Optional[float] = None,
     ) -> "ExperimentRunner":
@@ -230,7 +206,6 @@ def make_runner(
             self,
             can=can,
             io=io,
-            log_dir=log_dir,
             wire_bnc=wire_bnc,
             online_timeout_s=online_timeout_s,
         )
@@ -240,8 +215,8 @@ class ExperimentRunner:
     """
     Owns the tick loop: poll CAN → normalize → dispatch → timers → start/end.
 
-    Use ``run_blocking()`` for headless scripts, or call ``step(now)`` each
-    frame when hosted by the DearPyGui app.
+    Call ``step(now)`` each frame when hosted by the DearPyGui app.
+    Tests call ``inject()`` / ``step()`` with no CAN bound.
     """
 
     def __init__(
@@ -249,7 +224,6 @@ def __init__(
         experiment: Experiment,
         can: Optional[CanManager] = None,
         io: Optional[IOManager] = None,
-        log_dir: Optional[str] = None,
         wire_bnc: bool = True,
         online_timeout_s: Optional[float] = None,
     ) -> None:
@@ -260,8 +234,6 @@ def __init__(
             nodes=experiment.nodes,
             can=can,
             io=io,
-            log_dir=log_dir,
-            session_name=experiment.name,
             seed=experiment.seed,
         )
         # Default matches GUI 60s heartbeat × 3 offline multiplier.
@@ -429,22 +401,6 @@ def step(
 
         self._check_end(now)
 
-    def run_blocking(self, poll_hz: float = 50.0) -> ExperimentControl:
-        """Open CAN, run until the session ends, then clean up."""
-        self.open()
-        self.start()
-        interval = 1.0 / max(1.0, float(poll_hz))
-        try:
-            while not self._finished:
-                self.step()
-                time.sleep(interval)
-        except KeyboardInterrupt:
-            if self._active and not self._finished:
-                self._deactivate(time.time())
-        finally:
-            self.close()
-        return self.ctx
-
     # ------------------------------------------------------------------
     # Internal
     # ------------------------------------------------------------------
diff --git a/tools/dev_gui/base_station/experiment/schema.py b/packages/dev_gui/base_station/experiment/schema.py
similarity index 99%
rename from tools/dev_gui/base_station/experiment/schema.py
rename to packages/dev_gui/base_station/experiment/schema.py
index 796e9b5..5eec76a 100644
--- a/tools/dev_gui/base_station/experiment/schema.py
+++ b/packages/dev_gui/base_station/experiment/schema.py
@@ -145,7 +145,7 @@ def coerce_param_value(param: ExperimentParam, value: Any) -> Any:
     if param.is_node_param:
         # Node-scoped params pass through as-is: a dict {node_id: value} (or a
         # list of node ids for "nodes") from the GUI, or a string/list default
-        # for headless runs that the template parses itself.
+        # that the template parses itself.
         return value
     return "" if value is None else str(value)
 
diff --git a/tools/dev_gui/base_station/experiment/script.py b/packages/dev_gui/base_station/experiment/script.py
similarity index 100%
rename from tools/dev_gui/base_station/experiment/script.py
rename to packages/dev_gui/base_station/experiment/script.py
diff --git a/tools/dev_gui/base_station/experiment/templates/__init__.py b/packages/dev_gui/base_station/experiment/templates/__init__.py
similarity index 100%
rename from tools/dev_gui/base_station/experiment/templates/__init__.py
rename to packages/dev_gui/base_station/experiment/templates/__init__.py
diff --git a/tools/dev_gui/base_station/experiment/templates/fixed_and_random.py b/packages/dev_gui/base_station/experiment/templates/fixed_and_random.py
similarity index 97%
rename from tools/dev_gui/base_station/experiment/templates/fixed_and_random.py
rename to packages/dev_gui/base_station/experiment/templates/fixed_and_random.py
index ffc1acc..9c4922a 100644
--- a/tools/dev_gui/base_station/experiment/templates/fixed_and_random.py
+++ b/packages/dev_gui/base_station/experiment/templates/fixed_and_random.py
@@ -9,7 +9,7 @@
   * ``off`` nodes stay idle (no command).
 
 Roles come from ``node_roles``: a dict ``{node_id: "off"|"fixed"|"random"}``
-(from the GUI's per-node dropdown). For headless use you may instead pass
+(from the GUI's per-node dropdown). You may instead pass
 ``fixed_nodes`` (a comma-separated string or a sequence of ids) — those become
 fixed and every other node in ``nodes`` becomes random.
 
@@ -27,7 +27,6 @@
                 node_roles={1: "fixed", 2: "random", 3: "off"},
                 next_trial_wait="fixed_delay", fixed_delay_s=10.0,
                 random_prob=0.5)
-    exp.run(interface="vcan0")
 """
 
 from __future__ import annotations
@@ -112,7 +111,7 @@ def build(
     node_roles:
         Dict ``{node_id: "off"|"fixed"|"random"}`` (GUI). Overrides ``fixed_nodes``.
     fixed_nodes:
-        Legacy/headless fallback — nodes that dispense every cycle (string
+        Legacy fallback — nodes that dispense every cycle (string
         "1,3" or an iterable). Every other node becomes random.
     trigger / next_trial_wait:
         "fixed_delay" (wait ``fixed_delay_s``), "presence_clear" (wait until
diff --git a/tools/dev_gui/base_station/experiment/templates/free_feeding.py b/packages/dev_gui/base_station/experiment/templates/free_feeding.py
similarity index 99%
rename from tools/dev_gui/base_station/experiment/templates/free_feeding.py
rename to packages/dev_gui/base_station/experiment/templates/free_feeding.py
index 34bab2e..bff2dca 100644
--- a/tools/dev_gui/base_station/experiment/templates/free_feeding.py
+++ b/packages/dev_gui/base_station/experiment/templates/free_feeding.py
@@ -23,7 +23,6 @@
 
     exp = build(nodes=[1, 2, 3], next_trial_wait="fixed_delay",
                 fixed_delay_s=2.0, hours=12)
-    exp.run(interface="vcan0")
 """
 
 from __future__ import annotations
diff --git a/tools/dev_gui/base_station/experiment/templates/probability_delivery.py b/packages/dev_gui/base_station/experiment/templates/probability_delivery.py
similarity index 98%
rename from tools/dev_gui/base_station/experiment/templates/probability_delivery.py
rename to packages/dev_gui/base_station/experiment/templates/probability_delivery.py
index 45da49e..c537161 100644
--- a/tools/dev_gui/base_station/experiment/templates/probability_delivery.py
+++ b/packages/dev_gui/base_station/experiment/templates/probability_delivery.py
@@ -6,7 +6,7 @@
 of the time, node 2 ~30%, node 3 ~50% — an independent weighted-random draw
 every cycle (not a fixed split). Weights are normalized, so they need not sum
 to 100; a weight of 0 means that node is never picked (inactive). In the GUI
-weights come from a per-node % input (a dict); headless callers may pass a
+weights come from a per-node % input (a dict); callers may also pass a
 comma-separated string mapped to ``nodes`` in order.
 
 The trigger / next-trial wait is the shared sequential kit loop: pause while
@@ -21,7 +21,6 @@
 
     exp = build(nodes=[1, 2, 3], probabilities="20,30,50",
                 next_trial_wait="fixed_delay", fixed_delay_s=10.0)
-    exp.run(interface="vcan0")
 """
 
 from __future__ import annotations
diff --git a/tools/dev_gui/base_station/experiment/templates/two_armed_bandit.py b/packages/dev_gui/base_station/experiment/templates/two_armed_bandit.py
similarity index 99%
rename from tools/dev_gui/base_station/experiment/templates/two_armed_bandit.py
rename to packages/dev_gui/base_station/experiment/templates/two_armed_bandit.py
index 9e68126..806689c 100644
--- a/tools/dev_gui/base_station/experiment/templates/two_armed_bandit.py
+++ b/packages/dev_gui/base_station/experiment/templates/two_armed_bandit.py
@@ -66,7 +66,6 @@
     from base_station.experiment.templates.two_armed_bandit import build
 
     exp = build(nodes=[1, 2], block_size=50, p_high=0.9, seed=42)
-    exp.run(interface="vcan0")
 """
 
 from __future__ import annotations
diff --git a/tools/dev_gui/base_station/io_manager.py b/packages/dev_gui/base_station/io_manager.py
similarity index 100%
rename from tools/dev_gui/base_station/io_manager.py
rename to packages/dev_gui/base_station/io_manager.py
diff --git a/tools/dev_gui/base_station/log_manager.py b/packages/dev_gui/base_station/log_manager.py
similarity index 100%
rename from tools/dev_gui/base_station/log_manager.py
rename to packages/dev_gui/base_station/log_manager.py
diff --git a/tools/dev_gui/base_station/mac_id_registry.py b/packages/dev_gui/base_station/mac_id_registry.py
similarity index 100%
rename from tools/dev_gui/base_station/mac_id_registry.py
rename to packages/dev_gui/base_station/mac_id_registry.py
diff --git a/tools/dev_gui/base_station/node_registry.py b/packages/dev_gui/base_station/node_registry.py
similarity index 100%
rename from tools/dev_gui/base_station/node_registry.py
rename to packages/dev_gui/base_station/node_registry.py
diff --git a/tools/dev_gui/base_station/pellet_ledger.py b/packages/dev_gui/base_station/pellet_ledger.py
similarity index 100%
rename from tools/dev_gui/base_station/pellet_ledger.py
rename to packages/dev_gui/base_station/pellet_ledger.py
diff --git a/tools/dev_gui/base_station/protocol.py b/packages/dev_gui/base_station/protocol.py
similarity index 100%
rename from tools/dev_gui/base_station/protocol.py
rename to packages/dev_gui/base_station/protocol.py
diff --git a/tools/dev_gui/base_station/storage.py b/packages/dev_gui/base_station/storage.py
similarity index 100%
rename from tools/dev_gui/base_station/storage.py
rename to packages/dev_gui/base_station/storage.py
diff --git a/tools/dev_gui/deploy/80-can.network b/packages/dev_gui/deploy/80-can.network
similarity index 100%
rename from tools/dev_gui/deploy/80-can.network
rename to packages/dev_gui/deploy/80-can.network
diff --git a/tools/dev_gui/deploy/README.md b/packages/dev_gui/deploy/README.md
similarity index 94%
rename from tools/dev_gui/deploy/README.md
rename to packages/dev_gui/deploy/README.md
index f030167..3edfa66 100644
--- a/tools/dev_gui/deploy/README.md
+++ b/packages/dev_gui/deploy/README.md
@@ -2,7 +2,7 @@
 
 One-time system configuration to bring up the MCP2515 CAN controller on the
 custom base station HAT as a standard SocketCAN `can0` interface. Do this
-once per Raspberry Pi before running the SFM Developer GUI (`tools/dev_gui`)
+once per Raspberry Pi before running the SFM Developer GUI (`packages/dev_gui`)
 against real hardware.
 
 ## Hardware reference
@@ -25,7 +25,7 @@ effect after a reboot, so the script reboots itself once automatically —
 run it again afterward to confirm everything came up:
 
 ```bash
-cd tools/dev_gui/deploy
+cd packages/dev_gui/deploy
 
 # First run: configures the Pi and reboots automatically if needed
 sudo ./setup-can.sh
@@ -106,7 +106,7 @@ heartbeat frames at 1 Hz once the node is assigned an ID.
 ## Run the GUI
 
 Once `can0` is up, the SFM Developer GUI works exactly as documented in
-[tools/dev_gui/README.md](../README.md) — no additional configuration is
+[packages/dev_gui/README.md](../README.md) — no additional configuration is
 needed; `CanManager` opens `can0` directly via SocketCAN.
 
 ## Interactive hardware validation
@@ -114,7 +114,7 @@ needed; `CanManager` opens `can0` directly via SocketCAN.
 For a full pin-by-pin checklist (CAN, AEO, BNC IN/OUT, button), run:
 
 ```bash
-cd tools/dev_gui
+cd packages/dev_gui
 python tests/test_hat.py
 ```
 
diff --git a/tools/dev_gui/deploy/boot-config-can.append.txt b/packages/dev_gui/deploy/boot-config-can.append.txt
similarity index 100%
rename from tools/dev_gui/deploy/boot-config-can.append.txt
rename to packages/dev_gui/deploy/boot-config-can.append.txt
diff --git a/tools/dev_gui/deploy/setup-can.sh b/packages/dev_gui/deploy/setup-can.sh
similarity index 95%
rename from tools/dev_gui/deploy/setup-can.sh
rename to packages/dev_gui/deploy/setup-can.sh
index f868c52..89a8c43 100755
--- a/tools/dev_gui/deploy/setup-can.sh
+++ b/packages/dev_gui/deploy/setup-can.sh
@@ -4,8 +4,8 @@ set -euo pipefail
 # One-shot setup for the SFM base station CAN HAT on Raspberry Pi OS.
 #
 # Usage:
-#   sudo ./tools/dev_gui/deploy/setup-can.sh            # install + configure
-#   sudo ./tools/dev_gui/deploy/setup-can.sh --verify   # check status only (no changes)
+#   sudo ./packages/dev_gui/deploy/setup-can.sh            # install + configure
+#   sudo ./packages/dev_gui/deploy/setup-can.sh --verify   # check status only (no changes)
 #
 # The device tree overlay only takes effect after a reboot. If this is the
 # first run on a fresh Pi, the script will append the overlay and reboot
diff --git a/docs/BASE_STATION_HARDCODED_VALUES.md b/packages/dev_gui/docs/BASE_STATION_HARDCODED_VALUES.md
similarity index 95%
rename from docs/BASE_STATION_HARDCODED_VALUES.md
rename to packages/dev_gui/docs/BASE_STATION_HARDCODED_VALUES.md
index 3bec0c1..281afe3 100644
--- a/docs/BASE_STATION_HARDCODED_VALUES.md
+++ b/packages/dev_gui/docs/BASE_STATION_HARDCODED_VALUES.md
@@ -1,12 +1,12 @@
 # Base station hardcoded / tunable values
 
 Living note of Python timings and parameter defaults used by the GUI, experiment
-templates, and behavior reports under `tools/dev_gui/`.
+templates, and behavior reports under `packages/dev_gui/`.
 **Update this file when you change a default.** Source of truth remains the code;
 this is the checklist.
 
 Node firmware constants (dispense motion, sensor confirm windows, CAN opcodes)
-live in [HARDCODED_VALUES.md](HARDCODED_VALUES.md). GUI-exposed experiment
+live in [HARDCODED_VALUES.md](../../../firmware/docs/HARDCODED_VALUES.md). GUI-exposed experiment
 parameters can be overridden at Start without editing code; values here are the
 defaults those forms ship with, plus the ones that are *not* on a form.
 
@@ -49,7 +49,7 @@ defaults those forms ship with, plus the ones that are *not* on a form.
 ## HAT I/O and camera sync
 
 Pins are BCM numbering, fixed by the custom CAN HAT. See
-[deploy/README.md](../tools/dev_gui/deploy/README.md).
+[deploy/README.md](../deploy/README.md).
 
 
 | Value | Constant | Location | Notes |
@@ -91,7 +91,7 @@ Shared by every `@exp.script` template (`kit.synchronized_cycle`,
 | 64 | `MAX_ADVANCES_PER_TICK` | `script.py` | Cap on consecutive yield-resolves in one `step()` so a tight loop cannot spin the GUI |
 | 100 ms | `_poll` / `_run` reschedule | `kit.after_advance` | Presence-clear / session-pause poll interval (free-feeding reloads) |
 | 5 s | `resolve_advance` `default_delay_s` | `kit.py` | Fallback ITI if a template does not pass its own default |
-| [1, 2, 3] | `kit.session` default nodes | `kit.py` | Used when a headless `build()` is called with `nodes=None`. GUI always passes the live roster |
+| [1, 2, 3] | `kit.session` default nodes | `kit.py` | Used when `build()` is called with `nodes=None`. GUI always passes the live roster |
 
 
 Pellet-taken and presence-clear waits have **no timeout by design**. An animal
@@ -102,9 +102,9 @@ That stall is visible via `script_stalled`.
 
 ## Experiment parameter defaults
 
-These are the JSON form defaults (`tools/dev_gui/experiments/*.json`). Changing
+These are the JSON form defaults (`packages/dev_gui/experiments/*.json`). Changing
 the JSON changes what the GUI Start form shows; Python `build()` kwargs are the
-headless fallbacks (kept in sync).
+fallbacks (kept in sync).
 
 
 ### Shared across templates
@@ -178,7 +178,7 @@ headless fallbacks (kept in sync).
 Defaults used when a report design does not override them in
 `report/designs/*.json`. These shape analysis, not the live session.
 The report generator lives in a separate package,
-[`packages/sfm-analysis`](../packages/sfm-analysis/README.md) — every
+[`packages/sfm-analysis`](../../sfm-analysis/README.md) — every
 `report/...` path below is relative to
 `packages/sfm-analysis/src/sfm_analysis/`.
 
diff --git a/docs/GUI.png b/packages/dev_gui/docs/GUI.png
similarity index 100%
rename from docs/GUI.png
rename to packages/dev_gui/docs/GUI.png
diff --git a/packages/dev_gui/examples/templates/README.md b/packages/dev_gui/examples/templates/README.md
new file mode 100644
index 0000000..ce58c73
--- /dev/null
+++ b/packages/dev_gui/examples/templates/README.md
@@ -0,0 +1,41 @@
+# Custom experiment starters
+
+Copy-from templates for authoring your own task. They are **not** loaded
+by the GUI — `resolve_builder()` only imports
+`base_station.experiment.templates.<name>`. To make one appear in the
+Experiment panel, copy the pair into the engine:
+
+```
+packages/dev_gui/
+├── experiments/
+│   └── <name>.json                         # GUI form + parameter schema
+└── base_station/experiment/templates/
+    └── <name>.py                           # def build(**kwargs) -> Experiment
+```
+
+`template` in the JSON must equal the Python module name. After copying,
+the GUI lists it on the next launch; no registry edit is required. Optional:
+re-export in `templates/__init__.py` if you want
+`from base_station.experiment.templates import <name>`.
+
+## File layout (what you add)
+
+```
+experiments/<name>.json          # name, label, template, parameters[]
+templates/<name>.py              # build(nodes=None, *, name=..., **params)
+tests/test_<name>.py             # optional: make_runner() + inject() (no CAN)
+```
+
+A matching report design (optional, in `packages/sfm-analysis`) uses the
+same `<name>` in `"matches"` so `sfm-report` picks it automatically — see
+`packages/sfm-analysis/examples/report_design/`.
+
+## The two styles
+
+| Starter | Style | Behavior |
+|---------|--------|----------|
+| [`alternation.py`](alternation.py) + [`.json`](alternation.json) | Event-based (`@exp.on_*`) | Round-robin: after each take, wait, then dispense the next node |
+| [`bnc_paced.py`](bnc_paced.py) + [`.json`](bnc_paced.json) | Sequential (`@exp.script`) | BNC rising edge → dispense → wait for take → ITI → repeat |
+
+API reference, fault handling, and `@exp.script` semantics:
+[`base_station/experiment/README.md`](../../base_station/experiment/README.md).
diff --git a/packages/dev_gui/examples/templates/alternation.json b/packages/dev_gui/examples/templates/alternation.json
new file mode 100644
index 0000000..7f62565
--- /dev/null
+++ b/packages/dev_gui/examples/templates/alternation.json
@@ -0,0 +1,37 @@
+{
+  "name": "alternation",
+  "label": "Alternation (example)",
+  "template": "alternation",
+  "description": "Starter template: round-robin reload. After each take, wait, then dispense the next node in the session roster.",
+  "parameters": [
+    {
+      "key": "nodes",
+      "label": "Active nodes",
+      "type": "nodes",
+      "help": "Nodes this experiment runs on, in visit order"
+    },
+    {
+      "key": "delay_s",
+      "label": "Reload delay (s)",
+      "type": "float",
+      "default": 2.0,
+      "min": 0,
+      "max": 3600,
+      "help": "Wait this long after PelletTaken before dispensing the next node"
+    },
+    {
+      "key": "minutes",
+      "label": "Duration (min)",
+      "type": "float",
+      "default": 0,
+      "help": "0 = no limit"
+    },
+    {
+      "key": "max_pellets",
+      "label": "Max pellets",
+      "type": "int",
+      "default": 0,
+      "help": "0 = no cap"
+    }
+  ]
+}
diff --git a/packages/dev_gui/examples/templates/alternation.py b/packages/dev_gui/examples/templates/alternation.py
new file mode 100644
index 0000000..940a228
--- /dev/null
+++ b/packages/dev_gui/examples/templates/alternation.py
@@ -0,0 +1,70 @@
+"""
+alternation.py — starter event-based template.
+
+Round-robin reload: dispense the first session node at start; after each
+PelletTaken, wait ``delay_s`` then dispense the next node in
+``control.nodes`` (wrapping around). One node in the roster is a
+continuous reload of that node.
+
+Copy into the engine to register it in the GUI (see README.md next to
+this file): ``experiments/alternation.json`` +
+``base_station/experiment/templates/alternation.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from base_station.experiment.kit import log_faults, session
+from base_station.experiment.runner import Experiment
+
+
+def build(
+    nodes: Optional[Sequence[int]] = None,
+    *,
+    name: str = "alternation",
+    delay_s: float = 2.0,
+    hours: float = 0.0,
+    minutes: float = 0.0,
+    seconds: float = 0.0,
+    max_pellets: Optional[int] = None,
+    **_,
+) -> Experiment:
+    exp = session(name, nodes, hours=hours, minutes=minutes, seconds=seconds,
+                  max_pellets=max_pellets)
+    log_faults(exp)
+    delay = max(0.0, float(delay_s))
+
+    def _next_node(control, after: int) -> int:
+        roster = list(control.nodes)
+        if after in roster:
+            return roster[(roster.index(after) + 1) % len(roster)]
+        return roster[0]
+
+    @exp.on_start
+    def _start(control):
+        control.log("alternation_start", delay_s=delay, nodes=list(control.nodes))
+        control.next_trial()
+        control.dispense(control.nodes[0])
+
+    @exp.on_pellet_taken
+    def _advance(control, event):
+        nxt = _next_node(control, event.node_id)
+
+        def _go():
+            control.next_trial()
+            control.log("alternation_advance",
+                        from_node=event.node_id, to_node=nxt)
+            control.dispense(nxt)
+
+        if delay <= 0:
+            _go()
+        else:
+            control.after(delay, _go, node=nxt)
+
+    @exp.on_recover
+    def _rearm(control, event):
+        if event.node_id in control.nodes:
+            control.dispense(event.node_id)
+
+    return exp
diff --git a/packages/dev_gui/examples/templates/bnc_paced.json b/packages/dev_gui/examples/templates/bnc_paced.json
new file mode 100644
index 0000000..8bb5b2c
--- /dev/null
+++ b/packages/dev_gui/examples/templates/bnc_paced.json
@@ -0,0 +1,46 @@
+{
+  "name": "bnc_paced",
+  "label": "BNC-paced FR1 (example)",
+  "template": "bnc_paced",
+  "description": "Starter @exp.script template: wait for a BNC rising edge, dispense one node, wait for the take, optional ITI, repeat.",
+  "parameters": [
+    {
+      "key": "nodes",
+      "label": "Active nodes",
+      "type": "nodes",
+      "help": "The first checked node is the one that dispenses"
+    },
+    {
+      "key": "bnc_channel",
+      "label": "BNC IN channel",
+      "type": "int",
+      "default": 0,
+      "min": 0,
+      "max": 1,
+      "help": "0 = BNC IN 1, 1 = BNC IN 2"
+    },
+    {
+      "key": "iti_s",
+      "label": "ITI after take (s)",
+      "type": "float",
+      "default": 1.0,
+      "min": 0,
+      "max": 3600,
+      "help": "Fixed wait after PelletTaken before the next BNC arm"
+    },
+    {
+      "key": "minutes",
+      "label": "Duration (min)",
+      "type": "float",
+      "default": 0,
+      "help": "0 = no limit"
+    },
+    {
+      "key": "max_pellets",
+      "label": "Max pellets",
+      "type": "int",
+      "default": 0,
+      "help": "0 = no cap"
+    }
+  ]
+}
diff --git a/packages/dev_gui/examples/templates/bnc_paced.py b/packages/dev_gui/examples/templates/bnc_paced.py
new file mode 100644
index 0000000..0929ea5
--- /dev/null
+++ b/packages/dev_gui/examples/templates/bnc_paced.py
@@ -0,0 +1,73 @@
+"""
+bnc_paced.py — starter @exp.script template.
+
+One trial = wait for a BNC IN rising edge, dispense the first session
+node, wait for PelletTaken (no timeout — the animal sets the pace),
+then a fixed ITI. A fault on that node resolves the take-wait with
+``.faulted``; the script logs it and arms the next BNC edge.
+
+Copy into the engine to register it in the GUI (see README.md next to
+this file): ``experiments/bnc_paced.json`` +
+``base_station/experiment/templates/bnc_paced.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from base_station.experiment.kit import log_faults, session
+from base_station.experiment.runner import Experiment
+
+
+def build(
+    nodes: Optional[Sequence[int]] = None,
+    *,
+    name: str = "bnc_paced",
+    bnc_channel: int = 0,
+    iti_s: float = 1.0,
+    hours: float = 0.0,
+    minutes: float = 0.0,
+    seconds: float = 0.0,
+    max_pellets: Optional[int] = None,
+    **_,
+) -> Experiment:
+    exp = session(name, nodes, hours=hours, minutes=minutes, seconds=seconds,
+                  max_pellets=max_pellets)
+    log_faults(exp)
+    channel = int(bnc_channel)
+    iti = max(0.0, float(iti_s))
+
+    @exp.script
+    def run(control):
+        node = control.nodes[0]
+        control.log("bnc_paced_start", node=node, bnc_channel=channel, iti_s=iti)
+
+        while True:
+            while True:
+                edge = yield control.wait_for("bnc_in")
+                if not edge.ok or edge.event is None:
+                    continue
+                data = edge.event.data or {}
+                if data.get("edge") != "rising":
+                    continue
+                if data.get("channel") not in (None, channel):
+                    continue
+                break
+
+            trial = control.next_trial()
+            control.log("bnc_paced_trial", trial=trial, node=node)
+            if not control.dispense(node):
+                control.log("bnc_paced_skipped", trial=trial, node=node)
+                continue
+
+            taken = yield control.wait_for("pellet_taken", node=node)
+            if taken.faulted:
+                control.log("bnc_paced_faulted", trial=trial,
+                            node=taken.faulted_node or node)
+                yield control.wait(1.0)
+                continue
+
+            if iti > 0:
+                yield control.wait(iti)
+
+    return exp
diff --git a/tools/dev_gui/experiments/fixed_and_random.json b/packages/dev_gui/experiments/fixed_and_random.json
similarity index 100%
rename from tools/dev_gui/experiments/fixed_and_random.json
rename to packages/dev_gui/experiments/fixed_and_random.json
diff --git a/tools/dev_gui/experiments/free_feeding.json b/packages/dev_gui/experiments/free_feeding.json
similarity index 100%
rename from tools/dev_gui/experiments/free_feeding.json
rename to packages/dev_gui/experiments/free_feeding.json
diff --git a/tools/dev_gui/experiments/probability_delivery.json b/packages/dev_gui/experiments/probability_delivery.json
similarity index 100%
rename from tools/dev_gui/experiments/probability_delivery.json
rename to packages/dev_gui/experiments/probability_delivery.json
diff --git a/tools/dev_gui/experiments/two_armed_bandit.json b/packages/dev_gui/experiments/two_armed_bandit.json
similarity index 100%
rename from tools/dev_gui/experiments/two_armed_bandit.json
rename to packages/dev_gui/experiments/two_armed_bandit.json
diff --git a/tools/dev_gui/node_simulator.py b/packages/dev_gui/node_simulator.py
similarity index 100%
rename from tools/dev_gui/node_simulator.py
rename to packages/dev_gui/node_simulator.py
diff --git a/tools/dev_gui/pytest.ini b/packages/dev_gui/pytest.ini
similarity index 100%
rename from tools/dev_gui/pytest.ini
rename to packages/dev_gui/pytest.ini
diff --git a/tools/dev_gui/requirements.txt b/packages/dev_gui/requirements.txt
similarity index 92%
rename from tools/dev_gui/requirements.txt
rename to packages/dev_gui/requirements.txt
index 8dd6009..068afe9 100644
--- a/tools/dev_gui/requirements.txt
+++ b/packages/dev_gui/requirements.txt
@@ -8,4 +8,4 @@ gpiod>=2.1
 # change under packages/ is live immediately -- the same single-checkout
 # dev loop this repo has always had. Switch to a pinned `sfm-analysis>=X.Y`
 # once the package is published to PyPI.
--e ../../packages/sfm-analysis
+-e ../sfm-analysis
diff --git a/tools/dev_gui/run.py b/packages/dev_gui/run.py
similarity index 100%
rename from tools/dev_gui/run.py
rename to packages/dev_gui/run.py
diff --git a/tools/dev_gui/run_report.py b/packages/dev_gui/run_report.py
similarity index 100%
rename from tools/dev_gui/run_report.py
rename to packages/dev_gui/run_report.py
diff --git a/tools/dev_gui/setup_storage.sh b/packages/dev_gui/setup_storage.sh
similarity index 100%
rename from tools/dev_gui/setup_storage.sh
rename to packages/dev_gui/setup_storage.sh
diff --git a/tools/dev_gui/tests/__init__.py b/packages/dev_gui/tests/__init__.py
similarity index 100%
rename from tools/dev_gui/tests/__init__.py
rename to packages/dev_gui/tests/__init__.py
diff --git a/tools/dev_gui/tests/test_app.py b/packages/dev_gui/tests/test_app.py
similarity index 100%
rename from tools/dev_gui/tests/test_app.py
rename to packages/dev_gui/tests/test_app.py
diff --git a/tools/dev_gui/tests/test_app_pellet_counting.py b/packages/dev_gui/tests/test_app_pellet_counting.py
similarity index 100%
rename from tools/dev_gui/tests/test_app_pellet_counting.py
rename to packages/dev_gui/tests/test_app_pellet_counting.py
diff --git a/tools/dev_gui/tests/test_behavioral_log_names.py b/packages/dev_gui/tests/test_behavioral_log_names.py
similarity index 100%
rename from tools/dev_gui/tests/test_behavioral_log_names.py
rename to packages/dev_gui/tests/test_behavioral_log_names.py
diff --git a/tools/dev_gui/tests/test_discovery_manager.py b/packages/dev_gui/tests/test_discovery_manager.py
similarity index 100%
rename from tools/dev_gui/tests/test_discovery_manager.py
rename to packages/dev_gui/tests/test_discovery_manager.py
diff --git a/tools/dev_gui/tests/test_experiment.py b/packages/dev_gui/tests/test_experiment.py
similarity index 99%
rename from tools/dev_gui/tests/test_experiment.py
rename to packages/dev_gui/tests/test_experiment.py
index af63bb2..4279250 100644
--- a/tools/dev_gui/tests/test_experiment.py
+++ b/packages/dev_gui/tests/test_experiment.py
@@ -1,4 +1,4 @@
-"""Tests for the headless experiment engine and free-feeding template."""
+"""Tests for the experiment engine and free-feeding template."""
 
 from __future__ import annotations
 
@@ -840,7 +840,7 @@ def test_fixed_and_random_multiple_fixed_roles() -> None:
 
 
 def test_fixed_and_random_fixed_nodes_string_backcompat() -> None:
-    """Legacy headless form: fixed_nodes string → those fixed, others random."""
+    """Legacy form: fixed_nodes string → those fixed, others random."""
     exp = build_fixed_and_random(
         nodes=[1, 2, 3], fixed_nodes="1", trigger="timer",
         interval_s=5.0, random_prob=0.0, seconds=60, seed=1,
diff --git a/tools/dev_gui/tests/test_experiment_schema.py b/packages/dev_gui/tests/test_experiment_schema.py
similarity index 85%
rename from tools/dev_gui/tests/test_experiment_schema.py
rename to packages/dev_gui/tests/test_experiment_schema.py
index 1f66362..35314f9 100644
--- a/tools/dev_gui/tests/test_experiment_schema.py
+++ b/packages/dev_gui/tests/test_experiment_schema.py
@@ -155,3 +155,25 @@ def test_node_choice_dict_flows_to_builder() -> None:
     )
     assert exp.name == "fixed_and_random"
     assert exp.nodes == [1, 2, 3]
+
+
+def test_example_templates_build() -> None:
+    """Copy-from starters must keep a valid JSON schema and a build() factory."""
+    import importlib.util
+
+    root = Path(__file__).resolve().parents[1] / "examples" / "templates"
+    for name in ("alternation", "bnc_paced"):
+        defn = load_experiment_def(root / f"{name}.json")
+        assert defn.template == name
+        spec = importlib.util.spec_from_file_location(name, root / f"{name}.py")
+        assert spec is not None and spec.loader is not None
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        exp = mod.build(nodes=[1, 2], minutes=1)
+        assert exp.name == name
+        assert exp.nodes == [1, 2]
+    paced = importlib.util.spec_from_file_location("bnc_paced", root / "bnc_paced.py")
+    assert paced is not None and paced.loader is not None
+    paced_mod = importlib.util.module_from_spec(paced)
+    paced.loader.exec_module(paced_mod)
+    assert paced_mod.build(nodes=[1])._script is not None
diff --git a/tools/dev_gui/tests/test_hat.py b/packages/dev_gui/tests/test_hat.py
similarity index 99%
rename from tools/dev_gui/tests/test_hat.py
rename to packages/dev_gui/tests/test_hat.py
index fbded32..25abc91 100644
--- a/tools/dev_gui/tests/test_hat.py
+++ b/packages/dev_gui/tests/test_hat.py
@@ -6,7 +6,7 @@
 it is a manual, interactive checklist you run directly on the Raspberry Pi
 with the HAT (and ideally at least one VFM node) connected:
 
-    cd tools/dev_gui
+    cd packages/dev_gui
     python tests/test_hat.py
     python tests/test_hat.py --skip can,button      # skip specific sections
     python tests/test_hat.py --interface can0
@@ -69,7 +69,7 @@ def check_can_interface_up(interface: str) -> None:
     if not up:
         print(
             f"  Hint: check /boot/firmware/config.txt for the mcp2515-can0 overlay\n"
-            f"  and see tools/dev_gui/deploy/README.md for full bring-up steps."
+            f"  and see packages/dev_gui/deploy/README.md for full bring-up steps."
         )
 
 
diff --git a/tools/dev_gui/tests/test_log_manager.py b/packages/dev_gui/tests/test_log_manager.py
similarity index 100%
rename from tools/dev_gui/tests/test_log_manager.py
rename to packages/dev_gui/tests/test_log_manager.py
diff --git a/tools/dev_gui/tests/test_mac_id_registry.py b/packages/dev_gui/tests/test_mac_id_registry.py
similarity index 100%
rename from tools/dev_gui/tests/test_mac_id_registry.py
rename to packages/dev_gui/tests/test_mac_id_registry.py
diff --git a/tools/dev_gui/tests/test_node_registry.py b/packages/dev_gui/tests/test_node_registry.py
similarity index 100%
rename from tools/dev_gui/tests/test_node_registry.py
rename to packages/dev_gui/tests/test_node_registry.py
diff --git a/tools/dev_gui/tests/test_pellet_ledger.py b/packages/dev_gui/tests/test_pellet_ledger.py
similarity index 100%
rename from tools/dev_gui/tests/test_pellet_ledger.py
rename to packages/dev_gui/tests/test_pellet_ledger.py
diff --git a/tools/dev_gui/tests/test_protocol.py b/packages/dev_gui/tests/test_protocol.py
similarity index 100%
rename from tools/dev_gui/tests/test_protocol.py
rename to packages/dev_gui/tests/test_protocol.py
diff --git a/tools/dev_gui/tests/test_run_report_shim.py b/packages/dev_gui/tests/test_run_report_shim.py
similarity index 100%
rename from tools/dev_gui/tests/test_run_report_shim.py
rename to packages/dev_gui/tests/test_run_report_shim.py
diff --git a/tools/dev_gui/tests/test_schedule.py b/packages/dev_gui/tests/test_schedule.py
similarity index 100%
rename from tools/dev_gui/tests/test_schedule.py
rename to packages/dev_gui/tests/test_schedule.py
diff --git a/tools/dev_gui/tests/test_script.py b/packages/dev_gui/tests/test_script.py
similarity index 100%
rename from tools/dev_gui/tests/test_script.py
rename to packages/dev_gui/tests/test_script.py
diff --git a/tools/dev_gui/tests/test_two_armed_bandit.py b/packages/dev_gui/tests/test_two_armed_bandit.py
similarity index 100%
rename from tools/dev_gui/tests/test_two_armed_bandit.py
rename to packages/dev_gui/tests/test_two_armed_bandit.py
diff --git a/packages/sfm-analysis/README.md b/packages/sfm-analysis/README.md
index 89fb576..330affb 100644
--- a/packages/sfm-analysis/README.md
+++ b/packages/sfm-analysis/README.md
@@ -7,7 +7,7 @@ libraries. Pure standard library: no jinja2, no pandas, no matplotlib. A
 report is one self-contained HTML file with inline SVG charts, printable
 via Ctrl+P.
 
-This package is carved out of the VFM repository's `tools/dev_gui/`
+This package is carved out of the VFM repository's `packages/dev_gui/`
 (the Raspberry Pi base station that records the logs) precisely so that
 analysis doesn't have to happen on the Pi. The base station's own
 `run_report.py` is a thin wrapper around the CLI documented below.
@@ -126,6 +126,16 @@ experiment engine's own JSON-schema/Python split (`base_station/experiment/`
 in the parent repo — `matches: []` in a design plays the same role as
 `build(**kwargs)` in an experiment template).
 
+```
+src/sfm_analysis/report/
+├── designs/<name>.json     # "matches": ["<experiment>"] + ordered refs
+├── analyses/<name>.py      # numbers (no HTML)
+└── sections/<name>.py      # HTML; SECTIONS = {"func": ...}
+```
+
+Copy-from starter: [`examples/report_design/`](examples/report_design/).
+Full walkthrough: [docs/ANALYSIS_GUIDE.md](docs/ANALYSIS_GUIDE.md#9-turning-an-analysis-into-a-report-section).
+
 The design is picked automatically from the session's `experiment` field
 (the fields_json on its `session_start` row), falling back to
 `default.json` for anything without a matching design or with no
@@ -304,6 +314,7 @@ scratch:
 | [`dome_openings_during_presence.py`](examples/analysis/dome_openings_during_presence.py) | Windows where the dome was open while the mouse was present |
 | [`retrieval_latency_by_node.py`](examples/analysis/retrieval_latency_by_node.py) | Per-node summary stats, stdlib-only and pandas paths side by side |
 | [`takes_after_fault.py`](examples/analysis/takes_after_fault.py) | Pellet takes within a window after each fault interval started |
+| [`exp_events_by_name.py`](examples/analysis/exp_events_by_name.py) | Inventory a session's experiment-engine (`source=EXP`) events — the starting point for analysing a custom template's own log rows |
 
 Every one of them runs standalone against the bundled demo session, no
 rig or `--log-dir` needed:
@@ -317,6 +328,12 @@ output pinned against the demo session's known ground truth — a change
 that breaks a documented recipe fails the build instead of being found
 by the next person who copies one.
 
+To ship a **custom report design** for your own experiment (JSON design +
+Python analysis + HTML section), copy the three-file starter under
+[`examples/report_design/`](examples/report_design/) into
+`src/sfm_analysis/report/{designs,analyses,sections}/`. File layout and a
+worked walkthrough: [docs/ANALYSIS_GUIDE.md](docs/ANALYSIS_GUIDE.md#9-turning-an-analysis-into-a-report-section).
+
 ## Testing your own analysis code
 
 The test suite's own fixture builders are the fastest way to get a
@@ -360,10 +377,12 @@ pytest
 
 ## Design notes worth knowing
 
-- **Self-contained is a hard invariant.** No `<script>`, no `http(s)://`
-  reference — the whole report must render and print with the network
-  unplugged (`report/render.py`'s module docstring; enforced by
-  `tests/test_report_render.py`).
+- **Self-contained is a hard invariant.** No `http(s)://` reference, no
+  `<script src=>`, nothing that needs the network to render or print
+  (`report/render.py`'s module docstring; enforced by
+  `tests/test_report_render.py`). The interactive timeline is the one
+  exception to "no script": at most one inline `<script>` in the whole
+  document. `--no-explorer` drops it for a guaranteed script-free file.
 - **Every chart binds color + dash pattern + marker glyph + hatch texture
   to the same ordinal "key"** (`report/style.py`), so a series never
   depends on hue alone — this matters most exactly when a report is
@@ -375,7 +394,7 @@ pytest
 ## Firmware/SDK version skew
 
 `sfm_analysis.protocol` is a Python mirror of the VFM firmware's
-`src/services/ServiceTypes.h` and `src/services/CanService.h` (parent
+`firmware/src/services/ServiceTypes.h` and `firmware/src/services/CanService.h` (parent
 repo). Because this package now versions and ships independently of the
 firmware, it's possible for a base station running old firmware to be
 paired with a newer `sfm-analysis`, or vice versa. There's no version
diff --git a/packages/sfm-analysis/docs/ANALYSIS_GUIDE.md b/packages/sfm-analysis/docs/ANALYSIS_GUIDE.md
index 20c7864..ab207d7 100644
--- a/packages/sfm-analysis/docs/ANALYSIS_GUIDE.md
+++ b/packages/sfm-analysis/docs/ANALYSIS_GUIDE.md
@@ -23,6 +23,8 @@ building something the cookbook doesn't cover.
 7. [Time, timezone, and time-of-day](#7-time-timezone-and-time-of-day)
 8. [Designing your own analysis: a worked example](#8-designing-your-own-analysis-a-worked-example)
 9. [Turning an analysis into a report section](#9-turning-an-analysis-into-a-report-section)
+   - [File layout](#file-layout)
+   - [Complete example (custom experiment → custom design)](#complete-example-custom-experiment--custom-design)
 
 ## 1. Which layer to work at
 
@@ -59,7 +61,7 @@ doesn't bloat the main log.
 |---|---|---|
 | `timestamp_iso` | rig-local wall-clock string, e.g. `2025-06-01T14:32:07.123` | Written with `datetime.fromtimestamp()` **on the rig**, so it's already correct local time — see [§7](#7-time-timezone-and-time-of-day) |
 | `timestamp_ms` | epoch milliseconds | Used to recompute `.t` on load; don't trust it for wall-clock display without knowing the rig's real-world offset |
-| `elapsed_s` | seconds since the row's *originating process* started | **Never read this directly** — it resets across a reopened session and means something different for the GUI vs. a headless script. Use `RunData` rows' `.t` instead (see trap #2 below) |
+| `elapsed_s` | seconds since the row's *originating process* started | **Never read this directly** — it resets across a reopened session. Use `RunData` rows' `.t` instead (see trap #2 below) |
 | `session` | the session name | Groups rows into files; combined with `run_id` for run-scoping |
 | `run_id` | increments each time a session is reopened | A single CSV can hold several runs — see trap #1 |
 | `trial` | current trial number, `0` outside a trial | Convenience column; the authoritative trial boundary is the `trial` EXPERIMENT event |
@@ -159,6 +161,10 @@ s = load_session("EXP-Test-02")
 names = sorted({row["event_name"] for row in s.events_table(source="EXP")})
 ```
 
+[`examples/analysis/exp_events_by_name.py`](../examples/analysis/exp_events_by_name.py)
+runs that inventory against the bundled demo session (and is pinned in CI).
+Copy it as the first script you write against a new custom template.
+
 `report.metrics.APPARATUS_HEALTH_EVENTS` is the curated subset the report's
 "Apparatus Health" section surfaces — a good starting list of the
 diagnostic (as opposed to trial-structure) events worth watching.
@@ -406,6 +412,105 @@ Optional[SectionResult]` (`report.schema`), registered in some
 `report/sections/<module>.py`'s `SECTIONS` dict, referenced by
 `"module.function"` in a design JSON.
 
+### File layout
+
+Same split as an experiment template (JSON declares *what*, Python holds
+*behavior*), with one extra file because one experiment often has several
+related figures:
+
+```
+packages/sfm-analysis/src/sfm_analysis/report/
+├── designs/
+│   └── <name>.json       # "matches": ["<experiment>"] + ordered section refs
+├── analyses/
+│   └── <name>.py         # numbers: functions / dataclasses, no HTML
+└── sections/
+    └── <name>.py         # HTML; SECTIONS = {"func": fn, ...}
+```
+
+`resolve_design(experiment)` picks a design by `name` or `matches`, else
+`default.json`. `resolve_section("module.func")` imports
+`sections.<module>` and returns `SECTIONS["func"]`. Copy-from starter for
+the `alternation` experiment example:
+[`examples/report_design/`](../examples/report_design/).
+
+### Complete example (custom experiment → custom design)
+
+Pair this with `packages/dev_gui/examples/templates/alternation.py`, which
+logs `alternation_advance` (`from_node`, `to_node`) on every switch. After
+copying the three files below into the tree above, `sfm-report` on an
+alternation session renders a switch table at the end of the generic
+sections.
+
+`designs/alternation.json` (abridged — the starter file includes timeline
++ generic sections too):
+
+```json
+{
+  "name": "alternation",
+  "matches": ["alternation"],
+  "sections": [
+    { "ref": "generic.provenance" },
+    { "ref": "generic.retrieval_latency" },
+    { "ref": "alternation.switch_table" }
+  ],
+  "combined_sections": [
+    { "ref": "compare.cohort_table" },
+    { "ref": "alternation.switch_table" }
+  ]
+}
+```
+
+`analyses/alternation.py`:
+
+```python
+from collections import Counter
+from typing import Dict, List, Tuple
+from ..session import RunData
+
+def switches(run: RunData) -> List[Tuple[int, int, float]]:
+    out = []
+    for row in run.exp("alternation_advance"):
+        src, dst = row.fields.get("from_node"), row.fields.get("to_node")
+        if src is not None and dst is not None:
+            out.append((int(src), int(dst), row.t))
+    return out
+
+def switch_counts(run: RunData) -> Dict[Tuple[int, int], int]:
+    return Counter((a, b) for a, b, _ in switches(run))
+```
+
+`sections/alternation.py`:
+
+```python
+from typing import Optional
+from ..analyses.alternation import switch_counts, switches
+from ..charts import escape_text
+from ..schema import SectionContext, SectionResult
+
+def switch_table_section(ctx: SectionContext) -> Optional[SectionResult]:
+    parts = []
+    for run, m in zip(ctx.runs, ctx.metrics):
+        rows = switches(run)
+        if not rows:
+            continue
+        counts = switch_counts(run)
+        body = "".join(
+            f"<tr><td>{a} → {b}</td><td>{n}</td></tr>"
+            for (a, b), n in sorted(counts.items())
+        )
+        parts.append(f"<table><tr><th>From → to</th><th>Count</th></tr>{body}</table>")
+    if not parts:
+        return SectionResult(section_id="alternation.switch_table",
+                             title="Alternation switches", html="", empty=True)
+    return SectionResult(section_id="alternation.switch_table",
+                         title="Alternation switches", html="".join(parts))
+
+SECTIONS = {"switch_table": switch_table_section}
+```
+
+Minimal section shape, if you are not pairing with a new experiment:
+
 ```python
 def my_section(ctx: SectionContext) -> Optional[SectionResult]:
     figs = []
diff --git a/packages/sfm-analysis/examples/analysis/exp_events_by_name.py b/packages/sfm-analysis/examples/analysis/exp_events_by_name.py
new file mode 100644
index 0000000..3fd3ada
--- /dev/null
+++ b/packages/sfm-analysis/examples/analysis/exp_events_by_name.py
@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""exp_events_by_name.py — inventory a session's experiment-engine rows.
+
+Custom templates log their own EXP events (bandit_trial, alternation_advance,
+probability_pick, …). Before writing an analysis against those names, list
+what the file actually contains — this is the escape hatch in
+ANALYSIS_GUIDE §3.
+
+The demo session is two_armed_bandit, so the printed names are that
+template's vocabulary plus the engine's session-lifecycle rows.
+
+    python examples/analysis/exp_events_by_name.py
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from sfm_analysis.analysis import load_session
+from sfm_analysis.report.demo import DEMO_SESSION_PATH
+
+
+def main() -> None:
+    s = load_session(str(DEMO_SESSION_PATH))
+    run = s.run()
+    rows = s.events_table(run_id=run.run_id, source="EXP")
+    counts = Counter(row["event_name"] for row in rows)
+
+    print(f"{run.run_label}: {len(rows)} EXP row(s), {len(counts)} distinct name(s)")
+    for name, n in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0])):
+        print(f"  {n:4d}  {name}")
+
+    ends = [row for row in rows if row["event_name"] == "bandit_trial_end"]
+    valid = sum(1 for row in ends if (row["fields"] or {}).get("valid") == 1)
+    print(f"bandit_trial_end: {len(ends)} (valid={valid})")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/packages/sfm-analysis/examples/report_design/README.md b/packages/sfm-analysis/examples/report_design/README.md
new file mode 100644
index 0000000..a8f3088
--- /dev/null
+++ b/packages/sfm-analysis/examples/report_design/README.md
@@ -0,0 +1,36 @@
+# Custom report-design starter
+
+A report **design** is three files that share a name with the experiment
+template they describe. Copy them into the package — `resolve_design()`
+loads every `designs/*.json`; `resolve_section("module.func")` imports
+`sfm_analysis.report.sections.<module>.SECTIONS[func]`.
+
+```
+packages/sfm-analysis/src/sfm_analysis/report/
+├── designs/
+│   └── <name>.json          # section list; "matches": ["<experiment>"]
+├── analyses/
+│   └── <name>.py            # numbers (plain functions / dataclasses)
+└── sections/
+    └── <name>.py            # HTML; ends with SECTIONS = {"func": ...}
+```
+
+This folder is a copy-from pair for the `alternation` experiment starter
+in `packages/dev_gui/examples/templates/`. After copying:
+
+```bash
+# from packages/sfm-analysis/
+cp examples/report_design/designs/alternation.json src/sfm_analysis/report/designs/
+cp examples/report_design/analyses/alternation.py src/sfm_analysis/report/analyses/
+cp examples/report_design/sections/alternation.py src/sfm_analysis/report/sections/
+```
+
+`sfm-report` then picks this design for any session whose `session_start`
+`experiment` field is `"alternation"` (the `name` of the experiment
+template). Force it with `--design alternation`.
+
+Without a matching design, the generic `default.json` still renders —
+you do not have to ship a design on day one.
+
+Walkthrough of every field and a second, analysis-API-only example:
+[docs/ANALYSIS_GUIDE.md](../../docs/ANALYSIS_GUIDE.md#9-turning-an-analysis-into-a-report-section).
diff --git a/packages/sfm-analysis/examples/report_design/analyses/alternation.py b/packages/sfm-analysis/examples/report_design/analyses/alternation.py
new file mode 100644
index 0000000..e2d1895
--- /dev/null
+++ b/packages/sfm-analysis/examples/report_design/analyses/alternation.py
@@ -0,0 +1,29 @@
+"""analyses/alternation.py — starter numbers for the alternation example template.
+
+Counts ``alternation_advance`` rows the template logs (from_node → to_node)
+and the take that preceded each switch. Copy this file to
+``sfm_analysis/report/analyses/alternation.py``.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Dict, List, Tuple
+
+from ..session import RunData
+
+
+def switches(run: RunData) -> List[Tuple[int, int, float]]:
+    """(from_node, to_node, t) for every alternation_advance row."""
+    out: List[Tuple[int, int, float]] = []
+    for row in run.exp("alternation_advance"):
+        src = row.fields.get("from_node")
+        dst = row.fields.get("to_node")
+        if src is None or dst is None:
+            continue
+        out.append((int(src), int(dst), row.t))
+    return out
+
+
+def switch_counts(run: RunData) -> Dict[Tuple[int, int], int]:
+    return Counter((a, b) for a, b, _ in switches(run))
diff --git a/packages/sfm-analysis/examples/report_design/designs/alternation.json b/packages/sfm-analysis/examples/report_design/designs/alternation.json
new file mode 100644
index 0000000..b5d227b
--- /dev/null
+++ b/packages/sfm-analysis/examples/report_design/designs/alternation.json
@@ -0,0 +1,23 @@
+{
+  "name": "alternation",
+  "label": "Alternation — Behavior Report",
+  "description": "Starter design for the alternation example template. Generic sections plus a switch-count table from alternation_advance rows.",
+  "matches": ["alternation"],
+  "sections": [
+    { "ref": "timeline.explorer" },
+    { "ref": "timeline.session_raster" },
+    { "ref": "generic.provenance" },
+    { "ref": "generic.data_quality" },
+    { "ref": "generic.retrieval_latency" },
+    { "ref": "generic.throughput" },
+    { "ref": "generic.faults" },
+    { "ref": "generic.apparatus_health" },
+    { "ref": "alternation.switch_table" }
+  ],
+  "combined_sections": [
+    { "ref": "compare.cohort_table" },
+    { "ref": "generic.retrieval_latency" },
+    { "ref": "generic.faults" },
+    { "ref": "alternation.switch_table" }
+  ]
+}
diff --git a/packages/sfm-analysis/examples/report_design/sections/alternation.py b/packages/sfm-analysis/examples/report_design/sections/alternation.py
new file mode 100644
index 0000000..58c135a
--- /dev/null
+++ b/packages/sfm-analysis/examples/report_design/sections/alternation.py
@@ -0,0 +1,56 @@
+"""sections/alternation.py — HTML for the alternation starter analysis.
+
+Copy to ``sfm_analysis/report/sections/alternation.py``. A section reads
+``ctx.runs`` / ``ctx.metrics`` only — it must not touch the filesystem.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..analyses.alternation import switch_counts, switches
+from ..charts import escape_text
+from ..schema import SectionContext, SectionResult
+
+
+def switch_table_section(ctx: SectionContext) -> Optional[SectionResult]:
+    parts = []
+    any_data = False
+    for run, _m in zip(ctx.runs, ctx.metrics):
+        rows = switches(run)
+        if not rows:
+            continue
+        any_data = True
+        heading = f"<h3>{escape_text(run.run_label)}</h3>" if len(ctx.runs) > 1 else ""
+        counts = switch_counts(run)
+        body = "".join(
+            f"<tr><td>{a} → {b}</td><td>{n}</td></tr>"
+            for (a, b), n in sorted(counts.items())
+        )
+        parts.append(f"""
+        {heading}
+        <p>{len(rows)} switch(es) logged as <code>alternation_advance</code>.</p>
+        <table>
+          <tr><th>From → to</th><th>Count</th></tr>
+          {body}
+        </table>
+        """)
+
+    if not any_data:
+        return SectionResult(
+            section_id="alternation.switch_table",
+            title="Alternation switches",
+            html="",
+            empty=True,
+        )
+    return SectionResult(
+        section_id="alternation.switch_table",
+        title="Alternation switches",
+        html="".join(parts),
+        summary={"switches": sum(len(switches(r)) for r in ctx.runs)},
+    )
+
+
+SECTIONS = {
+    "switch_table": switch_table_section,
+}
diff --git a/packages/sfm-analysis/src/sfm_analysis/__init__.py b/packages/sfm-analysis/src/sfm_analysis/__init__.py
index 2bc8235..29610f8 100644
--- a/packages/sfm-analysis/src/sfm_analysis/__init__.py
+++ b/packages/sfm-analysis/src/sfm_analysis/__init__.py
@@ -1,11 +1,11 @@
 """sfm_analysis — cross-platform analysis and reporting for VFM/SFM feeder logs.
 
-Reads the session CSVs written by the VFM base station (``tools/dev_gui`` in
+Reads the session CSVs written by the VFM base station (``packages/dev_gui`` in
 the parent repo, https://github.com/Neurotech-Hub/VFM) and turns them into
 printable HTML behavior reports, with no dependency on the Raspberry Pi
 base-station GUI or any hardware library. Install with ``pip install
 sfm-analysis`` on Windows, macOS, or Linux and run ``sfm-report`` — see
-README.md for the full CLI and, in a later release, the Python analysis API.
+README.md for the full CLI and the Python analysis API.
 
 This package is stdlib-only by design: no jinja2, no pandas, no matplotlib.
 Reports are self-contained HTML with inline SVG, printable via Ctrl+P.
diff --git a/packages/sfm-analysis/src/sfm_analysis/logs.py b/packages/sfm-analysis/src/sfm_analysis/logs.py
index a43f20e..5d603c4 100644
--- a/packages/sfm-analysis/src/sfm_analysis/logs.py
+++ b/packages/sfm-analysis/src/sfm_analysis/logs.py
@@ -1,17 +1,14 @@
 """logs.py — the canonical VFM session-log CSV schemas.
 
-The single definition of both CSV schemas the VFM base station writes,
-shared with every reader in this package so a schema change can't
-silently drift between a writer and a reader in two different
-distributions:
+The single definition of both CSV schemas this package may encounter,
+shared with every reader so a schema change can't silently drift:
 
   - ``CSV_HEADER``: the 15-column unified session-log schema, written by
-    ``base_station.log_manager.LogManager`` (which binds it as a class
-    attribute) and read by ``sfm_analysis.report.loader``.
-  - ``EXP6_HEADER``: the 6-column headless-experiment CSV schema, written
-    by ``base_station.experiment.context.ExperimentControl`` (same
-    binding pattern) and also read by ``sfm_analysis.report.loader`` for
-    schema-sniffing.
+    ``base_station.log_manager.LogManager`` and read by
+    ``sfm_analysis.report.loader``. This is what the GUI writes today.
+  - ``EXP6_HEADER``: a legacy 6-column experiment CSV from older
+    standalone experiment runs. The loader still sniffs it so those
+    files are skipped with a warning instead of crashing.
 
 The report test suite's ``report_fixtures.py`` keys every synthetic row
 off ``CSV_HEADER`` precisely so a drift breaks the report tests loudly
diff --git a/packages/sfm-analysis/src/sfm_analysis/protocol.py b/packages/sfm-analysis/src/sfm_analysis/protocol.py
index 61864d8..7394580 100644
--- a/packages/sfm-analysis/src/sfm_analysis/protocol.py
+++ b/packages/sfm-analysis/src/sfm_analysis/protocol.py
@@ -1,7 +1,7 @@
 """
 protocol.py — VFM CAN protocol constants and frame helpers.
 
-Python mirror of src/services/ServiceTypes.h and src/services/CanService.h.
+Python mirror of firmware/src/services/ServiceTypes.h and firmware/src/services/CanService.h.
 All CAN ID arithmetic and payload encoding/decoding lives here so every other
 module imports a single source of truth.
 """
@@ -162,7 +162,7 @@ class ServiceStatus(IntEnum):
     """
     Fault codes carried in heartbeat byte 5 / Fault event extra.
 
-    Mirror of src/services/ServiceTypes.h ServiceStatus. Must match exactly —
+    Mirror of firmware/src/services/ServiceTypes.h ServiceStatus. Must match exactly —
     these are wire values, not just labels (see commit 4861a97, which dropped
     the firmware's ``Timeout`` member without updating this mirror; every code
     >= 2 decoded one fault low until this was fixed).
diff --git a/packages/sfm-analysis/src/sfm_analysis/report/loader.py b/packages/sfm-analysis/src/sfm_analysis/report/loader.py
index 0a87d04..7cd2a80 100644
--- a/packages/sfm-analysis/src/sfm_analysis/report/loader.py
+++ b/packages/sfm-analysis/src/sfm_analysis/report/loader.py
@@ -38,8 +38,8 @@ class LogSchema(str, Enum):
     UNIFIED = "unified"    # sfm_analysis.logs.CSV_HEADER — the only schema with fields_json
     LEGACY9 = "legacy9"    # timestamp_iso,timestamp_ms,direction,node_id,frame_type,
                             # event_name,raw_id_hex,raw_data_hex,details
-    EXP6 = "exp6"           # sfm_analysis.logs.EXP6_HEADER — the headless
-                            # ExperimentControl CSV (base_station.experiment.context)
+    EXP6 = "exp6"           # sfm_analysis.logs.EXP6_HEADER — legacy 6-column
+                            # experiment CSV (no longer written; sniffed so old files skip)
     UNKNOWN = "unknown"
 
 
diff --git a/packages/sfm-analysis/tests/report_fixtures.py b/packages/sfm-analysis/tests/report_fixtures.py
index f9ffd28..9af3290 100644
--- a/packages/sfm-analysis/tests/report_fixtures.py
+++ b/packages/sfm-analysis/tests/report_fixtures.py
@@ -154,7 +154,7 @@ def legacy9_file(tmp_path: Path, name: str = "legacy") -> Path:
 
 
 def exp6_file(tmp_path: Path, name: str = "experiment_free_feeding") -> Path:
-    """A file matching the headless ExperimentControl 6-column schema."""
+    """A file matching the legacy 6-column experiment CSV schema."""
     header = ["timestamp_iso", "timestamp_ms", "elapsed_s", "name", "node_id", "fields"]
     path = tmp_path / f"{name}.csv"
     with open(path, "w", newline="", encoding="utf-8") as f:
diff --git a/packages/sfm-analysis/tests/test_examples.py b/packages/sfm-analysis/tests/test_examples.py
index d3fbe9d..fb040d3 100644
--- a/packages/sfm-analysis/tests/test_examples.py
+++ b/packages/sfm-analysis/tests/test_examples.py
@@ -43,3 +43,11 @@ def test_takes_after_fault():
     assert result.returncode == 0, result.stderr
     assert "1 fault interval(s)" in result.stdout
     assert "1 pellet take(s) within 30s after a fault started" in result.stdout
+
+
+def test_exp_events_by_name():
+    result = _run("exp_events_by_name.py")
+    assert result.returncode == 0, result.stderr
+    assert "141 EXP row(s), 20 distinct name(s)" in result.stdout
+    assert "19  bandit_trial" in result.stdout
+    assert "bandit_trial_end: 17 (valid=17)" in result.stdout
diff --git a/tools/dev_gui/base_station/experiment/README.md b/tools/dev_gui/base_station/experiment/README.md
deleted file mode 100644
index d78c029..0000000
--- a/tools/dev_gui/base_station/experiment/README.md
+++ /dev/null
@@ -1,629 +0,0 @@
-# Writing Custom Experiment Templates (Python API)
-
-This is the guide for authoring your own experiments for the SFM dev GUI. An
-**experiment** automates the pellet-dispensing nodes over CAN: it decides *when*
-to dispense, *which* node(s), and *how* to react to what the nodes and the BNC
-sync inputs do.
-
-You write experiments in Python. There is **no base class to inherit** — a
-template is just a module with a `build(...)` factory that returns a configured
-`Experiment` object. A small JSON file describes the tunable parameters so the
-GUI can render a form for it.
-
-Everything an experiment does flows through the same CAN bus the manual controls
-use, so **the node tiles always show live status** while an experiment runs — you
-don't have to do anything special to keep them in sync. The same is true of the
-event log: `control.dispense` / `control.recover` (and their broadcast variants)
-show up as **COMMAND**-type rows identical to a manually-clicked button —
-filtering the log by COMMAND shows every command sent, regardless of whether a
-human or a running experiment triggered it. Everything else you log with
-`control.log(...)` (session lifecycle, per-cycle bookkeeping, etc.) shows up as
-**EXPERIMENT** rows.
-
-### Session naming and the unified log (GUI)
-
-The GUI's Experiment panel requires a **session name** before Start is
-enabled. That name resolves to one CSV, `<log_dir>/<sanitized_name>.csv`
-(non-alphanumeric characters collapse to `_`) — every CAN frame, heartbeat,
-BNC edge, and experiment row lands there with columns `run_id`, `trial`,
-`source`, and a lossless `fields_json` alongside the human-readable
-`details`. Starting a new run under a **name already used** appends rather
-than overwriting, and `run_id` increments so runs can be told apart in
-analysis — this is how a session picks back up across GUI restarts. All
-GUI-hosted experiments log through this one file; passing `log_dir` to
-`ExperimentController.start()` is a no-op from the GUI (`log_dir=None` is
-always passed to `make_runner()`) so nothing is written twice. The
-per-template `experiment_<name>_<timestamp>.csv` writer in
-`ExperimentControl` still exists and is used by headless runs (§11) — it
-just isn't wired up when the GUI hosts the runner.
-
-At the moment a session actually **activates** (immediately if the template
-has no `start_when`, later otherwise — see `ExperimentControl.on_session_start`),
-the GUI broadcasts `CanCmd.SyncFlash` (every node holds its status LED solid
-for ~500 ms) and fires a coincident BNC OUT pulse, so field-camera footage can
-be aligned to session start without a manual clapperboard. A node latched in
-`Fault` ignores the command (same guard the firmware uses for a solid fault
-indication) and is called out by id in the logged `SYNC` row.
-
-### Trial numbers
-
-Call `control.next_trial()` once per delivery cycle — the built-in templates
-that dispense on a timer/BNC trigger or per-node reload all do this, so
-`trial` (and its mirror `counter("trials")`) means "one delivery decision"
-consistently across templates, not just in `@exp.script`-based tasks like
-`two_armed_bandit`. The GUI mirrors the running `control.trial` onto every
-log row (CAN and experiment alike) each frame, so trial boundaries are
-visible outside `control.log(...)` rows too.
-
----
-
-## 1. Anatomy of a template
-
-Two files per template:
-
-```
-base_station/experiment/templates/<name>.py   # behavior  (the build() factory)
-experiments/<name>.json                   # parameters (drives the GUI form)
-```
-
-The Python module exposes one function:
-
-```python
-from ..runner import Experiment
-
-def build(nodes=None, *, name="<name>", **params) -> Experiment:
-    node_list = list(nodes) if nodes else [1, 2, 3]
-    exp = Experiment(nodes=node_list, name=name)
-
-    @exp.on_start
-    def _start(control):
-        for n in control.nodes:
-            control.dispense(n)
-
-    exp.end_after(minutes=30)
-    return exp
-```
-
-- `nodes` is injected by the GUI from the **node multi-select** in the Experiment
-  panel (or defaults inside the template). Templates iterate `control.nodes` —
-  never a hard-coded list — so node selection "just works".
-- Register behavior with the `@exp.on_*` decorators (§4), or write the task as
-  one sequential generator with `@exp.script` (§5) — you can mix both.
-- Call `exp.end_after(...)` for automatic stop conditions.
-- Return the `Experiment`.
-
-For duration/pellet-cap plumbing, the shared next-trial wait (`fixed_delay` /
-`presence_clear` / `bnc`), and the usual fault/recover logging, see
-[`kit.py`](kit.py) — small helpers the built-in templates share
-(`kit.session(...)`, `kit.wire_advance(...)`, `kit.next_trial_wait(...)`,
-`kit.after_advance(...)`, `kit.log_faults(...)`, `kit.log_cycle_summary(...)`).
-Using them is optional but saves boilerplate.
-
-### Registering the template
-
-Templates need no central registration. `resolve_builder()` in
-[`schema.py`](schema.py) dynamically imports
-`base_station.experiment.templates.<name>.build` — dropping a new
-`templates/<name>.py` (with a matching `experiments/<name>.json`) is enough. If
-you want it importable as `from .templates import my_template`, add one line to
-[`templates/__init__.py`](templates/__init__.py):
-
-```python
-from .my_template import build as my_template
-```
-
-### The JSON parameter file
-
-```json
-{
-  "name": "my_template",
-  "label": "My Template",
-  "template": "my_template",
-  "description": "One-line summary shown in the GUI.",
-  "parameters": [
-    { "key": "interval_s", "label": "Interval (s)", "type": "float",
-      "default": 10.0, "min": 0, "max": 3600, "help": "..." }
-  ]
-}
-```
-
-- `template` must match the module name under `templates/`.
-- Each parameter's `key` becomes a keyword argument to `build(...)`.
-- Convention: `max_pellets` and duration-in-`minutes` of `0` mean "no limit".
-
-Every parameter value passes through `coerce_param_value` before reaching
-`build(...)`, so you receive it already typed. **The GUI form is generated
-entirely from this JSON — you never write per-parameter UI code.**
-
-### Parameter types
-
-| `type` | Widget | Value passed to `build(...)` |
-|--------|--------|------------------------------|
-| `int` / `float` | number input (honors `min`/`max`) | `int` / `float` |
-| `bool` | checkbox | `bool` |
-| `str` | text input | `str` |
-| `choice` | dropdown (needs `"options": [...]`) | `str` (one of the options) |
-| `nodes` | one checkbox per node + **All/None** | *(drives the `nodes=` argument, below)* |
-| `node_number` | one number input per node (honors `min`/`max`) | `dict {node_id: number}` — `0` = node inactive |
-| `node_choice` | one dropdown per node (needs `"options"`) | `dict {node_id: str}` — **first option = inactive** |
-
-The three node types render **one control per node** automatically — that is how
-`fixed_and_random` (a role dropdown per node) and `probability_delivery` (a %
-per node) are built, with **no template-specific GUI code**.
-
-**Active nodes / the `nodes=` argument.** `build(nodes=...)` always receives the
-active node set, derived in this order: a `nodes`-type param's checked list →
-else a `node_number` param's keys with value > 0 → else a `node_choice` param's
-keys whose value ≠ the first (inactive) option → else all nodes. So per-node
-assignment *is* the active/inactive selection — a separate "active nodes" row is
-only needed for templates that have no per-node param (like `free_feeding`,
-which declares a `nodes` param).
-
-### Conditional display — `visible_when`
-
-Any param may declare `"visible_when": {"<other_key>": <value | [values]>}`; it
-is shown (and collected) only when the controlling param currently equals one of
-the values. Hidden params fall back to their JSON `default`. Example — show the
-delay only for `fixed_delay`, the settle time only for `presence_clear`, the
-channel only for BNC:
-
-```json
-{ "key": "next_trial_wait", "type": "choice",
-  "options": ["fixed_delay", "presence_clear", "bnc"], "default": "fixed_delay" },
-{ "key": "fixed_delay_s", "type": "float", "default": 10.0,
-  "visible_when": {"next_trial_wait": "fixed_delay"} },
-{ "key": "iti_quiet_s", "type": "float", "default": 1.0,
-  "visible_when": {"next_trial_wait": "presence_clear"} },
-{ "key": "bnc_channel", "type": "int", "default": 0, "min": 0, "max": 1,
-  "visible_when": {"next_trial_wait": "bnc"} }
-```
-
-A per-node role dropdown looks like:
-
-```json
-{ "key": "node_roles", "label": "Node role", "type": "node_choice",
-  "options": ["off", "fixed", "random"], "default": "random" }
-```
-
-Your `build(node_roles=...)` then receives `{1: "fixed", 2: "off", 3: "random"}`.
-While running, the whole form (template selector + every param) is **locked**;
-it re-enables on Stop or when the run ends on its own.
-
-BNC channels are **0-based**: `0` = first BNC input (IN1), `1` = second (IN2).
-
----
-
-## 2. Two styles: loop-based vs event-based
-
-Both use the **same** callback API — the difference is only what drives the
-actions. A third style, sequential scripts, is covered in §5 — reach for it when
-a task is naturally a series of trials rather than an open-loop reaction to
-events.
-
-### Loop-based (timer-driven)
-
-Cycles are paced by timers on the runner clock. `free_feeding` is the canonical
-example: dispense on start, then re-dispense a node some delay after it takes
-the pellet.
-
-```python
-@exp.on_start
-def _start(control):
-    for n in control.nodes:
-        control.dispense(n)
-
-@exp.on_pellet_taken
-def _reload(control, event):
-    # Node-scoped timer: cancelled automatically if this node faults.
-    control.after(2.0, lambda: control.dispense(event.node_id), node=event.node_id)
-```
-
-### Event-based (reacts to events)
-
-Actions fire off events — a BNC pulse, a pellet loaded, a dome closing, etc.
-
-```python
-@exp.on_bnc_in
-def _on_pulse(control, event):
-    if event.data.get("edge") == "rising":
-        control.dispense(control.nodes[0])   # dispense on every BNC rising edge
-```
-
-You can freely mix both in one template (e.g. a timer heartbeat plus BNC
-overrides).
-
----
-
-## 3. The `control` object (`ExperimentControl`)
-
-`control` is passed as the first argument to every callback and to your
-`@exp.script` generator. It is your entire action surface — see
-[`context.py`](context.py).
-
-### Actions
-
-| Call | Effect |
-|------|--------|
-| `control.dispense(node)` | Dispense on one node. **No-op while that node is halted, mid-cycle from a previous dispense, or already has a pellet on the plate** (all three logged — see below). |
-| `control.dispense(node, feed=False)` | Run the identical dispense motion with **no pellet**: lower, hold at the drop position, then raise an empty plate. The raise fires when this node hears another node's `Raising` event on the bus, so both plates reach the top together no matter how long the fed node's load took — there is no dwell to set. Use it so an inactive arm still moves/sounds the same as a fed one (e.g. a bandit task where the animal shouldn't be able to tell arms apart by sound). Same vetoes apply. With no fed node in the trial, the mimic has nothing to follow and holds until `recover()`. |
-| `control.recover(node)` | Send Recover to one node (stop motion + clear its fault). |
-| `control.broadcast_dispense()` / `control.broadcast_recover()` | Same, to all nodes. If any node isn't clear (occupied plate or a cycle in flight), `broadcast_dispense()` can't withhold the command from just that one node in a single CAN frame, so it falls back to individual `dispense(n)` calls (each carrying its own vetoes) and returns `False`. |
-| `control.bnc_pulse(duration_us=100)` | Pulse the BNC OUT line. |
-| `control.set_heartbeat_interval(node, ms)` | Reconfigure a node's heartbeat rate. |
-
-**Three standardized, top-priority vetoes (system-wide, every template, zero wiring needed).** `dispense()` is the single choke point every dispense in the codebase goes through — templates, scripts, the GUI — so these three checks apply everywhere automatically, in this order, before anything is transmitted:
-
-1. **Halted** (`is_halted(node)`) — a faulted node; logs `dispense_skipped_halted`.
-2. **Cycle in flight** (`is_dispensing(node)`) — a previous `dispense()`/`dispense(feed=False)` on this node hasn't resolved yet (no `LOADED`/`NO_FEED_PRESENTED`/`FEED_SKIPPED`/fault/offline event since it was sent). This is what stops a fast timer/BNC-triggered template from re-picking the *same* node while it's still mid-motion — the plate-occupied check below can't catch that window, since the pellet hasn't reached the plate yet. Logs `dispense_skipped_in_flight` (`warning=1`).
-3. **Pellet already on the plate** (`pellet_on_plate(node)`) — logs `dispense_skipped_pellet_present` (`warning=1`).
-
-All three return `False` with no command sent. Firmware's own occupancy guard (`DispenserService::dispense()`/`dispenseNoFeed()` — see `FeedSkipped`) remains a backstop for the small race between these client-side checks and the command reaching the bus, but the common case never reaches it. `control.pellet_clear(nodes=None)` / `control.is_dispensing(node)` let you gate your own wait on either signal — see `kit.next_trial_wait`'s `"presence_clear"` mode, which checks pellet state first, unconditionally, before presence.
-
-### Per-node fault handling (sticky)
-
-| Call | Effect |
-|------|--------|
-| `control.halt_node(node_id)` | Latch a node: cancel its timers, make its `dispense` a no-op. (The engine calls this automatically on a FAULT event — you rarely call it yourself.) |
-| `control.recover_node(node_id)` | Clear the halt and send Recover (clears the firmware fault). |
-| `control.is_halted(node_id)` → `bool` | Is this node latched? |
-| `control.halted_nodes` | Sorted list of halted node IDs. |
-
-### Timers (runner clock, not wall clock)
-
-| Call | Effect |
-|------|--------|
-| `control.after(seconds, cb, node=0)` | One-shot. Pass `node=` to tie it to a node so it is cancelled if that node faults. |
-| `control.every(seconds, cb, node=0)` | Repeating. |
-| `control.cancel_timer(timer)` / `control.cancel_node_timers(node_id)` / `control.cancel_all_timers()` | Cancel. |
-
-### Per-node sensor state (for `@exp.script` conditions, but usable anywhere)
-
-| Call | Effect |
-|------|--------|
-| `control.quiet_for(seconds, node=None)` → `bool` | No PG/dome/presence/pellet-taken/BNC activity on the given node(s) — or all session nodes if omitted — for `seconds`. Ignores heartbeats and the node's own dispense-phase events, so it reflects the *animal*, not our own commands. |
-| `control.domes_closed(nodes=None)` → `bool` | All the given (or all session) domes currently closed. |
-| `control.dome_open(node)` / `control.pellet_on_plate(node)` / `control.is_online(node)` → `bool` | Current per-node sensor snapshot. |
-| `control.pellet_clear(nodes=None)` → `bool` | No pellet on the plate on every given (or all session) node. Mirrors `presence_clear()`/`domes_closed()` — this is what `dispense()`'s own veto checks. |
-| `control.is_dispensing(node)` → `bool` | True from the moment `dispense(node)` sends a command until that cycle resolves. This is what `dispense()`'s "cycle already in flight" veto checks — see above. |
-| `control.presence(node)` → `bool` / `control.presence_clear(nodes=None)` → `bool` | Animal on the capacitive presence pad; clear on every given (or all session) node. Defaults `False`/clear until the first reading arrives for a node — gate on `is_online(node)` first if you need to tell "confirmed clear" from "not yet known". |
-| `control.presented_pellet(node)` / `control.presented_empty(node)` → `bool` | What the last **completed** dispense cycle on this node raised — a real pellet, or an empty plate from `dispense(node, feed=False)`. At most one is ever `True`. |
-| `control.presentation(node)` → `str` | `'pellet'` \| `'empty'` \| `'none'` (`'none'` while a cycle is in flight). |
-| `control.presentation_done(node)` → `bool` | `True` once the cycle has finished raising, either way. Stays `True` through the take — call `clear_presentation()` to reset it. `wait_until` this across several nodes to gate a response window on **all** of them being ready before acting on any (see `two_armed_bandit.py`). |
-| `control.clear_presentation(node)` | Reset a node's presentation state — call at the start of a new trial so a stale reading can't be mistaken for this trial's result. |
-
-### Counters, trials, RNG, time, logging, stop
-
-| Call | Effect |
-|------|--------|
-| `control.counter(name)` / `control.incr(name, amount=1)` / `control.set_counter(name, v)` | Named integer counters. |
-| `control.next_trial()` → `int` | Advance and return the trial counter (also mirrored in `counter("trials")`, logged as a `trial` row). For sequential trial-based tasks. |
-| `control.trial` | Current trial number (0 before the first `next_trial()`). |
-| `control.chance(p)` / `control.pick(seq)` / `control.shuffled(seq)` | Session-seeded RNG helpers. See `control.seed` — generated and logged in `session_start` if you didn't supply one, so any run can be replayed. |
-| `control.elapsed()` | Seconds since the session became active. |
-| `control.log(name, node=0, **fields)` | Write an experiment log row (to the GUI log + CSV). |
-| `control.stop(reason="...")` | End the whole session as soon as possible (cancels all timers). |
-| `control.nodes` | The node IDs this session runs on. |
-
-The engine auto-increments the `"pellets"` counter on every **`LOADED`**
-event (a fully delivered pellet) — a no-feed cycle's `NO_FEED_PRESENTED` does
-**not** increment it, so `end_after(pellets=...)` only counts real deliveries.
-For a per-node tally, keep your own counter:
-
-```python
-@exp.on_loaded
-def _p(control, event):
-    control.incr(f"pellets_{event.node_id}")
-```
-
----
-
-## 4. Events you can handle
-
-Register with `@exp.on(EventKind.X)` or the sugar decorators. Handlers receive
-`(control, event)` where `event` is a `NodeEvent(kind, node_id, timestamp, data)`.
-
-| Sugar decorator | EventKind | `event.data` notes |
-|-----------------|-----------|-----------------|
-| `@exp.on_start` / `@exp.on_end` | `SESSION_START` / `SESSION_END` | `(control)` only — no `event`. |
-| `@exp.on_on_plate` | `ON_PLATE` | `session_pellets`, `session_taken` |
-| `@exp.on_loaded` | `LOADED` | `session_pellets`, `session_taken` |
-| `@exp.on_pellet_taken` | `PELLET_TAKEN` | `session_taken`, `session_pellets`, `dome_open` |
-| `@exp.on_feed_skipped` | `FEED_SKIPPED` | plate already occupied when dispensed |
-| `@exp.on_no_feed_presented` | `NO_FEED_PRESENTED` | a no-feed dispense finished raising an empty plate |
-| `@exp.on_dome_opened` / `@exp.on_dome_closed` | `DOME_OPENED` / `DOME_CLOSED` | derived from the dome sensor |
-| `@exp.on_fault` | `FAULT` | `fault_code` (`FeedTimeout` / `ActuatorTimeout` / `Jam` / `PelletLost`) |
-| `@exp.on_recover` | `NODE_RECOVERED` | fired when an operator recovers a node |
-| `@exp.on_bnc_in` | `BNC_IN` | `channel` (0/1), `edge` ("rising"/"falling"), `high` |
-| `@exp.on_presence_changed` | `PRESENCE_CHANGED` | |
-
-Other kinds available via `@exp.on(...)`: `LOWERING`, `LOADING`, `DWELLING`,
-`RAISING`, `DOME_OPEN_WARNING`, `PG_CHANGED`, `HEARTBEAT`, `NODE_ONLINE`,
-`NODE_OFFLINE`. See [`events.py`](events.py) for the full list.
-
-### Pellet counts are session-scoped
-
-`session_pellets` and `session_taken` are the base station's own per-node
-counters. They start at zero when a run opens, so the first pellet of a run is
-always number 1 no matter how long the node has been powered.
-
-They are not simply "events I received". Node firmware counts pellets from
-power-on (`pelletCount_` / `takenCount_`) and puts that number on every
-milestone frame and heartbeat. The base station folds in the **delta** of that
-counter, so a `Loaded` frame lost to the bus is recovered by the next frame
-that carries the count — the following `DomeOpened`, `PelletTaken`, or just the
-next heartbeat — and the run total stays right. Gaps are written to the log as
-`Pellet Count Gap` rows so a correction is visible during analysis instead of
-silently smoothing over lost data. See
-[`pellet_ledger.py`](../pellet_ledger.py).
-
-The node's raw counter is still in the log, as `node_pellets` / `node_taken` in
-`fields_json`. Treat it as a diagnostic, never as the pellet number.
-
-### Start / end conditions
-
-```python
-exp.start_when(lambda control: control.counter("armed") > 0)   # defer SESSION_START
-exp.end_when(lambda control: control.elapsed() > 600)          # custom end
-exp.end_after(hours=0, minutes=30, seconds=0, pellets=100)     # duration and/or cap
-```
-
----
-
-## 5. Sequential tasks — `@exp.script`
-
-Some tasks are naturally a series of trials: do something, wait for a specific
-outcome, wait again, repeat — a two-armed bandit is the canonical example. That
-reads far more clearly as one generator than as a handful of `@exp.on_*`
-handlers threading state through a dict. `@exp.script` runs *alongside* the
-callback API (both may be used on the same `Experiment`) — there is exactly one
-script per experiment.
-
-```python
-@exp.script
-def run(control):
-    while True:
-        trial = control.next_trial()
-        control.dispense(fed_node)
-        control.dispense(other_node, feed=False)   # motion, no pellet
-
-        result = yield control.wait_for("pellet_taken", node=fed_node, timeout=30.0)
-        if result.faulted:
-            yield control.wait(5.0)
-            continue
-
-        yield control.wait_until(
-            lambda c: c.domes_closed() and c.quiet_for(5.0),
-            timeout=30.0,
-            label="iti_quiet",
-        )
-```
-
-### The three things you can `yield`
-
-- **`control.wait_for(kind, node=None, timeout=None)`** — wait for the next
-  matching event. `kind` is an event name (`"pellet_taken"`, case-insensitive)
-  or an `EventKind`. `node` restricts to one id or a list; omit for any node.
-- **`control.wait_until(predicate, timeout=None, node=None, label=None)`** — wait until
-  `predicate(control)` returns True (checked every tick). Pass `node=` only if
-  this wait should also abort when that node faults. Pass `label=` so
-  `script_stalled` / `script_timeout` name the wait (`"plates_clear"`) instead
-  of logging an unlabeled lambda as `condition`.
-- **`control.wait(seconds)`** — wait a fixed duration on the runner clock.
-
-Each `yield` returns the same object, with fields filled in once it resolves:
-`.ok` (`bool` — succeeded cleanly), `.timed_out`, `.faulted` / `.faulted_node`,
-and `.event` (the `NodeEvent` that satisfied a `wait_for`, if any). Ignoring the
-return value is the common case and costs nothing.
-
-### What "wait" actually means
-
-- Two lines like `control.dispense(fed)` then `yield control.wait_for(...)` can
-  never race — the engine is single-threaded, so no reply can arrive before the
-  next tick regardless of how the two lines are written.
-- `@exp.on_*` handlers for an event always run **before** any script code that
-  same event unblocks (they fire earlier in the same dispatch batch).
-- **Faults never raise inside your script.** If the node a pending `wait_for`
-  is scoped to faults, the wait resolves with `.faulted=True` instead of
-  hanging or throwing — the script decides what to do (usually: log it, wait a
-  bit, and move to the next trial). This matches the callback engine's own
-  behavior: a fault halts only that node; the rest of the session keeps going.
-- A generator that **returns** ends the session (`stop(reason="script_finished")`
-  — when your `run()` function is done, the experiment is done). A generator
-  that **raises** also ends the session, with the error and your code's own
-  file/line logged as `script_error` — unlike `@exp.on_*` handlers, whose
-  errors are isolated so one broken handler can't take down the rest.
-- **Every loop must yield.** `while True:` with no `yield` inside is an
-  uninterruptible Python loop and will hang the whole engine — there is no
-  runtime protection against this, only against loops that yield awaits which
-  keep resolving immediately (bounded to 64 resumes per tick).
-
-See [`script.py`](script.py) for the full scheduler and
-[`templates/two_armed_bandit.py`](templates/two_armed_bandit.py) for a complete
-worked example.
-
----
-
-## 6. Faults are sticky, per node
-
-When a node reports a **jam or timeout**:
-
-1. The firmware halts that node's motors and refuses further dispenses until a
-   Recover — it is already sticky at the hardware level.
-2. The engine calls `control.halt_node(node_id)`: cancels that node's timers and
-   makes its `control.dispense(...)` a no-op. **The other nodes keep running.**
-3. The node stays latched until an operator presses **Recover** on its tile (or a
-   BNC IN action / `runner.recover_node`). Recovery sends Recover (clears the fault)
-   and fires your `@exp.on_recover` handler so you can re-arm the node.
-
-This means your template usually needs **no fault bookkeeping** — keep calling
-`control.dispense(n)` for every node and halted ones simply stop receiving
-pellets. Use `@exp.on_recover` to resume a node's cycle (or `kit.log_faults(exp)`
-for the common log-only case):
-
-```python
-@exp.on_fault
-def _fault(control, event):
-    control.log("fault", node=event.node_id, fault_code=event.data.get("fault_code"))
-
-@exp.on_recover
-def _recovered(control, event):
-    control.dispense(event.node_id)   # resume this node
-```
-
----
-
-## 7. BNC sync I/O
-
-BNC is a base-station feature (Raspberry Pi GPIO); nodes are not involved.
-
-**BNC IN** — the GUI dispatches an action per **edge** (rising / falling), each
-independently optional. Configure it in the BNC panel (e.g. rising →
-`start_experiment`, falling → `stop_experiment`). Inside a running experiment you
-also get every edge as a `BNC_IN` event, so a template can react directly:
-
-```python
-@exp.on_bnc_in
-def _edge(control, event):
-    if event.data["edge"] == "rising" and event.data["channel"] == 0:
-        control.dispense(control.nodes[0])
-```
-
-**BNC OUT** — set the BNC OUT **Trigger** in the GUI to a CAN event name (e.g.
-`Loaded`) and it pulses whenever that event arrives from any node, during
-manual use *and* during an experiment. To pulse from template code directly, call
-`control.bnc_pulse(width_us)` (e.g. on each dispense).
-
----
-
-## 8. Node selection
-
-The Experiment panel has per-node checkboxes plus **All / None**. The checked set
-is passed to `build(nodes=...)`, so `control.nodes` is exactly the subset the
-operator chose. Always iterate `control.nodes`; never assume `[1, 2, 3]`.
-
----
-
-## 9. Worked examples in this repo
-
-- **[`templates/free_feeding.py`](templates/free_feeding.py)** — loop-based:
-  continuous reload after each pellet is taken, using the shared advance
-  (`next_trial_wait`: `fixed_delay` default 30 s, or `presence_clear`);
-  per-node sticky fault + recover. (`reload_delay_s=` is a headless alias
-  of `fixed_delay_s`.)
-- **[`templates/fixed_and_random.py`](templates/fixed_and_random.py)** — each
-  node has a **role** (`off` / `fixed` / `random`) from a `node_choice` param.
-  `fixed` nodes dispense every cycle, `random` nodes dispense with `random_prob`,
-  `off` nodes are inactive. `build(node_roles={1:"fixed", 2:"off", ...})`.
-  Advance with the same `next_trial_wait` as two-armed bandit (`fixed_delay` /
-  `presence_clear`), plus `bnc` for an external rising edge. (A legacy
-  `fixed_nodes` string and `trigger="timer"` / `interval_s=` are still
-  accepted for headless runs.)
-- **[`templates/probability_delivery.py`](templates/probability_delivery.py)** —
-  each cycle delivers on **one** node, chosen by an independent **weighted
-  random draw** (`random.choices`) — e.g. weights `20,80` mean node 1 has a 20%
-  chance and node 2 an 80% chance *on every single cycle*; it is not a fixed
-  20-of-100 allocation or round-robin, and over many cycles the observed split
-  converges to the configured weights. `0` means that node is never picked.
-  A `node_number` param supplies the per-node weights as `{node_id: pct}`
-  (a comma-separated string is accepted for headless runs). Same shared
-  `next_trial_wait` as `fixed_and_random`.
-- **[`templates/two_armed_bandit.py`](templates/two_armed_bandit.py)** —
-  `@exp.script`-based: exactly two nodes (the arms). Each trial, both arms run
-  the dispense motion (`control.dispense(fed)` / `control.dispense(empty,
-  feed=False)`), but only one delivers, chosen by a reward probability that
-  flips which arm is "rich" every `block_size` trials. Sweeps both plates
-  clear before trial 1, gates the response window on **both** arms finishing
-  their raise (`presentation_done`) so neither one tips off the animal by
-  finishing first, then waits — with no timeout — for the pellet to be taken.
-  Advances to the next trial either after a fixed delay or once the animal is
-  off both presence pads (`next_trial_wait`). If a no-feed arm's plate turns
-  out already occupied (firmware presents the leftover pellet honestly rather
-  than discarding it), the trial is logged invalid and the session keeps
-  running — see the module docstring for the full mutual-exclusion and sync
-  analysis. A good reference for writing your own trial-based `@exp.script`
-  template: see `control.presented_pellet`/`presented_empty`/`presentation_done`/
-  `clear_presentation`/`presence`/`presence_clear` in [`context.py`](context.py)
-  and `kit.next_trial_wait` in [`kit.py`](kit.py).
-
-Both `fixed_and_random` and `probability_delivery` accept `seed=` for
-reproducible runs (used by the tests); `two_armed_bandit` does too, and also
-logs whatever seed it used (generated if you didn't supply one) so any session
-can be replayed. Because all three use the declarative node param types above,
-none needs any per-template GUI code — the form (per-node dropdowns / % inputs,
-plus the advance-gated delay / settle / BNC fields) is generated entirely from their
-JSON.
-
----
-
-## 10. Testing your template
-
-Run headless against synthetic events — no CAN hardware needed:
-
-```python
-from base_station.experiment import EventKind, NodeEvent
-from base_station.experiment.templates.my_template import build
-
-exp = build(nodes=[1, 2], interval_s=5.0, seconds=60)
-runner = exp.make_runner()          # no CAN/IO bound → dry-run
-runner.start(now=0.0)
-runner.step(now=5.0)                 # advance the clock; timers fire
-
-# Inject events:
-runner.inject(NodeEvent(EventKind.FAULT, node_id=1, timestamp=6.0,
-                        data={"fault_code": 1}))
-
-# Inspect what was sent:
-print(runner.ctx.commands_sent)      # list of (node_id, CanCmd, payload)
-```
-
-`runner.ctx.commands_sent` records every command in dry-run mode, and
-`runner.ctx.is_halted(...)`, `runner.ctx.counter(...)`, and the log entries let you
-assert behavior. `runner.ctx` and `runner.control` are the same object — use
-whichever reads better. See
-[`../../tests/test_experiment.py`](../../tests/test_experiment.py) and
-[`../../tests/test_script.py`](../../tests/test_script.py) for patterns,
-including how to drive a `@exp.script` template through `inject()`/`step()`.
-
----
-
-## 11. Running headless (no GUI)
-
-The GUI is one host for the engine; you don't need it. There are two ways to run
-an experiment against a live SocketCAN interface (`can0`, or `vcan0` with the node
-simulator) — both go through `Experiment.run()` and write the same per-session CSV.
-
-**A. A plain Python script** — configure a template (or write behavior inline)
-and call `exp.run(...)`, which blocks until the session ends (duration / pellet
-cap / Ctrl+C):
-
-```python
-from base_station.experiment.templates.free_feeding import build
-
-exp = build(nodes=[1, 2, 3], reload_delay_s=30, minutes=10)
-exp.run(interface="vcan0", log_dir="~/sfm_logs", use_io=False)  # use_io=False off-Pi
-```
-
-This is all a custom experiment needs: your own module with a
-`build(nodes=None, *, ...) -> Experiment` factory (or just an `exp = Experiment(...)`),
-then `exp.run(...)`. See [`../../example_experiment.py`](../../example_experiment.py)
-for a runnable version (including an inline-callbacks variant with no template file).
-
-**B. The `run_experiment.py` CLI** — run a built-in template using its JSON values
-(the same schema the GUI form uses), a `.json` schema file, or **your own `.py`
-script**, with optional overrides:
-
-```bash
-# from tools/dev_gui/
-python run_experiment.py --list                                  # discover templates + params
-python run_experiment.py free_feeding -i vcan0 --minutes 10
-python run_experiment.py probability_delivery --set probabilities=1:20,2:80
-python run_experiment.py fixed_and_random --set node_roles=1:fixed,2:off,3:random
-python run_experiment.py two_armed_bandit --set block_size=50,p_high=0.9
-python run_experiment.py path/to/my_task.py --nodes 1,2,4        # your own template/script
-python run_experiment.py free_feeding --dry-run                  # build only, no CAN
-```
-
-`--set key=value` accepts a scalar (`minutes=10`), a list (`x=1,2,3`), or a
-**per-node map** (`x=1:fixed,2:off`) — the map/list forms feed the `node_choice` /
-`node_number` / `nodes` params exactly as the GUI's per-node widgets do. The CLI
-stops on the duration / pellet cap you configure (or Ctrl+C).
diff --git a/tools/dev_gui/example_experiment.py b/tools/dev_gui/example_experiment.py
deleted file mode 100644
index 78222e9..0000000
--- a/tools/dev_gui/example_experiment.py
+++ /dev/null
@@ -1,53 +0,0 @@
-#!/usr/bin/env python3
-"""
-example_experiment.py — the simplest way to run an experiment headless.
-
-Two equally valid styles are shown:
-
-  A) Configure a built-in template and run it.
-  B) Write the behavior inline with the same callback API the templates use.
-
-Run it:   python example_experiment.py         (uses vcan0 by default below)
-Stop it:  Ctrl+C   (or it ends on the duration / pellet cap you set)
-
-For a CLI that reads the JSON schema and takes --set overrides instead, use:
-    python run_experiment.py free_feeding --interface vcan0 --minutes 10
-    python run_experiment.py --list
-"""
-
-from base_station.experiment import Experiment
-from base_station.experiment.templates.free_feeding import build as build_free_feeding
-
-INTERFACE = "vcan0"   # SocketCAN interface the nodes (or node_simulator) are on
-
-
-def run_builtin_template() -> None:
-    """A) Take a built-in template, set parameters, run blocking."""
-    exp = build_free_feeding(nodes=[1, 2, 3], reload_delay_s=30, minutes=10)
-    exp.run(interface=INTERFACE, log_dir="~/sfm_logs", use_io=False)
-
-
-def run_custom_inline() -> None:
-    """B) Define behavior inline — no template file needed."""
-    exp = Experiment(nodes=[1, 2, 3], name="my_task")
-
-    @exp.on_start
-    def _start(control):
-        for n in control.nodes:
-            control.dispense(n)
-
-    @exp.on_pellet_taken
-    def _reload(control, event):
-        control.after(30.0, lambda: control.dispense(event.node_id), node=event.node_id)
-
-    @exp.on_recover
-    def _recover(control, event):
-        control.dispense(event.node_id)
-
-    exp.end_after(minutes=10)
-    exp.run(interface=INTERFACE, use_io=False)
-
-
-if __name__ == "__main__":
-    run_builtin_template()
-    # run_custom_inline()
diff --git a/tools/dev_gui/run_experiment.py b/tools/dev_gui/run_experiment.py
deleted file mode 100644
index 3532c3b..0000000
--- a/tools/dev_gui/run_experiment.py
+++ /dev/null
@@ -1,281 +0,0 @@
-#!/usr/bin/env python3
-"""
-run_experiment.py — run an SFM experiment headless (no GUI).
-
-Point it at a built-in template name, a ``.json`` schema, or your own ``.py``
-script, and it runs blocking against a SocketCAN interface until the session
-ends (duration / pellet cap / Ctrl+C).
-
-Examples::
-
-    # Built-in template using its experiments/<name>.json values, on vcan0:
-    python run_experiment.py free_feeding --interface vcan0 --minutes 10
-
-    # Override params (scalar / list / per-node map):
-    python run_experiment.py probability_delivery --set probabilities=1:20,2:80
-    python run_experiment.py fixed_and_random --set node_roles=1:fixed,2:off,3:random
-
-    # Your own script exposing `exp` or `build(**kwargs) -> Experiment`:
-    python run_experiment.py path/to/my_task.py --nodes 1,2,4
-
-    # Discover what's available, or build without hardware:
-    python run_experiment.py --list
-    python run_experiment.py free_feeding --dry-run
-"""
-
-from __future__ import annotations
-
-import argparse
-import importlib.util
-import sys
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence
-
-# Ensure the package is importable when run as a script from tools/dev_gui/.
-_HERE = Path(__file__).resolve().parent
-if str(_HERE) not in sys.path:
-    sys.path.insert(0, str(_HERE))
-
-from base_station.experiment import Experiment, build_experiment  # noqa: E402
-from base_station.experiment.schema import (  # noqa: E402
-    DEFAULT_EXPERIMENTS_DIR,
-    ExperimentDef,
-    load_experiment_def,
-    load_experiment_defs,
-    resolve_builder,
-)
-
-
-# ---------------------------------------------------------------------------
-# --set key=value parsing
-# ---------------------------------------------------------------------------
-
-def _coerce_scalar(text: str) -> Any:
-    """Best-effort scalar coercion: bool → int → float → str."""
-    t = text.strip()
-    low = t.lower()
-    if low in ("true", "false"):
-        return low == "true"
-    try:
-        return int(t)
-    except ValueError:
-        pass
-    try:
-        return float(t)
-    except ValueError:
-        pass
-    return t
-
-
-def parse_set_value(raw: str) -> Any:
-    """
-    Parse a --set value into a scalar, list, or per-node dict.
-
-    Forms:
-      * ``30`` / ``1.5`` / ``true`` / ``text`` → scalar
-      * ``1,2,3``                              → list ([1, 2, 3])
-      * ``1:fixed,2:off,3:random``             → dict ({1: "fixed", ...})
-    Per-node dicts feed node_number / node_choice params; lists feed a nodes
-    param; scalars feed everything else. build_experiment coerces per the
-    schema type, so these forms map onto the GUI's per-node widgets.
-    """
-    raw = raw.strip()
-    if not raw:
-        return ""
-    parts = [p.strip() for p in raw.split(",") if p.strip() != ""]
-    if parts and all(":" in p for p in parts):
-        result: Dict[Any, Any] = {}
-        for p in parts:
-            k, _, v = p.partition(":")
-            result[_coerce_scalar(k)] = _coerce_scalar(v)
-        return result
-    if len(parts) > 1:
-        return [_coerce_scalar(p) for p in parts]
-    return _coerce_scalar(raw)
-
-
-def parse_overrides(pairs: Optional[Sequence[str]]) -> Dict[str, Any]:
-    """Turn ``["k=v", ...]`` into ``{k: parsed_v}``."""
-    out: Dict[str, Any] = {}
-    for pair in pairs or []:
-        if "=" not in pair:
-            raise SystemExit(f"--set expects key=value, got: {pair!r}")
-        key, _, value = pair.partition("=")
-        out[key.strip()] = parse_set_value(value)
-    return out
-
-
-# ---------------------------------------------------------------------------
-# Target resolution → Experiment
-# ---------------------------------------------------------------------------
-
-def available_defs() -> List[ExperimentDef]:
-    """All JSON experiment definitions shipped under experiments/."""
-    return load_experiment_defs(DEFAULT_EXPERIMENTS_DIR)
-
-
-def _def_for_name(name: str) -> Optional[ExperimentDef]:
-    for d in available_defs():
-        if d.name == name:
-            return d
-    return None
-
-
-def _load_script(path: Path):
-    spec = importlib.util.spec_from_file_location(path.stem, path)
-    if spec is None or spec.loader is None:
-        raise SystemExit(f"Cannot load script: {path}")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def _warn_unknown_keys(exp_def: ExperimentDef, overrides: Dict[str, Any]) -> None:
-    known = {p.key for p in exp_def.parameters}
-    for key in overrides:
-        if key not in known:
-            print(f"warning: --set {key}=... is not a parameter of "
-                  f"'{exp_def.name}' (ignored). Known: {sorted(known)}")
-
-
-def build_from_target(
-    target: str,
-    overrides: Optional[Dict[str, Any]] = None,
-    nodes: Optional[Sequence[int]] = None,
-) -> Experiment:
-    """
-    Resolve ``target`` into a configured Experiment.
-
-    Resolution order:
-      1. a ``.json`` schema path                → build_experiment(def)
-      2. a built-in template name with a JSON    → build_experiment(def)   [uses .json values]
-      3. a ``.py`` script exposing ``exp``/``build``
-      4. a template module name without a JSON   → resolve_builder(name)(**overrides)  [build() defaults]
-    """
-    overrides = dict(overrides or {})
-    path = Path(target)
-
-    # 1) explicit JSON schema file
-    if path.suffix == ".json" and path.exists():
-        return build_experiment(load_experiment_def(path), overrides, nodes)
-
-    # 2) template name with a matching JSON schema
-    exp_def = _def_for_name(target)
-    if exp_def is not None:
-        _warn_unknown_keys(exp_def, overrides)
-        return build_experiment(exp_def, overrides, nodes)
-
-    # 3) a user .py script
-    if path.suffix == ".py" and path.exists():
-        module = _load_script(path)
-        if isinstance(getattr(module, "exp", None), Experiment):
-            return module.exp
-        if callable(getattr(module, "build", None)):
-            kwargs = dict(overrides)
-            if nodes is not None:
-                kwargs["nodes"] = list(nodes)
-            return module.build(**kwargs)
-        raise SystemExit(
-            f"{path} must define `exp = Experiment(...)` or `def build(...) -> Experiment`"
-        )
-
-    # 4) a template module name without a JSON schema
-    try:
-        builder = resolve_builder(target)
-    except ImportError as exc:
-        names = ", ".join(d.name for d in available_defs()) or "(none)"
-        raise SystemExit(
-            f"Unknown target {target!r}. Templates with JSON: {names}. "
-            f"Or pass a .py / .json path."
-        ) from exc
-    kwargs = dict(overrides)
-    if nodes is not None:
-        kwargs["nodes"] = list(nodes)
-    return builder(**kwargs)
-
-
-# ---------------------------------------------------------------------------
-# CLI
-# ---------------------------------------------------------------------------
-
-def _print_list() -> None:
-    defs = available_defs()
-    if not defs:
-        print("No experiment JSON files found in", DEFAULT_EXPERIMENTS_DIR)
-        return
-    print("Available templates (name — parameters):")
-    for d in defs:
-        params = ", ".join(f"{p.key}:{p.type}" for p in d.parameters)
-        print(f"  {d.name:22s} {d.description}")
-        if params:
-            print(f"  {'':22s} params: {params}")
-
-
-def main(argv: Optional[List[str]] = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="run_experiment.py",
-        description="Run an SFM experiment headless (JSON template, or a .py script).",
-    )
-    parser.add_argument("target", nargs="?",
-                        help="Template name, or path to a .json schema / .py script")
-    parser.add_argument("--interface", "-i", default="can0",
-                        help="SocketCAN interface (default: can0)")
-    parser.add_argument("--bitrate", "-b", type=int, default=250_000)
-    parser.add_argument("--nodes", default=None,
-                        help="Comma-separated node IDs (default: template's own)")
-    parser.add_argument("--set", dest="sets", action="append", metavar="KEY=VALUE",
-                        help="Override a parameter (repeatable). "
-                             "Value may be scalar, 'a,b' list, or '1:x,2:y' per-node map.")
-    # Common conveniences (equivalent to --set):
-    parser.add_argument("--minutes", type=float, default=None)
-    parser.add_argument("--seconds", type=float, default=None)
-    parser.add_argument("--hours", type=float, default=None)
-    parser.add_argument("--max-pellets", type=int, default=None, dest="max_pellets")
-    parser.add_argument("--log-dir", default="~/sfm_logs")
-    parser.add_argument("--no-io", action="store_true",
-                        help="Do not open GPIO/BNC (non-Pi hosts)")
-    parser.add_argument("--poll-hz", type=float, default=50.0)
-    parser.add_argument("--list", action="store_true", help="List templates and exit")
-    parser.add_argument("--dry-run", action="store_true",
-                        help="Build the experiment and print it, without opening CAN")
-    args = parser.parse_args(argv)
-
-    if args.list:
-        _print_list()
-        return 0
-    if not args.target:
-        parser.error("a target (template name / .json / .py) is required (or use --list)")
-
-    overrides = parse_overrides(args.sets)
-    for key in ("minutes", "seconds", "hours", "max_pellets"):
-        val = getattr(args, key)
-        if val is not None:
-            overrides.setdefault(key, val)
-
-    nodes = None
-    if args.nodes:
-        nodes = [int(x) for x in args.nodes.split(",") if x.strip()]
-
-    exp = build_from_target(args.target, overrides, nodes)
-
-    if args.dry_run:
-        print(f"[dry-run] built '{exp.name}' nodes={exp.nodes} "
-              f"handlers={sorted(k.name for k in exp._handlers)}")
-        return 0
-
-    print(f"Starting '{exp.name}' on {args.interface} nodes={exp.nodes}  (Ctrl+C to stop)")
-    control = exp.run(
-        interface=args.interface,
-        bitrate=args.bitrate,
-        log_dir=args.log_dir,
-        use_io=not args.no_io,
-        poll_hz=args.poll_hz,
-    )
-    print(f"Session ended. pellets={control.counter('pellets')} elapsed={control.elapsed():.1f}s")
-    if control.log_path:
-        print(f"Log: {control.log_path}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
diff --git a/tools/dev_gui/tests/test_run.py b/tools/dev_gui/tests/test_run.py
deleted file mode 100644
index f416ba9..0000000
--- a/tools/dev_gui/tests/test_run.py
+++ /dev/null
@@ -1,91 +0,0 @@
-"""Tests for the headless runner CLI (run_experiment.py)."""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-from run_experiment import (
-    build_from_target,
-    parse_overrides,
-    parse_set_value,
-)
-from base_station.experiment.schema import DEFAULT_EXPERIMENTS_DIR
-
-
-# ---------------------------------------------------------------------------
-# --set value parsing
-# ---------------------------------------------------------------------------
-
-def test_parse_set_value_scalars() -> None:
-    assert parse_set_value("30") == 30
-    assert parse_set_value("1.5") == 1.5
-    assert parse_set_value("true") is True
-    assert parse_set_value("false") is False
-    assert parse_set_value("timer") == "timer"
-
-
-def test_parse_set_value_list() -> None:
-    assert parse_set_value("1,2,3") == [1, 2, 3]
-
-
-def test_parse_set_value_per_node_map() -> None:
-    assert parse_set_value("1:20,2:80") == {1: 20, 2: 80}
-    assert parse_set_value("1:fixed,2:off,3:random") == {
-        1: "fixed", 2: "off", 3: "random",
-    }
-
-
-def test_parse_overrides() -> None:
-    out = parse_overrides(["minutes=10", "probabilities=1:20,2:80"])
-    assert out == {"minutes": 10, "probabilities": {1: 20, 2: 80}}
-
-
-# ---------------------------------------------------------------------------
-# target resolution → Experiment
-# ---------------------------------------------------------------------------
-
-def test_build_from_template_name_uses_json() -> None:
-    exp = build_from_target("free_feeding", overrides={"minutes": 5}, nodes=[1, 2])
-    assert exp.name == "free_feeding"
-    assert exp.nodes == [1, 2]
-    assert exp._end_after_s == 300.0  # minutes=5 flowed through the JSON schema
-
-
-def test_build_from_json_path() -> None:
-    path = str(DEFAULT_EXPERIMENTS_DIR / "fixed_and_random.json")
-    exp = build_from_target(path, overrides={"node_roles": {1: "fixed"}}, nodes=[1, 2, 3])
-    assert exp.name == "fixed_and_random"
-    assert exp.nodes == [1, 2, 3]
-
-
-def test_build_from_probability_with_node_map() -> None:
-    exp = build_from_target(
-        "probability_delivery",
-        overrides={"probabilities": {1: 0, 2: 100}, "max_pellets": 5},
-        nodes=[1, 2],
-    )
-    assert exp.name == "probability_delivery"
-    assert exp._end_pellets == 5
-
-
-def test_build_from_py_script(tmp_path) -> None:
-    script = tmp_path / "my_task.py"
-    script.write_text(
-        "from base_station.experiment import Experiment\n"
-        "def build(nodes=None, **kw):\n"
-        "    exp = Experiment(nodes=list(nodes or [1]), name='scripted')\n"
-        "    return exp\n"
-    )
-    exp = build_from_target(str(script), nodes=[4, 5])
-    assert exp.name == "scripted"
-    assert exp.nodes == [4, 5]
-
-
-def test_unknown_target_raises() -> None:
-    import pytest
-
-    with pytest.raises(SystemExit):
-        build_from_target("does_not_exist")

From 7c35693bc41d596ad58c0cd86fae0a3f449bb7fd Mon Sep 17 00:00:00 2001
From: Jemin Kachhadiya <jemin.b.kachhadiya@gmail.com>
Date: Wed, 26 Aug 2026 12:32:48 -0500
Subject: [PATCH 2/3] pypi hosting guide document

---
 README.md                          |   2 +
 packages/sfm-analysis/README.md    |   2 +-
 packages/sfm-analysis/docs/PYPI.md | 102 +++++++++++++++++++++++++++++
 3 files changed, 105 insertions(+), 1 deletion(-)
 create mode 100644 packages/sfm-analysis/docs/PYPI.md

diff --git a/README.md b/README.md
index 3afc8d1..ff5d48d 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@ The Arduino library is the `firmware/` folder (not the repo root). Copy or symli
 | [packages/dev_gui/base_station/experiment/README.md](packages/dev_gui/base_station/experiment/README.md) | How to author custom experiment templates (Python API + JSON params) |
 | [packages/sfm-analysis/README.md](packages/sfm-analysis/README.md) | Cross-platform session analysis and report generation — install, CLI, report design/section architecture, Python API |
 | [packages/sfm-analysis/docs/ANALYSIS_GUIDE.md](packages/sfm-analysis/docs/ANALYSIS_GUIDE.md) | Analysis reference: every log column, event name, derived metric field, and tidy-table column, plus a worked example |
+| [packages/sfm-analysis/docs/PYPI.md](packages/sfm-analysis/docs/PYPI.md) | Publishing `sfm-analysis` to PyPI (`pip install sfm-analysis`) |
 | [firmware/docs/WIRING.md](firmware/docs/WIRING.md) | Firmware pin names → physical jobs (motors, sensors, CAN, LEDs, discovery) |
 | [firmware/docs/DISPENSE_CYCLE.md](firmware/docs/DISPENSE_CYCLE.md) | How a node loads, raises, and reports pellet take / faults during a dispense |
 | [firmware/docs/HARDCODED_VALUES.md](firmware/docs/HARDCODED_VALUES.md) | Tunable firmware constants checklist (timings, speeds, thresholds) |
@@ -57,6 +58,7 @@ VFM/
 │   │   └── base_station/experiment/  # Engine + templates (see its README)
 │   └── sfm-analysis/         # Cross-platform session analysis / report SDK
 │       ├── docs/ANALYSIS_GUIDE.md
+│       ├── docs/PYPI.md      # To publish a new sfm-analysis version (Developer only)
 │       └── examples/         # Analysis recipes + a custom report-design starter
 └── README.md
 ```
diff --git a/packages/sfm-analysis/README.md b/packages/sfm-analysis/README.md
index 330affb..4fa35d5 100644
--- a/packages/sfm-analysis/README.md
+++ b/packages/sfm-analysis/README.md
@@ -18,7 +18,7 @@ analysis doesn't have to happen on the Pi. The base station's own
 pip install sfm-analysis
 ```
 
-Or, before the first PyPI release (or to track `main`):
+To track `main` instead of a released version:
 
 ```bash
 pip install "git+https://github.com/Neurotech-Hub/VFM.git#subdirectory=packages/sfm-analysis"
diff --git a/packages/sfm-analysis/docs/PYPI.md b/packages/sfm-analysis/docs/PYPI.md
new file mode 100644
index 0000000..265aa9c
--- /dev/null
+++ b/packages/sfm-analysis/docs/PYPI.md
@@ -0,0 +1,102 @@
+# Publishing `sfm-analysis` to PyPI
+
+How to ship a new version so `pip install sfm-analysis` picks it up.
+Uploads go to **[pypi.org](https://pypi.org)** — not TestPyPI.
+
+Package identity:
+
+
+|              |                                                                                       |
+| ------------ | ------------------------------------------------------------------------------------- |
+| PyPI name    | `sfm-analysis`                                                                        |
+| Import       | `sfm_analysis`                                                                        |
+| Source       | `packages/sfm-analysis/` in [Neurotech-Hub/VFM](https://github.com/Neurotech-Hub/VFM) |
+| Project page | [https://pypi.org/project/sfm-analysis/](https://pypi.org/project/sfm-analysis/)      |
+
+
+`.github/workflows/sdk.yml` tests and builds the wheel; it does **not**
+upload. Releases are cut from a laptop with Twine until trusted publishing
+is wired up.
+
+## 1. Bump the version
+
+PyPI versions are immutable — you cannot overwrite `0.1.0`. Change **both**:
+
+- `pyproject.toml` → `[project] version`
+- `src/sfm_analysis/__init__.py` → `__version__`
+
+Keep them identical. Then commit.
+
+## 2. Token
+
+1. Sign in at [pypi.org](https://pypi.org/) (not test.pypi.org).
+2. [Account → API tokens](https://pypi.org/manage/account/token/).
+3. **Add API token**.
+  - First upload of a new project: scope **Entire account**.
+  - Later releases: scope **Project: sfm-analysis**.
+4. Copy the value. It starts with `pypi-`. Shown once.
+
+If the Neurotech Hub organization should own the project, upload as a
+member of that org (or transfer ownership after the first release:
+project → Collaboration).
+
+## 3. Build and upload
+
+```bash
+cd packages/sfm-analysis
+python -m pip install --upgrade build twine
+rm -rf dist
+python -m build
+twine check dist/*
+twine upload dist/* \
+  --username __token__ \
+  --password 'pypi-PASTE_TOKEN_HERE'
+```
+
+- Username is exactly `__token__`.
+- Password is the full token in single quotes.
+- Do **not** pass `--repository testpypi`.
+- Ignore `This environment is not supported for trusted publishing` — that
+only applies to GitHub Actions, not a local Twine run.
+
+Success prints a URL like `https://pypi.org/project/sfm-analysis/0.1.1/`.
+
+## 4. Check the install
+
+In a **fresh** venv (not the one you built from):
+
+```bash
+python -m venv /tmp/sfm-check && source /tmp/sfm-check/bin/activate
+pip install --upgrade sfm-analysis
+python -c "import sfm_analysis; print(sfm_analysis.__version__)"
+sfm-report --list-designs
+```
+
+PyPI can take a minute to serve the new version. `pip install -U` if an
+older copy is cached.
+
+## 403 Forbidden
+
+Almost always the wrong token or the wrong site.
+
+
+| Cause                                          | Fix                                               |
+| ---------------------------------------------- | ------------------------------------------------- |
+| Token from **test.pypi.org**                   | Create a new token on **pypi.org**                |
+| Account password instead of token              | Username `__token__`, password `pypi-...`         |
+| Project-scoped token before the project exists | Entire-account token for the first upload         |
+| Name already owned by another PyPI user        | Collaboration / org transfer, or a different name |
+
+
+`twine upload dist/* --verbose` prints the real denial text.
+
+## Tracking `main` without PyPI
+
+```bash
+pip install "git+https://github.com/Neurotech-Hub/VFM.git#subdirectory=packages/sfm-analysis"
+```
+
+The base-station GUI keeps using the local editable install
+(`-e ../../packages/sfm-analysis` in `packages/dev_gui/requirements.txt`).
+Leave that for development on the Pi; only pin `sfm-analysis>=X.Y` there
+if the station should follow PyPI instead of the repo tree.
\ No newline at end of file

From 22422e60980879b4b80869ff19bda496cecf43c6 Mon Sep 17 00:00:00 2001
From: Jemin Kachhadiya <jemin.b.kachhadiya@gmail.com>
Date: Wed, 26 Aug 2026 12:43:21 -0500
Subject: [PATCH 3/3] fix CI after the packages/firmware layout move

Point the ServiceStatus firmware-header test at firmware/src instead of the old src/ tree, and stop writing HTML-metacharacter session names into Windows filenames.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 packages/dev_gui/tests/test_protocol.py           | 11 ++++++++---
 packages/sfm-analysis/tests/test_report_render.py |  7 +++++--
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/packages/dev_gui/tests/test_protocol.py b/packages/dev_gui/tests/test_protocol.py
index d4e42fc..b72710f 100644
--- a/packages/dev_gui/tests/test_protocol.py
+++ b/packages/dev_gui/tests/test_protocol.py
@@ -341,9 +341,14 @@ class TestServiceStatusMatchesFirmware:
     def test_values_match_firmware_header(self):
         import re
 
-        header = (
-            Path(__file__).resolve().parents[3]
-            / "src" / "services" / "ServiceTypes.h"
+        header = None
+        for parent in Path(__file__).resolve().parents:
+            candidate = parent / "firmware" / "src" / "services" / "ServiceTypes.h"
+            if candidate.is_file():
+                header = candidate
+                break
+        assert header is not None, (
+            "firmware/src/services/ServiceTypes.h not found above this test file"
         )
         text = header.read_text(encoding="utf-8")
         m = re.search(r"enum class ServiceStatus[^{]*\{([^}]*)\}", text)
diff --git a/packages/sfm-analysis/tests/test_report_render.py b/packages/sfm-analysis/tests/test_report_render.py
index 1fc904d..ceca0d8 100644
--- a/packages/sfm-analysis/tests/test_report_render.py
+++ b/packages/sfm-analysis/tests/test_report_render.py
@@ -2,7 +2,7 @@
 
 import re
 
-from report_fixtures import bandit_run, write_session
+from report_fixtures import bandit_run, write_csv, write_session
 
 from sfm_analysis.report import build_session_report
 from sfm_analysis.report.loader import load_rows
@@ -14,8 +14,11 @@
 
 
 def _runs(tmp_path, session="Weird&Session<Name>"):
+    # Session names in the CSV can contain HTML metacharacters (that's
+    # what the escaping tests cover). The filename must not: <>:"/\|?*
+    # are illegal on Windows.
     rows = bandit_run(n_trials=3, session=session)
-    path = write_session(tmp_path, rows, session=session)
+    path = write_csv(tmp_path / "session.csv", rows)
     loaded, _, _ = load_rows(path)
     return split_runs(loaded, [], path)