plesty-bench 0.3.2__tar.gz → 0.4.0.dev1__tar.gz

{plesty_bench-0.3.2 → plesty_bench-0.4.0.dev1}/.gitlab-ci.yml

@@ -87,6 +87,14 @@ tests:windows:
   rules:
     - if: $CI_COMMIT_TAG
 
+# The installers and the release page are for released versions only. A
+# snapshot tag (v0.4.0.dev1) publishes both wheels to PyPI and stops there:
+# an installer pins the version it installs, and a .dev one is not something a
+# bench should be pinned to — the installer job refuses it outright.
+.released-version-rules:
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+
 release:server-wheel:
   stage: release
   extends: .release-rules
@@ -139,10 +147,10 @@ release:server-wheel:
 
 installer:windows:
   stage: release
-  # on tags, and on demand from an installer/<name> branch to prove a change
+  # on release tags (not snapshots), and on demand from an installer/<name> branch to prove a change
   # to the Inno Setup script before it is tagged
   rules:
-    - if: $CI_COMMIT_TAG
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
     - if: $CI_COMMIT_BRANCH =~ /^installer\//
   tags:
     - saas-windows-medium-amd64
@@ -191,7 +199,7 @@ installer:windows:
 # distributions — the Releases page is the download list.
 release:assets:
   stage: release
-  extends: .release-rules
+  extends: .released-version-rules
   image: registry.gitlab.com/gitlab-org/release-cli:latest
   needs:
     - job: installer:windows
@@ -214,14 +222,40 @@ release:assets:
       grep -q "release_version=\"$version\"" install.sh || { echo "install.sh not stamped"; exit 1; }
       curl --fail --silent --show-error --header "JOB-TOKEN: $CI_JOB_TOKEN" \
         --upload-file install.sh "$REGISTRY/install.sh"
+    - |
+      # The release page says what this release changed. It used to carry one
+      # fixed sentence, identical on every tag, so the Releases list read as
+      # eight copies of the same paragraph and "See CHANGELOG.md" was the only
+      # thing that ever differed -- a pointer where the note should have been.
+      # The changelog entry for the tag is the note; a tag without one fails
+      # the job rather than publishing an empty release.
+      version="${CI_COMMIT_TAG#v}"
+      awk -v v="$version" '
+        $0 == "## [" v "]" || index($0, "## [" v "] ") == 1 { found = 1; next }
+        found && /^## \[/ { exit }
+        found { print }
+      ' CHANGELOG.md > changes.md
+      grep -q '[^[:space:]]' changes.md || { echo "no CHANGELOG entry for $version"; exit 1; }
+      {
+        echo "**Install** — Windows: run the installer below; it installs uv and the"
+        echo "application from PyPI and adds a Start-menu entry and an optional desktop"
+        echo "shortcut. macOS and Linux: download \`install.sh\` and run it with \`sh\`."
+        echo "Developer machines: \`uv tool install plesty-bench\`."
+        echo
+        echo "**Update a bench** — \`uv tool upgrade plesty-server\` on macOS and Linux."
+        echo "On Windows use the *Update PLESTY Bench* Start-menu entry: since 0.3.3 the"
+        echo "application lives in its own environment there, not in uv's tool environment."
+        echo
+        echo "## What changed in $CI_COMMIT_TAG"
+        cat changes.md
+      } > release_notes.md
+      cat release_notes.md
   release:
     tag_name: $CI_COMMIT_TAG
     name: "plesty-server $CI_COMMIT_TAG"
-    description: >-
-      Windows: run the installer (it installs uv and the application from PyPI;
-      Start-menu entry, optional desktop shortcut). macOS and Linux: download
-      install.sh and run it with sh. Developer machines: uv tool install plesty-bench.
-      Update a bench with uv tool upgrade plesty-server. See CHANGELOG.md.
+    # A path, not prose: release-cli reads the file the script above wrote, so
+    # the note is this release's changelog entry rather than a constant.
+    description: release_notes.md
     assets:
       links:
         - name: "plesty-server-$CI_COMMIT_TAG-windows-setup.exe (Windows installer)"

