pycontrol-core 3.0.0a2__tar.gz → 3.0.0a4__tar.gz

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycontrol-core
-Version: 3.0.0a2
+Version: 3.0.0a4
 Summary: Sans-IO host library for the pyControl behavioural-experiment framework.
 Project-URL: Homepage, https://github.com/karpova-lab/pycontrol-core
 Author: pyControl contributors
@@ -183,8 +183,8 @@ See [public-api.md](docs/public-api.md) for the supported import surface.
 New to the project? Start with the repo-level guides:
 
 - [Documentation index](../rewrite-docs/README.md) - map of everything, with a reading order.
-- [Architecture tour](../rewrite-docs/md-viewer.html?doc=ARCHITECTURE-TOUR.md) - learn the system end to end.
-- [Why the rewrite](../rewrite-docs/md-viewer.html?doc=WHY-REWRITE.md) - what changed versus pyControl v2 and why.
+- [Architecture tour](../rewrite-docs/ARCHITECTURE-TOUR.md) - learn the system end to end.
+- [Technical overview](../rewrite-docs/TECHNICAL.html) - what changed versus pyControl v2 and why.
 
 Orientation and operation:
 
@@ -208,19 +208,18 @@ Contracts and internals:
 
 Extending pyControl:
 
-- [Task extensions](docs/task-extensions.md)
+- [Task extensions](docs/task-extensions.md) - includes integrations and optional extras.
 - [Experiment extensions](docs/experiment-extensions.md)
 - [Extension settings](docs/extension-settings.md)
-- [Integrations](docs/integrations.md)
 - [Task sharing archives](docs/sharing.md)
 
 Project process:
 
 - [Testing guide](docs/testing.md)
 - [Changelog](docs/changelog.md)
-- [Current code review backlog](docs/code-review.md)
 
 ## Contributing
 
-See the repository-level [CONTRIBUTING.md](../CONTRIBUTING.md) for editable
-installs, tests, contracts, firmware notes, and trusted plugin guidance.
+See the repository-level [CONTRIBUTING.md](../pycontrol-archive/CONTRIBUTING.md)
+for editable installs, tests, contracts, firmware notes, and trusted plugin
+guidance.

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/README.md

@@ -143,8 +143,8 @@ See [public-api.md](docs/public-api.md) for the supported import surface.
 New to the project? Start with the repo-level guides:
 
 - [Documentation index](../rewrite-docs/README.md) - map of everything, with a reading order.
-- [Architecture tour](../rewrite-docs/md-viewer.html?doc=ARCHITECTURE-TOUR.md) - learn the system end to end.
-- [Why the rewrite](../rewrite-docs/md-viewer.html?doc=WHY-REWRITE.md) - what changed versus pyControl v2 and why.
+- [Architecture tour](../rewrite-docs/ARCHITECTURE-TOUR.md) - learn the system end to end.
+- [Technical overview](../rewrite-docs/TECHNICAL.html) - what changed versus pyControl v2 and why.
 
 Orientation and operation:
 
@@ -168,19 +168,18 @@ Contracts and internals:
 
 Extending pyControl:
 
-- [Task extensions](docs/task-extensions.md)
+- [Task extensions](docs/task-extensions.md) - includes integrations and optional extras.
 - [Experiment extensions](docs/experiment-extensions.md)
 - [Extension settings](docs/extension-settings.md)
-- [Integrations](docs/integrations.md)
 - [Task sharing archives](docs/sharing.md)
 
 Project process:
 
 - [Testing guide](docs/testing.md)
 - [Changelog](docs/changelog.md)
-- [Current code review backlog](docs/code-review.md)
 
 ## Contributing
 
-See the repository-level [CONTRIBUTING.md](../CONTRIBUTING.md) for editable
-installs, tests, contracts, firmware notes, and trusted plugin guidance.
+See the repository-level [CONTRIBUTING.md](../pycontrol-archive/CONTRIBUTING.md)
+for editable installs, tests, contracts, firmware notes, and trusted plugin
+guidance.

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/cmd/pycontrol-init/README.md

@@ -20,6 +20,9 @@ enough. Use `--prerelease allow` so uv can resolve the current PyPI alpha.
 ```bash
 mkdir my-workspace
 cd my-workspace
+```
+
+```bash
 uv init --bare --python 3.11
 uv add pycontrol-gui --prerelease allow
 uv run pycontrol workspace init .
@@ -31,6 +34,8 @@ uv run pycontrol-gui
 ```powershell
 mkdir my-workspace
 cd my-workspace
+```
+```powershell
 uv init --bare --python 3.11
 uv add pycontrol-gui --prerelease allow
 uv run pycontrol workspace init .

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/architecture.md

@@ -139,19 +139,19 @@ cycle is to keep:
 ```text
 ┌──────────────────────────────┐
 │  hwdef (per-rig, .py)        │  user authors; wires breakout pins to
-│   pin_X = ...; led = ...     │  Digital_input/Output, Analog_input, etc.
+│   pin_X = ...; led = ...     │  DigitalInput/Output, AnalogInput, etc.
 └──────────────┬───────────────┘
                │ uses
                ▼
 ┌──────────────────────────────┐
-│  Breakout (geometry only)    │  Breakout_1_2 / Breakout_H7 / ... map
+│  Breakout (geometry only)    │  Breakout12 / BreakoutH7 / ... map
 │   port_1.DIO_A = "X1", ...   │  human pin labels to MCU pin IDs.
 └──────────────┬───────────────┘
                │ runs on top of active profile
                ▼
 ┌──────────────────────────────┐
 │  BoardProfile (MCU-specific) │  StmF405Profile / StmH743Profile own the
-│   timer pool, reservations,  │  MCU-only resources. `pyControl.profile`
+│   timer pool, reservations,  │  MCU-only resources. `pycontrol.profile`
 │   encoder pins/AF            │  is the runtime singleton, auto-selected
 └──────────────────────────────┘  from detected board MCU at import time.
 ```
@@ -159,12 +159,12 @@ cycle is to keep:
 A typical H7 hwdef can now be:
 
 ```python
-from devices.breakout_H7 import Breakout_H7
+from devices.breakout_H7 import BreakoutH7
 
-from devices import Digital_output  # drivers cache from `profile` here
+from devices import DigitalOutput  # drivers cache from `profile` here
 ```
 
-Profile selection is automatic from the board MCU at `pyControl` import time.
+Profile selection is automatic from the board MCU at `pycontrol` import time.
 
 The host validates this layering both statically and at runtime:
 
@@ -189,7 +189,7 @@ Since the firmware is vendored under `src/pycontrol/firmware/`, the
 host always knows what the on-board copy *should* be -- but it never
 mutates the board behind the operator's back. `BoardSession.connect()`
 runs a read-only djb2 diff against the baseline files under
-`/flash/pyControl/`, the required baseline modules in `/flash/devices/`,
+`/flash/pycontrol/`, the required baseline modules in `/flash/devices/`,
 and the top-level files listed in `_FIRMWARE_TOPLEVEL_FILES` (currently
 just `device_helpers.py`, the on-board helper module that mirrors what
 the host execs into the raw REPL at connect time). Optional bundled