{plesty_bench-0.3.2 → plesty_bench-0.4.0.dev1}/CHANGELOG.md

@@ -2,6 +2,321 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com).
 
+## [Unreleased]
+
+### Added
+- **A run keeps its own report.** When a run ends — completed, stopped,
+  aborted or crashed — the job writes `report.html` into the run directory,
+  beside the data it reports on. A run directory handed to somebody months
+  later now reads itself without the console that made it; *Export HTML* is
+  still there and still writes a copy wherever you point it. A report that
+  cannot be compiled is a line in the job log, never a failed run.
+- **Open run** opens the selected run's directory — records, journal,
+  analyses and report. Offered while the run is going, which is when watching
+  the files appear is most useful, and on a run loaded from elsewhere.
+- **The views come out of the pane.** *Console ▸ Open these views in a window*,
+  on the views' own menu bar, floats the whole viewer — every panel, its menus
+  and its layout — into a window of its own, which is what a plot read closely
+  wants. *Dock them back here*, or the button the pane then shows, returns it.
+  It is the only way to take the views out as a whole: the viewer's own
+  *Panels* menu hides and shows them, and dragging one out by its title bar
+  floats that one.
+- **Starting a run says what it is waiting on.** Every device the setup names
+  is opened on its bench before the module is launched — seconds of hardware
+  per instrument, during which the console showed nothing and a working Run
+  read as a broken one. A dialog now names the device being opened. It is
+  closable and closing it stops nothing: the run starts either way, and
+  Devices has the detail.
+- **Configure… changes the selected run, and nothing else.** Create run copies
+  the chosen configuration file into the run directory as `config.yaml`, and
+  the run is started and resumed with that copy. With a created run selected,
+  Configure edits the copy — choosing another file gives the run that file —
+  and leaves the module's files and the other runs as they are; a started run
+  shows its configuration read-only. Duplicate repeats the run's own copy.
+  Before, Configure changed the experiment, so a run created a moment earlier
+  was still started with the file it was created with.
+- **The measurement report has a Device setup section**: each device's bench,
+  the address the run reached it on and where that bench sees the shared data
+  disk, with the run's shared point and raw data folder — as plesty-lib
+  journals them when a run starts. A resumed run lists each start, since the
+  ports change between starts; a run from an older plesty-lib says it did not
+  record them.
+- **The measurement report switches between light and dark** — Auto, the
+  reader's system setting, or Light or Dark from the switch in its header.
+  The switch is radio buttons read by the stylesheet, so the report still
+  runs no script.
+- **An experiment runs with its module's `setup.yaml`** — plesty-lib's
+  contract (`plesty.lib.experiment.setup`). Every experiment module ships one
+  at its root: a fleet file's `devices:` with bench entries beside them as
+  `benches:` — where each bench's agent listens, its token, and where it sees
+  the lab's shared data disk, each written as the variable holding it
+  (`${SPEC_PC_HOST}`); the values live in the checkout's `.env`. Installing
+  the module seeds that `.env` with a line per variable. The bench without an
+  address is the machine the experiment runs on; a device names its bench,
+  and no port. **Run** checks that every bench sees the one shared disk — a
+  probe written here, read and answered through each other bench's agent
+  (`plesty-server share-check`) — then has each device served by its bench
+  (`plesty-server serve`): declared from its entry when that bench lacks it,
+  started on a port the bench picks, with `DEVICE_DATA_PATH`, its bench's
+  view of the disk, under which it may write anywhere. The run is given
+  `PLESTY_DATA` and each `<DEVICE>_ADDRESS` from the port its bench said;
+  this replaces working out a run's devices from the fleet's ports. The
+  devices a run started are stopped when it ends, however it ends — the run's
+  job waits on the module and stops them (`_job experiment-run`), and Kill
+  stops them itself. Runs go
+  to the root the module declares, on the shared disk (`pol-pl` →
+  `<PLESTY_DATA>/pol-pl`), so a device on any bench can write into a run;
+  without a shared point they stay under this bench's home. A value set by hand in
+  the `.env` or the declaration still wins, and a value still missing is
+  named with its variable when a run cannot start. *Configure… ▸ Device
+  Setup* replaces the Environment tab and edits it — the benches by value,
+  this machine's first, saved as variables in the setup and values in the
+  `.env`, then a group per device. *Server ▸ Benches…* stays the list of
+  benches this console drives. A fleet file may carry `benches:`, so `fleet
+  up -f setup.yaml` works. Needs the plesty-lib that ships the contract.
+- **Hub ▸ Load from… puts a repository on this machine onto the bench, where
+  it lives.** Pick a module's folder and a branch: the bench reads what the
+  module is from its `pyproject.toml` (`[tool.plesty] module_type`), checks out
+  the branch — refused over uncommitted changes — and records the folder, its
+  version and commit under `<home>/packages/<package>/`, running it with the
+  folder's own `.venv` (made with `uv sync` only when there is none). Nothing
+  is copied; removing it forgets the record and never deletes the folder. A
+  loaded module serves only a declaration that names its folder (`path:`), so
+  loading one never changes what an existing declaration runs. *Create run*
+  offers a loaded experiment as `pol-pl (local)`. Also `plesty-server module
+  load FOLDER [--ref BRANCH]`.
+- **An experiment's configuration is laid out, not listed.** *Configure…*'s
+  first tab is **Experiment Config**: each group a titled box, a list of
+  records as rows with + and − at the end of each, grey text in an empty field
+  taken with Tab, and a picker over the module's `config/*.yaml` — each file
+  keeps its edits, and the one chosen when saving is the one runs read. The
+  YAML tab became **Edit YAML…**, which opens the file with the form's edits in
+  it; a file nobody changed is written back as it was, comments and all. The
+  dialog can be made as narrow as a key and a field allow. A double-click on an
+  experiment opens *Configure…*, on a device *Edit ▸ Device config…*; *Hub ▸
+  Search & install…* is now **Hub ▸ Marketplace…**.
+- **The run report shows what each analyzer says it found** (plesty-lib#55).
+  An analyzer's own report, saved beside its outputs as
+  `analysis/<name>.report.json`, becomes the analysis section: its sentence, its
+  tables — units, grouped headings, footnotes, math — and its figures, rendered
+  by plesty-lib as inline SVG and MathML, so the file still fetches and runs
+  nothing. The outputs a report covers (same provenance) are no longer guessed
+  at from their array names as well. A console whose plesty-lib predates
+  reports, or refuses one from a newer version, reads the outputs as before.
+- **A finished run compiles into one HTML report** (#13). *Export HTML* on the
+  Report pane lays out what a measurement is worth to somebody who was not
+  standing there: what was run and how it ended, the module and instruments it
+  recorded, the configuration frozen into its plan, the operator's notes, what
+  each analyzer made of the sweep with the options it was given, and every
+  committed record.
+
+  One file — the stylesheet is inlined, there is no script and nothing is
+  fetched, because a report has to open from an attachment and in ten years.
+  The markup is an asset and the colours are plesty-lib's palette tokens, so
+  nothing about how it looks is decided in Python.
+
+  The run is read directly rather than through plesty-lib's document readers:
+  an experiment runs in an environment of its own, so the library that wrote a
+  run is routinely newer than the console's, and a bench on 0.4.1 would
+  otherwise refuse to report a run it can plainly see.
+
+- **Help ▸ Report a problem fills the report in and filters it** (#14). The
+  first question a maintainer asks is what were you running and on what, so the
+  entry answers it: the machine, the interpreter, the Plesty versions, every
+  declared device with its package, version, state and port, and the tail of
+  each device log. What is sent is shown in full and stays editable — a review
+  is only real if what is on screen is what goes.
+
+  The bench files nothing itself. It holds no credential that could write to
+  the tracker, and giving it one would put a token on every lab machine for a
+  convenience; *Copy & open tracker* puts the report on the clipboard and opens
+  the project's new-issue page with the title filled in, and the operator
+  submits as themselves. Nothing that looks like a credential leaves the bench:
+  a device environment is reported by key and never by value, and every
+  captured line — the operator's own words included — loses assignments named
+  like secrets, credentials inside URLs, tokens that announce themselves by
+  prefix, and Authorization headers. Matched on names rather than shapes, so a
+  commit hash stays a commit hash.
+
+- **Experiments are set up, run and watched from the console.** `fleet.yaml`
+  grows an `experiments:` section beside `devices:`, and the Experiment tab is
+  the Devices half's shape: what this bench holds above, the detail of the
+  selected one below, with Status, Runs, Log, Data and Visualization panes.
+
+  **The settings form is the module's, not ours.** An experiment publishes
+  what it takes — `python -m <module> --manifest` prints every configuration
+  key with its type, unit, bounds and meaning — and *Configure…* renders that
+  with the same schema-to-widget mapping a device panel uses. The console
+  holds no per-experiment code and cannot offer a setting the module does not
+  take, or bound one differently from the way the module bounds it. A key
+  whose value is a document is offered as text; the YAML tab is the file
+  itself and is what is saved, so a key the schema does not declare — and the
+  comments explaining one — survive an edit made in the form. The Environment
+  tab names what the module reads and what of it is not set.
+
+  **A run is a detached job**, so closing the console does not stop the
+  measurement, and *Run* becomes *Resume* on a run that stopped unfinished.
+  *Pause* holds it before the next step with the rig still connected — the
+  difference from stopping and resuming, which pays a reconnect, a preflight
+  and possibly a re-home to come back. *Stop* lets the step in flight commit
+  first; *Abort* does not wait, releasing the instruments at once and leaving
+  that step to run again. All three take effect at a step boundary, where the
+  journal commits; a request made during a long exposure is pending, not
+  ignored, and the Status pane says so. *Report…* records what happened —
+  a helium top-up, a realignment — in the journal between the steps it sits
+  between.
+
+  **Status is read, never asked.** The journal, the plan and the progress file
+  are this bench's own files: a refresh costs a directory read and cannot
+  disturb a run. The journal is replayed here rather than through plesty-lib,
+  because the run was written by a module whose library version has nothing to
+  do with this console's — delegating would make the same run read differently
+  on two benches.
+
+  Visualization is a placeholder that says why: an experiment's views need its
+  own dependencies, so *Watch run* opens the module's viewer as a process of
+  its own.
+
+  An experiment is installed from its repository rather than from a release —
+  its `config/` and `.env.example` are in the checkout, not in the wheel.
+  Needs a module whose command line is built on
+  `plesty.lib.experiment.ExperimentCLI` (plesty-lib#54).
+
+- **One console for several benches.** A bench declares `role: master` or
+  `role: node` under *Server ▸ Configure…*. A master lists the other benches
+  under *Server ▸ Benches…* — name, address and agent token, kept in
+  `<home>/peers.yaml` — and shows their devices in the device table beside its
+  own, under a new **Host** column. It starts, stops, restarts, installs and
+  updates them, and opens their control panels, all over the agent's existing
+  `exec` and `device` requests; an install on another bench is started there
+  and its job id reported, since this console keeps no job list for a device it
+  does not host. One master to a group of benches and no chaining. It is how a
+  console is configured and not a permission: the agent checks one shared
+  secret and knows no caller identity, so a bench's token drives that bench
+  whoever holds it.
+
+  A device on another bench has no *Log*, *Jobs*, *Reports*, *Terminal* or
+  *Traffic*: all five read files in the bench that hosts it, and reading a log
+  tail off another machine every three seconds is the cost this avoids. Those
+  tabs are disabled, and the pane says which bench to read them on. Editing the
+  declaration, clearing the log, uninstalling, removing from the fleet and the
+  field test stay with the host bench too.
+
+- **The Hub offers experiments as well as devices.** *Catalogue* is now
+  **Hub**, and *Search & install…* lists the registry's experiment modules
+  beside its device modules, with a kind filter and a Kind column. The install
+  path is unchanged — it was always keyed by the package rather than by a
+  device. Only modules at the quantum standard are offered, as before;
+  analyzers are not listed, an analyzer being a library an experiment brings
+  with it.
+
+- **Control is a button, and each kind opens what it says.** *Control* on the
+  detail card opens the selected device's controls in a window of its own,
+  named for it; *Control* on the device table opens the wall — one window with
+  the controls of every running device. They were one window before, which
+  meant asking for one device's controls showed the last device's docked beside
+  them.
+
+- **Fleet up and Fleet down reach the nodes.** A master brings a rig up, and
+  the rig is every bench the table shows; each node is asked for its own
+  working fleet, which is that bench's declaration. A node that refuses costs a
+  line in the status bar and not the rest of the rig.
+
+- **plesty-lib 0.4.1 is the floor.** A panel on 0.4.0 cannot read or write a
+  grouped configuration parameter at all — it addresses one by its bare name,
+  which the device refuses — and sends an optional numeric argument as the text
+  typed into it. Both are fixed in 0.4.1, along with the panel's layout,
+  reading on request rather than on a clock, and units with real exponents.
+
+### Changed
+- **The Report pane says something about the report.** It names the run's own
+  `report.html` — when it was written and how big — or says when it will have
+  one. The operator's notes, which the pane also called "reports", are now
+  under **Notes**: two different things under one heading was what made the
+  pane hard to read.
+- **Requires plesty-lib 0.5.0.dev6** (was 0.5.0.dev5), which retires
+  `PLESTY_DATA_DIR` and `PLESTY_DATA_MOUNT` for the one shared root
+  `PLESTY_DATA` and makes a manifest's `run_root` relative to the shared point.
+  A run's environment is built from that contract, so a console on dev5 and a
+  module on dev6 do not agree on where a run writes. Still a prerelease until
+  the bound moves to 0.5.0, but the Windows installer needs no flag for it: it
+  installs with pip, which takes a prerelease a requirement names.
+- **The tables refresh every second**, not every three: the Progress column
+  follows a run step by step instead of jumping several at a time.
+- **The report's raw data is one table per kind of step**, one short line per
+  record: a field the same in every row is said once above the table, a file
+  shows by its name with its folder said once, and a timestamp by its time of
+  day with its date said once. A step recorded once, such as the rig's
+  identity, is a list of its fields.
+- **The window has two halves, Devices and Experiment**, and the menu bar reads
+  File, Edit, Device, Experiment, Hub, Server, View, Help. The Experiment tab is
+  empty and every item of the Experiment menu is disabled in this version: they
+  are built now so that the window does not change shape when the work behind
+  them lands.
+- **The documentation is rewritten for the people who use a bench.** It is in
+  three parts — *GUI*, the window element by element with its real buttons,
+  dialogs and screenshots; *CLI*, every command, file and setting; *Usages*,
+  tasks step by step — after *Install* and a walkthrough of a pol-pl run
+  across two benches, filmed from a real run. Every page was checked against
+  the code; `docs/imgs/gui/capture.py` and `capture_cross_bench.py` make the
+  images again.
+
+## [0.3.3] - 2026-09-09
+
+### Changed
+- **The release page says what the release changed.** Every release carried the
+  same fixed paragraph, so the Releases list read as eight copies of one
+  sentence and `See CHANGELOG.md` was the only part that could be right. The
+  note is now the changelog entry for the tag, and a tag without one fails the
+  job rather than publishing an empty release. The install lines above it were
+  wrong for Windows from this release on: a bench there updates from the
+  *Update PLESTY Bench* entry, not `uv tool upgrade`.
+
+### Fixed
+- **Renaming a device keeps the highlight on it.** The console refreshes every
+  three seconds into a four-task pool, so a refresh that started before a
+  rename lands after it, carrying the device under its old name. That repaint
+  took the pending selection, found no row to move to, selected nothing and
+  cleared it; the repaint that did carry the new row then fell back to the
+  current selection, which was the old name. The rename worked and the
+  highlight jumped back to a device that no longer existed. The pending
+  selection is now held until a repaint can honour it. Found as a Windows CI
+  failure that passed on a second run of the same commit — the race is wider
+  on a loaded machine, not absent on a fast one.
+- **The Windows installer installs with pip instead of `uv tool install`.**
+  Roughly one install in five failed on a bench with an on-access virus
+  scanner: `Failed to update Windows PE resources ... os error -2147024786`,
+  always naming the `pyside6-essentials` wheel. uv writes each console-script
+  launcher to a temp file and reopens it to patch its PE resources, and the
+  scanner blocks the reopen. `plesty-server[gui]` builds about 25 launchers,
+  23 of them PySide6 tools nothing here calls, so a per-file failure rate near
+  1% became a per-install failure rate near 20%. uv 0.12 has no way to skip
+  launchers it does not need.
+
+  The wizard now takes a Python from uv, builds a virtual environment under
+  `%LOCALAPPDATA%\PLESTY Bench\app`, and `pip install`s into it; pip writes a
+  launcher as one write of stub + shebang + zip payload to its final path and
+  reopens nothing. `plesty-server` and `plesty-server-gui` are copied to
+  `~\.local\bin` as before, so the shortcuts, PATH and `purge` are unchanged.
+  The install is slower.
+
+  Windows consequences, both carried by the wizard: an upgrade is the *Update
+  PLESTY Bench* entry (`python -m pip install --upgrade "plesty-server[gui]"`
+  in that environment) and not `uv tool upgrade`, and the uninstaller removes
+  the environment itself — it still takes off a pre-0.3.3 install from uv's
+  tool environment when it finds one. macOS and Linux are untouched and still
+  use `uv tool install`.
+- **The install retries are spread out instead of fired back to back.** Three
+  immediate retries all land inside the same burst of scanner activity, which
+  makes them one attempt rather than three. The whole install is now retried
+  after roughly 2, 8 and 30 seconds with jitter, and only for causes that can
+  clear — a version that is not on the index still fails at once.
+- **The uv interpreter search sorts by version again.** The version was
+  captured by the filter and read by the sort, but `Sort-Object` reads every
+  candidate before comparing any, so every one of them sorted on the last
+  directory's number. It also prefers the 3.12 series now: a bench carrying a
+  Python newer than PySide6 publishes wheels for would resolve to nothing.
+
 ## [0.3.2] - 2026-09-07
 
 ### Changed

{plesty_bench-0.3.2 → plesty_bench-0.4.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-bench
-Version: 0.3.2
+Version: 0.4.0.dev1
 Summary: Client for a PLESTY bench running plesty-server: run its commands and fetch its reports from another machine.
 Author-email: Yunshuang Yuan <yuanyunshuang@gmail.com>
 Maintainer-email: Plesty Development Team <plesty.dev@example.com>
@@ -11,36 +11,38 @@ Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 Requires-Dist: pyzmq>=26
 Provides-Extra: control
-Requires-Dist: plesty-lib[gui]>=0.4.0; extra == 'control'
+Requires-Dist: plesty-lib[gui]>=0.5.0.dev8; extra == 'control'
 Provides-Extra: gui
-Requires-Dist: plesty-lib>=0.4.0; extra == 'gui'
-Requires-Dist: plesty-lib[gui]>=0.4.0; extra == 'gui'
+Requires-Dist: plesty-lib[gui]>=0.5.0.dev8; extra == 'gui'
+Requires-Dist: plesty-lib[report]>=0.5.0.dev8; extra == 'gui'
 Requires-Dist: pyside6==6.11.2; extra == 'gui'
 Requires-Dist: pyyaml>=6.0; extra == 'gui'
 Provides-Extra: server
-Requires-Dist: plesty-lib>=0.4.0; extra == 'server'
+Requires-Dist: plesty-lib[report]>=0.5.0.dev8; extra == 'server'
 Requires-Dist: pyyaml>=6.0; extra == 'server'
 Description-Content-Type: text/markdown
 
 # plesty-server · plesty-bench
 
-**The bench PC's own console for the PLESTY platform.** It installs hub device
-modules, starts and supervises their device servers, runs field tests against
-the real instruments and keeps the logs — so a lab bench is set up and kept
-running from one place instead of one venv, one terminal and one hand-written
-`uv` pin per instrument.
+**The bench PC's own console for the PLESTY platform.** It installs hub
+modules, starts and supervises device servers, runs field tests against the
+real instruments, and runs experiments across the lab's benches — keeping the
+logs, the runs and their reports — so a lab bench is set up and kept running
+from one place instead of one venv, one terminal and one hand-written `uv` pin
+per instrument.
 
 This repository publishes two packages:
 
 | | Install on | Install with |
 |---|---|---|
-| **`plesty-server`** — the bench application: CLI, Qt console, agent | the bench PC | `uv tool install "plesty-server[gui]"` |
+| **`plesty-server`** — the bench application: CLI, Qt console, agent | the bench PC | the installer from the [releases](https://gitlab.com/plesty/core/plesty-bench/-/releases) |
 | **`plesty-bench`** — the client that drives a bench from elsewhere | your own machine | `uv tool install plesty-bench` |
 
-On a Windows bench, the [releases](https://gitlab.com/plesty/core/plesty-bench/-/releases)
-carry a `setup.exe` (per-user, no admin); macOS and Linux have `install.sh`.
-Both install `uv`, run the command above and add a Start-menu / Launchpad
-entry — they contain no application code of their own.
+Each release carries a Windows `setup.exe` (per-user, no admin) and an
+`install.sh` for macOS and Linux. Both install the whole application,
+console included, pinned to that release, and add a Start-menu or Launchpad
+entry. Without an installer, `uv tool install "plesty-server[gui]"` installs
+the same thing on macOS or Linux.
 
 ## Bringing up a bench
 
@@ -70,25 +72,20 @@ plesty-bench -b lab-bench-03 control pm100d          # a control panel per devic
 ## Documentation
 
 **[Full documentation](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/index.md)**
-— start there if anything below is unfamiliar. It is in two parts.
+— start there if anything below is unfamiliar. It is in three parts:
 
-*Using a bench*, in the order you meet it:
-
-| | |
+| Part | Covers |
 |---|---|
-| [Setting up a bench](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/bench_setup.md) | The fleet file, declaring devices, ports, the `.env` |
-| [Device modules](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/modules.md) | The catalogue, installing, several versions side by side |
-| [Running device servers](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/running.md) | Start, stop, status, logs, the working fleet, headless benches |
-| [Field tests](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/field_test.md) | Running a module's field test against the instrument |
-| [The console](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/console.md) | Every part of the window, and the control panels |
-| [Working remotely](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/remote.md) | The agent and the `plesty-bench` client |
-| [Maintenance](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/maintenance.md) | Upgrading, clearing logs, purging, uninstalling |
-| [Command reference](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/cli.md) | Every `plesty-server` command |
+| [GUI](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/gui/index.md) | The window element by element: the Devices and Experiments tabs, every menu, every dialog, the Control window |
+| [CLI](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/cli/index.md) | `plesty-server`, `plesty-bench`, and every file and setting |
+| [Usages](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/usage/index.md) | Tasks start to finish: set up a bench, install modules, field-test, run an experiment, work remotely, run without a window, maintain |
+
+A new bench starts at [Set up a bench](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/usage/first_bench.md).
 
 *[Design and internals](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/design/index.md)*
-is the other part: the architecture, the process model, the port rules, the
-installer, the agent protocol, the platform differences and the release
-machinery — for contributors, and for anyone debugging behaviour that only
+covers the architecture, the process model, the port rules, the
+installer, the agent protocol, experiment runs, the platform differences and
+the release machinery — for contributors, and for anyone debugging behaviour that only
 makes sense once the mechanism is visible.
 
 New to the platform? The [PLESTY quickstart](https://plesty.net/learn/quickstart/index.html)

plesty_bench-0.4.0.dev1/README.md

@@ -0,0 +1,68 @@
+# plesty-server · plesty-bench
+
+**The bench PC's own console for the PLESTY platform.** It installs hub
+modules, starts and supervises device servers, runs field tests against the
+real instruments, and runs experiments across the lab's benches — keeping the
+logs, the runs and their reports — so a lab bench is set up and kept running
+from one place instead of one venv, one terminal and one hand-written `uv` pin
+per instrument.
+
+This repository publishes two packages:
+
+| | Install on | Install with |
+|---|---|---|
+| **`plesty-server`** — the bench application: CLI, Qt console, agent | the bench PC | the installer from the [releases](https://gitlab.com/plesty/core/plesty-bench/-/releases) |
+| **`plesty-bench`** — the client that drives a bench from elsewhere | your own machine | `uv tool install plesty-bench` |
+
+Each release carries a Windows `setup.exe` (per-user, no admin) and an
+`install.sh` for macOS and Linux. Both install the whole application,
+console included, pinned to that release, and add a Start-menu or Launchpad
+entry. Without an installer, `uv tool install "plesty-server[gui]"` installs
+the same thing on macOS or Linux.
+
+## Bringing up a bench
+
+```bash
+plesty-server fleet init                      # a fleet.yaml to declare into
+plesty-server declare pm100d plesty-pm100d --version 0.2.1 \
+    --arg --address --arg "USB0::0x1313::…::INSTR"
+plesty-server start pm100d                    # installs, launches, waits until it answers
+plesty-server status
+```
+
+The instrument is now reachable from an experiment PC at this machine's
+address on the port `status` reports. `plesty-server gui` opens the same bench
+in a window; `plesty-server fleet run` keeps it up headless after a reboot.
+
+## Driving it from your own machine
+
+The bench serves an agent; the client sends it `plesty-server` command lines
+and follows the output.
+
+```bash
+plesty-bench -b lab-bench-03 status
+plesty-bench -b lab-bench-03 field-test pm100d --gates connect,drain
+plesty-bench -b lab-bench-03 control pm100d          # a control panel per device
+```
+
+## Documentation
+
+**[Full documentation](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/index.md)**
+— start there if anything below is unfamiliar. It is in three parts:
+
+| Part | Covers |
+|---|---|
+| [GUI](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/gui/index.md) | The window element by element: the Devices and Experiments tabs, every menu, every dialog, the Control window |
+| [CLI](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/cli/index.md) | `plesty-server`, `plesty-bench`, and every file and setting |
+| [Usages](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/usage/index.md) | Tasks start to finish: set up a bench, install modules, field-test, run an experiment, work remotely, run without a window, maintain |
+
+A new bench starts at [Set up a bench](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/usage/first_bench.md).
+
+*[Design and internals](https://gitlab.com/plesty/core/plesty-bench/-/blob/main/docs/design/index.md)*
+covers the architecture, the process model, the port rules, the
+installer, the agent protocol, experiment runs, the platform differences and
+the release machinery — for contributors, and for anyone debugging behaviour that only
+makes sense once the mechanism is visible.
+
+New to the platform? The [PLESTY quickstart](https://plesty.net/learn/quickstart/index.html)
+runs a whole experiment against a bench and is the gentlest way in.

{plesty_bench-0.3.2 → plesty_bench-0.4.0.dev1}/docs/api_reference.md

@@ -3,8 +3,8 @@
 Entry pages: the [bench application `plesty.server`](reference/plesty/server/index)
 and the [client `plesty.bench`](reference/plesty/bench/index).
 
-Most work is done through the [command line](cli.md) or the
-[client](remote.md); this is for code that drives a bench directly, and for
+Most work is done through the [command line](cli/plesty-server.md) or the
+[client](cli/plesty-bench.md); this is for code that drives a bench directly, and for
 contributors. What each layer is allowed to depend on is set out in
 [Architecture](design/architecture.md).