@@ -208,7 +208,7 @@ The CLI keys off this:
   `.py` files the baseline doesn't manage (override with
   `--keep-extras`). Optional bundled drivers are re-added on demand.
 - `pycontrol run` warns loudly when out of sync and proceeds (the run
-  will likely fail at the `from pyControl import *`, but that's the
+  will likely fail at the `from pycontrol import *`, but that's the
   operator's call); pass `--sync-firmware` to push first.
 
 GUIs follow the same pattern: read `firmware_status` after `connect()`,

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/changelog.md

@@ -91,4 +91,5 @@
 
 > Note: performance benches and hardware-in-the-loop tests have since moved
 > out of `pycontrol-core` into the sibling `pycontrol-archive/` tree, so they
-> stay out of the default offline CI run. See `docs/testing.md`.
+> stay out of the default offline CI run. The `perf` pytest marker moved with
+> them and is no longer defined in `pycontrol-core`. See `docs/testing.md`.

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/cli-reference.md

@@ -30,7 +30,7 @@ tracebacks so developer bugs remain visible during testing.
 ## Workspace Commands
 
 ```bash
-pycontrol workspace init [path] [--force] [--no-configure-ruff]
+pycontrol workspace init [path] [--force] [--configure-ruff | --no-configure-ruff]
 ```
 
 Creates a workspace by copying the bundled workspace template:
@@ -151,7 +151,7 @@ name-keyed `setups.json` shape before this CLI can load them.
 
 ```bash
 pycontrol firmware status --setup BoxA
-pycontrol firmware status --setup BoxA -v
+pycontrol firmware status --setup BoxA --verbose
 pycontrol firmware sync --setup BoxA
 pycontrol firmware sync --setup BoxA --force
 pycontrol firmware sync --setup BoxA --keep-extras

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/contracts.md

@@ -115,7 +115,7 @@ Rules:
 
 The task authoring surface is defined by:
 
-- `src/pycontrol/firmware/pyControl/`
+- `src/pycontrol/firmware/pycontrol/`
 - baseline files plus on-demand bundled drivers in `src/pycontrol/firmware/devices/`
 - `src/pycontrol/firmware/device_helpers.py`
 - `src/pycontrol/extension/task_api.py`

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/experiment-extensions.md

@@ -197,8 +197,8 @@ from pycontrol.extension import ExperimentExtension
 
 
 SETTINGS = (
-    BoolSetting("enabled", "Enabled", default=True),
-    StringSetting("webhook_url", "Webhook URL", secret=True),
+    BoolSetting("enabled", "Enabled", default=True, hint="Enable or disable this extension."),
+    StringSetting("webhook_url", "Webhook URL", secret=True, hint="Destination used for experiment notifications."),
 )
 
 
@@ -211,6 +211,9 @@ class Notifier(ExperimentExtension):
             send_notification(webhook_url, context.to_dict())
 ```
 
+Setting helpers accept `hint="..."`; the GUI Settings dialog shows that text as
+a tooltip when the user hovers over the setting label.
+
 ## Examples
 
 ### Write a Run Manifest

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/extension-settings.md

@@ -30,8 +30,8 @@ from pycontrol.extension import TaskExtension
 
 
 SETTINGS = (
-    BoolSetting("slack_enabled", "Slack enabled", default=False),
-    StringSetting("slack_bot_token", "Slack bot token", secret=True),
+    BoolSetting("slack_enabled", "Slack enabled", default=False, hint="Send run notifications to Slack."),
+    StringSetting("slack_bot_token", "Slack bot token", secret=True, hint="Bot token used to post messages."),
     StringSetting("slack_channel_id", "Slack channel ID"),
 )
 
@@ -49,7 +49,7 @@ from pycontrol.extension import TaskExtension
 
 class TrialMonitor(TaskExtension):
     SETTINGS = (
-        IntSetting("min_trials", "Minimum trials", default=20, minimum=1),
+        IntSetting("min_trials", "Minimum trials", default=20, minimum=1, hint="Ignore sessions with fewer trials."),
     )
 ```
 
@@ -83,6 +83,9 @@ StringSetting("bot_token", "Bot token", secret=True)
 
 Secret fields are masked in the Settings dialog, but they are still saved in the workspace `settings.json`.
 
+All setting helpers accept `hint="..."`. When provided, the Settings dialog shows
+the hint as a tooltip when the user hovers over the setting label.
+
 ## Runtime Access
 
 At runtime, the extension receives two attributes:

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/getting-started.md

@@ -54,49 +54,47 @@ go build .
   --gui-path /path/to/rewrite/pycontrol-gui
 ```
 
-## Manual Path From A Source Checkout
+## Manual Path With uv
 
-If you do not want to use `pycontrol-init`, create a workspace with editable
-local checkouts:
+If you do not want to use `pycontrol-init`, create a workspace directly with
+[uv](https://docs.astral.sh/uv/).
 
-```bash
-mkdir my-workspace
-cd my-workspace
-git init
-uv init --bare --python 3.11
+### Fastest path: install from PyPI
 
-uv add --editable /path/to/rewrite/pycontrol-core
-uv add --editable /path/to/rewrite/pycontrol-gui
+This is the same four-line setup shown on the community showcase page. In a new,
+empty folder:
 
+```bash
+uv init --bare --python 3.11
+uv add pycontrol-gui --prerelease allow
 uv run pycontrol workspace init .
 uv run pycontrol-gui
 ```
 
-For the `3.0.0a1` PyPI alpha, GUI users can install the GUI package directly.
-Pin the alpha for reproducible workspaces:
+`pycontrol-gui` depends on `pycontrol-core`, so adding the GUI package is enough
+for GUI users. To pin a specific alpha for reproducible workspaces instead of
+taking the newest, use `uv add "pycontrol-gui==3.0.0a1"` (the pip equivalent is
+`pip install --pre "pycontrol-gui==3.0.0a1"`). Add integration extras separately
+when needed, for example `uv add "pycontrol-core[slack]" --prerelease allow`;
+replace `slack` with `notion`, `s3`, or `integrations`.
 
-```bash
-uv add "pycontrol-gui==3.0.0a1"
-```
+### From a local source checkout (contributors)
 
-To accept the newest available alpha instead, use uv's prerelease flag:
+To develop against editable local checkouts of the packages:
 
 ```bash
-uv add pycontrol-gui --prerelease allow
-```
+mkdir my-workspace
+cd my-workspace
+git init
+uv init --bare --python 3.11
 
-The pip equivalent is:
+uv add --editable /path/to/rewrite/pycontrol-core
+uv add --editable /path/to/rewrite/pycontrol-gui
 
-```bash
-pip install --pre "pycontrol-gui==3.0.0a1"
+uv run pycontrol workspace init .
+uv run pycontrol-gui
 ```
 
-`pycontrol-gui` depends on `pycontrol-core`, so adding the GUI package is enough
-for GUI users. Add integration extras separately when needed, for example
-`uv add "pycontrol-core[slack]==3.0.0a2"` or
-`uv add "pycontrol-core[slack]" --prerelease allow`; replace `slack` with
-`notion`, `s3`, or `integrations` as needed.
-
 ## GUI Integration
 
 GUI frontends should create workspaces through the public core API rather than
@@ -126,28 +124,28 @@ the same scaffold:
 ```text
 my-workspace/
   tasks/
+    blinker.py
     examples/
       blinker.py
       button.py
   hardware_definitions/
-    example.py
-    example_h7.py
-    usr_button.py
-    usr_button_h7.py
-    encoder.py
-    encoder_h7.py
+    example.py / example_h7.py
+    usr_button.py / usr_button_h7.py
+    encoder.py / encoder_h7.py
+    ...
   devices/
     example_widget.py
   experiments/
     blink_demo.json
   plugins/
-    task_extensions/
-    experiment_extensions/
+    task_extensions/          # example_extension.py, run_notify.py, ...
+    experiment_extensions/    # notion_logger.py, s3_data_exporter.py
     task_plotters/
-    task_controls/
+    task_controls/            # example_dialog.py
   data/
   settings.json
   setups.json
+  launch-pycontrol-gui.command  # and launch-pycontrol-gui.bat on Windows
 ```
 
 The initializer is a safe merge by default. Existing identical files are reused,

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/hardware-definitions.md

@@ -11,7 +11,7 @@ Hardware definitions are per-rig MicroPython files in
 
 - **Hardware definition** - the user-authored rig file. It maps task-friendly
   names to breakout pins and device constructors.
-- **Breakout** - board geometry such as `Breakout_1_2` or `Breakout_H7`, mapping
+- **Breakout** - board geometry such as `Breakout12` or `BreakoutH7`, mapping
   human port labels to MCU pin IDs.
 - **Board profile** - MCU-specific resources such as timers, alternate
   functions, and reserved pins. The firmware chooses this automatically from the
@@ -37,11 +37,11 @@ should usually be copied and renamed for a real setup.
 The breakout import communicates the intended board family:
 
 ```python
-from devices import Breakout_1_2  # F405 pyboard breakout
+from devices import Breakout12  # F405 pyboard breakout
 ```
 
 ```python
-from devices.breakout_H7 import Breakout_H7  # pyboard-H7 breakout
+from devices.breakout_H7 import BreakoutH7  # pyboard-H7 breakout
 ```
 
 Host-side inspection uses that import to infer the expected MCU. If a setup has

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/migration-from-official.md

@@ -48,7 +48,7 @@ pyControl/code/
 | `controls_dialogs/` + `v.custom_controls_dialog` | `plugins/task_controls/` | See `pycontrol-gui/docs/task-controls.md`. |
 | `config/setups.json` keyed by serial port | Name-keyed `setups.json` (`SetupRegistry`) | Convert once before loading the workspace. |
 | `devices/`, `hardware_definitions/`, `tasks/` | Same roles in workspace template | Device sources are vendored under `pycontrol.firmware` for sync; task/hwdef files usually copy as-is. |
-| `source/pyControl/` on-board framework | `pycontrol.firmware.pyControl` | Sync with `pycontrol firmware sync`. |
+| `source/pyControl/` on-board framework | `pycontrol.firmware.pycontrol` | Sync with `pycontrol firmware sync`. |
 
 ## Host import and module map
 
@@ -97,8 +97,58 @@ Scripts and `api_classes` import from `source.*` with the repo root on `PYTHONPA
 8. **Sync firmware** explicitly: `pycontrol firmware status`, then `pycontrol firmware sync`.
 9. **Launch the GUI** with `uv run pycontrol-gui` instead of `pyControl_GUI.pyw`.
 
-Task, device, and hardware-definition files can often be copied unchanged unless you
-are adopting MCU-profile-aware H7/F7 workflows.
+Task, device, and hardware-definition files need a small naming pass before they
+run on this rewrite because the on-board firmware now uses PEP 8 class names
+without compatibility aliases for the old mixed/snake-case class names.
+
+## Firmware class-name changes
+
+Update task files, hardware definitions, and custom device files that import or
+instantiate firmware classes. Module filenames are unchanged for now, so imports
+such as `from devices.breakout_H7 import BreakoutH7` still use the existing
+module path while importing the renamed class.
+
+Common hardware classes:
+
+| pyControl v2 name | Rewrite name |
+| --- | --- |
+| `Digital_input` | `DigitalInput` |
+| `Digital_output` | `DigitalOutput` |
+| `Analog_input` | `AnalogInput` |
+| `Analog_channel` | `AnalogChannel` |
+| `Audio_output` | `AudioOutput` |
+| `IO_object` | `IOObject` |
+| `IO_expander_pin` | `IOExpanderPin` |
+| `Analog_threshold_watcher` | `AnalogThresholdWatcher` |
+
+Bundled device classes:
+
+| pyControl v2 name | Rewrite name |
+| --- | --- |
+| `Breakout_1_2` | `Breakout12` |
+| `Breakout_H7` | `BreakoutH7` |
+| `Rotary_encoder` | `RotaryEncoder` |
+| `LED_driver` | `LEDDriver` |
+| `Analog_LED` | `AnalogLED` |
+| `Audio_board` | `AudioBoard` |
+| `Audio_player` | `AudioPlayer` |
+| `Five_poke` | `FivePoke` |
+| `Frame_logger` | `FrameLogger` |
+| `Frame_trigger` | `FrameTrigger` |
+| `Grid_maze` | `GridMaze` |
+| `Grid_maze_3x3` | `GridMaze3x3` |
+| `Grid_maze_7x7` | `GridMaze7x7` |
+| `Load_cell` | `LoadCell` |
+| `Nine_poke` | `NinePoke` |
+| `Port_expander` | `PortExpander` |
+| `Solenoid_driver` | `SolenoidDriver` |
+| `Stepper_motor` | `StepperMotor` |
+| `uRFID` | `URFID` |
+| `UART_handler` | `UARTHandler` |
+
+Utility helper classes are also CapWords (`SampleWithoutReplacement`,
+`ExpMovingAverage`, `Variables`), but the function-style task helpers
+`sample_without_replacement(...)` and `exp_mov_ave(...)` remain available.
 
 ## Behavioral differences worth knowing
 
@@ -123,7 +173,7 @@ are adopting MCU-profile-aware H7/F7 workflows.
 
 ## Further reading
 
-- [Why the rewrite](../../rewrite-docs/md-viewer.html?doc=WHY-REWRITE.md)
+- [What's new for your lab](../../rewrite-docs/COMMUNITY.html)
 - [Getting started](getting-started.md)
 - [Task extensions](task-extensions.md)
 - [Public API](public-api.md)

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/public-api.md

@@ -83,11 +83,16 @@ from pycontrol.recording import (
     AnalogWriter,
     ConsoleSubscriber,
     FleetAggregator,
+    NativeEventLogger,
     TsvLogger,
     ms_to_readable_time,
 )
 ```
 
+`TsvLogger`/`AnalogWriter` write the legacy v2-compatible files;
+`NativeEventLogger` writes the native run-bundle event TSV and analog arrays
+(see `docs/data-format.md`).
+
 ## Extension API
 
 ```python

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/sharing.md

@@ -89,11 +89,8 @@ Every archive contains a top-level `meta.json` validated by
   "files": [
     {
       "role": "task",
-      "workspace_path": "tasks/sequence.py",
       "archive_path": "tasks/sequence.py",
-      "sha256": "0123...",
-      "size_bytes": 1234,
-      "behavior_affecting": true
+      "sha256": "0123..."
     }
   ],
   "task_variables": {
@@ -124,7 +121,7 @@ the GUI version.
 `validate_protocol_bundle()` accepts strict schema version 1 archives. It checks
 that the ZIP contains valid metadata, every member stays inside the allowed
 workspace folders, every member is declared, every declared file is present, and
-every declared file matches its SHA-256 digest and byte size. Archive members
+every declared file matches its SHA-256 digest. Archive members
 with absolute paths, parent traversal (`..`), unknown top-level folders, missing
 metadata entries, legacy folder-list file declarations, or digest mismatches
 raise `ArchiveError`.

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/subscriber-api.md

@@ -59,12 +59,15 @@ GUI thread.
 
 ## Built-in subscribers
 
-| Module | Purpose |
+All are importable from `pycontrol.recording`:
+
+| Class | Purpose |
 | --- | --- |
-| `pycontrol.recording.tsv_logger` | Writes the session `.tsv` file (frozen format). |
-| `pycontrol.recording.analog_writer` | Writes per-channel `.time.npy` + `.data.npy`. |
-| `pycontrol.recording.console` | Pretty-prints to a logger / stdout. |
-| `pycontrol.recording.fleet_aggregator` | Thread-safe cache of fleet envelopes for GUI or other frontend consumers. |
+| `TsvLogger` | Writes the legacy session `.tsv` file (frozen format). |
+| `AnalogWriter` | Writes per-channel `.time.npy` + `.data.npy`. |
+| `NativeEventLogger` | Writes the native run-bundle event TSV and analog arrays. |
+| `ConsoleSubscriber` | Pretty-prints to a logger / stdout. |
+| `FleetAggregator` | Thread-safe cache of fleet envelopes for GUI or other frontend consumers. |
 
 ## User Extension: TaskExtension
 

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/task-extensions.md

@@ -183,8 +183,8 @@ from pycontrol.extension import TaskExtension
 
 
 SETTINGS = (
-    BoolSetting("enabled", "Enabled", default=True),
-    IntSetting("min_trials", "Minimum trials", default=20, minimum=1),
+    BoolSetting("enabled", "Enabled", default=True, hint="Enable or disable this extension."),
+    IntSetting("min_trials", "Minimum trials", default=20, minimum=1, hint="Ignore runs with fewer trials."),
 )
 
 
@@ -194,6 +194,9 @@ class TrialMonitor(TaskExtension):
         self.min_trials = self.extension_settings.get("min_trials", 20)
 ```
 
+Setting helpers accept `hint="..."`; the GUI Settings dialog shows that text as
+a tooltip when the user hovers over the setting label.
+
 Settings are available as:
 
 ```python
@@ -250,16 +253,42 @@ class AnalogMonitor(TaskExtension):
                 self.print_message(f"received {len(analog.data)} lick_sensor samples")
 ```
 
-## Integrations
+## Integrations and Optional Extras
+
+`pycontrol.integrations` contains small helpers for extension authors. It is
+not a home for lab-specific policy: workspace extensions still declare their
+own `SETTINGS`, decide when to send data, and pass credentials explicitly.
+
+`pycontrol-core` keeps cloud client libraries out of the default install. Add
+the extra for each integration you want:
+
+```bash
+uv add "pycontrol-core[slack]" --prerelease allow
+```
+
+| Integration | Install extra | Where it is used |
+|-------|----------------|--------|
+| Slack | `pycontrol-core[slack]` | `pycontrol.integrations.notify` |
+| Notion | `pycontrol-core[notion]` | Workspace example: `plugins/experiment_extensions/notion_logger.py` |
+| S3 | `pycontrol-core[s3]` | Workspace example: `plugins/experiment_extensions/s3_data_exporter.py` |
+
+Use `pycontrol-core[integrations]` for all of the above at once. Telegram
+notifications use only the Python standard library. Notion and S3 have no
+facade modules in core: their example experiment extensions import
+`notion_client` and `boto3` directly and keep all settings in the workspace.
+
+When adding a new integration, prefer a workspace extension for site-specific
+behavior; add a module under `pycontrol/integrations/` only for broadly useful
+shared primitives, expose its client library as a named optional extra, and
+test it with the third-party package mocked.
+
+### Notifiers
 
 `pycontrol.integrations.notify` provides small notifier classes for task
 extensions that need Telegram or Slack messages. Extension files still own their
 `SETTINGS`; the notifier classes only handle credentials, background delivery,
 and errors.
 
-Telegram uses only the Python standard library. Slack uses the `slack_sdk`
-package, available through the `pycontrol-core[slack]` extra.
-
 ```python
 from pycontrol.config import BoolSetting, StringSetting
 from pycontrol.extension import TaskExtension

{pycontrol_core-3.0.0a2 → pycontrol_core-3.0.0a4}/docs/troubleshooting.md

@@ -27,12 +27,12 @@ Symptoms:
 
 - `pycontrol run` prints a firmware warning.
 - The GUI shows an out-of-sync firmware banner.
-- Tasks fail near import time with missing `pyControl` or `devices` modules.
+- Tasks fail near import time with missing `pycontrol` or `devices` modules.
 
 Check:
 
 ```bash
-pycontrol firmware status --setup BoxA -v
+pycontrol firmware status --setup BoxA --verbose
 ```
 
 Fix:
@@ -125,7 +125,7 @@ Checks:
 
 ```bash
 pycontrol board info --setup BoxA
-pycontrol firmware status --setup BoxA -v
+pycontrol firmware status --setup BoxA --verbose
 ```
 
 Fixes:
@@ -149,19 +149,19 @@ Fix:
 
 ```bash
 # Per run override:
-pycontrol run --setup BoxA --task blinker --hwdef example
+pycontrol run --setup BoxA --task blinker --hwdef example --subject m1
 
 # Or set a setup default once, then omit --hwdef on future runs:
 pycontrol setups add BoxA --port /dev/cu.usbmodemXXXX --hwdef example --force
-pycontrol run --setup BoxA --task blinker
+pycontrol run --setup BoxA --task blinker --subject m1
 ```
 
 The effective hardware definition is the explicit `--hwdef`, else the setup's
 `hardware_definition` default. The host uploads it as
 `/flash/hardware_definition.py` before loading the task, but only when the task
 statically imports `hardware_definition`. When a task needs one but none is
-configured, the run warns and continues with whatever is already cached on the
-board.
+configured, the run fails before connecting (exit code 2) rather than using a
+file already cached on the board.
 
 ## Variables Do Not Change